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

.github/aw/optimize-agentic-workflow.md

@@ -55,9 +55,10 @@ The workflow was stopped because it consumed more AI Credits than the configured
 Priority checks:
 1. Which tool calls dominated token usage? (`token-usage.jsonl`)
 2. Is the prompt front-loading large payloads that could be fetched on demand?
-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.
+4. Are there repetitive extraction steps that sub-agents could handle cheaply?
+5. Does the frontier model handle tasks that a small model could do?
+6. Can the workflow stay within its current budget after applying and measuring all applicable optimizations?
 
 Increasing `max-ai-credits` is the last resort. Recommend it only after the applicable optimizations below have been tried and measured, and the workflow still cannot complete with acceptable quality within the existing per-run budget.
 

.github/aw/token-optimization.md

@@ -20,6 +20,7 @@ Apply these in order, measuring cost and quality after each change:
 - [ ] **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
 - [ ] **Prompt caching**: Put stable instructions before dynamic content to maximize cache hits
 - [ ] **Context hygiene**: keep the orchestrator context compact; prefer short worker summaries over raw output
 - [ ] **Harness-wide diagnosis**: classify failures across context, tools, generation, orchestration, memory, and output processing before changing configuration
@@ -385,6 +386,29 @@ For self-hosted or BYOK models absent from the built-in table (e.g. Ollama, vLLM
 
 ---
 
+## 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.
+
+For GitHub-hosted files, prefer `mode: gh-proxy` and access via `gh`/`bash` so output can be piped through `jq`, `grep`, or `head` before it enters context — the agent never receives the full file:
+
+```bash
+# gh-proxy: fetch only the lines you need, no full-file injection
+gh api repos/{owner}/{repo}/contents/.github/aw/syntax-agentic.md \
+  --jq '.content' | base64 -d | grep -n "## Sub-agents"
+```
+
+```bash
+# Without gh-proxy: targeted local read
+bash: grep -n "## Sub-agents" .github/aw/syntax-agentic.md
+# or
+view: .github/aw/syntax-agentic.md view_range=[45, 90]
+```
+
+---
+
 ## Additional Resources
 
 | Topic | File |

AGENTS.md

@@ -29,6 +29,7 @@ Everything else should be loaded **lazily** through skills only when needed.
 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.
 
 ## Upstream-managed workflow sources (read-only in this repo)