AgentTool: When Necessary, It Sends a Clone

Task Type Definitions (Task.ts)

type TaskType =
  | 'local_bash'          // Local terminal command
  | 'local_agent'         // Local sub-agent
  | 'remote_agent'        // Remote agent (cloud execution, internal Ant use only)
  | 'in_process_teammate' // Teammate agent (multi-agent collaboration)
  | 'local_workflow'      // Local workflow
  | 'monitor_mcp'         // MCP monitoring
  | 'dream'               // Undisclosed purpose

type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'killed'

Launch Decision: Who Decides?

Claude decides, by passing different parameters to AgentTool. The code only does routing — it doesn't make active judgments. Anthropic encodes "the wisdom of task scheduling" into the system prompt and teaches it to the model, rather than hard-coding it as rules in the code.

Routing Decision Tree

Call AgentTool
  │
  ├── Both team_name + name present?
  │     └── → Multi-agent team (Teammate): tmux independent process, color-coded
  │
  ├── isolation = 'remote' (internal Ant only)
  │     └── → Remote CCR cloud execution, generates sessionUrl, runs in background
  │
  ├── isolation = 'worktree'
  │     └── → Creates independent git worktree; agent works in isolated copy
  │
  ├── run_in_background = true (or agent definition has background: true)
  │     └── → local_agent async background execution
  │           Shows Background Hint after 2 seconds
  │           Auto-promotes to background after 120 seconds (experimental)
  │
  └── Default
        └── → local_agent synchronous execution (blocking, waits for result)

subagent_type Routing

• User explicitly specifies → used directly
• Not specified + Fork experiment enabled (FORK_SUBAGENT feature gate) → sub-agent inherits parent's system prompt (saves tokens)
• Not specified + normal mode → defaults to general-purpose

Safety Guards

• An in-process teammate cannot spawn background agents (lifecycle is bound to the parent process)
• An in-process teammate cannot generate new teammates (team roster is flat)
• A forked sub-agent cannot fork again (recursive protection)

Full Example

Scenario: user says "refactor the code and write tests at the same time"

Step 1: Claude splits the task itself

Claude determines these are two independent things that can run in parallel. It decides to call AgentTool twice, creating two sub-agents.

Step 2: For each AgentTool call, the code routes

Agent A (refactor) — parameters Claude passes:

{
  description: "refactor codebase",
  prompt: "Refactor code in the src/utils directory",
  isolation: "worktree",         ← High-risk operation, needs isolation
  run_in_background: true        ← Background execution, non-blocking
}

Routing result: Creates an independent git branch copy; Agent A modifies code inside the copy — even if it breaks, it won't affect the main branch.

Agent B (write tests) — parameters Claude passes:

{
  description: "write tests",
  prompt: "Write unit tests for src/utils",
  run_in_background: true        ← Background execution, no isolation
}

Routing result: local_agent async background execution — adds test files directly to the current directory (only adds, no destructive risk, no worktree needed).

Why does Agent A need worktree but Agent B doesn't?

Step 3: Runtime user experience

You: Refactor the code and write tests at the same time

Claude: Sure, I've started two background tasks:
  [Agent A - Refactor] Running... (worktree isolation)
  [Agent B - Write Tests] Running...

(After 2 seconds, a Background Hint banner appears)

You can keep asking me questions.

(A few minutes later)
  ✓ [Agent B - Write Tests] Complete
  ✓ [Agent A - Refactor] Complete, in isolated branch — please confirm whether to merge