Agent hooks in Visual Studio Code (Preview)

Hooks enable you to execute custom shell commands at key lifecycle points during agent sessions. Use hooks to automate workflows, enforce security policies, validate operations, and integrate with external tools. Hooks run deterministically and can control agent behavior, including blocking tool execution or injecting context into the conversation.

Hooks are designed to work across agent types, including local agents, background agents, and cloud agents. Each hook receives structured JSON input and can return JSON output to influence agent behavior.

Why use hooks?

Hooks provide deterministic, code-driven automation. Unlike instructions or custom prompts that guide agent behavior, hooks execute your code at specific lifecycle points with guaranteed outcomes:

• Enforce security policies: Block dangerous commands like rm -rf or DROP TABLE before they execute, regardless of how the agent was prompted.

• Automate code quality: Run formatters, linters, or tests automatically after file modifications.

• Create audit trails: Log every tool invocation, command execution, or file change for compliance and debugging.

• Inject context: Add project-specific information, API keys, or environment details to help the agent make better decisions.

• Control approvals: Automatically approve safe operations while requiring confirmation for sensitive ones.

Hook lifecycle events

VS Code supports eight hook events that fire at specific points during an agent session:

Configure hooks

Hooks are configured in JSON files stored in your workspace or user directory.

Hook file locations

VS Code searches for hook configuration files in these locations:

• Workspace: .github/hooks/*.json - Project-specific hooks shared with your team
• Workspace: .claude/settings.local.json - Local workspace hooks (not committed)
• Workspace: .claude/settings.json - Workspace-level hooks
• User: ~/.claude/settings.json - Personal hooks applied across all workspaces

Workspace hooks take precedence over user hooks for the same event type.

Hook configuration format

Create a JSON file with a hooks object containing arrays of hook commands for each event type. VS Code uses the same hook format as Claude Code and Copilot CLI for compatibility:

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "./scripts/validate-tool.sh",
        "timeoutSec": 15
      }
    ],
    "PostToolUse": [
      {
        "type": "command",
        "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\""
      }
    ]
  }
}

Hook command properties

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

OS-specific commands

Specify different commands for each operating system:

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "./scripts/format.sh",
        "windows": "powershell -File scripts\\format.ps1",
        "linux": "./scripts/format-linux.sh",
        "osx": "./scripts/format-mac.sh"
      }
    ]
  }
}

The execution service selects the appropriate command based on your OS. If no OS-specific command is defined, it falls back to the command property.

Hook input and output

Hooks communicate with VS Code through stdin (input) and stdout (output) using JSON.

Input format

Every hook receives a JSON object via stdin with common fields:

{
  "timestamp": "2026-02-09T10:30:00.000Z",
  "cwd": "/path/to/workspace",
  "sessionId": "session-identifier",
  "hookEventName": "PreToolUse",
  "transcript_path": "/path/to/transcript.json"
}

For PreToolUse and PostToolUse hooks, additional fields are included:

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

The tool_response field is only present for PostToolUse hooks.

For UserPromptSubmit hooks, a prompt field is included with the text the user submitted.

For Stop and SubagentStop hooks, a stop_hook_active boolean is included. It is true when a stop hook is already keeping the session active.

Output format

Hooks can return JSON via stdout to influence agent behavior:

{
  "continue": true,
  "stopReason": "Security policy violation",
  "systemMessage": "Operation blocked by security hook"
}

Exit codes

The hook's exit code determines how VS Code handles the result:

PreToolUse hook 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"
  }
}

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

Configure hooks with the /hooks command

Use the /hooks slash command in chat to configure hooks through an interactive UI:

1. Type /hooks in the chat input and press Enter.

2. Select a hook event type from the list.

3. Choose an existing hook to edit or select Add new hook to create one.

4. Select or create a hook configuration file.

The command opens the hook file in the editor with your cursor positioned at the command field, ready for editing.

Usage scenarios

The following examples demonstrate common hook patterns.

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "./scripts/block-dangerous.sh",
        "timeoutSec": 5
      }
    ]
  }
}

#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
TOOL_INPUT=$(echo "$INPUT" | jq -r '.tool_input')

if [ "$TOOL_NAME" = "runTerminalCommand" ]; then
  COMMAND=$(echo "$TOOL_INPUT" | jq -r '.command // empty')

  if echo "$COMMAND" | grep -qE '(rm\s+-rf|DROP\s+TABLE|DELETE\s+FROM)'; then
    echo '{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"Destructive command blocked by security policy"}}'
    exit 0
  fi
fi

echo '{"continue":true}'

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "./scripts/format-changed-files.sh",
        "windows": "powershell -File scripts\\format-changed-files.ps1",
        "timeoutSec": 30
      }
    ]
  }
}

#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')

if [ "$TOOL_NAME" = "editFiles" ] || [ "$TOOL_NAME" = "createFile" ]; then
  FILES=$(echo "$INPUT" | jq -r '.tool_input.files[]? // .tool_input.path // empty')

  for FILE in $FILES; do
    if [ -f "$FILE" ]; then
      npx prettier --write "$FILE" 2>/dev/null
    fi
  done
fi

echo '{"continue":true}'

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "./scripts/log-tool-use.sh",
        "env": {
          "AUDIT_LOG": ".github/hooks/audit.log"
        }
      }
    ]
  }
}

#!/bin/bash
INPUT=$(cat)
TIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp')
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
SESSION_ID=$(echo "$INPUT" | jq -r '.sessionId')

echo "[$TIMESTAMP] Session: $SESSION_ID, Tool: $TOOL_NAME" >> "${AUDIT_LOG:-audit.log}"
echo '{"continue":true}'

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "./scripts/require-approval.sh"
      }
    ]
  }
}

#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')

# Tools that should always require approval
SENSITIVE_TOOLS="runTerminalCommand|deleteFile|pushToGitHub"

if echo "$TOOL_NAME" | grep -qE "^($SENSITIVE_TOOLS)$"; then
  echo '{"hookSpecificOutput":{"permissionDecision":"ask","permissionDecisionReason":"This operation requires manual approval"}}'
else
  echo '{"hookSpecificOutput":{"permissionDecision":"allow"}}'
fi

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "./scripts/inject-context.sh"
      }
    ]
  }
}

#!/bin/bash
PROJECT_INFO=$(cat package.json 2>/dev/null | jq -r '.name + " v" + .version' || echo "Unknown project")
BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")

cat <<EOF
{
  "systemMessage": "Project: $PROJECT_INFO | Branch: $BRANCH | Node: $(node -v 2>/dev/null || echo 'not installed')"
}
EOF

Troubleshooting

View hook diagnostics

To see which hooks are loaded and check for configuration errors:

1. Right-click in the Chat view and select Diagnostics.

2. Look for the hooks section to see loaded hooks and any validation errors.

View hook output

To review hook output and errors:

1. Open the Output panel.

2. Select Hooks from the channel list.

Common issues

Hook not executing: Verify the hook file is in .github/hooks/ and has a .json extension. Check that the type property is set to "command".

Permission denied errors: Ensure your hook scripts have execute permissions (chmod +x script.sh).

Timeout errors: Increase the timeoutSec value or optimize your hook script. The default is 30 seconds.

JSON parse errors: Verify your hook script outputs valid JSON to stdout. Use jq or a JSON library to construct output.

Frequently asked questions

How does VS Code handle Claude Code hook configurations?

VS Code parses Claude Code's hook configuration format, including matcher syntax. Currently, VS Code ignores matcher values, so hooks apply to all tools. Claude Code uses an empty string matcher ("") to represent all tools.

How does VS Code handle Copilot CLI hook configurations?

VS Code parses Copilot CLI hook configurations and converts the lowerCamelCase hook event names (like preToolUse) to the PascalCase format used by VS Code (PreToolUse). Both bash and powershell command formats are supported.

Security considerations

• Review hook scripts: Inspect all hook scripts before enabling them, especially in shared repositories.

• Limit hook permissions: Use the principle of least privilege. Hooks should only have access to what they need.

• Validate input: Hook scripts receive input from the agent. Validate and sanitize all input to prevent injection attacks.

• Secure credentials: Never hardcode secrets in hook scripts. Use environment variables or secure credential storage.

Related resources

• Use tools with agents - Learn about tool approval and execution
• Custom agents - Create specialized agent configurations
• Subagents - Delegate tasks to context-isolated subagents
• Security considerations - Best practices for AI security in VS Code