@oh-my-pi/pi-coding-agent 14.4.0 → 14.4.3

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

@@ -18,6 +18,7 @@ Performs structural code search using AST matching via native ast-grep.
 
 <output>
 - Grouped matches with file path, byte range, line/column ranges, metavariable captures
+- Match lines are anchor-prefixed: `*LINE+ID|content` for the matched line and ` LINE+ID|content` (leading space) for surrounding context
 - Summary counts (`totalMatches`, `filesWithMatches`, `filesSearched`) and parse issues when present
 </output>
 

package/src/prompts/tools/atom.md

@@ -7,90 +7,92 @@ Read the file first. Copy the full anchors exactly as shown by `read`.
 
 Each entry has one shared locator plus one or more verbs:
 - `loc: "160sr"` — single anchored line
-- `loc: "^"` — beginning of file (only valid with `pre`)
-- `loc: "$"` — end of file (only valid with `post`)
+- `loc: "$"` — whole file: `pre` prepends, `post` appends, `sed` substitutes across every line
 - `loc: "a.ts:160sr"` — cross-file override inside the locator
 
 Verbs:
-- `set: ["…"]` — replace the anchor line
-- `pre: ["…"]` — insert before the anchor line (or at BOF when `loc:"^"`)
-- `post: ["…"]` — insert after the anchor line (or at EOF when `loc:"$"`)
+- `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: "s/foo/bar/"` — sed-style substitution applied to the anchor line. **Prefer this over `splice` for token-level changes**
+Flags: `g` (all occurrences), `i` (case-insensitive), `F` (literal).
+Delimiter is whatever character follows `s`.
+You **MUST** keep the pattern as short as possible.
 
 Combination rules:
