context-firewall

Implement a **Context Firewall** workflow to prevent the master context from being flooded by large inputs. ## Purpose Route large inputs (big files, logs, PDFs/images, long MCP/tool outputs) through sub-agents that produce **compressed, auditable results**. Only pass back: - Structured claims - Evidence locators (line/symbol/tool-call) - Coverage statements ## When to use Prefer this workflow when any of the following is true: - The user wants the "full" content of a large file/log/document. - Tool output is long/noisy (search results, crawls, API responses). - The task needs multi-file scanning or cross-file synthesis. - The output must be **verifiable** without re-reading everything. ## Core contract (Evidence Contract) For every meaningful claim: - Attach at least one `evidence` item. - Use a locator that enables low-cost verification. Locator preference order: 1) `line_range` (default) 2) `symbol_range` (functions/classes) 3) `tool_call` (tool-derived facts; include args hash and rerun hint when safe) 4) `byte_range/json_path/stack_signature` (define, but treat as harder to verify in v1) Keep quotes short: - Respect the `quote_max_chars` constraint. - Never paste large raw blobs. ## Recommended workflow ### 1) Generate TaskSpec Create a `TaskSpec.v1` that is explicit about: - Objective - Inputs (files/tool calls) - Questions - must_cover checklist - Constraints (budget + evidence requirements) - Risk level Prefer using the command: - `/cf-spec` to generate a schema-valid template. ### 2) Run Map-Reduce preprocessing Use `/cf-run` to: - Split inputs into shards - Run `cf-fileworker` on each shard in parallel - Merge with `cf-aggregator` into a final `SubResult.v1` Hard requirements for sub-agents: - Output **strict JSON only** (no markdown fences, no extra commentary). - Ensure every claim includes evidence. ### 3) Verify cheaply Use `/cf-verify` to sample-check claims: - Choose sampling rate by `risk_level`. - Re-read only the referenced snippets. - Produce `VerifyReport.v1`. If verification fails: - Request stronger evidence (more/clearer locators). - Narrow `must_cover`. - Run a second-pass `cf-critic` to independently review. ## Coverage & anti-leak rules Always include a `coverage` section that declares: - Which inputs were scanned - Which method was used (grep+window, full scan, time-window scan) - Known gaps (missing archives, not provided inputs) Never: - Dump raw input into the master context. - Hide uncertainty: mark gaps explicitly. ## Operational defaults Default thresholds are configurable in: - `.claude/context-firewall.local.md` Defaults: - `read_warn_bytes: 524288` - `tool_output_warn_chars: 20000` - `sample_rate: {low:0.05, medium:0.15, high:0.30}` ## Related resources - Commands: - `plugins/context-firewall/commands/cf-spec.md` - `plugins/context-firewall/commands/cf-run.md` - `plugins/context-firewall/commands/cf-verify.md` - Agents: - `plugins/context-firewall/agents/cf-fileworker.md` - `plugins/context-firewall/agents/cf-aggregator.md` - `plugins/context-firewall/agents/cf-critic.md` - Schemas: - `plugins/context-firewall/schemas/task-spec.v1.schema.json` - `plugins/context-firewall/schemas/sub-result.v1.schema.json` - `plugins/context-firewall/schemas/verify-report.v1.schema.json` - `plugins/context-firewall/schemas/settings.v1.schema.json` - Settings template: - `plugins/context-firewall/scripts/settings-frontmatter.md`