bestagentkits · thieung · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026
diff --git a/content/docs/beta/troubleshooting/configuration.en.mdx b/content/docs/beta/troubleshooting/configuration.en.mdx
@@ -107,4 +107,5 @@ source and value, and a new runtime session behaves as expected.
 
 - [Runtime cannot find a Skill or Agent](./runtime-cannot-find-skill-or-agent)
 - [Kit installation problems](./kit-installation)
+- [Grok CLI Hook errors](./grok-hooks)
 - [CLI reference](../reference/cli)
diff --git a/content/docs/beta/troubleshooting/configuration.vi.mdx b/content/docs/beta/troubleshooting/configuration.vi.mdx
@@ -106,4 +106,5 @@ giá trị, và session runtime mới hoạt động như mong đợi.
 
 - [Runtime không tìm thấy Skill hoặc Agent](./runtime-cannot-find-skill-or-agent)
 - [Lỗi cài Kit](./kit-installation)
+- [Lỗi Hook trên Grok CLI](./grok-hooks)
 - [Tham chiếu CLI](../reference/cli)
diff --git a/content/docs/beta/troubleshooting/grok-hooks.en.mdx b/content/docs/beta/troubleshooting/grok-hooks.en.mdx
@@ -0,0 +1,114 @@
+---
+title: Grok CLI Hook errors
+description: Stop Grok from failing Claude-compat Hooks without editing AgentKit-managed settings.json, then re-enable Claude scan after an AgentKit update that folds global Hook commands.
+---
+
+Use this page when Grok CLI reports Hook errors on every prompt or tool call,
+especially a missing `~/.claude/node`, after a global AgentKit Kit install for
+Claude Code.
+
+## Confirm the symptom
+
+Typical signs:
+
+- Grok shows Hook errors on `SessionStart`, `UserPromptSubmit`, `PreToolUse`,
+  `PostToolUse`, or `Stop`.
+- The failing path is `~/.claude/node`, or Node starts without the Hook script.
+- One-liner Hooks already stored as a single `command` string still run. Entries
+  with `"command": "node"` plus an `args` array fail.
+
+Grok reads `~/.claude/settings.json` by default. It treats `command` as a path
+relative to that JSON file, or as an inline shell command when the string
+contains whitespace. It does not use Claude's `args` array.
+
+## Do not edit AgentKit-managed settings
+
+Do not rewrite `command` / `args` inside `~/.claude/settings.json` or
+`<project>/.claude/settings.json`. `ak kit update` matches managed Hooks by
+the `.cjs` script path and writes the exec-form back.
+
+Do not create `~/.claude/node` as a symlink to your real Node binary. Grok still
+drops `args`, so that shim would start Node with no script.
+
+Do not add a second copy of the same Hooks under `~/.grok/hooks/` while Claude
+compat scanning stays on. Grok merges sources and the Hooks would run twice.
+
+## Workaround until AgentKit folds global Hooks
+
+Keep Claude Code on the AgentKit-managed settings file. Point Grok at its own
+Hook files and turn off Claude Hook scanning.
+
+1. In `~/.grok/config.toml`:
+
+```toml
+[compat.claude]
+hooks = false
+```
+
+The same switch is `GROK_CLAUDE_HOOKS_ENABLED=0` for one process.
+
+2. Add Grok-native Hook files under `~/.grok/hooks/`. Use a one-liner `command`
+   that includes the script path, matching the form Grok already accepts:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node '/Users/you/.claude/hooks/session-init.cjs'"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Copy only the AgentKit Hooks you need from `~/.claude/settings.json`. Keep
+timeouts and matchers. Quote paths that contain spaces.
+
+3. Restart Grok and inspect `/hooks`. Project Hooks also need `/hooks-trust` or
+   `--trust` before they run.
+
+This overlay lives outside AgentKit ownership. Kit update and uninstall will
+not create, refresh, or delete `~/.grok/hooks/`. Re-check the overlay when a
+Kit adds or removes a Hook.
+
+Project-native Claude settings already emit portable `node "<script>"`
+shell-form. The failure is the **global** `~/.claude/settings.json` exec-form.
+
+## After the AgentKit fix ships
+
+The durable fix is AgentKit folding global Node Hooks into one quoted
+shell-form command with an absolute Node runner, then deleting `args`. Track
+[agentkit#1607](https://github.com/bestagentkits/agentkit/issues/1607).
+
+When that CLI is installed:
+
+```bash
+ak kit update engineer --target claude-code --global
+```
+
+Use the Kit name you actually installed. Then remove the Grok overlay if you
+no longer need it, set `[compat.claude] hooks = true` (or delete that key; the
+default is on), and start a new Grok session.
+
+`ak doctor` can confirm a Node runner is still resolvable. Do not treat doctor
+output as proof of Grok's stdin schema.
+
+## Residual behavior on Grok
+
+Even with a runnable `command`, some AgentKit Hooks were written for Claude
+Code's snake_case stdin JSON. Grok sends camelCase fields such as
+`hookEventName` and `toolName`. Those Hooks may no-op or fail-open on Grok.
+That is a separate schema mismatch, not the missing `~/.claude/node` path.
+
+## Related pages
+
+- [Configuration problems](./configuration)
+- [Kit installation problems](./kit-installation)
+- [Updates and recovery](./updates)
diff --git a/content/docs/beta/troubleshooting/grok-hooks.vi.mdx b/content/docs/beta/troubleshooting/grok-hooks.vi.mdx
@@ -0,0 +1,114 @@
+---
+title: Lỗi Hook trên Grok CLI
+description: Tắt lỗi Hook Claude-compat trên Grok mà không sửa settings.json do AgentKit quản lý, rồi bật lại scan Claude sau bản AgentKit gộp command Hook global.
+---
+
+Dùng trang này khi Grok CLI báo lỗi Hook mỗi lần gửi prompt hoặc gọi tool, đặc
+biệt khi thiếu `~/.claude/node`, sau khi cài Kit AgentKit global cho Claude
+Code.
+
+## Xác nhận triệu chứng
+
+Dấu hiệu thường gặp:
+
+- Grok báo lỗi Hook trên `SessionStart`, `UserPromptSubmit`, `PreToolUse`,
+  `PostToolUse` hoặc `Stop`.
+- Đường dẫn lỗi là `~/.claude/node`, hoặc Node chạy mà không có script Hook.
+- Hook one-liner đã nằm trong một chuỗi `command` vẫn chạy. Entry
+  `"command": "node"` kèm mảng `args` thì thất bại.
+
+Grok mặc định đọc `~/.claude/settings.json`. Nó coi `command` là đường dẫn
+tương đối so với file JSON đó, hoặc là lệnh shell nội tuyến khi chuỗi có
+khoảng trắng. Nó không dùng mảng `args` của Claude.
+
+## Không sửa settings do AgentKit quản lý
+
+Không viết lại `command` / `args` trong `~/.claude/settings.json` hoặc
+`<project>/.claude/settings.json`. `ak kit update` nhận diện Hook được quản lý
+theo đường dẫn script `.cjs` rồi ghi lại dạng exec-form.
+
+Không tạo `~/.claude/node` thành symlink tới Node thật. Grok vẫn bỏ `args`,
+nên shim đó chỉ mở Node mà không chạy script.
+
+Không thêm bản sao Hook dưới `~/.grok/hooks/` khi vẫn bật scan Claude compat.
+Grok merge các nguồn và Hook sẽ chạy hai lần.
+
+## Workaround cho đến khi AgentKit gộp Hook global
+
+Giữ Claude Code trên file settings do AgentKit quản lý. Cho Grok dùng file Hook
+của chính nó và tắt scan Hook Claude.
+
+1. Trong `~/.grok/config.toml`:
+
+```toml
+[compat.claude]
+hooks = false
+```
+
+Cùng một công tắc cho một process: `GROK_CLAUDE_HOOKS_ENABLED=0`.
+
+2. Thêm file Hook native của Grok dưới `~/.grok/hooks/`. Dùng `command` one-liner
+   có đường dẫn script, đúng form Grok đã chấp nhận:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node '/Users/you/.claude/hooks/session-init.cjs'"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Chỉ copy các Hook AgentKit bạn cần từ `~/.claude/settings.json`. Giữ timeout và
+matcher. Quote đường dẫn có khoảng trắng.
+
+3. Khởi động lại Grok và kiểm tra `/hooks`. Hook ở project còn cần
+   `/hooks-trust` hoặc `--trust` trước khi chạy.
+
+Overlay này nằm ngoài ownership của AgentKit. Cập nhật hoặc gỡ Kit sẽ không tạo,
+làm mới, hay xóa `~/.grok/hooks/`. Kiểm tra lại overlay khi Kit thêm hoặc bớt
+Hook.
+
+Settings Claude **project-native** đã emit dạng portable `node "<script>"`.
+Lỗi nằm ở exec-form **global** trong `~/.claude/settings.json`.
+
+## Sau khi bản sửa AgentKit được cài
+
+Sửa bền là AgentKit gộp Hook Node global thành một command shell-form đã quote,
+kèm absolute Node runner, rồi xóa `args`. Theo dõi
+[agentkit#1607](https://github.com/bestagentkits/agentkit/issues/1607).
+
+Khi CLI đó đã cài:
+
+```bash
+ak kit update engineer --target claude-code --global
+```
+
+Dùng đúng tên Kit bạn đã cài. Sau đó xóa overlay Grok nếu không còn cần, đặt
+`[compat.claude] hooks = true` (hoặc xóa key đó; mặc định là bật), rồi mở
+session Grok mới.
+
+`ak doctor` có thể xác nhận Node runner vẫn resolve được. Đừng coi output
+doctor là bằng chứng schema stdin của Grok.
+
+## Hành vi còn lại trên Grok
+
+Dù `command` đã chạy được, một số Hook AgentKit được viết cho JSON stdin
+snake_case của Claude Code. Grok gửi field camelCase như `hookEventName` và
+`toolName`. Các Hook đó có thể no-op hoặc fail-open trên Grok. Đó là lệch
+schema riêng, không phải lỗi thiếu `~/.claude/node`.
+
+## Trang liên quan
+
+- [Lỗi cấu hình](./configuration)
+- [Lỗi cài Kit](./kit-installation)
+- [Cập nhật và khôi phục](./updates)
diff --git a/content/docs/beta/troubleshooting/index.en.mdx b/content/docs/beta/troubleshooting/index.en.mdx
@@ -20,6 +20,8 @@ before reinstalling or changing files.
   recovery](./updates)
 - **A setting is invalid, ignored, or comes from the wrong scope:**
   [Configuration problems](./configuration)
+- **Grok CLI reports Hook errors or a missing `~/.claude/node`:** [Grok CLI
+  Hook errors](./grok-hooks)
 
 ## Safe diagnostic order
 

diff --git a/content/docs/beta/troubleshooting/index.vi.mdx b/content/docs/beta/troubleshooting/index.vi.mdx
@@ -19,6 +19,8 @@ thái đã ghi nhận trước khi cài lại hoặc thay đổi tệp.
   phục](./updates)
 - **Thiết lập không hợp lệ, bị bỏ qua hoặc đến từ sai phạm vi:** [Lỗi cấu
   hình](./configuration)
