[DOCS] Sub-agents page omits the Agent tool's per-invocation effort parameter and the values the per-invocation model parameter accepts #100347

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/sub-agents

Section/Topic

"Supported frontmatter fields" (effort row) and "Choose a model" (per-invocation model)

Current Documentation

The effort frontmatter row says: "Effort level when this subagent is active. Overrides the session effort level, but not the CLAUDE_CODE_EFFORT_LEVEL environment variable." The "Choose a model" section says Claude "can also pass a model parameter for that specific invocation" and gives the resolution order, but does not list which values that parameter accepts. The page does not mention a per-invocation effort parameter.

What's Wrong or Missing?

The 2.1.292 changelog says "Added an effort parameter to the Agent tool". The page does not document it. In our test on 2.1.293, a subagent whose definition sets effort: xhigh, spawned with effort: "low", recorded effort: "low" on its assistant records and in its .meta.json. The Agent tool's own parameter description says it is ignored for subagent_type: "fork"; the page does not say so, nor which values the parameter accepts.

Separately, in our 2.1.293 test the per-invocation model parameter rejected a full model ID ("claude-opus-5") with Invalid option: expected one of "sonnet"|"opus"|"haiku"|"fable". The page does not state this restriction, or distinguish it from the definition's model field, which accepts full model IDs.

Suggested Improvement

1. Document the per-invocation effort parameter: its accepted values, whether it applies to fork, and how it interacts with definition effort, the session effort and CLAUDE_CODE_EFFORT_LEVEL. (We only tested that it overrides definition effort.)
2. State the values the per-invocation model parameter accepts, and that, unlike the definition's model field and CLAUDE_CODE_SUBAGENT_MODEL, it does not take a full model ID.
3. Update the /tasks note under "Choose a model" ("adds the effort level when the subagent's definition, or the skill it forked from, sets effort") to cover a per-invocation effort, if /tasks shows it.

Impact

Medium - Makes feature difficult to understand

Additional Context

Related: #77298 (feature request this appears to address), #72596, #85416. Tested on Claude Code 2.1.293, macOS.