Add methods to HookPart and make them canonical

Author: msullivan

README.md

@@ -150,7 +150,8 @@ approval = await ai.hook(
     metadata={"tool": "send_email"},
 )
 
-ai.resolve_hook("approve_send_email", {"granted": True, "reason": "approved"})
+# From a HookEvent handler, resolve it with the resolve() method:
+event.hook.resolve({"granted": True, "reason": "approved"})
 ```
 
 ## Examples

docs/ai-python/content/docs/basics/durable-execution.mdx

@@ -102,7 +102,7 @@ interleaves model events and tool results while the model is still producing
 output.
 
 Consider using the serverless hook flow for approvals. When a deferred `HookEvent`
-appears, call `ai.defer_hook(event.hook)`, persist `stream.messages`,
+appears, call `event.hook.defer()`, persist `stream.messages`,
 and return the approval request to the client. On the next workflow turn, call
 `ai.resolve_hook(...)` inside the `agent.run(...)` block before iterating the
 stream. The SDK replays the interrupted assistant turn and continues when the

docs/ai-python/content/docs/basics/human-in-the-loop.mdx

@@ -21,7 +21,7 @@ async def notify_mothership(message: str) -> str:
 ```
 
 When the model calls the tool, the agent emits a hook event. Resolve it with
-`ai.resolve_hook`:
+the `resolve()` method:
 
 ```python
 async with agent.run(model, messages) as stream:
@@ -31,25 +31,23 @@ async with agent.run(model, messages) as stream:
             and event.hook.status == "pending"
         ):
             print(event.hook.hook_id, event.hook.metadata)
-            ai.resolve_hook(
-                event.hook,
+            event.hook.resolve(
                 ai.tools.ToolApproval(granted=True, reason="approved"),
             )
 ```
 
 Return a denial by resolving the hook with `granted=False`:
 
 ```python
-ai.resolve_hook(
-    "approve_tool_call_id_here",
+event.hook.resolve(
     ai.tools.ToolApproval(granted=False, reason="not allowed"),
 )
 ```
 
 Cancel a live hook when the waiting workflow should stop:
 
 ```python
-await ai.cancel_hook("approve_tool_call_id_here", reason="client disconnected")
+await event.hook.cancel(reason="client disconnected")
 ```
 
 Hook operations target the current `HookRegistry`, which is set inside the
@@ -106,13 +104,10 @@ approval = await ai.hook(
 )
 ```
 
-Resolve the hook from another part of your application:
+Resolve the hook from your event handler:
 
 ```python
-ai.resolve_hook(
-    "some_hook",
-    {"foo": 999},
-)
+event.hook.resolve({"foo": 999})
 ```
 
 ## Resume in serverless flows
@@ -127,34 +122,29 @@ Using the serverless flow only requires you to update the `agent.run` callsite
 ```python
 # start (or replay pre-hook part of) a run
 async with agent.run(model, messages) as stream:
-    # pre-register tool approvals before iterating the stream
-    for approval in approvals:
-        ai.resolve_hook(
-            approval.hook_id,
-            ai.tools.ToolApproval.model_validate(approval.data)
-        )
+    # apply approvals from the resumed request before iterating the stream
+    ai.agents.ui.ai_sdk.apply_approvals(approvals)
 
     async for event in stream:
         if (
             isinstance(event, ai.events.HookEvent)
             and event.hook.status == "pending"
         ):
             # interrupt the loop
