2924 Vscode Copilot Hooks Doc B9d46fa0

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.

Note

Agent hooks are currently in Preview for VS Code 1.109.3. The configuration format and behavior might change in future releases.

Important

Your organization might have disabled the use of hooks in VS Code. Contact your admin for more information. See enterprise policies for details.

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:

Expand table

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:

JSON

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "./scripts/validate-tool.sh",
        "timeout": 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:

Expand table

Note

OS-specific commands are selected based on the extension host platform. In remote development scenarios (SSH, Containers, WSL), this might differ from your local operating system.

OS-specific commands

Specify different commands for each operating system:

JSON

{
  "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.

Common input fields

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

JSON

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

Common output format

Hooks can return JSON via stdout to influence agent behavior. All hooks support these output fields:

JSON

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

Expand table

Exit codes

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

Expand table

PreToolUse

The PreToolUse hook fires before the agent invokes a tool.

PreToolUse input

In addition to the common fields, PreToolUse hooks receive:

JSON

{
  "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:

JSON

{
  "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"
  }
}

Expand table

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, run the command "Show Chat Debug View" 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:

JSON

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

PostToolUse output

The PostToolUse hook can provide additional context to the model, or block further processing:

JSON

{
  "decision": "block",
  "reason": "Post-processing validation failed",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "The edited file has lint errors that need to be fixed"
  }
}

Expand table

UserPromptSubmit

The UserPromptSubmit hook fires when the user submits a prompt.

UserPromptSubmit input

In addition to the common fields, UserPromptSubmit hooks receive a prompt field with the text the user submitted.

The UserPromptSubmit hook uses the common output format only.

SessionStart

The SessionStart hook fires when a new agent session begins.

SessionStart input

In addition to the common fields, SessionStart hooks receive:

JSON

{
  "source": "new"
}

Expand table

SessionStart output

The SessionStart hook can inject additional context into the agent's conversation:

JSON

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Project: my-app v2.1.0 | Branch: main | Node: v20.11.0"
  }
}

Expand table

Stop

The Stop hook fires when the agent session ends.

Stop input

In addition to the common fields, Stop hooks receive:

JSON

{
  "stop_hook_active": false
}

Expand table

Stop output

The Stop hook can prevent the agent from stopping:

JSON

{
  "hookSpecificOutput": {
    "hookEventName": "Stop",
    "decision": "block",
    "reason": "Run the test suite before finishing"
  }
}

Expand table

Important

When a Stop hook blocks the agent from stopping, the agent continues running and the additional turns consume premium requests. Always check the stop_hook_active field to prevent the agent from running indefinitely.

SubagentStart

The SubagentStart hook fires when a subagent is spawned.

SubagentStart input

In addition to the common fields, SubagentStart hooks receive:

JSON

{
  "agent_id": "subagent-456",
  "agent_type": "Plan"
}

Expand table

SubagentStart output

The SubagentStart hook can inject additional context into the subagent's conversation:

JSON

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "This subagent should follow the project coding guidelines"
  }
}

Expand table

SubagentStop

The SubagentStop hook fires when a subagent completes.

SubagentStop input

In addition to the common fields, SubagentStop hooks receive:

JSON

{
  "agent_id": "subagent-456",
  "agent_type": "Plan",
  "stop_hook_active": false
}

Expand table

SubagentStop output

The SubagentStop hook can prevent the subagent from stopping:

JSON

{
  "decision": "block",
  "reason": "Verify subagent results before completing"
}

Expand table

PreCompact

The PreCompact hook fires before conversation context is compacted.

PreCompact input

In addition to the common fields, PreCompact hooks receive:

JSON

{
  "trigger": "auto"
}

Expand table

The PreCompact hook uses the common output format only.

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.

Block dangerous terminal commands

Create a PreToolUse hook that prevents destructive commands:

.github/hooks/security.json:

JSON

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

scripts/block-dangerous.sh:

Bash

#!/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}'

Auto-format code after edits

Run Prettier automatically after any file modification:

.github/hooks/formatting.json:

JSON

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

scripts/format-changed-files.sh:

Bash

#!/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}'

Log tool usage for auditing

Create an audit trail of all tool invocations:

.github/hooks/audit.json:

JSON

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

scripts/log-tool-use.sh:

Bash

#!/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}'

Require approval for specific tools

Force manual confirmation for tools that modify infrastructure:

.github/hooks/approval.json:

JSON

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

scripts/require-approval.sh:

Bash

#!/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

Inject project context at session start

Provide project-specific information when a session begins:

.github/hooks/context.json:

JSON

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

scripts/inject-context.sh:

Bash

#!/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
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Project: $PROJECT_INFO | Branch: $BRANCH | Node: $(node -v 2>/dev/null || echo 'not installed')"
  }
}
EOF

Safety

If the agent has access to edit scripts run by hooks, then it has the ability to modify those scripts during its own run, and execute the code it writes. We recommend using the chat.tools.edits.autoApprove to disallow the agent from editing hook scripts without manual approval.

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 GitHub Copilot Chat 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 timeout 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

Caution

Hooks execute shell commands with the same permissions as VS Code. Review hook configurations carefully, especially when using hooks from untrusted sources.

• 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