@nanobpm/nano-workforce 0.145.1 → 0.147.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.147.0](https://github.com/nanobpm/nano-workforce/compare/v0.146.0...v0.147.0) (2026-08-26)
+
+### Features
+
+* **cockpit:** rich tool/diff cards + permission prompt mounted into the typed replay path ([#561](https://github.com/nanobpm/nano-workforce/issues/561)) ([4bd04a0](https://github.com/nanobpm/nano-workforce/commit/4bd04a06f12569e418566cb47b8a7bbf053cdb20)), closes [#559](https://github.com/nanobpm/nano-workforce/issues/559) [#setMode](https://github.com/nanobpm/nano-workforce/issues/setMode) [#structuredRegion](https://github.com/nanobpm/nano-workforce/issues/structuredRegion)
+
+## [0.146.0](https://github.com/nanobpm/nano-workforce/compare/v0.145.1...v0.146.0) (2026-08-26)
+
+### Features
+
+* **agentic:** add a permission transcript-event kind (request + resolution) ([#560](https://github.com/nanobpm/nano-workforce/issues/560)) ([722bb96](https://github.com/nanobpm/nano-workforce/commit/722bb962b24c85faf585e598b905bf67a43040d4)), closes [#559](https://github.com/nanobpm/nano-workforce/issues/559)
+
 ## [0.145.1](https://github.com/nanobpm/nano-workforce/compare/v0.145.0...v0.145.1) (2026-08-26)
 
 ### Bug Fixes

package/app/agentic/cockpit/index.ts

@@ -36,6 +36,7 @@ export {
 export {
   type DerivedTranscriptDom,
   deriveTranscript,
+  type RenderDerivedTranscriptOptions,
   renderDerivedTranscript,
 } from "./transcript-derive.ts";
 export {

package/app/agentic/cockpit/supply-boot.test.ts

@@ -7,8 +7,10 @@ import assert from "node:assert/strict";
 import { test } from "node:test";
 
 import { FakeDocument, FakeElement, FakeSocket } from "../../../test/agentic-cockpit-doubles.ts";
+import { TRANSCRIPT_EVENT_MARKER, TRANSCRIPT_EVENT_VERSION } from "../transcript-events.ts";
 import { bootSupplyCockpit, type SupplyCockpitEnv } from "./supply-boot.ts";
 import type { SupplyReport } from "./supply-view.ts";
+import type { TranscriptDataReport } from "./transcript-render.ts";
 
 const flush = () => new Promise<void>((resolve) => setImmediate(resolve));
 
@@ -358,3 +360,95 @@ test("a drill whose terminal build throws resets the panel to idle instead of le
   assert.equal(cockpit.currentMode, "live");
   assert.equal(cockpit.currentStream, "wk-a");
 });
+
+// A transcript envelope (marker + kind + fields), matching the one event grammar the fold parses.
+function env(kind: string, extra: Record<string, unknown> = {}): string {
+  return JSON.stringify({ [TRANSCRIPT_EVENT_MARKER]: TRANSCRIPT_EVENT_VERSION, kind, ...extra });
+}
+
+// A captured transcript carrying a pending ESCALATE permission request, for the structured replay path.
+function permissionTranscript(stream: string): TranscriptDataReport {
+  const chunks = [
+    env("turn", { index: 0 }),
+    env("message", { role: "assistant", text: "I need to run a command" }),
+    env("permission", {
+      phase: "request",
+      callId: "perm-1",
+      policy: "escalate",
+      title: "Run `rm -rf build`?",
+      options: [
+        { optionId: "allow", name: "Allow", kind: "allow-once" },
+        { optionId: "deny", name: "Deny", kind: "reject-once" },
+      ],
+    }),
+  ];
+  return { stream, from: 0, gap: false, nextOffset: chunks.length, entries: chunks.map((chunk, offset) => ({ offset, chunk })) };
+}
+
+// A rig whose replay endpoints (list + per-session bytes) are wired, plus an optional permission hook.
+function replayRig(onPermissionResolve?: SupplyCockpitEnv["onPermissionResolve"]): {
+  readonly env: SupplyCockpitEnv;
+  readonly host: FakeElement;
+  readonly data: TranscriptDataReport;
+} {
+  const r = rig();
+  const data = permissionTranscript("job:done");
+  const env: SupplyCockpitEnv = {
+    ...r.env,
+    fetchTranscripts: () => Promise.resolve({ count: 0, transcripts: [] }),
+    fetchTranscript: () => Promise.resolve(data),
+    ...(onPermissionResolve !== undefined ? { onPermissionResolve } : {}),
+  };
+  return { env, host: r.host, data };
+}
+
+test("replay MOUNTS the structured derived view beside the byte replay (typed boot/replay path)", async () => {
+  const { env, host } = replayRig();
+  const cockpit = bootSupplyCockpit(env);
+  await cockpit.replay("job:done");
+
+  // The dedicated structured region exists and now holds the derived view (the byte terminal replay,
+  // asserted elsewhere, is untouched — this is additive beside it).
+  const region = host.byData("structured", "region")[0];
+  assert.ok(region !== undefined, "the structured region is present");
+  assert.equal(region?.byClass("cockpit-transcript-derived").length, 1, "the derived structured view is mounted");
+  assert.equal(host.byData("permission", "request").length, 1, "the permission prompt is rendered in the structured view");
+});
+
+test("a SupplyCockpitEnv.onPermissionResolve hook is threaded into the structured render so a click reaches it", async () => {
+  const resolutions: Array<{ callId: string; optionId: string; allowed: boolean }> = [];
+  const { env, host } = replayRig((resolution) => resolutions.push(resolution));
+  const cockpit = bootSupplyCockpit(env);
+  await cockpit.replay("job:done");
+
+  const allow = host.byClass("cockpit-transcript-permission-option").find((b) => b.getAttribute("data-option-id") === "allow");
+  assert.ok(allow !== undefined, "the Allow button rendered");
+  allow?.dispatch("click");
+  assert.deepEqual(resolutions, [{ callId: "perm-1", optionId: "allow", allowed: true }]);
+});
+
+test("the structured view renders even without an onPermissionResolve hook (buttons are inert, no throw)", async () => {
+  const { env, host } = replayRig();
+  const cockpit = bootSupplyCockpit(env);
+  await cockpit.replay("job:done");
+  const allow = host.byClass("cockpit-transcript-permission-option").find((b) => b.getAttribute("data-option-id") === "allow");
+  assert.ok(allow !== undefined, "the Allow button rendered without a hook");
+  allow?.dispatch("click"); // no handler wired — must not throw
+});
+
+test("switching from replay to a LIVE drill CLEARS the stale structured derived view (no wrong-callId clicks)", async () => {
+  const { env, host } = replayRig();
+  const cockpit = bootSupplyCockpit(env);
+  await cockpit.replay("job:done");
+  // The structured region is populated with the derived view + pending permission prompt.
+  assert.equal(host.byData("permission", "request").length, 1, "the permission prompt is mounted on replay");
+
+  // Drilling into a live stream must tear the stale structured view down — leaving a clickable permission
+  // prompt over a live terminal risks an operator action against the wrong callId.
+  cockpit.drill("wk-a");
+  assert.equal(cockpit.currentMode, "live");
+  const region = host.byData("structured", "region")[0];
+  assert.ok(region !== undefined, "the structured region element persists (it is cleared, not removed)");
+  assert.equal(region?.byClass("cockpit-transcript-derived").length, 0, "the derived structured view is cleared on live drill");
+  assert.equal(host.byData("permission", "request").length, 0, "the stale permission prompt is gone in live mode");
+});

package/app/agentic/cockpit/supply-boot.ts

@@ -32,6 +32,7 @@ import type { CockpitRoute } from "./cockpit-route.ts";
 import { renderSupply } from "./supply-render.ts";
 import type { SupplyReport, SupplyView } from "./supply-view.ts";
 import { supplyView } from "./supply-view.ts";
+import { type RenderDerivedTranscriptOptions, renderDerivedTranscript } from "./transcript-derive.ts";
 import { renderTranscripts, replayTranscript, type TranscriptDataReport } from "./transcript-render.ts";
 import type { TranscriptListReport } from "./transcript-view.ts";
 import { transcriptsView } from "./transcript-view.ts";
@@ -88,6 +89,16 @@ export interface SupplyCockpitEnv {
   readonly pastFetchTimeoutMs?: number;
   /** Notified of a fetch/render/relay error (the poll keeps going). */
   readonly onError?: (err: unknown) => void;
+  /**
+   * The seam the wave-2 escalation bridge attaches to: threaded into the STRUCTURED replay view's
+   * {@link RenderDerivedTranscriptOptions.onPermissionResolve}, so a pending escalate-permission
+   * prompt's Allow/Deny click reaches the bridge. Optional (default `undefined`): the structured view
+   * still renders, its prompt buttons just have no handler. NOTE (runtime-layer truth): this is the
+   * TYPED boot/replay path exercised by unit tests + the published package, NOT the operator's live
+   * browser cockpit (`pages/cockpit/mount.js`, a hand-maintained drift twin) — surfacing the prompt
+   * there is a separate follow-up.
+   */
+  readonly onPermissionResolve?: RenderDerivedTranscriptOptions["onPermissionResolve"];
 }
 
 /** The running supply cockpit; dispose to stop polling and tear down the terminal. */
@@ -132,6 +143,10 @@ class SupplyCockpit implements SupplyCockpitHandle {
   readonly #env: SupplyCockpitEnv;
   readonly #listRegion: ElementLike;
   readonly #pastRegion: ElementLike | undefined;
+  // A dedicated volatile region the STRUCTURED derived view (messages, rich tool/diff cards, permission
+  // prompts) is mounted into on a replay — beside, and additive to, the byte-level terminal replay
+  // (which is left untouched). Present only when the transcript read endpoints are wired.
+  readonly #structuredRegion: ElementLike | undefined;
   readonly #terminalHost: ElementLike;
   readonly #terminalTitle: ElementLike;
   readonly #terminalNote: ElementLike;
@@ -247,6 +262,14 @@ class SupplyCockpit implements SupplyCockpitHandle {
     this.#terminalHost.className = "cockpit-terminal-host";
     this.#terminalHost.setAttribute("data-terminal", "host");
     this.#terminalPanel.appendChild(this.#terminalHost);
+    // The STRUCTURED derived view is mounted here on a replay, additive beside the byte terminal above.
+    // Only exists when the transcript read endpoints are wired (same pairing as the past-sessions list).
+    if (env.fetchTranscripts !== undefined) {
+      this.#structuredRegion = env.doc.createElement("div");
+      this.#structuredRegion.className = "cockpit-structured-region";
+      this.#structuredRegion.setAttribute("data-structured", "region");
+      this.#terminalPanel.appendChild(this.#structuredRegion);
+    }
     // A status note under the terminal, shown while a LIVE drill has connected but no output has
     // arrived yet (a quiet job between frames): without it the panel is an indistinguishable blank
     // black rectangle, so the operator can't tell "connected, waiting" from "broken". Cleared the
@@ -284,6 +307,11 @@ class SupplyCockpit implements SupplyCockpitHandle {
     // Any mode change replaces what's behind the panel, so the prior "waiting for output" note is
     // stale — clear it. A live drill re-arms it (below) once its fresh terminal is mounted.
     this.#setNote(undefined);
+    // The STRUCTURED derived view is only valid alongside a replay. Any non-replay mode (a live drill
+    // or idle) must clear it, or a stale derived transcript / pending permission prompt would linger —
+    // visible and CLICKABLE — over the live terminal, risking an operator action against the wrong
+    // callId. A replay re-mounts it (in replay(), after this #setMode("replay", …)).
+    if (mode !== "replay") this.#structuredRegion?.replaceChildren();
   }
 
   /** Show (or clear) the terminal status note — the "connected, waiting for output" affordance. */
@@ -577,6 +605,14 @@ class SupplyCockpit implements SupplyCockpitHandle {
       const session = new TerminalSession({ stream, sink, send: () => {}, from: data.from });
       replayTranscript(session, data);
       this.#setMode("replay", stream);
+      // Additively mount the STRUCTURED derived view beside the byte replay above (the byte replay is
+      // left untouched). The env's onPermissionResolve seam is threaded into the render so a pending
+      // escalate-permission prompt's Allow/Deny click reaches whatever the bridge wires there.
+      if (this.#structuredRegion !== undefined) {
+        renderDerivedTranscript(this.#structuredRegion, this.#env.doc, data, {
+          onPermissionResolve: this.#env.onPermissionResolve,
+        });
+      }
       // Re-render the past list so the just-selected session shows as active (best-effort).
       void this.#refreshPast(this.#route.kind === "worker" ? this.#route.instance : undefined);
     } catch (err) {

package/app/agentic/cockpit/transcript-derive.test.ts

@@ -4,7 +4,7 @@
 // cards, per-turn boundaries), and that raw chunks are preserved in the fidelity footer — the byte
 // replay is not lost. It renders into the in-memory DOM double, no browser.
 import { test } from "node:test";
-import { assertEquals } from "#test-assert";
+import { assert, assertEquals, assertStringIncludes } from "#test-assert";
 import { FakeDocument, FakeElement } from "../../../test/agentic-cockpit-doubles.ts";
 import { TRANSCRIPT_EVENT_MARKER, TRANSCRIPT_EVENT_VERSION } from "../transcript-events.ts";
 import { deriveTranscript, renderDerivedTranscript } from "./transcript-derive.ts";
@@ -76,3 +76,184 @@ test("renderDerivedTranscript shows an empty state for an all-raw (unstructured)
   assertEquals(host.byData("empty", "true").length, 1);
   assertEquals(host.byData("turn-count", "0").length, 1);
 });
+
+// A minimal single-page report of the given entries (offsets assigned in order).
+function page(chunks: readonly string[], stream = "job:x"): TranscriptDataReport {
+  return { stream, from: 0, gap: false, nextOffset: chunks.length, entries: chunks.map((chunk, offset) => ({ offset, chunk })) };
+}
+
+test("a tool card renders its args and result content", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("tool-call", { name: "read", callId: "c1", args: { path: "README.md" } }),
+      env("tool-result", { callId: "c1", ok: true, content: "file contents here" }),
+    ]),
+  );
+  const card = host.byData("tool", "read")[0];
+  assertEquals(card?.getAttribute("data-status"), "ok");
+  assertEquals(card?.getAttribute("data-tool-kind"), undefined); // not a diff
+  const argsEl = host.byData("tool-args", "true")[0];
+  assertStringIncludes(argsEl?.textContent ?? "", "README.md");
+  const resultEl = host.byData("tool-result", "true")[0];
+  assertEquals(resultEl?.textContent, "file contents here");
+});
+
+test("a diff tool renders a cockpit-transcript-diff block with per-line add/del/ctx markers", () => {
+  const host = new FakeElement("div");
+  const unified = "--- a/foo.txt\n+++ b/foo.txt\n@@ -1,2 +1,2 @@\n-old line\n+new line\n unchanged\n";
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("tool-call", { name: "edit", callId: "d1" }),
+      env("tool-result", { callId: "d1", ok: true, content: unified }),
+    ]),
+  );
+  const card = host.byData("tool", "edit")[0];
+  assertEquals(card?.getAttribute("data-tool-kind"), "diff");
+  assertEquals(host.byClass("cockpit-transcript-diff").length, 1);
+  assertEquals(host.byData("diff-line", "add").length, 1);
+  assertEquals(host.byData("diff-line", "del").length, 1);
+  assert(host.byData("diff-line", "ctx").length >= 1, "the hunk/header/context lines are marked ctx");
+  // The diff replaces the plain result rendering — no raw result <pre> for a diff tool.
+  assertEquals(host.byData("tool-result", "true").length, 0);
+});
+
+test("structured edit args (path + old/new text) render as a synthesized diff", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([env("tool-call", { name: "write", callId: "s1", args: { path: "a.txt", oldText: "one\ntwo", newText: "one\nTWO" } })]),
+  );
+  const card = host.byData("tool", "write")[0];
+  assertEquals(card?.getAttribute("data-tool-kind"), "diff");
+  assertEquals(host.byData("diff-line", "del").length, 2);
+  assertEquals(host.byData("diff-line", "add").length, 2);
+  // The diff was synthesized FROM args, so the raw args <pre> is not ALSO rendered.
+  assertEquals(host.byData("tool-args", "true").length, 0);
+});
+
+test("structured edit args ending in a trailing newline do not synthesize a spurious empty diff line", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([env("tool-call", { name: "write", callId: "s2", args: { path: "a.txt", oldText: "one\ntwo\n", newText: "one\nTWO\n" } })]),
+  );
+  // "one\ntwo\n" would naively split into 3 segments (…, "two", "") — the trailing empty is dropped.
+  assertEquals(host.byData("diff-line", "del").length, 2);
+  assertEquals(host.byData("diff-line", "add").length, 2);
+});
+
+test("an args-synthesized diff still renders non-diff result content (args+result, diff special render)", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("tool-call", { name: "write", callId: "s3", args: { path: "a.txt", oldText: "one", newText: "ONE" } }),
+      env("tool-result", { callId: "s3", ok: true, content: "wrote 1 file" }),
+    ]),
+  );
+  const card = host.byData("tool", "write")[0];
+  assertEquals(card?.getAttribute("data-tool-kind"), "diff");
+  // The diff came from args, so the result content is not the diff source — it is still shown.
+  const resultEl = host.byData("tool-result", "true")[0];
+  assertEquals(resultEl?.textContent, "wrote 1 file");
+});
+
+test("a pending escalate permission renders Allow/Deny buttons that invoke onPermissionResolve", () => {
+  const host = new FakeElement("div");
+  const calls: Array<{ callId: string; optionId: string; allowed: boolean }> = [];
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("permission", {
+        phase: "request",
+        callId: "p1",
+        policy: "escalate",
+        title: "Run a shell command?",
+        options: [
+          { optionId: "allow", name: "Allow", kind: "allow-once" },
+          { optionId: "deny", name: "Deny", kind: "reject-once" },
+        ],
+      }),
+    ]),
+    { onPermissionResolve: (resolution) => calls.push(resolution) },
+  );
+  const card = host.byData("permission", "request")[0];
+  assertEquals(card?.getAttribute("data-policy"), "escalate");
+  assertEquals(card?.getAttribute("data-status"), "pending");
+  assertEquals(card?.getAttribute("data-call-id"), "p1");
+  const buttons = host.byClass("cockpit-transcript-permission-option");
+  assertEquals(buttons.length, 2);
+
+  buttons.find((b) => b.getAttribute("data-option-id") === "allow")?.dispatch("click");
+  buttons.find((b) => b.getAttribute("data-option-id") === "deny")?.dispatch("click");
+  assertEquals(calls, [
+    { callId: "p1", optionId: "allow", allowed: true },
+    { callId: "p1", optionId: "deny", allowed: false },
+  ]);
+});
+
+test("a yolo permission request renders informational only — no Allow/Deny buttons", () => {
+  const host = new FakeElement("div");
+  const calls: unknown[] = [];
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("permission", {
+        phase: "request",
+        callId: "y1",
+        policy: "yolo",
+        options: [{ optionId: "allow", name: "Allow", kind: "allow-always" }],
+      }),
+    ]),
+    { onPermissionResolve: (resolution) => calls.push(resolution) },
+  );
+  const card = host.byData("permission", "request")[0];
+  assertEquals(card?.getAttribute("data-policy"), "yolo");
+  assertEquals(card?.getAttribute("data-status"), "auto");
+  assertEquals(host.byClass("cockpit-transcript-permission-option").length, 0);
+  assertEquals(calls.length, 0);
+});
+
+test("a resolved permission renders settled (allowed/denied) with the chosen option and no live buttons", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("permission", {
+        phase: "request",
+        callId: "r1",
+        policy: "escalate",
+        title: "Delete the file?",
+        options: [
+          { optionId: "allow", name: "Allow once", kind: "allow-once" },
+          { optionId: "deny", name: "Deny", kind: "reject-once" },
+        ],
+      }),
+      env("permission", { phase: "resolution", callId: "r1", optionId: "deny", allowed: false, by: "operator" }),
+    ]),
+  );
+  const card = host.byData("permission", "request")[0];
+  assertEquals(card?.getAttribute("data-status"), "denied");
+  const settled = host.byClass("cockpit-transcript-permission-settled")[0];
+  assertEquals(settled?.getAttribute("data-chosen-option"), "deny");
+  assertEquals(settled?.textContent, "Deny");
+  assertEquals(host.byClass("cockpit-transcript-permission-option").length, 0);
+});
+
+test("the existing 3-arg renderDerivedTranscript(host, doc, data) call still works (options optional)", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(host, doc, report());
+  assertEquals(host.byData("turn-count", "1").length, 1);
+  assertEquals(host.byData("permission-count", "0").length, 1);
+});

