@oh-my-pi/pi-coding-agent 14.1.2 → 14.2.1

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

@@ -0,0 +1,67 @@
+## `apply_patch`
+
+Use the `apply_patch` shell command to edit files.
+Your patch language is a stripped‑down, file‑oriented diff format designed to be easy to parse and safe to apply. You can think of it as a high‑level envelope:
+
+*** Begin Patch
+[ one or more file sections ]
+*** End Patch
+
+Within that envelope, you get a sequence of file operations.
+You **MUST** include a header to specify the action you are taking.
+Each operation starts with one of three headers:
+
+*** Add File: <path> - create a new file. Every following line is a + line (the initial contents).
+*** Delete File: <path> - remove an existing file. Nothing follows.
+*** Update File: <path> - patch an existing file in place (optionally with a rename).
+
+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:
+
+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.
+- If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:
+@@ class BaseClass
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+- If a code block is repeated so many times in a class or function such that even a single `@@` statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple `@@` statements to jump to the right context. For instance:
+
+@@ class BaseClass
+@@ 	 def method():
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+
+The full grammar definition is below:
+Patch := Begin { FileOp } End
+Begin := "*** Begin Patch" NEWLINE
+End := "*** End Patch" NEWLINE
+FileOp := AddFile | DeleteFile | UpdateFile
+AddFile := "*** Add File: " path NEWLINE { "+" line NEWLINE }
+DeleteFile := "*** Delete File: " path NEWLINE
+UpdateFile := "*** Update File: " path NEWLINE [ MoveTo ] { Hunk }
+MoveTo := "*** Move to: " newPath NEWLINE
+Hunk := "@@" [ header ] NEWLINE { HunkLine } [ "*** End of File" NEWLINE ]
+HunkLine := (" " | "-" | "+") text NEWLINE
+
+A full patch can combine several operations:
+
+*** Begin Patch
+*** Add File: hello.txt
++Hello world
+*** Update File: src/app.py
+*** Move to: src/main.py
+@@ def greet():
+-print("Hi")
++print("Hello, world!")
+*** Delete File: obsolete.txt
+*** End Patch
+
+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.

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

@@ -2,47 +2,42 @@ Performs structural AST-aware rewrites via native ast-grep.
 
 <instruction>
 - Use for codemods and structural rewrites where plain text replace is unsafe
-- Narrow scope with `path` before replacing (`path` accepts files, directories, glob patterns, or comma-separated path lists; use `glob` for an additional filter relative to `path`)
-- Default to language-scoped rewrites in mixed repositories: set `lang` and keep `path`/`glob` narrow
-- Treat parse issues as a scoping or pattern-shape signal: tighten `path`/`lang`, or rewrite the pattern into valid syntax before retrying
-- Metavariables captured in each rewrite pattern (`$A`, `$$$ARGS`) are substituted into that entry's rewrite template
-- For variadic captures (arguments, fields, statement lists), use `$$$NAME` (not `$$NAME`)
-- Rewrite patterns must parse as valid AST for the target language; if a method or declaration does not parse standalone, wrap it in valid context or switch to a contextual `sel`
-- If ast-grep reports `Multiple AST nodes are detected`, the rewrite pattern is not a single parseable node; wrap method snippets in valid context (for example `class $_ { … }`) and use `sel` to rewrite the inner node
-- When using contextual `sel`, the match and replacement target the selected node, not the outer wrapper you used to make the pattern parse
-- For TypeScript declarations and methods, prefer patterns that tolerate annotations you do not care about, e.g. `async function $NAME($$$ARGS): $_ { $$$BODY }` or `class $_ { method($ARG: $_): $_ { $$$BODY } }`
-- Metavariables must be the sole content of an AST node; partial-text metavariables like `prefix$VAR` or `"hello $NAME"` do NOT work in patterns or rewrites
-- To delete matched code, use an empty `out` string: `{"pat":"console.log($$$)","out":""}`
-- Each matched rewrite is a 1:1 structural substitution; you cannot split one capture into multiple nodes or merge multiple captures into one node
+- `path` accepts a comma-separated list in addition to file/dir/glob
+- Set `lang` explicitly in mixed-language trees for deterministic rewrites
+- Metavariables captured in `pat` (`$A`, `$$$ARGS`) are substituted into that entry's `out` template
+- **Patterns match AST structure, not text.** `$NAME` = one node (captured); `$_` = one without binding; `$$$NAME` = zero-or-more (lazy — stops at next matchable element); `$$$` = zero-or-more without binding. Use `$$$NAME`, **NOT** `$$NAME` — the two-dollar form is invalid. Metavariable names are UPPERCASE and **MUST** be the whole AST node — partial text like `prefix$VAR` or `"hello $NAME"` does NOT work
+- When the same metavariable appears twice, both occurrences **MUST** match identical code (`$A == $A` matches `x == x`, not `x == y`)
+- Rewrite patterns **MUST** parse as a single valid AST node. For method fragments or body snippets that don't parse standalone, wrap in context (e.g. `class $_ { … }`) and set `sel` to target the inner node — match and replacement target the selected node, not the wrapper. If ast-grep reports `Multiple AST nodes are detected`, wrap and use `sel`
+- For TS declarations/methods, tolerate unknown annotations: `async function $NAME($$$ARGS): $_ { $$$BODY }` or `class $_ { method($ARG: $_): $_ { $$$BODY } }`
+- Delete matched code with empty `out`: `{"pat":"console.log($$$)","out":""}`
+- Each rewrite is a 1:1 structural substitution — cannot split one capture across multiple nodes or merge multiple captures into one
 </instruction>
 
 <output>
