openclaw-code-agent 3.2.0 → 4.0.0

package/README.md

@@ -16,17 +16,27 @@
 - **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).
 
-## New In 3.2.0
+## Boundaries
 
-`3.2.0` is the release that makes the newer worktree and plan-review model feel reliable enough for daily use.
+`openclaw-code-agent` is separate from both OpenClaw's bundled `acpx` runtime plugin and OpenClaw's bundled `codex` plugin.
 
-- **Deterministic completion and approval state**. Terminal notifications and wakes no longer depend on transcript-style summary heuristics, and plan-gated sessions now surface explicit approval/execution state for operators and orchestration logic.
-- **Real auto-merge conflict recovery**. `auto-merge` now gets one autonomous conflict-resolution attempt, then retries the merge automatically before escalating back to a preserved branch or PR path.
-- **Lifecycle-first worktree cleanup**. Worktree status and cleanup now treat `released` as a first-class resolved state, so rebased, squashed, and cherry-picked work can still be identified and cleaned safely.
-- **Safer repository follow-through**. Worktree disk-space validation now checks the correct filesystem on first run and for custom worktree directories, and cross-repo PR auto-targeting now works for upstream-only repos.
-- **Stronger release hygiene**. The repo now standardizes on `pnpm` validation, and release automation validates `package.json`, `openclaw.plugin.json`, and the release version together before publish.
+- **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 4.0.0
+
+`4.0.0` is the messaging-contract cleanup release. Interactive direct notifications for Telegram and Discord now go through the same shared OpenClaw presentation contract, and the plugin drops the old Telegram legacy fallback plus the Discord-native component sender split.
+
+- **Shared outbound interactive delivery**. Telegram and Discord direct notifications now use one `message.send --presentation` path.
+- **Breaking compatibility floor update**. The plugin now requires OpenClaw `v2026.4.21` or newer.
+- **Removed legacy sender paths**. The Telegram `--buttons` fallback and the custom Discord component sender path are gone; both providers now depend on the shared presentation contract.
+- **State migration cleanup**. Persisted approval-prompt delivery state is now recorded as `direct-message`, while older `direct-telegram` entries still restore cleanly.
+- **Model refresh**. Built-in defaults now recommend `anthropic/claude-sonnet-4-7` for Claude Code and `gpt-5.5` for Codex, with `gpt-5.5-pro` also included in the built-in Codex allowlist.
 
 ## From Prompt To Merged Branch
 
@@ -65,9 +75,11 @@ Once launched, use `goal_status` / `/goal_status` to inspect progress and `goal_
 
 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
 
@@ -75,7 +87,7 @@ 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
 
@@ -110,7 +122,19 @@ openclaw plugins enable openclaw-code-agent
 openclaw gateway restart
 ```
 
-This release targets the OpenClaw `v2026.4.9` external plugin contract. `package.json` now carries the plugin API compatibility and build metadata used by modern OpenClaw / ClawHub installs, so keep those fields in sync when bumping the plugin release baseline.
+This release targets the OpenClaw `v2026.4.21` external plugin contract and is verified against the stable `v2026.4.23` 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`:
 
@@ -121,17 +145,17 @@ 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",
+              "defaultModel": "anthropic/claude-sonnet-4-7",
               "allowedModels": ["sonnet", "opus"]
             },
             "codex": {
-              "defaultModel": "gpt-5.4",
-              "allowedModels": ["gpt-5.4"],
+              "defaultModel": "gpt-5.5",
+              "allowedModels": ["gpt-5.5", "gpt-5.5-pro"],
               "reasoningEffort": "medium"
             }
           }
@@ -142,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
@@ -152,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
@@ -209,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 |