[Claude sub-agents] Add frontmatter capability hardening for high-use agents

[azalio]

Source

Source: https://code.claude.com/docs/en/sub-agents, read on 2026-07-21.

Relevant source takeaways:

• Claude Code subagents are configured by Markdown frontmatter. Only name and description are required, so omitted capability fields inherit broad defaults.
• The docs list tools, disallowedTools, permissionMode, maxTurns, skills, memory, background, effort, isolation, and hooks as supported fields.
• If tools is omitted, a custom subagent inherits available tools. disallowedTools can remove capabilities from the inherited set.
• Nested subagent spawning can be prevented by omitting Agent from the allowed tools or adding it to disallowedTools.
• Claude docs recommend limiting tool access and using focused subagents.

Repo evidence

Inspected source-of-truth templates, not generated files:

• src/mapify_cli/templates_src/agents/monitor.md.jinja: Monitor prompt says read-only and says workflow-gate blocks edits, but frontmatter has no tools or disallowedTools; only prompt-level restrictions and external hook enforcement carry the boundary.
• src/mapify_cli/templates_src/agents/research-agent.md.jinja: Research agent prompt says read-only, no raw contents, no edits, but frontmatter has no tools or disallowedTools.
• src/mapify_cli/templates_src/agents/predictor.md.jinja: Predictor is analysis-only but frontmatter has no capability allowlist/denylist.
• src/mapify_cli/templates_src/agents/evaluator.md.jinja: Evaluator is scoring-only but frontmatter has no capability allowlist/denylist.
• src/mapify_cli/templates_src/agents/task-decomposer.md.jinja: already has permissionMode: plan, so this is the positive existing pattern.
• src/mapify_cli/templates_src/agents/final-verifier.md.jinja: verifier writes .map/<branch>/final_verification.json and progress markdown by design, so it should not be blindly made read-only.
• src/mapify_cli/templates_src/agents/actor.md.jinja: Actor intentionally writes implementation and should not get read-only restrictions.
• rg -n "^(tools|disallowedTools|permissionMode|memory|maxTurns|background|isolation|hooks|skills):" src/mapify_cli/templates_src/agents ... found only permissionMode: plan on task-decomposer among Claude agent templates.

Existing issue search

Commands/queries checked:

• gh issue list --repo azalio/map-framework --state all --limit 120 --search "subagent OR sub-agent OR agent frontmatter OR persistent memory OR memory field OR tools allowlist OR disallowedTools OR permissionMode OR maxTurns OR isolation worktree OR background agents"
• gh issue list --repo azalio/map-framework --state all --limit 80

Related issues inspected:

• BMAD-style named agent personas with persistent identity and 3-layer customization #290 BMAD-style named personas: persistent identity/persona customization, not frontmatter capability hardening.
• GSD-style fresh-context-per-task: worktree isolation for autonomous execution #284 GSD-style worktree isolation: runner-owned worktree isolation and wave dispatch, not per-agent tools/disallowedTools/permissionMode declarations.
• Intra-run failure memory: fail-twice→guardrail-sign + per-attempt reflexion fed back next iteration #253 intra-run failure memory: anti-repeat retry memory, not subagent capability boundary.
• Scope learned rules by module/path — hierarchical rule loading from agentic engineering model #280 path-scoped learned rules: rule loading scope, not tool permissions.

Why this is not already covered

MAP has prompt-level read-only instructions and workflow-gate enforcement, but Claude docs now expose first-class frontmatter capability controls. For high-use agents, prompt-only restrictions are weaker than an explicit provider-level capability manifest. The existing task-decomposer already proves MAP accepts frontmatter provider controls via permissionMode: plan; the same audit has not been applied to monitor/research/predictor/evaluator.

Problem

High-use non-writer agents can inherit more tools than their role needs. If Claude Code behavior, project settings, or plugin tools change, the effective capability set can drift while the prompt still says read-only. That creates avoidable risk and makes agent behavior harder to audit.

Proposed slice

Add an explicit capability-hardening pass for Claude agent templates:

1. Introduce a small role capability table for shipped Claude agents.
2. Add tools and/or disallowedTools frontmatter to non-writer high-use agents where the Claude Code docs support it.
3. Keep Actor and final-verifier exceptions explicit because they legitimately write source or .map/ artifacts.
4. Add tests that parse rendered .claude/agents/*.md and assert expected capability metadata for high-use agents.
5. Update docs/architecture or usage notes only if user-visible behavior changes.

Initial target classification:

• research-agent: read/search only; no Edit/Write; no Agent unless nested research is explicitly desired and tested.
• predictor: read/search/shell grep style only; no Edit/Write; no Agent.
• evaluator: read/search only unless review pipeline needs shell checks; no Edit/Write; no Agent.
• monitor: allow read/search and build/test Bash, but deny Edit/Write and nested Agent.
• task-decomposer: keep permissionMode: plan; consider explicit tool set only after checking plan-mode behavior.
• actor and final-verifier: out of scope except documenting why they are exceptions.

Acceptance criteria

• Generated Claude agent templates include explicit capability metadata for monitor, research-agent, predictor, evaluator, or a documented reason per agent for omission.
• Actor and final-verifier remain able to perform their required writes.
• Tests fail if a high-use non-writer agent drops its explicit capability metadata.
• make render-templates and make check-render pass.
• pytest tests/test_skills.py tests/test_template_render.py -v passes.
• A dry-run uv run mapify init <tmp> --no-git --mcp none shows rendered .claude/agents/*.md with the expected frontmatter.

Guardrails

• Do not blanket-deny Bash for Monitor unless build/test validation still works.
• Do not add memory in this issue; persistent memory changes have separate trust and write-scope semantics.
• Do not rely on prompt text alone as the acceptance proof.
• Do not edit generated trees directly; change src/mapify_cli/templates_src/**/*.jinja and rerender.

[azalio]

Taking this task. Will add disallowedTools frontmatter to monitor, research-agent, predictor, and evaluator agent templates to enforce capability boundaries at the harness level rather than relying on prompt-text alone.

Plan:

• monitor: disallowedTools: [Edit, Agent] (Write kept — monitor may write .map/ evidence artifacts)
• research-agent: disallowedTools: [Edit, Agent] (Write kept — may append to research artifact in MAP-planning mode)
• predictor: disallowedTools: [Edit, Write, Agent]
• evaluator: disallowedTools: [Edit, Write, Agent]

task-decomposer already has permissionMode: plan and is excluded. actor and final-verifier are intentionally excluded as legitimate writers.

---

Generated by Claude Code

[azalio]

Implemented and merged in PR #382.

Added disallowedTools frontmatter to all four target agents:

• monitor: [Edit, Agent] (Write kept for .map/ evidence artifacts)
• research-agent: [Edit, Agent] (Write kept for MAP-planning research artifact append)
• predictor: [Edit, Write, Agent]
• evaluator: [Edit, Write, Agent]

Includes 15 regression tests in TestAgentCapabilityHardening and updated docs/ARCHITECTURE.md.

---

Generated by Claude Code