@xprnvd/pi-permission-system 41.0.0 → 42.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +33 -0
- package/README.md +4 -3
- package/dist/public.d.ts +13 -3
- package/docs/configuration.md +7 -0
- package/docs/glossary.md +283 -0
- package/docs/subagent-integration.md +1 -0
- package/package.json +14 -15
- package/schemas/permissions.schema.json +6 -0
- package/src/authority/forwarded-request-server.ts +2 -1
- package/src/authority/forwarding-io.ts +34 -12
- package/src/authority/permission-forwarding.ts +3 -2
- package/src/config/config-schema.ts +42 -19
- package/src/handlers/gates/bash-command.ts +61 -20
- package/src/policy/serving-policy.ts +9 -4
- package/src/types.ts +10 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [42.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v42.0.1...pi-permission-system-v42.0.2) (2026-11-16)
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
### Bug Fixes
|
|
12
|
+
|
|
13
|
+
* **pi-permission-system:** a subagent's forwarded bash command is matched in its spellings on the parent ([a3c7d54](https://github.com/gotgenes/pi-packages/commit/a3c7d54181c2d34a6b2ba042acd07499c0bfb4e4)), closes [#1019](https://github.com/gotgenes/pi-packages/issues/1019)
|
|
14
|
+
|
|
15
|
+
### Documentation
|
|
16
|
+
|
|
17
|
+
* **pi-permission-system:** document that forwarded bash commands are matched in their spellings ([83c52e2](https://github.com/gotgenes/pi-packages/commit/83c52e2e8ec1d419501c1fbcc6a6241e3563668a)), closes [#1019](https://github.com/gotgenes/pi-packages/issues/1019)
|
|
18
|
+
|
|
19
|
+
## [42.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v42.0.0...pi-permission-system-v42.0.1) (2026-11-16)
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
### Documentation
|
|
23
|
+
|
|
24
|
+
* **pi-permission-system:** add a package glossary ([cd313f5](https://github.com/gotgenes/pi-packages/commit/cd313f512aa465d1af00607b01ce7c915d88a81d)), closes [#799](https://github.com/gotgenes/pi-packages/issues/799)
|
|
25
|
+
* **pi-permission-system:** record ADR 0016, the policy channels ([d655ddd](https://github.com/gotgenes/pi-packages/commit/d655ddd80b94018edbc71396776da1024c3535a5)), closes [#799](https://github.com/gotgenes/pi-packages/issues/799)
|
|
26
|
+
* **pi-permission-system:** reconcile earlier records and the glossary with ADR 0016 ([3ce02e3](https://github.com/gotgenes/pi-packages/commit/3ce02e33e45a4724d39836704d3085913b4d35f7)), closes [#799](https://github.com/gotgenes/pi-packages/issues/799)
|
|
27
|
+
* **pi-permission-system:** order and name the ADR 0016 amendment entries ([f637e59](https://github.com/gotgenes/pi-packages/commit/f637e599d4e8596bee65d163a555ed13424816de)), closes [#799](https://github.com/gotgenes/pi-packages/issues/799)
|
|
28
|
+
|
|
29
|
+
## [42.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v41.0.0...pi-permission-system-v42.0.0) (2026-10-28)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
### Bug Fixes
|
|
33
|
+
|
|
34
|
+
* **pi-permission-system:** require zod 4.6.7, which patches CVE-2023-54404 ([ff17542](https://github.com/gotgenes/pi-packages/commit/ff17542daac79a54557e5fe6671581a98cd6e55c)), closes [#1090](https://github.com/gotgenes/pi-packages/issues/1090)
|
|
35
|
+
* **pi-permission-system:** **breaking:** reject a config array longer than 1,000 entries before walking it ([be1443a](https://github.com/gotgenes/pi-packages/commit/be1443af5e94635f8f80068f2ff0b775b381b8ae)), closes [#1090](https://github.com/gotgenes/pi-packages/issues/1090)
|
|
36
|
+
|
|
37
|
+
### Documentation
|
|
38
|
+
|
|
39
|
+
* **pi-permission-system:** archive Phase 15 to history ([8f7d73e](https://github.com/gotgenes/pi-packages/commit/8f7d73ef7b8042b585524649a822183984d6801d)), closes [#945](https://github.com/gotgenes/pi-packages/issues/945)
|
|
40
|
+
|
|
8
41
|
## [41.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v40.3.0...pi-permission-system-v41.0.0) (2026-10-17)
|
|
9
42
|
|
|
10
43
|
|
package/README.md
CHANGED
|
@@ -212,9 +212,9 @@ Hardening the gates against bypass, fail-closed corrections (breaking ones inclu
|
|
|
212
212
|
|
|
213
213
|
The [architecture doc](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/architecture/architecture.md#scope-and-non-goals) carries the full inventory, with the decision record behind each entry.
|
|
214
214
|
|
|
215
|
-
**
|
|
216
|
-
|
|
217
|
-
|
|
215
|
+
**How policy enters is decided.**
|
|
216
|
+
Which channels are admissible, at what precedence, and who may write policy back is settled in [ADR 0016](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0016-policy-channels.md).
|
|
217
|
+
It admits durable approvals into machine-local `config.local.json` files, makes auto-approve a step after any judge rather than a bypass of it, and declines Pi's `settings.json` and ancestor-directory configs as policy sources; each change ships in its own release.
|
|
218
218
|
The companion question — whether a capability model replaces the actor-keyed surface list — is settled: [ADR 0013](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0013-permission-policy-model.md) adds read/write as an axis beside the existing keys, so a policy can permit reading a path without also permitting writes to it.
|
|
219
219
|
|
|
220
220
|
**Where adjacent requests belong.**
|
|
@@ -227,6 +227,7 @@ Approve-and-steer, edit diffs, and risk explanations → a downstream package ov
|
|
|
227
227
|
|
|
228
228
|
| Document | Contents |
|
|
229
229
|
| ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
230
|
+
| [docs/glossary.md](docs/glossary.md) | The package's terms (surface, gate, chain, link, envelope, node, …) and what each means here |
|
|
230
231
|
| [docs/configuration.md](docs/configuration.md) | Full policy reference, runtime knobs, per-agent overrides, recipes |
|
|
231
232
|
| [docs/session-approvals.md](docs/session-approvals.md) | Session-scoped rules, pattern suggestions, bash arity table |
|
|
232
233
|
| [docs/cross-extension-api.md](docs/cross-extension-api.md) | Cross-extension service accessor, event bus integration, prompt and decision broadcasts |
|
package/dist/public.d.ts
CHANGED
|
@@ -97,10 +97,19 @@ interface PermissionCheckResult {
|
|
|
97
97
|
}
|
|
98
98
|
/**
|
|
99
99
|
* One unit of a bash chain the gate left asking, as the serving node of a
|
|
100
|
-
* forwarded ask needs it: the unit as typed,
|
|
100
|
+
* forwarded ask needs it: the unit as typed, the other spellings it was matched
|
|
101
|
+
* in, and the floor that raised it.
|
|
101
102
|
*/
|
|
102
103
|
interface AskingBashUnit {
|
|
103
104
|
command: string;
|
|
105
|
+
/**
|
|
106
|
+
* The other spellings of `command` the child's shell runs identically, as
|
|
107
|
+
* the child's program analysis produced them: home-expanded, and with path
|
|
108
|
+
* arguments made absolute against the child's working directory. Child-fixed:
|
|
109
|
+
* the serving node matches them as given and never recomputes them. Absent
|
|
110
|
+
* when there are none.
|
|
111
|
+
*/
|
|
112
|
+
spellings?: readonly string[];
|
|
104
113
|
floor?: string;
|
|
105
114
|
}
|
|
106
115
|
|
|
@@ -475,8 +484,9 @@ interface ForwardedAccessFacts {
|
|
|
475
484
|
*/
|
|
476
485
|
floor?: string;
|
|
477
486
|
/**
|
|
478
|
-
* Every unit of a bash chain the child left asking, each with its own floor
|
|
479
|
-
*
|
|
487
|
+
* Every unit of a bash chain the child left asking, each with its own floor
|
|
488
|
+
* and the spellings the child matched it in. `matchValues` names only the
|
|
489
|
+
* chain's winner, and the serving node's answer
|
|
480
490
|
* approves the whole tool call, so it judges each of these instead. Absent
|
|
481
491
|
* for a non-bash ask and for a bash ask raised without a chain (the empty
|
|
482
492
|
* parse), where `matchValues` is the whole command.
|
package/docs/configuration.md
CHANGED
|
@@ -123,6 +123,9 @@ This clamp is deny-preserving and, like `yoloMode`, applied at composition; when
|
|
|
123
123
|
| `piInfrastructureReadPaths` | `[]` | Extra directories to auto-allow for reads, bypassing the `external_directory` gate. Supports `~`/`$HOME`/`${HOME}` expansion and wildcard patterns (`*`, `?`). |
|
|
124
124
|
| `authorizerChain` | `[]` | Ordered names of registered live-authority chain links to consult before the terminal authorizer (see [Authorizer chain](#authorizer-chain--case-by-case-decision-links)). |
|
|
125
125
|
|
|
126
|
+
Every array field (`promptNotifications`, `piInfrastructureReadPaths`, `authorizerChain`, and a `commandEffects` entry's `effects` and `unlessOption` lists) accepts at most 1,000 entries.
|
|
127
|
+
A longer list makes the file invalid, so it is rejected like any other invalid value (see [Merge Precedence](#merge-precedence) for how an invalid scope fails closed).
|
|
128
|
+
|
|
126
129
|
Both logs write to `~/.pi/agent/extensions/pi-permission-system/logs/`.
|
|
127
130
|
No debug output is printed to the terminal.
|
|
128
131
|
|
|
@@ -616,6 +619,8 @@ A subagent's floored ask keeps its floor when it is forwarded to the parent sess
|
|
|
616
619
|
The parent's `allow` rule does not answer it, so `sudo rm x` from a subagent prompts in the parent even under a parent `bash: *` allow.
|
|
617
620
|
The parent's `deny` still denies, and a grant for the whole parent session or the parent's `yoloMode` still approves.
|
|
618
621
|
A subagent's chained command (`ls && rm -rf /tmp/x`) is judged by the parent command by command: every command the subagent's own policy left asking is forwarded with its floor, and the parent's `deny` or `ask` on any one of them decides, not only on the first.
|
|
622
|
+
The parent's rules and session grants match each forwarded command in the same spellings the subagent's own rules do: the [home-expanded form](#home-directory-expansion-in-patterns) and the form with every path argument made absolute against the subagent's working directory.
|
|
623
|
+
So a parent `"~/bin/tool *": "deny"` denies a subagent's `$HOME/bin/tool --now`, and a parent `"rm /tmp/builds/*": "deny"` denies `rm builds/x` from a subagent working in `/tmp`.
|
|
619
624
|
|
|
620
625
|
Because of this, set an explicit `bash` policy rather than relying on a permissive top-level `*`.
|
|
621
626
|
A config whose top-level `*` is `"allow"` with no `bash` `*` policy lets every bash command silently inherit `allow`; the extension emits a startup warning in that case.
|
|
@@ -1145,6 +1150,8 @@ Each key is a command's **bare basename**, and each entry has up to three fields
|
|
|
1145
1150
|
| `unlessOption` | Options that withdraw the declaration when they appear anywhere in the command, so its paths consult both surfaces again. |
|
|
1146
1151
|
| `subcommands` | Entries for the word that follows, keyed by that exact word. A value is a nested entry or, as a shorthand, just its `effects` (`"log": "read"`). |
|
|
1147
1152
|
|
|
1153
|
+
The `effects` and `unlessOption` arrays each accept at most 1,000 entries; a longer list rejects the whole config file.
|
|
1154
|
+
|
|
1148
1155
|
The rules are fail-closed wherever a rule had to choose:
|
|
1149
1156
|
|
|
1150
1157
|
- **Undeclared is unknown.**
|
package/docs/glossary.md
ADDED
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
# Glossary
|
|
2
|
+
|
|
3
|
+
The terms this package uses, each with the meaning it has here.
|
|
4
|
+
An entry defines a term; the record it links to decides how the thing behaves.
|
|
5
|
+
Terms are grouped by topic, and each heading is a stable anchor (`glossary.md#surface`) that other docs and agents may link to.
|
|
6
|
+
|
|
7
|
+
## Decisions
|
|
8
|
+
|
|
9
|
+
### Action
|
|
10
|
+
|
|
11
|
+
The outcome a rule assigns: `allow`, `ask`, or `deny`.
|
|
12
|
+
`allow` lets the call proceed, `deny` blocks it, and `ask` escalates it to live [authority](#authority).
|
|
13
|
+
A `deny` may carry a reason, which the agent is shown.
|
|
14
|
+
|
|
15
|
+
### Decision
|
|
16
|
+
|
|
17
|
+
The final `allow` or `deny` for one request, after any escalation.
|
|
18
|
+
The [review log](#review-log) records it with `decidedBy`, naming what decided: a rule, a session approval, [yolo](#yolo), the user, an [authorizer link](#link), or a forward.
|
|
19
|
+
|
|
20
|
+
### Verdict
|
|
21
|
+
|
|
22
|
+
What an [authorizer link](#link) returns for an `ask`: `allow`, `deny`, or [`defer`](#defer).
|
|
23
|
+
A [terminal](#terminal) returns only `allow` or `deny`.
|
|
24
|
+
See [ADR 0007](decisions/0007-model-judge-authorizer-chain-adr.md) decisions 1 and 2.
|
|
25
|
+
|
|
26
|
+
### Judgment
|
|
27
|
+
|
|
28
|
+
A decision made by live authority (the human, or a model behind an [authorizer link](#link)) on an `ask`, as opposed to the deterministic resolution of recorded authority.
|
|
29
|
+
Judgment may be non-deterministic; the package's determinism guarantee covers recorded authority only.
|
|
30
|
+
The layering rule is "surface deterministically, discriminate with judgment" ([ADR 0009](decisions/0009-bash-path-projection-completeness-contract.md)).
|
|
31
|
+
|
|
32
|
+
## Policy
|
|
33
|
+
|
|
34
|
+
### Rule
|
|
35
|
+
|
|
36
|
+
One `(surface, pattern) → action` entry, carrying its [origin](#origin).
|
|
37
|
+
Every policy source, config file or session approval, is normalized to rules before a check consults them.
|
|
38
|
+
See [Core data model](architecture/architecture.md#core-data-model).
|
|
39
|
+
|
|
40
|
+
### Pattern
|
|
41
|
+
|
|
42
|
+
The match side of a rule: a command glob, tool name, file path, MCP target, skill name, or `*`.
|
|
43
|
+
`*` matches any run of characters, including `/`, and `?` matches one character; `**` is not a separate globstar and behaves exactly like `*`.
|
|
44
|
+
|
|
45
|
+
### Surface
|
|
46
|
+
|
|
47
|
+
The key a rule is filed under, naming the kind of access it governs.
|
|
48
|
+
Surfaces are tool names (`read`, `write`, `edit`, `bash`, …), `mcp`, `skill`, and the directional path surfaces (`path_read`, `path_write`, `external_directory_read`, `external_directory_write`).
|
|
49
|
+
One tool call can be checked on several surfaces; see [gate](#gate).
|
|
50
|
+
The `*` key, `permission["*"]`, is the universal fallback for any surface without a matching rule.
|
|
51
|
+
|
|
52
|
+
### Surface family
|
|
53
|
+
|
|
54
|
+
`path` and `external_directory` each name a family of two directional surfaces, `_read` and `_write`.
|
|
55
|
+
The two directions are independent: a `path_write` allow grants no read, and a `path_read` deny blocks no write.
|
|
56
|
+
See [ADR 0013](decisions/0013-permission-policy-model.md) decisions 3 and 4.
|
|
57
|
+
|
|
58
|
+
### Sugar
|
|
59
|
+
|
|
60
|
+
A bare `path` or `external_directory` key in config.
|
|
61
|
+
It is expanded at load time, separately for each [scope](#scope) and before scopes are merged, into both directional surfaces of its family; explicit directional entries are placed after the expanded ones.
|
|
62
|
+
|
|
63
|
+
### Path
|
|
64
|
+
|
|
65
|
+
The `path` family governs a file path wherever it is, matched against both its typed spelling and its symlink-resolved one.
|
|
66
|
+
Its idiomatic use is carving denials such as `~/.ssh/*`; granting access outside the working directory is the job of [external directory](#external-directory).
|
|
67
|
+
|
|
68
|
+
### External directory
|
|
69
|
+
|
|
70
|
+
The `external_directory` family fires on a path's relation to the session's working directory (being outside it), not on how the path is spelled.
|
|
71
|
+
It answers "is this in scope at all", while `path` answers "is this particular access permitted", and a call must pass both.
|
|
72
|
+
Granting an outside root takes one line: `external_directory_read: { "~/dev/*": "allow" }`.
|
|
73
|
+
See [ADR 0013](decisions/0013-permission-policy-model.md) decision 5.
|
|
74
|
+
|
|
75
|
+
### Effect
|
|
76
|
+
|
|
77
|
+
What an access does to a file: `read` or `write`.
|
|
78
|
+
A bash path operand's effect is proven by syntax (a redirect), by the built-in set of pure-reader commands, or by the user's `commandEffects` declarations; an operand whose effect is unproven consults both directions.
|
|
79
|
+
`commandEffects` classifies commands; it is not a rule and grants nothing by itself.
|
|
80
|
+
See [ADR 0013](decisions/0013-permission-policy-model.md) decisions 2 and 7.
|
|
81
|
+
|
|
82
|
+
### Ruleset
|
|
83
|
+
|
|
84
|
+
The composed, ordered list of rules a check consults, built in layers: the synthesized default, then the MCP baseline, then config rules, then session rules.
|
|
85
|
+
Evaluation is [last-match-wins](#last-match-wins), so a later layer overrides an earlier one.
|
|
86
|
+
See [Composed ruleset](architecture/architecture.md#composed-ruleset).
|
|
87
|
+
|
|
88
|
+
### Origin
|
|
89
|
+
|
|
90
|
+
Which source contributed a rule (`RuleOrigin`): `global`, `project`, `agent`, `project-agent`, `builtin`, `baseline`, `session`, `yolo`, or `fail-closed`.
|
|
91
|
+
It is reported on the `permissions:decision` event and in the review log, so a surprising outcome traces to its source.
|
|
92
|
+
|
|
93
|
+
### Scope
|
|
94
|
+
|
|
95
|
+
A config source with a fixed precedence position: `global` (the global config file), `project` (the project config file), `agent` (global agent frontmatter), and `project-agent` (project agent frontmatter), in that order.
|
|
96
|
+
A later scope overrides an earlier one on an identical pattern, and a pattern only the later scope defines is placed after the earlier scope's.
|
|
97
|
+
A pattern both define keeps the earlier scope's position, so a later catch-all does not override an earlier scope's specific patterns ([ADR 0016](decisions/0016-policy-channels.md) measurement 4, changing in [#1108]).
|
|
98
|
+
The two project scopes load only for a trusted project; see [project trust](#project-trust).
|
|
99
|
+
|
|
100
|
+
### Channel
|
|
101
|
+
|
|
102
|
+
Any path by which something that changes a check's outcome reaches the package: a scope's file, agent frontmatter, the session layer, or a runtime knob such as `yoloMode`.
|
|
103
|
+
Which channels are admissible, and at what precedence, is decided in [ADR 0016](decisions/0016-policy-channels.md).
|
|
104
|
+
The authority model's "three channels" for reaching live authority, and its statement that yolo "is not a channel", use the word in that narrower sense.
|
|
105
|
+
|
|
106
|
+
### Relax and tighten
|
|
107
|
+
|
|
108
|
+
A change relaxes policy when it can move an outcome toward `allow` (`deny` or `ask` to `allow`), and tightens it when it moves the other way.
|
|
109
|
+
|
|
110
|
+
### Last-match-wins
|
|
111
|
+
|
|
112
|
+
Within one surface, the last matching rule in the [ruleset](#ruleset) decides, so a later layer overrides an earlier one; for scopes, see [scope](#scope).
|
|
113
|
+
|
|
114
|
+
### Most-restrictive-wins
|
|
115
|
+
|
|
116
|
+
Across the surfaces one tool call is checked on, the most restrictive outcome wins (`deny` over `ask` over `allow`), so an allow on one surface cannot loosen another.
|
|
117
|
+
|
|
118
|
+
### Session rule
|
|
119
|
+
|
|
120
|
+
A rule created when the human answers "for this session" at a prompt, also called a session approval.
|
|
121
|
+
It is held in memory, appended after every config rule (the session layer), and cleared when the session ends.
|
|
122
|
+
For bash, the suggested pattern comes from the arity table (`git checkout main` suggests `git checkout *`).
|
|
123
|
+
See [docs/session-approvals.md](session-approvals.md).
|
|
124
|
+
|
|
125
|
+
### Yolo
|
|
126
|
+
|
|
127
|
+
The `yoloMode` runtime knob.
|
|
128
|
+
When on, every `ask` becomes `allow` and every `deny` is preserved; the decision's origin is `yolo`.
|
|
129
|
+
A rule's `ask` is rewritten when the ruleset is composed, and an `ask` a gate synthesizes after resolution (the bash wrapper floor, an unparseable command) is granted at the gate.
|
|
130
|
+
Under yolo an `ask` never reaches live authority, so no [authorizer link](#link) or human is consulted.
|
|
131
|
+
See [yolo is recorded authority](architecture/architecture.md#yolo-is-recorded-authority).
|
|
132
|
+
|
|
133
|
+
### Fail-closed floor
|
|
134
|
+
|
|
135
|
+
When a non-global scope is present but invalid, every composed `allow` becomes `ask` (origin `fail-closed`), so a permissive lower scope cannot survive behind a broken higher one.
|
|
136
|
+
It is applied before yolo.
|
|
137
|
+
See [Fail-closed on an invalid non-global scope](architecture/architecture.md#fail-closed-on-an-invalid-non-global-scope).
|
|
138
|
+
|
|
139
|
+
### Default and baseline
|
|
140
|
+
|
|
141
|
+
The universal default is a synthesized catch-all rule from `permission["*"]` (`ask` when unset), placed first in the ruleset.
|
|
142
|
+
The baseline is a small set of synthesized MCP metadata allows, placed after the default and before config, so a config rule overrides it.
|
|
143
|
+
|
|
144
|
+
### Runtime knob
|
|
145
|
+
|
|
146
|
+
A config field that changes behavior without being a rule, such as `yoloMode`, `debugLog`, `permissionReviewLog`, or `promptTimeoutMs`.
|
|
147
|
+
|
|
148
|
+
### Propagation
|
|
149
|
+
|
|
150
|
+
When a running session sees a changed policy source.
|
|
151
|
+
Rules in config files and agent frontmatter are re-read at the next tool call; runtime knobs are re-read at the next [prompt](#prompt).
|
|
152
|
+
|
|
153
|
+
### Project trust
|
|
154
|
+
|
|
155
|
+
Pi's per-directory decision to trust a project's local resources, which this package observes through `ctx.isProjectTrusted()` and never makes itself.
|
|
156
|
+
See [ADR 0001](decisions/0001-project-trust-adoption.md).
|
|
157
|
+
|
|
158
|
+
## Checking
|
|
159
|
+
|
|
160
|
+
### Tool call
|
|
161
|
+
|
|
162
|
+
One invocation of a tool by the model.
|
|
163
|
+
Pi emits a `tool_call` event before the tool runs, where this package's [gates](#gate) check it and may block it.
|
|
164
|
+
|
|
165
|
+
### Gate
|
|
166
|
+
|
|
167
|
+
One check a tool call must pass: it names a surface and a value, resolves them against the ruleset, and acts on the [action](#action).
|
|
168
|
+
A tool call passes through a fixed sequence of six gates (skill read, path, external directory, bash external directory, bash path, tool), and the first block stops the call (an unconditionally denying gate is checked ahead of the rest); for a shell tool, the tool gate checks each command unit.
|
|
169
|
+
A `/skill:` invocation typed by the user has its own input gate.
|
|
170
|
+
|
|
171
|
+
### Access intent
|
|
172
|
+
|
|
173
|
+
The description of what a call accesses (a tool's input, a bash command unit, a set of paths), built without consulting policy and handed by a gate to the resolver.
|
|
174
|
+
|
|
175
|
+
### Exposure
|
|
176
|
+
|
|
177
|
+
The check run at `before_agent_start` that hides a tool from the model when every value on its surface resolves to `deny`.
|
|
178
|
+
It is the first of two phases; gating at each tool call is the second.
|
|
179
|
+
See [Two-phase checking](architecture/architecture.md#two-phase-checking).
|
|
180
|
+
|
|
181
|
+
### Review log
|
|
182
|
+
|
|
183
|
+
The permission review log, a JSONL file recording each gate decision with its request facts and `decidedBy`.
|
|
184
|
+
Values bound to sensitive names are masked.
|
|
185
|
+
|
|
186
|
+
## Authority
|
|
187
|
+
|
|
188
|
+
### Authority
|
|
189
|
+
|
|
190
|
+
The right to decide whether an action may happen.
|
|
191
|
+
Recorded authority is the [ruleset](#ruleset); live authority is reached only on `ask`, when recorded authority is silent; absent authority (nothing recorded, nothing reachable) means the action is denied.
|
|
192
|
+
See [The authority model](architecture/architecture.md#the-authority-model).
|
|
193
|
+
|
|
194
|
+
### Authorizer
|
|
195
|
+
|
|
196
|
+
The entity that holds live authority for an `ask`.
|
|
197
|
+
The [terminal](#terminal) authorizers are `LocalUserAuthorizer` (prompt the human here), `ParentAuthorizer` (forward to the parent), and `DenyingAuthorizer` (no authority reachable); [links](#link) are the non-terminal ones.
|
|
198
|
+
|
|
199
|
+
### Chain
|
|
200
|
+
|
|
201
|
+
The ordered sequence an `ask` passes through: the [links](#link) the operator names in `authorizerChain`, in config order, then the [terminal](#terminal).
|
|
202
|
+
Each link decides or defers.
|
|
203
|
+
There is one chain per [node](#node); a relaying node runs none and forwards instead.
|
|
204
|
+
See [ADR 0007](decisions/0007-model-judge-authorizer-chain-adr.md).
|
|
205
|
+
|
|
206
|
+
### Link
|
|
207
|
+
|
|
208
|
+
A named, non-terminal authorizer that another extension registers with `registerAuthorizer`.
|
|
209
|
+
It decides nothing until the operator names it in `authorizerChain`, and it returns a [verdict](#verdict).
|
|
210
|
+
|
|
211
|
+
### Terminal
|
|
212
|
+
|
|
213
|
+
The last authorizer in a chain, which must decide and cannot defer.
|
|
214
|
+
|
|
215
|
+
### Defer
|
|
216
|
+
|
|
217
|
+
A link's verdict meaning "not mine to decide": the `ask` passes to the next link, and in the end to the terminal.
|
|
218
|
+
|
|
219
|
+
### Envelope
|
|
220
|
+
|
|
221
|
+
The bounded-delegation checkpoint this package applies to every link verdict, so a link can never exceed the operator's policy.
|
|
222
|
+
A link's `allow` on the `path` or `external_directory` families becomes [`defer`](#defer), except on an `external_directory` ask carrying the nothing-on-disk [license](#license).
|
|
223
|
+
A `deny` rule never reaches the chain at all.
|
|
224
|
+
|
|
225
|
+
### License
|
|
226
|
+
|
|
227
|
+
A fact a gate computes that lets a link's otherwise-capped `allow` through the [envelope](#envelope).
|
|
228
|
+
The one license today is nothing-on-disk: every flagged path of a bash `external_directory` ask names nothing that exists.
|
|
229
|
+
|
|
230
|
+
## Sessions and nodes
|
|
231
|
+
|
|
232
|
+
### Session
|
|
233
|
+
|
|
234
|
+
One Pi conversation, from `session_start` to `session_shutdown`; `/new`, `/resume`, and `/fork` each start a new one.
|
|
235
|
+
Session rules live exactly this long.
|
|
236
|
+
|
|
237
|
+
### Prompt
|
|
238
|
+
|
|
239
|
+
One user submission and the agent loop it starts, from `agent_start` to `agent_end`.
|
|
240
|
+
`before_agent_start` fires once per prompt; this package refreshes its runtime config and runs [exposure](#exposure) there.
|
|
241
|
+
|
|
242
|
+
### Turn
|
|
243
|
+
|
|
244
|
+
One model response and the tool calls it requests, from `turn_start` to `turn_end`.
|
|
245
|
+
A single [prompt](#prompt) can run many turns.
|
|
246
|
+
|
|
247
|
+
### Node
|
|
248
|
+
|
|
249
|
+
One Pi session runtime: one `ExtensionContext`, one event bus, one set of gates, its own registries.
|
|
250
|
+
A node is not a process: one process can host several, such as a parent and its in-process subagent children.
|
|
251
|
+
See [ADR 0012](decisions/0012-cross-node-extension-contract.md).
|
|
252
|
+
|
|
253
|
+
### Requesting, relaying, serving, and adjudicating nodes
|
|
254
|
+
|
|
255
|
+
The roles in forwarding: the requesting node raises the `ask`; a relaying node forwards it instead of deciding; the serving node drains forwarded asks; the adjudicating node is the one whose chain and terminal decide.
|
|
256
|
+
|
|
257
|
+
### Forwarding
|
|
258
|
+
|
|
259
|
+
How a subagent that cannot decide sends its `ask` up the session tree: its `ParentAuthorizer` hands the request to the serving parent, whose chain and terminal decide.
|
|
260
|
+
See [docs/subagent-integration.md](subagent-integration.md).
|
|
261
|
+
|
|
262
|
+
## Packaging
|
|
263
|
+
|
|
264
|
+
### This package
|
|
265
|
+
|
|
266
|
+
`@gotgenes/pi-permission-system`, an npm package containing one Pi [extension](#extension).
|
|
267
|
+
|
|
268
|
+
### Extension
|
|
269
|
+
|
|
270
|
+
Code Pi loads into a session; it receives `ExtensionAPI` and registers event handlers, tools, and commands.
|
|
271
|
+
An extension is fully trusted code in Pi's process, so the boundaries this package draws are about operator attention, not about what other extensions are able to do.
|
|
272
|
+
|
|
273
|
+
### Pi package
|
|
274
|
+
|
|
275
|
+
Pi's installable unit (`pi install npm:…`, `git:…`, or a local path), bundling extensions, skills, prompt templates, and themes.
|
|
276
|
+
|
|
277
|
+
### Downstream extension
|
|
278
|
+
|
|
279
|
+
An extension that integrates with this package through its published service (`getPermissionsService(sessionId)`, with `registerAuthorizer`, `registerToolAccessExtractor`, and the query methods) or its `permissions:*` events, such as `@gotgenes/pi-permission-model-judge`.
|
|
280
|
+
The dependency points toward this package, never away from it.
|
|
281
|
+
See [docs/cross-extension-api.md](cross-extension-api.md).
|
|
282
|
+
|
|
283
|
+
[#1108]: https://github.com/gotgenes/pi-packages/issues/1108
|
|
@@ -149,6 +149,7 @@ When a delegated or routed subagent cannot decide an `ask` where it runs — bec
|
|
|
149
149
|
The main interactive session polls for forwarded requests, shows the confirmation prompt, writes the response, and the subagent resumes once that decision is available.
|
|
150
150
|
A parent `allow`/`deny` rule governs a child's escalation directly (the serving node resolves it as recorded authority before prompting), and a "whole session" grant recorded on the parent auto-approves later forwards of the same pattern.
|
|
151
151
|
For a chained bash command, the parent judges every command the child left asking, not only the first, and the most restrictive answer decides.
|
|
152
|
+
The parent matches each of those commands in the spellings the child computed for it (the home-expanded form and absolute path arguments), since only the child knows its working directory and whether the command rebinds `HOME`.
|
|
152
153
|
The exception is a bash ask the child raised through a [synthetic floor](configuration.md#fail-closed-behavior) (a wrapper such as `sudo` or `bash -c`, or a command the parser could not resolve): the child forwards the floor with the ask, and a parent `allow` rule escalates it to the parent's prompt instead of approving it.
|
|
153
154
|
|
|
154
155
|
This keeps `ask` policies usable even when the original permission check happens inside a non-UI execution context.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xprnvd/pi-permission-system",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "42.0.2",
|
|
4
4
|
"description": "Permission enforcement extension for the Pi coding agent.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": {
|
|
@@ -29,7 +29,7 @@
|
|
|
29
29
|
"scripts": {
|
|
30
30
|
"check": "tsc --noEmit",
|
|
31
31
|
"build:types": "rollup -c rollup.dts.config.mjs",
|
|
32
|
-
"prepack": "
|
|
32
|
+
"prepack": "npm run build:types",
|
|
33
33
|
"gen:schema": "node --experimental-strip-types scripts/generate-permissions-schema.ts && biome format --write schemas/permissions.schema.json",
|
|
34
34
|
"test": "vitest run",
|
|
35
35
|
"test:watch": "vitest",
|
|
@@ -41,7 +41,7 @@
|
|
|
41
41
|
"measure:unresolved-redirects": "node scripts/measure-unresolved-redirects.mjs",
|
|
42
42
|
"measure:wrapper-transparency": "node scripts/measure-wrapper-transparency.mjs",
|
|
43
43
|
"lint:md": "rumdl check *.md docs/**/*.md",
|
|
44
|
-
"lint": "biome check . &&
|
|
44
|
+
"lint": "biome check . && npm run lint:md"
|
|
45
45
|
},
|
|
46
46
|
"keywords": [
|
|
47
47
|
"pi-package",
|
|
@@ -61,12 +61,11 @@
|
|
|
61
61
|
"license": "MIT",
|
|
62
62
|
"repository": {
|
|
63
63
|
"type": "git",
|
|
64
|
-
"url": "git+https://github.com/xprnvd/pi-
|
|
65
|
-
"directory": "packages/pi-permission-system"
|
|
64
|
+
"url": "git+https://github.com/xprnvd/pi-permission-system.git"
|
|
66
65
|
},
|
|
67
|
-
"homepage": "https://github.com/
|
|
66
|
+
"homepage": "https://github.com/xprnvd/pi-permission-system",
|
|
68
67
|
"bugs": {
|
|
69
|
-
"url": "https://github.com/
|
|
68
|
+
"url": "https://github.com/xprnvd/pi-permission-system/issues"
|
|
70
69
|
},
|
|
71
70
|
"engines": {
|
|
72
71
|
"node": ">=22"
|
|
@@ -84,19 +83,19 @@
|
|
|
84
83
|
"@earendil-works/pi-tui": ">=1.0.0"
|
|
85
84
|
},
|
|
86
85
|
"devDependencies": {
|
|
87
|
-
"@biomejs/biome": "
|
|
86
|
+
"@biomejs/biome": "^2.5.11",
|
|
88
87
|
"@earendil-works/pi-coding-agent": "1.0.0",
|
|
89
88
|
"@earendil-works/pi-tui": "1.0.0",
|
|
90
|
-
"@types/node": "
|
|
91
|
-
"rollup": "
|
|
92
|
-
"rollup-plugin-dts": "
|
|
93
|
-
"rumdl": "
|
|
94
|
-
"typescript": "
|
|
95
|
-
"vitest": "
|
|
89
|
+
"@types/node": "^22.15.3",
|
|
90
|
+
"rollup": "^4.63.1",
|
|
91
|
+
"rollup-plugin-dts": "^6.5.1",
|
|
92
|
+
"rumdl": "0.2.24",
|
|
93
|
+
"typescript": "^6.0.3",
|
|
94
|
+
"vitest": "^4.1.11"
|
|
96
95
|
},
|
|
97
96
|
"dependencies": {
|
|
98
97
|
"tree-sitter-bash": "^0.25.1",
|
|
99
98
|
"web-tree-sitter": "^0.26.9",
|
|
100
|
-
"zod": "^4.
|
|
99
|
+
"zod": "^4.6.7"
|
|
101
100
|
}
|
|
102
101
|
}
|
|
@@ -72,6 +72,7 @@
|
|
|
72
72
|
"description": "Terminal notifications to emit when the inline permission dialog opens: bell (BEL), osc9 (OSC 9 notification), osc777 (OSC 777 notification). Omit or leave empty for none. TUI sessions only.",
|
|
73
73
|
"markdownDescription": "Terminal notifications to emit when the inline permission dialog opens, so a terminal or multiplexer can flag a session waiting on a decision.\n\n- `\"bell\"` writes a BEL — what tmux `monitor-bell` and most terminals react to.\n- `\"osc9\"` writes an OSC 9 desktop notification.\n- `\"osc777\"` writes an OSC 777 desktop notification.\n\nOmit or leave empty for none (the default). Applies to interactive **TUI** sessions only. The notification names the session and the requested tool and agent, never the command, path, or other value being decided.",
|
|
74
74
|
"default": [],
|
|
75
|
+
"maxItems": 1000,
|
|
75
76
|
"type": "array",
|
|
76
77
|
"items": {
|
|
77
78
|
"type": "string",
|
|
@@ -137,6 +138,7 @@
|
|
|
137
138
|
"description": "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the external_directory gate. Supports ~ expansion and wildcard patterns (* and ?).",
|
|
138
139
|
"markdownDescription": "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the `external_directory` gate.\n\nThe extension auto-discovers the global node_modules root (walks up from the extension's install path; falls back to `npm root -g` from a dev checkout), Pi's own install directory (via the coding-agent `getPackageDir()` API), Pi's harness entries under `agentDir` (`agents/`, `extensions/`, `git/`, `npm/`, `prompts/`, `skills/`, `themes/`, `settings.json`, `SYSTEM.md`, `APPEND_SYSTEM.md`, `AGENTS.md`), and project-local `.pi/npm/` and `.pi/git/`. The package's own logs directory is never auto-allowed, even when an entry here covers it. Add entries here for edge cases where auto-discovery is insufficient (e.g. custom `npmCommand` pointing to pnpm).\n\nSupports `~`/`$HOME` expansion. Entries may be plain directory prefixes or wildcard patterns using `*` (matches any characters, including `/`) and `?` (matches exactly one character). `**` and `*` are equivalent — both cross directory boundaries.\n\nOn Windows, matching is case-insensitive and tolerant of either path separator.",
|
|
139
140
|
"default": [],
|
|
141
|
+
"maxItems": 1000,
|
|
140
142
|
"type": "array",
|
|
141
143
|
"items": {
|
|
142
144
|
"type": "string",
|
|
@@ -147,6 +149,7 @@
|
|
|
147
149
|
"description": "Ordered names of registered live-authority chain links to consult before the terminal authorizer. Config order (not registration order) fixes the chain order; an unregistered name is skipped fail-safe (more prompting, never less); a link decides nothing until it is named here.",
|
|
148
150
|
"markdownDescription": "Ordered names of registered **live-authority chain links** (e.g. a model judge) to consult before the terminal authorizer (the human, or the subagent-forwarding / headless-deny fallback).\n\nA link reviews an `ask` and returns `allow` / `deny` (with an optional teaching reason) / `defer` to the next link. Three invariants govern the chain:\n\n- **Config order wins.** The order here — not the order extensions register in — fixes the security-relevant chain order.\n- **Fail-safe skip.** A name with no registered link is skipped with a warning; the `ask` still reaches the terminal (more prompting, never less).\n- **Opt-in activation.** Installing a judge extension grants it no authority; a link decides nothing until you name it here.\n\nThe chain owner caps every verdict with a bounded-delegation checkpoint: a link's `allow` on an excluded surface (`external_directory` or `path`) is downgraded to `defer`, so a link cannot exceed your policy. The one exception is per ask: a link's `allow` on a bash `external_directory` ask whose every flagged path names nothing on disk below the filesystem root (and is not a proven write) is honored, and the review log records `authorizer_allow_licensed`.\n\nDefaults to an empty list (no links).",
|
|
149
151
|
"default": [],
|
|
152
|
+
"maxItems": 1000,
|
|
150
153
|
"type": "array",
|
|
151
154
|
"items": {
|
|
152
155
|
"type": "string",
|
|
@@ -464,6 +467,7 @@
|
|
|
464
467
|
"description": "A filesystem effect: read (the command only reads its path operands) or write (it may modify them)."
|
|
465
468
|
},
|
|
466
469
|
{
|
|
470
|
+
"maxItems": 1000,
|
|
467
471
|
"type": "array",
|
|
468
472
|
"items": {
|
|
469
473
|
"type": "string",
|
|
@@ -476,6 +480,7 @@
|
|
|
476
480
|
},
|
|
477
481
|
"unlessOption": {
|
|
478
482
|
"description": "Option stems whose appearance anywhere in the command withdraws the declaration, so its path operands fall back to consulting both directional surfaces.",
|
|
483
|
+
"maxItems": 1000,
|
|
479
484
|
"type": "array",
|
|
480
485
|
"items": {
|
|
481
486
|
"type": "string",
|
|
@@ -504,6 +509,7 @@
|
|
|
504
509
|
"description": "A filesystem effect: read (the command only reads its path operands) or write (it may modify them)."
|
|
505
510
|
},
|
|
506
511
|
{
|
|
512
|
+
"maxItems": 1000,
|
|
507
513
|
"type": "array",
|
|
508
514
|
"items": {
|
|
509
515
|
"type": "string",
|
|
@@ -59,7 +59,8 @@ export interface InboxProcessor {
|
|
|
59
59
|
* The answer honors the floor the child raised (`intent.floor`): a serving
|
|
60
60
|
* `allow` rule does not answer an ask the child's own gate floored. A bash
|
|
61
61
|
* chain is judged on every unit the child left asking (`intent.askingUnits`),
|
|
62
|
-
* each with its own floor
|
|
62
|
+
* each with its own floor and in the spellings the child fixed for it, since
|
|
63
|
+
* this answer approves the whole tool call.
|
|
63
64
|
*
|
|
64
65
|
* Narrow by design (ISP): the server needs one decision, not the whole
|
|
65
66
|
* resolver. The composition root satisfies it with `ResolverServingPolicy`
|
|
@@ -193,27 +193,49 @@ function asForwardedAccessIntent(
|
|
|
193
193
|
*/
|
|
194
194
|
function isWellFormedAskingUnits(
|
|
195
195
|
value: unknown,
|
|
196
|
-
): value is readonly
|
|
196
|
+
): value is readonly AskingBashUnit[] {
|
|
197
197
|
return (
|
|
198
198
|
Array.isArray(value) &&
|
|
199
199
|
value.length > 0 &&
|
|
200
|
-
value.every(
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
200
|
+
value.every(isWellFormedAskingUnit)
|
|
201
|
+
);
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/**
|
|
205
|
+
* True for one `{ command: string, spellings?: string[], floor?: string }`
|
|
206
|
+
* unit.
|
|
207
|
+
*
|
|
208
|
+
* A present `spellings` must be a non-empty all-string list: the child omits
|
|
209
|
+
* the key when it has none, and a malformed list must never read as "no
|
|
210
|
+
* spellings", which would let a serving `deny` written against one miss.
|
|
211
|
+
*/
|
|
212
|
+
function isWellFormedAskingUnit(value: unknown): value is AskingBashUnit {
|
|
213
|
+
if (typeof value !== "object" || value === null) return false;
|
|
214
|
+
const unit = value as {
|
|
215
|
+
command?: unknown;
|
|
216
|
+
spellings?: unknown;
|
|
217
|
+
floor?: unknown;
|
|
218
|
+
};
|
|
219
|
+
return (
|
|
220
|
+
typeof unit.command === "string" &&
|
|
221
|
+
(unit.spellings === undefined || isNonEmptyStringList(unit.spellings)) &&
|
|
222
|
+
(unit.floor === undefined || typeof unit.floor === "string")
|
|
223
|
+
);
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
function isNonEmptyStringList(value: unknown): value is string[] {
|
|
227
|
+
return (
|
|
228
|
+
Array.isArray(value) &&
|
|
229
|
+
value.length > 0 &&
|
|
230
|
+
value.every((entry) => typeof entry === "string")
|
|
208
231
|
);
|
|
209
232
|
}
|
|
210
233
|
|
|
211
234
|
/** Rebuild each unit field by field, so no unread key rides through. */
|
|
212
|
-
function copyAskingUnits(
|
|
213
|
-
units: readonly { command: string; floor?: string }[],
|
|
214
|
-
): AskingBashUnit[] {
|
|
235
|
+
function copyAskingUnits(units: readonly AskingBashUnit[]): AskingBashUnit[] {
|
|
215
236
|
return units.map((unit) => ({
|
|
216
237
|
command: unit.command,
|
|
238
|
+
...(unit.spellings === undefined ? {} : { spellings: [...unit.spellings] }),
|
|
217
239
|
...(unit.floor === undefined ? {} : { floor: unit.floor }),
|
|
218
240
|
}));
|
|
219
241
|
}
|
|
@@ -133,8 +133,9 @@ export interface ForwardedAccessFacts {
|
|
|
133
133
|
*/
|
|
134
134
|
floor?: string;
|
|
135
135
|
/**
|
|
136
|
-
* Every unit of a bash chain the child left asking, each with its own floor
|
|
137
|
-
*
|
|
136
|
+
* Every unit of a bash chain the child left asking, each with its own floor
|
|
137
|
+
* and the spellings the child matched it in. `matchValues` names only the
|
|
138
|
+
* chain's winner, and the serving node's answer
|
|
138
139
|
* approves the whole tool call, so it judges each of these instead. Absent
|
|
139
140
|
* for a non-bash ask and for a bash ask raised without a chain (the empty
|
|
140
141
|
* parse), where `matchValues` is the whole command.
|
|
@@ -16,6 +16,13 @@ import { z } from "zod";
|
|
|
16
16
|
export const PERMISSIONS_SCHEMA_URL =
|
|
17
17
|
"https://raw.githubusercontent.com/gotgenes/pi-packages/main/packages/pi-permission-system/schemas/permissions.schema.json";
|
|
18
18
|
|
|
19
|
+
/**
|
|
20
|
+
* The most entries any config array accepts. zod checks `.max()` before it
|
|
21
|
+
* walks the elements, so an oversized array costs one issue rather than one per
|
|
22
|
+
* entry (CVE-2023-54404); an unbounded array has no such guard.
|
|
23
|
+
*/
|
|
24
|
+
const MAX_CONFIG_ARRAY_ITEMS = 1000;
|
|
25
|
+
|
|
19
26
|
const permissionStateSchema = z
|
|
20
27
|
.union([
|
|
21
28
|
z.literal("allow").meta({
|
|
@@ -334,7 +341,10 @@ const declaredEffectSchema = z.enum(["read", "write"]).meta({
|
|
|
334
341
|
});
|
|
335
342
|
|
|
336
343
|
const declaredEffectsSchema = z
|
|
337
|
-
.union([
|
|
344
|
+
.union([
|
|
345
|
+
declaredEffectSchema,
|
|
346
|
+
z.array(declaredEffectSchema).max(MAX_CONFIG_ARRAY_ITEMS),
|
|
347
|
+
])
|
|
338
348
|
.meta({
|
|
339
349
|
description:
|
|
340
350
|
'The filesystem effects of a command\'s path operands: "read", "write", or an array of them. An empty array declares that the operands touch no file, so they are withdrawn from the path surfaces.',
|
|
@@ -373,10 +383,14 @@ const commandKeySchema = z
|
|
|
373
383
|
const commandEffectsEntrySchema = z
|
|
374
384
|
.strictObject({
|
|
375
385
|
effects: declaredEffectsSchema.optional(),
|
|
376
|
-
unlessOption: z
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
386
|
+
unlessOption: z
|
|
387
|
+
.array(optionStemSchema)
|
|
388
|
+
.max(MAX_CONFIG_ARRAY_ITEMS)
|
|
389
|
+
.optional()
|
|
390
|
+
.meta({
|
|
391
|
+
description:
|
|
392
|
+
"Option stems whose appearance anywhere in the command withdraws the declaration, so its path operands fall back to consulting both directional surfaces.",
|
|
393
|
+
}),
|
|
380
394
|
get subcommands() {
|
|
381
395
|
return z
|
|
382
396
|
.record(
|
|
@@ -460,6 +474,7 @@ export const unifiedConfigSchema = z
|
|
|
460
474
|
permissionDialogKeys: dialogKeysSchema.optional(),
|
|
461
475
|
promptNotifications: z
|
|
462
476
|
.array(promptNotificationChannelSchema)
|
|
477
|
+
.max(MAX_CONFIG_ARRAY_ITEMS)
|
|
463
478
|
.optional()
|
|
464
479
|
.meta({
|
|
465
480
|
description:
|
|
@@ -516,20 +531,28 @@ export const unifiedConfigSchema = z
|
|
|
516
531
|
markdownDescription:
|
|
517
532
|
"**Deprecated and ignored.** Superseded by `promptMaxRows` and `promptFieldMaxWidth`, which bound the whole permission prompt rather than one summary inside it.\n\nStill accepted so an existing config is not rejected fail-closed, but the value no longer takes effect. Remove it.",
|
|
518
533
|
}),
|
|
519
|
-
piInfrastructureReadPaths: z
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
534
|
+
piInfrastructureReadPaths: z
|
|
535
|
+
.array(z.string().min(1))
|
|
536
|
+
.max(MAX_CONFIG_ARRAY_ITEMS)
|
|
537
|
+
.optional()
|
|
538
|
+
.meta({
|
|
539
|
+
description:
|
|
540
|
+
"Additional directories to auto-allow for reads as Pi infrastructure, bypassing the external_directory gate. Supports ~ expansion and wildcard patterns (* and ?).",
|
|
541
|
+
markdownDescription:
|
|
542
|
+
"Additional directories to auto-allow for reads as Pi infrastructure, bypassing the `external_directory` gate.\n\nThe extension auto-discovers the global node_modules root (walks up from the extension's install path; falls back to `npm root -g` from a dev checkout), Pi's own install directory (via the coding-agent `getPackageDir()` API), Pi's harness entries under `agentDir` (`agents/`, `extensions/`, `git/`, `npm/`, `prompts/`, `skills/`, `themes/`, `settings.json`, `SYSTEM.md`, `APPEND_SYSTEM.md`, `AGENTS.md`), and project-local `.pi/npm/` and `.pi/git/`. The package's own logs directory is never auto-allowed, even when an entry here covers it. Add entries here for edge cases where auto-discovery is insufficient (e.g. custom `npmCommand` pointing to pnpm).\n\nSupports `~`/`$HOME` expansion. Entries may be plain directory prefixes or wildcard patterns using `*` (matches any characters, including `/`) and `?` (matches exactly one character). `**` and `*` are equivalent — both cross directory boundaries.\n\nOn Windows, matching is case-insensitive and tolerant of either path separator.",
|
|
543
|
+
default: [],
|
|
544
|
+
}),
|
|
545
|
+
authorizerChain: z
|
|
546
|
+
.array(z.string().min(1))
|
|
547
|
+
.max(MAX_CONFIG_ARRAY_ITEMS)
|
|
548
|
+
.optional()
|
|
549
|
+
.meta({
|
|
550
|
+
description:
|
|
551
|
+
"Ordered names of registered live-authority chain links to consult before the terminal authorizer. Config order (not registration order) fixes the chain order; an unregistered name is skipped fail-safe (more prompting, never less); a link decides nothing until it is named here.",
|
|
552
|
+
markdownDescription:
|
|
553
|
+
"Ordered names of registered **live-authority chain links** (e.g. a model judge) to consult before the terminal authorizer (the human, or the subagent-forwarding / headless-deny fallback).\n\nA link reviews an `ask` and returns `allow` / `deny` (with an optional teaching reason) / `defer` to the next link. Three invariants govern the chain:\n\n- **Config order wins.** The order here \u2014 not the order extensions register in \u2014 fixes the security-relevant chain order.\n- **Fail-safe skip.** A name with no registered link is skipped with a warning; the `ask` still reaches the terminal (more prompting, never less).\n- **Opt-in activation.** Installing a judge extension grants it no authority; a link decides nothing until you name it here.\n\nThe chain owner caps every verdict with a bounded-delegation checkpoint: a link's `allow` on an excluded surface (`external_directory` or `path`) is downgraded to `defer`, so a link cannot exceed your policy. The one exception is per ask: a link's `allow` on a bash `external_directory` ask whose every flagged path names nothing on disk below the filesystem root (and is not a proven write) is honored, and the review log records `authorizer_allow_licensed`.\n\nDefaults to an empty list (no links).",
|
|
554
|
+
default: [],
|
|
555
|
+
}),
|
|
533
556
|
permission: permissionSchema.optional(),
|
|
534
557
|
shellTools: shellToolsSchema.optional(),
|
|
535
558
|
commandEffects: commandEffectsSchema.optional(),
|
|
@@ -111,13 +111,28 @@ export function resolveBashCommandCheck(
|
|
|
111
111
|
}
|
|
112
112
|
}
|
|
113
113
|
|
|
114
|
-
const
|
|
114
|
+
const units = commands.map((cmd) =>
|
|
115
115
|
resolveCommandUnit(cmd, command, agentName, resolver),
|
|
116
116
|
);
|
|
117
|
+
const checks = units.map((unit) => unit.check);
|
|
117
118
|
const winner =
|
|
118
|
-
pickMostRestrictive(
|
|
119
|
+
pickMostRestrictive(checks) ??
|
|
119
120
|
resolveOnBashSurface(command, [], agentName, resolver);
|
|
120
|
-
return withAskingUnits(withChainFloor(winner,
|
|
121
|
+
return withAskingUnits(withChainFloor(winner, checks), units);
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* One unit's verdict, and the spellings of the command that verdict names
|
|
126
|
+
* (`check.command`).
|
|
127
|
+
*
|
|
128
|
+
* The two travel together because a site can replace `check.command`, and the
|
|
129
|
+
* spellings describe one text only: a site that changes the command decides
|
|
130
|
+
* its spellings in the same expression, so they can never ride beside a text
|
|
131
|
+
* they do not spell.
|
|
132
|
+
*/
|
|
133
|
+
interface ResolvedUnit {
|
|
134
|
+
check: PermissionCheckResult;
|
|
135
|
+
spellings: readonly string[];
|
|
121
136
|
}
|
|
122
137
|
|
|
123
138
|
/**
|
|
@@ -125,19 +140,21 @@ export function resolveBashCommandCheck(
|
|
|
125
140
|
*
|
|
126
141
|
* The winner names one command, but a forwarded ask's answer approves the
|
|
127
142
|
* whole tool call, so the serving node has to judge every unit the child could
|
|
128
|
-
* not resolve, each with its own floor (#1030)
|
|
129
|
-
* the
|
|
143
|
+
* not resolve, each with its own floor (#1030) and in the spellings the child
|
|
144
|
+
* matched it in, which only the child's parse can produce (#1019). A unit the
|
|
145
|
+
* child's rules or the session allowed stays home.
|
|
130
146
|
*/
|
|
131
147
|
function withAskingUnits(
|
|
132
148
|
winner: PermissionCheckResult,
|
|
133
|
-
|
|
149
|
+
units: readonly ResolvedUnit[],
|
|
134
150
|
): PermissionCheckResult {
|
|
135
151
|
if (winner.state !== "ask") return winner;
|
|
136
|
-
const askingUnits =
|
|
137
|
-
.filter((
|
|
138
|
-
.map((
|
|
139
|
-
command:
|
|
140
|
-
...(
|
|
152
|
+
const askingUnits = units
|
|
153
|
+
.filter(({ check }) => check.state === "ask")
|
|
154
|
+
.map(({ check, spellings }) => ({
|
|
155
|
+
command: check.command ?? "",
|
|
156
|
+
...(spellings.length === 0 ? {} : { spellings: [...spellings] }),
|
|
157
|
+
...(check.floor === undefined ? {} : { floor: check.floor }),
|
|
141
158
|
}));
|
|
142
159
|
return askingUnits.length === 0 ? winner : { ...winner, askingUnits };
|
|
143
160
|
}
|
|
@@ -165,13 +182,16 @@ function withChainFloor(
|
|
|
165
182
|
* Resolve one command unit of the chain: its own `bash`-surface rule, floored
|
|
166
183
|
* where the enumerator established a reason to floor it, then tagged with the
|
|
167
184
|
* facts the prompt and the session-approval suggestion read off the winner.
|
|
185
|
+
*
|
|
186
|
+
* Paired with the unit's spellings: a plain unit and a wrapper unit both keep
|
|
187
|
+
* the unit's own text as `command`, so its spellings still apply.
|
|
168
188
|
*/
|
|
169
189
|
function resolveCommandUnit(
|
|
170
190
|
cmd: BashCommand,
|
|
171
191
|
command: string,
|
|
172
192
|
agentName: string | undefined,
|
|
173
193
|
resolver: ScopedPermissionResolver,
|
|
174
|
-
):
|
|
194
|
+
): ResolvedUnit {
|
|
175
195
|
const base = resolveOnBashSurface(
|
|
176
196
|
cmd.text,
|
|
177
197
|
cmd.spellings ?? [],
|
|
@@ -182,10 +202,24 @@ function resolveCommandUnit(
|
|
|
182
202
|
cmd.wrapperKind && base.state === "allow" && !isSessionGrant(base)
|
|
183
203
|
? resolveWrapperUnit(cmd, cmd.wrapperKind, base, agentName, resolver)
|
|
184
204
|
: base;
|
|
185
|
-
const
|
|
205
|
+
const unit = floorUnparsedUnit(cmd, command, {
|
|
206
|
+
check: floored,
|
|
207
|
+
spellings: cmd.spellings ?? [],
|
|
208
|
+
});
|
|
209
|
+
return { ...unit, check: tagWithUnitFacts(cmd, unit.check) };
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* Tag a unit's check with the facts the prompt reads off the winner: the
|
|
214
|
+
* execution context of a nested command, and the command a wrapper runs.
|
|
215
|
+
*/
|
|
216
|
+
function tagWithUnitFacts(
|
|
217
|
+
cmd: BashCommand,
|
|
218
|
+
check: PermissionCheckResult,
|
|
219
|
+
): PermissionCheckResult {
|
|
186
220
|
const contextual = cmd.context
|
|
187
|
-
? { ...
|
|
188
|
-
:
|
|
221
|
+
? { ...check, commandContext: cmd.context }
|
|
222
|
+
: check;
|
|
189
223
|
return cmd.executedUnit === undefined
|
|
190
224
|
? contextual
|
|
191
225
|
: { ...contextual, executedUnit: cmd.executedUnit };
|
|
@@ -211,20 +245,27 @@ function resolveCommandUnit(
|
|
|
211
245
|
* A session grant is never floored: the user approved this exact command, and
|
|
212
246
|
* an `ask` carrying it would tie with a sibling unit's real ask and could
|
|
213
247
|
* approve the whole chain through `GateRunner`'s session fast path (#1033).
|
|
248
|
+
*
|
|
249
|
+
* Naming the whole command drops the unit's spellings: they spell the unit's
|
|
250
|
+
* text, and no unit owns the whole command line.
|
|
214
251
|
*/
|
|
215
252
|
function floorUnparsedUnit(
|
|
216
253
|
cmd: BashCommand,
|
|
217
254
|
command: string,
|
|
218
|
-
resolved:
|
|
219
|
-
):
|
|
255
|
+
resolved: ResolvedUnit,
|
|
256
|
+
): ResolvedUnit {
|
|
257
|
+
const { check } = resolved;
|
|
220
258
|
if (
|
|
221
259
|
!cmd.parseUnresolved ||
|
|
222
|
-
|
|
223
|
-
isSessionGrant(
|
|
260
|
+
check.state !== "allow" ||
|
|
261
|
+
isSessionGrant(check)
|
|
224
262
|
) {
|
|
225
263
|
return resolved;
|
|
226
264
|
}
|
|
227
|
-
return {
|
|
265
|
+
return {
|
|
266
|
+
check: { ...floorToAsk(check, UNPARSED_SUBTREE_SENTINEL), command },
|
|
267
|
+
spellings: [],
|
|
268
|
+
};
|
|
228
269
|
}
|
|
229
270
|
|
|
230
271
|
/**
|
|
@@ -14,8 +14,11 @@ import { mostRestrictiveOf } from "./restrictiveness";
|
|
|
14
14
|
* A bash chain is judged unit by unit: the child names its winner in
|
|
15
15
|
* `matchValues`, but this answer approves the whole tool call, so every unit the
|
|
16
16
|
* child left asking (`askingUnits`) is resolved with its own floor and the most
|
|
17
|
-
* restrictive answer decides (#1030).
|
|
18
|
-
*
|
|
17
|
+
* restrictive answer decides (#1030). Each unit is matched in the spellings the
|
|
18
|
+
* child fixed for it (the home-expanded form, path arguments made absolute
|
|
19
|
+
* against the child's cwd), never recomputed here, since only the child's parse
|
|
20
|
+
* knows them (#1019). A request without units (an older child, or an ask raised
|
|
21
|
+
* without a chain) is judged on its single value.
|
|
19
22
|
*
|
|
20
23
|
* The `matchValues` are used as the child fixed them, never re-derived through
|
|
21
24
|
* this session's `PathNormalizer`/cwd. The resolver's surface-family fold is
|
|
@@ -41,7 +44,9 @@ export class ResolverServingPolicy implements ServingPolicy {
|
|
|
41
44
|
* Judge one unit the child left asking, with that unit's own floor.
|
|
42
45
|
*
|
|
43
46
|
* Resolved as the same `bash-command` intent the child's gate emitted for
|
|
44
|
-
* it, so a serving rule matches the unit exactly as a
|
|
47
|
+
* it, spellings included, so a serving rule matches the unit exactly as a
|
|
48
|
+
* local one would. A unit from an older child carries none and is matched as
|
|
49
|
+
* typed.
|
|
45
50
|
*/
|
|
46
51
|
private resolveUnit(
|
|
47
52
|
unit: AskingBashUnit,
|
|
@@ -51,7 +56,7 @@ export class ResolverServingPolicy implements ServingPolicy {
|
|
|
51
56
|
kind: "bash-command",
|
|
52
57
|
surface: "bash",
|
|
53
58
|
command: unit.command,
|
|
54
|
-
spellings: [],
|
|
59
|
+
spellings: unit.spellings ?? [],
|
|
55
60
|
agentName,
|
|
56
61
|
});
|
|
57
62
|
return honorChildFloor(check, unit.floor, this.isYoloEnabled());
|
package/src/types.ts
CHANGED
|
@@ -121,10 +121,19 @@ export interface PermissionCheckResult {
|
|
|
121
121
|
|
|
122
122
|
/**
|
|
123
123
|
* One unit of a bash chain the gate left asking, as the serving node of a
|
|
124
|
-
* forwarded ask needs it: the unit as typed,
|
|
124
|
+
* forwarded ask needs it: the unit as typed, the other spellings it was matched
|
|
125
|
+
* in, and the floor that raised it.
|
|
125
126
|
*/
|
|
126
127
|
export interface AskingBashUnit {
|
|
127
128
|
command: string;
|
|
129
|
+
/**
|
|
130
|
+
* The other spellings of `command` the child's shell runs identically, as
|
|
131
|
+
* the child's program analysis produced them: home-expanded, and with path
|
|
132
|
+
* arguments made absolute against the child's working directory. Child-fixed:
|
|
133
|
+
* the serving node matches them as given and never recomputes them. Absent
|
|
134
|
+
* when there are none.
|
|
135
|
+
*/
|
|
136
|
+
spellings?: readonly string[];
|
|
128
137
|
floor?: string;
|
|
129
138
|
}
|
|
130
139
|
|