Agent Hooks and Plugins

Purpose and Scope

Agent hooks and plugins are two complementary customization surfaces for Copilot agent workflows in VS Code. Hooks are deterministic lifecycle commands: they run shell commands at named points in an agent session and can enforce policy, add context, or stop unsafe work. Plugins are packaged bundles of agent customizations: a plugin can bring commands, skills, custom agents, hooks, and MCP server definitions into the chat experience as an installable unit. This page explains the source-backed vocabulary used by the repository prompt assets and how those concepts fit together for developers documenting, testing, or extending the agent customization experience.

Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md, extensions/copilot/assets/prompts/skills/agent-customization/references/agents.md, extensions/copilot/assets/prompts/skills/agent-customization/references/prompts.md

The key distinction is that instructions, prompts, skills, and agents guide model behavior, while hooks execute code. The hook reference in the Copilot prompt assets explicitly describes hooks as deterministic lifecycle automation for policy enforcement, validation, and runtime context injection. That makes hooks the right mechanism when a team needs a guaranteed result, such as blocking a dangerous tool invocation, running validation after edits, or recording audit events. Prompts and instructions remain useful, but they are advisory and depend on model interpretation rather than command execution.

Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md, extensions/copilot/assets/prompts/skills/agent-customization/references/instructions.md, extensions/copilot/assets/prompts/skills/agent-customization/references/agent-instructions.md

Plugins sit one level above individual customization files. The official VS Code documentation describes agent plugins as prepackaged bundles discoverable from plugin marketplaces, and the repository includes a generated Codex protocol type named PluginsMigration with marketplaceName and pluginNames. That type is small, but it is important because it shows that plugin marketplace identity and plugin-name lists are represented in the agent host protocol surface. In practice, a plugin can collect the same primitives a workspace could define locally, then distribute them together under marketplace-managed metadata.

Sources: src/vs/platform/agentHost/node/codex/protocol/generated/v2/PluginsMigration.ts

Relevant Source Files

• src/vs/platform/agentHost/node/codex/protocol/generated/v2/PluginsMigration.ts - Defines the generated PluginsMigration protocol shape with marketplaceName and pluginNames, grounding plugin migration metadata in the agent host protocol.
• extensions/copilot/assets/prompts/skills/agent-customization/references/agent-instructions.md - Documents project-wide agent instruction files, including .github/copilot-instructions.md and AGENTS.md, and explains when broad guidance should be used instead of hooks.
• extensions/copilot/assets/prompts/skills/agent-customization/references/agents.md - Documents custom .agent.md files, frontmatter, tool restrictions, subagent controls, handoffs, and inline hooks in agent frontmatter.
• extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md - Documents hook locations, lifecycle events, command configuration, input and output behavior, exit codes, and the distinction between hooks and advisory customizations.
• extensions/copilot/assets/prompts/skills/agent-customization/references/instructions.md - Documents file-specific .instructions.md files, discovery modes, applyTo matching, and principles for on-demand guidance.
• extensions/copilot/assets/prompts/skills/agent-customization/references/prompts.md - Documents reusable .prompt.md task templates, slash-command invocation, frontmatter, tool priority, and model fallback.

Core Primitives

A hook configuration is organized under a top-level hooks object whose keys are lifecycle event names. The repository reference lists events for session start, prompt submission, tool execution, context compaction, subagent start and stop, and session stop. Each hook entry is a command hook with fields such as type, command, platform-specific command overrides, cwd, env, and timeout. Hooks receive JSON on standard input and may return JSON on standard output, which allows a command to pass structured decisions back to the agent runtime rather than relying only on terminal text.

Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md

Custom agents are Markdown files with YAML frontmatter and a body that defines a focused persona. The source reference for agents names workspace and profile locations, frontmatter fields such as description, name, tools, model, argument-hint, agents, user-invocable, disable-model-invocation, handoffs, and hooks, and tool aliases such as execute, read, edit, search, agent, web, and todo. Inline hooks in agent frontmatter connect the lifecycle automation model directly to a specific agent, which is useful when a specialized persona needs specialized guardrails.

Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/agents.md, extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md

