Agent Frontmatter Policy

This document records which agents/*.md frontmatter fields Harness treats as runtime-enforced, advisory, or unsupported for plugin-delivered agents.

Checked against the Claude Code subagents documentation on 2026-05-05: https://code.claude.com/docs/en/sub-agents

Current Policy

Plugin subagents do not support these frontmatter fields:

• hooks
• mcpServers
• permissionMode

Claude Code ignores those fields when agents are loaded from a plugin. Harness therefore does not keep them in agents/worker.md, agents/reviewer.md, or agents/advisor.md.

If an operator needs per-agent hooks or permission mode experiments, copy the agent into .claude/agents/ or ~/.claude/agents/ and treat that as a local override, not a shipped plugin contract.

Supported Fields Used By Harness

Field	Harness use
name	Stable agent identifier
description	Delegation routing hint
tools	Tool allowlist
disallowedTools	Tool denylist
model	Preferred model family or model id
effort	Reasoning effort hint
maxTurns	Turn budget
color	UI display hint
memory	Agent memory scope
isolation	worktree isolation for Worker
initialPrompt	First-turn operating checklist
skills	Skills preloaded into agent context

Current Agent Audit

Agent	Mutating tools	Read-only intent	Notes
worker	Yes	No	Implementation worker. Uses tools plus Worker preflight.
reviewer	No	Yes	Write, Edit, Bash, and Agent are denied.
advisor	No	Yes	Returns advisor-response.v1; does not execute commands.

rg -n "permissionMode:|hooks:" agents/*.md should return no matches.

Worker Write Guard Responsibility

Worker safety is not enforced by agent-local hooks. It is layered:

1. Plugin-level hooks in hooks/hooks.json and .claude-plugin/hooks.json route tool use through the Harness hook entrypoints.
2. Go guardrails under go/internal/guardrail/ make the concrete deny / ask / warn decisions.
3. .claude-plugin/settings.json and generated settings provide session-level permission and sandbox defaults.
4. agents/worker.md preflight tells the Worker to verify file scope, DoD, contract path, and validation commands before editing.
5. Parent session permission mode is inherited by plugin agents; agent frontmatter does not override it.

Why The Fields Were Removed

Keeping ignored fields in shipped plugin agents makes the configuration look stronger than it is. Removing them makes the real safety boundary visible: plugin settings, plugin-level hooks, Go guardrail, and explicit Worker preflight.