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