@gajae-code/coding-agent 0.1.1

package/src/prompts/tools/hashline.md

@@ -0,0 +1,130 @@
+Your patch language is a compact, line-anchored edit format.
+
+A patch contains one or more file sections. The first non-blank line of every edit section MUST be `§PATH`.
+Operations reference lines in the file by their line number and hash, called "Anchors", e.g. `5th`, `123ab`.
+You MUST copy them verbatim from the latest output for the file you're editing.
+
+Purely textual format. The tool has NO awareness of language, indentation, brackets, fences, or table widths. You MUST emit valid syntax in replacements/insertions.
+
+<ops>
+§PATH           header: subsequent ops apply to PATH
+Each op line is ONE of:
+»ANCHOR         insert lines AFTER  the anchored line (or EOF); payload follows on subsequent lines
+«ANCHOR         insert lines BEFORE the anchored line (or BOF); payload follows on subsequent lines
+≔A..B           replace the inclusive range A..B with payload; delete the range if no payload follows
+≔A              shorthand for ≔A..A
+</ops>
+
+<rules>
+- Payload text is verbatim — NEVER escape unicode.
+- Payload ends at the next `»`, `«`, `≔`, `§`, envelope marker, or EOF.
+- `≔A..B` with no payload deletes the range. To keep a blank line, include one explicit empty payload line.
+- **Payload is only what's NEW relative to your range:**
+  - `≔` replaces inside; NEVER include lines outside.
+  - `»`/`«` adds at the anchor; NEVER repeat line A or neighbors.
+  - Payload matching nearby content duplicates — drop it or widen.
+- **Pick a self-contained unit first.** Touching a multiline construct? Widen to the whole thing.
+- Then smallest op: add → `»`/`«`; delete/replace → `≔`.
+</rules>
+
+<brace-shapes>
+When braces bound your edit, you SHOULD prefer these shapes:
+- **Whole block**: range spans `{` through matching `}`.
+- **Signature only**: one-line `≔` on the opener; body untouched.
+- **Insert inside**: anchor on `{` or last interior line; NEVER repeat the braces.
+- **End on `}`**: only when that `}` is part of the change. Otherwise extend or stop earlier.
+</brace-shapes>
+
+<common-failures>
+- **NEVER replay past your range.** Stop before B+1; extend B if it must go.
+- **NEVER duplicate chunks inside one payload.** Caught re-emitting? Rewrite.
+- **Anchor only inside the visible region.** B+1 truncated? Re-`read` first.
+- **You SHOULD prefer the narrowest self-contained edit.** Narrow range beats wide range.
+- **Anchors reference the file as last read.** NEVER shift for prior ops.
+- **One `»`/`«` op per block, NOT per line.** N lines = ONE op, N payloads. Collapse adjacent ops.
+- **NEVER fabricate anchor hashes.** Missing? Re-`read`.
+</common-failures>
+
+<case file="mod.ts">
+{{hline 1 "const TITLE = \"Mr\";"}}
+{{hline 2 "export function greet(name) {"}}
+{{hline 3 "\treturn ["}}
+{{hline 4 "\t\tTITLE,"}}
+{{hline 5 "\t\tname?.trim() || \"guest\","}}
+{{hline 6 "\t].join(\" \");"}}
+{{hline 7 "}"}}
+</case>
+
+<examples>
+# Replace one line (the payload must re-emit the original indentation)
+§mod.ts
+≔{{hrefr 1}}
+const TITLE = "Mrs";
+
+# Replace a full multiline statement (widen to a self-contained boundary)
+§mod.ts
+≔{{hrefr 3}}..{{hrefr 6}}
+	return [
+		"Mrs",
+		name?.trim() || "guest",
+	].join(" ");
+
+# Insert AFTER/BEFORE a line
+§mod.ts
+»{{hrefr 4}}
+		"Dr",
+«{{hrefr 5}}
+		"Dr",
+
+# Append to file
+§mod.ts
+»EOF
+export const done = true;
+
+# Delete a line
+§mod.ts
+≔{{hrefr 5}}
+
+# Blank a line (replace with LF: the empty payload is the blank line before `»EOF`)
+§mod.ts
+≔{{hrefr 5}}
+
+»EOF
+export const done = true;
+</examples>
+
+<anti-pattern>
+# WRONG — replaces 2 lines just to add one.
+§mod.ts
+≔{{hrefr 1}}..{{hrefr 2}}
+const TITLE = "Mr";
+const DEBUG = false;
+export function greet(name) {
+# RIGHT — same effect, one-line insert
+§mod.ts
+»{{hrefr 1}}
+const DEBUG = false;
+
+# WRONG — replace from the middle of a larger statement (error-prone)
+§mod.ts
+≔{{hrefr 4}}..{{hrefr 5}}
+		"Dr",
+		name?.trim() || "guest",
+# RIGHT — widen to the full statement
+§mod.ts
+≔{{hrefr 3}}..{{hrefr 6}}
+	return [
+		"Dr",
+		name?.trim() || "guest",
+	].join(" ");
+</anti-pattern>
+
+<critical>
+- Copy anchors verbatim (line number + 2-char hash); NEVER include the `|TEXT` body.
+- NEVER write unified diff syntax. Headers are `§PATH`; ops are `»`/`«`/`≔`.
+- `≔A..B` deletes the range when no payload follows. To keep a blank line, include one explicit empty payload line.
+- `≔A..B` with payload writes exactly that payload. Edge line matches just outside? Widen, or it duplicates.
+- Multiple ops are cheap. SHOULD prefer two narrow ops over one wide `≔`.
+  - Before `≔A..B`, mentally delete A..B. Splits an unclosed bracket/brace/string from above, or orphans a closer inside? You're bisecting a construct.
+- NEVER use this tool to reformat code (indentation, whitespace, line wrapping, style). Run the project's formatter instead.
+</critical>

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.
+- Do not 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,49 @@
+Sends short text messages to other live agents in this process and receives their prose replies.
+
+<instruction>
+- 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.
+- 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>
+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.
+- **Decision points outside your scope.** A genuine fork in the road that the assignment did not pre-decide (e.g. which of two viable APIs to use, whether to refactor adjacent code). Ask the requester rather than picking unilaterally.
+- **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>
+
+<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.
+- **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://` / `memory://` / `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.
+- **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>
+
+<output>
+- `send`: returns each recipient that received the message and any prose replies that arrived.
+- `list`: returns peers and channels visible to the caller.
+</output>
+
+<examples>
+# List peers
+`{"op": "list"}`
+# Direct message to the main agent (waits for prose reply)
+`{"op": "send", "to": "0-Main", "message": "Should I prefer JWT or session cookies for the auth flow?"}`
+# Unexpected state — ask the originator
+`{"op": "send", "to": "0-Main", "message": "Assignment says edit src/auth/jwt.ts but the file does not exist. Is the new path src/server/auth/jwt.ts?"}`
+# Blocked by a peer — ask them directly
+`{"op": "send", "to": "0-AuthLoader", "message": "Are you still touching src/server/auth.ts? I need to add a 401 path; OK to proceed or should I wait?"}`
+# Broadcast to discover who owns something (no replies, just informs them)
+`{"op": "send", "to": "all", "message": "About to refactor src/server/middleware/*. Anyone already in there?", "awaitReply": false}`
+</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.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`, `rsed`, 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/patch.md

@@ -0,0 +1,70 @@
+Patches files given diff hunks. Primary tool for existing-file edits.
+
+<instruction>
+**Hunk Headers:**
+- `@@` — 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:
+   - full function signature
+   - class declaration
+   - unique string literal/error message
+   - config key with uncommon name
+2. On "Found multiple matches": add context lines, use multiple hunks with separate anchors, or use longer anchor substring
+**Context Lines:**
+Use enough ` `-prefixed lines to make match unique (usually 2–8)
+When editing structured blocks (nested braces, tags, indented regions), include opening and closing lines so edit stays inside block
+</instruction>
+
+<parameters>
+```ts
+// Input is { path: string, edits: Entry[] }. `path` is required and applies to every entry.
+type Entry =
+   // Diff is one or more hunks for the top-level path.
+   // - Each hunk begins with "@@" (anchor optional).
+   // - Each hunk body only has lines starting with ' ' | '+' | '-'.
+   // - Each hunk includes at least one change (+ or -).
+   | { op: "update", diff: string }
+   // Diff is full file content, no prefixes.
+   | { op: "create", diff: string }
+   // No diff for delete.
+   | { op: "delete" }
+   // New path for update+move from the top-level path.
+   | { op: "update", rename: string, diff: string }
+```
+</parameters>
+
+<output>
+Returns success/failure; on failure, error message indicates:
+- "Found multiple matches" — anchor/context not unique enough
+- "No match found" — context lines don't exist in file (wrong content or stale read)
+- Syntax errors in diff format
+</output>
+
+<critical>
+- You MUST read the target file before editing
+- You MUST copy anchors and context lines verbatim (including whitespace)
+- 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.
+</critical>
+
+<examples>
+# Create
+`edit {"path":"hello.txt","edits":[{"op":"create","diff":"Hello\n"}]}`
+# Update
+`edit {"path":"src/app.py","edits":[{"op":"update","diff":"@@ def greet():\n def greet():\n-print('Hi')\n+print('Hello')\n"}]}`
+# Rename
+`edit {"path":"src/app.py","edits":[{"op":"update","rename":"src/main.py","diff":"@@\n …\n"}]}`
+# Delete
+`edit {"path":"obsolete.txt","edits":[{"op":"delete"}]}`
+# Multiple entries
+All entries in one call apply to the top-level `path`; use separate calls for different files.
+</examples>
+
+<avoid>
+- Generic anchors: `import`, `export`, `describe`, `function`, `const`
+- Repeating same addition in multiple hunks (duplicate blocks)
+- Full-file overwrites for minor changes (acceptable for major restructures or short files)
+</avoid>

package/src/prompts/tools/read.md

@@ -0,0 +1,82 @@
+Read files, directories, archives, SQLite databases, images, documents, internal resources, and web URLs through a single `path` string.
+
+<instruction>
+- One tool for filesystem, archives, SQLite, images, documents (PDF/DOCX/PPTX/XLSX/RTF/EPUB/ipynb), internal URIs, and web URLs (reader-mode by default).
+- You SHOULD parallelize independent reads when exploring related files.
+- You SHOULD reach for `read` — not a browser/puppeteer tool — for fetching web content.
+</instruction>
+
+## Parameters
+
+- `path` — required. Local path, internal URI (`agent://`, `artifact://`, `memory://`, `rule://`, `local://`), or URL. Append `:<sel>` for line ranges, raw mode, or special modes (e.g. `src/foo.ts:50-200`, `src/foo.ts:raw`, `db.sqlite:users:42`).
+
+## Selectors
+
+Append `:<sel>` to `path`. The bare path falls back to the default mode.
+
+- _(none)_ — parseable code → structural summary (signatures kept, bodies elided); other files → read from the start (up to {{DEFAULT_LIMIT}} lines).
+- `:50` / `:50-` — read from line 50 onward.
+- `:50-200` — lines 50–200 inclusive.
+- `:50+150` — 150 lines starting at line 50.
+- `:20+1` — exactly one line.
+- `:5-16,960-973` — multiple ranges in one call (sorted, overlaps merged).
+- `:raw` — verbatim text; no anchors, no summary, no line prefixes.
+- `:2-4:raw` or `:raw:2-4` — range AND verbatim; the two compose in either order.
+- `:conflicts` — one-line-per-block index of every unresolved git merge conflict.
+
+# Files
+
+- Reading a directory path returns a depth-limited dirent listing.
+{{#if IS_HL_MODE}}
+- Reading a file with an explicit selector returns lines prefixed with `line+hash` anchors: `41th|def alpha():`. The 2-char hash is a content fingerprint that `edit` / `apply_patch` consume — copy it verbatim, NEVER fabricate. The pipe character after the hash is a separator, not part of the file content.
+{{else}}
+{{#if IS_LINE_NUMBER_MODE}}
+- Reading a file with an explicit selector returns lines prefixed with line numbers: `41|def alpha():`.
+{{/if}}
+{{/if}}
+- Parseable code without a selector returns a **structural summary**: declarations kept, large bodies collapsed to `..` (merged brace pair) or `…` (standalone). Summarized output ends with a footer of the form:
+
+  `[NN lines across MM elided regions; read <path>:raw or a line range like <path>:1-9999 for verbatim content]`
+
+  If the elided body is what you actually need, re-issue the **exact selector the footer names**. NEVER guess what's inside `..` / `…` — those markers carry no content.
+
+# Documents & Notebooks
+
+Extracts text from PDF, Word, PowerPoint, Excel, RTF, and EPUB. Notebooks (`.ipynb`) are shown as editable `# %% [type] cell:N` text; edits round-trip back to the underlying JSON preserving notebook metadata. Add `:raw` to a notebook to bypass the converter and read the JSON directly.
+
+# Images
+
+Reading an image path returns metadata (mime, bytes, dimensions, channels, alpha). For actual visual analysis, call `inspect_image` with the path and a question describing what to inspect.
+
+# Archives
+
+Supports `.tar`, `.tar.gz`, `.tgz`, `.zip`. Use `archive.ext:path/inside/archive` to read a member, and append a normal selector to the inner path: `archive.zip:dir/file.ts:50-60`.
+
+# SQLite
+
+For `.sqlite`, `.sqlite3`, `.db`, `.db3`:
+- `file.db` — list tables with row counts
+- `file.db:table` — schema + sample rows
+- `file.db:table:key` — single row by primary key
+- `file.db:table?limit=50&offset=100` — paginated rows
+- `file.db:table?where=status='active'&order=created:desc` — filtered rows
+- `file.db?q=SELECT …` — read-only SELECT query
+
+# URLs
+
+- Default reader-mode: HTML pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs → clean text/markdown.
+- `:raw` returns untouched HTML; line selectors (`:50`, `:50-100`, `:50+150`) paginate the cached fetched output.
+- Bare `host:port` URLs collide with the selector grammar — add a trailing slash before the selector: `https://example.com/:80`.
+
+# Internal URIs
+
+`agent://<id>`, `artifact://<id>`, `memory://root`, `rule://<name>`, and `local://<name>.md` resolve transparently and accept the same line selectors as filesystem paths. Use `artifact://<id>` to recover full output that a previous bash/eval/tool result spilled or truncated.
+
+<critical>
+- You MUST use `read` for every file, directory, archive, and URL inspection. `cat`, `head`, `tail`, `less`, `more`, `ls`, `tar`, `unzip`, `curl`, `wget` are FORBIDDEN — any such bash call is a bug, regardless of how short or convenient it looks.
+- You MUST prefer `read` over a browser/puppeteer tool for URL content; only reach for a browser when `read` cannot deliver reasonable content.
+- You MUST always include `path`. NEVER call `read` with `{}`.
+- For line ranges, append the selector to `path` (`path="src/foo.ts:50-200"`, `path="src/foo.ts:50+150"`). NEVER substitute `sed -n`, `awk NR`, or `head`/`tail` pipelines.
+- Summary footer says `read <path>:raw …`? Re-issue the exact selector it names. NEVER guess what's inside `..` / `…` markers — they carry no content.
+- You MAY combine selectors with URL reads and internal URIs; both paginate the cached resolved output.
+</critical>

package/src/prompts/tools/recall.md

@@ -0,0 +1,5 @@
+Search long-term memory for relevant information. Returns raw matching entries ranked by relevance.
+
+Use proactively — before answering questions about past conversations, user preferences, project decisions, or any topic where prior context would help accuracy. When in doubt, recall first.
+
+Prefer `recall` when you need specific facts or entries. Use `reflect` instead when you need a synthesised answer across many memories.

package/src/prompts/tools/recipe.md

@@ -0,0 +1,16 @@
+Run a recipe / script / target from the project's task runners.
+
+<instruction>
+- `op` is a single string: task name plus any args, e.g. `{op: "test"}` or `{op: "build --release"}`.
+- In monorepos, package and Cargo target tasks are namespaced with `/`, e.g. `{op: "pkg-a/test"}` or `{op: "crate/bin/server"}`.
+{{#if hasMultipleRunners}}- When the same task name exists in more than one runner, prefix with the runner id, e.g. `{op: "{{ambiguityExampleRunner}}:{{ambiguityExampleTask}}"}`. The available runner ids are: {{#each runners}}`{{id}}`{{#unless @last}}, {{/unless}}{{/each}}.
+{{/if}}- Runs in the session's cwd. Output and exit code are returned in the same shape as `bash`.
+</instruction>
+
+{{#each runners}}
+<runner id="{{id}}" label="{{label}}" command="{{commandPrefix}}">
+{{#each tasks}}
+- `{{name}}{{#if paramSig}} {{paramSig}}{{/if}}`{{#if doc}} — {{doc}}{{/if}}{{#if command}} (`{{command}}`{{#if cwd}} in `{{cwd}}`{{/if}}){{/if}}
+{{/each}}
+</runner>
+{{/each}}

package/src/prompts/tools/reflect.md

@@ -0,0 +1,5 @@
+Generate a synthesised answer by reasoning over long-term memory. Unlike `recall`, `reflect` blends relevant memories into a coherent response.
+
+Use for open-ended questions spanning many stored facts: "What do you know about this user?", "Summarize project decisions.", "What are my preferences for X?"
+
+Optional `context` parameter focuses the synthesis on a specific angle or sub-topic.

package/src/prompts/tools/render-mermaid.md

@@ -0,0 +1,9 @@
+Convert Mermaid graph source into ASCII diagram output.
+
+Parameters:
+- `mermaid` (required): Mermaid graph text to render.
+- `config` (optional): JSON render configuration (spacing and layout options).
+Behavior:
+- Returns ASCII diagram text.
+- Saves full output to `artifact://<id>` when storage is available.
+- Returns error when Mermaid input is invalid or rendering fails.

package/src/prompts/tools/replace.md

@@ -0,0 +1,36 @@
+Performs string replacements in files with fuzzy whitespace matching.
+
+<instruction>
+- Params MUST be `{ path, edits }`; `path` is required at the top level and applies to every replacement
+- You MUST use the smallest `old_text` that uniquely identifies the change
+- If `old_text` is not unique, you MUST expand it with more context or use `all: true` to replace all occurrences
+- You SHOULD prefer editing existing files over creating new ones
+</instruction>
+
+<output>
+Returns success/failure status. On success, file modified in place with replacement applied. On failure (e.g., `old_text` not found or matches multiple locations without `all: true`), returns error describing issue.
+</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.
+</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/resolve.md

@@ -0,0 +1,9 @@
+Resolves a pending action by either applying or discarding it.
+- `action` is required:
+  - `"apply"` persists / submits the pending action.
+  - `"discard"` rejects the pending action.
+- `reason` is required: one short complete sentence explaining why, starting with a capital letter and ending with a period.
+- `extra` (optional) is free-form metadata passed to the resolving tool. When the pending action is a plan-approval gate, supply `extra.title` (kebab/PascalCase slug for the approved plan filename). For preview-style pending actions (e.g. `ast_edit`), `extra` is unused.
+
+Valid whenever a pending action exists — either a preview-style staging (e.g. `ast_edit`) or a long-lived approval gate.
+Call fails with an error when no pending action exists.

package/src/prompts/tools/retain.md

@@ -0,0 +1,6 @@
+Store one or more facts in long-term memory for future sessions.
+
+Use for durable, reusable knowledge: user preferences, project decisions, architectural choices, anything that improves future responses.
+Ephemeral task state does not belong here.
+
+Each item MUST be specific and self-contained — include who, what, when, and why. Batch related facts in a single call; they are deduplicated and consolidated.

package/src/prompts/tools/rewind.md

@@ -0,0 +1,13 @@
+End an active checkpoint. Rewind context to it, replacing intermediate exploration with your report.
+
+Call immediately after `checkpoint`-started investigative work.
+
+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.
+
+Behavior:
+- If no checkpoint is active, this tool errors.
+- On success, the session rewinds and keeps your report as retained context.

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

@@ -0,0 +1,33 @@
+Search hidden tool metadata to discover and activate tools.
+
+Activate hidden tools (MCP and built-in) when you need a capability not in your active tool set.
+{{#if hasDiscoverableMCPServers}}Discoverable MCP servers in this session: {{#list discoverableMCPServerSummaries join=", "}}{{this}}{{/list}}.{{/if}}
+{{#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`)
+
+Behavior:
+- Searches hidden tool metadata using BM25-style relevance ranking
+- Matches against tool name, label, server name, description/summary, and input schema keys
+- Activates the top matching tools for the rest of the current session
+- 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:
+- `query`
+- `activated_tools` — tools activated by this search call
+- `match_count` — number of ranked matches returned by the search
+- `total_tools`

package/src/prompts/tools/search.md

@@ -0,0 +1,25 @@
+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` 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>
+
+<output>
+{{#if IS_HL_MODE}}
+- Text output is anchor-prefixed: `*5th|content` (match) or ` 9x}|content` (context, leading space). The 2-char suffix is a content fingerprint. The `|` before content is a separator, not part of the file content.
+{{else}}
+{{#if IS_LINE_NUMBER_MODE}}
+- Text output is line-number-prefixed
+{{/if}}
+{{/if}}
+</output>
+
+<critical>
+- You MUST use the built-in `search` tool for any content search. NEVER shell out to `grep`, `rg`, `ripgrep`, `ag`, `ack`, `git grep`, `awk`, `sed`-for-search, or any other CLI search via Bash — even for a single match, even "just to check quickly", even piped through other commands.
+- Bash `grep`/`rg` loses `.gitignore` semantics, bypasses result limits, and wastes tokens. The `search` tool is faster, structured, and already wired into the workspace — there is no scenario where Bash search is preferable.
+- If you catch yourself typing `grep`, `rg`, or `| grep` in a Bash command, stop and re-issue the lookup through the `search` tool instead.
+- If the search is open-ended, requiring multiple rounds, you MUST use the Task tool with the explore subagent instead of chaining `search` calls yourself.
+</critical>