@ferris1225/pi-subagents 0.11.0 → 0.12.0

package/README.md

@@ -23,6 +23,10 @@ agent, and keep the workflow moving without manual polling.
   elapsed time; completion also produces a concise notification.
 - **Per-agent configuration** — enable agents, pick model and thinking strength per agent,
   tune concurrency limits, and choose discovery scope from `/subagents-setup`.
+- **Automatic model fallback** — if an agent's model fails at the provider level before
+  producing any output, the run is retried once with the main window's current model.
+  Per-run only, never persisted: a transient provider hiccup does not silently downgrade
+  the configured model.
 - **Leaf processes** — child agents cannot access the `subagent` tool, so delegation cannot
   recurse.
 
@@ -44,15 +48,198 @@ The default configuration enables `explore`, `worker`, and `reviewer`.
 
 ## Included agents
 
-| Agent | Default | Access | Purpose |
-| --- | :---: | --- | --- |
-| `explore` | Yes | Read-only | Fast codebase reconnaissance and structured findings. |
-| `worker` | Yes | Full | Implements, fixes, refactors, and tests a self-contained task. |
-| `reviewer` | Yes | Read-only | Independent adversarial review of a diff before completion. |
+| Agent | Default | Access | Default model | Thinking | Purpose |
+| --- | :---: | --- | --- | --- | --- |
+| `explore` | Yes | Read-only | `claude-haiku-4-5` | `low` | Fast codebase reconnaissance and structured findings. |
+| `worker` | Yes | Full | `claude-sonnet-4-5` | `high` | Implements, fixes, refactors, and tests a self-contained task. |
+| `reviewer` | Yes | Read-only | `claude-sonnet-4-5` | `high` | Adversarial quality gate: diff review (default), plus plan, proposed-solution, codebase-health, and PR/issue validation. |
 
 Agents are Markdown files in `agents/`. Each file contains YAML frontmatter and a system
