openclaw-code-agent 3.1.0 → 3.2.1

package/openclaw.plugin.json

@@ -2,7 +2,23 @@
   "id": "openclaw-code-agent",
   "name": "OpenClaw Code Agent",
   "description": "Multi-session coding-agent orchestration from OpenClaw chat",
-  "version": "3.1.0",
+  "version": "3.2.1",
+  "activation": {
+    "onCommands": [
+      "agent",
+      "agent_kill",
+      "agent_output",
+      "agent_respond",
+      "agent_sessions",
+      "agent_stats",
+      "goal",
+      "goal_status",
+      "goal_stop"
+    ]
+  },
+  "setup": {
+    "requiresRuntime": false
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -18,7 +34,8 @@
           "codex": {
             "defaultModel": "gpt-5.4",
             "allowedModels": [
-              "gpt-5.4"
+              "gpt-5.4",
+              "gpt-5.4-pro"
             ],
             "reasoningEffort": "medium"
           },
@@ -131,6 +148,7 @@
       },
       "defaultHarness": {
         "type": "string",
+        "enum": ["claude-code", "codex"],
         "default": "claude-code",
         "description": "Default agent harness when agent_launch omits the harness parameter."
       },
@@ -156,14 +174,14 @@
   "uiHints": {
     "fallbackChannel": {
       "label": "Fallback notification channel",
-      "help": "Default channel used when no workspace-specific agentChannels entry matches the session workdir. Prefer a fully routable channel string; bare providers are only weak fallbacks.",
-      "placeholder": "telegram|my-bot|123456789",
-      "sensitive": true
+      "help": "Optional but recommended. Default channel used when no workspace-specific agentChannels entry matches the session workdir. Prefer a fully routable channel string; bare providers are only weak fallbacks.",
+      "placeholder": "telegram|my-bot|123456789"
     },
     "agentChannels": {
       "label": "Workspace notification channels",
       "help": "Map absolute working-directory paths to notification channels so each workspace routes session updates to the right chat.",
-      "sensitive": true
+      "sensitive": true,
+      "advanced": true
     },
     "defaultWorkdir": {
       "label": "Default working directory",
@@ -172,37 +190,38 @@
     },
     "harnesses": {
       "label": "Harness configuration",
-      "help": "Per-harness defaults and model restrictions. Default: {\"codex\":{\"defaultModel\":\"gpt-5.4\",\"allowedModels\":[\"gpt-5.4\"],\"reasoningEffort\":\"medium\"},\"claude-code\":{\"defaultModel\":\"sonnet\",\"allowedModels\":[\"sonnet\",\"opus\"]}}."
-    },
-    "defaultModel": {
-      "label": "Legacy default model",
-      "help": "Deprecated. Mapped to harnesses[defaultHarness].defaultModel during migration.",
-      "placeholder": "sonnet"
-    },
-    "model": {
-      "label": "Legacy Codex model",
-      "help": "Deprecated. Use harnesses.codex.defaultModel instead.",
-      "placeholder": "gpt-5.3-codex"
+      "help": "Per-harness defaults and model restrictions. Default: {\"codex\":{\"defaultModel\":\"gpt-5.4\",\"allowedModels\":[\"gpt-5.4\",\"gpt-5.4-pro\"],\"reasoningEffort\":\"medium\"},\"claude-code\":{\"defaultModel\":\"sonnet\",\"allowedModels\":[\"sonnet\",\"opus\"]}}.",
+      "advanced": true
     },
     "maxSessions": {
       "label": "Maximum concurrent sessions",
-      "help": "Upper limit on concurrently running coding-agent sessions."
+      "help": "Upper limit on concurrently running coding-agent sessions.",
+      "advanced": true
     },
     "idleTimeoutMinutes": {
       "label": "Idle timeout (minutes)",
-      "help": "Minutes a paused multi-turn session can remain idle before the plugin auto-kills it."
+      "help": "Minutes a paused multi-turn session can remain idle before the plugin auto-kills it.",
+      "advanced": true
+    },
+    "defaultHarness": {
+      "label": "Default harness",
+      "help": "Choose the harness you expect to use most often. Pick Codex only when the Codex command and local auth are ready on this machine.",
+      "placeholder": "claude-code"
     },
     "permissionMode": {
       "label": "Default permission mode",
-      "help": "Default plugin orchestration mode used when new coding-agent sessions are launched. Use this for plan/default/bypass behavior; Codex execution stays fixed to 'never'."
+      "help": "Default plugin orchestration mode used when new coding-agent sessions are launched. Use this for plan/default/bypass behavior; Codex execution stays fixed to 'never'.",
+      "advanced": true
     },
     "planApproval": {
       "label": "Plan approval policy",
-      "help": "Choose whether plans are always sent to the user with Approve/Revise/Reject buttons (`ask`, default), delegated to the orchestrator for full-plan review first, or auto-approved."
+      "help": "Choose whether plans are always sent to the user with Approve/Revise/Reject buttons (`ask`, default), delegated to the orchestrator for full-plan review first, or auto-approved.",
+      "advanced": true
     },
     "defaultWorktreeStrategy": {
       "label": "Default worktree strategy",
-      "help": "Applies to all sessions that don't specify worktree_strategy explicitly. 'off' (default) disables worktrees globally. 'ask' creates a worktree and sends inline Merge locally / Create PR buttons on completion. 'delegate' wakes the orchestrator to decide autonomously. 'auto-merge' and 'auto-pr' are fully automated."
+      "help": "Applies to all sessions that don't specify worktree_strategy explicitly. 'off' (default) disables worktrees globally. 'ask' creates a worktree and sends inline Merge locally / Create PR buttons on completion. 'delegate' wakes the orchestrator to decide autonomously. 'auto-merge' and 'auto-pr' are fully automated.",
+      "advanced": true
     }
   },
   "skills": [

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "openclaw-code-agent",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "type": "module",
+  "packageManager": "pnpm@10.30.0",
   "main": "dist/index.js",
   "scripts": {
-    "build": "esbuild index.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/index.js --minify --external:openclaw --external:openclaw/plugin-sdk --external:@anthropic-ai/claude-agent-sdk",
+    "audit:prod": "pnpm audit --prod",
+    "build": "esbuild index.ts --bundle --platform=node --target=node22 --format=esm --outfile=dist/index.js --minify --external:openclaw --external:openclaw/plugin-sdk --external:openclaw/plugin-sdk/* --external:@anthropic-ai/claude-agent-sdk",
+    "check-plugin-security": "node scripts/check-plugin-security.mjs",
     "test": "node scripts/run-tests.mjs",
     "test:serial": "node scripts/run-tests.mjs",
     "test:file": "node scripts/run-tests.mjs",
@@ -13,13 +16,22 @@
     "smoke:codex-worktrees": "node scripts/run-tests.mjs tests/codex-harness.test.ts tests/session-bootstrap.test.ts tests/session-restore-service.test.ts",
     "smoke:codex-live": "OPENCLAW_RUN_LIVE_CODEX_SMOKE=1 node scripts/run-tests.mjs tests/live-codex-app-server-smoke.test.ts",
     "smoke:codex-release": "OPENCLAW_RUN_LIVE_CODEX_RELEASE_SMOKE=1 node scripts/run-tests.mjs tests/live-codex-app-server-smoke.test.ts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "validate:release-metadata": "node scripts/validate-release-metadata.mjs",
     "verify": "pnpm typecheck && pnpm build && pnpm test"
   },
   "openclaw": {
     "extensions": [
       "./dist/index.js"
-    ]
+    ],
+    "compat": {
+      "pluginApi": ">=2026.4.14",
+      "minGatewayVersion": "2026.4.14"
+    },
+    "build": {
+      "openclawVersion": "2026.4.21",
+      "pluginSdkVersion": "2026.4.21"
+    }
   },
   "files": [
     "dist/",
@@ -30,13 +42,14 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.81"
+    "@anthropic-ai/claude-agent-sdk": "^0.2.101"
   },
   "devDependencies": {
-    "@sinclair/typebox": "^0.34.48",
-    "@types/node": "^25.5.0",
-    "esbuild": "^0.27.4",
+    "@sinclair/typebox": "^0.34.49",
+    "@types/node": "^25.5.2",
+    "esbuild": "^0.28.0",
     "nanoid": "^5.1.7",
+    "openclaw": "2026.4.21",
     "tsx": "^4.21.0",
     "typescript": "^6.0.2"
   },
