Agent tool: add effort parameter for controlling subagent thinking depth

Resolved 💬 4 comments Opened Mar 26, 2026 by ray-amjad Closed May 28, 2026

Summary

When spawning subagents via the Agent tool, there's no way to control the effort/thinking level per invocation. The effort flag exists in agent frontmatter and as a CLI flag (--effort), but cannot be set dynamically when spawning ad-hoc subagents.

Current behavior

  • effort can be set in agent definition files (.claude/agents/*.md frontmatter)
  • effort can be set via claude --effort high CLI flag
  • The Agent tool accepts model, mode, isolation, etc. — but not effort
  • All ad-hoc subagents inherit the parent's effort level with no override

Desired behavior

The Agent tool should accept an effort parameter (low, medium, high) so users can control thinking depth per subagent at spawn time:

Agent(
  prompt: "Review this file for security issues",
  effort: "high"
)

Agent(
  prompt: "Rename these variables to snake_case", 
  effort: "low"
)

This would allow lightweight tasks (file renames, formatting) to run with minimal tokens while reserving deep reasoning for complex tasks (debugging, security review) — all within the same session.

Use case

When orchestrating multiple subagents in parallel, different tasks have very different complexity. A coordinator agent might spawn:

  • An explore agent (low effort — just finding files)
  • A code reviewer (high effort — needs deep reasoning)
  • A test runner (low effort — just executing commands)

Currently all three use the same effort level, wasting tokens on simple tasks or under-reasoning on complex ones.

Workaround

Create separate agent definition files for each effort level, which adds file bloat for what should be a single parameter.

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