openclaw-code-agent 4.1.1 → 4.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,112 +4,60 @@
4
4
  [![npm downloads](https://img.shields.io/npm/dm/openclaw-code-agent.svg)](https://www.npmjs.com/package/openclaw-code-agent)
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
6
6
 
7
- `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.
7
+ `openclaw-code-agent` runs Claude Code and Codex as managed background coding sessions from OpenClaw chat. It adds plan approval, session lifecycle, wake routing, worktree isolation, merge/PR follow-through, and explicit goal loops on top of the agent backends.
8
+
9
+ Use it when you want to start coding work from Telegram, Discord, or another OpenClaw-supported channel and keep the job observable after the first message.
10
+
11
+ ## Highlights
8
12
 
9
13
  - **Plan -> Review -> Execute**. `plan` is the default launch mode, and plan approval defaults to `delegate` so the orchestrator reviews the full plan before approving or escalating to the user.
10
14
  - **Delegated worktree isolation**. New sessions default to `delegate`; opt into `ask`, `off`, `manual`, `auto-merge`, or `auto-pr` when you want a different branch follow-through policy.
11
- - **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.
12
- - **Lifecycle-first cleanup**. Worktrees are treated as temporary task sandboxes. The plugin distinguishes `merged` from `released` so different-SHA branches whose content already landed on the base branch can still be cleaned safely.
15
+ - **State-driven decision UX**. `ask` sends explicit action buttons for **Merge**, **Open PR**, **Later**, and **Discard**. The same action-token model backs Telegram and Discord interactive callbacks.
16
+ - **Lifecycle-first cleanup**. Worktrees are temporary task sandboxes. The plugin distinguishes `merged` from `released` so different-SHA branches whose content already landed on the base branch can still be cleaned safely.
13
17
  - **Full session lifecycle**. Suspend, resume, fork, interrupt, and recover sessions across restarts with persisted metadata and output.
14
18
  - **Explicit goal-task loops**. Opt into verifier-driven repair loops or Ralph-style completion loops when you need iterative autonomous execution toward a specific goal.
15
19
  - **Real operator visibility**. `agent_sessions`, `agent_output`, and `agent_stats` show status, buffered output, duration, and USD cost.
16
20
  - **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.
17
- - **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)`.
18
-
19
- Need the ACPX vs Codex vs code-agent breakdown? See [docs/ACP-COMPARISON.md](docs/ACP-COMPARISON.md).
20
-
21
- ## Boundaries
22
-
23
- `openclaw-code-agent` is separate from both OpenClaw's bundled `acpx` runtime plugin and OpenClaw's bundled `codex` plugin.
24
-
25
- - **ACPX** is OpenClaw's ACP runtime backend for ACP session interoperability.
26
- - **OpenClaw's bundled `codex` plugin** is the core native Codex provider/harness pair for embedded agent turns.
27
- - **`openclaw-code-agent`** is the chat orchestration layer that adds plan approval, wake routing, session lifecycle, and worktree/merge/PR policy above its own native Claude Code and Codex harnesses.
28
-
29
- The shared substrate is often the local `codex` command and Codex App Server, but the responsibilities are different. This plugin is not an ACP server and it does not depend on OpenClaw's bundled Codex provider to expose its own `codex` harness.
30
-
31
- ## New In 4.1.1
32
-
33
- `4.1.1` is the OpenClaw `2026.5.4` compatibility patch. It keeps the `4.1.0` managed-lifecycle and notification reliability work intact, preserves the `>=2026.4.21` compatibility floor, and aligns harness model/thinking behavior with the newer OpenClaw release line.
34
-
35
- - **Managed TaskFlow lifecycle**. When the current OpenClaw runtime exposes managed TaskFlow APIs, code-agent sessions now create, update, wait, and finalize a gateway-owned flow record; older runtimes fall back cleanly without changing session behavior.
36
- - **Deterministic runtime state**. Completion and no-change paths now surface canonical approval/runtime state instead of asking operators to infer it from transcript text.
37
- - **Notification delivery reliability**. Direct notification timeouts, fallback failures, and completion-delivery diagnostics are handled explicitly so failed delivery is visible instead of silently hanging.
38
- - **Verified OpenClaw target**. Local build/test metadata targets stable OpenClaw `2026.5.4` while keeping the minimum compatibility floor at `>=2026.4.21`.
39
-
40
- ## From Prompt To Merged Branch
41
-
42
- 1. Launch a coding session from chat with `/agent ...` or `agent_launch(...)`.
43
- 2. Review the plan in the same thread before anything touches the repo.
44
- 3. Let the agent finish in an isolated worktree, then merge or publish the result from chat.
21
+ - **One continuation path**. Follow-ups, approvals, revisions, interrupts, and redirects all continue the existing session instead of launching a duplicate.
45
22
 
46
- ### Explicit Goal Tasks
23
+ This plugin is separate from OpenClaw's bundled `acpx` runtime plugin and bundled core `codex` plugin. Those own adjacent OpenClaw runtime/provider surfaces; `openclaw-code-agent` owns chat orchestration and repository follow-through for its own Claude Code and Codex harnesses. See [docs/ACP-COMPARISON.md](docs/ACP-COMPARISON.md) for the boundary details.
47
24
 
48
- Goal tasks are an explicit opt-in path for iterative autonomous work. They do not replace the default `agent_launch` flow.
25
+ ## From Prompt To Shipped Branch
49
26
 
50
- Use the dedicated goal entrypoints:
51
-
52
- - `/goal ...`
53
- - `goal_launch(...)`
54
-
55
- The plugin does not automatically switch into goal mode just because a freeform prompt contains the words `goal task`.
56
-
57
- Use them when you want the plugin to keep looping toward one concrete outcome:
58
-
59
- - **Verifier mode** reruns one or more shell checks after each coding turn and keeps iterating until they pass or the iteration budget is exhausted.
60
- - **Ralph mode** keeps resuming the same task until the agent emits an exact completion promise, with optional verifiers run after completion is claimed.
61
-
62
- Examples:
63
-
64
- ```bash
65
- /goal --workdir /repo --verify "npm test" --verify "npm run lint" Fix the failing auth flow
66
- /goal --workdir /repo --mode ralph --completion-promise DONE Ship the draft blog post workflow end to end
67
- goal_launch(goal="Fix the failing auth flow", verifier_commands=["npm test", "npm run lint"], workdir="/repo")
68
- goal_launch(goal="Ship the draft blog post workflow end to end", goal_mode="ralph", completion_promise="DONE", workdir="/repo")
69
- ```
70
-
71
- Once launched, use `goal_status` / `/goal_status` to inspect progress and `goal_stop` / `/goal_stop` to terminate the loop. Goal-task state is persisted so recoverable loops can resume after a gateway restart.
27
+ 1. Ask OpenClaw to launch a coding session from chat.
28
+ 2. Review the plan in the same thread before implementation starts.
29
+ 3. Let the agent finish in an isolated worktree.
30
+ 4. Merge into the base branch, open a PR, defer the decision, or discard the sandbox from the same control plane.
72
31
 
73
32
  ### Plan First
74
33
 
75
- 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)`. If the user asks for revisions, the revised submission becomes the new actionable review version for that same session, and `approve=true` resolves against that latest version instead of any stale earlier change-request state.
34
+ The core loop is plan review. Claude Code and Codex feed the same approval UX: the plugin receives a structured plan artifact, keeps execution blocked until approval, and continues the same session after the plan is approved. If the user asks for revisions, the revised plan becomes the latest actionable version for that same session.
76
35
 
77
- > Demo note: the GIFs below were recorded on an older build. They still show the overall flow correctly, but they do not include the newer explicit action buttons and some other current thread controls.
78
-
79
- <img src="assets/ask-readme.gif" alt="Plan review in ask mode with inline approval controls">
36
+ ### Finish Cleanly
80
37
 
81
- *`ask` mode keeps the human in the loop: the plan lands back in the originating thread, and execution only starts after approval. The current UI now uses explicit buttons for approval and follow-through, even though the GIF predates that update.*
38
+ When a task completes, the plugin can leave the branch for review, merge it automatically, open or update a PR, or wake the orchestrator with diff context. In `ask`, the user gets explicit decision buttons in the originating thread. In `delegate`, the orchestrator reviews the worktree result and escalates user-facing decisions such as PR creation.
82
39
 
83
- ### Finish Cleanly
40
+ ![Delegated worktree flow](https://raw.githubusercontent.com/goldmar/openclaw-code-agent/main/assets/delegate-readme.gif)
84
41
 
85
- 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.
42
+ *`delegate` keeps the main checkout clean while the branch lifecycle happens in the worktree. The chat thread stays current on what was attempted, what changed, and what follow-through is needed.*
86
43
 
87
- <img src="assets/delegate-readme.gif" alt="Delegated worktree flow with autonomous follow-through">
44
+ ![Ask-mode worktree decisions](https://raw.githubusercontent.com/goldmar/openclaw-code-agent/main/assets/ask-readme.gif)
88
45
 
89
- *The main checkout stays clean. The branch lifecycle happens in the worktree, and the chat thread stays current on what was shipped. The current UI includes newer buttons and lifecycle affordances that are not visible in this older recording.*
46
+ *`ask` keeps the human in the loop for branch follow-through. Current buttons adapt to state: new branches can show **Merge**, **Open PR**, **Later**, and **Discard**; branches with an existing PR can show **View PR** and **Sync PR** instead of **Open PR**. Older recordings may show prior wording.*
90
47
 
91
48
  ### Worktree Lifecycle
92
49
 
93
50
  Worktree-backed sessions move through product-facing lifecycle states:
94
51
 
95
52
  - `active`: sandbox still in use
96
- - `pending decision`: waiting for merge / PR / dismiss follow-through
53
+ - `pending decision`: waiting for merge, PR, later, or discard follow-through
97
54
  - `pr_open`: PR exists and the sandbox is being preserved
98
55
  - `merged`: branch landed by normal git ancestry
99
- - `released`: content is already on the base branch even though branch SHAs differ after rebase, squash, or cherry-pick
56
+ - `released`: content is already on the base branch after rebase, squash, or cherry-pick
100
57
  - `dismissed`: user intentionally discarded the sandbox
101
58
  - `no_change`: session finished without a committed delta
102
59
 
103
- For cleanup, use `agent_worktree_cleanup(mode="preview_safe")` to preview what **Clean all safe** would remove, `mode="clean_safe"` to perform that cleanup, and `mode="preview_all"` to review both safe sandboxes and the reasons other worktrees were retained.
104
-
105
- ## Supported Harnesses
106
-
107
- | Harness | Status | Notes |
108
- | --- | --- | --- |
109
- | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Supported | Native harness via `@anthropic-ai/claude-agent-sdk` |
110
- | [Codex](https://github.com/openai/codex) | Supported | Native harness via Codex App Server over stdio |
111
-
112
- 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.
60
+ Use `agent_worktree_status` for current state and `agent_worktree_cleanup(mode="preview_safe")` before removing resolved sandboxes.
113
61
 
114
62
  ## Quick Start
115
63
 
@@ -122,25 +70,7 @@ openclaw gateway restart
122
70
  openclaw plugins inspect openclaw-code-agent --runtime --json
123
71
  ```
124
72
 
125
- Restart or reload the gateway only as part of your normal install/upgrade flow; it is not needed for editing docs or preparing a release branch.
126
-
127
- This release targets the OpenClaw `v2026.4.21` external plugin contract and is verified against the stable `v2026.5.4` build/test target. `package.json` carries the plugin API compatibility and build metadata used by modern OpenClaw / ClawHub installs, and `openclaw.plugin.json` advertises the plugin-owned startup, command activation surface, tool contracts, and onboarding metadata OpenClaw uses during plugin-config setup. Keep those metadata surfaces in sync when bumping the plugin release baseline.
128
-
129
- After install or update, inspect the runtime plugin view after the gateway restart. The runtime inspection should show the chat commands, service, and `agent_*` / `goal_*` tools without diagnostics. If `tools.effective` or `tools.invoke` cannot see `agent_launch` or `agent_sessions`, the installed plugin is stale or the gateway has not restarted onto the updated manifest and bundle.
130
-
131
- The current manifest descriptors stay intentionally narrow: activation advertises startup loading plus only the chat commands this plugin owns, and setup stays minimal with `requiresRuntime: false`. First-run onboarding is driven by the manifest config schema and `uiHints`, not by provider/backend setup descriptors.
132
-
133
- ### First-Run Onboarding
134
-
135
- In OpenClaw's Manual setup flow, the plugin should only ask for three first-run decisions:
136
-
137
- - `defaultWorkdir`: the git repo path you expect to launch from most often
138
- - `defaultHarness`: whether your default harness is `claude-code` or `codex`
139
- - `fallbackChannel`: an optional but recommended fully routable notification target for async updates
140
-
141
- Everything else stays advanced/manual. In particular, `agentChannels`, per-harness model policy, permission defaults, and worktree policy are intentionally deferred until after the first successful launch, even though plan approval and worktree follow-through now default to delegated behavior. If your first launch must run outside a git repo, expand Advanced during setup or edit config afterwards and set `defaultWorktreeStrategy` to `off`.
142
-
143
- Add a minimal config block under `plugins.entries["openclaw-code-agent"]` in `~/.openclaw/openclaw.json`:
73
+ Add the smallest useful config under `plugins.entries["openclaw-code-agent"]` in `~/.openclaw/openclaw.json`:
144
74
 
145
75
  ```json
146
76
  {
@@ -150,19 +80,7 @@ Add a minimal config block under `plugins.entries["openclaw-code-agent"]` in `~/
150
80
  "enabled": true,
151
81
  "config": {
152
82
  "defaultWorkdir": "/home/user/project",
153
- "defaultHarness": "claude-code",
154
- "fallbackChannel": "telegram|my-bot|123456789",
155
- "harnesses": {
156
- "claude-code": {
157
- "defaultModel": "anthropic/claude-sonnet-4-7",
158
- "allowedModels": ["sonnet", "opus"]
159
- },
160
- "codex": {
161
- "defaultModel": "gpt-5.5",
162
- "allowedModels": ["gpt-5.5", "gpt-5.5-pro"],
163
- "reasoningEffort": "medium"
164
- }
165
- }
83
+ "defaultHarness": "claude-code"
166
84
  }
167
85
  }