@@ -71,7 +84,10 @@
   },
   "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"
+    "openclaw": ">=2026.4.14"
+  },
+  "overrides": {
+    "basic-ftp": "5.3.0"
   },
   "pnpm": {
     "onlyBuiltDependencies": [
@@ -81,6 +97,14 @@
       "sharp",
       "@img/sharp-linux-x64",
       "@img/sharp-linux-arm64"
-    ]
+    ],
+    "overrides": {
+      "basic-ftp": "5.3.0",
+      "axios@<1.15.0": ">=1.15.0",
+      "follow-redirects@<1.16.0": "1.16.0",
+      "protobufjs@>=7 <7.5.5": "7.5.5",
+      "brace-expansion@>=4.0.0 <5.0.5": ">=5.0.5",
+      "path-to-regexp@>=8.0.0 <8.4.0": ">=8.4.0"
+    }
   }
 }

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

@@ -1,6 +1,6 @@
 ---
 name: Code Agent Orchestration
-description: Skill for orchestrating coding agent sessions from OpenClaw. Covers launching, monitoring, multi-turn interaction, lifecycle management, notifications, and worktree decision rules.
+description: Skill for orchestrating coding agent sessions from OpenClaw. Covers launching, monitoring, plan approval, lifecycle management, and worktree decisions.
 metadata:
   openclaw:
     homepage: https://github.com/goldmar/openclaw-code-agent
