---
title: "Claude Code PreToolUse hook: Block unsafe tool calls securely"
description: "Learn how to use the Claude Code PreToolUse hook to intercept and block unsafe tool calls. Implement custom security guardrails for your workflows today."
---

# Claude Code PreToolUse hook: Block unsafe tool calls securely

Published: 2026-09-11T02:07:07.304Z

Author: [Goon Nguyen](/author/goon)

Reading time: 15 minutes

Learn how to use the Claude Code PreToolUse hook to intercept and block unsafe tool calls. Implement custom security guardrails for your workflows today.

# Claude Code PreToolUse hook: How to block unsafe tool calls

A Claude Code PreToolUse hook acts as a filter, blocking tool calls immediately after Claude chooses an action and before the tool runs. It lets you apply local validation rules to risks such as `.env` access, destructive Bash commands, or a direct `git push`. The handler receives JSON describing the proposed call, evaluates it against the repository policy, and returns a documented decision. This guide covers lifecycle placement, configuration, a Node.js policy handler, testing, and limitations. The hook is a useful guardrail, but it is not an operating-system sandbox.

![Image](https://cdn.agentkit.best/blog/cfai-media/8a4a42bf05534e0402a9a4be515b430215e1727426917ca9d59880460adb3164-a7fbffaf4a778f51e8c9ec119d9bf7ecb4c44cb6c9df24462de53c175f7b4e4d.jpg)

> **Quick answer:** A Claude Code `PreToolUse` hook is a programmable checkpoint for tool-call interception. It examines a matched tool’s name and inputs before execution, then allows, denies, or routes the action through a supported permission path. Its protection remains limited by matcher coverage, handler quality, credentials, and process privileges.

## What is a Claude Code PreToolUse hook?

`PreToolUse` is a Claude Code hook event that runs when Claude proposes a call to a matched tool. The [hook](https://agentkit.best/blog/claude-code-guides/claude-code-hooks-guide-automate-and-control-ai-workflows) can inspect tool-specific arguments before Claude Code applies the documented decision and proceeds with execution.

For example, Claude may propose `git push origin main` through the `Bash` tool. A Bash matcher invokes your handler, which reads the command and rejects it with an explicit reason. The underlying Git command does not execute through that permitted path.

Using a Claude Code PreToolUse hook provides stronger security than relying only on instructions in CLAUDE.md. While prompt guidance is merely suggestive, the hook enforces policy through code at a defined lifecycle boundary.

However, deterministic enforcement only applies to the configured hook boundary. An incomplete matcher, vulnerable validation logic, alternate tool, or privileged execution environment can still expose the repository.

### Where PreToolUse runs in the tool lifecycle

![Image](https://cdn.agentkit.best/blog/cfai-media/d27b4db02a2303bdc2b5400509d7c6e84b1d78f4603a20855e5382d535175d82-80a88d4067d7181ac55ba7b6de5402f022c527516740925e915622ab871bd027.jpg)

### Why PreToolUse is more reliable than prompt-only rules

`CLAUDE.md` remains valuable for conventions, such as preferred test commands or architectural rules. The hook is more appropriate when a specific command, path, branch, or environment requires programmatic tool execution control.

Its effectiveness still depends on narrow matchers, correct handler logic, protected configuration, process privileges, and complete execution-path coverage. Treat Claude Code hooks as one layer in a defense-in-depth security model.

## How PreToolUse receives and controls tool calls

Claude Code sends hook data to a command handler as JSON through standard input. The handler parses that data, validates the relevant fields, and communicates its result through the documented structured output or process exit behavior.

### The input fields that matter

`tool\_input` does not have one universal schema. A Bash call may expose a `command` string, while file or editing tools use different fields.

A defensive handler should:

### Allow, deny, and error behavior

For a structured response, machine-readable JSON belongs on **stdout**. Diagnostic messages should go to **stderr** so they do not corrupt the response payload.

Process status and structured decisions are separate mechanisms. Anthropic documentation has historically assigned special behavior to a blocking exit status, but other nonzero statuses may indicate handler failure rather than intentional policy denial.

A fail-closed policy blocks an action when validation fails. It reduces risk but can interrupt legitimate work. A fail-open policy preserves availability but may permit an unvalidated call. Critical, narrowly matched operations usually justify fail-closed behavior when recovery procedures are documented.

> **Version-sensitive behavior:** Verify the current event-specific output schema, supported decision values, `hookSpecificOutput` nesting, timeout behavior, and blocking exit-code semantics against the [official Claude Code hooks documentation](https://docs.anthropic.com/en/docs/claude-code/hooks) before deployment.

## How to configure a PreToolUse hook in settings.json

Use the narrowest practical matcher and keep the handler inside a clearly controlled repository path.

> **Verification record:** Before publication or rollout, record the documentation verification date, `claude --version`, `node --version`, operating system, settings scope, and tested working directory. Do not assume schema stability across Claude Code versions.

### Minimal settings.json Example

`{
  "hooks": {
    "PreToolUse": \[
      {
        "matcher": "Bash",
        "hooks": \[
          {
            "type": "command",
            "command": "node \\"$CLAUDE\_PROJECT\_DIR/.claude/hooks/guard-bash.mjs\\"",
            "timeout": 10
          }
        \]
      }
    \]
  }
}
`

The configuration contains:

The example uses `CLAUDE\_PROJECT\_DIR` to locate a repository-local script. Confirm the variable and timeout unit in the documentation for your installed version.

The quoted variable syntax assumes a compatible shell. If your team uses Windows without a POSIX-compatible shell, test path expansion and command quoting separately. The Node.js script itself is portable, but the launcher command may require adjustment.

Hook scripts run with the privileges available to the Claude Code process. They should therefore be reviewed, access-controlled, and treated as privileged local code.

### Create the hook handler

![Image](https://cdn.agentkit.best/blog/cfai-media/4de5857c6f4ab180b45c56a6505189923e662137cec07e078c19a507f9468fa6-406c0a3fa919995e7269dbcde70aa9ec0f9070fa10f2f7012c7ac1765d6c0ef6.jpg)

## Working example: Block dangerous Bash and Git Commands

Define the policy before writing regular expressions. This keeps implementation decisions tied to operational risk rather than an arbitrary list of command strings.

### Define the policy before writing the code

“Human-controlled” should not be mapped to an unsupported decision value. When native manual routing is unavailable or unverified, deny the command and explain the approved manual workflow.

### Inspect and reject unsafe commands

`// .claude/hooks/guard-bash.mjs

const deny = (reason) =\> {
  process.stdout.write(
    JSON.stringify({
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "deny",
        permissionDecisionReason: reason
      }
    })
  );
};

let raw = "";

try {
  for await (const chunk of process.stdin) {
    raw += chunk;
  }

  const input = JSON.parse(raw);

  if (
    input?.hook\_event\_name !== "PreToolUse" ||
    input?.tool\_name !== "Bash"
  ) {
    process.stdout.write("{}");
    process.exit(0);
  }

  if (
    !input.tool\_input ||
    typeof input.tool\_input !== "object" ||
    typeof input.tool\_input.command !== "string"
  ) {
    deny("Blocked: Bash command input is missing or invalid.");
    process.exit(0);
  }

  const command = input.tool\_input.command.trim();

  const policies = \[
    {
      pattern: /(^|\[\\s/"'=\])\\.env(?:\[\\w.-\]\*)?(?=$|\[\\s/"';&|\])/i,
      reason: "Blocked: access to environment files is not permitted."
    },
    {
      pattern: /\\bgit\\s+push\\b/i,
      reason: "Blocked: review and run git push manually."
    },
    {
      pattern: /\\bgit\\s+reset\\b\[^;&|\]\*--hard\\b/i,
      reason: "Blocked: git reset --hard can discard local work."
    },
    {
      pattern: /\\brm\\s+-\[a-z\]\*r\[a-z\]\*f\[a-z\]\*\\b/i,
      reason: "Blocked: recursive forced deletion is not permitted."
    }
  \];

  const violation = policies.find(({ pattern }) =\> pattern.test(command));

  if (violation) {
    deny(violation.reason);
  } else {
    process.stdout.write("{}");
  }
} catch {
  console.error("PreToolUse validation failed; command blocked.");
  deny("Blocked: the security hook could not validate the command.");
}
`

The handler performs five tasks:

This is a starter guardrail for shell command validation-not a complete command parser or [sandbox](https://agentkit.best/blog/claude-code-guides/claude-code-sandbox-a-guide-to-secure-ai-command-execution).

### Important limits of regex and substring checks

> **Warning:** A denylist can catch obvious commands, but it cannot reliably model every way a shell operation may be expressed.

Potential bypasses include:

For higher-risk repositories:

## Practical PreToolUse use cases

The strongest use cases involve a narrow, observable input and a clear policy decision.

### Protect secrets and sensitive paths

A handler can reject references to:

Path validation only works when the relevant tool is matched and the required path is visible in its input. A Bash-only matcher does not automatically control file access through other tools.

### Control Git, deployment, and database actions

### Validate tool inputs before execution

Pre-execution validation can confirm that required files exist, restrict Bash to approved scripts, or validate branch, environment, path, and command arguments.

Record only the minimum information needed for the policy decision. Use an appropriate post-execution event for result logging because a pre-execution record proves only that a call was evaluated—not that it succeeded.

## PreToolUse hooks vs. permissions vs. CLAUDE.md

These controls solve different problems and should not be treated as interchangeable.

Which control should you use?

A practical defense-in-depth setup combines project guidance, permissions, programmable validation, and infrastructure controls. Hooks provide contextual enforcement, while isolation limits the actual damage a process can cause.

## Testing, troubleshooting, and security best practices

Test the handler directly with JSON fixtures before relying on an interactive Claude Code session.

### Minimal test matrix

A minimal direct fixture can pipe JSON into the handler:

`printf '%s' \\
'{"hook\_event\_name":"PreToolUse","tool\_name":"Bash","tool\_input":{"command":"git push origin main"}}' \\
| node .claude/hooks/guard-bash.mjs
`

Add fixtures for approved commands, missing fields, incorrect data types, malformed JSON, and delayed execution. Do not include credentials or real secret paths in test data.

### Common implementation mistakes

### Production hardening checklist

![Image](https://cdn.agentkit.best/blog/cfai-media/05f5b0d3b42b8ecf06523f55670746065afcd57cfbff634d2f97b07c2c1a2e85-2c2560e6936d5b49870e1c69cdddc8fccd0b7866d743f67f680ba613e921ef68.jpg)

## Build a guardrail, not a false security boundary

A Claude Code PreToolUse hook creates a programmable checkpoint between a proposed tool call and tool execution. The implementation sequence is direct: Match the relevant tool, validate the JSON input, apply an explicit policy, return the documented decision, and test both permitted and prohibited scenarios.

For high-risk work, combine the hook with [Claude Code permissions](https://agentkit.best/blog/claude-code-guides/claude-code-permissions-security-guide-to-safe-workflows), least privilege, credential isolation, protected configuration, and an isolated environment. Regex rules alone should never carry the full security burden.

AgentKit’s PreToolUse security starter template packages a versioned `settings.json` example, portable Node.js handler, policy matrix, JSON fixtures, test matrix, and verification notes for reuse in non-production repositories.

## Frequently asked questions

### What is a Claude Code PreToolUse hook?

A `PreToolUse` hook is a programmable guardrail that intercepts a proposed tool call before it executes. It allows you to run a custom script to inspect the tool’s input, validate the action against your project policies, and either permit or block the execution deterministically.

### Where does the PreToolUse hook fit into the tool lifecycle?

The hook runs after [Claude Code](https://agentkit.best/blog/claude-code-guides/what-is-claude-code-a-complete-guide-to-the-ai-coding-tool) proposes a tool call but before that tool actually executes. The sequence is: Claude identifies a task, proposes a specific tool call, the `PreToolUse` matcher triggers your handler, your script evaluates the action, and then the tool runs only if permitted.

### Why use a PreToolUse hook instead of just prompting the AI?

Prompt-based guidance is advisory and can be overlooked by the model. A `PreToolUse` hook provides deterministic, code-based enforcement. It allows you to run logic that checks inputs against hard constraints—such as preventing access to `.env` files or blocking specific Git commands—regardless of how the agent is prompted.

### How do I configure a PreToolUse hook?

You define the hook in your `settings.json` file under the `hooks.PreToolUse` key. You must specify a "matcher" (such as `Bash`) to target specific tools, the path to your executable handler script, and a timeout. Ensure your matcher is narrow to avoid unnecessary performance overhead.

### What happens if my PreToolUse handler returns an error?

If your handler fails to execute or returns an invalid response, Claude Code’s behavior depends on your project’s configured fail-safe policy. It is recommended to design your handler to be robust, perform defensive JSON parsing, and write diagnostics to `stderr` while keeping structured output clean for the agent.

### Is a PreToolUse hook a complete security sandbox?

No. A `PreToolUse` hook is a local validation layer, not a security sandbox. It runs with the same system privileges as the Claude Code process. For high-risk workflows, you should combine hooks with Claude Code permissions, least-privilege credentials, and an isolated execution environment to ensure defense-in-depth.

### Can I block all dangerous Git commands using these hooks?

You can block specific dangerous Git patterns (like `git reset --hard` or `git push`) by inspecting the `tool\_input` field in your handler. However, because commands can be obfuscated or executed through different tools, rely on a combination of blocklists, project-local allowlists, and human-in-the-loop approvals for sensitive operations.

**Read more**:

## Conclusion

Ultimately, the Claude Code PreToolUse hook serves as a critical, programmable guardrail that intercepts and evaluates tool calls before they execute. By moving beyond advisory prompt instructions to deterministic, code-based validation, it effectively blocks high-risk operations like destructive Bash commands or unauthorized credential access. 

However, since it is not a comprehensive security sandbox and runs with the privileges of the Claude Code process, it should not bear the entire security burden. For true defense-in-depth, teams must combine these programmable hooks with narrow tool matchers, least-privilege credentials, and isolated execution environments.