168
86
  }
@@ -170,110 +88,119 @@ Add a minimal config block under `plugins.entries["openclaw-code-agent"]` in `~/
170
88
  }
171
89
  ```
172
90
 
173
- You can leave the advanced settings at their defaults for the first run. The plugin defaults to:
91
+ For the first run, choose:
92
+
93
+ - `defaultWorkdir`: a git repository root you expect to use often.
94
+ - `defaultHarness`: `claude-code` or `codex`.
95
+
96
+ The default policy is intentionally review-first:
174
97
 
175
98
  - `permissionMode: "plan"`
176
99
  - `planApproval: "delegate"`
177
100
  - `defaultWorktreeStrategy: "delegate"`
178
101
 
179
- Because delegated worktree follow-through is now the default, the first-run `defaultWorkdir` should normally point at a git repository. Non-git workdirs are still supported by setting `defaultWorktreeStrategy: "off"` globally or by launching with `worktree_strategy: "off"`.
102
+ Because worktree isolation defaults to `delegate`, `defaultWorkdir` should normally be a git repo. For non-git directories, set `defaultWorktreeStrategy` to `off` or launch with `worktree_strategy: "off"`.
103
+
104
+ Chat-launched sessions route updates back to their originating chat thread. For agent-launched tool sessions without an origin route, configure `fallbackChannel` or `agentChannels` in the reference guide.
180
105
 
