# How Caveman Subagents (Investigator, Builder, Reviewer) Differ from Standard Agents > Discover how Caveman subagents investigator, builder, and reviewer differ from standard agents. Learn about their specialized roles, limited toolsets, and rigid output formats. - Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman) - Tags: deep-dive - Published: 2026-07-07 --- **Caveman subagents are specialized, scope-limited agents with restricted toolsets and rigid output formats, whereas the standard agent acts as a universal orchestrator with full capabilities.** The JuliusBrussee/caveman repository implements a modular agent architecture that separates a general-purpose main agent from three specialized subagents. Understanding how Caveman subagents differ from standard agents is essential for leveraging the tool's full potential while maintaining safety boundaries. Each subagent—Investigator, Builder, and Reviewer—operates under strict contracts that limit their scope, tools, and output formats compared to the flexible main agent. ## Core Architectural Distinctions ### Purpose and Scope Constraints The standard Caveman agent serves as a universal orchestrator capable of chaining multiple steps, invoking other agents, and producing elaborate conversational output. In contrast, subagents are purpose-built for specific task classes: the **Investigator** handles read-only code location queries, the **Builder** performs small bounded edits (1-2 files), and the **Reviewer** generates concise diff reports. Subagents enforce strict scope limitations through hard-coded refusal patterns. According to the source code in [`agents/cavecrew-builder.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-builder.md), the Builder refuses edits affecting more than two files with a `too-big.` terminal line. Similarly, the Investigator never suggests fixes, and the Reviewer never expands beyond the supplied diff. These deterministic refusals ensure predictable, safe behavior. ### Tool Whitelists and Restrictions Unlike the standard agent which accesses the full Caveman tool suite (Read, Write, Edit, Grep, Glob, Bash, etc.), each subagent declares a restricted **tool whitelist** in its YAML header. - **Investigator**: `[Read, Grep, Glob, Bash]` (as defined in [`agents/cavecrew-investigator.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-investigator.md)) - **Builder**: `[Read, Edit, Write, Grep, Glob]` (as defined in [`agents/cavecrew-builder.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-builder.md)) - **Reviewer**: `[Read, Grep, Bash]` (as defined in [`agents/cavecrew-reviewer.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-reviewer.md)) This whitelist approach prevents scope creep and ensures the Investigator cannot write files, or the Builder cannot execute arbitrary bash commands. ### Machine-Readable Output Formats While the standard agent produces free-form text with explanations and suggestions, subagents emit rigid, machine-readable receipts: - **Builder**: Diff receipts formatted as ` — ` - **Investigator**: Tables formatted as `path:line — symbol — note` - **Reviewer**: Structured reports as `path:line: : . .` These constrained outputs make subagent results parseable by downstream automation or the main agent itself. ## Technical Implementation and Source Files The subagent definitions reside in specific markdown files within the repository. According to the Caveman source code, [`agents/cavecrew-investigator.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-investigator.md), [`agents/cavecrew-builder.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-builder.md), and [`agents/cavecrew-reviewer.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-reviewer.md) contain the system prompts and YAML headers that enforce these restrictions. The [`skills/cavecrew/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/README.md) provides human-readable documentation of these capabilities, while `src/plugins/opencode/commands/*.md` maps CLI invocations to the appropriate subagent. The master index in [`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/AGENTS.md) lists all available agents including these three specialized workers. ## Practical Usage Examples Invoke subagents directly from the command line to bypass the orchestration logic: ```bash # Use the Investigator subagent to locate a symbol caveman investigator "where is safeWriteFlag defined?" ``` ```bash # Use the Builder subagent to apply a tiny typo fix caveman builder "fix typo in src/utils.js line 42" ``` ```bash # Use the Reviewer subagent to get a concise diff review caveman reviewer "$(git diff HEAD~1 HEAD)" ``` Each command returns only the structured output format specific to that agent, which can be parsed programmatically or displayed to the user. ## Summary - **Caveman subagents** differ from the standard agent through strict scope limitations, tool whitelists, and rigid output formats. - The **Investigator** operates read-only with `[Read, Grep, Glob, Bash]`, while the **Builder** handles 1-2 file edits using `[Read, Edit, Write, Grep, Glob]`. - The **Reviewer** analyzes diffs using `[Read, Grep, Bash]` and outputs structured severity reports. - Subagents operate in isolation and emit deterministic refusal lines like `too-big.` or `Read-only.` when encountering out-of-scope requests. - Configuration files in `agents/cavecrew-*.md` define these constraints through YAML headers and system prompts. ## Frequently Asked Questions ### What tools are available to each Caveman subagent? The Investigator subagent has access to `[Read, Grep, Glob, Bash]` according to [`agents/cavecrew-investigator.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-investigator.md). The Builder subagent uses `[Read, Edit, Write, Grep, Glob]` as specified in [`agents/cavecrew-builder.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-builder.md). The Reviewer subagent operates with `[Read, Grep, Bash]` per [`agents/cavecrew-reviewer.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-reviewer.md). These tool whitelists prevent cross-functional operations like the Investigator writing files or the Builder executing bash commands. ### How does the Builder subagent handle requests affecting multiple files? The Builder subagent strictly refuses edits affecting more than two files. When encountering such requests, it emits a deterministic refusal line—typically `too-big.`—and stops execution. This safety mechanism ensures the Builder remains bounded to small, focused modifications as designed in the Caveman architecture. ### Can subagents invoke other agents or perform multi-step workflows? No. Unlike the standard agent which can delegate work and aggregate results, subagents operate in isolation. They never spawn other agents and never perform actions outside their declared scope. If a subagent encounters a task beyond its capabilities, it emits a single refusal line (e.g., `Read-only. Spawn cavecrew-builder.`) rather than attempting retries or fallbacks. ### Where are the subagent definitions stored in the Caveman repository? The subagent definitions reside in [`agents/cavecrew-investigator.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-investigator.md), [`agents/cavecrew-builder.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-builder.md), and [`agents/cavecrew-reviewer.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-reviewer.md). The [`skills/cavecrew/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/README.md) documents their capabilities, while `src/plugins/opencode/commands/*.md` contains the CLI command specifications. The complete agent index is available in [`AGENTS.md`](https://github.com/JuliusBrussee/caveman/blob/main/AGENTS.md) at the repository root.