anthropics / anthropics/claude-agent-sdk-typescript

Undocumented behavior changes in 0.3.208–0.3.217: raw transcript in TaskOutput results, non-deterministic SubagentStop for background subagents

Abierto
#388 0 comentarios 1 reacción 0 asignados Ver en GitHub
Lenguaje dominante
Shell
Estrellas
1.8k
Forks
226
Métricas de merge de PR
Sin PR fusionados en 30 d

Descripción

## Summary

Upgrading `@anthropic-ai/claude-agent-sdk` 0.3.207 → 0.3.217 surfaced four behavior changes. Two are covered by the CHANGELOG (`skippedLinks` on `rewindFiles`, `updatedToolOutput` working for built-in tools — thank you); two are documented nowhere we could find (CHANGELOG, GitHub releases, or the Agent SDK docs at code.claude.com). Both undocumented changes are load-bearing for hosts, and one has security implications for multi-tenant applications. All observations below were confirmed with live runs against 0.3.217.

## Change 1 — `TaskOutput` now returns the subagent's raw transcript (`isRawTranscript`)

**Before (0.3.207):** polling `TaskOutput` for a still-running or failed background subagent returned `task.output` / `task.result` as empty strings.

**After (0.3.217):** the same poll returns the subagent's raw JSONL transcript-so-far in `task.output` / `task.result`, flagged with a new, undocumented `task.isRawTranscript: true` field. The transcript content is timing-dependent (an instantly-failing subagent can still snapshot empty strings alongside the flag). The structured `task.status` / `task.error` fields are unchanged.

**Why this matters:** the raw transcript includes the subagent's system prompt and full reasoning. Because it arrives inside an ordinary tool result, it flows into the calling agent's context and into anything the host persists or streams from tool results. Multi-tenant hosts that treat subagent transcripts as sensitive must now actively sanitize this payload (PostToolUse `updatedToolOutput` works for this on 0.3.217 — but nothing tells you that you need to).

**Ask:** a CHANGELOG entry for when this was introduced, documentation of `isRawTranscript` and the payload shape (including that content is timing-dependent), and a note in the docs flagging the data-sensitivity implication.

## Change 2 — `SubagentStop` is no longer reliable for background subagents

**Observed on 0.3.217, across repeated live runs of the same scenario:**
- Successful background subagent: `SubagentStop` fires on some runs and not others (when it fires, it races turn settlement).
- Failed background subagent (e.g. invalid model): `SubagentStop` does not fire.
- `SubagentStart` and the `task_started` / `task_notification` / `background_tasks_changed` lifecycle remain deterministic.

**Why this matters:** the hooks documentation still presents `SubagentStop` as the way to track subagent completion, with no reliability caveat — and `agent_transcript_path` is available *only* on `SubagentStopHookInput`, so a host that keys transcript access or terminal bookkeeping on this hook silently loses both on the runs where it doesn't fire. We had to reverse-engineer the on-disk layout (`//subagents/agent-.jsonl`) to recover the transcript path from the deterministic `task_notification` signal instead.

**Ask:** document `SubagentStop`'s reliability semantics for background subagents (or fix the omission if it's unintended), and provide a supported deterministic source for `agent_transcript_path` — e.g. on the `task_notification` message or the `TaskOutput` result.

## Environment

- `@anthropic-ai/claude-agent-sdk` 0.3.217 (upgraded from 0.3.207), TypeScript, Node 24, Windows 11
- Background subagents via the `Agent` tool with `run_in_background`, polled with `TaskOutput`
- Reproduction sketch: define a subagent with an invalid model, launch with `run_in_background: true`, poll `TaskOutput` with `block: true` → observe `isRawTranscript: true` with transcript-so-far in `output`/`result`, `SubagentStop` never firing, and `task_notification: failed` arriving normally. For the success-path raciness, run a trivial successful background subagent repeatedly and observe `SubagentStop` presence varying across runs.

Guía de contribución

No hay ninguna guía de contribución indexada para este repositorio

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.