@bacnh85/pi-subagent 0.3.1 → 0.5.0

package/README.md

@@ -1,88 +1,52 @@
 # pi-subagent
 
-Minimal-overhead sub-agent extension for pi. Delegate tasks to specialized agents with isolated context — running in-process via the pi SDK for zero spawn overhead and ~10x fewer tokens than process-spawning.
-
-## Features
-
-- **In-process execution**: Uses `createAgentSession()` directly — no `spawn("pi")` overhead
-- **Minimal token budget**: Only the agent's system prompt (no AGENTS.md, no extensions, no thinking)
-- **Streaming progress**: Real-time tool-call and text updates during execution
-- **Three modes**: single, parallel (max 8 tasks, 4 concurrent), chain (sequential with `{previous}`)
-- **Abort support**: Esc propagates to all sub-agents
-- **TUI rendering**: Collapsed/expanded views with tool-call formatting and usage stats
-- **Bundled agents**: scout, reviewer, worker — overridable with your own
+Isolated in-process subagents for Pi. The `subagent` tool supports single, parallel (8 tasks, 4 concurrent), and chained execution; `/agent` opens inspectable child threads.
 
 ## Install
 
 ```bash
-cd extensions/pi-subagent
-npm install
-cd ../..
-pi install ./extensions/pi-subagent
-```
-
-Or test directly:
-
-```bash
-pi -e ./extensions/pi-subagent
+pi install npm:@bacnh85/pi-subagent
+# local checkout
+pi install ./pi-subagent
 ```
 
-## Usage
+## Bundled roles
 
-### Single agent
+| Role | Model | Thinking | Tools |
+| --- | --- | --- | --- |
+| `scout` | parent model | low | read, grep, find, ls |
+| `reviewer` | parent model | high | read, grep, find, ls |
+| `worker` | parent model | medium | standard coding tools |
+| `general-purpose` | parent model | off | standard coding tools |
 
-```
-Use scout to find authentication code in this project
-```
+Bundled roles inherit the parent model so they work with the account already active in Pi. User/project agent files may override `model` and `thinking`.
 
-### Parallel execution
+## Agent files
 
-```
-Run 2 scouts in parallel: one for models, one for providers
-```
-
-### Chain workflow
-
-```
-Chain: scout finds auth code, then reviewer checks it for security issues
-```
-
-## Included Agents
-
-| Agent | Model | Tools | Purpose |
-|-------|-------|-------|---------|
-| `scout` | Haiku | read, grep, find, ls | Fast codebase recon |
-| `reviewer` | Sonnet | read, grep, find, ls, bash | Code review |
-| `worker` | Sonnet | all | General implementation |
-
-## Custom Agents
-
-Create Markdown files with YAML frontmatter in `~/.pi/agent/agents/` (user-level) or `.pi/agents/` (project-level):
+Create `~/.pi/agent/agents/*.md` or `.pi/agents/*.md`:
 
 ```markdown
 ---
-name: my-agent
-description: When to use this agent
-tools: read, grep, find, ls, bash
-model: claude-haiku-4-5
+name: scout-fast
+description: Locate relevant files and symbols
+tools: read, grep, find, ls
+thinking: low
+model: optional-provider/optional-model
 ---
 
-Your system prompt here. This is the ONLY prompt the sub-agent sees.
+Return concise evidence with file/symbol anchors.
 ```
 
-See `agent-format.md` for the full format specification.
+Project agents require confirmation when requested through the public tool. Definitions are cached with file-signature invalidation; `/subagent reload` clears the cache.
+
+## Context and limits
 
-## Architecture
+Children use in-memory SDK sessions with no extensions, skills, prompt templates, or automatic `AGENTS.md` loading. The optional `instructions` argument passes a bounded 16 KB task/repository contract. Only Pi built-in tools are available; Serena, FFF, web, and Munin are not available in lean children.
 
-Sub-agents run in-process via the pi SDK. Compared to the process-spawn approach (spawning `pi --mode json`), this saves ~4-11K tokens per sub-agent invocation by:
+Threads are session-memory only and are cleared when Pi replaces or reloads the session. Timeout and parent cancellation propagate to child sessions. Subagents cannot recursively invoke `subagent`.
 
