@tduyng/pi-subagent 0.0.2 → 0.0.4

package/README.md

@@ -1,68 +1,81 @@
 # @tduyng/pi-subagent
 
-Delegates work to child pi sessions running in-process. The parent stays lean because the child reads the files, returns one message plus a file list and usage stats, and then its context is discarded. Each finished child also appends its usage to `<agentDir>/overhead.jsonl` under the parent's session, so `/cost` can show what the delegation spent alongside the conversation.
+A subagent that stays small on purpose. It reads docs, logs and source on a cheap model, returns one answer, and leaves none of that reading in the parent's context.
 
-## How delegation works
+A session spends most of its tokens reading. A question about which files build a retry policy has a paragraph for an answer and 40 KB of source behind it, and the parent carries that 40 KB into every later turn. The child's context dies with the task, so the cost of a delegation is bounded by its answer.
 
-The `subagent` tool sends one task, or up to `MAX_TASKS` tasks, to a child
-session. At most `MAX_CONCURRENT` children run at once. Each child runs on the
-current model unless a task, profile, or `subagent.json` override changes it.
-The child sees the task prompt, does the work, and returns one message. The
-parent never carries the child's exploration.
+Fanning four edit-capable children over one change is the case this is not for. Every child builds its own system prompt and tool list, and their edits still have to be reconciled.
 
-Use `scout` for read-only file and document search, code tracing, analysis, and
-short sourced summaries. Omitting `agent` selects `scout`. It is the cheap
-default for I/O-heavy work. `subagent.json` supplies its low-cost model.
+379 tokens a request for the tool. The bulk-read guard and the log reducer are event handlers, so they add no schema and no prompt text.
 
-Use `verifier` only
-after an artifact exists and the task explicitly asks for verification or
-review. Keep ordinary implementation, debugging, design, builds, tests, and lint
-in the parent session.
+## The tool
 
-### Resume ids
+```text
+subagent(task: "Which files construct the retry policy? Return path:line for each.", agent: "scout")
+```
+
+One task or up to 8, at most 4 running at once.
+
+| Field | Meaning |
+| --- | --- |
+| `task` | What the child does |
+| `agent` | Profile name, `scout` by default |
+| `cwd` | Working directory for the child |
+| `isolation` | `worktree` to give the child its own git checkout |
+| `schema` | Ask for structured output |
+| `context` | `fork` to replay the parent's history into the child |
+| `resume` | Task id, or `all`, to continue a stopped child |
+
+## Scout
+
+`agents/scout.md` is bundled, so `agent: "scout"` works with no setup and no profile. It is also the default when no agent is named, so the cheap read-only child is what a plain call gets.
+
+Scout carries `tools: read, grep, find, ls`, `inheritSkills: false`, and `thinking: low`. It never edits, never runs a command, never reaches the network, and answers in a fixed `STATUS / FINDING / NEXT` shape with file:line evidence.
 
-A child that reaches its turn budget is told to wrap up and gets a fresh budget in the same session, so a cap never turns work into a failure. If the child still stops early, its last text comes back as a `[partial answer]`. Salvage walks the whole transcript for that text, not just the last message, so a child stopped mid-tool-burst still returns what it wrote. Every failed task prints a `resume:` id. Pass `resume: "<id>"` (or `"all"`) to continue where it stopped instead of paying for the investigation again. An optional `task` alongside `resume` steers the continuation. Failed sessions are kept 30 minutes, completed ones 5.
+Override it with a copy in `~/.pi/agent/agents/scout.md` or `.pi/agents/scout.md`. A project file shadows a user file, and both shadow the bundled one.
 
-A deadline is reported as a timeout, not a cancellation. Pi keeps any final text produced before the deadline, marks it partial, and retains the session for resume.
+The child inherits the parent's model unless told otherwise, which defeats the point. Set it once in `~/.pi/agent/subagent.json`:
 
-Every run also writes `run.json` under `<agent-dir>/subagents/<session-id>/<run-id>/` with the task prompt, model, tools, and the path to each child session. The file is rewritten after each task transition, so it survives the process. Reopening the same Pi session reads it back: children interrupted less than ten minutes ago are resumed from their saved sessions and their result arrives as a `subagent-durable` message, while older interruptions are listed with their resume ids. `resume` therefore works after a restart, not only inside the process that started the child.
+```json
+{
+  "model": "claude/claude-haiku-5-5",
+  "thinking": "low"
+}
+```
+
+`.pi/subagent.json` overrides either field per project. A `model` on the profile wins over the file, so a judgment role such as `verifier` can opt out and ask for a strong model.
+
+## A stopped child is resumable
 
