← posts / ai integrations

Claude Code subagents: write a read-only reviewer and pin its model and tools

Write a code-reviewer subagent file with a read-only tool allowlist and a pinned model, learn how the model is resolved, and add a PreToolUse hook for finer limits.

if.codesNov 17, 2026 · 3 min read#claude-code#subagents#code-review#hooksAI-assisted

A subagent in Claude Code runs in its own context window with its own tool list and, if you choose, its own model. That keeps verbose output out of your main conversation and lets you restrict what a task can touch. This post builds a read-only code reviewer, then covers model resolution, where agent files live and when not to delegate. Everything here comes from the official sub-agents documentation.

Subagents operate as isolated contexts to keep the main conversation clean.
Subagents operate as isolated contexts to keep the main conversation clean.

The file format

A subagent is a Markdown file with YAML frontmatter. The body after the closing --- becomes the subagent's system prompt. Only name and description are required. The fields you will use most:

  • description: when Claude should delegate to this subagent.
  • tools: the tools it may use, as a comma-separated string or a YAML list. If omitted, it inherits all tools available to subagents.
  • disallowedTools: tools to remove from the inherited or specified list.
  • model: sonnet, opus, haiku, fable, a full model ID, or inherit.
  • maxTurns: the maximum number of agentic turns before it stops.

Field names are camelCase and must match exactly: the docs say Claude Code silently ignores unrecognised fields, so a typo gives you no error.

A read-only reviewer

Save this as .claude/agents/code-reviewer.md. The tool allowlist is what makes it read-only: it can read, glob and grep, and it has no edit or shell tool.

A read-only reviewer focuses on analysis without modifying the source code.
A read-only reviewer focuses on analysis without modifying the source code.
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
maxTurns: 20
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
Report findings as a list with file and line, and do not edit anything.

The first five lines of the body come from the documentation's example. The maxTurns line and the last sentence are my additions, using fields from the same table.

Where the file can live

When subagents share a name, the higher-priority location wins:

  1. Managed settings (organisation-wide)
  2. The --agents CLI flag (current session)
  3. .claude/agents/ (current project)
  4. ~/.claude/agents/ (all your projects)
  5. A plugin's agents/ directory

Put a reviewer in .claude/agents/ and commit it, and the whole team gets the same one.

Want AI wired into the systems you already run?I build LLM integrations with costs and quality you can see. The estimate is free.

How the model is chosen

If several sources set a model, Claude Code uses the first that applies:

  1. The per-invocation model parameter Claude passes when it starts the subagent.
  2. The model field in the subagent definition, including inherit.
  3. The CLAUDE_CODE_SUBAGENT_MODEL environment variable.
  4. The main conversation's model, or the spawning subagent's model for a nested one.

So pinning model: sonnet in the file beats the environment variable, but Claude can still override it per call. If cost matters, check which model a review really ran on.

Finer limits with a PreToolUse hook

A tool allowlist is all or nothing per tool. For a tool you want to allow in part, hooks in the frontmatter run only while that subagent is active. The documentation's example allows a Bash tool but only for read-only SQL:

PreToolUse hooks act as a fine-grained filter for tool execution.
PreToolUse hooks act as a fine-grained filter for tool execution.
---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

The script reads the hook input as JSON on stdin and blocks the command by exiting with code 2:

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

Two gotchas from the docs: run chmod +x on the script on macOS and Linux, or the hook fails instead of blocking, and project-level agent hooks only run after you trust the folder that contains the agent file.

When not to delegate

The documentation says to stay in the main conversation when:

  • The task needs frequent back-and-forth or iterative refinement.
  • Several phases share significant context, such as planning, implementation and testing.
  • You are making a quick, targeted change.
  • Latency matters: a non-fork subagent starts with a fresh context and may need time to gather information.

A reviewer is a good fit for the opposite case: a self-contained read of a diff that produces a short report.

Sources

if.codesI build RAG, AI integrations and agent pipelines on Go and Python backends — and write about it here.
// keep reading

More posts on AI and backends.

// free quote

Read something you need? I’ll quote it for free.

RAG, AI integrations, agents or the backend underneath — tell me what you have and what should change. I read every request myself.

Free · no commitment

Tell me what you have. I’ll tell you what it takes.

1Describe the projectA few sentences is enough — about two minutes.
2I review itI read it myself and may ask a follow-up question.
3You get a free quoteScope, approach and estimate — yours to keep, no strings.
What kind of project is it?
Free and without obligation. Your details are used only to reply — see the privacy policy.