openclaw-code-agent 3.0.0 → 3.1.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 parallel work patterns.
+description: Skill for orchestrating coding agent sessions from OpenClaw. Covers launching, monitoring, multi-turn interaction, lifecycle management, notifications, and worktree decision rules.
 metadata:
   openclaw:
     homepage: https://github.com/goldmar/openclaw-code-agent
@@ -15,515 +15,226 @@ metadata:
 
 # Code Agent Orchestration
 
-You orchestrate coding agent sessions via the `openclaw-code-agent`. Each session is an autonomous agent that executes code tasks in the background.
+Use `openclaw-code-agent` to run Claude Code or Codex sessions as background coding jobs from chat.
 
----
-
-## 1. Launching sessions
-
-### Mandatory rules
-
-- **Notifications are routed automatically** via `agentChannels` config. Do NOT pass `channel` manually — it bypasses automatic routing.
-- **Thread-aware routing**: When launched from a Telegram thread/topic, notifications are routed back to that same thread via `originThreadId`. This is handled automatically.
-- **Always pass `multi_turn: true`** unless the task is a guaranteed one-shot with no possible follow-up.
-- **Name the sessions** with `name` in kebab-case, short and descriptive.
-- **Set `workdir`** to the target project directory, not the agent's workspace.
-- **Default mode is `plan`**: Sessions start in plan mode. When the user approves a plan (e.g. "looks good", "go ahead"), the plugin automatically switches to `bypassPermissions` mode.
-
-### Essential parameters
-
-| Parameter | When to use |
-|---|---|
-| `prompt` | Always. Clear and complete instruction. |
-| `name` | Always. Descriptive kebab-case (`fix-auth-bug`, `add-dark-mode`). |
-| `channel` | **Do NOT pass.** Resolved automatically via `agentChannels`. |
-| `workdir` | Always when the project is not in the `defaultWorkdir`. |
-| `multi_turn` | `true` by default unless explicitly one-shot. |
-| `model` | When you want to force a specific model (`"sonnet"`, `"opus"`, `"gpt-5.4"`). Subject to `harnesses.<name>.allowedModels` restrictions if configured. |
-| `system_prompt` | To inject project-specific context. |
-| `permission_mode` | `"plan"` by default. `"bypassPermissions"` for trusted tasks. |
-
-### Harness-scoped model restrictions
-
-The plugin config restricts models per harness via `harnesses.<name>.allowedModels`:
-
-- **Matching:** Case-insensitive substring matching (e.g., `"sonnet"` matches `"claude-sonnet-4-6"`)
-- **Explicit model blocked:** If a caller explicitly requests a model not in that harness's `allowedModels`, the launch fails with an error
-- **Default model blocked:** If no model is specified and the resolved `harnesses.<name>.defaultModel` is not in `allowedModels`, the launch fails with a config error
-- **Not configured:** If `allowedModels` is empty or undefined for that harness, all models are allowed for that harness
-
-**Example configuration:**
-```json
-{
-  "harnesses": {
-    "claude-code": {
-      "defaultModel": "sonnet",
-      "allowedModels": ["sonnet", "haiku"]
-    },
-    "codex": {
-      "defaultModel": "gpt-5.4",
-      "allowedModels": ["gpt-5.4"]
-    }
-  }
-}
-```
-
-This configuration allows Claude models containing "sonnet" or "haiku" in their identifier, and restricts Codex launches to `gpt-5.4`.
+## 1. Launch Rules
 
-**Interaction with harness compatibility:**
-When both `harnesses.<name>.allowedModels` and harness compatibility constraints apply, you must satisfy BOTH:
-1. The model must be in `harnesses.<name>.allowedModels` (if configured)
-2. The model must be compatible with the chosen harness
+- 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`.
+- 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.
 
-Example: If `harnesses.claude-code.allowedModels = ["sonnet", "gpt-4"]` and you use the default `claude-code` harness, only "sonnet" will work because "gpt-4" is not a Claude-compatible model.
-
-### Examples
-
-```
-# Simple task
-agent_launch(
-  prompt: "Fix the null pointer in src/auth.ts line 42",
-  name: "fix-null-auth",
-  workdir: "/home/user/projects/myapp",
-  multi_turn: true
-)
+Example:
 