181
- If you run Codex sessions, keep Codex on the ChatGPT auth path:
106
+ This release targets the OpenClaw SDK package `openclaw@2026.5.5`, while keeping the plugin peer floor at `>=2026.4.21`.
107
+
108
+ If you use Codex, make sure the local `codex` command or `OPENCLAW_CODEX_APP_SERVER_COMMAND` override is available and authenticated. When Codex auth is inconsistent, this is the recommended `~/.codex/config.toml` setting:
182
109
 
183
110
  ```toml
184
111
  forced_login_method = "chatgpt"
185
112
  ```
186
113
 
187
- Put that in `~/.codex/config.toml`.
114
+ ## First Session
188
115
 
189
- Codex approval behavior is fixed to the supported execution path, and OpenClaw handles review gates through `permissionMode` plus `planApproval`.
116
+ In chat, ask OpenClaw to start work:
190
117
 
191
- ### Harness Availability Guidance
118
+ ```text
119
+ Start a coding session named fix-auth to fix the auth middleware bug.
120
+ ```
192
121
 
193
- OpenClaw's generic plugin onboarding can prompt for `defaultHarness`, but it does not yet have a plugin-specific readiness panel. Use these checks when choosing the default:
122
+ When the plan arrives, respond in the same thread:
194
123
 
