Docs: Document tool_response schema for each tool type in Hooks documentation

Resolved 💬 4 comments Opened Jan 20, 2026 by theoBLT Closed Mar 1, 2026

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:

  1. Add debug logging to discover the actual schema
  2. Make incorrect assumptions (as I did with exit_code)
  3. Fix their code after discovering the real structure

A reference table of tool response schemas would prevent this friction.

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