Summary

• Problem: ACP sessions_spawn runs are non-blocking but gave poor parent-session visibility during long or blocked initial turns.
• Why it matters: Orchestrator sessions could not see child progress/no-output state without external process inspection.
• What changed:
  • Added sessions_spawn.streamTo: "parent" support for runtime: "acp".
  • Added ACP parent relay that forwards initial child-run progress/no-output/completion/failure updates into requester session system events.
  • When streamTo: "parent" is used, direct child delivery for that initial run is disabled.
  • Added tests for relay behavior, ACP spawn behavior, and schema/tool forwarding.
  • Updated docs and changelog.
• What did NOT change (scope boundary):
  • No persistent tail-log file or full WebSocket parity implementation yet; this addresses parent visibility for the initial run path.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related [Feature]: ACP Session Streaming/Log Forwarding to Orchestrator #29909

User-visible / Behavior Changes

• sessions_spawn now accepts streamTo: "parent" for ACP runtime.
• With runtime: "acp" + streamTo: "parent", requester session receives progress/no-output/completion/failure system-event updates for the initial child run.
• Initial child run uses deliver: false in that mode to avoid direct child-delivery duplication.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22+
• Model/provider: ACP harness session path
• Integration/channel (if any): sessions/tool runtime path
• Relevant config (redacted): ACP enabled

Steps

1. Run sessions_spawn with { runtime: "acp", streamTo: "parent", task: "..." } from an active requester session.
2. Observe system-event updates in requester session while child run executes.
3. Verify direct child delivery is disabled for that initial run.

Expected

• Parent session receives progress/no-output/completion updates for initial ACP run.

Actual

• Covered by new tests and implementation.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • relay progress + completion updates
  • no-output + resumed update behavior
  • ACP spawn streamTo parent dispatch behavior (deliver=false)
  • sessions tool schema/forwarding updates
• Edge cases checked:
  • streamTo: "parent" rejected when requester session context is missing
• What you did not verify:
  • end-to-end channel UX on live gateway/channel environment

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly:
  • stop using streamTo: "parent" (default behavior unchanged)
  • revert relay + ACP spawn stream target commits
• Files/config to restore:
  • src/agents/acp-spawn-parent-stream.ts
  • src/agents/acp-spawn.ts
  • src/agents/tools/sessions-spawn-tool.ts
• Known bad symptoms reviewers should watch for:
  • missing or noisy requester system-event updates
  • unexpected delivery suppression when not using streamTo: "parent"

Risks and Mitigations

• Risk:
  • Parent relay could produce noisy updates on very chatty child output.
  • Mitigation:
    • Buffered/compacted forwarding with periodic flush and bounded snippets.
• Risk:
  • Missing requester session key with streamTo: "parent" could silently fail.
  • Mitigation:
    • Explicit validation error when requester session context is unavailable.

Original PR: #34055