-- Using only the agent's system prompt (no pi defaults)
-- Skipping AGENTS.md, extensions, skills, prompt templates
-- Disabling thinking, compaction, retry
-- Using in-memory sessions (no disk I/O)
-- Sharing the parent's auth/model infrastructure
+## Extension contract
 
-## Requirements
+`pi-subagent` owns the `pi-subagent:run` event contract for one named-agent request. `pi-review` uses it for isolated review. Requests use an immediate boolean `accept()` claim and exactly one `respond()` callback; this suppresses duplicate responders while missing services and timeouts remain caller-controlled.
 
-- pi coding agent with configured API keys
-- Peer dependencies satisfied by the pi runtime (no extra npm install needed)
+See [`agent-format.md`](./agent-format.md) for all frontmatter fields.

package/agent-format.md

@@ -8,7 +8,7 @@ Sub-agents are defined as Markdown files with YAML frontmatter.
 |----------|-------|
 | `~/.pi/agent/agents/*.md` | User-level (all projects) |
 | `.pi/agents/*.md` | Project-level |
-| `<skill>/agents/*.md` | Bundled with pi-sugagents |
+| `<package>/agents/*.md` | Bundled with pi-subagent |
 
 Project agents override user agents with the same name when `agentScope: "both"`.
 
@@ -19,7 +19,8 @@ Project agents override user agents with the same name when `agentScope: "both"`
 name: my-agent          # Required. Unique identifier (kebab-case).
 description: ...        # Required. When to use this agent.
 tools: read, grep, ...  # Optional. Comma-separated tool names. Defaults to all.