@@ -17,16 +17,16 @@ metadata:
 
 Use `openclaw-code-agent` to run Claude Code or Codex sessions as background coding jobs from chat.
 
-## 1. Launch Rules
+## Launch
 
 - Do not pass `channel` manually. Routing comes from `agentChannels`, the current chat context, and `fallbackChannel`.
-- Sessions are multi-turn. All sessions stay open for follow-up messages via `agent_respond`.
+- Sessions are multi-turn. Continue existing work with `agent_respond` or `agent_launch(..., resume_session_id=...)`; do not start a fresh session for the same task.
 - Always set a short kebab-case `name` when you care about later follow-up.
-- Set `workdir` to the target repo, not to the agent's own workspace.
-- Default behavior is `permission_mode: "plan"` plus `planApproval: "ask"` plus `defaultWorktreeStrategy: "off"`.
-- Use `permission_mode: "plan"` whenever the user wants a real planning checkpoint, reviewable plan, or approval buttons before implementation.
-- Use `permission_mode: "bypassPermissions"` only when the user wants autonomous execution. Do not try to recreate plan mode by stuffing "plan only" into the prompt unless you intentionally want a soft fallback rather than the primary UX contract.
-- In `plan` mode, the plan should be emitted directly in normal session output so the user can review it in chat. Do not tell the coding agent to write a plan document or markdown file unless the user explicitly asked for a file.
+- Set `workdir` to the target repo.
+- Use `permission_mode: "plan"` when the user wants a real review gate before implementation.
+- Use `permission_mode: "bypassPermissions"` only for autonomous execution.
+- `defaultWorktreeStrategy` now defaults to `off`. Opt into a worktree strategy explicitly when you want branch isolation.
+- In `plan` mode, the plan belongs in normal session output. Do not ask the coding agent to write plan docs or transcript artifacts unless the user explicitly asked for a file.
 
 Example:
 