-- On a single-anchor `loc`, you may combine `pre`, `set`, and `post` in the same entry.
-- `set: []` on a single-anchor `loc` deletes that line.
-- `set:[""]` is **not** delete — it replaces the line with a blank line.
+- 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 "// @ts-ignore"}}
-{{hline  2 "const timeout = 5000;"}}
-{{hline  3 "const tag = \"DO NOT SHIP\";"}}
-{{hline  4 "const fallback = group.targetFramework || 'All Frameworks';"}}
-{{hline  5 "function alpha() {"}}
-{{hline  6 "\tlog();"}}
-{{hline  7 "}"}}
-{{hline  8 ""}}
-{{hline  9 "function beta(x) {"}}
-{{hline 10 "\tif (x) {"}}
-{{hline 11 "\t\treturn parse(data);"}}
-{{hline 12 "\t}"}}
-{{hline 13 "\treturn null;"}}
-{{hline 14 "}"}}
+{{hline 1 "const tag = \"BAD\";"}}
+{{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 "}"}}
 ```
 
-# Swap an operator by replacing the line
-Original line 4: `const fallback = group.targetFramework || 'All Frameworks';`
-`{path:"a.ts",edits:[{loc:{{href 4 "const fallback = group.targetFramework || 'All Frameworks';"}},set:["const fallback = group.targetFramework ?? 'All Frameworks';"]}]}`
+# Replace a line with `splice`
+`{path:"a.ts",edits:[{loc:{{href 1 "const tag = \"BAD\";"}},splice:["const tag = \"OK\";"]}]}`
 
-# Flip a literal by replacing the line
-Original line 2: `const timeout = 5000;`
-`{path:"a.ts",edits:[{loc:{{href 2 "const timeout = 5000;"}},set:["const timeout = 30_000;"]}]}`
+# Combine `pre` + `splice` + `post` in one entry
+`{path:"a.ts",edits:[{loc:{{href 4 "\tif (x) {"}},pre:["\tvalidate();"],splice:["\tif (!x) {"],post:["\t\tlog();"]}]}`
 
-# Negate a condition by replacing the line
-Original line 10: `\tif (x) {`
-`{path:"a.ts",edits:[{loc:{{href 10 "\tif (x) {"}},set:["\tif (!x) {"]}]}`
+# Delete a line with `splice: []`
+`{path:"a.ts",edits:[{loc:{{href 7 "\treturn null;"}},splice:[]}]}`
 
-# Combine `pre` + `set` + `post` in one entry
-`{path:"a.ts",edits:[{loc:{{href 6 "\tlog();"}},pre:["\tvalidate();"],set:["\tlog();"],post:["\tcleanup();"]}]}`
+# Preserve a blank line with `splice:[""]`
+`{path:"a.ts",edits:[{loc:{{href 2 ""}},splice:[""]}]}`
 
-# Replace one whole line with `set`
-Use `set` to replace the full anchored line, preserving any unchanged surrounding lines yourself.
-`{path:"a.ts",edits:[{loc:{{href 3 "const tag = \"DO NOT SHIP\";"}},set:["const tag = \"OK\";"]}]}`
-
-# Replace multiple non-adjacent lines
-`{path:"a.ts",edits:[{loc:{{href 11 "\t\treturn parse(data);"}},set:["\t\treturn parse(data) ?? fallback;"]},{loc:{{href 13 "\treturn null;"}},set:["\treturn fallback;"]}]}`
-
-# Delete a line with `set: []`
-`{path:"a.ts",edits:[{loc:{{href 11 "\t\treturn parse(data);"}},set:[]}]}`
+# Insert before / after a line
+`{path:"a.ts",edits:[{loc:{{href 3 "function beta(x) {"}},pre:["function gamma() {","\tvalidate();","}",""]}]}`
 
-# Preserve a blank line with `set:[""]`
-`{path:"a.ts",edits:[{loc:{{href 8 ""}},set:[""]}]}`
+# Substitute one token with `sed` (regex) — preferred for token-level edits
+Use the smallest pattern that uniquely identifies the change.
+`{path:"a.ts",edits:[{loc:{{href 5 "\t\treturn parse(data) || fallback;"}},sed:"s/\\|\\|/??/"}]}`
 
-# Insert before / after a line
-`{path:"a.ts",edits:[{loc:{{href 9 "function beta(x) {"}},pre:["function gamma() {","\tvalidate();","}",""]}]}`
-`{path:"a.ts",edits:[{loc:{{href 6 "\tlog();"}},post:["\tvalidate();"]}]}`
+# Substitute every occurrence with `sed` (literal/fixed-string)
+Use the `F` flag to disable regex; the delimiter can be any non-alphanumeric char.
+`{path:"a.ts",edits:[{loc:{{href 5 "\t\treturn parse(data) || fallback;"}},sed:"s|data|input|gF"}]}`
 
 # Prepend / append at file edges
-`{path:"a.ts",edits:[{loc:"^",pre:["// Copyright (c) 2026",""]}]}`
+`{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 2 "const timeout = 5000;"}}",set:["const timeout = 30_000;"]}]}`
+`{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:"s/x/x \\&\\& ready/"},{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>
 
 <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`, `set`, and `post`.
