pi-subagents 0.17.2 → 0.17.4

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [0.17.4] - 2026-04-22
+
+### Added
+- Bundled a `pi-subagents` skill that teaches agents how to use builtin subagents, slash-command vs tool workflows, management-mode agent creation/editing, fork/intercom coordination, clarify mode, worktrees, async status inspection, and chain templating.
+
+### Changed
+- Tightened the builtin `oracle` prompt so intercom-enabled forked reviews now prefer concise conversational handoffs during the review and send a short final recommendation via `pi-intercom` before returning the full structured result.
+- Tightened `oracle-executor` so it explicitly frames itself as the single writer thread and escalates gaps in the approved direction instead of silently patching around them.
+
+## [0.17.3] - 2026-04-22
+
+### Added
+- Added builtin `oracle` and `oracle-executor` agents for the `main -> oracle -> main decision -> oracle-executor` workflow, plus README guidance for invoking the oracle pair with forked context.
+
+### Fixed
+- Migrated extension tool schemas from `@sinclair/typebox` to `typebox` 1.x so packaged installs follow Pi's current extension runtime contract.
+
+### Changed
+- Moved TypeBox from `peerDependencies` to a real `dependencies` entry so `pi install` production installs keep the schema package available at runtime.
+
 ## [0.17.2] - 2026-04-21
 
 ### Added

package/README.md

@@ -46,7 +46,10 @@ Project discovery also reads legacy `.agents/{name}.md` files. If both `.agents/
 
 Use `agentScope` parameter to control discovery: `"user"`, `"project"`, or `"both"` (default; project takes priority).
 
-**Builtin agents:** The extension ships with ready-to-use agents — `scout`, `planner`, `worker`, `reviewer`, `context-builder`, `researcher`, and `delegate`. They load at lowest priority so any user or project agent with the same name overrides them.
+**Builtin agents:** The extension ships with ready-to-use agents — `scout`, `planner`, `worker`, `reviewer`, `context-builder`, `researcher`, `delegate`, `oracle`, and `oracle-executor`. They load at lowest priority so any user or project agent with the same name overrides them.
+
+- `oracle` is a high-context advisory reviewer on `openai-codex/gpt-5.4:high`. It critiques direction, surfaces hidden risks, and proposes a concrete execution prompt, but it does not edit files directly.
+- `oracle-executor` is a high-context implementation escalator on `openai-codex/gpt-5.3-codex:high`. It is intended to run only after the main agent explicitly approves a course of action.
 
 You can also override selected builtin fields without copying the whole agent. Builtin overrides are stored in settings under `subagents.agentOverrides`:
 
@@ -301,6 +304,22 @@ You can combine `--fork` and `--bg` in any order:
 /run reviewer "review this diff" --bg --fork
 ```
 
+For the oracle pair, the intended default control loop is:
+
+1. main agent invokes `oracle` with forked context
+2. `oracle` returns diagnosis, recommendation, risks, and a suggested execution prompt
+3. main agent decides whether to accept that direction
+4. only then does main agent invoke `oracle-executor`
+
+Example:
+
+```text
+/run oracle "Review my current direction, challenge assumptions, and propose the best next move." --fork
+/run oracle-executor "Implement the approved approach: ..." --fork
+```
+
+This keeps decision authority in the main thread while still giving you a stronger review/escalation path.
+
 ## Agents Manager
 
 Press **Ctrl+Shift+A** or type `/agents` to open the Agents Manager overlay — a TUI for browsing, viewing, editing, creating, and launching agents and chains.

package/agents/oracle-executor.md

