Spawning

Spawning is the handoff from an AGH agent definition to a live ACP subprocess. It starts when a session is created or resumed, and it ends when the subprocess has completed ACP initialization and the AGH session becomes active.

Spawn inputs

The session manager builds acp.StartOpts from the resolved workspace and agent:

The ACP driver validates these before launch:

• AgentName, Command, and Cwd are required.
• Cwd must resolve to an existing directory.
• Each non-empty additional dir must be absolute and resolve to an existing directory.
• Duplicate additional dirs are removed after symlink resolution.
• An additional dir equal to the primary workspace root is skipped.
• Permissions must be deny-all, approve-reads, or approve-all.

Launch

AGH parses the provider command with shell-style quoting:

npx -y @agentclientprotocol/claude-agent-acp@latest

The parsed executable and arguments are launched directly, not through a shell. The subprocess runs with cwd set to the workspace root, and AGH connects JSON-RPC to the subprocess over stdio.

On Unix systems, managed ACP subprocesses start in their own process group. Stop can therefore terminate wrapper processes and their children, which matters for commands such as npx ... that start a Node wrapper before the actual ACP runtime.

Environment

The subprocess environment starts from the provider's env_policy:

• filtered keeps ordinary daemon context and strips secret-shaped variables before launch.
• isolated starts from a small operational allowlist and then adds only AGH runtime metadata, provider-home variables, and explicit bound credentials.

AGH then applies these additions:

AGH also prepends the AGH binary directory to PATH, removing a duplicate entry if it already exists. Before setting channel values, stale AGH_SESSION_CHANNEL and AGH_PEER_ID values are cleared from the inherited environment.

Provider API keys are injected only when auth_mode = "bound_secret" through provider credential_slots. A slot maps a secret_ref into a target environment variable such as OPENROUTER_API_KEY. env:NAME refs read from the daemon environment at launch, while vault:providers/<provider>/<slot> refs read encrypted AGH-managed provider credentials written through settings. Required slots fail startup when the bound secret is missing.

For native_cli providers, AGH does not require provider API-key environment variables. The provider command uses its own login/session store. The default home_policy = "operator" preserves existing CLI logins; home_policy = "isolated" creates a private provider home under $AGH_HOME and starts with no copied credentials.

For the direct native pi provider, AGH does not override Pi's operator auth directory. When home_policy = "isolated" is selected, AGH points Pi at $AGH_HOME/providers/pi/.pi/agent so agh provider auth login pi and session launch use the same isolated auth store. Wrapped API-key providers that use pi_acp with auth_mode = "bound_secret" get session-local settings.json and models.json; AGH sets PI_CODING_AGENT_DIR to that per-session runtime config and injects the provider key there.

ACP negotiation

After the process starts, AGH sends initialize.

AGH advertises:

• filesystem read text support
• filesystem write text support
• terminal support
• client name agh
• client version dev

The initialize response tells AGH whether the agent supports session/load.

New session

For a new session, AGH sends session/new:

{
  "cwd": "/workspace/root",
  "mcpServers": [],
  "additional_dirs": ["/workspace/other-root"]
}

additional_dirs is an AGH extension field. It is top-level snake_case because the upstream ACP SDK does not model it yet.

The response provides the ACP sessionId, supported modes, and supported models. AGH stores the ACP session ID separately from the durable AGH session ID.

Resume

For resume, AGH sends session/load:

{
  "cwd": "/workspace/root",
  "mcpServers": [],
  "additional_dirs": ["/workspace/other-root"],
  "sessionId": "provider-session-id"
}

Resume requires the agent to advertise loadSession during initialize. If it does not, startup fails with an unsupported load-session error. If the upstream runtime says the stored session no longer exists, AGH can recognize the ACP resource-not-found shape and repair resume behavior at the session layer.

Permission mode mapping

AGH applies its static permission mode to ACP session modes when the provider reports a compatible mode. When AGH enables the provider-native tool execution gateway, it may first try a separate approval-mediated ACP mode candidate such as default or ask so provider-native tool calls flow back through AGH before any real side effect. Those gateway candidates are separate from the static permission-to-session-mode mapping below. The configured permissions.mode still stays authoritative at the execution boundary.

If the provider does not advertise a compatible mediated mode, AGH falls back to the static permission-to-session-mode mapping below.

If no reported mode matches, AGH skips session/set_mode and still keeps its own inbound permission policy. Filesystem permission checks use the primary workspace root as the sandbox.

Prompt startup behavior

The AGENT.md body becomes the agent-owned role portion of the startup prompt. AGH wraps it with a daemon-owned runtime envelope that states the session is running inside AGH, records session and workspace facts, and explains that AGH owns the session lifecycle, runtime context, native tool gateway, and observable event stream.

Generic ACP does not provide a system-role field in session/new or session/load, so AGH sends the assembled startup prompt with the first user prompt and annotates that fallback in prompt metadata. Later turns send only user prompt text plus any live turn context AGH adds through its prompt augmenters. Provider-native system-prompt channels can receive the same rendered startup guidance directly when a harness supports them.

That means:

• the body should contain durable role and operating instructions, not the fact that the process is running inside AGH
• AGH runtime identity, session facts, and daemon-owned tool guidance are added by the runtime
• per-turn details belong in the user prompt or daemon-provided turn context
• changing AGENT.md affects new processes, not a process that is already running

Stop behavior

Stopping is cooperative first:

1. Mark the process as stop-requested.
2. Send ACP session/cancel when an ACP session ID exists.
3. Ask the managed subprocess to shut down.
4. Wait for process exit.
5. Escalate through the process-tree shutdown path when needed.
6. Close managed terminals and suppress expected wait errors for requested stops.

Failed startup uses the same cleanup path. If initialize, session/new, or session/load fails after the process was launched, AGH stops the process before returning the startup error.

Agent-Initiated Safe Spawn

An active agent can request a child session through agh spawn. This is separate from normal session creation: AGH validates the caller identity, requires a positive TTL, keeps the child inside the parent's workspace and coordination channel, denies coordinator-role children, and only permits permission subsets of the parent session.

Safe-spawn children are recorded as spawned sessions with parent/root lineage, depth, role, TTL, and permission metadata. In the MVP, max depth is 1 and the default max children per parent is 5. Parent-stop and TTL expiry cleanup release active task-run leases through the task service before stopping the child session.

Use Safe Spawn for command flags, constraints, and lifecycle hooks.

Edge cases

Related pages

• Agent Definitions shows how the launch inputs are declared.
• Providers lists the built-in provider commands.
• Session Lifecycle explains how the spawned process is wrapped by a durable AGH session.
• Safe Spawn covers agent-initiated child sessions.