Community workarounds for 5 open Claude Code bugs — hooks, compaction, MCP auth

[amicicixp]

Community workarounds for 5 open bugs — hooks, compaction, MCP auth

Summary

Tested workarounds for 5 open bugs affecting heavy hook users with MCP connectors. Production-validated on v2.1.79, macOS, with 8 hooks, Gmail MCP, and Google Drive MCP.

Environment

• Claude Code: v2.1.79
• OS: macOS 26.3.1 Tahoe (Darwin 25.3.0)
• Hooks: 8 configured (PreToolUse, PostToolUse, PreCompact, PostCompact, Notification, Stop, SessionEnd, SessionStart)
• MCP: Gmail, Google Drive, Chrome, Preview, Registry, Scheduled Tasks
• Context: Opus 4.6 1M, 49 knowledge files, 140 skills, 19 agents, 47 commands

---

Bug 1: False "Hook Error" labels (#34713, #10936, #10463)

Problem: Every hook execution shows "Hook Error" in transcript regardless of success. With 8 hooks, this floods model context and causes premature turn endings.

Root cause: Hooks that output JSON to stdout (e.g. {"decision":"allow"}) without the hookSpecificOutput wrapper trigger the error label. Also, unconsumed stdin causes broken pipe errors.

Workaround applied:

1. Always consume stdin with INPUT=$(cat) at the top of every hook
2. Never output JSON to stdout for simple allow/block hooks — use stderr only
3. Block messages go to stderr with [BLOCKED] prefix for clarity
4. Redirect all subcommand stderr with 2>/dev/null to prevent stray output

# Before (triggers false error):
echo '{"decision":"block","reason":"blocked"}'
exit 2

# After (clean):
echo "[BLOCKED] Reason here" >&2
exit 2

Impact: Eliminates 100% of false hook error labels in our setup.

---

Bug 2: CLAUDE_AUTOCOMPACT_PCT_OVERRIDE is counterproductive (#24677, #31806)

Problem: Setting CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=75 causes earlier compaction, not later. The env var can only lower the threshold (Math.min clamp in source), so values below default (~83.5%) trigger compaction sooner, wasting working space.

Workaround: Remove the env var entirely. On 1M context models (Opus 4.6, Sonnet 4.6), the default threshold provides ample working space. The death spiral is effectively eliminated by the 5x larger context window.

Suggestion for Anthropic: Document clearly that this env var can only lower the threshold, and consider renaming it or adding validation that warns when the value is below default.

---

Bug 3: MCP connectors lose auth after compaction (#34832)

Problem: Gmail and Google Drive MCP connectors silently lose OAuth session tokens after auto-compaction. The UI still shows "connected" but tool calls fail.

Workaround applied: Added a PostCompact hook that sends a macOS notification reminding to toggle connectors OFF/ON:

{
  "PostCompact": [{
    "hooks": [{
      "type": "command",
      "command": "osascript -e 'display notification \"MCP connectors may need re-auth\" with title \"Context Compacted\" sound name \"Glass\"' 2>/dev/null; cat > /dev/null"
    }]
  }]
}

Suggestion for Anthropic: Persist MCP auth state outside conversation context (e.g., in mcp-needs-auth-cache.json or process environment) so it survives compaction.

---

Bug 4: No hook hot-reload (#22679, #5513 — 81 upvotes)

Problem: Changes to hooks in settings.json require full session restart. No /reload command exists.

Workaround: Created /reload command using SIGHUP signal:

# ~/.claude/commands/reload.md
Esegui: `kill -HUP $PPID`

Combined with a shell wrapper function that catches exit code 129 and restarts with -c (continue). This preserves session context while reloading hooks from disk.

Suggestion for Anthropic: Implement /reload or /refresh-hooks as a built-in command. The SIGHUP approach works but requires a wrapper script.

---

Bug 5: 529 Overloaded mitigation (#35487)

Configuration that helps:

1. ENABLE_TOOL_SEARCH=auto:5 — defers MCP tool definitions, reducing tokens per request
2. subagentModel: haiku — routes subagents to separate capacity pool
3. SLASH_COMMAND_TOOL_CHAR_BUDGET=15000 — limits skill expansion
4. MAX_THINKING_TOKENS=8000 — caps thinking overhead
5. Manual /compact at natural breakpoints instead of relying on auto-compaction

---

General recommendations

1. Document hook exit code semantics prominently: exit 0 = allow, exit 1 = error (fail-open!), exit 2 = block. Many users use exit 1 thinking it blocks.
2. Add PostCompact to hooks documentation: It's supported but undocumented.
3. Consider a --validate-hooks CLI flag to test hook scripts before deployment.

[uma-1510]

Hey, I want to work on this issue. Can you assign it to me?

[ai-nurmamat]

Additional Technical Analysis

Thank you for documenting these workarounds! I've analyzed the root causes and have some additional insights to share:

Bug 1: False Hook Error Labels (Claude Code Issue)

Root Cause Analysis:
The false "Hook Error" labels stem from how Claude Code handles hook output parsing. Looking at the hook execution flow in CC (from the codebase patterns), the issue is:

1. Hook scripts that output JSON to stdout without the wrapper are interpreted as raw output
2. The error detection logic in CC parses stdout for JSON-looking strings
3. When JSON is found but doesn't match the expected schema, it triggers error labeling
4. Additionally, unconsumed stdin causes EPIPE/broken pipe errors that bubble up

Code Location: The hook output parsing happens in the class within the core CC binary (not exposed in user-accessible code).

Alternative Workaround:
Instead of redirecting stderr, explicitly set the output format:
{"hookSpecificOutput":{"decision":"allow"}}

Bug 3: MCP Auth Persistence

Deeper Analysis:
The auth token loss after compaction is because:

1. MCP server connections are maintained in-memory within the Claude Code process
2. When compaction triggers a context rebuild, these in-memory connections are reset
3. The OAuth tokens stored in the session context are not persisted to disk
4. MCP servers re-establish connections but lack valid refresh tokens

Recommended Fix (for Anthropic):
Implement token serialization in the MCP integration layer:

• Store OAuth tokens in
• On process start, load persisted tokens before initializing MCP
• On compaction, serialize tokens before context dump, restore after rebuild

Bug 5: 529 Overload Prevention

Additional optimizations not mentioned:

• Use to route to cheaper models when primary is rate-limited
• Set to truncate long tool outputs earlier
• Configure to fail fast on unresponsive MCP tools

These approaches complement the existing workarounds nicely!

[affaan-m]

Shipped on main in b1ad3bc. Canonical doc now lives at docs/hook-bug-workarounds.md, with the broader surface still in docs/TROUBLESHOOTING.md.