-model: claude-haiku-4-5 # Optional. Model ID. Defaults to parent's model.
+model: provider/model     # Optional. Defaults to parent's model.
+thinking: low             # Optional: off|minimal|low|medium|high|xhigh|max.
 ---
 ```
 
@@ -47,13 +48,17 @@ Model IDs are resolved via `getModel("provider", "id")`. Common values:
 
 If not specified, defaults to the parent session's model.
 
+## Instruction handoff
+
+Children do not automatically load repository instructions. Callers may pass an `instructions` task contract, truncated to 16 KB. Use this for relevant repository rules or review contracts rather than copying the parent transcript.
+
 ## Token Budget
 
 Each sub-agent runs with:
 - **System prompt**: agent body only (~200-1K tokens typical)
 - **No AGENTS.md**: saves 500-5K tokens
 - **No extensions/skills loaded**: saves 200-1K tokens
-- **Thinking off**: saves reasoning overhead
+- **Thinking per role**: defaults off; bundled scout/reviewer/worker choose low/high/medium
 - **No compaction**: avoids compaction token cost
 
 This is ~10x leaner than spawning a full `pi` process.

package/agents/reviewer.md

@@ -1,30 +1,36 @@
 ---
 name: reviewer
-description: Code review specialist. Use for reviewing changes, finding bugs, suggesting improvements.
-tools: read, grep, find, ls, bash
-model: openai-codex/gpt-5.5
+description: Code review specialist. Use for correctness, security, regression, and meaningful test-gap review.
+tools: read, grep, find, ls
+thinking: high
 ---
 
-You are a senior code reviewer. Review code changes and provide specific, actionable feedback.
+You are an independent senior code reviewer. Inspect the requested Git scope with read-only tools.
 
-Focus on:
-1. **Correctness**: Logic errors, edge cases, off-by-one
-2. **Security**: Injection risks, auth bypasses, data leaks
-3. **Performance**: N+1 queries, unnecessary allocations, blocking calls
-4. **Maintainability**: Unclear naming, missing error handling, tight coupling
-5. **Best practices**: Idiomatic patterns, testability, documentation
+Focus only on actionable issues introduced by the reviewed change:
+1. Correctness and edge cases
+2. Security and data loss
+3. Regressions and API compatibility
+4. Missing tests that allow a likely bug to escape
 
-Output format:
+Avoid style noise, praise, and speculative redesign. Every finding needs code evidence.
 
-## Summary
-Brief assessment (1-2 sentences)
+Return JSON only:
+```json
+{
+  "summary": "compact scope/result summary",
+  "findings": [
+    {
+      "severity": "critical|high|medium|low",
+      "file": "relative/path",
+      "line": 1,
+      "issue": "what is wrong and why it matters",
+      "evidence": "specific inspected code evidence",
+      "suggestedFix": "smallest safe fix",
+      "blocking": true
+    }
+  ]
+}
+```
 
-## Issues Found
-For each issue:
-- **Severity**: critical | high | medium | low
-- **File**: path with line numbers
-- **Problem**: What's wrong
-- **Fix**: Suggested change (code block)
-
-## Overall Assessment
-Green/yellow/red with reasoning.
+Use an empty `findings` array when clean. Do not modify files or Git state.

package/agents/scout.md

@@ -2,7 +2,7 @@
 name: scout
 description: Fast codebase recon that returns compressed context for handoff. Use for finding files, understanding structure, locating symbols.
 tools: read, grep, find, ls
-model: opencode-go/deepseek-v4-flash
+thinking: low
 ---
 
 You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.
@@ -22,8 +22,8 @@ Strategy:
 
 Output format:
 
-## Files Retrieved
-List with exact line ranges:
+## Evidence
+List exact file/symbol anchors and relevant line ranges:
 1. `path/to/file.ts` (lines 10-50) - Description of what's here
 2. `path/to/other.ts` (lines 100-150) - Description
 3. ...

package/agents/worker.md

@@ -1,7 +1,7 @@
 ---
 name: worker
-description: General-purpose coding agent with full tool access. Use for implementation, refactoring, debugging, and complex multi-step tasks.
-model: opencode-go/deepseek-v4-pro
+description: General-purpose coding agent with full tool access. Use only when explicitly requested for isolated implementation.
+thinking: medium
 ---
 
 You are a skilled software engineer. Implement the requested task with care and precision.

package/{agents.ts → extensions/agents.ts}

@@ -1,5 +1,5 @@
 /**
- * Agent discovery and configuration for pi-sugagents.
+ * Agent discovery and configuration for pi-subagent.
  *
  * Loads agent definitions from Markdown files with YAML frontmatter.
  * Discovers from user-level (~/.pi/agent/agents/), project-level
@@ -18,6 +18,7 @@ export interface AgentConfig {
 	description: string;
 	tools?: string[];
 	model?: string;
+	thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 	systemPrompt: string;
 	source: "user" | "project" | "bundled";
 	filePath: string;
@@ -32,6 +33,7 @@ interface AgentCache {
 	userDir: string;
 	projectDir: string | null;
 	bundledDir: string;
+	scope: AgentScope;
 	agents: AgentConfig[];
 	projectAgentsDir: string | null;
 	/** File-level signature per directory (name:mtime:size for each .md file) */
@@ -69,20 +71,25 @@ function loadAgentsFromDir(dir: string, source: "user" | "project" | "bundled"):
 			continue;
 		}
 
-		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+		const { frontmatter, body } = parseFrontmatter<Record<string, unknown>>(content);
 
-		if (!frontmatter.name || !frontmatter.description) continue;
+		if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") continue;
 
-		const tools = frontmatter.tools
-			?.split(",")
-			.map((t: string) => t.trim())
-			.filter(Boolean);
+		const tools =
+			typeof frontmatter.tools === "string"
+				? frontmatter.tools.split(",").map((t) => t.trim()).filter(Boolean)
+				: Array.isArray(frontmatter.tools)
+					? (frontmatter.tools as unknown[]).filter((t): t is string => typeof t === "string")
+					: undefined;
 
 		agents.push({
 			name: frontmatter.name,
 			description: frontmatter.description,
 			tools: tools && tools.length > 0 ? tools : undefined,
-			model: frontmatter.model || undefined,
+			model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
+			thinking: typeof frontmatter.thinking === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(frontmatter.thinking)
+				? frontmatter.thinking as AgentConfig["thinking"]
+				: undefined,
 			systemPrompt: body,
 			source,
 			filePath,
@@ -151,7 +158,8 @@ export function discoverAgents(
 		_cache &&
 		_cache.userDir === userDir &&
 		_cache.projectDir === projectAgentsDir &&
-		_cache.bundledDir === bundledAgentsDir
+		_cache.bundledDir === bundledAgentsDir &&
+		_cache.scope === scope
 	) {
 		let stale = false;
 		for (const [dir, cachedSig] of _cache.dirSignatures) {
@@ -195,6 +203,7 @@ export function discoverAgents(
 		userDir,
 		projectDir: projectAgentsDir,
 		bundledDir: bundledAgentsDir,
+		scope,
 		agents,
 		projectAgentsDir,
 		dirSignatures,