feat(session): add provision editor, visibility, and auto-provisioned timeline entries

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

Author: grypez

packages/caprock/bin/hook.test.ts

@@ -0,0 +1,115 @@
+/* eslint-disable n/no-process-env */
+import { execFile, spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+const execFileAsync = promisify(execFile);
+
+const HOOK_BIN = fileURLToPath(
+  new URL('../dist/bin/hook.mjs', import.meta.url),
+);
+const PKG_DIR = fileURLToPath(new URL('..', import.meta.url));
+
+/**
+ * Spawn hook.mjs with a JSON payload on stdin and collect all output.
+ *
+ * @param payload - The hook event payload to send.
+ * @param env - Extra environment variables.
+ * @param timeoutMs - Kill timeout in milliseconds.
+ * @returns stdout, stderr, and exit code.
+ */
+async function runHook(
+  payload: unknown,
+  env: NodeJS.ProcessEnv,
+  timeoutMs: number,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('node', [HOOK_BIN], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, ...env },
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (chunk: Buffer) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on('data', (chunk: Buffer) => {
+      stderr += chunk.toString();
+    });
+
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(new Error(`Hook timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      resolve({ stdout, stderr, exitCode: code ?? -1 });
+    });
+
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+
+    child.stdin.write(JSON.stringify(payload));
+    child.stdin.end();
+  });
+}
+
+describe('hook binary', () => {
+  let ocapHome: string;
+
+  beforeAll(async () => {
+    await execFileAsync('yarn', ['build'], { cwd: PKG_DIR });
+    ocapHome = await mkdtemp(join(tmpdir(), 'caprock-hook-test-'));
+  }, 60_000);
+
+  afterAll(async () => {
+    await rm(ocapHome, { recursive: true, force: true });
+  });
+
+  it('loads without SES globals (SessionStart)', async () => {
+    const { stderr, exitCode } = await runHook(
+      {
+        hook_event_name: 'SessionStart',
+        session_id: 'hook-integration-test',
+        transcript_path: '/dev/null',
+      },
+      { OCAP_HOME: ocapHome },
+      8_000,
+    );
+
+    expect(exitCode).toBe(0);
+    expect(stderr).not.toMatch(/harden is not defined/u);
+    expect(stderr).not.toMatch(/Cannot initialize @endo\/errors/u);
+    expect(stderr).not.toMatch(/missing globalThis\.assert/u);
+  }, 8_000);
+
+  it('loads without SES globals (PreToolUse)', async () => {
+    const { stdout, stderr, exitCode } = await runHook(
+      {
+        hook_event_name: 'PreToolUse',
+        session_id: 'hook-integration-test',
+        transcript_path: '/dev/null',
+        tool_name: 'Bash',
+        tool_input: { command: 'ls -la' },
+      },
+      { OCAP_HOME: ocapHome },
+      8_000,
+    );
+
+    expect(exitCode).toBe(0);
+    expect(stderr).not.toMatch(/harden is not defined/u);
+    expect(stderr).not.toMatch(/Cannot initialize @endo\/errors/u);
+    expect(stderr).not.toMatch(/missing globalThis\.assert/u);
+    // With no daemon running the hook must not block — it passes through.
+    expect(stdout).toContain('"continue":true');
+  }, 8_000);
+});

packages/caprock/bin/hook.ts

@@ -36,8 +36,10 @@ import {
   pingDaemon,
   sendCommand,
   decodeCapData,
+  decodeSmallcapsStrings,
   createKernelSession,
   authorizeRequest,
+  recordProvisioned,
 } from '../src/rpc.ts';
 import {
   loadSessionState,
@@ -262,6 +264,32 @@ async function vatAddSection(
   });
 }
 
+/**
+ * Return the first provision that matches the given tool and invocations,
+ * or null if none match.
+ *
+ * @param rootKref - The vat's root kref.
+ * @param tool - The tool name.
+ * @param invocations - The parsed command components.
+ * @returns The matching provision, or null.
+ */
+async function vatFindMatch(
+  rootKref: string,
+  tool: string,
+  invocations: ParsedInvocation[],
+): Promise<Provision | null> {
+  const response = await sendCommand({
+    socketPath: SOCKET_PATH,
+    method: 'queueMessage',
+    params: [rootKref, 'findMatch', [tool, invocations]],
+  });
+  if (isJsonRpcFailure(response)) {
+    return null;
+  }
+  const raw = decodeCapData(response.result as CapData);
+  return decodeSmallcapsStrings(raw) as Provision | null;
+}
+
 /**
  * Return the number of entries in the permission vat's allow set.
  *
@@ -517,6 +545,22 @@ async function onPreToolUse(payload: PreToolUsePayload): Promise<void> {
   });
 
   if (vatResponse === 'allow') {
+    if (state.kernelSessionId && invocations !== null) {
+      const autoDescription = `Allow ${tool_name}(${JSON.stringify(tool_input)})`;
+      vatFindMatch(state.rootKref, tool_name, invocations)
+        .then(async (matched) =>
+          recordProvisioned(
+            SOCKET_PATH,
+            state.kernelSessionId,
+            autoDescription,
+            {
+              invocations,
+              ...(matched === null ? {} : { provision: matched }),
+            },
+          ),
+        )
+        .catch(() => undefined);
+    }
     process.stdout.write(JSON.stringify({ continue: true }));
     return;
   }
@@ -546,7 +590,9 @@ async function onPreToolUse(payload: PreToolUsePayload): Promise<void> {
     if (!isNoSubscriber && errorStr.includes('Session not found')) {
       try {
         const ks = await createKernelSession(SOCKET_PATH, session_id);
+        // eslint-disable-next-line require-atomic-updates
         state.kernelSessionId = ks.sessionId;
+        // eslint-disable-next-line require-atomic-updates
         state.ocapUrl = ks.ocapUrl;
         await saveSessionState(session_id, state);
         connectId = ks.sessionId;
@@ -593,7 +639,7 @@ async function onPreToolUse(payload: PreToolUsePayload): Promise<void> {
       feedback: decision.feedback,
     });
     process.stdout.write(
-      `${preToolUseDeny(decision.feedback || 'Rejected via TUI')}\n`,
+      `${preToolUseDeny(decision.feedback ?? 'Rejected via TUI')}\n`,
     );
   }
 }

packages/caprock/src/rpc.ts

@@ -1,4 +1,7 @@
-import type { ParsedInvocation } from '@metamask/kernel-utils/session/provision';
+import type {
+  ParsedInvocation,
+  Provision,
+} from '@metamask/kernel-utils/session/provision';
 import type { JsonRpcResponse } from '@metamask/utils';
 import { assertIsJsonRpcResponse, isJsonRpcFailure } from '@metamask/utils';
 import { randomUUID } from 'node:crypto';
@@ -265,6 +268,32 @@ export async function authorizeRequest(
   return response.result as Decision;
 }
 
+/**
+ * Record a request that was auto-accepted by a standing provision.
+ *
+ * @param socketPath - The UNIX socket path.
+ * @param sessionId - The kernel session ID.
+ * @param description - Human-readable description of the auto-accepted operation.
+ * @param options - Optional parameters.
+ * @param options.invocations - Parsed invocations to forward to the TUI.
+ * @param options.provision - The standing provision that approved the request.
+ */
+export async function recordProvisioned(
+  socketPath: string,
+  sessionId: string,
+  description: string,
+  options?: { invocations?: ParsedInvocation[]; provision?: Provision },
+): Promise<void> {
+  const params: Record<string, unknown> = { sessionId, description };
+  if (options?.invocations !== undefined) {
+    params.invocations = options.invocations;
+  }
+  if (options?.provision !== undefined) {
+    params.provision = options.provision;
+  }
+  await sendCommand({ socketPath, method: 'session.record', params });
+}
+
 /**
  * Decode a CapData body to a JavaScript value.
  *
@@ -282,3 +311,31 @@ export function decodeCapData(capData: CapData): unknown {
   }
   throw new Error(`Unexpected CapData body format: ${body.slice(0, 40)}`);
 }
+
+/**
+ * Recursively strip the smallcaps `!` escape prefix from string values in a
+ * decoded CapData object. In smallcaps encoding, strings that begin with a
+ * sigil character (including `-` for negative special floats) are prefixed
+ * with `!` to distinguish them from encoding markers. This reversal is needed
+ * when decoding complex objects like Provision (whose argv may contain flags
+ * like `--oneline` that become `!--oneline` after encoding).
+ *
+ * @param value - A JSON-parsed smallcaps value.
+ * @returns The value with all `!`-escaped strings decoded.
+ */
+export function decodeSmallcapsStrings(value: unknown): unknown {
+  if (typeof value === 'string') {
+    return value.startsWith('!') ? value.slice(1) : value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(decodeSmallcapsStrings);
+  }
+  if (typeof value === 'object' && value !== null) {
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+      result[key] = decodeSmallcapsStrings(val);
+    }
+    return result;
+  }
+  return value;
+}

packages/caprock/vat/permission-tracker.ts

@@ -22,7 +22,11 @@ import type {
   Provision,
   ParsedInvocation,
 } from '@metamask/kernel-utils/session';
-import { computeAuthority, matchPattern } from '@metamask/kernel-utils/session';
+import {
+  computeAuthority,
+  matchPattern,
+  matchProvision,
+} from '@metamask/kernel-utils/session';
 import {
   constant,
   leastAuthority,
@@ -79,9 +83,7 @@ function provisionToProvider(
         );
       }
       for (let i = 0; i < provision.patterns.length; i++) {
-        const pattern = provision.patterns[
-          i
-        ] as (typeof provision.patterns)[number];
+        const pattern = provision.patterns[i];
         const inv = invocations[i] as ParsedInvocation;
         if (!matchPattern(pattern, inv.name, inv.argv)) {
           throw new Error(`pattern mismatch at index ${i}`);
@@ -162,6 +164,32 @@ export function buildRootObject(): ReturnType<typeof makeDefaultExo> {
       rebuildSection();
     },
 
+    /**
+     * Return the first provision that matches the given tool and invocations,
+     * or null if none match.
+     *
+     * @param tool - The tool name.
+     * @param invocations - The parsed command components.
+     * @returns The matching provision, or null.
+     */
+    findMatch(tool: string, invocations: ParsedInvocation[]): Provision | null {
+      for (const { provision } of sectionRecords) {
+        if (matchProvision(provision, tool, invocations)) {
+          return provision;
+        }
+      }
+      return null;
+    },
+
+    /**
+     * Return all provisions currently in the sheaf.
+     *
+     * @returns Array of provisions, oldest first.
+     */
+    listProvisions(): Provision[] {
+      return sectionRecords.map(({ provision }) => provision);
+    },
+
     /**
      * Return the current section count (for session_end stats).
      *

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

@@ -73,6 +73,7 @@ function makeTestSession(overrides: Partial<Session> = {}): Session {
       verdict: 'accept' as const,
       feedback: '',
     }),
+    recordProvisioned: vi.fn(),
     subscribe: vi.fn(),
     ...overrides,
   };
@@ -343,6 +344,38 @@ describe('startRpcSocketServer — session.* methods', () => {
     });
   });
 
+  it('session.record calls recordProvisioned with description and invocations', async () => {
+    const { startRpcSocketServer } = await import('./rpc-socket-server.ts');
+    const socketPath = makeSocketPath();
+    const existing = makeTestSession({
+      sessionId: 'alice',
+      ocapUrl: 'ocap://alice',
+      startedAt: '2026-01-01T00:00:00.000Z',
+    });
+    const registry = makeTestRegistry([existing]);
+
+    handle = await startRpcSocketServer({
+      socketPath,
+      kernel: {} as never,
+      kernelDatabase: { executeQuery: vi.fn() } as never,
+      channelFactory: {} as never,
+      sessionRegistry: registry,
+    });
+
+    const invocations = [{ name: 'git', argv: ['status'] }];
+    const response = await sendRequest(socketPath, 'session.record', {
+      sessionId: 'alice',
+      description: 'Allow Bash({"command":"git status"})',
+      invocations,
+    });
+
+    expect(response.result).toBeNull();
+    expect(existing.recordProvisioned).toHaveBeenCalledWith(
+      'Allow Bash({"command":"git status"})',
+      { invocations },
+    );
+  });
+
   it('session.authorize returns the decision from authorizeRequest()', async () => {
     const { startRpcSocketServer } = await import('./rpc-socket-server.ts');
     const socketPath = makeSocketPath();
@@ -376,8 +409,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' },
     );
   });
 });