@wahack/pi-coding-agent 15.11.0

package/src/prompts/tools/bash.md

@@ -0,0 +1,46 @@
+Executes bash command in shell session for terminal operations like git, bun, cargo, python.
+
+<instruction>
+- Use `cwd` to set working directory, not `cd dir && …`
+- Prefer `env: { NAME: "…" }` for multiline, quote-heavy, or untrusted values; reference as `$NAME`
+- Quote variable expansions like `"$NAME"` to preserve exact content
+- PTY mode is opt-in: set `pty: true` only when the command needs a real terminal (e.g. `sudo`, `ssh` requiring user input); default is `false`
+- Use `;` only when later commands should run regardless of earlier failures
+- Internal URIs (`skill://`, `agent://`, etc.) are auto-resolved to filesystem paths
+{{#if asyncEnabled}}
+- Use `async: true` for long-running commands when you don't need immediate output; the call returns a background job ID and the result is delivered automatically as a follow-up.
+{{/if}}
+</instruction>
+
+<critical>
+- NEVER use shell to fetch, display, list, page, or search content a dedicated tool serves: `cat`/`head`/`tail`/`less`/`more`/`ls` → `read`; `grep`/`rg`/`ag`/`ack` → `search`; `find`/`fd` → `find`; `sed -i`/`perl -i`/`awk -i` → `edit`; `echo >`/heredoc → `write`. The tools keep gitignore semantics, line anchors, and structured output that shell loses.
+- NEVER trim or silence output: no `| head -n N`, `| tail -n N`, `| less`, `2>&1`, `2>/dev/null`. stderr is already merged; long output is auto-truncated with the FULL capture kept at `artifact://<id>`. Defensive trimming is a habit from harnesses without artifact recovery — here it only destroys data the artifact would have saved.
+- Pipelines that COMPUTE a new fact are correct bash: `wc -l`, `sort | uniq -c`, `comm`, `cut`, `diff a b`, `shasum`. Litmus: produces a count, frequency table, set difference, or checksum no tool returns → bash. Merely moves or trims bytes a tool can fetch → use the tool.
+</critical>
+
+<output>
+- Returns output and exit code.
+- Truncated output is retrievable from `artifact://<id>` (linked in metadata)
+- Exit codes shown on non-zero exit
+</output>
+
+{{#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.
+- `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): pass an explicit large `timeout` (up to `3600`). The shell session persists across calls, so a backgrounded job (`cmd &`) keeps running between bash calls on its own.
+{{/if}}
+{{#if autoBackgroundEnabled}}
+
+## Auto-background
+
+- A foreground call still running after **{{autoBackgroundThresholdSeconds}}s** converts to a background job: you get a `Background job <id> started` notice plus the output so far, and the final result arrives as a follow-up tool call. The command keeps running — this is NOT a failure; do not retry it and do not wait synchronously.
+- Auto-backgrounding does NOT extend `timeout`: the job is still killed at the original deadline.
+- Need the result inline (e.g. piping into another command)? Raise `timeout` above the expected duration{{#if asyncEnabled}}, or set `async: true` up front{{/if}}.
+{{/if}}
+
+# Output minimizer
+
+- Long output is truncated and test/lint runner output is filtered down to failures. Whenever the visible text was changed, a `[raw output: artifact://<id>]` footer links the full capture — read it if a run looks suspicious or you need the exact bytes.
+- No footer = what you see is exactly what the command emitted.

package/src/prompts/tools/browser.md

@@ -0,0 +1,73 @@
+Drives real Chromium tab; full puppeteer access via JS execution.
+
+<instruction>
+- For static web content (articles, docs, issues/PRs, JSON, PDFs, feeds), prefer `read` tool with URL — reader-mode text without spinning up browser. Use this tool when you need JS execution, authentication, or interactive actions.
+- Three actions only:
+  - `open` — acquire or reuse named tab. `name` defaults `"main"`. Optional `url` navigates after tab ready. Optional `viewport` sets dimensions. Optional `dialogs: "accept" | "dismiss"` auto-handles `alert`/`confirm`/`beforeunload` so navigation/clicks don't hang; by default dialogs are unhandled and the page hangs until you wire `page.on('dialog', …)`.
+  - `close` — release tab by `name`, or every tab with `all: true`. For spawned-app browsers, set `kill: true` to terminate process tree (default leaves running).
+  - `run` — execute JS against existing tab. `code` is body of async function with `page`, `browser`, `tab`, `display`, `assert`, `wait` in scope. Function's return value JSON-stringified into 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 `app` field on `open`:
+  - default (no `app`) → headless Chromium with stealth patches.
+  - `app.path` → spawn absolute binary (Electron/CDP); a running instance with an open CDP port is reused. No stealth patches — NEVER tamper with real desktop app.
+  - `app.cdp_url` → connect to existing CDP endpoint (e.g. `http://127.0.0.1:9222`).
+  - `app.target` (with `path`/`cdp_url`) — substring matched against url+title to pick BrowserWindow when app exposes several.
+- Inside `run`, `tab` exposes high-level helpers; reach for `page` (raw puppeteer Page) when you need anything they don't cover.
+  - `tab.goto(url, { waitUntil? })` — clears element cache and navigates.
+  - `tab.observe({ includeAll?, viewportOnly? })` — accessibility snapshot. Returns `{ url, title, viewport, scroll, elements: [{ id, role, name, value, states, … }] }`. Element ids stable until next observe/goto.
+  - `tab.id(n)` — resolves element id from most recent observe to real `ElementHandle` you can `.click()`, `.type()`, etc.
+  - `tab.click(selector)` / `tab.type(selector, text)` / `tab.fill(selector, value)` / `tab.press(key, { selector? })` / `tab.scroll(dx, dy)` — selector-based actions.
+  - `tab.waitFor(selector)` — waits until selector attached, returns resolved `ElementHandle` for chaining (e.g. `const btn = await tab.waitFor('text/Submit'); await btn.click();`).
+  - `tab.drag(from, to)` — drag from one point to another. Each endpoint either selector string (drag center-to-center) or `{ x, y }` viewport-coordinate point (for canvases, sliders).
+  - `tab.scrollIntoView(selector)` — scroll matching element to center of viewport (use before clicking off-screen elements).
+  - `tab.select(selector, …values)` — set selected option(s) on `<select>`. Returns values that ended up selected. `tab.fill` NEVER works for selects.
+  - `tab.uploadFile(selector, …filePaths)` — attach files to `<input type="file">`. Paths resolve relative to cwd.
+  - `tab.waitForUrl(pattern, { timeout? })` — pattern substring or `RegExp`. Polls `location.href` so works for SPA pushState navigations, not just real navigations. Returns matched URL.
+  - `tab.waitForResponse(pattern, { timeout? })` — pattern substring, `RegExp`, or `(response) => boolean`. Returns raw puppeteer `HTTPResponse` (call `.text()` / `.json()` / `.status()` / `.headers()` on it).
+  - `tab.evaluate(fn, …args)` — sugar for `page.evaluate` with abort signal already wired. Use this instead of dropping to `page.evaluate` for ad-hoc DOM reads.
+  - `tab.screenshot({ selector?, fullPage?, save?, silent? })` — captures a screenshot and attaches it for you to view (`silent: true` skips attaching). Pass `save` (a path) only when a later step needs the file; never just to look.
+  - `tab.extract(format = "markdown")` — returns Readability-extracted page content as a string (`"markdown"` or `"text"`). Throws if the page yields no readable content.
+- Selectors accept CSS plus puppeteer query handlers: `aria/Sign in`, `text/Continue`, `xpath/…`, `pierce/…`. Playwright-style `p-aria/[name="…"]`, `p-text/…` normalized.
+- Default `tab.observe()` over `tab.screenshot()` for page state. Screenshot only when visual appearance matters.
+</instruction>
+
+<critical>
+- MUST call `open` before `run`. `run` does not implicitly create tab.
+- NEVER screenshot just to "see what's on page" — `tab.observe()` returns structured data with element ids you can act on immediately.
+- After `tab.goto()` or any navigation, prior element ids from `tab.observe()` invalidated. Re-observe before referencing them.
+- `code` runs with full Node access. Treat as your code, not sandboxed code.
+</critical>
+
+<examples>
+# Open a tab and read structured page data
+`{"action":"open","name":"docs","url":"https://example.com"}`
+`{"action":"run","name":"docs","code":"const obs = await tab.observe(); display(obs); return obs.elements.length;"}`
+
+# Click an observed element by id
+`{"action":"run","name":"docs","code":"const obs = await tab.observe(); const link = obs.elements.find(e => e.role === 'link' && e.name === 'Sign in'); assert(link, 'Sign in link missing'); await (await tab.id(link.id)).click();"}`
+
+# Screenshot to look at the page — no save path
+`{"action":"run","name":"docs","code":"await tab.screenshot();"}`
+
+# Keep a full-page screenshot on disk for a later step
+`{"action":"run","name":"docs","code":"await tab.screenshot({ fullPage: true, save: 'screenshot.png' });"}`
+
+# Fill and submit a form via selectors
+`{"action":"run","name":"docs","code":"await tab.fill('input[name=email]', 'me@example.com'); await tab.click('text/Continue');"}`
+
+# Attach to an existing Electron app
+`{"action":"open","name":"cursor","app":{"path":"/Applications/Cursor.app/Contents/MacOS/Cursor"}}`
+
+# Close one tab (browser stays alive if other tabs reference it)
+`{"action":"close","name":"docs"}`
+
+# Close every tab; leave spawned apps running
+`{"action":"close","all":true}`
+
+# Close every tab and kill spawned-app processes too
+`{"action":"close","all":true,"kill":true}`
+</examples>
+
+<output>
+- Per call: any `display(value)` outputs (text/images) followed by JSON-stringified return value of `code` function. `run` always produces at least status line.
+</output>

package/src/prompts/tools/checkpoint.md

@@ -0,0 +1,16 @@
+Creates a context checkpoint before exploratory work so you can later rewind and keep only a concise report.
+
+Use this when you need to investigate with many intermediate tool calls (read/search/find/lsp/etc.) and want to minimize context cost afterward.
+
+Rules:
+- You MUST call `rewind` before yielding after starting a checkpoint.
+- You MUST provide a clear `goal` explaining what you are investigating.
+- You NEVER call `checkpoint` while another checkpoint is active.
+- Not available in subagents.
+
+Typical flow:
+1. `checkpoint(goal: …)`
+2. Perform exploratory work
+3. `rewind(report: …)` with concise findings
+
+After rewind, intermediate checkpoint messages are removed from active context and replaced by the report.

package/src/prompts/tools/debug.md

@@ -0,0 +1,34 @@
+Provides debugger access through the Debug Adapter Protocol (DAP).
+Use for launching or attaching debuggers, setting breakpoints, stepping through execution, inspecting threads/stack/variables, evaluating expressions, capturing output, and interrupting hung programs.
+
+<instruction>
+- You SHOULD prefer this tool over bash for program state, breakpoints, stepping, thread inspection, or interrupting a running process.
+- `action: "launch"` starts a session; `program` is required, `adapter` optional (auto-selected from target path and workspace).
+  For Python, set `adapter: "debugpy"` and `program` to the target `.py` file; put interpreter/script flags in `args`.
+- `action: "attach"` connects to an existing process: `pid` for local attach, `port` for remote attach (where the adapter supports it), `adapter` to force a specific debugger.
+- **Breakpoints**: `set_breakpoint`/`remove_breakpoint` with source (`file`+`line`) or function (`function`); optional `condition` for conditional breakpoints.
+- **Flow control**: `continue` (resumes; briefly waits to observe whether the program stops or keeps running), `step_over`/`step_in`/`step_out` (single-step), `pause` (interrupt a running program so you can inspect state).
+- **Inspect**: `threads` (list), `stack_trace` (frames for current stopped thread), `scopes` (needs `frame_id` or a current stopped frame), `variables` (needs `variable_ref` or `scope_id`), `evaluate` (needs `expression`; `context: "repl"` for raw debugger commands when the adapter supports them), `output` (captured stdout/stderr/console), `sessions` (tracked debug sessions), `terminate`.
+- Timeouts apply per-request, not to the full session lifetime.
+</instruction>
+
+<caution>
+- Only one active debug session is supported at a time.
+- Some adapters require a launched session to receive `configurationDone` before the target actually runs; if the tool says configuration is pending, set breakpoints and then call `continue`.
+- Adapter availability depends on local binaries. Common built-ins: `gdb`, `lldb-dap`, `python -m debugpy.adapter`, `dlv dap`.
+- `program` must be an executable file or debug target, not a directory or interpreter name that resolves to a workspace directory.
+- Python debugging requires `debugpy`; install with `pip install debugpy` if the adapter is unavailable.
+</caution>
+
+<examples>
+# Launch and inspect hang
+1. `debug(action: "launch", program: "./my_app")`
+2. `debug(action: "set_breakpoint", file: "src/main.c", line: 42)`
+3. `debug(action: "continue")`
+4. If the program appears hung: `debug(action: "pause")`
+5. Inspect state with `threads`, `stack_trace`, `scopes`, and `variables`
+# Launch a Python script with debugpy
+`debug(action: "launch", adapter: "debugpy", program: "scripts/job.py", args: ["--flag"])`
+# Raw debugger command through repl
+`debug(action: "evaluate", expression: "info registers", context: "repl")`
+</examples>

package/src/prompts/tools/eval.md

@@ -0,0 +1,92 @@
+Run code in a persistent kernel using a list of cells.
+
+<instruction>
+Each call submits one or more cells. Cells run in array order. State persists within each language — across cells, tool calls, and subagents spawned with `task`: variables a parent or subagent declares are visible to the other. Lean on this: stage helpers, loaded datasets, or live clients once, then fan out `task` subagents that use them directly. No re-importing, re-fetching, or serializing across the boundary.
+
+Cell fields:
+
+- `language` — {{#if py}}`"py"` for the IPython kernel{{/if}}{{#ifAll py js}}, {{/ifAll}}{{#if js}}`"js"` for the persistent JavaScript VM{{/if}}.
+- `code` — cell body, verbatim. Newlines, quotes, and indentation are JSON-encoded; no fences, no headers.
+- `title` (optional) — short label shown in the transcript (e.g. `"imports"`, `"load config"`).
+- `timeout` (optional) — per-cell wall-clock budget in seconds (1-3600). Default 30. It bounds the cell's **own** work: compute, `print`/stdout, `log()`/`phase()`, and ordinary tool calls all count. The clock pauses while an `agent()`/`parallel()`/`completion()` call is in flight, so long fanouts and slow completions never need a raised `timeout`. Raise it only for heavy local work or long non-agent tool calls.
+- `reset` (optional) — wipe this cell's language kernel before running.{{#ifAll py js}} Reset is per-language: a `py` cell's reset does not touch the JavaScript VM and vice versa.{{/ifAll}}
+
+**Work incrementally:**
+
+- One logical step per cell (imports, define, test, use).
+- Pass multiple small cells in one call.
+- Define small reusable functions for individual debugging.
+- Put workflow explanations in the assistant message or `title` — never inside cell code.
+{{#if py}}- Python cells run inside an IPython kernel with a live event loop. Use top-level `await` directly (e.g. `await main()`); `asyncio.run(…)` raises "cannot be called from a running event loop".{{/if}}
+**On failure:** errors identify the failing cell (e.g., "Cell 3 failed"). Resubmit only the fixed cell (or fixed cell + remaining cells).
+</instruction>
+
+<prelude>
+{{#ifAll py js}}Same helpers in both runtimes with the same positional argument order. Python: trailing options as keyword args. JavaScript: trailing options are a single trailing object literal, never positional — passing options positionally (or any extra positional arg) throws. JavaScript helpers are async and `await`able; Python helpers run synchronously.{{else}}{{#if py}}Helpers run synchronously. Trailing options are keyword arguments.{{/if}}{{#if js}}Helpers are async and `await`able. Trailing options are a single trailing object literal, never positional — passing options positionally (or any extra positional arg) throws.{{/if}}{{/ifAll}}
+```
+display(value) → None
+    Render a value in the current cell output.
+print(value, ...) → None
+    Print to the cell's text output.
+read(path, offset?=1, limit?=None) → str
+    Read file contents as text. offset/limit are 1-indexed line bounds. Accepts `local://…` (resolved to the session-local root, same place `read local://…` reads).
+write(path, content) → str
+    Write content to a file (creates parent directories). Returns the resolved path. Accepts `local://…` to persist artifacts across turns / share with subagents.
+append(path, content) → str
+    Append content to a file. Returns the resolved path. Accepts `local://…`.
+tree(path?=".", max_depth?=3, show_hidden?=False) → str
+    Render a directory tree.
+diff(a, b) → str
+    Unified diff between two files.
+env(key?=None, value?=None) → str | None | dict
+    No args → full environment as dict. One arg → value of `key`. Two args → set `key=value` and return value.
+output(*ids, format?="raw", query?=None, offset?=None, limit?=None) → str | dict | list[dict]
+    Read task/agent output by ID. Single id returns text/dict; multiple ids return a list.
+tool.<name>(args) → unknown
+    Invoke any session tool by name. `args` is the tool's parameter object.
+completion(prompt, model?="default", system?=None, schema?=None) → str | dict
+    Oneshot, stateless completion (no history, no tools). `model` picks a tier: "smol" (fast), "default" (this session's model), "slow" (most capable). Pass `system` for a system prompt. Pass a JSON-Schema `schema` to force structured output and get the parsed object back; otherwise returns the completion text.
+{{#if spawns}}agent(prompt, agent_type?="task", model?=None, label?=None, schema?=None) → str | dict
+    Run a subagent and return its final output. Defaults to the bundled "task" agent; pass `agent_type`/`agentType` for another discovered agent. Pass a JSON-Schema `schema` to force structured output and get the parsed object back. Share background by writing a `local://` file and referencing it in the prompt.
+{{#if js}}    In JS, pass options as one trailing object — never positional: agent(prompt, { agentType, schema }).
+{{/if}}
+{{/if}}
+parallel(thunks) → list
+    Run thunks (callables) through a bounded pool, preserving input order. The pool is as wide as a `task` tool batch, so fan out as wide as the work divides — don't pre-shrink it. Barrier: returns once all finish; a thunk that throws propagates.
+pipeline(items, ...stages) → list
+    Map each item through stages left-to-right; a barrier runs between stages (every item clears stage N before stage N+1). Each stage is a one-arg callable: stage 1 gets the original item, later stages get the previous result. Same pool width as parallel().
+log(message) → None
+    Emit a progress line above the status tree.
+phase(title) → None
+    Start a phase; the status lines that follow group under it.
+budget → per-turn token budget
+    {{#if py}}`budget.total` (ceiling or None), `budget.spent()` (output tokens this turn), `budget.remaining()` (math.inf when no ceiling), `budget.hard` (bool).{{/if}}{{#if js}}`await budget.total()` (ceiling or null), `await budget.spent()`, `await budget.remaining()` (Infinity when no ceiling), `await budget.hard()`.{{/if}} A ceiling is set by a `+Nk` message directive (advisory) or `+Nk!`/Goal Mode (hard — `agent()` refuses to spawn past it); otherwise total is None/null and spend is still tracked across the turn (main loop + eval subagents).
+```
+</prelude>
+
+<output>
+Cells render like a Jupyter notebook. `display(value)` renders non-presentable data as an interactive JSON tree. Presentable values (figures, images, dataframes, etc.) use their native representation.
+</output>
+
+<caution>
+{{#if js}}- **js**: the VM exposes a selective `process` subset, Web APIs, `Buffer`, `fs/promises`, and the `Bun` global.
+{{/if}}</caution>
+
+<example>
+{{#if py}}```json
+{
+  "cells": [
+    { "language": "py", "title": "imports", "timeout": 10, "code": "import json\nfrom pathlib import Path" },
+    { "language": "py", "title": "load config", "code": "data = json.loads(read('package.json'))\ndisplay(data)" }
+  ]
+}
+```{{/if}}{{#ifAll py js}}
+
+{{/ifAll}}{{#if js}}```json
+{
+  "cells": [
+    { "language": "js", "title": "summary", "reset": true, "code": "const data = JSON.parse(await read('package.json'));\ndisplay(data);\nreturn data.name;" }
+  ]
+}
+```{{/if}}
+</example>

package/src/prompts/tools/find.md

@@ -0,0 +1,36 @@
+Finds files and directories using fast pattern matching that works with any codebase size.
+
+<instruction>
+- `paths` is required and accepts an array of globs, files, or directories
+- Pass multiple targets as **separate array elements** (`paths: ["a", "b"]`).
+- `gitignore` defaults to `true` and hides files matched by `.gitignore`. Set `gitignore: false` to find `.env*`, `*.log`, freshly-created build outputs, or anything else your repo ignores
+- `hidden` defaults to `true`; combine with `gitignore: false` to surface dotfiles that are also gitignored
+- `limit` is clamped to 1-200 (default 200). Narrow the pattern instead of raising the limit
+- `timeout` is in seconds (default 5, clamped to 0.5–60). On timeout, find returns whatever partial matches it has collected with `truncated: true` and a notice — increase `timeout` or narrow the pattern instead of retrying blindly
+- You SHOULD perform multiple searches in parallel when potentially useful
+</instruction>
+
+<output>
+Matching file and directory paths sorted by modification time (most recent first), grouped by directory to reduce token usage. Each group starts with `# <dir>/` followed by basenames (one per line); directory entries get a trailing `/`. Root-level entries have no header. Truncated at 200 entries or 50KB.
+</output>
+
+<examples>
+# Find files
+`{"paths": ["src/**/*.ts"]}`
+# Multiple targets — separate array elements
+`{"paths": ["src/**/*.ts", "test/**/*.ts"]}`
+# Find gitignored files like .env
+`{"paths": [".env*"], "gitignore": false}`
+# Find directories matching a name (returns both files and dirs; directories are suffixed with `/`)
+`{"paths": ["**/tests"]}`
+# Long-running search on a slow volume
+`{"paths": ["/Volumes/Storage/**/*.py"], "timeout": 30}`
+</examples>
+
+<avoid>
+For open-ended searches requiring multiple rounds of globbing and searching, you MUST use Task tool instead.
+</avoid>
+
+<critical>
+- You MUST use the built-in Find tool for every file-name lookup. NEVER shell out to `find`, `fd`, `locate`, `ls`, or `git ls-files` via Bash — they ignore `.gitignore`, blow past result limits, and waste tokens.
+</critical>

package/src/prompts/tools/github.md

@@ -0,0 +1,21 @@
+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:
+- `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`. 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`.
+- `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. 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`).
+- All `search_*` ops except `search_repos` default `repo` to the current checkout's `owner/repo` when omitted; pass an explicit `repo:`/`org:`/`user:` qualifier in `query` to search outside it.
+- 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). Fast-fails on the first job failure and returns tailed logs for the failed jobs.
+</instruction>
+
+<output>
+Returns a concise readable summary tailored to the chosen op (repo metadata, PR metadata, diff text, search results, checkout info, push target, or workflow run snapshot). For `run_watch`, the full failed-job logs are saved as a session artifact when failures occur.
+</output>

package/src/prompts/tools/goal.md

@@ -0,0 +1,18 @@
+Manage the active goal-mode objective.
+
+Use a single `op` field:
+- `create` starts a goal. Requires `objective`; optional `token_budget` must be positive. Use only when no goal exists and no goal is paused.
+- `get` returns the current goal (active or paused) and remaining token budget.
+- `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.
+
+Examples:
+- `goal({"op":"create","objective":"Implement feature X","token_budget":50000})`
+- `goal({"op":"get"})`
+- `goal({"op":"resume"})`
+- `goal({"op":"complete"})`
+- `goal({"op":"drop"})`
+
+NEVER call `complete` because a budget is low or a turn is ending. Call it only when the goal is actually done and verified.
+If `get` shows a paused goal, call `resume` before continuing work on it.

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

@@ -0,0 +1,7 @@
+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>

package/src/prompts/tools/inspect-image-system.md

@@ -0,0 +1,20 @@
+You are an image-analysis assistant.
+
+Core behavior:
+- Be evidence-first: distinguish direct observations from inferences.
+- If something is unclear, say uncertain rather than guessing.
+- NEVER fabricate unreadable or occluded details.
+- Keep output compact and useful.
+
+Default output format (unless the requested question asks for another format):
+1) Answer
+2) Key evidence
+3) Caveats / uncertainty
+
+For OCR-style requests:
+- Preserve exact visible text, including casing and punctuation.
+- If text is partially unreadable, mark the unreadable segments explicitly.
+
+For UI/screenshot debugging requests:
+- Focus on visible states, labels, toggles, error messages, disabled controls, and relevant affordances.
+- Separate observed UI state from probable root cause.

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

@@ -0,0 +1,32 @@
+Inspects an image file with a vision-capable model and returns compact text analysis.
+
+<instruction>
+- Use this for image understanding tasks (OCR, UI/screenshot debugging, scene/object questions)
+- Provide `path` to the local image file
+- Write a specific `question`:
+  - what to inspect
+  - constraints (for example: "quote visible text verbatim", "only report confirmed findings")
+  - desired output format (bullets/table/JSON/short answer)
+- Keep `question` grounded in observable evidence and ask for uncertainty when details are unclear
+- Use this tool over `read` when the goal is image analysis
+</instruction>
+
+<examples>
+# OCR with strict formatting
+`{"path":"screenshots/error.png","question":"Extract all visible text verbatim. Return as bullet list in reading order."}`
+# Screenshot debugging
+`{"path":"screenshots/settings.png","question":"Identify the likely cause of the disabled Save button. Return: (1) observations, (2) likely cause, (3) confidence."}`
+# Scene/object question
+`{"path":"photos/shelf.jpg","question":"List all clearly visible product labels and their shelf positions (top/middle/bottom). If unreadable, say unreadable."}`
+</examples>
+
+<output>
+- Returns text-only analysis from the vision model
+- No image content blocks are returned in tool output
+</output>
+
+<critical>
+- Parameters are strict: only `path` and `question` are allowed
+- If image submission is blocked by settings, the tool will fail with an actionable error
+- If configured model does not support image input, configure a vision-capable model role before retrying
+</critical>

package/src/prompts/tools/irc.md

@@ -0,0 +1,59 @@
+Sends short text messages to other agents in this process and receives theirs.
+
+<instruction>
+- The main agent is addressable as `Main`. Subagents reuse their task id (e.g. `AuthLoader`, or `AuthLoader-2` when the name repeats).
+- `op: "list"` — every addressable peer with status (`running` | `idle` | `parked`), unread count, parent, and last activity. Use it before sending if you are not sure who exists.
+- `op: "send"` — fire-and-forget delivery of `message` to `to` (a peer id, or `"all"` to broadcast to live peers). Returns per-recipient receipts immediately; it NEVER waits for the recipient to act. Receipt outcomes: `injected` (recipient was mid-turn; message folded in at their next step boundary), `woken` (idle recipient started a turn), `revived` (parked recipient was brought back and woken), `failed`.
+- Messaging an `idle` or `parked` peer is how you wake it — there is no separate revive call.
+- `send` with `await: true` — convenience round-trip: send, then block until the next message from that peer arrives (or the timeout passes). Invalid with `to: "all"`.
+- `op: "wait"` — block until a message arrives (optionally only `from` a specific peer); consumes and returns it. A timeout is a clean "no message" result, not an error.
+- `op: "inbox"` — drain pending messages without blocking (`peek: true` to leave them unread).
+- `replyTo` — set it to the id of the message you are answering so the sender can correlate.
+- Nobody answers on a peer's behalf anymore: a reply only arrives when the recipient actually sends one. For background on what a peer has been doing, `read` `history://<id>` instead of interrogating them.
+</instruction>
+
+<when_to_use>
+You SHOULD reach for `irc` proactively when continuing alone is wasteful or wrong. When in doubt, prefer messaging.
+- **Unexpected state.** The task did not describe what you found — missing file, config contradicting the assignment, API or tool behaving differently than told. DM `Main` (or the spawning agent) instead of guessing.
+- **Blocked by another agent.** A peer holds the file/branch/resource you need, 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 work.
+- **Decision points outside your scope.** A genuine fork the assignment did not pre-decide (e.g. which of two viable APIs, whether to refactor adjacent code). Ask the requester rather than picking unilaterally.
+- **Coordination opportunities.** A peer's in-flight work would benefit from yours, or vice-versa.
+
+NEVER use `irc` for: routine progress updates, things a tool call can verify, or questions already answered by your assignment / repo / docs.
+</when_to_use>
+
+<etiquette>
+These rules apply to both sending and replying.
+- **Plain prose only.** NEVER 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."
+- **NEVER quote the message you are replying to.** Lead with the answer; set `replyTo` instead.
+- **Use IRC, not terminal tools, to learn about peers.** NEVER `grep` artifacts, read other sessions' JSONL files, or shell-poke to figure out what another agent is doing. DM them, or `read` `history://<id>`.
+- **Send, then keep working.** `send` returns immediately — only `wait` (or `await: true`) when you genuinely cannot proceed without the answer. NEVER follow up with "did you get my message?"; a `failed` receipt means the peer is unreachable — move on or report the blocker; NEVER retry in a loop.
+- **Answer when a response is expected.** When an incoming message asks something, reply with `irc send` to the sender (you may finish your current step first).
+- **Stay terse.** A DM is a chat message, not a memo. One question per send. Share file paths and artifacts via `local://` / `memory://` / `artifact://` URLs instead of pasting blobs.
+- **Address peers by id.** Use the exact id from `op: "list"` (e.g. `AuthLoader`, `Main`). NEVER invent friendly names.
+- **NEVER IRC for things a tool would answer.** If a `read`, `grep`, or build command resolves the question, do that first.
+</etiquette>
+
+<output>
+- `send`: per-recipient delivery receipts (`injected` / `woken` / `revived` / `failed`); with `await: true`, also the reply (or a timeout notice).
+- `wait`: the consumed message, or a clean timeout notice.
+- `inbox`: pending messages, oldest first.
+- `list`: peers with status, unread count, parent, and last activity.
+</output>
+
+<examples>
+# List peers
+`{"op": "list"}`
+# Fire-and-forget DM — keep working, check inbox later
+`{"op": "send", "to": "AuthLoader", "message": "Are you still touching src/server/auth.ts? I need to add a 401 path."}`
+# Round-trip when you cannot proceed without the answer
+`{"op": "send", "to": "Main", "message": "Should I prefer JWT or session cookies for the auth flow?", "await": true}`
+# Wake a parked agent (same send — the bus revives it)
+`{"op": "send", "to": "SchemaMigrator", "message": "The users table changed again; please re-check your migration."}`
+# Block until a specific peer answers
+`{"op": "wait", "from": "AuthLoader", "timeoutMs": 60000}`
+# Drain pending messages
+`{"op": "inbox"}`
+# Broadcast to live peers (no replies expected)
+`{"op": "send", "to": "all", "message": "About to refactor src/server/middleware/*. Anyone already in there?"}`
+</examples>

package/src/prompts/tools/job.md

@@ -0,0 +1,19 @@
+Inspects, waits, or cancels async jobs.
+
+Background job results are delivered automatically when complete. Reach for this tool only when you need to intervene.
+
+# Operations
+
+## `list: true`
+Use to inspect what's running.
+
+## `poll: [id, …]`
+Block until the specified jobs finish or the wait window 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.
+
+## `cancel: [id, …]`
+Stop running jobs.
+- Use when a job is stalled, hung, or no longer needed.
+- Returns immediately after cancelling.

package/src/prompts/tools/lsp-late-diagnostic.md

@@ -0,0 +1,8 @@
+<system-notice>
+{{#if multiple}}Late LSP diagnostics arrived for {{files.length}} files after their edits returned:
+{{else}}Late LSP diagnostics arrived after the edit returned:
+{{/if}}
+{{#each files}}{{this.path}} — {{this.summary}}
+{{#each this.messages}}{{this}}
+{{/each}}{{#unless @last}}
+{{/unless}}{{/each}}</system-notice>

package/src/prompts/tools/lsp.md

@@ -0,0 +1,42 @@
+Interacts with Language Server Protocol servers for code intelligence.
+
+<operations>
+- `diagnostics`: Get errors/warnings for a file, a glob of files, or the entire workspace (`file: "*"`)
+- `definition`: Go to symbol definition → file path + position + 3-line source context
+- `type_definition`: Go to symbol type definition → file path + position + 3-line source context
+- `implementation`: Find concrete implementations → file path + position + 3-line source context
+- `references`: Find references → locations with 3-line source context (first 50), remaining location-only
+- `hover`: Get type info and documentation → type signature + docs
+- `symbols`: List symbols in a file, or search workspace with `file: "*"` and a `query`
+- `rename`: Rename symbol across codebase → preview or apply edits
+- `rename_file`: Rename or move a file/directory; sends `workspace/willRenameFiles` so LSP servers update import paths and other references → preview or apply edits + filesystem rename
+- `code_actions`: List available quick-fixes/refactors/import actions; apply one when `apply: true` and `query` matches title or index
+- `status`: Show active language servers
+- `capabilities`: Dump per-server capabilities (standard + experimental + executeCommand list) for discovery — file scopes to one server, omitted/`"*"` lists every active server
+- `request`: Send a raw LSP request to a server — `query` is the method name (e.g., `rust-analyzer/expandMacro`, `typescript/goToSourceDefinition`, `workspace/executeCommand`); use `payload` for arbitrary JSON params or let the tool auto-build them from `file`/`line`/`symbol`
+- `reload`: Restart a specific server (via `file`) or all servers with `file: "*"`
+</operations>
+
+<parameters>
+- `file`: File path, glob pattern (e.g. `src/**/*.ts`), or `"*"` for workspace scope. Globs are expanded locally before dispatch. `"*"` routes `diagnostics`/`symbols`/`reload` to their workspace-wide form.
+- `line`: 1-indexed line number for position-based actions
+- `symbol`: Substring on the target line used to resolve column automatically. Append `#N` to pick the Nth occurrence on that line (1-indexed; default 1) — e.g. `foo#2` selects the second `foo`.
+- `query`: Symbol search query, code-action kind filter / selector (list/apply mode), or LSP method name when `action: request`
+- `new_name`: Required for `rename` (new symbol identifier) and `rename_file` (destination path)
+- `apply`: Apply edits for rename/rename_file/code_actions (default true for rename and rename_file; list mode for code_actions unless explicitly true)
+- `payload`: JSON-encoded params for `action: request`. Overrides the auto-built `{ textDocument, position }` shape when present.
+- `timeout`: Request timeout in seconds (clamped to 5-60, default 20)
+</parameters>
+
+<caution>
+- Requires running LSP server for target language
+- Some operations require file to be saved to disk
+- Glob expansion samples up to 20 files per request; use `file: "*"` for broader coverage
+- When `symbol` is provided for position-based actions, missing symbols or out-of-bounds `#N` occurrence selectors return an explicit error instead of silently falling back
+</caution>
+
+<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`, or manual edits when `lsp` `rename` can do it. Text-based renames miss shadowing, re-exports, and usages in other files.
+- You SHOULD use `lsp` `code_actions` for imports, quick-fixes, and refactors the language server already knows how to apply.
+</critical>

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

@@ -0,0 +1,8 @@
+Edit Mnemopi long-term memories by id.
+
+Use only with ids returned by the `recall` tool. Operations:
+- `update`: replace content and/or importance for a working memory.
+- `forget`: permanently delete a working memory.
+- `invalidate`: softly supersede a working or episodic memory, optionally pointing at `replacement_id`.
+
+Prefer `invalidate` when a memory became stale but its history may still be useful. Use `forget` only for content that should be hard-deleted.