openclaw-code-agent 3.1.0 → 3.2.1

package/README.md

@@ -9,12 +9,34 @@
 - **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.
+- **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.
 - **Full session lifecycle**. Suspend, resume, fork, interrupt, and recover sessions across restarts with persisted metadata and output.
+- **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.
 - **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)`.
 
-Need the version-pinned ACP breakdown? See [docs/ACP-COMPARISON.md](docs/ACP-COMPARISON.md).
+Need the ACPX vs Codex vs code-agent breakdown? See [docs/ACP-COMPARISON.md](docs/ACP-COMPARISON.md).
+
+## Boundaries
+
+`openclaw-code-agent` is separate from both OpenClaw's bundled `acpx` runtime plugin and OpenClaw's bundled `codex` plugin.
+
+- **ACPX** is OpenClaw's ACP runtime backend for ACP session interoperability.
+- **OpenClaw's bundled `codex` plugin** is the core native Codex provider/harness pair for embedded agent turns.
+- **`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.
+
+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.
+
+## New In 3.2.1
+
+`3.2.1` is a maintenance release focused on routing correctness, compatibility metadata, and release/security hygiene around the newer plan-review and worktree model.
+
+- **Trusted route resolution for newer OpenClaw contexts**. The plugin now prefers `deliveryContext` and `requesterSenderId` when available, while keeping legacy routing fallbacks for persisted sessions and older fixtures.
+- **Safer verifier execution**. Goal-task verifier commands now drop shell bootstrap hooks like `BASH_ENV` and `ENV` so operator-provided verifier commands run with fewer implicit side effects.
+- **Compatibility and onboarding metadata refresh**. The release raises the external OpenClaw baseline to `v2026.4.14`, verifies against the stable `v2026.4.21` build target, and ships the manifest activation/setup descriptors plus narrower onboarding guidance for first-run setup.
+- **Codex harness policy refresh**. The built-in Codex allowlist now includes `gpt-5.4-pro`.
+- **Stronger security and release hygiene**. Dependency overrides, CI checks, plugin security validation, and release metadata parity checks are all updated to match the shipped package.
 
 ## From Prompt To Merged Branch
 
@@ -22,13 +44,42 @@ Need the version-pinned ACP breakdown? See [docs/ACP-COMPARISON.md](docs/ACP-COM
 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.
 
+### Explicit Goal Tasks
+
+Goal tasks are an explicit opt-in path for iterative autonomous work. They do not replace the default `agent_launch` flow.
+
+Use the dedicated goal entrypoints:
+
+- `/goal ...`
+- `goal_launch(...)`
+
+The plugin does not automatically switch into goal mode just because a freeform prompt contains the words `goal task`.
+
+Use them when you want the plugin to keep looping toward one concrete outcome:
+
+- **Verifier mode** reruns one or more shell checks after each coding turn and keeps iterating until they pass or the iteration budget is exhausted.
+- **Ralph mode** keeps resuming the same task until the agent emits an exact completion promise, with optional verifiers run after completion is claimed.
+
+Examples:
+
+```bash
+/goal --workdir /repo --verify "npm test" --verify "npm run lint" Fix the failing auth flow
+/goal --workdir /repo --mode ralph --completion-promise DONE Ship the draft blog post workflow end to end
+goal_launch(goal="Fix the failing auth flow", verifier_commands=["npm test", "npm run lint"], workdir="/repo")
+goal_launch(goal="Ship the draft blog post workflow end to end", goal_mode="ralph", completion_promise="DONE", workdir="/repo")
+```
+
+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.
+
 ### Plan First
 
-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)`.
+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.
+
+> 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.
 
 <img src="assets/ask-readme.gif" alt="Plan review in ask mode with inline approval controls">
 
-*`ask` mode keeps the human in the loop: the plan lands back in the originating thread, and execution only starts after approval.*
+*`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.*
 
 ### Finish Cleanly
 
@@ -36,7 +87,21 @@ When the task is done, the plugin can leave the branch for review, merge it auto
 
 <img src="assets/delegate-readme.gif" alt="Delegated worktree flow with autonomous follow-through">
 
-*The main checkout stays clean. The branch lifecycle happens in the worktree, and the chat thread stays current on what was shipped.*
+*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.*
+
+### Worktree Lifecycle
+
+Worktree-backed sessions move through product-facing lifecycle states:
+
+- `active`: sandbox still in use
+- `pending decision`: waiting for merge / PR / dismiss follow-through
+- `pr_open`: PR exists and the sandbox is being preserved
+- `merged`: branch landed by normal git ancestry
+- `released`: content is already on the base branch even though branch SHAs differ after rebase, squash, or cherry-pick
+- `dismissed`: user intentionally discarded the sandbox
+- `no_change`: session finished without a committed delta
+
+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.
 
 ## Supported Harnesses
 
