Copilot CLI: Add docs for user-level hooks and improve existing hooks docs (#61024)

Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com>

Author: hubwriter

content/copilot/concepts/agents/cloud-agent/about-cloud-agent.md

@@ -20,10 +20,9 @@ contentType: concepts
 category:
   - Learn about Copilot
 ---
-<!-- expires 2026-04-21 -->
-<!-- When this expires, search all references to {% data variables.copilot.copilot_cloud_agent_tmp %} in docs-internal and replace with {% data variables.copilot.copilot_cloud_agent %} -->
-## Overview of {% data variables.copilot.copilot_cloud_agent_tmp %}
-<!-- end expires 2026-04-21 -->
+
+## Overview of {% data variables.copilot.copilot_cloud_agent %}
+
 With {% data variables.copilot.copilot_cloud_agent %}, {% data variables.product.prodname_copilot %} can work independently in the background to complete tasks, just like a human developer.
 
 {% data variables.copilot.copilot_cloud_agent %} can:
@@ -137,7 +136,7 @@ You can customize {% data variables.copilot.copilot_cloud_agent %} in a number o
 * **Custom instructions**: Custom instructions allow you to give {% data variables.product.prodname_copilot_short %} additional context on your project and how to build, test and validate its changes. For more information, see [AUTOTITLE](/copilot/how-tos/configure-custom-instructions/add-repository-instructions).
 * **Model Context Protocol (MCP) servers**: MCP servers allow you to give {% data variables.product.prodname_copilot_short %} access to different data sources and tools. For more information, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/extend-cloud-agent-with-mcp).
 * **{% data variables.copilot.custom_agents_caps_short %}**: {% data variables.copilot.custom_agents_caps_short %} allow you to create different specialized versions of {% data variables.product.prodname_copilot_short %} for different tasks. For example, you could customize {% data variables.product.prodname_copilot_short %} to be an expert frontend engineer following your team's guidelines. For more information, see [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-custom-agents).
-* **Hooks**: Hooks allow you to execute custom shell commands at key points during agent execution, enabling you to add validation, logging, security scanning, or workflow automation. For more information, see [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-hooks).
+* **Hooks**: Hooks allow you to execute custom shell commands at key points during agent execution, enabling you to add validation, logging, security scanning, or workflow automation. For more information, see [AUTOTITLE](/copilot/concepts/agents/hooks).
 * **Skills**: Skills allow you to enhance the ability of {% data variables.product.prodname_copilot_short %} to perform specialized tasks with instructions, scripts, and resources. For more information, see [AUTOTITLE](/copilot/concepts/agents/about-agent-skills).
 
 ## Limitations of {% data variables.copilot.copilot_cloud_agent %}

content/copilot/concepts/agents/cloud-agent/index.md

@@ -9,7 +9,6 @@ children:
   - /about-cloud-agent
   - /agent-management
   - /about-custom-agents
-  - /about-hooks
   - /access-management
   - /mcp-and-cloud-agent
   - /risks-and-mitigations

content/copilot/concepts/agents/copilot-cli/about-copilot-cli.md

@@ -174,7 +174,7 @@ You can customize {% data variables.copilot.copilot_cli %} in a number of ways:
 * **Custom instructions**: Custom instructions allow you to give {% data variables.product.prodname_copilot_short %} additional context on your project and how to build, test and validate its changes. All custom instruction files now combine instead of using priority-based fallbacks. For more information, see [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions).
 * **Model Context Protocol (MCP) servers**: MCP servers allow you to give {% data variables.product.prodname_copilot_short %} access to different data sources and tools. For more information, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/use-copilot-cli#add-an-mcp-server).
 * **{% data variables.copilot.custom_agents_caps_short %}**: {% data variables.copilot.custom_agents_caps_short %} allow you to create different specialized versions of {% data variables.product.prodname_copilot_short %} for different tasks. For example, you could customize {% data variables.product.prodname_copilot_short %} to be an expert frontend engineer following your team's guidelines. {% data variables.copilot.copilot_cli %} includes specialized {% data variables.copilot.custom_agents_short %} that it automatically delegates common tasks to. For more information, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/use-copilot-cli#use-custom-agents).