-            ai.defer_hook(event.hook)
+            event.hook.defer()
 
 ```
 
-When handling the hook event, call `defer_hook` to interrupt the loop
+When handling the hook event, call `event.hook.defer()` to interrupt the loop
 and surface your tool approvals (or custom hook-related work) to the client.
 
 The `ToolRunner` will handle multiple concurrent aborts by waiting for all
 scheduled tasks to complete or get aborted. That way you can run approval-gated
 tools on serverless concurrently.
 
 Once the client has gathered payloads for all hooks, it will re-enter via the
-same endpoint, which will then pre-register hook resolutions inside the
-`agent.run` block, before iterating the stream. The loop will replay results
-of LLM calls and tool results
-from the first run without redoing non-deterministic and duplicating side-effects.
-When it hits the hook for which it has a pre-registered resolution, it will
-continue through without suspending.
+same endpoint, which will then apply the approvals inside the `agent.run`
+block, before iterating the stream. The loop will replay results of LLM calls
+and tool results from the first run without redoing non-deterministic and
+duplicating side-effects. When it hits the hook for which it has a
+pre-registered resolution, it will continue through without suspending.

docs/ai-python/content/docs/reference/ai/index.mdx

@@ -348,9 +348,13 @@ approval = await ai.hook(
 Hook exports:
 
 - `hook`: Emit a deferred hook event and wait for a matching resolution.
-- `resolve_hook`: Resolve a live or future hook.
+- `resolve_hook`: Resolve a live or future hook by ID or `HookPart`.
 - `defer_hook`: Mark a serialized deferred hook as aborted.
-- `cancel_hook`: Cancel a live hook by label.
+- `cancel_hook`: Cancel a live hook by ID or `HookPart`.
+
+`HookPart` also has convenience methods for event-driven code:
+`hook_part.resolve(...)`, `await hook_part.cancel(...)`, and
+`hook_part.defer()`.
 
 ## Errors
 

docs/ai-python/content/docs/reference/messages.mdx

@@ -61,6 +61,14 @@ Tool and runtime parts:
 - `BuiltinToolReturnPart`: A provider-executed tool result.
 - `HookPart`: A hook suspension, resolution, or cancellation.
 
+`HookPart` has convenience methods for hook event handlers:
+
+```python
+hook_part.resolve(data)
+await hook_part.cancel(reason="client disconnected")
+hook_part.defer()
+```
+
 `ToolResultPart.get_model_input()` returns the value sent back to the model. For
 most tools this is the same as `result`. Aggregator-backed tools can store a
 rich `result` while sending a simpler model-facing value.

examples/agents/custom_hook.py

@@ -49,13 +49,12 @@ async def main() -> None:
                 and event.hook.status == "pending"
             ):
                 print(f"\n[deferred] {event.hook.hook_id}")
-                ai.resolve_hook(
-                    event.hook,
+                event.hook.resolve(
                     DeploymentReview(
                         approved=True,
                         reviewer="ops",
                         reason="change window is open",
-                    ),
+                    )
                 )
             elif (
                 isinstance(event, ai.events.HookEvent)

examples/agents/tool_approval.py

@@ -31,12 +31,11 @@ async def live(messages: list[ai.messages.Message]) -> None:
                 and event.hook.status == "pending"
             ):
                 print(f"\n[deferred] {event.hook.hook_id}")
-                ai.resolve_hook(
-                    event.hook,
+                event.hook.resolve(
                     ai.tools.ToolApproval(
                         granted=True,
                         reason="approved while the run is still active",
-                    ),
+                    )
                 )
     print()
 
@@ -63,7 +62,7 @@ async def stateless(
             ):
                 deferred.append(event.hook)
                 print(f"\n[deferred] {event.hook.hook_id}")
-                ai.defer_hook(event.hook)
+                event.hook.defer()
 
     return stream.messages, deferred, "".join(text)
 

examples/apps/coding_agent/README.md

@@ -7,7 +7,7 @@ Minimal coding-agent TUI built with the AI SDK for Python and
 - streamed markdown replies (and reasoning, when the model emits it)
 - every bash call is gated behind a `ToolApproval` hook: the run
   suspends, a y/n prompt appears above the composer, and the decision
-  is resolved in-process with `ai.resolve_hook()`
+  is resolved in-process
 - messages typed while the agent is busy are queued and run in order;
   Esc interrupts the current turn
 

examples/apps/coding_agent/main.py

@@ -4,7 +4,7 @@
 streamed markdown, and an approval prompt.  The user types a message,
 the agent streams its reply, and every bash call suspends the run on a
 ``ToolApproval`` hook until the operator answers y/n — the decision is
-resolved in-process with ``ai.resolve_hook()``.
+resolved in-process.
 
 Run it from this directory:
 

examples/apps/web_agent/README.md

@@ -17,7 +17,7 @@ tool is gated behind user confirmation before execution.
 
 1. LLM emits a call to the gated tool
 2. The runtime emits a `HookEvent` with a deferred `HookPart`; the
-   backend aborts the deferred hook (`ai.defer_hook`) so the turn
+   backend defers the hook (`event.hook.defer()`) so the turn
    ends and the deferred approval streams to the client
 3. The frontend renders Approve / Reject buttons via the
    `<Confirmation>` component (from AI Elements)