Delegate

Overview

c3_delegate is one MCP tool with one Python entry point, cli.tools.delegate.handle_delegate. Every call is scored by c3 delegate-eval against the same suite, so a routing default here is a measured choice, not a guess — the CHANGELOG entries for 2.131 through 2.140 are a sequence of measurements, one change at a time (a "delegate remediation" that started from a bad baseline: of 44,038 C3 tool calls across 65 projects, only 19 were delegations, and 10 of the 12 with a logged outcome had errored).

Signature

c3_delegate(
  task: str, task_type: str = "ask", context: str = "",
  file_path: str = "", backend: str = "host",
  allow_write_delegation: bool = False,
  tier: str = "", model: str = "", scout: bool = False,
  write_paths: str = "",
)

Quick start

c3_delegate(
  task='Summarize this diff for a changelog in three bullets',
  context='<diff>', task_type='summarize',
)

c3_delegate(
  task='Which functions call charge_card, and where?',
  scout=True,
)

c3_delegate(
  task='Rename calc_total to order_total: its '
       'definition and every use. No alias.',
  write_paths='inv/orders.py, inv/report.py, '
              'tests/test_orders.py',
)

Backends

backend='host' (the default since 2.134.0) routes to the provider the calling agent runs on:

A host with no mapped backend, or whose mapped backend Access Guard would block, falls back to auto with a note in the response. host runs at delegate.default_tier (small).

Explicit backends

Tiers, effort & thinking caps

tier is a size, not a model id — a pinned id goes stale, an alias follows the CLI to the current model of that size. Aliases fold to a tier: haiku→small, sonnet→medium, opus→large, parent→default. An explicit model always overrides the tier.

Codex and Grok keep the account's own model and step reasoning effort instead of the model itself (a pinned model id goes stale — 2.132.0 measured the old Codex default rejected outright by ChatGPT logins); delegate.codex_tier_models / delegate.grok_tier_models can still name a model per tier for a project that wants that. delegate.claude_tier_models overrides the claude table.

Which default tier applies

Effort and thinking caps (claude only)

Two different knobs, measured separately. --effort had no measurable effect on Haiku 4.5; the thinking-token cap is what actually moves cost.

Measured (2.138.0) — why Haiku is capped at 1024 and Sonnet is not

On two real-file reviews, capping Haiku at 1024 cut cost ~55% and wall time 2.6× with no false finding, while cap-0 Haiku produced one false finding and Sonnet at any nonzero cap ignored the cap (9.4k output tokens regardless) — Sonnet's depth is the reason it stays uncapped. Config target syntax for comparing caps yourself: c3 delegate-eval --targets claude:small,claude:small+think=0 --targets claude:small+effort=low.

scout=true v2.135.0

A tool-less delegate answers only from what it's given — no backend but Codex passed the eval's lookup cases. A scout may read the project itself: on claude, claude -p --restricted --strict-mcp-config --tools Read,Grep,Glob --permission-mode dontAsk --settings …, run in the project; on codex, its own read-only sandbox (already project-scoped).

How the fence was built

