[BUG] Subagents appear to stop with no reason

[rudra-sett]

When running subagents with (run_in_background=True), no max_turns, some subagents send SubagentStop right after receiving a tool result successfully. In observed examples, the context window is not close to being filled.

This is one such example from the subagent JSONL log:

{"parentUuid":"7df5ab02-b2ad-4f42-a8fc-f8d94ee2a775","isSidechain":true,"userType":"external","cwd":"/home/user","sessionId":"a0c74ac8-27a4-4ed7-87b3-4d6c9527bfaa","version":"2.1.59","gitBranch":"HEAD","agentId":"aada4f57f1757310e","slug":"abundant-wibbling-swing","type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01XHeaLcTb3KAtKfEMEndmej","type":"tool_result","content":[{"type":"text","text":"original tool result removed for brevity"}]}]},"uuid":"01da8465-6438-4e98-94c7-3808ac37da08","timestamp":"2026-03-03T11:27:09.707Z","sourceToolAssistantUUID":"7df5ab02-b2ad-4f42-a8fc-f8d94ee2a775"}
{"parentUuid":"01da8465-6438-4e98-94c7-3808ac37da08","isSidechain":true,"userType":"external","cwd":"/home/user","sessionId":"a0c74ac8-27a4-4ed7-87b3-4d6c9527bfaa","version":"2.1.59","gitBranch":"HEAD","agentId":"aada4f57f1757310e","slug":"abundant-wibbling-swing","type":"progress","data":{"type":"hook_progress","hookEvent":"SubagentStop","hookName":"SubagentStop","command":"callback"},"parentToolUseID":"5edf13c0-4c7d-422d-a2e6-56495879cbc0","toolUseID":"5edf13c0-4c7d-422d-a2e6-56495879cbc0","timestamp":"2026-03-03T11:27:13.545Z","uuid":"e29cec7e-67bd-4ee4-9d8b-4bb52aae5343"}

Debug log

3702:2026-03-03T11:27:13.538Z [DEBUG] Stream started - received first chunk
3703:2026-03-03T11:27:13.544Z [DEBUG] Getting matching hook commands for SubagentStop with query: research-assistant
3704:2026-03-03T11:27:13.544Z [DEBUG] Found 1 hook matchers in settings
3705:2026-03-03T11:27:13.544Z [DEBUG] Matched 1 unique hooks for query "research-assistant" (1 before deduplication)
3706:2026-03-03T11:27:13.623Z [DEBUG] Writing to temp file: /home/user/.claude.json.tmp.442.1772537233623

I would expect the subagent to continue to work here, or at the very least, provide a ResultMessage which explains why it stopped. This looks like more of a bug than agent behavior.

[weiguangli-io]

Looking at the JSONL log and the SDK internals, here is what I think is happening:

Observed behavior: The subagent receives a valid tool_result (user message), then ~4 seconds later fires SubagentStop as a progress event. No AssistantMessage is emitted between the tool result and the stop, and critically, no ResultMessage is ever yielded to the SDK consumer.

Likely root cause: When the CLI's inner agent loop processes the tool result and sends it to the API, the API response comes back with a stop_reason that the CLI interprets as terminal (e.g., end_turn with no further tool calls). The CLI fires the SubagentStop hook correctly, but the issue is twofold:

1. Missing ResultMessage for background tasks: For isSidechain: true subagents, the CLI appears to emit SubagentStop as a hook/progress event but does not always emit a corresponding result message on the JSONL stream. The SDK's _read_messages in query.py only sets _first_result_event on type == "result" messages, so if no result is emitted, the consumer never gets a ResultMessage with stop_reason explaining why the subagent terminated.

2. Premature end_turn from the API: The model may be returning end_turn after processing the tool result without producing any text content. This could be a model-level issue (the model decides it has nothing more to say), but the SDK/CLI should still surface this as a ResultMessage with stop_reason: "end_turn" rather than silently stopping.

Proposed fix direction: The CLI should guarantee that every SubagentStop hook is preceded by (or accompanied by) a ResultMessage on the message stream, even for sidechain/background subagents. Concretely:

• When the inner agent loop for a subagent terminates (for any reason), emit a result message with the appropriate stop_reason, num_turns, and is_error fields before firing SubagentStop.
• If the stop was unexpected (no assistant content produced after the last tool result), consider setting is_error: true or adding a diagnostic field so SDK consumers can distinguish normal completion from this edge case.
• On the SDK side, TaskNotificationMessage (subtype task_notification) should include the stop_reason from the underlying subagent result, so consumers using the system message stream also get visibility.

This would make the behavior observable and actionable for SDK consumers, rather than requiring them to infer from the absence of a result message that something went wrong.

Would this approach work? Happy to submit a PR if so.

[tumtumtum]

We are experiencing this too