-# Full feature
+```text
 agent_launch(
-  prompt: "Implement dark mode toggle in the settings page. Use the existing theme context in src/context/theme.tsx. Add a toggle switch component and persist the preference in localStorage.",
-  name: "add-dark-mode",
-  workdir: "/home/user/projects/myapp",
-  multi_turn: true
+  prompt: "Fix the auth middleware bug and add tests",
+  name: "fix-auth",
+  workdir: "/home/user/projects/my-app"
 )
 ```
 
-### Resume and fork
+Resume and fork:
 
-```
-# Resume a completed session
+```text
 agent_launch(
-  prompt: "Continue. Also add error handling for the edge cases we discussed.",
-  resume_session_id: "fix-null-auth",
-  multi_turn: true
+  prompt: "Continue where you left off",
+  resume_session_id: "fix-auth"
 )
 
-# Fork to try an alternative approach
 agent_launch(
-  prompt: "Try a completely different approach: use middleware instead of decorators.",
-  resume_session_id: "refactor-db-repositories",
+  prompt: "Try a different approach",
+  resume_session_id: "fix-auth",
   fork_session: true,
-  name: "refactor-db-middleware-approach",
-  multi_turn: true
+  name: "fix-auth-alt"
 )
 ```
 
-### Harness and model compatibility
+## 2. Anti-Cascade Rule
 
-| Harness | Supported Models | Examples |
-|---------|-----------------|---------|
-| `claude-code` | Anthropic only | `sonnet`, `opus`, `haiku`, `claude-sonnet-4-6` |
-| `codex` | OpenAI only | `gpt-4`, `gpt-5`, `o1`, `o3-mini` |
+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:
 
-- When user says "with sonnet/opus/haiku" → use `harness: "claude-code"` (or omit — it's the default)
-- When user says "with gpt-4/o1/o3" → use `harness: "codex"`
-- **Never** pass Anthropic models to codex harness or OpenAI models to claude-code harness
+- `agent_output`
+- `agent_respond`
+- `agent_merge`
+- `agent_pr`
+- `agent_worktree_status`
 
-If `harnesses.<name>.allowedModels` is configured, both explicit model requests and default models outside that list are rejected with an error. When the default model is not allowed, the error message directs you to update the plugin config.
+## 2a. Resume vs. Spawn Rule (CRITICAL)
 
----
+**Always resume — never spawn fresh — when a session already exists for the task.**
 
-## 2. Anti-cascade rules (CRITICAL)
+| 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 |
 
-**When woken by a waiting-for-input or completion event, you MUST ONLY use `agent_respond` or `agent_output` for the referenced session. NEVER launch new sessions in response to wake events.**
+**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.
 
-This prevents cascading session creation. The orchestrator exists to manage existing sessions, not to spawn new ones from wake events.
+Only spawn a genuinely new session for work that is **completely independent** of any existing session.
 
----
-
-## 3. Monitoring sessions
+## 3. Monitoring
 
-### List sessions
+Use:
 
-```
-# All sessions
+```text
 agent_sessions()
-
-# Only running sessions
 agent_sessions(status: "running")
-
-# Completed sessions (for resume)
-agent_sessions(status: "completed")
-```
-
-### View output
-
-```
-# Summary (last 50 lines)
-agent_output(session: "fix-null-auth")
-
-# Full output (up to 2000 lines)
-agent_output(session: "fix-null-auth", full: true)
-
-# Specific last N lines
-agent_output(session: "fix-null-auth", lines: 100)
-```
-
-### Interpreting session state
-
-The `agent_output` header shows status, phase, cost, and duration:
-```
-Session: fix-auth [abc123] | Status: RUNNING | Phase: planning | Cost: $0.0312 | Duration: 2m15s
-```
-
-The `Phase:` indicator for running sessions:
-- `Phase: planning` — the agent is writing a plan
-- `Phase: awaiting-plan-approval` — plan submitted, waiting for review
-- `Phase: implementing` — actively writing code
-
-The `agent_sessions` listing also shows phase and cost when available:
-```
-🟢 fix-auth [abc123] (2m15s | $0.03) — multi-turn
-   ⚙️  Phase: planning
-```
-
-**Recency rule:** Always trust the Phase indicator and the *latest* (bottom) output lines. If earlier output mentions plan mode but Phase says `implementing`, the session has transitioned. Do NOT report it as "waiting for approval."
-
----
-
-## 4. Multi-turn interaction
-
-### Send a follow-up
-
-```
-# Reply to an agent question
-agent_respond(session: "add-dark-mode", message: "Yes, use CSS variables for the theme colors.")
-
-# Redirect a running session (interrupts the current turn)
-agent_respond(session: "add-dark-mode", message: "Stop. Use Tailwind dark: classes instead of CSS variables.", interrupt: true)
-```
-
-### Auto-respond rules (STRICT)
-
-**Auto-respond immediately with `agent_respond`:**
-- Permission requests to read/write files or run bash commands -> `"Yes, proceed."`
-- Explicit confirmations like "Should I continue?" -> `"Yes, continue."`
-
-**Forward to the user (everything else):**
-- Architecture decisions (Redis vs PostgreSQL, REST vs GraphQL...)
-- Destructive operations (deleting files, dropping tables...)
-- Ambiguous requirements not covered by the initial prompt
-- Scope changes ("This will require refactoring 15 files")
-- Anything involving credentials, secrets, or production environments
-- Questions about approach, design, or implementation choices
-- Codebase clarification questions
-- When in doubt -> always forward to the user
-
-**When forwarding to the user, quote the agent's exact question. Do NOT add your own analysis, interpretation, or commentary.**
-
-### Interaction cycle
-
-1. Session launches -> runs in background
-2. Wake event arrives when the session is waiting for input
-3. Read the question with `agent_output(session, full: true)`
-4. Decide: auto-respond (permissions/confirmations only) or forward
-5. If auto-respond: `agent_respond(session, answer)`
-6. If forward: relay the agent's exact question to the user, wait for their response, then `agent_respond`
-
----
-
-## 5. Lifecycle management
-
-### Stop or complete a session
-
-```
-# Kill a stuck/looping session
-agent_kill(session: "fix-null-auth")
-
-# Mark a session as successfully completed
-agent_kill(session: "fix-null-auth", reason: "completed")
-```
-
-Use `agent_kill` (no reason) when:
-- The session is stuck or looping
-- The user requests a stop
-
-Use `agent_kill(reason: "completed")` when:
-- The turn output shows the task is done — this sends a `✅ Completed` notification
-- Prefer this over letting the idle timer expire
-
-### Idle completion and auto-resume
-
-- After a turn completes without a question, the session is immediately **paused** (killed with reason `done`, auto-resumable).
-- On the next `agent_respond` to a completed or idle-killed session, the plugin **auto-resumes** by spawning a new session with the same session ID — conversation context is preserved.
-- Sessions idle for `idleTimeoutMinutes` (default: 15 min) are killed with reason `idle-timeout` and also auto-resume on next respond.
-- Sessions killed for any reason except `startup-timeout` auto-resume on next `agent_respond`. This includes user-killed sessions (`agent_kill`), shutdown-killed sessions (gateway restart), and idle-timeout sessions.
-
-### Timeouts
-
-- Idle multi-turn sessions are automatically killed after `idleTimeoutMinutes` (default: 15 min)
-- Completed sessions are garbage-collected after 1h but remain resumable via persisted IDs
-
-### Check the result after completion
-
-When a session completes (completion wake event):
-
-1. `agent_output(session: "xxx", full: true)` to read the result
-2. Summarize briefly: files changed, cost, duration, any issues
-3. If failed, analyze the error and decide: relaunch, fork, or escalate
-
----
-
-## 6. Notifications
-
-### Thread-based routing
-
-Notifications are routed to the Telegram thread/topic where the session was launched. This is handled automatically via `originThreadId` — no manual configuration needed. The `agentChannels` config handles chat-level routing, and the thread ID handles within-chat routing.
-
-### Events
-
-| Event | What happens |
-|---|---|
-| Session starts | Silent (command response confirms launch) |
-| 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>"
+agent_output(session: "fix-auth", lines: 100)
+agent_output(session: "fix-auth", full: true)
 ```
 
-**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.
+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:
 
-**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.
+- `requestedPermissionMode`
+- `effectivePermissionMode` / current permission mode (`currentPermissionMode` in plugin payloads)
+- `approvalExecutionState`
 
-The Telegram chat ID and topic thread ID are available from the current conversation context.
+Do not reinterpret approval behavior from transcript fragments when these fields are present.
 
-### Worktree `ask` strategy — no duplicate summary
+Completion and approval state handling:
 
-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
+- `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.
 
