Module firewall 

Context firewall: replace large tool outputs with a compact digest + retrieval ref.

When ephemeral mode is active ([archive].ephemeral, default on), genuinely large tool results are stored out-of-band via crate::core::archive and only a deterministic digest — a head/tail excerpt, size stats, and ctx_expand drilldown instructions — is returned inline. This keeps the agent’s context window small while preserving full, slice-addressable access to the raw output.

Scope: tool outputs (ctx_shell, ctx_execute, ctx_search, ctx_tree). Explicit file reads keep their own read-mode system and are never firewalled.

Functions

is_firewallable_tool

Tools whose large outputs are eligible for the firewall. Explicit file reads are intentionally excluded — they have their own read-mode (lines:, signatures, …).

is_protected_read

Explicit file-read tools whose result is the file content the agent reads and edits against. They must always return that content inline — never a head/tail digest (firewall) nor a stored-reference stub (reference_results) — regardless of output size or config. This is the single source of truth for “an explicit read always returns content”; both the firewall and the reference-results path honour it so a ctx_read can never degrade to a preview the agent can’t edit.

is_raw_command

Whether command runs a dataset program in any of its pipeline segments. gh counts only with --json/--jq — plain gh output is prose and compresses fine.

should_firewall

Whether a result of output_tokens from tool should be firewalled.

should_inline_shell

Whether an explicitly requested ctx_shell(inline=true) result fits the configured verbatim-delivery cap.

summarize

Build the inline digest that replaces a firewalled output. Deterministic (no LLM): a head/tail excerpt for multi-line output, or a char-bounded excerpt for output with few but very long lines (e.g. a single giant JSON line), followed by drilldown instructions keyed on archive_id.

summarize_unavailable

Keep the context bound even when output cannot safely be archived. The preview makes no lossless-recovery promise and contains no fabricated handle.

verbatim_cap_exceeded

Context-window guard for implicitly verbatim deliveries (#1541): dataset passthrough (#1260) and inline=true stay verbatim at any reasonable size, but above archive.verbatim_max_tokens a single delivery would flood the calling agent’s entire context window. The content is archived losslessly first, so the digest is a compression, never a loss. Explicit raw/bypass and the LEAN_CTX_MINIMAL escape hatch are never capped — callers gate on those before asking. 0 disables the cap.