features/agents/models_and_effort

features/agents/models_and_effort

[[features/agents/_index|..]]

---

Override sources

A node's agent identity and its overrides are configuration: the config keys agent (the command, extra words spliced into every invocation), provider (the route, see [[features/agents/providers]]), model, and effort. Every invocation builder also accepts per-call model and effort overrides, so a single spawn can deviate from the node's configured defaults.

Effort is passed through to the provider's own effort flag unvalidated — fractal does not maintain a level vocabulary; an unknown level surfaces as the agent's own error. A hard USD budget is a separate per-invocation knob accepted only by backends that declare budget enforcement; asking a non-enforcing backend for one is an error.

Per-backend spelling

Each backend translates the same two overrides into its own CLI dialect:

backend	model flag	effort flag
claude	--model	--effort
codex	-m	-c model_reasoning_effort="<lvl>"
grok	-m	--reasoning-effort
opencode	-m	--variant (a model variant)
omp	--model	--thinking (a thinking level)

For claude the effort flag outranks the settings-file effort level, and it is the only effort channel fractal uses -- the CLAUDE_CODE_EFFORT_LEVEL env knob is deliberately not set, since a spawn-env knob leaks into the session's own subprocesses and would override any nested claude run; ambient copies of the effort knobs are actively unset at invocation compose -- an operator shell's CLAUDE_CODE_EFFORT_LEVEL would override the step pin inside the session, and a stale CLAUDE_EFFORT (claude's own export to hook/Bash subprocesses) would masquerade as the child session's -- and so is the model-forcing CLAUDE_CODE_SUBAGENT_MODEL, which would force every fan-out sub-agent onto one model, explicit per-agent pins included (the seeded node settings deliberately do not set it either); node settings (permissions, model, environment) ride a CLI flag rather than a file merge. On the openrouter route a model-less claude invocation pins an explicit model slug, because the process environment beats the settings file and the route must not trust latest-model aliases.