-**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.
+## 4. Respond Rules
 
-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.
+Auto-respond immediately only for:
 
-**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.
+- permission requests for file reads, writes, or shell commands
+- explicit continuation prompts such as "Should I continue?"
 
----
+Forward everything else to the user:
 
-### Plan → Execute mode switch
+- architecture or design choices
+- destructive operations
+- scope changes
+- credentials or production questions
+- ambiguous requirements
+- anything you are not certain you should answer autonomously
 
-Sessions start in `plan` mode by default. When you reply with **only** an approval keyword as the **entire message** (`"go ahead"`, `"implement"`, `"looks good"`, `"approved"`, `"lgtm"`, `"do it"`, `"proceed"`, `"execute"`, `"ship it"`), the plugin switches the session to `bypassPermissions` mode. The message must contain **only** the keyword — extra text will prevent the switch. To approve and also give instructions, send the approval keyword first, then send implementation details as a separate follow-up message.
+When forwarding, quote the session's exact question. Do not add your own commentary.
 
-### Permission escalation with `approve: true`
+Examples:
 
-The `approve` parameter on `agent_respond` escalates session permissions to `bypassPermissions`. It works in two scenarios:
+```text
+agent_respond(session: "fix-auth", message: "Yes, proceed.")
 
-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 a session that keeps prompting for bash permissions
-agent_respond(session: "fix-auth", message: "proceed", approve: true)
+agent_respond(
+  session: "fix-auth",
+  message: "Stop. Do not touch the database schema.",
+  interrupt: true
+)
 ```
 
