docs: add approval-bound tool execution example

[jw-ond]

Summary

• Adds a small approval-bound side-effect example to the Tool Call Hooks guide
• Shows how to build a stable action object and SHA-256 digest before tool execution
• Maps external checkpoint decisions to allow, reviewer approval, or HookAborted block behavior

Checks

• Parsed all Python code blocks in docs/edge/en/learn/tool-hooks.mdx with ast.parse
• Verified heading numbering in the Common Use Cases section
• Verified the fork branch file matches the local edited file

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f0d79229-9b15-4671-b144-80d92368f12b

📥 Commits

Reviewing files that changed from the base of the PR and between 9e0dafa and b8eb979.

📒 Files selected for processing (1)

• docs/edge/en/learn/tool-hooks.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/edge/en/learn/tool-hooks.mdx

---

📝 Walkthrough

Walkthrough

The tool hooks guide adds approval-bound side-effect documentation. It covers deterministic SHA-256 action digests, approval decisions, human review, and execution blocking. Later use-case headings are renumbered from 3–6 to 4–7.

Changes

Tool Hooks Documentation

Layer / File(s)	Summary
Approval-bound side effects and section numbering docs/edge/en/learn/tool-hooks.mdx	Adds a Python example for checkpointing side-effecting tool calls, generating stable action digests, handling approval decisions, and requesting human review. Renumbers later sections from 3–6 to 4–7.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the documentation change and the approval-bound tool execution example.
Description check	✅ Passed	The description directly explains the documented example, its behavior, and the validation checks performed.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/edge/en/learn/tool-hooks.mdx (1)

186-190: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Harden stable_digest against non-JSON-serializable tool inputs.

stable_digest calls json.dumps(action, sort_keys=True, separators=(",", ":")) on an action dict that embeds ctx.tool_input directly. tool_input is typed as dict[str, Any], so a value that is not natively JSON-serializable (a datetime, UUID, Decimal, Enum, Path, or another custom object) raises TypeError inside the hook. The guide documents HookAborted as the deliberate way to block a call, but does not describe this failure mode. The same risk applies to the json.dumps(action, indent=2, sort_keys=True) call used for the human-readable prompt.

Add a default=str fallback to both json.dumps calls so the example degrades gracefully instead of crashing on non-JSON-native fields.

📝 Proposed fix

 def stable_digest(action: dict[str, Any]) -> str:
-    payload = json.dumps(action, sort_keys=True, separators=(",", ":"))
+    payload = json.dumps(action, sort_keys=True, separators=(",", ":"), default=str)
     return hashlib.sha256(payload.encode("utf-8")).hexdigest()

     response = ctx.request_human_input(
         prompt=f"Approve {ctx.tool_name} action?",
         default_message=(
             f"Action digest: {digest}\n"
-            f"Action: {json.dumps(action, indent=2, sort_keys=True)}\n"
+            f"Action: {json.dumps(action, indent=2, sort_keys=True, default=str)}\n"
             "Type 'yes' to approve:"
         ),
     )

Also applies to: 215-222

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/edge/en/learn/tool-hooks.mdx` around lines 186 - 190, Add a default=str
fallback to both json.dumps calls in the tool-hook example: stable_digest and
the human-readable action prompt serialization. Preserve the existing sorting,
separators, and indentation options so non-JSON-serializable tool inputs are
converted to strings instead of raising TypeError.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/edge/en/learn/tool-hooks.mdx`:
- Around line 186-190: Add a default=str fallback to both json.dumps calls in
the tool-hook example: stable_digest and the human-readable action prompt
serialization. Preserve the existing sorting, separators, and indentation
options so non-JSON-serializable tool inputs are converted to strings instead of
raising TypeError.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 9157506c-b690-4442-8b23-942fd1f04f85

📥 Commits

Reviewing files that changed from the base of the PR and between 3932d3f and 9e0dafa.

📒 Files selected for processing (1)

• docs/edge/en/learn/tool-hooks.mdx

[jw-ond]

Thanks for the review. The current PR head already applies the suggested default=str fallback in both places: stable_digest() preserves the existing sorted compact serialization, and the reviewer prompt serialization preserves the existing indentation/sorting. That should keep the example from raising TypeError on non-JSON-native tool input values while keeping the digest behavior deterministic for common primitive inputs.