PreToolUse

PreToolUse

PreToolUse runs after Hawa Code creates tool parameters and before processing the tool call. This is the key moment to intercept and control tool execution.

Core Features

  • Intercept tool calls: Inspect and intervene before tools are actually executed
  • Allow, deny, or ask: Automatically approve, block tools, or prompt user confirmation
  • Modify tool input: Modify tool parameters before execution
  • Add context: Inject additional context information into Hawa Code

Matcher

PreToolUse supports matching on tool names, including:

  • Single match: Match a single property, e.g., “Edit”.
  • Multiple matches: Use pipe | to separate multiple properties, e.g., “Edit|Write”.
  • Wildcard match: Use * for wildcard matching, e.g., “mcp__memory__.“, “mcp__.*__write.“, “mcp__.__write.|Edit”

Input Parameters

Property Description
session_id Current session ID
transcript_path Path to the conversation history JSON file
cwd Working directory when the hook is invoked
permission_mode Current permission mode: default, plan, acceptEdits, dontAsk, or bypassPermissions
hook_event_name PreToolUse
tool_name Name of the tool being processed
tool_input Tool input parameters
tool_use_id ID of the tool invocation

Input example:

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.hcode/projects/.../xxxx.jsonl",
  "cwd": "/home/user/my-project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm clear"
  }
}

Output Parameters

Property Description
continue If true, the tool will be allowed to execute; if false, the tool will be blocked
stopReason Sent to the LLM when the tool is blocked
systemMessage Warning message displayed in the CLI terminal, not sent to the LLM
suppressOutput Only displays systemMessage in the CLI terminal when true
hookSpecificOutput.hookEventName PreToolUse
hookSpecificOutput.permissionDecision deny (tool blocked), ask (tool requires user confirmation), allow (tool executes without confirmation)
hookSpecificOutput.updatedInput Modified input parameters that will be used when the tool executes

Output example:

{
  "continue": true,
  "stopReason": "Risky operation cannot be executed",
  "suppressOutput": true,
  "systemMessage": "This script has been analyzed. Please ignore this warning if not applicable.",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "ask",
    "permissionDecisionReason": "Script has risks and should be carefully verified and confirmed!",
    "updatedInput": {
      "command": "npm install"
    }
  }
}

Exit Codes

If the hook command returns a non-zero exit code, continue will be set to false, and stderr will be set as stopReason.

Configuration

Basic Configuration

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./security-check.sh",
            "timeout": 30,
            "statusMessage": "Checking...",
            "async": false
          }
        ]
      }
    ]
  }
}

Parameter Description

Parameter Type Description Default
matcher string Regex pattern to match tool names Required
type string Hook type: command/prompt Required
command string Command to execute (for command type) -
timeout number Timeout in seconds 600
statusMessage string Custom loading message -
async boolean Whether to run asynchronously false

Matcher Pattern Examples

// Match specific tool
"matcher": "Bash"

// Match multiple tools (regex)
"matcher": "Edit|Write"

// Match all MCP tools
"matcher": "mcp__.*"

// Match tools from specific MCP server
"matcher": "mcp__memory__.*"
Next