[BUG] claude -p --agent ignores the agent's frontmatter 'effort:' (hooks report session default)

Status Open
Reported on v2.1.220
Maintainer reply None cached
Activity 0 comments · opened Jul 29, 2026

Environment

  • Claude Code 2.1.220, Linux (Fedora), subscription auth

Summary

claude -p --agent <name> does not apply the agent's frontmatter effort: level. The documented resolved-effort channel (hook input effort.level — "the downgraded level the model actually used") reports the session default (high) even when the agent frontmatter says low. When the same agent definition is spawned as a child via the Agent tool from a parent session, the child's hook events DO report the configured frontmatter level — so the frontmatter is honored in the subagent path but ignored in the direct --agent path.

Repro

mkdir -p /tmp/effort-repro/.claude/agents && cd /tmp/effort-repro

cat > .claude/agents/demo.md <<'AGENT'
---
name: demo
description: Minimal repro agent
model: sonnet
effort: low
---
Answer briefly.
AGENT

cat > .claude/settings.json <<'SETTINGS'
{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "jq -c '{hook_event_name, effort}' >> effort-log.jsonl" } ] }
    ]
  }
}
SETTINGS

claude -p "Say ok" --agent demo --setting-sources project \
  --no-session-persistence --permission-mode dontAsk --tools "" \
  --output-format json >/dev/null

cat effort-log.jsonl
# => {"hook_event_name":"Stop","effort":{"level":"high"}}   <-- expected "low"

Cross-check from a fuller acceptance run on the same client: five direct --agent runs of agents configured low/medium all logged high on every hook event, while parent-session-spawned children of the same definitions logged their configured levels (high for a high-effort agent, low for a low-effort agent, with agent_type attribution on PreToolUse/SubagentStop).

Possibly related: CHANGELOG 2.1.210 fixed claude agents --effort being silently dropped for dispatched sessions; this looks like the same class of gap for frontmatter effort: in -p --agent.

Expected

The --agent run applies the agent's frontmatter effort: low, and hooks report {"effort":{"level":"low"}}.

Actual

Hooks report the session default (high); the frontmatter value is ignored.

View original on GitHub ↗