How Agent Frontmatter Patterns Configure Worker and Reviewer Sub-Agents in Claude-Code-Harness

The claude-code-harness treats each sub-agent as an isolated Claude Code session whose capabilities, tool permissions, and runtime constraints are declared entirely through a YAML frontmatter block in agents/worker.md or agents/reviewer.md, validated against the Agent Frontmatter Policy before execution.

The claude-code-harness orchestrates complex coding workflows by spawning specialized Worker and Reviewer processes. Unlike general Claude Code sessions, these sub-agents derive all behavioral configuration from a declarative YAML frontmatter block embedded at the top of their respective markdown files, creating a single source of truth for sandboxing, turn limits, and model selection.

Core Frontmatter Fields and Enforcement

The Harness reads the YAML block—lines 1‑30 in [agents/worker.md](https://github.com/Chachamaru127/claude-code-harness/blob/main/agents/worker.md#L1-L30) and lines 1‑25 in [agents/reviewer.md](https://github.com/Chachamaru127/claude-code-harness/blob/main/agents/reviewer.md#L1-L25)—to construct an internal AgentConfig struct that drives runtime behavior.

Tool Permissions and Sandboxing

The tools field defines an explicit whitelist of available capabilities. The Worker declares Read, Write, Edit, Bash, Grep, and Glob, while the Reviewer is restricted to Read, Grep, and Glob. Complementing this, the disallowedTools field creates a blacklist that overrides any implicit allowances. The Reviewer explicitly blocks Write, Edit, Bash, and Agent to guarantee read-only operation, whereas the Worker only denies the Agent tool to prevent spawning nested sub-agents.

Session Constraints and Resources

The maxTurns field imposes a hard limit on dialogue length before automatic abort—100 for Workers and 50 for Reviewers. The effort field presets token budgets, with Workers defaulting to medium and Reviewers demanding xhigh for deep reasoning depth. The Harness injects the model (claude-sonnet-4-6) into the Claude request payload and respects these budgets when calculating allocations.

Environment and Memory

The isolation field (Worker only) triggers the creation of a temporary Git worktree, ensuring file writes never contaminate the main repository until explicitly committed. Both agents use memory scope project to persist data across their lifecycle. The color field (yellow for Worker, blue for Reviewer) drives the UI representation, while initialPrompt prepopulates mandatory checks—such as task ID validation and contract path confirmation—as the first user message sent to Claude.

Pattern Rules and Safety Constraints

The Harness enforces strict pattern rules defined in [docs/agent-frontmatter-policy.md](https://github.com/Chachamaru127/claude-code-harness/blob/main/docs/agent-frontmatter-policy.md) and verified by [./tests/validate-plugin.sh](https://github.com/Chachamaru127/claude-code-harness/blob/main/tests/validate-plugin.sh).

• No permissionMode in plugins: As documented in [CHANGELOG.md](https://github.com/Chachamaru127/claude-code-harness/blob/main/CHANGELOG.md#L841-L847) lines 841‑847, the Harness explicitly ignores permissionMode for sub-agents to prevent stale permission settings from affecting behavior. [tests/test-agent-permission-mode.sh](https://github.com/Chachamaru127/claude-code-harness/blob/main/tests/test-agent-permission-mode.sh) provides automated verification of this constraint.

• Hooks are prohibited: Plugin agents cannot define hooks: because the Harness enforces safety at the Go runtime level using guards and pre-flight scripts rather than user-defined hooks.

• Immutable effort defaults: Workers document that they "自身は effort を動的変更しない" (never dynamically change their own effort), ensuring consistent token consumption throughout the session regardless of task complexity.

• Universal NG rules: The Worker frontmatter documents "NG‑1" (prohibiting breezing mode edits to Plans.md markers) and "NG‑2/NG‑3" (blocking embedded Git repositories and sub-agent spawning). The Harness checks these constraints before execution, aborting with structured JSON errors if violated.

How the Harness Wires Frontmatter to Runtime

The translation from markdown declaration to active sandbox follows four distinct phases:

1. Parsing: The Harness extracts the YAML block from the agent's markdown file, parsing fields like skills (e.g., harness-work for Workers, harness-review for Reviewers) and the description.

2. Validation: The Agent Frontmatter Policy validator checks required fields, ensures whitelist/blacklist consistency, and forbids ignored fields such as permissionMode and hooks.

3. Runtime Configuration: Based on the parsed data, the Harness initializes the AgentConfig struct, configuring the tool sandbox, model selection, turn budgets, memory scope, and worktree isolation.

4. Initial Prompt Injection: The initialPrompt string is dispatched as the first user message, forcing the agent to verify contracts, specifications, and profiles before proceeding with any task.

Launch Examples

The following commands demonstrate how the Harness applies frontmatter-constrained agents.

Launch a Worker in solo mode with full write capabilities:

claude-code --agent worker \
  --task-id 42.3.1 \
  --files src/main.ts \
  --contract-path .claude/state/contracts/42.3.1.sprint-contract.json \
  --mode solo

The Harness loads agents/worker.md, enforces the write-tool whitelist, and terminates the session if it exceeds the 100-turn maxTurns budget defined in the frontmatter.

Launch a read-only Reviewer with static profiling:

claude-code --agent reviewer \
  --type code \
  --target "Validate new authentication flow" \
  --files src/auth.ts \
  --contract-path .claude/state/contracts/45.2.1.sprint-contract.json \
  --spec-path docs/spec/00-project-spec.md \
  --reviewer-profile static

The Harness reads agents/reviewer.md, blocks any Write or Bash invocations via the disallowedTools blacklist, and limits the session to 50 turns at xhigh effort.

Inspect the parsed configuration for debugging:

claude-code --agent worker --print-config

This outputs the JSON representation of the AgentConfig derived from the frontmatter, useful for custom tooling and validation.

Summary

• Agent frontmatter patterns in claude-code-harness declare all capabilities, constraints, and safety rules through YAML blocks in agents/worker.md and agents/reviewer.md.
• Tool sandboxing relies on explicit whitelists (tools) and blacklists (disallowedTools), with the Reviewer strictly read-only while the Worker maintains write access within isolated worktrees.
• Runtime constraints including maxTurns, effort, and model are immutable once the session begins, enforced by the Harness validator and runtime guards.
• Validation pipeline ensures no forbidden fields like permissionMode or hooks enter the configuration, with automated tests preventing regression.

Frequently Asked Questions

What happens if a Worker attempts to call a tool not listed in its frontmatter whitelist?

The Harness intercepts the call at runtime and rejects the invocation with a structured JSON error. Because the tools field defines the complete allowed set—including Read, Write, Edit, Bash, Grep, and Glob—any attempt to invoke Agent or other unlisted tools triggers an immediate abort before Claude processes the request.

Why does the Reviewer frontmatter specify xhigh effort while the Worker uses medium?

The Reviewer requires deep reasoning capabilities to analyze complex code contracts and specifications comprehensively. According to the configuration in agents/reviewer.md, the xhigh effort setting allocates maximum token budgets for analysis, whereas the Worker’s medium effort balances implementation speed with resource consumption during long-running tasks up to 100 turns.

Can I dynamically override frontmatter fields like maxTurns or isolation during an agent session?

No. The Harness parses and validates frontmatter fields once at startup, caching the resulting AgentConfig for the session duration. Fields like maxTurns and isolation are immutable; the 100-turn limit for Workers and the temporary worktree creation are fixed when the agent initializes and cannot be altered by the caller or the agent itself mid-session.

How does the isolation field in the Worker frontmatter protect the main repository?

When the Worker frontmatter specifies isolation, the Harness creates a temporary Git worktree before launching the agent process. This ensures all Write and Edit operations occur in an isolated file system context, preventing partial or experimental changes from affecting the main working tree until the Harness explicitly prepares a commit, effectively sandboxing implementation work from source control integrity.

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