Summary

This PR adds an opt-in ACP stream setting for parent-owned Codex/ACP runs:

• Adds acp.stream.assistantCommentary with a default-off config/schema/docs surface.
• Threads that setting into sessions_spawn(..., runtime: "acp", streamTo: "parent") parent-stream relays.
• Keeps existing default behavior: phase: "commentary" assistant text is still hidden unless the operator enables the new option.
• When enabled, assistant commentary and ACP status progress allowed by acp.stream.tagVisibility use the same bounded parent-stream buffering/truncation path as other assistant progress text.
• Keeps final-answer selection/delivery unchanged.

This matters now because long CodexAgent ACP runs can be visibly active in tool logs while the parent OpenClaw conversation receives no natural-language progress updates. The existing relay counted commentary as internal progress but returned before any user-visible update, so operators could wait through long tool-heavy runs without knowing what was happening.

Intended outcome: deployments that want a more Codex-Desktop-like status experience can turn on assistant-authored progress/status text for ACP parent streams without changing current quiet defaults.

Out of scope: Discord-specific streaming.progress.commentary behavior, hidden chain-of-thought exposure, final transcript projection, or durable final-answer semantics.

Success looks like: default suppression remains unchanged; enabling acp.stream.assistantCommentary relays commentary into parent progress updates; final-answer relay still works as before.

Review focus: the config name/default, whether acp.stream is the right namespace, and the parent-stream classification behavior for opted-in commentary.

Scenario at a glance

The operator-facing failure mode is easiest to see as a long-running run:

This is a gateway/operator config choice, not a request to force commentary on everyone and not a per-user or per-sessions_spawn override. Existing deployments keep the current default. Operators who want a Codex-Desktop-like progress experience for ACP parent streams can turn it on explicitly for ACP parent streams served by that config.

Behavior diagrams

Current behavior:

sequenceDiagram
  participant U as User
  participant P as Parent OpenClaw chat
  participant A as ACP CodexAgent child
  participant T as Tools and logs

  U->>P: Ask broad request
  P->>A: sessions_spawn streamTo parent
  loop long tool-heavy work
    A->>T: tool calls and command output
    A-->>A: commentary updates internal progress only
    A--xP: no parent-visible text
  end
  A->>P: final answer

Opt-in behavior from this PR:

sequenceDiagram
  participant U as User
  participant P as Parent OpenClaw chat
  participant A as ACP CodexAgent child
  participant T as Tools and logs

  U->>P: Ask broad request
  P->>A: sessions_spawn streamTo parent
  Note over P,A: acp.stream.assistantCommentary = true
  loop long tool-heavy work
    A->>T: tool calls and command output
    A->>P: bounded commentary progress
  end
  A->>P: final answer

Linked context

Closes #89501

Related:

• Discord progress drafts should support assistant commentary events #83307 (closed): Discord progress drafts should support assistant commentary events.
• [Bug]: Discord progress commentary renders a literal leading underscore when an italic line is truncated #88895: Discord formatting bug when commentary is already enabled.
• Discord progress/partial streaming no longer shows visible in-progress updates #88227: Discord progress/partial visibility issue.

Requested by an OpenClaw/Codex operator report: local CodexAgent runs made many tool calls for long periods but did not provide interim message updates, making it unclear whether the agent was healthy or stuck.

Real behavior proof (required for external PRs)

• Behavior or issue addressed: ACP parent stream hard-suppressed assistant phase: "commentary" text and did not surface ACP status progress allowed by the existing tag-visibility policy even when streamTo: "parent" was requested.
• Real environment tested: Local OpenClaw source checkout under /Volumes/LEXAR/repos/openclaw-codex-claw-builtin, branch codex/acp-commentary-progress.
• Exact steps or command run after this patch: from the repo root, run node --import tsx /Volumes/LEXAR/Codex/openclaw-acp-commentary-proof.mjs. The script imports the patched OpenClaw relay module, emits an assistant event through the production agent-event bus, then drains the parent session's OpenClaw system-event queue.
• Evidence after fix:

OpenClaw ACP parent relay console proof
repo: /Volumes/LEXAR/repos/openclaw-codex-claw-builtin
input event A: assistant phase=commentary
assistantCommentary=false parent events: []
assistantCommentary=true parent events: ["codex: checking workspace and tool state before the next step"]
input event B: ACP runtime status tag=plan
assistantCommentary=false parent events: []
assistantCommentary=true, default tagVisibility parent events: []
assistantCommentary=true, tagVisibility.plan=true parent events: ["codex: plan: inspect the runtime handoff first"]

