<!-- source: https://deepwiki.com/openclaw/openclaw/3.8-acp-and-sub-agents -->

# ACP & Sub-Agents

- docs/plugins/hooks.md
- scripts/check-kysely-guardrails.mjs
- src/acp/control-plane/manager.cancel-session.test.ts
- src/acp/control-plane/manager.cancel-session.ts
- src/acp/control-plane/manager.close-session.ts
- src/acp/control-plane/manager.core.ts
- src/acp/control-plane/manager.initialize-session.test.ts
- src/acp/control-plane/manager.initialize-session.ts
- src/acp/control-plane/manager.runtime-config.test.ts
- src/acp/control-plane/manager.runtime-controls.ts
- src/acp/control-plane/manager.runtime-handle-cache.ts
- src/acp/control-plane/manager.runtime-handle-ensure.ts
- src/acp/control-plane/manager.runtime-options-commands.ts
- src/acp/control-plane/manager.runtime-resume-state.ts
- src/acp/control-plane/manager.startup-identity-reconcile.test.ts
- src/acp/control-plane/manager.startup-identity-reconcile.ts
- src/acp/control-plane/manager.status.ts
- src/acp/control-plane/manager.test.ts
- src/acp/control-plane/manager.turn-runner.ts
- src/acp/control-plane/manager.types.ts
- src/acp/control-plane/runtime-cache.test.ts
- src/acp/control-plane/runtime-cache.ts
- src/agents/agent-steering-queue.test.ts
- src/agents/agent-steering-queue.ts
- src/agents/openclaw-tools.sessions.test.ts
- src/agents/subagent-announce-output.test.ts
- src/agents/subagent-announce-output.ts
- src/agents/subagent-delivery-state.test.ts
- src/agents/subagent-delivery-state.ts
- src/agents/subagent-orphan-recovery.test.ts
- src/agents/subagent-registry-lifecycle.test.ts
- src/agents/subagent-registry-lifecycle.ts
- src/agents/subagent-registry-run-manager.ts
- src/agents/subagent-registry.steer-restart.test.ts
- src/agents/subagent-registry.test.ts
- src/agents/subagent-registry.ts
- src/agents/subagent-registry.types.ts
- src/agents/subagent-run-liveness.ts
- src/agents/subagent-run-timeout.test.ts
- src/agents/subagent-run-timeout.ts
- src/agents/subagent-session-reconciliation.ts
- src/agents/tools/agent-step.test.ts
- src/agents/tools/agent-step.ts
- src/agents/tools/sessions-send-tool.ts
- src/agents/tools/sessions.test.ts
- src/agents/utils/paths.ts
- src/auto-reply/reply/context-text.ts
- src/auto-reply/reply/dispatch-acp-command-bypass.test.ts
- src/auto-reply/reply/dispatch-acp-command-bypass.ts
- src/auto-reply/reply/dispatch-acp-delivery.test.ts
- src/auto-reply/reply/dispatch-acp-delivery.ts
- src/auto-reply/reply/dispatch-acp.ts
- src/auto-reply/reply/dispatch-from-config.test.ts
- src/auto-reply/reply/dispatch-from-config.ts
- src/auto-reply/reply/effective-reply-route.test.ts
- src/auto-reply/reply/effective-reply-route.ts
- src/commands/agent/session.test.ts
- src/infra/kysely-sync.ts
- src/plugin-sdk/acp-runtime-backend.ts
- src/plugin-sdk/acp-runtime.test.ts
- src/plugins/hook-types.ts
- src/shared/subagents-format.test.ts
- src/shared/subagents-format.ts

The **Agent Control Protocol (ACP)** and the **Sub-Agent** system provide a framework for orchestrating multi-agent workflows within OpenClaw. This system empowers a "parent" agent to delegate discrete tasks to "child" agents, which execute in isolated sessions and report results back asynchronously to the requester.

## Agent Control Protocol (ACP)

