pi-daddy 0.56.3 → 0.57.0

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.
Files changed (66) hide show
  1. package/CHANGELOG.md +7 -0
  2. package/README.md +15 -1
  3. package/dist/governance/approval-prompt.d.ts +3 -1
  4. package/dist/governance/approval-prompt.d.ts.map +1 -1
  5. package/dist/governance/approval-prompt.js +7 -3
  6. package/dist/governance/approval-prompt.js.map +1 -1
  7. package/dist/governance/permission-question.d.ts.map +1 -1
  8. package/dist/governance/permission-question.js +15 -5
  9. package/dist/governance/permission-question.js.map +1 -1
  10. package/dist/kernel/child-tools.d.ts +17 -0
  11. package/dist/kernel/child-tools.d.ts.map +1 -0
  12. package/dist/kernel/child-tools.js +46 -0
  13. package/dist/kernel/child-tools.js.map +1 -0
  14. package/dist/kernel/definitions.d.ts +2 -0
  15. package/dist/kernel/definitions.d.ts.map +1 -1
  16. package/dist/kernel/definitions.js.map +1 -1
  17. package/dist/kernel/delegate-types.d.ts +2 -0
  18. package/dist/kernel/delegate-types.d.ts.map +1 -1
  19. package/dist/kernel/delegate-types.js.map +1 -1
  20. package/dist/kernel/delegate.d.ts.map +1 -1
  21. package/dist/kernel/delegate.js +12 -1
  22. package/dist/kernel/delegate.js.map +1 -1
  23. package/dist/kernel/principal-binding.d.ts.map +1 -1
  24. package/dist/kernel/principal-binding.js +11 -0
  25. package/dist/kernel/principal-binding.js.map +1 -1
  26. package/dist/kernel/selected-definitions.d.ts.map +1 -1
  27. package/dist/kernel/selected-definitions.js +10 -1
  28. package/dist/kernel/selected-definitions.js.map +1 -1
  29. package/dist/kernel/selected-resources.d.ts +21 -0
  30. package/dist/kernel/selected-resources.d.ts.map +1 -0
  31. package/dist/kernel/selected-resources.js +10 -0
  32. package/dist/kernel/selected-resources.js.map +1 -0
  33. package/dist/kernel/spawn.d.ts +2 -0
  34. package/dist/kernel/spawn.d.ts.map +1 -1
  35. package/dist/kernel/spawn.js +3 -1
  36. package/dist/kernel/spawn.js.map +1 -1
  37. package/dist/products/dashboard-components.d.ts.map +1 -1
  38. package/dist/products/dashboard-components.js +17 -1
  39. package/dist/products/dashboard-components.js.map +1 -1
  40. package/dist/products/dashboard-screen.d.ts.map +1 -1
  41. package/dist/products/dashboard-screen.js +1 -1
  42. package/dist/products/dashboard-screen.js.map +1 -1
  43. package/dist/products/dashboard-settings.d.ts +2 -1
  44. package/dist/products/dashboard-settings.d.ts.map +1 -1
  45. package/dist/products/dashboard-settings.js +10 -1
  46. package/dist/products/dashboard-settings.js.map +1 -1
  47. package/extensions/approvals.ts +52 -38
  48. package/extensions/chain-approval-facts.ts +20 -0
  49. package/extensions/definition-describe.ts +1 -0
  50. package/extensions/delegate-chain.ts +35 -21
  51. package/extensions/grants.ts +2 -0
  52. package/extensions/session.ts +3 -0
  53. package/package.json +2 -2
  54. package/src/governance/approval-prompt.ts +10 -4
  55. package/src/governance/permission-question.ts +16 -5
  56. package/src/kernel/child-tools.ts +62 -0
  57. package/src/kernel/definitions.ts +2 -0
  58. package/src/kernel/delegate-types.ts +2 -0
  59. package/src/kernel/delegate.ts +12 -1
  60. package/src/kernel/principal-binding.ts +11 -0
  61. package/src/kernel/selected-definitions.ts +11 -1
  62. package/src/kernel/selected-resources.ts +20 -0
  63. package/src/kernel/spawn.ts +4 -1
  64. package/src/products/dashboard-components.ts +21 -1
  65. package/src/products/dashboard-screen.ts +1 -0
  66. package/src/products/dashboard-settings.ts +11 -0
