Docs: Document tool_response schema for each tool type in Hooks documentation
Summary
The Hooks documentation correctly states that tool_response schema varies by tool, but doesn't document the actual schema for each tool type. This led me to implement a PostToolUse hook with incorrect assumptions about the Bash tool's response structure.
Current State
The docs show only a Write tool example:
"tool_response": {
"filePath": "/path/to/file.txt",
"success": true
}
And note: "The exact schema for tool_input and tool_response depends on the tool."
What I Expected
For Bash tool, I assumed the response would include exit_code (a common pattern). The actual structure is:
"tool_response": {
"stdout": "...",
"stderr": "...",
"interrupted": false,
"isImage": false
}
Suggestion
Document the tool_response schema for each built-in tool:
- Bash:
stdout,stderr,interrupted,isImage - Read: (schema)
- Write:
filePath,success - Edit: (schema)
- Grep: (schema)
- Glob: (schema)
- etc.
This would help developers building hooks to correctly detect failures, parse responses, and handle tool-specific behavior without needing to add debug logging first.
Impact
Without this documentation, developers must:
- Add debug logging to discover the actual schema
- Make incorrect assumptions (as I did with
exit_code) - Fix their code after discovering the real structure
A reference table of tool response schemas would prevent this friction.
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