@syengup/friday-channel-next 0.1.39 → 1.0.0

package/src/approval/friday-approval-capability.ts

@@ -0,0 +1,227 @@
+// Friday Next exec/plugin approval capability.
+//
+// Lets the Friday app receive tool-execution approval REQUESTS (e.g. a Codex model wanting to run a
+// shell command that needs confirmation) and submit allow/deny DECISIONS — instead of those
+// approvals only reaching the gateway's built-in ControlUI.
+//
+// Model: unlike Slack (a separate approver list authorized per-account), friday-next uses a
+// device-owner model — the device that owns the originating session is the approver. HTTP requests
+// already carry the channel bearer token, so per-sender authorization happens at the route layer;
+// here we only resolve WHICH device a request belongs to (its session's device) and deliver the
+// prompt there over SSE. The decision round-trips via POST /friday-next/approvals/{id}.
+//
+// We intentionally do NOT set a `delivery.shouldSuppressForwardingFallback` adapter, so enabling
+// this stays additive: ControlUI keeps working as a fallback while the app surface is the primary.
+
+import { createChannelApprovalNativeRuntimeAdapter } from "openclaw/plugin-sdk/approval-handler-runtime";
+import type { ChannelApprovalCapability } from "openclaw/plugin-sdk/channel-contract";
+import { sseEmitter } from "../sse/emitter.js";
+import { resolveFridayDeviceIdForSessionKey } from "../friday-session.js";
+import { createFridayNextLogger } from "../logging.js";
+
+const logger = createFridayNextLogger("approval");
+
+/** SSE payload the app receives for an approval lifecycle event. `op` is the phase. */
+export interface FridayApprovalPayload {
+  op: "request" | "resolved" | "expired";
+  approvalId: string;
+  kind: "exec" | "plugin";
+  title: string;
+  description?: string | null;
+  // exec
+  commandText?: string | null;
+  commandPreview?: string | null;
+  cwd?: string | null;
+  host?: string | null;
+  // plugin
+  toolName?: string | null;
+  severity?: string | null;
+  metadata: { label: string; value: string }[];
+  actions: { decision: string; label: string; style: string }[];
+  expiresAtMs?: number | null;
+  decision?: string | null;
+  resolvedBy?: string | null;
+  sessionKey?: string | null;
+  runId?: string | null;
+  deviceId: string;
+  ts: number;
+}
+
+interface PreparedTarget {
+  deviceId: string;
+}
+interface PendingEntry {
+  deviceId: string;
+  approvalId: string;
+}
+
+/** Pull the originating sessionKey out of an exec/plugin approval request (`request.request.*`). */
+function sessionKeyOf(request: unknown): string | undefined {
+  const inner = (request as { request?: { sessionKey?: unknown } } | undefined)?.request;
+  const sk = inner?.sessionKey;
+  return typeof sk === "string" && sk.trim() ? sk.trim() : undefined;
+}
+
+/** Resolve the friday device that owns this approval's session, if any. */
+function deviceForRequest(request: unknown): string | undefined {
+  const sk = sessionKeyOf(request);
+  if (!sk) return undefined;
+  const dev = resolveFridayDeviceIdForSessionKey(sk);
+  return dev ? dev.toUpperCase() : undefined;
+}
+
+/** Build the normalized app payload from a pending/resolved/expired approval view. */
+export function buildPayload(params: {
+  op: FridayApprovalPayload["op"];
+  view: Record<string, unknown>;
+  request: unknown;
+  deviceId: string;
+}): FridayApprovalPayload {
+  const { op, view, request, deviceId } = params;
+  const str = (v: unknown): string | null => (typeof v === "string" ? v : null);
+  const num = (v: unknown): number | null => (typeof v === "number" ? v : null);
+  const actionsRaw = Array.isArray(view.actions) ? (view.actions as Record<string, unknown>[]) : [];
+  const metaRaw = Array.isArray(view.metadata) ? (view.metadata as Record<string, unknown>[]) : [];
+  return {
+    op,
+    approvalId: str(view.approvalId) ?? "",
+    kind: view.approvalKind === "plugin" ? "plugin" : "exec",
+    title: str(view.title) ?? "",
+    description: str(view.description),
+    commandText: str(view.commandText),
+    commandPreview: str(view.commandPreview),
+    cwd: str(view.cwd),
+    host: str(view.host),
+    toolName: str(view.toolName),
+    severity: str(view.severity),
+    metadata: metaRaw.map((m) => ({ label: str(m.label) ?? "", value: str(m.value) ?? "" })),
+    actions: actionsRaw.map((a) => ({
+      decision: str(a.decision) ?? "",
+      label: str(a.label) ?? "",
+      style: str(a.style) ?? "secondary",
+    })),
+    expiresAtMs: num(view.expiresAtMs),
+    decision: str(view.decision),
+    resolvedBy: str(view.resolvedBy),
+    sessionKey: sessionKeyOf(request) ?? null,
+    runId: sseEmitter.getLastRunIdForDevice(deviceId),
+    deviceId,
+    ts: Date.now(),
+  };
+}
+
+function emitApproval(deviceId: string, payload: FridayApprovalPayload): void {
+  sseEmitter.broadcast({ type: "approval", data: { ...payload } }, deviceId, true);
+}
+
+const fridayApprovalNativeRuntime = createChannelApprovalNativeRuntimeAdapter<
+  FridayApprovalPayload,
+  PreparedTarget,
+  PendingEntry,
+  never,
+  FridayApprovalPayload
+>({
+  eventKinds: ["exec", "plugin"],
+  availability: {
+    isConfigured: () => true,
+    shouldHandle: ({ request }) => deviceForRequest(request) !== undefined,
+  },
+  presentation: {
+    buildPendingPayload: ({ request, view }) => {
+      const deviceId = deviceForRequest(request) ?? "";
+      return buildPayload({
+        op: "request",
+        view: view as unknown as Record<string, unknown>,
+        request,
+        deviceId,
+      });
+    },
+    buildResolvedResult: ({ request, view }) => {
+      const deviceId = deviceForRequest(request) ?? "";
+      return {
+        kind: "update",
+        payload: buildPayload({
+          op: "resolved",
+          view: view as unknown as Record<string, unknown>,
+          request,
+          deviceId,
+        }),
+      };
+    },
+    buildExpiredResult: ({ request, view }) => {
+      const deviceId = deviceForRequest(request) ?? "";
+      return {
+        kind: "update",
+        payload: buildPayload({
+          op: "expired",
+          view: view as unknown as Record<string, unknown>,
+          request,
+          deviceId,
+        }),
+      };
+    },
+  },
+  transport: {
+    prepareTarget: ({ plannedTarget, request }) => {
+      const planned =
+        typeof plannedTarget?.target?.to === "string" && plannedTarget.target.to.trim()
+          ? plannedTarget.target.to.trim().toUpperCase()
+          : undefined;
+      const deviceId = planned ?? deviceForRequest(request);
+      if (!deviceId) return null;
+      return { dedupeKey: `friday-approval:${deviceId}`, target: { deviceId } };
+    },
+    deliverPending: ({ preparedTarget, pendingPayload }) => {
+      const deviceId = preparedTarget.deviceId;
+      logger.info(`deliver approval ${pendingPayload.approvalId} kind=${pendingPayload.kind} -> ${deviceId}`);
+      emitApproval(deviceId, { ...pendingPayload, deviceId });
+      return { deviceId, approvalId: pendingPayload.approvalId };
+    },
+    updateEntry: async ({ entry, payload }) => {
+      emitApproval(entry.deviceId, { ...payload, deviceId: entry.deviceId });
+    },
+    deleteEntry: async ({ entry, phase }) => {
+      emitApproval(entry.deviceId, {
+        op: phase === "resolved" ? "resolved" : "expired",
+        approvalId: entry.approvalId,
+        kind: "exec",
+        title: "",
+        metadata: [],
+        actions: [],
+        deviceId: entry.deviceId,
+        ts: Date.now(),
+      });
+    },
+  },
+  observe: {
+    onDeliveryError: ({ error }) => {
+      logger.warn(`approval delivery failed: ${String(error)}`);
+    },
+  },
+});
+
+/**
+ * friday-next approval capability. `native` declares delivery to the originating device's session;
+ * `nativeRuntime` builds the app payload and ferries it over SSE. No `delivery` suppressor → additive
+ * with ControlUI.
+ */
+export const fridayApprovalCapability: ChannelApprovalCapability = {
+  native: {
+    describeDeliveryCapabilities: ({ request }) => {
+      const enabled = deviceForRequest(request) !== undefined;
+      return {
+        enabled,
+        preferredSurface: "origin",
+        supportsOriginSurface: true,
+        supportsApproverDmSurface: false,
+      };
+    },
+    resolveOriginTarget: ({ request }) => {
+      const deviceId = deviceForRequest(request);
+      return deviceId ? { to: deviceId } : null;
+    },
+  },
+  // Cast widens the parameterized adapter to the field's `unknown`-typed shape (function-param
+  // contravariance). Same escape hatch Slack uses for its lazy runtime adapter.
+  nativeRuntime: fridayApprovalNativeRuntime as unknown as ChannelApprovalCapability["nativeRuntime"],
+};

