Phase 3–4 Deep Dive

Orchestration

Subagent spawning, task swarm isolation, model roles, risk taxonomy, and model-specific prompt variants. The intelligence layer that makes the agent self-directing.

R3 → R19: Subagents → Task Swarm

Tier 1 Supersession Background task pool (R3) evolving into 100-parallel isolated agents with git worktree backends (R19).

R3: Subagent spawning → R19: Task Agent Swarm
Capability
R3 (Phase 3)
R19 (Extension)
oh-my-pi
Parallel agents
10
10
100
Isolation backend
None
Worktree
FUSE/ProjFS
Fork mode (cache sharing)
Yes
Yes
Yes
Background notification
Yes
Yes
Yes
Merge strategies
N/A
Patches
Full
subagent lifecycle
spawn pi.registerTool("agent") — typed or fork mode
pool BackgroundTaskPool — max 10 concurrent, configurable
output summary via followUp + full at ~/.subq/agent/subagent-outputs/{id}.jsonl
fork SessionManager.forkFrom() — shares parent cache prefix
orphan self-terminate after 60s (reduced from 5min for security)
cancel /cancel <task_id> or /cancel all via pi.registerCommand()
worktree git worktree add — serialize creation with semaphore
safety filter git branch -D, git tag -d, git gc in worktrees

Discriminated Input

TypedAgentInput vs ForkAgentInput — no impossible states. TypeBox stays flat for LLMs.

Discriminated Result

{ status: "completed" | "failed" | "running" } — each variant carries exactly the fields it needs.

Shared BackgroundRunner

R3 pool, R6 auto-trigger, R14 pipeline all share one abstraction: run/error/lifecycle/notify.

Tool Restriction

Read-only subagents (R6 verification) spawn without bash, edit, or write. Only read, grep, find, ls.

Cache Sharing

Fork mode shares parent’s cache prefix. Different model_role values share family cache line.

R16: Model Roles

Tier 4 Novel Configure default/smol/slow/plan/commit models. Auto-discovery from provider. ≥30% cost reduction on exploration sessions.

default

Primary Agent

Main model for implementation, editing, and conversation. Full capability baseline.

smol

Cheap Exploration

Read-only operations: grep, find, read, ls, context_pack. Auto-suggest when next action is read-only.

slow

Deep Reasoning

Architecture decisions, complex debugging. Higher cost justified by accuracy on hard problems.

plan

Planning

Structured plan generation. Optimized for multi-step reasoning and dependency analysis.

commit

Commit Messages

Conventional commit generation. Small model, fast turnaround, low cost per commit.

≥30%
Cost reduction on exploration sessions
Cost math: If 60% of an exploration session’s turns use smol instead of default, cost reduction is 0.6 × (1 − smol_cost/default_cost) ≈ 30%. Achievable with good routing logic that auto-suggests smol for read-only operations.

R4: Risk-Based Authorization

Tier 2 Planned Silent decision tree replacing flat “don’t” lists. Agent self-assesses per-action without verbalizing for SAFE actions.

risk decision tree
DESTRUCTIVE rm -rf, git reset --hard, drop table, kill processes → ALWAYS ask
HARD-TO-REVERSE force push, amend published, downgrade deps, modify CI → ask unless pre-authorized
VISIBLE-TO-OTHERS push, create/close PRs, send messages, post external → ask unless instructed
SAFE everything else → proceed without asking, say nothing about risk
Key insight: The old instruction “state the risk category in ≤1 sentence” is a verbosity trap. The model prepends risk assessments to every tool call. Instead: silently classify. Only speak when asking permission. Pre-authorizations are ONLY recognized under ## Pre-Authorized Actions in AGENTS.md.
Pre-Authorization Format (AGENTS.md)
AGENTS.md
## Pre-Authorized Actions
- Push to feature/* branches without asking
- Run npm run deploy:staging without confirmation

R7: Model-Specific Variants

Tier 2 Planned Per-model-family prompt patches targeting actual failure modes. Variants in dynamic suffix to preserve single cache entry.

Family
Failure Mode
Variant Patch
Qwen
Over-comments, skips verification
Suppress comments on new code. MUST execute verification command and include stdout.
Claude
False claim accuracy, safety caveats
Quote actual terminal output. Drop “I should note” asides unless genuinely dangerous.
GPT
Question repetition, narration, filler
No question repeat-back. Execute first, don’t narrate plan. Ban “Great question!” et al.
DeepSeek
Non-English comments, phantom paths
English for all code. Verify file paths exist before editing.

Discriminated Unions

5 of 8 proposed types replaced with discriminated unions: AgentToolInput, HookResponse, MemoryEntry, AgentToolResult, TtsrMatchResult.

TypeBox + Narrow

TypeBox schema stays flat (LLMs can’t reason about unions). Internal TS type narrows via resolver functions.

SubqConfig Split

Flat config bag split into namespaced sub-interfaces: hooks, modelRoles, memory, session, autonomous.

Event Name Mapping

PreToolUse→tool_call via satisfies Record for exhaustive compile-time checks.

A/B Testing

20 benchmark tasks per failure mode. Measure: comment density, claim accuracy, response length, verification rate.