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

> Learn how agent frontmatter patterns configure worker and reviewer sub-agents in Claude-Code-Harness. Discover YAML frontmatter for isolated Claude Code sessions with tool permissions and runtime constraints.

- Repository: [Chachamaru/claude-code-harness](https://github.com/Chachamaru127/claude-code-harness)
- Tags: how-to-guide
- Published: 2026-05-28

---

**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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/agents/worker.md) or [`agents/reviewer.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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)](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)](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)](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)](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)](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)](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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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:

```bash
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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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:

```bash
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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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:

```bash
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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/agents/worker.md) and [`agents/reviewer.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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`](https://github.com/Chachamaru127/claude-code-harness/blob/main/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.