docs: add canonical hook bug workaround guide

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.

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)