Tool results
ToolResult
ToolResult=(
BashResult
| EditResult
| WriteResult
| ReadResult
| TaskResult
| TaskLaunchResult
| SkillResult
| AskUserQuestionResult
| TextResult
| OtherResult
)
ToolResultBase
Common shape of every typed tool result.
Usage
ToolResultBase()Attributes
name: builtins.str-
The tool name exactly as invoked (aliases are not normalized).
raw: collections.abc.Mapping[str, Any] | str | None-
The verbatim
toolUseResultpayload — a mapping for structured results, a plain string for denials, or None when the record carried none. Excluded from equality and repr.
parse_tool_result()
Parse a tool’s name and record-level toolUseResult into the typed hierarchy.
Usage
parse_tool_result(name, payload, *, on_error="raise")The payload is the verbatim toolUseResult — dict, string, or absent. A plain-string payload (a denial) is a TextResult; a payload for a tool the platform does not type is an OtherResult, as is an absent (None) payload. The native result lift is total, so on_error fires only when the payload carries values JSON cannot express: strict mode raises, on_error='other' degrades to a FallbackResult holding the original payload verbatim.
Example
>>> parse_tool_result("Bash", {"stdout": "hi", "stderr": ""}).stdout‘hi’
ToolResultError
A known tool’s result payload did not match its expected shape.
Usage
ToolResultError()BashResult
A Bash/Execute execution result.
Usage
BashResult()EditResult
An Edit result: the applied replacement and its structured patch.
Usage
EditResult()structured_patch and original_file are kept verbatim — the patch as the raw hunk list Claude Code emits, the original file as its full text.
WriteResult
A Write/Create result: the written content and its structured patch.
Usage
WriteResult()ReadResult
A Read result: the file payload and its content type.
Usage
ReadResult()file is kept verbatim — the raw mapping (filePath, content, numLines, …) Claude Code emits for the read window.
TaskResult
A completed Agent/Task subagent run.
Usage
TaskResult()tool_stats, usage, and content are kept verbatim — the raw per-tool stats, usage mapping, and final content-block list the subagent returned.
TaskLaunchResult
An in-flight Agent/Task launch (async or backgrounded subagent).
Usage
TaskLaunchResult()SkillResult
A Skill invocation result.
Usage
SkillResult()AskUserQuestionResult
An AskUserQuestion result: the rounds, the answers, and any annotations.
Usage
AskUserQuestionResult()Attributes
questions: tuple[Question, …]-
The rounds echoed in the native result payload.
answers: collections.abc.Mapping[str, str]-
A mapping from each round’s question text to the chosen answer. Non-string answer values are dropped, mirroring the Rust lift.
annotations: collections.abc.Mapping[str, QuestionAnnotation]- A mapping from question text to the reviewer’s QuestionAnnotation, present only for annotated rounds. Non-string preview/notes leaves read as None, mirroring the Rust lift.
Attributes
| Name | Description |
|---|---|
| questions | The AskUserQuestion rounds echoed in the result payload. |
questions
The AskUserQuestion rounds echoed in the result payload.
questions: tuple[Question, …]
QuestionAnnotation
A reviewer’s annotation on one answered AskUserQuestion round.
Usage
QuestionAnnotation()Attributes
preview: builtins.str | None-
The short preview the picker rendered under the answer, if any.
notes: builtins.str | None- The free-text note the reviewer attached, if any.
TextResult
A plain-string tool result — denials and other unstructured payloads.
Usage
TextResult()OtherResult
A tool result the platform does not type: unknown tools, untyped tools
Usage
OtherResult()(such as TodoWrite), and known tools whose payload shape did not match.