adaptationio/ac-hooks-manager

AC Hooks Manager

Hook installation and management for enabling autonomous operation.

Overview

Manages all Claude Code hooks for autonomous operation:

• Stop Hook: Enables autonomous continuation
• PreToolUse Hook: Security validation
• PostToolUse Hook: Result processing
• SessionStart/End Hooks: State management

Quick Start

Install Autonomous Hooks

from scripts.hooks_manager import HooksManager

hooks = HooksManager(project_dir)
await hooks.install_autonomous_hooks()
# Installs Stop hook for autonomous continuation

Check Hook Status

status = await hooks.get_status()
print(f"Stop hook: {'installed' if status.stop_hook else 'missing'}")

The Stop Hook (Core Innovation)

The Stop hook enables autonomous continuation by intercepting Claude Code's stop event:

Claude Code completes response
    │
    ▼ (Stop event fires)

Stop Hook Script
    ├─ Read transcript
    ├─ Check safety limits
    ├─ Call Opus analyzer
    └─ Return decision
    │
    ├─ CONTINUE: block stop, inject next task
    └─ COMPLETE: allow stop, terminate

How It Works

1. Claude Code finishes a response
2. Stop event fires (hook receives JSON input)
3. Hook script executes:
   • Checks stop_hook_active (prevents infinite loops)
   • Checks iteration/cost limits
   • Calls Opus analyzer for decision
4. Decision returned:
   • CONTINUE: Exit code 2 + reason → Claude continues
   • COMPLETE: Exit code 0 → Claude stops

Stop Hook Input

{
  "session_id": "abc123",
  "transcript_path": "/path/to/conversation.jsonl",
  "cwd": "/current/working/directory",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": false
}

Critical Field: stop_hook_active

• false: First time hook firing (proceed with analysis)
• true: Hook already blocked once (allow stop to prevent doom loop)

Stop Hook Output

To Continue:

{
  "decision": "block",
  "reason": "Next task: implement the login endpoint"
}

Exit code: 2

To Stop:

{
  "decision": "approve"
}

Exit code: 0

Hook Configuration

.claude/settings.json

{
  "hooks": {
    "Stop": [{
      "matcher": {},
      "hooks": [{
        "type": "command",
        "command": ".claude/skills/ac-hooks-manager/scripts/autonomous-loop.sh"
      }],
      "timeout": 120
    }],
    "PreToolUse": [{
      "tools": ["Bash"],
      "hooks": [{
        "type": "command",
        "command": ".claude/skills/ac-security-sandbox/scripts/validate.sh"
      }]
    }],
    "PostToolUse": [{
      "tools": ["Write", "Edit"],
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write \"$FILE\""
      }]
    }]
  }
}

Hook Types

1. Stop Hook (Autonomous Continuation)

await hooks.install_stop_hook(
    script_path=".claude/skills/ac-hooks-manager/scripts/autonomous-loop.sh",
    timeout=120
)

2. PreToolUse Hook (Security)

await hooks.install_pre_tool_hook(
    tools=["Bash"],
    script_path=".claude/skills/ac-security-sandbox/scripts/validate.sh"
)

3. PostToolUse Hook (Formatting)

await hooks.install_post_tool_hook(
    tools=["Write", "Edit"],
    command="npx prettier --write \"$FILE\""
)

4. Session Hooks

await hooks.install_session_hooks(
    on_start=".claude/hooks/load-memory.sh",
    on_end=".claude/hooks/save-memory.sh"
)

Operations

1. Install All Autonomous Hooks

await hooks.install_autonomous_hooks()
# Installs:
#   - Stop hook (continuation)
#   - PreToolUse hook (security)
#   - Session hooks (memory)

2. Install Specific Hook

await hooks.install_hook(
    event="Stop",
    config={
        "type": "command",
        "command": "path/to/script.sh"
    },
    timeout=120
)

3. Remove Hook

await hooks.remove_hook(event="Stop")

4. Check Status

status = await hooks.get_status()
# Returns:
#   stop_hook: bool
#   pre_tool_hooks: list
#   post_tool_hooks: list
#   session_hooks: dict

5. Validate Hooks

errors = await hooks.validate()
if errors:
    for error in errors:
        print(f"Hook error: {error}")

Autonomous Loop Script

scripts/autonomous-loop.sh

#!/bin/bash

# Read input from stdin
INPUT=$(cat)

# Extract fields
STOP_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active')
TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path')
CWD=$(echo "$INPUT" | jq -r '.cwd')

# Safety check: prevent doom loops
if [ "$STOP_ACTIVE" == "true" ]; then
    echo '{"decision": "approve"}'
    exit 0
fi

# Load state
STATE_FILE="$CWD/.claude/autonomous-state.json"
if [ -f "$STATE_FILE" ]; then
    ITERATION=$(jq -r '.iteration' "$STATE_FILE")
    COST=$(jq -r '.estimated_cost' "$STATE_FILE")
else
    ITERATION=0
    COST=0
fi

# Check limits
MAX_ITERATIONS=50
MAX_COST=20.00

if [ "$ITERATION" -ge "$MAX_ITERATIONS" ]; then
    echo '{"decision": "approve"}'
    exit 0
fi

if (( $(echo "$COST > $MAX_COST" | bc -l) )); then
    echo '{"decision": "approve"}'
    exit 0
fi

# Call Opus analyzer (see ac-opus-analyzer skill)
DECISION=$(python3 "$CWD/.claude/skills/ac-hooks-manager/scripts/analyze.py" \
    --transcript "$TRANSCRIPT" \
    --iteration "$ITERATION")

# Return decision
echo "$DECISION"
exit $(echo "$DECISION" | jq -r 'if .decision == "block" then 2 else 0 end')

Safety Mechanisms

1. Doom Loop Prevention

if [ "$STOP_ACTIVE" == "true" ]; then
    exit 0  # Allow stop
fi

2. Iteration Limits

if [ "$ITERATION" -ge "$MAX_ITERATIONS" ]; then
    exit 0  # Allow stop
fi

3. Cost Limits

if (( $(echo "$COST > $MAX_COST" | bc -l) )); then
    exit 0  # Allow stop
fi

4. Failure Detection

FAILURES=$(jq -r '.consecutive_failures' "$STATE_FILE")
if [ "$FAILURES" -ge 3 ]; then
    exit 0  # Allow stop, escalate
fi

Integration Points

• ac-session-manager: Triggers hooks
• ac-security-sandbox: PreToolUse validation
• ac-opus-analyzer: Decision making
• ac-state-tracker: State persistence
• ac-config-manager: Hook configuration

References

• references/HOOK-MECHANICS.md - Detailed hook behavior
• references/STOP-HOOK.md - Stop hook deep dive
• references/SAFETY.md - Safety mechanisms

Scripts

• scripts/hooks_manager.py - Core HooksManager
• scripts/autonomous-loop.sh - Stop hook handler
• scripts/analyze.py - Opus analyzer wrapper
• scripts/hook_installer.py - Hook installation