+- **Grok CLI báo lỗi Hook hoặc thiếu `~/.claude/node`:** [Lỗi Hook trên Grok
+  CLI](./grok-hooks)
 
 ## Thứ tự chẩn đoán an toàn
 

diff --git a/content/docs/beta/troubleshooting/meta.json b/content/docs/beta/troubleshooting/meta.json
@@ -7,6 +7,7 @@
     "kit-installation",
     "runtime-cannot-find-skill-or-agent",
     "updates",
-    "configuration"
+    "configuration",
+    "grok-hooks"
   ]
 }
diff --git a/content/docs/beta/troubleshooting/meta.vi.json b/content/docs/beta/troubleshooting/meta.vi.json
@@ -7,6 +7,7 @@
     "kit-installation",
     "runtime-cannot-find-skill-or-agent",
     "updates",
-    "configuration"
+    "configuration",
+    "grok-hooks"
   ]
 }
diff --git a/content/docs/stable/troubleshooting/configuration.en.mdx b/content/docs/stable/troubleshooting/configuration.en.mdx
@@ -107,4 +107,5 @@ source and value, and a new runtime session behaves as expected.
 
 - [Runtime cannot find a Skill or Agent](./runtime-cannot-find-skill-or-agent)
 - [Kit installation problems](./kit-installation)
+- [Grok CLI Hook errors](./grok-hooks)
 - [CLI reference](../reference/cli)
diff --git a/content/docs/stable/troubleshooting/configuration.vi.mdx b/content/docs/stable/troubleshooting/configuration.vi.mdx
@@ -106,4 +106,5 @@ giá trị, và session runtime mới hoạt động như mong đợi.
 
 - [Runtime không tìm thấy Skill hoặc Agent](./runtime-cannot-find-skill-or-agent)
 - [Lỗi cài Kit](./kit-installation)
+- [Lỗi Hook trên Grok CLI](./grok-hooks)
 - [Tham chiếu CLI](../reference/cli)