-- `loc:"^"` only supports `pre`. `loc:"$"` only supports `post`.
-- `set: []` deletes the anchored line. `set:[""]` preserves a blank line.
+- 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.
-- `set` operations target the current file content only. Do not try to reference old line text after the file has changed.
+- `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 `sed` pattern that uniquely identifies the change on that line; do not pad it with surrounding text just to feel safe. 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.
 </critical>

package/src/prompts/tools/bash.md

@@ -14,10 +14,10 @@ Executes bash command in shell session for terminal operations like git, bun, ca
 - 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.
+- Inspect background jobs with `read jobs://` (`read jobs://<job-id>` for detail). To wait for results, call `job` (with `poll`) — do NOT poll `read jobs://` in a loop or yield and hope for delivery.
 {{else}}
 {{#if autoBackgroundEnabled}}
-- For auto-backgrounded jobs, inspect with `read jobs://` and call `poll` to wait — do NOT poll in a loop.
+- For auto-backgrounded jobs, inspect with `read jobs://` and call `job` (with `poll`) to wait — do NOT poll in a loop.
 {{/if}}
 {{/if}}
 </instruction>

package/src/prompts/tools/grep.md

@@ -8,20 +8,17 @@ Searches files using powerful regex matching.
 
 <output>
 {{#if IS_HASHLINE_MODE}}
-- Text output is anchor-prefixed: `123th:content` (match) or `123th-content` (context). The 2-letter ID is a content fingerprint.
+- Text output is anchor-prefixed: `*123th|content` (match) or ` 123th|content` (context, leading space). The 2-letter ID is a content fingerprint.
 {{else}}
 {{#if IS_LINE_NUMBER_MODE}}
 - Text output is line-number-prefixed
 {{/if}}
 {{/if}}
-{{#if IS_CHUNK_MODE}}
-- Text output is chunk-path-prefixed: `path:sel>123th:content`
-{{/if}}
 </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` returns raw text without chunk paths, 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.
+- 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.
 </critical>

package/src/prompts/tools/irc.md

@@ -0,0 +1,49 @@
+Sends short text messages to other live agents in this process and receives their prose replies.
+
+<instruction>
+- The main agent is addressable as `0-Main`. Subagents reuse their task id (e.g. `0-AuthLoader`).
+- `op: "list"` returns the current set of visible peers. Use it before sending if you are not sure who is live.
+- `op: "send"` delivers `message` to `to`. `to` may be a specific id or `"all"` to broadcast.
+- The recipient generates the reply via an ephemeral side-channel turn that uses their current model, system prompt, and history — it does **not** wait for the recipient's main loop to be free, so it is safe to IRC an agent that is currently inside a long-running tool call.
+- The exchange (incoming question + auto-reply) is queued for injection into the recipient's persisted history; the recipient sees it on its next turn and can follow up if needed.
+</instruction>
+
+<when_to_use>
+You **SHOULD** reach for `irc` proactively when continuing alone is wasteful or wrong. When in doubt, prefer messaging.
+- **Unexpected state.** You hit something the original task did not describe — a missing file, a config that contradicts the assignment, an API behaving differently than you were told, a tool failing in a way that suggests the spec is wrong. DM `0-Main` (or the spawning agent) for guidance instead of guessing.
+- **Blocked by another agent.** A peer holds the file/branch/resource you need, has already started the change you are about to make, or owns a decision you depend on. DM that peer (or broadcast to discover who) before duplicating or stepping on work.
+- **Decision points outside your scope.** A genuine fork in the road that the assignment did not pre-decide (e.g. which of two viable APIs to use, whether to refactor adjacent code). Ask the requester rather than picking unilaterally.
+- **Coordination opportunities.** You realize a peer's in-flight work would benefit from yours, or vice-versa.
+
+Do **not** use `irc` for: routine progress updates, things you can verify with a tool call, or questions whose answer is already in your assignment / repo / docs.
+</when_to_use>
+
+<etiquette>
+These rules apply to both sending and replying.
+- **Plain prose only.** Do not send structured JSON status payloads (e.g. `{"type":"task_completed",…}`). Write a normal sentence: "Done with the auth refactor — left a TODO in `src/server/auth.ts` for the rate limiter."
+- **Do not quote the message you are replying to.** The sender already saw it; the TUI already renders it. Lead with the answer.
+- **Use IRC, not terminal tools, to learn about peers.** Do not `grep` artifacts, read other sessions' JSONL files, or shell-poke around to figure out what another agent is doing. DM them — they have the live answer and you do not.
+- **One round-trip is enough.** Replies arrive synchronously when the recipient is reachable. Do not follow up with "did you get my message?" — they did. If `delivered` is empty or the result was `failed`, the peer is unavailable; move on or report the blocker, do not retry in a loop.
+- **Stay terse.** A DM is a chat message, not a memo. One question per send when you can. Share file paths and artifacts via `local://` / `memory://` / `artifact://` URLs instead of pasting blobs.
+- **Address peers by id.** Use the exact id from `op: "list"` (e.g. `0-AuthLoader`, `0-Main`). Do not invent friendly names.
+- **Do not IRC for things a tool would answer.** If a `read`, `grep`, or build command would resolve the question, do that first.
+- **When you receive an IRC message, answer it before continuing.** The recipient injects the question + your auto-reply into your history; address it directly, do not repeat it back to the user.
+</etiquette>
+
+<output>
+- `send`: returns each recipient that received the message and any prose replies that arrived.
+- `list`: returns peers and channels visible to the caller.
+</output>
+
+<examples>
+# List peers
+`{"op": "list"}`
+# Direct message to the main agent (waits for prose reply)
+`{"op": "send", "to": "0-Main", "message": "Should I prefer JWT or session cookies for the auth flow?"}`
+# Unexpected state — ask the originator
+`{"op": "send", "to": "0-Main", "message": "Assignment says edit src/auth/jwt.ts but the file does not exist. Is the new path src/server/auth/jwt.ts?"}`
+# Blocked by a peer — ask them directly
+`{"op": "send", "to": "0-AuthLoader", "message": "Are you still touching src/server/auth.ts? I need to add a 401 path; OK to proceed or should I wait?"}`
+# Broadcast to discover who owns something (no replies, just informs them)
+`{"op": "send", "to": "all", "message": "About to refactor src/server/middleware/*. Anyone already in there?", "awaitReply": false}`
+</examples>

package/src/prompts/tools/job.md

@@ -0,0 +1,11 @@
+Manages background jobs: poll to wait for completion, cancel to stop running jobs.
+
+You **MUST** use the `job` tool (in a loop, if necessary) instead of manually reading in a loop or issuing sleep commands.
+
+Pass `poll` to wait for one or more background jobs to finalize. If the timeout elapses before any job changes state, it returns the current snapshot (still-running jobs and any already-completed deliveries) without erroring — call `job` again to keep waiting. Calling with no `poll` and no `cancel` waits on every running background job.
+
+You **MUST NOT** poll the same job repeatedly without evidence of progress. Between calls, inspect `read jobs://<id>` to confirm new output or activity. If a job is stalled, has hung, or is producing nothing useful, cancel it via `cancel` and try a different approach instead of waiting indefinitely.
+
+Pass `cancel` to stop one or more running background jobs (started via async tool execution or bash auto-backgrounding). You **SHOULD** cancel jobs that are no longer needed or stuck. You **MAY** inspect jobs first with `read jobs://` or `read jobs://<job-id>`.
+
+`poll` and `cancel` may be combined in a single call: cancellations apply first, then polling waits on the remaining ids. When only `cancel` is provided the call returns immediately without waiting.

package/src/prompts/tools/read.md

@@ -15,19 +15,18 @@ The `read` tool is multi-purpose and more capable than it looks — inspects fil
 |`sel` value|Behavior|
 |---|---|
 |*(omitted)*|Read full file (up to {{DEFAULT_LIMIT}} lines)|
-|`L50`|Read from line 50 onward (shorthand for L50 to EOF)|
-|`L50-L120`|Read lines 50 through 120|
-|`L20-L20`|Read exactly one line|
-|`raw`|Skip line-numbering / hashline / chunking; return file content as plain text. For URLs: untouched HTML.|
-
-Max {{DEFAULT_MAX_LINES}} lines per call.
+|`50`|Read from line 50 onward|
+|`50-200`|Read lines 50-200|
+|`50+150`|Read 150 lines starting at line 50|
+|`20+1`|Read exactly one line|
 
 # Filesystem
+- Reading a directory path returns a list of dirents.
 {{#if IS_HASHLINE_MODE}}
-- Reading from FS returns lines prefixed with anchors: `41th:def alpha():` (line number, 2-letter ID, colon, then content)
+- Reading a file returns lines prefixed with anchors (line # .. hash .. | .. line content): `41th|def alpha():`
 {{else}}
 {{#if IS_LINE_NUMBER_MODE}}
-- Reading from FS returns lines prefixed with line numbers: `41:def alpha():`
+- Reading a file returns lines prefixed with line numbers: `41|def alpha():`
 {{/if}}
 {{/if}}
 
@@ -47,13 +46,13 @@ For `.sqlite`, `.sqlite3`, `.db`, `.db3`:
 - `file.db?q=SELECT …` — read-only SELECT query
 
 # URLs
-Extracts content from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom feeds, JSON endpoints, PDFs at URLs, and similar text-based resources. Returns clean reader-mode text/markdown — no browser required. Use `sel="raw"` for untouched HTML; `timeout` to override the default request timeout. You **SHOULD** prefer `read` over a browser/puppeteer tool for fetching URL content; only use a browser when the page requires JS execution, authentication, or interactive actions (clicks, forms, scrolling).
+Extracts content from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom feeds, JSON endpoints, PDFs at URLs, and similar text-based resources. Returns clean reader-mode text/markdown — no browser required. Use `sel="raw"` for untouched HTML; `timeout` to override the default request timeout.
 </instruction>
 
 <critical>
-- You **MUST** use `read` (never bash `cat`/`head`/`tail`/`less`/`more`/`ls`/`tar`/`unzip`/`curl`/`wget`) for all file, directory, archive, and URL reads.
-- You **MUST NOT** reach for a browser/puppeteer tool to fetch static web content — `read` handles HTML, PDFs, JSON, feeds, and docs directly. Reserve browser tools for JS-heavy pages or interactive flows.
-- 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 **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 **MAY** use `sel` with URL reads; the tool paginates cached fetched output.
 </critical>

package/src/prompts/tools/task.md

@@ -2,7 +2,7 @@ Launches subagents to parallelize workflows.
 
 {{#if asyncEnabled}}
 - Use `read jobs://` to inspect state; `read jobs://<job_id>` for detail.
-- Use the `poll` tool to wait until completion. You **MUST NOT** poll `read jobs://` in a loop.
+- Use the `job` tool (with `poll`) to wait until completion. You **MUST NOT** poll `read jobs://` in a loop.
 {{/if}}
 
 {{#if defaultMode}}

package/src/prompts/tools/todo-write.md

@@ -23,11 +23,12 @@ Pass an object with an `ops` array:
 
 |Field|Type|When to use|
 |---|---|---|
-|`op`|string|Required. One of `replace`, `start`, `done`, `rm`, `drop`, `append`|
+|`op`|string|Required. One of `replace`, `start`, `done`, `rm`, `drop`, `append`, `note`|
 |`task`|string|Task id for `start`, or a task target for `done` / `rm` / `drop`|
 |`phase`|string|Phase target for `done` / `rm` / `drop`, or append destination for `append`|
 |`items`|{id, label}[]|Required for `append`. If the phase does not exist, it is created at the end|
 |`phases`|Phase[]|Only for `replace`. Keeps initial phased setup available for harness bootstrap and full restructures|
+|`text`|string|Required for `note`. The note text appended to `task.notes` (which is a list, joined with newlines on render)|
 
 ## Semantics
 - `start`: requires `task`; sets that task to `in_progress`
@@ -36,6 +37,7 @@ Pass an object with an `ops` array:
 - `drop`: marks one task, one phase, or all tasks abandoned
 - `append`: appends `items` to `phase`; creates the phase if missing
 - `replace`: replaces the full todo list
+- `note`: append `text` as a new note attached to `task`. Notes are append-only context the user added; they only render to you when the task is `in_progress`. Other tasks display only a `+N` marker. Use this when you want to leave a follow-up reminder for yourself when you reach a later task.
 
 If `done`, `rm`, or `drop` omits both `task` and `phase`, it applies to all tasks.
 
@@ -43,6 +45,11 @@ If `done`, `rm`, or `drop` omits both `task` and `phase`, it applies to all task
 - `label`: Short label (5-10 words). What is being done, not how.
 - `replace` task `content` should stay short and specific.
 
+## Phase Anatomy
+- `name`: Short, human-readable noun phrase (1-3 words). Capitalize naturally.
+- Always prefix with a roman-numeral ordinal (`I.`, `II.`, `III.`, `IV.`, …) to convey ordering — e.g. `I. Foundation`, `II. Auth`, `III. Routing`. Single-phase plans use `I.` too.
+- You **MUST NOT** use snake_case, `Phase1_*`, arabic numerals (`1.`), or letter prefixes (`A.`) — they render as ugly identifiers.
+
 ## Rules
 - Mark tasks done immediately after finishing — never defer.
 - Complete phases in order — do not skip ahead while earlier ones are pending.
@@ -59,18 +66,20 @@ Create a todo list when:
 </conditions>
 
 <examples>
-# Initial setup
-`{"ops":[{"op":"replace","phases":[{"name":"Investigation","tasks":[{"content":"Read source"},{"content":"Map callsites"}]},{"name":"Implementation","tasks":[{"content":"Apply fix"},{"content":"Run tests"}]}]}]}`
+# Initial setup (multi-phase)
+`{"ops":[{"op":"replace","phases":[{"name":"I. Foundation","tasks":[{"content":"Scaffold crate"},{"content":"Wire workspace"}]},{"name":"II. Auth","tasks":[{"content":"Port credential store"},{"content":"Wire OAuth providers"}]},{"name":"III. Verification","tasks":[{"content":"Run cargo test"}]}]}]}`
+# Initial setup (single phase — still prefixed)
+`{"ops":[{"op":"replace","phases":[{"name":"I. Implementation","tasks":[{"content":"Apply fix"},{"content":"Run tests"}]}]}]}`
 # Complete one task
 `{"ops":[{"op":"done","task":"task-2"}]}`
 # Complete a whole phase
-`{"ops":[{"op":"done","phase":"Implementation"}]}`
+`{"ops":[{"op":"done","phase":"II. Auth"}]}`
 # Remove all tasks
 `{"ops":[{"op":"rm"}]}`
 # Drop one task
 `{"ops":[{"op":"drop","task":"task-7"}]}`
 # Append tasks to a phase
-`{"ops":[{"op":"append","phase":"Implementation","items":[{"id":"task-8","label":"Handle retries"},{"id":"task-9","label":"Run tests"}]}]}`
+`{"ops":[{"op":"append","phase":"II. Auth","items":[{"id":"task-8","label":"Handle retries"},{"id":"task-9","label":"Run tests"}]}]}`
 </examples>
 
 <avoid>

package/src/registry/agent-registry.ts

@@ -0,0 +1,139 @@
+/**
+ * AgentRegistry - Process-global registry of live AgentSession instances.
+ *
+ * Tracks every alive agent (the main session plus every subagent) so the
+ * `irc` tool can address peers by id. Sessions are registered explicitly at
+ * creation and removed when the owner releases them.
+ */
+
+import type { AgentSession } from "../session/agent-session";
+
+export const MAIN_AGENT_ID = "0-Main";
+
+export type AgentStatus = "running" | "idle" | "completed" | "aborted";
+export type AgentKind = "main" | "sub";
+
+export interface AgentRef {
+	id: string;
+	displayName: string;
+	kind: AgentKind;
+	parentId?: string;
+	status: AgentStatus;
+	session: AgentSession | null;
+	sessionFile: string | null;
+	createdAt: number;
+	lastActivity: number;
+}
+
+export type RegistryEvent =
+	| { type: "registered"; ref: AgentRef }
+	| { type: "status_changed"; ref: AgentRef }
+	| { type: "removed"; ref: AgentRef };
+
+type RegistryListener = (event: RegistryEvent) => void;
+
+export interface RegisterInput {
+	id: string;
+	displayName: string;
+	kind: AgentKind;
+	parentId?: string;
+	session: AgentSession | null;
+	sessionFile?: string | null;
+	status?: AgentStatus;
+}
+
+export class AgentRegistry {
+	static #global: AgentRegistry | undefined;
+
+	static global(): AgentRegistry {
+		if (!AgentRegistry.#global) {
+			AgentRegistry.#global = new AgentRegistry();
+		}
+		return AgentRegistry.#global;
+	}
+
+	/** Reset the global registry. Test-only. */
+	static resetGlobalForTests(): void {
+		AgentRegistry.#global = new AgentRegistry();
+	}
+
+	readonly #refs = new Map<string, AgentRef>();
+	readonly #listeners = new Set<RegistryListener>();
+
+	register(input: RegisterInput): AgentRef {
+		const now = Date.now();
+		const ref: AgentRef = {
+			id: input.id,
+			displayName: input.displayName,
+			kind: input.kind,
+			parentId: input.parentId,
+			status: input.status ?? "running",
+			session: input.session,
+			sessionFile: input.sessionFile ?? null,
+			createdAt: now,
+			lastActivity: now,
+		};
+		this.#refs.set(ref.id, ref);
+		this.#emit({ type: "registered", ref });
+		return ref;
+	}
+
+	setStatus(id: string, status: AgentStatus): void {
+		const ref = this.#refs.get(id);
+		if (!ref || ref.status === status) return;
+		ref.status = status;
+		ref.lastActivity = Date.now();
+		this.#emit({ type: "status_changed", ref });
+	}
+
+	attachSession(id: string, session: AgentSession): void {
+		const ref = this.#refs.get(id);
+		if (!ref) return;
+		ref.session = session;
+		ref.lastActivity = Date.now();
+	}
+
+	detachSession(id: string): void {
+		const ref = this.#refs.get(id);
+		if (!ref) return;
+		ref.session = null;
+	}
+
+	unregister(id: string): void {
+		const ref = this.#refs.get(id);
+		if (!ref) return;
+		this.#refs.delete(id);
+		this.#emit({ type: "removed", ref });
+	}
+
+	get(id: string): AgentRef | undefined {
+		return this.#refs.get(id);
+	}
+
+	list(): AgentRef[] {
+		return [...this.#refs.values()];
+	}
+
+	/**
+	 * Returns every alive agent (running | idle) except the caller.
+	 * Flat namespace: every agent can see every other agent.
+	 */
+	listVisibleTo(id: string): AgentRef[] {
+		return this.list().filter(ref => ref.id !== id && (ref.status === "running" || ref.status === "idle"));
+	}
+
+	onChange(listener: RegistryListener): () => void {
+		this.#listeners.add(listener);
+		return () => this.#listeners.delete(listener);
+	}
+
+	#emit(event: RegistryEvent): void {
+		for (const listener of this.#listeners) {
+			try {
+				listener(event);
+			} catch {
+				// listeners must not break the dispatch loop
+			}
+		}
+	}
+}

package/src/sdk.ts

@@ -83,6 +83,7 @@ import {
 } from "./mcp/discoverable-tool-metadata";
 import { buildMemoryToolDeveloperInstructions, getMemoryRoot, startMemoryStartupTask } from "./memories";
 import asyncResultTemplate from "./prompts/tools/async-result.md" with { type: "text" };
+import { AgentRegistry, MAIN_AGENT_ID } from "./registry/agent-registry";
 import {
 	collectEnvSecrets,
 	deobfuscateSessionContext,
@@ -213,6 +214,12 @@ export interface CreateAgentSessionOptions {
 	requireYieldTool?: boolean;
 	/** Task recursion depth (for subagent sessions). Default: 0 */
 	taskDepth?: number;
+	/** Pre-allocated agent identity for IRC routing. Default: "0-Main" for top-level, parentTaskPrefix-derived for sub. */
+	agentId?: string;
+	/** Display name for the agent in IRC. Default: "main" or "sub". */
+	agentDisplayName?: string;
+	/** Optional shared agent registry for IRC routing. Default: AgentRegistry.global(). */
+	agentRegistry?: AgentRegistry;
 	/** Parent task ID prefix for nested artifact naming (e.g., "6-Extensions") */
 	parentTaskPrefix?: string;
 
@@ -896,6 +903,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			})
 		: undefined;
 
+	const agentRegistry = options.agentRegistry ?? AgentRegistry.global();
+	const resolvedAgentId = options.agentId ?? options.parentTaskPrefix ?? MAIN_AGENT_ID;
+	const resolvedAgentDisplayName =
+		options.agentDisplayName ?? ((options.taskDepth ?? 0) > 0 || options.parentTaskPrefix ? "sub" : "main");
 	const pythonKernelOwnerId = `agent-session:${Snowflake.next()}`;
 
 	try {
@@ -929,6 +940,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			trackPythonExecution: (execution, abortController) =>
 				session ? session.trackPythonExecution(execution, abortController) : execution,
 			getSessionId: () => sessionManager.getSessionId?.() ?? null,
+			getAgentId: () => resolvedAgentId,
+			agentRegistry,
 			getSessionSpawns: () => options.spawns ?? "*",
 			getModelString: () => (hasExplicitModel && model ? formatModelString(model) : undefined),
 			getActiveModelString,
@@ -1591,6 +1604,28 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		});
 		hasSession = true;
 
+		// Register this session in the global agent registry so other agents can
+		// address it via the irc tool. Wrap dispose to unregister on teardown.
+		agentRegistry.register({
+			id: resolvedAgentId,
+			displayName: resolvedAgentDisplayName,
+			kind: (options.taskDepth ?? 0) > 0 || options.parentTaskPrefix ? "sub" : "main",
+			parentId: options.parentTaskPrefix,
+			session,
+			sessionFile: sessionManager.getSessionFile() ?? null,
+			status: "running",
+		});
+		{
+			const originalDispose = session.dispose.bind(session);
+			session.dispose = async () => {
+				try {
+					await originalDispose();
+				} finally {
+					agentRegistry.unregister(resolvedAgentId);
+				}
+			};
+		}
+
 		if (model?.api === "openai-codex-responses") {
 			const codexModel = model;
 			const codexTransport = getOpenAICodexTransportDetails(codexModel, {