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

package/src/prompts/tools/atom.md

@@ -1,76 +1,94 @@
-Applies precise file edits using anchors (line+hash).
+Your patch language is a compact, file-oriented edit format.
 
-<ops>
-Each call **MUST** have shape `{path:"a.ts",edits:[…]}`. `path` is the default file; you **MAY** override it per edit with `loc:"b.ts:160sr"`.
-Each edit **MUST** have exactly one `loc` and **MUST** include one or more verbs.
-
-# Locators
-- `"A"` targets one anchored line. `"$"` targets the whole file: `pre` = BOF, `post` = EOF, `sed` = every line.
-- Bracketed locators are **`splice` only** and select a balanced region around anchor `A`.
-- `"(A)"` = block body. `"[A]"` = whole block/node.
-- `"[A"` / `"(A"` = tail after/including anchor, closer excluded.
-- `"A]"` / `"A)"` = head through/before anchor, opener excluded.
-- Anchor bracketed forms on a body line of the intended block, not the opener line.
-- Do not use bracketed locators on files that do not currently parse.
+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`).
 
-# Verbs
-- `splice:[…]` replaces the anchored line, or the bracketed region. `[]` deletes; `[""]` makes a blank line.
-- `pre:[…]` inserts before the anchor, or BOF with `loc:"$"`.
-- `post:[…]` inserts after the anchor, or EOF with `loc:"$"`.
+<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>
 
-<splice>
-Replaces the anchored line, or the bracketed region.
-- `[]` deletes. `[""]` leaves a blank line.
-- For bracketed `splice`, write body at column 0, it will be re-indented.
-- Do not use bracketed `splice` on broken files, or for single line edits.
-</splice>
-
-<sed>
-Use for tiny inline edits: names, operators, literals.
-- Keep `pat` as short as possible, it does not have to be unique.
-- `g:false` by default; set to replace all instead of first.
-</sed>
+<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>
 
-<examples>
-```ts title="a.ts"
-{{hline 1 "const FALLBACK = \"guest\";"}}
+<case file="a.ts">
+{{hline 1 "const DEF = \"guest\";"}}
 {{hline 2 ""}}
 {{hline 3 "export function label(name) {"}}
-{{hline 4 "\tconst clean = name || FALLBACK;"}}
-{{hline 5 "\treturn clean.trim().toLowerCase();"}}
+{{hline 4 "\tconst clean = name || DEF;"}}
+{{hline 5 "\treturn clean.trim();"}}
 {{hline 6 "}"}}
