context-course/pr_7/en/unit4/using-subagents.md

Using Subagents

The approach differs between Claude Code, Codex, and Pi, but the core idea is the same: a parent agent delegates a scoped task to a child, often in parallel.

Invoking Subagents

Conversational Invocation

The simplest way to use subagents in Claude Code is conversational:

I need to compare 5 ML frameworks. Use subagents to research each one in parallel.
For each framework, find:
  - GitHub metrics (stars, contributors)
  - Download popularity (PyPI, npm)
  - Community sentiment (GitHub discussions)

Claude Code automatically recognizes this as work suitable for subagents and:

1. Spawns 5 parallel subagents
2. Each researches one framework
3. Aggregates results into comparison report

Claude handles the subagent logic behind the scenes.

Custom Agents

For more control, define custom agents in .claude/agents/*.md with YAML frontmatter:

---
name: researcher
description: Research-focused agent for deep file exploration
tools: Read, Grep, Glob, WebFetch
model: sonnet
---
You are an expert researcher. Your job is to thoroughly explore files,
extract key information, and provide well-sourced insights.

Invoke it explicitly:

Use the researcher subagent to explore our auth system and report on security practices.

Claude Code launches the researcher subagent with the specified tools and system prompt.

Multiple custom agents:

<!-- architect.md -->
---
name: architect
description: System design specialist
tools: Read, Glob
model: sonnet
---
You design systems. You think about scalability, reliability, and maintainability.

<!-- security-reviewer.md -->
---
name: security-reviewer
description: Security-focused code reviewer
tools: Read, Grep
model: sonnet
---
You are a security expert. Review code for vulnerabilities.

Use them:

Have the architect review our system and the security-reviewer check for vulnerabilities.

CLAUDE.md Policies

Define reusable policies in .claude/CLAUDE.md for when subagents should be used:

# Project Guidelines

## Code Review Policy

All code reviews use a read-only security-reviewer subagent:

When a user proposes a change to core auth/ or security/ code, automatically:
1. Spawn a read-only security-reviewer subagent
2. Give it Read and Grep access (no Write)
3. Have it review for vulnerabilities
4. Report findings to user before commit

## Research Policy

Research tasks (10+ files) always use subagents to explore independently.
Each subagent focuses on one subsystem to avoid context overflow.

Claude Code can use these policies as guidance. They make delegation more consistent, but explicit requests are still the strongest signal when you need a specific subagent to run.

Skills in Subagents

You can invoke skills directly in subagent tasks:

Use a subagent to run the "hf-api-search" skill to find all BERT models

Or define which subagent should run which skill:

---
name: hf-researcher
description: Hugging Face specialist
skills: 
    - hf-api-search 
    - hf-dataset-fetch
model: sonnet
---
You are an expert at finding and evaluating models on Hugging Face.

Hooks and Lifecycle Events

Claude Code supports hooks via hooks.json format (see code.claude.com/docs/en/hooks). Hooks can trigger commands on events like PostToolUse, but automatic subagent spawning from hooks is not a built-in feature.

Instead, define CLAUDE.md policies to guide when Claude should use subagents:

.claude/CLAUDE.md:

# Project Guidelines

## Code Review Policy

When proposing changes to core auth/ or security/ code:
- Use a read-only security-reviewer subagent
- Have it check for SQL injection, token leakage, privilege escalation
- Report findings before committing

## Testing Policy

Large test suites (10+ files):
- Use a worker subagent to run tests in parallel
- Report coverage and failures
- Recommend fixes before commit

Claude Code reads these policies as guidance and can use subagents when appropriate. This is more flexible than rigid hooks, but it is still guidance rather than a guaranteed trigger. When you need a specific subagent, ask for it explicitly.

Background Execution (Ctrl+B)

When a subagent task is running, press Ctrl+B to send it to the background:

Researching 10 files...  [Press Ctrl+B]
✓ Sent to background. You can continue working.

Check running tasks:

/tasks

The /tasks view lists active background tasks and lets you bring a selected task back to the foreground.

Subagent Results

Subagents report back with:

• Structured findings
• Source files and line numbers
• Confidence levels
• Recommendations for parent agent

Parent agent uses these results to:

• Combine findings
• Make decisions
• Generate final output
• Handle conflicts or contradictions

Example: Research + Review Pipeline

Main task: "Design a new authentication system for our app"

Claude Code automatically:
1. [Spawns researcher subagent]
   Task: "Explore our current auth system in 15+ files"
   Tools: Read, Grep, Glob
   Result: Current architecture, pain points
   
2. [Spawns architect subagent]
   Task: "Design new auth using research from step 1"
   Tools: Read (no Write)
   Result: Proposed design
   
3. [Spawns security-reviewer subagent]
   Task: "Review proposed design for security issues"
   Tools: Read (read-only)
   Result: Vulnerability report, recommendations
   
4. [Parent combines]
   Input: Research, design, security review
   Output: Final design proposal with risks noted

Best Practices in Claude Code

Start with conversational invocation — let Claude decide when subagents help. Define custom agents for specialist roles like security-reviewer or performance-tester. Use read-only tools for review agents to prevent accidental writes. Leverage CLAUDE.md policies for consistent rules across your team, monitor background tasks with /tasks, and let the parent agent resolve conflicts when subagents disagree.

Spawning Subagents in Codex

Codex creates subagents only when explicitly requested via natural language. There is no separate codex-agent binary or CLI commands.

Request subagent spawning naturally:

Spawn one agent per point in this list.
Have pr_explorer map the affected code paths.
Use the default agent to research the API.

Codex recognizes the request and spawns appropriate agents automatically.

Built-in Agent Types

Codex provides 3 default agent types:

1. default — General-purpose fallback agent
2. worker — Execution-focused, optimized for implementation and fixes
3. explorer — Read-heavy, optimized for codebase exploration

Global Configuration

Configure subagent behavior in your Codex config under [agents]:

Setting	Default	Purpose
max_threads	6	Maximum concurrent open agent threads
max_depth	1	Maximum nesting depth for spawned agents
job_max_runtime_seconds	1800	Timeout per worker for batch jobs

Example codex.toml:

[agents]
max_threads = 8
max_depth = 1
job_max_runtime_seconds = 3600

Managing Subagents

Use the /agent command to list active subagent threads and switch between them. Once attached to a thread, steer it in natural language:

/agent

Tell this agent to also check security.
Stop the current agent.
Close this agent and report findings.

Custom Agent Types

Define custom agents in ~/.codex/agents/ (user) or .codex/agents/ (project) as TOML files:

.codex/agents/pr_explorer.toml:

name = "pr_explorer"
description = "Maps codebase and gathers evidence for PR reviews"
developer_instructions = """
You are a read-only codebase explorer. Map code paths affected by a PR,
identify dependencies, and gather evidence about what changed and why.
"""

nickname_candidates = ["Atlas", "Delta", "Echo"]
sandbox_mode = "read-only"

.codex/agents/docs_researcher.toml:

name = "docs_researcher"
description = "Verifies APIs and framework behavior via MCP docs server"
developer_instructions = """
You verify that code uses APIs correctly. Check documentation,
look for deprecations, and verify the framework behavior described in code.
"""

sandbox_mode = "read-only"
mcp_servers = ["mcp://docs.framework.org"]

Required fields:

• name — Agent identifier
• description — What the agent does
• developer_instructions — System prompt

Optional fields:

• nickname_candidates — Suggested friendly names
• model — Override model selection
• sandbox_mode — read-only for safe review agents
• mcp_servers — Specialized tools and APIs
• skills.config — Custom skill configurations

Sandbox and Approval Inheritance

Subagents inherit the parent session's sandbox configuration:

Parent: "Review this code for security. Spawn a security-reviewer."
→ security-reviewer automatically inherits parent's read-only mode

Parent: "Find and fix all bugs." (with --yolo flag)
→ Worker agents inherit full permissions

Approval requests from inactive threads surface to the parent. Parent session overrides (sandbox mode, --yolo) reapply to children.

CSV Batch Processing

Process CSV files with parallel worker agents:

Process this CSV with one agent per row. 
Column "model_name" should be evaluated on "benchmark".
Save results to output.csv.

Codex uses the spawn_agents_on_csv tool with:

• csv_path — Input CSV file
• instruction — Task template (use {column} placeholders)
• id_column — Unique row identifier
• output_schema — Expected result structure
• output_csv_path — Where to save combined results
• max_concurrency — How many agents run in parallel
• max_runtime_seconds — Timeout per worker

Each worker must call report_agent_job_result exactly once with structured output.

Example: PR Review with Specialized Agents

Define three custom agents:

1. pr_explorer (read-only) — Maps codebase, gathers evidence
2. reviewer (read-only) — Checks correctness, security, test coverage
3. docs_researcher (read-only) — Verifies APIs via MCP docs server

Invoke them naturally:

Have pr_explorer map the affected code paths,
reviewer find real risks and verify tests are comprehensive,
and docs_researcher verify the framework APIs are used correctly.

Codex spawns all three, they work in parallel, and report findings back to the parent.

Results include:

• Affected files and line numbers
• Security and correctness issues
• Test coverage gaps
• API usage verification
• Recommendations

Practical Example: Batch Model Evaluation

I need to evaluate 5 models on 3 benchmarks (15 tasks total).
Process this CSV with one worker per row.
Column "model" = model name, Column "benchmark" = benchmark name.
Task: "Load model {model}, run on {benchmark}, report F1 and latency."
Output to results.csv.
Max 5 workers in parallel, 30 minute timeout per task.

Codex:

1. Reads CSV with 15 rows
2. Spawns up to 5 worker agents
3. Each worker evaluates one model-benchmark pair
4. Workers report results to results.csv
5. Parent aggregates and analyzes

Best Practices in Codex

1. Request subagents conversationally — "Spawn agents to..." or "Have agent X research..."
2. Use read-only sandbox for reviewers — Prevents accidental modifications
3. Leverage custom agents for specialists — pr_explorer, security-reviewer, docs_researcher
4. Use /agent command to monitor — Switch threads, check progress, steer agents
5. Define CSV batch jobs for parallel work — Ideal for evaluation, testing, research
6. Let subagents inherit parent sandbox — No need to repeat sandbox settings

Install a Subagent Extension

Pi does not ship with built-in subagents, but the official repo includes a subagent example extension that spawns isolated pi subprocesses.

Project-local setup:

mkdir -p .pi/extensions/subagent .pi/agents .pi/prompts

Custom Agents

Define agents in .pi/agents/*.md with YAML frontmatter:

---
name: researcher
description: Research-focused agent for deep file exploration
tools: read, grep, find, ls
---
You are an expert researcher. Explore files broadly, compress findings,
and return only the context another agent will need.

Workflow Prompts

The example extension also supports reusable prompt templates in .pi/prompts/. For example:

/implement add OAuth2 authentication
/scout-and-plan refactor auth to support OAuth

Conversational Invocation

Once the extension is loaded, you can still ask naturally:

Use scout to map the auth system, then have planner produce an implementation plan.
Run two reviewers in parallel after the code change.

The extension delegates each subtask to a separate pi process with its own context window.

Best Practices in Pi

Keep agents in .pi/agents/, use read-only tool lists for reviewer agents, and rely on prompt templates or explicit requests for orchestration. Because this is extension-driven rather than built in, the exact workflow is yours to tune.

Worktree Isolation (Claude Code)

When using subagents for parallel edits, use git worktrees to prevent conflicts:

# Main workspace
git worktree add ../feature-a
git worktree add ../feature-b

# Subagent A works in feature-a/
# Subagent B works in feature-b/
# No conflicts—separate directories

Tell subagents where to work:

Subagent A: Create feature A in ../feature-a/ directory
Subagent B: Create feature B in ../feature-b/ directory
Then parent merges both features

Real-World Example: Code Review Pipeline

Task: "Review a proposed payment system for security issues and performance problems"

Main Agent:
  Task: Review payment system proposal
  
  1. Spawn security-reviewer subagent (read-only)
     Tools: Read, Grep
     Task: Find vulnerabilities
  
  2. Spawn performance-reviewer subagent (read-only)
     Tools: Read, Grep
     Task: Identify bottlenecks
  
  3. [Both run in parallel]
  
  4. Main agent combines findings
     Output: Final review with risks

Conversationally:

Use subagents to do a security and performance review of the payment system.
Have security-reviewer look for SQL injection, token leakage, etc.
Have performance-reviewer look for database queries, caching opportunities.
Run both in parallel.

Spawn two subagents to review the payment system:

Agent 1 (security-reviewer):
  Task: Find vulnerabilities (SQL injection, token leakage, privilege escalation)
  
Agent 2 (performance-reviewer):
  Task: Find bottlenecks (slow queries, N+1 problems, caching opportunities)

Run both in parallel.
Combine findings and report risks and recommendations.

Codex:

1. Spawns security-reviewer and performance-reviewer agents
2. Both explore the payment_system/ codebase in parallel
3. Security agent checks for vulnerabilities
4. Performance agent identifies bottlenecks
5. Parent agent combines findings into a final review report

Use /agent to monitor progress or steer either agent during execution.

Use the subagent extension to review the payment system in parallel:

Task 1 (security reviewer):
  Find SQL injection, token leakage, privilege escalation, and unsafe secrets handling.

Task 2 (performance reviewer):
  Find slow queries, N+1 patterns, unnecessary work inside request paths, and missing caches.

Run both in parallel, then summarize the risks and concrete fixes.

With the official example extension, this is usually modeled as parallel tasks that each target a named agent from .pi/agents/.

Key Takeaways

In Claude Code, use conversational invocation, custom agents in .claude/agents/, CLAUDE.md policies, and background execution with Ctrl+B. In Codex, request subagents in natural language with three built-in types (default, worker, explorer), define custom TOML agents, monitor with /agent, and use CSV batch jobs for parallel work. In Pi, install a subagent extension, define agents in .pi/agents/, and drive orchestration through prompt templates or explicit requests. All three approaches help when you have many files, several independent tasks, or need a fresh perspective. For parallel file edits, isolate work with git worktrees.

Next, a hands-on multi-agent workflow.