@@ -0,0 +1,49 @@
+---
+name: oracle-executor
+description: High-context implementation agent that executes only after main-agent approval
+tools: read, grep, find, ls, bash, edit, write, intercom
+model: openai-codex/gpt-5.3-codex
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+defaultProgress: true
+---
+
+You are `oracle-executor`: a high-context implementation subagent.
+
+You are the single writer thread. Your job is to execute approved direction, not to make new architectural or product decisions.
+
+You are invoked after the main agent has already decided on a direction, often based on advice from `oracle`. You are allowed to act, but you are not the owner of product or architecture decisions. The main agent remains the final decision authority.
+
+If runtime bridge instructions are present, use them as the source of truth for which orchestrator session to contact and how to coordinate. Use `intercom({ action: "ask", ... })` when a new decision is needed to continue safely. Use `intercom({ action: "send", ... })` for concise progress or completion handoffs when that extra coordination is helpful.
+
+First understand the inherited context and the explicit task. Then execute carefully and minimally.
+
+If the task appears to require a new decision that has not clearly been approved by the main agent, stop and ask via `intercom` instead of making that decision yourself.
+
+Default responsibilities:
+- validate the approved direction against the actual code
+- implement the approved change with minimal, coherent edits
+- verify the result with appropriate checks
+- report back clearly, including risks and next steps
+
+Working rules:
+- Follow existing patterns in the codebase.
+- Prefer narrow, correct changes over broad rewrites.
+- Do not add speculative scaffolding or future-proofing unless explicitly required.
+- Use `bash` for inspection, validation, and relevant tests.
+- Escalate uncertainty to the main agent with `intercom` when needed.
+- If the implementation reveals a gap in the approved direction, pause and escalate via `intercom` rather than silently patching around it with an implicit decision.
+- If implementation reveals an unapproved product or architecture choice, pause and ask via `intercom` instead of deciding it yourself.
+- If you send a completion handoff through `intercom`, keep it short and still return the full structured task result normally.
+- Keep `progress.md` accurate when asked to maintain it.
+- Do not silently change the scope of the task.
+
+Your completion handoff should follow this exact shape:
+
+Implemented X.
+Changed files: Y.
+Validation: Z.
+Open risks/questions: R.
+Recommended next step: N.

package/agents/oracle.md

@@ -0,0 +1,74 @@
+---
+name: oracle
+description: High-context decision-consistency oracle that protects inherited state and prevents drift
+tools: read, grep, find, ls, bash, intercom
+model: openai-codex/gpt-5.4
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+---
+
+You are the oracle: a high-context decision-consistency subagent.
+
+Your primary job is to prevent the main agent from making hidden, conflicting, or inconsistent decisions by treating the inherited forked context as the authoritative contract. You are not the primary executor. You do not silently become a second decision-maker.
+
+Before you do anything else, reconstruct the key inherited decisions, constraints, and open questions from the forked conversation, codebase state, and task. Those decisions form your baseline contract. Preserve them unless there is strong evidence they should be overturned.
+
+If you need clarification from the main agent, use `intercom`. If runtime bridge instructions are present, use them as the source of truth for which orchestrator session to contact and how to phrase coordination.
+
+Use `intercom({ action: "ask", ... })` when you need a real decision or clarification. Use `intercom({ action: "send", ... })` for concise conversational handoffs during the review and for a short final recommendation before you return your full result. Keep intercom traffic tight and purposeful. Do not narrate your whole review through intercom, but do treat `intercom` as the preferred path for back-and-forth with the orchestrator when bridge instructions are available.
+
+Core responsibilities:
+- reconstruct inherited decisions, constraints, and open questions from the context
+- identify drift between the current trajectory and those inherited decisions
+- surface contradictions and hidden assumptions the main agent may be missing
+- call out when a proposed move conflicts with an earlier decision or constraint
+- protect consistency over novelty; prefer the path that honors existing decisions unless the context clearly supports a pivot
+- when you do recommend a pivot, explain exactly which prior assumption or decision should be revised and why
+- exploit your clean forked context to spot things the main agent may have missed due to context rot, accumulated reasoning, or errors in the original instruction
+- look beyond the explicit question and suggest guidance based on the overall agent trajectory, even when not directly asked
+
+What you do not do by default:
+- do not edit files or write code
+- do not propose additional parallel decision-makers or new subagent trees unless explicitly asked
+- do not assume an `oracle-executor` handoff is the default outcome
+- do not propose broad pivots unless the context clearly supports them
+- do not continue the user conversation directly
+
+Working rules:
+- Use `bash` only for inspection, verification, or read-only analysis.
+- If information is missing and it matters, ask the main agent via `intercom` instead of guessing.
+- If the answer depends on a decision the main agent has not made yet, stop and ask via `intercom` before continuing.
+- When bridge instructions are present, send concise intercom messages when a recommendation, concern, or question would benefit from immediate discussion instead of waiting silently until the final return.
+- Before returning your full structured result, send a short intercom handoff summarizing the recommended next move when bridge instructions are present.
+- Prefer narrow, specific corrections to the current path over rewriting the whole plan.
+
+Your output should follow this shape. If no executor handoff is warranted, say so plainly.
+
+Inherited decisions:
+- the key decisions, constraints, and assumptions already in play
+
+Diagnosis:
+- what is actually going on
+- what the main agent may be missing
+
+Drift / contradiction check:
+- where the current trajectory conflicts with inherited decisions or constraints
+- what assumptions have quietly changed
+
+Recommendation:
+- the best next move
+- why it is the best move
+- if recommending a pivot, which inherited decision is being revised and why
+
+Risks:
+- what could still go wrong
+- what assumptions remain uncertain
+
+Need from main agent:
+- specific question or decision required before continuing, if any
+
+Suggested execution prompt:
+- a concrete prompt for `oracle-executor`, only if an executor handoff is actually warranted
+- if no handoff is warranted, say so explicitly

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.17.2",
+  "version": "0.17.4",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -30,6 +30,7 @@
     "!*.test.ts",
     "*.mjs",
     "agents/",
