@prometheus-ai/agent 0.5.0

package/src/prompts/tools/read.md

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

package/src/prompts/tools/recall.md

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

package/src/prompts/tools/reflect.md

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

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

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

package/src/prompts/tools/replace.md

@@ -0,0 +1,36 @@
+Performs string replacements in files with fuzzy whitespace matching.
+
+<instruction>
+- Params MUST be `{ path, edits }`; `path` is required at the top level and applies to every replacement
+- You MUST use the smallest `old_text` that uniquely identifies the change
+- If `old_text` is not unique, you MUST expand it with more context or use `all: true` to replace all occurrences
+- You SHOULD prefer editing existing files over creating new ones
+</instruction>
+
+<output>
+Returns success/failure status. On success, file modified in place with replacement applied. On failure (e.g., `old_text` not found or matches multiple locations without `all: true`), returns error describing issue.
+</output>
+
+<critical>
+- You MUST read the file at least once in the conversation before editing. Tool errors if you attempt edit without reading file first.
+</critical>
+
+<bash-alternatives>
+Replace for content-addressed changes—you identify \_what* to change by its text.
+
+For position-addressed or pattern-addressed changes, bash more efficient:
+
+|Operation|Command|
+|---|---|
+|Append to file|`cat >> file <<'EOF'`…`EOF`|
+|Prepend to file|`{ cat - file; } <<'EOF' > tmp && mv tmp file`|
+|Delete lines N-M|`sed -i 'N,Md' file`|
+|Insert after line N|`sed -i 'Na\text' file`|
+|Regex replace|`sd 'pattern' 'replacement' file`|
+|Bulk replace across files|`sd 'pattern' 'replacement' **/*.ts`|
+|Copy lines N-M to another file|`sed -n 'N,Mp' src >> dest`|
+|Move lines N-M to another file|`sed -n 'N,Mp' src >> dest && sed -i 'N,Md' src`|
+
+Use Replace when _content itself_ identifies location.
+Use bash when _position_ or _pattern_ identifies what to change.
+</bash-alternatives>

package/src/prompts/tools/resolve.md

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

package/src/prompts/tools/retain.md

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

package/src/prompts/tools/rewind.md

@@ -0,0 +1,13 @@
+End an active checkpoint. Rewind context to it, replacing intermediate exploration with your report.
+
+Call immediately after `checkpoint`-started investigative work.
+
+Requirements:
+- `report` is REQUIRED and must be concise, factual, and actionable.
+- Include key findings, decisions, and any unresolved risks.
+- Do not include raw scratch logs unless essential.
+- You MUST call this before yielding if a checkpoint is active.
+
+Behavior:
+- If no checkpoint is active, this tool errors.
+- On success, the session rewinds and keeps your report as retained context.

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