Instructions and prompts provide the surrounding guidance layer that often accompanies hooks and plugins. Project-wide instructions belong in .github/copilot-instructions.md or AGENTS.md, but the repository guidance says to use only one broad instruction file type, keep it concise, and link to existing docs instead of copying them. File-specific .instructions.md files support descriptions and optional applyTo globs so guidance can attach on demand or when matching files are edited. Prompt files are reusable task templates exposed through chat slash commands, the Chat: Run Prompt... command, or the prompt-file editor play button.

Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/agent-instructions.md, extensions/copilot/assets/prompts/skills/agent-customization/references/instructions.md, extensions/copilot/assets/prompts/skills/agent-customization/references/prompts.md

Lifecycle Hook Reference

Use hooks when a workflow must run even if the model does not choose it voluntarily. A PreToolUse hook can inspect the requested tool, decide whether to allow, ask, or deny execution, and optionally add context or modify input. A PostToolUse hook can react after successful tool use, for example by formatting files or blocking further processing when validation fails. Session and prompt events are better suited for context injection, audit logging, or setup checks, while subagent events are useful when delegated work needs separate tracking or policy enforcement.

Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "./scripts/validate-tool.sh",
        "timeout": 15
      }
    ]
  }
}

The hook output contract is intentionally structured. Common output can communicate whether processing should continue, a stop reason, or a system message. For PreToolUse, the hook-specific output includes permissionDecision values of allow, ask, or deny, plus a human-readable reason. The repository reference also records exit-code semantics: 0 means success, 2 is a blocking error, and other values produce non-blocking warnings. These conventions let teams implement auditable policy scripts without encoding all policy in natural-language instructions.

Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md

Plugin and Customization Composition

A plugin can package the same pieces that teams already use locally: slash-command prompts, skills, custom agents, hooks, and MCP servers. The plugin concept is therefore not a replacement for workspace customization; it is a distribution and installation model for those customizations. Locally defined hooks or agents remain appropriate for repository-specific policy, while a plugin is useful when the same capability should be discovered, installed, updated, or migrated as a named bundle. The generated PluginsMigration type reinforces that migration operates over marketplace and plugin-name metadata rather than over individual hook files.

Sources: src/vs/platform/agentHost/node/codex/protocol/generated/v2/PluginsMigration.ts, extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md, extensions/copilot/assets/prompts/skills/agent-customization/references/agents.md

When composing these primitives, start with the least forceful mechanism that solves the problem. Use agent instructions for broad team standards, file-specific instructions for scoped guidance, prompt files for repeatable single tasks, custom agents for role-based workflows with specific tools, and hooks only when command execution or enforcement is required. If a capability needs external tools or organization-wide reuse, package the pieces as a plugin and include hooks only for the lifecycle points that truly need deterministic behavior. This layering keeps the customization surface understandable and reduces unexpected side effects.

Sources: extensions/copilot/assets/prompts/skills/agent-customization/references/agent-instructions.md, extensions/copilot/assets/prompts/skills/agent-customization/references/instructions.md, extensions/copilot/assets/prompts/skills/agent-customization/references/prompts.md, extensions/copilot/assets/prompts/skills/agent-customization/references/agents.md, extensions/copilot/assets/prompts/skills/agent-customization/references/hooks.md

Compact Reference

Next Steps

If you are adding agent customization to a workspace, write down the desired behavior before choosing a primitive. If the behavior is guidance, prefer instructions, prompts, or a custom agent. If the behavior must run as code, define a small hook, keep the command auditable, validate its JSON input, and avoid hardcoded secrets. If you need to distribute a reusable bundle, treat plugins as the packaging layer and keep each bundled customization focused. For adjacent topics, continue with custom-agents-skills-and-prompts, agent-customization-instructions, mcp-servers, and chat-tools-and-approvals.