-```
+</case>
+
+<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();
 
-# Single-line replacement:
-`{path:"a.ts",edits:[{loc:{{href 1 "const FALLBACK = \"guest\";"}},splice:["const FALLBACK = \"anonymous\";"]}]}`
-# Small token edit: prefer `sed`:
-`{path:"a.ts",edits:[{loc:{{href 5 "\treturn clean.trim().toLowerCase();"}},sed:{pat:"toLowerCase",rep:"toUpperCase"}}]}`
-# Insert before / after an anchor:
-`{path:"a.ts",edits:[{loc:{{href 5 "\treturn clean.trim().toLowerCase();"}},pre:["\tif (!clean) return FALLBACK;"],post:["\t// normalized label"]}]}`
-# Delete a line vs make it blank:
-`{path:"a.ts",edits:[{loc:{{href 2 ""}},splice:[]}]}`
-`{path:"a.ts",edits:[{loc:{{href 2 ""}},splice:[""]}]}`
-# File edges:
-`{path:"a.ts",edits:[{loc:"$",pre:["// Copyright (c) 2026",""]}]}`
-`{path:"a.ts",edits:[{loc:"$",post:["","export { FALLBACK };"]}]}`
-# Cross-file override:
-`{path:"a.ts",edits:[{loc:{{href 1 "const FALLBACK = \"guest\";" "config.ts:" ""}},splice:["const FALLBACK = \"anonymous\";"]}]}`
-# Body replacement: use bracketed `splice`, write body at column 0:
-`{path:"a.ts",edits:[{loc:{{href 4 "\tconst clean = name || FALLBACK;" "(" ")"}},splice:["if (name == null) return FALLBACK;","const clean = String(name).trim();","return clean || FALLBACK;"]}]}`
-# Whole function replacement: anchor on a body line:
-`{path:"a.ts",edits:[{loc:{{href 5 "\treturn clean.trim().toLowerCase();" "[" "]"}},splice:["export function label(name) {","\treturn String(name ?? FALLBACK).trim().toLowerCase();","}"]}]}`
-# WRONG: bare-anchor `splice` does not own neighboring lines:
-`{path:"a.ts",edits:[{loc:{{href 4 "\tconst clean = name || FALLBACK;"}},splice:["\tconst clean = String(name ?? FALLBACK).trim();","\treturn clean.toLowerCase();"]}]}`
-This replaces only line 4. Original line 5 still shifts down, so the function now has two returns.
-# RIGHT: use a body edit for that rewrite:
-`{path:"a.ts",edits:[{loc:{{href 4 "\tconst clean = name || FALLBACK;" "(" ")"}},splice:["const clean = String(name ?? FALLBACK).trim();","return clean.toLowerCase();"]}]}`
+# Wrong: do not replace by deleting then adding
+---a.ts
+-{{hrefr 5}}
++{{hrefr 5}}=	return clean.trim().toUpperCase();
 </examples>
 
 <critical>
-- You **MUST** copy full anchors exactly from a read op (e.g. `160sr`); you **MUST NOT** send only the 2-letter suffix.
-- You **MUST** make the minimum exact edit; you **MUST NOT** reformat unrelated code.
-- A bare anchor **MUST** target one line only; you **MUST** use bracketed `splice` for balanced block rewrites.
-- You **MUST NOT** include unchanged adjacent lines in `splice`/`pre`/`post`; they shift and duplicate.
-- For bracketed `splice`, replacement braces **MUST** be balanced for the selected region.
+- 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

@@ -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";
@@ -263,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() */
@@ -478,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;
@@ -611,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",
@@ -5999,6 +6009,13 @@ export class AgentSession {
 			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]);
@@ -6024,11 +6041,59 @@ export class AgentSession {
 			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

package/src/system-prompt.ts

@@ -384,6 +384,8 @@ export async function loadSystemPromptFiles(options: LoadContextFilesOptions = {
 export interface SystemPromptToolMetadata {
 	label: string;
 	description: string;
+	/** Tool name the model sees on the provider wire. Defaults to the internal tool name. */
+	wireName?: string;
 }
 
 export function buildSystemPromptToolMetadata(
@@ -394,12 +396,16 @@ export function buildSystemPromptToolMetadata(
 		Array.from(tools.entries(), ([name, tool]) => {
 			const toolRecord = tool as AgentTool & { label?: string; description?: string };
 			const override = overrides[name];
+			const wireName =
+				override?.wireName ??
+				(typeof toolRecord.customWireName === "string" ? toolRecord.customWireName : undefined);
 			return [
 				name,
 				{
 					label: override?.label ?? (typeof toolRecord.label === "string" ? toolRecord.label : ""),
 					description:
 						override?.description ?? (typeof toolRecord.description === "string" ? toolRecord.description : ""),
+					wireName,
 				},
 			] as const;
 		}),
@@ -570,14 +576,17 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		}
 	}
 
-	// Build tool descriptions for system prompt rendering
+	// Build tool descriptions for system prompt rendering.
+	const toolPromptNames = new Map<string, string>(toolNames.map(name => [name, tools?.get(name)?.wireName ?? name]));
+	const toolRefs = Object.fromEntries(toolPromptNames.entries());
 	const toolInfo = toolNames.map(name => ({
-		name,
+		name: toolPromptNames.get(name) ?? name,
+		internalName: name,
 		label: tools?.get(name)?.label ?? "",
 		description: tools?.get(name)?.description ?? "",
 	}));
 
-	// Filter skills to only include those with read tool
+	// Filter skills to only include those with read tool.
 	const hasRead = tools?.has("read");
 	const filteredSkills = hasRead ? skills : [];
 
@@ -589,6 +598,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 	const injectedAlwaysApplyRules = dedupeAlwaysApplyRules(alwaysApplyRules, promptSources);
 
 	const environment = await logger.time("getEnvironmentInfo", getEnvironmentInfo);
+	const reportToolIssueToolName = toolPromptNames.get("report_tool_issue") ?? "report_tool_issue";
 	const data = {
 		systemPromptCustomization: effectiveSystemPromptCustomization,
 		customPrompt: resolvedCustomPrompt,
@@ -596,6 +606,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		tools: toolNames,
 		toolInfo,
 		repeatToolDescriptions,
+		toolRefs,
 		environment,
 		contextFiles,
 		agentsMdSearch,
@@ -617,8 +628,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 
 	// When autoqa is active the report_tool_issue tool is in the tool set — nudge the agent.
 	if (toolNames.includes("report_tool_issue")) {
-		rendered +=
-			"\n\n<critical>\nThe `report_tool_issue` tool is available for automated QA. If ANY tool you call returns output that is unexpected, incorrect, malformed, or otherwise inconsistent with what you anticipated given the tool's described behavior and your parameters, call `report_tool_issue` with the tool name and a concise description of the discrepancy. Do not hesitate to report — false positives are acceptable.\n</critical>";
+		rendered += `\n\n<critical>\nThe \`${reportToolIssueToolName}\` tool is available for automated QA. If ANY tool you call returns output that is unexpected, incorrect, malformed, or otherwise inconsistent with what you anticipated given the tool's described behavior and your parameters, call \`${reportToolIssueToolName}\` with the tool name and a concise description of the discrepancy. Do not hesitate to report — false positives are acceptable.\n</critical>`;
 	}
 
 	return rendered;