feat(session): thread ParsedInvocation through authorization pipeline

Carries parsed command invocations from the hook call-site through
the session registry and channel to TUI history entries, enabling
the provision editor to show per-arg pattern controls.

- Move ParsedInvocation type to session/types.ts to avoid circular deps
- Add invocations? to SectionNotification and SessionHistoryEntry
- Change authorizeRequest signature to an options bag
  { reason?, timeoutMs?, invocations? } for extensibility
- channel.listAll() includes invocations via ifDefined in both the
  pending and decided entry paths
- rpc-socket-server session.authorize handler extracts invocations
  from JSON-RPC params and forwards to session.authorizeRequest

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: grypez

packages/kernel-node-runtime/src/daemon/rpc-socket-server.test.ts

@@ -376,8 +376,7 @@ describe('startRpcSocketServer — session.* methods', () => {
     expect(response.result).toStrictEqual(decision);
     expect(existing.authorizeRequest).toHaveBeenCalledWith(
       'Allow read access',
-      'Needed for operation',
-      undefined,
+      { reason: 'Needed for operation' },
     );
   });
 });

packages/kernel-node-runtime/src/daemon/rpc-socket-server.ts

@@ -1,7 +1,10 @@
 import { RpcService } from '@metamask/kernel-rpc-methods';
 import type { KernelDatabase } from '@metamask/kernel-store';
 import { ifDefined } from '@metamask/kernel-utils';
-import type { Provision } from '@metamask/kernel-utils/session';
+import type {
+  ParsedInvocation,
+  Provision,
+} from '@metamask/kernel-utils/session';
 import type { Kernel } from '@metamask/ocap-kernel';
 import { rpcHandlers } from '@metamask/ocap-kernel/rpc';
 import { unlink } from 'node:fs/promises';
@@ -302,11 +305,14 @@ async function handleSessionRequest(
           typeof args.reason === 'string' ? args.reason : undefined;
         const timeoutMs =
           typeof args.timeoutMs === 'number' ? args.timeoutMs : undefined;
-        const decision = await session.authorizeRequest(
-          description,
-          reason,
-          timeoutMs,
-        );
+        const invocations = Array.isArray(args.invocations)
+          ? (args.invocations as ParsedInvocation[])
+          : undefined;
+        const decision = await session.authorizeRequest(description, {
+          ...ifDefined({ reason }),
+          ...ifDefined({ timeoutMs }),
+          ...ifDefined({ invocations }),
+        });
         return ok(decision);
       }
 

packages/kernel-utils/src/session/channel.ts

@@ -1,6 +1,7 @@
 import { makePromiseKit } from '@endo/promise-kit';
 import type { PromiseKit } from '@endo/promise-kit';
 