ACP is a dedicated runtime harness designed for multi-session orchestration involving external AI CLI tools (e.g., Codex, Claude Code, Gemini CLI, Cursor). It extends the sub-agent model by supporting session resumption, streaming output routing, and advanced configuration [src/acp/control-plane/manager.core.ts1-28](https://github.com/openclaw/openclaw/blob/fbdf5937/src/acp/control-plane/manager.core.ts#L1-L28)

### ACP Session Management

The `AcpSessionManager` is the central control plane for ACP. It handles session initialization, state transitions, and persistence of session metadata [src/acp/control-plane/manager.core.ts62-77](https://github.com/openclaw/openclaw/blob/fbdf5937/src/acp/control-plane/manager.core.ts#L62-L77)

- Session Initialization: The initializeSession method prepares the runtime environment, enforces concurrent session limits, and writes the initial session metadata src/acp/control-plane/manager.core.ts 145-168
- Turn Execution: runTurn manages the execution of a single interaction turn, tracking latency stats and handling streaming output via the AcpRuntime src/acp/control-plane/manager.core.ts 243-260
- Observability: The manager provides snapshots of active turns, queue depth, and average latency to monitor system health src/acp/control-plane/manager.core.ts 112-130
- Identity Reconcile: Upon gateway startup, reconcilePendingSessionIdentities restores state for sessions that were active before a restart src/acp/control-plane/manager.core.ts 132-143

**Sources:** [src/acp/control-plane/manager.core.ts62-260](https://github.com/openclaw/openclaw/blob/fbdf5937/src/acp/control-plane/manager.core.ts#L62-L260) [src/acp/control-plane/manager.test.ts54-103](https://github.com/openclaw/openclaw/blob/fbdf5937/src/acp/control-plane/manager.test.ts#L54-L103)

## Sub-Agent System Architecture

Sub-agents are isolated agent sessions launched by a parent session. Each sub-agent runs in its own session key space, typically identified by a `subagent` segment in the key [src/agents/subagent-registry.test.ts189-192](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/subagent-registry.test.ts#L189-L192)

### Sub-Agent Registry

The `subagent-registry.ts` tracks active runs, maintaining a mapping between `runId`, `childSessionKey`, and the `requesterSessionKey` (the parent) [src/agents/subagent-registry.ts52-78](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/subagent-registry.ts#L52-L78)

### Lifecycle & Cleanup

The `createSubagentRegistryLifecycleController` manages the terminal states of a sub-agent run [src/agents/subagent-registry-lifecycle.ts115-145](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/subagent-registry-lifecycle.ts#L115-L145)

- Completion Reasons: Runs can end with SUBAGENT_ENDED_REASON_COMPLETE , SUBAGENT_ENDED_REASON_ERROR , or SUBAGENT_ENDED_REASON_KILLED src/agents/subagent-registry.ts 32-37
- Resource Cleanup: Upon completion, the system triggers cleanupBrowserSessionsForLifecycleEnd to terminate associated browser automation instances src/agents/subagent-registry-lifecycle.ts 73-77 and can purge session artifacts if the cleanup mode is set to delete src/agents/subagent-registry-run-manager.ts 45-47
- Task Integration: Sub-agent outcomes are reported back to the detached-task-runtime to update the status of background tasks src/agents/subagent-registry-lifecycle.ts 11-14

**Sources:** [src/agents/subagent-registry.ts52-78](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/subagent-registry.ts#L52-L78) [src/agents/subagent-registry-lifecycle.ts11-145](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/subagent-registry-lifecycle.ts#L11-L145) [src/agents/subagent-registry-run-manager.ts45-47](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/subagent-registry-run-manager.ts#L45-L47)

## Technical Data Flow: Spawn to Announcement

The orchestration involves a tool-triggered spawn followed by an asynchronous completion announcement.

### Sub-Agent Orchestration Flow

```

```

**Sources:** [src/agents/tools/sessions-send-tool.ts202-230](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/tools/sessions-send-tool.ts#L202-L230) [src/agents/subagent-registry.ts105-123](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/subagent-registry.ts#L105-L123) [src/agents/subagent-registry-run-manager.ts158-204](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/subagent-registry-run-manager.ts#L158-L204) [src/agents/subagent-registry-lifecycle.ts115-145](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/subagent-registry-lifecycle.ts#L115-L145)

### Delivery Dispatch

When a task completes, the system handles the delivery of results back to the original channel.

- Wait Mechanism: The system uses waitForAgentRun to poll for completion via the agent.wait RPC method src/agents/subagent-registry-run-manager.ts 11
- Outcome Timing: withSubagentOutcomeTiming wraps the result to track execution duration and success metrics src/agents/subagent-registry-run-manager.ts 13
- Idempotency: Idempotency keys are generated to prevent duplicate completion announcements src/agents/subagent-registry-lifecycle.ts 21-24
- Recovery: Recoverable errors (like timeouts) trigger a retry logic with backoff src/agents/subagent-registry-run-manager.ts 42-43

**Sources:** [src/agents/subagent-registry-run-manager.ts11-43](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/subagent-registry-run-manager.ts#L11-L43) [src/agents/subagent-registry-lifecycle.ts21-24](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/subagent-registry-lifecycle.ts#L21-L24)

## Code Entity Map: Sessions Send Logic

The `sessions-send` tool serves as a primary interface for agents to communicate with other sessions, including sub-agents.

```

```

**Sources:** [src/agents/tools/sessions-send-tool.ts56-88](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/tools/sessions-send-tool.ts#L56-L88) [src/agents/tools/sessions-send-tool.ts202-230](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/tools/sessions-send-tool.ts#L202-L230) [src/acp/control-plane/manager.core.ts145-168](https://github.com/openclaw/openclaw/blob/fbdf5937/src/acp/control-plane/manager.core.ts#L145-L168) [src/agents/subagent-registry.ts52-65](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/subagent-registry.ts#L52-L65)

### Tool Parameter Resolution

The system normalizes parameters like `message` and `sessionKey` before dispatching to the specific delivery logic [src/agents/tools/sessions-send-tool.ts68-88](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/tools/sessions-send-tool.ts#L68-L88)

**Sources:** [src/agents/tools/sessions-send-tool.ts56-88](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/tools/sessions-send-tool.ts#L56-L88) [src/agents/subagent-registry-run-manager.ts145](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/subagent-registry-run-manager.ts#L145-L145)

## Persistent Bindings

OpenClaw supports **Session Bindings**, allowing sub-agents and ACP sessions to "own" a specific messaging conversation or thread.

- Conversation Binding: The resolveConversationBindingRecord identifies if a specific channel/thread is currently bound to an agent session src/auto-reply/reply/dispatch-from-config.ts 38-40
- Inbound Claim: When a message arrives, the system checks for existing bindings. If a session is bound, it claims the inbound message for that specific session src/auto-reply/reply/dispatch-from-config.ts 132
- ACP Integration: If an ACP session is parent-owned and running in the background, specific interaction rules apply to how it consumes inbound messages src/auto-reply/reply/dispatch-from-config.ts 2
- Hooks: The subagent_spawned and subagent_ended hooks allow plugins to observe and react to lifecycle changes, such as setting up custom routing or notifications src/plugins/hook-types.ts 101-102

**Sources:** [src/auto-reply/reply/dispatch-from-config.ts2-132](https://github.com/openclaw/openclaw/blob/fbdf5937/src/auto-reply/reply/dispatch-from-config.ts#L2-L132) [src/plugins/hook-types.ts101-102](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/hook-types.ts#L101-L102)
