pi-output-policy

Large-output policy for Pi tool results: minimization, bounded truncation, and full-output preservation. Tuned to keep long autonomous runs under provider request-buffer limits without losing the full tool output (it lands on disk).

Two budgets, one policy

Output policy enforces two related but distinct budgets:

• Compact renderer UI — how big a tool block can be without breaking Pi's TUI. Caps line width, hard line count, and absolute block size.
• Model transcript / session JSONL — how much each tool result adds to the request body that gets resent on every turn. Long runs with many "fine" 50–200 KB results have crashed with HTTP 507: exceeded request buffer limit while retrying upstream even when no individual block was UI-pathological.

Earlier defaults only had teeth on the first budget. The default balanced policy mode now also constrains the second, while leaving the full text on disk via per-session artifacts.

Policy modes

Pick the trade-off via Policy mode (or policyMode in JSON):

Mode	Spill (KB)	Inline tail (KB / lines)	Max block (KB)	Max lines	Max line width	sanitizeDetails
balanced (default)	48	16 / 400	24	400	3 000	on (with allowlist)
compact	16	6 / 200	8	200	2 000	on (with allowlist)
compat	200	100 / 2 000	200	8 000	20 000	off

balanced keeps any single non-read/non-mutation tool result under ~24 KB inline while preserving the full output to disk. compact is for very long autonomous runs that need to stretch the request buffer further. compat is the legacy UI-safety-only profile — no transcript-size protection, but it still applies the old caps (200 KB block / 8 000 lines / 20 000-char lines). For truly untruncated inline output, set enabled: false instead.

Any per-knob value you set in vstack.extensionManager.config["@vanillagreen/pi-output-policy"] overrides the mode default; unset knobs follow the mode.

Highlights

• Preserves oversized tool output to disk and includes the artifact path in results.
• Head truncation for search/listing tools; tail truncation for command/log tools.
• Explicit truncation notices show size, line count, direction, artifact path, per-turn/session bytes saved, and continuation guidance.
• File reads and edit/write results pass through unmodified by default — opt in per category.
• Tool-result details are sanitized by default in balanced/compact (off in compat); state-bearing tools (tasks_write, bg_task, subagent, …) bypass sanitization so sidecar restore semantics stay safe.
• When details are sanitized, the result carries a vstackOutputPolicySanitized marker (and capped arrays/objects include a sentinel string) so consumers can detect the truncation.
• Shell output minimizer compresses noisy git/npm/cargo/test output before truncation while preserving warnings, errors, and summaries.

Install

Via npm:

pi install npm:@vanillagreen/pi-output-policy

Via vstack:

cargo install --git https://github.com/vanillagreencom/vstack.git vstack
vstack add vanillagreencom/vstack --pi-extension pi-output-policy --harness pi -y

Restart Pi after installation.

Settings

Open /extensions:settings; settings appear under the Output Policy tab.

Project settings in .pi/settings.json apply only after Pi marks the workspace trusted; before trust, vstack Pi extensions read user/global settings only.

General

Setting	What it does
Enable output policy	Master toggle.
Policy mode	balanced (default), compact, or compat. See Policy modes.

Truncation

Setting	What it does
Truncate file reads	Apply spill/truncation to read results.
Truncate edits/writes	Apply spill/truncation to edit/write results.
Output spill threshold (KB)	Preserve full output externally above this size. Unset = mode default.
Inline tail size (KB)	Bytes kept inline for tail-truncated command/log output. Unset = mode default.
Inline tail lines	Lines kept inline for tail-truncated command/log output. Unset = mode default.

UI safety

Setting	What it does
Max UI-safe text block (KB)	Hard cap on text blocks even when spill is off. Unset = mode default.
Max UI-safe line count	Hard line cap for rendered text. Unset = mode default.
Max UI-safe line width	Truncate pathological wide lines. Unset = mode default.
Sanitize details payloads	Cap nested tool-result details. Unset = mode default (balanced/compact on, compat off).
Sanitize details allowlist	Comma-separated tool names whose details bypass sanitization. Empty = built-in list (tasks_write, tasks_read, bg_task, bg_status, subagent, subagent_run, stop_subagent, steer_subagent, get_subagent_result).

Storage

Setting	What it does
Preserve full output externally	Write oversized output to an artifact file when possible.

Shell minimizer

Setting	What it does
Reduce verbose shell output	Compress git/npm/cargo/test output before truncation. On by default; disable when you need full successful build logs inline.
Allowlist	Comma-separated command families to minimize.
Denylist	Comma-separated command families to leave alone.
Max capture bytes	Skip minimizer on output larger than this; truncate directly.

Switching back to verbatim behavior

compat mode restores the legacy generous UI-safety caps (200 KB block, 8 000 lines, 20 000-char lines) and turns off sanitizeDetails, but it is not "fully untruncated" — anything above those caps still spills. Pick it when those caps are wide enough for your workflow:

{
  "vstack": {
    "extensionManager": {
      "config": {
        "@vanillagreen/pi-output-policy": {
          "policyMode": "compat"
        }
      }
    }
  }
}

For truly untruncated inline output (no spill, no minimizer, no sanitization), disable the policy entirely:

{
  "vstack": {
    "extensionManager": {
      "config": {
        "@vanillagreen/pi-output-policy": { "enabled": false }
      }
    }
  }
}

Notes

Pi's built-in tools may truncate before reaching this extension. Custom tools that return full large text benefit most from spill preservation.

For truncated file reads, continue reading the original file with offset/limit. For truncated command output, the inline notice points at the artifact file on disk and reports per-turn and per-session bytes saved so users can see the transcript impact at a glance.

Extension-produced custom messages (pi.sendMessage) are not policed by this extension; add per-package caps in extensions that emit large custom messages.