[1.x] Report a sub-agent that throws as a failed tool call
When a sub-agent used as a tool throws (a provider error, a timeout), AgentTool catches it and returns Agent failed: <message> as a normal result. The catch was added on purpose in #348: before #1191, it was what kept the parent run alive, because any tool that threw ended the run. Since #1191 every other tool's failure is recovered, but to the rest of the package a failed sub-agent still looks like a successful call:
ToolInvokedis dispatched with the error text as the result, andToolFailednever is.- The step's
ToolResulthasfailed: false, sosuccessful()is true anderror()is null, in the response, the stream'stool_resultevent and the stored conversation.
A listener or UI that shows tool status can only spot a failed sub-agent by matching the Agent failed: prefix.
This PR removes the catch from AgentTool, so a sub-agent's failure is handled like any other tool's:
- Prompted:
executeTool()dispatchesToolFailed, and the model gets a failed result,The tool call failed: <message>. The exception is reported and the parent run continues, as for any tool since #1191. - Streamed:
executeAgentToolStreaming()catches a throw from the sub-agent's stream and does the same. It had notry/catchbefore, becauseAgentTool::stream()never threw. - Resumed after approval: unchanged. That path already turns any tool's exception into a failed result, without reporting it, as #1191 left it.
The sub-agent's own AgentFailed is still dispatched.
[!WARNING]
- The model now reads
The tool call failed: … instead of Agent failed: …. Agents whose instructions mention the old text need the new wording.
- A failing sub-agent is now passed to
report(), so it shows up in the exception handler (Sentry, Flare) like any other failed tool.
ToolInvoked is no longer dispatched for a sub-agent that throws. Listen for ToolFailed instead.
- Code that calls
AgentTool::handle() or AgentTool::stream() directly now gets the exception instead of an Agent failed: string.
Until this ships, wrapping the sub-agent in a plain Tool whose handle() calls $agent->prompt() gets the same failed result, at the cost of the sub-agent's streamed output.
Tests cover a throwing sub-agent on the prompted and streamed paths, including one that throws after it has streamed output: ToolFailed, no ToolInvoked, the sub-agent's own AgentFailed, a failed result, and the parent run continuing.