Hooks Mechanism for AI Coding Assistants: Auto-Formatting and Safety Checks in Practice

Why Hooks Matter: From Soft Prompts to Deterministic Automation

When developers use an AI coding assistant, they typically write a set of engineering rules in a global prompt file—things like “format files after every edit,” “never run high-risk system commands,” or “always run checks before committing.” These rules are natural-language instructions for the model. The model follows them most of the time, but as the conversation grows longer and attention spreads, occasional lapses are almost inevitable.

That is exactly where engineering risk lives. Inconsistent formatting makes code review painful. A mis-executed high-risk command can cause serious incidents. Skipping safety checks can push vulnerabilities into production. For any rule where “occasional misses” are unacceptable, relying on the model’s goodwill is not enough.

The Hooks mechanism exists for precisely this reason. It lets you write a command or script in advance and bind it to a specific lifecycle node in the assistant’s runtime. When that event fires—regardless of what the model is doing at the moment—the code runs automatically. Its core value is this: it upgrades engineering rules from “the AI should remember” to “this will definitely execute at a defined moment.”

In short, prompts are soft constraints; Hooks are hard constraints. Any rule you cannot afford to miss even once should be enforced through Hooks.

Lifecycle Events: Where Hooks Can Attach

During a full session, an AI coding assistant passes through several lifecycle nodes. Hooks mount on those nodes, which fall into three broad categories.

Session-Level Events

Event	When It Fires	Can Intercept	Typical Use
SessionStart	On session initialization or resumption	No	Load project state, print to-do lists, initialize the dev environment, check dependency versions

These events fire only once per conversation and are ideal for global setup—pulling the latest project configuration, verifying the current branch, or starting a local dev server.

Turn-Level Events

Event	When It Fires	Can Intercept	Typical Use
UserPromptSubmit	Before the model processes a user message	Yes	Validate user input, inject real-time context (current Git branch, unstaged-change count, etc.)

This event fires on every user message and supports interception. A Hook script can return a specific signal to halt further processing, making it the perfect spot for input validation and context enrichment.

Tool-Call-Level Events

Event	When It Fires	Can Intercept	Typical Use
PreToolUse	Right before a tool is invoked	Yes	Block dangerous commands, review operation parameters, enforce pre-checks
PostToolUse	Right after a tool finishes	No	Trigger file formatting, run test suites, execute security scans

These two are the most commonly used and the most powerful. PreToolUse lets you decide whether to allow or block a command before it runs. PostToolUse is suited for post-processing such as formatting a file that was just edited.

Hook Configuration Structure and Context Data

Basic Configuration Shape

Hooks are typically declared in a configuration file at the project root. Each entry has three core elements:

• matcher: which lifecycle event the Hook listens for;
• command: the command or script path to run when the event fires;
• conditions (optional): narrow the trigger scope by file type, environment variable, command content, etc.

Here is an illustrative snippet:

hooks:
  - matcher: PostToolUse
    command: ./scripts/format.sh
    if:
      - file_extension: ".ts,.tsx,.js,.jsx"
  - matcher: PreToolUse
    command: ./scripts/safety_check.sh
    if:
      - command_contains: "rm -rf"
      - or:
          - command_contains: "sudo"
          - command_contains: "chmod 777"

How Hook Scripts Receive Context Data

Hook scripts do not run in isolation. When triggered, the assistant passes a structured payload that typically includes:

• The event type and timestamp;
• Associated file paths and change content;
• The full command text about to run (critical for PreToolUse);
• Session ID, working directory, and other environment info.

The script reads this data from stdin or environment variables, applies its logic, and for PreToolUse events usually returns an explicit signal—exit code 0 to allow, non-zero to block—so the host knows whether to proceed.

Three Practical Implementations

1. PostToolUse Auto-Formatting

Scenario: After the assistant edits a file via a tool call, automatically run a formatter to keep code style consistent.

Approach:

1. Attach the Hook to the PostToolUse event.
2. The script extracts the modified file path and extension from context.
3. It selects the appropriate formatter for the file type (TypeScript/JavaScript, Python, etc.).
4. It formats and writes the file back.
5. If a syntax error surfaces during formatting, it can roll back and notify the user.