Measured before shipping it (Claude Code 2.1.270, a .env canary, a repository-wide Grep): with no controls the value leaked; a PreToolUse hook alone still leaked it (a hook sees a Grep's arguments, never its hits); permission denies (Read(**/.env*), Read(./secrets/**)) stopped it; an absolute Read(//C:/…) deny did not; CLAUDE.md is not loaded under --restricted anyway.

• Every Access Guard deny, confirm-held read, and mask rule becomes a Read() permission deny in the scout's --settings.
• --restricted ignores every settings file except this one, so the read denies are the only permissions the scout runs with.
• A corrupt rule scope refuses the scout outright rather than running it unfenced.
• Scout answers are never cached. Timeout: delegate.claude_scout_timeout (240s).

Measured (2.135.0)

Haiku spent 15 turns and a minute hunting for the denied value before giving up; Sonnet stopped after 2 — which is why a scout defaults to medium, not small.

write_paths v2.139.0

The stronger model decides a change and describes it; a cheaper Claude worker makes it and hands back a diff. Claude only, never cascades, defaults to Sonnet. Full design: docs/delegate-write.md.

When to use it

The change is already decided and can be written down: which files, what behavior, the edge cases. Rename across three files, fix a named bug, add a function to a spec, write tests for a given function. Not for open-ended work ("improve this module") or anything that needs commands — the worker cannot run tests, so you run them after reading the diff. For multi-step work that needs commands, the c3-worker subagent fits better (see below).

The worker and its fences

The worker is claude -p --restricted --strict-mcp-config --tools Read,Grep,Glob,Edit,Write --permission-mode dontAsk --settings <json>, in the project directory, with no MCP servers and no user or project settings. Four layers:

1. Claude Code permission rules. Edit(./<glob>) allows are the write set; Read() / Edit() denies come from every Access Guard deny, read_only, confirm and mask rule. Deny beats allow, so a broad write set cannot reopen a held path.
2. --restricted. No command-running tools; file tools confined to the project; writes to settings, git and tool-configuration files refused.
3. The guard hook in worker mode (hook_access_guard.py --worker-state), on every file tool: inside the project; not under .git/ or .c3/; not a credential-vault file; Access Guard with no grants and no filed override requests (a confirm hold is a refusal here — a headless worker cannot wait for a human); the write set; and no other agent's file lock. Any hook error denies.
4. Pre-images. The same hook saves each file's content before its first write in the run. C3 diffs against these afterward, so the answer is right even when the worker's own report is not.

What comes back

[delegate:write] claude medium (sonnet) changed 3 file(s) in 21.4s. Review the diff and run the tests before relying on it.
  M inv/orders.py (+1 -1)
  M inv/report.py (+2 -2)
  M tests/test_orders.py (+2 -2)
Refused (1): Edit inv/money.py

--- worker report ---
<the worker's own summary: what it changed, what it could not do, assumptions>

--- diff ---
<unified diff of every change, capped at delegate.claude_write_diff_max_chars>

Each changed file is logged to the edit ledger (tags c3_delegate, claude, the tier). A worker stopped at its deadline still answers [delegate:write-failed] and lists what it changed. A literal write path Access Guard already refuses (.env, CLAUDE.md) is dropped before the worker starts; if every path is refused, nothing runs ([delegate:blocked]).

Measured (2026-09-14, 66 worker runs) — why Sonnet is the default

Haiku failed where the spec was subtle (a CSV line-number off-by-one twice, a $-0.05 parsed as +5 once). No run, Haiku or Sonnet, touched a file outside its write set or reached .env; both reported the part they couldn't do. Cost is close to a wash; the lead's own reading cost is not, since Sonnet's diffs were smaller.

Delegation without the agent deciding v2.136.0 / v2.140.0

c3_delegate only saves anything when an agent calls it, and agents rarely do (19 of 44,038 calls at the start of this work). Two mechanisms close that gap without needing a decision. Design: docs/delegate-auto.md.

Downshift subagents v2.136.0

c3 install-mcp (Claude Code) writes two subagents to .claude/agents:

They run inside your session, so Access Guard, the edit ledger and discipline hooks apply to them as they do to the parent. Install rewrites only files carrying C3's marker; a file without it is yours and is left alone. Skip both with --no-agents.

Subagent downshift (the hook) v2.140.0

Measured over ~/.claude/projects transcripts since 2026-07-01: 963 of 991 Agent calls had no model, and on Claude Code 2.1.270 such a call runs on the parent's own model — a probe with a Sonnet parent put an entire Explore run, and a general-purpose run, on Sonnet. So an Opus or Fable session paid its own rate for every search-and-summarize branch it spawned.

A PreToolUse hook (cli/hook_agent_model.py, policy in services/agent_downshift.py) fills a model-less Agent/Task call's model one tier down, via hookSpecificOutput.updatedInput. Verified live: an Opus parent's model-less Explore call ran on Sonnet.

Never touched: a call that passes model explicitly; a subagent whose own definition sets model: (like c3-scout/c3-worker); plugin agents; non-Claude hosts. The parent's model is read, in order, from the transcript's last assistant row, then the last model this project saw in the past 14 days, then Claude settings — if none is known, nothing changes.

Delegation hints v2.140.0

services/delegate_hints.py watches a per-session window and adds one [c3:delegate-hint] line to a successful c3_edit, c3_read, c3_search or c3_delegate response when the session's own work looks delegable:

Each kind has a 45-minute cooldown (delegate.hint_cooldown_minutes) and won't fire while the session is already delegating that kind. delegate.hints: false turns them off entirely.

Telemetry & c3 delegate-eval v2.132.0

Every c3_delegate response writes a detail row to .c3/tool_telemetry.jsonl: host, requested and actual backend, task type, outcome, wall time, and when known tier, model, mode, confidence, cascade, tokens and cost. aggregate_tool_telemetry folds these into delegate_by_backend (calls, outcomes, ok rate, cost, tokens, models, task types, wall p50/p95), which feeds the [delegate:7d] line on c3_status(view='budget'):

# exact format (cli/tools/status.py)
[delegate:7d] {calls} calls, {ok} answered, ${cost} reported{, N file(s) written} ({backend:calls, ...})

What c3 delegate-eval measures

Every case in tests/delegate_eval/gold_suite.jsonl (25 bounded tasks: 22 core, 3 lookup) is sent through handle_delegate against backend[:tier] targets and graded by regex checks (must_match, any_match, must_not_match, max_words), case-insensitive. A no-answer status (error, timeout, blocked, disabled, unavailable, degraded) grades as an error, never as a wrong answer, so a broken backend never reads as a weak model. Core cases carry everything the answer needs in context/file_path; lookup cases carry neither, so only a delegate that reads the fixture project itself (+scout) can pass — a live run writes an env canary and lookup-env-secret fails any answer that leaks it. Append +scout to a target to run it that way; write-mode cases live in a separate suite (--suite write, see write_paths).

Running it (verified against c3 delegate-eval --help)

# live: every case costs what the backend costs
c3 delegate-eval --targets claude:small,claude:medium,claude:large --record run.json

# a subset of cases, delegate config overridden just for this run
c3 delegate-eval --targets ollama --cases explain-slice,review-toctou \
  --config '{"allow_model_fallback": false, "preferred_model": "gemma3:12b"}'

# grade a recorded run again — free, deterministic
c3 delegate-eval --replay run.json

# CI-style gate: exit 1 when a target's core pass rate is under the floor
c3 delegate-eval --replay run.json --floor 0.8

# --suite: 'gold' (bundled, default), 'write', or a .jsonl path
# --json emits the full report as JSON instead of the table

Live runs work on a throwaway copy of tests/delegate_eval/project, so a delegate that reads or writes never touches the checkout. Pass --allow-write-delegation to measure a write-capable backend on a machine with Access Guard rules. When several tiers of one backend run together, the report names the cheapest passing tier per task type: the lowest mean cost among tiers whose pass rate reaches the floor (default 0.8) and sits within 0.1 of that backend's best tier.

tests/delegate_eval/replay_fixture.json holds a correct and a plausibly-wrong answer for every case; tests/test_delegate_eval.py requires every correct one to pass and every wrong one to fail in CI, so a check that can't fail is caught without spending on a model.

Grok Build backend v2.131.0

xAI's Grok Build CLI (grok) is both a C3 host (c3 install-mcp --ide grok, alias grok-build) and a c3_delegate backend. Full detail: docs/grok-native.md.

c3_delegate(task='...', backend='grok')
# runs: grok --prompt-file <tmp> --output-format json \
#         --tools read_file,grep,list_dir --max-turns N [-m model] --cwd <dir>

In both modes the child drops the parent's host session identity and Grok's Claude Code / Cursor imports are disabled, so a delegate never inherits another host's hooks, agents or MCP servers. It also joins the auto cascade (after gemini for heavy task types) and answers task_type='grok_check' with a version-only check (no model call).

Grok Build uses its own login (e.g. a SuperGrok account); C3 stores no xAI key.

c3_agent — a different tool

c3_agent(workflow=..., scope=..., context=...) is not delegation: it orchestrates multiple C3 tool calls inside the calling agent's own turn, for compound investigations that would otherwise be five-plus separate tool calls. Workflows: available, review_changes, prepare_context, investigate, preflight, validate_compress.

# Pre-task check: recall memory + status + recent changes
c3_agent(workflow='preflight', context='starting auth refactor')

# Multi-step: search → compress → summarize → recommend
c3_agent(workflow='investigate', context='why does session restore fail after compact?')

Use c3_delegate to hand work to a different (usually cheaper) model. Use c3_agent to run a known sequence of C3 tools without spelling out each call.

Troubleshooting