Claude Code subagents

Reproducible practice

Design a read-only reviewer subagent and prove its tool boundary

Delegate an independent review without granting edits, secret access, or unrestricted child-agent spawning.

Prerequisites

• A unique temporary repository.
• A bounded review question with expected evidence.
• No confidential fixture beyond what the reviewer must read.

Steps

1. Create a scoped agent definition

   Allow only inspection tools and require evidence in the prompt.

   AGENT_LAB=$(mktemp -d "${TMPDIR:-/tmp}/claude-agent.XXXXXX")
   printf '%s\n' "$AGENT_LAB"
   cd "$AGENT_LAB" && git init -q
   mkdir -p .claude/agents
   printf '%s\n' '---' 'name: read-only-reviewer' 'description: Review a bounded diff and cite file evidence.' 'tools: Read, Grep, Glob' '---' '' 'Report findings by severity. Do not propose edits without cited evidence.' > .claude/agents/read-only-reviewer.md

2. Inspect the allowlist

   Confirm Edit, Write, Bash, MCP, and Agent are absent before launch.

   sed -n '1,12p' .claude/agents/read-only-reviewer.md

3. Run against a harmless fixture

   Ask the main session to use the named agent on one text file; model execution was not performed in this audit.

4. Challenge the result independently

   Verify cited lines yourself and reject conclusions unsupported by the file.

Expected result

The reviewer returns file-grounded findings without editing, running commands, calling MCP, or spawning another agent.

Validation

• Inspect tool usage rather than trusting the final prose.
• Confirm `git status --short` is unchanged.
• Run a negative prompt that requests an edit and verify the boundary holds.

Failure handling

Cleanup or rollback

• Return to the original directory and remove only the printed AGENT_LAB path.
• Disable a real project agent through reviewed version control rather than editing user-level agents.

Boundaries and when not to use it

• Subagents inherit available tools unless restricted; least privilege must be explicit.
• Delegation separates context, not responsibility: the main reviewer must verify findings and data exposure.