@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/src/agentpod-authority.ts

@@ -8,10 +8,12 @@ import {
   writeFileSync,
   fsyncSync,
   realpathSync,
+  mkdirSync,
 } from 'node:fs';
 import { join } from 'node:path';
 import type { Store } from './store.js';
-import { canonical, digest, ServiceError, object, integer } from './protocol.js';
+import { canonical, digest, ServiceError, object, integer, type Session } from './protocol.js';
+import { forkPiSession } from './pi-sessions.js';
 import {
   agentpodBinding,
   AGENTPOD_LEASE_MS,
@@ -80,10 +82,45 @@ export function readAgentPodPins(configPath: string, state: string): AgentPodPin
 }
 
 /** A local node admission, not an Accounts token issuer or a provider login. */
+/** An agent's standing "Always allow" rule (approval scopes). v1 knows one scope: workspace
+ * writes, never deletes, hidden paths, commands, network or anything outside the workspace. */
+export interface ApprovalRule {
+  id: string;
+  scope: 'workspace-write';
+  set_by: string;
+}
+const ruleId = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** Closed: 1 to 16 rules, exact keys, a known scope, unique ids. Absent means none. */
+export function approvalRules(value: unknown): ApprovalRule[] {
+  if (value === undefined) return [];
+  const bad = () => {
+    throw new ServiceError('invalid_approval_rules', 'Malformed approval rules', 400);
+  };
+  if (!Array.isArray(value) || value.length < 1 || value.length > 16) bad();
+  const rules = (value as unknown[]).map((r) => {
+    if (!r || typeof r !== 'object' || Array.isArray(r)) bad();
+    const v = r as Record<string, unknown>;
+    if (
+      Object.keys(v).sort().join(',') !== 'id,scope,set_by' ||
+      typeof v.id !== 'string' ||
+      !ruleId.test(v.id) ||
+      v.scope !== 'workspace-write' ||
+      typeof v.set_by !== 'string' ||
+      v.set_by.length < 1 ||
+      v.set_by.length > 128 ||
+      /[\u0000-\u001f\u007f]/.test(v.set_by)
+    )
+      bad();
+    return { id: v.id as string, scope: 'workspace-write' as const, set_by: v.set_by as string };
+  });
+  if (new Set(rules.map((r) => r.id)).size !== rules.length) bad();
+  return rules.sort((a, b) => a.id.localeCompare(b.id));
+}
 export class AgentPodAuthority {
   readonly boot = randomUUID();
   readonly pins: AgentPodPins;
   private key: Buffer;
+  private readonly stateDir: string;
   constructor(
     readonly store: Store,
     state: string,
@@ -92,6 +129,7 @@ export class AgentPodAuthority {
     readonly ownedResourcesStopped: (session: string) => boolean = () => true,
   ) {
     this.pins = readAgentPodPins(configPath, state);
+    this.stateDir = state;
     const keyPath = join(state, 'agentpod-control-key');
     try {
       const fd = openSync(keyPath, 'wx', 0o600);
@@ -112,6 +150,9 @@ export class AgentPodAuthority {
     }
     this.key = privateBytes(keyPath);
     if (this.key.length !== 32) throw Error('Invalid AgentPod control key');
+    store.db.exec(
+      'CREATE TABLE IF NOT EXISTS agentpod_approval_rules(admission_id TEXT NOT NULL,rule_id TEXT NOT NULL,scope TEXT NOT NULL,set_by TEXT NOT NULL,revoked_at TEXT,PRIMARY KEY(admission_id,rule_id))',
+    );
     store.agentpodAuthorityCheck = (session) => this.assert(this.bySession(session));
     store.requireAgentPodAuthority = true;
   }
@@ -158,6 +199,19 @@ export class AgentPodAuthority {
       );
     return remaining;
   }
+  /** The session's pinned approval rules that no renewal has revoked. */
+  approvalRules(session: string): ApprovalRule[] {
+    return this.store.db
+      .prepare(
+        'SELECT r.rule_id AS id,r.scope,r.set_by FROM agentpod_approval_rules r JOIN agentpod_admissions a ON a.id=r.admission_id WHERE a.session_id=? AND r.revoked_at IS NULL ORDER BY r.rule_id',
+      )
+      .all(session)
+      .map((r) => ({
+        id: String(r.id),
+        scope: 'workspace-write' as const,
+        set_by: String(r.set_by),
+      }));
+  }
   private checked(input: unknown): AgentPodBinding {
     const b = agentpodBinding(input);
     for (const k of Object.keys(this.pins) as (keyof AgentPodPins)[])
@@ -247,12 +301,30 @@ export class AgentPodAuthority {
     this.assert(row);
     return { session_id: row.session_id, binding: JSON.parse(row.binding) };
   }
-  admit(input: unknown, request: string) {
+  /**
+   * `continueFrom` names an earlier interactive admission (its hub session id) whose conversation
+   * this new admission carries on. The earlier execution stays revoked: the new admission gets a
+   * NEW session, its own lease and its own authority, seeded with a branch of the old Pi
+   * transcript and its entries. Only a revoked, stopped and reconciled interactive admission for
+   * the same organization, station, occupant and workspace can be continued, and only once.
+   */
+  admit(input: unknown, request: string, continueFrom?: string, rulesInput?: unknown) {
     const b = this.checked(input);
+    const rules = approvalRules(rulesInput);
+    if (
+      continueFrom !== undefined &&
+      (typeof continueFrom !== 'string' || !continueFrom || continueFrom.length > 128)
+    )
+      throw new ServiceError('invalid_continuation', 'continue_from must be a hub session id', 400);
     const admitted = this.store.request(
       'agentpod-node',
       request,
-      { kind: 'admit', binding: b },
+      {
+        kind: 'admit',
+        binding: b,
+        ...(continueFrom === undefined ? {} : { continue_from: continueFrom }),
+        ...(rules.length ? { approval_rules: rules } : {}),
+      },
       () => {
         const old = this.store.db
           .prepare('SELECT id FROM agentpod_admissions WHERE hub_session_id=?')
@@ -303,17 +375,56 @@ export class AgentPodAuthority {
             'INSERT INTO agentpod_station_epochs VALUES (?,?,?) ON CONFLICT(station_id) DO UPDATE SET occupancy_epoch=excluded.occupancy_epoch,principal_id=excluded.principal_id',
           )
           .run(b.station_id, b.occupancy_epoch, b.principal_id);
+        const prior = continueFrom === undefined ? undefined : this.continuable(b, continueFrom);
         const session = randomUUID(),
           id = randomUUID();
-        this.store.db
-          .prepare('INSERT INTO sessions(id,cwd,pi_session_id) VALUES (?,?,?)')
-          .run(session, b.workspace, session);
-        this.store.event(
-          session,
-          'session.created',
-          { cwd: b.workspace, authority: 'agentpod-v1' },
-          request,
-        );
+        if (prior) {
+          const source = this.store.session(prior.session_id);
+          const file = source.pi_session_file
+            ? (() => {
+                const dir = join(this.stateDir, 'workers', session, 'sessions');
+                mkdirSync(dir, { recursive: true, mode: 0o700 });
+                return forkPiSession(source.pi_session_file, source.cwd, dir, session);
+              })()
+            : null;
+          this.store.db
+            .prepare(
+              'INSERT INTO sessions(id,cwd,pi_session_id,pi_session_file,pi_cursor,pi_leaf) VALUES (?,?,?,?,?,?)',
+            )
+            .run(session, b.workspace, session, file, source.pi_cursor, source.pi_leaf);
+          this.store.event(
+            session,
+            'session.created',
+            { cwd: b.workspace, authority: 'agentpod-v1', forked_from: prior.session_id },
+            request,
+          );
+          this.store.db
+            .prepare(
+              'INSERT INTO pi_entries SELECT ?,entry_id,payload FROM pi_entries WHERE session_id=?',
+            )
+            .run(session, prior.session_id);
+          this.store.event(
+            session,
+            'session.forked',
+            {
+              parent: prior.session_id,
+              parent_revision: source.revision,
+              leaf: source.pi_leaf,
+              cursor: source.pi_cursor,
+            },
+            request,
+          );
+        } else {
+          this.store.db
+            .prepare('INSERT INTO sessions(id,cwd,pi_session_id) VALUES (?,?,?)')
+            .run(session, b.workspace, session);
+          this.store.event(
+            session,
+            'session.created',
+            { cwd: b.workspace, authority: 'agentpod-v1' },
+            request,
+          );
+        }
         this.store.db
           .prepare(
             'INSERT INTO agentpod_admissions(id,session_id,hub_session_id,run_key,binding,digest,pins_digest,expires_at) VALUES (?,?,?,?,?,?,?,?)',
@@ -328,10 +439,20 @@ export class AgentPodAuthority {
             digest(this.pins),
             Date.now() + AGENTPOD_LEASE_MS,
           );
+        // The agent's standing rules, pinned for this run; a renewal may add or revoke one.
+        for (const r of rules)
+          this.store.db
+            .prepare('INSERT INTO agentpod_approval_rules VALUES (?,?,?,?,NULL)')
+            .run(id, r.id, r.scope, r.set_by);
         this.store.event(
           session,
           'agentpod.admitted',
-          { admission_id: id, binding_digest: digest(b), binding: b },
+          {
+            admission_id: id,
+            binding_digest: digest(b),
+            binding: b,
+            ...(prior ? { continued_from: continueFrom, continued_admission: prior.id } : {}),
+          },
           request,
         );
         return { admission_id: id };
@@ -340,13 +461,14 @@ export class AgentPodAuthority {
     const row = this.row(admitted.admission_id);
     return { ...this.status(row), token: this.token(row.id) };
   }
-  renew(input: unknown, request: string, sequence: number) {
+  renew(input: unknown, request: string, sequence: number, rulesInput?: unknown) {
     const b = this.checked(input);
     integer(sequence, 'lease_sequence');
+    const rules = approvalRules(rulesInput);
     return this.store.request(
       'agentpod-node',
       request,
-      { kind: 'renew', binding: b, sequence },
+      { kind: 'renew', binding: b, sequence, ...(rules.length ? { approval_rules: rules } : {}) },
       () => {
         const row = this.bound(b);
         if (
@@ -375,6 +497,44 @@ export class AgentPodAuthority {
             performance.now() + AGENTPOD_LEASE_MS,
             row.id,
           );
+        // Revocation is immediate: a pinned rule the hub no longer lists ends now, for good.
+        const listed = new Set(rules.map((r) => r.id));
+        for (const pinned of this.store.db
+          .prepare(
+            'SELECT rule_id FROM agentpod_approval_rules WHERE admission_id=? AND revoked_at IS NULL',
+          )
+          .all(row.id)) {
+          if (listed.has(String(pinned.rule_id))) continue;
+          this.store.db
+            .prepare(
+              'UPDATE agentpod_approval_rules SET revoked_at=? WHERE admission_id=? AND rule_id=?',
+            )
+            .run(new Date().toISOString(), row.id, String(pinned.rule_id));
+          this.store.event(
+            row.session_id,
+            'approval_rule.revoked',
+            { admission_id: row.id, rule_id: pinned.rule_id },
+            request,
+          );
+        }
+        // A rule the hub newly lists joins the run now (operator ruling 2026-10-28: a person who
+        // chose "Always allow" mid-run is not asked again). One this run already holds, or held
+        // and lost to revocation, is left as it is: revocation stays final for the run.
+        for (const r of rules) {
+          const known = this.store.db
+            .prepare('SELECT 1 FROM agentpod_approval_rules WHERE admission_id=? AND rule_id=?')
+            .get(row.id, r.id);
+          if (known) continue;
+          this.store.db
+            .prepare('INSERT INTO agentpod_approval_rules VALUES (?,?,?,?,NULL)')
+            .run(row.id, r.id, r.scope, r.set_by);
+          this.store.event(
+            row.session_id,
+            'approval_rule.added',
+            { admission_id: row.id, rule_id: r.id, scope: r.scope, set_by: r.set_by },
+            request,
+          );
+        }
         this.store.event(
           row.session_id,
           'agentpod.renewed',
@@ -385,6 +545,59 @@ export class AgentPodAuthority {
       },
     );
   }
+  /** The earlier admission a new interactive admission may continue, or a refusal. */
+  private continuable(b: AgentPodBinding, continueFrom: string): Admission {
+    if (b.run.source !== 'agentpod')
+      throw new ServiceError(
+        'continuation_refused',
+        'Only an interactive admission can continue an earlier conversation',
+      );
+    const row = this.store.db
+      .prepare('SELECT id FROM agentpod_admissions WHERE hub_session_id=?')
+      .get(continueFrom);
+    if (!row)
+      throw new ServiceError(
+        'admission_not_found',
+        'The session to continue has no admission',
+        404,
+      );
+    const prior = this.row(String(row.id));
+    const before = JSON.parse(prior.binding) as AgentPodBinding;
+    if (
+      prior.binding !== canonical(before) ||
+      prior.digest !== digest(before) ||
+      before.run.source !== 'agentpod' ||
+      before.organization_id !== b.organization_id ||
+      before.station_id !== b.station_id ||
+      before.principal_id !== b.principal_id ||
+      before.workspace !== b.workspace ||
+      before.hub_session_id === b.hub_session_id
+    )
+      throw new ServiceError(
+        'continuation_refused',
+        'Only the same station, occupant and workspace can continue this conversation',
+      );
+    const status = this.status(prior);
+    if (
+      prior.state !== 'revoked' ||
+      !status.revoked ||
+      !status.owned_execution_stopped ||
+      status.unresolved_operations.length
+    )
+      throw new ServiceError(
+        'execution_unconfirmed',
+        'The conversation to continue must be revoked, stopped and reconciled first',
+      );
+    if (
+      this.store.db
+        .prepare(
+          "SELECT 1 FROM events WHERE kind='agentpod.admitted' AND json_extract(payload,'$.continued_admission')=? LIMIT 1",
+        )
+        .get(prior.id)
+    )
+      throw new ServiceError('already_continued', 'This conversation was already continued');
+    return prior;
+  }
   revoke(input: unknown, request: string, reason: string) {
     const b = this.checked(input);
     this.store.request('agentpod-node', request, { kind: 'revoke', binding: b, reason }, () => {
@@ -482,9 +695,15 @@ export class AgentPodAuthority {
       this.assert(row);
       authorized = true;
     } catch {}
+    const continued = this.store.db
+      .prepare(
+        "SELECT json_extract(payload,'$.continued_from') AS source FROM events WHERE session_id=? AND kind='agentpod.admitted' LIMIT 1",
+      )
+      .get(row.session_id) as { source: string | null } | undefined;
     return {
       admission_id: row.id,
       session_id: row.session_id,
+      continued_from: continued?.source ?? null,
       binding: JSON.parse(row.binding) as AgentPodBinding,
       binding_digest: row.digest,
       lease_sequence: row.lease_sequence,

package/src/agentpod-default-config.ts

@@ -0,0 +1,16 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * The AgentPod pins a node operator drops for this user, used when
+ * `service start` names no --agentpod-config. Without it a daemon an AgentPod
+ * node expects to bind starts unbound and the node never detects a station.
+ */
+export function defaultAgentPodConfig(
+  env: NodeJS.ProcessEnv,
+  exists: (path: string) => boolean,
+): string | undefined {
+  const base = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), '.config');
+  const path = join(base, 'salaam', 'agentpod-pins.json');
+  return exists(path) ? path : undefined;
+}

package/src/agentpod-work-decision-protocol.ts

@@ -12,7 +12,27 @@ export interface WorkDecision {
   approval_revision: number;
   expires_at: number;
   question: string;
-  options: [{ id: 'approve'; title: string }, { id: 'deny'; title: string }];
+  /** Readable approvals: what is being approved, as structured fields. */
+  detail?: WorkDecisionDetail;
+  /** approve, [approve-run], [always], deny, in that order. "Always allow" (operator ruling
+   * 2026-10-28) is a workspace owner's or admin's choice only: `requires` says so to the board, and
+   * the hub checks the answerer's role and sets the standing rule before it forwards the answer. */
+  options: WorkDecisionOption[];
+}
+export type WorkDecisionOption =
+  | { id: 'approve' | 'approve-run' | 'deny'; title: string }
+  | { id: 'always'; title: string; requires: 'workspace-admin' };
+export interface WorkDecisionDetail {
+  version: 1;
+  summary: string;
+  reason: string | null;
+  files: {
+    path: string;
+    change: 'create' | 'edit' | 'delete';
+    bytes: number | null;
+    preview: string | null;
+  }[];
+  digest: string;
 }
 export interface WorkDecisionAnswer {
   version: 1;
@@ -20,7 +40,7 @@ export interface WorkDecisionAnswer {
   decision: WorkDecision;
   decision_digest: string;
   elicitation_id: string;
-  option_id: 'approve' | 'deny';
+  option_id: 'approve' | 'approve-run' | 'always' | 'deny';
   answered_by: string;
   answered_at: string;
 }
@@ -57,7 +77,9 @@ export function workDecision(value: unknown): WorkDecision {
     'expires_at',
     'question',
     'options',
+    ...('detail' in v ? ['detail'] : []),
   ]);
+  if ('detail' in v) workDecisionDetail(v.detail);
   if (
     v.version !== 1 ||
     !['request_id', 'work_request_id', 'task_id', 'operation_id', 'approval_id'].every((k) =>
@@ -71,13 +93,25 @@ export function workDecision(value: unknown): WorkDecision {
     ) ||
     !text(v.question, 8192) ||
     !Array.isArray(v.options) ||
-    v.options.length !== 2
+    ![2, 3, 4].includes(v.options.length)
+  )
+    fail();
+  // approve, [approve-run], [always], deny. Nothing else, in that order.
+  const ids = v.options.map((o) => String(object(o).id));
+  if (
+    ![
+      'approve,deny',
+      'approve,approve-run,deny',
+      'approve,always,deny',
+      'approve,approve-run,always,deny',
+    ].includes(ids.join(','))
   )
     fail();
-  for (let i = 0; i < 2; i++) {
-    const opt = object(v.options[i]);
-    keys(opt, ['id', 'title']);
-    if (opt.id !== ['approve', 'deny'][i] || !text(opt.title, 256)) fail();
+  for (const value of v.options) {
+    const opt = object(value);
+    keys(opt, opt.id === 'always' ? ['id', 'title', 'requires'] : ['id', 'title']);
+    if (!text(opt.title, 256) || (opt.id === 'always' && opt.requires !== 'workspace-admin'))
+      fail();
   }
   return v as unknown as WorkDecision;
 }
@@ -101,7 +135,7 @@ export function workDecisionAnswer(value: unknown): WorkDecisionAnswer {
     !/^[a-f0-9]{64}$/.test(v.decision_digest) ||
     !text(v.elicitation_id, 128) ||
     !/^elc_[A-Za-z0-9]{6,}$/.test(v.elicitation_id) ||
-    !['approve', 'deny'].includes(String(v.option_id)) ||
+    !['approve', 'approve-run', 'always', 'deny'].includes(String(v.option_id)) ||
     !text(v.answered_by, 128) ||
     typeof v.answered_at !== 'string' ||
     !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?Z$/.test(v.answered_at) ||
@@ -111,3 +145,30 @@ export function workDecisionAnswer(value: unknown): WorkDecisionAnswer {
     fail();
   return v as unknown as WorkDecisionAnswer;
 }
+
+function workDecisionDetail(value: unknown): WorkDecisionDetail {
+  const d = object(value);
+  keys(d, ['version', 'summary', 'reason', 'files', 'digest']);
+  if (
+    d.version !== 1 ||
+    !text(d.summary, 200) ||
+    (d.reason !== null && !text(d.reason, 300)) ||
+    typeof d.digest !== 'string' ||
+    !/^[a-f0-9]{64}$/.test(d.digest) ||
+    !Array.isArray(d.files) ||
+    d.files.length > 16
+  )
+    fail();
+  for (const f of d.files as unknown[]) {
+    const file = object(f);
+    keys(file, ['path', 'change', 'bytes', 'preview']);
+    if (
+      !text(file.path, 512) ||
+      !['create', 'edit', 'delete'].includes(String(file.change)) ||
+      (file.bytes !== null && (!Number.isSafeInteger(file.bytes) || Number(file.bytes) < 0)) ||
+      (file.preview !== null && (typeof file.preview !== 'string' || file.preview.length > 1200))
+    )
+      fail();
+  }
+  return d as unknown as WorkDecisionDetail;
+}

package/src/agentpod-work-decisions.ts

@@ -2,14 +2,43 @@ import { randomUUID } from 'node:crypto';
 import type { AgentPodWork } from './agentpod-work.js';
 import type { ManagedWork } from './managed.js';
 import { canonical, digest, ServiceError } from './protocol.js';
-import { workDecisionAnswer, type WorkDecision } from './agentpod-work-decision-protocol.js';
+import { type RunGrants, runGrantCovers, runGrantPrefix } from './run-grants.js';
+import {
+  workDecisionAnswer,
+  type WorkDecision,
+  type WorkDecisionDetail,
+} from './agentpod-work-decision-protocol.js';
 /** Private authenticated Hub control only. Answers choose an existing approval;
  * they never execute an operation or supply a second effect grant. */
 export class AgentPodWorkDecisions {
   constructor(
     readonly work: AgentPodWork,
     readonly managed: ManagedWork,
+    readonly grants?: RunGrants,
   ) {}
+  /** The run directory a grant for this operation would cover, when it is a covered write. */
+  private grantable(binding: unknown, op: { kind: string; value: string }): string | null {
+    if (!this.grants || op.kind !== 'workspace') return null;
+    const run = (binding as { run?: { id?: unknown } } | null)?.run;
+    const prefix = runGrantPrefix(typeof run?.id === 'string' ? run.id : '');
+    let args: Record<string, unknown> = {};
+    try {
+      args = JSON.parse(op.value) as Record<string, unknown>;
+    } catch {
+      return null;
+    }
+    return prefix && runGrantCovers(prefix, args) ? prefix : null;
+  }
+  /** "Always allow" covers exactly what the standing workspace-write rule answers: a workspace
+   * write anywhere in the workspace, never a delete or a hidden path. */
+  private alwaysAllowable(op: { kind: string; value: string }): boolean {
+    if (op.kind !== 'workspace') return false;
+    try {
+      return runGrantCovers('', JSON.parse(op.value) as Record<string, unknown>);
+    } catch {
+      return false;
+    }
+  }
   private owner(binding: unknown) {
     const root = this.work.authority.inspect(binding);
     const row = this.work.store.db
@@ -51,10 +80,23 @@ export class AgentPodWorkDecisions {
             version: 1,
             request_id: randomUUID(),
             ...identity,
-            question: 'Approve this exact operation? ' + op.kind + ' ' + op.action_key,
+            question: approvalDetail(op).summary + '?',
+            detail: approvalDetail(op),
             options: [
-              { id: 'approve', title: 'Approve once' },
-              { id: 'deny', title: 'Deny' },
+              { id: 'approve' as const, title: 'Approve once' },
+              ...(this.grantable(root.binding, op)
+                ? [{ id: 'approve-run' as const, title: 'Approve for this run' }]
+                : []),
+              ...(this.alwaysAllowable(op)
+                ? [
+                    {
+                      id: 'always' as const,
+                      title: 'Always allow this agent to write in its workspace',
+                      requires: 'workspace-admin' as const,
+                    },
+                  ]
+                : []),
+              { id: 'deny' as const, title: 'Deny' },
             ],
           }),
         );
@@ -97,13 +139,45 @@ export class AgentPodWorkDecisions {
           approval.expires_at !== offered.expires_at
         )
           throw new ServiceError('approval_mismatch', 'Approval ownership changed');
+        // "Approve for this run" must have been offered, and still be grantable, to be chosen.
+        const prefix =
+          answer.option_id === 'approve-run'
+            ? this.grantable(root.binding, this.managed.operation(offered.operation_id))
+            : null;
+        if (
+          answer.option_id === 'approve-run' &&
+          (!prefix || !offered.options.some((o) => o.id === 'approve-run'))
+        )
+          throw new ServiceError('approval_mismatch', 'This approval cannot cover the run');
+        // "Always allow" approves this write; the standing rule is the hub's, set before it forwards.
+        if (
+          answer.option_id === 'always' &&
+          (!offered.options.some((o) => o.id === 'always') ||
+            !this.alwaysAllowable(this.managed.operation(offered.operation_id)))
+        )
+          throw new ServiceError(
+            'approval_mismatch',
+            'Always allow was not offered for this write',
+          );
         this.managed.decide(
           offered.approval_id,
           answer.request_id,
           offered.approval_revision,
           offered.operation_digest,
-          answer.option_id,
+          answer.option_id === 'deny' ? 'deny' : 'approve',
         );
+        const grant =
+          answer.option_id === 'approve-run'
+            ? this.grants!.createInTransaction({
+                session_id: root.session_id,
+                task_id: task.id,
+                plan_revision: offered.plan_revision,
+                binding_digest: offered.binding_digest,
+                path_prefix: prefix!,
+                approval_id: offered.approval_id,
+                granted_by: answer.answered_by,
+              })
+            : null;
         this.work.store.execution.assert(root.session_id);
         return {
           version: 1 as const,
@@ -111,8 +185,52 @@ export class AgentPodWorkDecisions {
           decision_digest: answer.decision_digest,
           approval_id: offered.approval_id,
           decision: answer.option_id,
+          ...(grant ? { grant_id: grant.id } : {}),
         };
       },
     );
   }
 }
+
+/** Readable approvals: what a person approves, from the operation's own canonical arguments only.
+ * A workspace write names its file, the change, its size, a short preview and the agent's one-line
+ * reason; anything else names its kind and target. The digest still binds the exact operation. */
+export function approvalDetail(op: {
+  kind: string;
+  action_key: string;
+  target: string;
+  value: string;
+  operation_digest: string;
+}): WorkDecisionDetail {
+  const base = { version: 1 as const, reason: null, files: [], digest: op.operation_digest };
+  if (op.kind === 'review') return { ...base, summary: 'Accept this step for review' };
+  if (op.kind !== 'workspace')
+    return { ...base, summary: ('Run ' + op.kind + ' ' + op.target).slice(0, 200) };
+  let args: Record<string, unknown> = {};
+  try {
+    args = JSON.parse(op.value) as Record<string, unknown>;
+  } catch {
+    /* not a patch: the generic form below */
+  }
+  const path = typeof args.path === 'string' ? args.path : op.target.replace(/^station:/, '');
+  const content = typeof args.content === 'string' ? args.content : null;
+  const change = args.content === null ? 'delete' : args.expected_hash === null ? 'create' : 'edit';
+  const verb = { create: 'Create', edit: 'Edit', delete: 'Delete' }[change];
+  const reason =
+    typeof args.reason === 'string' && args.reason.trim()
+      ? args.reason.replace(/\s+/g, ' ').trim().slice(0, 300)
+      : null;
+  return {
+    ...base,
+    summary: (verb + ' ' + path + ' in the workspace').slice(0, 200),
+    reason,
+    files: [
+      {
+        path: path.slice(0, 512),
+        change,
+        bytes: content === null ? null : Buffer.byteLength(content),
+        preview: content === null ? null : content.slice(0, 1200),
+      },
+    ],
+  };
+}