Dial Reasoning Up on Hard Subagents, Down on Cheap Ones: opts.effort in Claude Code Workflows

Set effort='low' on scans, effort='xhigh' on verification — three reasoning tiers in one workflow cuts cost 40–60% without touching quality on hard steps.

Every agent() call in a Claude Code workflow inherits the session's reasoning effort by default. The opts.effort parameter overrides it per call: 'low' | 'medium' | 'high' | 'xhigh' | 'max'. The right tier depends on what kind of thinking the subagent actually needs.

export const meta = { name: 'audit-and-fix', description: 'Security audit with tiered effort' }

// Stage 1: read files in parallel — no reasoning needed, just retrieval
const files = await parallel(paths.map(p => () =>
  agent(`Read and return the full contents of ${p}`, { effort: 'low' })
))

// Stage 2: implement fixes — medium effort (default) is fine for local edits
const fixes = await pipeline(files, f =>
  agent(`Fix any SQL injection risks in this file:\n\n${f}`)  // inherits session effort
)

// Stage 3: adversarial verify — xhigh: we want real scrutiny, not pattern-matching
const verdicts = await parallel(fixes.map(fix => () =>
  agent(`Try to find a bypass for this SQL injection fix. Default to bypassed=true if uncertain.`,
    { effort: 'xhigh', schema: VERDICT_SCHEMA })
))

Decision table

Stage type	Recommended effort	Reason
File reads, searches, grep	low	Output is deterministic; reasoning adds nothing
Straightforward implementation	medium (default)	Balanced cost/quality
Debugging, root-cause analysis	high	Benefits from reasoning steps
Adversarial verification, security review	xhigh	Needs genuine scrutiny

Limits to know

• max effort is not available on Haiku 4.5 — use xhigh as the ceiling there.
• Higher effort does not improve purely deterministic tasks (file reads, JSON parsing) — it just costs more tokens.
• Combine with opts.model for maximum control: effort: 'low', model: 'haiku' for cheap scans; effort: 'xhigh', model: 'opus' for the final judgment stage.
• Per-agent overrides are sticky within that agent only — the session's default effort is unaffected.

Sources: Workflow SDK reference — code.claude.com · Model configuration — code.claude.com · claudefa.st — community practitioner notes