anthropics / anthropics/claude-code

docs: subagent frontmatter `effort` field is implemented but undocumented

Offen
#91,415 1 Kommentar 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
area:agents documentation enhancement
Vorherrschende Sprache
Python
Sterne
145k
Forks
23.1k
PR-Merge-Kennzahlen
PR-Kennzahlen ausstehend

Beschreibung

## Summary

Claude Code 2.1.258 parses an `effort` field in custom subagent definition files (`.claude/agents/*.md`, `~/.claude/agents/*.md`), but the sub-agents documentation does not list it, so users assume the field does not exist (or that a value they wrote is inert).

## Evidence

The agent-definition schema embedded in the 2.1.258 binary contains:

```
effort: enum(["low","medium","high","xhigh","max"]) | int, optional
"Reasoning effort level for this agent. Either a named level or an integer"
```

It sits alongside the other frontmatter fields (`maxTurns`, `background`, `memory`, `permissionMode`, `observer`). The Agent tool description also states that each agent type's "model, reasoning effort, and tools come from its definition (`.claude/agents/*.md` frontmatter or SDK `agents`)".

The official docs, however:

- https://code.claude.com/docs/en/sub-agents — the frontmatter field table lists only `name`, `description`, `tools`, `model`, `permissionMode`, `skills`, `memory`, `isolation`. No `effort`.
- https://code.claude.com/docs/en/model-config — documents `effortLevel`, `modelSettings..effortLevel`, `CLAUDE_CODE_EFFORT_LEVEL` and `/effort`, but says nothing about subagents (neither the frontmatter field nor whether a subagent inherits the parent session's effort).

This is the follow-up to #43083 (closed 2026-08-17), whose later comments show users still unsure whether the feature exists or what the default is.

## Requested change

1. Add `effort` to the sub-agents frontmatter table: accepted values (`low`/`medium`/`high`/`xhigh`/`max` or an integer), and an example.
2. State the precedence and default: what a subagent uses when `effort` is omitted (parent session effort? `modelSettings` for its model? a fixed default?).
3. Optionally cross-link from the model-config page.

## Environment

- Claude Code 2.1.258, macOS

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Rechercherichtung

Start by reading the sub-agents and model-config documentation pages, then compare their frontmatter tables with the agent-definition schema and Agent tool description quoted in the issue. Confirm the omitted-field precedence and default with the project maintainers, then document the accepted values, an example, and the resolved behavior, adding a cross-link if appropriate.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
3/5
Geschätzter Aufwand
1-2 Tage
Aktivitätsstatus
Aktiv
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
65/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.