@spences10/pi-redact
Tool-output redaction for Pi that replaces likely secrets before they reach the model context
Package details
Install @spences10/pi-redact from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@spences10/pi-redact- Package
@spences10/pi-redact- Version
0.1.0- Published
- Nov 14, 2026
- Downloads
- 10.1K/mo · 1,194/wk
- Author
- spences10
- License
- MIT
- Types
- extension
- Size
- 118 KB
- Dependencies
- 1 dependency · 2 peers
Pi manifest JSON
{
"image": "https://raw.githubusercontent.com/spences10/my-pi/main/assets/pi-package-preview.png",
"extensions": [
"./dist/index.js"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
@spences10/pi-redact

Mask likely secrets and explicitly registered values before output reaches model context. This is a safety net for accidental exposure, not a perfect secret detector or a shell sandbox.
Installation
pi install npm:@spences10/pi-redact
Local development from this monorepo:
pnpm --filter @spences10/pi-redact run build
pi install ./packages/pi-redact
# or for one run only
pi -e ./packages/pi-redact
my-pi includes this package. Custom SDK harnesses can pass its
default export as an ExtensionFactory.
Detection
The matcher combines:
- distinctive provider formats, including GitHub, GitLab, Slack, npm, Google, AWS, Stripe, OpenAI/Anthropic, SendGrid and JWT tokens
- contextual credential fields in JSON, environment/config assignments, authorization headers and credential-bearing connection URLs
- private-key blocks and header-bearing fragments
- SSH config metadata such as
HostName,User,IdentityFile,ProxyJumpand forwarding directives - explicitly registered exact values, including their JSON-escaped, percent-encoded, base64 and base64url forms in textual output
Markers identify the match, for example [REDACTED:GitHub Token].
Matched credentials are replaced entirely; contextual labels and URL
schemes remain where applicable. Ordinary code expressions and
unlabelled high-entropy output are not treated as credentials merely
for looking random.
Filtering boundaries
tool_resultmasks final text, nested string leaves indetailsandstructuredContent, and tokens split across adjacent text blocks. Objects, non-string values and binary payload bytes are preserved.user_bashwraps Pi's local shell backend.!and!!output is decoded incrementally and terminal controls are removed before matching. Safe complete lines stream while the command runs; incomplete lines, registered-value prefixes and ambiguous PEM/SSH context wait for enough evidence or command completion. Callbacks, saved output and Pi's truncation files receive sanitized bytes. UTF-8, escape sequences and registered multiline values can cross arbitrary chunks. Exit codes, cancellation and shell settings remain Pi's responsibility.message_endmasks finalized message text before the normal agent loop persists it. Executable tool-call arguments and protocol IDs are not changed.contextandcontext_with_systemsanitize request copies, including user/custom text, old shell commands/output, summaries and historical tool arguments. A bounded content-keyed cache works across Pi's cloned messages and is invalidated on exact-value registration.session_before_compactandsession_before_treesanitize cloned preparation messages and entries used by the default summarizers. They do not replace Pi's authentication, model selection or summary implementation, and do not rewrite raw history.
A tool_call source check blocks local read targets beginning with
a private-key header and plausible key payload, even for a first read
starting mid-file or through a path alias. Replacing the key file with
ordinary content does not leave that path permanently blocked. There
is no general filename denylist or credential-store scanning.
After a masked read, a write to that same file is blocked when it
would introduce an observed redaction marker absent on disk, or when
the current file cannot be checked. This prevents copying a masked
view back over credentials. It does not reject unrelated new files or
intentional markers already present on disk. Prefer targeted edits
that leave the masked value alone. An edit using masked text as its
exact old text normally fails to match the real file.
Register exact values from trusted code
Register values you already possess through Pi's in-memory event bus, not a model-visible tool, prompt, command argument or transcript:
import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
export function register_secrets(pi: ExtensionAPI, values: string[]) {
pi.events.emit('pi-redact:register-secrets', { values });
}
Load pi-redact before the extension that emits this event. The
payload must contain an array of strings; malformed registrations are
ignored and empty strings are skipped. Values are deduplicated, held
only in that runtime's memory, and cleared on session shutdown/reload.
Register again for a new runtime. No credential store, environment or
directory is scanned. Register before producing output; already
emitted text cannot be retroactively masked.
Standalone callers can supply values without an extension runtime:
import { redact_text } from '@spences10/pi-redact';
const result = redact_text(output, { known_values: values });
// result.redacted and result.count
The existing looks_like_ssh_config and redact_ssh_config_metadata
helpers remain exported. redact_text also accepts force_ssh_config
and force_private_key; the latter masks plausible key-payload lines,
not every line of arbitrary text.
Commands
/redact-stats
Shows matched replacements scanned in the current runtime. Cached text is not counted again; evicted text can be counted again if rescanned. This is a diagnostic counter, not a count of unique secrets or proof that every secret was removed.
Limitations
Coverage is tested against Pi 1.5.2 using an offline SDK transport, including normal turns, default compaction and default tree summaries. Important boundaries remain:
- Unknown arbitrary passwords, novel formats, unregistered encodings and unrelated chunks can be missed. Unlabelled high-entropy text is not blanket-masked, and false positives remain possible.
- Final tool-result filtering does not protect earlier tool progress
events, tool-owned logs/files or an earlier extension's observers.
Direct-shell filtering applies only when this
user_bashhandler owns execution. Load safety/confirmationuser_bashhandlers beforepi-redact: its operations result stops all later handlers. An earlier SSH or other custom-backend handler can instead intercept first and bypass this local wrapper; a later backend handler will not run. Direct SDKexecuteBash()calls must use the hook's operations to get the same protection. - Streaming is conditional, not byte-by-byte. A long unfinished line,
a long registered prefix, or an unconfirmed SSH/PEM candidate can
delay following output and consume memory until resolved or EOF. SSH
directives before
Hostare retained rather than emitted raw; unmatched candidates are released unchanged apart from other secret matches. Exact and pattern detections use original-text spans so overlapping matches do not expose suffixes or erase neighboring context. Terminal-control payloads, including unfinished escapes at EOF, are not displayed. - Pi still records the original direct-shell command string. Do not put secrets in commands. Request and summary fallbacks mask copies, not the saved command. The original command still executes.
- Previously saved history remains raw. Immediate custom-message
appends (
triggerTurn: false), directrecordBashResult()and direct session-manager writes bypass the pre-persistence hook. Their text is protected only when it later passes through request or summary preparation hooks. Other extensions can still read raw entries. - Compaction and branch summaries bypass normal context/provider hooks. Preparation filtering protects their history inputs, but compaction's separately supplied custom instructions and newly generated summary output have no equivalent pre-persistence transform here. Do not supply secrets in compaction instructions.
- Binary/image bytes, opaque provider signatures, protocol metadata and live tool-call arguments are intentionally preserved. This is not OCR, a filesystem guard for arbitrary shell commands or a universal filter for auxiliary provider requests. The private-key source check inspects only the first 2 KiB of a requested local file; overridden remote reads and concurrent file replacement can bypass that source check.
Use proper secret hygiene as the primary control: avoid printing or
encoding secrets, prefer nopeek to loading .env files into model
context, use scoped revocable tokens, and rotate exposed credentials.
Development
Package scripts build transitive workspace dependencies first, then
run local tools through Vite+ with vp exec.
pnpm --filter @spences10/pi-redact run check
pnpm --filter @spences10/pi-redact run test
pnpm --filter @spences10/pi-redact run build
License
MIT