Specialized Subagents

A purpose-built agent with its own workspace, SOUL, model config, and restricted tool access. Dispatched via sessions_spawn({ agentId: "...", task: "..." }) for specific task types.

When to Use

• A recurring task type (coding, design, research) that benefits from focused context and isolation
• Tasks where tool access should be restricted (e.g., a design agent that should only use its CLI, not the browser)
• Work that shouldn't contaminate the main session's context or history

Architecture

Each specialized subagent gets:

• Own workspace directory with tailored AGENTS.md, SOUL.md, TOOLS.md
• Own model config — primary model + fallbacks, independent of main agent
• Tool lockdown at config level — denied tools are invisible to the agent
• Push-based completion — results auto-announced back to the spawning session

Key Design Points

• Tool lockdown must be at config level. Prompt-level instructions ("only use the design CLI") are routinely ignored by models under pressure. Deny tools in the agent config — the model can't use what it can't see.
• Per-agent model fallbacks are independent. A model specified in a cron or spawn must exist in that agent's own model.fallbacks list, not just in agents.defaults. An unregistered model causes a silent hang with no error.
• Workspace files should be minimal. The subagent's AGENTS.md should contain only what it needs for its specific role. Blank template files (empty IDENTITY.md, etc.) waste tokens on every spawn.
• Codex models shouldn't drive tool-use agents. Codex excels at focused code generation from a spec, but hallucinates tool execution — it reports having run commands and produced files that don't exist. Use sonnet or opus for agents that must reliably call tools.

Reference Implementation

See Dedicated Coder Agent for a full example with three-phase workflow, model switching, and skill override patterns.

Failure Modes

• Stale workspace docs — agent's AGENTS.md references tools or patterns that no longer exist, causing confusion
• Tool bypass — model ignores prompt-level tool restrictions and uses familiar tools directly (fix: config-level deny)
• Model hallucination — codex models complete in seconds claiming to have executed tools without actually calling them
• Missing model in fallbacks — cron or spawn specifies a model not in the agent's config, causing silent timeout