[BUG] Claude hallucinates Claude Code's own settings/hooks schema

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Problem

Asked to add a SessionStart hook, Claude (Opus 4.7) confidently wrote configs that are not in the documented schema, then debugged its own hallucinations for ~45 minutes across six commits before being told to check docs.

Concrete hallucinations in one session:

1. Hook matcher. Wrote "matcher": "startup|resume|clear" assuming regex. SessionStart matcher is literal string — value never matched, hook silently skipped. Not in docs the agent read; not in docs the agent didn't read either.
2. Settings scope. Placed the hook in ~/.claude/settings.local.json. There is no user-home settings.local.json scope — it's project-only per https://code.claude.com/docs/en/settings. File silently ignored.
3. Invented regression. Framed (2) as "Claude Code v2.1.x silently drops command hooks from settings.local.json" and wrote that to a memory file before checking docs.

Each fix targeted the wrong layer. Each one shipped as a commit. Each one was wrong.

Root cause

The agent does not know Claude Code's own schema and does not refuse to write Claude Code config without verifying. It guesses, ships, and only consults docs when the human says "are you hallucinating?".

Fix ideas

1. Bake the settings + hooks schema (valid scopes, valid keys per scope, matcher semantics literal-vs-regex per event) into the in-CLI agent's system prompt. Bounded, stable, exactly the kind of fact agents shouldn't look up.
2. Expose an MCP/skill claude_code__schema_lookup(path|field) → "honored at scope X / not honored, nearest valid is Y / matcher is literal not regex". Agent calls it before any settings edit.
3. Require doc-grounding before writing ~/.claude/settings.json or /.claude/settings*.json — same rigor the agent already applies to writing migrations.

Environment

• Claude Code 2.1.133, Claude Opus 4.7 (1M context)
• Windows 11 + WSL2 Debian

What Should Happen?

The agent should reach ~/.claude/settings.json with no matcher on turn one using correct syntax.

Error Messages/Logs

Hallucinated hooks won't work, will lead to shaving the yak, wasting hours and tokens. No logs to speak of. You only "see" the hooks not working.

Steps to Reproduce

Ask Claude inside Claude Code to add a SessionStart hook that runs a shell script. Observe whether it (a) places it in ~/.claude/settings.local.json and (b) writes a regex-style matcher. Both are hallucinations.

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.138 (Claude Code)

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

PowerShell

Additional Information

_No response_