-- Returns replacement summary, per-file replacement counts, and change diffs
-- Includes parse issues when files cannot be processed
+- Replacement summary, per-file replacement counts, and change diffs
+- Parse issues when files cannot be processed
 </output>
 
 <examples>
 - Rename a call site across a directory:
   `{"ops":[{"pat":"oldApi($$$ARGS)","out":"newApi($$$ARGS)"}],"lang":"typescript","path":"src/"}`
-- Delete all matching calls (empty `out` removes the matched node):
+- Delete matching calls (empty `out` removes the node):
   `{"ops":[{"pat":"console.log($$$ARGS)","out":""}],"lang":"typescript","path":"src/"}`
-- Rewrite an import source path:
+- Rewrite import source path:
   `{"ops":[{"pat":"import { $$$IMPORTS } from \"old-package\"","out":"import { $$$IMPORTS } from \"new-package\""}],"lang":"typescript","path":"src/"}`
 - Modernize to optional chaining (same metavariable enforces identity):
   `{"ops":[{"pat":"$A && $A()","out":"$A?.()"}],"lang":"typescript","path":"src/"}`
 - Swap two arguments using captures:
   `{"ops":[{"pat":"assertEqual($A, $B)","out":"assertEqual($B, $A)"}],"lang":"typescript","path":"tests/"}`
-- Rename a TypeScript function declaration while tolerating any return type annotation:
+- Rename a function declaration while tolerating any return type annotation:
   `{"ops":[{"pat":"async function fetchData($$$ARGS): $_ { $$$BODY }","out":"async function loadData($$$ARGS): $_ { $$$BODY }"}],"sel":"function_declaration","lang":"typescript","path":"src/api.ts"}`
-- Rewrite a TypeScript method body fragment by wrapping it in parseable context and selecting the method node:
+- Rewrite a method body fragment by wrapping in parseable context and selecting the method:
   `{"ops":[{"pat":"class $_ { async execute($INPUT: $_) { $$$BEFORE; const $PARSED = $_.parse($INPUT); $$$AFTER } }","out":"class $_ { async execute($INPUT: $_) { $$$BEFORE; const $PARSED = $SCHEMA.parse($INPUT); $$$AFTER } }"}],"sel":"method_definition","lang":"typescript","path":"src/tools/todo.ts"}`
-- Convert Python print calls to logging:
+- Python — convert print calls to logging:
   `{"ops":[{"pat":"print($$$ARGS)","out":"logger.info($$$ARGS)"}],"lang":"python","path":"src/"}`
 </examples>
 
 <critical>
-- `ops` **MUST** contain at least one concrete `{ pat, out }` entry
-- If the path pattern spans multiple languages, set `lang` explicitly for deterministic rewrites
-- Parse issues mean the rewrite request is malformed or mis-scoped; do not assume a clean no-op until the pattern parses successfully
-- For one-off local text edits, prefer the Edit tool instead of AST edit
+- Parse issues mean the rewrite is malformed or mis-scoped — fix the pattern before assuming a clean no-op
+- For one-off local text edits, prefer the Edit tool
 </critical>

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

@@ -1,54 +1,47 @@
 Performs structural code search using AST matching via native ast-grep.
 
 <instruction>