@@ -57,6 +122,20 @@ openclaw plugins enable openclaw-code-agent
 openclaw gateway restart
 ```
 
+This release targets the OpenClaw `v2026.4.14` external plugin contract and is verified against the stable `v2026.4.21` build/test target. `package.json` now carries the plugin API compatibility and build metadata used by modern OpenClaw / ClawHub installs, and `openclaw.plugin.json` now advertises the plugin-owned command activation surface plus the onboarding metadata OpenClaw uses during plugin-config setup. Keep those metadata surfaces in sync when bumping the plugin release baseline.
+
+The current manifest descriptors stay intentionally narrow: activation advertises 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.
+
+### First-Run Onboarding
+
+In OpenClaw's Manual setup flow, the plugin should only ask for three first-run decisions:
+
+- `defaultWorkdir`: the repo or workspace path you expect to launch from most often
+- `defaultHarness`: whether your default harness is `claude-code` or `codex`
+- `fallbackChannel`: an optional but recommended fully routable notification target for async updates
+
+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.
+
 Add a minimal config block under `plugins.entries["openclaw-code-agent"]` in `~/.openclaw/openclaw.json`:
 
 ```json
@@ -66,9 +145,9 @@ Add a minimal config block under `plugins.entries["openclaw-code-agent"]` in `~/
       "openclaw-code-agent": {
         "enabled": true,
         "config": {
+          "defaultWorkdir": "/home/user/project",
+          "defaultHarness": "claude-code",
           "fallbackChannel": "telegram|my-bot|123456789",
-          "planApproval": "ask",
-          "defaultWorktreeStrategy": "off",
           "harnesses": {
             "claude-code": {
               "defaultModel": "sonnet",
@@ -76,7 +155,7 @@ Add a minimal config block under `plugins.entries["openclaw-code-agent"]` in `~/
             },
             "codex": {
               "defaultModel": "gpt-5.4",
-              "allowedModels": ["gpt-5.4"],
+              "allowedModels": ["gpt-5.4", "gpt-5.4-pro"],
               "reasoningEffort": "medium"
             }
           }
@@ -87,6 +166,12 @@ Add a minimal config block under `plugins.entries["openclaw-code-agent"]` in `~/
 }
 ```
 
+You can leave the advanced settings at their defaults for the first run. The plugin defaults to:
+
+- `permissionMode: "plan"`
+- `planApproval: "ask"`
+- `defaultWorktreeStrategy: "off"`
+
 If you run Codex sessions, keep Codex on the ChatGPT auth path:
 
 ```toml
@@ -97,6 +182,17 @@ Put that in `~/.codex/config.toml`.
 
 Codex approval behavior is fixed to the supported execution path, and OpenClaw handles review gates through `permissionMode` plus `planApproval`.
 
+### Harness Availability Guidance
+
+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:
+
+- `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
+- `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
+
+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.
+
+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.
+
 Launch a first session:
 
 ```bash
@@ -110,14 +206,15 @@ For multi-workspace or multi-bot setups, configure `agentChannels`. The full rou
 
 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.
 
-### Upgrade Note For 3.1.0
+### Upgrade Note For 3.2.0
 
-`3.1.0` is a maintenance release focused on reliability, explicit session state, and release-tooling hardening.
+If you are upgrading from `3.1.0`, the important behavioral changes are:
 
-- 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.
+- `defaultWorktreeStrategy` is back to `off`, so worktree isolation remains opt-in unless you configure it explicitly.
+- `auto-merge` now attempts one autonomous conflict resolution before escalating.
+- Completion wakes and no-change outcomes are deterministic and carry explicit approval/execution state instead of relying on transcript inference.
+- 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.
+- Release validation now checks package/plugin version parity in addition to the normal `pnpm verify` gate.
 
 ### Backend Capabilities
 
@@ -138,10 +235,13 @@ Prefer fully routable channel strings such as `telegram|123456789` or `telegram|
 | `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 |
+| `agent_worktree_status` | Show authoritative lifecycle state, derived repo evidence, cleanup safety, and retained reasons |
+| `agent_worktree_cleanup` | Clean all lifecycle-safe worktrees or dismiss one pending decision without touching live/unsafe worktrees |
+| `goal_launch` | Start an explicit verifier or Ralph-style goal loop |
+| `goal_status` | Show one goal task or list all goal tasks |
+| `goal_stop` | Stop a running goal task |
 
-The chat command surface mirrors the common workflows: `/agent`, `/agent_sessions`, `/agent_output`, `/agent_respond`, `/agent_kill`, and `/agent_stats`.
+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`.
 
 ## Docs
 
@@ -150,6 +250,7 @@ The chat command surface mirrors the common workflows: `/agent`, `/agent_session
 | [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/SECURITY.md](docs/SECURITY.md) | Accepted subprocess surfaces, verifier-shell boundary, and current scanner findings |
 | [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 |