<h2 id="table-of-contents">Table of contents</h2>
<ul>
<li><a href="#claude-code-hooks">Claude Code hooks</a></li>
<li><a href="#how-hooks-work">How hooks work</a></li>
<li><a href="#blocking-destructive-commands">Blocking destructive commands</a></li>
<li><a href="#protecting-sensitive-files">Protecting sensitive files</a></li>
<li><a href="#audit-trail">Audit trail</a></li>
<li><a href="#wiring-it-up">Wiring it up</a></li>
<li><a href="#prompt-injection-defense">Prompt injection defense</a></li>
<li><a href="#why-global-config-not-per-repo">Why global config, not per-repo</a></li>
<li><a href="#same-idea-different-tools">Same idea, different tools</a></li>
</ul>
<h1 id="claude-code-hooks">Claude Code hooks</h1>
<p>Claude Code runs shell commands, reads files, and edits code
on your machine. Hooks let you intercept those actions with
shell scripts that run before or after each tool call. The
scripts get JSON on stdin describing what Claude is about to
do, and they can block it by exiting with code 2.</p>
<p>I set up three hooks: one that blocks destructive commands,
one that blocks access to sensitive files, and one that logs
everything to a JSONL audit trail.</p>
<h1 id="how-hooks-work">How hooks work</h1>
<p>A hook is a shell script registered in
<code>~/.claude/settings.json</code>. There are two lifecycle events:</p>
<ul>
<li><strong>PreToolUse</strong>: runs before Claude executes a tool. Exit 0
to allow, exit 2 to block. The block message goes to stderr.</li>
<li><strong>PostToolUse</strong>: runs after. Good for logging. Can run async
so it doesn't slow things down.</li>
</ul>
<p>Each hook gets a JSON object on stdin with <code>tool_name</code>,
<code>tool_input</code>, <code>session_id</code>, and <code>cwd</code>. You can use <code>jq</code> to
pull out whatever you need.</p>
<p>A <code>matcher</code> field controls which tools trigger the hook. It
takes a regex, so <code>Bash</code> matches only the Bash tool while
<code>Read|Edit|Write|Bash</code> matches all four.</p>
<h1 id="blocking-destructive-commands">Blocking destructive commands</h1>
<p>This one intercepts every Bash tool call and blocks anything
that could wreck the system.</p>
<pre><code class="language-bash">#!/usr/bin/env bash
# ~/.claude/hooks/block-destructive.sh
# PreToolUse hook, matcher: Bash

set -euo pipefail

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [[ -z "$COMMAND" ]]; then
  exit 0
fi

BLOCKED=""

case "$COMMAND" in
  *"rm -rf /"*|*"rm -rf ~"*)
    BLOCKED="recursive delete of root or home" ;;
  *"git push --force"*|*"git push -f "*)
    BLOCKED="force push" ;;
  *"git reset --hard"*)
    BLOCKED="hard reset" ;;
  *"DROP TABLE"*|*"DROP DATABASE"*)
    BLOCKED="database drop" ;;
  *":(){ :|:&#x26; };:"*)
    BLOCKED="fork bomb" ;;
  *"curl"*"|"*"sh"*|*"curl"*"|"*"bash"*)
    BLOCKED="piped remote execution" ;;
  *"chmod 777"*)
    BLOCKED="world-writable permissions" ;;
  *"mkfs."*)
    BLOCKED="filesystem format" ;;
esac

# Check dd writing to /dev/
if [[ -z "$BLOCKED" ]] &#x26;&#x26; echo "$COMMAND" | \
   grep -qE 'dd\s+if=.*of=/dev/'; then
  BLOCKED="raw device write"
fi

if [[ -n "$BLOCKED" ]]; then
  echo "BLOCKED by block-destructive hook: $BLOCKED" >&#x26;2
  exit 2
fi

exit 0
</code></pre>
<p>Testing it:</p>
<pre><code class="language-bash">$ echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' \
  | ~/.claude/hooks/block-destructive.sh
BLOCKED by block-destructive hook: recursive delete of root or home
# exit code: 2

$ echo '{"tool_name":"Bash","tool_input":{"command":"git push --force origin main"}}' \
  | ~/.claude/hooks/block-destructive.sh
BLOCKED by block-destructive hook: force push
# exit code: 2

$ echo '{"tool_name":"Bash","tool_input":{"command":"ls -la"}}' \
  | ~/.claude/hooks/block-destructive.sh
# exit code: 0  (allowed)
</code></pre>
<p>When Claude tries a blocked command, it sees the stderr
message and knows the action was rejected. It can then
rephrase or ask for confirmation.</p>
<h1 id="protecting-sensitive-files">Protecting sensitive files</h1>
<p>The second hook blocks access to credentials, SSH keys, and
cloud configs. It handles both file-path tools (Read, Edit,
Write) and Bash commands that might <code>cat</code> or exfiltrate
those files.</p>
<pre><code class="language-bash">#!/usr/bin/env bash
# ~/.claude/hooks/protect-sensitive.sh
# PreToolUse hook, matcher: Read|Edit|Write|Bash

