Add post-tool-use failure hooks

[stephentoub]

Adds a post-tool-use failure hook so SDK users can observe failed tool executions and inject follow-up guidance without conflating failures with the success-only postToolUse hook.

Summary

• Exposes postToolUseFailure/on_post_tool_use_failure/OnPostToolUseFailure across Node, Python, Go, .NET, and Rust.
• Maps runtime wire fields consistently to each SDK's public hook shape, including timestamp conversion and cwd -> workingDirectory naming.
• Wires hook dispatch and hook activation for session create/resume flows.
• Documents the failure-only behavior and adds cross-language E2E coverage using a shared replay snapshot.

Validation

• Node typecheck and targeted postToolUseFailure E2E
• Python targeted postToolUseFailure E2E
• Go targeted postToolUseFailure E2E
• Rust targeted postToolUseFailure E2E
• .NET SDK build and targeted postToolUseFailure E2E

[stephentoub]

@SteveSandersonMS this looks like an accidental omission... please take a quick look at the surface area to make sure it's in line with all the refactorings you've been doing.

[Copilot]

Pull request overview

Adds a dedicated post-tool-use failure hook across SDKs so consumers can observe tool executions that ended with a "failure" result and optionally inject follow-up guidance without conflating with the success-only postToolUse hook.

Changes:

• Introduces postToolUseFailure hook types/handlers and hook-dispatch wiring across Node.js, Python, Go, .NET, and Rust.
• Adds cross-language E2E coverage via a shared replay snapshot plus targeted unit tests for hook dispatch/normalization.
• Updates hook documentation to clearly distinguish success-only onPostToolUse from failure-only onPostToolUseFailure and reflects cwd -> workingDirectory / timestamp conversions.

Show a summary per file

File	Description
test/snapshots/hooks_extended/should_invoke_posttoolusefailure_hook_for_failed_tool_result.yaml	New replay snapshot that exercises a failed tool call and the injected failure-hook guidance.
rust/tests/e2e/hooks_extended.rs	Adds Rust E2E validating on_post_tool_use_failure fires (and postToolUse does not) for failed tool results.
rust/src/hooks.rs	Adds Rust hook input/output types, dispatch plumbing, and unit tests for postToolUseFailure.
rust/README.md	Documents the new Rust hook event and clarifies success vs failure hook semantics.
python/test_client.py	Adds Python unit tests validating postToolUseFailure dispatch + input normalization (timestamp/cwd).
python/README.md	Documents on_post_tool_use_failure and updates the available hooks list.
python/e2e/test_hooks_extended_e2e.py	Adds Python E2E ensuring failure hook fires and injects guidance; verifies on_post_tool_use doesn’t fire.
python/copilot/session.py	Adds Python hook TypedDicts/handler type for failure hook and wires it into dispatch map.
python/copilot/init.py	Exports the new Python hook types/handler.
nodejs/test/e2e/hooks_extended.e2e.test.ts	Adds Node E2E that asserts onPostToolUseFailure invocation and guidance injection.
nodejs/test/client.test.ts	Adds Node unit tests covering dispatch routing and wire→public normalization for postToolUseFailure.
nodejs/src/types.ts	Introduces PostToolUseFailure* public types and documents success-only vs failure-only hook behavior.
nodejs/src/session.ts	Wires postToolUseFailure into handler map; hook input normalization maps cwd → workingDirectory.
nodejs/README.md	Documents the new failure hook and updates available hooks list/wording.
nodejs/docs/examples.md	Updates hooks overview table and adds guidance/examples for reacting to tool failures.
nodejs/docs/agent-author.md	Updates hook reference to include failure hook and reflect workingDirectory/Date timestamp shapes.
go/types.go	Adds Go PostToolUseFailureHookInput/Output + handler type and includes it in SessionHooks.
go/session.go	Dispatches postToolUseFailure hook invocations to OnPostToolUseFailure.
go/session_test.go	Adds unit tests validating postToolUseFailure dispatch and forward-compat unknown hook handling.
go/README.md	Documents OnPostToolUseFailure and clarifies OnPostToolUse is success-only.
go/internal/e2e/hooks_extended_e2e_test.go	Adds Go E2E asserting failure hook behavior and injected guidance.
go/client.go	Ensures hook activation logic considers OnPostToolUseFailure for create/resume flows.
dotnet/test/E2E/HookLifecycleAndOutputE2ETests.cs	Adds .NET E2E validating OnPostToolUseFailure behavior and message exchange assertions.
dotnet/src/Types.cs	Adds .NET PostToolUseFailureHookInput/Output and exposes OnPostToolUseFailure on SessionHooks.
dotnet/src/Session.cs	Adds dispatch case + JSON source-gen registrations for new hook types.
dotnet/src/Client.cs	Ensures hook activation checks include OnPostToolUseFailure for create/resume.
dotnet/README.md	Documents OnPostToolUseFailure and clarifies OnPostToolUse is success-only.
docs/troubleshooting/compatibility.md	Updates compatibility matrix to include onPostToolUseFailure.
docs/hooks/post-tool-use.md	Clarifies onPostToolUse is success-only and documents the failure variant behavior/signature at a high level.
docs/hooks/hooks-overview.md	Adds failure hook to the hooks overview table and links to the failure-variant anchor.
docs/features/hooks.md	Updates hooks feature overview table and examples to reflect Date/workingDirectory and the failure hook.
.github/agents/docs-maintenance.agent.md	Updates hook name lists used for docs validation guidance (but Python validation commands need correction).

Copilot's findings

• Files reviewed: 32/32 changed files
• Comments generated: 2

[github-actions]

Cross-SDK Consistency Review

This PR does an excellent job of adding postToolUseFailure hooks across Node.js, Python, Go, .NET, and Rust with consistent API shape and naming conventions. 👏

However, Java is the only SDK not updated — it currently has onPostToolUse / PostToolUseHandler / PostToolUseHookInput / PostToolUseHookOutput in java/src/main/java/com/github/copilot/sdk/json/, but the new failure-hook counterparts are absent:

Missing Java artifact	Equivalent in other SDKs
PostToolUseFailureHookInput.java	PostToolUseFailureHookInput (.NET), PostToolUseFailureHookInput (Node/TS), PostToolUseFailureInput (Go/Python)
PostToolUseFailureHookOutput.java	PostToolUseFailureHookOutput (.NET / Node)
PostToolUseFailureHandler.java	PostToolUseFailureHandler (.NET / Node functional interface pattern)
onPostToolUseFailure field in SessionHooks.java	OnPostToolUseFailure (.NET), onPostToolUseFailure (Node), OnPostToolUseFailure (Go)

The Java SessionHooks.hasHooks() guard would also need updating to include the new handler.

Would you like to include the Java implementation in this PR to keep all SDKs in sync, or is a follow-up planned?

Generated by SDK Consistency Review Agent for issue #1421 · ● 2.9M · ◷