package/src/channel.ts

@@ -10,6 +10,9 @@ import os from "node:os";
 import path from "node:path";
 import { createChatChannelPlugin } from "openclaw/plugin-sdk/core";
 import { waitUntilAbort } from "openclaw/plugin-sdk/channel-lifecycle";
+import { registerChannelRuntimeContext } from "openclaw/plugin-sdk/channel-runtime-context";
+import { CHANNEL_APPROVAL_NATIVE_RUNTIME_CONTEXT_CAPABILITY } from "openclaw/plugin-sdk/approval-handler-adapter-runtime";
+import type { ChannelGatewayContext } from "openclaw/plugin-sdk/channel-contract";
 import { createFridayNextLogger } from "./logging.js";
 import type { ChannelAccountSnapshot } from "openclaw/plugin-sdk/status-helpers";
 import { saveMediaBuffer } from "openclaw/plugin-sdk/media-store";
@@ -24,6 +27,7 @@ import {
 } from "./friday-session.js";
 import { getRunRoute } from "./run-metadata.js";
 import { getLastFridayInboundAt } from "./friday-inbound-stats.js";
+import { fridayApprovalCapability } from "./approval/friday-approval-capability.js";
 
 const logger = createFridayNextLogger("channel");
 const CHANNEL_ID = "friday-next" as const;