package/app/agentic/cockpit/transcript-derive.ts

@@ -13,7 +13,13 @@
 // the same {@link DerivedView}, and the renderer draws into the injected {@link DocumentLike} subset so
 // a real DOM satisfies it at runtime and an in-memory fake satisfies it for DOM-free Node tests.
 import type { DocumentLike, ElementLike } from "@nanobpm/agentic/cockpit";
-import { type DerivedView, deriveViewFromChunks } from "../transcript-events.ts";
+import {
+  type DerivedPermission,
+  type DerivedTool,
+  type DerivedView,
+  deriveViewFromChunks,
+  type PermissionOptionKind,
+} from "../transcript-events.ts";
 import type { TranscriptDataReport } from "./transcript-render.ts";
 
 /**
@@ -36,13 +42,235 @@ export interface DerivedTranscriptDom {
   readonly root: ElementLike;
 }
 
+/**
+ * Options for {@link renderDerivedTranscript}. This is the SHARED SEAM the wave-2 escalation bridge
+ * attaches its handler to: an escalate-policy permission prompt's Allow/Deny buttons invoke
+ * {@link onPermissionResolve} on click (mirroring how `transcript-render.ts` wires `onReplay`). The
+ * render itself only *invokes* the callback — the relay round-trip that actually releases the blocked
+ * agent lives in the bridge, not here. Optional/defaulted so the 3-arg call sites keep working.
+ */
+export interface RenderDerivedTranscriptOptions {
+  /**
+   * Called when the operator picks an Allow/Deny option on a pending `escalate` permission prompt. The
+   * resolution shape is the minimal `{ callId, optionId, allowed }` the bridge folds into a
+   * `permission` RESOLUTION frame — `allowed` is derived from the chosen option's kind (allow-* ⇒ true,
+   * reject-* ⇒ false). Yolo requests never prompt, so this never fires for a yolo policy.
+   */
+  readonly onPermissionResolve?: (resolution: { callId: string; optionId: string; allowed: boolean }) => void;
+}
+
+/** A single classified line of a rendered diff block. */
+type DiffLineKind = "add" | "del" | "ctx";
+interface DiffLine {
+  readonly kind: DiffLineKind;
+  readonly text: string;
+}
+interface DetectedDiff {
+  readonly lines: readonly DiffLine[];
+  /** Where the diff came from — so the raw `args`/`result` content isn't ALSO rendered redundantly. */
+  readonly source: "args" | "result";
+}
+
+/** Render an arbitrary derived value (tool args/result) as displayable text without re-parsing the log. */
+function toText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value === undefined) return "";
+  return JSON.stringify(value, null, 2);
+}
+
+/** Read the first string-valued field among `keys` off an object, without an `as` cast. */
+function pickString(obj: object, keys: readonly string[]): string | undefined {
+  for (const key of keys) {
+    const value = Reflect.get(obj, key);
+    if (typeof value === "string") return value;
+  }
+  return undefined;
+}
+
+/** Classify one line of a unified diff (file/hunk headers are context, not add/del). */
+function classifyUnifiedLine(line: string): DiffLineKind {
+  if (line.startsWith("+++") || line.startsWith("---") || line.startsWith("@@") || line.startsWith("diff ")) return "ctx";
+  if (line.startsWith("+")) return "add";
+  if (line.startsWith("-")) return "del";
+  return "ctx";
+}
+
+/** Heuristic: does this string look like a unified diff (a hunk header, or paired +/- content lines)? */
+function looksLikeUnifiedDiff(text: string): boolean {
+  if (text.length === 0) return false;
+  let add = false;
+  let del = false;
+  let hunk = false;
+  for (const line of text.split("\n")) {
+    if (line.startsWith("@@") || line.startsWith("diff --git")) hunk = true;
+    else if (line.startsWith("+++") || line.startsWith("---")) continue;
+    else if (line.startsWith("+")) add = true;
+    else if (line.startsWith("-")) del = true;
+  }
+  return hunk || (add && del);
+}
+
+/** Split a unified-diff string into classified lines (dropping a single trailing empty line). */
+function parseUnifiedDiff(text: string): DiffLine[] {
+  const lines = text.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return lines.map((line) => ({ kind: classifyUnifiedLine(line), text: line }));
+}
+
+/** Split a block of text into lines, dropping a single trailing empty segment (text ending in "\n"). */
+function splitTextLines(text: string): string[] {
+  const lines = text.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return lines;
+}
+
+/** Synthesize a diff from structured edit args (`{ path?, oldText/old_string, newText/new_string }`). */
+function structuredDiff(args: unknown): DiffLine[] | undefined {
+  if (typeof args !== "object" || args === null) return undefined;
+  const oldText = pickString(args, ["oldText", "old_string", "oldStr", "old", "before"]);
+  const newText = pickString(args, ["newText", "new_string", "newStr", "new", "after"]);
+  if (oldText === undefined && newText === undefined) return undefined;
+  const lines: DiffLine[] = [];
+  const path = pickString(args, ["path", "file", "filePath", "fileName"]);
+  if (path !== undefined) lines.push({ kind: "ctx", text: `diff --git a/${path} b/${path}` });
+  if (oldText !== undefined && oldText.length > 0) {
+    for (const line of splitTextLines(oldText)) lines.push({ kind: "del", text: `-${line}` });
+  }
+  if (newText !== undefined && newText.length > 0) {
+    for (const line of splitTextLines(newText)) lines.push({ kind: "add", text: `+${line}` });
+  }
+  return lines.length > 0 ? lines : undefined;
+}
+
+/** Detect diff-shaped content on a tool call/result — a unified-diff string or structured edit args. */
+function detectDiff(tool: DerivedTool): DetectedDiff | undefined {
+  const content = tool.result?.content;
+  if (typeof content === "string" && looksLikeUnifiedDiff(content)) {
+    return { lines: parseUnifiedDiff(content), source: "result" };
+  }
+  if (typeof tool.args === "string" && looksLikeUnifiedDiff(tool.args)) {
+    return { lines: parseUnifiedDiff(tool.args), source: "args" };
+  }
+  const structured = structuredDiff(tool.args);
+  if (structured !== undefined) return { lines: structured, source: "args" };
+  return undefined;
+}
+
+/** Render one tool card: name, status, args + result content, and a distinguishable diff block. */
+function renderTool(doc: DocumentLike, tool: DerivedTool): ElementLike {
+  const card = el(doc, "div", "cockpit-transcript-tool");
+  card.setAttribute("data-tool", tool.name);
+  card.setAttribute("data-offset", String(tool.offset));
+  card.setAttribute("data-status", tool.result === undefined ? "pending" : tool.result.ok ? "ok" : "error");
+  card.appendChild(el(doc, "div", "cockpit-transcript-tool-name", tool.name));
+
+  const diff = detectDiff(tool);
+  if (diff !== undefined) card.setAttribute("data-tool-kind", "diff");
+
+  // Show the raw args unless the diff was synthesized FROM the args (then the diff block replaces it).
+  if (tool.args !== undefined && !(diff !== undefined && diff.source === "args")) {
+    const argsEl = el(doc, "pre", "cockpit-transcript-tool-args", toText(tool.args));
+    argsEl.setAttribute("data-tool-args", "true");
+    card.appendChild(argsEl);
+  }
+
+  if (diff !== undefined) {
+    const pre = el(doc, "pre", "cockpit-transcript-diff");
+    pre.setAttribute("data-diff", "true");
+    for (const line of diff.lines) {
+      // A <pre> may only contain phrasing content, so each diff line is a phrasing <span>
+      // (not a block <div>, which would be invalid markup) carrying a trailing "\n". The
+      // enclosing <pre> preserves that newline, so lines break onto their own line without
+      // depending on host CSS forcing display:block.
+      const row = el(doc, "span", "cockpit-transcript-diff-line", `${line.text}\n`);
+      row.setAttribute("data-diff-line", line.kind);
+      pre.appendChild(row);
+    }
+    card.appendChild(pre);
+  }
+
+  // Render the result content unless it was itself consumed as the diff source (source === "result").
+  if (typeof tool.result?.content === "string" && !(diff !== undefined && diff.source === "result")) {
+    const resEl = el(doc, "pre", "cockpit-transcript-tool-result", tool.result.content);
+    resEl.setAttribute("data-tool-result", "true");
+    card.appendChild(resEl);
+  }
+  return card;
+}
+
+/** Does a permission option kind allow (true) or reject (false) the proposed action? */
+function optionAllows(kind: PermissionOptionKind): boolean {
+  return kind === "allow-once" || kind === "allow-always";
+}
+
+/**
+ * Render one permission prompt card from a {@link DerivedPermission}:
+ * - a pending `escalate` request → interactive Allow/Deny buttons wired to `onPermissionResolve`;
+ * - a `yolo` request → informational only (yolo auto-allows, it never prompts a human);
+ * - a resolved permission → settled (`allowed`/`denied`), showing the chosen option, no live buttons.
+ */
+function renderPermission(doc: DocumentLike, perm: DerivedPermission, options: RenderDerivedTranscriptOptions): ElementLike {
+  const card = el(doc, "div", "cockpit-transcript-permission");
+  card.setAttribute("data-permission", "request");
+  card.setAttribute("data-policy", perm.policy);
+  card.setAttribute("data-call-id", perm.callId);
+  card.setAttribute("data-offset", String(perm.offset));
+  if (perm.toolName !== undefined) card.setAttribute("data-tool", perm.toolName);
+  if (perm.title !== undefined) card.appendChild(el(doc, "div", "cockpit-transcript-permission-title", perm.title));
+  if (perm.reason !== undefined) card.appendChild(el(doc, "div", "cockpit-transcript-permission-reason", perm.reason));
+
+  if (perm.resolved !== undefined) {
+    // Settled: show which option was chosen and no live buttons.
+    card.setAttribute("data-status", perm.resolved.allowed ? "allowed" : "denied");
+    const chosen = perm.options.find((option) => option.optionId === perm.resolved?.optionId);
+    const settled = el(doc, "div", "cockpit-transcript-permission-settled", chosen?.name ?? perm.resolved.optionId);
+    settled.setAttribute("data-chosen-option", perm.resolved.optionId);
+    if (perm.resolved.by !== undefined) settled.setAttribute("data-by", perm.resolved.by);
+    card.appendChild(settled);
+    return card;
+  }
+
+  if (perm.policy === "yolo") {
+    // Informational: yolo auto-allows and never prompts a human, so no Allow/Deny buttons.
+    card.setAttribute("data-status", "auto");
+    card.appendChild(el(doc, "div", "cockpit-transcript-permission-note", "Auto-allowed (yolo) — no operator prompt."));
+    return card;
+  }
+
+  // Pending escalate: one interactive button per offered option, wired to the resolve seam.
+  card.setAttribute("data-status", "pending");
+  const actions = el(doc, "div", "cockpit-transcript-permission-actions");
+  for (const option of perm.options) {
+    const allowed = optionAllows(option.kind);
+    const button = el(doc, "button", "cockpit-transcript-permission-option", option.name);
+    button.setAttribute("type", "button");
+    button.setAttribute("data-option-id", option.optionId);
+    button.setAttribute("data-option-kind", option.kind);
+    button.setAttribute("data-allowed", String(allowed));
+    const onPermissionResolve = options.onPermissionResolve;
+    if (onPermissionResolve !== undefined) {
+      button.addEventListener("click", () => onPermissionResolve({ callId: perm.callId, optionId: option.optionId, allowed }));
+    }
+    actions.appendChild(button);
+  }
+  card.appendChild(actions);
+  return card;
+}
+
 /**
  * Render the DERIVED structured view of a fetched transcript into `host`, replacing whatever was there.
- * Draws per-turn sections with their derived messages and tool cards, plus a raw-fidelity footer
- * (retained bytes/chunks) so the operator sees the byte-replay is preserved alongside the structure.
- * Idempotent — call again on each refresh. Everything it shows is a derivation of the one event log.
+ * Draws per-turn sections with their derived messages, rich tool/diff cards and permission prompts, plus
+ * a raw-fidelity footer (retained bytes/chunks) so the operator sees the byte-replay is preserved
+ * alongside the structure. Idempotent — call again on each refresh. Everything it shows is a derivation
+ * of the one event log. `options.onPermissionResolve`, when provided, is invoked by a pending
+ * escalate-permission prompt's Allow/Deny buttons.
  */
