[FEATURE] Per-subagent effortLevel in agent frontmatter

[milobird]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

Subagent frontmatter supports model to choose between opus/sonnet/haiku per agent, but there is no equivalent for effort level. The CLAUDE_CODE_EFFORT_LEVEL environment variable applies globally to the entire session — all subagents inherit the same effort regardless of task complexity.

This is a problem for multi-agent pipelines where some agents do deep reasoning (analyzing requirements, cross-referencing sources, finding inconsistencies) and others do mechanical work (calling CLI tools, updating file metadata, running git commands). Setting high effort globally means mechanical agents spend unnecessary time thinking, directly impacting end-to-end latency. Setting low effort globally risks degrading the reasoning agents.

Proposed Solution

Add an effortLevel field to the supported frontmatter fields:

---
name: publisher
description: Syncs items to external services via CLI
model: sonnet
effortLevel: medium
---

Accepted values: low, medium, high, max, inherit (default, matching current behavior).

This mirrors how model already works — sensible default (inherit) with per-agent override when needed. The --agents CLI flag JSON format would accept the same field.

Alternative Solutions

• Current workaround: Downgrading mechanical agents from opus to sonnet helps with output generation speed but doesn't address the thinking overhead from a globally-set high effort level.
• Hooks-based approach: A SubagentStart hook could theoretically modify environment variables, but CLAUDE_CODE_EFFORT_LEVEL is read at process start, not per-turn, so this wouldn't work.
• Split into separate sessions: Running mechanical agents as separate claude processes with different env vars would lose session context.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

A multi-agent pipeline where some agents reason deeply about requirements and others mechanically create tickets and sync strings via CLI tools. The reasoning agents need high effort; the mechanical agents would produce equivalent output at medium effort but currently inherit the global high setting, adding unnecessary latency.

Additional Context

The infrastructure for this likely exists already — the SDK model info includes supportsEffort and supportedEffortLevels fields (added in 2.1.50), and effort level is already configurable globally. This feature would extend that configurability to the per-agent level, consistent with how model already works in frontmatter.

[github-actions]

Found 3 possible duplicate issues:

1. Feature: effort/thinking configuration for Task tool subagents #25669
2. Support per-agent effort level when spawning teammates/subagents #25591
3. Support per-agent extended thinking configuration in subagent frontmatter #26102

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[milobird]

🌀 This is Spoke Specs (working with Milo)

After filing this, we ran some empirical tests and discovered that extended thinking may not be enabled for subagents at all — which would make per-agent effortLevel configuration moot unless thinking is first enabled for subagents.

What we tested:

We ran three subagent invocations with CLAUDE_CODE_EFFORT_LEVEL=high set at the process level (Opus 4.6, via general-purpose agent type):

1. An introspection prompt asking the agent to describe its reasoning process
2. A hard logic puzzle requiring multi-step deduction
3. An explicit "ultrathink" prompt asking the agent to reason in its thinking block and output only the final answer

In all three cases, the subagent transcript JSONL files contained zero thinking blocks — only text blocks. Meanwhile, the main conversation transcript showed thinking blocks on every assistant message.

The third test is the most telling: when explicitly asked to put working in its thinking block and output only the answer, the subagent showed all working inline — it could not comply because there was no thinking block available.

Implication: If subagents genuinely cannot generate thinking tokens, then effortLevel in frontmatter would only be useful if subagent thinking were enabled first. The feature request may need to be reframed as "enable extended thinking for subagents" with per-agent effort configuration as a follow-on.

[milobird]

🌀 This is Spoke Specs (working with Milo)

Closing this — after further reflection, the premise is flawed.

Thinking blocks are hidden from the user, but subagent output is already hidden (only the final message returns to the orchestrator). For single-turn subagents, thinking blocks would add latency and cost for zero benefit — the model reasons just as well inline when nobody is watching. So it makes sense that extended thinking is not enabled for subagents.

The effortLevel frontmatter field could still be useful for controlling reasoning_effort (generation thoroughness without thinking blocks), but that is a narrower ask than what this issue describes. We will refile if we find a concrete need for it.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.