@@ -38,76 +38,68 @@ agent_launch(
 )
 ```
 
-Resume and fork:
+## Resume, Don't Respawn
 
-```text
-agent_launch(
-  prompt: "Continue where you left off",
-  resume_session_id: "fix-auth"
-)
-
-agent_launch(
-  prompt: "Try a different approach",
-  resume_session_id: "fix-auth",
-  fork_session: true,
-  name: "fix-auth-alt"
-)
-```
-
-## 2. Anti-Cascade Rule
-
-When you are woken because a session is waiting or completed, do not launch a new coding session in response. Only use the existing session with:
-
-- `agent_output`
-- `agent_respond`
-- `agent_merge`
-- `agent_pr`
-- `agent_worktree_status`
+When a session already exists for the task, keep using it.
 
-## 2a. Resume vs. Spawn Rule (CRITICAL)
+- Waiting for plan approval: `agent_respond(session, message, approve=true)` or `agent_request_plan_approval(...)` if delegated approval must escalate to the user
+- Waiting for a question answer: `agent_respond(session, message)`
+- Killed/stopped by restart: `agent_respond(session, message)`
+- Completed but needs follow-up: `agent_launch(resume_session_id=session_id, prompt="...")`
+- Fresh `agent_launch` is only for genuinely independent work
 
-**Always resume — never spawn fresh — when a session already exists for the task.**
+Do not launch a new coding session from a wake event for the same task.
 
-| Situation | Correct action |
-|-----------|---------------|
-| Session waiting for plan approval | `agent_respond(session, message, approve=true)` |
-| Session waiting for a question answer | `agent_respond(session, message)` |
-| Session killed/stopped by restart | `agent_respond(session, message)` — killed sessions auto-resume on next `agent_respond` |
-| Session completed, user wants to extend/revise | `agent_launch(resume_session_id=session_id)` |
-| Worktree has uncommitted work after a crash | `agent_respond` on the stopped session first; only if truly unrecoverable, relaunch with the worktree still in place |
-
-**Never use `agent_launch` to start a fresh session when `agent_respond` would work.** Spawning fresh loses conversation history, may duplicate worktrees, and confuses the user.
-
-Only spawn a genuinely new session for work that is **completely independent** of any existing session.
-
-## 3. Monitoring
+## State and Monitoring
 
 Use:
 
 ```text
 agent_sessions()