-export function renderDerivedTranscript(host: ElementLike, doc: DocumentLike, data: TranscriptDataReport): DerivedTranscriptDom {
+export function renderDerivedTranscript(
+  host: ElementLike,
+  doc: DocumentLike,
+  data: TranscriptDataReport,
+  options: RenderDerivedTranscriptOptions = {},
+): DerivedTranscriptDom {
   const view = deriveTranscript(data);
   host.replaceChildren();
   const root = el(doc, "div", "cockpit-transcript-derived");
@@ -51,6 +279,7 @@ export function renderDerivedTranscript(host: ElementLike, doc: DocumentLike, da
   root.setAttribute("data-turn-count", String(view.turns.length));
   root.setAttribute("data-message-count", String(view.messages.length));
   root.setAttribute("data-tool-count", String(view.tools.length));
+  root.setAttribute("data-permission-count", String(view.permissions.length));
 
   if (view.turns.length === 0) {
     const empty = el(doc, "div", "cockpit-transcript-empty", "No structured events derived — raw replay only.");
@@ -70,11 +299,10 @@ export function renderDerivedTranscript(host: ElementLike, doc: DocumentLike, da
       section.appendChild(row);
     }
     for (const tool of turn.tools) {
-      const card = el(doc, "div", "cockpit-transcript-tool", tool.name);
-      card.setAttribute("data-tool", tool.name);
-      card.setAttribute("data-offset", String(tool.offset));
-      card.setAttribute("data-status", tool.result === undefined ? "pending" : tool.result.ok ? "ok" : "error");
-      section.appendChild(card);
+      section.appendChild(renderTool(doc, tool));
+    }
+    for (const perm of turn.permissions) {
+      section.appendChild(renderPermission(doc, perm, options));
     }
     root.appendChild(section);
   }

package/app/agentic/transcript-events.test.ts

@@ -184,3 +184,227 @@ test("deriveViewFromChunks: a mixed log derives typed structure while retaining
   assertEquals(view.messages.map((m) => m.text), ["hi"]);
   assertEquals(view.rawChunkCount, 1);
 });
+
+// --- permission kind (issue #559) -----------------------------------------------------------------
+
+const REQUEST_OPTIONS = [
+  { optionId: "allow", name: "Allow", kind: "allow-once" },
+  { optionId: "deny", name: "Deny", kind: "reject-once" },
+];
+
+test("core vocab decodes a permission REQUEST envelope", () => {
+  const chunk = env("permission", {
+    phase: "request",
+    callId: "p1",
+    policy: "escalate",
+    options: REQUEST_OPTIONS,
+    toolName: "write_file",
+    title: "Write to /etc/hosts?",
+    reason: "The agent wants to modify a system file",
+  });
+  assertEquals(parseTranscriptEvent({ offset: 1, chunk }), {
+    kind: "permission",
+    phase: "request",
+    offset: 1,
+    callId: "p1",
+    policy: "escalate",
+    options: REQUEST_OPTIONS,
+    toolName: "write_file",
+    title: "Write to /etc/hosts?",
+    reason: "The agent wants to modify a system file",
+  });
+});
+
+test("core vocab decodes a permission REQUEST with only required fields (optional fields omitted)", () => {
+  const chunk = env("permission", { phase: "request", callId: "p2", policy: "yolo", options: REQUEST_OPTIONS });
+  assertEquals(parseTranscriptEvent({ offset: 0, chunk }), {
+    kind: "permission",
+    phase: "request",
+    offset: 0,
+    callId: "p2",
+    policy: "yolo",
+    options: REQUEST_OPTIONS,
+  });
+});
+
+test("core vocab decodes a permission RESOLUTION envelope", () => {
+  const chunk = env("permission", { phase: "resolution", callId: "p1", optionId: "allow", allowed: true, by: "operator" });
+  assertEquals(parseTranscriptEvent({ offset: 2, chunk }), {
+    kind: "permission",
+    phase: "resolution",
+    offset: 2,
+    callId: "p1",
+    optionId: "allow",
+    allowed: true,
+    by: "operator",
+  });
+});
+
+test("core vocab: malformed permission envelopes fall back to raw stream-chunk", () => {
+  // request missing options
+  assertEquals(
+    parseTranscriptEvent({ offset: 0, chunk: env("permission", { phase: "request", callId: "p1", policy: "escalate" }) }).kind,
+    "stream-chunk",
+  );
+  // request with a bad policy
+  assertEquals(
+    parseTranscriptEvent({
+      offset: 0,
+      chunk: env("permission", { phase: "request", callId: "p1", policy: "maybe", options: REQUEST_OPTIONS }),
+    }).kind,
+    "stream-chunk",
+  );
+  // request with a malformed option (bad kind)
+  assertEquals(
+    parseTranscriptEvent({
+      offset: 0,
+      chunk: env("permission", { phase: "request", callId: "p1", policy: "escalate", options: [{ optionId: "a", name: "A", kind: "nope" }] }),
+    }).kind,
+    "stream-chunk",
+  );
+  // resolution missing allowed
+  assertEquals(
+    parseTranscriptEvent({ offset: 0, chunk: env("permission", { phase: "resolution", callId: "p1", optionId: "allow" }) }).kind,
+    "stream-chunk",
+  );
+  // resolution with a present-but-unknown `by` provenance (rejected, not silently dropped)
+  assertEquals(
+    parseTranscriptEvent({
+      offset: 0,
+      chunk: env("permission", { phase: "resolution", callId: "p1", optionId: "allow", allowed: true, by: "robot" }),
+    }).kind,
+    "stream-chunk",
+  );
+  // resolution with a present-but-NON-STRING `by` (e.g. 123) — rejected, not accepted with `by` dropped
+  assertEquals(
+    parseTranscriptEvent({
+      offset: 0,
+      chunk: env("permission", { phase: "resolution", callId: "p1", optionId: "allow", allowed: true, by: 123 }),
+    }).kind,
+    "stream-chunk",
+  );
+  // missing callId
+  assertEquals(
+    parseTranscriptEvent({ offset: 0, chunk: env("permission", { phase: "request", policy: "escalate", options: REQUEST_OPTIONS }) }).kind,
+    "stream-chunk",
+  );
+  // unknown phase
+  assertEquals(
+    parseTranscriptEvent({ offset: 0, chunk: env("permission", { phase: "wat", callId: "p1" }) }).kind,
+    "stream-chunk",
+  );
+});
+
+test("mergeTranscriptVocab: the permission kind is additive — provable via a merged vocab too", () => {
+  // Registering an unrelated kind via merge must not disturb the core `permission` decoder.
+  const vocab = mergeTranscriptVocab(CORE_TRANSCRIPT_VOCAB, {
+    reasoning: (body, offset) => ({ kind: "message", offset, role: "system", text: String(body.text ?? "") }),
+  });
+  const chunk = env("permission", { phase: "request", callId: "p9", policy: "escalate", options: REQUEST_OPTIONS });
+  assertEquals(parseTranscriptEvent({ offset: 5, chunk }, vocab), {
+    kind: "permission",
+    phase: "request",
+    offset: 5,
+    callId: "p9",
+    policy: "escalate",
+    options: REQUEST_OPTIONS,
+  });
+});
+
+test("encodeTranscriptEvent round-trips the permission kind through the one parser", () => {
+  const events: TranscriptEvent[] = [
+    {
+      kind: "permission",
+      phase: "request",
+      offset: 10,
+      callId: "p1",
+      policy: "escalate",
+      options: REQUEST_OPTIONS.map((o) => ({ optionId: o.optionId, name: o.name, kind: o.kind === "allow-once" ? "allow-once" : "reject-once" })),
+      toolName: "rm",
+      title: "Delete?",
+      reason: "why",
+    },
+    { kind: "permission", phase: "resolution", offset: 11, callId: "p1", optionId: "deny", allowed: false, by: "auto" },
+  ];
+  for (const original of events) {
+    const chunk = encodeTranscriptEvent(original);
+    assertEquals(parseTranscriptEvent({ offset: original.offset, chunk }), original);
+  }
+});
+
+test("deriveView: pairs a permission request with its resolution by callId, carrying policy + options", () => {
+  const view = deriveView([
+    { kind: "turn", offset: 0, index: 0 },
+    {
+      kind: "permission",
+      phase: "request",
+      offset: 1,
+      callId: "p1",
+      policy: "escalate",
+      options: [
+        { optionId: "allow", name: "Allow", kind: "allow-once" },
+        { optionId: "deny", name: "Deny", kind: "reject-once" },
+      ],
+      title: "Write file?",
+    },
+    { kind: "permission", phase: "resolution", offset: 2, callId: "p1", optionId: "allow", allowed: true, by: "operator" },
+  ]);
+  assertEquals(view.permissions.length, 1);
+  const permission = view.permissions[0];
+  assertEquals(permission?.policy, "escalate");
+  assertEquals(permission?.title, "Write file?");
+  assertEquals(permission?.options.length, 2);
+  assertEquals(permission?.resolved, { allowed: true, optionId: "allow", offset: 2, by: "operator" });
+  // Also attached to its enclosing turn.
+  assertEquals(view.turns[0]?.permissions.length, 1);
+  assertEquals(view.turns[0]?.permissions[0]?.resolved?.optionId, "allow");
+});
+
+test("deriveView: an unresolved permission request stays pending (no resolution)", () => {
+  const view = deriveView([
+    {
+      kind: "permission",
+      phase: "request",
+      offset: 0,
+      callId: "p1",
+      policy: "escalate",
+      options: [{ optionId: "allow", name: "Allow", kind: "allow-once" }],
+    },
+  ]);
+  assertEquals(view.permissions.length, 1);
+  assertEquals(view.permissions[0]?.resolved, undefined);
+  assertEquals(view.permissions[0]?.policy, "escalate");
+  // Content before any turn event opens an implicit turn 0 (consistent with messages/tools).
+  assertEquals(view.turns.length, 1);
+  assertEquals(view.turns[0]?.permissions.length, 1);
+});
+
+test("deriveView: the policy field survives derivation for a yolo request", () => {
+  const view = deriveView([
+    {
+      kind: "permission",
+      phase: "request",
+      offset: 0,
+      callId: "p1",
+      policy: "yolo",
+      options: [{ optionId: "allow", name: "Allow", kind: "allow-always" }],
+    },
+    { kind: "permission", phase: "resolution", offset: 1, callId: "p1", optionId: "allow", allowed: true, by: "auto" },
+  ]);
+  assertEquals(view.permissions[0]?.policy, "yolo");
+  assertEquals(view.permissions[0]?.resolved?.by, "auto");
+});
+
+test("ACP plan updates map onto the existing step/turn vocabulary (no new kind)", () => {
+  // An ACP plan entry becomes a `step` (its label the entry title); a plan/turn boundary a `turn`.
+  const view = deriveViewFromChunks([
+    { offset: 0, chunk: env("turn", { index: 0 }) },
+    { offset: 1, chunk: env("step", { label: "Investigate the failing test", index: 0 }) },
+    { offset: 2, chunk: env("step", { label: "Fix the bug", index: 1 }) },
+    { offset: 3, chunk: env("turn", { index: 1 }) },
+    { offset: 4, chunk: env("step", { label: "Write a regression test" }) },
+  ]);
+  assertEquals(view.turns.length, 2);
+  assertEquals(view.turns[0]?.steps, 2);
+  assertEquals(view.turns[1]?.steps, 1);
+});

package/app/agentic/transcript-events.ts

@@ -64,7 +64,8 @@ export type TranscriptEventKind =
   | "tool-result"
   | "turn"
   | "step"
-  | "lifecycle";
+  | "lifecycle"
+  | "permission";
 
 /** The message roles the derived history distinguishes (assistant is authoritative for derivation). */
 export type TranscriptRole = "assistant" | "user" | "system" | "tool";
@@ -124,6 +125,70 @@ export interface LifecycleEvent extends TranscriptEventBase {
   readonly phase: "open" | "completed" | "exited";
 }
 
+// --- Permission (ACP `session/request_permission`) — SHARED CONTRACT (issue #559) ------------------
+// A `permission` event models ACP's `session/request_permission`: the agent asks the operator to
+// allow/deny a proposed action (usually a tool call), and the operator (or an auto policy) resolves it.
+// It is decoded here (the ONE parser) and folded here (the ONE fold) into a paired {@link DerivedPermission}.
+// These exported types are the SINGLE SOURCE OF TRUTH the sibling slices (cockpit render, escalation
+// bridge) consume — they must import these, never reinvent a divergent permission shape. See the durable
+// declaration in `app/contracts.ts` (`type:PermissionPolicy`, `wire:transcript.permission`).
+
+/**
+ * The role's permission policy the PRODUCER tags a request with. `"escalate"` means a human must be
+ * asked (the cockpit renders an Allow/Deny prompt, the escalation bridge raises a user task);
+ * `"yolo"` means the action is auto-allowed and never prompts a human. Cockpit + bridge branch on this.
+ */
+export type PermissionPolicy = "escalate" | "yolo";
+
+/** The kind of a permission option — mirrors ACP's option kinds (allow/reject × once/always). */
+export type PermissionOptionKind = "allow-once" | "allow-always" | "reject-once" | "reject-always";
+
+/** One offered permission option (ACP `options[]` member): a stable id, a label, and its kind. */
+export interface PermissionOption {
+  readonly optionId: string;
+  readonly name: string;
+  readonly kind: PermissionOptionKind;
+}
+
+/**
+ * A permission REQUEST: the agent asks the operator to allow/deny a proposed action. The `callId`
+ * pairs the eventual {@link PermissionResolutionEvent} back to this request (mirroring how
+ * `tool-call`/`tool-result` pair by `callId`).
+ */
+export interface PermissionRequestEvent extends TranscriptEventBase {
+  readonly kind: "permission";
+  readonly phase: "request";
+  /** Stable id pairing this request to its resolution. */
+  readonly callId: string;
+  /** The producer-tagged policy the cockpit + bridge branch on. */
+  readonly policy: PermissionPolicy;
+  /** The offered options — always at least one (the decoder rejects an empty list). */
+  readonly options: readonly PermissionOption[];
+  /** The tool the proposed action would invoke, when known. */
+  readonly toolName?: string;
+  /** A short human-readable title for the prompt. */
+  readonly title?: string;
+  /** A longer human-readable reason for the prompt. */
+  readonly reason?: string;
+}
+
+/**
+ * A permission RESOLUTION: the operator's (or an auto policy's) decision, carrying the same `callId`,
+ * the chosen `optionId`, and whether the action was `allowed`.
+ */
+export interface PermissionResolutionEvent extends TranscriptEventBase {
+  readonly kind: "permission";
+  readonly phase: "resolution";
+  /** The `callId` of the {@link PermissionRequestEvent} this resolves. */
+  readonly callId: string;
+  /** The chosen option's id. */
+  readonly optionId: string;
+  /** True = allowed, false = denied. */
+  readonly allowed: boolean;
+  /** Provenance of the decision, when supplied. */
+  readonly by?: "operator" | "auto";
+}
+
 /** The core typed transcript-event union (merge-extensible: authors add kinds via the vocab). */
 export type TranscriptEvent =
   | StreamChunkEvent
@@ -132,7 +197,9 @@ export type TranscriptEvent =
   | ToolResultEvent
   | TurnEvent
   | StepEvent
-  | LifecycleEvent;
+  | LifecycleEvent
+  | PermissionRequestEvent
+  | PermissionResolutionEvent;
 
 /** A stored chunk as the store/read path exposes it (mirrors `TranscriptChunk`). */
 export interface StoredChunk {
@@ -172,6 +239,32 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
+const PERMISSION_OPTION_KINDS: readonly PermissionOptionKind[] = [
+  "allow-once",
+  "allow-always",
+  "reject-once",
+  "reject-always",
+];
+
+/**
+ * Decode ACP's `options[]` into typed {@link PermissionOption}s, or `undefined` if the array is
+ * missing/empty or any member is malformed (so the whole request envelope is rejected → `stream-chunk`).
+ */
+function decodePermissionOptions(value: unknown): PermissionOption[] | undefined {
+  if (!Array.isArray(value) || value.length === 0) return undefined;
+  const options: PermissionOption[] = [];
+  for (const raw of value) {
+    if (!isRecord(raw)) return undefined;
+    const optionId = str(raw, "optionId");
+    const name = str(raw, "name");
+    const kindRaw = str(raw, "kind");
+    const kind = PERMISSION_OPTION_KINDS.find((k) => k === kindRaw);
+    if (optionId === undefined || name === undefined || kind === undefined) return undefined;
+    options.push({ optionId, name, kind });
+  }
+  return options;
+}
+
 /**
  * The opinionated core vocabulary — the built-in event kinds every consumer understands out of the
  * box. Authors extend it in the SAME schema via {@link mergeTranscriptVocab}; they never fork the
@@ -207,6 +300,11 @@ export const CORE_TRANSCRIPT_VOCAB: TranscriptVocab = Object.freeze({
       ...(content !== undefined ? { content } : {}),
     };
   },
+  // ACP `plan` mapping: ACP `session/update` plan updates map onto the EXISTING `step`/`turn`
+  // vocabulary rather than a new kind — an ACP plan ENTRY becomes a `step` (its `label` is the plan
+  // entry's title; the entry ordinal is not preserved, as `StepEvent` carries only a `label`), and a
+  // plan/turn BOUNDARY becomes a `turn` (its `index` the ACP turn/plan ordinal). The decoders below
+  // already cope with an ACP-shaped `label` (`step`) / `index` (`turn`), so no new kind is needed.
   turn: (body, offset) => {
     const index = num(body, "index");
     return index !== undefined ? { kind: "turn", offset, index } : { kind: "turn", offset };
@@ -220,6 +318,51 @@ export const CORE_TRANSCRIPT_VOCAB: TranscriptVocab = Object.freeze({
     if (phase !== "open" && phase !== "completed" && phase !== "exited") return undefined;
     return { kind: "lifecycle", offset, phase };
   },
+  // A single `permission` decoder handles BOTH shapes (never a parser fork), branching on `phase`.
+  // Malformed envelopes return `undefined` and fall back to `stream-chunk`, like the other decoders.
+  permission: (body, offset) => {
+    const callId = str(body, "callId");
+    if (callId === undefined) return undefined;
+    const phase = str(body, "phase");
+    if (phase === "request") {
+      const policy = str(body, "policy");
+      if (policy !== "escalate" && policy !== "yolo") return undefined;
+      const options = decodePermissionOptions(body.options);
+      if (options === undefined) return undefined;
+      const toolName = str(body, "toolName");
+      const title = str(body, "title");
+      const reason = str(body, "reason");
+      const event: PermissionRequestEvent = { kind: "permission", phase: "request", offset, callId, policy, options };
+      return {
+        ...event,
+        ...(toolName !== undefined ? { toolName } : {}),
+        ...(title !== undefined ? { title } : {}),
+        ...(reason !== undefined ? { reason } : {}),
+      };
+    }
+    if (phase === "resolution") {
+      const optionId = str(body, "optionId");
+      if (optionId === undefined) return undefined;
+      if (typeof body.allowed !== "boolean") return undefined;
+      const by = str(body, "by");
+      // Reject a malformed `by` rather than silently dropping it: a present-but-unknown provenance is a
+      // producer bug, and swallowing it would make the typed event diverge from the on-wire JSON. This
+      // covers BOTH a present-but-non-string `by` (e.g. `by: 123`, where str() coerces to undefined) and
+      // a string that isn't a known provenance — either way the on-wire `by` is present but invalid.
+      if (body.by !== undefined && by === undefined) return undefined;
+      if (by !== undefined && by !== "operator" && by !== "auto") return undefined;
+      const event: PermissionResolutionEvent = {
+        kind: "permission",
+        phase: "resolution",
+        offset,
+        callId,
+        optionId,
+        allowed: body.allowed,
+      };
+      return { ...event, ...(by !== undefined ? { by } : {}) };
+    }
+    return undefined;
+  },
 });
 
 /**
@@ -302,12 +445,35 @@ export interface DerivedMessage {
   readonly offset: number;
 }
 
+/**
+ * A derived permission: a permission REQUEST paired with its RESOLUTION by `callId` (resolution absent
+ * while the request is still pending), mirroring how {@link DerivedTool} pairs a call with its result.
+ * The cockpit and the escalation bridge read THIS — they never re-parse the log.
+ */
+export interface DerivedPermission {
+  readonly callId: string;
+  readonly policy: PermissionPolicy;
+  readonly options: readonly PermissionOption[];
+  readonly toolName?: string;
+  readonly title?: string;
+  readonly reason?: string;
+  readonly offset: number;
+  /** The resolution, once present (pending request → `undefined`). */
+  readonly resolved?: {
+    readonly allowed: boolean;
+    readonly optionId: string;
+    readonly by?: "operator" | "auto";
+    readonly offset: number;
+  };
+}
+
 /** A derived turn: the messages, tool cards and step count folded within one turn boundary. */
 export interface DerivedTurn {
   readonly index: number;
   readonly startOffset: number;
   readonly messages: readonly DerivedMessage[];
   readonly tools: readonly DerivedTool[];
+  readonly permissions: readonly DerivedPermission[];
   readonly steps: number;
 }
 
@@ -319,6 +485,8 @@ export interface DerivedView {
   readonly messages: readonly DerivedMessage[];
   /** Every tool card across all turns, in offset order. */
   readonly tools: readonly DerivedTool[];
+  /** Every permission across all turns, in offset order (each request paired to its resolution by `callId`). */
+  readonly permissions: readonly DerivedPermission[];
   /** Total retained raw bytes (UTF-8) across `stream-chunk` events — the byte-replay fidelity accounting. */
   readonly rawByteLength: number;
   /** Number of retained raw chunks. */
@@ -334,6 +502,7 @@ interface MutableTurn {
   startOffset: number;
   messages: DerivedMessage[];
   tools: DerivedTool[];
+  permissions: DerivedPermission[];
   steps: number;
 }
 
@@ -351,8 +520,10 @@ export function deriveView(events: Iterable<TranscriptEvent>): DerivedView {
   const turns: MutableTurn[] = [];
   const messages: DerivedMessage[] = [];
   const tools: DerivedTool[] = [];
+  const permissions: DerivedPermission[] = [];
   const openTools = new Map<string, DerivedTool>();
   let anonymousTool: DerivedTool | undefined;
+  const openPermissions = new Map<string, DerivedPermission>();
   let rawByteLength = 0;
   let rawChunkCount = 0;
   let lifecycle: "open" | "completed" | "exited" = "open";
@@ -361,7 +532,7 @@ export function deriveView(events: Iterable<TranscriptEvent>): DerivedView {
 
   const ensureTurn = (offset: number): MutableTurn => {
     if (current === undefined) {
-      current = { index: turns.length, startOffset: offset, messages: [], tools: [], steps: 0 };
+      current = { index: turns.length, startOffset: offset, messages: [], tools: [], permissions: [], steps: 0 };
       turns.push(current);
     }
     return current;
@@ -371,7 +542,14 @@ export function deriveView(events: Iterable<TranscriptEvent>): DerivedView {
     eventCount++;
     switch (event.kind) {
       case "turn": {
-        current = { index: event.index ?? turns.length, startOffset: event.offset, messages: [], tools: [], steps: 0 };
+        current = {
+          index: event.index ?? turns.length,
+          startOffset: event.offset,
+          messages: [],
+          tools: [],
+          permissions: [],
+          steps: 0,
+        };
         turns.push(current);
         break;
       }
@@ -408,6 +586,33 @@ export function deriveView(events: Iterable<TranscriptEvent>): DerivedView {
         }
         break;
       }
+      case "permission": {
+        // A `permission` event is one of two phases (same discriminant `kind`); branch on `phase`. A
+        // REQUEST opens a pending DerivedPermission (paired to its turn); a RESOLUTION folds back into
+        // the open request by `callId` — mirroring the tool-call/tool-result open-map pairing above.
+        if (event.phase === "request") {
+          const permission: DerivedPermission = {
+            policy: event.policy,
+            options: event.options,
+            offset: event.offset,
+            callId: event.callId,
+            ...(event.toolName !== undefined ? { toolName: event.toolName } : {}),
+            ...(event.title !== undefined ? { title: event.title } : {}),
+            ...(event.reason !== undefined ? { reason: event.reason } : {}),
+          };
+          permissions.push(permission);
+          ensureTurn(event.offset).permissions.push(permission);
+          openPermissions.set(event.callId, permission);
+        } else {
+          const target = openPermissions.get(event.callId);
+          if (target !== undefined) {
+            pairResolution(permissions, target, event);
+            pairResolutionInTurns(turns, target, event);
+            openPermissions.delete(event.callId);
+          }
+        }
+        break;
+      }
       case "lifecycle": {
         lifecycle = event.phase;
         break;
@@ -421,9 +626,17 @@ export function deriveView(events: Iterable<TranscriptEvent>): DerivedView {
   }
 
   return {
-    turns: turns.map((t) => ({ index: t.index, startOffset: t.startOffset, messages: t.messages, tools: t.tools, steps: t.steps })),
+    turns: turns.map((t) => ({
+      index: t.index,
+      startOffset: t.startOffset,
+      messages: t.messages,
+      tools: t.tools,
+      permissions: t.permissions,
+      steps: t.steps,
+    })),
     messages,
     tools,
+    permissions,
     rawByteLength,
     rawChunkCount,
     lifecycle,
@@ -457,6 +670,35 @@ function withResult(tool: DerivedTool, result: ToolResultEvent): DerivedTool {
   };
 }
 
+/** Replace a pending permission with its resolution in the flat list (by identity — see {@link pairResult}). */
+function pairResolution(list: DerivedPermission[], target: DerivedPermission, resolution: PermissionResolutionEvent): void {
+  const idx = list.indexOf(target);
+  if (idx >= 0) list[idx] = withResolution(target, resolution);
+}
+
+/** Replace a pending permission with its resolution inside whichever turn holds it. */
+function pairResolutionInTurns(turns: MutableTurn[], target: DerivedPermission, resolution: PermissionResolutionEvent): void {
+  for (const turn of turns) {
+    const idx = turn.permissions.indexOf(target);
+    if (idx >= 0) {
+      turn.permissions[idx] = withResolution(target, resolution);
+      return;
+    }
+  }
+}
+
+function withResolution(permission: DerivedPermission, resolution: PermissionResolutionEvent): DerivedPermission {
+  return {
+    ...permission,
+    resolved: {
+      allowed: resolution.allowed,
+      optionId: resolution.optionId,
+      offset: resolution.offset,
+      ...(resolution.by !== undefined ? { by: resolution.by } : {}),
+    },
+  };
+}
+
 /**
  * Convenience: parse a run of stored chunks into typed events through {@link parseTranscriptEvent} (the
  * one parser) and fold them with {@link deriveView} in a single call — the entry point a consumer uses

package/app/contracts.ts

@@ -407,9 +407,26 @@ export const WIRE_CONTRACTS = {
       "Filesystem-import request body POSTed to /actions/delivery-graph/library/import (issue #524, epic #519 S5). Declared in openapi.yaml as `ImportToLibrarySubmit`; the compose App-View's `<input type=file accept=.json>` reads the picked file's text client-side and POSTs it here as the raw `graphJson` string. The door validates + compiles it through the SAME `parseAndCompileText` pipeline preview/stage/save use, then persists `source: imported` — an uncompilable graph is a clean 400 and NOTHING is written. Its `name` defaults to the imported graph's own `name`; an explicit `name` overrides it (an unnamed graph with no override is a clean 400 — the library id is name-derived). Related to but DISTINCT from `SaveToLibrarySubmit` (which is graphJson-OR-digest and needs no required file text); consume this ONE shape across the openapi edge, the door, and the compose mount — do not re-declare a synonym.",
     shape: "{ graphJson: string, name?: string, description?: string }",
   },
+  "transcript.permission": {
+    category: "wire",
+    name: "transcript.permission",
+    owner: "app/agentic/transcript-events.ts",
+    semantics:
+      "The `permission` transcript-event envelope (issue #559) modelling ACP's `session/request_permission`, decoded by the ONE parser (`parseTranscriptEvent`) and folded by the ONE fold (`deriveView`) in app/agentic/transcript-events.ts. Two phases share the `kind:\"permission\"` discriminant, distinguished by `phase`. A REQUEST carries a stable `callId` (pairs the resolution back, like tool-call/tool-result), the producer-tagged `policy` (\"escalate\" = must ask a human, \"yolo\" = auto-allowed), the offered `options` (a NON-EMPTY array of ACP `{optionId,name,kind}` where kind is allow-once/allow-always/reject-once/reject-always — the decoder rejects a missing or empty `options`), and optional `toolName`/`title`/`reason`. A RESOLUTION carries the same `callId`, the chosen `optionId`, a boolean `allowed`, and optional `by` provenance (operator/auto). deriveView surfaces these as `DerivedPermission` (paired by callId) on `DerivedView.permissions` and `DerivedTurn.permissions`. The cockpit-render and escalation-bridge slices CONSUME this exact wire shape — do not re-declare a synonym.",
+    shape:
+      '{ nwfTranscriptEvent: 1, kind: "permission", phase: "request", callId: string, policy: "escalate"|"yolo", options: [{ optionId: string, name: string, kind: "allow-once"|"allow-always"|"reject-once"|"reject-always" }, ...Array<{ optionId: string, name: string, kind: "allow-once"|"allow-always"|"reject-once"|"reject-always" }>], toolName?: string, title?: string, reason?: string } | { nwfTranscriptEvent: 1, kind: "permission", phase: "resolution", callId: string, optionId: string, allowed: boolean, by?: "operator"|"auto" }',
+  },
 } as const satisfies Record<string, WireContract>;
 
 export const TYPE_CONTRACTS = {
+  PermissionPolicy: {
+    category: "type",
+    name: "PermissionPolicy",
+    owner: "app/agentic/transcript-events.ts",
+    semantics:
+      "The role's permission policy a `permission` transcript-event REQUEST is tagged with (issue #559): `\"escalate\"` (a human must be asked — cockpit renders an Allow/Deny prompt, the escalation bridge raises a user task) vs `\"yolo\"` (auto-allowed, never prompts). Exported from app/agentic/transcript-events.ts alongside the shared permission contract types (`PermissionOption`, `PermissionOptionKind`, `PermissionRequestEvent`, `PermissionResolutionEvent`, and the derived `DerivedPermission` surface on `DerivedView`/`DerivedTurn`). The cockpit-render and escalation-bridge siblings IMPORT these — they must not reinvent a divergent permission shape or a synonym policy enum.",
+    module: "app/agentic/transcript-events.ts",
+  },
   BlackboardEntry: {
     category: "type",
     name: "BlackboardEntry",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.145.1",
+  "version": "0.147.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",