-### Worktree isolation
+A child that hits its turn budget is told to wrap up and gets a fresh budget in the same session, so a cap never turns work into a failure. If it still stops early, its last text comes back marked `[partial answer]`, recovered by walking the whole transcript, so a child stopped mid tool-burst still returns what it wrote.
 
-With `isolation: "worktree"`, each child runs in its own git worktree on a branch named `pi-task-<id>`, so concurrent children never edit the same checkout and a commit a child makes outlives the checkout. The task result names the branch.
+Every failed task prints a `resume:` id. Passing it back continues where the child stopped instead of paying for the investigation again. Failed sessions are kept 30 minutes and completed ones 5.
 
-### Structured output
+Every run writes `run.json` under `<agent-dir>/subagents/<session-id>/<run-id>/` with the task, model, tools and the path to each child session. Reopening the session reads it back: a child interrupted less than ten minutes ago is resumed from its saved session and its answer arrives as a `subagent-durable` message, and older interruptions are listed with their resume ids. `resume` therefore works after a restart.
 
-Pass `schema` to ask the child to call a `structured_output` tool exactly once. The parsed payload comes back in the task result. If the child finishes without calling the tool, the extension re-prompts the same session up to three times, so the investigation is not paid for twice. If it still refuses, the text answer stands and the task completes marked partial. If a provider rejects the schema tool, the extension removes it and retries once in plain-text mode.
+## Worktrees, schemas, forks
 
-### Fork context
+`isolation: "worktree"` runs each child in its own git worktree on a branch named `pi-task-<id>`, so concurrent children never edit the same checkout and a commit the child makes outlives it. The result names the branch. This is also the answer to two sessions committing in one repository, which no path reservation covers.
 
-With `context: "fork"`, the parent's conversation history is replayed into the child as context entries.
+`schema` asks the child to call `structured_output` exactly once, and the parsed payload comes back in the task result. A child that finishes without calling it is re-prompted in the same session up to three times, so the investigation is not paid for twice. If it still refuses, the text answer stands and the task completes marked partial. If a provider rejects the schema tool, the extension removes it and retries once as plain text.
 
-## Agent profiles
+`context: "fork"` replays the parent's conversation history into the child as context entries.
 
-The `/agents` command lists agent profiles, which are markdown files with YAML frontmatter in `<agent-dir>/agents` or `.pi/agents`. Project agents shadow user agents of the same name. Each profile specifies a tool list, model, thinking level, limits, and optional color for the widget. Profiles can also set `inheritProjectContext` and `inheritSkills` to control whether the child picks up the parent project's context files and skills, and `systemPromptMode: replace` to swap the default system prompt instead of appending to it. The `subagent` widget in the TUI shows up to 8 running and recently finished children, with a summary line of counts by status. Navigate with Down/Up, Enter opens a live transcript viewer, d/x dismisses.
+## Two guards on the parent
 
-## Bulk-read guard
+**Bulk read.** The guard blocks a read of a file above `BULK_READ_MIN_LINES` lines (default 350), and blocks `cat`, `less` or `more` that would dump a large file. The block names `outline` first, so the model fetches a map of declarations rather than the text. The second call for the same path passes, and so does a read that returns fewer lines than the threshold, whether from a `limit`, an `offset`, a small file, or `head` and `tail` on their 10-line default.
 
-The guard blocks reads of files above `BULK_READ_MIN_LINES` lines (default 350). It also blocks `cat`, `less`, and `more` commands that would dump large files. The second call for the same path passes through, so the file stays reachable. A read passes when it returns fewer lines than the threshold, whether that comes from a `limit`, an `offset`, a small file, or `head`/`tail` on their 10-line default, and so does a piped command.
+**Log reducer.** The reducer replaces a build or test log above 4,096 bytes from a diagnostic command with a short receipt of quoted lines. It verifies every quote byte for byte against the archived original, and if validation fails the full log reaches the model untouched. It runs on `tool_result`, so the swap happens before the result enters history, and the raw log is archived next to the session.
 
-## Log reducer
+Both are what stop a delegation from being undone by the next `cat`.
 
