Subagent

subagent — one-shot / batch / background provider subagent

Wrong lane? A long-lived collaborator you message back and forth → /cc-fleet:team; a multi-phase pipeline with dependencies or resume → /cc-fleet:workflow; arbitration in cc-fleet-shared/routing.md.

When this skill cites cc-fleet-shared/<file>.md, OPEN it with the Read tool at ../cc-fleet-shared/<file>.md relative to this SKILL.md — the cited content is load-bearing, not optional background.

> Execution environment — check before running anything. Confirm your shell tool executes on the host where cc-fleet is installed. In sandboxed or remote agent sessions, a tool named Bash may run on an isolated machine with a different filesystem, PATH, processes, and tmux server — command not found, a healthy-looking doctor whose leaves can't reach your files, or a wrong working directory should prompt you to verify whether you are in a sandbox shell, not conclude that cc-fleet is broken. If so, route commands through a host-executing bridge tool (for example, desktop-commander) and pass host paths for any files you reference; do not retry the same Bash call expecting different results. If no host-executing tool is available, stop and explain that cc-fleet must run on its installation host.

cc-fleet subagent runs a provider model headless and returns the result directly on Bash stdout — no tmux pane, no TeamCreate/SendMessage/TeamDelete. The analog of the native Agent/Task tool, but the model can be a provider id. It reuses the same provider selection and the same fingerprint self-heal flow as spawn (cc-fleet-shared/troubleshooting.md). It's the lightweight synchronous branch.

When to use it

• One-shot research / analysis / judgement — you want an answer, not a long-lived colleague.
• Batch fan-out — N independent tasks in parallel. subagent is lock-free, so N calls don't serialize behind a server lock the way N spawns do — true parallelism.
• Cost-bounded probes — --timeout caps wall-clock; the return value carries usage / total_cost_usd; it stops when done (nothing to forget to tear down).

The provider ask ladder (ask at most once per task)

• The user named a provider or model → use it.
• Else run cc-fleet default --json: if it returns a provider (source "configured" or "auto"), use it and STATE it in your kickoff line (e.g. "using glm (default)").
• Else (several providers, none default) ask the user ONCE which to use — list the enabled providers from cc-fleet list --json (name + default_model + the one-line note in cc-fleet-shared/providers.md). After they pick, run cc-fleet default <chosen> so you never ask again. (cc-fleet default <p> is user-layer; only run it to FILL a blank default, never with --force.)
• A mid-task provider failure (insufficient balance / rate limit / auth) → STOP, tell the user what happened, propose the next provider, and WAIT for their confirmation. Never switch providers silently.

Model tier within a provider: fan-out / leaf work → omit --model (or --model fast); judge / synthesis / sustained work → --model strong. The provider's roster decides the actual model — see cc-fleet-shared/providers.md.

The reserved native leaf — claude. cc-fleet subagent claude … runs the official claude CLI on the user's OWN Claude Code login (their subscription OAuth or whatever they're logged in as) — no providers.toml row, no profile, no key material. A NAMED deliberate choice, never the auto-default (cc-fleet default claude errors; it never auto-resolves). --model takes a literal id (opus / sonnet / a full id) — the slot keywords default/strong/fast are rejected (no roster); omitted = claude's login default, which is typically the most expensive tier, so naming a model is usually wise. Profiles apply unchanged. The leaf spends the lead session's own subscription window — use it for one or two synthesis / judgement nodes, never a wide fan-out.

cc-fleet subagent claude --model opus --prompt "<synthesis over the gathered notes>" --json

Calling it (run via Bash, always with --json)

cc-fleet subagent --prompt "<task>" --json                 # no provider arg → default provider
cc-fleet subagent deepseek --model strong \
  --prompt "Analyze the worst-case complexity of quicksort in src/sort.go; give a triggering input" --json

The provider arg is optional — with no provider, cc-fleet uses the default. NO_DEFAULT_PROVIDER / DEFAULT_PROVIDER_DISABLED / DEFAULT_PROVIDER_UNKNOWN in the failure envelope mean there is no usable default — apply the provider ask ladder above.

