PreToolUse Hook Success Causes Agent Freeze in VS Code Extension (Not Terminal)

PreToolUse Hook Success Causes Agent Freeze in VS Code Extension (Not Terminal)

Environment

• Claude Code Version: 2.0.42 (VS Code extension)
• VS Code Version: [Auto-detected]
• Model: Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• OS: macOS (Darwin 24.6.0)
• Date: 2025-11-17

Summary

When a PreToolUse hook successfully returns {"continue": true}, the Claude Code VS Code extension displays a misleading system reminder ("PreToolUse:Edit hook stopped continuation: Execution stopped by hook") and the agent freezes for extended periods (20+ minutes) despite the tool operation succeeding. This bug does NOT occur in Claude Code terminal - only in the VS Code extension.

Critical Finding

• ✅ Terminal Claude Code: No freeze, agent continues immediately
• ❌ VS Code Extension: Agent freezes for 24+ minutes after successful hook execution

Steps to Reproduce

1. Setup Hook

Create ~/.claude/hooks/pre_infrastructure_modification_check.sh:

#!/bin/bash
set -euo pipefail

HOOK_INPUT=$(cat)
TOOL_NAME=$(echo "$HOOK_INPUT" | jq -r '.tool_name // empty')
FILE_PATH=$(echo "$HOOK_INPUT" | jq -r '.tool_input.file_path // empty')

# Only check ~/.claude/ files
if [[ ! "$FILE_PATH" =~ ^/Users/[^/]+/\.claude/ ]]; then
    echo '{"continue": true}'
    exit 0
fi

# Check for uncommitted changes
cd "$HOME/.claude"
UNCOMMITTED=$(git status --porcelain 2>/dev/null || echo "")

if [[ -n "$UNCOMMITTED" ]]; then
    ERROR_MSG="Uncommitted changes detected in ~/.claude - commit and push before modifying"
    echo "{\"continue\": false, \"systemMessage\": \"$ERROR_MSG\"}"
    exit 0
fi

# Success - allow modification
echo '{"continue": true}'
exit 0

2. Register Hook in ~/.claude/settings.local.json

{
  "hooks": {
    "preToolUse": [
      {
        "matcher": "tools:Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/pre_infrastructure_modification_check.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

3. Trigger Bug in VS Code Extension

Open Claude Code in VS Code extension and run:

FREEZE BUG TEST

Please do these 3 steps WITHOUT PAUSING:

1. Edit /Users/emanuelfarruda/.claude/CLAUDE.md - add this comment at line 1:
   <!-- Freeze test [current timestamp] -->

2. Run: cd ~/.claude && git status

3. Run: ls -lh ~/.claude/hooks/

Complete all 3 steps immediately. Do NOT wait for my input between steps.

4. Compare with Terminal

Run the EXACT same test in Claude Code terminal (not VS Code extension).

Expected Behavior

After the Edit succeeds and hook returns {"continue": true}:

1. Agent immediately continues to step 2 (git status)
2. Agent immediately continues to step 3 (ls -lh)
3. Total time: <30 seconds

Actual Behavior (VS Code Extension Only)

Timeline from session b2e60a57-0225-457c-a596-00ac00391a23:

2025-11-17T20:10:40.967Z - Edit tool_use sent
2025-11-17T20:10:51.440Z - tool_result received (Edit succeeded)
2025-11-17T20:35:19.567Z - User manually opened file in IDE (24.5 MINUTE GAP)

What happens:

1. Edit succeeds (tool_result shows clean success)
2. Hook returns {"continue": true} (verified in logs)
3. System reminder appears: "PreToolUse:Edit hook stopped continuation: Execution stopped by hook"
4. Agent freezes for 24+ minutes
5. User must manually prompt "are you stuck?" or "continue" to restart
6. Agent then completes remaining steps immediately

Terminal behavior (NO FREEZE):

• Same test, same hook, same configuration
• Agent continues immediately after Edit
• All 3 steps complete in ~5 seconds

Evidence

Session Files

• VS Code freeze: /Users/emanuelfarruda/.claude/projects/-Users-emanuelfarruda/b2e60a57-0225-457c-a596-00ac00391a23.jsonl
• Terminal no-freeze: Confirmed via terminal test (2025-11-17)

Hook Logs

Hook successfully returns {"continue": true}:

[2025-11-17 15:04:41] All checks passed - allowing modification

System Reminder (Misleading)

Despite hook returning {"continue": true}, system shows:

PreToolUse:Edit hook stopped continuation: Execution stopped by hook

This message is misleading - the hook did NOT stop continuation, it explicitly allowed it.

Root Cause Hypothesis

The system reminder message uses stop-oriented language ("stopped continuation", "Execution stopped") that appears even when the hook returns {"continue": true}. This creates a contradiction:

Hook returns: {"continue": true} ✅
System message says: "stopped continuation" ❌

The VS Code extension agent appears to misinterpret this system message as an instruction to halt, despite the hook's actual return value saying to continue.

Why terminal doesn't freeze: Terminal version may handle hooks differently or not show the misleading system reminder, preventing the misinterpretation.

Impact

• Severity: High - Blocks agent for 20+ minutes
• Frequency: Intermittent (appears to occur in fresh VS Code sessions more than long-running sessions)
• Workaround: Use terminal Claude Code instead of VS Code extension
• Scope: Any PreToolUse hook that returns {"continue": true} on ~/.claude/ file modifications

Suggested Fix

1. System Reminder Accuracy: Change system reminder to reflect actual hook outcome:

• If {"continue": true} → "PreToolUse hook allowed continuation"
• If {"continue": false} → "PreToolUse hook blocked continuation"

1. VS Code Extension Hook Handling: Fix VS Code extension to check hook return value instead of relying on system message text

1. Agent Instructions: Add explicit guidance: "When you see 'hook stopped continuation', check the actual tool_result. If tool succeeded, CONTINUE immediately regardless of system message wording."

Additional Context

This bug was discovered during investigation of why agents were freezing after infrastructure file modifications. The issue persisted across:

• Multiple test sessions
• Both Sonnet 4.5 and Haiku 4.5 models (though Sonnet appears more susceptible)
• Fresh and long-running sessions

The critical finding: Exact same test, exact same hook, VS Code extension freezes, terminal does not.

Related

• Hook file: /Users/emanuelfarruda/.claude/hooks/pre_infrastructure_modification_check.sh
• Settings: /Users/emanuelfarruda/.claude/settings.local.json
• First observed: 2025-11-16 01:57:47Z (4.5 hours after hook creation)