Movatterモバイル変換

[0]ホーム
URL:

Skip to main content
GitHub Docs

Hooks configuration

Find information about configuring hooks for use with GitHub Copilot CLI and Copilot coding agent.

This reference article describes the available hook types with examples, including their input and output formats, script best practices, and advanced patterns for logging, security enforcement, and external integrations. For general information about creating hooks, seeUsing hooks with GitHub Copilot agents. For a tutorial on creating hooks for the CLI, seeUsing hooks with Copilot CLI for predictable, policy-compliant execution.

Hook types

Session start hook

Executed when a new agent session begins or when resuming an existing session.

Input JSON:

JSON
{"timestamp":1704614400000,"cwd":"/path/to/project","source":"new","initialPrompt":"Create a new feature"}

Fields:

  • timestamp: Unix timestamp in milliseconds
  • cwd: Current working directory
  • source: Either"new" (new session),"resume" (resumed session), or"startup"
  • initialPrompt: The user's initial prompt (if provided)

Output: Ignored (no return value processed)

Example hook:

JSON
{"type":"command","bash":"./scripts/session-start.sh","powershell":"./scripts/session-start.ps1","cwd":"scripts","timeoutSec":30}

Example script (Bash):

Shell
#!/bin/bashINPUT=$(cat)SOURCE=$(echo "$INPUT" | jq -r '.source')TIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp')echo "Session started from $SOURCE at $TIMESTAMP" >> session.log

Session end hook

Executed when the agent session completes or is terminated.

Input JSON:

JSON
{"timestamp":1704618000000,"cwd":"/path/to/project","reason":"complete"}

Fields:

  • timestamp: Unix timestamp in milliseconds
  • cwd: Current working directory
  • reason: One of"complete","error","abort","timeout", or"user_exit"

Output: Ignored

Example script:

Shell
#!/bin/bashINPUT=$(cat)REASON=$(echo "$INPUT" | jq -r '.reason')echo "Session ended: $REASON" >> session.log#Cleanup temporary filesrm -rf /tmp/session-*

User prompt submitted hook

Executed when the user submits a prompt to the agent.

Input JSON:

JSON
{"timestamp":1704614500000,"cwd":"/path/to/project","prompt":"Fix the authentication bug"}

Fields:

  • timestamp: Unix timestamp in milliseconds
  • cwd: Current working directory
  • prompt: The exact text the user submitted

Output: Ignored (prompt modification not currently supported in customer hooks)

Example script:

Shell
#!/bin/bashINPUT=$(cat)PROMPT=$(echo "$INPUT" | jq -r '.prompt')TIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp')#Log to a structured fileecho "$(date -d @$((TIMESTAMP/1000))): $PROMPT" >> prompts.log

Pre-tool use hook

Executed before the agent uses any tool (such asbash,edit,view). This is the most powerful hook as it canapprove or deny tool executions.

Input JSON:

JSON
{"timestamp":1704614600000,"cwd":"/path/to/project","toolName":"bash","toolArgs":"{\"command\":\"rm -rf dist\",\"description\":\"Clean build directory\"}"}

Fields:

  • timestamp: Unix timestamp in milliseconds
  • cwd: Current working directory
  • toolName: Name of the tool being invoked (such as "bash", "edit", "view", "create")
  • toolArgs: JSON string containing the tool's arguments

Output JSON (optional):

JSON
{"permissionDecision":"deny","permissionDecisionReason":"Destructive operations require approval"}

Output fields:

  • permissionDecision: Either"allow","deny", or"ask" (only"deny" is currently processed)
  • permissionDecisionReason: Human-readable explanation for the decision

Example hook to block dangerous commands:

Shell
#!/bin/bashINPUT=$(cat)TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')TOOL_ARGS=$(echo "$INPUT" | jq -r '.toolArgs')#Log the tool useecho "$(date): Tool=$TOOL_NAME Args=$TOOL_ARGS" >> tool-usage.log#Checkfor dangerous patternsif echo "$TOOL_ARGS" | grep -qE "rm -rf /|format|DROP TABLE"; then  echo '{"permissionDecision":"deny","permissionDecisionReason":"Dangerous command detected"}'  exit 0fi#Allow by default (or omit output to allow)echo '{"permissionDecision":"allow"}'