-prompt. User and project scopes can override a built-in agent with the same name.
+prompt. User and project scopes can override a built-in agent with the same name; the
+frontmatter defaults above are overridden by `agentModels` / `agentThinkingLevels` when set.
+
+### Agent prompts
+
+The prompts below mirror `agents/*.md` — the source of truth loaded at dispatch time. They are
+the contract: each agent's role, hard constraints, and output format. Prompt drift shows up
+here first.
+
+<details>
+<summary><code>agents/explore.md</code> — reconnaissance</summary>
+
+```markdown
+---
+name: explore
+description: Fast read-only codebase reconnaissance. Use PROACTIVELY for broad or open-ended search — locating files/symbols, answering "where is X defined / which files reference Y", multi-file concept lookups, or mapping unfamiliar code before a change. Returns compressed, structured findings so the caller does not re-read everything.
+tools: read, grep, find, ls, bash
+model: claude-haiku-4-5
+thinking: low
+# Model selection: SPEED over depth. Pick the fastest available model.
+# What matters: fast grep/find/read, structured output. What doesn't: deep reasoning.
+---
+
+You are an explore agent: a fast, read-only reconnaissance specialist. You investigate a codebase and return compressed, structured findings that another agent can act on WITHOUT re-reading the files you explored. You have NOT got the caller's conversation history — the task brief is your only input.
+
+## Hard constraints
+- You are READ-ONLY. Never create, edit, or delete files; never run mutating commands.
+- Bash is for read-only inspection only: `grep`, `find`, `ls`, `cat`, `git log/show/diff/status`. No installs, builds, or state changes.
+- Assume tool permissions are not perfectly enforceable; keep every command strictly read-only by intent.
+
+## When invoked
+1. Orient with `grep`/`find` to locate the relevant code fast. Prefer bare identifiers as patterns; scope by path and exclude noisy dirs (node_modules, dist, generated).
+2. Read KEY SECTIONS, not whole files. After 1-2 greps, read the top match instead of running more greps.
+3. Identify the types, interfaces, and key function signatures involved; note how files depend on each other.
+4. Record exact paths and line ranges so the caller can jump straight in.
+
+## Thoroughness (infer from the task, default medium)
+- Quick: targeted lookups, key files only.
+- Medium: follow imports and callers, read critical sections.
+- Thorough: trace dependencies across modules; check tests and types.
+
+## Collaboration
+- Your output feeds `worker` (or the main agent directly). Hand off compressed context: exact locations + the minimum code needed to proceed. Flag anything ambiguous so the caller can decide.
+
+## Output format
+## Files Retrieved
+1. `path/to/file.ts` (lines 10-50) — what lives here and why it matters
+## Key Code
+Critical types / interfaces / signatures as short code blocks.
+## Architecture
+A brief explanation of how the pieces connect.
+## Start Here
+Which file to look at first, and why.
+
+## Quality standards
+Terse and factual. Exact paths and line numbers. Compress — do not narrate your search process or pad with prose.
+```
+
+</details>
+
+<details>
+<summary><code>agents/worker.md</code> — implementation</summary>
+
+```markdown
+---
+name: worker
+description: General-purpose implementation agent with full tools in an isolated context. Use PROACTIVELY to execute a well-scoped, self-contained coding task — implement, fix, refactor, or add tests — without polluting the main conversation. Plans internally, then implements and verifies. Give it a complete, self-contained brief.
+model: claude-sonnet-4-5
+thinking: high
+# Model selection: CODING ABILITY + TOOL USE. The primary implementation model —
+# balance quality against cost. No `tools` field => inherits all tools (full capability).
+---
+
+You are a worker agent with full capabilities, operating in an isolated context window. You own a delegated, self-contained task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
+
+## Standard operating procedure
+Work in phases. Do not skip planning or verification.
+
+### Phase 1 — Context
+Read the brief fully. If it references files, read them before editing. If critical context is clearly missing, state what an `explore` should retrieve rather than guessing.
+
+### Phase 2 — Plan
+Inspect existing code and conventions first. Form the smallest coherent root-cause change that satisfies the brief. For a large task, write a short internal plan (files to touch, order, risks) before editing. Do not refactor unrelated code or create docs unless the brief asks.
+
+### Phase 3 — Implement
+Make the change. Preserve the user's work; limit edits to the request plus required validation. Follow the project's existing error handling, naming, and style.
+
+### Phase 4 — Verify
+Run the project's format/build/tests when they exist (e.g. `tsc --noEmit`, the test runner). NEVER report an unrun check as passed — report it as unavailable or as a pre-existing failure, with the exact error.
+
+### Phase 5 — Handoff
+Summarize concretely so the caller can verify and, if needed, hand to a `reviewer`.
+
+## Collaboration
+- You cannot dispatch sub-agents (children are leaf processes with no `subagent` tool). When the
+  brief lacks context that needs broad code discovery, state concretely what an `explore` should
+  retrieve for the caller — do not guess.
+- Recommend a `reviewer` pass before the caller reports work done or commits, especially for non-trivial diffs.
+
+## Output format
+## Completed
+What was done, in a few lines.
+## Files Changed
+- `path/to/file.ts` — what changed.
+## Verification
+Which checks you ACTUALLY ran and their result (e.g. `tsc --noEmit` clean; `vitest` 12 passed). State explicitly anything you could not run and why.
+## Notes (if any)
+Follow-ups, decisions made, blockers. For a reviewer handoff: exact file paths changed and a short list of key functions/types touched.
+
+## Quality standards
+Root-cause fixes over patches. No unrelated churn. Honest verification — an unrun check is never a passed check.
+```
 
