feat(agents): dispatch Claude Code CLI runs as persistent, resumable subagents

[gyant]

feat(agents): dispatch Claude Code CLI runs as persistent, resumable subagents

Summary

This PR enables a workflow for dispatching Claude Code CLI processes as kept subagents that run in specific project directories, pick up MCP tools via .mcp.json, and support iterative follow-up — all driven by the existing lifecycle/announce pipeline without cron or polling.

Spawn a subagent into a git worktree → it discovers project-specific MCP servers → it completes and announces its result → you follow up to refine → the cycle continues with full prior context.

Motivation

The built-in subagent system and CLI backends (claude-cli) already support spawning headless Claude Code runs. With cleanup: "keep", sessions persist and can be resumed. But two gaps prevented this from being useful for multi-turn coding workflows:

1. No way to follow up. The announce message didn't include the child session key, the subagent didn't expect follow-ups, and async sends silently dropped results. The main agent had no structured path to iterate on a subagent's work.

2. No way to control where the process runs. The CLI process always launched in the agent's configured workspace directory (~/.openclaw/workspace by default). If your project has a .mcp.json that provides MCP tools, the subagent never sees them — and telling it to cd to your project breaks MCP discovery since servers are initialized relative to the process cwd at startup.

Changes

Working directory separation (cwd)

The sessions_spawn tool now accepts an optional cwd parameter that controls where the CLI/embedded process actually runs, independently from the agent's workspace directory.

• workspaceDir — the agent's home for memory, bootstrap files, skills, and state. Resolved from agent config as before.
• cwd — where the process runs. Defaults to workspaceDir when not specified. When set, only affects spawn() in the CLI runner and process.chdir() / createAgentSession({ cwd }) in the embedded runner.

Nothing is written into the cwd directory by the agent framework — no AGENTS.md, SOUL.md, or other scaffolding. The typical workflow:

1. Create a git worktree for the task
2. Spawn a subagent with cwd pointing at the worktree
3. The Claude CLI process starts in the worktree, discovers .mcp.json, and gets project-specific MCP tools
4. Follow up as needed, clean up the worktree when done

Files: sessions-spawn-tool.ts (schema + passthrough), agent.ts (protocol schema), server-methods/agent.ts (handler), agent/types.ts (opts), agent.ts (command), cli-runner.ts (spawn), pi-embedded-runner/run.ts + run/attempt.ts + run/params.ts + run/types.ts (embedded runner)

Follow-up messaging to kept subagent sessions

When a subagent is spawned with cleanup: "keep", the main agent can now send follow-up messages that build on the subagent's full prior context. Three things were missing:

Announce message includes follow-up key (subagent-announce.ts)

When cleanup === "keep", the announce trigger now appends the child session key and a hint that sessions_send can continue the conversation.

Subagent system prompt is context-aware (subagent-announce.ts, sessions-spawn-tool.ts)

buildSubagentSystemPrompt gains an optional resumable parameter. When the spawn tool passes resumable: true, the subagent prompt swaps "Be ephemeral" for "Resumable — your session persists after completion. You may receive follow-up messages."

Async follow-ups register for announce delivery (sessions-send-tool.ts)

When sessions_send dispatches async (timeoutSeconds: 0) to a subagent session key, it now calls registerSubagentRun — the same registration that sessions_spawn uses. This wires follow-ups into the existing lifecycle → announce pipeline so results are delivered back automatically.

CLI output available for announce flows (agent.ts, chat.ts)

CLI-backed runs don't write to the gateway chat store, so readLatestAssistantReply returned nothing when the announce flow tried to read the subagent's output. Now, CLI output is injected via chat.inject before emitting the lifecycle event. The handler accepts createIfMissing: true so transcripts can be bootstrapped on first write.

Design rationale

The sessions_send follow-up path reuses the full subagent lifecycle pipeline (registerSubagentRun → lifecycle listener → runSubagentAnnounceFlow → finalizeSubagentCleanup) rather than building a parallel delivery mechanism. Each follow-up generates a unique runId, so multiple concurrent follow-ups to different subagents are tracked independently.

The cwd / workspaceDir separation is intentionally minimal — cwd only affects the process working directory, not skills resolution, bootstrap file loading, or any other agent state. This keeps the security model intact: the operator controls the workspace via config, while cwd lets the orchestrating agent point tasks at specific project directories.

Testing

pnpm build && pnpm check && pnpm test

Type-check clean, formatter clean, all 252 tests pass (41 test files).

Verified manually:

• sessions_spawn with cleanup: "keep" — announce message includes the follow-up session key
• sessions_send to the child session key — subagent resumes with full prior context
• sessions_spawn with cwd pointing at a project with .mcp.json — CLI process discovers MCP servers
• Spawning a new subagent and asking "What's the last thing I asked you?" — correctly reports no history, confirming session isolation
• Async sessions_send results announced back automatically via the lifecycle flow

Sign-Off

• AI-assisted: Yes — developed collaboratively with Claude (Opus 4.6)
• Testing: Type-check clean, all existing tests pass, manual verification confirmed above

[greptile-apps]

_{3 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Additional Comments (1)

src/gateway/server-methods/chat.ts
chat.inject bypasses send policy
chat.inject appends an assistant message after only loadSessionEntry succeeds; it does not enforce resolveSendPolicy (unlike chat.send). With createIfMissing: true, this means any gateway caller with access to this method can write assistant messages into transcripts for sessions where messaging would otherwise be denied by policy.

If chat.inject is intended to be internal-only, it should enforce an equivalent policy/scope check (or reuse resolveSendPolicy) before writing the transcript.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/gateway/server-methods/chat.ts
Line: 661:668

Comment:
**chat.inject bypasses send policy**
`chat.inject` appends an assistant message after only `loadSessionEntry` succeeds; it does not enforce `resolveSendPolicy` (unlike `chat.send`). With `createIfMissing: true`, this means any gateway caller with access to this method can write assistant messages into transcripts for sessions where messaging would otherwise be denied by policy.

If `chat.inject` is intended to be internal-only, it should enforce an equivalent policy/scope check (or reuse `resolveSendPolicy`) before writing the transcript.

How can I resolve this? If you propose a fix, please make it concise.

[openclaw-barnacle]

This pull request has been automatically marked as stale due to inactivity.
Please add updates or it will be closed.