Key Details:

• Restrict by file extension to avoid touching images, binaries, or other non-code files.
• Run formatting silently in the background so it does not interrupt the conversation.
• Store a shared formatter configuration in the project so every developer uses the same rules.

#!/bin/bash
# format.sh — illustrative script
FILE_PATH=$(echo "$HOOK_INPUT" | jq -r '.file_path')
EXT="${FILE_PATH##*.}"
case "$EXT" in
  ts|tsx|js|jsx)
    npx formatter --write "$FILE_PATH"
    ;;
  py)
    npx pyformatter --in-place "$FILE_PATH"
    ;;
  *)
    exit 0  # Not a target file type, skip
    ;;
esac

2. PreToolUse Dangerous-Command Interception

Scenario: Before the assistant executes any system command, run a safety check to block high-risk operations.

Approach:

1. Attach the Hook to the PreToolUse event.
2. The script pulls the full pending command string from context.
3. It matches against a list of dangerous patterns using regex or keyword checks.
4. If a pattern matches, it returns a non-zero exit code with a reason; the host cancels the tool call and warns the user.
5. If clean, it returns 0 and the command proceeds normally.

Typical dangerous patterns to catch:

• Recursive force-delete: rm -rf /, rm -rf ~
• High-privilege operations: sudo with risky flags
• Over-permissive modes: chmod 777
• Network exposure: binding sensitive ports directly to the public internet
• Data destruction: unconfirmed DROP DATABASE or TRUNCATE

#!/bin/bash
# safety_check.sh — illustrative script
COMMAND=$(echo "$HOOK_INPUT" | jq -r '.command')
DANGEROUS_PATTERNS=(
  "rm -rf /"
  "rm -rf ~"
  "chmod 777"
  "sudo.*dd "
  "sudo.*mkfs"
  "DROP DATABASE"
  "DROP TABLE"
)
for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if [[ "$COMMAND" =~ $pattern ]]; then
    echo "{\"block\": true, \"reason\": \"Detected dangerous command: $pattern\"}"
    exit 1
  fi
done
exit 0  # Safe, allow

Important: Maintain the blocklist regularly. Cover known risks without over-blocking normal workflows. Consider a team whitelist and a temporary-allow path for edge cases.

3. UserPromptSubmit Real-Time Context Injection

Scenario: Before each user message reaches the model, automatically inject the project’s live state—current branch, unstaged-change count, latest build result, and so on—so the assistant works with fresher information.

Approach:

1. Attach the Hook to the UserPromptSubmit event.
2. The script runs before the user’s message is sent to the model.
3. It gathers real-time project data and produces a structured context block.
4. That block is prepended to the original user message and delivered together.

Useful information to inject:

• Current Git branch and latest commit hash
• List and count of unstaged files
• Pass/fail status of the most recent build or test run
• Number of open code-review comments
• Status of dependency lockfiles

The payoff: the assistant no longer needs the user to manually describe the project each time. Every turn gets the latest context, leading to more accurate suggestions.

Best Practices and Caveats

1. Version-control your Hooks: Commit both the config and scripts so the whole team shares the same automation.
2. Keep scripts lightweight: They run on every event trigger; avoid heavy operations or complex dependencies that slow the dev experience.
3. Make failures observable: When a Hook fails, produce clear logs so you can tell whether the rule is too strict or the script has a bug.
4. Roll out gradually: Start with PostToolUse formatting and PreToolUse safety interception—the highest-value scenarios—then expand once they are stable.
5. Complement, don’t replace, CI/CD: Hooks handle real-time local automation; they are not a substitute for the comprehensive checks in your CI/CD pipeline. Think of them as layered protection.

Summary

The Hooks mechanism turns engineering rules from “hope the AI remembers” into “this code will definitely run at a defined lifecycle moment.” By picking the right events, writing focused script logic, and feeding in real-time context, developers can build an automation layer that covers formatting, safety interception, and context enrichment. This dramatically cuts the risk of human oversights and makes the assistant’s output more consistent and predictable—a key step from simply using an AI tool to using it well.