@pi-unipi/subagents 2.6.1 → 2.9.0

package/skills/subagents/references/multi-lane-orchestration.md

@@ -0,0 +1,39 @@
+# Multi-Lane Orchestration
+
+Use this reference when several independent tasks need coordinated workers, worktrees, or repositories. It defines lane ownership; use the other unipi subagents references for run controls, prompts, and mission details. The parent remains the final decision-maker.
+
+## Lane board and authority
+
+Before multiple mutation-capable lanes start, record this board in the parent context:
+
+`Lane | repo/cwd | exact decision | claimed files or contract | isolation path | authority | next gate | handoff | why independent`
+
+Record the isolation path before the first mutation. Do not split one source seam or decision into duplicate lanes. Make overlapping work one lane with one source of truth.
+
+For every lane, record the delivery target, allowed actions, required validation, and review rigor. For cross-repository work, name the shared contract and which repository changes first. A blocked decision is a lane state: record the owner, options, recommended default, and evidence needed to continue.
+
+## Partitioned runs
+
+Use one writer per repo/cwd or worktree. Mutation lanes need distinct isolation paths and explicit `cwd` values. Set `worktree: true` when a run needs managed worktree isolation within one repository. Read-only runs can share a checkout only when they cannot change state or create generated files.
+
+For Pi extension repositories, keep lane worktrees outside auto-discovered extension directories such as `~/.pi/agent/extensions`. A stale extension worktree there can auto-load duplicate tools and shortcuts. Remove or move it only after its handoff is durable, the worktree is clean, and no run owns it.
+
+Partition fanout by repository, source seam, decision, or review angle. Each run needs a stable key, lane-specific task, and durable output path. Do not launch prompts that differ only by item name or broad file glob.
+
+Use one async `workflowScript` for a coordinated wave. Use `runs.all` for independent lanes and `runs.run` for dependent lane stages. Give cross-repository runs explicit `cwd` values and lane-qualified outputs. Use `outputMode: "file-only"` when a report must survive the run or feed a later stage.
+
+## Keep independent work moving
+
+While one lane waits, run safe independent preparation, validation, or fresh read-only review lanes. Do not block the parent just because a run is active. If no safe lane remains, record the blocker and the event that will reopen work.
+
+An ordinary coordinated workflow has one mission. Use its durable state, artifacts, run records, and receipts for recovery. Treat a receipt as evidence, not as authority or acceptance.
+
+After a writer produces a candidate, run the required fresh-context, read-only reviewer. The reviewer inspects the exact worktree and returns evidence-backed findings. The parent decides which findings are in scope and whether the lane is ready. Send accepted fixes to that lane's sole writer, then rerun only the affected gate.
+
+## Handoff, cleanup, and recovery
+
+Use stable lane-qualified paths for reports and review output. A handoff states the lane status, repository and worktree, changed files, validation, open decisions, next action, and artifact or receipt paths.
+
+Keep a worktree until its handoff is durable, no run owns it, and no later gate needs it. Clean up only inside the recorded authority boundary. If a run stops or needs attention, preserve its worktree and artifacts, record the last known state and recovery owner, then resume that run or create one replacement lane from the handoff. Do not start another writer while worktree ownership is uncertain.
+
+Before completion, inspect the board. Every lane must be terminal or blocked with a named next action. Confirm one writer per repo/cwd or worktree, required validation, required fresh read-only review, and a durable handoff. The parent reports outcomes, evidence, residual risks, and the next decision.

package/skills/subagents/references/prompting-and-roles.md