-- Use this when syntax shape matters more than raw text (calls, declarations, specific language constructs)
-- Prefer a precise `path` scope to keep results targeted and deterministic (`path` accepts files, directories, glob patterns, or comma-separated path lists; use `glob` for an additional filter relative to `path`)
-- Default to language-scoped search in mixed repositories: pair `path` + `glob` + explicit `lang` to avoid parse-noise from non-source files
-- `pat` is required and must include at least one non-empty AST pattern; `lang` is optional (`lang` is inferred per file extension when omitted)
-- Multiple patterns run in one native pass; results are merged and then `offset`/`limit` are applied to the combined match set
-- Use `sel` only for contextual pattern mode; otherwise provide direct patterns
-- In contextual pattern mode, results are returned for the selected node (`sel`), not the outer wrapper used to make the pattern parse
-- For variadic captures (arguments, fields, statement lists), use `$$$NAME` (not `$$NAME`)
-- Patterns must parse as a single valid AST node for the target language; if a bare pattern fails, wrap it in valid context or use `sel`
-- If ast-grep reports `Multiple AST nodes are detected`, your pattern is not a single parseable node; wrap method snippets in valid context (for example `class $_ { … }`) and use `sel` to target the inner node
-- Patterns match AST structure, not text — whitespace/formatting differences are ignored
-- When the same metavariable appears multiple times, all occurrences must match identical code
-- For TypeScript declarations and methods, prefer shapes that tolerate annotations you do not care about, e.g. `async function $NAME($$$ARGS): $_ { $$$BODY }` or `class $_ { method($ARG: $_): $_ { $$$BODY } }` instead of omitting annotations entirely
-- Metavariables must be the sole content of an AST node; partial-text metavariables like `prefix$VAR`, `"hello $NAME"`, or `a $OP b` do NOT work — match the whole node instead
-- `$$$` captures are lazy (non-greedy): they stop when the next element in the pattern can match; place the most specific node after `$$$` to control where capture ends
-- `$_` is a non-capturing wildcard (matches any single node without binding); use it when you need to tolerate a node but don't need its value
-- Search the right declaration form before concluding absence: top-level function, class method, and variable-assigned function are different AST shapes
-- If you only need to prove a symbol exists, prefer a looser contextual search such as `pat: ["executeBash"]` with `sel: "identifier"`
+- Use when syntax shape matters more than raw text (calls, declarations, specific language constructs)
+- `path` accepts a comma-separated list in addition to file/dir/glob
+- Set `lang` explicitly in mixed-language trees to avoid parse noise from non-source files
+- Multiple patterns in `pat` run in one native pass, merged, then `offset`/`limit` applied
+- **Patterns match AST structure, not text** — whitespace/formatting is ignored
+- `$NAME` captures one node; `$_` matches one without binding; `$$$NAME` captures zero-or-more (lazy — stops at next matchable element); `$$$` matches zero-or-more without binding. Use `$$$NAME`, **NOT** `$$NAME` — the two-dollar form is invalid and produces a parse error
+- Metavariable names are UPPERCASE and must be the whole AST node — partial-text like `prefix$VAR`, `"hello $NAME"`, or `a $OP b` does NOT work; match the whole node instead
+- When the same metavariable appears twice, both occurrences **MUST** match identical code (`$A == $A` matches `x == x`, not `x == y`)
+- Patterns **MUST** parse as a single valid AST node for the target language. For method fragments or body snippets that don't parse standalone, wrap in valid context (e.g. `class $_ { … }`) and set `sel` to target the inner node — results return for the selected node, not the outer wrapper. If ast-grep reports `Multiple AST nodes are detected`, the pattern isn't a single parseable node — wrap and use `sel`
+- C++ qualified calls used as expression statements need the statement semicolon in the pattern: use `ns::doThing($ARG);`, `$CALLEE($ARG)`, or wrap a statement snippet and select `call_expression`. Without `;`, tree-sitter-cpp may parse `ns::doThing($ARG)` as declaration-like syntax and return no matches
+- For TS declarations/methods, tolerate unknown annotations: `async function $NAME($$$ARGS): $_ { $$$BODY }` or `class $_ { method($ARG: $_): $_ { $$$BODY } }`
+- Declaration forms are structurally distinct — top-level `function foo`, class method `foo()`, and `const foo = () => {}` are different AST shapes; search the right form before concluding absence
+- Loosest existence check: `pat: ["executeBash"]` with `sel: "identifier"`
 </instruction>
 
 <output>