195
- - `codex`: choose this only when the `codex` command (or your `OPENCLAW_CODEX_APP_SERVER_COMMAND` override) is available and local Codex auth under `~/.codex` is already working
196
- - `claude-code`: choose this when the bundled Claude SDK/CLI is installed and you expect Claude Code to be the main path on this machine
124
+ ```text
125
+ Approve.
126
+ ```
197
127
 
198
- Codex readiness is the easier one to verify locally because the plugin depends on a resolvable command plus local auth files. Claude Code installation is verifiable, but authenticated usability may still require Claude-side login/account setup the first time you launch a session.
128
+ Send follow-ups as ordinary chat replies:
199
129
 
200
- This is this plugin's own harness selection, not OpenClaw ACPX runtime selection and not the bundled core `codex` provider toggle. The real prerequisites are the local backend commands and local auth state.
130
+ ```text
131
+ Add unit tests too.
132
+ Show me the latest output.
133
+ Stop this session.
134
+ ```
201
135
 
202
- Launch a first session:
136
+ ## Core Workflows
203
137
 
204
- ```bash
205
- /agent --name fix-auth Fix the auth middleware bug
206
- /agent_sessions
207
- /agent_respond fix-auth Add unit tests too
208
- agent_launch(prompt="<new task>", resume_session_id="fix-auth", fork_session=true)
209
- ```
138
+ ### Plan Review
210
139
 
