@nanobpm/nano-workforce 0.147.0 → 0.148.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.148.0](https://github.com/nanobpm/nano-workforce/compare/v0.147.0...v0.148.0) (2026-08-26)
+
+### Features
+
+* **agentic:** bridge escalate-policy ACP permission requests to the nwf Tasks inbox ([#562](https://github.com/nanobpm/nano-workforce/issues/562)) ([44e5cfb](https://github.com/nanobpm/nano-workforce/commit/44e5cfb3ff262fa50db17466f690b64eb3405e56)), 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) [#561](https://github.com/nanobpm/nano-workforce/issues/561)
+
 ## [0.147.0](https://github.com/nanobpm/nano-workforce/compare/v0.146.0...v0.147.0) (2026-08-26)
 
 ### Features

package/app/agentCompletion.ts

@@ -24,6 +24,7 @@ import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
 import { DELIVERY_HUMAN_ELEMENT, isDeliveryHumanElement } from "./deliveryHuman.ts";
+import { ACP_PERMISSION_ELEMENT } from "./userTasks.ts";
 
 const now = () => new Date().toISOString();
 
@@ -92,13 +93,18 @@ export const CONFORMANCE_ESCALATION_TASK_ELEMENT = CONFORMANCE_ESCALATION_ELEMEN
 
 /** The user-task `elementId`s a HUMAN operator may complete from the Tasks inbox via the one canonical
  *  `complete-user-task` door: every agent-answerable escalation PLUS the human-only `feature-blocked`
- *  and `conformance-escalation` acknowledgements. The AGENT completer stays scoped to
- *  `ESCALATION_TASK_ELEMENTS` (neither ack), so widening the human surface never lets an agent retire
- *  a blocked run or a conformance review. */
+ *  and `conformance-escalation` acknowledgements, PLUS the advisory ACP permission prompt
+ *  (`ACP_PERMISSION_ELEMENT`, issue #559) a bridged escalate-policy `session/request_permission` raises.
+ *  The AGENT completer stays scoped to `ESCALATION_TASK_ELEMENTS` (none of these three), so widening the
+ *  human surface never lets an agent retire a blocked run, a conformance review, or an agent-permission
+ *  prompt. The permission element has no static `.form` (it is not a BPMN user task), so
+ *  `validateEscalationVariables` leaves its Allow/Deny variables unenforced — the permission bridge
+ *  translates them into a RESOLUTION frame (`app/agentic/permission-bridge.ts`). */
 export const HUMAN_COMPLETABLE_ELEMENTS: ReadonlySet<string> = new Set([
   ...ESCALATION_TASK_ELEMENTS,
   FEATURE_BLOCKED_TASK_ELEMENT,
   CONFORMANCE_ESCALATION_TASK_ELEMENT,
+  ACP_PERMISSION_ELEMENT,
 ]);
 
 /** Each escalation `elementId` → the `.form` whose contract governs its completion variables (the

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

@@ -18,7 +18,7 @@ import {
   type DerivedTool,
   type DerivedView,
   deriveViewFromChunks,
-  type PermissionOptionKind,
+  optionKindAllows,
 } from "../transcript-events.ts";
 import type { TranscriptDataReport } from "./transcript-render.ts";
 
@@ -198,11 +198,6 @@ function renderTool(doc: DocumentLike, tool: DerivedTool): ElementLike {
   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`;
@@ -241,7 +236,7 @@ function renderPermission(doc: DocumentLike, perm: DerivedPermission, options: R
   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 allowed = optionKindAllows(option.kind);
     const button = el(doc, "button", "cockpit-transcript-permission-option", option.name);
     button.setAttribute("type", "button");
     button.setAttribute("data-option-id", option.optionId);

package/app/agentic/permission-bridge.test.ts

@@ -0,0 +1,288 @@
+// The escalation-bridge acceptance tests (issue #559, ADR 0056). They drive the REAL in-repo operator
+// path end to end with in-memory fakes:
+//   escalate-policy permission REQUEST → a Tasks-inbox row raised (the new ACP_PERMISSION_ELEMENT kind) →
+//   an operator Allow/Deny answered through the canonical `completeEscalationAsHuman` door →
+//   a permission RESOLUTION frame sent down the relay CONTROL lane with the matching callId/optionId/allowed.
+// A focused unit test proves the exported `onPermissionResolve` adapter converges on the SAME frame, and
+// a yolo/opt-out test proves the bridge is bypassed by default.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import {
+  buildPermissionResolutionFrame,
+  completePermissionEscalationAsHuman,
+  createOnPermissionResolve,
+  optionKindAllows,
+  type PermissionBridgeDeps,
+  permissionEscalationEnabled,
+  permissionOptionAllows,
+  permissionQuestion,
+  permissionUserTaskRow,
+} from "./permission-bridge.ts";
+import { jobStream } from "./correlation.ts";
+import {
+  type DerivedPermission,
+  parseTranscriptEvent,
+  type PermissionResolutionEvent,
+} from "./transcript-events.ts";
+
+// ── In-memory fakes (mirroring the shared patterns in app/agentCompletion.test.ts) ────────────────
+
+/** A minimal in-memory `Table<T>` with AUTOINCREMENT ids on insert and structural find/get/delete. */
+function memTable(rows: any[], key: string) {
+  let seq = rows.reduce((m, r) => Math.max(m, Number(r[key]) || 0), 0);
+  return {
+    insert: (row: any) => {
+      const id = ++seq;
+      const stored = key === "id" ? { ...row, id } : { ...row };
+      rows.push(stored);
+      return Promise.resolve(key === "id" ? id : stored[key]);
+    },
+    get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k)),
+    find: (q: any = {}) => Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    findOne: (q: any = {}) => Promise.resolve(rows.find((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    update: (k: any, patch: any) => {
+      const r = rows.find((x) => x[key] === k);
+      if (r) Object.assign(r, patch);
+      return Promise.resolve(r ? 1 : 0);
+    },
+    delete: (k: any) => {
+      const i = rows.findIndex((r) => r[key] === k);
+      if (i >= 0) rows.splice(i, 1);
+      return Promise.resolve(i >= 0 ? 1 : 0);
+    },
+    count: (q: any = {}) => Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v)).length),
+    all: () => Promise.resolve(rows.slice()),
+  };
+}
+
+function memData(stores: Record<string, { rows: any[]; key: string }>) {
+  return {
+    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+  } as any;
+}
+
+/** A stub engine that records every `completeUserTask` against a seeded set of open user tasks (the
+ *  completer resolves via `openUserTasks`, CREATED only). */
+function fakeEngine(openTasks: Array<{ userTaskKey: string; elementId?: string }>) {
+  const completed: Array<{ userTaskKey: string; variables?: Record<string, unknown> }> = [];
+  const engine = {
+    openUserTasks: () => Promise.resolve(openTasks),
+    searchUserTasks: () => Promise.reject(new Error("completer must resolve via openUserTasks")),
+    completeUserTask: (userTaskKey: string, variables?: Record<string, unknown>) => {
+      completed.push({ userTaskKey, variables });
+      return Promise.resolve();
+    },
+  } as any;
+  return { engine, completed };
+}
+
+/** A relay-send spy: records every frame the bridge emits. */
+function sendSpy() {
+  const frames: any[] = [];
+  const deps: PermissionBridgeDeps = { send: (frame) => frames.push(frame) };
+  return { deps, frames };
+}
+
+/** Decode a produced resolution chunk back through the ONE parser (never re-parsing bytes by hand). */
+function decodeResolution(frame: any): PermissionResolutionEvent {
+  const chunk = frame.payload.chunk as string;
+  const event = parseTranscriptEvent({ offset: 0, chunk });
+  assert(event.kind === "permission" && event.phase === "resolution", "expected a permission RESOLUTION");
+  return event;
+}
+
+/** An escalate-policy permission REQUEST offering Allow (allow-once) and Deny (reject-once). */
+function escalateRequest(callId = "job-1"): DerivedPermission {
+  return {
+    callId,
+    policy: "escalate",
+    options: [
+      { optionId: "allow", name: "Allow", kind: "allow-once" },
+      { optionId: "deny", name: "Deny", kind: "reject-once" },
+    ],
+    toolName: "write_file",
+    title: "Write /etc/hosts",
+    reason: "The agent wants to modify a protected file.",
+    offset: 3,
+  };
+}
+
+// ── Acceptance: the full real-operator path, Allow and Deny ────────────────────────────────────────
+
+test("escalate REQUEST → Tasks-inbox row → operator ALLOW via the completion door → RESOLUTION down the control lane", async () => {
+  const request = escalateRequest("job-allow");
+  const stream = jobStream(request.callId);
+
+  // 1. The request surfaces as an answerable Tasks-inbox row of the new permission kind.
+  const row = permissionUserTaskRow(request, { userTaskKey: "ut-perm-1", subjectKey: "hire-42" }, { enabled: true });
+  assert(row !== null, "an escalate-policy request must raise a row");
+  assertEquals(row.element_id, "acp-permission");
+  assertEquals(row.kind_label, "Agent permission");
+  assertEquals(row.subject_type, "agent");
+  assertEquals(row.user_task_key, "ut-perm-1");
+  assert(row.question?.includes("Write /etc/hosts"), "the row carries the request's title/reason as the question");
+  assert(row.question?.includes("modify a protected file"), "the row carries the request's reason");
+
+  // 2. The operator answers Allow through the ONE canonical completion door.
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-perm-1", elementId: "acp-permission" }]);
+  const { deps, frames } = sendSpy();
+
+  const result = await completePermissionEscalationAsHuman(data, engine, deps, {
+    permission: request,
+    userTaskKey: "ut-perm-1",
+    optionId: "allow",
+    operatorId: "op:ada",
+  });
+
+  // The completion took through the canonical door (recorded attribution + engine completion).
+  assertEquals(result.completion.ok, true);
+  assertEquals(result.completion.elementId, "acp-permission");
+  assertEquals(completed.length, 1);
+  assertEquals(completed[0].userTaskKey, "ut-perm-1");
+  assertEquals(completed[0].variables, { optionId: "allow", allowed: true });
+  assertEquals(stores.task_completions.rows.length, 1);
+  assertEquals(stores.task_completions.rows[0].actor_kind, "human");
+
+  // 3. A RESOLUTION frame flowed back down the relay CONTROL lane, releasing the blocked request.
+  assertEquals(frames.length, 1);
+  assertEquals(frames[0].lane, "control");
+  assertEquals(frames[0].family, "relay");
+  assertEquals(frames[0].payload.op, "produce");
+  assertEquals(frames[0].payload.stream, stream);
+  const resolution = decodeResolution(frames[0]);
+  assertEquals(resolution.callId, "job-allow");
+  assertEquals(resolution.optionId, "allow");
+  assertEquals(resolution.allowed, true);
+  assertEquals(resolution.by, "operator");
+});
+
+test("escalate REQUEST → operator DENY via the completion door → RESOLUTION allowed=false down the control lane", async () => {
+  const request = escalateRequest("job-deny");
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-perm-2", elementId: "acp-permission" }]);
+  const { deps, frames } = sendSpy();
+
+  const result = await completePermissionEscalationAsHuman(data, engine, deps, {
+    permission: request,
+    userTaskKey: "ut-perm-2",
+    optionId: "deny",
+    operatorId: "op:ada",
+  });
+
+  assertEquals(result.completion.ok, true);
+  assertEquals(completed[0].variables, { optionId: "deny", allowed: false });
+  assertEquals(frames.length, 1);
+  const resolution = decodeResolution(frames[0]);
+  assertEquals(resolution.callId, "job-deny");
+  assertEquals(resolution.optionId, "deny");
+  assertEquals(resolution.allowed, false);
+  assertEquals(resolution.by, "operator");
+});
+
+test("a failed completion (no open task) NEVER sends a resolution — the block is only released on a real answer", async () => {
+  const request = escalateRequest("job-missing");
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine } = fakeEngine([]); // no open task with this key
+  const { deps, frames } = sendSpy();
+
+  const result = await completePermissionEscalationAsHuman(data, engine, deps, {
+    permission: request,
+    userTaskKey: "ut-nope",
+    optionId: "allow",
+    operatorId: "op:ada",
+  });
+
+  assertEquals(result.completion.ok, false);
+  assertEquals(result.resolution, undefined);
+  assertEquals(frames.length, 0);
+});
+
+// ── Convergence: the onPermissionResolve adapter and the completion door build the SAME frame ───────
+
+test("the exported onPermissionResolve adapter produces the SAME relay RESOLUTION as the completion door", async () => {
+  const request = escalateRequest("job-converge");
+  const stream = jobStream(request.callId);
+
+  // Path A: the completion-door path.
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine } = fakeEngine([{ userTaskKey: "ut-perm-3", elementId: "acp-permission" }]);
+  const doorSpy = sendSpy();
+  await completePermissionEscalationAsHuman(data, engine, doorSpy.deps, {
+    permission: request,
+    userTaskKey: "ut-perm-3",
+    optionId: "allow",
+    operatorId: "op:ada",
+  });
+
+  // Path B: the exported cockpit seam adapter, invoked with the cockpit-derived {callId, optionId, allowed}.
+  const seamSpy = sendSpy();
+  const onPermissionResolve = createOnPermissionResolve(seamSpy.deps);
+  onPermissionResolve({ callId: request.callId, optionId: "allow", allowed: true });
+
+  assertEquals(doorSpy.frames.length, 1);
+  assertEquals(seamSpy.frames.length, 1);
+  // Byte-identical frames: same lane, family, seq, and produce payload (stream + encoded chunk).
+  assertEquals(seamSpy.frames[0], doorSpy.frames[0]);
+  assertEquals(seamSpy.frames[0].payload.stream, stream);
+  // And they equal the pure builder's frame for the same decision + stream.
+  const pure = buildPermissionResolutionFrame(stream, { callId: request.callId, optionId: "allow", allowed: true, by: "operator" });
+  assertEquals(doorSpy.frames[0], pure.frame);
+});
+
+// ── yolo / opt-out: the bridge is bypassed by default ──────────────────────────────────────────────
+
+test("a yolo-policy request NEVER raises a user task and never emits a bridge resolution", () => {
+  const yolo: DerivedPermission = {
+    callId: "job-yolo",
+    policy: "yolo",
+    options: [{ optionId: "allow", name: "Allow", kind: "allow-once" }],
+    offset: 1,
+  };
+  // No row for yolo, even when the bridge is enabled (yolo auto-allows elsewhere; the bridge is inert).
+  assertEquals(permissionUserTaskRow(yolo, { userTaskKey: "ut-y", subjectKey: "hire-1" }, { enabled: true }), null);
+  // No completion door is invoked for yolo, so no send edge fires — nothing to assert beyond the null row:
+  // the bridge only ever emits from `completePermissionEscalationAsHuman`/`createOnPermissionResolve`.
+});
+
+test("the bridge is opt-in: a disabled bridge raises no row even for an escalate-policy request", () => {
+  const request = escalateRequest("job-off");
+  assertEquals(permissionUserTaskRow(request, { userTaskKey: "ut-off", subjectKey: "hire-1" }, { enabled: false }), null);
+});
+
+test("permissionEscalationEnabled defaults OFF and honours the truthy forms of the master switch", () => {
+  assertEquals(permissionEscalationEnabled({}), false);
+  assertEquals(permissionEscalationEnabled({ NANO_WORKFORCE_PERMISSION_ESCALATION: "off" }), false);
+  assertEquals(permissionEscalationEnabled({ NANO_WORKFORCE_PERMISSION_ESCALATION: "false" }), false);
+  for (const on of ["1", "true", "on", "yes", "TRUE", "On"]) {
+    assertEquals(permissionEscalationEnabled({ NANO_WORKFORCE_PERMISSION_ESCALATION: on }), true, `expected ${on} to enable`);
+  }
+});
+
+// ── Pure derivations ────────────────────────────────────────────────────────────────────────────
+
+test("optionKindAllows / permissionOptionAllows derive allow vs reject from the option kind (fail-closed)", () => {
+  assertEquals(optionKindAllows("allow-once"), true);
+  assertEquals(optionKindAllows("allow-always"), true);
+  assertEquals(optionKindAllows("reject-once"), false);
+  assertEquals(optionKindAllows("reject-always"), false);
+  const request = escalateRequest();
+  assertEquals(permissionOptionAllows(request, "allow"), true);
+  assertEquals(permissionOptionAllows(request, "deny"), false);
+  assertEquals(permissionOptionAllows(request, "unknown-option"), false); // fail-closed
+});
+
+test("permissionQuestion folds title + reason, falling back to the tool name", () => {
+  assertEquals(
+    permissionQuestion(escalateRequest()),
+    "Write /etc/hosts — The agent wants to modify a protected file.",
+  );
+  assertEquals(
+    permissionQuestion({ callId: "c", policy: "escalate", options: [], toolName: "run_shell", offset: 0 }),
+    "Permission requested for run_shell",
+  );
+});