-- Returns grouped matches with file path, byte range, line/column ranges, and metavariable captures
-- Includes summary counts (`totalMatches`, `filesWithMatches`, `filesSearched`) and parse issues when present
+- Grouped matches with file path, byte range, line/column ranges, metavariable captures
+- Summary counts (`totalMatches`, `filesWithMatches`, `filesSearched`) and parse issues when present
 </output>
 
 <examples>
-- Find all console logging calls in one pass (multi-pattern, scoped):
+- Multi-pattern scoped search:
   `{"pat":["console.log($$$)","console.error($$$)"],"lang":"typescript","path":"src/"}`
-- Find all named imports from a specific package:
+- Named imports from a specific package (quoted string inside pattern):
   `{"pat":["import { $$$IMPORTS } from \"react\""],"lang":"typescript","path":"src/"}`
-- Match arrow functions assigned to a const (different AST shape than function declarations):
+- Arrow functions assigned to a const (distinct AST from function declarations):
   `{"pat":["const $NAME = ($$$ARGS) => $BODY"],"lang":"typescript","path":"src/utils/"}`
-- Match any method call on an object using wildcard `$_` (ignores method name):
+- Method call on any object, ignoring method name with `$_`:
   `{"pat":["logger.$_($$$ARGS)"],"lang":"typescript","path":"src/"}`
-- Contextual pattern with selector — match only the identifier `foo`, not the whole call:
+- Contextual pattern with selector — match the identifier `foo`, not the whole call:
   `{"pat":["foo()"],"sel":"identifier","lang":"typescript","path":"src/utils.ts"}`
-- Match a TypeScript function declaration without caring about its exact return type:
+- Match a function declaration while tolerating any return type annotation (`sel` targets the inner node):
   `{"pat":["async function processItems($$$ARGS): $_ { $$$BODY }"],"sel":"function_declaration","lang":"typescript","path":"src/worker.ts"}`
-- Match a TypeScript method body fragment by wrapping it in parseable context and selecting the method node:
+- Match a method body fragment by wrapping in parseable context and selecting the method:
   `{"pat":["class $_ { async execute($INPUT: $_) { $$$BEFORE; const $PARSED = $_.parse($INPUT); $$$AFTER } }"],"sel":"method_definition","lang":"typescript","path":"src/tools/todo.ts"}`
 - Loosest existence check for a symbol in one file:
   `{"pat":["processItems"],"sel":"identifier","lang":"typescript","path":"src/worker.ts"}`
 </examples>
 
 <critical>
-- `pat` is required
-- Set `lang` explicitly to constrain matching when path pattern spans mixed-language trees
-- Avoid repo-root AST scans when the target is language-specific; narrow `path` first
-- Treat parse issues as query failure, not evidence of absence: repair the pattern or tighten `path`/`glob`/`lang` before concluding "no matches"
-- If exploration is broad/open-ended across subsystems, use Task tool with explore subagent first
+- Avoid repo-root AST scans when the target is language-specific — narrow `path` first
+- Parse issues are query failure, not evidence of absence: repair the pattern or tighten `path`/`glob`/`lang` before concluding "no matches"
+- For broad/open-ended exploration across subsystems, use Task tool with explore subagent first
 </critical>

package/src/prompts/tools/bash.md

@@ -2,44 +2,34 @@ Executes bash command in shell session for terminal operations like git, bun, ca
 
 <instruction>
 - You **MUST** use `cwd` parameter to set working directory instead of `cd dir && …`
-- Prefer `env: { NAME: "…" }` for multiline, quote-heavy, or untrusted values instead of inlining them into shell syntax; reference them from the command as `$NAME`
+- Prefer `env: { NAME: "…" }` for multiline, quote-heavy, or untrusted values; reference them as `$NAME`
 - Quote variable expansions like `"$NAME"` to preserve exact content and avoid shell parsing bugs