-* **Hooks**: Hooks allow you to execute custom shell commands at key points during agent execution, enabling you to add validation, logging, security scanning, or workflow automation. See [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-hooks).
+* **Hooks**: Hooks allow you to execute custom shell commands at key points during agent execution, enabling you to add validation, logging, security scanning, or workflow automation. See [AUTOTITLE](/copilot/concepts/agents/hooks).
 * **Skills**: Skills allow you to enhance the ability of {% data variables.product.prodname_copilot_short %} to perform specialized tasks with instructions, scripts, and resources. For more information, see [AUTOTITLE](/copilot/concepts/agents/about-agent-skills).
 * **{% data variables.copilot.copilot_memory %}**: {% data variables.copilot.copilot_memory %} allows {% data variables.product.prodname_copilot_short %} to build a persistent understanding of your repository by storing "memories", which are pieces of information about coding conventions, patterns, and preferences that {% data variables.product.prodname_copilot_short %} deduces as it works. This reduces the need to repeatedly explain context in your prompts and makes future sessions more productive. For more information, see [AUTOTITLE](/copilot/concepts/agents/copilot-memory).
 

content/copilot/concepts/agents/copilot-cli/comparing-cli-features.md

@@ -271,8 +271,7 @@ Avoid hooks when:
 
 See:
 * [AUTOTITLE](/copilot/how-tos/copilot-cli/use-hooks)
-* [AUTOTITLE](/copilot/reference/hooks-configuration)
-* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-hooks-reference)
+* [AUTOTITLE](/copilot/reference/hooks-reference)
 
 ## Subagents
 

…ncepts/agents/cloud-agent/about-hooks.md content/copilot/concepts/agents/hooks.mdcontent/copilot/concepts/agents/cloud-agent/about-hooks.md renamed to content/copilot/concepts/agents/hooks.md content/copilot/concepts/agents/cloud-agent/about-hooks.md renamed to content/copilot/concepts/agents/hooks.md

@@ -1,33 +1,34 @@
 ---
-title: About hooks
+title: About hooks for {% data variables.product.prodname_copilot %}
 shortTitle: Hooks
 intro: 'Extend and customize {% data variables.product.prodname_copilot %} agent behavior by executing custom shell commands at key points during agent execution.'
-product: '{% data reusables.gated-features.copilot-cloud-agent %}<br><a href="https://github.com/features/copilot/plans?ref_product=copilot&ref_type=purchase&ref_style=button" target="_blank" class="btn btn-primary mt-3 mr-3 no-underline"><span>Sign up for {% data variables.product.prodname_copilot_short %}</span> {% octicon "link-external" height:16 %}</a>'
 versions:
   feature: copilot
 contentType: concepts
 category:
   - Configure Copilot
 redirect_from:
   - /copilot/concepts/agents/coding-agent/about-hooks
+  - /copilot/concepts/agents/cloud-agent/about-hooks
+  - /copilot/concepts/agents/about-hooks
 ---
 
-## About hooks
+## What are hooks?
 
-Hooks enable you to execute custom shell commands at strategic points in an agent's workflow, such as when an agent session starts or ends, or before and after a prompt is entered or a tool is called.
+Hooks are a way of executing custom shell commands at strategic points in an agent's workflow, such as when an agent session starts or ends, when you enter a prompt, or when a tool is called.
 
 Hooks receive detailed information about agent actions via JSON input, enabling context-aware automation. For example, you can use hooks to:
 
 * Programmatically approve or deny tool executions.
-* Utilize built-in security features like secret scanning to prevent credential leaks.
+* Use built-in security features like secret scanning to prevent credential leaks.
 * Implement custom validation rules and audit logging for compliance.
 
-{% data variables.product.prodname_copilot_short %} agents support hooks stored in JSON files in your repository at `.github/hooks/*.json`.
-
 Hooks are available for use with:
 
-* {% data variables.copilot.copilot_cloud_agent %} on {% data variables.product.github %}
-* {% data variables.copilot.copilot_cli %} in the terminal
+* **{% data variables.copilot.copilot_cloud_agent %}** on {% data variables.product.github %}.
+* **{% data variables.copilot.copilot_cli %}** in your terminal.
+
+You define hooks in JSON files, stored in your repository at `.github/hooks/*.json`. These apply whenever {% data variables.product.prodname_copilot_short %} agents are used in the repository. {% data variables.copilot.copilot_cli_short %} also supports personal hooks that you store in your home directory at `~/.copilot/hooks/*.json`. These apply whenever you use {% data variables.copilot.copilot_cli_short %}.
 
 ## Types of hooks
 
