fix: stream tool summaries early and tool output

CHANGELOG.md

@@ -23,9 +23,11 @@
 - Block streaming: drop final payloads after soft chunking to keep Discord order intact.
 - Gmail hooks: resolve gcloud Python to a real executable when PATH uses mise shims — thanks @joargp.
 - Control UI: generate UUIDs when `crypto.randomUUID()` is unavailable over HTTP — thanks @ratulsarna.
+- Control UI: stream live tool output cards in Chat (agent events include sessionKey).
 - Agent: add soft block-stream chunking (800–1200 chars default) with paragraph/newline preference.
 - Agent tools: scope the Discord tool to Discord surface runs.
 - Agent tools: format verbose tool summaries without brackets, with unique emojis and `tool: detail` style.
+- Agent tools: emit verbose tool summaries at tool start (no debounce).
 - Gateway: split server helpers/tests into hooks/session-utils/ws-log/net modules for better isolation; add unit coverage for hooks/session utils/ws log.
 - Gateway: extract WS method handling + HTTP/provider/constant helpers to shrink server wiring and improve testability.
 - Onboarding: fix Control UI basePath usage when showing/opening gateway URLs.
@@ -108,6 +110,7 @@
 - Skills: add tmux-first coding-agent skill + `requires.anyBins` gate for multi-CLI setup (thanks @sreekaransrinath).
 
 ### Fixes
