openclaw-code-agent 2.3.1 → 3.0.0

package/openclaw.plugin.json

@@ -140,19 +140,29 @@
       },
       "planApproval": {
         "type": "string",
-        "default": "delegate",
+        "default": "ask",
         "enum": [
           "approve",
           "ask",
           "delegate"
         ],
-        "description": "Plan approval behavior. 'delegate' (default): orchestrator autonomously decides whether to approve low-risk plans or escalate to the user. 'approve': orchestrator can auto-approve after verification. 'ask': orchestrator always forwards plans to the user for approval."
+        "description": "Plan approval behavior. 'ask' (default): orchestrator always forwards plans to the user for approval. 'delegate': orchestrator autonomously decides whether to approve low-risk plans or escalate to the user. 'approve': orchestrator can auto-approve after verification."
       },
       "defaultHarness": {
         "type": "string",
         "default": "claude-code",
         "description": "Default agent harness when agent_launch omits the harness parameter."
       },
+      "defaultWorktreeStrategy": {
+        "type": "string",
+        "default": "ask",
+        "enum": ["off", "manual", "ask", "delegate", "auto-merge", "auto-pr"],
+        "description": "Default worktree strategy for all new sessions when agent_launch omits worktree_strategy. 'ask' (default) = push branch and notify user with inline buttons (merge / open PR / dismiss). 'off' = no worktree. 'manual' = create worktree, no automatic action. 'delegate' = push branch and wake orchestrator to autonomously decide (merge, PR, or escalate). 'auto-merge' = auto-merge to base branch on completion. 'auto-pr' = auto-create/update GitHub PR on completion."
+      },
+      "worktreeDir": {
+        "type": "string",
+        "description": "Base directory for agent worktrees. Defaults to <repoRoot>/.worktrees when unset. Overridden by OPENCLAW_WORKTREE_DIR env var."
+      },
       "allowedModels": {
         "type": "array",
         "items": {
@@ -212,6 +222,10 @@
     "planApproval": {
       "label": "Plan approval policy",
       "help": "Choose whether plans are auto-approved, always escalated, or delegated to the orchestrator."
+    },
+    "defaultWorktreeStrategy": {
+      "label": "Default worktree strategy",
+      "help": "Applies to all sessions that don't specify worktree_strategy explicitly. 'ask' (default) creates worktrees and prompts user with inline buttons on completion. 'off' disables worktrees globally. 'delegate' wakes the orchestrator to decide autonomously. 'auto-merge' and 'auto-pr' are fully automated."
     }
   },
   "skills": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-code-agent",
-  "version": "2.3.1",
+  "version": "3.0.0",
   "type": "module",
   "main": "dist/index.js",
   "scripts": {
@@ -22,16 +22,16 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.37",
-    "@openai/codex-sdk": "^0.107.0"
+    "@anthropic-ai/claude-agent-sdk": "^0.2.81",
+    "@openai/codex-sdk": "^0.116.0"
   },
   "devDependencies": {
     "@sinclair/typebox": "^0.34.48",
-    "@types/node": "^25.3.3",
-    "esbuild": "^0.27.3",
-    "nanoid": "^3.3.7",
+    "@types/node": "^25.5.0",
+    "esbuild": "^0.27.4",
+    "nanoid": "^5.1.7",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.2"
+    "typescript": "^6.0.2"
   },
   "keywords": [
     "openclaw",
@@ -62,5 +62,18 @@
   "publishConfig": {
     "access": "public"
   },
-  "description": "An OpenClaw plugin that orchestrates coding agent sessions as managed background processes. Launch, monitor, and control coding agents (Claude Code, Codex, and more) directly from your AI gateway."
+  "description": "An OpenClaw plugin that orchestrates coding agent sessions as managed background processes. Launch, monitor, and control coding agents (Claude Code, Codex, and more) directly from your AI gateway.",
+  "peerDependencies": {
+    "openclaw": ">=2026.3.22"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "koffi",
+      "protobufjs",
+      "sharp",
+      "@img/sharp-linux-x64",
+      "@img/sharp-linux-arm64"
+    ]
+  }
 }

package/skills/code-agent-orchestration/SKILL.md

@@ -161,7 +161,7 @@ agent_sessions(status: "completed")
 # Summary (last 50 lines)
 agent_output(session: "fix-null-auth")
 
-# Full output (up to 200 blocks)
+# Full output (up to 2000 lines)
 agent_output(session: "fix-null-auth", full: true)
 
 # Specific last N lines
@@ -284,13 +284,48 @@ Notifications are routed to the Telegram thread/topic where the session was laun
 | Event | What happens |
 |---|---|
 | Session starts | Silent (command response confirms launch) |
-| Session completed | Brief one-liner to originating thread |
-| Session failed | Error notification to originating thread |
-| Waiting for input | Wake event + `❓ Waiting for input` in thread (only when the agent actually asks a question) |
-| Turn completes without a question | `⏸️ Paused after turn | Auto-resumable` |
+| Session completed | `✅ Completed` — brief one-liner to originating thread |
+| Session completed (deliverable mode) | `📄 Deliverable ready` — when launched with `output_mode: "deliverable"` |
+| Session failed | `❌ Failed` — error notification with `harnessSessionId` and resume guidance |
+| Waiting for input | `❓ Waiting for input` — wake event (only when the agent actually asks a question) |
+| Turn completes without a question | `⏸️ Paused after turn \| Auto-resumable` |
+| `agent_respond` send | `↪️` — notification sent for every `agent_respond` call |
+| `agent_respond` plan approval | `👍` — notification sent when `approve: true` |
 | Session auto-resumes | `▶️ Auto-resumed` |
 | Session idle-times out | `💤 Idle timeout` |
 | Session is forcibly stopped | `⛔ Stopped ...` with the specific stop reason |
+| Worktree decision pending (`ask`) | Inline Telegram buttons sent to user (Merge locally / Create PR) — Alice must NOT preempt |
+| Worktree decision pending (`delegate`) | Wake sent to Alice with diff context — Alice must decide and call `agent_merge` or `agent_pr` |
+
+### Sending completion summaries — use `message send`, not inline reply
+
+When you process a CC session completion wake and want to notify the user with a summary, **always send the summary via the `message` tool** rather than as an inline session reply:
+
+```bash
+# Correct — standalone message, guaranteed notification ping
+openclaw message send --channel telegram --target <chatId> --thread-id <topicId> \
+  --message "✅ [session-name] Done — <one-line summary>"
+```
+
+**Why this matters**: Alice's inline session replies are sent as Telegram *replies* (`reply_to_message_id`) to the message that triggered the wake. Because the plugin's ⏸️ status notification typically arrives just before the wake fires, Alice's reply targets that bot message — and Telegram does not re-ping the user when a bot replies to a recent bot message in an already-active topic thread. The `message` tool sends a standalone new message (`message_thread_id` only, no `reply_to_message_id`), which always generates a fresh notification ping.
+
+**Rule**: Inline replies are fine for conversational back-and-forth. For any user-facing "session done" notification that must reliably reach the user, use `message send` explicitly.
+
+The Telegram chat ID and topic thread ID are available from the current conversation context.
+
+### Worktree `ask` strategy — no duplicate summary
+
+When a session completes with `worktree_strategy: "ask"`, the plugin sends the user a single consolidated Telegram message that contains:
+- The full commit list and diff stats
+- The ⬇️ Merge locally / 🔀 Create PR inline buttons
+
+**Do NOT send a separate completion summary.** The button message IS the completion signal. Sending an additional "✅ Done!" or "Here's what was done:" message creates duplicates and confuses the user.
+
+This applies when the wake message says "Worktree strategy buttons delivered to user." — treat that as confirmation that the user is already fully informed. Take no further action until the user clicks a button.
+
+**Buttons are handled automatically by the plugin.** When the user taps a button, the plugin's callback router dispatches the action (`agent_merge` or `agent_pr`) directly — no agent `agent_merge`/`agent_pr` call is needed in response to a button tap. If the action succeeds, the plugin sends a result notification. If the action fails, a failure notification is sent. Alice does not need to poll or intervene.
+
+---
 
 ### Plan → Execute mode switch
 
@@ -300,13 +335,13 @@ Sessions start in `plan` mode by default. When you reply with **only** an approv
 
 The `approve` parameter on `agent_respond` escalates session permissions to `bypassPermissions`. It works in two scenarios:
 
-1. **Plan mode approval**: When a session has a pending plan approval (after `ExitPlanMode` / `set_permission_mode`), `approve: true` approves the plan and switches to `bypassPermissions`.
-2. **`acceptEdits` / `default` mode escalation**: When a session is in `acceptEdits` or `default` mode and keeps prompting for shell/exec command permissions, `approve: true` escalates to `bypassPermissions` to skip all remaining prompts.
+1. **Plan mode approval**: When a session has a pending plan approval (after `ExitPlanMode` / `set_permission_mode`), `approve: true` approves the plan and switches to `bypassPermissions`. Sends a 👍 notification.
+2. **`default` mode escalation**: When a session in `default` mode keeps prompting for shell/exec command permissions, `approve: true` escalates to `bypassPermissions` to skip all remaining prompts.
 
 If the session is already in `bypassPermissions` mode, `approve: true` is a no-op. In `plan` mode without a pending plan, it is ignored.
 
 ```
-# Escalate an acceptEdits session that keeps prompting for bash permissions
+# Escalate a session that keeps prompting for bash permissions
 agent_respond(session: "fix-auth", message: "proceed", approve: true)
 ```
 
@@ -314,9 +349,9 @@ agent_respond(session: "fix-auth", message: "proceed", approve: true)
 
 The `planApproval` config controls how the orchestrator handles plan-approval events:
 
-- **`delegate`** (default): The orchestrator autonomously decides whether to approve or escalate each plan to the user. Approve when the plan is low-risk, well-scoped, and matches the original task. Escalate when the plan involves destructive operations, credentials/production, architectural decisions, scope expansion, or ambiguous requirements. When in doubt, always escalate.
+- **`ask`** (default): The orchestrator always forwards plans to the user. It never auto-approves on the user's behalf.
+- **`delegate`**: The orchestrator autonomously decides whether to approve or escalate each plan to the user. Approve when the plan is low-risk, well-scoped, and matches the original task. Escalate when the plan involves destructive operations, credentials/production, architectural decisions, scope expansion, or ambiguous requirements. When in doubt, always escalate.
 - **`approve`**: The orchestrator can auto-approve straightforward, low-risk plans. Before approving, it verifies the working directory, codebase, and scope.
-- **`ask`**: The orchestrator always forwards plans to the user. It never auto-approves on the user's behalf.
 
 #### Delegate mode decision criteria
 
@@ -337,7 +372,103 @@ When operating in `delegate` mode, **approve** the plan directly if ALL of the f
 
 ---
 
-## 7. Best practices
+## 7. Worktree workflow
+
+When a session uses `worktree_strategy`, the agent runs in an isolated git branch. After completion, the branch needs to be merged or published as a PR.
+
+### Strategies at a glance
+
+| Strategy | What it does | When to use |
+|---|---|---|
+| `off` | No worktree. Session runs in main checkout | Simple/trusted tasks where isolation isn't needed |
+| `ask` (default) | Push branch and send inline buttons (Merge locally / Create PR); wake orchestrator with full decision context | User should decide — the interactive default |
+| `delegate` | Push branch and wake orchestrator to decide autonomously (merge, create PR, or leave for later) | Set via `defaultWorktreeStrategy` config — orchestrator decides autonomously |
+| `auto-merge` | Automatically merge back to base branch on completion; spawns conflict-resolver if needed | Trusted tasks on a safe branch |
+| `auto-pr` | Automatically open a GitHub PR on completion (requires `gh`) | Feature branches needing review |
+| `manual` | Push the branch; no further action — user handles merge/PR manually | You want to review diffs before merging |
+
+### Launch with worktree isolation
+
+```
+agent_launch(
+  prompt: "Implement the new user settings page",
+  name: "user-settings",
+  workdir: "/app",
+  worktree_strategy: "auto-pr"
+)
+```
+
+### Post-completion behavior by strategy
+
+When a session with a worktree completes, your action depends on the strategy:
+
+| Strategy | What to do after completion |
+|---|---|
+| `ask` | **Do nothing.** The plugin sends inline Telegram buttons (Merge locally / Create PR) to the user. **Never** call `agent_merge`, `agent_pr`, or any `git` command — wait for the user to decide. |
+| `delegate` | You receive a `worktree-delegate` wake with diff context. Evaluate and act (see *Delegate mode* below). |
+| `auto-merge` | No action needed — merge happens automatically. Watch for `worktree-merge-success` or `worktree-merge-conflict` notification. |
+| `auto-pr` | No action needed — PR is created/updated automatically. |
+| `manual` | Call `agent_merge` or `agent_pr` **only** when the user explicitly asks. |
+| `off` | No worktree — nothing to merge. |
+
+Note: the ⏸️ turn-complete wake is suppressed for both `ask` and `delegate` strategies — the worktree decision notification replaces it as the completion signal.
+
+### Delegate mode: deciding merge vs PR
+
+When you receive a `worktree-delegate` wake:
+
+1. **Evaluate the diff** — read the commit count, files changed, and diff summary included in the wake message
+2. **Compare to original task scope** — does the diff match what was asked?
+3. **Decide:**
+   - **Call `agent_merge`** when: changes are low-risk, well-scoped, match the original task, and no code review is needed
+   - **Call `agent_pr`** when: changes are non-trivial, touch many files, introduce significant complexity, or when uncertain
+   - **Escalate to the user** when: changes are ambiguous, out of scope, or involve sensitive areas
+4. **Notify the user briefly** — send a short message with your decision and one-sentence reasoning (e.g. "Merged `agent/feature-x` — straightforward 2-file change matching the original task.")
+5. **Never use raw `git` commands** — always use `agent_merge` or `agent_pr`
+
+### Check worktree status
+
+```
+agent_worktree_status()                      # all sessions with worktrees
+agent_worktree_status(session: "user-settings")  # specific session
+```
+
+### Manual merge or PR after `manual`/`ask`
+
+```
+# Merge back to base branch
+agent_merge(session: "user-settings", strategy: "merge")
+
+# Or create/update a GitHub PR
+agent_pr(session: "user-settings", title: "Add user settings page")
+```
+
+### Resume with worktree context
+
+When resuming a session that had a worktree, the worktree context (branch, strategy, PR URL) is inherited automatically — no need to pass `worktree_strategy` again:
+
+```
+agent_launch(
+  prompt: "Continue — also add unit tests",
+  resume_session_id: "user-settings"
+)
+```
+
+### Deliverable mode
+
+For document/report generation tasks, use `output_mode: "deliverable"` to send 📄 instead of ✅:
+
+```
+agent_launch(
+  prompt: "Write a technical spec for the new auth system",
+  name: "auth-spec",
+  output_mode: "deliverable"
+)
+```
+
+---
+
+## 8. Best practices
 
 ### Launch checklist
 
