Merge branch 'main' into fix/handover-rereads-config

Author: codeslake

WORKAROUND_CATALOG.md

@@ -0,0 +1,149 @@
+# Workaround Catalog — Claude Code symptoms and known mitigations
+
+When a CC bug or surprising default hits a user, there are often several mitigation paths at different depths — a settings.json snippet, a CLI flag, an env var, a process wrapper, a proxy extension, a hook, a binary patch. This catalog indexes them by symptom so triage doesn't re-derive what's already known.
+
+**Source-of-truth discipline:** every row's "knob" string must be verbatim from a primary source (an upstream CC issue, a settings.json key reachable in the published extension docs, an env var verified in the shipped binary, a configuration setting present in the extension's `package.json`). Where the source is community-reported and we have not independently verified, the "Verified by" column says so.
+
+**Maintenance contract:** when we post on a CC issue OR ship a new proxy extension OR a community member reports a new workaround, the catalog row gets updated in the same change. Catalog drift starts at the moment a contributor stops doing this.
+
+**What this catalog is NOT:**
+
+- A list of every CC bug. That is `TRACKED_ISSUES.md`.
+- An endorsement of binary-patching tools. Binary patches are listed when they are the source of an originator's published workaround, with the depth column making the tradeoff explicit.
+- A pointer to non-CC tooling that modifies the CC binary or removes safety surfaces. We do not link such tools.
+
+---
+
+## Legend
+
+**Surface depth** — how invasive the mitigation is, lowest to highest:
+
+1. `settings.json` — User edits a known-supported VS Code or CC settings file.
+2. `cli-flag` — User adds a documented or hidden-but-supported flag to their CC invocation.
+3. `env-var` — User sets an environment variable.
+4. `process-wrapper` — User installs a script that wraps `claude` invocations (officially supported by `claudeCode.claudeProcessWrapper` in the VS Code extension).
+5. `proxy-extension` — User runs `cache-fix-proxy` with the relevant extension enabled.
+6. `hook` — User installs a CC hook script (PreToolUse / PostToolUse / SessionStart).
+7. `binary-patch` — User modifies the CC binary directly.
+8. `tool` — User runs a separate companion tool.
+
+**Survives CC update?** — whether the workaround keeps working after `npm install -g @anthropic-ai/claude-code` ships a new version.
+
+**Verified by** — `cache-fix-team` (we ran it), `originator` (we accepted the report but did not independently reproduce), or `community` (multiple independent confirmations on the upstream issue).
+
+**Recommendation** — `preferred` (the right starting point for most users), `narrow-use` (better for a subset), `community-reported` (we have not validated and do not recommend), `internal-only` (we use it; users probably should not).
+
+---
+
+## Catalog
+
+### CC#59844 — `showThinkingSummaries: true` silently no-ops on Opus 4.7 in non-interactive surfaces
+
+Upstream: https://github.com/anthropics/claude-code/issues/59844 — Open as of 2026-06-11.
+
+| Depth | Knob | Survives update? | Verified by | Recommendation |
+|---|---|---|---|---|
+| `process-wrapper` | `claudeCode.claudeProcessWrapper` setting + wrapper script that appends `--thinking-display summarized` when `--output-format` is present on the command line | Yes — patches nothing, just appends a flag | originator (claudio-felicioli, 2026-06-11) | `preferred` for VS Code extension users hitting this specific issue |
+| `proxy-extension` | `thinking-display` extension at order 360 in `proxy/extensions.json` (`enabled: true` by default in cache-fix-proxy v3.6.1+); injects `thinking.display: "summarized"` at the API boundary when a request has `thinking.type` in `{enabled, adaptive}` but `display` unset | Yes — proxy is separate from CC | cache-fix-team (shipped v3.6.1, 2026-05-17) | `preferred` for users already running cache-fix-proxy for the broader cache-stability surface |
+| `binary-patch` | Byte-patch the bundled CLI binary at offset 230510690 in the relevant CC version, replacing `!T6()&&` with 7 spaces. Length-preserving | No — offset shifts every CC release | originator (ojura, 2026-05-17) | `community-reported`; cited as empirical verification of the gate-drop fix, not as the deployment path. We do not deploy this. |
+
+**Authoritative fix Anthropic should ship** (per the issue body): pass `--thinking-display summarized` when `showThinkingSummaries` is `true`. Two voices on the thread for it (issue author + AI Team Lead 2026-06-11).
+
+---
+
+### CC#59628 — Worktree sessions can edit files in the parent main checkout with no guardrail
+
+Upstream: https://github.com/anthropics/claude-code/issues/59628 — Closed 2026-07-08 as `not_planned` by Anthropic. The workaround below is still applicable for users who want the guardrail; Anthropic will not ship a native fix.
+
+| Depth | Knob | Survives update? | Verified by | Recommendation |
+|---|---|---|---|---|
+| `hook` | Install `hooks/examples/worktree-edit-guard.py` as a `PreToolUse` hook; matcher `Edit\|Write\|MultiEdit\|NotebookEdit`; settings.json snippet in `docs/hooks/worktree-edit-guard.md` | Yes — hook contract is stable | cache-fix-team (shipped 2026-05-26 — `hooks/README.md`) | `preferred` for users with worktree-heavy workflows |
+
+---
+
+### CC#63147 — Resuming an extended-thinking session fails permanently with 400 "thinking blocks cannot be modified"
+
+Upstream: https://github.com/anthropics/claude-code/issues/63147 — Open as of 2026-06-11.
+
+| Depth | Knob | Survives update? | Verified by | Recommendation |
+|---|---|---|---|---|
+| `env-var` | `CLAUDE_CODE_DISABLE_THINKING=1` OR `MAX_THINKING_TOKENS=0` — both binary-confirmed to fully disable thinking | Yes — env-var contract is stable | cache-fix-team (binary inspection, see `playbook_heal_thinking_wedged_session`) | `narrow-use` — disables thinking entirely; lossy. Last resort for users who need session resume to work and don't need reasoning depth. |
+| `env-var` (negative — do not cite) | `DISABLE_INTERLEAVED_THINKING=1` or `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` | n/a | cache-fix-team (binary-verified NOT to stop the wedge) | Do NOT recommend; explicitly does not fix this symptom. The first only drops the interleaved beta; the second only adaptive-effort escalation. |
+| `proxy-extension` | `session-health` extension in cache-fix-proxy; detects and surfaces the wedge condition pre-API | Yes | cache-fix-team (shipped — see cache-fix #160) | `preferred` for users running cache-fix-proxy. |
+
+---
+
+### CC#62272 — Silent JSONL deletion despite `cleanupPeriodDays` set high (mechanism unresolved)
+
+Upstream: https://github.com/anthropics/claude-code/issues/62272 — Closed 2026-08-19 as duplicate of **#41458** (canonical tracker; follow that one). Related historical loss: #59248 (orphaned subagent/tool-results dirs).
+
+**Status of the theories on the thread — read this before citing anything below.**
+
+An earlier reading of gregmarkowitz-gif's 2026-08-31 report on the thread framed the mechanism as signed-int32 overflow of a days→ms cutoff. **That hypothesis has been retracted by the original reporter on 2026-09-01T15:42Z.** The kill argument is short: `2^31 - 1 ms ≈ 24.855 days`, so if a days→ms cutoff truly overflowed int32, the shipped default `cleanupPeriodDays: 30` would misbehave identically. The default doesn't misbehave for the general user base, so int32 overflow can't be the mechanism. Any earlier framing (including cache-fix-team's comment posted on the thread the same day) is superseded.
+
+**What is known on the thread as of 2026-09-01:**
+
+- **Version-specific.** Machine A on 2.1.252 lost files under `cleanupPeriodDays: 99999`. Machine B in the same org on 2.1.251 with the same setting lost none (714 transcripts intact back to 2026-08-01). Loss window narrows to 2.1.252+.
+- **Not simple age reap.** After the wipe on machine A, the busiest project directory held **exactly 25** top-level `.jsonl`, none older than 2026-08-31T18:48Z, while quieter project directories on the same box kept files from 2026-08-24 through 08-28. A global age reap takes the oldest first; here the oldest survived in quiet dirs and newer files in the busy dir died. Working hypothesis on the thread: **per-project-directory count cap (~25) applied to the busiest dir**. Not confirmed.
+- **Inverse pattern reported on WSL2** by dowdys on 2026-07-21: idle project directories deleted entirely (64 of 69), busy directories survived. Same directory axis, opposite sign. Possibly two mechanisms; possibly one mechanism keyed on "was this directory being written to at sweep time" with a sign that hasn't been pinned.
+- **Age-based cleanup does work at moderate settings on 2.1.252.** Canary on machine A at `cleanupPeriodDays: 365`: two synthetic `.jsonl` files backdated to −40d and −400d — next pass deleted the −400d file and spared the −40d file. So the setting itself honors age when it's in the sane range; the Aug-31 mass loss under 99999 is the anomaly to explain, and it isn't age.
+- **Sweep cadence on affected boxes is ~4 hours, not daily**, per the same reporter's `~/.claude/.last-cleanup` timeline on machine A (`12:16:17Z`, `16:16:17Z`, same seconds 4h apart). Docs describe daily.
+- **Blast radius is broader than `~/.claude/projects/`** per the WSL2 report: `file-history/` and paste-cache siblings were swept with the same cutoff. So any workaround that only snapshots `projects/` is partial.
+
+| Depth | Knob | Survives update? | Verified by | Recommendation |
+|---|---|---|---|---|
+| `settings.json` | `"cleanupPeriodDays": <sane value>` (default 30 or a smaller integer) in `~/.claude/settings.json` and any per-project `.claude/settings.json`. **Do NOT set 99999, 36500, or other "keep forever" placeholders on 2.1.252+.** Community-reported: they are the exact configurations under which the losses occurred. Note this is defensive-configuration only — it does not target the actual (unknown) mechanism. | Yes — the setting key is stable. | `community-reported` — several thread reporters on 2.1.252+ recovered stability by dropping to `365` or below. Mechanism still open on #41458. | `preferred` while the upstream fix is pending. |
+| `settings.json` | Downgrade to a CC version before 2.1.252 via `npm install -g @anthropic-ai/claude-code@2.1.251` (or earlier) and pin. | No — the point is to stay off the affected versions until the fix ships. | community-reported (machine B in the reporter's org on 2.1.251 + 99999 lost nothing). | `narrow-use` — trades this bug against every fix that shipped after 2.1.251. Only for users whose retention needs strictly exceed the sane-range cap and who can defer other CC updates. |
+| `tool` | Out-of-band snapshot of `~/.claude/` (not just `projects/` — include `file-history/`, `paste-cache/`, memory subdirs) to a filesystem the built-in cleanup does not walk. `rsync -a` with hardlink dedup between snapshots (or `cp --reflink` on Btrfs) is the durable-copy primitive; retention on the archive is orthogonal to whatever CC does. See `blain3white/clean-my-agent` on the thread for a shipped user-space implementation. | Yes — decoupled from CC entirely. | community-reported (`blain3white/clean-my-agent`); cache-fix-team runs an internal equivalent (hourly rsync to a Btrfs tier with 48h rotation). | `preferred` for users who need retention past whatever cap the mechanism turns out to be. This is the only workaround that survives if the mechanism turns out to be per-dir count cap or idle-dir removal rather than age. |
+
+**What the thread has NOT established:** the actual mechanism, the exact CC version boundary (some reports use `2.1.114`, some `2.1.252`), whether Windows/WSL2/Linux/macOS all share one bug or multiple, and whether `.last-cleanup`'s ~4h cadence is intentional. Reading the shipped binary for 2.1.252+ is the missing evidence.
+
+**Authoritative fix Anthropic should ship (from the thread):** the canonical tracker is #41458. Any workaround here is defensive; the upstream fix is theirs. Ship with the mechanism identified so users can distinguish "safe to leave setting high" from "safe to leave setting low" from "no configuration is safe."
+
+---
+
+### Cross-symptom — Post-update silent model remap (the Web Manager / April 17 pattern)
+
+Upstream: This is a behavior, not a single tracked issue. Mechanism credit: @fgrosswig binary analysis of CC v2.1.91 (privately shared 2026-05-09; methodology is public, findings are not NDA-scoped, credit Falk by name in any public artifact that uses these).
+
+| Depth | Knob | Survives update? | Verified by | Recommendation |
+|---|---|---|---|---|
+| `env-var` | `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP=1` | Yes | cache-fix-team (via @fgrosswig binary analysis, 2026-05-09) | `preferred` — single most impactful flag for users who pin model versions. |
+
+---
+
+## Process notes
+
+### Conventions for adding a row
+
+1. **Symptom heading must point at a real, currently-open CC issue.** If the issue is closed-as-not-planned by the stale-bot, link the refile (see TRACKED_ISSUES.md row for #43657 → #67497 as an example).
+2. **Knob field must be verbatim** from one of: (a) the upstream issue body, (b) the originator's reproduction, (c) the extension's `package.json`, (d) cache-fix-proxy source. Paraphrasing is not allowed; the field must be greppable.
+3. **Originator field credits whoever first published the workaround.** Don't claim originator status for the cache-fix team unless we genuinely originated it (e.g., the `thinking-display` proxy extension).
+4. **"Verified by" is honest about who actually tested it.** `cache-fix-team` means we ran it. `originator` means we accepted the report but did not independently reproduce. `community` means multiple independent confirmations on the upstream thread.
+5. **Recommendation field is operationally meaningful.** `preferred` means we point users here first. `narrow-use` means it has tradeoffs that make it wrong for the general population. `community-reported` means we are not vouching for it. `internal-only` means we run it but it has properties (proprietary, undisclosed, complex) that make it wrong to recommend.
+
+### When NOT to add a row
+
+- A binary patch that removes safety surfaces, telemetry, or refusal logic. We do not catalog binary patches whose effect is removing classifier or AUP enforcement, regardless of whether the upstream bug is real (see "What this catalog is NOT" above).
+- A workaround that requires modifying signed binaries without an explicit, narrow, length-preserving rationale (ojura's CC#59844 entry is on the edge; we list it because the entry is for empirical verification of a code-level fix, not for deployment).
+- A workaround that depends on a third-party fork. The forked binary's behavior is the fork's responsibility, not Anthropic's; cataloging would imply equivalence we cannot vouch for.
+- A workaround that is internal-only (e.g., `~/.claude/hooks/gh-bot-guard.sh` — our write-prefix guard for bot-identity discipline; not useful to general users).
+
+### Relationship to TRACKED_ISSUES.md
+
+- `TRACKED_ISSUES.md` is the index of CC issues we are monitoring, have commented on, or are directly relevant to our interceptor work.
+- `WORKAROUND_CATALOG.md` is the index of mitigation paths organized by symptom.
+- Most catalog symptoms point at a tracked issue. The reverse is not true: many tracked issues do not yet have an actionable workaround.
+- When we post on a CC issue or ship a new proxy extension, both files should be updated in the same change.
+
+---
+
+## Seeding inventory (initial draft, to be expanded)
+
+This is the seed for the catalog. Future additions are made by the contributor who discovers or posts on the issue, following the conventions above. Initial entries cover the highest-traffic surfaces:
+
+1. **CC#59844 / thinking-display** — three mitigations at three depths; the claudio-felicioli wrapper is the cleanest for VS Code extension users.
+2. **CC#59628 / worktree-edit-guard** — our shipped hook example.
+3. **CC#63147 / thinking-wedge** — env-var workarounds (lossy) + proxy `session-health` extension.
+4. **CC#62272 / cleanupPeriodDays silent JSONL loss (mechanism unresolved)** — closed as dupe of #41458. Defensive settings (`cleanupPeriodDays` at 365 or lower), pin to pre-2.1.252, and durable out-of-band snapshot are the three complementary paths; the int32-overflow theory from an earlier version of this entry has been retracted upstream.
+5. **Silent model remap (Web Manager pattern)** — `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP=1` env-var.