Skip to main content
Hooks let you intercept and respond to events during a Claude Code session. They run your custom logic before or after tool calls, when sessions start or end, when the user submits a prompt, and more. Use them to enforce policies, inject context, gate permissions, or integrate with external systems.

​
How Hooks Work

A hook is a callback function that fires when a specific event occurs during the agent session. Each hook receives event-specific input data and returns an output that can influence the agent’s behavior — for example, allowing or denying a tool call, injecting additional context, or stopping the session. Hooks are configured in your settings files and passed to the Claude Code SDK at session startup. Jinzo merges hooks from all settings sources (user, project, local) and applies them to every run.

​
Hook Events

EventWhen it firesWhat you can do
PreToolUseBefore a tool executesAllow, deny, or modify tool input
PostToolUseAfter a tool executes successfullyInspect output, inject additional context
PostToolUseFailureAfter a tool execution failsHandle errors, add context for recovery
UserPromptSubmitWhen the user sends a messageTransform or validate user input
StopWhen the agent is about to stopInspect the final message, trigger follow-up actions
SessionStartWhen a session starts, resumes, or restartsSet up context, log session metadata
SessionEndWhen a session endsClean up resources, log session results
SubagentStartWhen a subagent is spawnedInject context into subagent
SubagentStopWhen a subagent finishesInspect subagent results
PreCompactBefore conversation history is compactedAdd instructions for compaction
NotificationWhen the agent emits a notification (permission, idle, etc.)React to agent status changes
PermissionRequestWhen a tool requests elevated permissionsCustom permission decision logic
SetupOn initial setup or maintenance triggersEnvironment initialization
TeammateIdleWhen a teammate agent goes idleCoordinate team workflows
TaskCompletedWhen a task is marked completeTrigger downstream actions
ConfigChangeWhen configuration changes during a sessionReact to setting updates

​
Hook Structure

Each hook event accepts an array of matchers. A matcher defines which tools trigger the hook (via a regex pattern) and the callback functions to execute. 
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": ["callback"],
        "timeout": 30
      }
    ]
  }
}
FieldDescription
matcherRegex pattern to match tool names. Omit to match all tools.
hooksArray of callback functions to execute when the pattern matches
timeoutTimeout in seconds (default: 60)

​
PreToolUse: Controlling Tool Execution

The most common hook. It fires before every tool call and lets you allow, deny, or modify the operation. Your callback receives:
FieldTypeDescription
tool_namestringName of the tool being called
tool_inputRecord<string, unknown>Arguments passed to the tool
tool_use_idstringUnique ID for this tool invocation
Your callback can return a permissionDecision:
DecisionEffect
allowTool executes immediately, no user prompt
denyTool is blocked with an optional reason
askFalls through to the interactive approval dialog
You can also return updatedInput to modify the tool’s arguments before execution, or additionalContext to inject a message into the agent’s context.

​
Built-in Tool Approval Hook

Jinzo automatically registers a PreToolUse hook that handles the interactive tool approval flow. When the agent calls a tool that isn’t pre-approved, this hook pauses execution and shows an approval dialog in the workspace UI. You can approve or reject the call, and optionally provide an answer for AskUserQuestion tool calls. Pre-approved tools (Bash, Read, Write, Edit, Glob, Grep, and all MCP tools) execute automatically without prompting.

​
PostToolUse: Reacting to Results

Fires after a tool executes successfully. Useful for logging, auditing, or injecting follow-up context. Your callback receives the same fields as PreToolUse, plus:
FieldTypeDescription
tool_responseunknownThe tool’s output
Return additionalContext to append a message to the agent’s context after the tool completes.

​
UserPromptSubmit: Transforming Input

Fires when the user sends a message. Use this to validate, transform, or enrich user prompts before the agent processes them. Your callback receives:
FieldTypeDescription
promptstringThe user’s prompt text
Return additionalContext to prepend context to the prompt.

​
Session Lifecycle Hooks

​
SessionStart

Fires when a session begins. The source field tells you how:
SourceMeaning
startupFresh session
resumeResumed from a previous session
clearSession was cleared and restarted
compactSession was compacted and continued

​
SessionEnd

Fires when a session ends. The reason field indicates why:
  • clear — user cleared the session
  • logout — user logged out
  • prompt_input_exit — user exited the prompt
  • bypass_permissions_disabled — bypass mode was disabled
  • other — any other reason

​
Common Input Fields

All hook callbacks receive these base fields:
FieldTypeDescription
session_idstringCurrent session identifier
transcript_pathstringPath to the conversation transcript file
cwdstringCurrent working directory

​
Settings Sources

Hooks are configured in your settings files and merged in priority order:
SourcePath
User (global)~/.claude/settings.json
Project (shared).jinzo/settings.json
Local (personal).jinzo/settings.local.json
Run-level hooks (defined per workspace or run) are appended after config-level hooks, so they execute in addition to — not instead of — your base hooks.
Hooks are only available for the Claude Code agent runtime. For Copilot, use the tool permissions system instead.