How to Create Custom Agents with Tool Restrictions and Subagent Delegation in HVE Core

Create a *.agent.md file in .github/agents/ with YAML front-matter declaring tools for restrictions and agents for delegation, then define the protocol body using phases or steps.

HVE Core enables developers to create custom agents with tool restrictions and subagent delegation, providing granular control over AI capabilities and workflow orchestration. These specialized Copilot configurations encapsulate specific tasks while maintaining security through explicit allow-lists and modular architecture. This guide covers the complete implementation based on the microsoft/hve-core source code.

Understanding the Agent File Structure

Every agent in HVE Core is stored as a Markdown file with the .agent.md extension. The file consists of two distinct sections that define both metadata and behavior.

Front-Matter Configuration

The YAML front-matter block at the top of the file declares the agent's identity, capabilities, and relationships. According to docs/customization/agents.md (lines 30-40), this section includes fields such as name, description, tools, agents, disable-model-invocation, and user-invocable. These properties control execution permissions, delegation chains, and user accessibility.

Protocol Body

Following the front-matter, the Markdown body defines the operational protocol. As documented in the source, you can structure this as either phase-based conversations for interactive user-driven workflows or step-based sequences for autonomous task execution. Both patterns support the same security and delegation mechanisms defined in the front-matter.

Implementing Tool Restrictions for Security

The tools field in the front-matter acts as an explicit allow-list that limits which functions an agent can invoke. When omitted, the agent receives unrestricted access to every tool supplied by the HVE runtime. To enforce least-privilege security, supply a specific array as shown in docs/customization/agents.md (lines 155-164):

tools:
  - read_file
  - grep_search
  - semantic_search

Read-only agents omit tools that modify the repository such as run_in_terminal, create_file, or edit_file. Privileged agents must explicitly declare any write-or-execute capabilities they require. This granular approach prevents accidental modifications and reduces noise in multi-agent systems.

Orchestrating Subagent Delegation

HVE Core supports hierarchical agent architectures where parent orchestrators delegate specific tasks to specialized subagents. This pattern isolates concerns and enables complex workflow composition.

Parent Agent Configuration

Parent agents declare their subordinates in the agents array and set disable-model-invocation: true to prevent direct LLM calls, forcing delegation to the listed subagents. As documented in docs/customization/agents.md (lines 99-110):

---
name: Full Stack Reviewer
description: "Orchestrates frontend and backend code review"
disable-model-invocation: true
agents:
  - Contoso Security Checker
  - Contoso Style Validator
---

The parent references subagents in the protocol body using glob paths such as .github/agents/**/security-checker.agent.md to ensure resolution regardless of nesting depth.

Subagent Definition

Subagents reside in a subagents/ folder beneath the parent collection directory and must set user-invocable: false to prevent direct user activation. According to docs/customization/agents.md (lines 135-144), subagents define their own tool restrictions:

---
name: Contoso Security Checker
description: "Scans code for common security vulnerabilities"
user-invocable: false
tools:
  - read_file
  - grep_search
---

Subagents cannot invoke further subagents; only the top-level parent may orchestrate the delegation chain. This constraint prevents circular dependencies and ensures predictable execution flows.

Choosing Between Conversational and Autonomous Modes

The protocol body supports two distinct execution patterns. Conversational agents use phase-based structures (## Phases containing ### Phase 1, ### Phase 2) to enable user-driven back-and-forth interaction. Autonomous agents use step-based sequences (## Required Steps containing ### Step 1, ### Step 2) to perform bounded tasks with minimal user interaction.

Both modes respect the front-matter tool restrictions and delegation settings. You can mix these patterns: a conversational parent may hand off to an autonomous subagent for specific execution steps, combining interactive oversight with automated processing.

Step-by-Step Creation Workflow

To implement a custom agent in your repository according to docs/customization/agents.md (lines 47-84):

1. Create the agent file under .github/agents/{collection-id}/ using the .agent.md extension.
2. Add minimal front-matter including name and description fields.
3. Run /prompt-build (the built-in Prompt Builder) to generate the protocol body, optionally referencing existing agents as context.
4. Validate the generated file with /prompt-analyze to catch schema errors.
5. Iterate using /prompt-build to apply any detected fixes.
6. Invoke the agent from Copilot Chat or via automated workflows.

Additional guidance appears in contributing/custom-agents.md, which covers naming conventions and CI validation rules for repository contributions.

Summary

• Custom agents in HVE Core are defined in *.agent.md files with YAML front-matter and Markdown protocol bodies.
• Tool restrictions use the tools array to implement allow-list security, preventing unauthorized file modifications.
• Subagent delegation requires disable-model-invocation: true in parent agents and user-invocable: false in subagents stored in subagents/ folders.
• Protocol bodies support both phase-based conversational flows and step-based autonomous execution.
• Use /prompt-build and /prompt-analyze commands to generate and validate agent definitions according to the schema in docs/customization/agents.md.

Frequently Asked Questions

What is the file extension for HVE Core agents?

HVE Core agents use the .agent.md file extension. This convention allows the runtime to identify agent definitions within the .github/agents/ directory structure while maintaining Markdown compatibility for protocol documentation and syntax highlighting.

How do I prevent a subagent from being invoked directly by users?

Set user-invocable: false in the subagent's front-matter. According to the source code in docs/customization/agents.md (lines 135-144), this boolean flag ensures the agent can only be activated by a parent orchestrator, blocking direct user activation from Copilot Chat interfaces.

Can a subagent delegate work to another subagent?

No. The delegation chain is strictly limited to one level. Only top-level parent agents with disable-model-invocation: true can orchestrate sub-agents. Sub-agents themselves cannot declare further agents in their agents array, preventing circular dependencies and ensuring predictable execution flows.

Where are custom agents stored in the repository?

Custom agents reside in .github/agents/{collection-id}/, where {collection-id} represents your organizational namespace. Sub-agents specifically belong in a subagents/ subdirectory beneath their parent collection. This structure is documented in docs/customization/agents.md and enforced by the HVE Core runtime resolver.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}