@@ -113,7 +117,22 @@ const fridayLifecycle = {
  * (reload/shutdown) so the channel stays `running:true` and continuously deliverable.
  */
 const fridayGateway = {
-  startAccount: async (ctx: { abortSignal: AbortSignal }): Promise<void> => {
+  startAccount: async (ctx: ChannelGatewayContext): Promise<void> => {
+    // Activate exec/plugin approval delivery to the app. The gateway's approval-handler bootstrap
+    // only wires up our `approvalCapability` once the channel registers an "approval.native" runtime
+    // context (the registration event is the gate — without it approvals silently skip friday-next
+    // and only reach ControlUI). friday-next's nativeRuntime needs no per-account state — it resolves
+    // the target device from each request's sessionKey via global singletons — so context is empty.
+    if (ctx.channelRuntime) {
+      registerChannelRuntimeContext({
+        channelRuntime: ctx.channelRuntime,
+        channelId: CHANNEL_ID,
+        accountId: ctx.accountId,
+        capability: CHANNEL_APPROVAL_NATIVE_RUNTIME_CONTEXT_CAPABILITY,
+        context: {},
+        abortSignal: ctx.abortSignal,
+      });
+    }
     await waitUntilAbort(ctx.abortSignal);
   },
 };
@@ -342,3 +361,8 @@ export const fridayNextChannelPlugin = createChatChannelPlugin({
     },
   },
 });
+
+// Attach exec/plugin approval delivery to the app. `createChatChannelPlugin` has no config slot for
+// it, so it's set on the returned plugin object; setting it auto-registers the native approval
+// handler via the gateway's approval bootstrap. Additive with ControlUI (no forwarding suppressor).
+fridayNextChannelPlugin.approvalCapability = fridayApprovalCapability;

package/src/codex-reasoning-config.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { hasTopLevelSummaryKey } from "./codex-reasoning-config.js";
+
+describe("hasTopLevelSummaryKey", () => {
+  it("returns true when the key is a top-level entry", () => {
+    expect(hasTopLevelSummaryKey('model_reasoning_summary = "detailed"\n')).toBe(true);
+    expect(
+      hasTopLevelSummaryKey('model_reasoning_summary = "auto"\n\n[projects."/x"]\ntrust_level = "trusted"\n'),
+    ).toBe(true);
+  });
+
+  it("returns false when the file has no key", () => {
+    expect(hasTopLevelSummaryKey("")).toBe(false);
+    expect(hasTopLevelSummaryKey('[projects."/x"]\ntrust_level = "trusted"\n')).toBe(false);
+  });
+
+  it("treats a key nested under a [section] as NOT top-level (TOML scoping)", () => {
+    // This is the trap: appended after a table header the key belongs to that table, so Codex
+    // ignores it. Must be reported as absent so the caller prepends a real top-level key.
+    const nested = '[projects."/x"]\ntrust_level = "trusted"\nmodel_reasoning_summary = "detailed"\n';
+    expect(hasTopLevelSummaryKey(nested)).toBe(false);
+  });
+
+  it("ignores commented or partial matches", () => {
+    expect(hasTopLevelSummaryKey('# model_reasoning_summary = "detailed"\n')).toBe(false);
+    expect(hasTopLevelSummaryKey("model_reasoning_summary_extra = 1\n")).toBe(false);
+  });
+});

