diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 058a11210..3a11ece11 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -193,6 +193,14 @@ In particular: link release-notes navigation to GitHub Releases rather than addi
 - Do not reformat unrelated files just because they are nearby.
 - Keep comments useful and concise.
 
+When working on diff generation or rendering, import public APIs and types from
+`diff`; the package supplies its own TypeScript declarations, so do not add
+`@types/diff` or import internal library paths. Use `diffWordsWithSpace` when
+rendering must preserve whitespace. Keep patch filenames separate from hunk
+content: serialized headers may quote or escape filenames, and parsed patches
+can omit filenames. Check the diff and edit-snippet tests when changing these
+paths.
+
 ## Provider Changes
 
 OpenClaude supports multiple provider paths. Before contributing provider changes, review the relevant documentation to ensure your implementation follows the expected patterns:
diff --git a/bun.lock b/bun.lock
index e79904137..889b97660 100644
--- a/bun.lock
+++ b/bun.lock
@@ -41,7 +41,7 @@
         "cli-highlight": "2.1.11",
         "commander": "12.1.0",
         "cross-spawn": "7.0.6",
-        "diff": "8.0.4",
+        "diff": "9.0.0",
         "duck-duck-scrape": "^2.2.7",
         "emoji-regex": "11.0.0",
         "env-paths": "4.0.0",
@@ -707,7 +707,7 @@
 
     "detect-libc": ["detect-libc@2.1.2", "", {}, "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ=="],
 
-    "diff": ["diff@8.0.4", "", {}, "sha512-DPi0FmjiSU5EvQV0++GFDOJ9ASQUVFh5kD+OzOnYdi7n3Wpm9hWWGfB/O2blfHcMVTL5WkQXSnRiK9makhrcnw=="],
+    "diff": ["diff@9.0.0", "", {}, "sha512-svtcdpS8CgJyqAjEQIXdb3OjhFVVYjzGAPO8WGCmRbrml64SPw/jJD4GoE98aR7r25A0XcgrK3F02yw9R/vhQw=="],
 
     "dijkstrajs": ["dijkstrajs@1.0.3", "", {}, "sha512-qiSlmBq9+BCdCA/L46dw8Uy93mloxsPSbwnm5yrKn2vMPiy8KyAskTF6zuV/j5BMsmOGZDPs7KjU+mjb670kfA=="],
 
diff --git a/package.json b/package.json
index 342d23d82..baa8c29fa 100644
--- a/package.json
+++ b/package.json
@@ -121,7 +121,7 @@
     "cli-highlight": "2.1.11",
     "commander": "12.1.0",
     "cross-spawn": "7.0.6",
-    "diff": "8.0.4",
+    "diff": "9.0.0",
     "duck-duck-scrape": "^2.2.7",
     "emoji-regex": "11.0.0",
     "env-paths": "4.0.0",