GitHub Copilot CLI hooks reference

Hooks are external commands that execute at specific lifecycle points during a session, enabling custom automation, security controls, and integrations. Hook configuration files are loaded automatically from .github/hooks/*.json in your repository.

Hook configuration format

Hook configuration files use JSON format with version 1.

Command hooks

Command hooks run shell scripts and are supported on all hook types.

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "your-bash-command",
        "powershell": "your-powershell-command",
        "cwd": "optional/working/directory",
        "env": { "VAR": "value" },
        "timeoutSec": 30
      }
    ]
  }
}

Field	Type	Required	Description
bash	string	One of bash/powershell	Shell command for Unix.
cwd	string	No	Working directory for the command (relative to repository root or absolute).
env	object	No	Environment variables to set (supports variable expansion).
powershell	string	One of bash/powershell	Shell command for Windows.
timeoutSec	number	No	Timeout in seconds. Default: 30.
type	"command"	Yes	Must be "command".

Prompt hooks

Prompt hooks auto-submit text as if the user typed it. They are only supported on sessionStart and only fire for new interactive sessions. They do not fire on resume, and they do not fire in non-interactive prompt mode (-p). The text can be a natural language prompt or a slash command.

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "prompt",
        "prompt": "Your prompt text or /slash-command"
      }
    ]
  }
}

Field	Type	Required	Description
type	"prompt"	Yes	Must be "prompt".
prompt	string	Yes	Text to submit—can be a natural language message or a slash command.

Hook events

Event	Fires when	Output processed
agentStop	The main agent finishes a turn.	Yes — can block and force continuation.
errorOccurred	An error occurs during execution.	No
notification	Fires asynchronously when the CLI emits a system notification (shell completion, agent completion or idle, permission prompts, elicitation dialogs). Fire-and-forget: never blocks the session. Supports matcher regex on notification_type.	Optional — can inject additionalContext into the session.
permissionRequest	Fires before the permission service runs (rules engine, session approvals, auto-allow/auto-deny, and user prompting). If the merged hook output returns behavior: "allow" or "deny", that decision short-circuits the normal permission flow. Supports matcher regex on toolName.	Yes — can allow or deny programmatically.
postToolUse	After each tool completes successfully.	Yes — can replace the successful result (SDK programmatic hooks only).
postToolUseFailure	After a tool completes with a failure.	Yes — can provide recovery guidance via additionalContext (exit code 2 for command hooks).
preCompact	Context compaction is about to begin (manual or automatic). Supports matcher to filter by trigger ("manual" or "auto").	No — notification only.
preToolUse	Before each tool executes.	Yes — can allow, deny, or modify.
sessionEnd	The session terminates.	No
sessionStart	A new or resumed session begins.	No
subagentStart	A subagent is spawned (before it runs). Returns additionalContext prepended to the subagent's prompt. Supports matcher to filter by agent name.	No — cannot block creation.
subagentStop	A subagent completes.	Yes — can block and force continuation.
userPromptSubmitted	The user submits a prompt.	No

Hook event input payloads

Each hook event delivers a JSON payload to the hook handler. Two payload formats are supported, selected by the event name used in the hook configuration:

• camelCase format — Configure the event name in camelCase (for example, sessionStart). Fields use camelCase.
• VS Code compatible format — Configure the event name in PascalCase (for example, SessionStart). Fields use snake_case to match the VS Code Copilot extension format.

sessionStart / SessionStart

camelCase input:

{
    sessionId: string;
    timestamp: number;      // Unix timestamp in milliseconds
    cwd: string;
    source: "startup" | "resume" | "new";
    initialPrompt?: string;
}

VS Code compatible input:

{
    hook_event_name: "SessionStart";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    source: "startup" | "resume" | "new";
    initial_prompt?: string;
}

sessionEnd / SessionEnd

camelCase input:

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
}

VS Code compatible input:

{
    hook_event_name: "SessionEnd";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
}

userPromptSubmitted / UserPromptSubmit

camelCase input:

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    prompt: string;
}

VS Code compatible input:

{
    hook_event_name: "UserPromptSubmit";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    prompt: string;
}

preToolUse / PreToolUse

camelCase input:

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
}

VS Code compatible input:

When configured with the PascalCase event name PreToolUse, the payload uses snake_case field names to match the VS Code Copilot extension format:

{
    hook_event_name: "PreToolUse";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    tool_name: string;
    tool_input: unknown;    // Tool arguments (parsed from JSON string when possible)
}

postToolUse / PostToolUse

camelCase input:

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
    toolResult: {
        resultType: "success";
        textResultForLlm: string;
    }
}

VS Code compatible input:

{
    hook_event_name: "PostToolUse";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    tool_name: string;
    tool_input: unknown;
    tool_result: {
        result_type: "success" | "failure" | "denied" | "error";
        text_result_for_llm: string;
    }
}

postToolUseFailure / PostToolUseFailure

camelCase input:

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
    error: string;
}

VS Code compatible input:

{
    hook_event_name: "PostToolUseFailure";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    tool_name: string;
    tool_input: unknown;
    error: string;
}

agentStop / Stop

camelCase input:

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    stopReason: "end_turn";
}

VS Code compatible input:

{
    hook_event_name: "Stop";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    stop_reason: "end_turn";
}

subagentStart

Input:

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    agentName: string;
    agentDisplayName?: string;
    agentDescription?: string;
}

subagentStop / SubagentStop

camelCase input:

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    agentName: string;
    agentDisplayName?: string;
    stopReason: "end_turn";
}

VS Code compatible input:

{
    hook_event_name: "SubagentStop";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    agent_name: string;
    agent_display_name?: string;
    stop_reason: "end_turn";
}

errorOccurred / ErrorOccurred

camelCase input:

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    error: {
        message: string;
        name: string;
        stack?: string;
    };
    errorContext: "model_call" | "tool_execution" | "system" | "user_input";
    recoverable: boolean;
}

VS Code compatible input:

{
    hook_event_name: "ErrorOccurred";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    error: {
        message: string;
        name: string;
        stack?: string;
    };
    error_context: "model_call" | "tool_execution" | "system" | "user_input";
    recoverable: boolean;
}

preCompact / PreCompact

camelCase input:

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    trigger: "manual" | "auto";
    customInstructions: string;
}

VS Code compatible input:

{
    hook_event_name: "PreCompact";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    trigger: "manual" | "auto";
    custom_instructions: string;
}

preToolUse decision control

The preToolUse hook can control tool execution by writing a JSON object to stdout.

Field	Values	Description
permissionDecision	"allow", "deny", "ask"	Whether the tool executes. Empty output uses default behavior.
permissionDecisionReason	string	Reason shown to the agent. Required when decision is "deny".
modifiedArgs	object	Substitute tool arguments to use instead of the originals.

agentStop / subagentStop decision control

Field	Values	Description
decision	"block", "allow"	"block" forces another agent turn using reason as the prompt.
reason	string	Prompt for the next turn when decision is "block".

permissionRequest decision control

The permissionRequest hook fires before the permission service runs—before rule checks, session approvals, auto-allow/auto-deny, and user prompting. If hooks return behavior: "allow" or "deny", that decision short-circuits the normal permission flow. Returning nothing falls through to normal permission handling. Use it to approve or deny tool calls programmatically—especially useful in pipe mode (-p) and CI environments where no interactive prompt is available.

All configured permissionRequest hooks run for each request (except read and hook permission kinds, which short-circuit before hooks). Hook outputs are merged with later hook outputs overriding earlier ones.

Matcher: Optional regex tested against toolName. Anchored as ^(?:pattern)$; must match the full tool name. When set, the hook fires only for matching tool names.

Output JSON to stdout to control the permission decision:

Field	Values	Description
behavior	"allow", "deny"	Whether to approve or deny the tool call.
message	string	Reason fed back to the LLM when denying.
interrupt	boolean	When true combined with "deny", stops the agent entirely.

Return empty output or {} to fall through to the normal permission flow. For command hooks, exit code 2 is treated as a deny; stdout JSON (if any) is merged with {"behavior":"deny"}, and stderr is ignored.

notification hook

The notification hook fires asynchronously when the CLI emits a system notification. These hooks are fire-and-forget: they never block the session, and any errors are logged and skipped.

Input:

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    hook_event_name: "Notification";
    message: string;           // Human-readable notification text
    title?: string;            // Short title (e.g., "Permission needed", "Shell completed")
    notification_type: string; // One of the types listed below
}

Notification types:

Type	When it fires
shell_completed	A background (async) shell command finishes
shell_detached_completed	A detached shell session completes
agent_completed	A background subagent finishes (completed or failed)
agent_idle	A background agent finishes a turn and enters idle state (waiting for write_agent)
permission_prompt	The agent requests permission to execute a tool
elicitation_dialog	The agent requests additional information from the user

Output:

{
    additionalContext?: string; // Injected into the session as a user message
}

If additionalContext is returned, the text is injected into the session as a prepended user message. This can trigger further agent processing if the session is idle. Return {} or empty output to take no action.

Matcher: Optional regex on notification_type. The pattern is anchored as ^(?:pattern)$. Omit matcher to receive all notification types.

Tool names for hook matching

Tool name	Description
ask_user	Ask the user a clarifying question.
bash	Execute shell commands (Unix).
create	Create new files.
edit	Modify file contents.
glob	Find files by pattern.
grep	Search file contents.
powershell	Execute shell commands (Windows).
task	Run subagent tasks.
view	Read file contents.
web_fetch	Fetch web pages.

If multiple hooks of the same type are configured, they execute in order. For preToolUse, if any hook returns "deny", the tool is blocked. For postToolUseFailure command hooks, exiting with code 2 causes stderr to be returned as recovery guidance for the assistant. Hook failures (non-zero exit codes or timeouts) are logged and skipped—they never block agent execution.

Further reading

• Using hooks with GitHub Copilot CLI
• Hooks configuration
• GitHub Copilot CLI command reference