+import { ifDefined } from '../misc.ts';
 import type {
   Decision,
   SectionNotification,
@@ -181,6 +182,7 @@ export function makeChannel(): Channel {
         queuedAt: hist.queuedAt,
         status: hist.verdict,
         decidedAt: hist.decidedAt,
+        ...ifDefined({ invocations: hist.notification.invocations }),
       }));
       const stillPending: SessionHistoryEntry[] = Array.from(
         pending.values(),
@@ -191,6 +193,7 @@ export function makeChannel(): Channel {
         guard: pend.notification.guard,
         queuedAt: pend.queuedAt,
         status: 'pending' as const,
+        ...ifDefined({ invocations: pend.notification.invocations }),
       }));
       return [...decided, ...stillPending].sort((lhs, rhs) => {
         if (lhs.queuedAt < rhs.queuedAt) {

packages/kernel-utils/src/session/index.ts

@@ -1,6 +1,7 @@
 export type {
   ArgPattern,
   InvocationPattern,
+  ParsedInvocation,
   Provision,
   SectionRequest,
   SectionNotification,
@@ -14,7 +15,7 @@ export { makeChannel } from './channel.ts';
 export type { Channel, ModalStream } from './channel.ts';
 export { makeSessionRegistry } from './session-registry.ts';
 export type { Session, SessionRegistry } from './session-registry.ts';
-export type { ParsedInvocation, PatternOrder } from './provision.ts';
+export type { PatternOrder } from './provision.ts';
 export {
   isPathArg,
   pathInterval,

packages/kernel-utils/src/session/provision.ts

@@ -1,6 +1,9 @@
-import type { ArgPattern, InvocationPattern, Provision } from './types.ts';
-
-export type ParsedInvocation = { name: string; argv: string[] };
+import type {
+  ArgPattern,
+  InvocationPattern,
+  ParsedInvocation,
+  Provision,
+} from './types.ts';
 
 /**
  * Returns true if the string looks like a file-system path (absolute or relative).

packages/kernel-utils/src/session/session-registry.test.ts

@@ -139,10 +139,9 @@ describe('makeSessionRegistry', () => {
     const registry = makeSessionRegistry(makeChannelBundle());
     const session = await registry.createSession();
 
-    const authPromise = session.authorizeRequest(
-      'Write /tmp/out',
-      'needs temp',
-    );
+    const authPromise = session.authorizeRequest('Write /tmp/out', {
+      reason: 'needs temp',
+    });
 
     // Retrieve the token from the pending list so we can decide it
     const pending = session.listPending();
@@ -162,11 +161,10 @@ describe('makeSessionRegistry', () => {
       const registry = makeSessionRegistry(makeChannelBundle());
       const session = await registry.createSession();
 
-      const authPromise = session.authorizeRequest(
-        'Execute script',
-        'needs shell',
-        500,
-      );
+      const authPromise = session.authorizeRequest('Execute script', {
+        reason: 'needs shell',
+        timeoutMs: 500,
+      });
 
       // Advance past the timeout — no subscriber decides, so the race rejects
       vi.advanceTimersByTime(600);

packages/kernel-utils/src/session/session-registry.ts

@@ -2,6 +2,7 @@ import { ifDefined } from '../misc.ts';
 import type { Channel, ModalStream } from './channel.ts';
 import type {
   Decision,
+  ParsedInvocation,
   SectionNotification,
   SessionHistoryEntry,
 } from './types.ts';
@@ -28,8 +29,11 @@ export type Session = {
   queueRequest(description: string, reason?: string): string;
   authorizeRequest(
     description: string,
-    reason?: string,
-    timeoutMs?: number,
+    options?: {
+      reason?: string;
+      timeoutMs?: number;
+      invocations?: ParsedInvocation[];
+    },
   ): Promise<Decision>;
   subscribe(stream: ModalStream): void;
 };
@@ -69,10 +73,17 @@ function makeSession(
   const makeNotification = (
     description: string,
     reason: string,
+    invocations?: ParsedInvocation[],
   ): SectionNotification => {
     const token = `req-${requestCount}`;
     requestCount += 1;
-    return { token, description, reason, guard: { body: '#{}', slots: [] } };
+    return {
+      token,
+      description,
+      reason,
+      guard: { body: '#{}', slots: [] },
+      ...ifDefined({ invocations }),
+    };
   };
 
   return harden({
@@ -101,10 +112,14 @@ function makeSession(
 
     async authorizeRequest(
       description: string,
-      reason = 'Queued from CLI',
-      timeoutMs?: number,
+      options: {
+        reason?: string;
+        timeoutMs?: number;
+        invocations?: ParsedInvocation[];
+      } = {},
     ): Promise<Decision> {
-      const notification = makeNotification(description, reason);
+      const { reason = 'Queued from CLI', timeoutMs, invocations } = options;
+      const notification = makeNotification(description, reason, invocations);
       const decision = channel.broadcast(notification);
       if (timeoutMs === undefined) {
         return decision;

packages/kernel-utils/src/session/types.ts

@@ -1,3 +1,9 @@
+/**
+ * A single parsed command-or-tool invocation: the name and its positional args.
+ * Used to describe what exactly was called before being converted to a Provision.
+ */
+export type ParsedInvocation = { name: string; argv: string[] };
+
 /**
  * Pattern for one positional argument in a provision.
  *
@@ -61,6 +67,8 @@ export type SectionNotification = {
   reason: string;
   schema?: unknown;
   guard: { body: string; slots: string[] };
+  /** Parsed invocations for the request — present when routed through the PreToolUse hook. */
+  invocations?: ParsedInvocation[];
 };
 
 /**
@@ -103,6 +111,8 @@ export type SessionHistoryEntry = {
   queuedAt: string;
   status: 'pending' | 'accepted' | 'rejected';
   decidedAt?: string;
+  /** Parsed invocations — present when routed through the PreToolUse hook. */
+  invocations?: ParsedInvocation[];
 };
 
 /**