Undocumented Claude Code Config Fields Found in the Source Code

My notes

Summary

A developer reverse-engineered the Claude Code npm package source (@anthropic-ai/[email protected]) and documented dozens of undocumented configuration fields not in official docs. Covers hooks that rewrite tool inputs mid-flight, persistent agent memory, a self-improvement dream loop, and the plain-English YOLO auto-approval classifier. Every example is copy-paste ready.

Key Insight

Hook stdout response fields (biggest gap in official docs)

• PreToolUse hooks can return updatedInput to rewrite a command before execution, e.g., silently add --dry-run to every git push
• permissionDecision: "allow"/"deny" lets a shell script act as a permission classifier without prompting the user
• SessionStart hooks can return watchPaths (auto-file-watch) and initialUserMessage (prepend to first turn)
• PostToolUse hooks can return updatedMCPToolOutput to modify what the model sees from an MCP tool

Three undocumented hook fields

• once: true fires exactly once, then self-removes (useful for first-run setup)
• async: true runs in background, zero blocking latency (good for audit logging)
• asyncRewake: true is non-blocking unless it exits code 2, then wakes the model and blocks. Best pattern for async secret scanning on writes.

Skill frontmatter extras

• model: haiku/sonnet/opus overrides per skill; use haiku for cheap linting, opus for architecture review
• effort: low/medium/high/max controls reasoning depth
• hooks: are scoped hooks that register on skill start and deregister on completion (clean)
• disable-model-invocation: true prevents accidental auto-invocation for destructive skills
• agent: delegates the whole skill to a named agent

Agent frontmatter extras

• memory: user/project/local gives persistent memory across invocations; agents can accumulate project-specific expertise over sessions
• omitClaudeMd: true skips loading CLAUDE.md hierarchy; useful for unbiased “fresh eyes” reviewers
• criticalSystemReminder_EXPERIMENTAL is a short message re-injected every turn, survives conversation compaction; flagged unstable by Anthropic engineers
• requiredMcpServers means the agent only appears if named MCP servers are configured

YOLO Classifier / autoMode

• autoMode.environment array accepts plain English strings (not patterns) describing the setup, e.g. “This is a staging server, destructive operations are acceptable.” The classifier reads these to make safety decisions on ambiguous commands.
• soft_deny patterns always require confirmation regardless of auto-mode

Compound learning loop

• autoMemoryEnabled: true means after each session a background agent extracts durable memories to ~/.claude/projects/<path>/memory/
• autoDreamEnabled: true means every 24h, if 5+ sessions have accumulated, a background agent consolidates memories (merges dupes, resolves contradictions, prunes stale). Together these create genuine learning from experience without model retraining.

Cache gotcha for forked skills

• context: fork skills share the parent’s prompt cache via CacheSafeParams; all forks produce byte-identical API request prefixes. If you set a different model: on a forked skill, cache prefixes diverge, cache miss, full cost. Use model: inherit or omit the field on forked skills.

Full permission glob syntax

• ** matches recursively through directories (e.g. Read(src/**/*.ts))
• MCP permissions: mcp__<server>__<tool> or mcp__<server> for all tools on a server
• Three permission tiers: allow, deny, ask, where ask is distinct from deny