211
- 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).
140
+ By default, Claude Code and Codex produce a plan before implementation. The plan can be approved, revised, or rejected through buttons when available, or with plain-text `Approve`, `Revise`, or `Reject` in the same thread.
212
141
 
213
- 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.
142
+ Revisions stay attached to the same session, so the newest plan is the actionable one.
214
143
 
215
- ### Upgrade Notes
144
+ ### Worktree Follow-Through
216
145
 
217
- For OpenClaw `2026.5.4` readiness:
146
+ New sessions use delegated worktree follow-through unless configured otherwise. That keeps changes in an isolated branch and wakes the orchestrator with diff context. In `ask` mode, user-facing buttons depend on state:
218
147
 
219
- - Build and SDK metadata now target OpenClaw `2026.5.4`; the peer floor remains `>=2026.4.21` for existing compatible installs.
220
- - If your OpenClaw config uses an exclusive `plugins.allow` list, include `openclaw-code-agent` or the plugin's `agent_*` / `goal_*` tools will not load even if `tools.allow` names them.
221
- - Harness model policy should live under `harnesses.codex.*` and `harnesses["claude-code"].*`. Legacy `defaultModel`, `model`, `reasoningEffort`, and global `allowedModels` are compatibility-only. Configured `reasoningEffort` supports `low`, `medium`, `high`, `xhigh`, and `max`.
222
- - Codex and Claude Code restrictions are harness-scoped. Codex defaults to `gpt-5.5` with `gpt-5.5` / `gpt-5.5-pro` allowed; Claude Code defaults to `anthropic/claude-sonnet-4-7` with `sonnet` / `opus` matching.
223
- - `tools.deny` does not disable OpenClaw's `apply_patch` tool by itself. Use OpenClaw's `tools.exec.applyPatch.*` settings when you need patch-tool policy.
148
+ | State | Buttons |
149
+ | --- | --- |
150
+ | New branch and GitHub CLI available | `Merge`, `Open PR`, `Later`, `Discard` |
151
+ | Existing PR | `Merge`, `View PR`, `Sync PR`, `Later`, `Discard` |
152
+ | GitHub CLI unavailable | `Merge`, `Later`, `Discard` |
224
153
 
