Subagent effort level is unobservable: cannot tell whether frontmatter `effort:` applies to background-dispatched subagents

Summary

There is no way to observe the effort level a subagent is actually running at — not from inside the subagent, not from the Agent tool result, and (apparently) not from the UI when switching to a dispatched background agent. Because of that, an effort configuration that isn't taking effect fails silently and expensively: the only signal is the token bill, days later.

Related: the equivalent question for model: is answerable, because a subagent can self-report its model. Effort has no such affordance.

Environment

• Claude Code 2.1.226
• Linux
• Session effort: xhigh (effortLevel: "xhigh" in ~/.claude/settings.json)
• Subagents dispatched via the Agent tool with run_in_background: true

What happened

A project set Use "high" thinking level. in prompt text and in agent definition bodies, believing that controlled subagent effort. It does not — reasonable, that's prose. The documented mechanism was then applied instead: effort: high in each subagent definition's frontmatter, per sub-agents docs:

effort — Effort level when this subagent is active. Overrides the session effort level. Default: inherits from session.

After adding effort: high, a freshly dispatched background subagent still displayed xhigh in the UI when switched to. Same after changing effortLevel to "high" in ~/.claude/settings.json and dispatching a new agent.

Frontmatter itself is definitely being honoured. A throwaway agent definition with model: haiku, dispatched from an Opus session with no model override on the tool call, self-reported claude-haiku-4-5-20251001. So the file is parsed and applied at dispatch — this is not #44385 (frontmatter model: ignored), which does not reproduce on 2.1.226.

That leaves two possibilities, and from outside there is no way to tell them apart:

1. effort: in frontmatter is not applied to background-dispatched subagents (while model: is), or
2. it is applied correctly, and the UI shows the session's effort rather than the agent's when you switch to a background agent.

Why this matters

Both possibilities look identical to a user, and the failure mode is silent. A long multi-agent session ran an entire fleet at xhigh while every prompt, every agent body, and eventually every frontmatter said high. Nobody could tell, because nothing reports it. It surfaced only as an exhausted weekly token budget.

Six different mechanisms were tried before the ambiguity was even isolated:

| attempt | result |
|---|---|
| instruction in the prompt text | no effect (expected — it's prose) |
| instruction in the agent definition body | no effect (expected — also prose) |
| effort: high in frontmatter | UI still showed xhigh |
| /effort high sent via SendMessage | arrives as plain text, does not execute |
| effortLevel: "high" in ~/.claude/settings.json | UI still showed xhigh on a newly dispatched agent |
| model: haiku in frontmatter (control) | honoured — proves frontmatter is read |

Only the last one produced a definitive answer, and only because model is self-reportable.

Requests

1. Clarify whether frontmatter effort applies to subagents dispatched with run_in_background: true. The docs give an explicit frontmatter override for permissionMode on dispatched sessions and say nothing equivalent for effort; agent-view discusses where a background session's effort comes from without mentioning the subagent frontmatter field at all.
2. Make effective effort observable. Any one of these would have turned days of guessing into one check:

• show the agent's own effort in the UI when switching to it (if that's already the intent, the value shown appears to be the session's)
• include it in the Agent tool result metadata alongside subagent_tokens and duration_ms
• let a subagent report it on request, as it can for model

1. Consider an effort parameter on the Agent tool. model has one, which is what makes #44385 survivable — there's a documented workaround. effort has no such escape hatch, so if the frontmatter path is broken there is nothing to fall back on.

Repro

# 1. session at xhigh
#    ~/.claude/settings.json -> "effortLevel": "xhigh"

# 2. .claude/agents/probe.md
cat > .claude/agents/probe.md <<'EOF'
---
name: probe
description: effort probe
tools: Read
model: haiku
effort: low
---
Reply "standing by" and stop.
EOF

# 3. dispatch it with run_in_background: true, switch to it in the UI
#    observed: model reflects the frontmatter (haiku); effort shows xhigh