@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 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
- **One decision is still open.**
216
- How policy may _enter_ the system — which channels are admissible, and with what precedence — is being worked out in [issue #799](https://github.com/gotgenes/pi-packages/issues/799).
217
- Several requested widenings are parked on it rather than declined, durable persistence of an approval among them.
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, and the floor that raised it.
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
- * `matchValues` names only the chain's winner, and the serving node's answer
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.
@@ -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.**
@@ -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": "41.0.0",
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": "pnpm run build:types",
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 . && eslint . && pnpm run lint:md"
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-packages.git",
65
- "directory": "packages/pi-permission-system"
64
+ "url": "git+https://github.com/xprnvd/pi-permission-system.git"
66
65
  },
67
- "homepage": "https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system#readme",
66
+ "homepage": "https://github.com/xprnvd/pi-permission-system",
68
67
  "bugs": {
69
- "url": "https://github.com/gotgenes/pi-packages/issues"
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": "catalog:",
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": "catalog:",
91
- "rollup": "catalog:",
92
- "rollup-plugin-dts": "catalog:",
93
- "rumdl": "catalog:",
94
- "typescript": "catalog:",
95
- "vitest": "catalog:"
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.4.3"
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, since this answer approves the whole tool call.
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 { command: string; floor?: string }[] {
196
+ ): value is readonly AskingBashUnit[] {
197
197
  return (
198
198
  Array.isArray(value) &&
199
199
  value.length > 0 &&
200
- value.every(
201
- (unit: unknown) =>
202
- typeof unit === "object" &&
203
- unit !== null &&
204
- typeof (unit as { command?: unknown }).command === "string" &&
205
- ((unit as { floor?: unknown }).floor === undefined ||
206
- typeof (unit as { floor?: unknown }).floor === "string"),
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
- * `matchValues` names only the chain's winner, and the serving node's answer
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([declaredEffectSchema, z.array(declaredEffectSchema)])
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.array(optionStemSchema).optional().meta({
377
- description:
378
- "Option stems whose appearance anywhere in the command withdraws the declaration, so its path operands fall back to consulting both directional surfaces.",
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.array(z.string().min(1)).optional().meta({
520
- description:
521
- "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the external_directory gate. Supports ~ expansion and wildcard patterns (* and ?).",
522
- markdownDescription:
523
- "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.",
524
- default: [],
525
- }),
526
- authorizerChain: z.array(z.string().min(1)).optional().meta({
527
- description:
528
- "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.",
529
- markdownDescription:
530
- "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).",
531
- default: [],
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 results = commands.map((cmd) =>
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(results) ??
119
+ pickMostRestrictive(checks) ??
119
120
  resolveOnBashSurface(command, [], agentName, resolver);
120
- return withAskingUnits(withChainFloor(winner, results), results);
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). A unit the child's rules or
129
- * the session allowed stays home.
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
- results: readonly PermissionCheckResult[],
149
+ units: readonly ResolvedUnit[],
134
150
  ): PermissionCheckResult {
135
151
  if (winner.state !== "ask") return winner;
136
- const askingUnits = results
137
- .filter((result) => result.state === "ask")
138
- .map((result) => ({
139
- command: result.command ?? "",
140
- ...(result.floor === undefined ? {} : { floor: result.floor }),
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
- ): PermissionCheckResult {
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 unparsed = floorUnparsedUnit(cmd, command, floored);
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
- ? { ...unparsed, commandContext: cmd.context }
188
- : unparsed;
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: PermissionCheckResult,
219
- ): PermissionCheckResult {
255
+ resolved: ResolvedUnit,
256
+ ): ResolvedUnit {
257
+ const { check } = resolved;
220
258
  if (
221
259
  !cmd.parseUnresolved ||
222
- resolved.state !== "allow" ||
223
- isSessionGrant(resolved)
260
+ check.state !== "allow" ||
261
+ isSessionGrant(check)
224
262
  ) {
225
263
  return resolved;
226
264
  }
227
- return { ...floorToAsk(resolved, UNPARSED_SUBTREE_SENTINEL), command };
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). A request without units (an older child,
18
- * or an ask raised without a chain) is judged on its single value.
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 local one would.
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, and the floor that raised it.
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