set -euo pipefail

INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')

check_path() {
  local filepath="$1"
  case "$filepath" in
    */.env|*/.env.*|*.env)
      echo "BLOCKED by protect-sensitive hook: .env file" >&#x26;2
      exit 2 ;;
    */.ssh/id_*)
      echo "BLOCKED by protect-sensitive hook: SSH key" >&#x26;2
      exit 2 ;;
    */.aws/credentials*)
      echo "BLOCKED by protect-sensitive hook: AWS creds" >&#x26;2
      exit 2 ;;
    */.kube/config*)
      echo "BLOCKED by protect-sensitive hook: kubeconfig" >&#x26;2
      exit 2 ;;
  esac
}

if [[ "$TOOL" == "Bash" ]]; then
  COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
  if echo "$COMMAND" | \
     grep -qE '(cat|less|head|tail|curl -d @|base64|scp)\s+\.env'; then
    echo "BLOCKED by protect-sensitive hook: .env access via bash" >&#x26;2
    exit 2
  fi
  if echo "$COMMAND" | \
     grep -qE '(cat|less|head|tail)\s+.*(\.ssh/id_|\.aws/credentials|\.kube/config)'; then
    echo "BLOCKED by protect-sensitive hook: sensitive file access via bash" >&#x26;2
    exit 2
  fi
else
  FILEPATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
  if [[ -n "$FILEPATH" ]]; then
    check_path "$FILEPATH"
  fi
fi

exit 0
</code></pre>
<pre><code class="language-bash">$ echo '{"tool_name":"Read","tool_input":{"file_path":"/home/user/.ssh/id_ed25519"}}' \
  | ~/.claude/hooks/protect-sensitive.sh
BLOCKED by protect-sensitive hook: SSH key
# exit code: 2

$ echo '{"tool_name":"Bash","tool_input":{"command":"cat .env"}}' \
  | ~/.claude/hooks/protect-sensitive.sh
BLOCKED by protect-sensitive hook: .env access via bash
# exit code: 2
</code></pre>
<p>This isn't foolproof. Claude could read a sensitive file
by some path I didn't think of. But it catches the obvious
cases and raises the bar.</p>
<h1 id="audit-trail">Audit trail</h1>
<p>The third hook runs after every tool call and appends a JSON
line to a log file. It runs async so it doesn't slow Claude
down.</p>
<pre><code class="language-bash">#!/usr/bin/env bash
# ~/.claude/hooks/audit-log.sh
# PostToolUse hook, async

LOG="/Users/kp/gh/multi/logs/claude-audit.jsonl"

INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
SESSION=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
CWD=$(echo "$INPUT" | jq -r '.cwd // "unknown"')

case "$TOOL" in
  Bash)
    PARAM=$(echo "$INPUT" | jq -r '.tool_input.command // empty') ;;
  Read|Edit|Write)
    PARAM=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty') ;;
  *)
    PARAM="" ;;
esac

jq -nc \
  --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --arg sid "$SESSION" \
  --arg tool "$TOOL" \
  --arg param "$PARAM" \
  --arg cwd "$CWD" \
  '{timestamp: $ts, session_id: $sid, tool: $tool, param: $param, cwd: $cwd}' \
  >> "$LOG"