+    "skills/**/*",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -44,14 +45,19 @@
     "extensions": [
       "./index.ts",
       "./notify.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "peerDependencies": {
     "@mariozechner/pi-agent-core": "*",
     "@mariozechner/pi-ai": "*",
     "@mariozechner/pi-coding-agent": "*",
-    "@mariozechner/pi-tui": "*",
-    "@sinclair/typebox": "*"
+    "@mariozechner/pi-tui": "*"
+  },
+  "dependencies": {
+    "typebox": "^1.1.24"
   },
   "devDependencies": {
     "@marcfargas/pi-test-harness": "^0.5.0",

package/schemas.ts

@@ -2,7 +2,7 @@
  * TypeBox schemas for subagent tool parameters
  */
 
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 
 // Note: Using Type.Any() for Google API compatibility (doesn't support anyOf)
 const SkillOverride = Type.Any({ description: "Skill name(s) to inject (comma-separated), array of strings, or boolean (false disables, true uses default)" });

package/skills/pi-subagents/SKILL.md

@@ -0,0 +1,426 @@
+---
+name: pi-subagents
+description: |
+  Delegate work to builtin or custom subagents with single-agent, chain,
+  parallel, async, forked-context, and intercom-coordinated workflows. Use
+  for advisory review, implementation handoffs, and multi-step tasks where a
+  single agent should stay in control while other agents contribute context,
+  planning, or execution.
+---
+
+# Pi Subagents
+
+Use this skill when you need to launch a specialized subagent, compose multiple
+agents into a workflow, or create/edit agents and chains on demand.
+
+## When to Use
+
+- **Advisory review**: fork to `oracle` or `reviewer` for a branched review thread
+- **Implementation handoff**: have `oracle` advise, then `oracle-executor` or `worker` implement
+- **Recon and planning**: use `scout` or `context-builder`, then `planner`
+- **Parallel exploration**: run multiple non-conflicting tasks concurrently
+- **Long-running work**: launch async/background runs and inspect them later
+- **Agent authoring**: create, update, or override agents and chains for a project
+
+## Tool vs Slash Commands
+
+Agents can use the `subagent(...)` and `subagent_status(...)` tools directly.
+Humans often use the slash-command layer instead:
+
+- `/run` — launch a single agent
+- `/chain` — launch a chain of steps
+- `/parallel` — launch top-level parallel tasks
+- `/agents` — open the agents manager TUI
+- `/subagents-status` — inspect active/recent async runs
+
+Prefer the tool when you are writing agent logic. Prefer the slash commands when
+you are guiding a human through an interactive flow.
+
+## 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 | `openai-codex/gpt-5.4-mini` | Writes `context.md` handoff material |
+| `planner` | Creates implementation plans | `openai-codex/gpt-5.4` | Writes `plan.md` |
+| `worker` | General implementation | `openai-codex/gpt-5.4` | Edits code directly |
+| `reviewer` | Review-and-fix specialist | `openai-codex/gpt-5.3-codex:high` | Can edit/fix reviewed code |
+| `context-builder` | Requirements/codebase handoff builder | `openai-codex/gpt-5.4` | Writes structured context files |
+| `researcher` | Web research brief generator | `openai-codex/gpt-5.4` | Writes `research.md` |
+| `delegate` | Lightweight generic delegate | inherits parent model | No fixed output; generic delegated work |
+| `oracle` | Decision-consistency advisory review | `openai-codex/gpt-5.4:high` | Advisory review, intercom coordination |
+| `oracle-executor` | Implementation after approval | `openai-codex/gpt-5.3-codex:high` | Single-writer implementation after approval |
+
+Override builtin defaults via settings before copying full agent files when a
+small tweak is enough.
+
+Settings locations:
+- User scope: `~/.pi/agent/settings.json`
+- Project scope: `.pi/settings.json`
+
+Useful override fields: `model`, `fallbackModels`, `thinking`,
+`systemPromptMode`, `inheritProjectContext`, `inheritSkills`, `disabled`,
+`skills`, `tools`, and `systemPrompt`.
+
+## Discovery and Scope Rules
+
+Agent files can live in:
+- `~/.pi/agent/agents/*.md` — user scope
+- `.pi/agents/*.md` — canonical project scope
+- legacy `.agents/*.md` — still read for compatibility, but `.pi/agents/` wins on conflicts
+
+Chains live in:
+- `~/.pi/agent/agents/*.chain.md`
+- `.pi/agents/*.chain.md`
+- legacy `.agents/*.chain.md`
+
+Precedence is:
+1. project scope
+2. user scope
+3. builtin agents
+
+## Running Subagents
+
+### Single agent
+
+```typescript
+subagent({
+  agent: "oracle",
+  task: "Review my current direction and challenge assumptions."
+})
+```
+
+### Forked context
+
+```typescript
+subagent({
+  agent: "oracle",
+  task: "Review my current direction and challenge assumptions.",
+  context: "fork"
+})
+```
+
+`context: "fork"` creates a branched child session from the current persisted
+parent session. It does **not** create a fresh minimal review context or filter
+history down to only the relevant parts. Use it when you want a separate review
+or execution thread that can still reference the parent session history.
+
+### Parallel execution
+
+```typescript
+subagent({
+  tasks: [
+    { agent: "scout", task: "Explore the auth module" },
+    { agent: "reviewer", task: "Review the API client" }
+  ]
+})
+```
+
+### Chain execution
+
+```typescript
+subagent({
+  chain: [
+    { agent: "scout", task: "Map the auth flow and summarize key files" },
+    { agent: "planner", task: "Create an implementation plan from {previous}" },
+    { agent: "worker", task: "Implement the approved plan based on {previous}" }
+  ]
+})
+```
+
+Chain steps can use templated variables such as `{task}`, `{previous}`, and
+`{chain_dir}`. This is the main way to pass structured summaries between steps
+without forcing each step to rediscover everything.
+
+### Async/background
+
+```typescript
+subagent({
+  agent: "worker",
+  task: "Run the full test suite",
+  async: true
+})
+```
+
+Inspect async runs with the `subagent_status(...)` tool or the
+`/subagents-status` slash command.
+
+## Clarify TUI
+
+Single and parallel runs support a clarification TUI when you want to preview or
+edit parameters before launch:
+
+```typescript
+subagent({
+  agent: "worker",
+  task: "Implement feature X",
+  clarify: true
+})
+```
+
+Chains default to clarify mode unless you explicitly set `clarify: false`.
+For programmatic background launches, use `clarify: false, async: true`.
+
+## Worktree Isolation
+
+When multiple agents might write concurrently, use worktrees instead of letting
+them share one filesystem view.
+
+```typescript
+subagent({
+  tasks: [
+    { agent: "worker", task: "Implement feature A" },
+    { agent: "worker", task: "Implement feature B" }
+  ],
+  worktree: true
+})
+```
+
+`worktree: true` gives each parallel task its own git worktree branched from
+HEAD. This requires a clean git state and is mainly for intentionally parallel
+write workflows. If you want one writer thread and several advisory agents,
+prefer a single-writer pattern instead.
+
+## The Oracle Workflow
+
+The intended oracle loop is:
+1. the main agent forks to `oracle`
+2. `oracle` reviews direction, drift, assumptions, and risks
+3. `oracle` can coordinate back to the orchestrator via `intercom`
+4. the main agent decides what direction to approve
+5. only then should `oracle-executor` implement
+
+```typescript
+// Advisory review in a branched thread
+subagent({
+  agent: "oracle",
+  task: "Review my current direction, challenge assumptions, and propose the best next move.",
+  context: "fork"
+})
+
+// Implementation only after explicit approval
+subagent({
+  agent: "oracle-executor",
+  task: "Implement the approved approach: ...",
+  context: "fork"
+})
+```
+
+`oracle` is not a fresh-context reviewer in the Cognition article sense. It is
+a forked advisory thread that inherits the parent session history and uses that
+history as a baseline contract.
+
+## Subagent + Intercom Coordination
+
+When `pi-intercom` is installed and enabled, delegated runs can coordinate with
+the orchestrator through the intercom bridge.
+
+### Subagent asks the orchestrator
+
+```typescript
+intercom({
+  action: "ask",
+  to: "orchestrator",
+  message: "Should I optimize for readability or performance here?"
+})
+```
+
+### Orchestrator replies
+
+```typescript
+intercom({ action: "reply", message: "Optimize for readability." })
+```
+
+Or inspect unresolved asks first:
+
+```typescript
+intercom({ action: "pending" })
+```
+
+Use `intercom` when:
+- a subagent is blocked on a decision
+- an advisory agent wants to send a concise handoff mid-flight
+- a detached or async child needs to coordinate without waiting for normal tool return flow
+
+## Management Mode
+
+The `subagent(...)` tool also supports management actions.
+
+### List available agents and chains
+
+```typescript
+subagent({ action: "list" })
+```
+
+### Create an agent
+
+```typescript
+subagent({
+  action: "create",
+  config: {
+    name: "my-agent",
+    description: "Project-specific implementation helper",
+    systemPrompt: "Your system prompt here.",
+    systemPromptMode: "replace",
+    model: "openai-codex/gpt-5.4",
+    tools: "read,grep,find,ls,bash"
+  }
+})
+```
+
+### Update an agent
+
+```typescript
+subagent({
+  action: "update",
+  agent: "my-agent",
+  config: {
+    thinking: "high"
+  }
+})
+```
+
+### Delete an agent
+
+```typescript
+subagent({ action: "delete", agent: "my-agent" })
+```
+
+Use management actions when the system needs to create or edit subagents on
+demand without dropping into raw file editing.
+
+## Creating and Editing Agents by File
+
+A minimal agent file looks like this:
+
+```markdown
+---
+name: my-agent
+description: What this agent does
+model: openai-codex/gpt-5.4
+thinking: high
+tools: read, grep, find, ls, bash
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+---
+
+Your system prompt here.
+```
+
+That is only a starting point. Common optional fields include:
+- `defaultProgress`
+- `defaultReads`
+- `output`
+- `fallbackModels`
+- `maxSubagentDepth`
+
+For many customizations, builtin overrides in settings are lower-friction than
+copying a full builtin file.
+
+## Prompt Template Integration
+
+If `pi-prompt-template-model` is installed, prompt templates can delegate into
+`pi-subagents`. This is useful when a slash command should always run through a
+particular agent or with forked context.
+
+## Important Constraints
+
+- **Forking requires a persisted parent session.** If the current session does not
+  have a persisted session file, forked runs fail.
+- **Forked runs inherit parent history.** They are branched threads, not fresh
+  filtered contexts.
+- **Default subagent nesting depth is 2.** Deeper recursive delegation is blocked
+  unless configured otherwise.
+- **Intercom asks are blocking.** A session can only maintain one pending outbound
+  ask wait state at a time.
+- **Keep conversational authority clear.** Advisory subagents should not silently
+  become second decision-makers.
+
+## Best Practices
+
+### Keep writes single-threaded by default
+
+A strong pattern is one main decision-maker plus advisory/research/review
+subagents around it. Use `oracle` for advice and `oracle-executor` or `worker`
+for the actual write path.
+
+### Use fork for branched advisory or execution threads
+
+Forked runs are useful when the child should reason in a separate thread while
+still inheriting the parent’s accumulated context.
+
+### Prefer narrow tasks
+
+Give subagents specific tasks rather than vague mandates.
+`Review auth.ts for null-check gaps` works better than `Review everything`.
+
+### Escalate decisions upward
+
+If a subagent encounters an unapproved product, architecture, or scope choice,
+it should coordinate back via `intercom` instead of deciding alone.
+
+### Name sessions meaningfully
+
+Use `/name` so intercom targeting stays stable.
+
+## Common Workflows
+
+### Recon → Plan → Implement
+
+```typescript
+subagent({
+  chain: [
+    { agent: "scout", task: "Map the auth flow and summarize relevant files" },
+    { agent: "planner", task: "Plan the migration from {previous}" },
+    { agent: "worker", task: "Implement the approved plan from {previous}" }
+  ]
+})
+```
+
+### Review loop
+
+```typescript
+subagent({ agent: "worker", task: "Add retry logic to the API client." })
+subagent({
+  agent: "reviewer",
+  task: "Review the retry logic implementation. Look for edge cases and race conditions.",
+  context: "fork"
+})
+```
+
+### Parallel non-conflicting analysis
+
+```typescript
+subagent({
+  tasks: [
+    { agent: "scout", task: "Audit frontend auth flow" },
+    { agent: "researcher", task: "Research current retry/backoff best practices" }
+  ]
+})
+```
+
+## Error Handling
+
+**"Unknown agent"**
+```typescript
+subagent({ action: "list" })
+// Check available agents and chains, then confirm scope/precedence.
+```
+
+**"Max subagent depth exceeded"**
+```typescript
+// Flatten the workflow or raise maxSubagentDepth in config.
+```
+
+**"Session manager did not return a session file"**
+```typescript
+// Persist the current session before using context: "fork".
+```
+
+**Intercom "Already waiting for a reply"**
+```typescript
+// Resolve the current outbound ask before starting another one.
+```