package/app/agentic/permission-bridge.ts

@@ -0,0 +1,268 @@
+// The ACP permission → nano-workforce escalation bridge (issue #559, ADR 0056 — the advisory agentic
+// app-tier plane). It does NOT touch BPMN, the agent job envelope, or the worker⇄engine protocol.
+//
+// When an ACP-driven agent emits a permission REQUEST tagged `policy: "escalate"` on the relay lane
+// (a blocked `session/request_permission`), this bridge:
+//   1. raises it as an answerable row in the unified Tasks inbox (a new `ACP_PERMISSION_ELEMENT` kind,
+//      via the pure `buildUserTaskRow` derivation), carrying the request's title/reason as the question;
+//   2. lets a human operator answer Allow/Deny through the ONE canonical completion door
+//      (`completeEscalationAsHuman`), the exact seam every other escalation uses; then
+//   3. flows the answer BACK DOWN the relay as a permission RESOLUTION frame on the CONTROL lane (a
+//      permission answer is high-priority control), releasing the agent's blocked request.
+//
+// A `yolo`-policy request NEVER reaches this path (it auto-allows elsewhere), and the whole bridge is
+// OPT-IN per hire — the default (`NANO_WORKFORCE_PERMISSION_ESCALATION` off) is yolo: no user task, no
+// prompt, no bridge resolution.
+//
+// Derivation over duplication: the core is a set of PURE functions (raise the row / build the
+// resolution frame), with the side-effecting relay `send` and the completion door kept as thin edges.
+// Because the cockpit-render slice exposed a `RenderDerivedTranscriptOptions.onPermissionResolve` seam,
+// this module ALSO exports an adapter that produces an `onPermissionResolve` handler backed by the SAME
+// pure resolution builder, so the seam and the completion door converge on one bridge. Wiring the live
+// in-browser Allow/Deny of `pages/cockpit/mount.js` to this bridge is a deferred follow-up (there is no
+// in-repo cockpit boot site), OUT OF SCOPE here.
+import type { Frame } from "@nanobpm/agentic/protocol";
+import { RELAY_FAMILY } from "@nanobpm/agentic/relay";
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { type AgentCompleteResult, completeEscalationAsHuman } from "../agentCompletion.ts";
+import { readEnvOr } from "../contracts.ts";
+import { ACP_PERMISSION_ELEMENT, buildUserTaskRow, type UserTaskRow } from "../userTasks.ts";
+import type { RenderDerivedTranscriptOptions } from "./cockpit/transcript-derive.ts";
+import { jobStream } from "./correlation.ts";
+import {
+  type DerivedPermission,
+  encodeTranscriptEvent,
+  optionKindAllows,
+  type PermissionResolutionEvent,
+} from "./transcript-events.ts";
+
+/** The exact `onPermissionResolve` seam the cockpit-render slice exported — consumed VERBATIM (not
+ *  re-declared) so a drift in the cockpit's prop shape is a compile error here, never a silent skew. */
+export type OnPermissionResolve = NonNullable<RenderDerivedTranscriptOptions["onPermissionResolve"]>;
+
+/** Read the per-hire opt-in master switch for the permission-escalation bridge. Default OFF (yolo).
+ *  Governed by the one typed env schema (`NANO_WORKFORCE_PERMISSION_ESCALATION`, `app/contracts.ts`). */
+export function permissionEscalationEnabled(env: Record<string, string | undefined> = process.env): boolean {
+  const raw = readEnvOr("NANO_WORKFORCE_PERMISSION_ESCALATION", "off", env).toLowerCase();
+  return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
+}
+
+/** Re-exported canonical allow/deny derivation (defined beside `PermissionOptionKind` in
+ *  `transcript-events.ts`). The bridge and the cockpit render seam share this ONE implementation, so the
+ *  completion-door path and the `onPermissionResolve` seam can never disagree on what a chosen option means. */
+export { optionKindAllows };
+
+/** Pure: whether the chosen `optionId` allows the action, derived from the REQUEST's own options.
+ *  Returns false for an unknown option (fail-closed — an unrecognised answer denies). */
+export function permissionOptionAllows(permission: DerivedPermission, optionId: string): boolean {
+  const option = permission.options.find((o) => o.optionId === optionId);
+  return option !== undefined && optionKindAllows(option.kind);
+}
+
+/** Pure: fold a permission request's `title`/`reason` (falling back to its `toolName`) into the one
+ *  human-readable `question` the Tasks inbox row shows. */
+export function permissionQuestion(permission: DerivedPermission): string {
+  const parts: string[] = [];
+  if (permission.title) parts.push(permission.title);
+  if (permission.reason) parts.push(permission.reason);
+  if (parts.length === 0 && permission.toolName) parts.push(`Permission requested for ${permission.toolName}`);
+  return parts.join(" — ");
+}
+
+/** The denormalised context a bridged permission request needs to raise its Tasks-inbox row. */
+export interface PermissionUserTaskContext {
+  /** The completable key the raised row carries (the operator answers this key through the door). */
+  readonly userTaskKey: string;
+  /** The subject the row is keyed on (the hire / job / session the permission belongs to). */
+  readonly subjectKey: string;
+  readonly subjectTitle?: string | null;
+  readonly subjectUrl?: string | null;
+  readonly processKey?: string | null;
+}
+
+/** Pure: the Tasks-inbox row an escalate-policy permission REQUEST raises, or `null` when the bridge is
+ *  disabled (opt-out default) or the policy is `yolo` (auto-allow — no user task, no prompt). The row is
+ *  the `ACP_PERMISSION_ELEMENT` kind, carrying the request's title/reason as its `question`, so a bridged
+ *  permission surfaces in the SAME inbox as every other escalation. */
+export function permissionUserTaskRow(
+  permission: DerivedPermission,
+  ctx: PermissionUserTaskContext,
+  opts: { enabled: boolean },
+  at?: string,
+): UserTaskRow | null {
+  if (!opts.enabled) return null;
+  if (permission.policy !== "escalate") return null;
+  return buildUserTaskRow(
+    {
+      userTaskKey: ctx.userTaskKey,
+      elementId: ACP_PERMISSION_ELEMENT,
+      subjectType: "agent",
+      subjectKey: ctx.subjectKey,
+      subjectTitle: ctx.subjectTitle,
+      subjectUrl: ctx.subjectUrl,
+      question: permissionQuestion(permission),
+      processKey: ctx.processKey,
+    },
+    at,
+  );
+}
+
+/** The chosen answer to a permission request: the option id and whether it allows the action. */
+export interface PermissionDecision {
+  readonly callId: string;
+  readonly optionId: string;
+  readonly allowed: boolean;
+  /** Provenance of the decision — an operator answer (default) or an auto policy. */
+  readonly by?: "operator" | "auto";
+}
+
+/** A produced permission RESOLUTION: the typed event, its encoded wire chunk, and the control-lane
+ *  relay frame that carries it back down to the blocked agent. */
+export interface PermissionResolution {
+  readonly event: PermissionResolutionEvent;
+  readonly chunk: string;
+  readonly frame: Frame;
+}
+
+/** Pure: the typed RESOLUTION event that releases a blocked `session/request_permission`. The `offset`
+ *  is a placeholder — `encodeTranscriptEvent` strips it (the hub assigns the authoritative offset). */
+export function buildPermissionResolutionEvent(decision: PermissionDecision): PermissionResolutionEvent {
+  return {
+    kind: "permission",
+    phase: "resolution",
+    offset: 0,
+    callId: decision.callId,
+    optionId: decision.optionId,
+    allowed: decision.allowed,
+    ...(decision.by !== undefined ? { by: decision.by } : {}),
+  };
+}
+
+/** Options for the wire framing of a resolution — the producer generation and per-stream sequence the
+ *  edge assigns. Both default to `0` so two independent callers with the same decision + stream produce
+ *  byte-identical frames (the convergence the completion door and the `onPermissionResolve` seam rely on). */
+export interface ResolutionFrameOptions {
+  readonly seq?: number;
+  readonly incarnation?: number;
+}
+
+/** Pure: encode a permission RESOLUTION into the CONTROL-lane relay frame that carries it back down to
+ *  the blocked agent. The chunk speaks the one envelope grammar (`encodeTranscriptEvent`); the frame
+ *  rides the control lane because a permission answer is high-priority control. This is the single
+ *  builder BOTH the completion-door path and the `onPermissionResolve` adapter converge on. */
+export function buildPermissionResolutionFrame(
+  stream: string,
+  decision: PermissionDecision,
+  opts: ResolutionFrameOptions = {},
+): PermissionResolution {
+  const event = buildPermissionResolutionEvent(decision);
+  const chunk = encodeTranscriptEvent(event);
+  const frame: Frame = {
+    lane: "control",
+    family: RELAY_FAMILY,
+    seq: opts.seq ?? 0,
+    payload: { op: "produce", stream, incarnation: opts.incarnation ?? 0, chunk },
+  };
+  return { event, chunk, frame };
+}
+
+/** The thin side-effecting edge: emit a resolution frame down the relay to the blocked agent. */
+export type RelayResolutionSend = (frame: Frame) => void;
+
+/** The bridge's edge dependencies: the relay `send`, plus how a permission `callId` maps to the relay
+ *  stream its resolution travels back down and the frame's per-stream `seq`/`incarnation`. */
+export interface PermissionBridgeDeps {
+  /** Emit the RESOLUTION frame down the relay (control lane). */
+  readonly send: RelayResolutionSend;
+  /** Resolve the relay stream a permission `callId` is answered on. Defaults to `job:<callId>` (the
+   *  request's `callId` is the blocked job's key); a bridge with richer correlation supplies its own. */
+  readonly streamForCallId?: (callId: string) => string;
+  /** The frame `seq` for a resolution on a `callId`'s stream (default 0). */
+  readonly seq?: (callId: string) => number;
+  /** The producer generation stamped on the resolution frame (default 0). */
+  readonly incarnation?: number;
+}
+
+function resolveStream(deps: PermissionBridgeDeps, callId: string): string {
+  return deps.streamForCallId?.(callId) ?? jobStream(callId);
+}
+
+function sendResolution(deps: PermissionBridgeDeps, stream: string, decision: PermissionDecision): PermissionResolution {
+  const resolution = buildPermissionResolutionFrame(stream, decision, {
+    seq: deps.seq?.(decision.callId),
+    incarnation: deps.incarnation,
+  });
+  deps.send(resolution.frame);
+  return resolution;
+}
+
+/**
+ * The exported adapter behind the cockpit slice's `RenderDerivedTranscriptOptions.onPermissionResolve`
+ * seam. Given the bridge's relay-send dependency, returns a handler matching the seam signature verbatim
+ * that emits the SAME control-lane RESOLUTION frame the completion-door path emits (both route through
+ * `buildPermissionResolutionFrame`). Provided so a future cockpit boot site can plug it in — this module
+ * does NOT wire it into a live boot (there is no in-repo cockpit boot site; that is a deferred follow-up).
+ */
+export function createOnPermissionResolve(deps: PermissionBridgeDeps): OnPermissionResolve {
+  return (resolution) => {
+    sendResolution(deps, resolveStream(deps, resolution.callId), {
+      callId: resolution.callId,
+      optionId: resolution.optionId,
+      allowed: resolution.allowed,
+      by: "operator",
+    });
+  };
+}
+
+/** What an operator supplies to answer a bridged permission escalation through the completion door. */
+export interface PermissionEscalationAnswer {
+  /** The request being answered (its `callId`/`options` are the source of truth for the resolution). */
+  readonly permission: DerivedPermission;
+  /** The completable key of the raised Tasks-inbox row. */
+  readonly userTaskKey: string;
+  /** The relay stream the resolution travels back down. Defaults to the deps' `streamForCallId`. */
+  readonly stream?: string;
+  /** The option the operator chose (Allow/Deny). `allowed` is derived from the request's option kind. */
+  readonly optionId: string;
+  /** The operator's audit handle. */
+  readonly operatorId: string;
+}
+
+/** The result of answering a bridged permission escalation: the completion-door result plus (on
+ *  success) the RESOLUTION that was sent down the relay. */
+export interface PermissionEscalationResult {
+  readonly completion: AgentCompleteResult;
+  readonly resolution?: PermissionResolution;
+}
+
+/**
+ * Answer a bridged permission escalation AS A HUMAN operator through the ONE canonical completion door
+ * (`completeEscalationAsHuman`), then flow the answer back down the relay as a control-lane RESOLUTION
+ * frame that releases the agent's blocked `session/request_permission`. The completion and the relay
+ * `send` are the thin edges; the resolution itself is the pure `buildPermissionResolutionFrame`, so this
+ * converges with the `onPermissionResolve` adapter on one bridge. When the completion door refuses the
+ * task (a 404-style no-op or a failed engine completion) NO resolution is sent — the block is only
+ * released when the operator's answer actually took.
+ */
+export async function completePermissionEscalationAsHuman(
+  data: DataLayer,
+  engine: EngineClient,
+  deps: PermissionBridgeDeps,
+  answer: PermissionEscalationAnswer,
+): Promise<PermissionEscalationResult> {
+  const allowed = permissionOptionAllows(answer.permission, answer.optionId);
+  const completion = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: answer.userTaskKey,
+    variables: { optionId: answer.optionId, allowed },
+    operatorId: answer.operatorId,
+  });
+  if (!completion.ok) return { completion };
+  const stream = answer.stream ?? resolveStream(deps, answer.permission.callId);
+  const resolution = sendResolution(deps, stream, {
+    callId: answer.permission.callId,
+    optionId: answer.optionId,
+    allowed,
+    by: "operator",
+  });
+  return { completion, resolution };
+}