@@ -0,0 +1,40 @@
+Search hidden tool metadata to discover and activate tools.
+
+Activate hidden tools (MCP and built-in) when you need a capability not in your active tool set.
+{{#if hasDiscoverableMCPServers}}
+Discoverable MCP servers in this session: {{#list discoverableMCPServerSummaries join=", "}}{{this}}{{/list}}.
+{{/if}}
+{{#if hasDiscoverableBuiltinTools}}
+Discoverable built-in tools: {{#list discoverableBuiltinToolNames join=", "}}{{this}}{{/list}}.
+{{/if}}
+{{#if discoverableToolCount}}
+Total discoverable tools available: {{discoverableToolCount}}.
+{{/if}}
+Input:
+- `query` — required natural-language or keyword query
+- `limit` — optional maximum number of tools to return and activate (default `8`)
+
+Behavior:
+- Searches hidden tool metadata using BM25-style relevance ranking
+- Matches against tool name, label, server name, description/summary, and input schema keys
+- Activates the top matching tools for the rest of the current session
+- Repeated searches add to the active tool set; they do not remove earlier selections
+- Newly activated tools become available before the next model call in the same overall turn
+
+Notes:
+Start with `limit` 5–10 if unsure.
+- `query` is matched against tool metadata fields:
+  - `name`
+  - `label`
+  - `server_name` (MCP tools)
+  - `mcp_tool_name` (MCP tools)
+  - `description` / `summary`
+  - input schema property keys (`schema_keys`)
+
+Not for repository/file/code search. Tool discovery only.
+
+Returns JSON with:
+- `query`
+- `activated_tools` — tools activated by this search call
+- `match_count` — number of ranked matches returned by the search
+- `total_tools`

package/src/prompts/tools/search.md

@@ -0,0 +1,25 @@
+Searches files using powerful regex matching.
+
+<instruction>
+- Supports Rust regex syntax (RE2-style — no lookaround or backreferences). Use line anchors or post-filters instead of (?!…)/(?<!…)
+- `paths` accepts either one string or an array of files, directories, globs, or internal URLs. Optional: when omitted or empty it searches the workspace root (`.`). Prefer scoping to specific paths when you know them.
+- For multiple targets, pass an array with one target per element: `["src", "tests"]`.
+- Cross-line patterns are detected from literal `\n` or escaped `\\n` in `pattern`
+</instruction>
+
+<output>
+{{#if IS_HL_MODE}}
+- Text output emits a file snapshot tag header per matched file plus numbered lines: `[src/login.ts#1A2B]`, `*42:if (user.id) {` (match), ` 43:return user;` (context). Copy the header for anchored edits; ops use bare line numbers.
+{{else}}
+{{#if IS_LINE_NUMBER_MODE}}
+- Text output is line-number-prefixed
+{{/if}}
+{{/if}}
+</output>
+
+<critical>
+- You MUST use the built-in `search` tool for any content search. NEVER shell out to `grep`, `rg`, `ripgrep`, `ag`, `ack`, `git grep`, `awk`, `sed`-for-search, or any other CLI search via Bash — even for a single match, even "just to check quickly", even piped through other commands.
+- Bash `grep`/`rg` loses `.gitignore` semantics, bypasses result limits, and wastes tokens. The `search` tool is faster, structured, and already wired into the workspace — there is no scenario where Bash search is preferable.
+- If you catch yourself typing `grep`, `rg`, or `| grep` in a Bash command, stop and re-issue the lookup through the `search` tool instead.
+- If the search is open-ended, requiring multiple rounds, you MUST use the Task tool with the explore subagent instead of chaining `search` calls yourself.
+</critical>

package/src/prompts/tools/ssh.md

@@ -0,0 +1,35 @@
+Runs commands on remote hosts.
+
+<instruction>
+You MUST build commands from the reference below
+</instruction>
+
+<commands>
+**linux/bash, linux/zsh, macos/bash, macos/zsh** — Unix-like:
+- Files: `ls`, `cat`, `head`, `tail`, `grep`, `find`
+- System: `ps`, `top`, `df`, `uname` (all), `free` (Linux only)
+- Navigation: `cd`, `pwd`
+**windows/bash, windows/sh** — Windows Unix layer (WSL, Cygwin, Git Bash):
+- Files/System/Navigation: same as Unix-like above, minus `free`
+**windows/powershell** — PowerShell:
+- Files: `Get-ChildItem`, `Get-Content`, `Select-String`
+- System: `Get-Process`, `Get-ComputerInfo`
+- Navigation: `Set-Location`, `Get-Location`
+**windows/cmd** — Command Prompt:
+- Files: `dir`, `type`, `findstr`, `where`
+- System: `tasklist`, `systeminfo`
+- Navigation: `cd`, `echo %CD%`
+</commands>
+
+<critical>
+You MUST verify the shell type from "Available hosts" and use matching commands.
+</critical>
+
+<examples>
+# List files: Linux
+Host: server1 (10.0.0.1) | linux/bash. Command: `ls -la /home/user`
+# Show running processes: Windows cmd
+Host: winbox (192.168.1.5) | windows/cmd. Command: `tasklist /v`
+# Get system info: macOS
+Host: macbook (10.0.0.20) | macos/zsh. Command: `uname -a && sw_vers`
+</examples>

package/src/prompts/tools/task-summary.md

@@ -0,0 +1,28 @@
+<task-summary>
+<header>{{successCount}}/{{totalCount}} succeeded{{#if hasCancelledNote}} ({{cancelledCount}} cancelled){{/if}} [{{duration}}]</header>
+
+{{#each summaries}}
+<agent id="{{id}}" agent="{{agent}}">
+<status>{{status}}</status>
+{{#if meta}}<meta lines="{{meta.lineCount}}" size="{{meta.charSize}}" />{{/if}}
+{{#if truncated}}
+<preview full-path="agent://{{id}}">
+{{preview}}
+</preview>
+{{else}}
+<result>
+{{preview}}
+</result>
+{{/if}}
+</agent>
+{{#unless @last}}
+---
+{{/unless}}
+{{/each}}
+
+{{#if mergeSummary}}
+<merge-summary>
+{{mergeSummary}}
+</merge-summary>
+{{/if}}
+</task-summary>

package/src/prompts/tools/task.md

@@ -0,0 +1,80 @@
+Launches subagents to parallelize workflows.
+
+{{#if asyncEnabled}}
+- Results are delivered automatically when complete.
+- The tool result lists the assigned task ids (e.g. `AuthLoader`) — those are the live agent ids.
+{{#if ircEnabled}}
+- Coordinate with running tasks via `irc` using those ids. `job cancel` terminates a task and **cannot carry a message** — only use it for stalled/abandoned work.
+- If genuinely blocked on completion, wait with `job poll`; otherwise keep working.
+{{else}}
+- If genuinely blocked on completion, wait with `job poll`; otherwise keep working.
+- Use `job list` to snapshot manager state; `cancel: [id]` only to actually stop a stuck task.
+{{/if}}
+{{/if}}
+
+{{#if ircEnabled}}
+Subagents have no conversation history, but they can reach you and their siblings live via the `irc` tool. Front-load every fact, file path, and direction they need in {{#if contextEnabled}}`context` or `assignment`{{else}}each `assignment`{{/if}}.
+{{else}}
+Subagents have no conversation history. Every fact, file path, and direction they need MUST be explicit in {{#if contextEnabled}}`context` or `assignment`{{else}}each `assignment`{{/if}}.
+{{/if}}
+
+<parameters>
+- `agent`: agent type for all tasks
+- `tasks`: tasks to execute in parallel
+ - `.id`: CamelCase, ≤32 chars
+ - `.description`: UI label only — subagent never sees it
+ - `.assignment`: complete self-contained instructions; one-liners and missing acceptance criteria are PROHIBITED
+{{#if contextEnabled}}- `context`: shared background prepended to every assignment; session-specific only{{/if}}
+{{#if customSchemaEnabled}}- `schema`: JTD schema for expected structured output (do not put format rules in assignments){{/if}}
+{{#if isolationEnabled}}- `isolated`: run in isolated env; use when tasks edit overlapping files{{/if}}
+</parameters>
+
+<rules>
+- **Maximize batch width.** Spawn the widest parallel set the work decomposes into. NEVER spawn a single-task batch for divisible work, or defer work that could have been concurrent.
+- NEVER assign tasks to run project-wide build/test/lint. Caller verifies after the batch.
+- **Subagents do not verify, lint, or format.** Every assignment MUST instruct the subagent to skip all gates and formatters. You run them once at the end across the union of changed files — avoids redundant runs and racing formatter passes.
+- No globs, no "update all", no package-wide scope. Fan out.
+- Do not concern yourself with how agents might overlap on certain actions. Never use it as an excuse to go slower: they can resolve collisions in real-time with the harness facilities.
+- Pass large payloads via `local://<path>` URIs, not inline. {{#if contextEnabled}} (other than the context){{/if}}
+{{#if contextEnabled}}- Put shared constraints in `context` once; do not duplicate across assignments.{{/if}}
+- Prefer agents that investigate **and** edit in one pass; only spin a read-only discovery step when affected files are genuinely unknown.
+- **Read-only agents**: Agents tagged READ-ONLY (e.g. `explore`) have no edit/write/command tools. NEVER hand them an assignment that requires changing files or running commands — they cannot do it and the turn is wasted. Use them to investigate and report back; do the edits yourself or delegate to a writing agent (`task`, `oracle`, `designer`).
+- **No reasoning offload**: NEVER offload reasoning, analysis, design, or decision-making to `quick_task` or `explore` — they run minimal-effort / small models for mechanical lookups and data collection only. Keep judgment and synthesis in your own context; delegate hard thinking to `task`, `plan`, or `oracle`.
+</rules>
+
+<parallelization>
+{{#if ircEnabled}}
+Test: can task B run correctly without seeing A's output? If no, sequence A → B — **unless** B can reasonably ask A for the missing piece over `irc`. Live coordination beats a serial waterfall when the contract is small and easy to describe in a DM.
+Still sequence when one task produces a large, evolving contract (generated types, schema migration, core module API) the other consumes wholesale — IRC round-trips do not replace a finished artifact.
+Parallel when tasks touch disjoint files, are independent refactors/tests, or only need occasional clarification that can be resolved peer-to-peer.
+{{else}}
+Test: can task B run correctly without seeing A's output? If no, sequence A → B.
+Sequential when one task produces a contract (types, API, schema, core module) the other consumes.
+Parallel when tasks touch disjoint files or are independent refactors/tests.
+{{/if}}
+</parallelization>
+
+{{#if contextEnabled}}
+<context-fmt>
+# Goal         ← one sentence: what the batch accomplishes
+# Constraints  ← MUST/NEVER rules and session decisions
+# Contract     ← exact types/signatures if tasks share an interface
+</context-fmt>
+{{/if}}
+
+<assignment-fmt>
+# Target       ← exact files and symbols; explicit non-goals
+# Change       ← step-by-step add/remove/rename; APIs and patterns
+# Acceptance   ← observable result; no project-wide commands
+</assignment-fmt>
+
+<agents>
+{{#if spawningDisabled}}
+Agent spawning is disabled for this context.
+{{else}}
+{{#list agents join="\n"}}
+# {{name}}{{#if readOnly}} — READ-ONLY (no edit/write/exec tools){{/if}}
+{{description}}
+{{/list}}
+{{/if}}
+</agents>

package/src/prompts/tools/todo.md

@@ -0,0 +1,58 @@
+**Tasks are referenced by their verbatim content string, not by any auto-generated ID. There is no "task-1"/"task-N" identifier — the tool never emits one. Pass the task's content text in the `task` field.**
+
+Manages a phased task list. Pass `ops`: a flat array of operations.
+The next pending task is auto-promoted to `in_progress` after each completion.
+Allowed `op` values are only `init`, `start`, `done`, `drop`, `rm`, `append`, and `note`. `pending` is a task status, not an `op`; leave not-yet-started tasks implicit in `init`/`append` lists.
+
+## Operations
+
+|`op`|Required fields|Effect|
+|---|---|---|
+|`init`|`list: [{phase, items: string[]}]`|Initialize the full list (replaces any existing list)|
+|`start`|`task`|Mark in progress|
+|`done`|`task` or `phase`|Mark completed|
+|`drop`|`task` or `phase`|Mark abandoned|
+|`rm`|`task` or `phase`|Remove|
+|`append`|`phase`, `items: string[]`|Append tasks to `phase`; lazily creates phase|
+|`note`|`task`, `text`|Append a note to a task. Reminders for future-you only.|
+
+## Anatomy
+- **Task content**: 5–10 words, what is being done, not how. Used as the task identifier — unique.
+- **Phase name**: short noun phrase (e.g. `Foundation`, `Auth`, `Verification`). Used as the phase identifier — unique. Do not add prefixes like `1.`, `A)`, `Phase 1:`, etc.
+
+## Rules
+- Mark tasks done immediately after finishing.
+- Complete phases in order.
+- On blockers, `append` a new task to the active phase to unblock yourself, or `drop`.
+- `task` and `phase` fields reference content/name verbatim; keep them stable once introduced.
+
+## When to create a list
+- Task requires 3+ distinct steps
+- User explicitly requests one
+- User provides a set of tasks to complete
+- New instructions arrive mid-task — capture before proceeding
+
+<examples>
+# Initial setup (multi-phase)
+`{"ops":[{"op":"init","list":[{"phase":"Foundation","items":["Scaffold crate","Wire workspace"]},{"phase":"Auth","items":["Port credential store","Wire OAuth providers"]},{"phase":"Verification","items":["Run cargo test"]}]}]}`
+# Initial setup (single phase)
+`{"ops":[{"op":"init","list":[{"phase":"Implementation","items":["Apply fix","Run tests"]}]}]}`
+# Complete one task
+`{"ops":[{"op":"done","task":"Wire workspace"}]}`
+# Complete a whole phase
+`{"ops":[{"op":"done","phase":"Auth"}]}`
+# Remove all tasks
+`{"ops":[{"op":"rm"}]}`
+# Drop one task
+`{"ops":[{"op":"drop","task":"Run cargo test"}]}`
+# Append tasks to a phase
+`{"ops":[{"op":"append","phase":"Auth","items":["Handle retries","Run tests"]}]}`
+</examples>
+
+<critical>
+When the user hands you a multi-step plan — a phased todo, a numbered or bulleted checklist, or "N bugs/items/tasks" to work through:
+- You MUST `init` the list with EVERY item as its own task before doing the work.
+- Enumerate all of them;
+- NEVER summarize the plan into fewer tasks, sample "the important ones", drop items, or rely on memory to track the rest.
+The entire point is to remember every one.
+</critical>

package/src/prompts/tools/web-search.md

@@ -0,0 +1,10 @@
+Searches the web for up-to-date information beyond knowledge cutoff.
+
+<instruction>
+- You SHOULD prefer primary sources (papers, official docs) and corroborate key claims with multiple sources
+- You MUST include links for cited sources in the final response
+</instruction>
+
+<caution>
+Searches are performed automatically within a single API call—no pagination or follow-up requests needed.
+</caution>

package/src/prompts/tools/write.md

@@ -0,0 +1,14 @@
+Creates or overwrites file at specified path.
+
+<conditions>
+- Creating new files explicitly required by task
+- Replacing entire file contents when editing would be more complex
+- Supports `.tar`, `.tar.gz`, `.tgz`, and `.zip` archive entries via `archive.ext:path/inside/archive`
+- Supports SQLite row operations via `db.sqlite:table` (insert), `db.sqlite:table:key` (update with JSON content, delete with empty content)
+</conditions>
+
+<critical>
+- You SHOULD use Edit tool for modifying existing files (more precise, preserves formatting)
+- You NEVER create documentation files (*.md, README) unless explicitly requested
+- You NEVER use emojis unless requested
+</critical>

package/src/registry/agent-registry.ts

@@ -0,0 +1,140 @@
+/**
+ * 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 = "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, sessionFile?: string | null): void {
+		const ref = this.#refs.get(id);
+		if (!ref) return;
+		ref.session = session;
+		if (sessionFile !== undefined) ref.sessionFile = sessionFile;
+		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
+			}
+		}
+	}
+}