GitHub Copilot Guide: Hooks for Permissions, Auditing, and Recovery

InYourLeague Research · 2026-08-30

Answer in brief

GitHub Copilot hooks run external commands at defined lifecycle points in Copilot CLI and Copilot cloud agent. They can enforce pre-tool permission decisions, create audit records, and trigger cleanup or alerts, but configuration sources, supported events, and output persistence differ by surface.

Key facts at a glance

Failure modes and verification

FAQ

Where can GitHub Copilot hook configuration be stored?

Repository hooks use .github/hooks/*.json. Copilot CLI also supports user directories, inline settings, installed plugins, and administrator policy sources. Copilot cloud agent discovers only repository hook files by default. See the official hooks reference.

Are the same hook events available in Copilot CLI and Copilot cloud agent?

No. Copilot CLI supports all events described in the hooks reference, while Copilot cloud agent fires only a subset. Confirm the target surface before relying on a lifecycle event.

Which hook can approve or deny tool execution?

preToolUse can programmatically approve or deny a proposed tool execution. Copilot cloud agent runs with tool permissions pre-granted and does not show permission dialogs, so this control is programmatic rather than interactive. See the official hooks reference.

Which events are useful for audit logging?

sessionStart, sessionEnd, userPromptSubmitted, preToolUse, postToolUse, stop events, and errorOccurred can record different execution stages. postToolUse runs after both successful and failed tool executions. Logs should exclude secrets and unnecessary prompt content.

Do hooks automatically roll back failed changes?

The supplied documentation does not define automatic rollback behavior. Events such as errorOccurred, sessionEnd, and a resumed sessionStart can launch custom recovery, cleanup, or validation commands, but any rollback logic must be designed and tested explicitly.

How can cloud-agent audit output be retained?

Files in the ephemeral Linux sandbox are discarded when the job ends. Output that must persist must be sent through an http hook entry. Destinations outside GitHub and Copilot require an administrator-configured firewall allow rule.

What happens when hook configuration is invalid?

For directory-loaded files, an invalid individual hook is dropped and logged while valid siblings continue loading. Invalid JSON, an unsupported version, or a non-array event list rejects the whole file. An item-level error in inline settings.json hooks rejects the entire hooks field.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-08-30

Extended guide

GitHub Copilot hooks execute external commands at defined points in an agent session. They are available in Copilot CLI and Copilot cloud agent, but the two surfaces differ in configuration discovery, supported events, execution environment, and output persistence. Hooks can gate tool calls, capture audit data, and initiate cleanup or alerts. The documentation does not define hooks as an automatic rollback mechanism.

Scope and hook locations

Configuration uses JSON with version: 1 and a hooks object whose event keys contain arrays of hook definitions. Command hooks run synchronously and block agent execution, so they should have bounded timeouts and remain fast. GitHub recommends keeping execution under five seconds when possible.

Operational design

1. Choose the enforcement scope. Put shared repository controls in .github/hooks/*.json. Use CLI user hooks for personal behavior and administrator-installed policy hooks for machine-wide requirements. Review every combined source because hooks for the same event do not replace one another.
2. Map each event to one responsibility. Use sessionStart to initialize or validate state, including when a session resumes. Use userPromptSubmitted to record requests, preToolUse to evaluate the next tool call, and postToolUse to capture its outcome. Use stop and session-end events for final records and cleanup.
3. Make permission decisions safely. Treat hook input as untrusted JSON, validate its structure, sanitize values, and apply correct shell escaping. Never include passwords, tokens, or unnecessary prompt content in commands or logs. In Copilot cloud agent, tool permissions are pre-granted and no permission dialogs are shown, so a preToolUse policy is programmatic rather than interactive. See the hooks reference.
4. Build a bounded audit trail. Record only the identifiers, decisions, timestamps, outcomes, and errors required by the audit policy. Set timeoutSec, protect scripts and logs with suitable permissions, and ensure logging failures do not create an uncontrolled delay. Test both approval and denial paths and both successful and failed tool results.
5. Design recovery explicitly. Use errorOccurred for error records or alerts, sessionEnd for cleanup and reports, and sessionStart to revalidate state after resumption. These events can launch custom recovery procedures, but they do not themselves restore files or reverse completed actions. Define any rollback command, eligibility check, and audit record as part of the hook implementation.

Cloud-agent files are discarded when the job ends. Output that must survive the job must be sent through an http hook entry; destinations outside GitHub and Copilot require an administrator-configured firewall allow rule. Validate this export path without recording sandbox tokens. For directory-loaded configuration, an invalid individual hook is dropped and logged while valid siblings continue to load. Invalid JSON, an unsupported version, or a non-array event list rejects the entire file. Inline settings.json hooks are stricter: an item-level validation error rejects the whole hooks field.

Model availability note: The official source does not specify a selectable model ID.