GitHub Copilot hooks: .github/hooks/*.json for Copilot CLI and the cloud agent

• Copilot cloud agent: .github/hooks/*.json in the cloned repository. The file must be on the default branch.
• Copilot CLI, repository: .github/hooks/*.json.
• Copilot CLI, user: ~/.copilot/hooks/ (or $COPILOT_HOME/hooks/ when that is set).
• Copilot CLI, policy: /etc/github-copilot/policy.d/*.json on Linux and macOS, C:\ProgramData\GitHub\Copilot\policy.d\*.json on Windows. Policy hooks cannot be turned off with disableAllHooks.
• Plugins ship their own hooks.json.

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/pre-tool-policy.sh",
        "powershell": "./scripts/pre-tool-policy.ps1",
        "cwd": ".github/hooks",
        "timeoutSec": 15
      }
    ]
  }
}

The hook allows the call by doing nothing. To deny it, print a decision object on stdout:

{"permissionDecision":"deny","permissionDecisionReason":"Privilege escalation requires manual approval."}

The input arrives as JSON on stdin. toolArgs is a JSON string, not an object, so parse it a second time before reading fields like command.

• sessionStart and sessionEnd
• userPromptSubmitted and userPromptTransformed
• preToolUse, postToolUse and postToolUseFailure
• permissionRequest
• subagentStart and subagentStop
• agentStop
• preCompact
• notification
• errorOccurred

The cloud agent how-to lists six of these: sessionStart, sessionEnd, userPromptSubmitted, preToolUse, postToolUse and errorOccurred.

• Files use version 1. Invalid JSON or a wrong version rejects the whole file.
• In the cloud agent a preToolUse decision of "ask" is treated as "deny", because no user is there to answer.
• The cloud agent ignores the powershell command, because it runs on Linux.
• timeoutSec defaults to 30 seconds.