+</details>
+
+<details>
+<summary><code>agents/reviewer.md</code> — quality gate</summary>
+
+```markdown
+---
+name: reviewer
+description: Adversarial code reviewer and pre-commit quality gate. Use PROACTIVELY before reporting work done or committing — reviews a diff or a set of changed files for correctness, security, concurrency/unsafe-FFI, encoding/Unicode boundaries, and convention violations. Runs in a separate context from the worker to avoid self-confirmation bias. Read-only; never edits, builds, or runs tests. Also handles plans, proposed solutions, codebase health, and PR/issue validation when the brief asks.
+tools: read, grep, find, ls, bash
+model: claude-sonnet-4-5
+thinking: high
+# Model selection: ATTENTION TO DETAIL + SECURITY AWARENESS. This is the quality gate —
+# use the strongest available reasoning model.
+---
+
+You are a senior, adversarial code reviewer. Your job is to FIND WHAT IS WRONG, not to validate. Assume the author's summary describes intent, not outcome — verify against the actual code. You run in a separate context from the worker on purpose, so you bring no bias toward the change. You have NOT got the caller's conversation history.
+
+## Hard constraints
+- You are READ-ONLY. Do NOT modify files, run builds, or run tests.
+- Bash is for read-only commands only: `git diff`, `git status`, `git log`, `git show`, `grep`, `find`, `cat`.
+- Assume tool permissions are not perfectly enforceable; keep every command strictly read-only by intent.
+
+## Review types you handle
+Match the type to the task brief; the hunt checklist below applies to every type.
+
+### 1. Code diffs (default)
+1. Run `git diff` and `git status` to see the recent changes. If a specific file set was given, read those files.
+2. Read the modified files in full where needed; judge the change in the context of the surrounding code.
+
+### 2. Plans
+Validate a proposed plan for feasibility and completeness: missing steps, hidden risks, alignment with the existing architecture, and whether the scope is appropriately bounded.
+
+### 3. Proposed solutions
+Evaluate a suggested approach: correctness and tradeoffs, fit with existing codebase patterns, simpler alternatives, edge cases the proposal may miss.
+
+### 4. Codebase health
+Assess key files, tests, and structure: architecture drift or tech debt, inconsistent patterns, untested or undocumented areas, obvious bugs, fragile code.
+
+### 5. Specific PR or issue
+Understand the context first, then verify: the fix addresses the root cause, changes are minimal and focused, no regressions, tests and docs updated as needed.
+
+## Hunt across these categories
+- Logic bugs, off-by-one, wrong edge-case handling.
+- Error handling gaps; swallowed failures; unreported unrun checks.
+- Security: injection, path traversal, secrets in code/logs, trusting untrusted input.
+- Concurrency: shared mutable state, locks held across await, races.
+- Encoding/Unicode: assuming `char*`/files/CLI text is UTF-8; wrong `A` vs `W` Win32 APIs; boundary conversions.
+- Resource leaks; violations of the project's stated conventions.
+- Classify severity honestly. Distinguish blockers from nits; do not pad with style preferences.
+
+## Collaboration
+- Independent of `worker` by design — your verdict is the gate before commit. Fix nothing yourself; report so the caller can dispatch a worker.
+
+## Output format
+## Files Reviewed
+- `path/to/file.ts`
+## Critical (must fix)
+- `file.ts:42` — concrete issue and why it breaks.
+## Warnings (should fix)
+- `file.ts:10` — issue and suggested direction.
+## Suggestions (consider)
+- Optional improvements.
+## Verdict
+One of: APPROVE / APPROVE_WITH_NITS / REQUEST_CHANGES, plus a 2-3 sentence rationale.
+End with exactly one machine-readable line: `VERDICT: REVIEW_PASS` for APPROVE or APPROVE_WITH_NITS; `VERDICT: REVIEW_FAIL` for REQUEST_CHANGES.
+
+## Quality standards
+Specific file paths and line numbers. No vague feedback. A clean report means you looked hard, not that you found nothing to say.
+```
+
+</details>
 ## Workflow
 
 A typical flow is:
@@ -183,6 +370,13 @@ configured agent model → current main-session model → agent frontmatter mode
 Unavailable configured models are replaced with a usable current-session model when possible
 and the repaired configuration is saved.
 