package/app/agentic/transcript-events.ts

@@ -143,6 +143,15 @@ 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";
 
+/** Pure, canonical: does a permission option kind ALLOW (true) or REJECT (false) the proposed action?
+ *  The `allow-*` vs `reject-*` prefix is the single source of truth. This lives beside
+ *  {@link PermissionOptionKind} so every consumer (the cockpit render seam and the permission-escalation
+ *  bridge) derives allow/deny from ONE implementation — the two paths can never disagree on what a
+ *  chosen option means (no drift surface). */
+export function optionKindAllows(kind: PermissionOptionKind): boolean {
+  return kind === "allow-once" || kind === "allow-always";
+}
+
 /** One offered permission option (ACP `options[]` member): a stable id, a label, and its kind. */
 export interface PermissionOption {
   readonly optionId: string;

package/app/contracts.ts

@@ -292,6 +292,14 @@ export const ENV_CONTRACTS = {
     owner: "app/agentGuide.ts",
     semantics: "Engine transport selector.",
   },
+  NANO_WORKFORCE_PERMISSION_ESCALATION: {
+    category: "env",
+    name: "NANO_WORKFORCE_PERMISSION_ESCALATION",
+    owner: "app/agentic/permission-bridge.ts",
+    semantics:
+      "Per-hire opt-in master switch for the ACP permission-escalation bridge (issue #559, ADR 0056). When on ('1'/'true'/'on'/'yes'), an escalate-policy session/request_permission is bridged to a nano-workforce Tasks-inbox escalation and the operator's Allow/Deny answer is flowed back down the relay as a permission RESOLUTION. Default OFF → yolo auto-allow: no user task, no prompt. A yolo-policy request never reaches the bridge regardless.",
+    default: "off",
+  },
 } as const satisfies Record<string, EnvContract>;
 
 /** The set of declared config-key names — the single typed vocabulary of env keys. */