Example hook to enforce file permissions:

Shell
#!/bin/bashINPUT=$(cat)TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')#Only allow editing specific directoriesif [ "$TOOL_NAME" = "edit" ]; then  PATH_ARG=$(echo "$INPUT" | jq -r '.toolArgs' | jq -r '.path')  if [[ ! "$PATH_ARG" =~ ^(src/|test/) ]]; then    echo '{"permissionDecision":"deny","permissionDecisionReason":"Can only edit files in src/ or test/ directories"}'    exit 0  fifi#Allow all other tools

Post-tool use hook

Executed after a tool completes execution (whether successful or failed).

Example input JSON:

JSON
{"timestamp":1704614700000,"cwd":"/path/to/project","toolName":"bash","toolArgs":"{\"command\":\"npm test\"}","toolResult":{"resultType":"success","textResultForLlm":"All tests passed (15/15)"}}

Fields:

  • timestamp: Unix timestamp in milliseconds
  • cwd: Current working directory
  • toolName: Name of the tool that was executed
  • toolArgs: JSON string containing the tool's arguments
  • toolResult: Result object containing:
    • resultType: Either"success","failure", or"denied"
    • textResultForLlm: The result text shown to the agent

Output: Ignored (result modification is not currently supported)

Example script that logs tool execution statistics to a CSV file:

This script logs tool execution statistics to a CSV file and sends an email alert when a tool fails.

Shell
#!/bin/bashINPUT=$(cat)TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')RESULT_TYPE=$(echo "$INPUT" | jq -r '.toolResult.resultType')#Track statisticsecho "$(date),${TOOL_NAME},${RESULT_TYPE}" >> tool-stats.csv#Alert on failuresif [ "$RESULT_TYPE" = "failure" ]; then  RESULT_TEXT=$(echo "$INPUT" | jq -r '.toolResult.textResultForLlm')  echo "FAILURE: $TOOL_NAME - $RESULT_TEXT" | mail -s "Agent Tool Failed" admin@example.comfi

Error occurred hook

Executed when an error occurs during agent execution.

Example input JSON:

JSON
{"timestamp":1704614800000,"cwd":"/path/to/project","error":{"message":"Network timeout","name":"TimeoutError","stack":"TimeoutError: Network timeout\n    at ..."}}

Fields:

  • timestamp: Unix timestamp in milliseconds
  • cwd: Current working directory
  • error: Error object containing:
    • message: Error message
    • name: Error type/name
    • stack: Stack trace (if available)

Output: Ignored (error handling modification is not currently supported)

Example script that extracts error details to a log file:

Shell
#!/bin/bashINPUT=$(cat)ERROR_MSG=$(echo "$INPUT" | jq -r '.error.message')ERROR_NAME=$(echo "$INPUT" | jq -r '.error.name')echo "$(date): [$ERROR_NAME] $ERROR_MSG" >> errors.log

Script best practices

Reading input

This example script reads JSON input from stdin into a variable, then usesjq to extract thetimestamp andcwd fields.

Bash:

Shell
#!/bin/bash#Read JSON from stdinINPUT=$(cat)#Parse with jqTIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp')CWD=$(echo "$INPUT" | jq -r '.cwd')

PowerShell:

PowerShell
# Read JSON from stdin$input = [Console]::In.ReadToEnd() |ConvertFrom-Json# Access properties$timestamp =$input.timestamp$cwd =$input.cwd

Outputting JSON

This example script shows how to output valid JSON from your hook script. Usejq -c in Bash for compact single-line output, orConvertTo-Json -Compress in PowerShell.

Bash:

Shell
#!/bin/bash#Use jq to compact the JSON output to a single lineecho '{"permissionDecision":"deny","permissionDecisionReason":"Security policy violation"}' | jq -c#Or construct with variablesREASON="Too dangerous"jq -n --arg reason "$REASON" '{permissionDecision: "deny", permissionDecisionReason: $reason}'

PowerShell:

PowerShell
# Use ConvertTo-Json to compact the JSON output to a single line$output =@{    permissionDecision ="deny"    permissionDecisionReason ="Security policy violation"}$output |ConvertTo-Json-Compress

Error handling

This script example demonstrates how to handle errors in hook scripts.

Bash:

Shell
#!/bin/bashset -e  # Exit on errorINPUT=$(cat)#... process input ...#Exit with 0for successexit 0

PowerShell:

PowerShell
$ErrorActionPreference ="Stop"try {$input = [Console]::In.ReadToEnd() |ConvertFrom-Json# ... process input ...exit0}catch {Write-Error$_.Exception.Messageexit1}

Handling timeouts

Hooks have a default timeout of 30 seconds. For longer operations, increasetimeoutSec:

JSON
{"type":"command","bash":"./scripts/slow-validation.sh","timeoutSec":120}

Advanced patterns

Multiple hooks of the same type

You can define multiple hooks for the same event. They execute in order:

JSON
{"version":1,"hooks":{"preToolUse":[{"type":"command","bash":"./scripts/security-check.sh","comment":"Security validation - runs first"},{"type":"command","bash":"./scripts/audit-log.sh","comment":"Audit logging - runs second"},{"type":"command","bash":"./scripts/metrics.sh","comment":"Metrics collection - runs third"}]}}

Conditional logic in scripts

Example: Only block specific tools

Shell
#!/bin/bashINPUT=$(cat)TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')#Only validate bash commandsif [ "$TOOL_NAME" != "bash" ]; then  exit 0  # Allow all non-bash toolsfi#Check bashcommandfor dangerous patternsCOMMAND=$(echo "$INPUT" | jq -r '.toolArgs' | jq -r '.command')if echo "$COMMAND" | grep -qE "rm -rf|sudo|mkfs"; then  echo '{"permissionDecision":"deny","permissionDecisionReason":"Dangerous system command"}'fi

Structured logging

Example: JSON Lines format

Shell
#!/bin/bashINPUT=$(cat)TIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp')TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')RESULT_TYPE=$(echo "$INPUT" | jq -r '.toolResult.resultType')#Output structuredlog entryjq -n \  --arg ts "$TIMESTAMP" \  --arg tool "$TOOL_NAME" \  --arg result "$RESULT_TYPE" \  '{timestamp: $ts, tool: $tool, result: $result}' >> logs/audit.jsonl

Integration with external systems

Example: Send alerts to Slack

Shell
#!/bin/bashINPUT=$(cat)ERROR_MSG=$(echo "$INPUT" | jq -r '.error.message')WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"curl -X POST "$WEBHOOK_URL" \  -H 'Content-Type: application/json' \  -d "{\"text\":\"Agent Error: $ERROR_MSG\"}"

Example use cases

Compliance audit trail

Log all agent actions for compliance requirements by utilizing log scripts:

JSON
{"version":1,"hooks":{"sessionStart":[{"type":"command","bash":"./audit/log-session-start.sh"}],"userPromptSubmitted":[{"type":"command","bash":"./audit/log-prompt.sh"}],"preToolUse":[{"type":"command","bash":"./audit/log-tool-use.sh"}],"postToolUse":[{"type":"command","bash":"./audit/log-tool-result.sh"}],"sessionEnd":[{"type":"command","bash":"./audit/log-session-end.sh"}]}}

Cost tracking

Track tool usage for cost allocation:

Shell
#!/bin/bashINPUT=$(cat)TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')TIMESTAMP=$(echo "$INPUT" | jq -r '.timestamp')USER=${USER:-unknown}echo "$TIMESTAMP,$USER,$TOOL_NAME" >> /var/log/copilot/usage.csv

Code quality enforcement

Prevent commits that violate code standards:

Shell
#!/bin/bashINPUT=$(cat)TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName')if [ "$TOOL_NAME" = "edit" ] || [ "$TOOL_NAME" = "create" ]; then  #Run linter before allowing edits  npm run lint-staged  if [ $? -ne 0 ]; then    echo '{"permissionDecision":"deny","permissionDecisionReason":"Code does not pass linting"}'  fifi

Notification system

Send notifications on important events:

Shell
#!/bin/bashINPUT=$(cat)PROMPT=$(echo "$INPUT" | jq -r '.prompt')#Notify on production-related promptsif echo "$PROMPT" | grep -iq "production"; then  echo "ALERT: Production-related prompt: $PROMPT" | mail -s "Agent Alert" team@example.comfi
[8]ページ先頭
©2009-2026 Movatter.jp