225
- For `4.1.0`:
154
+ Ask OpenClaw for worktree status before cleaning resolved sandboxes.
226
155
 
227
- - Managed TaskFlow integration is opportunistic. It uses OpenClaw's current managed-flow runtime when available and degrades to the existing session-only behavior when that surface is absent.
228
- - Direct notification failures are now surfaced more explicitly. Treat a missing button delivery as a delivery/routing problem, not as evidence that the underlying plan or worktree state changed.
229
- - Runtime and approval state fields in wakes are authoritative. Prefer them over transcript fragments when deciding whether execution was approved, bypassed, completed, or still waiting.
156
+ ### Goal Tasks
230
157
 
231
- For `3.2.0`:
158
+ Goal tasks are explicit autonomous loops for work that should keep iterating toward a defined finish line. They do not replace ordinary coding sessions.
232
159
 
233
- If you are upgrading from `3.1.0`, the important behavioral changes are:
160
+ Ask in normal chat:
234
161
 
235
- - `defaultWorktreeStrategy` now defaults to `delegate`, so new sessions use worktree isolation and orchestrator-led follow-through unless you configure or launch with a different strategy.
236
- - `auto-merge` now attempts one autonomous conflict resolution before escalating.
237
- - Completion wakes and no-change outcomes are deterministic and carry explicit approval/execution state instead of relying on transcript inference.
238
- - Worktree cleanup is lifecycle-first and can now classify already-landed branches as `released`, which makes `preview_safe` and `clean_safe` more trustworthy after rebase, squash, or cherry-pick flows.
239
- - Release validation now checks package/plugin version parity in addition to the normal `pnpm verify` gate.
162
+ ```text
163
+ Start a verifier goal in /repo: fix the failing auth flow and keep running pnpm test until it passes.
164
+ Start a Ralph-style goal for /repo: ship the draft workflow, and consider it complete when the output says DONE.
165
+ Show goal status.
166
+ Stop the auth goal.
167
+ ```
240
168
 
241
- ### Backend Capabilities
169
+ OpenClaw agents can use the goal tools directly when they need explicit loop control; humans can usually describe the goal in plain language.
242
170
 
243
- - Claude Code stays on plugin-managed worktrees.
244
- - Codex now runs through App Server structured events and may execute inside a native backend-managed worktree.
245
- - Merge, PR, reminder, and decision policy remain plugin-owned above both backends.
246
- - Operators should continue sessions by plugin session ID or name. Backend conversation IDs are accepted only for recovery and diagnostics.
171
+ ## Tools And Commands
247
172
 
