@xprnvd/pi-permission-system 42.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,27 @@ 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
+
8
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)
9
30
 
10
31
 
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.
@@ -619,6 +619,8 @@ A subagent's floored ask keeps its floor when it is forwarded to the parent sess
619
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.
620
620
  The parent's `deny` still denies, and a grant for the whole parent session or the parent's `yoloMode` still approves.
621
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`.
622
624
 
623
625
  Because of this, set an explicit `bash` policy rather than relying on a permissive top-level `*`.
624
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.
@@ -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": "42.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": {
@@ -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.
@@ -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