Delegation

Delegation & Parallelization Reference

Last synced: Oct 27, 2026

RETIRED 2026-07-21 (BLE capability-surfacing cleanup). The Delegation skill and this reference are gone: they hand-maintained a manual of harness capabilities (Task(), TeamCreate/team_name, max_turns, effort tiers) that rotted against the live tool surface. Capability existence is surfaced natively — tool schemas ride in context every turn, skills list their USE WHEN, agent types their descriptions, ToolSearch loads the rest. What LifeOS keeps is only what the harness can’t know: election rules and spend facts (Algorithm §Spend), the fork-reviewer clause (criterion 11), dispatch/model rules (OPERATIONAL_PREFERENCES § Model selection). The retired-tokens /ic check blocks this rot class from returning. One exception is current: ## Dispatch practice below (added 2026-09-24), which Algorithm § Routing points to for how a leg is sent. Everything else is history.

Delegation & Parallelization Reference

Delegation exists so the LifeOS hill-climb (LifeOs/LifeOsThesis.md) doesn’t serialize: independent gap-closing work runs in parallel, matched to the cheapest model that can do it.

No skill fronts this file any more (the Delegation skill was retired 2026-07-21). Only § Dispatch practice below is current.

History: Delegation & Parallelization (retired 2026-07-21, not current guidance)

Model Selection for Agents (CRITICAL FOR SPEED)

The Agent tool has a model parameter - USE IT.

Resuming agents: To continue a previously spawned agent, use SendMessage({to: agentId}). This auto-resumes stopped background agents. Do NOT use Agent(resume=...) — the resume parameter no longer exists.

Agents that omit model inherit the session model (harness behavior — the AgentInvocation model injector was removed v1.3.0, 2026-07-11 baseline; the hook now only logs each dispatch’s resolved model to subagent-events.jsonl). Model choice is per-dispatch judgment: pass model explicitly when a different rung fits the work — the light worker (or Sonnet on a Claude-only install) for utility or mechanical fan-outs, the strongest available for intelligence-hungry dispatches (note model: fable on Agent executed Opus at last probe, 2026-07-07 — genuine Fable off the main loop is the Inference.ts --level max subprocess). Each inference with 30K+ context takes 5-15 seconds on a frontier model; a simple 10-tool-call task = 1-2+ minutes of pure thinking time.

Model Selection Matrix:

Task Type	Model	Why
(This table is the Claude-tier ladder, the default for an install with no other vendor. Where `WORK_LADDER` in `LIFEOS/TOOLS/models.ts` names worker agents, send the leg to the worker for that level instead; `OPERATIONAL_PREFERENCES § Model selection` decides.)
Deep reasoning, complex architecture, strategic decisions	`opus`	Maximum intelligence needed
Standard implementation, moderate complexity, most coding	`sonnet`	Good balance of speed + capability
Simple lookups, file reads, quick checks, parallel grunt work	the light worker, else `sonnet`	Fast and cheap. Never the smallest Claude tier: it cannot hold a brief, and as a worker wrapper it did the work itself and returned nothing

Examples:

// Inherits the session model for a simple visual check
Agent({ prompt: "Check if blue bar exists on website", subagent_type: "general-purpose" })

// Inherits the session model for standard coding work
Agent({ prompt: "Senior engineer, TDD. Implement the login form validation", subagent_type: "general-purpose" })

// RIGHT - Opus for complex architectural planning
Agent({ prompt: "System design / distributed systems. Design the distributed caching strategy", subagent_type: "general-purpose", model: "opus" })

Rule of Thumb:

If it’s grunt work or verification → the light worker, else sonnet
If it’s implementation or research → sonnet
If it requires deep strategic thinking → opus (or let it default)

Parallel tasks especially benefit from the light lane - launching 5 light agents is faster AND cheaper than 1 Opus agent doing sequential work.

Agent Types

