@oh-my-pi/pi-coding-agent 14.5.2 → 14.5.5

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

@@ -1,5 +1,3 @@
-## `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:
 

package/src/prompts/tools/atom.md

@@ -1,103 +1,94 @@
-Applies precise file edits using full anchors from `read` output (for example `160sr`).
-
-Read the file first. Copy the full anchors exactly as shown by `read`.
-
-<operations>
-**Top level**: `{ path, edits: […] }` — `path` is shared by all entries. You may still override the file inside `loc` with forms like `other.ts:160sr`.
-
-Each entry has one shared locator plus one or more verbs:
-- `loc: "160sr"` — single anchored line
-- `loc: "$"` — whole file: `pre` prepends, `post` appends, `sed` substitutes across every line
-- `loc: "a.ts:160sr"` — cross-file override inside the locator
-
-Verbs:
-- `splice: […]`: lines are spliced in at the anchor.
-- `pre: […]`: prepend before the anchor (or at BOF if `loc=$`)
-- `post: […]`: append after the anchor (or at EOF if `loc=$`)
-- `sed: { pat, rep, g?, F? }` — structured find/replace on the anchor line. **Prefer this over `splice` for token-level changes**
-  - `pat`: pattern to find (regex by default)
-  - `rep`: replacement (regex back-refs like `$1`, `$&` available)
-  - `g`: global — replace every occurrence (default `false`; pass `true` to replace all)
-  - `F`: literal — treat `pat` as a literal substring (no regex). Use this whenever `pat` contains `||`, `.`, `(`, `?`, `\`, etc. you mean literally.
-You **MUST** keep `pat` as short as possible.
-
-Combination rules:
-- On a single-anchor `loc`, you may combine `pre`, `splice`, and `post` in the same entry.
-- `splice: []` on a single-anchor `loc` deletes that line.
-- `splice:[""]` is **not** delete — it replaces the line with a blank line.
-</operations>
-
-<examples>
-All examples below reference the same file:
-
-```ts title="a.ts"
-{{hline 1 "const tag = \"BAD\";"}}
+Your patch language is a compact, file-oriented edit format.
+
+When emitting a patch, the first non-blank line **MUST** be `---PATH`.
+A Lid is the anchor emitted in read/grep etc. (line number + id, e.g. `5th`).
+
+<ops>
+---PATH  start editing PATH with cursor at EOF
+!rm      delete PATH
+!mv X    move file to X
+$        move cursor to BOF
+^        move cursor to EOF
+@Lid     move cursor after Lid
++X       insert X at the cursor; `+` alone inserts a blank line
+Lid=X    replace whole line with X; `Lid=` blanks it out
+-Lid     delete line (repeat for multi)
+</ops>
+
+<rules>
+- You may have multiple `---PATH` sections to edit multiple files at once.
+- Ops starting with `$` / `^` / `@Lid` do not alter lines; you must still issue an op like `+` afterwards.
+- Consecutive `+X` ops insert consecutive lines.
+- `Lid=X` replaces the whole line. X must be the complete new line, not a fragment.
+- To rewrite multiple adjacent lines, delete each with `-Lid` then emit the new content as `+TEXT` lines. Do not stack `Lid=X` over a contiguous range — it requires the new block to match the old line count and silently corrupts the file when they differ.
+</rules>
+
+<case file="a.ts">
+{{hline 1 "const DEF = \"guest\";"}}
 {{hline 2 ""}}
