Subagent

subagent — one-shot / batch / background provider subagent

Wrong lane? A multi-phase pipeline with dependencies or resume → /cc-fleet:workflow.

When this skill cites cc-fleet-shared/<file>.md, read ../cc-fleet-shared/<file>.md relative to this SKILL.md (load-bearing, not optional background).

Execution environment — check before running anything. Confirm this shell runs on the machine where cc-fleet is installed. In a remote or split-host agent session the shell can run on a separate machine with its own filesystem and PATH, so cc-fleet: command not found or a wrong working directory can indicate that the shell is running on the wrong machine, not that cc-fleet is broken — route commands through a host-executing bridge and pass host paths for the files you reference, and stop cleanly if no such bridge exists. (Different-machine case only; for the same-machine codex sandbox — a clean doctor but network-blocked leaves — see Approval & sandbox below.)

cc-fleet subagent runs a provider model headless and returns the result directly on your shell's stdout — no tmux pane, no team, no locks. A one-shot provider agent whose model can be a provider id. It reuses the same provider selection and fingerprint gate as the rest of cc-fleet. It's the lightweight synchronous branch.

Preflight (first fan-out per session). Run cc-fleet doctor --json once and read the per-check results. The ONLY hard stops are the claude binary check and the fingerprint check (the worker engine) — if either fails, tell the user to install or fix Claude Code, and stop. Do not stop on the "all configured providers' keys reachable" check: it aggregates every enabled provider, so one unrelated provider — especially a daemon-backed codex / openai-*, whose loopback proxy is only up during a spawn — flips ok:false / exit 1 while your target provider is fine. Provider API keys are configured separately in cc-fleet, so a provider model needs the claude binary but not a Claude subscription. To check the provider you'll actually use, run cc-fleet models <provider> --json (PROVIDER_UNKNOWN ⇒ not configured); that confirms it's configured + enabled, not that it's reachable — the run itself proves reachability.

Approval & sandbox (non-bypass codex)

cc-fleet spawns a network-using child (claude -p → the provider API) and writes a job record (plus a file when you use --prompt-file or redirect --json to one). On a codex that is not in full-bypass mode, expect two things — neither is a cc-fleet bug, so set the user's expectation rather than reporting a failure:

• Approval prompts are normal. A non-bypass approval policy asks the user to approve each cc-fleet … shell call; a fan-out or chunked wait re-prompts. Say so up front — approving is expected; to reduce the prompts the user can lower the approval friction (--ask-for-approval, a less-restrictive mode) or run codex bypassed.
• A sandbox can block the provider call. A workspace-write sandbox disables network by default, so the claude -p child cannot reach the provider and the leaf fails looking like PROVIDER_UNREACHABLE / a timeout — the real cause is the sandbox, not the provider. Heuristic: cc-fleet doctor is locally clean but every provider leaf is "unreachable" → the sandbox is blocking egress. Fix it by letting that command reach the network — approve the escalation codex offers, have the user enable network for the workspace-write sandbox, or run codex bypassed if they accept that.

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)

1. The user named a provider or model → use it.
2. 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)").
3. 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.)
4. 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 (fable / 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 with your shell tool, always with --json)

cc-fleet subagent --prompt "<task>" --label "codex/<cwd-basename>/<short>" --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" \
  --label "codex/cc-fleet/quicksort" --json

Label every job. A codex-launched job is grouped on the Agents Board under your Codex launcher (a codex <thread> header, not (no session)); a --label "codex/<cwd-basename>/<short>" still helps you tell your jobs apart within that group.

Expected-large output → redirect --json to a file and read the file, sidestepping any shell-output cap: cc-fleet subagent … --json > out.json, then read out.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.

Useful flags (full list: cc-fleet subagent --help):

• 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, raise --timeout or use --background (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 (cap the agentic tool loop). On fan-out, strongly consider a budget cap on every call. Size --max-turns generously up front — a read-heavy / multi-file / git-inspecting task spends ~1 turn per file read or command, so give it 30–50 (or omit it); a small cap (8/10) starves it and the leaf fails SUBAGENT_MAX_TURNS mid-task (budget ~$0.3–0.9 for such a leaf).
• 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).