-Build or test logs above 4,096 bytes, matched by diagnostic command patterns, get replaced with a short receipt of quoted lines. Every quote is verified byte-for-byte against the archived original. If validation fails, the full log reaches the model untouched. The reducer runs on `tool_result`, so the swap happens before the result enters history. The raw log is archived next to the session for full access.
+## Profiles and the widget
 
-## Design
+A profile is a markdown file with YAML frontmatter in `~/.pi/agent/agents/`, `.pi/agents/`, or bundled. It sets the tool list, model, thinking level, limits, an optional color, `inheritProjectContext` and `inheritSkills`, and `systemPromptMode: replace` to swap the default system prompt rather than append to it.
 
-- The default safe delegation is read-only I/O: `scout` searches, traces, analyses, and summarizes without editing or running commands.
-- `verifier` is reserved for explicit verification of an existing artifact. It may write only its verification report, never implementation files.
-- Ordinary implementation, debugging, design, builds, tests, and lint stay in the parent session.
-- The tool rejects concurrent write-capable tasks. Read-only scouts may still run in parallel. A call whose task texts normalize to the same request is rejected, so one question does not get paid for twice.
-- Children see one prompt and return one message. No sequential pipelines.
-- Children cannot spawn their own subagents. No grandchildren.
-- The `subagent` tool schema is present on every turn, and it lists only the fields a model sets: `task`, `agent`, `cwd`, `isolation`, `schema`, `context`, and `resume`. `label`, `thinking`, `model`, `timeoutMs`, and `maxTurns` are profile policy. They still work when a scripted caller passes them, and three of them already resolved to the profile before the split.
-- The `subagent` tool schema is present on every turn. The `bulk-read` and `log-reducer` extensions add no tool schemas. They run as event handlers. The registry holds at most 50 tasks. The widget shows at most 8 rows. The `touched` file list per task is capped at 12 entries. Progress updates emit at most once every 250ms.
-- Child deadlines default to 30 minutes. A shorter `timeoutMs` or profile `maxExecutionTimeMs` is raised to 30 minutes, while longer values pass through. A profile deadline beyond the 32-bit setTimeout ceiling (2,147,483,647 ms) clamps to the ceiling. Node would round a larger delay down to 1 ms and kill the child instantly, so the clamp degrades a bad value to a very long deadline.
-- Children inherit the parent's model by default. Thinking does not inherit: it resolves from the task's `thinking`, then the profile, then `subagent.json`, then `medium`.
+`/agents` lists them with their tools, model and limits. The roster rarely changes mid-task, so it is a command, not a model tool.
+
+A persistent widget lists running and recently finished children. Down on an empty prompt highlights the roster, Up and Down move, Escape clears, Enter opens a live conversation viewer with thinking, tool calls and results.
 
 ## Install
 
@@ -72,10 +85,19 @@ pi install npm:@tduyng/pi-subagent
 
 Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-subagent`
 
-## Configure
+Worktree isolation needs `git` on PATH, and the bulk-read hint names `rg`.
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `BULK_READ` | `1` | `0` disables the read guard |
+| `BULK_READ_MIN_LINES` | `350` | Line threshold for a blocked read |
+| `PI_LOG_REDUCER` | `1` | `0` disables the log reducer |
+| `PI_LOG_REDUCER_TIMEOUT_MS` | `15000` | Reducer deadline, 60,000 at most |
+
+## Limits
 
-- `subagent.json` in the agent dir (`~/.pi/agent/`) sets the default child model and thinking level. A project's `.pi/subagent.json` overrides either field. Shape: `{ "model": "provider/model-id", "thinking": "medium" }`, both optional. `thinking` is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Unset, it is `medium`. No file means children inherit the parent's model.
-- `BULK_READ=0` disables the bulk-read guard. `BULK_READ_MIN_LINES` sets the line threshold (default 350).
-- `PI_LOG_REDUCER=0` disables the log reducer.
-- `PI_LOG_REDUCER_TIMEOUT_MS` sets the reducer deadline. The default is 15 seconds and the maximum is 60 seconds.
-- Agent profiles are markdown files with YAML frontmatter in `~/.pi/agent/agents/` or `.pi/agents/` (project shadowing user on name collision).
+- Eight tasks per call, four running at once. A fifth concurrent write-capable child is refused rather than queued.
+- Child deadlines default to 30 minutes. A profile deadline past the 32-bit `setTimeout` ceiling clamps to it, because Node rounds a larger delay down to 1 ms and would kill the child instantly.
+- A child cannot spawn its own subagent, so delegation stays one level deep.
+- Read-only children run in parallel. A write-capable child never runs alongside another one, and two tasks that normalize to the same request are refused.
+- The registry holds 50 tasks, the widget 8 rows, and the touched list 12 entries per task.

package/agents/scout.md

@@ -0,0 +1,43 @@
+---
+name: scout
+description: Cheap read-only I/O and analysis agent. Searches files and docs, traces code, answers one bounded question, and returns a short sourced summary. Never edits, writes, runs commands, or reaches the internet.
+tools: read, grep, find, ls
+inheritSkills: false
+thinking: low
+---
+
+You are a SCOUT, a cheap read-only I/O and analysis subagent. The caller hands
+you exactly one bounded question in a fresh context. Answer it from what is on
+disk and return a short, sourced answer. You change nothing.
+
+Use this profile for file and document search, code tracing, comparison, and
+summarization. If the task asks you to implement, edit, run a check, or
+make a design decision, return that the parent must handle it.
+
+Rules:
+
+- Read only what the question needs. Use `grep` and `find` to locate, then read
+  the specific range. Never read a whole file to answer a narrow question.
+- Prefer file paths, line numbers, exact text, and literal command output over
+  general impressions. A summary is useful only when its evidence is included.
+- Answer with evidence: file paths with line numbers, exact text you found, or
+  the literal output you observed. No paraphrase of code you did not read.
+- A negative result is a real result. If the answer is not on disk, say what you
+  searched and what you ruled out.
+- You have no write, edit, bash, or web tools. Do not ask for them, and do not
+  propose patches. Name the gap instead. A task that needs those capabilities
+  belongs in the parent session. A question about the
+  internet cannot be answered by you at all: say so in one line under NEXT and
+  stop, rather than searching the disk for a substitute.
+- Spend your turns on the search that answers the question, and when you are
+  told to wrap up, answer with what you have and say what is still unchecked
+  under NEXT.
+
+Reply with exactly this, and nothing else:
+
+STATUS: solved|continue
+FINDING: <the answer, with file:line evidence, at most five lines>
+NEXT: <up to three bullets, or "none">
+
+When a `structured_output` tool is available, call it once with the same
+STATUS, FINDING, and NEXT content as its fields, and write no text after it.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tduyng/pi-subagent",
-  "version": "0.0.2",
-  "description": "Delegation to in-process child sessions: a subagent tool with agent profiles and worktree isolation, a side chat, a guard that redirects bulk reads, and a verified log reducer.",
+  "version": "0.0.4",
+  "description": "Cheap delegation: a child session reads docs, logs, and source, returns one answer, and its context is thrown away. Scout profile bundled.",
   "keywords": [
     "pi",
     "pi-package",
@@ -25,6 +25,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "agents",
     "README.md",
     "LICENSE"
   ],

package/src/subagent/agent.ts

@@ -101,8 +101,16 @@ export function loadAgentsFrom(dirs: string[]): Map<string, AgentProfile> {
     return agents
 }
 
+const BUNDLED_AGENTS = path.join(import.meta.dirname, '..', '..', 'agents')
+
+// The default `agent` is scout, so a checkout with no profile on disk would refuse every
+// delegation that omits it. The bundled profile is the floor, not an override.
 export function loadAgents(cwd: string): Map<string, AgentProfile> {
-    return loadAgentsFrom(agentDirs(cwd))
+    const agents = loadAgentsFrom(agentDirs(cwd))
+    for (const [name, profile] of loadAgentsFrom([BUNDLED_AGENTS])) {
+        if (!agents.has(name)) agents.set(name, profile)
+    }
+    return agents
 }
 
 export function parseModelName(name: string): { provider: string; id: string } | undefined {

package/src/subagent/index.ts

@@ -69,7 +69,7 @@ import {
 } from './types.js'
 import { SubagentViewer, widgetLines } from './viewer.js'
 
-export { parseFrontmatter, loadAgentsFrom, parseModelName } from './agent.js'
+export { parseFrontmatter, loadAgents, loadAgentsFrom, parseModelName } from './agent.js'
 
 const MAX_FORK_CONTEXT_CHARS = 120_000
 const RUN_SAVE_INTERVAL_MS = 5_000