How to use hooks in the GitHub Copilot CLI | demo

Key Concepts

• Copilot CLI: A command-line interface tool that utilizes AI agents to perform tasks.
• Agent Loop: The iterative process where an AI agent reasons, executes tool calls, and repeats until no further actions are required.
• Hooks: Event-driven triggers within the agent lifecycle that allow users to execute custom commands or logic at specific stages.
• Sub-agents: Secondary agent loops spawned by the primary agent to handle specific tasks, following the same reasoning and tool-calling logic.
• Blocking vs. Non-blocking Hooks: The distinction between hooks that allow for intervention (e.g., approving or denying a tool call) and those that merely observe or log events.

The Agent Lifecycle

To understand hooks, one must first understand the "Agent Lifecycle." When a user sends a prompt, the following process occurs:

1. Reasoning: The agent processes the input and generates tokens.
2. Tool Calls: The agent executes specific actions such as reading/writing files or running bash scripts.
3. Iteration: The agent continues to loop through reasoning and tool calls until no further actions are needed.
4. Sub-agent Execution: If necessary, the agent spawns a sub-agent, which operates as its own independent loop, following the same reasoning-to-tool-call pattern.
5. Completion: The process concludes when the agent determines no more tool calls are required, resulting in a final response to the user.

Hook Events and Placement

Hooks are events triggered at specific points in the lifecycle. They allow developers to intercept or respond to the agent's activity:

• session start: Fires only once at the beginning of a new chat session.
• user prompt submitted: Fires every time a user sends a prompt, including subsequent prompts within the same session.
• pre-tool use: Fires immediately before the agent executes a tool call. This is a blocking hook, meaning the user can intervene to approve or deny the execution.
• post-tool use: Fires immediately after a tool call is completed.
• sub agent start / sub agent stop: Fires when a sub-agent begins or finishes its specific task loop.
• session end: Fires when the final response is delivered and the session concludes.
• error occurred: A global hook that fires whenever an error is encountered at any point in the lifecycle.

Functionality and Application

The primary utility of hooks is to provide granular control over the agent's behavior.

• Intervention: Hooks like pre-tool use are critical because they allow for conditional logic. A developer can inspect the intended tool call and decide whether to permit it, providing a layer of security or oversight.
• Context Persistence: While the lifecycle may repeat (e.g., multiple prompts in one session), the context of the entire conversation is maintained and passed down through each iteration, ensuring the agent remains aware of previous actions.
• Error Handling: The error occurred hook provides a centralized way to manage failures, regardless of where they happen in the complex loop of reasoning and tool execution.

Synthesis

Hooks transform the Copilot CLI from a static tool into a programmable environment. By understanding that the agent operates as a continuous loop of reasoning and tool execution, developers can strategically place hooks to monitor, log, or gatekeep agent actions. The distinction between blocking hooks (which allow for decision-making) and non-blocking hooks (which provide visibility) is essential for building robust, automated workflows within the CLI.