-agent_sessions(status: "running")
 agent_output(session: "fix-auth", lines: 100)
 agent_output(session: "fix-auth", full: true)
 ```
 
-Trust the latest output and current phase. Do not report an old planning state after the session has already moved into implementation.
-Treat these wake fields as authoritative session state, not hints:
+For worktree follow-through, inspect:
+
+```text
+agent_worktree_status()
+agent_worktree_status(session: "fix-auth")
+```
+
+Treat that tool's lifecycle, derived state, cleanup disposition, and retained reasons as authoritative. Do not infer cleanup safety from a transcript summary or from branch names alone.
+
+Treat these wake fields as authoritative state when present:
 
 - `requestedPermissionMode`
-- `effectivePermissionMode` / current permission mode (`currentPermissionMode` in plugin payloads)
+- `effectivePermissionMode` / `currentPermissionMode`
 - `approvalExecutionState`
 
-Do not reinterpret approval behavior from transcript fragments when these fields are present.
+Use those deterministic fields instead of inferring behavior from transcript fragments.
+
+Approval/execution meanings:
+
+- `approved_then_implemented`: normal approved execution
+- `implemented_without_required_approval`: actual approval bypass
+- `awaiting_approval`: still stopped at the approval gate
+- `not_plan_gated`: no plan gate applied
 
-Completion and approval state handling:
+Completion ownership:
 
-- `approved_then_implemented` means normal approved execution. Do not frame it as rogue, surprising, or a bypass.
-- `implemented_without_required_approval` means the session left a required approval gate. Treat that as the actual approval-bypass case.
-- `awaiting_approval` means the session is still waiting at the gate. Do not describe implementation as started.
-- If the plugin wake says it already sent the canonical approval or completion message, do not send a duplicate plain-text recap unless you are adding real synthesis, a risk callout, or concrete next-step guidance.
+- The plugin sends the canonical completion notification.
+- The plugin owns the canonical completion status line; the orchestrator owns any additional plain-text follow-up.
+- After a coding-agent session completes, the orchestrator should usually add at least a short human-useful summary of what changed, what was done, or the concrete outcome.
+- That expectation applies to ordinary terminal/manual completions, manual no-change completions, and delegated worktree completions alike.
+- Treat the plugin's canonical `✅` as the status signal and your follow-up as the factual outcome summary that should usually come right after it.
+- That summary can be brief; one sentence is often enough.
+- Extra synthesis, risk framing, and next-step guidance are optional. Add them when useful; do not force them every time.
+- Do not generate your own heuristic completion summary from transcript tail lines. Base any summary on reliable result data such as `agent_output(..., full=true)`, diff context, or deterministic tool state.
+- Skip the summary only in narrow cases:
+  - no user-facing follow-up will be sent at all because the orchestrator is silently continuing an internal multi-phase pipeline
+  - the completion produced no meaningful outcome to report, or the reliable result data is still too incomplete to support even a short factual summary
+  - the session is a silent cron/system pipeline that already returned `NO_REPLY` or otherwise explicitly opted out of a user-facing follow-up summary
 
-## 4. Respond Rules
+## Respond Rules
 
 Auto-respond immediately only for:
 
@@ -121,120 +113,99 @@ Forward everything else to the user:
 - scope changes
 - credentials or production questions
 - ambiguous requirements
-- anything you are not certain you should answer autonomously
 
-When forwarding, quote the session's exact question. Do not add your own commentary.
+When forwarding, quote the session's exact question. Do not add commentary.
 
-Examples:
+## Plan Approval
 
-```text
-agent_respond(session: "fix-auth", message: "Yes, proceed.")
-
-agent_respond(
-  session: "fix-auth",
-  message: "Stop. Do not touch the database schema.",
-  interrupt: true
-)
-```
-
-## 5. Plan Approval
+Use `permission_mode: "plan"` whenever the user wants a real planning checkpoint.
 
-Mode selection:
+### `planApproval: "ask"`
 
-- `permission_mode: "plan"` is the primary contract for planning sessions. It produces a plan-review stop and is the only mode you should rely on for explicit approval UX.
-- `permission_mode: "bypassPermissions"` is for autonomous execution. Do not try to recreate plan mode by stuffing "plan only", "do not implement yet", or similar text into the prompt.
-- If the user says "investigate first", "show me the plan", "plan only", or "wait for approval before coding", launch in `plan` mode.
-- If the user says "just do it", "run autonomously", or wants uninterrupted execution, use `bypassPermissions`.
-- In `plan` mode, the plan belongs in the agent's normal output stream. Do not ask the coding agent to write `PLAN.md`, investigation notes, or similar artifacts unless the user explicitly requested a file deliverable.
+- Approval belongs to the user.
+- The plugin sends the canonical Approve / Revise / Reject prompt directly to the user.
+- If the user requests changes, wait for the revised plan from that same session; the revised submission becomes the latest actionable review version automatically.
+- Wait for the user's answer, then forward it with `agent_respond(...)`.
+- Do not send a duplicate approval recap or second approval prompt.
 
-Approve a pending plan with:
+### `planApproval: "delegate"`
 
-```text
-agent_respond(
-  session: "fix-auth",
-  message: "Approved. Go ahead.",
-  approve: true,
-  userInitiated: true
-)
-```
+- Approval belongs to the orchestrator first.
+- This is wake-first: the plugin wakes the orchestrator without user buttons.
+- Before deciding, read the full plan with `agent_output(session, full=true)`; do not rely on the truncated preview.
+- Approve directly with `agent_respond(..., approve=true)` only when the latest actionable plan version is clearly in-bounds and low risk.
+- When approving directly, pass a structured rationale with `approval_rationale`, for example: `agent_respond(session='...', message='Approved. Go ahead.', approve=true, approval_rationale='Scope matches the request and the changes are low risk.')`
+- After approving directly, send the user a short plain-text follow-up explaining what was approved and why. The plugin's `👍 Plan approved` line is only a fallback signal, not the full explanation.
+- If a prior version had `changes_requested`, that stale state should not block approval of the latest revised plan version.
+- If escalation is needed, call `agent_request_plan_approval(session='...', summary='...')` exactly once so the plugin sends the single canonical user approval prompt.
+- That escalation summary must concisely explain why you are escalating, plus risk/scope notes the user needs to decide.
+- After that canonical prompt exists, wait for the user's decision; do not send a second plain-text approval summary.
 
-Rules:
+### `planApproval: "approve"`
 
-- `approve: true` approves a pending plan or escalates a `default` mode session into `bypassPermissions`.
-- Do not send approval and revision feedback in the same call.
-- In `planApproval: "ask"`, the user is expected to approve or revise. Wait for that input.
-- Telegram users may get inline `Approve`, `Reject`, and `Revise` buttons for plan review.
+- Auto-approve only after verification per the session policy.
 
-## 6. Worktree Decision Rules
-
-### `ask`
+## Worktree Decisions
 
-Do nothing after completion. The plugin already informed the user and attached 4 buttons:
-- **✅ Merge** — merge branch locally
-- **📬 Open PR** — create a GitHub PR
-- **⏭️ Decide later** — snooze reminders for 24h
-- **🗑️ Dismiss (deletes branch)** — permanently delete branch and worktree (irreversible)
+Treat worktrees as temporary task sandboxes, not as generic branch inventory.
 
-Do not call `agent_merge` or `agent_pr` unless the user explicitly asks after that.
+Lifecycle meanings:
 
-### `delegate`
+- `pending_decision`: still waiting for merge / PR / dismiss follow-through
+- `pr_open`: PR exists; preserve the sandbox
+- `merged`: normal ancestry merge landed
+- `released`: content already landed on the base branch even though SHAs differ after rebase, squash, or cherry-pick
+- `dismissed`: sandbox intentionally discarded
+- `no_change`: no committed delta
 
-Read the diff context from the wake, then decide:
+If `agent_worktree_status` reports `released`, treat that sandbox as already landed. Do not narrate it as “still unmerged” just because the branch appears ahead.
 
-- `agent_merge` for low-risk, clearly scoped changes that match the task
-- **NEVER call `agent_pr()` autonomously** — always escalate PR decisions to the user
-- escalate to the user if scope or risk is unclear, or if a PR is the safer choice
-- if the wake already says the plugin sent the canonical completion message, only add user-facing follow-up when you need synthesis, risk framing, or concrete next steps beyond that message
+### `off`
 
-### `manual`
+- No worktree. The session runs in the main checkout.
 
-Wait for an explicit user request before calling `agent_merge` or `agent_pr`.
+### `ask`
 
-### Never
+- The plugin owns the user-facing completion/decision message and button UI.
+- Do not call `agent_merge` or `agent_pr` unless the user explicitly asks after that.
+- A completed ask-session worktree may later resolve as `released` if its content already landed on base through another path. Confirm that with `agent_worktree_status(...)` before deciding what follow-up is still needed.
 
-- never use raw `git merge` or raw PR commands in place of the plugin tools
-- never clear a pending worktree decision by inventing your own workaround; use `agent_worktree_cleanup(session: "...", dismiss_session: true)` to permanently dismiss
-- never call `agent_pr()` autonomously in `delegate` flows — always escalate to the user for PR decisions
+### `delegate`
 
-## 6b. Planning Document Policy
+- The plugin wakes the orchestrator with diff context and no automatic user buttons.
+- Read the diff context and decide whether a local merge is clearly safe.
+- `agent_merge` is acceptable for low-risk, clearly scoped changes that match the task.
+- Never call `agent_pr()` autonomously in delegate flows. Escalate PR decisions to the user.
+- If the wake already says the plugin sent the canonical completion notification, do not repeat that status line, but you should still usually add a short summary of the completed outcome.
 
-- Do NOT ask the coding agent to write planning documents, investigation notes, or analysis artifacts as files unless the user explicitly requested a file
-- Do NOT commit planning documents, investigation notes, or analysis artifacts to the branch
-- Only commit actual code, configuration, tests, and documentation changes that were explicitly requested as part of the task
+### `manual`
 
-## 6c. Resume vs New Session
+- Wait for an explicit user request before calling `agent_merge` or `agent_pr`.
 
-- When resuming a session with an existing worktree, use `resume_session_id` with `agent_launch`
-- Do not create a new session if the old worktree branch still has unmerged changes — resume instead
-- If the user wants a fresh start, use `fork_session: true` to branch from the previous session state
+### Cleanup
 
-## 7. Lifecycle Notes
+- Use `agent_worktree_cleanup(mode: "preview_safe")` to review what **Clean all safe** would remove.
+- Use `agent_worktree_cleanup(mode: "clean_safe")` only when the user asked to clean up safe sandboxes.
+- Use `agent_worktree_cleanup(mode: "preview_all")` when you need both safe candidates and retained reasons.
+- Respect retained reasons from `agent_worktree_status` / `agent_worktree_cleanup`; they are the lifecycle model, not advisory prose.
 
-- `agent_respond` auto-resumes paused, idle-killed, and most other terminal sessions.
-- The only common non-resumable path is `startup-timeout`.
-- Terminal runtime sessions are evicted after `sessionGcAgeMinutes` (default 1440 minutes), but persisted metadata remains resumable.
-- `agent_stats` is the quick operator view for aggregate cost and duration.
+### Never
 
-## 8. Chat Commands
+- Never use raw `git merge` or raw PR commands in place of plugin tools.
+- Never invent your own workaround for a pending worktree decision; use `agent_worktree_cleanup(session: "...", dismiss_session: true)` to dismiss permanently.
+- Never use `agent_worktree_cleanup` to force-delete unresolved worktrees. The supported bulk action is "clean all safe": omit `session` and let the plugin remove only lifecycle-safe worktrees while preserving anything active, pending, dirty, or PR-open.
+- Never merge or PR an `ask` worktree behind the user's back.
 
-Common command equivalents:
+## File Artifact Policy
 
-```text
-/agent --name fix-auth Fix the auth middleware bug
-/agent_sessions
-/agent_output fix-auth
-/agent_respond fix-auth Add tests too
-/agent_kill fix-auth
-/agent_resume --fork fix-auth Try a different approach
-/agent_stats
-```
+- Do not ask the coding agent to write planning documents, investigation notes, or analysis artifacts as files unless the user explicitly requested a file.
+- Do not commit planning documents, investigation notes, or transcript-summary artifacts to the branch.
+- Commit only actual code, configuration, tests, and explicitly requested documentation.
 
-## 9. Anti-Patterns
+## Anti-Patterns
 
-- Do not pass a `multi_turn` or `multi_turn_disabled` parameter; all sessions are multi-turn and the parameter no longer exists.
-- Do not pass `channel` manually unless you are debugging routing at a very low level.
+- Do not pass `multi_turn` or `multi_turn_disabled`; all sessions are multi-turn.
+- Do not pass `channel` manually unless you are debugging routing.
 - Do not auto-answer design or scope questions.
-- Do not launch new sessions from wake events.
-- Do not merge or PR an `ask` worktree behind the user's back.
-
-See `README.md` for the product overview and `docs/REFERENCE.md` for the canonical operator reference.
+- Do not infer approval/completion ownership from old transcript snippets when deterministic fields are present.
+- Do not post duplicate completion or approval recaps when the plugin already sent the canonical message.