package/src/codex-reasoning-config.ts

@@ -0,0 +1,82 @@
+// Ensures the Codex app-server backend emits reasoning *summary* text so Friday can stream it.
+//
+// Background: OpenAI models authenticated via ChatGPT/OAuth run through OpenClaw's Codex
+// app-server backend. That backend sends `reasoning_effort` per turn but never requests a
+// reasoning summary, and OpenClaw exposes no `openclaw.json` lever for it. Without a summary the
+// model's reasoning stays encrypted (`encrypted_content`) and no reasoning text reaches the
+// channel — so the Friday app shows no streaming "thinking" for Codex models.
+//
+// The only switch that makes Codex return summary text is the Codex CLI's own
+// `model_reasoning_summary` key in `~/.openclaw/agents/<id>/agent/codex-home/config.toml`.
+// We keep the fix on the plugin side by asserting that key on activation (idempotently, for every
+// agent that has a codex-home), so it survives OpenClaw rewrites of that file across restarts.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const CONFIG_KEY = "model_reasoning_summary";
+// "detailed" is the value verified end-to-end (reasoning streamed to the app). Codex also accepts
+// "auto"/"concise"; tune here if the summaries feel too verbose.
+const SUMMARY_VALUE = "detailed";
+
+function resolveOpenClawHome(): string {
+  const env = process.env.OPENCLAW_HOME?.trim();
+  return env && env.length > 0 ? env : join(homedir(), ".openclaw");
+}
+
+/**
+ * True if a top-level `model_reasoning_summary` key already exists. TOML scoping matters: a key is
+ * only top-level (and thus honored by Codex) if it appears before the first `[section]` header, so
+ * we stop scanning at the first table header.
+ */
+export function hasTopLevelSummaryKey(content: string): boolean {
+  for (const raw of content.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line.startsWith("[")) break;
+    if (new RegExp(`^${CONFIG_KEY}\\s*=`).test(line)) return true;
+  }
+  return false;
+}
+
+function ensureKeyInCodexHome(codexHome: string): "added" | "present" | "skip" {
+  const configPath = join(codexHome, "config.toml");
+  const header = `${CONFIG_KEY} = "${SUMMARY_VALUE}"\n`;
+  if (!existsSync(configPath)) {
+    writeFileSync(configPath, header, "utf8");
+    return "added";
+  }
+  const content = readFileSync(configPath, "utf8");
+  if (hasTopLevelSummaryKey(content)) return "present";
+  // Prepend so the key stays top-level even if the file starts with a `[section]` table.
+  writeFileSync(configPath, `${header}\n${content}`, "utf8");
+  return "added";
+}
+
+/**
+ * Best-effort: ensure every agent's Codex config requests a reasoning summary. Never throws —
+ * activation must not fail because of a config write. `log` receives a one-line summary per change.
+ */
+export function ensureCodexReasoningSummary(log: (msg: string) => void): void {
+  try {
+    const agentsDir = join(resolveOpenClawHome(), "agents");
+    if (!existsSync(agentsDir)) return;
+    for (const agentId of readdirSync(agentsDir)) {
+      const codexHome = join(agentsDir, agentId, "agent", "codex-home");
+      // Only touch agents Codex has actually initialized (codex-home exists). New agents are
+      // picked up on the next activation/restart.
+      if (!existsSync(codexHome)) continue;
+      try {
+        mkdirSync(codexHome, { recursive: true });
+        const result = ensureKeyInCodexHome(codexHome);
+        if (result === "added") {
+          log(`codex reasoning summary enabled (agent=${agentId})`);
+        }
+      } catch (err) {
+        log(`codex reasoning summary write failed (agent=${agentId}): ${String(err)}`);
+      }
+    }
+  } catch (err) {
+    log(`codex reasoning summary ensure failed: ${String(err)}`);
+  }
+}

