# Opus 4.7 Configuration Patterns

> Token-efficiency patterns for Claude Opus 4.7. Detection IDs map to TOK scanner findings.
> Sources: research/01-opus-47-features-token-efficiency.md (Topic 1), research/04-prompt-caching-patterns.md (Topic 4). Last verified 2026-04-19.

Opus 4.7 raises the cost ceiling per turn while expanding the context window
and prompt-cache window. Net effect: cache reuse and tool-schema discipline
become the dominant levers for keeping a session affordable. The patterns
below are structural — they can be detected statically by reading config files
without running a session. Cache hit-rate measurement requires runtime
telemetry and is explicitly out of scope.

| # | Pattern | Detection (ID) | Severity | Fix |
|---|---------|----------------|----------|-----|
| 1 | Cache-breaking volatile top-of-file content in CLAUDE.md (timestamps, session ids, rolling activity logs above stable content) | CA-TOK-001 | medium | Move volatile sections to the bottom of CLAUDE.md, or extract to an `@import`-ed file that lives outside the prompt-cache prefix. Keep the first 30 lines stable across turns. |
| 2 | Redundant tool/permission declarations in settings.json (e.g., both `"Read"` and `"Read(**)"`, duplicate Bash matchers, overlapping glob patterns) | CA-TOK-002 | low | Deduplicate the `permissions.allow` and `permissions.deny` arrays. Prefer the most specific entry that still grants the intended access. Each duplicate entry inflates the tool-schema payload sent on every turn. |
| 3 | Deep `@import` chain in CLAUDE.md (more than 2 hops, e.g., A → B → C → D) | CA-TOK-003 | medium | Flatten the chain to ≤ 2 hops. Each `@import` boundary fragments the prompt-cache prefix; deeply chained imports defeat caching for the deepest content even when it never changes. |
| 4 | Sonnet-era configuration signature: clean structural baseline with no Opus 4.7 features enabled (no skills, no managed-settings, no plugins, no rules) | CA-TOK-004 | info | Informational only. The configuration is structurally clean but does not yet leverage Opus 4.7-specific features (managed settings, deeper plugin integration). Not a defect — a hint that token-efficiency-driven optimisations have not been applied. Threshold calibration pending Topic 3 research. |

## Detection notes

- **Pattern 1 (cache-breaking)** is detected by inspecting the first ~30 lines
  of CLAUDE.md for tokens that look volatile: literal `{timestamp}`, `{uuid}`,
  `{date}`, `{session}` placeholders, or runs of ISO-timestamp-prefixed lines.
  The scanner does not attempt to verify cache-hit rate; it flags the *shape*
  of content that empirically defeats prompt-cache reuse.
- **Pattern 2 (redundant tools)** is detected by flattening the
  `permissions.allow` and `permissions.deny` arrays and looking for entries
  that are strict subsets of broader entries (e.g., `Bash(npm test)` when
  `Bash(*)` is also present), or exact duplicates.
- **Pattern 3 (deep imports)** uses the existing IMP scanner's chain depth as
  the input — anything > 2 hops triggers TOK-003 as well as the IMP finding.
- **Pattern 4 (sonnet-era)** is informational and emitted only when a config
  is otherwise clean (no skills, no managed-settings, no plugins, minimal
  hooks). The threshold is heuristic until Topic 3 research lands.

## Threshold calibration

All thresholds in this catalogue are **structural** — derived from the
existing `estimateTokens(bytes, kind)` heuristic in
`scanners/lib/active-config-reader.mjs:29-39`. They are intentionally
conservative until Topic 3 (token-cost model) research is complete. When
Topic 3 lands, severities for patterns 1–3 will be re-tuned and pattern 4
may gain a measurable threshold.

The `estimateTokens` heuristic uses ~4 bytes per token for markdown content,
which is conservative but unverified against an authoritative tokenizer.
All token counts surfaced by the TOK scanner carry an implicit ±20%
uncertainty band.

## Severity Scale

| Severity | Meaning |
|----------|---------|
| medium | Materially inflates token cost per turn (cache miss, schema bloat) |
| low | Detectable inefficiency that compounds across long sessions |
| info | Informational signal — no action required, may indicate room for optimisation |