#19136: feat(claude-code): implement spawn mode for Claude Code sub-agents

## Motivation OpenClaw agents can spawn sub-agents for background tasks, but these run as API-driven sessions with no persistent workspace. For coding tasks, this means every spawn starts from scratch — no file context, no git state, no tool access beyond what the API provides. Claude Code (CC) is purpose-built for coding: it understands repos, runs in a project directory, and maintains session state. By spawning CC as the backend instead of an API session, agents get a real coding environment. Critically, **CC sessions are resumable** — an agent can spawn a task, and the session can later be resumed in the CC CLI or VS Code extension for human review, debugging, or continuation. This bridges the gap between autonomous agent work and human-in-the-loop development. `sessions_spawn(mode: "claude-code")` operates CC as CC — not a simulation, not an API wrapper. It runs the actual CLI binary, communicates via its native NDJSON protocol, and persists sessions in CC's own format. The result is that agent-initiated coding work lives in the same session history a developer would see in their editor. ## What it does - **Spawns Claude Code CLI** as a child process with the task as input - **Streams NDJSON protocol** — parses all CC message types (assistant, result, system, tool_use/tool_result) - **Session persistence** — sessions are stored per-agent per-repo, resumable from CC CLI or VS Code - **MCP bridge** — exposes select gateway tools (web_search, web_fetch, message, memory) to CC via stdio MCP server - **Progress relay** — streams periodic summaries back to the requester's chat - **Result announcement** — announces completion/failure with stats (duration, cost, turns) - **Graceful lifecycle** — tracks active CC processes, kills orphans on gateway shutdown - **CLI**: `openclaw cc` for listing, inspecting, attaching to, and killing CC sessions ## Configuration ```jsonc // openclaw.json { "agents": { "defaults": { "subagents": { "claudeCode": { "enabled": true, "defaultRepo": "/path/to/project", "repos": { "myapp": "/path/to/myapp" }, "permissionMode": "bypassPermissions", "model": "opus", "timeoutSeconds": 600, "maxBudgetUsd": 5 } } } } } ``` ## Testing 31 unit tests covering protocol parsing, session management, binary resolution, MCP bridge, runner lifecycle, and live-state tracking. <!-- greptile_comment --> <h3>Greptile Summary</h3> This PR adds Claude Code spawn mode, enabling OpenClaw agents to delegate coding tasks to Claude Code CLI as background sub-agents. The implementation includes a complete protocol parser for NDJSON streaming, session management with persistence, an MCP bridge to expose OpenClaw tools to Claude Code, and graceful lifecycle management. **Key Changes:** - New `src/agents/claude-code/` module with protocol parser, runner, session registry, MCP bridge, and live-state tracking - Integration into `sessions_spawn` tool with `mode: "claude-code"` parameter - Configuration schema for Claude Code settings in agent defaults - CLI command `openclaw cc` for session management (list, info, attach, kill, costs) - Gateway shutdown hooks to clean up orphaned child processes - 31 unit tests covering protocol parsing, session management, and runner lifecycle **Architecture Highlights:** - Bidirectional NDJSON communication via stdin/stdout with Claude Code CLI - Per-repo concurrency control (1 active + 1 queued spawn) - Progress relay with periodic summaries sent to chat - MCP bridge exposes 4 tools: conversation context, memory search, announce, session info - Idle debounce timeout (30s) works around Claude Code CLI bugs where result messages are missing - Persistent session mode for follow-up messages with 30-minute idle timeout - Session registry persists to `~/.openclaw/agents/{agentId}/claude-code-sessions.json` **Testing:** - Comprehensive unit test coverage (31 tests) - Protocol parsing validated for all message types - Session registry CRUD operations tested - Binary resolution with fallback handling tested <h3>Confidence Score: 4/5</h3> - Safe to merge with thorough testing and clean architecture - Strong implementation with comprehensive test coverage (31 tests), proper error handling, graceful shutdown mechanisms, and well-structured protocol parsing. Environment variables are properly cleaned to prevent nested session issues. The MCP bridge correctly escapes JSON inputs to prevent injection. Minor concern about the idle debounce workaround for upstream CLI bugs, but this is documented and includes active child process detection as a safeguard. - No files require special attention _{Last reviewed commit: f991bfa} <!-- greptile_other_comments_section --> _{(3/5) Reply to the agent's comments like "Can you suggest a fix for this @greptileai?" or ask follow-up questions!} <!-- /greptile_comment -->