package/app/userTasks.ts

@@ -44,6 +44,15 @@ export const PR_WAIT_ANSWER_ELEMENT = "wait-answer";
  *  canonical `completeUserTask` door and surfaced in this same Tasks inbox. */
 export const PR_WAIT_MERGE_ANSWER_ELEMENT = "wait-merge-answer";
 
+/** The ACP permission-prompt escalation (issue #559, ADR 0056) — the Tasks-inbox kind a bridged
+ *  `session/request_permission` surfaces under when an escalate-policy agent asks a human to Allow/Deny
+ *  a proposed action. Unlike the other escalation elements this is NOT a BPMN user-task element; it is
+ *  the advisory app-tier permission bridge's row kind, raised from a derived permission REQUEST and
+ *  answered through the same canonical `completeEscalationAsHuman` door as every other escalation, with
+ *  the operator's answer flowed back down the relay as a permission RESOLUTION. The bridge is OPT-IN per
+ *  hire — a `yolo`-policy request never reaches this path (see `app/agentic/permission-bridge.ts`). */
+export const ACP_PERMISSION_ELEMENT = "acp-permission";
+
 /** One row per currently-open native user-task escalation, denormalised for the Tasks page. Keyed on
  *  the completable `user_task_key` (a task is open at most once). Present iff the engine reports the
  *  task open; `pollUserTasks` deletes it once the task is gone. */
@@ -83,6 +92,7 @@ export const USER_TASK_KIND_LABELS: Readonly<Record<string, string>> = {
   [PR_WAIT_MERGE_ANSWER_ELEMENT]: "PR merge",
   [CONFORMANCE_ESCALATION_ELEMENT]: "Conformance review",
   [DELIVERY_HUMAN_ELEMENT]: "Delivery: human step",
+  [ACP_PERMISSION_ELEMENT]: "Agent permission",
 };
 
 /** The Tasks-inbox label for an open user-task `elementId`, or `undefined` when the element is not a
@@ -99,7 +109,7 @@ export function userTaskKindLabel(elementId: string): string | undefined {
 export interface UserTaskContext {
   userTaskKey: string;
   elementId: string;
-  subjectType: "feature" | "plan" | "pr" | "delivery";
+  subjectType: "feature" | "plan" | "pr" | "delivery" | "agent";
   subjectKey: string;
   /** The subject's human-readable title from its own row (`feature_runs`/`plans`/`pull_requests`.
    *  `title`). Optional/blank tolerated — `buildUserTaskRow` coalesces it to `subjectKey` so the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.147.0",
+  "version": "0.148.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",