fix: detect Grok Build agent state

refs #133

4 files changed, 12 insertions, 0 deletions

diff --git a/docs/next/CHANGELOG.md b/docs/next/CHANGELOG.md
index 93caba87..32148d7b 100644
--- a/docs/next/CHANGELOG.md
+++ b/docs/next/CHANGELOG.md
@@ -10,6 +10,7 @@
 - Renamed the focused pane fullscreen keybinding to `keys.zoom`; `keys.fullscreen` remains supported as a legacy alias.
 
 ### Fixed
+- Grok Build is now detected as `grok`, with basic working, blocked, and idle state detection. Conflicting known-agent hook labels are ignored once native foreground-process detection identifies a different known agent. (#133)
 - GitHub Copilot is now correctly detected when its process name is `copilot`.
 - Integration installs now respect `PI_CODING_AGENT_DIR`, `CLAUDE_CONFIG_DIR`, and `CODEX_HOME` when choosing Pi, Claude Code, and Codex config paths.
 - Split pane resize hit areas no longer overlap the first content column or row, making text selection work from the start of right and bottom panes.
diff --git a/docs/next/CONFIGURATION.md b/docs/next/CONFIGURATION.md
index 59956c0d..e988e72e 100644
--- a/docs/next/CONFIGURATION.md
+++ b/docs/next/CONFIGURATION.md
@@ -402,6 +402,7 @@ available agent keys:
 - `kimi`
 - `droid`
 - `amp`
+- `grok`
 
 ## experimental
 
diff --git a/docs/next/INTEGRATIONS.md b/docs/next/INTEGRATIONS.md
index ff46d0c5..23b41ab8 100644
--- a/docs/next/INTEGRATIONS.md
+++ b/docs/next/INTEGRATIONS.md
@@ -108,6 +108,7 @@ notes:
 - claude code hooks also run inside subagents. herdr treats subagent `working` and `blocked` reports as real pane state.
 - subagent stop/release events are converted to `working` by the bundled hook script so a completed subagent does not make the parent claude pane look idle.
 - `PostToolUse` and `PostToolUseFailure` move the pane back to `working` after a permissioned tool call resolves.
+- some non-claude tools, including grok cli, may load claude settings or plugins. herdr ignores conflicting known-agent hook labels once native foreground-process detection identifies a different known agent.
 
 uninstall:
 
@@ -209,6 +210,14 @@ this removes:
 ~/.config/opencode/plugins/herdr-agent-state.js
 ```
 
+## grok cli
+
+herdr does not currently install a grok hook or plugin.
+
+grok is heuristic-only in herdr. herdr detects `grok` and `grok-build` from the foreground process and uses screen heuristics for `working`, `blocked`, and `idle` states.
+
+grok cli may load claude settings or plugins as a compatibility feature, including hooks from `~/.claude/settings.json`. if that causes the claude herdr hook to run in a grok pane, herdr ignores the conflicting `claude` hook label once native foreground-process detection identifies the pane as `grok`.
+
 ## amp
 
 herdr does not currently install an Amp plugin.
diff --git a/docs/next/README.md b/docs/next/README.md
index f4587261..16649d6e 100644
--- a/docs/next/README.md
+++ b/docs/next/README.md
@@ -177,6 +177,7 @@ automatic detection works out of the box. process name matching plus terminal ou
 | [droid](https://factory.ai) | ✓ | ✓ | ✓ |
 | [amp](https://ampcode.com) | ✓ | ✓ | ✓ |
 | [opencode](https://github.com/anomalyco/opencode) | ✓ | ✓ | ✓ |
+| [grok cli](https://x.ai/grok) | ✓ | ✓ | ✓ |
 
 detected but not fully tested: gemini cli, cursor agent, cline, kimi, github copilot cli.