anthropics / anthropics/claude-code

Agent frontmatter: unrecognized keys (e.g. outputStyle) are silently ignored with no warning

Offen
#93,109 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
area:agents bug platform:linux
Vorherrschende Sprache
Python
Sterne
145k
Forks
23.1k
PR-Merge-Kennzahlen
PR-Kennzahlen ausstehend

Beschreibung

### Summary

Unrecognized keys in a subagent definition's YAML frontmatter (`~/.claude/agents/*.md`) are silently dropped. Nothing is printed, logged to the user, or surfaced in any diagnostic, so there is no way to tell that a key had no effect.

I hit this with `outputStyle`, which is not a supported agent frontmatter key. But the silent-ignore applies to any unsupported key or typo, which is the more general problem.

Filing here rather than `/feedback`, which is disabled by policy in my environment.

### Version

`2.1.266`, Linux.

### Reproduction

1. Create `~/.claude/agents/terse.md`:

```markdown
---
name: terse
description: Test agent.
outputStyle: some-style
---

You are a test agent.
```

2. Spawn the agent (Agent tool, or `--agent terse`).

3. Observe: the agent loads and runs fine, the key has no effect, and there is no warning at startup, on load, or in any diagnostic output. Same result for an outright typo (`ouputStyle`, `tool` instead of `tools`, etc.).

### What's happening

From inspecting the bundled CLI:

- The agent frontmatter schema accepts `name`, `description`, `model`, `tools`, `disallowedTools`, `color`, `effort`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `background`, `isolation`, `observer`, `observerMessage`, `observeSubagents`. There is no `outputStyle`.
- The runtime loader parses frontmatter with a non-strict `.parse()`, so unknown keys are stripped.
- A `.strict()` copy of the same schema does exist and is `safeParse`d. On an `unrecognized_keys` issue it only emits a deduped internal telemetry event (keyed `frontmatter_shadow:*`). It never throws, and nothing reaches the user. There is no "unknown frontmatter key" message string anywhere in the bundle.

So the strict check that would catch this already runs — its result just isn't shown to anyone outside telemetry.

### Requests

**1. Surface unrecognized agent frontmatter keys to the user.** This is the actual bug. A startup warning, `--debug` output, or a line in a diagnostic command would all work. Right now a typo in an agent file is undetectable without decompiling the CLI. The same likely applies to skill and output-style frontmatter, which use the same strict-schema table.

**2. Consider supporting `outputStyle` in agent frontmatter.** Separate feature ask, lower priority. Output styles currently apply only to the main REPL thread — the prompt-id helper reads `outputStyle` and yields `repl_main_thread:outputStyle:`, whereas subagents get `agent:custom:` and their system prompt is built by a separate path that never consults the output style. Subagents also don't inherit the session's style. Today the only ways to shape a subagent's output are restating the style prose in the agent's markdown body, or the `@internal` `appendSubagentSystemPrompt` setting gated behind `CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT`. Neither is a documented per-agent equivalent of an output style. Given output styles and agent definitions are both user-authored prompt customizations, reaching for `outputStyle:` in an agent file is a natural guess — which is what made the silent ignore costly.

**3. Document the supported agent frontmatter keys.** I could not find a complete list in the docs; I got the one above out of the bundle.

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Rechercherichtung

Start with the bundled CLI's agent frontmatter runtime loader and the strict schema/safeParse path described in the report. Trace how unrecognized_keys are handled and where startup, --debug, or diagnostic output is assembled; done means an unknown key produces a user-visible warning while valid keys remain unchanged, with supported keys documented.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Bereich
cli, documentation
Issue-Typ
Bug
Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Aktivitätsstatus
Aktiv
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
48/100

Neue Issues direkt in Ihr Postfach

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