exit 0
</code></pre>
<p>After a session, the log looks like:</p>
<pre><code class="language-json">{"timestamp":"2026-03-11T13:14:18Z","session_id":"abc123","tool":"Bash","param":"echo hello","cwd":"/Users/kp/gh/multi"}
</code></pre>
<p>You could pipe this into whatever alerting or analysis you
want. I'm keeping it simple for now, just a file on disk.</p>
<p>The end goal is to use this log to build something like
<a href="https://github.com/ldayton/Dippy">Dippy</a>, a smart
auto-approve hook. Dippy parses bash commands with an AST
and auto-approves safe ones while still prompting for
anything destructive. I want to do the same thing but
trained on my own audit trail, so the approve/deny decisions
reflect how I actually work. That's a future post.</p>
<h1 id="wiring-it-up">Wiring it up</h1>
<p>All three hooks go in <code>~/.claude/settings.json</code> under a
<code>hooks</code> key:</p>
<pre><code class="language-json">{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "/Users/kp/.claude/hooks/block-destructive.sh"
        }]
      },
      {
        "matcher": "Read|Edit|Write|Bash",
        "hooks": [{
          "type": "command",
          "command": "/Users/kp/.claude/hooks/protect-sensitive.sh"
        }]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [{
          "type": "command",
          "command": "/Users/kp/.claude/hooks/audit-log.sh",
          "async": true
        }]
      }
    ]
  }
}
</code></pre>
<p>Use absolute paths, not <code>~</code>. JSON doesn't expand tilde.</p>
<p>The <code>async: true</code> on the audit hook means Claude doesn't
wait for it to finish before moving on. Logging shouldn't
slow down the workflow.</p>
<p>For a full reference of <code>settings.json</code> options, slash
commands, and CLI flags, the
<a href="/claude-code-cheat-sheet.html">Claude Code CLI Cheat-Sheet</a>
covers all of it.</p>
<h1 id="prompt-injection-defense">Prompt injection defense</h1>
<p>One thing I haven't built yet but plan to: a PostToolUse
hook that scans tool output for prompt injection attempts.</p>
<p>The idea is to grep the output for patterns like "ignore
previous instructions" or "you are now in admin mode" and
flag them. This matters most for tools that ingest external
data. If Claude is reading web pages, parsing documents,
or pulling content from APIs, a malicious payload in that
content could try to hijack the session.</p>
<p>Lasso Security published a
<a href="https://www.lasso.security/blog/prompt-injection-taxonomy-techniques">prompt injection taxonomy</a>
cataloging these techniques: encoding, obfuscation,
role-playing, context manipulation, and more. A PostToolUse
hook is the right place to catch
them because you see the actual content before Claude acts
on it.</p>
<p>I'll cover this in a future post once I have it running on
real workloads.</p>
<h1 id="why-global-config-not-per-repo">Why global config, not per-repo</h1>
<p>Claude Code hooks can be configured at three levels:</p>
<ul>
<li><code>~/.claude/settings.json</code> (global, user-level)</li>
<li><code>.claude/settings.json</code> (per-repo, checked into git)</li>
<li><code>.claude/settings.local.json</code> (per-repo, gitignored)</li>
</ul>
<p>Safety hooks belong in global config. If they're per-repo,
a malicious repository can ship its own <code>.claude/settings.json</code>
that disables your protections or adds hooks that exfiltrate
data. You clone it, run Claude Code, and the repo's hooks
run instead of yours.</p>
<p>This is a real attack vector. In 2025, Check Point Research
found
<a href="https://research.checkpoint.com/2026/rce-and-api-token-exfiltration-through-claude-code-project-files-cve-2025-59536/">CVE-2025-59536</a>:
an attacker plants a <code>.claude/settings.json</code> with hooks in
a repo. You clone it, run Claude Code, approve the trust
dialog (which doesn't mention hooks), and the hook commands
execute immediately. Reverse shell, data exfiltration,
whatever the attacker wants. Anthropic patched it in August
2025, but the lesson stands: keep safety hooks in global
config where only you control them.</p>
<h1 id="same-idea-different-tools">Same idea, different tools</h1>
<p>Claude Code isn't the only AI coding tool with hook support.
Here's how the same concepts map elsewhere.</p>
<table>
<thead>
<tr>
<th>Feature</th>
<th>Claude Code</th>
<th>Cursor</th>
</tr>
</thead>
<tbody>
<tr>
<td>Hook format</td>
<td>Shell scripts</td>
<td>Shell scripts</td>
</tr>
<tr>
<td>Config</td>
<td><code>~/.claude/settings.json</code></td>
<td><code>.cursor/hooks.json</code></td>
</tr>
<tr>
<td>Events</td>
<td><code>PreToolUse</code>, <code>PostToolUse</code></td>
<td><code>preToolUse</code>, <code>postToolUse</code></td>
</tr>
<tr>
<td>Input</td>
<td>JSON on stdin</td>
<td>JSON on stdin</td>
</tr>
<tr>
<td>Block mechanism</td>
<td>Exit code 2 + stderr</td>
<td>Exit code 2 + stderr</td>
</tr>
<tr>
<td>Async support</td>
<td><code>"async": true</code></td>
<td>Not documented</td>
</tr>
</tbody>
</table>
<p>Cursor added hooks in version 1.7 (October 2025) with a
nearly identical model: shell scripts, JSON stdin, exit
codes. It also supports a "prompt" handler type where an
LLM evaluates a natural language condition to allow or deny,
which is interesting but slower. The same shell scripts
could work in both tools with minor config changes.</p>
<p>OpenCode takes a different approach. Instead of shell
scripts, it uses JavaScript or TypeScript plugins placed in
<code>.opencode/plugins/</code> or <code>~/.config/opencode/plugins/</code>. You
register functions on events like <code>tool.execute.before</code> and
<code>tool.execute.after</code>. More powerful (you get full access to
the session and project context), but less portable than a
shell script you can reuse across tools.</p>


Kyle Pericak

"It works in my environment"

Categories

Tags