-### Plan approval modes
-
-The `planApproval` config controls how the orchestrator handles plan-approval events:
-
-- **`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.
-
-#### Delegate mode decision criteria
-
-When operating in `delegate` mode, **approve** the plan directly if ALL of the following are true:
-- The plan scope matches the original task request
-- The changes are low-risk (no destructive operations, no credential handling, no production deployments)
-- The plan is clear and well-scoped (no ambiguous requirements or open design questions)
-- No architectural decisions that the user should weigh in on
-- The working directory and codebase are correct
-
-**Escalate** to the user (forward with 👋 and wait) if ANY of the following are true:
-- Destructive operations (deleting files, dropping tables, force-pushing)
-- Credentials, secrets, or production environments
-- Architectural decisions not covered by the original task
-- Scope expanded beyond the original request
-- Ambiguous requirements or assumptions the user should confirm
-- When in doubt — always escalate
-
----
-
-## 7. Worktree workflow
+## 5. Plan Approval
 
-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.
+Mode selection:
 
-### Strategies at a glance
+- `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.
 
-| 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 |
+Approve a pending plan with:
 
-### Launch with worktree isolation
-
-```
-agent_launch(
-  prompt: "Implement the new user settings page",
-  name: "user-settings",
-  workdir: "/app",
-  worktree_strategy: "auto-pr"
+```text
+agent_respond(
+  session: "fix-auth",
+  message: "Approved. Go ahead.",
+  approve: true,
+  userInitiated: true
 )
 ```
 
-### 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. |
+Rules:
 
-Note: the ⏸️ turn-complete wake is suppressed for both `ask` and `delegate` strategies — the worktree decision notification replaces it as the completion signal.
+- `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.
 