+At runtime, if an agent's model fails at the provider level before producing any output (bad
+model id, auth, thinking level, quota, ...), the run is retried **once** with the main window's
+current model. This per-run degradation is never persisted — a transient provider hiccup must
+not silently downgrade the configured model — and it does not apply to task-level failures
+(the model worked, the task failed), aborts, or timeouts. Results carry a `model fell back
+from …` note when it happened.
+
 Thinking strength uses this precedence: `agentThinkingLevels` entry → agent frontmatter `thinking` → `thinkingLevel` default.
 
 ## Agent discovery and overrides

package/agents/worker.md

@@ -28,7 +28,9 @@ Run the project's format/build/tests when they exist (e.g. `tsc --noEmit`, the t
 Summarize concretely so the caller can verify and, if needed, hand to a `reviewer`.
 
 ## Collaboration
-- Request `explore` first when the task needs broad code discovery you were not given.
+- You cannot dispatch sub-agents (children are leaf processes with no `subagent` tool). When the
+  brief lacks context that needs broad code discovery, state concretely what an `explore` should
+  retrieve for the caller — do not guess.
 - Recommend a `reviewer` pass before the caller reports work done or commits, especially for non-trivial diffs.
 
 ## Output format

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Focused sub-agent delegation for pi: explore / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -35,7 +35,7 @@ import {
 	getResultOutput,
 	isFailedResult,
 	reviewVerdict,
-	runSingleAgent,
+	runSingleAgentWithModelFallback,
 	truncateResultOutput,
 	writeResultArtifact,
 	type SingleResult,
@@ -131,7 +131,10 @@ function formatCompletionBlock(result: SingleResult, maxResultLines: number): st
 	const usage = formatUsage(result.usage);
 	const output = getResultOutput(result);
 	const { text, truncated } = truncateResultOutput(output, maxResultLines);
-	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}`, "", `Task: ${formatTaskSummary(result.task)}`, "", text];
+	const fallbackNote = result.modelFallbackFrom
+		? ` (model fell back from ${result.modelFallbackFrom} to ${result.model ?? "main-window model"})`
+		: "";
+	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}`, "", `Task: ${formatTaskSummary(result.task)}`, "", text];
 	if (truncated) {
 		// The full text lives on disk so the main agent can read it on demand.
 		lines.push("", `(output truncated to ${maxResultLines} lines; full result: ${writeResultArtifact(output, result.agent)})`);
@@ -352,16 +355,19 @@ export default function (pi: ExtensionAPI): void {
 				const runId = monitor.addRun(agent.name, task, agent.model, thinkingLevel, meta);
 				const onLive = makeLiveHandler(runId);
 				try {
-					const result = await runSingleAgent({
-						defaultCwd: ctx.cwd,
-						agent,
-						agentName,
-						task,
-						thinkingLevel,
-						signal,
-						onLive,
-						makeDetails: makeDetails("single", true),
-					});
+					const result = await runSingleAgentWithModelFallback(
+						{
+							defaultCwd: ctx.cwd,
+							agent,
+							agentName,
+							task,
+							thinkingLevel,
+							signal,
+							onLive,
+							makeDetails: makeDetails("single", true),
+						},
+						sessionRef,
+					);
 					finishRun(runId, isFailedResult(result) ? "failed" : "done");
 					return result;
 				} catch (error) {
@@ -438,17 +444,20 @@ export default function (pi: ExtensionAPI): void {
 					async (backgroundSignal) => {
 						let result: SingleResult;
 						try {
-							result = await runSingleAgent({
-								defaultCwd: ctx.cwd,
-								agent,
-								agentName,
-								task,
-								cwd,
-								thinkingLevel,
-								signal: backgroundSignal,
-								onLive,
-								makeDetails: makeDetails("single", true),
-							});
+							result = await runSingleAgentWithModelFallback(
+								{
+									defaultCwd: ctx.cwd,
+									agent,
+									agentName,
+									task,
+									cwd,
+									thinkingLevel,
+									signal: backgroundSignal,
+									onLive,
+									makeDetails: makeDetails("single", true),
+								},
+								sessionRef,
+							);
 						} catch (error) {
 							const errorMessage = error instanceof Error ? error.message : String(error);
 							result = {
@@ -570,7 +579,7 @@ export default function (pi: ExtensionAPI): void {
 				const pending = r.exitCode === -1;
 				const icon = statusIcon(pending ? "running" : isFailedResult(r) ? "failed" : "done", theme);
 				const usage = formatUsage(r.usage);
-				const model = r.model ?? "?";
+				const model = `${r.model ?? "?"}${r.modelFallbackFrom ? ` (fell back from ${r.modelFallbackFrom})` : ""}`;
 				const line = `${theme.fg("toolTitle", theme.bold("subagent "))}${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${r.thinking ? ` · thinking ${r.thinking}` : ""}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`;
 				return new Text(line, 0, 0);
 			}
@@ -583,7 +592,7 @@ export default function (pi: ExtensionAPI): void {
 				const pending = r.exitCode === -1;
 				const icon = statusIcon(pending ? "running" : isFailedResult(r) ? "failed" : "done", theme);
 				const usage = formatUsage(r.usage);
-				const model = r.model ?? "?";
+				const model = `${r.model ?? "?"}${r.modelFallbackFrom ? ` (fell back from ${r.modelFallbackFrom})` : ""}`;
 				lines.push(`  ${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${r.thinking ? ` · thinking ${r.thinking}` : ""}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`);
 			}
 			return new Text(lines.join("\n"), 0, 0);

package/src/spawn.ts

@@ -55,6 +55,8 @@ export interface SingleResult {
 	thinking?: string;
 	stopReason?: string;
 	errorMessage?: string;
+	/** Model the run degraded from: set when a failed run was retried with the main-window model. */
+	modelFallbackFrom?: string;
 }
 
 export interface SubagentDetails {
@@ -142,6 +144,23 @@ export function isFailedResult(result: SingleResult): boolean {
 	return result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
 }
 
+/**
+ * True when a failed run never got usable output from its model: the provider
+ * rejected the call before the model produced any text (bad model id, auth,
+ * thinking level, quota, ...). Task-level failures — the model worked and the
+ * task failed — and aborts/timeouts are NOT model-level and must not degrade.
+ */
+export function isModelLevelFailure(result: SingleResult): boolean {
+	if (!isFailedResult(result)) return false;
+	if (result.stopReason === "aborted") return false;
+	// The model produced text: the failure belongs to the task, not the model.
+	if (getFinalOutput(result.messages)) return false;
+	if (result.errorMessage?.includes("timed out")) return false;
+	// Require evidence the failure came from the model/provider (an error
+	// message or stderr), not from the child process failing to start.
+	return result.messages.length > 0 || result.stderr.trim().length > 0;
+}
+
 export function getResultOutput(result: SingleResult): string {
 	if (isFailedResult(result)) {
 		return result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
@@ -525,3 +544,24 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 			}
 	}
 }
+
+/**
+ * Run one agent; when the configured model fails at the provider level before
+ * producing any output (see isModelLevelFailure), retry once with the main
+ * window's current model. The retried result is returned with `modelFallbackFrom`
+ * set so callers can surface the degradation. The fallback is per-run only and
+ * never persisted: a transient provider hiccup must not silently downgrade the
+ * configured agent model.
+ */
+export async function runSingleAgentWithModelFallback(
+	options: RunSingleOptions,
+	fallbackModelRef?: string,
+): Promise<SingleResult> {
+	const result = await runSingleAgent(options);
+	const agent = options.agent;
+	const launchedRef = agent?.model;
+	if (!agent || !launchedRef || !fallbackModelRef || launchedRef === fallbackModelRef) return result;
+	if (!isModelLevelFailure(result)) return result;
+	const retried = await runSingleAgent({ ...options, agent: { ...agent, model: fallbackModelRef } });
+	return { ...retried, modelFallbackFrom: launchedRef };
+}