-- PTY mode is opt-in: set `pty: true` only when command expects a real terminal (for example `sudo`, `ssh` where you need input from the user); default is `false`
+- 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`
 - You **MUST** use `;` only when later commands should run regardless of earlier failures
-- `skill://` URIs are auto-resolved to filesystem paths before execution
-	- `python skill://my-skill/scripts/init.py` runs the script from the skill directory
-	- `skill://<name>/<relative-path>` resolves within the skill's base directory
-- Internal URLs are also auto-resolved to filesystem paths before execution.
+- Internal URIs (`skill://`, `agent://`, etc.) are auto-resolved to filesystem paths. Examples: `python skill://my-skill/scripts/init.py` runs the skill script; `skill://<name>/<relative-path>` resolves within the skill directory.
 {{#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}}
 {{#if autoBackgroundEnabled}}
-- Long-running non-PTY bash commands may auto-background after about {{autoBackgroundThresholdSeconds}}s and continue as background jobs automatically.
+- Long-running non-PTY commands may auto-background after ~{{autoBackgroundThresholdSeconds}}s and continue as background jobs.
 {{/if}}
 {{#if asyncEnabled}}
+- Inspect background jobs with `read jobs://` (`read jobs://<job-id>` for detail). To wait for results, call `poll` — do NOT poll `read jobs://` in a loop or yield and hope for delivery.
 {{else}}
 {{#if autoBackgroundEnabled}}
-- Auto-backgrounded jobs use the same background-job pipeline as explicit async execution.
-{{/if}}
-{{/if}}
-{{#if asyncEnabled}}
-- Use `read jobs://` to inspect all background jobs and `read jobs://<job-id>` for detailed status/output when needed.
-- When you need to wait for async results before continuing, call `poll` — it blocks until jobs complete. Do NOT poll `read jobs://` in a loop or yield and hope for delivery.
-{{else}}
-{{#if autoBackgroundEnabled}}
-- If a command auto-backgrounds, use `read jobs://` to inspect jobs and `poll` when you need to wait for completion instead of polling in a loop.
+- For auto-backgrounded jobs, inspect with `read jobs://` and call `poll` to wait — do NOT poll in a loop.
 {{/if}}
 {{/if}}
 </instruction>
 
 <output>
-Returns the output, and an exit code from command execution.
-- If output truncated, full output can be retrieved from `artifact://<id>`, linked in metadata
+Returns output and exit code.
+- Truncated output is retrievable from `artifact://<id>` (linked in metadata)
 - Exit codes shown on non-zero exit
 </output>
 
 <critical>
-You **MUST** use specialized tools instead of bash for ALL file operations:
+You **MUST NOT** use bash for file operations where specialized tools exist:
 
 |Instead of (WRONG)|Use (CORRECT)|
 |---|---|
@@ -52,11 +42,9 @@ You **MUST** use specialized tools instead of bash for ALL file operations:
 |`ls dir/`|`read(path="dir/")`|
 |`cat <<'EOF' > file`|`write(path="file", content="…")`|
 |`sed -i 's/old/new/' file`|`edit(path="file", edits=[…])`|
-
 {{#if hasAstEdit}}|`sed -i 's/oldFn(/newFn(/' src/*.ts`|`ast_edit({ops:[{pat:"oldFn($$$A)", out:"newFn($$$A)"}], path:"src/"})`|{{/if}}
 {{#if hasAstGrep}}- You **MUST** use `ast_grep` for structural code search instead of bash `grep`/`awk`/`perl` pipelines{{/if}}
 {{#if hasAstEdit}}- You **MUST** use `ast_edit` for structural rewrites instead of bash `sed`/`awk`/`perl` pipelines{{/if}}
-- You **MUST NOT** use Bash for these operations like read, grep, find, edit, write, where specialized tools exist.
-- You **MUST NOT** use `2>&1` | `2>/dev/null` pattern, stdout and stderr are already merged.
-- You **MUST NOT** use `| head -n 50` or `| tail -n 100` pattern, use `head` and `tail` parameters instead.
+- You **MUST NOT** use `2>&1` or `2>/dev/null` — stdout and stderr are already merged
+- You **MUST NOT** use `| head -n 50` or `| tail -n 100` — use `head`/`tail` parameters instead
 </critical>

package/src/prompts/tools/debug.md

@@ -1,33 +1,19 @@
 Provides debugger access through the Debug Adapter Protocol (DAP). Use this to launch or attach debuggers, set breakpoints, step through execution, inspect threads/stack/variables, evaluate expressions, capture program output, and interrupt hung programs.
 
 <instruction>
-- Prefer this over bash when you need program state, breakpoints, stepping, thread inspection, or to interrupt a running process.
-- `action: "launch"` starts a debugger session for a program or script. `program` is required. `adapter` is optional; when omitted, the tool selects an installed adapter from the target path and workspace.
-- `action: "attach"` connects to an existing process. Provide `pid` for local process attach or `port` for adapters that support remote attach. Use `adapter` to force a specific debugger.
-- Breakpoints:
-  - Source breakpoints: `set_breakpoint` / `remove_breakpoint` with `file` + `line`
-  - Function breakpoints: `set_breakpoint` / `remove_breakpoint` with `function`
-  - Optional `condition` adds a conditional breakpoint expression
-- Flow control:
-  - `continue` resumes execution and waits briefly to see whether the program stops or keeps running
-  - `step_over`, `step_in`, `step_out` perform single-step execution
-  - `pause` interrupts a running program so you can inspect the current state
-- Inspection:
-  - `threads` lists threads
-  - `stack_trace` returns frames for the current stopped thread
-  - `scopes` requires `frame_id` or a current stopped frame
-  - `variables` requires `variable_ref` or `scope_id`
-  - `evaluate` requires `expression`; use `context: "repl"` for raw debugger commands when the adapter supports them
-  - `output` returns captured stdout/stderr/console output from the debuggee and adapter
-  - `sessions` lists tracked debug sessions
-  - `terminate` ends the active debug session
-- Timeouts apply to individual debugger requests, not the full session lifetime.
+- Prefer 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).
+- `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 are `gdb`, `lldb-dap`, `python -m debugpy.adapter`, and `dlv dap`.
+- Adapter availability depends on local binaries. Common built-ins: `gdb`, `lldb-dap`, `python -m debugpy.adapter`, `dlv dap`.
 </caution>
 
 <example name="launch and inspect hang">

package/src/prompts/tools/find.md

@@ -1,10 +1,6 @@
 Finds files using fast pattern matching that works with any codebase size.
 
 <instruction>
-- Pattern includes the search path: `src/**/*.ts`, `lib/*.json`, `**/*.md`
-- You may provide comma-separated path lists, for example `apps/,packages/,phases/`
-- Simple patterns like `*.ts` automatically search recursively from cwd
-- Includes hidden files by default (use `hidden: false` to exclude)
 - You **SHOULD** perform multiple searches in parallel when potentially useful
 </instruction>
 

package/src/prompts/tools/grep.md

@@ -2,11 +2,9 @@ Searches files using powerful regex matching.
 
 <instruction>
 - Supports full regex syntax (e.g., `log.*Error`, `function\\s+\\w+`); literal braces need escaping (`interface\\{\\}` for `interface{}` in Go)
-- `path` may be a file, directory, glob path, or comma-separated path list; pair it with `glob` when you need an additional relative file filter
-- Filter files with `glob` (e.g., `*.js`, `**/*.tsx`) or `type` (e.g., `js`, `py`, `rust`)
-- Respects `.gitignore` by default; set `gitignore: false` to include ignored files
-- For cross-line patterns like `struct \\{[\\s\\S]*?field`, set `multiline: true` if needed
-- If the pattern contains a literal `\n`, multiline defaults to true
+- `path` also accepts comma-separated path lists; pair with `glob` when you need a relative file filter in addition to `type`
+- For cross-line patterns like `struct \\{[\\s\\S]*?field`, set `multiline: true`
+- If the pattern contains a literal `\n`, `multiline` defaults to true automatically
 </instruction>
 
 <output>

package/src/prompts/tools/hashline.md

@@ -16,11 +16,12 @@ Read the file first. Copy anchors exactly from the latest `read` output. After a
 **`loc` values**
 - `"append"` / `"prepend"` — insert at end/start of file
 - `{ append: "N#ID" }` / `{ prepend: "N#ID" }` — insert after/before anchored line
-- `{ range: { pos: "N#ID", end: "N#ID" } }` — replace inclusive range of lines `pos..end` with new content
-  </operations>
+- `{ range: { pos: "N#ID", end: "N#ID" } }` — replace inclusive range `pos..end` with new content (set `pos == end` for single-line replace)
+</operations>
 
 <examples>
 All examples below reference the same file:
+
 ```ts title="a.ts"
 {{hline  1 "// @ts-ignore"}}
 {{hline  2 "const timeout = 5000;"}}
@@ -44,6 +45,7 @@ All examples below reference the same file:
 
 <example name="replace a block body">
 Replace only the catch body. Do not target the shared boundary line `} catch (err) {`.
+
 ```
 {
   edits: [{
@@ -60,6 +62,7 @@ Replace only the catch body. Do not target the shared boundary line `} catch (er
 
 <example name="replace whole block including closing brace">
 Replace the entire body of `alpha`, including its closing `}`. `end` **MUST** be {{href 7 "}"}} because `content` includes `}`.
+
 ```
 {
   edits: [{
@@ -73,10 +76,13 @@ Replace the entire body of `alpha`, including its closing `}`. `end` **MUST** be
   }]
 }
 ```
-**Wrong**: using `end: {{href 6 "\tlog();"}}` with the same content — line 7 (`}`) survives the replacement AND content emits `}`, producing two closing braces.
+
+**Wrong**: `end: {{href 6 "\tlog();"}}` with the same content — line 7 (`}`) survives AND content emits `}`, producing two closing braces.
 </example>
 
 <example name="replace one line">
+Single-line replace uses `pos == end`.
+
 ```
 {
   edits: [{
@@ -102,6 +108,7 @@ Replace the entire body of `alpha`, including its closing `}`. `end` **MUST** be
 
 <example name="insert before sibling">
 When adding a sibling declaration, prefer `prepend` on the next declaration.
+
 ```
 {
   edits: [{
@@ -120,12 +127,11 @@ When adding a sibling declaration, prefer `prepend` on the next declaration.
 </examples>
 
 <critical>
-- Make the minimum exact edit. Do not rewrite nearby code unless the consumed range requires it.
-- Use anchors exactly as `N#ID` from the latest `read` output.
+- Make the minimum exact edit. Do not rewrite nearby code unless the range requires it.
+- Copy anchors exactly as `N#ID` from the latest `read` output.
 - `range` requires both `pos` and `end`.
-- When your replacement `content` ends with a closing delimiter (`}`, `*/`, `)`, `]`), verify `end` includes the original line carrying that delimiter. If `end` stops one line too early, the original delimiter survives and your content adds a second copy.
-- **Self-check**: compare the last line of `content` with the line immediately after `end` in the file. If they match (e.g., both are `}`), extend `end` to include that line.
-- For a range, either replace only the body or replace the whole range. Do not split range boundaries.
+- **Closing-delimiter check**: when your replacement `content` ends with a closing delimiter (`}`, `*/`, `)`, `]`), compare it against the line immediately after `end` in the file. If they match, extend `end` to include that line — otherwise the original delimiter survives and `content` adds a second copy.
+- For a range, replace only the body or the whole range — don't split range boundaries.
 - `content` must be literal file content with matching indentation. If the file uses tabs, use real tabs.
-- You **MUST NOT** use this tool to reformat or clean up unrelated code. **ALWAYS** use project-specific tooling like linters or code formatters which are much more efficient and reliable.
-  </critical>
+- You **MUST NOT** use this tool to reformat or clean up unrelated code — use project-specific linters or code formatters instead.
+</critical>

package/src/prompts/tools/python.md

@@ -1,15 +1,11 @@
 Runs Python cells sequentially in persistent IPython kernel.
 
 <instruction>
-Kernel persists across calls and cells; **imports, variables, and functions survive—use this.**
-**Work incrementally:**
-- You **SHOULD** use one logical step per cell (imports, define function, test it, use it)
-- You **SHOULD** pass multiple small cells in one call
-- You **SHOULD** define small functions you can reuse and debug individually
-- You **MUST** put workflow explanations in assistant message or cell title
-**When something fails:**
-- Errors tell you which cell failed (e.g., "Cell 3 failed")
-- You **SHOULD** resubmit only the fixed cell (or fixed cell + remaining cells)
+Kernel persists across calls and cells; **imports, variables, and functions survive — use this.**
+
+**Work incrementally:** one logical step per cell (imports, define, test, use). Pass multiple small cells in one call. Define small reusable functions you can debug individually. You **MUST** put workflow explanations in the assistant message or cell title — never inside cell code.
+
+**On failure:** errors identify the failing cell (e.g., "Cell 3 failed"). Resubmit only the fixed cell (or fixed cell + remaining cells).
 </instruction>
 
 {{#if categories.length}}
@@ -35,21 +31,21 @@ User sees output like Jupyter notebook; rich displays render fully:
 - `display(HTML(…))` → rendered HTML
 - `display(Markdown(…))` → formatted markdown
 - `plt.show()` → inline figures
-  **You will see object repr** (e.g., `<IPython.core.display.JSON object>`). Trust `display()`; you **MUST NOT** assume user sees only repr.
+
+**You will see object repr** (e.g., `<IPython.core.display.JSON object>`). Trust `display()`; you **MUST NOT** assume the user sees only the repr.
 </output>
 
 <caution>
-- Per-call mode uses fresh kernel each call
-- You **MUST** use `reset: true` to clear state when session mode active
+- Per-call mode uses a fresh kernel each call
+- You **MUST** use `reset: true` to clear state when session mode is active
 </caution>
 
 <critical>
 - You **MUST** use `run()` for shell commands; you **MUST NOT** use raw `subprocess`
 </critical>
 
-<example name="good">
+<example name="multiple small cells">
 ```python
-# Multiple small cells
 cells: [
     {"title": "imports", "code": "import json\nfrom pathlib import Path"},
     {"title": "parse helper", "code": "def parse_config(path):\n    return json.loads(Path(path).read_text())"},

package/src/prompts/tools/read.md

@@ -1,13 +1,13 @@
 Reads the content at the specified path or URL.
 
 <instruction>
-The `read` tool is a multi-purpose tool that can be used to inspect all kinds of files and URLs.
+The `read` tool is multi-purpose — inspects files, directories, archives, SQLite databases, and URLs.
 - You **MUST** parallelize reads when exploring related files
 
 ## Parameters
-- `path` -- file path or URL (required)
-- `sel` -- optional selector for line ranges or raw mode
-- `timeout` -- seconds, for URLs only
+- `path` — file path or URL (required)
+- `sel` — optional selector for line ranges or raw mode
+- `timeout` — seconds, for URLs only
 
 ## Selectors
 
@@ -22,42 +22,35 @@ Max {{DEFAULT_MAX_LINES}} lines per call.
 
 # Filesystem
 {{#if IS_HASHLINE_MODE}}
-- If reading from FS, result will be prefixed with anchors: `41#ZZ:def alpha():`
+- Reading from FS returns lines prefixed with anchors: `41#ZZ:def alpha():`
 {{else}}
-  {{#if IS_LINE_NUMBER_MODE}}
-- If reading from FS, result will be prefixed with line numbers: `41:def alpha():`
-  {{/if}}
+{{#if IS_LINE_NUMBER_MODE}}
+- Reading from FS returns lines prefixed with line numbers: `41:def alpha():`
+{{/if}}
 {{/if}}
 
 # Inspection
-When used with a PDF, Word, PowerPoint, Excel, RTF, EPUB, or Jupyter notebook file, the tool will return the extracted text.
-It can also be used to inspect images.
+Extracts text from PDF, Word, PowerPoint, Excel, RTF, EPUB, and Jupyter notebook files. Can inspect images.
 
 # Directories & Archives
-When used against a directory, or an archive root, the tool will return a list of directory entries within.
-- Formats: `.tar`, `.tar.gz`, `.tgz`, and `.zip`.
-- Use `archive.ext:path/inside/archive` to read or list archive contents
+Directories and archive roots return a list of entries. Supports `.tar`, `.tar.gz`, `.tgz`, `.zip`. Use `archive.ext:path/inside/archive` to read contents.
 
 # SQLite Databases
-When used against a SQLite database (`.sqlite`, `.sqlite3`, `.db`, `.db3`), returns structured database content.
+For `.sqlite`, `.sqlite3`, `.db`, `.db3`:
 - `file.db` — list tables with row counts
-- `file.db:table` — table schema + sample rows
+- `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
-- Extract information from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, technical blogs, RSS/Atom feeds, JSON endpoints
-- `sel="raw"` for untouched HTML or debugging
-- `timeout` to override the default request timeout
+Extracts content from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom feeds, JSON endpoints, and similar text-based resources. Use `sel="raw"` for untouched HTML; `timeout` to override the default request timeout.
 </instruction>
 
 <critical>
-- You **MUST** use `read` instead of bash for ALL file reading: `cat`, `head`, `tail`, `less`, `more` are FORBIDDEN.
-- You **MUST** use `read` instead of `ls` for directory listings.
-- You **MUST** use `read` instead of shelling out to `tar` or `unzip` for supported archive reads.
-- You **MUST** always include the `path` parameter, NEVER call `read` with empty arguments `{}`.
-- When reading specific line ranges, use `sel`: `read(path="file", sel="L50-L150")` not `cat -n file | sed`.
-- You **MAY** use `sel` with URL reads; the tool will paginate the cached fetched output.
+- You **MUST** use `read` (never bash `cat`/`head`/`tail`/`less`/`more`/`ls`/`tar`/`unzip`) for all file, directory, and archive reads.
+- You **MUST** always include the `path` parameter; never call with `{}`.
+- For specific line ranges, use `sel`: `read(path="file", sel="L50-L150")` — not `cat -n file | sed`.
+- You **MAY** use `sel` with URL reads; the tool paginates cached fetched output.
 </critical>