Hooks reference

This article provides a reference for agent hook configuration properties and the input and output schemas of each hook event in VS Code. For information about configuring and using hooks, see Agent hooks.

Every hook also receives a set of common input fields and can return the common output format. The fields documented in the event sections are in addition to those common fields.

Hook command properties

Each hook entry must have type: "command" and at least one command property:

Property Type Description
type string Must be "command"
command string Default command to run (cross-platform)
windows string Windows-specific command override
linux string Linux-specific command override
osx string macOS-specific command override
cwd string Working directory (relative to repository root)
env object Additional environment variables
timeout number Timeout in seconds (default: 30)

PreToolUse

The PreToolUse hook fires before the agent invokes a tool.

PreToolUse input

In addition to the common fields, PreToolUse hooks receive:

{
  "tool_name": "editFiles",
  "tool_input": { "files": ["src/main.ts"] },
  "tool_use_id": "tool-123"
}

PreToolUse output

The PreToolUse hook can control tool execution through a hookSpecificOutput object:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by policy",
    "updatedInput": { "files": ["src/safe.ts"] },
    "additionalContext": "User has read-only access to production files"
  }
}
Field Values Description
permissionDecision "allow", "deny", "ask" Controls tool approval
permissionDecisionReason string Reason shown to user
updatedInput object Modified tool input (optional)
additionalContext string Extra context for the model

Permission decision priority: When multiple hooks run for the same tool invocation, the most restrictive decision wins:

  1. deny (most restrictive): blocks tool execution
  2. ask: requires user confirmation
  3. allow (least restrictive): auto-approves execution

updatedInput format: To determine the format of updatedInput, open the agent logs and find the logged tool schema. If updatedInput doesn't match the expected schema, it will be ignored.

PostToolUse

The PostToolUse hook fires after a tool completes successfully.

PostToolUse input

In addition to the common fields, PostToolUse hooks receive:

{
  "tool_name": "editFiles",