Add post-tool-use failure hooks (#1421)

* Add post-tool-use failure hook

Expose postToolUseFailure hooks across SDKs, wire runtime hook dispatch, update docs, and add cross-language E2E coverage for failed tool results.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Format Python hook tests

Apply ruff formatting to the post-tool-use failure hook unit tests.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address PR review feedback

Fix Rust E2E formatting and update docs-maintenance Python validation paths.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix Python lint issues

Sort hook exports and wrap the long E2E prompt string.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix failure hook snapshot text

Match the bundled runtime's postToolUseFailure guidance label in the shared E2E snapshot.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix Rust hook E2E helper

Make the Rust E2E RecordingHooks failure hook a no-op unless the failure hook is explicitly configured.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: stephentoub

.github/agents/docs-maintenance.agent.md

@@ -344,7 +344,7 @@ cat nodejs/src/types.ts | grep -A 10 "export interface ExportSessionOptions"
 - `CopilotClient` constructor options: `cliPath`, `cliUrl`, `useStdio`, `port`, `logLevel`, `autoStart`, `env`, `githubToken`, `useLoggedInUser`
 - `createSession()` config: `model`, `tools`, `hooks`, `systemMessage`, `mcpServers`, `availableTools`, `excludedTools`, `streaming`, `reasoningEffort`, `provider`, `infiniteSessions`, `customAgents`, `workingDirectory`
 - `CopilotSession` methods: `send()`, `sendAndWait()`, `getMessages()`, `disconnect()`, `abort()`, `on()`, `once()`, `off()`
-- Hook names: `onPreToolUse`, `onPostToolUse`, `onUserPromptSubmitted`, `onSessionStart`, `onSessionEnd`, `onErrorOccurred`
+- Hook names: `onPreToolUse`, `onPostToolUse`, `onPostToolUseFailure`, `onUserPromptSubmitted`, `onSessionStart`, `onSessionEnd`, `onErrorOccurred`
 
 #### Python Validation
 
@@ -353,16 +353,16 @@ cat nodejs/src/types.ts | grep -A 10 "export interface ExportSessionOptions"
 grep -E "^\s+async def [a-z]" python/copilot/client.py python/copilot/session.py
 
 # Key types
-cat python/copilot/types.py | grep -A 20 "class CopilotClientOptions"
-cat python/copilot/types.py | grep -A 30 "class SessionConfig"
-cat python/copilot/types.py | grep -A 15 "class SessionHooks"
+cat python/copilot/client.py | grep -A 20 "class _CopilotClientOptions"
+cat python/copilot/client.py | grep -A 80 "async def create_session"
+cat python/copilot/session.py | grep -A 15 "class SessionHooks"
 ```
 
 **Must match (snake_case):**
 - `CopilotClient` options: `cli_path`, `cli_url`, `use_stdio`, `port`, `log_level`, `auto_start`, `env`, `github_token`, `use_logged_in_user`
 - `create_session()` config keys: `model`, `tools`, `hooks`, `system_message`, `mcp_servers`, `available_tools`, `excluded_tools`, `streaming`, `reasoning_effort`, `provider`, `infinite_sessions`, `custom_agents`, `working_directory`
 - `CopilotSession` methods: `send()`, `send_and_wait()`, `get_messages()`, `disconnect()`, `abort()`, `export_session()`
-- Hook names: `on_pre_tool_use`, `on_post_tool_use`, `on_user_prompt_submitted`, `on_session_start`, `on_session_end`, `on_error_occurred`
+- Hook names: `on_pre_tool_use`, `on_post_tool_use`, `on_post_tool_use_failure`, `on_user_prompt_submitted`, `on_session_start`, `on_session_end`, `on_error_occurred`
 
 #### Go Validation
 
@@ -380,7 +380,7 @@ cat go/types.go | grep -A 15 "type SessionHooks struct"
 - `ClientOptions` fields: `CLIPath`, `CLIUrl`, `UseStdio`, `Port`, `LogLevel`, `AutoStart`, `Env`, `GithubToken`, `UseLoggedInUser`
 - `SessionConfig` fields: `Model`, `Tools`, `Hooks`, `SystemMessage`, `MCPServers`, `AvailableTools`, `ExcludedTools`, `Streaming`, `ReasoningEffort`, `Provider`, `InfiniteSessions`, `CustomAgents`, `WorkingDirectory`
 - `Session` methods: `Send()`, `SendAndWait()`, `GetMessages()`, `Disconnect()`, `Abort()`, `ExportSession()`
-- Hook fields: `OnPreToolUse`, `OnPostToolUse`, `OnUserPromptSubmitted`, `OnSessionStart`, `OnSessionEnd`, `OnErrorOccurred`
+- Hook fields: `OnPreToolUse`, `OnPostToolUse`, `OnPostToolUseFailure`, `OnUserPromptSubmitted`, `OnSessionStart`, `OnSessionEnd`, `OnErrorOccurred`
 
 #### .NET Validation
 
@@ -398,7 +398,7 @@ cat dotnet/src/Types.cs | grep -A 15 "public class SessionHooks"
 - `CopilotClientOptions` properties: `CliPath`, `CliUrl`, `UseStdio`, `Port`, `LogLevel`, `AutoStart`, `Environment`, `GithubToken`, `UseLoggedInUser`
 - `SessionConfig` properties: `Model`, `Tools`, `Hooks`, `SystemMessage`, `McpServers`, `AvailableTools`, `ExcludedTools`, `Streaming`, `ReasoningEffort`, `Provider`, `InfiniteSessions`, `CustomAgents`, `WorkingDirectory`
 - `CopilotSession` methods: `SendAsync()`, `SendAndWaitAsync()`, `GetMessagesAsync()`, `DisposeAsync()`, `AbortAsync()`, `ExportSessionAsync()`
-- Hook properties: `OnPreToolUse`, `OnPostToolUse`, `OnUserPromptSubmitted`, `OnSessionStart`, `OnSessionEnd`, `OnErrorOccurred`
+- Hook properties: `OnPreToolUse`, `OnPostToolUse`, `OnPostToolUseFailure`, `OnUserPromptSubmitted`, `OnSessionStart`, `OnSessionEnd`, `OnErrorOccurred`
 
 #### Common Sample Errors to Check