package/src/e2e/subagent.e2e.test.ts

@@ -295,6 +295,9 @@ describe("subagent via sessions_spawn tool", () => {
         label: "cr",
         parentRunId: mainRunId,
         depth: 1,
+        // A1: annotation now ships stable identity (childSessionKey) + lifecycle status.
+        childSessionKey: childKey,
+        status: "running",
       });
     });
 
@@ -524,6 +527,9 @@ describe("subagent via sessions_spawn tool", () => {
         label: "reviewer",
         parentRunId: mainRunId,
         depth: 1,
+        // A1: annotation now ships stable identity (childSessionKey) + lifecycle status.
+        childSessionKey: childKeyA,
+        status: "running",
       });
 
       // sessions_spawn for B (nested from A's tool call — but parentRunId should come from the context)

package/src/friday-session.forward-agent.test.ts

@@ -16,6 +16,10 @@ import {
 } from "./agent/run-usage-accumulator.js";
 import { sseEmitter } from "./sse/emitter.js";
 import { toSessionStoreKey } from "./session/session-manager.js";
+import {
+  ensureSubagentFromSpawnTool,
+  resetForTest as resetSubagentRegistryForTest,
+} from "./agent/subagent-registry.js";
 
 describe("forwardAgentEventRaw (thinking delta rewrite)", () => {
   const runId = "run-thinking-test";
@@ -395,3 +399,126 @@ function commonPrefixLen(a: string, b: string): number {
   while (i < len && a.charCodeAt(i) === b.charCodeAt(i)) i++;
   return i;
 }
+
+// P1 of the subagent streaming redo (see subagent-streaming-redo-plan.md):
+// the plugin ships authoritative correlation keys so the app stops self-deriving identity.
+describe("forwardAgentEventRaw (subagent stable-identity fields: A1/A2/A3)", () => {
+  const sessionKey = "agent:main:friday-session-test";
+  const deviceId = "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE";
+  const childKey = "agent:main:subagent:abc";
+
+  type SubagentBroadcast = { type: string; data: Record<string, unknown> };
+
+  function subagentBroadcasts(phase: string): Record<string, unknown>[] {
+    return (sseEmitter.broadcast as ReturnType<typeof vi.fn>).mock.calls
+      .map((c) => c[0] as SubagentBroadcast)
+      .filter((m) => m.type === "subagent" && m.data.phase === phase)
+      .map((m) => m.data);
+  }
+
+  beforeEach(() => {
+    sseEmitter.resetForTest();
+    resetThinkingStreamAccumStateForTest();
+    resetOpenClawRunDeviceMappingForTest();
+    resetSubagentRegistryForTest();
+    registerFridaySessionDeviceMapping(sessionKey, deviceId);
+    vi.spyOn(sseEmitter, "broadcastToRun").mockImplementation(() => {});
+    vi.spyOn(sseEmitter, "broadcast").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  // A2: spawning carries the spawn tool-call id as a stable correlation key.
+  it("spawning event carries the spawn toolCallId", () => {
+    forwardAgentEventRaw({
+      runId: "parent-run",
+      seq: 1,
+      stream: "tool",
+      sessionKey,
+      data: {
+        name: "sessions_spawn",
+        phase: "start",
+        toolCallId: "tc-1",
+        args: { taskName: "weather" },
+      },
+    });
+
+    const spawning = subagentBroadcasts("spawning");
+    expect(spawning).toHaveLength(1);
+    expect(spawning[0].toolCallId).toBe("tc-1");
+    expect(spawning[0].childSessionKey).toBeNull();
+    expect(spawning[0].runId).toBeNull();
+    expect(spawning[0].label).toBe("weather");
+  });
+
+  // A1: a subagent's own agent-delta is annotated with childSessionKey + status.
+  it("subagent agent-delta annotation includes childSessionKey and status", () => {
+    ensureSubagentFromSpawnTool({
+      childSessionKey: childKey,
+      bareRunId: "sub-bare",
+      label: "weather",
+      deviceId,
+      parentRunId: "parent-run",
+      requesterSessionKey: sessionKey,
+    });
+
+    forwardAgentEventRaw({
+      runId: "sub-bare",
+      seq: 1,
+      stream: "thinking",
+      sessionKey: childKey, // subagent's own event → sessionKey === childSessionKey
+      data: { text: "looking up", delta: "looking up" },
+    });
+
+    expect(sseEmitter.broadcastToRun).toHaveBeenCalledTimes(1);
+    const payload = (sseEmitter.broadcastToRun as ReturnType<typeof vi.fn>).mock.calls[0][1].data;
+    const subagent = payload.subagent as Record<string, unknown>;
+    expect(subagent).toBeDefined();
+    expect(subagent.childSessionKey).toBe(childKey);
+    expect(subagent.status).toBe("running");
+    expect(subagent.label).toBe("weather");
+    expect(subagent.parentRunId).toBe("parent-run");
+  });
+
+  // A3: the parent's announce-summary lifecycle.start emits an explicit dismiss keyed by
+  // childSessionKey — replacing the app's fragile announce-runId string parsing.
+  it("announce-summary lifecycle.start emits a dismissed subagent event by childSessionKey", () => {
+    ensureSubagentFromSpawnTool({
+      childSessionKey: childKey,
+      bareRunId: "sub-bare",
+      label: "weather",
+      deviceId,
+      parentRunId: "parent-run",
+      requesterSessionKey: sessionKey,
+    });
+
+    const announceRunId = `announce:v1:${childKey}:sub-bare`;
+    forwardAgentEventRaw({
+      runId: announceRunId,
+      seq: 1,
+      stream: "lifecycle",
+      sessionKey, // parent's sessionKey, not the child's
+      data: { phase: "start" },
+    });
+
+    const dismissed = subagentBroadcasts("dismissed");
+    expect(dismissed).toHaveLength(1);
+    expect(dismissed[0].childSessionKey).toBe(childKey);
+    expect(dismissed[0].runId).toBe("sub-bare");
+    expect(dismissed[0].parentRunId).toBe("parent-run");
+  });
+
+  // A3 must not fire on ordinary (non-announce) lifecycle.start frames.
+  it("does not emit dismissed for a normal lifecycle.start", () => {
+    forwardAgentEventRaw({
+      runId: "parent-run",
+      seq: 1,
+      stream: "lifecycle",
+      sessionKey,
+      data: { phase: "start" },
+    });
+    expect(subagentBroadcasts("dismissed")).toHaveLength(0);
+  });
+});

package/src/friday-session.ts

@@ -9,6 +9,8 @@ import type { FridaySessionUsagePayload } from "./session-usage-snapshot.js";
 import { readSessionUsageSnapshotFromStore } from "./session-usage-store.js";
 import {
   lookupByRunId,
+  lookupByChildSessionKey,
+  parseAnnounceRunId,
   registerSessionKeyForRun,
   registerSpawnIntent,
   consumeSpawnIntent,
@@ -31,6 +33,27 @@ export function resetThinkingStreamAccumStateForTest(): void {
   lastThinkingTextByRun.clear();
 }
 
+/**
+ * Runs backed by the OpenClaw Codex app-server backend (model api `openai-chatgpt-responses`).
+ * They emit their activity under a `codex_app_server.*` stream namespace and — unlike the embedded
+ * runner — do NOT put reasoning text on the agent-event bus (`stream: "thinking"`); that text only
+ * arrives via the dispatch `onReasoningStream` callback. Likewise exec stdout never reaches the
+ * `command_output` stream. We mark a run as Codex the first time we see any `codex_app_server.*`
+ * frame so the message handler / tool hooks know to synthesize the missing `thinking` /
+ * `command_output` events for it (and ONLY for it — embedded runs already get both via the bus).
+ */
+const codexRunIds = new Set<string>();
+
+/** True once a `codex_app_server.*` frame has been seen for this run. */
+export function isCodexRun(runId: string): boolean {
+  return codexRunIds.has(runId);
+}
+
+/** Vitest-only */
+export function resetCodexRunTrackingForTest(): void {
+  codexRunIds.clear();
+}
+
 /**
  * OpenClaw `runId` → device UUID (uppercase).
  * When `lifecycle.end` / `error` is emitted, the gateway may call `clearAgentRunContext` before this extension's
@@ -234,7 +257,13 @@ function completeAgentEventForward(params: {
   deviceIdRaw: string;
   outgoingData: Record<string, unknown>;
   isTerminalLifecycle: boolean;
-  subagentMeta?: { label?: string; parentRunId?: string; depth: number };
+  subagentMeta?: {
+    label?: string;
+    parentRunId?: string;
+    depth: number;
+    childSessionKey?: string;
+    status?: string;
+  };
 }): void {
   const { evt, sk, deviceIdRaw, outgoingData, isTerminalLifecycle, subagentMeta } = params;
 
@@ -338,6 +367,12 @@ export function forwardAgentEventRaw(evt: ForwardAgentEventArgs): void {
 
   openClawRunIdToDeviceId.set(evt.runId, deviceIdRaw.toUpperCase());
 
+  // Flag Codex app-server runs so the message handler / tool hooks synthesize the `thinking` /
+  // `command_output` events that this backend never emits on the bus (see `isCodexRun`).
+  if (typeof evt.stream === "string" && evt.stream.startsWith("codex_app_server")) {
+    codexRunIds.add(evt.runId);
+  }
+
   // Register sessionKey → runId so we can resolve parentRunId
   if (sk && evt.stream === "lifecycle" && evt.data.phase === "start") {
     registerSessionKeyForRun(sk, evt.runId);
@@ -367,6 +402,10 @@ export function forwardAgentEventRaw(evt: ForwardAgentEventArgs): void {
             phase: "spawning",
             childSessionKey: null,
             runId: null,
+            // A2: the spawn tool-call id is the only stable correlation key before the
+            // gateway assigns childSessionKey/runId — the app mints the placeholder window
+            // under it, then rekeys to childSessionKey on spawned.
+            toolCallId,
             label: intent.label ?? null,
             parentRunId: intent.parentRunId,
             depth: intent.depth,
@@ -408,6 +447,9 @@ export function forwardAgentEventRaw(evt: ForwardAgentEventArgs): void {
             phase: "spawned",
             runId: compoundRunId,
             childSessionKey: entry.childSessionKey,
+            // A2: echo the spawn toolCallId so the app deterministically links this
+            // spawned event to the placeholder window it minted at spawning time.
+            toolCallId: toolCallId || null,
             label: entry.label ?? null,
             parentRunId: entry.parentRunId ?? null,
             depth: entry.depth,
@@ -419,6 +461,33 @@ export function forwardAgentEventRaw(evt: ForwardAgentEventArgs): void {
     }
   }
 
+  // Phase 3 (A3): announce-summary delivery to the parent. OpenClaw emits the parent's
+  // `lifecycle.start` under the announce compound runId once a subagent's result is being
+  // folded back in. We parse the authoritative childSessionKey here (the registry already
+  // knows how) and broadcast an explicit `dismissed` subagent event, so the app removes the
+  // settled window by childSessionKey instead of re-parsing the announce runId itself.
+  if (evt.stream === "lifecycle" && evt.data.phase === "start") {
+    const announced = parseAnnounceRunId(evt.runId);
+    if (announced) {
+      const entry =
+        lookupByChildSessionKey(announced.childSessionKey) ?? lookupByRunId(evt.runId);
+      sseEmitter.broadcast(
+        {
+          type: "subagent",
+          data: {
+            phase: "dismissed",
+            childSessionKey: entry?.childSessionKey ?? announced.childSessionKey,
+            runId: entry?.runId ?? announced.bareRunId ?? null,
+            parentRunId: entry?.parentRunId ?? null,
+            depth: entry?.depth ?? 1,
+            deviceId: deviceIdRaw,
+          },
+        },
+        deviceIdRaw,
+      );
+    }
+  }
+
   const subagentEntry = lookupByRunId(evt.runId);
   // Only annotate events that originate from the subagent itself
   // (sessionKey matches childSessionKey). Main-agent delivery events
@@ -429,6 +498,11 @@ export function forwardAgentEventRaw(evt: ForwardAgentEventArgs): void {
         label: subagentEntry.label,
         parentRunId: subagentEntry.parentRunId,
         depth: subagentEntry.depth,
+        // A1: ship the authoritative childSessionKey + lifecycle status on every
+        // subagent agent-delta so the app routes/identifies by stable keys instead of
+        // guessing from runId.
+        childSessionKey: subagentEntry.childSessionKey,
+        status: subagentEntry.status,
       }
     : undefined;
 
@@ -453,6 +527,7 @@ export function forwardAgentEventRaw(evt: ForwardAgentEventArgs): void {
     }
     if (phase === "end" || phase === "error") {
       lastThinkingTextByRun.delete(evt.runId);
+      codexRunIds.delete(evt.runId);
     }
   }