• Observed result after fix: with the default configuration, neither input event produces parent-visible text. With assistantCommentary: true, the phased assistant input produces codex: checking workspace and tool state before the next step. The plan status remains hidden by default and only produces codex: plan: inspect the runtime handoff first when tagVisibility.plan=true.
• What was not tested: a live remote ACP/Codex harness run through an actual user channel. That path depends on host auth/runtime setup and can be long-running or credential-consuming.
• Before evidence: current main had an explicit if (assistantPhase === "commentary") { lastProgressAt = Date.now(); return; } branch in src/agents/acp-spawn-parent-stream.ts.

Tests and validation

Commands run:

• CI=true pnpm install --frozen-lockfile --ignore-scripts --prefer-offline
• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/acp-spawn-parent-stream.test.ts --pool forks --maxWorkers=1 (passed: 17 tests)
• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/acp-spawn.test.ts --pool forks --maxWorkers=1 -t 'streamTo="parent"|announces parent relay start' (passed: 4 tests, 61 skipped)
• node scripts/run-vitest.mjs run --config test/vitest/vitest.runtime-config.config.ts src/config/schema.help.quality.test.ts src/config/schema.test.ts --pool forks --maxWorkers=1 (passed: 71 tests)
• pnpm exec oxfmt --check src/agents/acp-spawn.ts src/agents/acp-spawn-parent-stream.ts src/agents/acp-spawn-parent-stream.test.ts src/auto-reply/reply/acp-stream-settings.ts src/config/types.acp.ts src/config/zod-schema.ts src/config/schema.help.ts src/config/schema.labels.ts (passed)
• pnpm config:docs:check (passed after pnpm config:docs:gen)
• pnpm tsgo:prod (passed after the follow-up fixes)
• pnpm exec oxlint --tsconfig config/tsconfig/oxlint.core.json src/agents/acp-spawn.ts src/agents/acp-spawn-parent-stream.ts src/agents/acp-spawn-parent-stream.test.ts src/auto-reply/reply/acp-stream-settings.ts src/config/schema.help.ts --type-aware --report-unused-disable-directives-severity error --threads=4 (passed)
• git diff --check (passed)

Regression coverage added:

• Default commentary suppression remains tested.
• New opt-in commentary relay is tested.
• New opt-in ACP status progress relay honors acp.stream.tagVisibility.
• Hidden ACP status tags such as plan, usage/config/tool/session-info remain suppressed from parent progress unless explicitly enabled by tag visibility.
• Opted-in commentary/status progress is classified as visible output for stall/no-output messaging.
• Config schema/help/doc baseline accepts the new key.

Acceptance proof:

• Default-off suppression is covered by suppresses commentary-phase assistant relay text and the status-progress proof script default case.
• Opt-in relay is covered by the assistant-commentary enabled test and the ACP status-progress enabled-with-tag-visibility test.
• Stall/no-output classification is covered by the opted-in visible-output test.
• Config schema/help/docs coverage proves the new key is documented and accepted.

Failed/limited:

• pnpm tsgo:test:src was started earlier as a broader compile check but produced no output for roughly 95 seconds; it was terminated to avoid a long local validation run.
• pnpm check:test-types was started after the follow-up type-shape fix, but local tsgo:core:test produced no diagnostics or completion after roughly 4 minutes 20 seconds and was terminated. Remote CI should carry broader test typechecking.
• pnpm lint --threads=4 was started after the tag-visibility fix, but the local core shard produced no diagnostics after roughly 5 minutes 30 seconds and was terminated. The changed TypeScript files passed targeted type-aware oxlint; remote CI should carry broad lint.

Risk checklist

Did user-visible behavior change? (Yes/No)

Yes, but only when acp.stream.assistantCommentary: true is set. Defaults remain unchanged.

Did config, environment, or migration behavior change? (Yes/No)

Yes. Adds an optional config key under acp.stream; no migration required.

Did security, auth, secrets, network, or tool execution behavior change? (Yes/No)

No tool execution/auth/network behavior changes. The user-visible risk is exposing assistant-authored commentary/status progress text when explicitly configured and allowed by tag visibility. This relies on the ACP phase/status contract; it does not opt into hidden reasoning or chain-of-thought.

What is the highest-risk area?

Accidentally making commentary/status progress visible by default, relaying hidden thought/status tags, or changing final-answer behavior.

How is that risk mitigated?

The new option defaults off, existing suppression tests remain, hidden ACP status tags are filtered, and the implementation only changes the parent-stream relay branch when assistantCommentary === true. Final-answer relay code remains on the existing path.

Current review state

Next action: maintainer review.

Waiting on: maintainer preference on the exact config name/namespace. Current-head CI/proof checks are green or intentionally skipped.

Bot/reviewer comments addressed: none yet.