[Idea] Let rich subagent providers expose events and sessions without complicating one-shot runs

[Risu12138]

Hi! I have spent some time reading the Subagent implementation, especially the Codex provider, and wanted to share where I landed.

My first reaction was that CodexProvider looked almost too thin. After following the call chain, I changed my mind: most of that simplicity is earned by the Subagent layer. The framework owns provider registration, capability checks, descriptors, parent/child identity, cancellation, result settlement, lifecycle events, and disposal; the provider only owns the backend-specific mechanism.

That is a clean design for one-shot delegation.

This exploration started from a few practical questions:

• Does changing tools across turns hurt prompt caching?
• How does DSH keep parent and child context separate?
• How are Codex and Claude Code actually integrated?
• Where do streaming output, reasoning summaries, approvals, and file side effects go?
• Can an external agent keep a real multi-turn session?

Following those questions through the code made one tradeoff stand out:

Today, a rich external agent is intentionally compressed into an asynchronous one-shot function call.

The current public handle is essentially:

interface SubagentRun {
  readonly result: Promise<SubagentResult>
  dispose(): Promise<void>
}

Source: SubagentRun

That is a very good minimum. I wonder whether it could remain the minimum while gaining a few optional layers for richer providers.

1. An observation stream separate from model context

Codex App Server can emit agent-message deltas, reasoning summaries, command output, file changes, tool progress, and usage updates. The current Codex adapter deliberately keeps only the completed final answer, which fits the existing SubagentRun result contract.

The limitation is that there is no standard place to expose those events even to UI, tracing, or diagnostics.

A possible incremental extension:

interface SubagentRun {
  readonly events?: AsyncIterable<SubagentEvent>
  readonly result: Promise<SubagentResult>
  dispose(): Promise<void>
}

The important part would be semantic, not just syntactic:

events → UI / tracing / observability
result → parent Agent Tool Result

Intermediate events should not automatically enter the parent model context. That keeps context and prompt caching stable while still allowing users to see what the child is doing.

2. An optional external-session capability

The one-shot path creates a fresh Codex process, ephemeral thread, and single turn. Meanwhile, Codex App Server itself supports thread resume/fork and turn steer/interrupt.

DSH's continuation manager is strong for DSH-owned children, but the current Provider contract does not give an external provider ownership of a persistent remote session.

Rather than stretching SubagentRun, perhaps this deserves a separate optional capability, something along the lines of:

interface ExternalSubagentSession {
  turn(input: ContentBlock[]): Promise<SubagentTurn>
  steer(input: ContentBlock[]): Promise<void>
  dispose(): Promise<void>
}

Providers that only support one-shot work would stay exactly as they are. Codex, ACP, or future remote agents could opt into the richer lifecycle.

3. Structured effects and diagnostics

A child can modify the shared workspace and then finish with stopReason: "error". The parent learns that the run failed, but the generic result does not describe:

• which files changed;
• which commands or tools ran;
• what artifacts were produced;
• token usage;
• remote thread/turn identifiers;
• whether partial side effects remain.

It might be useful for SubagentResult to optionally carry provider-neutral metadata such as changes, artifacts, usage, structured diagnostics, and provider correlation IDs. This would make failures and side effects easier to inspect without forcing backend-specific details into the final assistant text.

Why I think this can be incremental

I would not replace the current one-shot seam. Its small surface is a feature:

• simple providers stay simple;
• capability mismatches fail loudly;
• cancellation and disposal have one shared meaning;
• the parent receives one predictable final result.

The possible direction is additive:

One-shot result        mandatory, unchanged
Observation events     optional
Persistent session     optional capability
Effects/diagnostics    optional result metadata

This would preserve the good part of the current design while avoiding a lowest-common-denominator ceiling for richer Agent backends.

I realize some of these choices may be intentionally deferred while DSH is still pre-release, and I may be missing constraints that are obvious to the maintainers. I would be very interested in the team's view on where the Subagent seam is meant to stop.

Also, I noticed the repository currently does not accept external pull requests. If the team would like community help on a small, well-scoped part of this area, I would genuinely enjoy contributing code, tests, and documentation. Feel free to invite or point me (@Risu12138) at a concrete slice — I promise to start smaller than this discussion. 🙂

[weijiafu14]

A concrete data point from the Pi-plugin route may be useful for the additive design proposed here.

In pi2dsh, a Pi extension calling createAgentSession() is translated onto the public DSH Agent registry. Each child is a genuine DSH session with the official subagent/descriptor event and parent lineage, while the Pi package keeps the richer lifecycle: background execution, tool activity, explicit mid-run steer, result wait, stop, resume, and reopen from disk.

The persistent-session half has been exercised across two separate OS processes: process 1 records the child's archive identity; process 2 reopens that exact DSH session through agents.resume({ resumeSessionId, setup }); the same session log grows from one turn to two and the child recalls information without rereading the source. The steer path is also tested with an instruction whose filename/content exist only in the steer message, followed by an observable file effect.

This does not solve the optional event/session contract for out-of-process Codex/ACP providers, but it is evidence that the proposed rich lifecycle can coexist with DSH's mandatory one-shot minimum when the provider can materialize a native child session. The descriptor + lineage + persisted-resume shape may be useful as the normalization target.

Implementation and falsifiable acceptance:
https://github.com/weijiafu14/pi2dsh/tree/main/examples/subagents
https://github.com/weijiafu14/pi2dsh/blob/main/community/subagents-acceptance-report.md