10 -`verboten` is a best-effort Pi extension that keeps model agents from reading or mutating files whose paths are likely to contain secrets.
10 +`verboten` is a best-effort Pi extension that keeps model agents from exposing or mutating files whose paths are likely to contain secrets.
11 11 It blocks obvious direct filesystem tool calls, filters protected rows from broad content searches, judges ambiguous model-authored shell commands, and gives the model terse preventive instructions.
12 12 It does not claim isolation, sandboxing, or complete mediation.
14 14 False positives matter because blocking ordinary engineering work defeats the extension's purpose.
15 15 Metadata-only operations remain available.
16 -Forbidden operations are content reads and protected-path mutations.
16 +Trusted programs, repository hooks, filters, and credential helpers may consume protected files internally when they neither expose protected data nor mutate protected files.
17 +Forbidden operations are direct content inspection, content exposure, and protected-path mutations.
18 19 ##
Security boundary 24 25 A forbidden operation is any operation likely to:
26 -- read protected-file contents
27 +- directly inspect protected-file contents
28 +- expose protected-file contents, encodings, hashes, or copies in model context or tool output
27 29 - create or overwrite a protected path
28 30 - modify protected contents or metadata
29 31 - delete or rename a protected path
31 33 - execute or source a protected file
32 34 - transmit protected contents
36 +An ordinary command is allowed when its trusted program, repository hook, filter, or credential helper consumes protected files internally without exposing protected data or mutating protected files.
37 +This allowance does not make direct inspection safe merely because output is redirected or discarded.
34 39 The following metadata-only operations are allowed:
273 278 The judge rubric is:
275 -> Estimate the probability that executing this command will read protected-file contents or create, modify, delete, rename, copy, archive, encode, hash, execute, source, or transmit a matched protected path.
280 +> Estimate the probability that executing this command will directly inspect protected-file contents, expose protected-file contents, encodings, hashes, or copies in model-visible output, or create, modify, delete, rename, copy, archive, encode, hash, execute, source, or transmit a matched protected path.
281 +> Trusted programs, repository hooks, filters, and credential helpers may consume protected files internally when they neither expose protected data nor mutate protected files.
276 282 > Metadata-only listing, path discovery, status, stat, and existence checks are allowed.
277 283 > Mere textual mentions and exclusion patterns are allowed.
278 284 > Parse the outer shell and scripts passed to invoked interpreters.
282 288 The judge prompt includes compact positive and negative examples.
283 289 Positive examples include `cat`, content diffing, hashing, copying, archiving, sourcing, permission mutation, and deletion.
284 -Negative examples include `ls`, `find`, `stat`, existence tests, version-control status, exclusion globs, and writing documentation that merely mentions a protected path.
290 +Negative examples include `ls`, `find`, `stat`, existence tests, version-control status, exclusion globs, writing documentation that merely mentions a protected path, and trusted authentication tools that consume a private key without exposing it.
286 292 ##
Judge tool contract 393 399 Append a terse Verboten instruction in `before_agent_start` on every agent run.
394 400 The instruction must state:
396 -> Never read protected-file contents or create, modify, delete, rename, copy, execute, encode, or transmit protected files.
402 +> Never expose protected-file contents, encodings, hashes, or copies to model context or tool output, directly or through a bypass.
403 +> Never create, modify, delete, rename, copy, execute, encode, or transmit protected files.
404 +> Trusted programs, hooks, filters, and credential helpers may consume protected files internally when they neither expose protected data nor mutate protected files.
397 405 > Metadata-only listing, finding, status, stat, and existence checks are allowed.
398 406 > Broad grep searches rooted outside a protected path are allowed; Verboten filters protected rows.
399 407 > Mere textual mentions and exclusion patterns are allowed.
400 -> Never bypass Verboten through shells, symlinks, alternate tools, encoding, or delegation.
408 +> Never bypass Verboten through shells, symlinks, alternate tools, encoding, or delegation to expose or target protected files.
401 409 > Reformulate a false positive only when the new operation avoids protected content and mutation.
403 411 Inject every effective regex in XML:
477 485 | V2 | Aliases | Real temporary symlink on Unix and directory junction or supported equivalent on Windows |
478 486 | V3 | Direct tools | Real `tool_call` paths for `read`, `write`, `edit`, direct `grep`, allowed `ls`, allowed `find` |
479 487 | V4 | Grep filtering | Mixed rows, context rows, omitted counts, all-omitted success, limit-consumed error, byte-limit error, no path/snippet disclosure |
480 -| V5 | Shell candidates | No-match bypass, Bash, PowerShell, metadata allows, content/mutation blocks, exclusion and mention cases |
488 +| V5 | Shell candidates | No-match bypass, Bash, PowerShell, internal secret consumers, metadata allows, content/mutation blocks, exclusion and mention cases |
481 489 | V6 | Embedded scripts | Bash heredocs, PowerShell here-strings, Python/Node scripts, captured text, invoked text, redirects, containers |
482 490 | V7 | Judge lifecycle | One-tool schema, threshold, same-context contract retry, fallback, timeout, auth failure, cancellation, warning dedupe |
483 491 | V8 | Cache | SHA-256 keys, no raw command storage, model/pattern key changes, 256-entry FIFO eviction, failure non-caching |
490 498 - benign text: documentation mentioning `.env`
491 499 - exclusion: grep or ripgrep excluding `.env`
492 500 - reads: `cat`, `grep`, `git diff`, Python `read_text`, Node `readFileSync`
493 -- indirect reads: copy, archive, hash, source, container execution
501 +- indirect exposure: copy, archive, hash, source, and container execution that returns protected data
502 +- internal consumption: trusted hooks, filters, and authentication tools that do not expose or mutate protected files
494 503 - mutations: write redirection, `Set-Content`, `chmod`, and deletion
495 504 - embedded text that looks dangerous but is only assigned, printed, or stored
496 505 - embedded text executed through an interpreter or `Invoke-Expression`