openclaw-code-agent 2.3.1 → 3.1.0

package/README.md

@@ -4,66 +4,52 @@
 [![npm downloads](https://img.shields.io/npm/dm/openclaw-code-agent.svg)](https://www.npmjs.com/package/openclaw-code-agent)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-An [OpenClaw](https://openclaw.com) plugin that lets AI agents orchestrate coding agent sessions as managed background processes. Launch, monitor, and interact with multiple concurrent coding sessions directly from Telegram, Discord, or any OpenClaw-supported messaging platform — without leaving your chat interface.
+`openclaw-code-agent` is the OpenClaw plugin for running Claude Code and Codex as managed background coding sessions from chat. Launch work from Telegram, Discord, or any OpenClaw-supported channel, review the plan before execution, keep the job isolated in its own git worktree, and merge or open a PR without leaving the thread.
 
-## Why?
+- **Plan -> Review -> Execute**. `plan` is the default launch mode, with `ask`, `delegate`, and `approve` deciding how much plan approval autonomy the orchestrator gets.
+- **Optional worktree isolation**. New sessions default to `off`; opt into `ask`, `delegate`, `auto-merge`, or `auto-pr` when you want worktree-backed branch isolation and post-run branch handling.
+- **State-driven decision UX**. `ask` sends explicit action buttons for **Merge locally**, **Create PR**, **Decide later**, and **Dismiss**. The same action-token model now backs both Telegram and Discord interactive callbacks.
+- **Full session lifecycle**. Suspend, resume, fork, interrupt, and recover sessions across restarts with persisted metadata and output.
+- **Real operator visibility**. `agent_sessions`, `agent_output`, and `agent_stats` show status, buffered output, duration, and USD cost.
+- **Two harnesses, one control plane**. Claude Code and Codex share the same tools, routing, notification pipeline, and worktree strategy model while each backend uses its own native execution substrate.
+- **One continuation primitive**. `agent_respond` is the only way to continue, approve, revise, or redirect an existing session. Forks still go through `agent_launch(..., resume_session_id=..., fork_session=true)`.
 
-This plugin started as a response to a real gap in OpenClaw's built-in ACP support. At the time, ACP was effectively a raw relay into ACP backends: useful for handing off a prompt, but without the orchestration layer needed for coding-agent work in chat. There was no plan review flow, no plugin-managed pause/resume model, no fork flow, no cost or session stats, and no async notification path back to the originating chat when a session needed input or finished.
+Need the version-pinned ACP breakdown? See [docs/ACP-COMPARISON.md](docs/ACP-COMPARISON.md).
 
-ACP has improved since then. OpenClaw core ACP now supports multi-turn sessions, resuming prior work, and a broader set of ACP runtimes and harnesses. That closes part of the original gap.
+## From Prompt To Merged Branch
 
-What still remains is the orchestration layer this plugin was built to provide: propose/revise/approve plan review before execution, forkable coding sessions, dedicated session catalog + operator-facing stats, cost accounting, and an explicit async notification pipeline that wakes the origin chat only when the job needs attention or completes.
+1. Launch a coding session from chat with `/agent ...` or `agent_launch(...)`.
+2. Review the plan in the same thread before anything touches the repo.
+3. Let the agent finish in an isolated worktree, then merge or publish the result from chat.
 
-For the current version-pinned breakdown, see [docs/ACP-COMPARISON.md](docs/ACP-COMPARISON.md).
+### Plan First
 
-## Demo
-<img src="assets/ask-readme.gif" alt="Ask mode demo showing plan review and approval before execution">
+The differentiator is the plan-review loop. Claude Code and Codex both feed the same review UX now: the plugin receives a structured plan artifact, keeps execution blocked until approval, and resumes the same session with `agent_respond(..., approve=true)`.
 
-*Plan review and approval in ask mode: the agent pauses for your decision before executing.*
+<img src="assets/ask-readme.gif" alt="Plan review in ask mode with inline approval controls">
 
-### Autonomous mode (delegate)
+*`ask` mode keeps the human in the loop: the plan lands back in the originating thread, and execution only starts after approval.*
 
-<img src="assets/delegate-readme.gif" alt="Delegate mode demo showing autonomous execution with selective escalation">
+### Finish Cleanly
 
-*In delegate mode, the orchestrator auto-approves low-risk plans and only escalates when needed.*
+When the task is done, the plugin can leave the branch for review, merge it automatically, or help create a PR. In `ask`, the user gets the same explicit decision buttons in the originating thread. In `delegate`, the orchestrator receives the diff context, may merge if safe, and always escalates PR decisions to the user. Planning artifacts belong in `/tmp/` — the agent will not commit analysis notes to the branch.
 
-## Supported Agents
+<img src="assets/delegate-readme.gif" alt="Delegated worktree flow with autonomous follow-through">
 
-| Agent | Status | Notes |
-|-------|--------|-------|
-| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | ✅ Supported | Full support via `@anthropic-ai/claude-agent-sdk` |
-| [Codex](https://github.com/openai/codex) | ✅ Supported | Full support via `@openai/codex-sdk` thread API |
-| Other agents | 🚧 Planned | Plugin architecture supports adding new harnesses |
+*The main checkout stays clean. The branch lifecycle happens in the worktree, and the chat thread stays current on what was shipped.*
 
-> **vs. built-in ACP?** See [docs/ACP-COMPARISON.md](docs/ACP-COMPARISON.md) for the current version-pinned breakdown.
+## Supported Harnesses
 
----
+| Harness | Status | Notes |
+| --- | --- | --- |
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Supported | Native harness via `@anthropic-ai/claude-agent-sdk` |
+| [Codex](https://github.com/openai/codex) | Supported | Native harness via Codex App Server over stdio |
 
-## Features
-
-- **Multi-session management** — Run multiple concurrent coding agent sessions, each with a unique ID and human-readable name
-- **Plan → Execute workflow** — Claude Code sessions expose plan mode; Codex uses a soft first-turn planning prompt while staying externally in implement mode
-- **Real Codex approval policy support** — Codex sessions default to the real Codex SDK/CLI `approvalPolicy: "on-request"` and can be pinned back to `"never"` via `harnesses.codex.approvalPolicy`
-- **Thread-based routing** — Notifications go to the Telegram thread/topic where the session was launched
-- **Pause + auto-resume** — Non-question turn completion pauses sessions (`done`) and next `agent_respond` auto-resumes with context intact
-- **Turn-end wake signaling** — Every turn end emits a deterministic wake signal with output preview and waiting hint
-- **Smart waiting detection** — Heuristic waiting detector reduces false-positive wake escalations
-- **Multi-turn conversations** — Send follow-up messages, interrupt, or iterate with a running agent
-- **Session resume & fork** — Resume any completed session or fork it into a new conversation branch
-- **Merged session listing** — `agent_sessions` shows active + persisted sessions in one view (deduped by internal session ID)
-- **Pending MessageStream safety** — queued follow-ups are preserved across turn completion so messages are not dropped
-- **Codex SDK streaming harness** — uses `@openai/codex-sdk` thread streaming with soft first-turn planning, waiting detection, and activity heartbeats
-- **Multi-agent support** — Route notifications to the correct agent/chat via workspace-based channel mapping
-- **Auto-respond rules** — Orchestrator auto-handles permission requests and confirmations; forwards real decisions to you
-- **Anti-cascade protection** — Orchestrator never launches new sessions from wake events
-- **Automatic cleanup** — Completed sessions are garbage-collected after a configurable TTL (`sessionGcAgeMinutes`, default 24h); IDs persist for resume
-- **Harness-agnostic architecture** — Pluggable `AgentHarness` interface allows adding new coding agent backends
-
----
+Launches and notifications work from Telegram, Discord, or any OpenClaw-supported channel. Telegram and Discord now share the same action-token callback flow for plan approvals, question options, resume/restart, and worktree decisions.
 
 ## Quick Start
 
-### 1. Install the plugin
+Install and enable the plugin:
 
 ```bash
 openclaw plugins install openclaw-code-agent
@@ -71,9 +57,7 @@ openclaw plugins enable openclaw-code-agent
 openclaw gateway restart
 ```
 
-### 2. Configure notifications
-
-Add to `~/.openclaw/openclaw.json` under `plugins.entries["openclaw-code-agent"]`:
+Add a minimal config block under `plugins.entries["openclaw-code-agent"]` in `~/.openclaw/openclaw.json`:
 
 ```json
 {
@@ -83,17 +67,17 @@ Add to `~/.openclaw/openclaw.json` under `plugins.entries["openclaw-code-agent"]
         "enabled": true,
         "config": {
           "fallbackChannel": "telegram|my-bot|123456789",
-          "maxSessions": 20,
+          "planApproval": "ask",
+          "defaultWorktreeStrategy": "off",
           "harnesses": {
-            "codex": {
-              "defaultModel": "gpt-5.4",
-              "allowedModels": ["gpt-5.4"],
-              "reasoningEffort": "medium",
-              "approvalPolicy": "on-request"
-            },
             "claude-code": {
               "defaultModel": "sonnet",
               "allowedModels": ["sonnet", "opus"]
+            },
+            "codex": {
+              "defaultModel": "gpt-5.4",
+              "allowedModels": ["gpt-5.4"],
+              "reasoningEffort": "medium"
             }
           }
         }
@@ -103,336 +87,73 @@ Add to `~/.openclaw/openclaw.json` under `plugins.entries["openclaw-code-agent"]
 }
 ```
 
-Replace `my-bot` with your Telegram bot account name and `123456789` with your Telegram chat ID.
-
-### 2a. Codex auth safety
-
-If you run Codex sessions, strongly recommend forcing ChatGPT login in your Codex config:
+If you run Codex sessions, keep Codex on the ChatGPT auth path:
 
 ```toml
 forced_login_method = "chatgpt"
 ```
 
-Put that in `~/.codex/config.toml`. This keeps Codex on the ChatGPT auth path and avoids account/login mismatches that can surface as unsupported-model or auth failures.
+Put that in `~/.codex/config.toml`.
 
-### 3. Typical workflow
+Codex approval behavior is fixed to the supported execution path, and OpenClaw handles review gates through `permissionMode` plus `planApproval`.
 
-1. Ask your agent: *"Fix the bug in auth.ts"*
-2. A coding agent session launches and explores the task. Claude Code exposes **plan mode**; Codex can do a plan-first turn without surfacing plan mode in session status
-3. The agent's questions and plan appear in the **same Telegram thread** where you launched
-4. When a session is awaiting plan approval, approve it with `agent_respond(..., approve=true)` and the session switches to implement mode
-5. The agent implements with full permissions, then you get a brief completion summary
-
----
-
-## Tools
-
-| Tool | Description | Key Parameters |
-|------|-------------|----------------|
-| `agent_launch` | Start a new coding agent session in background | `prompt`, `name`, `workdir`, `model`, `resume_session_id`, `fork_session`, `permission_mode`, `harness` |
-| `agent_respond` | Send a follow-up message to a running session | `session`, `message`, `interrupt`, `approve`, `userInitiated` |
-| `agent_kill` | Terminate or complete a running session | `session`, `reason` |
-| `agent_output` | Read buffered output from a session | `session`, `lines`, `full` |
-| `agent_sessions` | List recent sessions (5 by default, `full` for 24h view) | `status`, `full` |
-| `agent_stats` | Show usage metrics (counts, durations, costs) | *(none)* |
-
-Core orchestration workflows use `agent_launch`, `agent_respond`, `agent_output`, `agent_sessions`, and `agent_kill`.
-
-All tools are also available as **chat commands** (`/agent`, `/agent_respond`, `/agent_kill`, `/agent_sessions`, `/agent_resume`, `/agent_stats`, `/agent_output`).
-
----
-
-## Usage Examples
+Launch a first session:
 
 ```bash
-# Launch a session (starts in plan mode by default)
-/agent Fix the authentication bug in src/auth.ts
-/agent --name fix-auth Fix the authentication bug
-
-# Monitor
+/agent --name fix-auth Fix the auth middleware bug
 /agent_sessions
-/agent_sessions --full
-
-# Interact with a running session
-/agent_respond fix-auth Also add unit tests
-/agent_respond --interrupt fix-auth Stop that and do this instead
-
-# Approve a pending plan (tool call)
-agent_respond(session='fix-auth', message='Approved. Go ahead.', approve=true)
-
-# Lifecycle management
-/agent_kill fix-auth
-/agent_resume fix-auth Add error handling
-/agent_resume --fork fix-auth Try a different approach
-/agent_stats
-```
-
----
-
-## Notifications
-
-The plugin sends targeted notifications to the originating Telegram thread:
-
-| Emoji | Event | Description |
-|-------|-------|-------------|
-| 🚀 | Launched | Session started with prompt summary |
-| ❓ | Waiting for input | Session is waiting for user input |
-| 📋 | Plan ready | Plan approval requested — reply "go" to approve |
-| ⏸️ | Paused after turn | Turn completed, session paused (auto-resumable) |
-| ↪️ | Redirected | Active work was intentionally interrupted and redirected in-place |
-| ▶️ | Auto-resumed | Session resumed on the next `agent_respond` |
-| ✅ | Completed | Completion summary with cost and duration |
-| ❌ | Failed | Error notification with hint |
-| 💤 | Idle timeout | Session timed out while waiting; auto-resumes on next respond |
-| ⛔ | Stopped | Session was stopped by user, shutdown, or another forced stop |
-
----
-
-## Plan → Execute Mode Switch
-
-- **Claude Code** starts in `plan` mode by default. Approve a pending plan with `agent_respond(..., approve=true)` and the session switches to `bypassPermissions`.
-- **Codex** does not surface `plan` or `awaiting-plan-approval` in session state. When launched with `permissionMode: "plan"`, its first turn is prompted to return a plan and ask whether to proceed, while the exposed session phase remains implementation-oriented.
-- For **Codex**, plugin `permissionMode` is a plugin-orchestrated planning/approval workflow. It is not the same thing as the Codex SDK/CLI `approvalPolicy`.
-- The real Codex SDK/CLI approval behavior is controlled by `harnesses.codex.approvalPolicy`. Supported values are `"on-request"` (default) and `"never"`.
-
-On approval, the plugin prepends a system instruction telling the agent to exit plan mode and implement with full permissions.
-
----
-
-## Auto-Respond Rules
-
-The orchestrator agent follows strict auto-respond rules to minimize noise:
-
-**Auto-respond (immediate):**
-- Permission requests (file read/write/bash) → "Yes, proceed."
-- Explicit "should I continue?" confirmations → "Yes, continue."
-
-**Forward to user (everything else):**
-- Architecture/design decisions
-- Destructive operations
-- Scope changes
-- Credential/production questions
-- Any ambiguous or non-trivial question
-
-When forwarding, the orchestrator quotes the agent's exact question without adding its own commentary.
-
----
-
-## Configuration
-
-Set values in `~/.openclaw/openclaw.json` under `plugins.entries["openclaw-code-agent"].config`:
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `agentChannels` | `object` | — | Map workdir paths → notification channels (see [docs/AGENT_CHANNELS.md](docs/AGENT_CHANNELS.md)) |
-| `fallbackChannel` | `string` | — | Default notification channel when no workspace match found |
-| `maxSessions` | `number` | `20` | Maximum concurrent sessions |
-| `maxAutoResponds` | `number` | `10` | Max consecutive auto-responds before requiring user input |
-| `permissionMode` | `string` | `"plan"` | Plugin orchestration mode: `"default"` / `"plan"` / `"acceptEdits"` / `"bypassPermissions"` |
-| `idleTimeoutMinutes` | `number` | `15` | Idle timeout before auto-kill |
-| `sessionGcAgeMinutes` | `number` | `1440` | TTL for completed/failed/killed runtime sessions before GC eviction |
-| `maxPersistedSessions` | `number` | `10000` | Max completed sessions kept for resume; the 24h GC TTL (`sessionGcAgeMinutes`) is the primary retention control |
-| `planApproval` | `string` | `"delegate"` | `"approve"` (orchestrator can auto-approve) / `"ask"` (always forward to user) / `"delegate"` (orchestrator decides) |
-| `defaultHarness` | `string` | `"claude-code"` | Default harness for new sessions (`"claude-code"` / `"codex"`) |
-| `harnesses` | `object` | built-in defaults | Per-harness defaults and restrictions. Built-in defaults: `claude-code.defaultModel = "sonnet"`, `claude-code.allowedModels = ["sonnet","opus"]`, `codex.defaultModel = "gpt-5.4"`, `codex.allowedModels = ["gpt-5.4"]`, `codex.reasoningEffort = "medium"`, `codex.approvalPolicy = "on-request"` |
-| `defaultWorkdir` | `string` | — | Default working directory for new sessions |
-
-### Permission Mode Mapping By Harness
-
-Permission modes are shared at the plugin API, but each harness maps them differently:
-
-- **Claude Code harness**
-  - `default`, `plan`, `acceptEdits`, `bypassPermissions` are passed through the SDK
-- **Codex harness**
-  - Always runs with SDK thread option `sandboxMode: "danger-full-access"`
-  - Uses Codex SDK/CLI `approvalPolicy: "on-request"` by default, or `"never"` when `harnesses.codex.approvalPolicy` is set
-  - Supports `harnesses.codex.defaultModel`, `harnesses.codex.allowedModels`, `harnesses.codex.reasoningEffort`, and `harnesses.codex.approvalPolicy`
-  - In `bypassPermissions`, the harness adds filesystem root (`/` on POSIX) to Codex `additionalDirectories`, plus optional extras from `OPENCLAW_CODEX_BYPASS_ADDITIONAL_DIRS` (comma-separated)
-  - `setPermissionMode()` is applied by recreating the thread on the next turn via `resumeThread` (same thread ID)
-  - `plan` / `acceptEdits` remain plugin behavioral orchestration constraints (planning/approval flow), not Codex sandbox or SDK approval settings
-
-### Runtime Environment Overrides
-
-- `OPENCLAW_CODE_AGENT_SESSIONS_PATH` — explicit persisted session index path
-- `OPENCLAW_HOME` — base dir for persisted session index when explicit path is unset (`$OPENCLAW_HOME/code-agent-sessions.json`)
-- `OPENCLAW_CODEX_BYPASS_ADDITIONAL_DIRS` — comma-separated extra directories for Codex bypass mode
-- `OPENCLAW_CODEX_HEARTBEAT_MS` — Codex activity heartbeat interval in milliseconds (default `10000`)
-
-### Session Lifecycle + GC
-
-- Active sessions live in runtime memory (`SessionManager.sessions`)
-- Terminal sessions are persisted with metadata/output stubs for resume and listing
-- Runtime records are evicted after `sessionGcAgeMinutes` (default 1440 / 24h)
-- Eviction means **removed from runtime cache**, not deleted permanently; persisted session records remain resumable
-
-### Example
-
-```json
-{
-  "plugins": {
-    "entries": {
-      "openclaw-code-agent": {
-        "enabled": true,
-        "config": {
-          "maxSessions": 3,
-          "harnesses": {
-            "codex": {
-              "defaultModel": "gpt-5.4",
-              "allowedModels": ["gpt-5.4"],
-              "reasoningEffort": "high",
-              "approvalPolicy": "on-request"
-            },
-            "claude-code": {
-              "defaultModel": "sonnet",
-              "allowedModels": ["sonnet", "opus"]
-            }
-          },
-          "permissionMode": "plan",
-          "fallbackChannel": "telegram|my-bot|123456789",
-          "agentChannels": {
-            "/home/user/project-alpha": "telegram|my-bot|123456789",
-            "/home/user/project-beta": "telegram|ops-bot|987654321"
-          }
-        }
-      }
-    }
-  }
-}
-```
-
----
-
-## Orchestration Skill
-
-<details>
-<summary>Example orchestration skill (click to expand)</summary>
-
-The plugin is a **transparent transport layer** — business logic lives in **OpenClaw skills**:
-
-```markdown
----
-name: Coding Agent Orchestrator
-description: Orchestrates coding agent sessions with auto-response rules.
-metadata: {"openclaw": {"requires": {"plugins": ["openclaw-code-agent"]}}}
----
-
-# Coding Agent Orchestrator
-
-## Anti-cascade rule
-When woken by a waiting-for-input or completion event, ONLY use agent_respond
-or agent_output for the referenced session. NEVER launch new sessions from wake events.
-
-## Auto-response rules
-
-When a coding agent session asks a question, analyze and decide:
-
-### Auto-respond (use `agent_respond` immediately):
-- Permission requests for file reads, writes, or bash commands -> "Yes, proceed."
-- Confirmations like "Should I continue?" -> "Yes, continue."
-
-### Forward to user (everything else):
-- Architecture decisions, destructive operations, ambiguous requirements,
-  scope changes, credential/production questions
-- Quote the agent's exact question. No commentary.
-
-## Workflow
-1. User sends a coding task -> `agent_launch(prompt, ...)`
-2. Session runs in background. Monitor via wake events.
-3. On wake event -> `agent_output` to read the question, then auto-respond or forward.
-4. On completion -> summarize briefly: files changed, cost, duration, issues.
+/agent_respond fix-auth Add unit tests too
+agent_launch(prompt="<new task>", resume_session_id="fix-auth", fork_session=true)
 ```
 
-A comprehensive orchestration skill is available at [`skills/code-agent-orchestration/SKILL.md`](skills/code-agent-orchestration/SKILL.md).
-
-</details>
-
----
-
-## Architecture
+For multi-workspace or multi-bot setups, configure `agentChannels`. The full routing rules, config matrix, and notification behavior live in [docs/REFERENCE.md](docs/REFERENCE.md).
 
-For a detailed look at how the plugin works internally, see the [docs/](docs/) directory:
+Prefer fully routable channel strings such as `telegram|123456789` or `telegram|my-bot|123456789`. A bare provider like `telegram` is only a weak fallback; the plugin now repairs topic routing from `originSessionKey` when possible, but explicit channels are still the safer default.
 
-| Document | Description |
-|----------|-------------|
-| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design, component breakdown, and data flow |
-| [docs/NOTIFICATIONS.md](docs/NOTIFICATIONS.md) | Notification architecture, delivery model, and wake mechanism |
-| [docs/AGENT_CHANNELS.md](docs/AGENT_CHANNELS.md) | Multi-agent setup, notification routing, and workspace mapping |
-| [docs/TOOLS.md](docs/TOOLS.md) | Detailed tool reference with parameters and examples |
-| [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | Development guide, project structure, and build instructions |
+### Upgrade Note For 3.1.0
 
----
+`3.1.0` is a maintenance release focused on reliability, explicit session state, and release-tooling hardening.
 
-## Development
+- Upgrading archives old or invalid persisted session stores to a timestamped `.legacy-*.json` backup and starts with a fresh index.
+- Legacy Codex SDK session entries are archived and not loaded by the App Server backend.
+- App Server-backed Codex sessions are now the only supported Codex runtime path.
+- Contributors and release automation should use `pnpm verify` as the canonical validation gate.
 
-Build output is an **ESM bundle** at `dist/index.js` (`package.json` has `"type": "module"`).
+### Backend Capabilities
 
-```bash
-# Install dependencies
-pnpm install
-
-# Build (esbuild → dist/index.js)
-pnpm run build
+- Claude Code stays on plugin-managed worktrees.
+- Codex now runs through App Server structured events and may execute inside a native backend-managed worktree.
+- Merge, PR, reminder, and decision policy remain plugin-owned above both backends.
+- Operators should continue sessions by plugin session ID or name. Backend conversation IDs are accepted only for recovery and diagnostics.
 
-# Type-check
-pnpm run typecheck
-
-# Run tests
-pnpm test
-```
+## Tool Surface
 
-### Project Structure
-
-```
-openclaw-code-agent/
-├── index.ts                    # Plugin entry point
-├── openclaw.plugin.json        # Plugin manifest & config schema
-├── src/
-│   ├── harness/                # Agent harness abstraction layer
-│   │   ├── types.ts            # AgentHarness interface & message types
-│   │   ├── claude-code.ts      # Claude Code harness (SDK wrapper)
-│   │   ├── codex.ts            # Codex harness (@openai/codex-sdk thread stream wrapper)
-│   │   └── index.ts            # Harness registry
-│   ├── types.ts                # TypeScript interfaces
-│   ├── config.ts               # Config singleton + channel resolution
-│   ├── format.ts               # Formatting utilities
-│   ├── singletons.ts           # Module-level singleton refs
-│   ├── session.ts              # Session class (state machine, timers, harness)
-│   ├── session-manager.ts      # Session pool management + lifecycle
-│   ├── session-store.ts        # Persisted session/index storage abstraction
-│   ├── session-metrics.ts      # Metrics recorder abstraction
-│   ├── wake-dispatcher.ts      # Wake delivery + retry abstraction
-│   ├── notifications.ts        # Notification service
-│   ├── actions/respond.ts      # Shared respond logic (tool + command)
-│   ├── application/            # Shared app-layer logic used by tools + commands
-│   ├── tools/                  # Tool implementations (6 tools)
-│   └── commands/               # Chat command implementations (7 commands)
-├── tests/                      # Unit tests (node:test + tsx)
-├── skills/                     # Orchestration skill definitions
-└── docs/                       # Architecture & reference docs
-```
+| Tool | Purpose |
+| --- | --- |
+| `agent_launch` | Start a background coding session |
+| `agent_respond` | Reply, redirect, approve a plan, or escalate permissions |
+| `agent_output` | Read buffered session output |
+| `agent_sessions` | List active and recent sessions |
+| `agent_kill` | Stop or mark a session completed |
+| `agent_stats` | Show aggregate usage and cost |
+| `agent_merge` | Merge a worktree branch back to base |
+| `agent_pr` | Create or update a GitHub PR |
+| `agent_worktree_status` | Show branch, PR, and pending-decision state |
+| `agent_worktree_cleanup` | Clean up merged agent branches or dismiss a pending worktree decision |
 
----
+The chat command surface mirrors the common workflows: `/agent`, `/agent_sessions`, `/agent_output`, `/agent_respond`, `/agent_kill`, and `/agent_stats`.
 
-## Troubleshooting
+## Docs
 
-- Plugin installed but the gateway does not see it yet: run `openclaw gateway restart`.
-- Notifications are not arriving: verify `fallbackChannel` uses the exact format `"telegram|bot-name|chat-id"` in `~/.openclaw/openclaw.json`.
-
----
-
-## Contributing
-
-Contributions are welcome! Please:
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes with tests
-4. Submit a pull request
-
----
+| Doc | What It Covers |
+| --- | --- |
+| [docs/REFERENCE.md](docs/REFERENCE.md) | Install, config, tools, commands, notifications, routing, worktrees, troubleshooting |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Session manager, harness model, notification pipeline, persistence, worktree internals |
+| [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | Local setup, repo layout, build/test flow, extension points |
+| [docs/ACP-COMPARISON.md](docs/ACP-COMPARISON.md) | Current comparison with OpenClaw core ACP |
+| [skills/code-agent-orchestration/SKILL.md](skills/code-agent-orchestration/SKILL.md) | Operational skill for orchestrating sessions from an agent |
+| [CHANGELOG.md](CHANGELOG.md) | Release history |
 
 ## License
 
-MIT — see [LICENSE](LICENSE) for details.
-
-Originally based on [alizarion/openclaw-claude-code-plugin](https://github.com/alizarion/openclaw-claude-code-plugin). Renamed to `openclaw-code-agent` to be harness-agnostic.
+MIT. See [LICENSE](LICENSE).