From ee018d5c82a593907bae9011bc074766e670d593 Mon Sep 17 00:00:00 2001
From: Chris Yang <415386365@qq.com>
Date: Mon, 30 Mar 2026 12:01:57 +0800
Subject: [PATCH] docs: rename patch tool to apply_patch and clarify
 apply_patch behavior (#19979)

---
 packages/web/src/content/docs/tools.mdx | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/packages/web/src/content/docs/tools.mdx b/packages/web/src/content/docs/tools.mdx
index 4c48d194b0..abd486aeb6 100644
--- a/packages/web/src/content/docs/tools.mdx
+++ b/packages/web/src/content/docs/tools.mdx
@@ -95,7 +95,7 @@ Create new files or overwrite existing ones.
 Use this to allow the LLM to create new files. It will overwrite existing files if they already exist.
 
 :::note
-The `write` tool is controlled by the `edit` permission, which covers all file modifications (`edit`, `write`, `patch`, `multiedit`).
+The `write` tool is controlled by the `edit` permission, which covers all file modifications (`edit`, `write`, `apply_patch`, `multiedit`).
 :::
 
 ---
@@ -191,7 +191,7 @@ To configure which LSP servers are available for your project, see [LSP Servers]
 
 ---
 
-### patch
+### apply_patch
 
 Apply patches to files.
 
@@ -206,8 +206,12 @@ Apply patches to files.
 
 This tool applies patch files to your codebase. Useful for applying diffs and patches from various sources.
 
+When handling `tool.execute.before` or `tool.execute.after` hooks, check `input.tool === "apply_patch"` (not `"patch"`).
+
+`apply_patch` uses `output.args.patchText` instead of `output.args.filePath`. Paths are embedded in marker lines within `patchText` and are relative to the project root (for example: `*** Add File: src/new-file.ts`, `*** Update File: src/existing.ts`, `*** Move to: src/renamed.ts`, `*** Delete File: src/obsolete.ts`).
+
 :::note
-The `patch` tool is controlled by the `edit` permission, which covers all file modifications (`edit`, `write`, `patch`, `multiedit`).
+The `apply_patch` tool is controlled by the `edit` permission, which covers all file modifications (`edit`, `write`, `apply_patch`, `multiedit`).
 :::
 
 ---