Agent Creator

---
name: agent-name              # REQ: lowercase-hyphens; no leading `-`, no `:` (reserved for plugin namespacing)
description: "..."            # REQ: action verb + Triggers: keyword list
model: sonnet                 # OPT: fable|opus|sonnet|haiku|inherit  (fable=claude-fable-5, Mythos-class, CC 2.1.170+)
effort: high                  # OPT: low|medium|high|xhigh|max (no auto, no bare integer)
maxTurns: 20                  # OPT: integer, max turns before abort
tools: Read, Glob, Grep       # OPT: omit = inherit all
disallowedTools: Write, Edit  # OPT: explicit deny list
skills: skill1, skill2        # OPT: full content injected into context at startup
color: cyan                   # OPT: 8 valid values -- magenta is NOT one
memory: project               # OPT: user|project|local -- auto-adds Read/Write/Edit
background: true              # OPT: true keeps it backgrounded even when Claude wants the result (DEF unset, no `false` switch)
isolation: worktree           # OPT: FM accepts `worktree` only -- LOW PRIORITY, see below (`remote` is invocation-level, never FM)
permissionMode: default       # OPT: LOCAL-ONLY -- ignored + warn in plugin agents
mcpServers: [server1]         # OPT: LOCAL-ONLY -- ignored + warn in plugin agents
initialPrompt: "..."          # OPT: LOCAL-ONLY -- first prompt sent on start
observer: "reviewer"          # OPT: LOCAL-ONLY -- observing agent
observerMessage: "watch for X"  # OPT: LOCAL-ONLY -- brief for observer
observeSubagents: false       # OPT: LOCAL-ONLY -- `false` disables observation
---

Scope — verified against CC 2.1.233 (two separate parsers: local .claude/agents/ and plugin <plugin>/agents/**.md):

initialPrompt auto-submits as the first user turn only when this exact definition runs as the MAIN session (--agent <name> or the agent setting) — irrelevant on an ordinary subagent spawn, but honored for plugin agents too since origin isn’t the boundary, execution context is. Need permissionMode/hooks/mcpServers? Move the agent to .claude/agents/ — plugin agents ignore these three no matter how the frontmatter is written. isolation: remote is never a valid FM value anywhere — it is invocation-level only, reachable from an Agent(...) tool call.

Description patterns by ambiguity level:

Subagent spawn note: CC allows nested subagent spawning, but prefer spawning from the main conversation so the orchestrator can integrate each agent’s result directly. Brewcode agents are stateless and resolve plugin paths via ${CLAUDE_PLUGIN_ROOT}.

Known active bugs: #29423 (subagents skip CLAUDE.md), #27736 (skills: in plugin agents), #31392 (global agents not discovered in v2.1.70+).

A turn = one model inference plus its tool calls; tool results return, then the next turn begins. Parallel tool calls in one assistant message count as ONE turn, so turns are usually fewer than tool calls. Observed in real transcripts from this repo: 12 turns / 19 tool calls, 21 / 33, 40 / 53, 51 / 55.

maxTurns sized by role — every generated agent gets an explicit value:

Calibrated against real subagent transcripts (.claude/projects/*/subagents/agent-*.jsonl), not invented. At roughly 10-20 seconds per turn, 120 turns is a 20-30 minute ceiling. Rule of thumb: maxTurns ≈ 2-3x the role’s typical run.

maxTurns is an emergency anti-loop stop, not a budget. On exhaustion the binary emits Reached max turns limit (N) and the agent aborts — written files persist, but the final report is lost. That is why agent-creator also writes a checkpointing instruction into every generated agent body: record incremental progress to a report file after each milestone, and on resume read that file first and continue from the last checkpoint.

Relevant environment variables (set under env in settings.json):

Time-based control is only reachable through PreToolUse, which fires inside the subagent loop and carries agent_id and agent_type: warn at 80% of the budget, deny non-Write tools at 100%. SubagentStart and SubagentStop fire in the MAIN session, not inside the agent. No timer hook exists.

Recovering a partial result: