The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs: add canonical hook bug workaround guide
Affaan Mustafab1ad3bcfc74e
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.mdindex 5800c3603..34af96246 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.mdnew file mode 100644index 000000000..74f4dc607--- /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)