# Hooks

Claude Code hooks are shell scripts or HTTP endpoints that run
before or after tool execution. They are the primary security
mechanism for Claude Code, equivalent to OpenClaw's exec approvals
and Docker sandboxing.

## Files in this directory

| File | Hook event | Purpose |
|------|-----------|---------|
| `pre-tool-use.sh` | PreToolUse | Blocks dangerous shell commands |
| `post-tool-use.sh` | PostToolUse | Logs all tool executions |
| `audit.log` | (generated) | Append-only audit trail |

## How hooks work

Hooks are configured in `.claude/settings.json`:

```json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "bash hooks/pre-tool-use.sh"
      }]
    }]
  }
}
```

### PreToolUse

Runs before a tool executes. The script receives JSON on stdin
with `tool_name` and `tool_input`. Return decisions:

- Exit 0: allow (no output needed)
- Exit 2 + JSON `{"decision": "block", "reason": "..."}`: block the tool call

### PostToolUse

Runs after a tool executes. Same stdin format plus `tool_output`.
Cannot block (already executed). Use for logging, notifications,
or triggering follow-up actions.

### Other hook events

Claude Code supports these additional events:

| Event | When it fires |
|-------|--------------|
| SessionStart | When Claude Code launches |
| SessionEnd | When the session closes |
| Stop | When Claude Code finishes a response |
| SubagentStop | When a subagent completes |
| UserPromptSubmit | Before processing user input |
| PreCompact | Before context compaction |
| Notification | When Claude Code shows a notification |

## Comparison to OpenClaw

| Feature | OpenClaw | Claude Code |
|---------|----------|-------------|
| Exec blocking | /approve command + DM pairing | PreToolUse hooks |
| Audit logging | command-logger hook | PostToolUse hooks |
| Tool deny lists | Per-session/agent config | disallowedTools + settings.json deny |
| Container isolation | Docker sandbox (off/non-main/all) | macOS sandbox-exec |
| Policy engine | NemoClaw YAML policies | Hook scripts (any logic) |
| HTTP webhooks | Built-in webhook system | HTTP hooks (POST JSON to URL) |

Claude Code hooks are more flexible (arbitrary shell logic) but
require more setup. OpenClaw's approach is more structured but
less customizable.