diff --git a/content/copilot/concepts/agents/copilot-cli/about-remote-access.md b/content/copilot/concepts/agents/copilot-cli/about-remote-access.md index e61bd5be441e..5ba7f361ee8e 100644 --- a/content/copilot/concepts/agents/copilot-cli/about-remote-access.md +++ b/content/copilot/concepts/agents/copilot-cli/about-remote-access.md @@ -12,7 +12,7 @@ docsTeamMetrics: - copilot-cli --- -This article explains the concepts around remote access to {% data variables.copilot.copilot_cli_short %} sessions. For instructions on how to enable remote access, see [AUTOTITLE](/copilot/how-tos/copilot-cli/steer-remotely). +This article explains the concepts around remote access to {% data variables.copilot.copilot_cli_short %} sessions. For instructions on how to enable remote access, see [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely). ## Introduction @@ -64,9 +64,9 @@ When connected to a session remotely from {% data variables.product.prodname_dot If the connection between your local machine and {% data variables.product.prodname_dotcom %} is temporarily lost—for example, due to a network interruption—you can continue using the session remotely as soon as the connection is restored. -You can use the `/keep-alive` slash command to prevent your machine from going to sleep. See [Preventing your machine from going to sleep](/copilot/how-tos/copilot-cli/steer-remotely#preventing-your-machine-from-going-to-sleep). +You can use the `/keep-alive` slash command to prevent your machine from going to sleep. See [Preventing your machine from going to sleep](/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely#preventing-your-machine-from-going-to-sleep). -If you closed a session that had remote access enabled, when you resume the session—either using `copilot --continue` or `copilot --resume=ID`—you must re-enable remote access. For more information, see [AUTOTITLE](/copilot/how-tos/copilot-cli/steer-remotely#resuming-a-session-with-remote-access). +If you closed a session that had remote access enabled, when you resume the session—either using `copilot --continue` or `copilot --resume=ID`—you must re-enable remote access. For more information, see [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely#resuming-a-session-with-remote-access). ## Visibility of remote access sessions diff --git a/content/copilot/concepts/agents/copilot-cli/cancel-and-roll-back.md b/content/copilot/concepts/agents/copilot-cli/cancel-and-roll-back.md index e25d30058598..58ea72954445 100644 --- a/content/copilot/concepts/agents/copilot-cli/cancel-and-roll-back.md +++ b/content/copilot/concepts/agents/copilot-cli/cancel-and-roll-back.md @@ -46,7 +46,7 @@ As a rule of thumb, use Esc when you want to intervene selectively, a While {% data variables.product.prodname_copilot_short %} is inactive and there is no text in the input area, you can press Esc twice to display a list of points in your current session that you can roll back to. Each point corresponds to a snapshot of your workspace that was taken immediately before {% data variables.product.prodname_copilot_short %} started working on the prompt shown in the list. -For full details of how to use the double Esc keypress to roll back changes made during a session, see [AUTOTITLE](/copilot/how-tos/copilot-cli/roll-back-changes). +For full details of how to use the double Esc keypress to roll back changes made during a session, see [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/roll-back-changes). > [!WARNING] > {% data reusables.copilot.copilot-cli.cli-rewind-warning %} diff --git a/content/copilot/concepts/agents/copilot-cli/chronicle.md b/content/copilot/concepts/agents/copilot-cli/chronicle.md index 66376166ea59..f3939633b1d2 100644 --- a/content/copilot/concepts/agents/copilot-cli/chronicle.md +++ b/content/copilot/concepts/agents/copilot-cli/chronicle.md @@ -23,7 +23,7 @@ This session data powers several features: * **Asking questions about your history**: You can ask {% data variables.product.prodname_copilot_short %} questions about your past work, and it will query your session data to answer them. * **The `/chronicle` slash command**: A set of purpose-built subcommands that generate standup reports, personalized tips, and suggestions for improving your custom instructions—all derived from your session history. -This conceptual article explains how session data is stored, and how you can leverage it to enhance your workflow. For a practical guide to resuming a session, asking {% data variables.product.prodname_copilot_short %} about your CLI sessions, and using the `/chronicle` slash command, see [AUTOTITLE](/copilot/how-tos/copilot-cli/chronicle). +This conceptual article explains how session data is stored, and how you can leverage it to enhance your workflow. For a practical guide to resuming a session, asking {% data variables.product.prodname_copilot_short %} about your CLI sessions, and using the `/chronicle` slash command, see [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle). {% data reusables.copilot.copilot-cli.cli-experimental-chronicle %} @@ -92,5 +92,5 @@ To reindex the session store, use the following slash command in an interactive ## Further reading -* [AUTOTITLE](/copilot/how-tos/copilot-cli/chronicle) +* [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle) * [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference) diff --git a/content/copilot/concepts/agents/copilot-cli/comparing-cli-features.md b/content/copilot/concepts/agents/copilot-cli/comparing-cli-features.md index 43f725b0ad1d..68cf236cd539 100644 --- a/content/copilot/concepts/agents/copilot-cli/comparing-cli-features.md +++ b/content/copilot/concepts/agents/copilot-cli/comparing-cli-features.md @@ -269,7 +269,10 @@ Avoid hooks when: ### Find out more about hooks -See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-hooks). +See: +* [AUTOTITLE](/copilot/how-tos/copilot-cli/use-hooks) +* [AUTOTITLE](/copilot/reference/hooks-configuration) +* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-hooks-reference) ## Subagents diff --git a/content/copilot/concepts/agents/copilot-cli/fleet.md b/content/copilot/concepts/agents/copilot-cli/fleet.md index d3993fcad913..dec9ba2bddee 100644 --- a/content/copilot/concepts/agents/copilot-cli/fleet.md +++ b/content/copilot/concepts/agents/copilot-cli/fleet.md @@ -17,7 +17,7 @@ docsTeamMetrics: The `/fleet` slash command in {% data variables.copilot.copilot_cli_short %} is designed to take an implementation plan and break it down into smaller, independent tasks that can be executed in parallel by subagents. This allows for faster completion of complex requests that involve multiple steps. -This article gives an overview of the `/fleet` slash command. For details of how to use it, see [AUTOTITLE](/copilot/how-tos/copilot-cli/speed-up-task-completion). +This article gives an overview of the `/fleet` slash command. For details of how to use it, see [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/speed-up-task-completion). ## How `/fleet` works @@ -70,6 +70,6 @@ For more information about autopilot mode, see [AUTOTITLE](/copilot/concepts/age ## Further reading -* [AUTOTITLE](/copilot/how-tos/copilot-cli/speed-up-task-completion) +* [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/speed-up-task-completion) * [AUTOTITLE](/copilot/how-tos/copilot-cli) * [AUTOTITLE](/copilot/how-tos/use-copilot-agents/use-copilot-cli) diff --git a/content/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing.md b/content/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing.md index e731fe79efbf..78c3d79322ba 100644 --- a/content/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing.md +++ b/content/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing.md @@ -16,7 +16,7 @@ docsTeamMetrics: ## Introduction -Plugins are packages that extend the functionality of {% data variables.copilot.copilot_cli_short %}. You can install a plugin from a marketplace that you have registered with the CLI, from a Git repository, or from a local path. +Plugins are packages that extend the functionality of {% data variables.copilot.copilot_cli_short %}. You can install a plugin from a marketplace that you have registered with the CLI. For more information, see [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about-cli-plugins). @@ -26,8 +26,6 @@ For more information, see [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about Plugins are collected together in marketplaces. A marketplace is a registry of plugins that you can browse and install from. You can add a marketplace to your CLI configuration, which allows you to use the CLI to browse and install plugins from that marketplace—see [Adding plugin marketplaces](#adding-plugin-marketplaces). {% data variables.product.prodname_copilot_short %} comes with two marketplaces already registered by default: `copilot-plugins` and `awesome-copilot`. -Alternatively, you can search for plugin marketplaces online and then add a plugin directly from a repository. - To use the CLI to browse the plugins in one of your registered marketplaces: 1. **Check which marketplaces are currently registered.** @@ -55,11 +53,9 @@ To use the CLI to browse the plugins in one of your registered marketplaces: ## Installing plugins -Typically, you'll install a plugin from one of your registered marketplaces. However, you can also install a plugin directly from a Git repository, or from a local path. - -For information on how to register additional marketplaces, see [Adding and removing plugin marketplaces](#adding-and-removing-plugin-marketplaces). +You can install plugins from a registered marketplace. For information on how to register additional marketplaces, see [Adding plugin marketplaces](#adding-plugin-marketplaces). -### Install from a registered marketplace +To install a plugin, enter: ```shell copy copilot plugin install PLUGIN-NAME@MARKETPLACE-NAME @@ -77,43 +73,6 @@ Alternatively, in an interactive session, enter: /plugin install PLUGIN-NAME@MARKETPLACE-NAME ``` -### Install directly from an online Git repository - -You can install a plugin directly from a repository, rather than doing so using a registered marketplace. - -To install a plugin directly from a repository **on {% data variables.product.prodname_dotcom_the_website %}**, enter: - -```shell copy -copilot plugin install OWNER/REPO -``` - -To install a plugin from **any online Git repository**, enter: - -```shell copy -copilot plugin install URL-OF-GIT-REPO -``` - -For example, `copilot plugin install https://gitlab.com/OWNER/REPO.git`. - -> [!IMPORTANT] -> For these commands to work, the repository must contain a `plugin.json` file in a `.plugin`, `.github/plugin`, or `.claude-plugin` directory, or at the root of the repository. - -To install a plugin directly from a repository on {% data variables.product.prodname_dotcom_the_website %} where the `plugin.json` file is located somewhere other than `.github/plugin`, `.claude-plugin`, or the repository root—for example, if you are installing a plugin directly from a marketplace repository such as [anthropics/claude-code](https://github.com/anthropics/claude-code)—enter: - -```shell copy -copilot plugin install OWNER/REPO:PATH/TO/PLUGIN -``` - -Where `PATH/TO/PLUGIN` is the path from the root of the repository to a directory that contains `plugin.json`, `.github/plugin/plugin.json` or `.claude-plugin/plugin.json`. - -For example, `copilot plugin install anthropics/claude-code:plugins/frontend-design` - -### Install from a local path - -```shell copy -copilot plugin install ./PATH/TO/PLUGIN -``` - ## Managing installed plugins ```bash @@ -122,10 +81,6 @@ copilot plugin update PLUGIN-NAME # Update plugin to latest version copilot plugin uninstall PLUGIN-NAME # Remove plugin completely ``` -## Where plugins are stored - -Plugins installed from a marketplace are stored at: `~/.copilot/installed-plugins/MARKETPLACE/PLUGIN-NAME/`. Plugins installed directly (for example, from a local path) are stored at: `~/.copilot/installed-plugins/_direct/SOURCE-ID/`. - ## Adding plugin marketplaces To add a marketplace to the list of registered marketplaces, enter the following command in the terminal: diff --git a/content/copilot/how-tos/copilot-cli/customize-copilot/use-hooks.md b/content/copilot/how-tos/copilot-cli/customize-copilot/use-hooks.md index 6807feb08dfa..b3e883d7b3f9 100644 --- a/content/copilot/how-tos/copilot-cli/customize-copilot/use-hooks.md +++ b/content/copilot/how-tos/copilot-cli/customize-copilot/use-hooks.md @@ -30,3 +30,4 @@ docsTeamMetrics: * [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) diff --git a/content/copilot/how-tos/copilot-cli/index.md b/content/copilot/how-tos/copilot-cli/index.md index 2d54e41dc6c9..74170d029236 100644 --- a/content/copilot/how-tos/copilot-cli/index.md +++ b/content/copilot/how-tos/copilot-cli/index.md @@ -17,53 +17,62 @@ children: - /cli-getting-started - /cli-best-practices - /set-up-copilot-cli - - /allowing-tools - - /steer-remotely + - /use-copilot-cli - /automate-copilot-cli - /customize-copilot - - /connecting-vs-code - - /use-copilot-cli-agents - /administer-copilot-cli-for-your-enterprise - - /speed-up-task-completion - - /manage-pull-requests - - /roll-back-changes - - /chronicle - - /content/copilot/concepts/agents/copilot-cli/about-copilot-cli - - /content/copilot/concepts/agents/copilot-cli/comparing-cli-features - - /content/copilot/concepts/agents/copilot-cli/cancel-and-roll-back + - /automate-copilot-cli/automate-with-actions + - /automate-copilot-cli/quickstart + - /automate-copilot-cli/run-cli-programmatically - /content/copilot/concepts/agents/about-agent-skills - /content/copilot/concepts/agents/copilot-cli/about-cli-plugins - - /content/copilot/concepts/agents/copilot-cli/autopilot + - /content/copilot/concepts/agents/copilot-cli/about-copilot-cli - /content/copilot/concepts/agents/copilot-cli/about-remote-access - - /content/copilot/concepts/agents/copilot-cli/fleet - - /content/copilot/concepts/agents/copilot-cli/research - - /content/copilot/concepts/agents/copilot-cli/lsp-servers + - /content/copilot/concepts/agents/copilot-cli/autopilot + - /content/copilot/concepts/agents/copilot-cli/cancel-and-roll-back - /content/copilot/concepts/agents/copilot-cli/chronicle + - /content/copilot/concepts/agents/copilot-cli/comparing-cli-features - /content/copilot/concepts/agents/copilot-cli/context-management - - /set-up-copilot-cli/install-copilot-cli - - /set-up-copilot-cli/configure-copilot-cli - - /set-up-copilot-cli/add-lsp-servers - - /automate-copilot-cli/quickstart - - /automate-copilot-cli/automate-with-actions - - /automate-copilot-cli/run-cli-programmatically + - /content/copilot/concepts/agents/copilot-cli/fleet + - /content/copilot/concepts/agents/copilot-cli/lsp-servers + - /content/copilot/concepts/agents/copilot-cli/research + - /content/copilot/reference/copilot-cli-reference/acp-server + - /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/responsible-use/copilot-cli + - /content/copilot/tutorials/copilot-cli-hooks - /customize-copilot/add-custom-instructions - - /customize-copilot/create-custom-agents-for-cli + - /customize-copilot/add-mcp-servers - /customize-copilot/add-skills + - /customize-copilot/create-custom-agents-for-cli + - /customize-copilot/overview - /customize-copilot/plugins-creating - /customize-copilot/plugins-finding-installing - /customize-copilot/plugins-marketplace - - /customize-copilot/overview + - /customize-copilot/use-byok-models - /customize-copilot/use-hooks - - /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/copilot-cli-reference/acp-server - - /content/copilot/reference/hooks-configuration - - /content/copilot/tutorials/copilot-cli-hooks - - /content/copilot/responsible-use/copilot-cli + - /set-up-copilot-cli/add-lsp-servers + - /set-up-copilot-cli/authenticate-copilot-cli + - /set-up-copilot-cli/configure-copilot-cli + - /set-up-copilot-cli/install-copilot-cli + - /set-up-copilot-cli/troubleshoot-copilot-cli-auth + - /use-copilot-cli/agentic-code-review + - /use-copilot-cli/allowing-tools + - /use-copilot-cli/chronicle + - /use-copilot-cli/connecting-vs-code + - /use-copilot-cli/delegate-tasks-to-cca + - /use-copilot-cli/invoke-custom-agents + - /use-copilot-cli/manage-pull-requests + - /use-copilot-cli/overview + - /use-copilot-cli/roll-back-changes + - /use-copilot-cli/speed-up-task-completion + - /use-copilot-cli/steer-agents + - /use-copilot-cli/steer-remotely carousels: recommended: - - /copilot/how-tos/copilot-cli/use-copilot-cli-agents/overview + - /copilot/how-tos/copilot-cli/use-copilot-cli/overview - /copilot/how-tos/copilot-cli/cli-best-practices - /copilot/reference/copilot-cli-reference/cli-command-reference includedCategories: diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/index.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/index.md deleted file mode 100644 index 0fc6978da73a..000000000000 --- a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Use {% data variables.copilot.copilot_cli %} agents -shortTitle: Use Copilot CLI agents -intro: Understand the different ways you can use agents in {% data variables.copilot.copilot_cli_short %} to delegate and automate work. -versions: - feature: copilot -children: - - /overview - - /delegate-tasks-to-cca - - /invoke-custom-agents - - /steer-agents - - /agentic-code-review -contentType: how-tos -docsTeamMetrics: - - copilot-cli ---- - diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/agentic-code-review.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/agentic-code-review.md similarity index 92% rename from content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/agentic-code-review.md rename to content/copilot/how-tos/copilot-cli/use-copilot-cli/agentic-code-review.md index 67456cf5d983..6c691af7f0c3 100644 --- a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/agentic-code-review.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/agentic-code-review.md @@ -7,13 +7,15 @@ product: '{% data reusables.gated-features.copilot-cli %}' versions: feature: copilot contentType: how-tos +redirect_from: + - /copilot/how-tos/copilot-cli/use-copilot-cli-agents/agentic-code-review category: - Build with Copilot CLI docsTeamMetrics: - copilot-cli --- -## About agentic code review +## About agentic code review You can use the `/review` slash command to have {% data variables.product.prodname_copilot_short %} analyze code changes without leaving the CLI. This lets you get quick feedback on your changes prior to committing. diff --git a/content/copilot/how-tos/copilot-cli/allowing-tools.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools.md similarity index 99% rename from content/copilot/how-tos/copilot-cli/allowing-tools.md rename to content/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools.md index 2aaf0886922e..83a71e029a23 100644 --- a/content/copilot/how-tos/copilot-cli/allowing-tools.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools.md @@ -5,6 +5,8 @@ intro: 'Control which tools {% data variables.copilot.copilot_cli_short %} can u versions: feature: copilot contentType: how-tos +redirect_from: + - /copilot/how-tos/copilot-cli/allowing-tools category: - Author and optimize with Copilot # Copilot discovery page - Build with Copilot CLI # Copilot CLI bespoke page diff --git a/content/copilot/how-tos/copilot-cli/chronicle.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle.md similarity index 99% rename from content/copilot/how-tos/copilot-cli/chronicle.md rename to content/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle.md index 0e29fa991a29..bb3ad0b54445 100644 --- a/content/copilot/how-tos/copilot-cli/chronicle.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle.md @@ -6,6 +6,8 @@ intro: 'Resume previous {% data variables.copilot.copilot_cli_short %} sessions, versions: feature: copilot contentType: how-tos +redirect_from: + - /copilot/how-tos/copilot-cli/chronicle category: - Author and optimize with Copilot # Copilot discovery page - Build with Copilot CLI # Copilot CLI bespoke page diff --git a/content/copilot/how-tos/copilot-cli/connecting-vs-code.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/connecting-vs-code.md similarity index 99% rename from content/copilot/how-tos/copilot-cli/connecting-vs-code.md rename to content/copilot/how-tos/copilot-cli/use-copilot-cli/connecting-vs-code.md index 9073ef280ac9..58b200e337e4 100644 --- a/content/copilot/how-tos/copilot-cli/connecting-vs-code.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/connecting-vs-code.md @@ -6,6 +6,8 @@ intro: 'Connect {% data variables.copilot.copilot_cli_short %} to {% data variab versions: feature: copilot contentType: how-tos +redirect_from: + - /copilot/how-tos/copilot-cli/connecting-vs-code category: - Author and optimize with Copilot # Copilot discovery page - Build with Copilot CLI # Copilot CLI bespoke page diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/delegate-tasks-to-cca.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/delegate-tasks-to-cca.md similarity index 95% rename from content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/delegate-tasks-to-cca.md rename to content/copilot/how-tos/copilot-cli/use-copilot-cli/delegate-tasks-to-cca.md index 4e80f732a4bc..91112a695e61 100644 --- a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/delegate-tasks-to-cca.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/delegate-tasks-to-cca.md @@ -7,6 +7,8 @@ product: '{% data reusables.gated-features.copilot-cli %}' versions: feature: copilot contentType: how-tos +redirect_from: + - /copilot/how-tos/copilot-cli/use-copilot-cli-agents/delegate-tasks-to-cca category: - Build with Copilot CLI docsTeamMetrics: @@ -48,4 +50,4 @@ Alternatively, prefix a prompt with `&` to delegate it: ## Next steps -To learn how to invoke specialized agents tailored to specific tasks, such as code review, documentation, or security audits, see [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli-agents/invoke-custom-agents). +To learn how to invoke specialized agents tailored to specific tasks, such as code review, documentation, or security audits, see [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/invoke-custom-agents). diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli/index.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/index.md new file mode 100644 index 000000000000..397559a3f848 --- /dev/null +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/index.md @@ -0,0 +1,25 @@ +--- +title: 'Use {% data variables.copilot.copilot_cli %}' +shortTitle: 'Use {% data variables.copilot.copilot_cli_short %}' +intro: Understand the different ways you can use {% data variables.product.prodname_copilot %} in your terminal. +versions: + feature: copilot +redirect_from: + - /copilot/how-tos/copilot-cli/use-copilot-cli-agents +children: + - /overview + - /allowing-tools + - /connecting-vs-code + - /delegate-tasks-to-cca + - /roll-back-changes + - /invoke-custom-agents + - /steer-agents + - /steer-remotely + - /agentic-code-review + - /manage-pull-requests + - /speed-up-task-completion + - /chronicle +contentType: how-tos +docsTeamMetrics: + - copilot-cli +--- diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/invoke-custom-agents.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/invoke-custom-agents.md similarity index 97% rename from content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/invoke-custom-agents.md rename to content/copilot/how-tos/copilot-cli/use-copilot-cli/invoke-custom-agents.md index 237755abbaf3..11412a07c394 100644 --- a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/invoke-custom-agents.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/invoke-custom-agents.md @@ -6,6 +6,8 @@ product: '{% data reusables.gated-features.copilot-cli %}' versions: feature: copilot contentType: how-tos +redirect_from: + - /copilot/how-tos/copilot-cli/use-copilot-cli-agents/invoke-custom-agents category: - Build with Copilot CLI docsTeamMetrics: @@ -110,4 +112,4 @@ For more detailed information on adding and managing MCP servers in {% data vari ## Next steps -To learn how to guide and refine agent behavior during task execution to keep work on track, see [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli-agents/steer-agents). +To learn how to guide and refine agent behavior during task execution to keep work on track, see [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/steer-agents). diff --git a/content/copilot/how-tos/copilot-cli/manage-pull-requests.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests.md similarity index 99% rename from content/copilot/how-tos/copilot-cli/manage-pull-requests.md rename to content/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests.md index c099bcda46fe..2444213183ec 100644 --- a/content/copilot/how-tos/copilot-cli/manage-pull-requests.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests.md @@ -5,6 +5,8 @@ intro: 'Use the `/pr` slash command to view, create, and fix pull requests direc versions: feature: copilot contentType: how-tos +redirect_from: + - /copilot/how-tos/copilot-cli/manage-pull-requests category: - Author and optimize with Copilot # Copilot discovery page - Build with Copilot CLI # Copilot CLI bespoke page diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/overview.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/overview.md similarity index 98% rename from content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/overview.md rename to content/copilot/how-tos/copilot-cli/use-copilot-cli/overview.md index ed6fff88ecb1..6ca5cae91661 100644 --- a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/overview.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/overview.md @@ -6,7 +6,6 @@ product: '{% data reusables.gated-features.copilot-cli %}' redirect_from: - /copilot/how-tos/use-copilot-cli - /copilot/how-tos/use-copilot-agents/use-copilot-cli - - /copilot/how-tos/copilot-cli/use-copilot-cli versions: feature: copilot contentType: how-tos @@ -293,10 +292,10 @@ For additional information use one of the following commands in your terminal: You can work with agents in {% data variables.copilot.copilot_cli_short %} to support a full task lifecycle, from delegating work to reviewing results: -* **Delegate tasks autonomously**: Run {% data variables.copilot.copilot_cli_short %} in autopilot mode to complete multi-step tasks without requiring approval at each step. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli-agents/delegate-tasks-to-cca). -* **Invoke custom agents**: Invoke specialized agents tailored to specific tasks, such as code review, documentation, or security audits. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli-agents/invoke-custom-agents). -* **Steer agents**: Guide and refine agent behavior during task execution to keep work on track. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli-agents/steer-agents). -* **Request a code review**: Use {% data variables.copilot.copilot_cli_short %} to get an AI-powered review of your code changes. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli-agents/agentic-code-review). +* **Delegate tasks autonomously**: Run {% data variables.copilot.copilot_cli_short %} in autopilot mode to complete multi-step tasks without requiring approval at each step. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/delegate-tasks-to-cca). +* **Invoke custom agents**: Invoke specialized agents tailored to specific tasks, such as code review, documentation, or security audits. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/invoke-custom-agents). +* **Steer agents**: Guide and refine agent behavior during task execution to keep work on track. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/steer-agents). +* **Request a code review**: Use {% data variables.copilot.copilot_cli_short %} to get an AI-powered review of your code changes. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/agentic-code-review). ## Further reading diff --git a/content/copilot/how-tos/copilot-cli/roll-back-changes.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/roll-back-changes.md similarity index 98% rename from content/copilot/how-tos/copilot-cli/roll-back-changes.md rename to content/copilot/how-tos/copilot-cli/use-copilot-cli/roll-back-changes.md index a7c47cfd1920..b6f272102903 100644 --- a/content/copilot/how-tos/copilot-cli/roll-back-changes.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/roll-back-changes.md @@ -5,6 +5,8 @@ intro: 'Rewind your {% data variables.copilot.copilot_cli_short %} session to a versions: feature: copilot contentType: how-tos +redirect_from: + - /copilot/how-tos/copilot-cli/roll-back-changes category: - Author and optimize with Copilot # Copilot discovery page - Build with Copilot CLI # Copilot CLI bespoke page diff --git a/content/copilot/how-tos/copilot-cli/speed-up-task-completion.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/speed-up-task-completion.md similarity index 97% rename from content/copilot/how-tos/copilot-cli/speed-up-task-completion.md rename to content/copilot/how-tos/copilot-cli/use-copilot-cli/speed-up-task-completion.md index 65f3bb526629..4ec9c9a19068 100644 --- a/content/copilot/how-tos/copilot-cli/speed-up-task-completion.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/speed-up-task-completion.md @@ -7,6 +7,7 @@ versions: contentType: how-tos redirect_from: - /copilot/how-tos/copilot-cli/speeding-up-task-completion + - /copilot/how-tos/copilot-cli/speed-up-task-completion category: - Author and optimize with Copilot # Copilot discovery page - Build with Copilot CLI # Copilot CLI bespoke page diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/steer-agents.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/steer-agents.md similarity index 90% rename from content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/steer-agents.md rename to content/copilot/how-tos/copilot-cli/use-copilot-cli/steer-agents.md index 7e5de86b67d5..e6d25c59e903 100644 --- a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/steer-agents.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/steer-agents.md @@ -6,6 +6,8 @@ product: '{% data reusables.gated-features.copilot-cli %}' versions: feature: copilot contentType: how-tos +redirect_from: + - /copilot/how-tos/copilot-cli/use-copilot-cli-agents/steer-agents category: - Build with Copilot CLI docsTeamMetrics: @@ -26,4 +28,4 @@ Steering lets you: ## Next steps -To learn how to use {% data variables.copilot.copilot_cli_short %} to get an AI-powered review of your code changes, see [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli-agents/agentic-code-review). +To learn how to use {% data variables.copilot.copilot_cli_short %} to get an AI-powered review of your code changes, see [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/agentic-code-review). diff --git a/content/copilot/how-tos/copilot-cli/steer-remotely.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely.md similarity index 99% rename from content/copilot/how-tos/copilot-cli/steer-remotely.md rename to content/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely.md index 41a6261c5979..5ee4f8ae4b56 100644 --- a/content/copilot/how-tos/copilot-cli/steer-remotely.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely.md @@ -6,6 +6,8 @@ intro: 'Enable remote access to a {% data variables.copilot.copilot_cli_short %} versions: feature: copilot contentType: how-tos +redirect_from: + - /copilot/how-tos/copilot-cli/steer-remotely category: - Author and optimize with Copilot # Copilot discovery page - Build with Copilot CLI # Copilot CLI bespoke page diff --git a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md index 1f36f6cbbed1..a0450162490a 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md @@ -151,7 +151,7 @@ copilot completion fish > ~/.config/fish/completions/copilot.fish | `/context` | Show the context window token usage and visualization. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/context-management#checking-your-context-usage). | | `/copy` | Copy the last response to the clipboard. | | `/cwd`, `/cd [PATH]` | Change the working directory or display the current directory. | -| `/delegate [PROMPT]` | Delegate changes to a remote repository with an AI-generated pull request. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli-agents/delegate-tasks-to-cca). | +| `/delegate [PROMPT]` | Delegate changes to a remote repository with an AI-generated pull request. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/delegate-tasks-to-cca). | | `/diff` | Review the changes made in the current directory. | | `/downgrade ` | Download and restart into a specific CLI version. Available for team accounts. | | `/env` | Show loaded environment details (instructions, MCP servers, skills, agents, plugins, LSPs, extensions). | @@ -160,7 +160,7 @@ copilot completion fish > ~/.config/fish/completions/copilot.fish | `/feedback`, `/bug` | Provide feedback about the CLI. | | `/fleet [PROMPT]` | Enable parallel subagent execution of parts of a task. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/fleet). | | `/help` | Show the help for interactive commands. | -| `/ide` | Connect to an IDE workspace. See [AUTOTITLE](/copilot/how-tos/copilot-cli/connecting-vs-code#managing-the-connection-with-the-ide-slash-command). | +| `/ide` | Connect to an IDE workspace. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/connecting-vs-code#managing-the-connection-with-the-ide-slash-command). | | `/init` | Initialize {% data variables.product.prodname_copilot_short %} custom instructions and agentic features for this repository. See [Project initialization for {% data variables.product.prodname_copilot_short %}](#project-initialization-for-copilot). | | `/instructions` | View and toggle custom instruction files. | | `/keep-alive [on\|busy\|NUMBERm\|NUMBERh]` | Prevent the machine from going to sleep: while a CLI session is active, while the agent is busy, or for a defined length of time. {% data reusables.copilot.experimental %} | @@ -172,14 +172,14 @@ copilot completion fish > ~/.config/fish/completions/copilot.fish | `/model`, `/models [MODEL]` | Select the AI model you want to use. | | `/plan [PROMPT]` | Create an implementation plan before coding. | | `/plugin [marketplace\|install\|uninstall\|update\|list] [ARGS...]` | Manage plugins and plugin marketplaces. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about-cli-plugins). | -| `/pr [view\|create\|fix\|auto]` | Manage pull requests for the current branch. See [AUTOTITLE](/copilot/how-tos/copilot-cli/manage-pull-requests). | -| `/remote [on\|off]` | Show remote status (if no argument provided), enable remote steering (`on`), or end the remote connection (`off`). See [AUTOTITLE](/copilot/how-tos/copilot-cli/steer-remotely). | +| `/pr [view\|create\|fix\|auto]` | Manage pull requests for the current branch. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/manage-pull-requests). | +| `/remote [on\|off]` | Show the remote control status (if no argument provided), enable remote steering (`on`), or end the remote connection (`off`). See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely). | | `/rename [NAME]` | Rename the current session (auto-generates a name if omitted; alias for `/session rename`). | | `/research TOPIC` | Run a deep research investigation using {% data variables.product.github %} search and web sources. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/research). | | `/reset-allowed-tools` | Reset the list of allowed tools. | | `/restart` | Restart the CLI, preserving the current session. | -| `/resume [VALUE]`, `/continue` | Switch to a different session by choosing from a list. Optionally specify a session ID, ID prefix, or session name to resume a specific session. | -| `/review [PROMPT]` | Run the code review agent to analyze changes. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli-agents/agentic-code-review). | +| `/resume [SESSION-ID]`, `/continue [SESSION-ID]` | Switch to a different session by choosing from a list (optionally specify a session ID). | +| `/review [PROMPT]` | Run the code review agent to analyze changes. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/agentic-code-review). | | `/session [info\|checkpoints [n]\|files\|plan\|rename [NAME]\|cleanup\|prune\|delete [ID]\|delete-all]`, `/sessions [info\|checkpoints [n]\|files\|plan\|rename [NAME]\|cleanup\|prune\|delete [ID]\|delete-all]` | Show session information and manage sessions. Subcommands: `info`, `checkpoints`, `files`, `plan`, `rename`, `cleanup`, `prune`, `delete`, `delete-all`. | | `/share [file\|html\|gist] [session\|research] [PATH]`, `/export [file\|html\|gist] [session\|research] [PATH]` | Share the session to a Markdown file, interactive HTML file, or {% data variables.product.github %} gist. | | `/skills [list\|info\|add\|remove\|reload] [ARGS...]` | Manage skills for enhanced capabilities. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/create-skills). | @@ -248,7 +248,7 @@ For a complete list of available slash commands enter `/help` in the CLI's inter | `--plan` | Start in plan mode. Shorthand for `--mode plan`. Cannot be combined with `--mode` or `--autopilot`. | | `--plain-diff` | Disable rich diff rendering (syntax highlighting via the diff tool specified by your git config). | | `--plugin-dir=DIRECTORY` | Load a plugin from a local directory (can be used multiple times). | -| `--remote` | Enable remote access to this session from {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_mobile %}. See [AUTOTITLE](/copilot/how-tos/copilot-cli/steer-remotely). | +| `--remote` | Enable remote access to this session from {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_mobile %}. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/steer-remotely). | | `--resume[=VALUE]` | Resume a previous interactive session by choosing from a list. Optionally specify a session ID, ID prefix, or session name. Name matching is exact and case-insensitive; falls back to the auto-generated summary when no explicit name matches. | | `-s`, `--silent` | Output only the agent response (without usage statistics), useful for scripting with `-p`. | | `--screen-reader` | Enable screen reader optimizations. | @@ -389,563 +389,7 @@ For more information, see [AUTOTITLE](/copilot/how-tos/configure-custom-instruct ## Hooks reference -Hooks are external commands, HTTP webhooks, or (on `sessionStart` only) prompt strings 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`. Each hook entry is a command hook, an HTTP hook, or (on `sessionStart` only) a prompt hook. - -#### Command hooks - -Command hooks run shell scripts and are supported on all hook types. - -```json -{ - "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. - -```json -{ - "version": 1, - "hooks": { - "sessionStart": [ - { - "type": "prompt", - "prompt": "Your prompt text or /slash-command" - } - ] - } -} -``` - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `prompt` | string | Yes | Text to submit—can be a natural language message or a slash command. | -| `type` | `"prompt"` | Yes | Must be `"prompt"`. | - -#### HTTP hooks - -HTTP hooks POST the event payload as JSON to a configured URL and parse the JSON response body. They are supported on all hook event types and are useful for webhook-style integrations—remote policy services, audit endpoints, and approval workflows—without requiring a local executable. - -```json -{ - "version": 1, - "hooks": { - "preToolUse": [ - { - "type": "http", - "url": "https://policy.example.com/preToolUse" - } - ] - } -} -``` - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `type` | `"http"` | Yes | Must be `"http"`. | -| `url` | string | Yes | Endpoint URL. Must use `http:` or `https:`. No env var substitution in the URL itself. | -| `headers` | object | No | Request headers. Values support `$VAR` / `${VAR}` substitution restricted to names listed in `allowedEnvVars`. | -| `allowedEnvVars` | string[] | No | Allowlist for header value templating. Setting to a non-empty array requires HTTPS. | -| `timeoutSec` | number | No | Per-request timeout in seconds. Default: `30`. `timeout` is accepted as an alias; `timeoutSec` takes precedence. | -| `matcher` | string | No | Regex filter. Supported only on `preCompact`, `subagentStart`, `permissionRequest`, and `notification`. Anchored as `^(?:pattern)$`. | - -The response body uses the same JSON schema as command hook stdout for each event. Respond `204 No Content` or any 2xx with empty body when no action is needed. - -> [!WARNING] -> HTTP hooks have no exit-code semantics. A non-2xx response is a hook failure, not a deny decision. To deny a tool call from an HTTP `preToolUse` hook, return `200 OK` with `{"permissionDecision":"deny","permissionDecisionReason":"..."}`. To deny from an HTTP `permissionRequest` hook, return `200 OK` with `{"behavior":"deny","message":"..."}`. - -A hook entry with both `bash` and `url` fields parses as whichever variant matches first; the unused field is silently dropped. Always set `type` explicitly and remove command-hook fields when using HTTP hooks. - -##### HTTP hook security - -HTTPS is required in the following cases: - -* When `allowedEnvVars` is a non-empty array, to prevent credentials from being sent over plaintext. -* By default for `preToolUse` and `permissionRequest` hooks, to protect the permission decision channel. - -The CLI enforces a default-deny SSRF policy: any URL whose hostname resolves to a loopback, private, link-local, or cloud metadata address is rejected before connection. DNS is resolved up front and all returned addresses are validated (DNS rebinding defense). - -The following environment variables relax these defaults for development and testing only. - -| Variable | Effect | Intended use | -|----------|--------|--------------| -| `COPILOT_HOOK_ALLOW_LOCALHOST=1` | Permits `http://` to literal `localhost`, `127.*`, or `[::1]` (HTTPS rules), and any hostname resolving entirely to loopback (SSRF rule). | Local development only | -| `COPILOT_HOOK_ALLOW_HTTP_AUTH_HOOKS=1` | Permits `http://` for `preToolUse` and `permissionRequest` hooks anywhere. | Testing only | - -Both variables must be set before launching `copilot`. Do not set them globally, in CI, or in shared environments. - -##### HTTP hook failure semantics - -| Condition | Behavior | -|-----------|----------| -| 2xx + valid JSON body | Body parsed per event output schema. | -| 2xx + empty or non-JSON body | No action. | -| Non-2xx response | Hook fails. Error logged. Agent continues. | -| 3xx redirect | Hook fails ("returned redirect"). Agent continues. | -| Timeout | Hook fails. Error logged. Agent continues. | -| Network, DNS, or TLS error | Hook fails. Error logged. Agent continues. | -| Configuration validation error at load | Entire configuration file rejected; no hooks from that file register. | - -For `preToolUse` and `permissionRequest`, an HTTP hook failure is fail-open: the agent falls through to the default permission flow. - -### Hook events - -| Event | Fires when | Output processed | -|-------|------------|------------------| -| `sessionStart` | A new or resumed session begins. | Optional — can return `additionalContext` to inject session-wide context prepended to every turn. | -| `sessionEnd` | The session terminates. | No | -| `userPromptSubmitted` | The user submits a prompt. | No | -| `preToolUse` | Before each tool executes. | Yes — can allow, deny, or modify. | -| `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). | -| `agentStop` | The main agent finishes a turn. | Yes — can block and force continuation. | -| `subagentStop` | A subagent completes. | Yes — can block and force continuation. | -| `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. | -| `preCompact` | Context compaction is about to begin (manual or automatic). Supports `matcher` to filter by trigger (`"manual"` or `"auto"`). | No — notification only. | -| `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. | -| `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. | - -### 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. -* **{% data variables.product.prodname_vscode_shortname %} compatible format** — Configure the event name in PascalCase (for example, `SessionStart`). Fields use snake_case to match the {% data variables.product.prodname_vscode_shortname %} {% data variables.product.prodname_copilot_short %} extension format. - -#### `sessionStart` / `SessionStart` - -**camelCase input:** - -```typescript -{ - sessionId: string; - timestamp: number; // Unix timestamp in milliseconds - cwd: string; - source: "startup" | "resume" | "new"; - initialPrompt?: string; -} -``` - -**{% data variables.product.prodname_vscode_shortname %} compatible input:** - -```typescript -{ - 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:** - -```typescript -{ - sessionId: string; - timestamp: number; - cwd: string; - reason: "complete" | "error" | "abort" | "timeout" | "user_exit"; -} -``` - -**{% data variables.product.prodname_vscode_shortname %} compatible input:** - -```typescript -{ - 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:** - -```typescript -{ - sessionId: string; - timestamp: number; - cwd: string; - prompt: string; -} -``` - -**{% data variables.product.prodname_vscode_shortname %} compatible input:** - -```typescript -{ - hook_event_name: "UserPromptSubmit"; - session_id: string; - timestamp: string; // ISO 8601 timestamp - cwd: string; - prompt: string; -} -``` - -#### `preToolUse` / `PreToolUse` - -**camelCase input:** - -```typescript -{ - sessionId: string; - timestamp: number; - cwd: string; - toolName: string; - toolArgs: unknown; -} -``` - -**{% data variables.product.prodname_vscode_shortname %} compatible input:** - -When configured with the PascalCase event name `PreToolUse`, the payload uses snake_case field names to match the {% data variables.product.prodname_vscode_shortname %} {% data variables.product.prodname_copilot_short %} extension format: - -```typescript -{ - 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:** - -```typescript -{ - sessionId: string; - timestamp: number; - cwd: string; - toolName: string; - toolArgs: unknown; - toolResult: { - resultType: "success"; - textResultForLlm: string; - } -} -``` - -**{% data variables.product.prodname_vscode_shortname %} compatible input:** - -```typescript -{ - 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:** - -```typescript -{ - sessionId: string; - timestamp: number; - cwd: string; - toolName: string; - toolArgs: unknown; - error: string; -} -``` - -**{% data variables.product.prodname_vscode_shortname %} compatible input:** - -```typescript -{ - 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:** - -```typescript -{ - sessionId: string; - timestamp: number; - cwd: string; - transcriptPath: string; - stopReason: "end_turn"; -} -``` - -**{% data variables.product.prodname_vscode_shortname %} compatible input:** - -```typescript -{ - hook_event_name: "Stop"; - session_id: string; - timestamp: string; // ISO 8601 timestamp - cwd: string; - transcript_path: string; - stop_reason: "end_turn"; -} -``` - -#### `subagentStart` - -**Input:** - -```typescript -{ - sessionId: string; - timestamp: number; - cwd: string; - transcriptPath: string; - agentName: string; - agentDisplayName?: string; - agentDescription?: string; -} -``` - -#### `subagentStop` / `SubagentStop` - -**camelCase input:** - -```typescript -{ - sessionId: string; - timestamp: number; - cwd: string; - transcriptPath: string; - agentName: string; - agentDisplayName?: string; - stopReason: "end_turn"; -} -``` - -**{% data variables.product.prodname_vscode_shortname %} compatible input:** - -```typescript -{ - 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:** - -```typescript -{ - sessionId: string; - timestamp: number; - cwd: string; - error: { - message: string; - name: string; - stack?: string; - }; - errorContext: "model_call" | "tool_execution" | "system" | "user_input"; - recoverable: boolean; -} -``` - -**{% data variables.product.prodname_vscode_shortname %} compatible input:** - -```typescript -{ - 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:** - -```typescript -{ - sessionId: string; - timestamp: number; - cwd: string; - transcriptPath: string; - trigger: "manual" | "auto"; - customInstructions: string; -} -``` - -**{% data variables.product.prodname_vscode_shortname %} compatible input:** - -```typescript -{ - 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 (command hooks) or returning it in the response body (HTTP hooks). - -| Field | Values | Description | -|-------|--------|-------------| -| `permissionDecision` | `"allow"`, `"deny"`, `"ask"` | Whether the tool executes. Empty output uses default behavior. | -| `permissionDecisionReason` | string | Reason shown to the agent. Recommended when decision is `"deny"` or `"ask"`. | -| `modifiedArgs` | unknown | Replaces the entire tool input before execution. Only valid when `permissionDecision` is not `"deny"` or `"ask"`. | -| `additionalContext` | string | Queued as context for the next model turn. Only valid when `permissionDecision` is not `"deny"` or `"ask"`. | - -> [!NOTE] -> The {% data variables.product.prodname_vscode_shortname %} alias (`PreToolUse`) also accepts nested `hookSpecificOutput.{permissionDecision, permissionDecisionReason, updatedInput, additionalContext}`. `updatedInput` is normalized to `modifiedArgs`. Top-level fields are accepted as a fallback. - -### `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:** - -```typescript -{ - 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:** - -```typescript -{ - 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 | -|-----------|-------------| -| `bash` | Execute shell commands (Unix). | -| `powershell` | Execute shell commands (Windows). | -| `view` | Read file contents. | -| `edit` | Modify file contents. | -| `create` | Create new files. | -| `glob` | Find files by pattern. | -| `grep` | Search file contents. | -| `web_fetch` | Fetch web pages. | -| `task` | Run subagent tasks. | -| `ask_user` | Ask the user a clarifying question. | - -If multiple hooks of the same type are configured, they execute in order. For `preToolUse`, if any hook returns `"deny"`, the tool is blocked. Exit codes apply to command hooks only—for HTTP hooks, see the [HTTP hook failure semantics](#http-hook-failure-semantics). For `postToolUseFailure` command hooks, exiting with code `2` causes stderr to be returned as recovery guidance for the assistant. For `permissionRequest` command hooks, exit code `2` is treated as a deny; stdout JSON (if any) is merged with `{"behavior":"deny"}`, and stderr is ignored. Hook failures (non-zero exit codes or timeouts) are logged and skipped—they never block agent execution. +For detailed information about hooks—including hook configuration formats, hook events, input payloads, and decision control—see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-hooks-reference). ## MCP server configuration @@ -1369,6 +813,7 @@ When content capture is enabled, the following attributes are populated. ## Further reading * [AUTOTITLE](/copilot/how-tos/copilot-cli) +* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-hooks-reference) * [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-plugin-reference) * [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-programmatic-reference) * [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-config-dir-reference) diff --git a/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md b/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md index b8bf0c3440c0..197a3c04bca8 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md @@ -268,3 +268,4 @@ The local configuration file uses the same schema as the repository configuratio * [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference) * [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-programmatic-reference) * [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-plugin-reference) +* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-hooks-reference) diff --git a/content/copilot/reference/copilot-cli-reference/cli-hooks-reference.md b/content/copilot/reference/copilot-cli-reference/cli-hooks-reference.md new file mode 100644 index 000000000000..cb91ccc0b4ea --- /dev/null +++ b/content/copilot/reference/copilot-cli-reference/cli-hooks-reference.md @@ -0,0 +1,507 @@ +--- +title: GitHub Copilot CLI hooks reference +shortTitle: CLI hooks reference +intro: 'Find hook events, configuration formats, and input payloads for {% data variables.copilot.copilot_cli_short %}.' +versions: + feature: copilot +category: + - Author and optimize with Copilot # Copilot discovery page + - Configure Copilot CLI # Copilot CLI bespoke page +contentType: reference +docsTeamMetrics: + - copilot-cli +--- + +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. + +```json +{ + "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. + +```json +{ + "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. +* **{% data variables.product.prodname_vscode_shortname %} compatible format** — Configure the event name in PascalCase (for example, `SessionStart`). Fields use snake_case to match the {% data variables.product.prodname_vscode_shortname %} {% data variables.product.prodname_copilot_short %} extension format. + +### `sessionStart` / `SessionStart` + +**camelCase input:** + +```typescript +{ + sessionId: string; + timestamp: number; // Unix timestamp in milliseconds + cwd: string; + source: "startup" | "resume" | "new"; + initialPrompt?: string; +} +``` + +**{% data variables.product.prodname_vscode_shortname %} compatible input:** + +```typescript +{ + 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:** + +```typescript +{ + sessionId: string; + timestamp: number; + cwd: string; + reason: "complete" | "error" | "abort" | "timeout" | "user_exit"; +} +``` + +**{% data variables.product.prodname_vscode_shortname %} compatible input:** + +```typescript +{ + 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:** + +```typescript +{ + sessionId: string; + timestamp: number; + cwd: string; + prompt: string; +} +``` + +**{% data variables.product.prodname_vscode_shortname %} compatible input:** + +```typescript +{ + hook_event_name: "UserPromptSubmit"; + session_id: string; + timestamp: string; // ISO 8601 timestamp + cwd: string; + prompt: string; +} +``` + +### `preToolUse` / `PreToolUse` + +**camelCase input:** + +```typescript +{ + sessionId: string; + timestamp: number; + cwd: string; + toolName: string; + toolArgs: unknown; +} +``` + +**{% data variables.product.prodname_vscode_shortname %} compatible input:** + +When configured with the PascalCase event name `PreToolUse`, the payload uses snake_case field names to match the {% data variables.product.prodname_vscode_shortname %} {% data variables.product.prodname_copilot_short %} extension format: + +```typescript +{ + 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:** + +```typescript +{ + sessionId: string; + timestamp: number; + cwd: string; + toolName: string; + toolArgs: unknown; + toolResult: { + resultType: "success"; + textResultForLlm: string; + } +} +``` + +**{% data variables.product.prodname_vscode_shortname %} compatible input:** + +```typescript +{ + 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:** + +```typescript +{ + sessionId: string; + timestamp: number; + cwd: string; + toolName: string; + toolArgs: unknown; + error: string; +} +``` + +**{% data variables.product.prodname_vscode_shortname %} compatible input:** + +```typescript +{ + 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:** + +```typescript +{ + sessionId: string; + timestamp: number; + cwd: string; + transcriptPath: string; + stopReason: "end_turn"; +} +``` + +**{% data variables.product.prodname_vscode_shortname %} compatible input:** + +```typescript +{ + hook_event_name: "Stop"; + session_id: string; + timestamp: string; // ISO 8601 timestamp + cwd: string; + transcript_path: string; + stop_reason: "end_turn"; +} +``` + +### `subagentStart` + +**Input:** + +```typescript +{ + sessionId: string; + timestamp: number; + cwd: string; + transcriptPath: string; + agentName: string; + agentDisplayName?: string; + agentDescription?: string; +} +``` + +### `subagentStop` / `SubagentStop` + +**camelCase input:** + +```typescript +{ + sessionId: string; + timestamp: number; + cwd: string; + transcriptPath: string; + agentName: string; + agentDisplayName?: string; + stopReason: "end_turn"; +} +``` + +**{% data variables.product.prodname_vscode_shortname %} compatible input:** + +```typescript +{ + 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:** + +```typescript +{ + sessionId: string; + timestamp: number; + cwd: string; + error: { + message: string; + name: string; + stack?: string; + }; + errorContext: "model_call" | "tool_execution" | "system" | "user_input"; + recoverable: boolean; +} +``` + +**{% data variables.product.prodname_vscode_shortname %} compatible input:** + +```typescript +{ + 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:** + +```typescript +{ + sessionId: string; + timestamp: number; + cwd: string; + transcriptPath: string; + trigger: "manual" | "auto"; + customInstructions: string; +} +``` + +**{% data variables.product.prodname_vscode_shortname %} compatible input:** + +```typescript +{ + 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:** + +```typescript +{ + 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:** + +```typescript +{ + 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 + +* [AUTOTITLE](/copilot/how-tos/copilot-cli/use-hooks) +* [AUTOTITLE](/copilot/reference/hooks-configuration) +* [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference) diff --git a/content/copilot/reference/copilot-cli-reference/index.md b/content/copilot/reference/copilot-cli-reference/index.md index a763d0c872ff..f8fdffce2470 100644 --- a/content/copilot/reference/copilot-cli-reference/index.md +++ b/content/copilot/reference/copilot-cli-reference/index.md @@ -6,6 +6,7 @@ versions: feature: copilot children: - /cli-command-reference + - /cli-hooks-reference - /cli-plugin-reference - /cli-programmatic-reference - /acp-server diff --git a/src/content-pipelines/config.yml b/src/content-pipelines/config.yml index bf8aab4a6b9a..2136f5288e90 100644 --- a/src/content-pipelines/config.yml +++ b/src/content-pipelines/config.yml @@ -22,6 +22,7 @@ copilot-cli: target-articles: - content/copilot/reference/copilot-cli-reference/cli-command-reference.md - content/copilot/reference/copilot-cli-reference/cli-plugin-reference.md + - content/copilot/reference/copilot-cli-reference/cli-hooks-reference.md - content/copilot/reference/copilot-cli-reference/acp-server.md - content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md exclusions: @@ -31,7 +32,8 @@ copilot-cli: content-mapping: | cli-plugin-reference.md covers only plugin-specific content. All information relating to files in the ~/.copilot configuration directory, and settings in those files, should go in cli-config-dir-reference.md. - All other CLI topics (hooks, MCP, skills, agents, permissions, etc.) belong in cli-command-reference.md even when they mention plugins. + All reference details relating to hooks should go in cli-hooks-reference.md. + All other CLI topics (MCP, skills, agents, permissions, etc.) belong in cli-command-reference.md even when they mention plugins. # TODO # mcp-server: