perf: add 20 KB large-file guard to prevent MCP file read token spikes by Copilot · Pull Request #48454 · github/gh-aw

Copilot · 2026-07-27T21:37:04Z

Unguarded github-mcp-server-get_file_contents calls on large workflow/skill markdown files cause 2–2.5× input token inflation mid-session (observed: 44K → 108K tokens across 8 turns). The fix enforces a 20 KB threshold after which agents must use targeted reads instead of full-file reads.

Changes

AGENTS.md — New Critical Rule Weekly Research Report: AI Workflow Automation Landscape and Market Opportunities - August 2025 #7: files >20 KB must use grep/glob/bash/view_range instead of get_file_contents; links to the full technique
.github/aw/token-optimization.md
- New "Bound file reads" Quick-Reference Checklist item
- New Technique 11 — Cap Session Context Growth from Large File Reads with the 20 KB rule, a targeted-read tool table, size-check-first process, lazy glob **/*.md anti-pattern warning, and before/after examples:

# Before — injects full 34 KB file into context
get_file_contents path=".github/aw/syntax-agentic.md"

# After — check size first, then read only what's needed
bash: wc -c .github/aw/syntax-agentic.md   # → 33908 bytes (> 20 KB)
bash: grep -n "## Sub-agents" .github/aw/syntax-agentic.md
# or
view: .github/aw/syntax-agentic.md view_range=[45, 90]

.github/aw/optimize-agentic-workflow.md — Adds large file reads as priority check Add workflow: githubnext/agentics/weekly-research #3 in the max-ai-credits exceeded entry point

Fixes [copilot-opt] perf: cap session context growth — large MCP file reads cause 2.5× token inflation mid-session #48426

…reads Add a 20 KB file-size guard to prevent late-session token spikes from unguarded github-mcp-server-get_file_contents calls on large workflow and skill markdown files. Session analysis showed 2–2.5× input token inflation when two large workflow files were loaded via MCP mid-session. Changes: - AGENTS.md: Add rule #7 — large-file guard (> 20 KB → use targeted reads) - token-optimization.md: Add "Bound file reads" checklist item and Technique 11 (Cap Session Context Growth from Large File Reads) - optimize-agentic-workflow.md: Elevate large file reads as priority #3 cost driver check in the max-ai-credits exceeded entry point Closes #48426 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

github-actions · 2026-07-28T00:58:30Z

🤖 PR Triage

Field	Value
Category	chore (perf)
Risk	🟢 low
Score	42/100 (impact:20 urgency:12 quality:10)
Action	⚡ `fast_track`

Adds 20 KB large-file guard to prevent MCP file read token spikes (2–2.5× inflation observed). Tiny change (61 adds, 3 dels, 3 files). Low risk, good ROI once undrafted.

Generated by 🔧 PR Triage Agent · sonnet46 · 63.9 AIC · ⌖ 5.94 AIC · ⊞ 5.7K · ◷

pelikhan

@copilot apply caveman optimization to changes

pelikhan · 2026-07-28T01:34:28Z

+
+Unguarded full-file reads via `github-mcp-server-get_file_contents` are the single most common cause of late-session token spikes. Workflow markdown files (`.github/aw/*.md`, `.github/workflows/*.md`) and skill files can exceed hundreds of KB. Loading even two such files mid-session can 2–2.5× the input context size, degrading model performance and inflating cost.
+
+**Observed evidence:** In session `30290667268`, input grew from **44,043 → 108,331 tokens** (2.46×) across 8 turns. The spike occurred at turn 7 when two large workflow markdown files were loaded via MCP without a size guard.


@copilot delete sentence

Done in 3c8a06e~1 → latest. Sentence removed.

…ence Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-07-28T01:41:54Z

@copilot apply caveman optimization to changes

Applied in the latest commit. Technique 11 trimmed from ~45 lines to ~15 (rule + one paragraph + single before/after example). AGENTS.md rule also trimmed by one redundant sentence.

pelikhan · 2026-07-28T01:47:01Z

 ---

+## Technique 11 — Cap Session Context Growth from Large File Reads
+


@copilot suggest to use the gh proxy mode instead and access github through gh and bash to leverage piping, jq, etc...

Done. Added a gh-proxy paragraph with a gh api … | base64 -d | grep example showing how to pipe and filter before content enters context, followed by the local-read fallback for non-GitHub-hosted files.

…et_file_contents for large files Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot

Pull request overview

Adds guidance to prevent large MCP file reads from inflating agent context and token usage.

Changes:

Establishes a 20 KB large-file guard.
Documents targeted-read alternatives.
Adds large-file reads to token-optimization diagnostics.

Show a summary per file

File	Description
`AGENTS.md`	Adds the repository-wide large-file rule.
`.github/aw/token-optimization.md`	Documents the optimization technique and examples.
`.github/aw/optimize-agentic-workflow.md`	Adds large reads to priority diagnostics.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (3)

.github/aw/token-optimization.md:391

This states a broader invariant than the optimization actually needs and contradicts the recommended gh api ... | grep pipeline below, which downloads and decodes the entire file but filters it before tool output enters the model context. Framing the guard around context injection avoids incorrectly prohibiting safe local processing of a large file.

> **Files larger than 20 KB must not be read in full.** Use targeted reads instead.

.github/aw/token-optimization.md:393

wc -c <path> only measures the local checkout, while get_file_contents can target an arbitrary owner, repository, and ref. For a cross-repository or non-checked-out ref, this either fails or measures a different file, so the guard can still allow the large remote file into context. The size check needs to address the exact MCP target.

Before calling `get_file_contents`, check size with `wc -c <path>`. If > 20 KB, use `grep`, `glob`, `bash head`, or `view` with `view_range` to read only the section you need. The same rule applies after `glob **/*.md` — read each matched file with `grep` or `view_range`, not full-file reads.

.github/aw/token-optimization.md:400

This replacement silently reads the repository's default branch. A get_file_contents call may have targeted a PR branch, tag, or commit via ref; following this example would then inspect stale or unrelated content. Preserve the target ref in the Contents API request.

gh api repos/{owner}/{repo}/contents/.github/aw/syntax-agentic.md \
  --jq '.content' | base64 -d | grep -n "## Sub-agents"

Files reviewed: 3/3 changed files
Comments generated: 4
Review effort level: Medium

+## Technique 11 — Cap Session Context Growth from Large File Reads
+
+> **Files larger than 20 KB must not be read in full.** Use targeted reads instead.
+
+Before calling `get_file_contents`, check size with `wc -c <path>`. If > 20 KB, use `grep`, `glob`, `bash head`, or `view` with `view_range` to read only the section you need. The same rule applies after `glob **/*.md` — read each matched file with `grep` or `view_range`, not full-file reads.


 4. After workflow markdown changes (`.md` under `.github/workflows/`), run `make recompile`.
 5. Do not add `.lock.yml` files to `.gitignore`.
 6. Never attempt to trigger a workflow run (e.g., `gh run`, `gh aw run`) as part of a Copilot cloud agent run. The token does not have the required access. Always fail with an error — do not task the user or ask them to run it manually.
+7. **Large-file guard**: before reading any file with `github-mcp-server-get_file_contents`, check its size. Files larger than 20 KB must be read with targeted tools (`grep`, `glob`, `bash`, or `view` with `view_range`) instead of full-file reads. See [token-optimization.md](.github/aw/token-optimization.md) for the full technique.


 - [ ] **Prompt size**: Strip redundant instructions, examples, and pleasantries from the prompt body
 - [ ] **Dynamic context**: Inject only required fields — `${{ github.event.issue.number }}` not the full event payload
 - [ ] **Pull context on demand**: query logs/data only after a hypothesis forms; avoid preloading large raw dumps into the initial prompt
+- [ ] **Bound file reads**: for files > 20 KB, use `bash`/`grep`/`glob`/`view_range` instead of full-file MCP reads — late-session token spikes most often trace to unguarded `get_file_contents` calls on large workflow or skill markdown


-3. Are there repetitive extraction steps that sub-agents could handle cheaply?
-4. Does the frontier model handle tasks that a small model could do?
-5. Can the workflow stay within its current budget after applying and measuring all applicable optimizations?
+3. Are there large file reads (> 20 KB) via `get_file_contents` that could be replaced with `grep`/`glob`/`view_range`? These are the most common cause of late-session token spikes.


Initial plan

b820467

Copilot AI assigned Copilot and pelikhan Jul 27, 2026

Copilot started work on behalf of pelikhan July 27, 2026 21:37 View session

Copilot AI linked an issue Jul 27, 2026 that may be closed by this pull request

[copilot-opt] perf: cap session context growth — large MCP file reads cause 2.5× token inflation mid-session #48426

Closed

Copilot AI changed the title ~~[WIP] Optimize session context growth from large MCP file reads~~ perf: add 20 KB large-file guard to prevent MCP file read token spikes Jul 27, 2026

Copilot finished work on behalf of pelikhan July 27, 2026 21:51

Copilot AI requested a review from pelikhan July 27, 2026 21:51

github-actions Bot added pr-action:fast_track pr-agent:copilot pr-priority:medium pr-risk:low pr-type:chore labels Jul 28, 2026

pelikhan reviewed Jul 28, 2026

View reviewed changes

Copilot started work on behalf of pelikhan July 28, 2026 01:36 View session

perf: caveman optimize Technique 11 and delete observed-evidence sent…

a373b36

…ence Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI requested a review from pelikhan July 28, 2026 01:42

Copilot finished work on behalf of pelikhan July 28, 2026 01:42

pelikhan reviewed Jul 28, 2026

View reviewed changes

Copilot started work on behalf of pelikhan July 28, 2026 01:48 View session

perf: suggest gh-proxy + gh/bash piping as preferred alternative to g…

f70ec36

…et_file_contents for large files Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot finished work on behalf of pelikhan July 28, 2026 01:53

Copilot AI requested a review from pelikhan July 28, 2026 01:53

pelikhan marked this pull request as ready for review July 28, 2026 01:57

Copilot AI review requested due to automatic review settings July 28, 2026 01:57

pelikhan merged commit 7918bcd into main Jul 28, 2026

pelikhan deleted the copilot/copilot-opt-prevent-context-growth branch July 28, 2026 01:57

Copilot started reviewing on behalf of pelikhan July 28, 2026 01:57 View session

Copilot AI reviewed Jul 28, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

perf: add 20 KB large-file guard to prevent MCP file read token spikes - #48454

perf: add 20 KB large-file guard to prevent MCP file read token spikes#48454
pelikhan merged 4 commits into
mainfrom
copilot/copilot-opt-prevent-context-growth

Copilot AI commented Jul 27, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 28, 2026

Uh oh!

pelikhan left a comment

Uh oh!

pelikhan Jul 28, 2026

Uh oh!

Copilot AI Jul 28, 2026

Uh oh!

Copilot AI commented Jul 28, 2026

Uh oh!

pelikhan Jul 28, 2026

Uh oh!

Copilot AI Jul 28, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		Unguarded full-file reads via `github-mcp-server-get_file_contents` are the single most common cause of late-session token spikes. Workflow markdown files (`.github/aw/.md`, `.github/workflows/.md`) and skill files can exceed hundreds of KB. Loading even two such files mid-session can 2–2.5× the input context size, degrading model performance and inflating cost.

		Observed evidence: In session `30290667268`, input grew from 44,043 → 108,331 tokens (2.46×) across 8 turns. The spike occurred at turn 7 when two large workflow markdown files were loaded via MCP without a size guard.

		---

		## Technique 11 — Cap Session Context Growth from Large File Reads

Uh oh!

Conversation

Copilot AI commented Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

github-actions Bot commented Jul 28, 2026

🤖 PR Triage

Uh oh!

pelikhan left a comment

Choose a reason for hiding this comment

Uh oh!

pelikhan Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jul 28, 2026

Uh oh!

pelikhan Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Jul 27, 2026 •

edited

Loading