@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 +21 -0
- package/README.md +4 -3
- package/dist/public.d.ts +13 -3
- package/docs/configuration.md +2 -0
- package/docs/glossary.md +283 -0
- package/docs/subagent-integration.md +1 -0
- package/package.json +1 -1
- package/src/authority/forwarded-request-server.ts +2 -1
- package/src/authority/forwarding-io.ts +34 -12
- package/src/authority/permission-forwarding.ts +3 -2
- package/src/handlers/gates/bash-command.ts +61 -20
- package/src/policy/serving-policy.ts +9 -4
- package/src/types.ts +10 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,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
|
-
**
|
|
216
|
-
|
|
217
|
-
|
|
215
|
+
**How policy enters is decided.**
|
|
216
|
+
Which channels are admissible, at what precedence, and who may write policy back is settled in [ADR 0016](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0016-policy-channels.md).
|
|
217
|
+
It admits durable approvals into machine-local `config.local.json` files, makes auto-approve a step after any judge rather than a bypass of it, and declines Pi's `settings.json` and ancestor-directory configs as policy sources; each change ships in its own release.
|
|
218
218
|
The companion question — whether a capability model replaces the actor-keyed surface list — is settled: [ADR 0013](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0013-permission-policy-model.md) adds read/write as an axis beside the existing keys, so a policy can permit reading a path without also permitting writes to it.
|
|
219
219
|
|
|
220
220
|
**Where adjacent requests belong.**
|
|
@@ -227,6 +227,7 @@ Approve-and-steer, edit diffs, and risk explanations → a downstream package ov
|
|
|
227
227
|
|
|
228
228
|
| Document | Contents |
|
|
229
229
|
| ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
230
|
+
| [docs/glossary.md](docs/glossary.md) | The package's terms (surface, gate, chain, link, envelope, node, …) and what each means here |
|
|
230
231
|
| [docs/configuration.md](docs/configuration.md) | Full policy reference, runtime knobs, per-agent overrides, recipes |
|
|
231
232
|
| [docs/session-approvals.md](docs/session-approvals.md) | Session-scoped rules, pattern suggestions, bash arity table |
|
|
232
233
|
| [docs/cross-extension-api.md](docs/cross-extension-api.md) | Cross-extension service accessor, event bus integration, prompt and decision broadcasts |
|
package/dist/public.d.ts
CHANGED
|
@@ -97,10 +97,19 @@ interface PermissionCheckResult {
|
|
|
97
97
|
}
|
|
98
98
|
/**
|
|
99
99
|
* One unit of a bash chain the gate left asking, as the serving node of a
|
|
100
|
-
* forwarded ask needs it: the unit as typed,
|
|
100
|
+
* forwarded ask needs it: the unit as typed, the other spellings it was matched
|
|
101
|
+
* in, and the floor that raised it.
|
|
101
102
|
*/
|
|
102
103
|
interface AskingBashUnit {
|
|
103
104
|
command: string;
|
|
105
|
+
/**
|
|
106
|
+
* The other spellings of `command` the child's shell runs identically, as
|
|
107
|
+
* the child's program analysis produced them: home-expanded, and with path
|
|
108
|
+
* arguments made absolute against the child's working directory. Child-fixed:
|
|
109
|
+
* the serving node matches them as given and never recomputes them. Absent
|
|
110
|
+
* when there are none.
|
|
111
|
+
*/
|
|
112
|
+
spellings?: readonly string[];
|
|
104
113
|
floor?: string;
|
|
105
114
|
}
|
|
106
115
|
|
|
@@ -475,8 +484,9 @@ interface ForwardedAccessFacts {
|
|
|
475
484
|
*/
|
|
476
485
|
floor?: string;
|
|
477
486
|
/**
|
|
478
|
-
* Every unit of a bash chain the child left asking, each with its own floor
|
|
479
|
-
*
|
|
487
|
+
* Every unit of a bash chain the child left asking, each with its own floor
|
|
488
|
+
* and the spellings the child matched it in. `matchValues` names only the
|
|
489
|
+
* chain's winner, and the serving node's answer
|
|
480
490
|
* approves the whole tool call, so it judges each of these instead. Absent
|
|
481
491
|
* for a non-bash ask and for a bash ask raised without a chain (the empty
|
|
482
492
|
* parse), where `matchValues` is the whole command.
|
package/docs/configuration.md
CHANGED
|
@@ -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.
|
package/docs/glossary.md
ADDED
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
# Glossary
|
|
2
|
+
|
|
3
|
+
The terms this package uses, each with the meaning it has here.
|
|
4
|
+
An entry defines a term; the record it links to decides how the thing behaves.
|
|
5
|
+
Terms are grouped by topic, and each heading is a stable anchor (`glossary.md#surface`) that other docs and agents may link to.
|
|
6
|
+
|
|
7
|
+
## Decisions
|
|
8
|
+
|
|
9
|
+
### Action
|
|
10
|
+
|
|
11
|
+
The outcome a rule assigns: `allow`, `ask`, or `deny`.
|
|
12
|
+
`allow` lets the call proceed, `deny` blocks it, and `ask` escalates it to live [authority](#authority).
|
|
13
|
+
A `deny` may carry a reason, which the agent is shown.
|
|
14
|
+
|
|
15
|
+
### Decision
|
|
16
|
+
|
|
17
|
+
The final `allow` or `deny` for one request, after any escalation.
|
|
18
|
+
The [review log](#review-log) records it with `decidedBy`, naming what decided: a rule, a session approval, [yolo](#yolo), the user, an [authorizer link](#link), or a forward.
|
|
19
|
+
|
|
20
|
+
### Verdict
|
|
21
|
+
|
|
22
|
+
What an [authorizer link](#link) returns for an `ask`: `allow`, `deny`, or [`defer`](#defer).
|
|
23
|
+
A [terminal](#terminal) returns only `allow` or `deny`.
|
|
24
|
+
See [ADR 0007](decisions/0007-model-judge-authorizer-chain-adr.md) decisions 1 and 2.
|
|
25
|
+
|
|
26
|
+
### Judgment
|
|
27
|
+
|
|
28
|
+
A decision made by live authority (the human, or a model behind an [authorizer link](#link)) on an `ask`, as opposed to the deterministic resolution of recorded authority.
|
|
29
|
+
Judgment may be non-deterministic; the package's determinism guarantee covers recorded authority only.
|
|
30
|
+
The layering rule is "surface deterministically, discriminate with judgment" ([ADR 0009](decisions/0009-bash-path-projection-completeness-contract.md)).
|
|
31
|
+
|
|
32
|
+
## Policy
|
|
33
|
+
|
|
34
|
+
### Rule
|
|
35
|
+
|
|
36
|
+
One `(surface, pattern) → action` entry, carrying its [origin](#origin).
|
|
37
|
+
Every policy source, config file or session approval, is normalized to rules before a check consults them.
|
|
38
|
+
See [Core data model](architecture/architecture.md#core-data-model).
|
|
39
|
+
|
|
40
|
+
### Pattern
|
|
41
|
+
|
|
42
|
+
The match side of a rule: a command glob, tool name, file path, MCP target, skill name, or `*`.
|
|
43
|
+
`*` matches any run of characters, including `/`, and `?` matches one character; `**` is not a separate globstar and behaves exactly like `*`.
|
|
44
|
+
|
|
45
|
+
### Surface
|
|
46
|
+
|
|
47
|
+
The key a rule is filed under, naming the kind of access it governs.
|
|
48
|
+
Surfaces are tool names (`read`, `write`, `edit`, `bash`, …), `mcp`, `skill`, and the directional path surfaces (`path_read`, `path_write`, `external_directory_read`, `external_directory_write`).
|
|
49
|
+
One tool call can be checked on several surfaces; see [gate](#gate).
|
|
50
|
+
The `*` key, `permission["*"]`, is the universal fallback for any surface without a matching rule.
|
|
51
|
+
|
|
52
|
+
### Surface family
|
|
53
|
+
|
|
54
|
+
`path` and `external_directory` each name a family of two directional surfaces, `_read` and `_write`.
|
|
55
|
+
The two directions are independent: a `path_write` allow grants no read, and a `path_read` deny blocks no write.
|
|
56
|
+
See [ADR 0013](decisions/0013-permission-policy-model.md) decisions 3 and 4.
|
|
57
|
+
|
|
58
|
+
### Sugar
|
|
59
|
+
|
|
60
|
+
A bare `path` or `external_directory` key in config.
|
|
61
|
+
It is expanded at load time, separately for each [scope](#scope) and before scopes are merged, into both directional surfaces of its family; explicit directional entries are placed after the expanded ones.
|
|
62
|
+
|
|
63
|
+
### Path
|
|
64
|
+
|
|
65
|
+
The `path` family governs a file path wherever it is, matched against both its typed spelling and its symlink-resolved one.
|
|
66
|
+
Its idiomatic use is carving denials such as `~/.ssh/*`; granting access outside the working directory is the job of [external directory](#external-directory).
|
|
67
|
+
|
|
68
|
+
### External directory
|
|
69
|
+
|
|
70
|
+
The `external_directory` family fires on a path's relation to the session's working directory (being outside it), not on how the path is spelled.
|
|
71
|
+
It answers "is this in scope at all", while `path` answers "is this particular access permitted", and a call must pass both.
|
|
72
|
+
Granting an outside root takes one line: `external_directory_read: { "~/dev/*": "allow" }`.
|
|
73
|
+
See [ADR 0013](decisions/0013-permission-policy-model.md) decision 5.
|
|
74
|
+
|
|
75
|
+
### Effect
|
|
76
|
+
|
|
77
|
+
What an access does to a file: `read` or `write`.
|
|
78
|
+
A bash path operand's effect is proven by syntax (a redirect), by the built-in set of pure-reader commands, or by the user's `commandEffects` declarations; an operand whose effect is unproven consults both directions.
|
|
79
|
+
`commandEffects` classifies commands; it is not a rule and grants nothing by itself.
|
|
80
|
+
See [ADR 0013](decisions/0013-permission-policy-model.md) decisions 2 and 7.
|
|
81
|
+
|
|
82
|
+
### Ruleset
|
|
83
|
+
|
|
84
|
+
The composed, ordered list of rules a check consults, built in layers: the synthesized default, then the MCP baseline, then config rules, then session rules.
|
|
85
|
+
Evaluation is [last-match-wins](#last-match-wins), so a later layer overrides an earlier one.
|
|
86
|
+
See [Composed ruleset](architecture/architecture.md#composed-ruleset).
|
|
87
|
+
|
|
88
|
+
### Origin
|
|
89
|
+
|
|
90
|
+
Which source contributed a rule (`RuleOrigin`): `global`, `project`, `agent`, `project-agent`, `builtin`, `baseline`, `session`, `yolo`, or `fail-closed`.
|
|
91
|
+
It is reported on the `permissions:decision` event and in the review log, so a surprising outcome traces to its source.
|
|
92
|
+
|
|
93
|
+
### Scope
|
|
94
|
+
|
|
95
|
+
A config source with a fixed precedence position: `global` (the global config file), `project` (the project config file), `agent` (global agent frontmatter), and `project-agent` (project agent frontmatter), in that order.
|
|
96
|
+
A later scope overrides an earlier one on an identical pattern, and a pattern only the later scope defines is placed after the earlier scope's.
|
|
97
|
+
A pattern both define keeps the earlier scope's position, so a later catch-all does not override an earlier scope's specific patterns ([ADR 0016](decisions/0016-policy-channels.md) measurement 4, changing in [#1108]).
|
|
98
|
+
The two project scopes load only for a trusted project; see [project trust](#project-trust).
|
|
99
|
+
|
|
100
|
+
### Channel
|
|
101
|
+
|
|
102
|
+
Any path by which something that changes a check's outcome reaches the package: a scope's file, agent frontmatter, the session layer, or a runtime knob such as `yoloMode`.
|
|
103
|
+
Which channels are admissible, and at what precedence, is decided in [ADR 0016](decisions/0016-policy-channels.md).
|
|
104
|
+
The authority model's "three channels" for reaching live authority, and its statement that yolo "is not a channel", use the word in that narrower sense.
|
|
105
|
+
|
|
106
|
+
### Relax and tighten
|
|
107
|
+
|
|
108
|
+
A change relaxes policy when it can move an outcome toward `allow` (`deny` or `ask` to `allow`), and tightens it when it moves the other way.
|
|
109
|
+
|
|
110
|
+
### Last-match-wins
|
|
111
|
+
|
|
112
|
+
Within one surface, the last matching rule in the [ruleset](#ruleset) decides, so a later layer overrides an earlier one; for scopes, see [scope](#scope).
|
|
113
|
+
|
|
114
|
+
### Most-restrictive-wins
|
|
115
|
+
|
|
116
|
+
Across the surfaces one tool call is checked on, the most restrictive outcome wins (`deny` over `ask` over `allow`), so an allow on one surface cannot loosen another.
|
|
117
|
+
|
|
118
|
+
### Session rule
|
|
119
|
+
|
|
120
|
+
A rule created when the human answers "for this session" at a prompt, also called a session approval.
|
|
121
|
+
It is held in memory, appended after every config rule (the session layer), and cleared when the session ends.
|
|
122
|
+
For bash, the suggested pattern comes from the arity table (`git checkout main` suggests `git checkout *`).
|
|
123
|
+
See [docs/session-approvals.md](session-approvals.md).
|
|
124
|
+
|
|
125
|
+
### Yolo
|
|
126
|
+
|
|
127
|
+
The `yoloMode` runtime knob.
|
|
128
|
+
When on, every `ask` becomes `allow` and every `deny` is preserved; the decision's origin is `yolo`.
|
|
129
|
+
A rule's `ask` is rewritten when the ruleset is composed, and an `ask` a gate synthesizes after resolution (the bash wrapper floor, an unparseable command) is granted at the gate.
|
|
130
|
+
Under yolo an `ask` never reaches live authority, so no [authorizer link](#link) or human is consulted.
|
|
131
|
+
See [yolo is recorded authority](architecture/architecture.md#yolo-is-recorded-authority).
|
|
132
|
+
|
|
133
|
+
### Fail-closed floor
|
|
134
|
+
|
|
135
|
+
When a non-global scope is present but invalid, every composed `allow` becomes `ask` (origin `fail-closed`), so a permissive lower scope cannot survive behind a broken higher one.
|
|
136
|
+
It is applied before yolo.
|
|
137
|
+
See [Fail-closed on an invalid non-global scope](architecture/architecture.md#fail-closed-on-an-invalid-non-global-scope).
|
|
138
|
+
|
|
139
|
+
### Default and baseline
|
|
140
|
+
|
|
141
|
+
The universal default is a synthesized catch-all rule from `permission["*"]` (`ask` when unset), placed first in the ruleset.
|
|
142
|
+
The baseline is a small set of synthesized MCP metadata allows, placed after the default and before config, so a config rule overrides it.
|
|
143
|
+
|
|
144
|
+
### Runtime knob
|
|
145
|
+
|
|
146
|
+
A config field that changes behavior without being a rule, such as `yoloMode`, `debugLog`, `permissionReviewLog`, or `promptTimeoutMs`.
|
|
147
|
+
|
|
148
|
+
### Propagation
|
|
149
|
+
|
|
150
|
+
When a running session sees a changed policy source.
|
|
151
|
+
Rules in config files and agent frontmatter are re-read at the next tool call; runtime knobs are re-read at the next [prompt](#prompt).
|
|
152
|
+
|
|
153
|
+
### Project trust
|
|
154
|
+
|
|
155
|
+
Pi's per-directory decision to trust a project's local resources, which this package observes through `ctx.isProjectTrusted()` and never makes itself.
|
|
156
|
+
See [ADR 0001](decisions/0001-project-trust-adoption.md).
|
|
157
|
+
|
|
158
|
+
## Checking
|
|
159
|
+
|
|
160
|
+
### Tool call
|
|
161
|
+
|
|
162
|
+
One invocation of a tool by the model.
|
|
163
|
+
Pi emits a `tool_call` event before the tool runs, where this package's [gates](#gate) check it and may block it.
|
|
164
|
+
|
|
165
|
+
### Gate
|
|
166
|
+
|
|
167
|
+
One check a tool call must pass: it names a surface and a value, resolves them against the ruleset, and acts on the [action](#action).
|
|
168
|
+
A tool call passes through a fixed sequence of six gates (skill read, path, external directory, bash external directory, bash path, tool), and the first block stops the call (an unconditionally denying gate is checked ahead of the rest); for a shell tool, the tool gate checks each command unit.
|
|
169
|
+
A `/skill:` invocation typed by the user has its own input gate.
|
|
170
|
+
|
|
171
|
+
### Access intent
|
|
172
|
+
|
|
173
|
+
The description of what a call accesses (a tool's input, a bash command unit, a set of paths), built without consulting policy and handed by a gate to the resolver.
|
|
174
|
+
|
|
175
|
+
### Exposure
|
|
176
|
+
|
|
177
|
+
The check run at `before_agent_start` that hides a tool from the model when every value on its surface resolves to `deny`.
|
|
178
|
+
It is the first of two phases; gating at each tool call is the second.
|
|
179
|
+
See [Two-phase checking](architecture/architecture.md#two-phase-checking).
|
|
180
|
+
|
|
181
|
+
### Review log
|
|
182
|
+
|
|
183
|
+
The permission review log, a JSONL file recording each gate decision with its request facts and `decidedBy`.
|
|
184
|
+
Values bound to sensitive names are masked.
|
|
185
|
+
|
|
186
|
+
## Authority
|
|
187
|
+
|
|
188
|
+
### Authority
|
|
189
|
+
|
|
190
|
+
The right to decide whether an action may happen.
|
|
191
|
+
Recorded authority is the [ruleset](#ruleset); live authority is reached only on `ask`, when recorded authority is silent; absent authority (nothing recorded, nothing reachable) means the action is denied.
|
|
192
|
+
See [The authority model](architecture/architecture.md#the-authority-model).
|
|
193
|
+
|
|
194
|
+
### Authorizer
|
|
195
|
+
|
|
196
|
+
The entity that holds live authority for an `ask`.
|
|
197
|
+
The [terminal](#terminal) authorizers are `LocalUserAuthorizer` (prompt the human here), `ParentAuthorizer` (forward to the parent), and `DenyingAuthorizer` (no authority reachable); [links](#link) are the non-terminal ones.
|
|
198
|
+
|
|
199
|
+
### Chain
|
|
200
|
+
|
|
201
|
+
The ordered sequence an `ask` passes through: the [links](#link) the operator names in `authorizerChain`, in config order, then the [terminal](#terminal).
|
|
202
|
+
Each link decides or defers.
|
|
203
|
+
There is one chain per [node](#node); a relaying node runs none and forwards instead.
|
|
204
|
+
See [ADR 0007](decisions/0007-model-judge-authorizer-chain-adr.md).
|
|
205
|
+
|
|
206
|
+
### Link
|
|
207
|
+
|
|
208
|
+
A named, non-terminal authorizer that another extension registers with `registerAuthorizer`.
|
|
209
|
+
It decides nothing until the operator names it in `authorizerChain`, and it returns a [verdict](#verdict).
|
|
210
|
+
|
|
211
|
+
### Terminal
|
|
212
|
+
|
|
213
|
+
The last authorizer in a chain, which must decide and cannot defer.
|
|
214
|
+
|
|
215
|
+
### Defer
|
|
216
|
+
|
|
217
|
+
A link's verdict meaning "not mine to decide": the `ask` passes to the next link, and in the end to the terminal.
|
|
218
|
+
|
|
219
|
+
### Envelope
|
|
220
|
+
|
|
221
|
+
The bounded-delegation checkpoint this package applies to every link verdict, so a link can never exceed the operator's policy.
|
|
222
|
+
A link's `allow` on the `path` or `external_directory` families becomes [`defer`](#defer), except on an `external_directory` ask carrying the nothing-on-disk [license](#license).
|
|
223
|
+
A `deny` rule never reaches the chain at all.
|
|
224
|
+
|
|
225
|
+
### License
|
|
226
|
+
|
|
227
|
+
A fact a gate computes that lets a link's otherwise-capped `allow` through the [envelope](#envelope).
|
|
228
|
+
The one license today is nothing-on-disk: every flagged path of a bash `external_directory` ask names nothing that exists.
|
|
229
|
+
|
|
230
|
+
## Sessions and nodes
|
|
231
|
+
|
|
232
|
+
### Session
|
|
233
|
+
|
|
234
|
+
One Pi conversation, from `session_start` to `session_shutdown`; `/new`, `/resume`, and `/fork` each start a new one.
|
|
235
|
+
Session rules live exactly this long.
|
|
236
|
+
|
|
237
|
+
### Prompt
|
|
238
|
+
|
|
239
|
+
One user submission and the agent loop it starts, from `agent_start` to `agent_end`.
|
|
240
|
+
`before_agent_start` fires once per prompt; this package refreshes its runtime config and runs [exposure](#exposure) there.
|
|
241
|
+
|
|
242
|
+
### Turn
|
|
243
|
+
|
|
244
|
+
One model response and the tool calls it requests, from `turn_start` to `turn_end`.
|
|
245
|
+
A single [prompt](#prompt) can run many turns.
|
|
246
|
+
|
|
247
|
+
### Node
|
|
248
|
+
|
|
249
|
+
One Pi session runtime: one `ExtensionContext`, one event bus, one set of gates, its own registries.
|
|
250
|
+
A node is not a process: one process can host several, such as a parent and its in-process subagent children.
|
|
251
|
+
See [ADR 0012](decisions/0012-cross-node-extension-contract.md).
|
|
252
|
+
|
|
253
|
+
### Requesting, relaying, serving, and adjudicating nodes
|
|
254
|
+
|
|
255
|
+
The roles in forwarding: the requesting node raises the `ask`; a relaying node forwards it instead of deciding; the serving node drains forwarded asks; the adjudicating node is the one whose chain and terminal decide.
|
|
256
|
+
|
|
257
|
+
### Forwarding
|
|
258
|
+
|
|
259
|
+
How a subagent that cannot decide sends its `ask` up the session tree: its `ParentAuthorizer` hands the request to the serving parent, whose chain and terminal decide.
|
|
260
|
+
See [docs/subagent-integration.md](subagent-integration.md).
|
|
261
|
+
|
|
262
|
+
## Packaging
|
|
263
|
+
|
|
264
|
+
### This package
|
|
265
|
+
|
|
266
|
+
`@gotgenes/pi-permission-system`, an npm package containing one Pi [extension](#extension).
|
|
267
|
+
|
|
268
|
+
### Extension
|
|
269
|
+
|
|
270
|
+
Code Pi loads into a session; it receives `ExtensionAPI` and registers event handlers, tools, and commands.
|
|
271
|
+
An extension is fully trusted code in Pi's process, so the boundaries this package draws are about operator attention, not about what other extensions are able to do.
|
|
272
|
+
|
|
273
|
+
### Pi package
|
|
274
|
+
|
|
275
|
+
Pi's installable unit (`pi install npm:…`, `git:…`, or a local path), bundling extensions, skills, prompt templates, and themes.
|
|
276
|
+
|
|
277
|
+
### Downstream extension
|
|
278
|
+
|
|
279
|
+
An extension that integrates with this package through its published service (`getPermissionsService(sessionId)`, with `registerAuthorizer`, `registerToolAccessExtractor`, and the query methods) or its `permissions:*` events, such as `@gotgenes/pi-permission-model-judge`.
|
|
280
|
+
The dependency points toward this package, never away from it.
|
|
281
|
+
See [docs/cross-extension-api.md](cross-extension-api.md).
|
|
282
|
+
|
|
283
|
+
[#1108]: https://github.com/gotgenes/pi-packages/issues/1108
|
|
@@ -149,6 +149,7 @@ When a delegated or routed subagent cannot decide an `ask` where it runs — bec
|
|
|
149
149
|
The main interactive session polls for forwarded requests, shows the confirmation prompt, writes the response, and the subagent resumes once that decision is available.
|
|
150
150
|
A parent `allow`/`deny` rule governs a child's escalation directly (the serving node resolves it as recorded authority before prompting), and a "whole session" grant recorded on the parent auto-approves later forwards of the same pattern.
|
|
151
151
|
For a chained bash command, the parent judges every command the child left asking, not only the first, and the most restrictive answer decides.
|
|
152
|
+
The parent matches each of those commands in the spellings the child computed for it (the home-expanded form and absolute path arguments), since only the child knows its working directory and whether the command rebinds `HOME`.
|
|
152
153
|
The exception is a bash ask the child raised through a [synthetic floor](configuration.md#fail-closed-behavior) (a wrapper such as `sudo` or `bash -c`, or a command the parser could not resolve): the child forwards the floor with the ask, and a parent `allow` rule escalates it to the parent's prompt instead of approving it.
|
|
153
154
|
|
|
154
155
|
This keeps `ask` policies usable even when the original permission check happens inside a non-UI execution context.
|
package/package.json
CHANGED
|
@@ -59,7 +59,8 @@ export interface InboxProcessor {
|
|
|
59
59
|
* The answer honors the floor the child raised (`intent.floor`): a serving
|
|
60
60
|
* `allow` rule does not answer an ask the child's own gate floored. A bash
|
|
61
61
|
* chain is judged on every unit the child left asking (`intent.askingUnits`),
|
|
62
|
-
* each with its own floor
|
|
62
|
+
* each with its own floor and in the spellings the child fixed for it, since
|
|
63
|
+
* this answer approves the whole tool call.
|
|
63
64
|
*
|
|
64
65
|
* Narrow by design (ISP): the server needs one decision, not the whole
|
|
65
66
|
* resolver. The composition root satisfies it with `ResolverServingPolicy`
|
|
@@ -193,27 +193,49 @@ function asForwardedAccessIntent(
|
|
|
193
193
|
*/
|
|
194
194
|
function isWellFormedAskingUnits(
|
|
195
195
|
value: unknown,
|
|
196
|
-
): value is readonly
|
|
196
|
+
): value is readonly AskingBashUnit[] {
|
|
197
197
|
return (
|
|
198
198
|
Array.isArray(value) &&
|
|
199
199
|
value.length > 0 &&
|
|
200
|
-
value.every(
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
200
|
+
value.every(isWellFormedAskingUnit)
|
|
201
|
+
);
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/**
|
|
205
|
+
* True for one `{ command: string, spellings?: string[], floor?: string }`
|
|
206
|
+
* unit.
|
|
207
|
+
*
|
|
208
|
+
* A present `spellings` must be a non-empty all-string list: the child omits
|
|
209
|
+
* the key when it has none, and a malformed list must never read as "no
|
|
210
|
+
* spellings", which would let a serving `deny` written against one miss.
|
|
211
|
+
*/
|
|
212
|
+
function isWellFormedAskingUnit(value: unknown): value is AskingBashUnit {
|
|
213
|
+
if (typeof value !== "object" || value === null) return false;
|
|
214
|
+
const unit = value as {
|
|
215
|
+
command?: unknown;
|
|
216
|
+
spellings?: unknown;
|
|
217
|
+
floor?: unknown;
|
|
218
|
+
};
|
|
219
|
+
return (
|
|
220
|
+
typeof unit.command === "string" &&
|
|
221
|
+
(unit.spellings === undefined || isNonEmptyStringList(unit.spellings)) &&
|
|
222
|
+
(unit.floor === undefined || typeof unit.floor === "string")
|
|
223
|
+
);
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
function isNonEmptyStringList(value: unknown): value is string[] {
|
|
227
|
+
return (
|
|
228
|
+
Array.isArray(value) &&
|
|
229
|
+
value.length > 0 &&
|
|
230
|
+
value.every((entry) => typeof entry === "string")
|
|
208
231
|
);
|
|
209
232
|
}
|
|
210
233
|
|
|
211
234
|
/** Rebuild each unit field by field, so no unread key rides through. */
|
|
212
|
-
function copyAskingUnits(
|
|
213
|
-
units: readonly { command: string; floor?: string }[],
|
|
214
|
-
): AskingBashUnit[] {
|
|
235
|
+
function copyAskingUnits(units: readonly AskingBashUnit[]): AskingBashUnit[] {
|
|
215
236
|
return units.map((unit) => ({
|
|
216
237
|
command: unit.command,
|
|
238
|
+
...(unit.spellings === undefined ? {} : { spellings: [...unit.spellings] }),
|
|
217
239
|
...(unit.floor === undefined ? {} : { floor: unit.floor }),
|
|
218
240
|
}));
|
|
219
241
|
}
|
|
@@ -133,8 +133,9 @@ export interface ForwardedAccessFacts {
|
|
|
133
133
|
*/
|
|
134
134
|
floor?: string;
|
|
135
135
|
/**
|
|
136
|
-
* Every unit of a bash chain the child left asking, each with its own floor
|
|
137
|
-
*
|
|
136
|
+
* Every unit of a bash chain the child left asking, each with its own floor
|
|
137
|
+
* and the spellings the child matched it in. `matchValues` names only the
|
|
138
|
+
* chain's winner, and the serving node's answer
|
|
138
139
|
* approves the whole tool call, so it judges each of these instead. Absent
|
|
139
140
|
* for a non-bash ask and for a bash ask raised without a chain (the empty
|
|
140
141
|
* parse), where `matchValues` is the whole command.
|
|
@@ -111,13 +111,28 @@ export function resolveBashCommandCheck(
|
|
|
111
111
|
}
|
|
112
112
|
}
|
|
113
113
|
|
|
114
|
-
const
|
|
114
|
+
const units = commands.map((cmd) =>
|
|
115
115
|
resolveCommandUnit(cmd, command, agentName, resolver),
|
|
116
116
|
);
|
|
117
|
+
const checks = units.map((unit) => unit.check);
|
|
117
118
|
const winner =
|
|
118
|
-
pickMostRestrictive(
|
|
119
|
+
pickMostRestrictive(checks) ??
|
|
119
120
|
resolveOnBashSurface(command, [], agentName, resolver);
|
|
120
|
-
return withAskingUnits(withChainFloor(winner,
|
|
121
|
+
return withAskingUnits(withChainFloor(winner, checks), units);
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* One unit's verdict, and the spellings of the command that verdict names
|
|
126
|
+
* (`check.command`).
|
|
127
|
+
*
|
|
128
|
+
* The two travel together because a site can replace `check.command`, and the
|
|
129
|
+
* spellings describe one text only: a site that changes the command decides
|
|
130
|
+
* its spellings in the same expression, so they can never ride beside a text
|
|
131
|
+
* they do not spell.
|
|
132
|
+
*/
|
|
133
|
+
interface ResolvedUnit {
|
|
134
|
+
check: PermissionCheckResult;
|
|
135
|
+
spellings: readonly string[];
|
|
121
136
|
}
|
|
122
137
|
|
|
123
138
|
/**
|
|
@@ -125,19 +140,21 @@ export function resolveBashCommandCheck(
|
|
|
125
140
|
*
|
|
126
141
|
* The winner names one command, but a forwarded ask's answer approves the
|
|
127
142
|
* whole tool call, so the serving node has to judge every unit the child could
|
|
128
|
-
* not resolve, each with its own floor (#1030)
|
|
129
|
-
* the
|
|
143
|
+
* not resolve, each with its own floor (#1030) and in the spellings the child
|
|
144
|
+
* matched it in, which only the child's parse can produce (#1019). A unit the
|
|
145
|
+
* child's rules or the session allowed stays home.
|
|
130
146
|
*/
|
|
131
147
|
function withAskingUnits(
|
|
132
148
|
winner: PermissionCheckResult,
|
|
133
|
-
|
|
149
|
+
units: readonly ResolvedUnit[],
|
|
134
150
|
): PermissionCheckResult {
|
|
135
151
|
if (winner.state !== "ask") return winner;
|
|
136
|
-
const askingUnits =
|
|
137
|
-
.filter((
|
|
138
|
-
.map((
|
|
139
|
-
command:
|
|
140
|
-
...(
|
|
152
|
+
const askingUnits = units
|
|
153
|
+
.filter(({ check }) => check.state === "ask")
|
|
154
|
+
.map(({ check, spellings }) => ({
|
|
155
|
+
command: check.command ?? "",
|
|
156
|
+
...(spellings.length === 0 ? {} : { spellings: [...spellings] }),
|
|
157
|
+
...(check.floor === undefined ? {} : { floor: check.floor }),
|
|
141
158
|
}));
|
|
142
159
|
return askingUnits.length === 0 ? winner : { ...winner, askingUnits };
|
|
143
160
|
}
|
|
@@ -165,13 +182,16 @@ function withChainFloor(
|
|
|
165
182
|
* Resolve one command unit of the chain: its own `bash`-surface rule, floored
|
|
166
183
|
* where the enumerator established a reason to floor it, then tagged with the
|
|
167
184
|
* facts the prompt and the session-approval suggestion read off the winner.
|
|
185
|
+
*
|
|
186
|
+
* Paired with the unit's spellings: a plain unit and a wrapper unit both keep
|
|
187
|
+
* the unit's own text as `command`, so its spellings still apply.
|
|
168
188
|
*/
|
|
169
189
|
function resolveCommandUnit(
|
|
170
190
|
cmd: BashCommand,
|
|
171
191
|
command: string,
|
|
172
192
|
agentName: string | undefined,
|
|
173
193
|
resolver: ScopedPermissionResolver,
|
|
174
|
-
):
|
|
194
|
+
): ResolvedUnit {
|
|
175
195
|
const base = resolveOnBashSurface(
|
|
176
196
|
cmd.text,
|
|
177
197
|
cmd.spellings ?? [],
|
|
@@ -182,10 +202,24 @@ function resolveCommandUnit(
|
|
|
182
202
|
cmd.wrapperKind && base.state === "allow" && !isSessionGrant(base)
|
|
183
203
|
? resolveWrapperUnit(cmd, cmd.wrapperKind, base, agentName, resolver)
|
|
184
204
|
: base;
|
|
185
|
-
const
|
|
205
|
+
const unit = floorUnparsedUnit(cmd, command, {
|
|
206
|
+
check: floored,
|
|
207
|
+
spellings: cmd.spellings ?? [],
|
|
208
|
+
});
|
|
209
|
+
return { ...unit, check: tagWithUnitFacts(cmd, unit.check) };
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* Tag a unit's check with the facts the prompt reads off the winner: the
|
|
214
|
+
* execution context of a nested command, and the command a wrapper runs.
|
|
215
|
+
*/
|
|
216
|
+
function tagWithUnitFacts(
|
|
217
|
+
cmd: BashCommand,
|
|
218
|
+
check: PermissionCheckResult,
|
|
219
|
+
): PermissionCheckResult {
|
|
186
220
|
const contextual = cmd.context
|
|
187
|
-
? { ...
|
|
188
|
-
:
|
|
221
|
+
? { ...check, commandContext: cmd.context }
|
|
222
|
+
: check;
|
|
189
223
|
return cmd.executedUnit === undefined
|
|
190
224
|
? contextual
|
|
191
225
|
: { ...contextual, executedUnit: cmd.executedUnit };
|
|
@@ -211,20 +245,27 @@ function resolveCommandUnit(
|
|
|
211
245
|
* A session grant is never floored: the user approved this exact command, and
|
|
212
246
|
* an `ask` carrying it would tie with a sibling unit's real ask and could
|
|
213
247
|
* approve the whole chain through `GateRunner`'s session fast path (#1033).
|
|
248
|
+
*
|
|
249
|
+
* Naming the whole command drops the unit's spellings: they spell the unit's
|
|
250
|
+
* text, and no unit owns the whole command line.
|
|
214
251
|
*/
|
|
215
252
|
function floorUnparsedUnit(
|
|
216
253
|
cmd: BashCommand,
|
|
217
254
|
command: string,
|
|
218
|
-
resolved:
|
|
219
|
-
):
|
|
255
|
+
resolved: ResolvedUnit,
|
|
256
|
+
): ResolvedUnit {
|
|
257
|
+
const { check } = resolved;
|
|
220
258
|
if (
|
|
221
259
|
!cmd.parseUnresolved ||
|
|
222
|
-
|
|
223
|
-
isSessionGrant(
|
|
260
|
+
check.state !== "allow" ||
|
|
261
|
+
isSessionGrant(check)
|
|
224
262
|
) {
|
|
225
263
|
return resolved;
|
|
226
264
|
}
|
|
227
|
-
return {
|
|
265
|
+
return {
|
|
266
|
+
check: { ...floorToAsk(check, UNPARSED_SUBTREE_SENTINEL), command },
|
|
267
|
+
spellings: [],
|
|
268
|
+
};
|
|
228
269
|
}
|
|
229
270
|
|
|
230
271
|
/**
|
|
@@ -14,8 +14,11 @@ import { mostRestrictiveOf } from "./restrictiveness";
|
|
|
14
14
|
* A bash chain is judged unit by unit: the child names its winner in
|
|
15
15
|
* `matchValues`, but this answer approves the whole tool call, so every unit the
|
|
16
16
|
* child left asking (`askingUnits`) is resolved with its own floor and the most
|
|
17
|
-
* restrictive answer decides (#1030).
|
|
18
|
-
*
|
|
17
|
+
* restrictive answer decides (#1030). Each unit is matched in the spellings the
|
|
18
|
+
* child fixed for it (the home-expanded form, path arguments made absolute
|
|
19
|
+
* against the child's cwd), never recomputed here, since only the child's parse
|
|
20
|
+
* knows them (#1019). A request without units (an older child, or an ask raised
|
|
21
|
+
* without a chain) is judged on its single value.
|
|
19
22
|
*
|
|
20
23
|
* The `matchValues` are used as the child fixed them, never re-derived through
|
|
21
24
|
* this session's `PathNormalizer`/cwd. The resolver's surface-family fold is
|
|
@@ -41,7 +44,9 @@ export class ResolverServingPolicy implements ServingPolicy {
|
|
|
41
44
|
* Judge one unit the child left asking, with that unit's own floor.
|
|
42
45
|
*
|
|
43
46
|
* Resolved as the same `bash-command` intent the child's gate emitted for
|
|
44
|
-
* it, so a serving rule matches the unit exactly as a
|
|
47
|
+
* it, spellings included, so a serving rule matches the unit exactly as a
|
|
48
|
+
* local one would. A unit from an older child carries none and is matched as
|
|
49
|
+
* typed.
|
|
45
50
|
*/
|
|
46
51
|
private resolveUnit(
|
|
47
52
|
unit: AskingBashUnit,
|
|
@@ -51,7 +56,7 @@ export class ResolverServingPolicy implements ServingPolicy {
|
|
|
51
56
|
kind: "bash-command",
|
|
52
57
|
surface: "bash",
|
|
53
58
|
command: unit.command,
|
|
54
|
-
spellings: [],
|
|
59
|
+
spellings: unit.spellings ?? [],
|
|
55
60
|
agentName,
|
|
56
61
|
});
|
|
57
62
|
return honorChildFloor(check, unit.floor, this.isYoloEnabled());
|
package/src/types.ts
CHANGED
|
@@ -121,10 +121,19 @@ export interface PermissionCheckResult {
|
|
|
121
121
|
|
|
122
122
|
/**
|
|
123
123
|
* One unit of a bash chain the gate left asking, as the serving node of a
|
|
124
|
-
* forwarded ask needs it: the unit as typed,
|
|
124
|
+
* forwarded ask needs it: the unit as typed, the other spellings it was matched
|
|
125
|
+
* in, and the floor that raised it.
|
|
125
126
|
*/
|
|
126
127
|
export interface AskingBashUnit {
|
|
127
128
|
command: string;
|
|
129
|
+
/**
|
|
130
|
+
* The other spellings of `command` the child's shell runs identically, as
|
|
131
|
+
* the child's program analysis produced them: home-expanded, and with path
|
|
132
|
+
* arguments made absolute against the child's working directory. Child-fixed:
|
|
133
|
+
* the serving node matches them as given and never recomputes them. Absent
|
|
134
|
+
* when there are none.
|
|
135
|
+
*/
|
|
136
|
+
spellings?: readonly string[];
|
|
128
137
|
floor?: string;
|
|
129
138
|
}
|
|
130
139
|
|