@@ -0,0 +1,267 @@
+# Pi Subagents: Prompting And Roles
+
+This file is a detailed reference loaded from `skills/subagents/SKILL.md`.
+
+## Capability ceilings
+
+Parent extensions may register a session-scoped, out-of-band ceiling through `unipi subagents/capability-ceiling`. Child tools and eligible canonical agent names are intersected with every active registration and inherited snapshot; `denyExtensions` removes ambient/provider extension loading while retaining package protocol runtime. `{ action: "list" }` marks non-allowlisted agents as restricted, and launch rejects them before spawn. Do not add a model-visible ceiling field or rely on unrestricted role selection for enforcement. Restricted schedules are rejected until their ceiling can be persisted safely.
+
+## When to Use
+
+- **Complex work orchestration**: use Fable mode as the default parent-agent loop for complex work. Complex means the task has multiple moving parts, unclear acceptance, cross-cutting code, meaningful user-visible impact, expensive or irreversible validation, broad review surface, or the user asks for orchestration. Lightweight one-off delegation can stay lightweight.
+- **Advisory review**: use fresh-context `reviewer` agents for adversarial code review, or fork to `oracle` when inherited decisions and drift matter
+- **Implementation handoff**: have `oracle` advise, then `worker` implement only after an approved direction
+- **Recon and planning**: use `scout`, then write a plan when needed
+- **Parallel exploration**: run multiple non-conflicting tasks concurrently
+- **Regular skill specialists**: when discovery shows proactive skill subagent suggestions and the current work is broad enough, launch a small fresh-context fanout that asks one subagent per relevant regularly used skill to apply that skill's perspective to the task
+- **Long-running work**: launch async/background runs and inspect them later. For mutation-capable work, bound the delivery slice and elapsed runtime, then request checkpoints after active tool work returns. Reserve hard turn and tool-call caps for explicitly read-only children.
+- **Subagent control**: watch needs-attention signals and soft-interrupt only when a delegated run is genuinely blocked
+- **Agent authoring**: create, update, or override project agents. Treat saved chain records as legacy inspection or migration inputs, not as a current authoring target.
+
+## Tool vs Slash Commands
+
+Agents use the `subagent(...)` tool with `workflowScript` for execution, and `action` for management, status, and control. Humans often use the slash-command layer instead:
+
+- `/run` — launch a single agent
+- `workflowScript` — the sole public surface for sequence, parallelism, branching, retries, and aggregation
+- `/subagents` — interactive admin for inspecting agents and editing model, thinking, or system prompt
+- `/subagents-stop [run-id]` — stop a current-session top-level async run; opens a selector when no id is given
+- `/subagents-detach [run-id]` — detach an active foreground single-subagent run without terminating its child
+- `/subagent-cost` — show parent plus child token usage and cost for the session
+- `/subagents-fleet` — open the live fleet inspector with per-child controls; `Ctrl+Alt+F` opens it during an active foreground turn, `↑↓`/`jk` selects children, `PgUp`/`PgDn` scrolls transcript detail, `s` steers the selected live async child, and `D` stops its top-level async run after confirmation
+- `/subagents-watchdog` — inspect or configure the opt-in adversarial change watchdog (model, on/off, recommend-model, check)
+- `/subagents-doctor` — diagnose setup, discovery, async paths, and intercom bridge state
+- `/subagents-models [agent]` — show the live runtime-loaded builtin model mapping
+- `/subagents-profiles`, `/subagents-load-profile`, `/subagents-refresh-provider-models`, `/subagents-generate-profiles`, `/subagents-check-profile` — manage model profiles and provider catalogs
+- `/prompt-workflow` — run a prompt template through native workflowScript execution
+
+Prefer the tool when you are writing agent logic. Prefer the slash commands when
+you are guiding a human through an interactive flow.
+
+Packaged prompt shortcuts are also available for repeatable workflows. Treat them as reusable orchestration recipes, not just human slash commands. When the user asks for one of these shapes, or when the workflow clearly fits, apply the same pattern directly with `subagent(...)` and other tools:
+- `/parallel-review` — fresh-context reviewers with distinct review angles, then synthesis
+- `/review-loop` — parent-orchestrated worker, fresh-reviewer, and fix-worker cycles until clean or capped
+- `/parallel-research` — combine `researcher` and `scout` for external evidence plus local code context
+- `/gather-context-and-clarify` — scout/research first, then ask the user clarifying questions with `interview`
+- `/parallel-cleanup` — two fresh-context reviewers (deslop + verbosity passes) for an adversarial cleanup review of the current diff
+- `/council` — bounded advisor council for material decisions, plan critique, cross-exam, and parent-written decision memos
+
+## Applying Prompt Techniques Without Slash Commands
+
+The prompt templates in `prompts/` encode workflows the parent agent can run on demand. If the user provides a URL, issue, PR, plan, local file, screenshot, or freeform target, treat that target as the primary scope: read or fetch it before launching children, then include it explicitly in every child task. For targets outside the parent cwd, include the exact repository, explicit `cwd`, authority boundary, and expected output path in each child task. Do not depend on the parent conversation history when the recipe calls for fresh context.
+
+### Council Mode technique
+
+Use Council Mode when the user asks to convene advisors, debate a material decision, cross-examine recommendations, or critique and improve a plan with several model perspectives. This includes requests such as “run a council on this architecture,” “have Sol, Fable, and Kimi critique this plan,” or “get multiple oracles to debate the tradeoffs.” Read `../council-mode/SKILL.md` and follow its bounded parent-supervised protocol instead of launching ad hoc parallel oracle calls.
+
+Council advisors are read-only. The parent assigns temporary roles such as architect, skeptic, operator, or product reviewer. User or project `council-*` profiles can pin models such as GPT 5.6 Sol, Fable, or Kimi while the `/council` request supplies the role for that run. The parent collects independent reports, optionally sends curated cross-exam packets, and writes the final memo. Do not treat the council as agent-to-agent chat, implementation authority, or a writer swarm.
+
+### Parallel review technique
+
+Use this when the user wants adversarial review of a diff, plan, issue, file, or implemented work. Launch fresh-context `reviewer` agents with distinct angles generated from the actual target. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability; adapt for TypeScript, UI, security, docs, or large structural changes. Reviewers should inspect files and diffs directly, return concise evidence-backed findings with file/line references, and avoid edits unless the user explicitly asks for a writer pass. The parent synthesizes fixes worth doing now, optional improvements, and feedback to ignore/defer before applying anything.
+
+### Proactive skill-specialist technique
+
+Use this when `{ action: "list" }` reports proactive skill subagent suggestions and the user's task would benefit from perspectives the parent regularly uses. These suggestions are conservative: a skill is recommended only when it is available and referenced repeatedly by configured agents or saved chains. Treat the list as an opt-in hint for the current task, not a command to always fan out.
+
+Default guardrails:
+- Keep the fanout small: usually one or two skill-specialist children, never more than the listed recommendations or configured cap.
+- Prefer `context: "fresh"` and include only the files, diff, plan, URL, or request details each child needs. Use forked context only when private/session history is essential and appropriate to share.
+- Use read-only agents for analysis/review unless implementation was explicitly requested; do not create several writers in the same worktree.
+- Skip proactive skill subagents for tiny questions, direct commands, highly private requests, or when the user asks not to delegate.
+- Make cost and concurrency visible by using an ordinary `subagent(...)` call rather than hidden/background automation.
+
+Example shape:
+
+```typescript
+subagent({
+  workflowScript: `
+    const results = await runs.all([
+      { key: "deslop", agent: "reviewer", task: "Apply the available 'deslop' skill to review the current diff for concrete cleanup findings only. Do not modify files.", skill: "deslop" },
+      { key: "accessibility", agent: "reviewer", task: "Apply the available 'accessibility' skill to review the UI changes for concrete issues only. Do not modify files.", skill: "accessibility" }
+    ]);
+    return results.map(result => result.output);
+  `,
+  context: "fresh"
+})
+```
+
+### Review-loop technique
+
+Use this when the user wants implementation or current diff review to continue until reviewers stop finding fixes worth doing now. Keep the loop in the parent session: one async `worker` implements or fixes, fresh-context `reviewer` agents inspect the actual repo and diff, the parent synthesizes accepted fixes, and one async forked `worker` applies them. The parent can express the sequence up front as an async/background `workflowScript` when the workflow is known, or continue with explicit follow-up workflowScript runs after each async completion. For an initial workflow, pass `async: true` so the main chat is unblocked. Treat an async implementation worker handoff as an intermediate state, not final completion, unless the user explicitly asked for worker-only work, review-only output, or to stop after implementation. Stop when reviewers find no blockers or fixes worth doing now, remaining feedback is optional or deferred, an unapproved product/scope/architecture decision appears, or the max review-round cap is reached. Default to 3 review rounds unless the user sets a different cap. Do not loop for optional polish, and do not let children launch subagents or decide the loop outcome.
+
+As a conservative orchestration policy, do not pass `turnBudget` or a hard `toolBudget` to an implementation worker, fix worker, reviewer with edit authority, or other mutation-capable child. The default tool budget blocks read/search tools rather than mutation tools, but count limits still do not measure delivery safety. Use a narrow task plus an outer elapsed deadline with enough margin, then request a checkpoint after the current tool returns. The checkpoint should report changed files, build/test state, remaining work, and commit or PR state. An elapsed timeout is not a mutation-safe boundary and must not be used as the checkpoint trigger.
+
+### Parallel research technique
+
+Use this when the question needs both external evidence and local implications. Combine `researcher` for official docs, specs, ecosystem behavior, recent changes, benchmarks, and primary sources with `scout` for repository files, patterns, constraints, tests, and likely integration points. Give each child a distinct angle: external evidence, local code context, and practical tradeoffs. Ask for source links or file ranges, confidence level, gaps, and decision implications. Do not ask these children to edit unless implementation was explicitly requested.
+
+
+
+### Gather-context-and-clarify technique
+
+Use this at the start of non-trivial work. Launch `scout` for local context and `researcher` only when external docs, recent sources, ecosystem context, or primary evidence would materially improve understanding. Ask children for concise findings plus remaining clarification questions. Then synthesize what is known and use `interview` to ask the unresolved questions needed for shared understanding before planning or implementing.
+
+### Parallel cleanup technique
+
+Use this after implementation when the user wants cleanup review or when a final pass would reduce AI-slop. Launch two fresh-context `reviewer` tasks with `output: false` and `progress: false`: one deslop pass and one verbosity pass. If the `deslop` or `verbosity-cleaner` skills are available, pass the relevant skill to that reviewer; otherwise inline the criteria. Both reviewers are review-only and should flag concrete issues with severity, file/line references, and smallest safe fixes. Phrase the constraint as “Do not modify project/source files; returning findings through the configured output artifact is allowed” when you use `output` or `outputMode: "file-only"`. The parent decides what to apply and asks before making changes unless cleanup was already authorized.
+
+### Staged fix orchestration technique
+
+Use this when a broad diff has known reviewer findings across several items and the user wants the parent to “orchestrate subagents like a boss.” Keep the active worktree safe with a three-stage `workflowScript`:
+
+1. A parallel read-only planning fanout, one reviewer per issue cluster. Each child inspects the real diff and returns exact files, line refs, proposed fixes, and focused validation. They must not edit.
+2. One writer worker. It receives the reviewer summaries as the awaited planning results (or their durable output paths) interpolated into its task, plus the parent’s accepted scope, stop rules, and verification contract. It is the only child allowed to edit the active worktree.
+3. A parallel read-only validation fanout. Validators inspect the worker diff from fresh context with distinct angles, report pass/fail, remaining blockers, and missing verification.
+
+Prefer `async: true`, `context: "fresh"` for reviewers/validators, `outputMode: "file-only"` for large summaries, and per-stage output names that will not collide. Use stable `runs` keys plus `phase` and `label` on each launch item to make async status readable, and hold each awaited result in an ordinary JavaScript variable when a later step needs that specific result — interpolate it (or the durable output path you declared for that child) into the later task text instead of passing a whole aggregate blob. Use this pattern instead of launching several writer workers into a dirty worktree. Include non-blocking suggestions in the writer prompt only when they are small, safe, and do not expand product scope; otherwise record them as deferred.
+
+When one child returns a structured target list, use ordinary JavaScript to validate/filter it and map bounded entries into `runs.all`; do not use the removed chain fanout DSL.
+
+Example shape:
+
+```typescript
+subagent({
+  async: true,
+  context: "fresh",
+  workflowScript: `
+    // Stage 1: parallel read-only planning fanout (stable keys, one per issue cluster)
+    const plans = await runs.all([
+      { key: "deploy-plan", agent: "reviewer", phase: "Planning", label: "Deploy docs", task: "Plan fixes for deploy docs/workflow. Inspect the current diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/deploy.md", outputMode: "file-only" },
+      { key: "scheduler-plan", agent: "reviewer", phase: "Planning", label: "Scheduler contract", task: "Plan fixes for scheduler contract. Inspect the current diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/scheduler.md", outputMode: "file-only" },
+      { key: "sandbox-plan", agent: "reviewer", phase: "Planning", label: "Sandbox/security", task: "Plan fixes for sandbox/security. Inspect the current diff. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "plans/sandbox.md", outputMode: "file-only" }
+    ]);
+
+    // Stage 2: single writer — the only child allowed to edit the active worktree.
+    // Under outputMode "file-only" the awaited .output is the saved-output
+    // reference, so pass the durable paths declared above to the writer.
+    const worker = await runs.run("apply-fixes", {
+      agent: "worker",
+      phase: "Implementation",
+      label: "Apply accepted fixes",
+      task: "Apply only the accepted fixes from these planning summaries. You are the sole writer for the active worktree. Run focused validation and report changed files, commands, failures, and remaining issues.\\n\\nDeploy plan: plans/deploy.md\\n\\nScheduler plan: plans/scheduler.md\\n\\nSandbox plan: plans/sandbox.md",
+      output: "worker/fixes.md",
+      outputMode: "file-only"
+    });
+
+    // Stage 3: parallel read-only validation fanout
+    const validations = await runs.all([
+      { key: "validate-deploy-scheduler", agent: "reviewer", phase: "Validation", label: "Deploy/scheduler validation", task: "Validate the post-worker diff for deploy and scheduler fixes. Start from the worker result: " + worker.output + " (also worker/fixes.md). Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/deploy-scheduler.md", outputMode: "file-only" },
+      { key: "validate-sandbox", agent: "reviewer", phase: "Validation", label: "Sandbox validation", task: "Validate the post-worker diff for sandbox/security fixes. Start from the worker result: " + worker.output + " (also worker/fixes.md). Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/sandbox.md", outputMode: "file-only" }
+    ]);
+
+    return { worker: worker.output, validations: validations.map(v => v.output) };
+  `
+})
+```
+
+## Builtin Agents
+
+Builtin agents load at the lowest priority. Project agents override user agents,
+and user/project agents override builtins with the same name.
+
+| Agent | Purpose | Model | Typical output / role |
+|-------|---------|-------|------------------------|
+| `scout` | Fast codebase recon | inherits default | Writes `context.md` handoff material |
+| `worker` | Implementation and approved oracle handoffs | inherits default | Single-writer implementation with decision escalation |
+| `reviewer` | Review specialist | inherits default | Default recipes are review-only; tools include edit/write when a fix pass is explicit |
+| `researcher` | Web research brief generator | inherits default | Writes `research.md` |
+| `delegate` | Lightweight generic delegate | inherits default | No fixed output; generic delegated work |
+| `oracle` | Decision-consistency advisory review | inherits default | Advisory review, intercom coordination |
+| `advisor` | Claude Code-compatible alias for `oracle` | inherits default | Same advisory role as `oracle` |
+
+Builtin `worker` and `delegate` use strict tool allowlists and do not inherit ambient parent extension tools. To give a child an extension tool, name it in `tools` and load its provider via `extensions`, a path-like `tools` entry, or `subagentOnlyExtensions`. Custom agents without an `extensions` field follow `subagents.defaultExtensions` when set.
+
+Builtin agents inherit the current Pi default model unless a run, user setting, project setting, or `subagents.defaultModel` overrides `model`. Set `subagents.defaultModel` when subagents should use a different default model than the parent session. Override builtin defaults before copying full agent files when a small tweak is enough.
+
+Set `subagents.defaultThinking` to apply a shared thinking level to builtin, package, user, and project agents whose frontmatter leaves `thinking` unset. Project settings win over user settings; explicit frontmatter (including `thinking: false`), `agentOverrides.<name>.thinking`, and per-run overrides remain more specific. This setting affects child agents only and does not change the parent session's default thinking level.
+
+```json
+{
+  "subagents": {
+    "defaultThinking": "medium"
+  }
+}
+```
+
+For one run, use inline config:
+
+```text
+/run reviewer[model=anthropic/claude-sonnet-4] "Review this diff"
+```
+
+For persistent tweaks, edit `subagents.agentOverrides` in user or project settings. User overrides apply everywhere. Project overrides apply only in that repo and win over user overrides. Use `/subagents-models` or `subagent({ action: "models" })` to inspect the live mapping after settings and overrides load.
+
+Model ids do not have to be exact. Separator variations (`claude-haiku-4.5` vs `claude-haiku-4-5`), case (`Claude-Sonnet-4`), and optional trailing date stamps (`claude-haiku-4-5-20251001`) all resolve to the same registry model. Exact `provider/id` wins; a qualified `provider/model` never switches providers. To constrain subagents to a budget or compliance profile, set `subagents.modelScope: { enforce: true, allow: ["anthropic/*", "openai/gpt-5-*"] }` in user or project settings. Out-of-scope models you pass explicitly error and abort; models inherited from frontmatter, `subagents.defaultModel`, agent frontmatter, or the parent session only warn.
+
+For model fleets, use the profile commands instead of hand-editing repeated overrides: `/subagents-refresh-provider-models <provider>`, `/subagents-generate-profiles <provider>`, `/subagents-load-profile <name>`, and `/subagents-check-profile <name>`. Profiles live under `~/.pi/agent/profiles/unipi subagents/` and replace only `settings.subagents` when loaded.
+
+## Prompting role subagents
+
+Builtin role agents inherit the current Pi default model unless you override them. When launching them, write the task prompt as a compact contract, not a long procedural script. Define the destination and let the role choose the efficient path.
+
+A strong subagent prompt usually includes:
+- **Goal**: the concrete outcome the child should produce.
+- **Target**: repository, explicit `cwd`, branch/ref/head, and source seam when the target is not the parent cwd.
+- **Authority boundary**: whether the child may read, edit, commit, push, comment, close, merge, publish, or release. Omit or forbid actions that are not approved.
+- **Context/evidence**: relevant plan paths, files, diffs, decisions, or user constraints already approved.
+- **Success criteria**: what must be true before the child can finish.
+- **Hard constraints**: true invariants only, such as no edits for review-only tasks, one writer thread, child must not run subagents unless it is an explicitly assigned `tools: subagent` fanout child, or escalation for unapproved decisions.
+- **Validation**: targeted checks to run, or the next-best check when validation is impossible.
+- **Output**: the expected summary shape, artifact path, or finding format. Use repo-qualified durable output paths for cross-codebase waves.
+- **Stop rules**: when to ask via `intercom` or `contact_supervisor`, when to stop after enough evidence, and when not to keep searching.
+
+Give each role useful discovery anchors. Name source roots, filenames, symbols, types, methods, and paths for scouts. Give workers context files, plans, task paths, and named source seams before asking them to search. Give reviewers changed files, contracts, and any exhaustive-verification target. Tell oracle whether current source behavior, product/policy documents, plans, or inherited decisions are the evidence that matters.
+
+Avoid carrying over old prompt habits that over-specify every step. Use `must`, `always`, and `never` for real invariants; for judgment calls, give decision rules. For example, tell a reviewer to inspect the staged diff directly and report only evidence-backed findings, rather than prescribing every file or command. Tell a researcher the retrieval budget: start with broad targeted searches, fetch only the strongest sources, search again only when a required fact is missing, then stop.
+
+For implementation handoffs, name the approved scope and success criteria more clearly than the process. Good prompts say what to change, what not to change, where the evidence lives, how to validate, and when to escalate. They should not ask the child to create another subagent plan or continue the parent conversation.
+
+Settings locations:
+- User scope: `~/.pi/agent/settings.json`
+- Project scope: `.pi/settings.json`
+
+Direct settings example:
+
+```json
+{
+  "subagents": {
+    "agentOverrides": {
+      "reviewer": {
+        "model": "anthropic/claude-sonnet-4",
+        "thinking": "high",
+        "fallbackModels": ["openai/gpt-5-mini"],
+        "acceptanceRole": "read-only"
+      }
+    }
+  }
+}
+```
+
+Useful override fields: `description`, `model`, `fallbackModels`, `thinking`,
+`systemPromptMode`, `inheritProjectContext`, `inheritSkills`, `defaultContext`,
+`acceptanceRole`, `disabled`, `skills`, `tools`, `extensions`, and `systemPrompt`.
+`description` replaces the discovered description for builtin and custom agents
+in `list` output, which is useful for deployment-specific routing notes.
+Use `acceptanceRole: false` to clear an override. Create a user or project
+agent with the same name only when you want a substantially different agent.
+
+### Recommended model tiering (optional)
+
+When several providers are available, route agents by task shape instead of one model for everything:
+
+1. **Fast workhorse** — cheapest capable model at low thinking for recon, lookups, and mechanical edits (for example on `scout`).
+2. **Standard well-scoped** — mid-tier model at medium thinking for most delegations: routine multi-file edits, focused reviews, straightforward implementation (for example on `worker`, `reviewer`, `delegate`).
+3. **Deep but bounded** — top reasoning model at high thinking only for hard tasks that arrive with explicit goals and completion criteria; these models loop on vague goals (for example on oracle-style agents).
+4. **Taste and intent** — a model that reads human intent well for ambiguous work: UX/design judgment, product tradeoffs, planning from vague requirements, writing quality.
+
+Routing rule: use tiers 1–3 when the task is well-scoped; use tier 4 when scoping or judging is the task itself. Give tier-4 agents cross-provider `fallbackModels` so subscription usage limits degrade gracefully; fallback triggers automatically on rate-limit and overload errors. Note that forked context over an Anthropic parent transcript with signed thinking blocks forces the child's thinking off, so intent-tier agents work best with fresh context.
+
+If a provider rejects model IDs with thinking suffixes, use
+`subagents.disableThinking: true` in user or project settings to clear bundled
+builtin thinking defaults globally. A higher-precedence per-agent `thinking`
+override can opt one builtin back in. Existing custom-agent frontmatter remains authoritative.
+
+Set `subagents.defaultExtensions` to give agents without an `extensions` field a shared child extension allowlist. Omit it to preserve ambient extension discovery, set it to `[]` to disable ambient extensions by default, or use `agentOverrides.<name>.extensions` for one agent. Explicit custom-agent frontmatter still wins.
+
+Tool description modes live in `~/.pi/agent/extensions/subagent/config.json`, not `subagents` settings. The default uses split prompt metadata: a short tool description plus active `promptSnippet` and `promptGuidelines`. Set `toolDescriptionMode` to `full` or `compact` to force one description string, or `custom` to read `subagent-tool-description.md` from the project config dir or agent dir; invalid custom files fall back to full mode and the safety guidance is still appended.

package/src/acceptance.ts

@@ -0,0 +1,331 @@
+/**
+ * @pi-unipi/subagents — Acceptance gates
+ *
+ * Ported from pi-subagents src/runs/shared/acceptance.ts (core semantics):
+ * levels auto/none/attested/checked/verified, evidence kinds, criteria gates,
+ * verify commands run at the host, structured report parsing from child
+ * output, and the ledger (status/evidenceStatus/runtimeChecks/verifyRuns).
+ */
+
+import { execSync } from "node:child_process";
+
+export const ACCEPTANCE_LEVELS = ["auto", "none", "attested", "checked", "verified"] as const;
+export type AcceptanceLevel = (typeof ACCEPTANCE_LEVELS)[number];
+
+export const ACCEPTANCE_EVIDENCE_KINDS = [
+  "changed-files",
+  "tests-added",
+  "commands-run",
+  "validation-output",
+  "residual-risks",
+  "no-staged-files",
+  "diff-summary",
+  "review-findings",
+  "manual-notes",
+] as const;
+export type AcceptanceEvidenceKind = (typeof ACCEPTANCE_EVIDENCE_KINDS)[number];
+
+const LEVEL_RANK: Record<AcceptanceLevel, number> = {
+  none: 0,
+  auto: 1,
+  attested: 1,
+  checked: 2,
+  verified: 3,
+};
+
+export interface AcceptanceCriterion {
+  id: string;
+  must: string;
+  evidence?: AcceptanceEvidenceKind[];
+  severity?: "required" | "recommended";
+}
+
+export interface VerifyCommand {
+  id: string;
+  command: string;
+  timeoutMs?: number;
+}
+
+export interface AcceptanceConfig {
+  level: AcceptanceLevel;
+  reason?: string;
+  criteria?: AcceptanceCriterion[];
+  evidence?: AcceptanceEvidenceKind[];
+  verify?: VerifyCommand[];
+}
+
+export interface AcceptanceLedger {
+  status: "not-required" | "claimed" | "attested" | "checked" | "verified" | "rejected";
+  evidenceStatus: string;
+  effectiveAcceptance: AcceptanceConfig;
+  criteria: AcceptanceCriterion[];
+  runtimeChecks: Array<{ id: string; status: "passed" | "failed"; message: string }>;
+  verifyRuns: Array<{ id: string; command: string; status: "passed" | "failed" | "timed-out"; output?: string }>;
+  failureMessage?: string;
+}
+
+// ============================================================================
+// Validation (reference error strings)
+// ============================================================================
+
+/** Validate an acceptance input; returns error strings (empty = valid). */
+export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"): string[] {
+  const errors: string[] = [];
+  if (input === undefined || input === false) return errors;
+  if (typeof input === "string") {
+    if (!ACCEPTANCE_LEVELS.includes(input as AcceptanceLevel)) {
+      errors.push(`${pathLabel} has invalid level '${input}'.`);
+    } else if (input === "none") {
+      errors.push(`${pathLabel} level "none" requires a reason; use { level: "none", reason: "..." }.`);
+    } else if (input === "verified") {
+      errors.push(`${pathLabel} level "verified" requires object form with at least one runtime verify command. Use level "checked" or provide a non-empty acceptance.verify array.`);
+    }
+    return errors;
+  }
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    errors.push(`${pathLabel} must be a string level, false, or an object.`);
+    return errors;
+  }
+  const value = input as Record<string, unknown>;
+  const allowedKeys = new Set(["level", "reason", "criteria", "evidence", "verify"]);
+  for (const key of Object.keys(value)) {
+    if (!allowedKeys.has(key)) errors.push(`${pathLabel}.${key} is not supported.`);
+  }
+  if (value.level !== undefined && (typeof value.level !== "string" || !ACCEPTANCE_LEVELS.includes(value.level as AcceptanceLevel))) {
+    errors.push(`${pathLabel}.level must be one of ${ACCEPTANCE_LEVELS.join(", ")}.`);
+  }
+  if (value.level === "none" && (typeof value.reason !== "string" || !(value.reason as string).trim())) {
+    errors.push(`${pathLabel}.reason is required when level is none.`);
+  }
+  if (value.criteria !== undefined && !Array.isArray(value.criteria)) errors.push(`${pathLabel}.criteria must be an array.`);
+  if (Array.isArray(value.criteria)) {
+    const ids = new Set<string>();
+    for (const [index, criterion] of value.criteria.entries()) {
+      const criterionPath = `${pathLabel}.criteria[${index}]`;
+      if (!criterion || typeof criterion !== "object" || Array.isArray(criterion)) {
+        errors.push(`${criterionPath} must be a string or an object.`);
+        continue;
+      }
+      const gate = criterion as Record<string, unknown>;
+      if (typeof gate.id !== "string" || !gate.id.trim()) errors.push(`${criterionPath}.id is required.`);
+      else {
+        const normalized = gate.id.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+        if (ids.has(normalized)) errors.push(`${criterionPath}.id duplicates normalized criterion id '${normalized}'.`);
+        ids.add(normalized);
+      }
+      if (typeof gate.must !== "string" || !gate.must.trim()) errors.push(`${criterionPath}.must is required.`);
+      if (gate.evidence !== undefined && !Array.isArray(gate.evidence)) {
+        errors.push(`${criterionPath}.evidence must be an array.`);
+      }
+      if (Array.isArray(gate.evidence)) {
+        for (const item of gate.evidence) {
+          if (typeof item !== "string" || !ACCEPTANCE_EVIDENCE_KINDS.includes(item as AcceptanceEvidenceKind)) {
+            errors.push(`${criterionPath}.evidence contains unsupported kind '${String(item)}'.`);
+          }
+        }
+      }
+      if (gate.severity !== undefined && gate.severity !== "required" && gate.severity !== "recommended") {
+        errors.push(`${criterionPath}.severity must be required or recommended.`);
+      }
+    }
+  }
+  if (value.level === "verified" && (!Array.isArray(value.verify) || value.verify.length === 0)) {
+    errors.push(`${pathLabel}.verify must contain at least one runtime command when level is verified.`);
+  } else if (value.verify !== undefined && !Array.isArray(value.verify)) {
+    errors.push(`${pathLabel}.verify must be an array.`);
+  }
+  if (Array.isArray(value.verify)) {
+    for (const [index, command] of value.verify.entries()) {
+      if (!command || typeof command !== "object" || Array.isArray(command)) {
+        errors.push(`${pathLabel}.verify[${index}] must be an object with id and command.`);
+        continue;
+      }
+      const cmd = command as Record<string, unknown>;
+      if (typeof cmd.id !== "string" || !cmd.id.trim()) errors.push(`${pathLabel}.verify[${index}].id is required.`);
+      if (typeof cmd.command !== "string" || !cmd.command.trim()) errors.push(`${pathLabel}.verify[${index}].command is required.`);
+    }
+  }
+  return errors;
+}
+
+/** Normalize shorthand forms into a full config. */
+export function normalizeAcceptanceInput(input: unknown): AcceptanceConfig | undefined {
+  if (input === undefined || input === false) return undefined;
+  if (typeof input === "string") {
+    return { level: input as AcceptanceLevel };
+  }
+  const value = input as Record<string, unknown>;
+  return {
+    level: (value.level as AcceptanceLevel) ?? "auto",
+    ...(typeof value.reason === "string" ? { reason: value.reason } : {}),
+    ...(Array.isArray(value.criteria) ? { criteria: value.criteria as AcceptanceCriterion[] } : {}),
+    ...(Array.isArray(value.evidence) ? { evidence: value.evidence as AcceptanceEvidenceKind[] } : {}),
+    ...(Array.isArray(value.verify) ? { verify: value.verify as VerifyCommand[] } : {}),
+  };
+}
+
+/** Gate shorthand: one host-run verification command. */
+export function normalizeGateAcceptance(gate: unknown): AcceptanceConfig | undefined {
+  if (typeof gate !== "string" || !gate.trim()) return undefined;
+  return {
+    level: "verified",
+    verify: [{ id: "gate", command: gate.trim() }],
+  };
+}
+
+// ============================================================================
+// Report parsing + evaluation
+// ============================================================================
+
+export interface AcceptanceReport {
+  criteria?: Array<{ id: string; satisfied: boolean; notes?: string }>;
+  evidence?: Partial<Record<AcceptanceEvidenceKind, string>>;
+  residualRisks?: string[];
+}
+
+const REPORT_OPEN = "<acceptance-report>";
+const REPORT_CLOSE = "</acceptance-report>";
+
+/** Parse the structured acceptance report from child output. */
+export function parseAcceptanceReport(output: string): { report?: AcceptanceReport; error?: string } {
+  const start = output.indexOf(REPORT_OPEN);
+  const end = output.indexOf(REPORT_CLOSE);
+  if (start === -1 || end === -1 || end < start) {
+    return { error: "Structured acceptance report not found." };
+  }
+  const body = output.slice(start + REPORT_OPEN.length, end).trim();
+  try {
+    const parsed = JSON.parse(body) as AcceptanceReport;
+    if (!parsed || typeof parsed !== "object") throw new Error("not an object");
+    return { report: parsed };
+  } catch (error) {
+    return { error: `Invalid acceptance-report JSON: ${error instanceof Error ? error.message : String(error)}` };
+  }
+}
+
+/** Strip the report block from output shown to the parent. */
+export function stripAcceptanceReport(output: string): string {
+  const start = output.indexOf(REPORT_OPEN);
+  const end = output.indexOf(REPORT_CLOSE);
+  if (start === -1 || end === -1) return output;
+  return (output.slice(0, start) + output.slice(end + REPORT_CLOSE.length)).trim();
+}
+
+function checkCriteriaSatisfied(
+  criteria: AcceptanceCriterion[],
+  report: AcceptanceReport,
+): Array<{ id: string; status: "passed" | "failed"; message: string }> {
+  const checks: Array<{ id: string; status: "passed" | "failed"; message: string }> = [];
+  const reported = new Map((report.criteria ?? []).map((c) => [c.id, c]));
+  for (const criterion of criteria) {
+    const match = reported.get(criterion.id);
+    if (!match) {
+      checks.push({
+        id: `criterion:${criterion.id}`,
+        status: criterion.severity === "recommended" ? "passed" : "failed",
+        message: `Criterion '${criterion.id}' missing from child report.`,
+      });
+    } else if (!match.satisfied && criterion.severity !== "recommended") {
+      checks.push({
+        id: `criterion:${criterion.id}`,
+        status: "failed",
+        message: `Criterion '${criterion.id}' not satisfied${match.notes ? `: ${match.notes}` : "."}`,
+      });
+    } else {
+      checks.push({ id: `criterion:${criterion.id}`, status: "passed", message: criterion.must });
+    }
+  }
+  return checks;
+}
+
+/**
+ * Evaluate acceptance: parse the child's report, check criteria, run verify
+ * commands at the host, and produce the ledger.
+ */
+export async function evaluateAcceptance(input: {
+  acceptance: AcceptanceConfig;
+  output: string;
+  cwd: string;
+  signal?: AbortSignal;
+}): Promise<AcceptanceLedger> {
+  const acceptance = input.acceptance;
+  const ledger: AcceptanceLedger = {
+    status: acceptance.level === "none" ? "not-required" : "claimed",
+    evidenceStatus: acceptance.level === "none" ? "not-required" : "claimed",
+    effectiveAcceptance: acceptance,
+    criteria: acceptance.criteria ?? [],
+    runtimeChecks: [],
+    verifyRuns: [],
+  };
+  if (acceptance.level === "none") return ledger;
+
+  // Attestation: structured report present? Gate-shorthand configs (verify
+  // commands without criteria) skip the report requirement — the host command
+  // IS the verification.
+  const gateOnly = (acceptance.verify?.length ?? 0) > 0 && (acceptance.criteria?.length ?? 0) === 0;
+  const parsed = parseAcceptanceReport(input.output);
+  if (parsed.report) {
+    ledger.status = "attested";
+    ledger.evidenceStatus = "attested";
+  } else if (!gateOnly && (LEVEL_RANK[acceptance.level] >= LEVEL_RANK.checked || acceptance.level === "attested")) {
+    ledger.runtimeChecks.push({ id: "attestation", status: "failed", message: parsed.error ?? "Structured acceptance report missing." });
+    ledger.status = "rejected";
+    ledger.evidenceStatus = "rejected";
+    ledger.failureMessage = `Acceptance rejected: ${parsed.error}`;
+    return ledger;
+  }
+
+  // Criteria checks at checked+.
+  if (parsed.report && LEVEL_RANK[acceptance.level] >= LEVEL_RANK.checked) {
+    ledger.runtimeChecks = checkCriteriaSatisfied(ledger.criteria, parsed.report);
+    if (ledger.runtimeChecks.some((check) => check.status === "failed")) {
+      ledger.status = "rejected";
+      ledger.evidenceStatus = "rejected";
+      ledger.failureMessage = `Acceptance rejected: ${ledger.runtimeChecks.find((c) => c.status === "failed")!.message}`;
+      return ledger;
+    }
+    ledger.status = "checked";
+    ledger.evidenceStatus = "checked";
+  }
+
+  // Runtime verify commands at verified+.
+  if (LEVEL_RANK[acceptance.level] >= LEVEL_RANK.verified && (acceptance.level === "verified" || (acceptance.verify?.length ?? 0) > 0)) {
+    for (const command of acceptance.verify ?? []) {
+      if (input.signal?.aborted) break;
+      try {
+        const output = execSync(command.command, {
+          cwd: input.cwd,
+          encoding: "utf8",
+          timeout: command.timeoutMs ?? 120_000,
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+        ledger.verifyRuns.push({ id: command.id, command: command.command, status: "passed", output: output.slice(-2000) });
+      } catch (error) {
+        const err = error as { status?: number; message?: string; killed?: boolean };
+        ledger.verifyRuns.push({
+          id: command.id,
+          command: command.command,
+          status: err.killed ? "timed-out" : "failed",
+          output: (err.message ?? "").slice(-2000),
+        });
+      }
+    }
+    if (ledger.verifyRuns.some((run) => run.status === "failed" || run.status === "timed-out")) {
+      const failed = ledger.verifyRuns.find((r) => r.status !== "passed")!;
+      ledger.status = "rejected";
+      ledger.evidenceStatus = "rejected";
+      ledger.failureMessage = `Acceptance verification '${failed.id}' ${failed.status}.`;
+      return ledger;
+    }
+    if (!ledger.runtimeChecks.some((check) => check.status === "failed")) {
+      ledger.status = "verified";
+      ledger.evidenceStatus = "verified";
+    }
+  }
+
+  if (ledger.status === "claimed") {
+    ledger.status = acceptance.level === "auto" ? "attested" : (acceptance.level as AcceptanceLedger["status"]);
+    ledger.evidenceStatus = ledger.status;
+  }
+  return ledger;
+}