@@ -367,7 +498,7 @@ When a session completes, keep summaries brief:
 
 ---
 
-## 8. Anti-patterns
+## 9. Anti-patterns
 
 | Anti-pattern | Consequence | Fix |
 |---|---|---|
@@ -377,16 +508,22 @@ When a session completes, keep summaries brief:
 | Passing `channel` explicitly | Bypasses automatic routing | Let `agentChannels` handle routing automatically |
 | Not checking the result of a completed session | User doesn't know what happened | Always read `agent_output` and summarize briefly |
 | Launching too many sessions in parallel | `maxSessions` limit reached | Respect the limit, prioritize, sequence if necessary |
+| Calling `agent_merge` or `agent_pr` when strategy is `ask` | Bypasses the user's inline-button decision | Wait for the Telegram buttons — do nothing until the user decides |
+| Using raw `git merge` instead of `agent_merge` | Skips conflict resolution, cleanup, and session state tracking | Always use `agent_merge` when the user asks to merge a worktree branch |
 
 ---
 
-## 9. Quick tool reference
+## 10. Quick tool reference
 
 | Tool | Usage | Key parameters |
 |---|---|---|
-| `agent_launch` | Launch a session | `prompt`, `name`, `workdir`, `multi_turn` |
+| `agent_launch` | Launch a session | `prompt`, `name`, `workdir`, `multi_turn`, `worktree_strategy`, `output_mode` |
 | `agent_sessions` | List sessions | `status` (all/running/completed/failed/killed) |
 | `agent_output` | Read the output | `session`, `full`, `lines` |
 | `agent_kill` | Kill or complete a session | `session`, `reason` (`"completed"` or omit) |
 | `agent_respond` | Send a follow-up | `session`, `message`, `interrupt`, `approve` |
 | `agent_stats` | Usage metrics | none |
+| `agent_worktree_status` | Show worktree status for sessions | `session` (optional — omit for all) |
+| `agent_merge` | Merge worktree branch to base | `session`, `base_branch`, `strategy`, `push`, `delete_branch` |
+| `agent_pr` | Create/update GitHub PR for worktree branch | `session`, `title`, `body`, `base_branch`, `force_new` |
+| `agent_worktree_cleanup` | Clean up merged agent/* branches | `workdir`, `base_branch`, `skip_session_check`, `dry_run`, `session` |

package/workflows/plan-approval.lobster

@@ -1,15 +0,0 @@
-name: plan-approval
-args:
-  session_id:
-    required: true
-  session_name:
-    required: true
-  plan_summary:
-    required: true
-steps:
-  - id: approve
-    approval: required
-
-  - id: proceed
-    command: openclaw.invoke --tool agent_respond --args-json '{"session":"$session_id","message":"Approved. Go ahead.","approve":true}'
-    condition: $approve.approved