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.

Constants

DEFAULT_RAW_COMMANDS

Programs whose stdout is a dataset: rows or JSON the caller already narrowed with where / limit / --json / a filter expression. Head+tail elision does not compress those — it deletes the interior rows, which for sorted output is exactly where the answer lives (#1260). No size threshold makes that safe, so these bypass the firewall entirely.

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.

min_tokens

Effective minimum token count before firewalling (config + env override).

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.