@@ -168,13 +168,13 @@ export async function storedApprovals(
168
168
  gated: Capability[],
169
169
  subject: string,
170
170
  expectedBinding?: ApprovalBinding,
171
- ): Promise<ResolveApprovalsResult> {
171
+ ): Promise<ResolveApprovalsResult & { recheckReasons: Record<Capability, string> }> {
172
172
  const { valid, dropped } = await loadApprovals({
173
173
  cwd: session.cwd,
174
174
  now: new Date(),
175
175
  snapshotOf: (name) => snapshotOf(session, name),
176
176
  });
177
- return resolveApprovals({
177
+ const result = resolveApprovals({
178
178
  gated,
179
179
  subject,
180
180
  sessionApprovals: session.sessionApprovals,
@@ -186,6 +186,28 @@ export async function storedApprovals(
186
186
  // arrives at `session_start` — after the session object is built.
187
187
  inherited: verifyInherited(session.inheritedApprovals, (name) => snapshotOf(session, name)),
188
188
  });
189
+ const recheckReasons: Record<Capability, string> = {};
190
+ const reasons = {
191
+ expired: "The previous permission expired or its expiry could not be verified.",
192
+ "instructions-changed": "The agent instructions changed or their previous version could not be verified.",
193
+ "type-changed": "The agent’s requested tools changed since the previous permission.",
194
+ "type-missing": "The previously approved agent definition is no longer available.",
195
+ "foreign-cwd": "The previous permission belongs to a different project folder.",
196
+ valid: "",
197
+ };
198
+ for (const capability of result.needsPrompt) {
199
+ const key = approvalKey(capability, subject);
200
+ const previous = dropped.find((entry) => entry.key === key);
201
+ if (previous) recheckReasons[capability] = reasons[previous.verdict];
202
+ else if (result.scopeMismatched.includes(capability))
203
+ recheckReasons[capability] = "The saved permission covers a different request.";
204
+ else {
205
+ const inherited = session.inheritedApprovals.get(key);
206
+ if (inherited && inherited !== snapshotOf(session, subject)?.bodySha256)
207
+ recheckReasons[capability] = reasons["instructions-changed"];
208
+ }
209
+ }
210
+ return { ...result, recheckReasons };
189
211
  }
190
212
 
191
213
  /**
@@ -255,40 +277,32 @@ export async function obtainApprovals(
255
277
  let refusalCode: RefusalCode | undefined;
256
278
  let reason: string | undefined;
257
279
 
258
- for (const capability of pre.needsPrompt) {
259
- const outcome = await gate.request({
260
- capability,
261
- subject,
262
- path,
263
- task,
264
- signal,
265
- project: session.cwd,
266
- workspace: expectedBinding?.workspace_id,
267
- recheckReason: pre.expired.includes(capability)
268
- ? "The previous permission expired."
269
- : pre.scopeMismatched.includes(capability)
270
- ? "The saved permission covers a different request."
271
- : undefined,
272
- ...(expectedBinding ? { bindingKey: approvalBindingDigest(expectedBinding) } : {}),
273
- });
274
- if (outcome.scope === null) {
275
- // Forward the gate's own discriminant rather than re-deriving it from `hasUI`: `hasUI` is true in
276
- // RPC mode too, so an automated client's timeout or dismissal there would misreport as "a human
277
- // declined" if we asked `ctx.hasUI` instead. Only `kind === "declined"` means a person said no.
278
- humanDenied = outcome.kind === "declined";
279
- // The full discriminant, not just the one bit of it that had a field. `no-ui`, `dismissed` and
280
- // `error` used to produce records identical to each other, separated only by free-text `reason` —
281
- // so "was there an operator who timed out, or was there nobody?" had no answer, and the two want
282
- // different fixes. It was computed here all along and thrown away.
283
- gateOutcome = outcome.kind;
284
- refusalCode = pre.expired.includes(capability)
280
+ const outcome = await gate.request({
281
+ capability: pre.needsPrompt[0]!,
282
+ capabilities: pre.needsPrompt,
283
+ subject,
284
+ path,
285
+ task,
286
+ signal,
287
+ project: session.cwd,
288
+ workspace: expectedBinding?.workspace_id,
289
+ recheckReason: [...new Set(Object.values(pre.recheckReasons))].join(" ") || undefined,
290
+ ...(expectedBinding ? { bindingKey: approvalBindingDigest(expectedBinding) } : {}),
291
+ });
292
+ if (outcome.scope === null) {
293
+ // Only an explicit Deny is a human refusal. Cancellation, expiry and UI failure grant nothing.
294
+ humanDenied = outcome.kind === "declined";
295
+ gateOutcome = outcome.kind;
296
+ refusalCode =
297
+ pre.expired.length > 0
285
298
  ? "APPROVAL_EXPIRED"
286
- : pre.scopeMismatched.includes(capability)
299
+ : pre.scopeMismatched.length > 0
287
300
  ? "APPROVAL_SCOPE_MISMATCH"
288
301
  : "GATED_UNAPPROVED";
289
- reason = outcome.reason;
290
- break;
291
- }
302
+ reason = outcome.reason;
303
+ }
304
+ for (const capability of outcome.scope === null ? [] : pre.needsPrompt) {
305
+ const scope = outcome.scope!;
292
306
  approved.push(capability);
293
307
  // R-66: `prompt` means A HUMAN SAW A DIALOG FOR THIS. A caller that joined another's in-flight answer
294
308
  // did not, so it records the source it actually had — the session approval that answer created. Eight
@@ -296,12 +310,12 @@ export async function obtainApprovals(
296
310
  // prompt. Same repair as R-46, one level up: stop asserting a human was asked on a path where they
297
311
  // were not.
298
312
  sources[capability] = outcome.source === "auto" ? "auto" : outcome.joined ? "session" : "prompt";
299
- scopes[capability] = outcome.scope;
300
- recordedScopes[capability] = outcome.scope;
313
+ scopes[capability] = scope;
314
+ recordedScopes[capability] = scope;
301
315
  if (expectedBinding) bindings[capability] = expectedBinding;
302
- if (outcome.scope === "once") uses[capability] = { max: 1, remaining: 0 };
316
+ if (scope === "once") uses[capability] = { max: 1, remaining: 0 };
303
317
 
304
- if (outcome.scope === "session" || outcome.scope === "always") {
318
+ if (scope === "session" || scope === "always") {
305
319
  const key = approvalKey(capability, subject);
306
320
  // Whether THIS call created the authority, decided before we add it. `joined` means a human answer
307
321
  // opened by another delegation was shared with us; an existing key means it was already standing.
@@ -313,7 +327,7 @@ export async function obtainApprovals(
313
327
  else session.sessionApprovals.add(key);
314
328
  banked.push({ key, capability, subject, persisted: false, owned });
315
329
  }
316
- if (outcome.scope === "always") {
330
+ if (scope === "always") {
317
331
  const now = new Date();
318
332
  const current = snapshot(subject);
319
333
  // No readable ceiling means the entry would carry `grantAtApproval: []`, which `entryVerdict`
@@ -2,6 +2,26 @@ import type { InheritableApproval } from "../src/kernel/approval.ts";
2
2
  import type { Capability } from "../src/kernel/resolve.ts";
3
3
  import type { ApprovalOutcome } from "./approvals.ts";
4
4
 
5
+ /** An upfront Auto answer is provisional until an actual step admission, never consumed approval evidence. */
6
+ export function retainedChainApproval(outcome: ApprovalOutcome): ApprovalOutcome | undefined {
7
+ const approved = outcome.approved.filter((capability) => outcome.sources[capability] !== "auto");
8
+ if (!approved.length) return undefined;
9
+ const keep = new Set(approved);
10
+ const filter = <T>(values: Record<Capability, T>): Record<Capability, T> =>
11
+ Object.fromEntries(Object.entries(values).filter(([capability]) => keep.has(capability)));
12
+ return {
13
+ ...outcome,
14
+ approved,
15
+ sources: filter(outcome.sources),
16
+ scopes: filter(outcome.scopes),
17
+ recordedScopes: filter(outcome.recordedScopes),
18
+ bindings: filter(outcome.bindings),
19
+ expiresAt: filter(outcome.expiresAt),
20
+ uses: filter(outcome.uses),
21
+ ...(outcome.banked ? { banked: outcome.banked.filter((entry) => keep.has(entry.capability)) } : {}),
22
+ };
23
+ }
24
+
5
25
  export interface ChainApprovalAudit {
6
26
  sources: Map<string, ApprovalOutcome["sources"][Capability]>;
7
27
  scopes: Map<string, ApprovalOutcome["recordedScopes"][Capability]>;
@@ -38,6 +38,7 @@ export function registerDefinitionDescribe(pi: ExtensionAPI, session: GrantsSess
38
38
  bodySha256: digestDefinition(definition).sha256,
39
39
  binding: definition.binding ?? null,
40
40
  definitionId: definition.definitionId,
41
+ selectedResources: definition.selectedResources ?? null,
41
42
  };
42
43
  const capture = publicEvidenceCall(session.publicEvidence, _id, "delegate_describe", [{ agent: params.agent }]);
43
44
  capture.selected(0, definition);
@@ -44,7 +44,12 @@ import { runOneDelegation } from "./run-delegation.ts";
44
44
  import { isCriticalAssuranceBlock } from "./execute-child.ts";
45
45
  import type { GrantsSession } from "./session.ts";
46
46
  import { GovernanceRefusal, refusal, type StructuredRefusal } from "../src/kernel/refusals.ts";
47
- import { chainApprovalFacts, newChainApprovalAudit, rememberChainApproval } from "./chain-approval-facts.ts";
47
+ import {
48
+ chainApprovalFacts,
49
+ newChainApprovalAudit,
50
+ rememberChainApproval,
51
+ retainedChainApproval,
52
+ } from "./chain-approval-facts.ts";
48
53
  import { newExecutionId } from "../src/kernel/execution-id.ts";
49
54
  import { planChain, type GateRequest } from "./chain-plan.ts";
50
55
  import { contextShape } from "./context-shape.ts";
@@ -234,7 +239,7 @@ export function registerChainTool(pi: ExtensionAPI, session: GrantsSession): voi
234
239
  throw new Error(message);
235
240
  }
236
241
 
237
- // One dialog per `capability@subject`, each naming the step that needs it, all before the first step runs.
242
+ // One dialog per exact permission set for an agent/step, all before the first step runs.
238
243
  const preApproved: InheritableApproval[] = [];
239
244
  const approvalAudit = newChainApprovalAudit();
240
245
  const approvalStep = new Map<string, number>();
@@ -242,36 +247,45 @@ export function registerChainTool(pi: ExtensionAPI, session: GrantsSession): voi
242
247
  [];
243
248
  let declined: { request: GateRequest; outcome: Awaited<ReturnType<typeof obtainApprovals>> } | undefined;
244
249
 
250
+ const requestGroups = new Map<string, GateRequest[]>();
245
251
  for (const request of chainPlan.requests) {
252
+ const key = JSON.stringify([request.subject, request.path, request.stepIndex]);
253
+ const group = requestGroups.get(key) ?? [];
254
+ group.push(request);
255
+ requestGroups.set(key, group);
256
+ }
257
+ for (const requests of requestGroups.values()) {
258
+ const request = requests[0]!;
246
259
  const outcome = await obtainApprovals(
247
260
  session,
248
- [request.capability],
261
+ requests.map((entry) => entry.capability),
249
262
  request.subject,
250
263
  request.path,
251
264
  ctx,
252
265
  request.task,
253
266
  signal,
254
267
  );
255
- if (!outcome.approved.includes(request.capability)) {
256
- // **Stop asking.** The chain's outcome is already fixed, and every further dialog banks authority — a
257
- // `session` yes into `sessionApprovals` and an `always` yes onto disk for 30 days — for a chain that will
258
- // not run. The single-delegate path breaks on the first no for the same reason.
259
- declined = { request, outcome };
268
+ const missing = requests.find((entry) => !outcome.approved.includes(entry.capability));
269
+ if (missing) {
270
+ // Once the chain cannot run, ask nobody else and bank no further authority.
271
+ declined = { request: missing, outcome };
260
272
  break;
261
273
  }
262
- // Auto is provisional and belongs to an actual step admission, never the upfront union.
263
- if (outcome.sources[request.capability] === "auto") continue;
264
- preApproved.push({
265
- capability: request.capability,
266
- subject: request.subject,
267
- scope: outcome.scopes[request.capability] ?? ("once" as const),
268
- // Pinned to THIS subject's body (ADR-0022). Stamped from a single shared subject, the pin was verified
269
- // against one definition's instructions while the capability was spent on another's.
270
- bodySha256: snapshotOf(session, request.subject)?.bodySha256,
271
- });
272
- rememberChainApproval(approvalAudit, request.capability, request.subject, outcome);
273
- approvalStep.set(`${request.capability}@${request.subject}`, request.stepIndex);
274
- approvedDecisions.push({ request, outcome });
274
+ for (const entry of requests) {
275
+ // Auto belongs to actual step admission, never to the upfront permission set.
276
+ if (outcome.sources[entry.capability] === "auto") continue;
277
+ preApproved.push({
278
+ capability: entry.capability,
279
+ subject: entry.subject,
280
+ scope: outcome.scopes[entry.capability] ?? ("once" as const),
281
+ bodySha256: snapshotOf(session, entry.subject)?.bodySha256,
282
+ });
283
+ rememberChainApproval(approvalAudit, entry.capability, entry.subject, outcome);
284
+ approvalStep.set(`${entry.capability}@${entry.subject}`, entry.stepIndex);
285
+ }
286
+ // Retain the group once, excluding provisional Auto facts that no step has admitted or consumed.
287
+ const retained = retainedChainApproval(outcome);
288
+ if (retained) approvedDecisions.push({ request, outcome: retained });
275
289
  }
276
290
 
277
291
  if (declined) {
@@ -42,6 +42,7 @@ import { ENV_WORKSPACE_REGISTRY } from "../src/kernel/workspace.ts";
42
42
  import { appendRecord, buildRecord } from "../src/governance/ledger.ts";
43
43
  import { openPaneCount, reapOpenPanesAsync } from "../src/executors/pane-reaper.ts";
44
44
  import { ENV_GRANT, deriveOwnGrant, observeToolNames } from "../src/kernel/propagation.ts";
45
+ import { snapshotChildTools } from "../src/kernel/child-tools.ts";
45
46
  import { snapshotOf } from "./approvals.ts";
46
47
  import { registerDelegationTools } from "./delegation.ts";
47
48
  import { grantsCommand } from "./grants-command.ts";
@@ -89,6 +90,7 @@ export default function (pi: ExtensionAPI, trustedSession?: GrantsSession) {
89
90
  })();
90
91
  const observerExtensionPath = fileURLToPath(new URL("./activity-timeline.ts", import.meta.url));
91
92
  const session = trustedSession ?? createGrantsSession(extensionPath, undefined, observerExtensionPath);
93
+ session.childToolSources = () => snapshotChildTools(pi.getAllTools());
92
94
  bindEcosystemVersions(pi, session, fileURLToPath(new URL("../", import.meta.url)));
93
95
  session.currentThinking = typeof pi.getThinkingLevel === "function" ? () => pi.getThinkingLevel() : undefined;
94
96
  registerActivityTimeline(pi, session);
@@ -244,6 +244,8 @@ export interface GrantsSession extends NativeSessionHost {
244
244
  ownGrant: Capability[];
245
245
  observed: boolean;
246
246
  observedTools: string[] | null;
247
+ /** Re-read public origins at admission; a parent's callable name does not prove child delivery. */
248
+ childToolSources?: () => readonly import("../src/kernel/child-tools.ts").ChildToolSource[];
247
249
  /** ADR-0016: `SKILL.md` definitions, keyed by name. The format this package spawns from now. */
248
250
  ensureDefinitions?: () => Promise<void>;
249
251
  definitions: Map<string, SkillDefinition>;
@@ -687,6 +689,7 @@ export function createGrantsSession(
687
689
  ledgerPath: session.ledgerPath,
688
690
  extensionPath: session.extensionPath,
689
691
  observerExtensionPath: session.observerExtensionPath,
692
+ childToolSources: session.childToolSources?.(),
690
693
  childEnv: activityChildEnv(session.activity),
691
694
  // ADR-0042: the pin this session holds, handed to the kernel so a delegated child inherits a narrowed
692
695
  // one through the same builder `publishChildEnv` uses. Read here rather than in the kernel so there is
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-daddy",
3
- "version": "0.56.3",
3
+ "version": "0.57.0",
4
4
  "description": "Capability governance for pi sub-agents: spawn Agent Skills (SKILL.md) definitions whose allowed-tools becomes a grant that can only narrow going down a delegation tree, enforced by pi's own --tools allowlist, with an append-only ledger.",
5
5
  "keywords": [
6
6
  "pi-package",
@@ -53,7 +53,7 @@
53
53
  "typecheck": "tsc -p tsconfig.check.json",
54
54
  "test": "node scripts/unit-tests.ts",
55
55
  "test:integration": "node --test test-integration/*.it.ts",
56
- "test:integration:ci": "node --test test-integration/approval.it.ts test-integration/governance.it.ts test-integration/activity.it.ts test-integration/auto-chain.it.ts test-integration/pi-sdk/automatic-start.it.ts test-integration/pi-sdk/dashboard-prompts.it.ts test-integration/pi-sdk/owned-pattern-cleanup.it.ts",
56
+ "test:integration:ci": "node --test test-integration/approval.it.ts test-integration/governance.it.ts test-integration/activity.it.ts test-integration/auto-chain.it.ts test-integration/pi-sdk/automatic-start.it.ts test-integration/pi-sdk/dashboard-prompts.it.ts test-integration/pi-sdk/owned-pattern-cleanup.it.ts test-integration/pi-sdk/child-tool-delivery.it.ts",
57
57
  "contracts:generate": "node scripts/generate-ledger-record-contract.ts",
58
58
  "prepack": "npm run build",
59
59
  "test:smoke": "node scripts/smoke-installed.mjs",
@@ -12,7 +12,7 @@
12
12
 
13
13
  import { randomUUID } from "node:crypto";
14
14
  import type { AutoModeReader } from "../kernel/auto-mode.ts";
15
- import { approvalKey, offeredScopes, type ApprovalPath, type ApprovalScope } from "../kernel/approval.ts";
15
+ import { offeredScopes, type ApprovalPath, type ApprovalScope } from "../kernel/approval.ts";
16
16
  import type { Capability } from "../kernel/resolve.ts";
17
17
  import { selectPermission } from "./permission-question.ts";
18
18
 
@@ -36,6 +36,8 @@ export const SCOPE_LABELS: Record<ApprovalScope, string> = {
36
36
 
37
37
  export interface PromptRequest {
38
38
  capability: Capability;
39
+ /** Exact set covered by this one decision. Omitted for legacy single-capability callers. */
40
+ capabilities?: Capability[];
39
41
  /** Agent type name, or `DELEGATE_SUBJECT` on the delegate path. */
40
42
  subject: string;
41
43
  path: ApprovalPath;
@@ -159,7 +161,7 @@ async function selectApproval(
159
161
  untrack = options.autoMode?.trackPending({
160
162
  id: randomUUID(),
161
163
  subject: request.subject,
162
- capability: request.capability,
164
+ capability: (request.capabilities ?? [request.capability]).join(", "),
163
165
  });
164
166
  const selection = selectPermission(options.ui, request, labels, controller.signal).then((chosen) => {
165
167
  settled = true;
@@ -211,7 +213,7 @@ async function joinApproval(pending: Promise<PromptOutcome>, request: PromptRequ
211
213
  }
212
214
 
213
215
  /**
214
- * The single-flight queue: one dialog per approval key at a time.
216
+ * The single-flight queue: one dialog per exact capability set, subject and binding at a time.
215
217
  *
216
218
  * `delegate` sets no `executionMode`, so an orchestrator can fan out several children at once and two can
217
219
  * hit the same gate simultaneously — otherwise two stacked dialogs asking the identical question.
@@ -302,6 +304,10 @@ export function createApprovalGate(
302
304
 
303
305
  return {
304
306
  async request(request: PromptRequest): Promise<PromptOutcome> {
307
+ const capabilities = [...new Set(request.capabilities ?? [request.capability])].sort();
308
+ if (!capabilities.length || !capabilities.includes(request.capability))
309
+ return { scope: null, kind: "error", reason: "Invalid permission set; no permission was granted." };
310
+ request = { ...request, capabilities };
305
311
  if (request.signal?.aborted) return interrupted(request, "aborted");
306
312
  try {
307
313
  if (options.autoMode && (await options.autoMode.read()).enabled) {
@@ -322,7 +328,7 @@ export function createApprovalGate(
322
328
  };
323
329
  }
324
330
 
325
- const key = `${approvalKey(request.capability, request.subject)}${request.bindingKey ? `#${request.bindingKey}` : ""}`;
331
+ const key = JSON.stringify([request.path, request.subject, capabilities, request.bindingKey ?? null]);
326
332
 
327
333
  // R-29. Join an in-flight dialog, but only *keep* its answer if that answer was about more than one
328
334
  // spawn. A `once` belongs to whichever caller the human was actually looking at — the title shows
@@ -24,16 +24,22 @@ function oneLine(value: string, limit: number): string {
24
24
  .trimEnd() + "…";
25
25
  }
26
26
 
27
- function headline(request: PromptRequest): string {
27
+ function permissionAction(capability: string): string {
28
28
  const actions: Record<string, string> = {
29
29
  "tool:bash": "run shell commands",
30
30
  "tool:write": "write files",
31
31
  "tool:edit": "edit files",
32
32
  "tool:delegate": "delegate work to another agent",
33
33
  };
34
+ return actions[capability] ?? `use ${oneLine(clean(capability), 90)}`;
35
+ }
36
+
37
+ function headline(request: PromptRequest): string {
38
+ const capabilities = request.capabilities ?? [request.capability];
34
39
  const subject = request.path === "delegate" ? "this delegated agent" : oneLine(clean(request.subject), 80);
35
- const action = actions[request.capability] ?? `use ${oneLine(clean(request.capability), 90)}`;
36
- return `Allow ${subject} to ${action}?`;
40
+ return capabilities.length === 1
41
+ ? `Allow ${subject} to ${permissionAction(capabilities[0]!)}?`
42
+ : `Allow ${subject} these ${capabilities.length} permissions?`;
37
43
  }
38
44
 
39
45
  function scopeHint(request: PromptRequest): string {
@@ -46,7 +52,7 @@ function scopeHint(request: PromptRequest): string {
46
52
  /** Render the full, untrusted brief in pages so choices stay reachable on a typical terminal. */
47
53
  function detailLines(request: PromptRequest): string[] {
48
54
  const rows = [
49
- `Permission: ${clean(request.capability)}`,
55
+ ...(request.capabilities ?? [request.capability]).map((capability) => `Permission: ${clean(capability)}`),
50
56
  `Agent: ${clean(request.subject)}`,
51
57
  ...(request.project ? [`Permission project: ${clean(request.project)}`] : []),
52
58
  ...(request.workspace ? [`Requested workspace: ${clean(request.workspace)}`] : []),
@@ -77,11 +83,16 @@ export async function selectPermission(
77
83
  .find((line) => line.trim());
78
84
  const title = [
79
85
  headline(request),
86
+ ...((request.capabilities?.length ?? 1) > 1
87
+ ? request.capabilities!.map((capability) => ` • ${permissionAction(capability)}`)
88
+ : []),
80
89
  ...(task ? [`Requested task: ${oneLine(task, 115)}`] : []),
81
90
  ...(request.project
82
91
  ? [`Permission project: ${oneLine(clean(basename(request.project) || request.project), 60)}`]
83
92
  : []),
84
- ...(request.capability === "tool:bash" ? ["Shell access can change files and run other commands."] : []),
93
+ ...((request.capabilities ?? [request.capability]).includes("tool:bash")
94
+ ? ["Shell access can change files and run other commands."]
95
+ : []),
85
96
  ...(request.recheckReason ? [request.recheckReason] : []),
86
97
  scopeHint(request),
87
98
  ].join("\n");
@@ -0,0 +1,62 @@
1
+ /** Child delivery is separate from a parent's catalog and from permission to grant a tool. */
2
+ import { toPiToolsAllowlist, type Capability } from "./resolve.ts";
3
+ import { refusal, type StructuredRefusal } from "./refusals.ts";
4
+
5
+ /** Native CLI tools shared by the qualified Pi 1.0.4 and 1.5.2 runtimes, not the display catalog. */
6
+ const nativeTools = new Set(["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"]);
7
+ const governedTools = new Set(["delegate", "delegate_all", "delegate_chain", "delegate_describe"]);
8
+ export interface ChildToolSource {
9
+ readonly name: string;
10
+ readonly sourceInfo?: Readonly<{ path?: string; source?: string }>;
11
+ }
12
+
13
+ /** Copy only public origin metadata. Provider schemas, credentials and runtime objects do not cross. */
14
+ export function snapshotChildTools(tools: readonly ChildToolSource[]): readonly ChildToolSource[] {
15
+ return Object.freeze(
16
+ tools.map((tool) =>
17
+ Object.freeze({
18
+ name: tool.name,
19
+ ...(tool.sourceInfo
20
+ ? {
21
+ sourceInfo: Object.freeze({
22
+ path: tool.sourceInfo.path,
23
+ source: tool.sourceInfo.source,
24
+ }),
25
+ }
26
+ : {}),
27
+ }),
28
+ ),
29
+ );
30
+ }
31
+
32
+ export function childToolDeliveryRefusal(
33
+ requested: Capability[],
34
+ context: { childToolSources?: readonly ChildToolSource[]; extensionPath?: string },
35
+ ): StructuredRefusal | undefined {
36
+ const unavailable: string[] = [];
37
+ for (const name of toPiToolsAllowlist(requested) ?? []) {
38
+ // The existing narrowing guard owns wildcard refusal, not delivery classification.
39
+ if (name === "*") continue;
40
+ const entries = context.childToolSources?.filter((tool) => tool.name === name);
41
+ const source = entries?.length === 1 ? entries[0].sourceInfo : undefined;
42
+ // Pure legacy callers may omit observations; real extension dispatch always supplies the live inventory.
43
+ const unobserved = context.childToolSources === undefined;
44
+ const builtin =
45
+ nativeTools.has(name) && (unobserved || (source?.source === "builtin" && source.path === `builtin:${name}`));
46
+ const governed =
47
+ governedTools.has(name) &&
48
+ requested.includes("tool:delegate") &&
49
+ !!context.extensionPath &&
50
+ (unobserved || source?.path === context.extensionPath);
51
+ if (!builtin && !governed) unavailable.push(name);
52
+ }
53
+ if (!unavailable.length) return undefined;
54
+ return refusal(
55
+ "UNKNOWN_TOOL",
56
+ `child tool unavailable: ${unavailable.join(", ")} — the parent catalog is not child delivery. ` +
57
+ "Governed children load native Pi tools and Daddy's explicit entrypoint only; external extensions, MCP and " +
58
+ "SDK-only tools have no qualified child provider here. Keep this work in the parent or choose a definition " +
59
+ "using supported child tools. Additional permission cannot install or qualify a provider.",
60
+ { kind: "child-tool-unavailable", tools: unavailable.join(",") },
61
+ );
62
+ }
@@ -59,6 +59,8 @@ export function digestDefinition(definition: SkillDefinition): DefinitionDigest
59
59
  }
60
60
 
61
61
  export interface SkillDefinition {
62
+ /** Trusted selected-source locations, frozen with the definition identity; never additional authority. */
63
+ selectedResources?: import("./selected-resources.ts").SelectedResources;
62
64
  /** Present only for explicit local public-evidence capture; excluded from authority and identity. */
63
65
  sourceSnapshot?: import("./definition-sources.ts").DefinitionSourceSnapshot;
64
66
  /** Immutable selected-resource identity, independent of the model-authored name. */
@@ -80,6 +80,8 @@ export interface DelegationContext {
80
80
  extensionPath?: string;
81
81
  /** No-tool activity observer injected only for governed leaf children. */
82
82
  observerExtensionPath?: string;
83
+ /** Public tool origins observed in the current host; names alone do not establish child delivery. */
84
+ childToolSources?: readonly import("./child-tools.ts").ChildToolSource[];
83
85
  /**
84
86
  * Extra per-child environment supplied by the composition layer (today: the activity timeline's local
85
87
  * observation identity). Evaluated once the child's execution id is known. The kernel refuses any key in
@@ -5,7 +5,9 @@
5
5
 
6
6
  import { planSpawn } from "./spawn.ts";
7
7
  import { ceilingForDefinition, digestDefinition, type DefinitionDigest, type SkillDefinition } from "./definitions.ts";
8
- import { assertNarrowing, type Capability, type ResolveResult, expandSubsumed } from "./resolve.ts";
8
+ import { assertNarrowing, type Capability, type ResolveResult, expandSubsumed, resolve } from "./resolve.ts";
9
+ import { childToolDeliveryRefusal } from "./child-tools.ts";
10
+ import { selectedResourcePrompt } from "./selected-resources.ts";
9
11
  import { checkRoutingAuthority, checkWorkspaceWildcardRequest } from "./routing-authority.ts";
10
12
  import { DELEGATE_CAPABILITY, agentCapability, maySpawnDefinition, normaliseCapability } from "./capabilities.ts";
11
13
 
@@ -296,6 +298,14 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
296
298
  return denied({ ...empty, requested, reason: wildcardRequest.reason }, wildcardRequest.code);
297
299
  }
298
300
 
301
+ // Refuse undeliverable tools before calculating a permission request. Preserve escalation precedence:
302
+ // a caller without authority still receives the ordinary denial and its exact denied capability set.
303
+ const authority = resolve({ requested, parentGrant: ctx.ownGrant });
304
+ if (authority.denied.length === 0 && authority.universal.length === 0) {
305
+ const unavailable = childToolDeliveryRefusal(requested, ctx);
306
+ if (unavailable) return { ...empty, requested, reason: unavailable.message, refusal: unavailable };
307
+ }
308
+
299
309
  const { result, approvalBinding, bindingMismatch } = resolveDelegationApproval({
300
310
  task: request.task,
301
311
  agent: request.agent,
@@ -365,6 +375,7 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
365
375
  skillPaths: ctx.skillPaths,
366
376
  contextFiles: ctx.contextFiles,
367
377
  systemPrompt,
378
+ selectedResourcePrompt: selectedResourcePrompt(spawned?.selectedResources),
368
379
  // A fork replaces the session file rather than joining it: pi refuses `--fork` beside `--session`.
369
380
  ...(staged?.forkFrom ? { forkFrom: staged.forkFrom } : { sessionFile: ctx.sessionFile }),
370
381
  ...(staged?.contextPrompt ? { contextPrompt: staged.contextPrompt } : {}),
@@ -100,5 +100,16 @@ export async function principalBinding(
100
100
  runtimePreferences: agent.runtimePreferences ?? inline.runtimePreferences,
101
101
  ...(typeof pkg.version === "string" ? { packageVersion: pkg.version } : {}),
102
102
  binding: Object.freeze({ package: "principal-pi-skills", phase }),
103
+ selectedResources: Object.freeze({
104
+ version: 1 as const,
105
+ selectedSkill: Object.freeze({ path, sha256: hash(skillText) }),
106
+ definition: Object.freeze({ path: agentPath, sha256: hash(agentText) }),
107
+ resourceDirectory: dirname(path),
108
+ package: Object.freeze({
109
+ name: "principal-pi-skills" as const,
110
+ root,
111
+ ...(typeof pkg.version === "string" ? { version: pkg.version } : {}),
112
+ }),
113
+ }),
103
114
  };
104
115
  }
@@ -1,6 +1,6 @@
1
1
  /** Selected Pi 1.0.4 resources, frozen once per extension instance. No independent resource scan. */
2
2
  import { createHash } from "node:crypto";
3
- import { resolve as resolvePath } from "node:path";
3
+ import { dirname, resolve as resolvePath } from "node:path";
4
4
  import { lstat } from "node:fs/promises";
5
5
  import { BoundedReadCleanupError, readBoundedBytes } from "./bounded-read.ts";
6
6
  import { parseSkillDefinition, type SkillDefinition } from "./definitions.ts";
@@ -50,6 +50,14 @@ export async function selectedDefinitions(
50
50
  const parsed = parseSkillDefinition(path, text);
51
51
  if (!parsed || parsed.name !== name) throw Error("selected name/path does not match definition");
52
52
  const bound = await principalBinding(path, parsed, text, sources, read);
53
+ const selectedResources =
54
+ bound.selectedResources ??
55
+ Object.freeze({
56
+ version: 1 as const,
57
+ selectedSkill: Object.freeze({ path, sha256: hash(text) }),
58
+ definition: Object.freeze({ path: bound.source, sha256: bound.sourceHash! }),
59
+ resourceDirectory: dirname(path),
60
+ });
53
61
  const definitionId = hash(
54
62
  JSON.stringify({
55
63
  name,
@@ -61,6 +69,7 @@ export async function selectedDefinitions(
61
69
  runtimePreferences: bound.runtimePreferences,
62
70
  binding: bound.binding,
63
71
  packageVersion: bound.packageVersion,
72
+ selectedResources,
64
73
  }),
65
74
  );
66
75
  if (bound.metadata) Object.freeze(bound.metadata);
@@ -68,6 +77,7 @@ export async function selectedDefinitions(
68
77
  name,
69
78
  Object.freeze({
70
79
  ...bound,
80
+ selectedResources,
71
81
  definitionId,
72
82
  ...(sources
73
83
  ? { sourceSnapshot: Object.freeze({ resources: Object.freeze(sources), body: bound.body }) }
@@ -0,0 +1,20 @@
1
+ /** Locations of the selected definition, not permission to load additional resources. */
2
+ export interface SelectedResources {
3
+ readonly version: 1;
4
+ readonly selectedSkill: Readonly<{ path: string; sha256: string }>;
5
+ readonly definition: Readonly<{ path: string; sha256: string }>;
6
+ readonly resourceDirectory: string;
7
+ /** Present only after the selected Principal package's existing binding checks succeeded. */
8
+ readonly package?: Readonly<{ name: "principal-pi-skills"; root: string; version?: string }>;
9
+ }
10
+
11
+ export function selectedResourcePrompt(resources: SelectedResources | undefined): string | undefined {
12
+ if (!resources) return undefined;
13
+ return (
14
+ "Selected definition resource locations (pi-daddy, version 1):\n" +
15
+ JSON.stringify(resources) +
16
+ "\nThese locations identify the selected instruction source. Resolve its relative resource references here, " +
17
+ "using only tools already granted. Other resource contents and availability have not been verified or loaded. " +
18
+ "These locations grant no additional tools, runtime skills, permission, or task approval."
19
+ );
20
+ }