pi-subagents

The watchdog is an opt-in adversarial reviewer that checks repository edits at the agent_end boundary. It is distinct from the reviewer subagent.

Key Features

• Trigger: Runs only when a writer agent changes the final repo state. It skips unchanged/reverted diffs and .pi-subagents/ or tmp/ artifacts.
• LSP Integration: Automatically checks changed TS/JS files using typescript-language-server. Errors are blockers; warnings are concerns.
• Model Pairing: It is recommended to use a strong, complementary model to your main session (e.g., if using Opus, use GPT).

Commands

• /subagents-watchdog on: Enables the watchdog.
• /subagents-watchdog recommend-model: Asks for the current recommended strong pairing.
• /subagents-watchdog model <model_id>: Sets the watchdog model (e.g., anthropic/claude-opus-4-8:high).
• /subagents-watchdog check: Manually triggers a check.

Configuration

Configure the watchdog in settings using subagents.watchdog:

• Main Watchdog: subagents.watchdog.main.model and subagents.watchdog.main.thinking.
• Child Watchdogs: subagents.watchdog.children.model (default) or subagents.watchdog.children.overrides.<agent>.model.
• LSP Bounds: subagents.watchdog.lsp.enabled, timeoutMs, maxFiles, and maxDiagnostics.

{
  "subagents": {
    "watchdog": {
      "enabled": true,
      "main": {
        "model": "anthropic/claude-opus-4-8",
        "thinking": "high"
      }
    }
  }
}

The oracle agent is a forked advisory thread that inherits the parent session history. It is intended to be used as a 'smart-friend' escalation for trajectory and architectural concerns rather than simple diff inspection.

The Oracle Loop Pattern:

1. Fork to Oracle: The main agent forks to oracle to review direction, drift, assumptions, and risks.
2. Coordinate: oracle can coordinate back via contact_supervisor if the bridge allows.
3. Approve: The main agent decides which direction to approve.
4. Implement: Only after approval does a worker agent implement the task.

When to use oracle:

• Architectural boundaries or model capability routing.
• Merge conflicts or reviewer disagreements.
• Context drift after long work sessions.
• When a worker is about to invent a new pattern or requires product/scope tradeoffs.

// 1. Advisory review in a branched thread
subagent({
  agent: "oracle",
  task: "Review my current direction, challenge assumptions, and propose the best next move."
})

// 2. Implementation only after explicit approval
subagent({
  agent: "worker",
  task: "Implement the approved approach: ..."
})

When dealing with a broad diff with multiple reviewer findings, use a three-stage chain to keep the worktree safe and avoid multiple writers competing in the same space.

The Three Stages:

1. Planning (Parallel Read-Only): Multiple reviewer agents (one per issue cluster) inspect the diff and return proposed fixes/validation plans. They must not edit.
2. Implementation (Single Writer): One worker receives the planning summaries via {previous} and is the sole agent allowed to edit the active worktree.
3. Validation (Parallel Read-Only): Multiple reviewer agents inspect the worker's diff from fresh context to report pass/fail and remaining blockers.

Best Practices:

• Use async: true and context: "fresh" for planners/validators.
• Use outputMode: "file-only" for large summaries.
• Use as and {outputs.name} to pass specific results between stages instead of the entire {previous} blob.
• Use phase and label to make the async status readable.

subagent({
  async: true,
  context: "fresh",
  chain: [
    { parallel: [
      { agent: "reviewer", phase: "Planning", label: "Deploy docs", as: "deployPlan", 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" },
      { agent: "reviewer", phase: "Planning", label: "Scheduler contract", as: "schedulerPlan", 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" },
      { agent: "reviewer", phase: "Planning", label: "Sandbox/security", as: "sandboxPlan", 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" }
    ], concurrency: 3 },
    { agent: "worker", phase: "Implementation", label: "Apply accepted fixes", as: "workerResult", 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:\n{outputs.deployPlan}\n\nScheduler plan:\n{outputs.schedulerPlan}\n\nSandbox plan:\n{outputs.sandboxPlan}", output: "worker/fixes.md", outputMode: "file-only", progress: true },
    { parallel: [
      { agent: "reviewer", phase: "Validation", label: "Deploy/scheduler validation", task: "Validate the post-worker diff for deploy and scheduler fixes. Start from the worker result: {outputs.workerResult}. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/deploy-scheduler.md", outputMode: "file-only" },
      { agent: "reviewer", phase: "Validation", label: "Sandbox validation", task: "Validate the post-worker diff for sandbox/security fixes. Start from the worker result: {outputs.workerResult}. Do not modify project/source files; returning findings via the configured output artifact is allowed.", output: "validation/sandbox.md", outputMode: "file-only" }
    ], concurrency: 2 }
  ]
})

Async runs generate machine-readable lifecycle artifacts for observability.

File Structure

For a top-level async run, details.asyncDir points to a directory containing:

• status.json: Contains stable v1 fields like runId, state, startedAt, endedAt, totalTokens, totalCost, and results.
• events.jsonl: A log of lifecycle transitions (e.g., subagent.run.started, subagent.step.completed, subagent.run.stopped).
• output-<index>.log: Standard output logs.
• subagent-log-<runId>.md: A markdown log of the subagent's activity.

Final summaries are written to the Pi subagent results directory as <runId>.json.

Process Proofs

Lifecycle artifact v3 includes process-terminal-candidate.json (private) and process-terminal.json (public proof). A proof is only marked as observed once the parent observes the exact detached runner's close event and all child writers have closed. If the observer is unavailable, the status is unknown.

Use this to produce a solution brief or implementation-ready handoff by combining external research and local context.

Workflow:

1. Parallel Step: Run researcher (external) and context-builder (local) in parallel.
2. Synthesis Step: A final context-builder reads the previous outputs and writes a handoff/final-handoff-plan.md containing the recommended approach, constraints, risks, and a compact implementation-ready meta-prompt.

subagent({
  chain: [
    { parallel: [
      { agent: "researcher", task: "Research the external reference and transferable implementation ideas for: ...", output: "handoff/external-reference.md" },
      { agent: "context-builder", task: "Build local codebase context for: ...", output: "handoff/local-context.md" },
      { agent: "context-builder", task: "Compare evidence and propose implementation strategy for: ...", output: "handoff/implementation-strategy.md" }
    ] },
    { agent: "context-builder", task: "Read {previous} and synthesize the final handoff plan and implementation-ready meta-prompt.", output: "handoff/final-handoff-plan.md" }
  ],
  context: "fresh"
})

This technique implements an iterative loop where a worker implements fixes and reviewer agents inspect the results until no more significant issues are found.

Workflow:

1. Worker: An async worker implements or fixes code.
2. Reviewer: Fresh-context reviewer agents inspect the actual repo/diff.
3. Synthesis: The parent synthesizes accepted fixes.
4. Application: An async forked worker applies the fixes.

Constraints:

• Async Mode: Use async: true to unblock the main chat. Do not use clarify: true unless explicitly requested.
• Loop Termination: Stop when reviewers find no blockers, an unapproved decision is reached, or the max review-round cap (default 3) is hit.
• Safety: Do not pass turnBudget or toolBudget to mutation-capable children (workers/reviewers with edit authority). Instead, use a narrow task with an elapsed deadline and request a checkpoint.