Add file reading guardrails to prevent review agent hallucination loops

[derekmisler]

Closes: https://github.com/docker/gordon/issues/190

Summary

• Adds explicit file reading guardrails to the root review agent prompt to prevent it from entering infinite loops of guessing non-existent file paths
• Removes directory_tree from root agent toolset to discourage deep repo exploration

Problem

The root review agent was entering degenerate loops of hallucinated read_file calls, burning through the entire 40-minute timeout without ever posting a review. In this observed failure, the agent made 500+ consecutive read_file calls to paths that don't exist, including completely unrelated concepts like gordon/raft.md, gordon/byzantine-fault-tolerance.md, gordon/six-sigma.md, gordon/kaizen.md, etc.

The PR being reviewed was a simple 349-line rebrand diff. The agent read the diff successfully, then started speculatively exploring the repo and never stopped.

Changes

New "File Reading Guardrails" section in root agent instructions:

1. Only read directly relevant files — diff, AGENTS.md/CLAUDE.md, and files referenced in the diff
2. Never guess file paths — use list_directory first
3. Circuit breaker — stop after 3 consecutive "not found" reads
4. Cap total reads — max 10 files for root agent (drafter/verifier handle deeper analysis)
5. Never enumerate topics as paths — prevents the hallucinated concept-name loop

Also removes directory_tree from root agent toolset since the drafter and verifier handle file-level analysis.

Test plan

• Re-run review on the same PR that triggered the failure
• Verify the agent completes within a reasonable time and posts a review
• Run on a large diff (>1500 lines) to confirm chunked review still works
• Run existing evals to check for regressions

[docker-agent]

🟢 Code Review: APPROVED

Summary

This PR adds file reading guardrails to prevent the review agent from entering hallucination loops. The changes include:

• New "CRITICAL: File Reading Guardrails" section with 5 rules to limit file exploration
• Removal of directory_tree from the root agent's filesystem toolset

Analysis: All potential issues identified during review were related to the enforceability of prompt-based rules. However, these are standard and appropriate mechanisms for AI agent configuration in YAML-based agent frameworks. The guardrails use clear, imperative language with high salience ("MUST NOT", "CRITICAL") to guide agent behavior, which is the expected design pattern. The PR also includes technical enforcement by removing directory_tree from the toolset, demonstrating understanding of both prompt-based and technical controls.

Verdict: No bugs found in the changed code. The implementation is sound and follows best practices for AI agent configuration. ✅

Test Coverage

As noted in the PR description, please verify:

• Re-run on the original failing PR
• Test with large diffs (>1500 lines)
• Run existing evals for regression checks

[krissetto]

lots of "do this, dont do that", in general in this bot..hope it keeps behaving, we might need to change prompting strat eventually

[krissetto]

why agents/claude.md?

[derekmisler]

Just following the trends I've noticed. These are the files people tend to add the most, but that prompt-files flag appends the contents of the prompt files to every request, which seems like a waste of tokens. So I'm trying out just telling the agents to read these files once.