Session grouping — no flag needed by default. cc-fleet subagent auto-detects the parent Claude session (fail-closed: an unvalidatable registry shows (no session), never a guess). The one exception: inside a known team, pass --lead-session-id (the team's leadSessionId from ~/.claude/teams/<team>/config.json) to force the job under that team's session — an explicit flag always wins.

# Optional explicit override, with a known team:
lead_session_id=$(jq -r '.leadSessionId // empty' "$HOME/.claude/teams/<team>/config.json")
cc-fleet subagent --prompt "..." --lead-session-id "$lead_session_id" --json

Useful flags (full list in cc-fleet-shared/cli-reference.md):

• Name it → --label "<short-alias>" (e.g. --label sort-complexity). The Agents Board shows the label instead of the opaque job id — pass one on every launch, like a teammate name. Display-only metadata; capped at 256 bytes.
• Large / sensitive prompt → --prompt-file <path> (read from file, piped via stdin, kept out of argv / ps). Use it once a single prompt approaches ~128 KiB (MAX_ARG_STRLEN, the per-argument cap — not the ~2 MB total ARG_MAX). --prompt-file - reads stdin.
• Long task → --timeout 600s (default 300s). For tasks that may exceed the timeout, run the sync call in a backgrounded Bash, or use --background (both below). Note: a provider that's down on auth (401) or quota (429) makes claude retry ~180s before surfacing KEY_INVALID / INSUFFICIENT_BALANCE, so keep --timeout ≥ ~200s (the 300s default is fine) — a shorter timeout reports those as SUBAGENT_TIMEOUT instead. --probe does not catch a bad key (the models endpoint may not 401 it).
• Cost / runaway gates → --max-budget-usd 0.5 (cap spend) and --max-turns 8 (cap the agentic tool loop). On fan-out, strongly consider passing these on every call.
• Prompt profile — slim is the DEFAULT; read-only research → --profile slim-ro; --profile full ONLY to compare against a full session or diagnose a suspected slim regression. --tools REPLACES the whole tool set, never appends. Write prescriptive prompts ("Run cmd", "Use the Read tool on X"), not "look at" / "check" — weak provider models skip tools on weak imperatives under any profile. Tool whitelists / --skills / --mcp defaults / downgrade behavior: cc-fleet-shared/providers.md.
• Probe is off by default (--probe to opt in): the inner claude -p call is itself the authoritative reachability + auth test. On a big fan-out, run one shared cc-fleet doctor / probe up front rather than paying 3s × N.
• --prompt and --prompt-file are mutually exclusive — pass exactly one (else error_code=SUBAGENT_BAD_ARGS, no claude launched).

Success envelope

{"ok":true,"result":"<answer text>","provider":"deepseek","model":"deepseek-reasoner",
 "duration_ms":12044,"usage":{"input_tokens":812,"output_tokens":1530},
 "total_cost_usd":0.0031,"session_id":"…"}

→ Take .result as this subagent's output and hand it back / continue orchestrating. model is the model the provider actually billed (routing evidence). Keep .session_id if you intend a multi-turn follow-up (below).

Failure envelope — dispatch on error_code (do not parse prose)

error_msg is a canonical string only; never matched on. Dispatch on error_code:

| error_code | Meaning | What you do |

|---|---|---|

| SUBAGENT_BAD_ARGS | Missing/both --prompt & --prompt-file. | Fix the call (exactly one). |

| NO_DEFAULT_PROVIDER | No provider arg and no default configured. | Apply the provider ask ladder. |

| DEFAULT_PROVIDER_DISABLED | The default provider is disabled. | Apply the provider ask ladder; or the user re-enables via cc-fleet edit <provider> --enable. |

| DEFAULT_PROVIDER_UNKNOWN | The default names a provider that no longer exists. | Apply the provider ask ladder; the user re-pins with cc-fleet default <p>. |

| DEFAULT_PROVIDER_RESERVED | default_provider is hand-set to the reserved claude (explicit-only). | The user runs cc-fleet default --unset or re-pins a real provider; don't retry. |

| CONFIG_LOAD_FAILED | providers.toml failed to load/validate. | cc-fleet doctor; surface to the user — don't retry. |

| UNKNOWN_PROVIDER / PROVIDER_DISABLED | Provider not configured / disabled. | Tell the user to cc-fleet add / cc-fleet edit <provider> --enable. |

| PROVIDER_RESERVED | A providers.toml row is named claude (reserved for the native leaf). | Tell the user to rename or cc-fleet remove claude; spawn still uses the row meanwhile. |

| FINGERPRINT_MISSING | An existing fingerprint.json is corrupt (a fresh install uses the bundled recipe, so this is rare). | Run the self-heal flow in cc-fleet-shared/troubleshooting.md, then retry. |

| FINGERPRINT_STALE | No claude binary found anywhere (not a missing recipe). | Tell the user to install/fix Claude Code or PATH; the self-heal flow can't help. cc-fleet doctor confirms. |

| KEY_INVALID | Provider 401/403. | Have the user rotate the key; do not retry blindly. |

| INSUFFICIENT_BALANCE | Out of balance / quota (429/402 + balance signature). | Retry can't help — propose the next provider (provider ask ladder, step 4) or fall back to native Agent; tell the user they're out of credit. |

| RATE_LIMITED | Provider 429. | Wait briefly, retry once, or propose a switch (provider ask ladder, step 4). |

| MODEL_NOT_FOUND | Model name rejected (400). | cc-fleet refresh <provider> then retry, or drop --model to use the default. |

| PROVIDER_UNREACHABLE | Transport failure (only with --probe). | cc-fleet doctor; if urgent, fall back to native Agent. |

| SUBAGENT_TIMEOUT | Exceeded --timeout. | Real long task → raise --timeout (or use --background) and retry; suspected hang → switch provider / fall back (with user confirmation). |

| PROVIDER_API_ERROR | Other provider failure (5xx / overloaded). | Retry once or propose a switch. |

| CODEX_PROXY_UNAVAILABLE | The codex conversion daemon could not start (no login, or the loopback port is held). | Tell the user: cc-fleet codex login, or free / change the port (cc-fleet codex add --port <n>). |

| CODEX_CLOUDFLARE_BLOCKED | The ChatGPT backend's edge blocked this IP/client — not a key problem. | Switch network/IP or retry later; don't rotate credentials. |

| SUBAGENT_MAX_TURNS | claude hit the --max-turns cap without finishing (the spent cost is surfaced — not silently $0). | Raise --max-turns (or omit it) and retry — a read-heavy / multi-file task needs ~1 turn per file read or command; a genuinely long task can use --background. |

| SUBAGENT_FAILED | claude exited with no parseable result (or budget exhaustion). For a claude native leaf on a logged-out machine, this is the login failure — the error preview names it (no dedicated code). | Inspect; retry or switch provider. A logged-out native leaf → tell the user to log in to Claude Code interactively. |

| SUBAGENT_OUTPUT_TOO_LARGE | The child's stdout/stderr exceeded the byte cap; the run was killed. | Have it write its output to a file and return a short answer (or narrow the ask) — a blind retry overflows again. |

| SUBAGENT_STOPPED | An operator stopped the job (workflow stop / a leaf stop) — terminal, NOT a failure. | Never auto-retry; surface it. |

Batch fan-out (parallel, each returns synchronously)

# These Bash calls are independent and can fire in parallel; subagent is
# lock-free, so they don't queue behind each other.
cc-fleet subagent glm      --prompt "Summarize docs/a.md" --json
cc-fleet subagent glm      --prompt "Summarize docs/b.md" --json
cc-fleet subagent deepseek --prompt "Summarize docs/c.md" --json
# Each returns its own {ok, result, total_cost_usd}; aggregate them. No
# TeamCreate / TeamDelete needed.

A flat fan-out only — phases, dependencies, or dynamic orchestration over the results is /cc-fleet:workflow.

Long tasks: a backgrounded Bash is the push notification

A finished subagent CAN wake you: a backgrounded Bash command's exit is delivered to the session as a task notification. Never spawn an agent (or loop yourself) to poll. Two shapes:

• Sync call in a backgrounded Bash (first choice). Run the ordinary cc-fleet subagent … --json with the Bash tool's run_in_background=true, end your turn, and the harness wakes you when it exits — the envelope is the task output. Zero extra mechanism; the process is tied to your session.
• --background + a waited status — when the job must survive your session, or you want it grouped on the Agents Board:

cc-fleet subagent --prompt "<long task>" --background --json
# → {"ok":true,"job_id":"<uuid>","status":"running","output_file":"…","pid":…}
# arm the notifier (backgrounded Bash — its exit wakes you):
cc-fleet subagent-status <job_id> --wait --timeout 5m --json

Wake-up dispatch on the exit code: 0 done (envelope has .result) · 1 failed OR stopped — check .status first: stopped is an operator stop, never auto-retry; failed → dispatch on .error_code · 3 held (a workflow-leaf id an operator parked — surface it, never wait it out) · 124 still pending at --timeout (a heartbeat: re-arm; escalate only if the job is far past its own --timeout) · 130 interrupted. Always pass --timeout, and re-arm any still-pending wait after a session restart.

cc-fleet subagent-gc --json prunes finished job files.

Multi-turn: --resume

Continue a prior subagent session (stateful, but not long-lived between turns — each turn is a fresh claude -p --resume):

cc-fleet subagent --resume <session_id> --prompt "<follow-up>" --json

<session_id> is the .session_id from the previous turn's envelope. A default-profile (slim) resume is silent; an explicitly passed --profile over --resume warns on stderr — it swaps the system prompt mid-session. Keep the profile constant across a session's turns.

Cleanup vs. resume — they're independent

A sync subagent has nothing to tear down; "cleanup" only concerns --background job records on the Agents Board. The rules:

• The one rule that matters: capture .session_id BEFORE pruning if a follow-up is likely. gc deletes cc-fleet's job record (which holds the envelope with the id) but never Claude's transcript — so --resume works after gc *iff* you kept the id, and keeping the record without the id buys you nothing.
• Prune finished, scoped to your session: cc-fleet subagent-gc --session <lead_session_id> --json (immediate, skips pinned) — prefer it over a blanket subagent-gc --older-than 0s so you never wipe another session's records. Default gc only removes finished jobs older than 24h; running jobs are always kept; pinned records are user-owned — never force-remove them.

Anti-patterns

• Using subagent for work that needs multiple turns / collaboration → /cc-fleet:team.
• Chaining subagents into a dependent pipeline by hand → /cc-fleet:workflow.
• TeamCreate / SendMessage / polling cc-fleet ps --check for a subagent → unnecessary; the result is on stdout.
• Stuffing a giant prompt into --prompt (hits MAX_ARG_STRLEN ~128 KiB) → use --prompt-file.
• Running a possibly-stuck provider with no bound → the default --timeout 300s caps it, but tune per task on fan-out, and run genuinely long work via a backgrounded Bash or --background (Long tasks above).
• Polling subagent-status in a loop (or delegating an agent to watch a job) → arm subagent-status --wait in a backgrounded Bash once; its exit is the notification.
• Looping on a failure without dispatching .error_code → every --json failure carries a code; switch on it (table above; spawn-side codes in cc-fleet-shared/troubleshooting.md).
• Switching providers silently after a balance / rate-limit / auth failure → stop, tell the user, wait for their pick (provider ask ladder, step 4).
• Fanning out N claude native leaves → drains your own subscription window; use a metered provider for breadth, claude only for one or two synthesis nodes.