[FEATURE] Let PostToolUseFailure hooks replace the error output the model sees (re-file of #77180)

Re-filing #77180, which was auto-closed as stale on 2026-09-18 without a maintainer response. The gap is still present in v2.1.280.

Problem

A PostToolUse hook can replace the output the model sees for a successful built-in tool call via hookSpecificOutput.updatedToolOutput (for Bash, the object {stdout, stderr, interrupted, isImage}). A PostToolUseFailure hook has no equivalent. When a Bash command exits nonzero, the full raw error text always reaches the model, and a hook can only append to it.

This blocks output-bounding and redaction hooks exactly where they matter most: failing builds and test runs produce the largest outputs, and error output is where secrets, tokens, and paths tend to leak.

Reproduction (v2.1.280, Linux)

Register a PostToolUseFailure hook on Bash that spills the error to disk and emits a short digest, then run a command such as seq 1 2000; false (2001 lines, exit 1). Each of the following was tested live; in every case the model received all 2001 raw lines:

| Hook response | Result |
|---|---|
| hookSpecificOutput: {hookEventName: "PostToolUseFailure", updatedToolError: "<digest>"} | ignored |
| hookSpecificOutput: {hookEventName: "PostToolUseFailure", updatedToolOutput: {stdout: "<digest>", stderr: "", interrupted: false, isImage: false}} | ignored |
| top-level decision: "block", reason: "<pointer>" | raw error delivered; reason appended as a separate "hook blocking error" message |
| exit code 2 with the pointer on stderr | same as block |

For comparison, the same hook's PostToolUse branch with object-form updatedToolOutput correctly replaces the output of a successful command (seq 1 2000).

Unknown keys in the failure response are stripped without a warning, so a hook author gets no signal that the replacement was discarded.

Request

Add a documented way for PostToolUseFailure hooks to replace the error content the model sees, for example hookSpecificOutput.updatedToolError (string) or updatedToolOutput accepting the tool's error shape. As noted on #77180, the failure payload carries an error string rather than a tool_response, so a string-valued replacement for error would be the natural fit.

At minimum, please warn (or document) when a failure-hook response contains replacement keys that are dropped.

Current workaround

The only workaround we can see is a PreToolUse hook that rewrites the Bash command via updatedInput so the shell itself spills and truncates output while preserving the exit code. That changes the command the user approves and sees, and interacts with other PreToolUse hooks that inspect command text, so native support would be much cleaner.

Related: #77180 (original request), #86753 and #68951 (success-path shape requirement), #96193 (other silently dropped hook fields).