Default for parallel work: custom agents as inline briefs on general-purpose. (The old Agents composition skill — ComposeAgent/Traits.yaml — was retired; see AgentSystem.md § Forbidden Patterns. Public issue #1504, @tzioup, caught the stale routing here.)

Compose task-specific agents by writing the role/perspective/voice directly into each prompt:

Use a SINGLE message with MULTIPLE Agent tool calls
Each agent gets FULL CONTEXT and a DETAILED role brief written into its prompt, launched with subagent_type: "general-purpose"
~~Launch as many as needed (no artificial limit)~~ — corrected 2026-07-23 (public PR #1569, @elhoim): since Claude Code 2.1.217, concurrently-running subagents are capped (default 20, override CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS) and subagents no longer spawn nested subagents by default (override CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH)
ALWAYS launch a spotcheck agent after parallel work completes

Agent routing by task type:

Research tasks → Use the Research skill (has dedicated researcher agents)
Code implementation → Use general-purpose with a senior-engineer/TDD brief in the prompt
Architecture/design → Use general-purpose with a system-design / distributed-systems brief in the prompt
Everything else → Write a distinct inline brief per agent → subagent_type: "general-purpose"

History: Agent routing (Agent Teams as the default is retired; `TeamCreate` and `team_name` no longer exist, and routing is Algorithm § Routing)

Three Agent Systems — preference order:

Priority	User Says	System	Tool	What Happens
1. DEFAULT	”parallel work”, “agents”, “team”, “swarm”, or Algorithm selects delegation	Agent Teams	`TeamCreate` → `Agent` with `team_name` → `TaskCreate` → `SendMessage`	Persistent teammates, shared task list, peer messaging, task dependencies
2. EXPLICIT	”custom agents”, “spin up custom agents”	Custom Agents (inline briefs)	`Agent(subagent_type="general-purpose", prompt=<distinct role brief per agent>)`	Unique personalities, voices, one-shot parallel work
3. UNATTENDED	”run overnight”, “long-running”, “CI trigger”, or task exceeds session lifetime	Managed Agents (Anthropic cloud API)	`Skill("claude-api")` to build workflows	Durable sessions, sandboxed containers, vault credentials, $0.08/session-hour

These are three distinct systems:

Agent Teams = persistent local teammates with shared task lists, messaging, and multi-turn coordination via TeamCreate. DEFAULT for all parallel work.
Custom Agents = one-shot parallel workers with unique identities written as inline briefs. ONLY when the principal explicitly says “custom agents”.
Managed Agents = cloud-hosted agents with durable sessions that survive disconnects. For unattended/overnight work only.

Additional routing by task type:

User Says	What to Use	Why
”research X”, “investigate Y”	Research skill	Dedicated researcher agents
Code implementation tasks	`general-purpose` + senior-engineer/TDD brief	Job-specific brief replaces the retired Engineer type
Architecture/design tasks	`general-purpose` + system-design brief	Job-specific brief replaces the retired Architect type

For Agent Teams (default):

TeamCreate with descriptive team name
TaskCreate for each work item (with dependencies if needed)
Spawn teammates via Agent with team_name and name parameters
Teammates self-claim tasks, message each other, go idle between rounds

For Custom Agents (only when explicitly requested):

Write a distinct inline brief for EACH agent — role, perspective, voice, expertise in the prompt itself
Launch each brief as subagent_type: "general-purpose"
Each agent’s voice is described in the brief

For research specifically: Use the Research skill. Quick and Standard run each vendor’s search as a tool call in the session, with no agent; Extensive and Deep fan out the dedicated researcher agents (ClaudeResearcher, GeminiResearcher, etc.) as parallel legs.

Before spawning any agent: Router rules 27–28 (Algorithm § Routing) apply. A subagent on the session’s own model earns its place only through parallel width, a fresh-eyes review, or context the session can’t hold, and a skill (the how) or a tool (the doing) comes before a new agent (Router ISA F12, 2026-10-24).

Reference: agent routing (LIFEOS/DOCUMENTATION/Agents/AgentSystem.md) | Managed Agents: https://www.anthropic.com/engineering/managed-agents

Full Context Requirements: When delegating, ALWAYS include:

WHY this task matters (business context)
WHAT the current state is (existing implementation)
EXACTLY what to do (precise actions, file paths, patterns)
SUCCESS CRITERIA (what output should look like)
TIMING SCOPE (fast|standard|deep) — controls agent output verbosity

Timing Scope in Agent Prompts

Every agent prompt MUST include a ## Scope section that matches the validated timing tier from the Algorithm’s THINK phase. This prevents agents from over-producing on simple tasks or under-delivering on complex ones.

Timing + Model Selection:

Timing	Model	Agent Output	Example
fast	`sonnet`	<500 words, direct answer	”Check if server is running”
standard	`sonnet`	<1500 words, focused work	”Implement login validation”
deep	`opus`	No limit, thorough analysis	”Comprehensive security audit”

Examples:

// FAST — simple check, sonnet model, minimal output
Agent({
  prompt: `Check if the auth middleware exports are correct.
## Scope
Timing: FAST — direct answer only.
- Under 500 words
- Answer the question, report the result, done`,
  subagent_type: "Explore",
})

// STANDARD — typical implementation work
Agent({
  prompt: `Senior engineer, TDD. Implement input validation for the login form.
## Scope
Timing: STANDARD — focused implementation.
- Under 1500 words
- Stay on task, deliver the work, verify it works`,
  subagent_type: "general-purpose",
})

// DEEP — comprehensive analysis
Agent({
  prompt: `Offensive-security operator mindset: map the attack surface, find the seam, prove it, document it. Authorized testing only.
Perform a thorough security review of all auth flows.
## Scope
Timing: DEEP — comprehensive analysis.
- No word limit
- Explore alternatives, consider edge cases
- Thorough verification and documentation`,
  subagent_type: "general-purpose",
  model: "opus"
})

Dispatch practice

Which lane a leg gets is Algorithm § Routing. These say how the leg is sent; they moved here from the routing rules on 2026-09-24.

A leg goes down in one call: bun ~/.claude/LIFEOS/TOOLS/Worker.ts <sol|astra> --slug <slug> --cwd <absolute task dir>, in the background. Without --cwd the codex child runs in the caller’s directory, and the helper refuses that when it is the LifeOS install. A Workflow agent waits on the run with Worker.ts wait <sol|astra> --slug <slug>.
The Haiku agent (at its routed effort, passed as the Agent tool’s effort parameter) runs in session; the Sol wrapper only when the leg needs a Claude-side tool.
A worker facing an undecided choice returns needs-judgment instead of guessing.
Fully specified work gets a script, not a model.
Two stalls on one problem: re-dispatch one rung up. A stall at the top goes to the principal.

Async Primitives — When to Use What

Three primitives for non-blocking work. Pick the right one:

Primitive	Tool	Token Cost	Notification	Use When
One-shot wait	`Bash(run_in_background)`	Zero until done	On exit (success/fail)	Build, deploy, test suite, any command you just need to finish
Event stream	`Monitor`	Zero between events	Per stdout line	Log tailing, CI status polling, file watching, deploy streaming
AI work	`Agent(run_in_background)`	Full agent cost	On completion	Research, implementation, analysis — work requiring reasoning

Decision flow:

Does it need AI reasoning? → Agent(run_in_background)
Do you need events as they happen? → Monitor
Just need to know when it’s done? → Bash(run_in_background)

Monitor vs Pulse: Monitor is an in-session watcher — lives and dies with the conversation. Pulse is the out-of-process daemon that runs 24/7. Use Monitor for session-scoped watching (deploy logs, CI). Use Pulse for persistent monitoring (iMessage, Siri, cron checks).

Monitor guidelines:

Always use grep --line-buffered in pipes — without it, pipe buffering delays events by minutes
Poll intervals: 30s+ for remote APIs (rate limits), 0.5-1s for local checks
Handle transient failures in poll loops (curl ... || true)
Only stdout triggers notifications — stderr goes to output file (readable via Read)
Watches end at 30 min (10 in -p); re-arm on the deadline notice
Use TaskStop to cancel a monitor early
Selective filters only — never pipe raw logs. Monitors producing too many events get auto-stopped.

Knowledge Archive Access

Delegated agents can query the Knowledge Archive (~/.claude/LIFEOS/MEMORY/KNOWLEDGE/) for accumulated knowledge organized by 6 entity types: People, Companies, Ideas, Blogs, Research and Books (KNOWLEDGE/_schema.md). Topic is a tag, not a domain. Managed by Algorithm LEARN phase (direct writes), LIFEOS/TOOLS/KnowledgeHarvester.ts (validation/maintenance), and the Cortex skill. Include archive query instructions in agent prompts when the task benefits from prior research or domain context.

Examples

One task, four workers, one message

Delegation at its smallest: a task that splits cleanly into independent parts, run all at once instead of one after another.

Say a small site has four sections and you need to know which ones have a broken link. The parts don’t depend on each other — checking section two tells you nothing about section three. So you fan out: four agents in a single message, each handed one section, each on haiku because the work is mechanical lookup, not reasoning. They run at the same time and report back. Then one spotcheck agent confirms the four results line up.

Four light agents finishing together is faster and cheaper than one opus agent walking the sections in sequence. The model is matched to the work (grunt work → the light lane), and the parallelism is matched to the structure (independent parts → fan out).

When not to fan out

The reinforcing case is knowing when parallel is the wrong move — because forcing it either breaks the work or wastes agents:

Serial dependency — “write the migration, then test it against the result.” The test needs the migration’s output. Parallelizing would have the tester grading a thing that doesn’t exist yet. Run it in sequence.
A single trivial lookup — “is the dev server up?” One Bash check answers it. Spinning up an agent, let alone several, is pure overhead.
Shared, evolving state — when workers must see each other’s progress mid-flight, that’s an Agent Team (shared task list, messaging), not a set of one-shot fan-out agents.

The test: are the parts truly independent? Independent → fan out. Dependent → sequence, or a team that can coordinate.

Fan-out, then gather

flowchart TD
    A[Task with independent parts] --> B{Parallelizable?}
    B -->|no, serial dependency| C[Run in sequence]
    B -->|yes| D[One message, many Agent calls]
    D --> E1[light: part 1]
    D --> E2[light: part 2]
    D --> E3[light: part 3]
    E1 --> F[Spotcheck agent]
    E2 --> F
    E3 --> F
    F --> G[Merged result]

The diagram is the pattern in one frame: split only what’s genuinely independent, launch the workers together in a single message, match each to the cheapest model that can do it, and always close with a spotcheck before trusting the merge.

See Also:

~/.claude/LIFEOS/DOCUMENTATION/LifeosSystemArchitecture.md — Master architecture reference (system-of-systems)
LIFEOS/DOCUMENTATION/Router/RouterSystem.md - Who runs what, on which model and effort
LIFEOS/DOCUMENTATION/Agents/AgentSystem.md - Agent routing and composition

Delegation & Parallelization Reference

History: Delegation & Parallelization (retired 2026-07-21, not current guidance)

Model Selection for Agents (CRITICAL FOR SPEED)

Agent Types

History: Agent routing (Agent Teams as the default is retired; TeamCreate and team_name no longer exist, and routing is Algorithm § Routing)

Timing Scope in Agent Prompts

Dispatch practice

Async Primitives — When to Use What

Knowledge Archive Access

Examples

One task, four workers, one message

When not to fan out

Fan-out, then gather

History: Agent routing (Agent Teams as the default is retired; `TeamCreate` and `team_name` no longer exist, and routing is Algorithm § Routing)