-### Delegate mode: deciding merge vs PR
+## 6. Worktree Decision Rules
 
-When you receive a `worktree-delegate` wake:
+### `ask`
 
-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`
+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)
 
-### Check worktree status
+Do not call `agent_merge` or `agent_pr` unless the user explicitly asks after that.
 
-```
-agent_worktree_status()                      # all sessions with worktrees
-agent_worktree_status(session: "user-settings")  # specific session
-```
+### `delegate`
 
-### Manual merge or PR after `manual`/`ask`
+Read the diff context from the wake, then decide:
 
-```
-# Merge back to base branch
-agent_merge(session: "user-settings", strategy: "merge")
+- `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
 
-# Or create/update a GitHub PR
-agent_pr(session: "user-settings", title: "Add user settings page")
-```
+### `manual`
 
-### Resume with worktree context
+Wait for an explicit user request before calling `agent_merge` or `agent_pr`.
 
-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:
+### Never
 
-```
-agent_launch(
-  prompt: "Continue — also add unit tests",
-  resume_session_id: "user-settings"
-)
-```
+- 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
 
-### Deliverable mode
+## 6b. Planning Document Policy
 
-For document/report generation tasks, use `output_mode: "deliverable"` to send 📄 instead of ✅:
+- 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
 
-```
-agent_launch(
-  prompt: "Write a technical spec for the new auth system",
-  name: "auth-spec",
-  output_mode: "deliverable"
-)
-```
+## 6c. Resume vs New Session
 
----
+- 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
 
-## 8. Best practices
+## 7. Lifecycle Notes
 
-### Launch checklist
+- `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.
 
-1. `agentChannels` is configured for this workdir -> notifications arrive
-2. `multi_turn: true` -> interaction is possible after launch
-3. `name` is descriptive -> easy to identify in `agent_sessions`
-4. `workdir` points to the correct project -> the agent works in the right directory
+## 8. Chat Commands
 
-### Parallel tasks
+Common command equivalents:
 
-```
-# Launch multiple sessions on independent tasks
-agent_launch(prompt: "Build the frontend auth page", name: "frontend-auth", workdir: "/app/frontend", multi_turn: true)
-agent_launch(prompt: "Build the backend auth API", name: "backend-auth", workdir: "/app/backend", multi_turn: true)
+```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
 ```
 
-- Respect the `maxSessions` limit (default: 5)
-- Each session must have a unique `name`
-- Monitor each session individually via wake events
+## 9. Anti-Patterns
 
-### Reporting results
-
-When a session completes, keep summaries brief:
-- Files changed
-- Cost and duration
-- Any issues or remaining TODOs
-
----
-
-## 9. Anti-patterns
-
-| Anti-pattern | Consequence | Fix |
-|---|---|---|
-| Launching new sessions from wake events | Cascading sessions | Only use `agent_respond`/`agent_output` when woken |
-| Adding commentary when forwarding questions | User gets noise, not the question | Quote the agent's exact question, nothing else |
-| Auto-responding to design/architecture questions | Decisions made without user input | Only auto-respond to permissions and explicit confirmations |
-| 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 |
-
----
+- 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 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.
 
-## 10. Quick tool reference
-
-| Tool | Usage | Key parameters |
-|---|---|---|
-| `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` |
+See `README.md` for the product overview and `docs/REFERENCE.md` for the canonical operator reference.