@sayknow-cli/coding-agent 0.3.7 → 0.3.8

package/src/prompts/system/volatile-project-context.md

@@ -0,0 +1,10 @@
+<system-reminder>
+{{#if workspaceTree.rendered}}<workspace-tree>
+Working directory layout (sorted by mtime, recent first; depth ≤ 3):
+{{workspaceTree.rendered}}
+{{#if workspaceTree.truncated}}
+(some entries elided to keep the tree short — use `find`/`read` to drill in)
+{{/if}}
+</workspace-tree>
+{{/if}}Today is {{date}}, and the current working directory is '{{cwd}}'.
+</system-reminder>

package/src/prompts/system/web-search.md

@@ -1,25 +1,22 @@
 Research assistant with web search. Find accurate, well-sourced information. Synthesize comprehensive answers.
 
-<priorities>
+<instruction>
 1. Accuracy over speed — verify claims across multiple sources when possible
 2. Primary over secondary — prefer official docs, papers, and announcements over blog summaries
 3. Recency matters — note publication dates; prefer recent sources for time-sensitive topics
 4. Transparency on uncertainty — distinguish confirmed facts from inferences
-</priorities>
-
-<synthesis>
 - Lead with a direct answer, then supporting evidence
 - Quote or paraphrase specific sources; no vague attributions
 - Sources conflict: acknowledge the discrepancy and note which is more authoritative
 - Technical topics: prefer official documentation and specifications
 - News/events: prefer primary reporting over aggregators
 - Include concrete data: version numbers, dates, exact figures, code snippets, specific examples
-</synthesis>
+</instruction>
 
-<format>
+<output>
 - Be thorough — cover the topic in depth with specific evidence, not surface-level summaries
 - Omit filler and unnecessary hedging; do NOT sacrifice detail for brevity
 - Include publication dates when recency affects relevance
 - Structure answers with clear sections when covering multiple aspects
 - Cite sources inline using provided search results
-</format>
+</output>

package/src/prompts/tools/apply-patch.md

@@ -16,6 +16,9 @@ Each operation starts with one of three headers:
 May be immediately followed by *** Move to: <new path> if you want to rename the file.
 Then one or more "hunks", each introduced by @@ (optionally followed by a hunk header).
 Within a hunk each line starts with:
+- ` ` (space) — an unchanged context line
+- `-` — a line removed from the file
+- `+` — a line added to the file
 
 For instructions on [context_before] and [context_after]:
 - By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change's [context_after] lines in the second change's [context_before] lines.
@@ -63,3 +66,6 @@ It is important to remember:
 - You must include a header with your intended action (Add/Delete/Update)
 - You must prefix new lines with `+` even when creating a new file
 - File references can only be relative, NEVER ABSOLUTE.
+- You MUST read the target file before editing, and copy context lines verbatim (including whitespace).
+- If a patch fails, re-read the file and produce a new patch from current content — NEVER retry the same patch.
+- NEVER use patches to fix indentation or reformat code; run the project formatter once at the end instead.

package/src/prompts/tools/ast-edit.md

@@ -14,6 +14,7 @@ Performs structural AST-aware rewrites via native ast-grep.
 </instruction>
 
 <output>
+- Output is a **staged preview** — nothing touches disk until you call `resolve` with `action: "apply"`; call `resolve` with `action: "discard"` to reject the staged rewrite
 - Replacement summary, per-file replacement counts, and change diffs as `-LINE+ID|before` / `+LINE+ID|after` lines
 - Parse issues when files cannot be processed
 </output>

package/src/prompts/tools/bash.md

@@ -57,7 +57,7 @@ Use it only for sanctioned SKC workflow CLI persistence or state read/write/cont
 {{#if asyncEnabled}}
 # Timeout and async
 
-- `timeout` (seconds) caps the **wall-clock duration** of the command. When it elapses the process is killed and the call returns with a timeout annotation. Range: `1`–`3600`s; default `300`s (see `clampTimeout("bash", …)` in `tool-timeouts.ts`).
+- `timeout` (seconds) caps the **wall-clock duration** of the command. When it elapses the process is killed and the call returns with a timeout annotation. Range: `1`–`3600`s; default `300`s.
 - `async: true` only defers **reporting** of the result — it does NOT disable, extend, or detach the timeout. A daemon started with `async: true` is still killed when `timeout` elapses, regardless of how long the agent waits before reading the result.
 - For long-running daemons (dev servers, watchers): either pass an explicit large `timeout` (up to `3600`), or fully detach the process from this shell using `nohup …  &` / `setsid … &` / `disown` so it survives independent of the bash call's lifecycle.
 {{/if}}

package/src/prompts/tools/bisect.md

@@ -0,0 +1,22 @@
+Find the exact commit that introduced (or fixed) a behavior by driving `git bisect` with a shell predicate, then restore the working tree and report the culprit.
+
+Use this instead of running `git bisect` by hand when you have a reproducible pass/fail check and a known-good and known-bad revision. The tool guarantees clean setup and teardown: it always runs `git bisect reset` and then discards any tracked-file edits the predicate made (`git reset --hard`), so it never leaves the repository stranded in a detached bisect state or with the predicate's tracked-file modifications behind. Untracked files the predicate creates are left in place (the tool never deletes files it did not create).
+
+Parameters:
+- `good`: the OLDER endpoint — a commit that must be an ancestor of `bad`.
+- `bad`: the NEWER endpoint (defaults to `HEAD`).
+- `run`: the shell command evaluated at each revision. Exit `0` = good, `125` = skip (untestable revision), any other non-zero = bad.
+- `invert`: set true to find the commit that FIXED the behavior instead of the one that broke it.
+- `maxSteps` / `stepTimeoutMs`: bounds; a step that exceeds `stepTimeoutMs` is treated as a skip.
+
+Search direction:
+- Default (find the regression): the predicate passes at `good` and fails at `bad`. The tool reports the first commit that turned it bad.
+- `invert` (find the fix): the predicate fails at `good` and passes at `bad`. The tool reports the first commit that turned it good.
+
+Rules:
+- Requires a git repository and a clean working tree. Commit or stash uncommitted changes first — bisect checks out historical commits and would clobber them.
+- `good` must resolve, `bad` must resolve, they must differ, and `good` must be an ancestor of `bad`.
+- Make `run` self-contained and deterministic (build + test in one command). It always runs from the repository root (the top level of the working tree), even when the tool is invoked from a subdirectory — reference files by repo-relative paths, and do not assume the current subdirectory exists at every candidate commit.
+- Prefer a narrow predicate that targets only the behavior you are hunting, so unrelated breakage does not mislead the search.
+
+The result reports the first bad (or first fixing) commit with its author, date, subject, and changed files, plus every revision tested. Every tracked file is restored to its pre-bisect state; if the predicate created untracked files they are reported and left in place.

package/src/prompts/tools/browser.md

@@ -5,8 +5,8 @@ Drives a real Chromium tab with full puppeteer access via JS execution.
 - Four actions:
   - `open` — acquire (or reuse) a named tab. `name` defaults to `"main"`. Optional `url` navigates after the tab is ready. Optional `viewport` sets dimensions. Optional `dialogs: "accept" | "dismiss"` auto-handles `alert`/`confirm`/`beforeunload` so navigation/clicks don't hang (default: leave dialogs unhandled — page hangs until caller wires `page.on('dialog', …)`).
   - `close` — release a tab by `name`, or every tab with `all: true`. For spawned-app browsers, set `kill: true` to terminate the process tree (default leaves it running).
-  - `run` — execute JS against an existing tab. `code` is the body of an async function with `page`, `browser`, `tab`, `display`, `assert`, `wait` in scope. The function's return value is JSON-stringified into the tool result; multiple `display(value)` calls accumulate text/images.
   - `act` — run a list of structured `actions` against an existing tab without writing JS (preferred for routine navigation/interaction). Each step is `{ verb, … }`; verbs: `navigate {url, wait_until?}`, `click {id|selector}`, `type {id|selector, text}`, `fill {selector, value}`, `select {selector, values}`, `press {key, selector?}`, `scroll {dx?, dy?}`, `back`, `wait {selector?|ms?}`, `observe {viewport_only?, include_all?}`, `extract {format?}`, `screenshot`. Address elements by the numeric `id` from a prior `observe` (preferred) or a selector. Steps run in order; the tool returns an array of per-step results (observations/extracted content included). Use `run` only when a verb does not cover what you need.
+  - `run` — execute JS against an existing tab. `code` is the body of an async function with `page`, `browser`, `tab`, `display`, `assert`, `wait` in scope. The function's return value is JSON-stringified into the tool result; multiple `display(value)` calls accumulate text/images.
 - Tabs survive across `run` calls and across in-process subagents. Open once, reuse many times.
 - Browser kinds, selected by the `app` field on `open`:
   - default (no `app`) → headless Chromium with stealth patches.

package/src/prompts/tools/computer.md

@@ -6,7 +6,7 @@
 
 - Disabled means disabled: when the tool is disabled (`computer.alwaysOn=false` with `computer.enabled` unset/false) or the platform is unsupported, every action including `screenshot` fails with `COMPUTER_DISABLED` and captures nothing.
 - Callable only on Apple Silicon macOS (`arm64` darwin); available by default there, with `computer.alwaysOn=false` as the off-switch and `computer.enabled=true` as the manual enable path.
-- Native execution remains supervisor-gated. If the stop/suspend supervisor is unavailable, stale, suspended, permissioned off, display-stale, or cancelled, the action fails closed with a `COMPUTER_*` code.
+- Native execution remains supervisor-gated. If the stop/suspend supervisor is unavailable, stale, suspended, permissioned off, display-stale, or cancelled, the action fails closed with a `COMPUTER_*` code. Coordinate actions carry the latest known screenshot display epoch when one is available so display-topology changes fail with `COMPUTER_DISPLAY_STALE`.
 - Respect the user's stop/suspend request immediately. Do not loop desktop actions after a stop/suspend/error.
 - The user can stop or suspend the session at any time with the configured kill-switch hotkey (default `Control+Option+Command+Escape`). If you see `COMPUTER_CANCELLED` or `COMPUTER_SUPERVISOR_NOT_LIVE`, stop and wait for the user.
 
@@ -14,7 +14,7 @@
 
 Coordinates are screenshot pixels, not CSS pixels and not normalized fractions. Use the latest successful `screenshot` dimensions and origin/scale metadata as the coordinate frame. Do not guess coordinates outside the screenshot bounds.
 
-When you send a sequence of actions in one `batch` call, pointer coordinates in later steps are validated against the most recent screenshot from that batch. If a coordinate is out of bounds, the batch stops and reports `COMPUTER_COORD_INVALID`. Always capture a fresh screenshot before acting if the display may have changed.
+For stale-display protection to apply, derive pointer coordinates from a successful screenshot in the same tool session; a screenshot-first `batch` is preferred because later coordinate steps are validated against that screenshot and carry its display epoch into native execution. If a coordinate is out of bounds, the batch stops and reports `COMPUTER_COORD_INVALID`. Always capture a fresh screenshot before acting if the display may have changed.
 
 ## Actions
 

package/src/prompts/tools/cron.md

@@ -23,5 +23,3 @@ Use a single `op` field to select the operation:
 - All times are interpreted in the local timezone.
 - Recurring tasks fire with up to 30 minutes of deterministic jitter (or up to half their interval for sub-hourly tasks). One-shot tasks scheduled for `:00` or `:30` may fire up to 90 s early. Pick an off-minute if exact timing matters.
 - Closing or replacing the session clears every scheduled task.
-
-Disable the scheduler entirely via `CLAUDE_CODE_DISABLE_CRON=1`.

package/src/prompts/tools/eval.md

@@ -55,7 +55,7 @@ Cells render like a Jupyter notebook. `display(value)` renders non-presentable d
 {{#if js}}- **js**: the VM exposes a selective `process` subset, Web APIs, `Buffer`, `fs/promises`, and the `Bun` global.
 {{/if}}</caution>
 
-<example>
+<examples>
 {{#if py}}```json
 {
   "cells": [
@@ -72,4 +72,4 @@ Cells render like a Jupyter notebook. `display(value)` renders non-presentable d
   ]
 }
 ```{{/if}}
-</example>
+</examples>

package/src/prompts/tools/find.md

@@ -25,7 +25,7 @@ Matching file paths sorted by modification time (most recent first). Truncated a
 </examples>
 
 <avoid>
-For open-ended searches requiring multiple rounds of globbing and searching, you MUST use Task tool instead.
+For open-ended searches requiring multiple rounds of globbing and searching, delegate a bounded fact-finding task to an appropriate canonical role agent (`planner` for sequencing/context maps or `architect` for read-only architecture assessment) instead.
 </avoid>
 
 <critical>

package/src/prompts/tools/github.md

@@ -1,15 +1,15 @@
-GitHub CLI tool with a single op-based dispatch. Wraps `gh` for repositories, pull requests, search, checkout, push, and Actions watch workflows. For reading a single issue or PR view, use the `issue://<N>` or `pr://<N>` URL schemes (cached automatically) — they replace what used to be `op: issue_view` and `op: pr_view`. For reading PR diffs, use `pr://<N>/diff` (changed-file listing), `pr://<N>/diff/<i>` (single file slice, 1-indexed), or `pr://<N>/diff/all` (full unified diff) — they replace what used to be `op: pr_diff`.
+GitHub CLI tool with a single op-based dispatch. Wraps `gh` for repositories, pull requests, search, checkout, push, and Actions watch workflows. For reading a single issue or PR view, use the `issue://<N>` or `pr://<N>` URL schemes (cached automatically). For reading PR diffs, use `pr://<N>/diff` (changed-file listing), `pr://<N>/diff/<i>` (single file slice, 1-indexed), or `pr://<N>/diff/all` (full unified diff).
 
 <instruction>
-Pick the operation via `op`. Each op uses a subset of the parameters:
+Pick the operation via `op`. Each op uses a subset of the parameters. Search ops (`search_issues`, `search_prs`, `search_code`, `search_commits`) default `repo` to the current checkout's `owner/repo` when omitted; pass an explicit `repo:`/`org:`/`user:` qualifier in `query` to search outside it.
 - `repo_view` — Read repository metadata. Optional `repo` (owner/repo) and `branch`. Falls back to the current checkout or default `gh` repo.
 - `pr_create` — Create a pull request. Either provide `title` (and optional `body`) or set `fill: true` to auto-fill from commits. Optional `base` (target, defaults to repo default), `head` (source, defaults to current branch), `draft`, `repo`, `reviewer[]`, `assignee[]`, `label[]`. Returns the new PR URL plus a summary.
 - `pr_checkout` — Check one or more pull requests out into dedicated git worktrees. Optional `pr` (number, URL, branch, or array of any of those — pass an array to batch-check-out multiple PRs in one call), `repo`, `force` (reset existing local branch).
 - `pr_push` — Push a checked-out PR branch back to its source branch. Requires the branch to have been checked out via `op: pr_checkout` (carries push metadata). Optional `branch`; defaults to the current checked-out git branch. Optional `forceWithLease`.
-- `search_issues` — Search issues using normal GitHub issue search syntax. Optional `query` (required unless `since`/`until` is set), `repo`, `limit`, `since`, `until`, `dateField`. Defaults `repo` to the current checkout's `owner/repo` when omitted; pass an explicit `repo:`/`org:`/`user:` qualifier in `query` to search outside it.
-- `search_prs` — Search pull requests using normal GitHub PR search syntax. Optional `query` (required unless `since`/`until` is set), `repo`, `limit`, `since`, `until`, `dateField`. Defaults `repo` to the current checkout's `owner/repo` when omitted; pass an explicit `repo:`/`org:`/`user:` qualifier in `query` to search outside it.
-- `search_code` — Search code with GitHub code search syntax. Required `query`. Optional `repo`, `limit`. Returns matching paths with surrounding fragments. Defaults `repo` to the current checkout's `owner/repo` when omitted; pass an explicit `repo:`/`org:`/`user:` qualifier in `query` to search outside it. Date filtering (`since`/`until`) is **not** supported by GitHub code search.
-- `search_commits` — Search commits across GitHub. Optional `query` (required unless `since`/`until` is set), `repo`, `limit`, `since`, `until`. `dateField` is ignored — always uses `committer-date`. Defaults `repo` to the current checkout's `owner/repo` when omitted; pass an explicit `repo:`/`org:`/`user:` qualifier in `query` to search outside it.
+- `search_issues` — Search issues using normal GitHub issue search syntax. Optional `query` (required unless `since`/`until` is set), `repo`, `limit`, `since`, `until`, `dateField`.
+- `search_prs` — Search pull requests using normal GitHub PR search syntax. Optional `query` (required unless `since`/`until` is set), `repo`, `limit`, `since`, `until`, `dateField`.
+- `search_code` — Search code with GitHub code search syntax. Required `query`. Optional `repo`, `limit`. Returns matching paths with surrounding fragments. Date filtering (`since`/`until`) is **not** supported by GitHub code search.
+- `search_commits` — Search commits across GitHub. Optional `query` (required unless `since`/`until` is set), `repo`, `limit`, `since`, `until`. `dateField` is ignored — always uses `committer-date`.
 - `search_repos` — Search repositories across GitHub. Optional `query` (required unless `since`/`until` is set), `limit`, `since`, `until`, `dateField` (use query qualifiers like `org:`, `language:` instead of `repo`).
 - Date filter format for `since` / `until`: relative duration `<n><unit>` (`m`/`h`/`d`/`w`/`mo`/`y`, e.g. `3d`, `12h`, `2w`), an ISO date `YYYY-MM-DD`, or an ISO datetime. Translated to a single GitHub-search qualifier (`created:≥…`, `created:≤…`, or `created:since..until`). `dateField: "updated"` maps to `updated:` for issues/prs and `pushed:` for repos. When you only want a date filter and no keywords, omit `query` entirely.
 - `run_watch` — Watch a GitHub Actions workflow run. Optional `run` (id or URL). Omitting `run` watches all workflow runs for the current HEAD commit; `branch` falls back to the current branch. Optional `tail` (log lines per failed job). Streams snapshots, fast-fails on the first detected job failure (with a brief grace period to capture concurrent failures), then fetches tailed logs for the failed jobs. The full failed-job logs are saved as a session artifact for on-demand reads.

package/src/prompts/tools/goal.md

@@ -6,7 +6,7 @@ Use a single `op` field:
 - `resume` re-activates a paused goal so work can continue.
 - `complete` marks the goal complete after you have verified every deliverable against current evidence.
 - `drop` discards the current goal without completing it.
-- `pause` parks an active goal without completing or dropping it. The autonomous continuation loop stops while the goal is paused, so the agent is not re-activated every turn. Use `pause` (not `drop`) when the goal is genuinely still alive but every outstanding deliverable is blocked on human input or action only the user can perform — e.g. the user must sing, record, edit, approve, or perform a manual/physical step — and no further autonomous progress is possible. A paused goal keeps its progress and is fully resumable via `resume`.
+- `pause` parks an active goal without completing or dropping it. While paused, the autonomous continuation loop stops re-activating the agent. Pause only when the goal is still alive but every outstanding deliverable is blocked on action only the user can perform (e.g. record, approve, a manual/physical step); it is never a substitute for `complete`. A paused goal keeps its progress and is resumable via `resume`.
 
 Examples:
 - `goal({"op":"create","objective":"Implement feature X"})`
@@ -16,6 +16,4 @@ Examples:
 - `goal({"op":"complete"})`
 - `goal({"op":"drop"})`
 
-Call `complete` only when the goal is actually done and verified.
 If `get` shows a paused goal, call `resume` before continuing work on it.
-Do not `pause` as a substitute for `complete`; pause only when the outstanding work is human-blocked.

package/src/prompts/tools/image-gen.md

@@ -1,7 +1,14 @@
 Generates or edits images.
 
-<instructions>
-- You MUST provide a single detailed `subject` prompt for image generation or editing.
-- When using multiple `input`, you SHOULD describe each image's role directly in `subject`, e.g. `Image 1` for composition reference, `Image 2` for lighting reference, `Image 3` for background.
-- For text: you SHOULD add "sharp, legible, correctly spelled" for important text; keep text short
-</instructions>
+<instruction>
+- `subject` is required: the main subject, described in detail. The tool assembles the final prompt as "subject, action, scene. composition. lighting. style." — use the structured fields rather than packing everything into `subject`:
+  - `action`: what the subject is doing
+  - `scene`: location or environment
+  - `composition`: camera angle and framing
+  - `lighting`: lighting setup
+  - `style`: artistic style
+- `text`: text to render in the image. For important text you SHOULD add "sharp, legible, correctly spelled"; keep text short.
+- `aspect_ratio` / `image_size`: output shape controls.
+- For edits: pass `changes` (array of edit instructions) and the source image via `input`.
+- `input`: array of `{path}` or `{data, mime_type}` entries. When using multiple `input` images, you SHOULD describe each image's role directly in `subject`, e.g. `Image 1` for composition reference, `Image 2` for lighting reference, `Image 3` for background.
+</instruction>

package/src/prompts/tools/irc.md

@@ -4,11 +4,12 @@ Sends short text messages to other live agents in this process and receives thei
 - The main agent is addressable as `0-Main`. Subagents reuse their task id (e.g. `0-AuthLoader`).
 - `op: "list"` returns the current set of visible peers. Use it before sending if you are not sure who is live.
 - `op: "send"` delivers `message` to `to`. `to` may be a specific id or `"all"` to broadcast.
+- `awaitReply` (optional): wait for a prose reply. Defaults to `true` for DMs and `false` for `to: "all"` broadcasts.
 - The recipient generates the reply via an ephemeral side-channel turn that uses their current model, system prompt, and history — it does **not** wait for the recipient's main loop to be free, so it is safe to IRC an agent that is currently inside a long-running tool call.
 - The exchange (incoming question + auto-reply) is queued for injection into the recipient's persisted history; the recipient sees it on its next turn and can follow up if needed.
 </instruction>
 
-<when_to_use>
+<conditions>
 You SHOULD reach for `irc` proactively when continuing alone is wasteful or wrong. When in doubt, prefer messaging.
 - **Unexpected state.** You hit something the original task did not describe — a missing file, a config that contradicts the assignment, an API behaving differently than you were told, a tool failing in a way that suggests the spec is wrong. DM `0-Main` (or the spawning agent) for guidance instead of guessing.
 - **Blocked by another agent.** A peer holds the file/branch/resource you need, has already started the change you are about to make, or owns a decision you depend on. DM that peer (or broadcast to discover who) before duplicating or stepping on work.
@@ -16,17 +17,17 @@ You SHOULD reach for `irc` proactively when continuing alone is wasteful or wron
 - **Coordination opportunities.** You realize a peer's in-flight work would benefit from yours, or vice-versa.
 
 Do **not** use `irc` for: routine progress updates, things you can verify with a tool call, or questions whose answer is already in your assignment / repo / docs.
-</when_to_use>
+</conditions>
 
 <etiquette>
 These rules apply to both sending and replying.
 - **Plain prose only.** Do not send structured JSON status payloads (e.g. `{"type":"task_completed",…}`). Write a normal sentence: "Done with the auth refactor — left a TODO in `src/server/auth.ts` for the rate limiter."
 - **Do not quote the message you are replying to.** The sender already saw it; the TUI already renders it. Lead with the answer.
-- **Use IRC, not terminal tools, to learn about peers.** Do not `grep` artifacts, read other sessions' JSONL files, or shell-poke around to figure out what another agent is doing. DM them — they have the live answer and you do not.
+- **Use IRC, not terminal tools, to learn about peers.** Do not `search` artifacts, read other sessions' JSONL files, or shell-poke around to figure out what another agent is doing. DM them — they have the live answer and you do not.
 - **One round-trip is enough.** Replies arrive synchronously when the recipient is reachable. Do not follow up with "did you get my message?" — they did. If `delivered` is empty or the result was `failed`, the peer is unavailable; move on or report the blocker, do not retry in a loop.
 - **Stay terse.** A DM is a chat message, not a memo. One question per send when you can. Share file paths and artifacts via `local://` / `artifact://` URLs instead of pasting blobs.
 - **Address peers by id.** Use the exact id from `op: "list"` (e.g. `0-AuthLoader`, `0-Main`). Do not invent friendly names.
-- **Do not IRC for things a tool would answer.** If a `read`, `grep`, or build command would resolve the question, do that first.
+- **Do not IRC for things a tool would answer.** If a `read`, `search`, or build command would resolve the question, do that first.
 - **When you receive an IRC message, answer it before continuing.** The recipient injects the question + your auto-reply into your history; address it directly, do not repeat it back to the user.
 </etiquette>
 

package/src/prompts/tools/job.md

@@ -1,6 +1,6 @@
 Inspects, waits, or cancels async jobs.
 
-Background job results are delivered automatically when complete. Running job output stays quiet by default to avoid flooding the conversation; use `tail` when you explicitly want to show/reopen retained output. Reach for this tool only when you need to inspect or intervene.
+Background job results are delivered automatically when complete. Jobs that back task subagents should be controlled via the `subagent` tool when it is available; use `job` for non-subagent jobs (async bash, monitors) and as a compatibility fallback. Running job output stays quiet by default to avoid flooding the conversation; use `tail` when you explicitly want to show/reopen retained output. Reach for this tool only when you need to inspect or intervene.
 
 In the interactive TUI, supported managed foreground bash can be folded into a background job by pressing `Ctrl+B` twice while it is running. Raw shell `Ctrl+Z`/`bg` is not the supported path inside SKC because it bypasses job ownership and output-routing contracts.
 
@@ -16,7 +16,7 @@ Show the retained output buffer for one or more background jobs without waiting.
 - Prefer `tail` over polling when you only need to peek at progress, so the conversation can continue without flooding the TUI.
 
 ## `poll: [id, …]`
-Block until the specified jobs finish or the wait window elapses.
+Block until the specified jobs finish or the wait window (~30 s, not configurable) elapses.
 - Use when you are genuinely blocked on a result and have no other work to do.
 - Returns the current snapshot when the timer elapses; running jobs remain running.
 - Completed jobs include their final output in the returned snapshot.

package/src/prompts/tools/lsp.md

@@ -37,6 +37,6 @@ Interacts with Language Server Protocol servers for code intelligence.
 
 <critical>
 - You MUST use `lsp` for symbol-aware operations (rename, find references, go to definition/implementation, code actions) whenever a language server is available — it is safer and more accurate than text-based alternatives.
-- You NEVER perform cross-file renames with `ast_edit`, `sed`, `rsed`, or manual edits when `lsp` `rename` can do it. Text-based renames miss shadowing, re-exports, and usages in other files.
+- You NEVER perform cross-file renames with `ast_edit`, `sed`, or manual edits when `lsp` `rename` can do it. Text-based renames miss shadowing, re-exports, and usages in other files.
 - Prefer `lsp` `code_actions` for imports, quick-fixes, and refactors the language server already knows how to apply.
 </critical>

package/src/prompts/tools/monitor.md

@@ -23,8 +23,8 @@ Pick by how many notifications you need:
 
 ## Output
 
-Returns `Monitor started · task <task_id>` plus a task entry visible via `job({op:"list"})`. Each stdout line of the monitored command becomes a `<task-notification>` event delivered between turns.
+Returns `Monitor started · task <task_id>` plus a task entry visible via `job({list: true})`. Each stdout line of the monitored command becomes a `<task-notification>` event delivered between turns.
 
 ## Cancellation
 
-There is no separate `monitor` kill tool. Cancel a running monitor with `job` using the returned `task_id`. Disposing the session also cancels every monitor the calling agent started.
+There is no separate `monitor` kill tool. Cancel a running monitor via `job({cancel: ["<task_id>"]})` using the returned `task_id`. Disposing the session also cancels every monitor the calling agent started.

package/src/prompts/tools/patch.md

@@ -5,7 +5,7 @@ Patches files given diff hunks. Primary tool for existing-file edits.
 - `@@` — bare header when context lines unique
 - `@@ $ANCHOR` — anchor copied verbatim from file (full line or unique substring)
 **Anchor Selection:**
-1. Otherwise choose highly specific anchor copied from file:
+1. Prefer a bare `@@` when the context lines alone are unique; otherwise choose a highly specific anchor copied from the file:
    - full function signature
    - class declaration
    - unique string literal/error message
@@ -47,7 +47,7 @@ Returns success/failure; on failure, error message indicates:
 - You NEVER use anchors as comments (no line numbers, location labels, placeholders like `@@ @@`)
 - You NEVER place new lines outside the intended block
 - If edit fails or breaks structure, you MUST re-read the file and produce a new patch from current content — you NEVER retry the same diff
-- NEVER use edit to fix indentation, whitespace, or reformat code. Formatting is a single command run once at the end (`bun fmt`, `cargo fmt`, `prettier —write`, etc.)—not N individual edits. If you see inconsistent indentation after an edit, leave it; the formatter will fix all of it in one pass.
+- NEVER use edit to fix indentation, whitespace, or reformat code. Formatting is a single command run once at the end (`bun fmt`, `cargo fmt`, `prettier --write`, etc.)—not N individual edits. If you see inconsistent indentation after an edit, leave it; the formatter will fix all of it in one pass.
 </critical>
 
 <examples>

package/src/prompts/tools/replace.md

@@ -12,25 +12,6 @@ Returns success/failure status. On success, file modified in place with replacem
 </output>
 
 <critical>
-- You MUST read the file at least once in the conversation before editing. Tool errors if you attempt edit without reading file first.
+- You MUST read the file at least once in the conversation before editing.
+- Use Replace when the _content itself_ identifies the location. For position-addressed changes (append, insert at line N, delete a line range), use the `write` or line-anchored edit tools — NEVER `cat`/`sed` pipelines.
 </critical>
-
-<bash-alternatives>
-Replace for content-addressed changes—you identify \_what* to change by its text.
-
-For position-addressed or pattern-addressed changes, bash more efficient:
-
-|Operation|Command|
-|---|---|
-|Append to file|`cat >> file <<'EOF'`…`EOF`|
-|Prepend to file|`{ cat - file; } <<'EOF' > tmp && mv tmp file`|
-|Delete lines N-M|`sed -i 'N,Md' file`|
-|Insert after line N|`sed -i 'Na\text' file`|
-|Regex replace|`sd 'pattern' 'replacement' file`|
-|Bulk replace across files|`sd 'pattern' 'replacement' **/*.ts`|
-|Copy lines N-M to another file|`sed -n 'N,Mp' src >> dest`|
-|Move lines N-M to another file|`sed -n 'N,Mp' src >> dest && sed -i 'N,Md' src`|
-
-Use Replace when _content itself_ identifies location.
-Use bash when _position_ or _pattern_ identifies what to change.
-</bash-alternatives>

package/src/prompts/tools/rewind.md

@@ -6,7 +6,7 @@ Requirements:
 - `report` is REQUIRED and must be concise, factual, and actionable.
 - Include key findings, decisions, and any unresolved risks.
 - Do not include raw scratch logs unless essential.
-- You MUST call this before yielding if a checkpoint is active.
+- `checkpoint`'s must-rewind-before-yield rule applies: never yield with a checkpoint still active.
 
 Behavior:
 - If no checkpoint is active, this tool errors.

package/src/prompts/tools/search-tool-bm25.md

@@ -5,7 +5,7 @@ Activate hidden tools (MCP and built-in) when you need a capability not in your
 {{#if discoverableMCPToolCount}}Total discoverable tools available: {{discoverableMCPToolCount}}.{{/if}}
 Input:
 - `query` — required natural-language or keyword query
-- `limit` — optional maximum number of tools to return and activate (default `8`)
+- `limit` — optional maximum number of tools to return and activate (default `8`; start with 5–10 if unsure)
 
 Behavior:
 - Searches hidden tool metadata using BM25-style relevance ranking
@@ -14,16 +14,6 @@ Behavior:
 - Repeated searches add to the active tool set; they do not remove earlier selections
 - Newly activated tools become available before the next model call in the same overall turn
 
-Notes:
-Start with `limit` 5–10 if unsure.
-- `query` is matched against tool metadata fields:
-  - `name`
-  - `label`
-  - `server_name` (MCP tools)
-  - `mcp_tool_name` (MCP tools)
-  - `description` / `summary`
-  - input schema property keys (`schema_keys`)
-
 Not for repository/file/code search. Tool discovery only.
 
 Returns JSON with:

package/src/prompts/tools/search.md

@@ -2,7 +2,7 @@ Searches files using powerful regex matching.
 
 <instruction>
 - Supports Rust regex syntax (RE2-style — no lookaround or backreferences). Use line anchors or post-filters instead of (?!…)/(?<!…)
-- `paths` is required and accepts an array of files, directories, globs, or internal URLs
+- `paths` accepts an array of files, directories, globs, or internal URLs; when omitted, the whole working directory is searched
 - `paths` is an array; do not embed commas or spaces inside a single entry. Pass `["src", "tests"]` not `["src,tests"]`.
 - Cross-line patterns are detected from literal `\n` or escaped `\\n` in `pattern`
 </instruction>

package/src/prompts/tools/skill.md

@@ -8,14 +8,15 @@ Invoke another available skill in the current turn.
 <instruction>
 - `name` is the skill name as it appears in `/skill:<name>` (e.g. `ralplan`, `ultragoal`, `team`, `deep-interview`)
 - `args` is the free-form argument string the skill would receive after `/skill:<name>` on the command line
-- The skill tool dispatches the callee's SKILL.md as a user-attribution custom message in the current turn (steering the stream when active, appending otherwise). Before dispatch, the tool atomically demotes the caller and promotes the callee in `.skc/state/` by calling `skc state <caller> handoff --to <callee>` in-process.
-- The chain is refused unless the caller's `current_phase` is in `{complete, completed, handoff, failed, cancelled, canceled, inactive}`. To prepare the active skill for chaining, write `current_phase: "handoff"` to its mode-state via `skc state <skill> write --input '{"current_phase":"handoff"}' --json`. The skill tool itself then runs `skc state <skill> handoff --to <callee>` in-process to atomically demote the caller and promote the callee — you do not need to run the handoff verb separately.
+- The tool loads the callee's SKILL.md into the current turn and handles the caller→callee state handoff itself.
+- The chain is refused while the caller skill is still active. If your current skill has not yet reached a terminal phase, prepare it first with `skc state <skill> write --input '{"current_phase":"handoff"}' --json`; no other handoff command is needed.
 - Call once per chain step. To chain `A → B → C`, A calls `skill(B)`; B's next agent turn calls `skill(C)`.
 </instruction>
 
 <critical>
 - Do NOT use this tool to "remind yourself" of a skill you're already running. The current SKILL.md is already in your context.
 - Do NOT chain into the same skill recursively. If a skill's flow needs another iteration, follow its in-document instructions.
+- `name` MUST be one concrete skill name, NOT a glob or wildcard. Passing `*`, `?`, or a pattern like `git-*` is rejected immediately — the `--skills '*'` launch filter is unrelated to this tool's `name`.
 - The chained skill's planning/execution-boundary rules still apply. Chaining does not grant execution approval.
 </critical>
 

package/src/prompts/tools/ssh.md

@@ -1,7 +1,8 @@
 Runs commands on remote hosts.
 
 <instruction>
-You MUST build commands from the reference below
+You MUST build commands from the reference below.
+The local coreutils restrictions (`cat`/`grep`/`find`/`head`/`tail` bans) do NOT apply on remote hosts — `read`/`search`/`find` cannot reach them, so these shell commands are the only tools available there.
 </instruction>
 
 <commands>

package/src/prompts/tools/subagent.md

@@ -2,12 +2,12 @@ Lists, inspects, awaits, pauses, resumes, steers, or cancels detached task subag
 
 Task launches return immediately. Use this tool when you need direct control over those running subagents. Prefer `subagent` for task subagents; generic `job` remains available for non-subagent jobs and compatibility fallback access.
 
-`verbosity` controls output size: `receipt` (default) returns status metadata plus a single <=280-character result/error preview and an `agent://<id>` output ref when available; `preview` returns <=2000 characters; `full` returns <=12000 characters and requires explicit `ids`.
+`verbosity` controls output size: `receipt` (default) returns status metadata plus a single ≤280-character result/error preview and an `agent://<id>` output ref when available; `preview` returns ≤2000 characters; `full` returns ≤12000 characters and requires explicit `ids`.
 
 # Operations
 
 ## `action: "list"`
-Snapshot your visible detached subagents, including `running`, `paused`, `queued`, and terminal subagents when retained. Output is receipt-only by default; use `verbosity: "preview"` for a bounded preview or inspect explicit `ids` with `verbosity: "full"` when fuller retained text is necessary.
+Snapshot your visible detached subagents, including `running`, `paused`, `queued`, and terminal subagents when retained. Optional `limit` (1–50) caps how many subagents are returned. Output is receipt-only by default; use `verbosity: "preview"` for a bounded preview or inspect explicit `ids` with `verbosity: "full"` when fuller retained text is necessary.
 
 ## `action: "inspect"`
 Inspect selected subagents by `ids`; omit `ids` to inspect current running subagents. Terminal subagents return receipt-only output by default, with an `agent://<id>` ref when a verified output artifact is available. `verbosity: "full"` requires explicit `ids`.

package/src/prompts/tools/task.md

@@ -3,12 +3,11 @@ Launches subagents to parallelize workflows.
 - Results are delivered automatically when complete.
 - The tool result lists the assigned task ids (e.g. `0-AuthLoader`) — those are the live agent ids.
 {{#if ircEnabled}}
-- Coordinate with running tasks via `irc` using those ids. `subagent` cancel terminates a task and **cannot carry a message** — never cancel because an await timed out; cancel only when the task has actually failed, gone off-track, or become unrecoverably wrong.
-- If genuinely blocked on completion, wait with `subagent` action `await` and a timeout; timeout only bounds your wait and does not stop or fail the subagent.
+- Coordinate with running tasks via `irc` using those ids. `subagent` cancel terminates a task and **cannot carry a message**.
 {{else}}
-- If genuinely blocked on completion, wait with `subagent` action `await` and a timeout; timeout only bounds your wait and does not stop or fail the subagent.
-- Use `subagent` action `inspect` or `list` to snapshot manager state; `cancel` only when a task has actually failed, gone off-track, or become unrecoverably wrong.
+- Use `subagent` action `inspect` or `list` to snapshot manager state.
 {{/if}}
+- To wait or cancel, use the `subagent` tool; its await/cancel doctrine applies (never cancel just because an await timed out).
 
 {{#if ircEnabled}}
 Subagents have no conversation history, but they can reach you and their siblings live via the `irc` tool. Front-load every fact, file path, and direction they need in {{#if contextEnabled}}`context` or `assignment`{{else}}each `assignment`{{/if}}.
@@ -19,7 +18,7 @@ Subagents have no conversation history. Every fact, file path, and direction the
 <parameters>
 - `agent`: agent type for all tasks
 - `tasks`: tasks to execute in parallel
- - `.id`: CamelCase, ≤32 chars
+ - `.id`: filesystem-safe, ≤48 chars, matching `[A-Za-z0-9][A-Za-z0-9_-]*`; prefer CamelCase
  - `.description`: UI label only — subagent never sees it
  - `.assignment`: complete self-contained instructions; one-liners and missing acceptance criteria are PROHIBITED
 {{#if contextEnabled}}- `context`: shared background prepended to every assignment; session-specific only{{/if}}

package/src/prompts/tools/todo-write.md

@@ -12,7 +12,7 @@ Allowed `op` values are only `init`, `start`, `done`, `drop`, `rm`, `append`, an
 |`start`|`task`|Mark in progress|
 |`done`|`task` or `phase`|Mark completed|
 |`drop`|`task` or `phase`|Mark abandoned|
-|`rm`|`task` or `phase`|Remove|
+|`rm`|`task` or `phase` or *(none = clear all tasks)*|Remove a task; with `phase`, empties the phase (the phase entry remains); bare `rm` clears every task in every phase|
 |`append`|`phase`, `items: string[]`|Append tasks to `phase`; lazily creates phase|
 |`note`|`task`, `text`|Append a note to a task. Reminders for future-you only.|
 

package/src/prompts/tools/vim.md

@@ -1,6 +1,7 @@
 Vim-style `edit` mode. The tool name stays `edit`; every call requires `file`, and the buffer loads automatically on first use.
 - `{"file": "path"}` - view file
 - `{"file": "path", "steps": [{"kbd": ["…"], "insert": "…"}]}` - edit file
+- `pause` (optional boolean) - a "paused" call skips the auto-save after its steps and may leave the last step in INSERT mode; the buffer stays open for the next call. Non-paused calls auto-save once after all steps complete.
 
 **Multi-location edits: always edit highest line number first (bottom-up).** Each insert shifts lines below it.
 

package/src/prompts/tools/web-search.md

@@ -3,9 +3,11 @@ Searches the web for up-to-date information beyond knowledge cutoff.
 <instruction>
 - You SHOULD prefer primary sources (papers, official docs) and corroborate key claims with multiple sources
 - You MUST include links for cited sources in the final response
+- Provider-neutral params: `recency` (freshness window), `limit`/`num_search_results` (result counts), `max_tokens`, `temperature`
 </instruction>
 
 <xai>
+The parameters below apply ONLY when the active search provider is `xai`; ignore them (and never pass them) on any other provider.
 - With provider `xai`, use `xai_search_mode: "web"` for normal web search, `"x"` for X/Twitter search, or `"web_and_x"` when both surfaces are relevant.
 - xAI web filters: `allowed_domains` or `excluded_domains` (max 5, mutually exclusive), plus `enable_image_understanding` and `enable_image_search`.
 - xAI X filters: `allowed_x_handles` or `excluded_x_handles` (max 20, mutually exclusive), `from_date`, `to_date`, `enable_image_understanding`, and `enable_video_understanding`.

package/src/prompts/tools/write.md

@@ -3,10 +3,16 @@ Creates or overwrites file at specified path.
 <conditions>
 - Creating new files explicitly required by task
 - Replacing entire file contents when editing would be more complex
-- Supports `.tar`, `.tar.gz`, `.tgz`, and `.zip` archive entries via `archive.ext:path/inside/archive`
-- Supports SQLite row operations via `db.sqlite:table` (insert), `db.sqlite:table:key` (update with JSON content, delete with empty content)
 </conditions>
 
+<instruction>
+- Archives: write entries inside `.tar`, `.tar.gz`, `.tgz`, and `.zip` via `archive.ext:path/inside/archive`.
+- SQLite rows:
+  - `db.sqlite:table` with JSON content — insert a row
+  - `db.sqlite:table:key` with JSON content — update the row with that primary key
+  - `db.sqlite:table:key` with empty content — DELETE that row (destructive; double-check the key)
+</instruction>
+
 <critical>
 - You SHOULD use Edit tool for modifying existing files (more precise, preserves formatting)
 - You NEVER create documentation files (*.md, README) unless explicitly requested

package/src/runtime-api-key.ts

@@ -0,0 +1,16 @@
+export interface RuntimeApiKeyTarget {
+	setRuntimeApiKey(provider: string, apiKey: string): void;
+}
+
+export interface RuntimeApiKeyModel {
+	provider: string;
+}
+
+export function applyCliRuntimeApiKeyOverride(
+	target: RuntimeApiKeyTarget,
+	apiKey: string | undefined,
+	model: RuntimeApiKeyModel | undefined,
+): void {
+	if (!apiKey || !model) return;
+	target.setRuntimeApiKey(model.provider, apiKey);
+}