Summary

PR #76914 (merged 2026-05-09) bridged CLI-runtime assistant text deltas into channel preview pipelines, closing the silence gap on the API vs CLI runtime split for streaming text. Tool-progress events were left out of that fix — they're still dropped on the CLI runtime path while the embedded native (API) runtime emits them normally. Channel previews that subscribe to stream: "tool" for live tool-progress decoration (Telegram's "📖 Read:", "🛠️ Bash:", etc.) stay silent during tool-heavy CLI-backed turns, so users see typing indicators and final text but never the work-in-progress trail the API path already produces.

This PR closes the rest of the API/CLI parity gap by surfacing tool-use lifecycle events from the CLI stream output and bridging them through the same agent-event bus #76914 used for assistant text.

Behavior change

Two scope tiers:

• Parser layer (src/agents/cli-output.ts) — claude-cli-specific. Recognises the claude --output-format stream-json dialect's tool_use content blocks and tool_result user-messages and surfaces them through new optional callbacks on createCliJsonlStreamingParser. Other CLI dialects (codex-cli, kiro-cli) ship their own parsers and continue to work as today; this PR only adds parsing for claude-cli's dialect because that's the one OpenClaw bundles a parser for.
• Bridge layer (src/agents/cli-runner/execute.ts, src/agents/cli-runner/claude-live-session.ts, src/auto-reply/reply/agent-runner-execution.ts) — CLI-generic. The runCliAgent execution path is gated by isCliProvider(cliExecutionProvider, runtimeConfig) at agent-runner-execution.ts:1415, so any CLI runtime emitting agent-event { stream: "tool" } for its run id (whether claude-cli today or future CLIs that adopt the same emission shape) gets the events forwarded to params.opts.onToolStart automatically. This is the matching layer to PR fix(agents/cli): bridge CLI assistant deltas into channel preview (#76869) #76914's assistant-bridge addition and shares its serialization, drain, and silentExpected guards.

Layer-by-layer details:

1. Parser — new dispatchClaudeCliStreamingToolEvent in src/agents/cli-output.ts recognises three claude stream-json record shapes:

   • stream_event { event: { type: "content_block_start", content_block: { type: "tool_use", id, name } } } → record id+name in tracker (no emit yet; args haven't streamed).
   • assistant { message: { content: [{ type: "tool_use", id, name, input }] } } → emit onToolUseStart({ toolCallId, name, args: input }) with full args.
   • user { message: { content: [{ type: "tool_result", tool_use_id, is_error, content }] } } → emit onToolResult({ toolCallId, name, isError, result }).
   • content_block_stop without preceding assistant snapshot → fallback emit start with empty args (turn-aborted edge case).

   The shape {phase: "start" | "result", name, toolCallId, args | isError | result} matches what the embedded native runtime already emits at src/agents/pi-embedded-subscribe.handlers.tools.ts:696-705,998-1009, so existing channel consumers pick them up unchanged. Per-parser ToolUseTracker dedupes start/result events. New optional callbacks; when neither is subscribed, behavior is byte-identical to before.

2. Parser consumer — both claude-cli execution paths in src/agents/cli-runner/execute.ts (live-session and JSONL-streaming) wire the new callbacks to emitAgentEvent({ runId, stream: "tool", data: {...} }). Args and results are passed through sanitizeToolArgs / sanitizeToolResult from src/agents/pi-embedded-subscribe.tools.ts before emission, matching the embedded native runtime's privacy contract at pi-embedded-subscribe.handlers.tools.ts:703,705,1005,1007 — redacts Authorization headers, API key fields, and shell commands containing tokens before they reach the shared bus. The parser is constructed fresh per turn in claude-live-session.ts:createTurn, so the ToolUseTracker is per-turn — no cross-turn state leak.

3. Agent-event bus consumer (CLI-generic) — src/auto-reply/reply/agent-runner-execution.ts adds a parallel rawUnsubscribeToolBridge = onAgentEvent(...) next to the assistant-text bridge from fix(agents/cli): bridge CLI assistant deltas into channel preview (#76869) #76914 inside the isCliProvider(...) branch. Filters by runId, respects silentExpected (heartbeat / NO_REPLY runs do not leak), and forwards phase === "start" and "update" events to params.opts.onToolStart. Mirrors fix(agents/cli): bridge CLI assistant deltas into channel preview (#76869) #76914's serialization pattern (toolBridgeDelivery Promise chain + drainToolBridgeDelivery) so callbacks land in order even when onToolStart is async, and unsubscribe is mirrored at every place the assistant unsubscribe is called (success, catch, finally) so the listener never leaks.

No new public APIs in plugin-sdk; channel-side code is unchanged. Telegram, Discord, Slack, etc. preview pipelines automatically light up because they already subscribe to stream: "tool" on the agent-event bus through params.opts.onToolStart.

Scope note: this PR forwards phase: "start" and phase: "update" events through onToolStart (the channel-progress activation surface). phase: "result" is emitted on the bus but not forwarded to the channel here — the embedded handler's result events also include a meta field that this CLI emit omits, and the channel-progress pipeline today only consumes activation events. Adding result-phase forwarding (with meta parity) is left as a follow-up PR if/when a consumer needs completion events on the CLI path.

Verification

• pnpm test src/agents/cli-output.test.ts → 21/21 PASS (5 new tests: full happy-path, fallback on content_block_stop without assistant snapshot, dedup when both content_block_start and assistant snapshot announce same tool, error tool_result with name passthrough, parser-vs-consumer privacy-contract regression locking in that args/result surface raw at the parser boundary and the consumer applies sanitizeToolArgs/sanitizeToolResult before emission).
• pnpm test src/auto-reply/reply/agent-runner-execution.test.ts → 73/73 PASS (2 new bridge tests: forwards tool events to onToolStart with correct args; respects silentExpected).
• pnpm test src/agents/cli-runner → 50/50 PASS.
• pnpm check:changed → all gates green (typecheck core + tests, lint core, runtime sidecar loaders, import cycles, webhook/pairing guards).
• pnpm exec oxfmt --check --threads=1 src/agents/cli-output.ts src/agents/cli-output.test.ts src/agents/cli-runner/execute.ts src/agents/cli-runner/claude-live-session.ts src/auto-reply/reply/agent-runner-execution.ts src/auto-reply/reply/agent-runner-execution.test.ts → clean.
• Pre-existing failures on origin/main@cb86388cec: pi-embedded-runner.run-embedded-pi-agent.auth-profile-rotation.e2e.test.ts has 3 failures + 1 unhandled rejection on clean main (verified by stashing this branch and re-running). Backoff/auth-rotation assertion expected "vi.fn()" to be called 2 times, but got 3 times. Unrelated.

Real behavior proof

Behavior or issue addressed: CLI-runtime turns silently dropping tool_use content blocks and tool_result user-messages between cli-output.ts and the channel preview pipeline, so Telegram's tool-progress UI never lights up for CLI-backed turns even though the underlying CLI is producing the data.

Real environment tested: Live OpenClaw 2026.5.7 deployment on macOS with the claude-cli backend driving Telegram. Same setup I used for the proof on #76914.

Exact steps or command run after this patch: I hand-applied this PR's three structural changes to the installed 2026.5.7 dist files (claude-live-session-*.js, execute.runtime-*.js, agent-runner.runtime-*.js), instrumented each layer with a tracing log, restarted the OpenClaw gateway via launchctl kickstart -k "gui/$(id -u)/ai.openclaw.gateway", and sent a real Telegram turn: "Read /etc/hosts, then read /etc/zshrc, then count their combined lines. Use Bash for the count." — three tool calls per turn, driven through the live gateway. I also captured the parser layer in isolation by piping a real claude-cli --output-format stream-json JSONL fixture through the patched createCliJsonlStreamingParser:

echo "Run 'ls /' and tell me how many entries." \
  | claude -p --output-format stream-json --include-partial-messages \
           --verbose --setting-sources user --allowedTools Bash \
  > /tmp/claude-stream-fixture.jsonl
node --import tsx ./proof.mts

proof.mts:

import { readFileSync } from "node:fs";
import { createCliJsonlStreamingParser } from "./src/agents/cli-output.ts";
const raw = readFileSync("/tmp/claude-stream-fixture.jsonl", "utf-8");
const events: Array<{ kind: string; data: unknown }> = [];
const parser = createCliJsonlStreamingParser({
  backend: { command: "claude", output: "jsonl", jsonlDialect: "claude-stream-json" },
  providerId: "claude-cli",
  onAssistantDelta: () => undefined,
  onToolUseStart: (d) => events.push({ kind: "tool.start", data: d }),
  onToolResult: (d) => events.push({ kind: "tool.result", data: d }),
});
parser.push(raw); parser.finish();
for (const e of events) console.log(`${e.kind}: ${JSON.stringify(e.data)}`);

Evidence after fix: Redacted runtime logs from the live Telegram + claude-cli turn, captured directly from ~/.openclaw/logs/gateway.err.log with the dist hand-patches in place. Each layer of the pipeline writes a [demo-trace] line so the chain is visible end-to-end:

[claude-cli stream-json record arrives on stdout]
parser → dispatchClaudeCliStreamingToolEvent type=stream_event
parser → emitToolStart name=Read toolCallId=toolu_...01 hasCallback=true
runtime onToolUseStart name=Read toolCallId=toolu_...01 runId=8be3085a-...
agent-runner BUS evt stream=tool phase=start name=Read
agent-runner forward to onToolStart hasCallback=true name=Read
[Telegram channel] PREVIEW partial-branch enabled=true suppressed=false normalized=📖 Read: from /etc/hosts
[Telegram editMessageText emitted]

Same chain fires for the second Read, then for the Bash call, then for tool results. The parser-isolation harness captured this terminal output for the same kind of turn driven through the real claude CLI:

Captured 2 tool events from 29 JSONL records:
  - tool.start: {"toolCallId":"toolu_01EXAMPLE","name":"Bash","args":{"command":"ls / | wc -l","description":"Count entries in root directory"}}
  - tool.result: {"toolCallId":"toolu_01EXAMPLE","name":"Bash","isError":false,"result":"      16"}

Observed result after fix: With this PR's structural change applied, my Telegram turn against the live gateway showed the bot's preview message updating with 📖 Read: from /etc/hosts, then 📖 Read: from /etc/zshrc, then 🛠️ Bash: ... lines while the agent worked, before delivering the final answer — the same per-tool decoration users already see on embedded-native-runtime agents. With streaming.mode: "progress" the lines accumulate for the full turn; with streaming.mode: "partial" (the default) they flash before the streaming answer text replaces the preview, matching the existing embedded-runtime behavior. Without the patch (stock 2026.5.7), the same prompt produces zero [demo-trace] BUS evt stream=tool log lines and the Telegram preview shows only the assistant text — the onToolStart callback the channel pipeline already exposes is never invoked because no CLI-side emitter publishes to it.

What was not tested: I did not exercise non-claude CLI runtimes (codex-cli, kiro-cli) against the bridge layer — those don't ship a stream-json parser in this repo, so the parser layer change doesn't apply to them. The bridge layer at agent-runner-execution.ts is gated by isCliProvider(...) and would forward any stream: "tool" events those runtimes might emit in the future, but that future is not exercised here. I also did not test the phase: "result" channel-side rendering — the bridge filters result to keep parity with #76914's activation-only forwarding (see Scope note above), so this PR's change is invisible to consumers that only handle start/update today.