PostToolUse Hook

PostToolUse

PostToolUse is triggered immediately after a tool is successfully executed. Supports the same matcher values as PreToolUse.

Common Matchers

  • Task - Subagent tasks
  • Bash - Shell commands
  • Glob - File pattern matching
  • Grep - Content search
  • Read - File reading
  • Edit - File editing
  • Write - File writing
  • WebFetch, WebSearch - Web operations

Configuration Methods

Configure Hooks in the settings file:

  • ~/.hcode/settings.json - User-level settings
  • .hcode/settings.json - Project-level settings

Basic Structure

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

matcher: Pattern used to match tool names, case-sensitive

  • Simple string: Exact match, e.g., Write only matches the Write tool
  • Regular expression: Supports patterns like Edit|Write or Notebook.*
  • Wildcard: Use * to match all tools, or use empty string "" or omit matcher

hooks: Array of hooks to execute when the pattern matches

  • type: Hook execution type, "command" means execute bash command
  • command: The bash command to execute
  • timeout: (Optional) Hook execution timeout in seconds

PostToolUse in Plugin Hooks

Example plugin hook configuration:

{
  "description": "Automatic code formatting",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "node ./scripts/format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Input Parameters

The specific format of tool_input and tool_response depends on the tool type.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.hcode/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  },
  "tool_use_id": "toolu_01ABC123..."
}

Field Descriptions

Field Type Description
session_id string Session unique identifier
transcript_path string Full path to the conversation JSON file
cwd string Current working directory when the hook is called
permission_mode string Current permission mode: "default", "plan", "acceptEdits", "dontAsk" or "bypassPermissions"
hook_event_name string Fixed as "PostToolUse"
tool_name string Name of the executed tool (e.g., Write, Edit, Bash, etc.)
tool_input object Tool’s input parameters (varies by tool)
tool_response object Tool’s response result (varies by tool)
tool_use_id string Unique identifier for the tool call

Note: The specific format of tool_input and tool_response depends on the tool type.

Output Parameters / Decision Control

PostToolUse hooks can provide feedback to Hawa Code after tool execution.

  • "block": Block subsequent operations and prompt Hawa Code with reason
  • undefined: Do nothing, reason is ignored
  • "hookSpecificOutput.additionalContext": Add extra context for Hawa Code
{
  "decision": "block" | undefined,
  "reason": "Decision explanation",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information provided to Hawa Code"
  }
}

Field Descriptions

Field Type Description
decision string | undefined "block" means block and prompt with reason, undefined means do nothing
reason string Explanation of the decision
hookSpecificOutput object Hook-specific output information
hookSpecificOutput.hookEventName string Fixed as "PostToolUse"
hookSpecificOutput.additionalContext string Additional context information added for Hawa Code

Exit Code Behavior

Simple Exit Codes

Hooks communicate status through exit codes, stdout, and stderr:

  • Exit code 0: Success, stdout is displayed to the user
  • Exit code 2: Blocking error, stderr is displayed to Hawa Code (tool has been executed), format is [command]: {stderr}
  • Other exit codes: Non-blocking error, displayed in stderr

PostToolUse Specific Exit Code 2 Behavior

Hook Event Behavior
PostToolUse Display stderr to Hawa Code (tool has been executed)
Next