anthropics / anthropics/claude-code

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

オープン
#93,109 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
area:agents bug platform:linux
主要言語
Python
スター
145k
フォーク
23.1k
PR マージ指標
PR 指標を取得中

説明

### 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.

コントリビューションガイド

このリポジトリのコントリビューションガイドは索引されていません

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

評価

領域
cli, documentation
issue の種類
バグ
難易度
4/5
見積もり時間
3〜5日
活発さ
活発
明瞭さ
おおむね明確
初心者へのやさしさ
48/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。