-{{hline 3 "function beta(x) {"}}
-{{hline 4 "\tif (x) {"}}
-{{hline 5 "\t\treturn parse(data) || fallback;"}}
-{{hline 6 "\t}"}}
-{{hline 7 "\treturn null;"}}
-{{hline 8 "}"}}
-```
-
-# Replace a line with `splice`
-`{path:"a.ts",edits:[{loc:{{href 1 "const tag = \"BAD\";"}},splice:["const tag = \"OK\";"]}]}`
-
-# Combine `pre` + `splice` + `post` in one entry
-`{path:"a.ts",edits:[{loc:{{href 4 "\tif (x) {"}},pre:["\tvalidate();"],splice:["\tif (!x) {"],post:["\t\tlog();"]}]}`
+{{hline 3 "export function label(name) {"}}
+{{hline 4 "\tconst clean = name || DEF;"}}
+{{hline 5 "\treturn clean.trim();"}}
+{{hline 6 "}"}}
+</case>
 
-# Delete a line with `splice: []`
-`{path:"a.ts",edits:[{loc:{{href 7 "\treturn null;"}},splice:[]}]}`
-
-# Preserve a blank line with `splice:[""]`
-`{path:"a.ts",edits:[{loc:{{href 2 ""}},splice:[""]}]}`
-
-# Insert before / after a line
-`{path:"a.ts",edits:[{loc:{{href 3 "function beta(x) {"}},pre:["function gamma() {","\tvalidate();","}",""]}]}`
-
-# Substitute one token with `sed` (regex) — preferred for token-level edits
-Use the smallest `pat` that uniquely identifies the change.
-`{path:"a.ts",edits:[{loc:{{href 5 "\t\treturn parse(data) || fallback;"}},sed:{pat:"\\|\\|",rep:"??"}}]}`
-
-# Substitute literal text — set `F:true` so `pat` is not parsed as regex
-`{path:"a.ts",edits:[{loc:{{href 5 "\t\treturn parse(data) || fallback;"}},sed:{pat:"data",rep:"input",F:true}}]}`
-
-# Comment out a line by capturing the whole content with a regex
-Use `$&` (the entire match) inside `rep` to keep the original text and prepend `// `.
-`{path:"a.ts",edits:[{loc:{{href 7 "\treturn null;"}},sed:{pat:".+",rep:"// $&"}}]}`
-
-# Prepend / append at file edges
-`{path:"a.ts",edits:[{loc:"$",pre:["// Copyright (c) 2026",""]}]}`
-`{path:"a.ts",edits:[{loc:"$",post:["","export const VERSION = \"1.0.0\";"]}]}`
-
-# Cross-file override inside `loc`
-`{path:"a.ts",edits:[{loc:"b.ts:{{href 1 "const tag = \"BAD\";"}}",splice:["const tag = \"OK\";"]}]}`
-
-# WRONG: retyping unchanged neighbors inside `splice` duplicates them
-`{path:"a.ts",edits:[{loc:{{href 4 "\tif (x) {"}},splice:["\tif (x && ready) {","\t\treturn parse(data) ?? fallback;","\t\t//unreachable"]}]}`
-The 2nd array element matches existing line 5, which is **not** overwritten, it shifts, so return statement ends up duplicated.
-
-# RIGHT: split into separate edits
-- `{path:"a.ts",edits:[{loc:{{href 4 "\tif (x) {"}},sed:{pat:"x",rep:"x && ready",g:false}},{loc:{{href 5 "\t\treturn parse(data) ?? fallback;"}},post:["\t\t//unreachable"]}]}`
-OR
-- `{path:"a.ts",edits:[{loc:{{href 4 "\tif (x) {"}},splice:["\tif (x && ready) {"]},{loc:{{href 5 "\t\treturn parse(data) ?? fallback;"}},splice:["\t\treturn parse(data) ?? fallback;","\t\t//unreachable"]}]}`
+<examples>
+# Replace line
+---a.ts
+{{hrefr 5}}=	return clean.trim().toUpperCase();
+
+# Rewrite multiple adjacent lines (delete the old, insert the new)
+---a.ts
+-{{hrefr 3}}
+-{{hrefr 4}}
+-{{hrefr 5}}
+-{{hrefr 6}}
++export function label(name: string): string {
++	return (name || DEF).trim().toUpperCase();
++}
+
+# Append after
+---a.ts
+@{{hrefr 4}}
++	const suffix = "";
+
+# Delete a line
+---a.ts
+-{{hrefr 2}}
+
+# Prepend and append
+---a.ts
+$
++// Copyright (c) 2026
++
+^
++export { DEF };
+
+# File ops
+---a.ts
+!rm
+---b.ts
+!mv a.ts
+
+# Wrong: `@Lid=TEXT` is not replacement syntax
+---a.ts
+@{{hrefr 5}}=	return clean.trim().toUpperCase();
+
+# Wrong: do not split `Lid=TEXT` across lines
+---a.ts
+{{hrefr 5}}=
+	return clean.trim().toUpperCase();
+
+# Wrong: do not replace by deleting then adding
+---a.ts
+-{{hrefr 5}}
++{{hrefr 5}}=	return clean.trim().toUpperCase();
 </examples>
 
 <critical>