248
- ## Tool Surface
173
+ Most users interact in chat. The tool surface is for OpenClaw agents and advanced integrations.
249
174
 
250
- | Tool | Purpose |
175
+ | Agent-facing tool | Purpose |
251
176
  | --- | --- |
252
177
  | `agent_launch` | Start a background coding session |
253
178
  | `agent_respond` | Reply, redirect, approve a plan, or escalate permissions |
179
+ | `agent_request_plan_approval` | Escalate a delegated plan review to the user |
180
+ | `agent_send_plan_offer` | Send a message with Start Plan / Dismiss buttons for a plan-gated follow-up |
254
181
  | `agent_output` | Read buffered session output |
255
182
  | `agent_sessions` | List active and recent sessions |
256
183
  | `agent_kill` | Stop or mark a session completed |
257
184
  | `agent_stats` | Show aggregate usage and cost |
258
185
  | `agent_merge` | Merge a worktree branch back to base |
259
186
  | `agent_pr` | Create or update a GitHub PR |
260
- | `agent_worktree_status` | Show authoritative lifecycle state, derived repo evidence, cleanup safety, and retained reasons |
261
- | `agent_worktree_cleanup` | Clean all lifecycle-safe worktrees or dismiss one pending decision without touching live/unsafe worktrees |
187
+ | `agent_worktree_status` | Show worktree lifecycle state and cleanup safety |
188
+ | `agent_worktree_cleanup` | Clean safe worktrees or dismiss one pending decision |
262
189
  | `goal_launch` | Start an explicit verifier or Ralph-style goal loop |
263
190
  | `goal_status` | Show one goal task or list all goal tasks |
264
191
  | `goal_stop` | Stop a running goal task |
265
192
 
266
- The chat command surface mirrors the common workflows: `/agent`, `/agent_sessions`, `/agent_output`, `/agent_respond`, `/agent_kill`, `/agent_stats`, `/goal`, `/goal_status`, and `/goal_stop`.
193
+ Chat commands mirror the common workflows when you want explicit commands instead of natural-language chat, but most human use should start with plain requests like the examples above. Available commands are `/agent`, `/agent_sessions`, `/agent_output`, `/agent_respond`, `/agent_kill`, `/agent_stats`, `/goal`, `/goal_status`, and `/goal_stop`.
267
194
 
268
195
  ## Docs
269
196
 
270
197
  | Doc | What It Covers |
271
198
  | --- | --- |
272
- | [docs/REFERENCE.md](docs/REFERENCE.md) | Install, config, tools, commands, notifications, routing, worktrees, troubleshooting |
273
- | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Session manager, harness model, notification pipeline, persistence, worktree internals |
274
- | [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | Local setup, repo layout, build/test flow, extension points |
275
- | [docs/SECURITY.md](docs/SECURITY.md) | Accepted subprocess surfaces, verifier-shell boundary, and current scanner findings |
276
- | [docs/ACP-COMPARISON.md](docs/ACP-COMPARISON.md) | Current comparison with OpenClaw core ACP |
199
+ | [docs/REFERENCE.md](docs/REFERENCE.md) | Full operator reference: install, config, tools, commands, routing, worktrees, troubleshooting |
200
+ | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Internal architecture and lifecycle design |
201
+ | [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | Local setup, validation, release prep, extension points |
202
+ | [docs/SECURITY.md](docs/SECURITY.md) | Accepted subprocess surfaces, verifier shell boundary, scanner findings |
203
+ | [docs/ACP-COMPARISON.md](docs/ACP-COMPARISON.md) | Boundary with OpenClaw ACPX and bundled Codex surfaces |
277
204
  | [skills/code-agent-orchestration/SKILL.md](skills/code-agent-orchestration/SKILL.md) | Operational skill for orchestrating sessions from an agent |
278
205
  | [CHANGELOG.md](CHANGELOG.md) | Release history |
279
206