fix(agents): add context budget, file discovery, and capability guardrails#117
fix(agents): add context budget, file discovery, and capability guardrails#117marcusquinn merged 4 commits intomainfrom
Conversation
…rails - Add 3 new Critical Rules to AGENTS.md: - File discovery: Use git ls-files/fd, NOT mcp_glob - Context budget: Never >100K tokens; README first for remote repos - Agent capability check: Verify Edit/Write/Bash before edits - Enhance File Discovery section with self-check prompt and table - Add remote repository guardrails to context-builder.md - Create tools/context/context-guardrails.md with comprehensive guidance - Add Tool Selection Checklist to build-agent.md Prevents context overload from large repo packing and enforces optimal tool selection patterns. Fixes issue where Plan+ agent attempted edits without suggesting switch to Build+, and where mcp_glob was used instead of git ls-files.
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughAdds and reorganized documentation and guardrails for file-discovery and context budgeting: STOP-before-mcp_glob guidance, a self-check workflow, a tool-selection checklist, remote-repo packing protocol, and a new context-guardrails document with token/size thresholds and recovery steps. Changes
Sequence Diagram(s)(omitted — changes are documentation and guardrails without new multi-component runtime control flow) Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Summary of ChangesHello @marcusquinn, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the robustness and efficiency of agents by implementing critical guardrails and guidelines. It addresses common pitfalls such as exceeding context window limits, using suboptimal tools for file operations, and agents attempting tasks beyond their designated capabilities. The changes introduce a structured approach to context management, particularly for remote repositories, and promote the use of more efficient command-line tools, ultimately leading to more reliable and performant agent operations. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Sun Jan 18 16:38:26 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a valuable set of guardrails for the AI agent system, addressing critical issues like context overload, incorrect tool selection, and capability mismatches. The new documentation in AGENTS.md, build-agent.md, and the new context-guardrails.md provides clear, actionable rules and workflows that will significantly improve the agent's robustness and efficiency. The changes are well-structured and clearly explained. My review includes a couple of suggestions to enhance the clarity and consistency of the new documentation.
|
|
||
| GitHub API `.size` is in KB. Rough token estimate: | ||
|
|
||
| - **Repo KB x 10 = approximate full-pack tokens** (very rough) |
There was a problem hiding this comment.
This token estimation formula contradicts the 'Size Thresholds' tables in this file (lines 22-26) and in context-builder.md.
- The tables suggest a ratio where
< 500 KBcorresponds to< 50Ktokens, which is approximately1 KB ≈ 100 tokens. - This formula,
Repo KB x 10, suggests a ratio of1 KB ≈ 10 tokens.
This 10x discrepancy could lead to significant miscalculations when estimating context size. To ensure consistency, the formula should be updated to align with the values used in the tables.
| - **Repo KB x 10 = approximate full-pack tokens** (very rough) | |
| - **Repo KB x 100 = approximate full-pack tokens** (very rough) |
| | Task | Preferred Tool | Avoid | Why | | ||
| |------|---------------|-------|-----| | ||
| | Find files by pattern | `git ls-files` or `fd` | `mcp_glob` | CLI is 10x faster | | ||
| | Search file contents | `rg` (ripgrep) | `mcp_grep` for simple cases | CLI more powerful | |
There was a problem hiding this comment.
The wording in the 'Avoid' column for this task is a bit confusing. "Avoid mcp_grep for simple cases" could be misinterpreted, as it implies it might be acceptable for complex cases, whereas the 'Why' column suggests rg is always superior. To make the guidance clearer and more direct, consider rephrasing to unambiguously recommend against using mcp_grep when rg is available.
For example:
| Search file contents | `rg` (ripgrep) | `mcp_grep` | `rg` is more powerful and should always be preferred. |![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @.agent/tools/context/context-builder.md:
- Around line 67-83: The guidance in "CRITICAL: Remote Repository Guardrails"
references using webfetch but the agent frontmatter currently disables it via
the token "webfetch: false"; update the subagent frontmatter to enable webfetch
(set webfetch: true) so the recommended steps (e.g., webfetch
"https://github.com/{user}/{repo}" and repomix_pack_remote_repository with
includePatterns) are executable, or alternatively adjust the guidance to use an
available fetch tool if you intentionally want webfetch disabled.
🧹 Nitpick comments (2)
.agent/AGENTS.md (1)
110-135: Consider moving detailed File Discovery guidance out of root AGENTS.md.
The new self-check + table add a lot of instruction surface area. To stay within the root AGENTS.md instruction-budget and progressive-disclosure guidance, keep only a brief pointer here and move the full table/workflow into a subagent (e.g.,tools/context/context-guardrails.md).Based on coding guidelines, ...
.agent/tools/context/context-guardrails.md (1)
35-43: Reference Claude's context window generically rather than hard-coding "200K tokens".As of January 2026, Claude supports multiple context window tiers (200K standard, 500K enterprise, 1M for select high-tier deployments). Hard-coding "200K" creates documentation drift and may mislead users about actual limits available to them. Rephrase as "current model context window" or reference the active model's documented limit from Anthropic's official documentation.
🤖 Augment PR SummarySummary: Adds documentation guardrails to reduce context overload and steer agents toward faster CLI tooling and capability-appropriate behavior. Changes:
Technical Notes: This is a documentation/protocol-focused PR (no runtime code changes) and emphasizes keeping context-heavy operations within a strict budget (≤100K tokens) via incremental escalation and size-based thresholds. 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
|
|
||
| | Tool | Typical Output | Risk Level | | ||
| |------|----------------|------------| | ||
| | `repomix_pack_remote_repository` | 100K - 5M+ tokens | **EXTREME** | |
There was a problem hiding this comment.
This document refers to repomix_pack_remote_repository, but the Repomix MCP tooling documented elsewhere here is repomix_pack_repository (and the helper script uses context-builder-helper.sh remote). If the name is wrong, these guardrails will be hard to follow (also applies to the new references in tools/context/context-builder.md and tools/build-agent/build-agent.md).
🤖 Was this useful? React with 👍 or 👎
|
|
||
| GitHub API `.size` is in KB. Rough token estimate: | ||
|
|
||
| - **Repo KB x 10 = approximate full-pack tokens** (very rough) |
There was a problem hiding this comment.
The rule of thumb Repo KB x 10 = approximate full-pack tokens doesn’t match the earlier size table (<500KB → <50K tokens implies ~x100). Consider reconciling these so size checks lead to consistent decisions.
🤖 Was this useful? React with 👍 or 👎
| | Read file contents | `mcp_read` | `cat` via bash | Better error handling | | ||
| | Edit files | `mcp_edit` | `sed` via bash | Safer, atomic | | ||
| | Web content | `mcp_webfetch` | `curl` via bash | Handles redirects | | ||
| | Remote repo research | `webfetch` README first | `repomix_pack_remote_repository` | Prevents context overload | |
There was a problem hiding this comment.
The checklist mixes mcp_webfetch (row above) with webfetch here; standardizing the naming would help ensure agents call the intended tool in a given runtime (MCP vs built-in capability).
🤖 Was this useful? React with 👍 or 👎
- Fix token estimation: KB x 100 (not x 10) to match size thresholds - Enable webfetch in context-builder.md frontmatter - Standardize tool naming: use mcp_repomix_pack_remote_repository - Add helper script reference: context-builder-helper.sh remote - Clarify mcp_grep avoidance in tool selection checklist Addresses feedback from Gemini, CodeRabbit, and Augment reviews.
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Sun Jan 18 16:51:06 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @.agent/tools/context/context-guardrails.md:
- Around line 128-165: The fenced code block under the "Recovery from Context
Overflow" section is indented and misformatted; fix it by replacing the indented
snippet with a properly aligned fenced code block (three backticks) so the block
begins at column 0 and closes with matching backticks, preserving the exact
content of the /remember FAILED_APPROACH line and the sample message; locate the
block in the "Recovery from Context Overflow" section (look for the string
"/remember FAILED_APPROACH" and the surrounding triple-backtick markers) and
ensure both opening and closing fences are unindented and use the same language
tag (`text`).
♻️ Duplicate comments (2)
.agent/tools/build-agent/build-agent.md (1)
639-658: Approve the Tool Selection Checklist with minor naming verification needed.The Tool Selection Checklist effectively operationalizes the guardrails described in the PR objectives. The self-check prompts (lines 652-656) provide actionable decision points before tool invocation, and the reference to
context-guardrails.mdensures agents can access detailed guidance.However, past reviewers have flagged potential issues:
- The
mcp_greprow wording may need clarification (as noted by gemini-code-assist[bot])- Naming consistency between
mcp_webfetchandwebfetchshould be verified (as noted by augmentcode[bot])Please verify the MCP tool naming is consistent with the actual installed tools:
#!/bin/bash # Description: Verify MCP tool naming consistency for repomix and webfetch # Check if mcp_repomix_pack_remote_repository exists in MCP configurations rg -n "mcp_repomix_pack_remote_repository|repomix_pack_repository" .agent/ --type md # Check webfetch vs mcp_webfetch usage patterns rg -n "mcp_webfetch|webfetch" .agent/tools/build-agent/build-agent.md --type md -C2.agent/tools/context/context-guardrails.md (1)
33-73: Approve workflow and rules; verify tool naming consistency.The Problem section effectively illustrates risk levels, and the Golden Rules provide clear, numbered guardrails. The Remote Repository Research Workflow diagram presents a progressive escalation strategy that aligns with the PR's context budget objectives.
However, a naming inconsistency exists at line 39 where the tool is referenced as
repomix_pack_remote_repository, while lines 85 and 87 usemcp_repomix_pack_remote_repository. As noted by augmentcode[bot] in past reviews, this inconsistency could confuse agents about which tool to invoke.The verification script in the previous comment will confirm the correct tool naming across all files.
🧹 Nitpick comments (1)
.agent/tools/context/context-guardrails.md (1)
1-8: Consider declaring all tool permissions explicitly.The YAML frontmatter follows the subagent pattern but only declares
read,bash, andwebfetchpermissions. Per the build-agent.md guidelines, explicitly declaring all tool permissions (includingwrite: false,edit: false,glob: true,grep: true,task: false) improves clarity about the agent's intended capabilities.♻️ Complete frontmatter declaration
--- description: Context budget management and guardrails for AI assistants mode: subagent tools: read: true + write: false + edit: false bash: true + glob: true + grep: true webfetch: true + task: false ---
| ## Recovery from Context Overflow | ||
|
|
||
| If you hit "prompt is too long": | ||
|
|
||
| 1. **Start a new conversation** - Context cannot be reduced mid-session | ||
| 2. **Ask user what specific question they have** - Focus on the actual need | ||
| 3. **Use targeted approach** - Get only needed context | ||
| 4. **Document the failure** - Use `/remember` for future sessions: | ||
| ``` | ||
| /remember FAILED_APPROACH: Attempted to pack {repo} without size check. | ||
| Repo was {size}KB (~{tokens} tokens). Use includePatterns next time. | ||
| ``` | ||
|
|
||
| ## File Discovery Guardrails | ||
|
|
||
| Before using `mcp_glob`, check if faster alternatives work: | ||
|
|
||
| | Use Case | Preferred Tool | Fallback | | ||
| |----------|---------------|----------| | ||
| | Git-tracked files | `git ls-files '*.md'` | `mcp_glob` | | ||
| | Untracked files | `fd -e md` | `mcp_glob` | | ||
| | System-wide search | `fd -g '*.md' ~/.config/` | `mcp_glob` | | ||
|
|
||
| **Why?** `mcp_glob` is CPU-intensive on large codebases. CLI tools are 10x faster. | ||
|
|
||
| ## Agent Capability Check | ||
|
|
||
| Before attempting edits, verify you have the required tools: | ||
|
|
||
| ```text | ||
| Self-check: "Do I have Edit/Write/Bash tools for this task?" | ||
|
|
||
| If NO (e.g., in Plan+ agent): | ||
| -> Suggest: "This task requires edits. Please switch to Build+ agent." | ||
|
|
||
| If YES: | ||
| -> Proceed with pre-edit git check | ||
| ``` |
There was a problem hiding this comment.
Approve guardrail content; address markdown formatting.
The Recovery, File Discovery, and Agent Capability Check sections provide essential guardrails:
- Recovery steps include learning pattern via
/rememberto prevent repeat failures - File Discovery table aligns with AGENTS.md File Discovery rules (CLI tools preferred over mcp_glob)
- Agent Capability Check prevents agents from recommending edits they cannot perform
However, the fenced code block at line 136 needs formatting corrections per static analysis:
🔧 Fix markdown formatting for fenced code block
4. **Document the failure** - Use `/remember` for future sessions:
+
- ```
+ ```text
/remember FAILED_APPROACH: Attempted to pack {repo} without size check.
Repo was {size}KB (~{tokens} tokens). Use includePatterns next time.
```🧰 Tools
🪛 GitHub Check: Codacy Static Code Analysis
[notice] 136-136: .agent/tools/context/context-guardrails.md#L136
Fenced code blocks should be surrounded by blank lines
[notice] 136-136: .agent/tools/context/context-guardrails.md#L136
Fenced code blocks should have a language specified
🪛 markdownlint-cli2 (0.18.1)
136-136: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
136-136: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In @.agent/tools/context/context-guardrails.md around lines 128 - 165, The
fenced code block under the "Recovery from Context Overflow" section is indented
and misformatted; fix it by replacing the indented snippet with a properly
aligned fenced code block (three backticks) so the block begins at column 0 and
closes with matching backticks, preserving the exact content of the /remember
FAILED_APPROACH line and the sample message; locate the block in the "Recovery
from Context Overflow" section (look for the string "/remember FAILED_APPROACH"
and the surrounding triple-backtick markers) and ensure both opening and closing
fences are unindented and use the same language tag (`text`).
Fixes Codacy markdown style issues: - Fenced code blocks should be surrounded by blank lines - Fenced code blocks should have a language specified
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Sun Jan 18 16:57:21 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
- Add check_markdown_lint() function to linters-local.sh - Checks files changed in current branch vs main - Uses markdownlint if installed, falls back to basic regex check - Currently non-blocking (warns only) due to pre-existing issues - Detects fenced code blocks without language specifier (MD040) This would have caught the Codacy issues before PR submission.
|
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Sun Jan 18 17:06:40 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
1 participant
Summary
Adds guardrails to prevent context overload and enforce optimal tool selection patterns.
Problem
mcp_globinstead of recommendedgit ls-files/fdChanges
AGENTS.md Critical Rules (+3 new rules):
git ls-filesorfd, NOTmcp_globFile Discovery section: Enhanced with self-check prompt and decision table
context-builder.md: Added "Remote Repository Guardrails" section with size thresholds
NEW: context-guardrails.md: Comprehensive reference for:
build-agent.md: Added "Tool Selection Checklist" with preferred vs avoided tools
Testing
Related
Discovered during Clawdbot research task (t046) when repomix returned 4.4M tokens
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.