-- Make the minimum exact edit.
-- Copy the full anchors exactly as shown by `read/grep` (for example `160sr`, not just `sr`).
-- `loc` chooses the target. Verbs describe what to do there.
-- On a single-anchor `loc`, you may combine `pre`, `splice`, and `post`.
-- `loc:"$"` operates on the whole file: `pre` prepends, `post` appends, `sed` runs across every line.
-- `splice: []` deletes the anchored line. `splice:[""]` preserves a blank line.
-- Within a single request you may submit edits in any order — the runtime applies them bottom-up so they don't shift each other. After any request that mutates a file, anchors below the mutation are stale on disk; re-read before issuing more edits to that file.
-- `splice` operations target the current file content only. Do not try to reference old line text after the file has changed.
-- For **small** in-line edits (renaming a token, flipping an operator, tweaking a literal), prefer `sed` over `splice`. The `loc` anchor already pins the line — repeating the entire line in a `splice` array invites hallucinated content. Use the smallest `pat` that uniquely identifies the change on that line; do not pad it with surrounding text just to feel safe. When `pat` contains regex metacharacters you mean literally (e.g. `||`, `.`, `(`, `?`, `\`), set `F:true` to disable regex. `g` is `false` by default — pass `g:true` to replace every occurrence. For multi-line restructuring (wrapping logic, adding new branches, inserting blocks), use `splice`/`pre`/`post` — do **not** stretch `sed` into a rewrite tool.
-- When you do use `splice`, re-read the anchored line first and copy it verbatim, changing only the required token(s). Anchor identity does not verify line content, so a hallucinated replacement will silently corrupt the file.
-- Anchors are pin points, not region markers. One anchor pins exactly one line. If your change touches N distinct source lines, that is N edits with N anchors — not one big `splice` array intended to cover the whole region. `splice` cannot "replace lines 4 through 7"; it can only splice content in at one anchor.
-- You **MUST NOT** include lines in `splice`/`pre`/`post` that already exist immediately adjacent to the anchor in the current file. `splice` does not overwrite the lines below — they shift down — so any neighbor you re-type in your array becomes a duplicate. If your intended replacement contains content that is already on neighboring source lines, split into multiple edits at each real change site instead of one fat `splice`.
-- Before issuing a multi-line `splice`, mentally diff each array element against the current file lines at and just below the anchor. Any element that matches a line within ~5 lines of the anchor will become a duplicate after the splice. If you find a match, drop that element and use a separate edit (or `pre`/`post`) at the real change point.
-- Text 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.
+- Copy Lids **EXACTLY** from prior tool output. Never guess, shorten, or omit the letters.
+- Only emit lines that change. Never repeat unchanged context — anchors imply it.
+- This is **NOT** unified diff. Never send `@@`, `-OLD` / `+NEW` pairs, or unchanged context.
+- Never split `Lid=TEXT` across two physical lines.
+- Never stack `Lid=X` over a contiguous range. Use `-Lid`+`+TEXT` for block rewrites.
 </critical>

package/src/prompts/tools/bash.md

@@ -29,22 +29,25 @@ Returns output and exit code.
 </output>
 
 <critical>
-You **MUST NOT** use bash for file operations where specialized tools exist:
+You **MUST** use specialized tools instead of bash for any file, directory, or text-search operation. Do **NOT** use Bash to run commands when a relevant dedicated tool is provided — dedicated tools are faster, render diffs, respect `.gitignore`, and let the user review your work. Bash commands matching the patterns below are intercepted and blocked at runtime.
 
 |Instead of (WRONG)|Use (CORRECT)|
 |---|---|
 |`cat file`, `head -n N file`|`read(path="file", limit=N)`|
 |`cat -n file \|sed -n '50,150p'`|`read(path="file", offset=50, limit=100)`|
-{{#if hasGrep}}|`grep -A 20 'pat' file`|`grep(pattern="pat", path="file", post=20)`|
-|`grep -rn 'pat' dir/`|`grep(pattern="pat", path="dir/")`|
-|`rg 'pattern' dir/`|`grep(pattern="pattern", path="dir/")`|{{/if}}
+{{#if hasSearch}}|`grep -A 20 'pat' file`|`search(pattern="pat", path="file", post=20)`|
+|`grep -rn 'pat' dir/`|`search(pattern="pat", path="dir/")`|
+|`rg 'pattern' dir/`|`search(pattern="pattern", path="dir/")`|{{/if}}
 {{#if hasFind}}|`find dir -name '*.ts'`|`find(pattern="dir/**/*.ts")`|{{/if}}
 |`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}}