+- macOS codesign: make ad-hoc signing opt-in with loud warnings and document TCC permission fragility — thanks @mcinteerj.
 - Gog calendar: format date ranges as RFC 3339 with timezone to satisfy Google Calendar API (thanks @jayhickey).
 - macOS onboarding: add scrollable page gutter for overflowing content (#105) — thanks @thewilloftheshadow.
 - Chat UI: keep the chat scrolled to the latest message after switching sessions.

docs/agent.md

@@ -14,6 +14,10 @@ You must set an agent home directory via `agent.workspace`. CLAWDIS uses this as
 
 Recommended: use `clawdis setup` to create `~/.clawdis/clawdis.json` if missing and initialize the workspace files.
 
+If `agent.sandbox` is enabled, non-main sessions can override this with
+per-session workspaces under `agent.sandbox.workspaceRoot` (see
+`docs/configuration.md`).
+
 ## Bootstrap files (injected)
 
 Inside `agent.workspace`, CLAWDIS expects these user-editable files:
@@ -85,6 +89,8 @@ via `agent.blockStreamingDefault: "off"` if you only want the final response.
 Tune the boundary via `agent.blockStreamingBreak` (`text_end` vs `message_end`; defaults to text_end).
 Control soft block chunking with `agent.blockStreamingChunk` (defaults to
 800–1200 chars; prefers paragraph breaks, then newlines; sentences last).
+Verbose tool summaries are emitted at tool start (no debounce); Control UI
+streams tool output via agent events when available.
 
 ## Configuration (minimal)
 

docs/control-ui.md

@@ -20,6 +20,7 @@ The dashboard settings panel lets you store a token; passwords are not persisted
 
 ## What it can do (today)
 - Chat with the model via Gateway WS (`chat.history`, `chat.send`, `chat.abort`)
+- Stream tool calls + live tool output cards in Chat (agent events)
 - Connections: WhatsApp/Telegram status + QR login + Telegram config (`providers.status`, `web.login.*`, `config.set`)
 - Instances: presence list + refresh (`system-presence`)
 - Sessions: list + per-session thinking/verbose overrides (`sessions.list`, `sessions.patch`)

docs/mac/permissions.md

@@ -0,0 +1,40 @@
+---
+summary: "macOS permission persistence (TCC) and signing requirements"
+read_when:
+  - Debugging missing or stuck macOS permission prompts
+  - Packaging or signing the macOS app
+  - Changing bundle IDs or app install paths
+---
+# macOS permissions (TCC)
+
+macOS permission grants are fragile. TCC associates a permission grant with the
+app's code signature, bundle identifier, and on-disk path. If any of those change,
+macOS treats the app as new and may drop or hide prompts.
+
+## Requirements for stable permissions
+- Same path: run the app from a fixed location (for Clawdis, `dist/Clawdis.app`).
+- Same bundle identifier: changing the bundle ID creates a new permission identity.
+- Signed app: unsigned or ad-hoc signed builds do not persist permissions.
+- Consistent signature: use a real Apple Development or Developer ID certificate
+  so the signature stays stable across rebuilds.
+
+Ad-hoc signatures generate a new identity every build. macOS will forget previous
+grants, and prompts can disappear entirely until the stale entries are cleared.
+
+## Recovery checklist when prompts disappear
+1. Quit the app.
+2. Remove the app entry in System Settings -> Privacy & Security.
+3. Relaunch the app from the same path and re-grant permissions.
+4. If the prompt still does not appear, reset TCC entries with `tccutil` and try again.
+5. Some permissions only reappear after a full macOS restart.
+
+Example resets (replace bundle ID as needed):
+
+```bash
+sudo tccutil reset Accessibility com.clawdis.mac
+sudo tccutil reset ScreenCapture com.clawdis.mac
+sudo tccutil reset AppleEvents
+```
+
+If you are testing permissions, always sign with a real certificate. Ad-hoc
+builds are only acceptable for quick local runs where permissions do not matter.

docs/mac/signing.md

@@ -9,22 +9,24 @@ This app is usually built from `scripts/package-mac-app.sh`, which now:
 
 - sets a stable debug bundle identifier: `com.clawdis.mac.debug`
 - writes the Info.plist with that bundle id (override via `BUNDLE_ID=...`)
-- calls `scripts/codesign-mac-app.sh` to sign the main binary, bundled CLI, and app bundle so macOS treats each rebuild as the same signed bundle and keeps TCC permissions (notifications, accessibility, screen recording, mic, speech). Requires a valid signing identity.
+- calls `scripts/codesign-mac-app.sh` to sign the main binary, bundled CLI, and app bundle so macOS treats each rebuild as the same signed bundle and keeps TCC permissions (notifications, accessibility, screen recording, mic, speech). For stable permissions, use a real signing identity; ad-hoc is opt-in and fragile (see `docs/mac/permissions.md`).
 - uses `CODESIGN_TIMESTAMP=auto` by default; it enables trusted timestamps for Developer ID signatures. Set `CODESIGN_TIMESTAMP=off` to skip timestamping (offline debug builds).
 - inject build metadata into Info.plist: `ClawdisBuildTimestamp` (UTC) and `ClawdisGitCommit` (short hash) so the About pane can show build, git, and debug/release channel.
 - **Packaging requires Bun**: The embedded gateway relay is compiled using `bun`. Ensure it is installed (`curl -fsSL https://bun.sh/install | bash`).
-- reads `SIGN_IDENTITY` from the environment. Add `export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"` (or your Developer ID Application cert) to your shell rc to always sign with your cert; otherwise signing falls back to ad‑hoc.
+- reads `SIGN_IDENTITY` from the environment. Add `export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"` (or your Developer ID Application cert) to your shell rc to always sign with your cert. Ad-hoc signing requires explicit opt-in via `ALLOW_ADHOC_SIGNING=1` or `SIGN_IDENTITY="-"` (not recommended for permission testing).
 
 ## Usage
 
 ```bash
 # from repo root
-scripts/package-mac-app.sh               # ad-hoc signing
+scripts/package-mac-app.sh               # auto-selects identity; errors if none found
 SIGN_IDENTITY="Developer ID Application: Your Name" scripts/package-mac-app.sh   # real cert
+ALLOW_ADHOC_SIGNING=1 scripts/package-mac-app.sh    # ad-hoc (permissions will not stick)
+SIGN_IDENTITY="-" scripts/package-mac-app.sh        # explicit ad-hoc (same caveat)
 ```
 
 ### Ad-hoc Signing Note
-When signing with `SIGN_IDENTITY="-"` (ad-hoc), the script automatically disables the **Hardened Runtime** (`--options runtime`). This is necessary to prevent crashes when the app attempts to load embedded frameworks (like Sparkle) that do not share the same Team ID.
+When signing with `SIGN_IDENTITY="-"` (ad-hoc), the script automatically disables the **Hardened Runtime** (`--options runtime`). This is necessary to prevent crashes when the app attempts to load embedded frameworks (like Sparkle) that do not share the same Team ID. Ad-hoc signatures also break TCC permission persistence; see `docs/mac/permissions.md` for recovery steps.
 
 ## Build metadata for About
 

docs/web.md

@@ -13,6 +13,7 @@ The Gateway serves a small **browser Control UI** (Vite + Lit) from the same por
 
 The UI talks directly to the Gateway WS and supports:
 - Chat (`chat.history`, `chat.send`, `chat.abort`)
+- Chat tool cards (agent tool events)
 - Connections (provider status, WhatsApp QR, Telegram config)
 - Instances (`system-presence`)
 - Sessions (`sessions.list`, `sessions.patch`)

scripts/codesign-mac-app.sh

@@ -57,12 +57,40 @@ select_identity() {
 
 if [ -z "$IDENTITY" ]; then
   if ! IDENTITY="$(select_identity)"; then
-    echo "ERROR: No signing identity found. Set SIGN_IDENTITY to a valid codesigning certificate." >&2
-    exit 1
+    if [[ "${ALLOW_ADHOC_SIGNING:-}" == "1" ]]; then
+      echo "WARN: No signing identity found. Falling back to ad-hoc signing (-)." >&2
+      echo "      !!! WARNING: Ad-hoc signed apps do NOT persist TCC permissions (Accessibility, etc) !!!" >&2
+      echo "      !!! You will need to re-grant permissions every time you restart the app.         !!!" >&2
+      IDENTITY="-"
+    else
+      echo "ERROR: No signing identity found. Set SIGN_IDENTITY to a valid codesigning certificate." >&2
+      echo "       Alternatively, set ALLOW_ADHOC_SIGNING=1 to fallback to ad-hoc signing (limitations apply)." >&2
+      exit 1
+    fi
   fi
 fi
 
 echo "Using signing identity: $IDENTITY"
+if [[ "$IDENTITY" == "-" ]]; then
+  cat <<'WARN' >&2
+
+================================================================================
+!!! AD-HOC SIGNING IN USE - PERMISSIONS WILL NOT STICK (macOS RESTRICTION) !!!
+
+macOS ties permissions to the code signature, bundle ID, and app path.
+Ad-hoc signing generates a new signature every build, so macOS treats the app
+as a different binary and will forget permissions (prompts may vanish).
+
+For correct permission behavior you MUST sign with a real Apple Development or
+Developer ID certificate.
+
+If prompts disappear: remove the app entry in System Settings -> Privacy & Security,
+relaunch the app, and re-grant. Some permissions only reappear after a full
+macOS restart.
+================================================================================
+
+WARN
+fi
 
 timestamp_arg="--timestamp=none"
 case "$TIMESTAMP_MODE" in
@@ -82,6 +110,9 @@ case "$TIMESTAMP_MODE" in
     exit 1
     ;;
 esac
+if [[ "$IDENTITY" == "-" ]]; then
+  timestamp_arg="--timestamp=none"
+fi
 
 options_args=()
 if [[ "$IDENTITY" != "-" ]]; then

src/agents/pi-embedded-runner.ts

@@ -48,6 +48,7 @@ import {
 } from "./pi-embedded-subscribe.js";
 import { extractAssistantText } from "./pi-embedded-utils.js";
 import { createClawdisCodingTools } from "./pi-tools.js";
+import { resolveSandboxContext } from "./sandbox.js";
 import {
   applySkillEnvOverrides,
   applySkillEnvOverridesFromSnapshot,
@@ -362,7 +363,13 @@ export async function runEmbeddedPiAgent(params: {
   return enqueueCommandInLane(sessionLane, () =>
     enqueueGlobal(async () => {
       const started = Date.now();
-      const resolvedWorkspace = resolveUserPath(params.workspaceDir);
+      const sandbox = await resolveSandboxContext({
+        config: params.config,
+        sessionKey: params.sessionKey,
+        workspaceDir: params.workspaceDir,
+      });
+      const workspaceDir = sandbox?.workspaceDir ?? params.workspaceDir;
+      const resolvedWorkspace = resolveUserPath(workspaceDir);
       const prevCwd = process.cwd();
 
       const provider =
@@ -425,6 +432,7 @@ export async function runEmbeddedPiAgent(params: {
         const tools = createClawdisCodingTools({
           bash: params.config?.agent?.bash,
           surface: params.surface,
+          sandbox,
         });
         const machineName = await getMachineDisplayName();
         const runtimeInfo = {
@@ -497,7 +505,6 @@ export async function runEmbeddedPiAgent(params: {
           assistantTexts,
           toolMetas,
           unsubscribe,
-          flush: flushToolDebouncer,
           waitForCompactionRetry,
         } = subscribeEmbeddedPiSession({
           session,
@@ -571,7 +578,6 @@ export async function runEmbeddedPiAgent(params: {
             abortWarnTimer = undefined;
           }
           unsubscribe();
-          flushToolDebouncer();
           if (ACTIVE_EMBEDDED_RUNS.get(params.sessionId) === queueHandle) {
             ACTIVE_EMBEDDED_RUNS.delete(params.sessionId);
           }

src/agents/pi-embedded-subscribe.test.ts

@@ -630,4 +630,107 @@ describe("subscribeEmbeddedPiSession", () => {
     await waitPromise;
     expect(resolved).toBe(true);
   });
+
+  it("emits tool summaries at tool start when verbose is on", () => {
+    let handler: ((evt: unknown) => void) | undefined;
+    const session: StubSession = {
+      subscribe: (fn) => {
+        handler = fn;
+        return () => {};
+      },
+    };
+
+    const onToolResult = vi.fn();
+
+    subscribeEmbeddedPiSession({
+      session: session as unknown as Parameters<
+        typeof subscribeEmbeddedPiSession
+      >[0]["session"],
+      runId: "run-tool",
+      verboseLevel: "on",
+      onToolResult,
+    });
+
+    handler?.({
+      type: "tool_execution_start",
+      toolName: "read",
+      toolCallId: "tool-1",
+      args: { path: "/tmp/a.txt" },
+    });
+
+    expect(onToolResult).toHaveBeenCalledTimes(1);
+    const payload = onToolResult.mock.calls[0][0];
+    expect(payload.text).toContain("/tmp/a.txt");
+
+    handler?.({
+      type: "tool_execution_end",
+      toolName: "read",
+      toolCallId: "tool-1",
+      isError: false,
+      result: "ok",
+    });
+
+    expect(onToolResult).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips tool summaries when shouldEmitToolResult is false", () => {
+    let handler: ((evt: unknown) => void) | undefined;
+    const session: StubSession = {
+      subscribe: (fn) => {
+        handler = fn;
+        return () => {};
+      },
+    };
+
+    const onToolResult = vi.fn();
+
+    subscribeEmbeddedPiSession({
+      session: session as unknown as Parameters<
+        typeof subscribeEmbeddedPiSession
+      >[0]["session"],
+      runId: "run-tool-off",
+      shouldEmitToolResult: () => false,
+      onToolResult,
+    });
+
+    handler?.({
+      type: "tool_execution_start",
+      toolName: "read",
+      toolCallId: "tool-2",
+      args: { path: "/tmp/b.txt" },
+    });
+
+    expect(onToolResult).not.toHaveBeenCalled();
+  });
+
+  it("emits tool summaries when shouldEmitToolResult overrides verbose", () => {
+    let handler: ((evt: unknown) => void) | undefined;
+    const session: StubSession = {
+      subscribe: (fn) => {
+        handler = fn;
+        return () => {};
+      },
+    };
+
+    const onToolResult = vi.fn();
+
+    subscribeEmbeddedPiSession({
+      session: session as unknown as Parameters<
+        typeof subscribeEmbeddedPiSession
+      >[0]["session"],
+      runId: "run-tool-override",
+      verboseLevel: "off",
+      shouldEmitToolResult: () => true,
+      onToolResult,
+    });
+
+    handler?.({
+      type: "tool_execution_start",
+      toolName: "read",
+      toolCallId: "tool-3",
+      args: { path: "/tmp/c.txt" },
+    });
+
+    expect(onToolResult).toHaveBeenCalledTimes(1);
+  });
 });

src/agents/pi-embedded-subscribe.ts

@@ -2,10 +2,7 @@ import type { AgentEvent, AgentMessage } from "@mariozechner/pi-agent-core";
 import type { AssistantMessage } from "@mariozechner/pi-ai";
 import type { AgentSession } from "@mariozechner/pi-coding-agent";
 
-import {
-  createToolDebouncer,
-  formatToolAggregate,
-} from "../auto-reply/tool-meta.js";
+import { formatToolAggregate } from "../auto-reply/tool-meta.js";
 import { emitAgentEvent } from "../infra/agent-events.js";
 import { splitMediaFromOutput } from "../media/parse.js";
 import { defaultRuntime } from "../runtime.js";
@@ -113,6 +110,7 @@ export function subscribeEmbeddedPiSession(params: {
   const assistantTexts: string[] = [];
   const toolMetas: Array<{ toolName?: string; meta?: string }> = [];
   const toolMetaById = new Map<string, string | undefined>();
+  const toolSummaryById = new Set<string>();
   const blockReplyBreak = params.blockReplyBreak ?? "text_end";
   let deltaBuffer = "";
   let blockBuffer = "";
@@ -176,17 +174,25 @@ export function subscribeEmbeddedPiSession(params: {
     return afterStart.slice(0, endIndex);
   };
 
-  const toolDebouncer = createToolDebouncer((toolName, metas) => {
-    if (!params.onPartialReply) return;
-    const text = formatToolAggregate(toolName, metas);
-    const { text: cleanedText, mediaUrls } = splitMediaFromOutput(text);
-    void params.onPartialReply({
-      text: cleanedText,
-      mediaUrls: mediaUrls?.length ? mediaUrls : undefined,
-    });
-  });
-
   const blockChunking = params.blockReplyChunking;
+  const shouldEmitToolResult = () =>
+    typeof params.shouldEmitToolResult === "function"
+      ? params.shouldEmitToolResult()
+      : params.verboseLevel === "on";
+  const emitToolSummary = (toolName?: string, meta?: string) => {
+    if (!params.onToolResult) return;
+    const agg = formatToolAggregate(toolName, meta ? [meta] : undefined);
+    const { text: cleanedText, mediaUrls } = splitMediaFromOutput(agg);
+    if (!cleanedText && (!mediaUrls || mediaUrls.length === 0)) return;
+    try {
+      void params.onToolResult({
+        text: cleanedText,
+        mediaUrls: mediaUrls?.length ? mediaUrls : undefined,
+      });
+    } catch {
+      // ignore tool result delivery failures
+    }
+  };
 
   const findSentenceBreak = (window: string, minChars: number): number => {
     if (!window) return -1;
@@ -298,12 +304,12 @@ export function subscribeEmbeddedPiSession(params: {
     assistantTexts.length = 0;
     toolMetas.length = 0;
     toolMetaById.clear();
+    toolSummaryById.clear();
     deltaBuffer = "";
     blockBuffer = "";
     lastStreamedAssistant = undefined;
     lastBlockReplyText = undefined;
     assistantTextBaseline = 0;
-    toolDebouncer.flush();
   };
 
   const unsubscribe = params.session.subscribe(
@@ -336,6 +342,15 @@ export function subscribeEmbeddedPiSession(params: {
           stream: "tool",
           data: { phase: "start", name: toolName, toolCallId },
         });
+
+        if (
+          params.onToolResult &&
+          shouldEmitToolResult() &&
+          !toolSummaryById.has(toolCallId)
+        ) {
+          toolSummaryById.add(toolCallId);
+          emitToolSummary(toolName, meta);
+        }
       }
 
       if (evt.type === "tool_execution_update") {
@@ -382,7 +397,8 @@ export function subscribeEmbeddedPiSession(params: {
         const sanitizedResult = sanitizeToolResult(result);
         const meta = toolMetaById.get(toolCallId);
         toolMetas.push({ toolName, meta });
-        toolDebouncer.push(toolName, meta);
+        toolMetaById.delete(toolCallId);
+        toolSummaryById.delete(toolCallId);
 
         emitAgentEvent({
           runId: params.runId,
@@ -406,25 +422,6 @@ export function subscribeEmbeddedPiSession(params: {
             isError,
           },
         });
-
-        const emitToolResult =
-          typeof params.shouldEmitToolResult === "function"
-            ? params.shouldEmitToolResult()
-            : params.verboseLevel === "on";
-        if (emitToolResult && params.onToolResult) {
-          const agg = formatToolAggregate(toolName, meta ? [meta] : undefined);
-          const { text: cleanedText, mediaUrls } = splitMediaFromOutput(agg);
-          if (cleanedText || (mediaUrls && mediaUrls.length > 0)) {
-            try {
-              void params.onToolResult({
-                text: cleanedText,
-                mediaUrls: mediaUrls?.length ? mediaUrls : undefined,
-              });
-            } catch {
-              // ignore tool result delivery failures
-            }
-          }
-        }
       }
 
       if (evt.type === "message_update") {
@@ -626,7 +623,6 @@ export function subscribeEmbeddedPiSession(params: {
 
       if (evt.type === "agent_end") {
         defaultRuntime.log?.(`embedded run agent end: runId=${params.runId}`);
-        toolDebouncer.flush();
         if (pendingCompactionRetry > 0) {
           resolveCompactionRetry();
         } else {
@@ -640,7 +636,6 @@ export function subscribeEmbeddedPiSession(params: {
     assistantTexts,
     toolMetas,
     unsubscribe,
-    flush: () => toolDebouncer.flush(),
     waitForCompactionRetry: () => {
       if (compactionInFlight || pendingCompactionRetry > 0) {
         ensureCompactionPromise();

src/auto-reply/tool-meta.test.ts

@@ -1,7 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 import {
-  createToolDebouncer,
   formatToolAggregate,
   formatToolPrefix,
   shortenMeta,
@@ -48,37 +47,3 @@ describe("tool meta formatting", () => {
     expect(formatToolPrefix("x", "/Users/test/a.txt")).toBe("🧩 x: ~/a.txt");
   });
 });
-
-describe("tool meta debouncer", () => {
-  it("flushes on timer and when tool changes", () => {
-    vi.useFakeTimers();
-    try {
-      const calls: Array<{ tool: string | undefined; metas: string[] }> = [];
-      const d = createToolDebouncer((tool, metas) => {
-        calls.push({ tool, metas });
-      }, 50);
-
-      d.push("a", "/tmp/1");
-      d.push("a", "/tmp/2");
-      expect(calls).toHaveLength(0);
-
-      vi.advanceTimersByTime(60);
-      expect(calls).toHaveLength(1);
-      expect(calls[0]).toMatchObject({
-        tool: "a",
-        metas: ["/tmp/1", "/tmp/2"],
-      });
-
-      d.push("a", "x");
-      d.push("b", "y"); // tool change flushes immediately
-      expect(calls).toHaveLength(2);
-      expect(calls[1]).toMatchObject({ tool: "a", metas: ["x"] });
-
-      vi.advanceTimersByTime(60);
-      expect(calls).toHaveLength(3);
-      expect(calls[2]).toMatchObject({ tool: "b", metas: ["y"] });
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-});

src/auto-reply/tool-meta.ts

@@ -4,9 +4,6 @@ import {
 } from "../agents/tool-display.js";
 import { shortenHomeInString, shortenHomePath } from "../utils.js";
 
-export const TOOL_RESULT_DEBOUNCE_MS = 500;
-export const TOOL_RESULT_FLUSH_COUNT = 5;
-
 export function shortenPath(p: string): string {
   return shortenHomePath(p);
 }
@@ -77,33 +74,3 @@ function isPathLike(value: string): boolean {
   if (value.includes("&&") || value.includes("||")) return false;
   return /^~?(\/[^\s]+)+$/.test(value);
 }
-
-export function createToolDebouncer(
-  onFlush: (toolName: string | undefined, metas: string[]) => void,
-  windowMs = TOOL_RESULT_DEBOUNCE_MS,
-) {
-  let pendingTool: string | undefined;
-  let pendingMetas: string[] = [];
-  let timer: NodeJS.Timeout | null = null;
-
-  const flush = () => {
-    if (!pendingTool && pendingMetas.length === 0) return;
-    onFlush(pendingTool, pendingMetas);
-    pendingTool = undefined;
-    pendingMetas = [];
-    if (timer) {
-      clearTimeout(timer);
-      timer = null;
-    }
-  };
-
-  const push = (toolName?: string, meta?: string) => {
-    if (pendingTool && toolName && pendingTool !== toolName) flush();
-    if (!pendingTool) pendingTool = toolName;
-    if (meta) pendingMetas.push(meta);
-    if (timer) clearTimeout(timer);
-    timer = setTimeout(flush, windowMs);
-  };
-
-  return { push, flush };
-}

src/gateway/server-chat.ts

@@ -186,12 +186,18 @@ export function createAgentEventHandler({
   };
 
   return (evt: AgentEventPayload) => {
+    const chatLink = chatRunState.registry.peek(evt.runId);
+    const sessionKey =
+      chatLink?.sessionKey ?? resolveSessionKeyForRun(evt.runId);
+    // Include sessionKey so Control UI can filter tool streams per session.
+    const agentPayload = sessionKey ? { ...evt, sessionKey } : evt;
     const last = agentRunSeq.get(evt.runId) ?? 0;
     if (evt.seq !== last + 1) {
       broadcast("agent", {
         runId: evt.runId,
         stream: "error",
         ts: Date.now(),
+        sessionKey,
         data: {
           reason: "seq gap",
           expected: last + 1,
@@ -200,18 +206,15 @@ export function createAgentEventHandler({
       });
     }
     agentRunSeq.set(evt.runId, evt.seq);
-    broadcast("agent", evt);
+    broadcast("agent", agentPayload);
 
-    const chatLink = chatRunState.registry.peek(evt.runId);
-    const sessionKey =
-      chatLink?.sessionKey ?? resolveSessionKeyForRun(evt.runId);
     const jobState =
       evt.stream === "job" && typeof evt.data?.state === "string"
         ? (evt.data.state as "done" | "error" | string)
         : null;
 
     if (sessionKey) {
-      bridgeSendToSession(sessionKey, "agent", evt);
+      bridgeSendToSession(sessionKey, "agent", agentPayload);
       if (evt.stream === "assistant" && typeof evt.data?.text === "string") {
         const clientRunId = chatLink?.clientRunId ?? evt.runId;
         emitChatDelta(sessionKey, clientRunId, evt.seq, evt.data.text);

src/gateway/server.agent.test.ts

@@ -478,4 +478,43 @@ describe("gateway server agent", () => {
     ws.close();
     await server.close();
   });
+
+  test("agent events include sessionKey in agent payloads", async () => {
+    const { server, ws } = await startServerWithClient();
+    await connectOk(ws, {
+      client: {
+        name: "webchat",
+        version: "1.0.0",
+        platform: "test",
+        mode: "webchat",
+      },
+    });
+
+    registerAgentRunContext("run-tool-1", { sessionKey: "main" });
+
+    const agentEvtP = onceMessage(
+      ws,
+      (o) =>
+        o.type === "event" &&
+        o.event === "agent" &&
+        o.payload?.runId === "run-tool-1",
+      8000,
+    );
+
+    emitAgentEvent({
+      runId: "run-tool-1",
+      stream: "tool",
+      data: { phase: "start", name: "read", toolCallId: "tool-1" },
+    });
+
+    const evt = await agentEvtP;
+    const payload =
+      evt.payload && typeof evt.payload === "object"
+        ? (evt.payload as Record<string, unknown>)
+        : {};
+    expect(payload.sessionKey).toBe("main");
+
+    ws.close();
+    await server.close();
+  });
 });

src/infra/agent-events.ts

@@ -11,6 +11,7 @@ export type AgentEventPayload = {
   stream: AgentEventStream;
   ts: number;
   data: Record<string, unknown>;
+  sessionKey?: string;
 };
 
 export type AgentRunContext = {

ui/src/ui/app-render.ts

@@ -84,6 +84,7 @@ export type AppViewState = {
   chatSending: boolean;
   chatMessage: string;
   chatMessages: unknown[];
+  chatToolMessages: unknown[];
   chatStream: string | null;
   chatRunId: string | null;
   chatThinkingLevel: string | null;
@@ -168,6 +169,7 @@ export type AppViewState = {
   handleWhatsAppLogout: () => Promise<void>;
   handleTelegramSave: () => Promise<void>;
   handleSendChat: () => Promise<void>;
+  resetToolStream: () => void;
 };
 
 export function renderApp(state: AppViewState) {
@@ -241,6 +243,7 @@ export function renderApp(state: AppViewState) {
               onSessionKeyChange: (next) => {
                 state.sessionKey = next;
                 state.chatMessage = "";
+                state.resetToolStream();
                 state.applySettings({ ...state.settings, sessionKey: next });
               },
               onRefresh: () => state.loadOverview(),
@@ -370,20 +373,24 @@ export function renderApp(state: AppViewState) {
                 state.chatMessage = "";
                 state.chatStream = null;
                 state.chatRunId = null;
+                state.resetToolStream();
                 state.applySettings({ ...state.settings, sessionKey: next });
                 void loadChatHistory(state);
               },
               thinkingLevel: state.chatThinkingLevel,
               loading: state.chatLoading,
               sending: state.chatSending,
-              messages: state.chatMessages,
+              messages: [...state.chatMessages, ...state.chatToolMessages],
               stream: state.chatStream,
               draft: state.chatMessage,
               connected: state.connected,
               canSend: state.connected && hasConnectedMobileNode,
               disabledReason: chatDisabledReason,
               sessions: state.sessionsResult,
-              onRefresh: () => loadChatHistory(state),
+              onRefresh: () => {
+                state.resetToolStream();
+                return loadChatHistory(state);
+              },
               onDraftChange: (next) => (state.chatMessage = next),
               onSend: () => state.handleSendChat(),
             })

ui/src/ui/app.ts

@@ -81,6 +81,62 @@ type EventLogEntry = {
   payload?: unknown;
 };
 
+const TOOL_STREAM_LIMIT = 50;
+
+type AgentEventPayload = {
+  runId: string;
+  seq: number;
+  stream: string;
+  ts: number;
+  sessionKey?: string;
+  data: Record<string, unknown>;
+};
+
+type ToolStreamEntry = {
+  toolCallId: string;
+  runId: string;
+  sessionKey?: string;
+  name: string;
+  args?: unknown;
+  output?: string;
+  startedAt: number;
+  updatedAt: number;
+  message: Record<string, unknown>;
+};
+
+function extractToolOutputText(value: unknown): string | null {
+  if (!value || typeof value !== "object") return null;
+  const record = value as Record<string, unknown>;
+  if (typeof record.text === "string") return record.text;
+  const content = record.content;
+  if (!Array.isArray(content)) return null;
+  const parts = content
+    .map((item) => {
+      if (!item || typeof item !== "object") return null;
+      const entry = item as Record<string, unknown>;
+      if (entry.type === "text" && typeof entry.text === "string") return entry.text;
+      return null;
+    })
+    .filter((part): part is string => Boolean(part));
+  if (parts.length === 0) return null;
+  return parts.join("\n");
+}
+
+function formatToolOutput(value: unknown): string | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  const contentText = extractToolOutputText(value);
+  if (contentText) return contentText;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
 declare global {
   interface Window {
     __CLAWDIS_CONTROL_UI_BASE_PATH__?: string;
@@ -125,6 +181,7 @@ export class ClawdisApp extends LitElement {
   @state() chatSending = false;
   @state() chatMessage = "";
   @state() chatMessages: unknown[] = [];
+  @state() chatToolMessages: unknown[] = [];
   @state() chatStream: string | null = null;
   @state() chatRunId: string | null = null;
   @state() chatThinkingLevel: string | null = null;
@@ -260,6 +317,8 @@ export class ClawdisApp extends LitElement {
   private chatScrollFrame: number | null = null;
   private chatScrollTimeout: number | null = null;
   private nodesPollInterval: number | null = null;
+  private toolStreamById = new Map<string, ToolStreamEntry>();
+  private toolStreamOrder: string[] = [];
   basePath = "";
   private popStateHandler = () => this.onPopState();
   private themeMedia: MediaQueryList | null = null;
@@ -292,6 +351,7 @@ export class ClawdisApp extends LitElement {
     if (
       this.tab === "chat" &&
       (changed.has("chatMessages") ||
+        changed.has("chatToolMessages") ||
         changed.has("chatStream") ||
         changed.has("chatLoading") ||
         changed.has("chatMessage") ||
@@ -377,12 +437,109 @@ export class ClawdisApp extends LitElement {
     });
   }
 
+  resetToolStream() {
+    this.toolStreamById.clear();
+    this.toolStreamOrder = [];
+    this.chatToolMessages = [];
+  }
+
+  private trimToolStream() {
+    if (this.toolStreamOrder.length <= TOOL_STREAM_LIMIT) return;
+    const overflow = this.toolStreamOrder.length - TOOL_STREAM_LIMIT;
+    const removed = this.toolStreamOrder.splice(0, overflow);
+    for (const id of removed) this.toolStreamById.delete(id);
+  }
+
+  private syncToolStreamMessages() {
+    this.chatToolMessages = this.toolStreamOrder
+      .map((id) => this.toolStreamById.get(id)?.message)
+      .filter((msg): msg is Record<string, unknown> => Boolean(msg));
+  }
+
+  private buildToolStreamMessage(entry: ToolStreamEntry): Record<string, unknown> {
+    const content: Array<Record<string, unknown>> = [];
+    content.push({
+      type: "toolcall",
+      name: entry.name,
+      arguments: entry.args ?? {},
+    });
+    if (entry.output) {
+      content.push({
+        type: "toolresult",
+        name: entry.name,
+        text: entry.output,
+      });
+    }
+    return {
+      role: "assistant",
+      toolCallId: entry.toolCallId,
+      runId: entry.runId,
+      content,
+      timestamp: entry.startedAt,
+    };
+  }
+
+  private handleAgentEvent(payload?: AgentEventPayload) {
+    if (!payload || payload.stream !== "tool") return;
+    const sessionKey =
+      typeof payload.sessionKey === "string" ? payload.sessionKey : undefined;
+    if (sessionKey && sessionKey !== this.sessionKey) return;
+    // Fallback: only accept session-less events for the active run.
+    if (!sessionKey && this.chatRunId && payload.runId !== this.chatRunId) return;
+
+    const data = payload.data ?? {};
+    const toolCallId =
+      typeof data.toolCallId === "string" ? data.toolCallId : "";
+    if (!toolCallId) return;
+    const name = typeof data.name === "string" ? data.name : "tool";
+    const phase = typeof data.phase === "string" ? data.phase : "";
+    const args = phase === "start" ? data.args : undefined;
+    const output =
+      phase === "update"
+        ? formatToolOutput(data.partialResult)
+        : phase === "result"
+          ? formatToolOutput(data.result)
+          : undefined;
+
+    const now = Date.now();
+    let entry = this.toolStreamById.get(toolCallId);
+    if (!entry) {
+      entry = {
+        toolCallId,
+        runId: payload.runId,
+        sessionKey,
+        name,
+        args,
+        output,
+        startedAt: typeof payload.ts === "number" ? payload.ts : now,
+        updatedAt: now,
+        message: {},
+      };
+      this.toolStreamById.set(toolCallId, entry);
+      this.toolStreamOrder.push(toolCallId);
+    } else {
+      entry.name = name;
+      if (args !== undefined) entry.args = args;
+      if (output !== undefined) entry.output = output;
+      entry.updatedAt = now;
+    }
+
+    entry.message = this.buildToolStreamMessage(entry);
+    this.trimToolStream();
+    this.syncToolStreamMessages();
+  }
+
   private onEvent(evt: GatewayEventFrame) {
     this.eventLog = [
       { ts: Date.now(), event: evt.event, payload: evt.payload },
       ...this.eventLog,
     ].slice(0, 250);
 
+    if (evt.event === "agent") {
+      this.handleAgentEvent(evt.payload as AgentEventPayload | undefined);
+      return;
+    }
+
     if (evt.event === "chat") {
       const payload = evt.payload as ChatEventPayload | undefined;
       const state = handleChatEvent(this, payload);

ui/src/ui/views/chat.ts

@@ -170,14 +170,18 @@ function renderMessage(message: unknown, opts?: { streaming?: boolean }) {
   const m = message as Record<string, unknown>;
   const role = typeof m.role === "string" ? m.role : "unknown";
   const toolCards = extractToolCards(message);
+  const hasToolCards = toolCards.length > 0;
   const isToolResult = isToolResultMessage(message);
-  const text =
-    !isToolResult
-      ? extractText(message) ??
-        (typeof m.content === "string"
-          ? m.content
-          : JSON.stringify(message, null, 2))
-      : null;
+  const extractedText = extractText(message);
+  const contentText = typeof m.content === "string" ? m.content : null;
+  const fallback = hasToolCards ? null : JSON.stringify(message, null, 2);
+  const text = !isToolResult
+    ? extractedText?.trim()
+      ? extractedText
+      : contentText?.trim()
+        ? contentText
+        : fallback
+    : null;
 
   const timestamp =
     typeof m.timestamp === "number" ? new Date(m.timestamp).toLocaleTimeString() : "";