From b1ad3bcfc74ef1ea2b42ec57489c4d1d0dbae71f Mon Sep 17 00:00:00 2001
From: Affaan Mustafa <affaan@dcube.ai>
Date: Mon, 6 Apr 2026 14:12:21 -0700
Subject: [PATCH] docs: add canonical hook bug workaround guide

---
 docs/TROUBLESHOOTING.md      |  1 +
 docs/hook-bug-workarounds.md | 74 ++++++++++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 docs/hook-bug-workarounds.md

diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 5800c360..34af9624 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -69,6 +69,7 @@ exit 2
 
 ## Related ECC Docs
 
+- [hook-bug-workarounds.md](./hook-bug-workarounds.md) for the shorter hook/compaction/MCP recovery checklist.
 - [hooks/README.md](../hooks/README.md) for ECC's documented hook lifecycle and exit-code behavior.
 - [token-optimization.md](./token-optimization.md) for cost and context management settings.
 - [issue #644](https://github.com/affaan-m/everything-claude-code/issues/644) for the original report and tested environment.
diff --git a/docs/hook-bug-workarounds.md b/docs/hook-bug-workarounds.md
new file mode 100644
index 00000000..74f4dc60
--- /dev/null
+++ b/docs/hook-bug-workarounds.md
@@ -0,0 +1,74 @@
+# Hook Bug Workarounds
+
+Community-tested workarounds for current Claude Code bugs that can affect ECC hook-heavy setups.
+
+This page is intentionally narrow: it collects the highest-signal operational fixes from the longer troubleshooting surface without repeating speculative or unsupported configuration advice. These are upstream Claude Code behaviors, not ECC bugs.
+
+## When To Use This Page
+
+Use this page when you are specifically debugging:
+
+- false `Hook Error` labels on otherwise successful hook runs
+- earlier-than-expected compaction
+- MCP connectors that look authenticated but fail after compaction
+- hook edits that do not hot-reload
+- repeated `529 Overloaded` responses under heavy hook/tool pressure
+
+For the fuller ECC troubleshooting surface, use [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).
+
+## High-Signal Workarounds
+
+### False `Hook Error` labels
+
+What helps:
+
+- Consume stdin at the start of shell hooks (`input=$(cat)`).
+- Keep stdout quiet for simple allow/block hooks unless your hook explicitly requires structured stdout.
+- Send human-readable diagnostics to stderr.
+- Use the correct exit codes: `0` allow, `2` block, other non-zero values are treated as errors.
+
+```bash
+input=$(cat)
+echo "[BLOCKED] Reason here" >&2
+exit 2
+```
+
+### Earlier-than-expected compaction
+
+What helps:
+
+- Remove `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` if lowering it causes earlier compaction in your build.
+- Prefer manual `/compact` at natural task boundaries.
+- Use ECC's `strategic-compact` guidance instead of forcing a lower threshold.
+
+### MCP auth looks live but fails after compaction
+
+What helps:
+
+- Toggle the affected connector off and back on after compaction.
+- If your Claude Code build supports it, add a lightweight `PostCompact` reminder hook that tells you to re-check connector auth.
+- Treat this as a recovery reminder, not a permanent fix.
+
+### Hook edits do not hot-reload
+
+What helps:
+
+- Restart the Claude Code session after changing hooks.
+- Advanced users sometimes use shell-local reload helpers, but ECC does not ship one because those approaches are shell- and platform-dependent.
+
+### Repeated `529 Overloaded`
+
+What helps:
+
+- Reduce tool-definition pressure with `ENABLE_TOOL_SEARCH=auto:5` if your setup supports it.
+- Lower `MAX_THINKING_TOKENS` for routine work.
+- Route subagent work to a cheaper model such as `CLAUDE_CODE_SUBAGENT_MODEL=haiku` if your setup exposes that knob.
+- Disable unused MCP servers per project.
+- Compact manually at natural breakpoints instead of waiting for auto-compaction.
+
+## Related ECC Docs
+
+- [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
+- [token-optimization.md](./token-optimization.md)
+- [hooks/README.md](../hooks/README.md)
+- [issue #644](https://github.com/affaan-m/everything-claude-code/issues/644)