+- You **MUST NOT** create files with `cat <<EOF`, `echo > file`, or `printf > file`. Use `write` — heredoc content cannot be cached for permission reuse, every revision triggers a fresh review, and there is no diff. This is the most-violated rule.
+- You **MUST NOT** read line ranges with `sed -n 'A,Bp'`, `awk 'NR≥A && NR≤B'`, or `head | tail` pipelines. Use `read` with `offset`/`limit` (or `sel` if available).
 {{#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 `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
+- If you catch yourself typing `cat`, `head`, `tail`, `less`, `more`, `ls`, `grep`, `rg`, `find`, `fd`, `sed -i`, `awk -i`, or a heredoc redirect inside a Bash call, stop and switch to the dedicated tool. There is no scenario where bash is preferable for these operations.
 </critical>

package/src/prompts/tools/checkpoint.md

@@ -1,6 +1,6 @@
 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/grep/find/lsp/etc.) and want to minimize context cost afterward.
+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.

package/src/prompts/tools/find.md

@@ -14,5 +14,10 @@ Matching file paths sorted by modification time (most recent first). Truncated a
 </examples>
 
 <avoid>
-For open-ended searches requiring multiple rounds of globbing and grepping, you **MUST** use Task tool instead.
+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. Do **NOT** shell out to `find`, `fd`, `locate`, `ls`, or `git ls-files` via Bash — they ignore `.gitignore`, blow past result limits, and waste tokens.
+- If you catch yourself typing `find -name`, `fd`, or `ls **/*.ext` in a Bash command, stop and re-issue the lookup through the Find tool with a glob pattern instead.
+</critical>

package/src/prompts/tools/hashline.md

@@ -5,10 +5,9 @@ Read the file first. Copy the full anchors exactly as shown by `read`.
 <operations>
 **Top level**
 - `edits` — array of edit entries
-- `path` (optional) — default file path used when an entry omits its own `path`. Lets you share the path across many edits in one request.
+- `path` (required) — file path for all edits in this request
 
-**Edit entry**: `{ path?, loc, content }`
-- `path` — file path (omit to fall back to the request-level `path`)
+**Edit entry**: `{ loc, content }`
 - `loc` — where to apply the edit (see below)
 - `content` — replacement/inserted lines (`string[]`, one element per line; `null` to delete)
 
@@ -44,24 +43,24 @@ All examples below reference the same file:
 
 # Replace a block body
 Replace only the catch body. Do not target the shared boundary line `} catch (err) {`.
-`{edits:[{path:"a.ts",loc:{range:{pos:{{href 15 "\t\tconsole.error(err);"}},end:{{href 16 "\t\treturn null;"}}}},content:["\t\tif (isEnoent(err)) return null;","\t\tthrow err;"]}]}`
+`{path:"a.ts",edits:[{loc:{range:{pos:{{href 15}},end:{{href 16}}}},content:["\t\tif (isEnoent(err)) return null;","\t\tthrow err;"]}]}`
 # Replace whole block including closing brace
-Replace `alpha`'s entire body including the closing `}`. `end` **MUST** be {{href 7 "}"}} because `content` includes `}`.
-`{edits:[{path:"a.ts",loc:{range:{pos:{{href 6 "\tlog();"}},end:{{href 7 "}"}}}},content:["\tvalidate();","\tlog();","}"]}]}`
-**Wrong**: `end: {{href 6 "\tlog();"}}` — line 7 (`}`) survives AND content emits `}`, producing two closing braces.
+Replace `alpha`'s entire body including the closing `}`. `end` **MUST** be {{href 7}} because `content` includes `}`.
+`{path:"a.ts",edits:[{loc:{range:{pos:{{href 6}},end:{{href 7}}}},content:["\tvalidate();","\tlog();","}"]}]}`
+**Wrong**: `end: {{href 6}}` — line 7 (`}`) survives AND content emits `}`, producing two closing braces.
 # Replace one line
 Single-line replace uses `pos == end`.
-`{edits:[{path:"a.ts",loc:{range:{pos:{{href 2 "const timeout = 5000;"}},end:{{href 2 "const timeout = 5000;"}}}},content:["const timeout = 30_000;"]}]}`
+`{path:"a.ts",edits:[{loc:{range:{pos:{{href 2}},end:{{href 2}}}},content:["const timeout = 30_000;"]}]}`
 # Delete a range
-`{edits:[{path:"a.ts",loc:{range:{pos:{{href 10 "\t// TODO: remove after migration"}},end:{{href 11 "\tlegacy();"}}}},content:null}]}`
+`{path:"a.ts",edits:[{loc:{range:{pos:{{href 10}},end:{{href 11}}}},content:null}]}`
 # Insert before a sibling
 When adding a sibling declaration, prefer `prepend` on the next declaration.
-`{edits:[{path:"a.ts",loc:{prepend:{{href 9 "function beta() {"}}},content:["function gamma() {","\tvalidate();","}",""]}]}`
+`{path:"a.ts",edits:[{loc:{prepend:{{href 9}}},content:["function gamma() {","\tvalidate();","}",""]}]}`
 </examples>
 
 <critical>
 - Make the minimum exact edit.
-- Copy the full anchors exactly as shown by `read/grep` (for example `160sr`, not just `sr`).
+- Copy the full anchors exactly as shown by `read/search` (for example `160sr`, not just `sr`).
 - `range` requires both `pos` and `end`.
 - **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.

package/src/prompts/tools/patch.md

@@ -18,19 +18,19 @@ When editing structured blocks (nested braces, tags, indented regions), include
 
 <parameters>
 ```ts
-// Input is { edits: Entry[] } where Entry is one of:
+// Input is { path: string, edits: Entry[] }. `path` is required and applies to every entry.
 type Entry =
-   // Diff is one or more hunks in the same file.
+   // 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 -).
-   | { path: string, op: "update", diff: string }
+   | { op: "update", diff: string }
    // Diff is full file content, no prefixes.
-   | { path: string, op: "create", diff: string }
+   | { op: "create", diff: string }
    // No diff for delete.
-   | { path: string, op: "delete" }
-   // New path for update+move.
-   | { path: string, op: "update", rename: string, diff: string }
+   | { op: "delete" }
+   // New path for update+move from the top-level path.
+   | { op: "update", rename: string, diff: string }
 ```
 </parameters>
 
@@ -52,15 +52,15 @@ Returns success/failure; on failure, error message indicates:
 
 <examples>
 # Create
-`edit {"edits":[{"path":"hello.txt","op":"create","diff":"Hello\n"}]}`
+`edit {"path":"hello.txt","edits":[{"op":"create","diff":"Hello\n"}]}`
 # Update
-`edit {"edits":[{"path":"src/app.py","op":"update","diff":"@@ def greet():\n def greet():\n-print('Hi')\n+print('Hello')\n"}]}`
+`edit {"path":"src/app.py","edits":[{"op":"update","diff":"@@ def greet():\n def greet():\n-print('Hi')\n+print('Hello')\n"}]}`
 # Rename
-`edit {"edits":[{"path":"src/app.py","op":"update","rename":"src/main.py","diff":"@@\n …\n"}]}`
+`edit {"path":"src/app.py","edits":[{"op":"update","rename":"src/main.py","diff":"@@\n …\n"}]}`
 # Delete
-`edit {"edits":[{"path":"obsolete.txt","op":"delete"}]}`
-# Multi-file
-`edit {"edits":[{"path":"src/types.ts","op":"update","diff":"@@\n-old\n+new\n"},{"path":"src/index.ts","op":"update","diff":"@@\n-old\n+new\n"}]}`
+`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>

package/src/prompts/tools/read.md

@@ -23,7 +23,7 @@ The `read` tool is multi-purpose and more capable than it looks — inspects fil
 # Filesystem
 - Reading a directory path returns a list of dirents.
 {{#if IS_HASHLINE_MODE}}
-- Reading a file returns lines prefixed with anchors (line # .. hash .. | .. line content): `41th|def alpha():`
+- Reading a file returns lines prefixed with anchors (line+hash): `41th|def alpha():`
 {{else}}
 {{#if IS_LINE_NUMBER_MODE}}
 - Reading a file returns lines prefixed with line numbers: `41|def alpha():`
@@ -50,9 +50,9 @@ Extracts content from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, R
 </instruction>
 
 <critical>
-- You **MUST** use `read` for all file, directory, archive, and URL reads; never cat/head/ls/tar/unzip/curl, etc.
-You **MUST** prefer `read` over a browser/puppeteer tool for fetching URL content; only use a browser if this method fails to deliver reasonable content.
-- You **MUST** always include the `path` parameter.
-- For specific line ranges, use `sel`.
+- You **MUST** use `read` for every file, directory, archive, and URL read. `cat`, `head`, `tail`, `less`, `more`, `ls`, `tar`, `unzip`, `curl`, and `wget` are **FORBIDDEN** for inspection — 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 fetching URL content; only use a browser if `read` fails to deliver reasonable content.
+- You **MUST** always include the `path` parameter — never call `read` with an empty argument object `{}`.
+- For specific line ranges, use `sel` (e.g. `sel="50-200"`, `sel="50+150"`) — do **NOT** reach for `sed -n`, `awk NR`, or `head`/`tail` pipelines.
 - You **MAY** use `sel` with URL reads; the tool paginates cached fetched output.
 </critical>

package/src/prompts/tools/replace.md

@@ -1,9 +1,9 @@
 Performs string replacements in files with fuzzy whitespace matching.
 
 <instruction>
-- You **MUST** use the smallest edit that uniquely identifies the change
-- If `old_text` not unique, you **MUST** expand to include more context or use `all: true` to replace all occurrences
-- Fuzzy matching handles minor whitespace/indentation differences automatically
+- 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>
 

package/src/prompts/tools/{grep.md → search.md}

@@ -17,8 +17,8 @@ Searches files using powerful regex matching.
 </output>
 
 <critical>
-- You **MUST** use the built-in Grep tool for any content search. Do **NOT** 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 Grep 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 search through the Grep tool instead.
-- If the search is open-ended, requiring multiple rounds, you **MUST** use the Task tool with the explore subagent instead of chaining Grep calls yourself.
+- You **MUST** use the built-in `search` tool for any content search. Do **NOT** 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>

package/src/sdk.ts

@@ -66,6 +66,7 @@ import {
 	InternalUrlRouter,
 	JobsProtocolHandler,
 	LocalProtocolHandler,
+	type LocalProtocolOptions,
 	McpProtocolHandler,
 	MemoryProtocolHandler,
 	PiProtocolHandler,
@@ -111,7 +112,6 @@ import {
 	discoverStartupLspServers,
 	EditTool,
 	FindTool,
-	GrepTool,
 	getSearchTools,
 	HIDDEN_TOOLS,
 	isSearchProviderPreference,
@@ -121,10 +121,12 @@ import {
 	ReadTool,
 	ResolveTool,
 	renderSearchToolBm25Description,
+	SearchTool,
 	setPreferredImageProvider,
 	setPreferredSearchProvider,
 	type Tool,
 	type ToolSession,
+	WebSearchTool,
 	WriteTool,
 	warmupLspServers,
 } from "./tools";
@@ -226,6 +228,9 @@ export interface CreateAgentSessionOptions {
 	/** Session manager. Default: session stored under the configured agentDir sessions root */
 	sessionManager?: SessionManager;
 
+	/** Override local:// protocol options for subagent local:// sharing. Default: uses the session's own artifacts dir and session ID. */
+	localProtocolOptions?: LocalProtocolOptions;
+
 	/** Settings instance. Default: Settings.init({ cwd, agentDir }) */
 	settings?: Settings;
 
@@ -271,13 +276,14 @@ export {
 	createTools,
 	EditTool,
 	FindTool,
-	GrepTool,
 	HIDDEN_TOOLS,
 	loadSshTool,
 	PythonTool,
 	ReadTool,
 	ResolveTool,
+	SearchTool,
 	type ToolSession,
+	WebSearchTool,
 	WriteTool,
 };
 
@@ -996,10 +1002,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			}),
 		);
 		internalRouter.register(
-			new LocalProtocolHandler({
-				getArtifactsDir,
-				getSessionId: () => sessionManager.getSessionId(),
-			}),
+			new LocalProtocolHandler(
+				options.localProtocolOptions ?? {
+					getArtifactsDir,
+					getSessionId: () => sessionManager.getSessionId(),
+				},
+			),
 		);
 		internalRouter.register(
 			new SkillProtocolHandler({
@@ -1386,7 +1394,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			? requestedActiveToolNames
 			: requestedActiveToolNames.filter(name => !defaultInactiveToolNames.has(name));
 		const explicitlyRequestedMCPToolNames = options.toolNames
-			? requestedActiveToolNames.filter(name => name.startsWith("mcp_"))
+			? requestedActiveToolNames.filter(name => name.startsWith("mcp__"))
 			: [];
 		const discoveryDefaultServers = new Set(
 			(settings.get("mcp.discoveryDefaultServers") ?? []).map(serverName => serverName.trim()).filter(Boolean),
@@ -1412,7 +1420,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				: [...new Set([...restoredSelectedMCPToolNames, ...defaultSelectedMCPToolNames])];
 			initialToolNames = [
 				...new Set([
-					...initialRequestedActiveToolNames.filter(name => !name.startsWith("mcp_")),
+					...initialRequestedActiveToolNames.filter(name => !name.startsWith("mcp__")),
 					...initialSelectedMCPToolNames,
 				]),
 			];
@@ -1424,7 +1432,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			...registeredTools.filter(t => !t.definition.defaultInactive).map(t => t.definition.name),
 		];
 		for (const name of alwaysInclude) {
-			if (mcpDiscoveryEnabled && name.startsWith("mcp_")) {
+			if (mcpDiscoveryEnabled && name.startsWith("mcp__")) {
 				continue;
 			}
 			if (toolRegistry.has(name) && !initialToolNames.includes(name)) {
@@ -1601,6 +1609,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			ttsrManager,
 			obfuscator,
 			asyncJobManager,
+			agentId: resolvedAgentId,
+			agentRegistry,
 		});
 		hasSession = true;
 

package/src/session/agent-session.ts

@@ -130,6 +130,7 @@ import planModeToolDecisionReminderPrompt from "../prompts/system/plan-mode-tool
 	type: "text",
 };
 import ttsrInterruptTemplate from "../prompts/system/ttsr-interrupt.md" with { type: "text" };
+import { type AgentRegistry, MAIN_AGENT_ID } from "../registry/agent-registry";
 import { deobfuscateSessionContext, type SecretObfuscator } from "../secrets/obfuscator";
 import { resolveThinkingLevelForModel, toReasoningEffort } from "../thinking";
 import { assertEditableFile } from "../tools/auto-generated-guard";
@@ -196,7 +197,8 @@ export type AgentSessionEvent =
 	| { type: "retry_fallback_succeeded"; model: string; role: string }
 	| { type: "ttsr_triggered"; rules: Rule[] }
 	| { type: "todo_reminder"; todos: TodoItem[]; attempt: number; maxAttempts: number }
-	| { type: "todo_auto_clear" };
+	| { type: "todo_auto_clear" }
+	| { type: "irc_message"; message: CustomMessage };
 
 /** Listener function for agent session events */
 export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
@@ -262,6 +264,10 @@ export interface AgentSessionConfig {
 	obfuscator?: SecretObfuscator;
 	/** Logical owner for retained Python kernels created by this session. */
 	pythonKernelOwnerId?: string;
+	/** Agent identity (registry id like "0-Main" or "3-Alice") used for IRC routing. */
+	agentId?: string;
+	/** Shared agent registry (for forwarding IRC observations to the main session UI). */
+	agentRegistry?: AgentRegistry;
 }
 
 /** Options for AgentSession.prompt() */
@@ -477,6 +483,9 @@ export class AgentSession {
 	// Drained into history (via emitExternalEvent) once the recipient becomes idle.
 	#pendingBackgroundExchanges: CustomMessage[][] = [];
 	#scheduledBackgroundExchangeFlush = false;
+	// Agent identity + registry for IRC relay forwarding to the main session UI.
+	#agentId: string | undefined;
+	#agentRegistry: AgentRegistry | undefined;
 	// Extension system
 	#extensionRunner: ExtensionRunner | undefined = undefined;
 	#turnIndex = 0;
@@ -610,6 +619,8 @@ export class AgentSession {
 		);
 		this.#ttsrManager = config.ttsrManager;
 		this.#obfuscator = config.obfuscator;
+		this.#agentId = config.agentId;
+		this.#agentRegistry = config.agentRegistry;
 		this.agent.setAssistantMessageEventInterceptor((message, assistantMessageEvent) => {
 			const event: AgentEvent = {
 				type: "message_update",
@@ -5997,6 +6008,14 @@ export class AgentSession {
 			attribution: "agent",
 			timestamp: incomingTimestamp,
 		};
+		void this.#emitSessionEvent({ type: "irc_message", message: incomingRecord });
+		this.#forwardIrcRelayToMain({
+			from: args.from,
+			to: this.#agentId ?? "?",
+			body: args.message,
+			kind: "message",
+			timestamp: incomingTimestamp,
+		});
 
 		if (!awaitReply) {
 			this.#queueBackgroundExchangeInjection([incomingRecord]);
@@ -6021,11 +6040,60 @@ export class AgentSession {
 			attribution: "agent",
 			timestamp: Date.now(),
 		};
+		void this.#emitSessionEvent({ type: "irc_message", message: replyRecord });
+		this.#forwardIrcRelayToMain({
+			from: this.#agentId ?? "?",
+			to: args.from,
+			body: replyText,
+			kind: "reply",
+			timestamp: replyRecord.timestamp,
+		});
 		this.#queueBackgroundExchangeInjection([incomingRecord, replyRecord]);
 
 		return { replyText };
 	}
 
+	/**
+	 * Forward an IRC exchange observation to the main agent's session UI so the
+	 * user can see every IRC conversation in the main transcript, even when the
+	 * main agent is not a direct participant. The relay record is display-only:
+	 * it is NOT injected into the main agent's persisted history.
+	 */
+	#forwardIrcRelayToMain(args: {
+		from: string;
+		to: string;
+		body: string;
+		kind: "message" | "reply";
+		timestamp: number;
+	}): void {
+		const registry = this.#agentRegistry;
+		if (!registry) return;
+		// If this session is the main agent, the local emit already reached the main UI.
+		if (this.#agentId === MAIN_AGENT_ID) return;
+		const mainRef = registry.get(MAIN_AGENT_ID);
+		const mainSession = mainRef?.session;
+		if (!mainSession || mainSession === this) return;
+		const arrow = args.kind === "reply" ? "\u2192 (auto)" : "\u2192";
+		const relayRecord: CustomMessage = {
+			role: "custom",
+			customType: "irc:relay",
+			content: `[IRC \`${args.from}\` ${arrow} \`${args.to}\`]\n\n${args.body}`,
+			display: true,
+			details: { from: args.from, to: args.to, body: args.body, kind: args.kind },
+			attribution: "agent",
+			timestamp: args.timestamp,
+		};
+		mainSession.emitIrcRelayObservation(relayRecord);
+	}
+
+	/**
+	 * Emit an IRC relay observation event on this session for UI rendering only.
+	 * Does not persist the record to history. Public so other sessions can forward.
+	 */
+	emitIrcRelayObservation(record: CustomMessage): void {
+		void this.#emitSessionEvent({ type: "irc_message", message: record });
+	}
+
 	/**
 	 * Run a single ephemeral side-channel turn against this session's current
 	 * model + system prompt + history.  No tools are used; the side request