Feature Request: Enable Hooks to Return Rich, Structured Feedback

Title: Feature Request: Enable Hooks to Return Rich, Structured Feedback

Labels: enhancement, feature-request, hooks, tools, developer-experience

Overview

Claude Code hooks provide a mechanism for custom tools to feed information back to the model, typically via stderr or the reason field in a JSON response. This is effective for simple text-based feedback.

However, to unlock more advanced agentic workflows, hooks need the ability to return complex, structured, and multi-modal information directly to Claude. This proposal outlines an enhancement to the hook output schema to support rich, structured content.

The Problem: Feedback is Limited to Plain Text

Currently, the feedback a hook can provide to Claude is limited to a single string. This forces developers to serialize any complex information (like JSON data, tables, or file paths) into text. The model must then parse this serialized string in its next turn, which is inefficient, error-prone, and costly in terms of tokens.

For example, a hook that runs a data analysis script and generates a visualization cannot return the image directly. It can only return a text description or a file path, forcing the model to take another step to process the visualization.

Proposed Solution

Enhance the hook JSON output schema to include an optional feedback_content field. This field would accept an array structured identically to the content array in the Anthropic Messages API.

This would allow hooks to return a rich mix of content blocks, including:

• text
• image
• tool_result
• Any future content block types supported by the Messages API.

When a hook returns feedback_content, this content would be appended to the conversation history and be made available to Claude for its next turn.

Example

A PostToolUse hook runs a data analysis script that generates a plot and a summary. Instead of returning a file path, it could return the image and text directly:

// A hook runs a data analysis tool and returns a plot and summary.
{
  "decision": "continue",
  "suppressOutput": true, // Optional: Hide the raw tool output from the user
  "feedback_content": [
    {
      "type": "text",
      "text": "The data analysis is complete. Here is a visualization of the results:"
    },
    {
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/png",
        "data": "iVBORw0KGgoAAAANSUhEUg..."
      }
    },
    {
      "type": "text",
      "text": "The plot shows a clear upward trend in Q3 sales, which aligns with the launch of the new product line."
    }
  ]
}

Claude would receive this multi-modal content directly, enabling a more sophisticated follow-up analysis in the very next turn without needing to read files or parse complex text.

Benefits

• Richer Context: Hooks can provide multi-modal data (images, charts) or structured data (JSON, XML) that Claude can immediately understand and reason about.
• Reduced Ambiguity: The model doesn't need to parse serialized text, eliminating potential misinterpretations and hallucinations.
• Lower Token Costs: The model receives pre-structured data, reducing the need for prompts that explain how to parse a complex string or instructions to read a file from disk.
• Enables New Workflows: Unlocks powerful use cases like automated data visualization, returning structured error reports, or chaining tool results in a more native way.

Conclusion

Allowing hooks to return rich, structured content would significantly elevate their utility. It would enable a much tighter and more powerful integration between custom tools and the model, fostering more complex and reliable agentic behaviors. This moves hooks beyond simple text feedback and toward a true structured data exchange with the LLM.