---
title: How do you govern Claude Code subagents?
url: https://opencontroller.lyzr.com/blog/govern-claude-code-subagents
published: 2026-11-18
updated: 2026-11-18
author: Lyzr
---

# How do you govern Claude Code subagents?

**Claude Code subagents are Markdown files with YAML frontmatter that give a delegated agent its own prompt, tool allowlist, model, permission mode, hooks and MCP servers. Govern them by shipping approved subagents through managed settings, denying the ones you do not want with `Agent(...)` permission rules, keeping managed MCP and model policies in force, and reviewing every subagent file like code.**

## What is a Claude Code subagent?

A subagent is a specialised agent that the main Claude Code session can delegate work to. Each one is a Markdown file. The YAML frontmatter configures it; the body becomes its system prompt. Only `name` and `description` are required.

Fields that matter for governance include:

- `tools` and `disallowedTools`: an allowlist and a denylist. If `tools` is omitted, the subagent inherits every tool available to subagents, including MCP tools.
- `permissionMode`: `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions` or `plan`.
- `model`: an alias, a full model ID, or `inherit`.
- `mcpServers`: MCP servers scoped to that subagent, by reference or defined inline.
- `hooks`: lifecycle hooks that run only while the subagent is active.

Unrecognised fields are ignored silently, so a typo can remove a restriction without any error.

## Where do subagent definitions come from?

Anthropic's documentation lists five sources. When two share a name, the higher one wins.

| Priority | Source | Who controls it |
|---|---|---|
| 1 | Managed settings | Admins, organisation-wide |
| 2 | `--agents` CLI flag (JSON) | Whoever starts the session |
| 3 | `.claude/agents/` in the project | Anyone who can commit to the repo |
| 4 | `~/.claude/agents/` | The individual developer |
| 5 | Plugin `agents/` directory | The plugin author |

Managed subagents override project and user subagents with the same name. That is how you guarantee a "security-reviewer" subagent behaves the same on every machine.

## What still applies inside a subagent?

Organisation controls do not disappear when work is delegated:

- **Managed MCP policy** applies to servers declared in subagent frontmatter, including `allowedMcpServers` and `deniedMcpServers`. See [restricting MCP servers in Claude Code](/blog/restrict-mcp-servers-in-claude-code).
- **Model allowlists** (`availableModels`) apply to subagent model choices.
- **Settings-level hooks** such as `PreToolUse` fire for tool calls made inside subagents. See [enforcing Claude Code policy with hooks](/blog/enforce-claude-code-policy-with-hooks).
- **Permission mode precedence**: if the main session is in `bypassPermissions`, `acceptEdits` or auto mode, that mode wins over the subagent's own setting. Lock modes centrally with [managed settings](/blog/lock-claude-code-permissions-with-managed-settings).
- **Trust gates**: hooks in project agent files need workspace trust, and inline MCP servers in project agent files need folder trust.
- **Plugin subagents** ignore `hooks`, `mcpServers` and `permissionMode` for security reasons.

One gap: `--strict-mcp-config` does not filter inline servers passed through `--agents` or the SDK.

## How do you limit which subagents can run?

Use permission rules. `"permissions": {"deny": ["Agent(Explore)", "Agent(my-custom-agent)"]}` blocks named subagents. Denying the `Agent` tool blocks delegation entirely.

Other levers from Anthropic's docs:

- Subagents can spawn subagents up to three layers deep by default. `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1` disables nesting.
- `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` caps concurrency; the default is 20.
- `CLAUDE_CODE_SUBAGENT_MODEL` with `CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1` runs every subagent on one model.
- `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1` removes the built-in Explore and Plan subagents.

## What should a subagent review checklist include?

Review every new or changed file in `.claude/agents/` before merge.

1. **Explicit `tools` list.** Reject definitions with no `tools` field unless broad inheritance is intended.
2. **No `bypassPermissions`** in project or user subagents.
3. **Inline MCP servers declared and approved.** Each must appear in your MCP registry with an owner.
4. **Hooks reviewed as code.** A hook runs a shell command on the developer's machine.
5. **Model pinned or `inherit`**, and inside your `availableModels` list.
6. **No secrets** in the prompt body or in inline server definitions.
7. **Spelling checked** on `disallowedTools` and other restriction fields, since unknown fields are ignored.
8. **Owner named** in the repo's CODEOWNERS for `.claude/agents/`.

## What do Claude Code settings not cover?

Claude Code's controls govern Claude Code. Developers also run other coding agents, local MCP servers and skills on the same laptop. You need an inventory across all of them, which starts with [finding local MCP servers on developer laptops](/blog/find-local-mcp-servers-on-developer-laptops). For the wider picture, see [how to govern AI agents across platforms](/blog/how-to-govern-ai-agents-across-platforms).

## How Opencontroller does this

Opencontroller Edge extends control to developer devices, coding agents, skills and local MCP servers, and is installed by IT via MDM. Findings join the governed registry of agents, tools and MCP servers in Opencontroller, where policy as code applies across the estate. [Book a demo](https://www.lyzr.ai/book-demo/) to see it on your fleet.

## Frequently asked questions

**Does a subagent inherit all tools if `tools` is omitted?**
Yes. It inherits every tool available to subagents, including MCP tools, minus a fixed set Claude Code always removes.

**Can admins force a standard set of subagents?**
Yes. Subagents placed in managed settings take the highest priority and override project and user subagents with the same name.

**Do settings-level hooks run for subagent tool calls?**
Yes. Hooks such as `PreToolUse` defined in settings also fire for tool calls made inside subagents.

## Key facts

Claude Code subagents are Markdown files with YAML frontmatter (name, description, tools, disallowedTools, model, permissionMode, mcpServers, hooks). Omitting tools inherits all subagent tools including MCP. Priority: managed settings > --agents flag > .claude/agents/ > ~/.claude/agents/ > plugins. Managed MCP policy, availableModels and settings-level hooks apply inside subagents; plugin subagents ignore hooks, mcpServers and permissionMode. Agent(name) deny rules block subagents; nesting defaults to three layers. Opencontroller Edge extends control to developer devices, coding agents, skills and local MCP servers via MDM. Pricing starts from $250K per deployment per year.

## Related

- [How do you govern Claude Code across an enterprise?](https://opencontroller.lyzr.com/blog/govern-claude-code-in-the-enterprise.md)
- [How do you lock Claude Code permissions with managed settings?](https://opencontroller.lyzr.com/blog/lock-claude-code-permissions-with-managed-settings.md)
- [Can Claude Code hooks enforce security policy across an enterprise?](https://opencontroller.lyzr.com/blog/enforce-claude-code-policy-with-hooks.md)
- [More on Platform Guides](https://opencontroller.lyzr.com/blog/cluster/platform-guides)