@@ -42,7 +43,7 @@ The following types of hooks are available:
 * **subagentStop**: Executed when a subagent completes, before returning results to the parent agent.
 * **errorOccurred**: Executed when an error occurs during agent execution. Can be used to log errors for debugging, send notifications, track error patterns, and generate reports.
 
-To see a complete reference of hook types with example use cases, best practices, and advanced patterns, see [AUTOTITLE](/copilot/reference/hooks-configuration).
+To see a complete reference of hook types with example use cases, best practices, and advanced patterns, see [AUTOTITLE](/copilot/reference/hooks-reference).
 
 ## Hook configuration format
 
@@ -162,4 +163,6 @@ To ensure security is maintained when using hooks, keep the following considerat
 
 ## Next steps
 
-To start creating hooks, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/use-hooks).
+To start creating hooks, see:
+* [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/use-hooks) for {% data variables.copilot.copilot_cloud_agent %}
+* [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/use-hooks) for {% data variables.copilot.copilot_cli %}

content/copilot/concepts/agents/index.md

@@ -10,6 +10,7 @@ children:
   - /copilot-cli
   - /code-review
   - /copilot-memory
+  - /hooks
   - /about-third-party-agents
   - /openai-codex
   - /anthropic-claude

content/copilot/get-started/features.md

@@ -45,7 +45,7 @@ These features can work autonomously without direct human supervision. However,
 
 A command line interface that lets you use {% data variables.product.prodname_copilot_short %} in your terminal. Use the CLI to add features or fix bugs, then create a pull request. Start {% data variables.product.prodname_copilot_short %} working on a task in your terminal, then continue working in the same session on {% data variables.product.prodname_dotcom_the_website %}, or on your mobile. See [AUTOTITLE](/copilot/concepts/agents/about-copilot-cli).
 
-### {% data variables.copilot.copilot_cloud_agent_tmp %}
+### {% data variables.copilot.copilot_cloud_agent %}
 
 An autonomous AI agent that can research a repository, create an implementation plan, and make code changes on a branch. You can review the diff, iterate, and create a pull request when you're ready. You can also assign a {% data variables.product.github %} issue to {% data variables.product.prodname_copilot_short %} or ask it to open a pull request directly to complete a task. See [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent).
 

content/copilot/how-tos/copilot-cli/customize-copilot/use-hooks.md

@@ -16,18 +16,95 @@ docsTeamMetrics:
 
 {% data reusables.copilot.cloud-agent.hooks-intro %}
 
-## Creating a hook in a repository on {% data variables.product.github %}
+## Prerequisite
+
+**For Windows only:** The examples in this article use PowerShell. If you're using Windows, you must have PowerShell 7.0 or later installed and in your PATH. You can check your PowerShell version by running `pwsh --version` in a terminal. To install PowerShell, run `winget install Microsoft.PowerShell` then restart your terminal.
+
+## Creating a repository-level hook
+
+1. Create a new `NAME.json` file (where `NAME` describes the purpose of the file) in the `.github/hooks/` folder of your repository.
 
 {% data reusables.copilot.cloud-agent.create-hooks-instructions %}
 
