PreToolUse Hook Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• hooks/hooks.json
• README.md
• hooks/rewrite-docs-url.sh
• hooks/rewrite-docs-url.test.sh
• skills/claude-code-docs/SKILL.md
• sync.ts

The PreToolUse hook is a critical component of the Claude Code plugin architecture that intercepts tool calls before they are executed. In this project, it is specifically utilized to rewrite documentation URLs from their standard HTML web representation to their raw Markdown counterparts. This ensures that when the WebFetch tool is invoked, it retrieves clean, LLM-friendly content instead of the HTML application shell.

Sources: hooks/hooks.json:1-4, README.md:54-58, hooks/rewrite-docs-url.sh:2-4

Hook Architecture and Registration

Hooks are registered via a central configuration file that defines which tools they apply to and what commands they execute. The registration mechanism uses a matcher to identify the target tool (e.g., WebFetch) and specifies the execution environment.

Registration Structure

The hooks.json file defines the following configuration for the PreToolUse event:

Configuration Field	Value	Description
Event Name	PreToolUse	The lifecycle event triggered before tool execution.
Matcher	WebFetch	Limits the hook to instances where the WebFetch tool is called.
Type	command	Indicates the hook executes an external shell command.
Command	bash ${CLAUDE_PLUGIN_ROOT}/hooks/rewrite-docs-url.sh	The script executed to process the tool input.
Timeout	5	The execution limit in seconds.

Sources: hooks/hooks.json:4-18

Execution Flow

The following diagram illustrates how the PreToolUse hook intercepts a tool request and modifies it before final execution.

The hook provides a non-blocking intervention that can either modify the input or allow the original request to proceed untouched.

Sources: hooks/hooks.json:6-15, hooks/rewrite-docs-url.sh:5-8, README.md:65-68

URL Rewriting Logic

The core logic resides in a Bash script that parses JSON input from STDIN, evaluates the URL, and outputs a modified JSON response.

Transformation Rules

The hook identifies standard documentation URLs and appends the .md extension while stripping fragments or query parameters.

Input URL Pattern	Transformation Result
.../docs/en/agents	.../docs/en/agents.md
.../docs/en/hooks#fragment	.../docs/en/hooks.md
.../docs/en/hooks?query=1	.../docs/en/hooks.md
.../docs/en/agents/	.../docs/en/agents.md

Sources: hooks/rewrite-docs-url.sh:16-20, hooks/rewrite-docs-url.test.sh:16-20, README.md:60-63

Validation and Filtering

The script includes several safeguards to prevent incorrect rewriting:

1. Domain Check: Only URLs starting with https://code.claude.com/docs/* are processed.
2. File Extension Check: If a path already contains a dot (e.g., .md, .txt, .png), it is ignored to prevent double-extension or corrupting static assets.
3. Locale Segment Check: Only URLs under a locale segment (like /docs/en/) are rewritten; the root docs directory is left untouched.

Sources: hooks/rewrite-docs-url.sh:11-35

Data Structures and Output Format

The hook must return a specific JSON schema to Claude Code to communicate the decision and the modified input.

Hook Output Schema

When a rewrite occurs, the script outputs a hookSpecificOutput object:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "...",
    "updatedInput": {
      "url": "https://code.claude.com/docs/en/page.md",
      "prompt": "original_prompt"
    }
  }
}

Key Fields

• permissionDecision: Set to "allow" to bypass additional user prompts for the modified URL.
• updatedInput: Contains the original tool input object with the url field replaced.
• permissionDecisionReason: A human-readable string explaining why the URL was changed.

Sources: hooks/rewrite-docs-url.sh:37-45, README.md:65-68

Integration with Documentation Sync

The PreToolUse hook relies on the mirrored structure maintained by the sync.ts utility. The sync process treats llms.txt as the source of truth and populates the docs/ directory.

Summary

The PreToolUse hook configuration provides a seamless way to optimize documentation retrieval. By intercepting WebFetch calls via hooks.json and processing them through rewrite-docs-url.sh, the system ensures that the LLM always receives clean Markdown data. This automation is paired with a robust sync process that maintains a local mirror of the documentation, allowing tools like ask and csp to perform semantic searches efficiently.

Sources: README.md:28-45, 54-58, skills/claude-code-docs/SKILL.md:10-14