+## Creating a user-level hook
+
+User-level hooks are configured just like repository-level hooks, but the hook files are stored locally, below your home directory.
+
+The following examples for macOS and Windows show how to configure hooks that will play a sound and display a message box when the CLI finishes responding to a prompt, and when you quit {% data variables.copilot.copilot_cli_short %}. Hooks for Linux would be similar to the macOS example, but would use Linux tools for playing sounds and displaying messages.
+
+### User-level example for macOS
+
+1. Create a file called `notification-hooks.json` in `~/.copilot/hooks/`.
+
+   > [!NOTE]
+   > If `COPILOT_HOME` is set, create the file in `$COPILOT_HOME/hooks/`.
+
+1. Copy and paste the following JSON into the file:
+
+   ```json copy
+   {
+     "version": 1,
+     "hooks": {
+       "agentStop": [
+         {
+           "type": "command",
+           "bash": "osascript -e 'do shell script \"afplay /System/Library/Sounds/Funk.aiff &> /dev/null &\"' -e 'display dialog \"Agent stopped.\" with title \"Hook-generated message\" buttons {\"OK\"} default button \"OK\"'",
+           "timeoutSec": 5
+         }
+       ],
+       "sessionEnd": [
+         {
+           "type": "command",
+           "bash": "osascript -e 'do shell script \"afplay /System/Library/Sounds/Funk.aiff &> /dev/null &\"' -e 'display dialog \"Session ended.\" with title \"Hook-generated message\" buttons {\"OK\"} default button \"OK\"'",
+           "timeoutSec": 5
+         }
+       ]
+     }
+   }
+   ```
+
+{% data reusables.copilot.cloud-agent.hooks-example-steps %}
+
+### User-level example for Windows
+
+1. Create a file called `notification-hooks.json` in `%USERPROFILE%\.copilot\hooks\`.
+
+   > [!NOTE]
+   > If `COPILOT_HOME` is set, create the file in `%COPILOT_HOME%\hooks\`.
+
+1. Copy and paste the following JSON into the file:
+
+   ```json copy
+   {
+     "version": 1,
+     "hooks": {
+       "agentStop": [
+         {
+           "type": "command",
+           "powershell": "Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Agent stopped.', 'Hook-generated message') | Out-Null",
+           "timeoutSec": 5
+         }
+       ],
+       "sessionEnd": [
+         {
+           "type": "command",
+           "powershell": "Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Session ended.', 'Hook-generated message') | Out-Null",
+           "timeoutSec": 5
+         }
+       ]
+     }
+   }
+   ```
+
+{% data reusables.copilot.cloud-agent.hooks-example-steps %}
+
 ## Troubleshooting
 
 {% data reusables.copilot.cloud-agent.troubleshoot-hooks %}
 
 ## Further reading
 
-* [AUTOTITLE](/copilot/reference/hooks-configuration)
+* [AUTOTITLE](/copilot/reference/hooks-reference)
 * [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-cloud-agent)
 * [AUTOTITLE](/copilot/concepts/agents/about-copilot-cli)
 * [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment)
-* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-hooks-reference)

content/copilot/how-tos/copilot-cli/index.md

@@ -42,7 +42,7 @@ children:
   - /content/copilot/reference/copilot-cli-reference/cli-command-reference
   - /content/copilot/reference/copilot-cli-reference/cli-plugin-reference
   - /content/copilot/reference/copilot-cli-reference/cli-programmatic-reference
-  - /content/copilot/reference/hooks-configuration
+  - /content/copilot/reference/hooks-reference
   - /content/copilot/responsible-use/copilot-cli
   - /content/copilot/tutorials/copilot-cli-hooks
   - /customize-copilot/add-custom-instructions

content/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/use-hooks.md

@@ -5,7 +5,7 @@ intro: 'Run automated checks—like linting, formatting, or security scans—at
 versions:
   feature: copilot
 contentType: how-tos
-category: 
+category:
   - Configure Copilot
 redirect_from:
   - /copilot/how-tos/use-copilot-agents/coding-agent/use-hooks
@@ -16,6 +16,11 @@ redirect_from:
 
 ## Creating a hook in a repository on {% data variables.product.github %}
 
+1. Create a new `NAME.json` file (where `NAME` describes the purpose of the file) in the `.github/hooks/` folder of your repository.
+
+   > [!IMPORTANT]
+   > The hooks configuration file **must be present** on your repository's default branch to be used by {% data variables.copilot.copilot_cloud_agent %}.
+
 {% data reusables.copilot.cloud-agent.create-hooks-instructions %}
 
 ## Troubleshooting
@@ -24,7 +29,7 @@ redirect_from:
 
 ## Further reading
 
-* [AUTOTITLE](/copilot/reference/hooks-configuration)
+* [AUTOTITLE](/copilot/reference/hooks-reference)
 * [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-cloud-agent)
 * [AUTOTITLE](/copilot/concepts/agents/about-copilot-cli)
 * [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment)