azcomputerguru/claudetools
1
0
Fork 0
Code Issues 58 Pull Requests Actions Packages Projects Releases Wiki Activity

grok: fix headless reasoning modes — pin grok-4.5 (was stale grok-build)

Browse Source 
Grok self-diagnosed and fixed the empty-text failure: the reasoning modes
(text/verify/review*) pinned -m grok-build, which the CLI (0.2.111) now rejects
as an unknown model id, producing empty output with a blank stopReason. Updated
the pin to grok-4.5 (the current default per `grok models`). Media/xsearch keep
GROK_MODEL="" (runtime default). Adds HEADLESS.md + PEER_GUIDE.md docs.

Verified: `ask-grok.sh text` now returns cleanly on GURU-5070.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Mike Swanson
2026-07-23 18:28:22 -07:00
parent 2e5c0c00f4
commit 728308de62
4 changed files with 1180 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

724
.claude/skills/grok/HEADLESS.md Normal file
View File

@@ -0,0 +1,724 @@
# Grok headless — exact syntax, abilities, and harness contract
**Audience:** Claude Code, Gemini/agy, and any automation that shells to Grok.
**Scope:** Non-interactive (`-p` / `--prompt-file`) runs only.
**Sources of truth:** this file + `scripts/ask-grok.sh` + local
`~/.grok/docs/user-guide/14-headless-mode.md` (vendor CLI docs).
**Verified on:** GURU-5070 — `grok 0.2.111`, default model `grok-4.5` (2026-07).
For *when* to call Grok and the peer trust model, see [PEER_GUIDE.md](./PEER_GUIDE.md).
For the short skill summary, see [SKILL.md](./SKILL.md).
---
## 0. Two layers — do not confuse them
| Layer | What it is | When to use |
|-------|------------|-------------|
| **A. Harness wrapper** | `bash .claude/skills/grok/scripts/ask-grok.sh <mode> …` | **Default for Claude/agy.** Modes, timeouts, path conversion, JSON parse, media copy, agy fallback, errorlog. |
| **B. Raw Grok CLI** | `grok --prompt-file …` / `grok -p "…"` | Escape hatch via `ask-grok.sh raw …`, debugging, or capabilities the wrapper has no mode for (`image_edit`, `reference_to_video`, resume sessions, tool allowlists). |
**Rule for peers:** use layer A unless you deliberately need layer B. Do not invent ad-hoc `grok -p` one-liners from memory — quoting, Windows paths, permissions, and artifact recovery will bite you.
---
## 1. Prerequisites
### Binary location
| Priority | Source |
|----------|--------|
| 1 | Env `GROK=` pointing at the executable |
| 2 | `.claude/identity.json` → `grok.binary` |
| 3 | Auto: `~/.grok/bin/grok.exe`, PATH `grok`, etc. |
Typical Windows path: `C:\Users\<user>\.grok\bin\grok.exe` (often **not** on PATH).
```bash
# From Git Bash / harness bash:
"$HOME/.grok/bin/grok.exe" version
# or
grok version
```
Example output: `grok 0.2.111 (94172f2aa4) [stable]`
### Auth (required)
This fleet uses **OIDC / grok.com login** (no API key in the skill).
| Method | When |
|--------|------|
| `grok login` | Interactive machine with browser (normal) |
| `grok login --device-auth` | Headless SSH/VM without local browser |
| `XAI_API_KEY=…` | CI / container alternative (vendor docs) |
Credentials cache: `~/.grok/auth.json`. On auth failure: user re-runs login; do not invent keys.
### Fleet gate (`identity.json`)
```json
"grok": {
"installed": true,
"binary": "C:/Users/guru/.grok/bin/grok.exe",
"auth": "oidc",
"is_fleet_host": true,
"capabilities": ["text","verify","image","video","xsearch"]
}
```
If `grok.installed` is `false`, **`ask-grok.sh` exits 3** immediately with routing guidance. Do not probe further on that machine (remote routing not wired yet).
### Shell requirements for the wrapper
- **bash** = Git-for-Windows MSYS bash (not WSL stub). See `windows-bash` skill.
- **python** = `py` / `python` / `python3` (JSON field extraction).
- **timeout** / **gtimeout** (macOS) for wall-clock limits.
- **cygpath** (MSYS) so paths handed to `grok.exe` are native Windows paths.
- **Never write prompts to Git-Bash `/tmp` for later Read-tool use** — path mismatch on Windows. Prefer repo-relative `./.claim.md` or the wrapper’s own temp dir.
---
## 2. Harness wrapper — exact syntax
### Invocation skeleton
```bash
# From ClaudeTools repo root (or with CLAUDETOOLS_ROOT set):
bash "${CLAUDETOOLS_ROOT:-.}/.claude/skills/grok/scripts/ask-grok.sh" <mode> [args...]
```
Short form when CWD is repo root:
```bash
bash .claude/skills/grok/scripts/ask-grok.sh <mode> [args...]
```
### Modes (complete)
| Mode | Syntax | Stdout success | Typical wall time |
|------|--------|----------------|-------------------|
| `text` | `text "<prompt>"` **or** `text --prompt-file <path>` | Answer text | ≤ ~180s budget |
| `verify` | `verify "<claim>"` **or** `verify --prompt-file <path>` | Verdict + reasons | ≤ ~180s |
| `review` | `review <file-path> ["instructions"]` | Review text | ≤ ~240s (+ optional embed retry) |
| `review-files` | `review-files [-i\|--instr "…"] <f1> [f2 …]` | Review text | ≤ ~300s |
| `review-diff` | `review-diff [-C <repo-dir>] [-i "…"] <gitref> [-- <pathspec>]` | Review text | ≤ ~300s |
| `image` | `image "<prompt>" [out.png]` | `[ask-grok] image OK -> <out> (session <id>)` | ≤ ~240s |
| `video` | `video "<motion>" <input-image> [out.mp4]` | `[ask-grok] video OK -> <out> (session <id>)` | ≤ ~360s |
| `xsearch` | `xsearch "<query>"` | Answer text (or agy fallback) | ≤ ~240s then possible agy |
| `raw` | `raw <any grok CLI args…>` | Whatever `grok` prints | Unlimited (your problem) |
Alias: `review` also accepts mode name `file` (same code path).
### Exit codes (`ask-grok.sh`)
| Code | Meaning |
|------|---------|
| `0` | Success — text printed or media copied |
| `1` | No usable result / empty artifact / empty git diff |
| `2` | Usage error (missing args, file not found for review target, bad mode) |
| `3` | Grok not installed on this machine (`identity.json`) |
| `127` | Binary or python missing |
Vendor `grok` itself may exit `0` / `1` / `130` (SIGINT) / `143` (SIGTERM). The wrapper **ignores** grok’s exit for most modes and judges success by JSON `text` or recovered artifact (Cancelled stopReason is common on media).
### Environment overrides the wrapper honors
| Env | Effect |
|-----|--------|
| `GROK=` | Path to `grok` / `grok.exe` |
| `GROK_MODEL=` | Model id for modes that pin a model. Default **`grok-4.5`**. Empty string clears pin (used internally for image/video). |
| `CLAUDETOOLS_ROOT=` | Repo root for path resolution and errorlog |
| `HOME` / user profile | Session artifact search under `~/.grok/sessions/` |
```bash
# Example: force a specific model for verify
GROK_MODEL=grok-4.5 bash .claude/skills/grok/scripts/ask-grok.sh verify "Claim: …"
```
### What each mode actually does under the hood
#### Shared `run_grok` defaults (text / verify / review* / image / video)
Unless a mode overrides, the wrapper builds:
```text
timeout <secs> <GROK> \
--prompt-file <WINPATH(tmp/prompt.txt)> \
--output-format json \
[-m <GROK_MODEL>] \ # omitted if GROK_MODEL is empty
--permission-mode dontAsk \
--no-subagents \
--no-plan \
--cwd <WINPATH(run_cwd)> \
[extra mode flags...]
```
- Prompt is **always** a file (never a huge shell-quoted `-p` string).
- Paths to grok.exe are **Windows-native** via `cygpath -w` on MSYS.
- stdout → temp JSON; stderr → temp err file.
- Grok exit code is swallowed (`|| true`); success is content-based.
#### `text`
```bash
bash .claude/skills/grok/scripts/ask-grok.sh text "One-sentence question?"
bash .claude/skills/grok/scripts/ask-grok.sh text --prompt-file ./.prompt.md
```
- Steers prompt: `Answer directly in text; do not use tools.\n<user content>`
- Extra flags: `--disable-web-search --max-turns 3`
- Timeout: **180s**
- Model: pinned (`GROK_MODEL`, default `grok-4.5`)
- cwd: disposable temp work dir
- Parses JSON field `text` → prints to stdout
#### `verify`
```bash
bash .claude/skills/grok/scripts/ask-grok.sh verify "Claim: the delete API removes the user."
bash .claude/skills/grok/scripts/ask-grok.sh verify --prompt-file ./.claim.md
```
- Steers prompt to **adversarially refute** then give verdict + justification; text only, no tools
- Same flags/timeout/model as `text`
- Note: vendor `--check` / self-verify is **not** used — that verifies Grok’s *own* answer, not an external claim
#### `review` (single file)
```bash
bash .claude/skills/grok/scripts/ask-grok.sh review /d/claudetools/path/to/file.rs
bash .claude/skills/grok/scripts/ask-grok.sh review ./relative/file.ts "Focus on authz"
```
**Path resolution (strict):**
1. If `<path>` exists as given (relative to **caller CWD**) → use it
2. Else if `$CLAUDETOOLS_ROOT/<path>` exists → use that
3. Else → exit 2 `file not found`
**Not** resolved against arbitrary submodules. For files under
`projects/msp-tools/guru-rmm/…` pass **absolute** paths.
- Instructs Grok to `read_file` the **Windows absolute** path; may read related files; **must not modify**
- cwd for grok: **repo root** (`CLAUDETOOLS_ROOT`)
- Timeout: **240s**, `--max-turns 12`
- If empty result and file ≤ **262144 bytes**: one automatic **embed fallback** (inline file body, no tools, max-turns 3)
- If empty and file larger: no embed; fail with session/stopReason
#### `review-files`
```bash
bash .claude/skills/grok/scripts/ask-grok.sh review-files \
-i "Focus on cross-file auth regressions" \
"D:/claudetools/projects/msp-tools/guru-rmm/server/src/a.rs" \
"D:/claudetools/projects/msp-tools/guru-rmm/server/src/b.rs"
```
- Flags: `-i` / `--instr` then instruction string; all other args are files
- Same path resolution **per file** as `review`
- Timeout: **300s**, `--max-turns 24`
- Embed fallback if combined size ≤ 256 KiB
#### `review-diff`
```bash
# Diff against main at monorepo root
bash .claude/skills/grok/scripts/ask-grok.sh review-diff main
# Submodule repo
bash .claude/skills/grok/scripts/ask-grok.sh review-diff \
-C projects/msp-tools/guru-rmm \
-i "Security only" \
HEAD~3 -- server/src/
# Unstaged/staged local changes vs HEAD
bash .claude/skills/grok/scripts/ask-grok.sh review-diff HEAD
```
- Runs `git -C <gdir> diff <gitref> [-- pathspec…]` into a temp file
- Empty diff → exit 1
- Embeds unified diff in the prompt; invites `read_file` on changed paths (relative to `-C` dir; strip `a/` `b/` prefixes)
- cwd for grok: **`<gdir>`** (the git root being diffed)
- Timeout: **300s**, `--max-turns 20`
- Embed fallback: no-tools re-run with diff only if ≤ 256 KiB
#### `image`
```bash
bash .claude/skills/grok/scripts/ask-grok.sh image "flat blue shield icon, no text" ./out/icon.png
# default out path if omitted:
bash .claude/skills/grok/scripts/ask-grok.sh image "a red cube on white"
# → copies to ./grok-image.png relative to caller CWD
```
- Prompt forces tool: `image_gen` then stop
- **Model pin cleared** (runtime default — media verified on default, not forced coding model)
- `--disable-web-search --max-turns 12`, timeout **240s**
- Reads JSON `sessionId`; finds newest file under
`~/.grok/sessions/*/<sessionId>/images/*`
and `cp` to `out`
- Success line: `[ask-grok] image OK -> <out> (session <id>)`
- Does **not** print the image bytes to stdout
#### `video`
```bash
bash .claude/skills/grok/scripts/ask-grok.sh video \
"slow push-in, gentle light" \
./out/hero.png \
./out/hero.mp4
```
- Requires existing input image (exit 2 if missing)
- Copies input to temp work dir as **`input.jpg`** (name is fixed for the model prompt)
- Prompt forces `image_to_video` on `input.jpg`
- Model pin cleared; timeout **360s**; `--max-turns 20`
- Artifact from `…/videos/*` → `out` (default `grok-video.mp4`)
- Success: `[ask-grok] video OK -> <out> (session <id>)`
#### `xsearch`
```bash
bash .claude/skills/grok/scripts/ask-grok.sh xsearch "UniFi OS 4.x latest stable release notes"
```
**Different policy from other modes** (do not “fix” this back to `--no-subagents`):
```text
timeout 240 <GROK> \
--prompt-file <prompt> \
--output-format streaming-json \
--yolo \
--no-plan \
--cwd <temp> \
--max-turns 14
```
- No `--no-subagents` (web_search multi-agent hung with zero output when subagents were disabled — fixed 2026-06-16)
- No model pin (searcher model is separate / runtime)
- Parses NDJSON lines with `"type":"text"` and concatenates `data`
- If exit≠0 or empty: logs error, prints
`[grok xsearch timed out -> answered via agy search]`,
then **`exec`s** `ask-agy.sh search "<same query>"` when available
- **Provenance:** if you see that banner, the answer is **not** pure Grok
#### `raw`
```bash
bash .claude/skills/grok/scripts/ask-grok.sh raw \
--prompt-file ./p.txt --output-format json --yolo --max-turns 8
```
- Passes all remaining args straight to `"$GROK" "$@"`
- **No** timeout, **no** path conversion, **no** JSON parse, **no** media recovery
- You own safety. Prefer documented modes.
---
## 3. Copy-paste recipes (wrapper)
```bash
ROOT="${CLAUDETOOLS_ROOT:-/d/claudetools}" # adjust; on Windows Git Bash often /d/claudetools
AG="$ROOT/.claude/skills/grok/scripts/ask-grok.sh"
# --- Second opinion ---
bash "$AG" verify --prompt-file "$ROOT/.claim.md"
# --- Text Q&A ---
bash "$AG" text "List three risks of disabling MFA for a shared mailbox."
# --- Single-file review (absolute path) ---
bash "$AG" review "D:/claudetools/projects/msp-tools/guru-rmm/server/src/api/auth.rs" \
"Security and authz only; cite file:line"
# --- Multi-file ---
bash "$AG" review-files -i "Cross-file consistency" \
"D:/claudetools/…/a.rs" "D:/claudetools/…/b.rs"
# --- Diff in submodule ---
bash "$AG" review-diff -C "$ROOT/projects/msp-tools/guru-rmm" HEAD~1
# --- Still image ---
bash "$AG" image "square app icon, blue shield, white check, no text" \
"$ROOT/projects/acg-website-showcase/design/icon.png"
# --- Still then video ---
bash "$AG" image "hero still, server rack, soft light, no text, 16:9" /tmp/hero.png
bash "$AG" video "slow dolly in" /tmp/hero.png /tmp/hero.mp4
# Prefer repo-relative outs on Windows, not Git-Bash /tmp for later tool Read
# --- Live search ---
bash "$AG" xsearch "What is the current xAI Grok CLI default model?"
```
### PowerShell callers
From PowerShell, still invoke **bash** (MSYS), not `grok.exe` directly, for wrapper modes:
```powershell
bash "D:/claudetools/.claude/skills/grok/scripts/ask-grok.sh" text "ping"
```
Do not nest PowerShell-escaped double quotes into complex `-p` prompts; use `--prompt-file` via the wrapper.
### Backgrounding
Run each `ask-grok` as its **own** tool/shell call. Do **not** combine:
```bash
# BAD — empty captures seen fleet-wide
bash ask-grok.sh verify "…" & curl …; wait
```
---
## 4. Raw Grok CLI headless (layer B)
Official flag reference: `~/.grok/docs/user-guide/14-headless-mode.md`
CLI help: `grok --help` / `grok version` / `grok models`
### How headless is triggered
Any of:
```bash
grok -p "prompt text" # --single
grok --prompt-file /path/to/prompt.txt
grok --prompt-json '<json content blocks>'
```
**Stdin is not the prompt.** Do not pipe the prompt into grok; use `-p` or `--prompt-file`.
### Output formats
| Flag | Shape |
|------|--------|
| (default) `plain` | Human text on stdout |
| `--output-format json` | One JSON object after completion |
| `--output-format streaming-json` | NDJSON events (`text`, `thought`, `end`, `error`, …) |
#### JSON success object (fields peers care about)
```json
{
"text": "…",
"stopReason": "EndTurn",
"sessionId": "019f…",
"requestId": "…",
"thought": "…",
"num_turns": 1,
"usage": { "input_tokens": 0, "cache_read_input_tokens": 0, "output_tokens": 0, "reasoning_tokens": 0, "total_tokens": 0 },
"modelUsage": { "<model-id>": { "inputTokens": 0, "outputTokens": 0, "modelCalls": 1, "costUSD": 0.0 } },
"total_cost_usd": 0.0
}
```
Error object example:
```json
{"type":"error","message":"Couldn't set model 'grok-build': Invalid params: \"unknown model id\"…"}
```
#### streaming-json events
| `type` | Meaning |
|--------|---------|
| `text` | Chunk; field `data` |
| `thought` | Reasoning chunk |
| `end` | Final; includes `stopReason`, `sessionId`, spend fields |
| `error` | Failure |
Wrapper xsearch concatenates all `type==text` `data` fields.
### Models (live — re-check with `grok models`)
```bash
grok models
```
**2026-07 snapshot on GURU-5070:**
- Default: **`grok-4.5`**
- Wire/usage name may appear as `grok-4.5-build` inside `modelUsage`
- **`grok-build` is invalid** (`unknown model id`) — older docs and an older wrapper default are obsolete
- Do **not** pass `--reasoning-effort` / `--effort` unless `grok models` / model menu shows support; unsupported values 400
Wrapper default for reasoning modes: `GROK_MODEL=grok-4.5` (overridable).
### Permission modes (headless-critical)
| Mechanism | Effect |
|-----------|--------|
| `--yolo` / `--always-approve` / `--permission-mode bypassPermissions` | Auto-approve tool runs (deny rules + hooks still apply) |
| `--permission-mode dontAsk` | Passed by wrapper; deny anything not auto-approved / allowed (CI-safe posture) |
| Config `~/.grok/config.toml` `[ui] permission_mode = "always-approve"` | Local fleet default can be loose — wrapper flags try to bound peer calls |
| Headless + would-prompt | Tool call is **cancelled** and reported to the model (does not hang for UI) |
**Peers:** for unattended *tool* work you intend (search, media tools), you need either YOLO/bypass or tools that are auto-approved as read-only. The wrapper uses:
- **dontAsk + no-subagents** for text/verify/review/image/video (prompt steering + media tools)
- **yolo + subagents allowed** for xsearch only
Vendor note: some permission-mode values are better set via Claude-compat `defaultMode` in settings; flag support evolves — if tools silently fail, check stderr with `RUST_LOG=error` and permission docs (`22-permissions-and-safety.md`).
### Important headless flags (cheat sheet)
| Flag | Purpose |
|------|---------|
| `-p` / `--prompt-file` / `--prompt-json` | Enter headless |
| `-m` / `--model` | Model id |
| `--cwd` | Working directory (project discovery walks up for `.git`) |
| `--output-format` | `plain` \| `json` \| `streaming-json` |
| `--max-turns N` | Cap agentic loops (headless-only) |
| `--no-plan` | Disable plan mode |
| `--no-subagents` | Block subagent fan-out |
| `--disable-web-search` | Disable web_search + web_fetch |
| `--tools a,b,c` | Allowlist built-in tools (headless-only) |
| `--disallowed-tools a,b` | Denylist; `Agent` / `Agent(explore)` special forms |
| `--allow` / `--deny` | Permission rules `Bash(…)`, `Read(…)`, etc. |
| `--rules "…"` | Extra system rules |
| `--system-prompt-override` | Replace system prompt |
| `--verbatim` | Send prompt exactly |
| `--no-memory` | Disable cross-session memory |
| `-r` / `--resume ID` | Resume session |
| `-c` / `--continue` | Continue latest session in cwd |
| `-s` / `--session-id UUID` | **New** session only (must be fresh UUID) |
| `--json-schema '…'` | Structured JSON output (implies json format) |
| `--sandbox <profile>` | FS/network sandbox |
| `--no-auto-update` | Skip update checks |
### Tool filtering examples (raw)
```bash
# Read-only review style
grok --prompt-file ./p.txt --output-format json \
--tools "read_file,grep,list_dir" \
--permission-mode dontAsk --no-subagents --no-plan --max-turns 12
# No shell, no edits
grok --prompt-file ./p.txt --output-format json --yolo \
--disallowed-tools "run_terminal_cmd,search_replace,write" \
--max-turns 8
```
Internal shell tool id is `run_terminal_cmd` (not `bash`) per vendor docs.
### Session resume (raw; wrapper does not multi-turn)
```bash
SID=$(grok --prompt-file ./p1.txt --output-format json --yolo | jq -r .sessionId)
grok --prompt-file ./p2.txt --output-format json --yolo --resume "$SID"
```
Each `ask-grok.sh` mode starts a **fresh** session (no `-r`/`-c`).
### Vendor exit codes
| Code | Meaning |
|------|---------|
| 0 | Completed |
| 1 | Error (auth, network, runtime, bad model, …) |
| 130 | SIGINT |
| 143 | SIGTERM |
### Env vars affecting headless
| Variable | Role |
|----------|------|
| `XAI_API_KEY` | API-key auth |
| `GROK_HOME` | Override `~/.grok` |
| `GROK_LOG_FILE` | Log path |
| `RUST_LOG` | Log level; headless logs on **stderr** (stdout stays clean for json) |
| `GROK_DISABLE_AUTOUPDATER=1` | Suppress updates |
| `GROK_SANDBOX` | Sandbox profile |
```bash
RUST_LOG=error grok --prompt-file ./p.txt --output-format json --yolo 2>grok.err
```
---
## 5. Abilities available headless
### A. Via wrapper modes (supported peer surface)
| Ability | Mode | Notes |
|---------|------|--------|
| One-shot reasoning / drafting | `text` | No tools; web search off |
| Adversarial claim check | `verify` | Prompt-steered refute |
| Code/doc review (Grok reads files) | `review`, `review-files` | read_file; no modify |
| Diff review | `review-diff` | git diff + optional read_file |
| Still image generation | `image` | `image_gen` (Imagine) |
| Animate one still → short video | `video` | `image_to_video` |
| Live web (+ X) search | `xsearch` | May fall back to agy |
### B. Native Grok tools (exist in product; wrapper coverage)
| Tool / capability | Wrapper? | How to reach |
|-------------------|----------|--------------|
| `image_gen` | **Yes** — `image` | Prefer wrapper |
| `image_to_video` | **Yes** — `video` | Prefer wrapper |
| `image_edit` | **No mode** | Interactive TUI or `raw` + careful prompt + artifact hunt |
| `reference_to_video` | **No mode** | Interactive or `raw`; 2–7 refs |
| `web_search` / `web_fetch` | **Partial** — `xsearch` | Do not combine with `--no-subagents` |
| `x_keyword_search`, `x_semantic_search`, `x_user_search`, `x_thread_fetch` | No dedicated mode | `raw` or interactive; xsearch prompt only asks for `web_search` |
| `read_file`, `list_dir`, `grep` | **Yes** in review* | Also available if you `raw` with tools |
| `run_terminal_command` / shell | **Not** in safe modes | Only if you `raw --yolo` — **do not** for production MSP actions |
| `search_replace` / `write` | **Not** intended for peers | Claude owns repo edits |
| MCP tools (e.g. GrepAI) | Depends on config | Project `.grok/config.toml` / user config; headless can use if server up |
| Subagents | Off in wrapper except xsearch | `--no-subagents` vs xsearch yolo |
| Scheduler / monitor | No | Interactive / specialized |
| `/imagine`, `/imagine-video` slash | TUI | Headless uses tools via prompt, not slash UI |
### C. Media artifact locations
```text
~/.grok/sessions/<encoded-cwd-or-slug>/<sessionId>/images/<file>
~/.grok/sessions/<encoded-cwd-or-slug>/<sessionId>/videos/<file>
```
Wrapper: `ls -t ~/.grok/sessions/*/$SID/images/* | head -1` (same for videos).
Headless may report `stopReason: Cancelled` even when the file exists — **always** recover by sessionId for media, do not trust stdout path alone.
### D. Explicit non-abilities / anti-patterns headless
| Do not expect | Why |
|---------------|-----|
| Long-form multi-scene film | Short clips only |
| Print-quality catalog photography | Web/concept grade |
| Unsupervised production deletes via Grok | Peer contract + post-mortem |
| Stable `grok-build` model id (2026-07) | Unknown model; use `grok-4.5` |
| Prompt via stdin pipe | Not supported |
| Wrapper multi-turn memory across modes | Fresh session each call |
| `ask-grok.sh image_edit` | Does not exist — use raw/interactive |
| Mixing background `&` with capture | Empty output friction |
---
## 6. Windows / path rules (mandatory)
1. **`grok.exe` is a native Windows binary.** Git Bash paths like `/d/claudetools/...` or `/tmp/...` often fail inside grok unless converted. The wrapper uses `cygpath -w`.
2. **Review targets:** pass absolute Windows or MSYS paths that resolve under CWD or `CLAUDETOOLS_ROOT` only.
3. **Submodules:** always absolute paths or `review-diff -C <submodule>`.
4. **Spaces in paths:** wrapper handles via prompt file + winpath; avoid embedding paths in fragile double-quoted PowerShell/`curl` chains.
5. **Prompt files for peers:** repo-relative `./.claim.md`, not Git-Bash `/tmp`, if a later Claude Read must open them.
6. **bash mapping:** harness scripts require MSYS bash — see `windows-bash` skill / CLAUDE.md.
---
## 7. Timeouts, turns, and failure modes
| Mode | timeout(1) secs | max-turns | Empty/fail behavior |
|------|-----------------|-----------|---------------------|
| text / verify | 180 | 3 | exit 1 + errorlog |
| image | 240 | 12 | exit 1 if no artifact |
| video | 360 | 20 | exit 1 if no artifact |
| review | 240 | 12 | embed retry once ≤256KiB |
| review-files | 300 | 24 | embed retry once |
| review-diff | 300 | 20 | embed retry once |
| xsearch | 240 | 14 | agy search fallback |
**Functional errors** (empty text, no artifact, xsearch incomplete) call:
```bash
bash "$REPO_ROOT/.claude/scripts/log-skill-error.sh" "grok" "<msg>" --context "…"
```
Soft-fail — does not replace the exit code semantics above.
### stopReason values
Peers may see in diagnostics: `EndTurn`, `Cancelled`, empty, etc.
`Cancelled` + media: still check session artifact dir.
Empty `text` with `EndTurn`: treat as failure / re-prompt.
---
## 8. Minimal raw templates (only when wrapper is insufficient)
### Structured verify-like call (raw mirror of wrapper)
```bash
PF=$(mktemp)
printf '%s\n' 'Adversarially evaluate the following claim… Answer in text only; do not use tools. Content:
'"$CLAIM" > "$PF"
grok --prompt-file "$(cygpath -w "$PF" 2>/dev/null || echo "$PF")" \
--output-format json \
-m grok-4.5 \
--permission-mode dontAsk \
--no-subagents \
--no-plan \
--disable-web-search \
--max-turns 3 \
--cwd "$(cygpath -w "$PWD" 2>/dev/null || echo "$PWD")"
```
Prefer `ask-grok.sh verify` instead.
### image_edit sketch (unsupported by wrapper — fragile)
```bash
# Interactive preferred. Raw sketch only:
# 1) Put source image in --cwd
# 2) Prompt: use image_edit on ./source.png with description …
# 3) --output-format json --yolo --max-turns 12
# 4) Recover from ~/.grok/sessions/**/<sessionId>/images/
bash .claude/skills/grok/scripts/ask-grok.sh raw \
--prompt-file ./edit-prompt.txt \
--output-format json --yolo --no-plan --max-turns 12 \
--cwd "D:/path/with/source"
```
### Live model id check (run before debugging “unknown model”)
```bash
grok models
```
---
## 9. Security posture for headless peers
1. Prefer wrapper modes that disable web search and subagents for pure reasoning.
2. Never `raw --yolo` against production MSP APIs or vault paths as a substitute for Claude skills.
3. Review prompts always say **do not modify**; still treat Grok as untrusted for writes.
4. Media: view/inspect before client or public use ([PEER_GUIDE.md](./PEER_GUIDE.md) §3).
5. xsearch: disclose agy fallback when the banner appears.
6. Secrets: never put decrypted credentials in prompts or generated images.
---
## 10. Quick reference card
```text
WRAPPER:
bash .claude/skills/grok/scripts/ask-grok.sh text|verify|review|review-files|review-diff|image|video|xsearch|raw …
EXITS: 0 ok | 1 no result | 2 usage | 3 not installed | 127 missing binary/python
DEFAULT MODEL (reasoning modes): grok-4.5 (override GROK_MODEL=)
MEDIA / XSEARCH MODEL: runtime default (pin cleared)
AUTH: grok login | identity.json grok.installed
DOCS: ~/.grok/docs/user-guide/14-headless-mode.md
PEER: .claude/skills/grok/PEER_GUIDE.md
```
---
## 11. Related paths
| Path | Role |
|------|------|
| `scripts/ask-grok.sh` | Implementation (read when behavior is ambiguous) |
| [SKILL.md](./SKILL.md) | Skill entry + short mode table |
| [PEER_GUIDE.md](./PEER_GUIDE.md) | When/why + media product rules + trust |
| `~/.grok/docs/user-guide/14-headless-mode.md` | Vendor headless reference |
| `~/.grok/docs/user-guide/22-permissions-and-safety.md` | Permission pipeline |
| `docs/session-notes/2026-06-03-claude-postmortem-grok-mspbackups-sbs.md` | Why peers must verify end-state |
---
*Last verified against live CLI on GURU-5070: grok 0.2.111, models default `grok-4.5`, `grok-build` rejected. Re-run `grok models` after CLI upgrades.*

437
.claude/skills/grok/PEER_GUIDE.md Normal file
View File

@@ -0,0 +1,437 @@
# How Claude and Gemini (agy) should interact with Grok
**Audience:** Claude Code sessions and Antigravity/Gemini (`agy`) sessions in the
ClaudeTools harness. **Author:** Grok (xAI). **Status:** live peer contract.
This is the canonical brief for *calling* Grok as a peer (judgment + trust).
| Doc | Use for |
|-----|---------|
| **[HEADLESS.md](./HEADLESS.md)** | **Exact headless syntax**, every `ask-grok.sh` mode, flags, timeouts, exit codes, raw CLI, abilities matrix, Windows paths |
| [SKILL.md](./SKILL.md) | Short skill entry + mode table |
| `scripts/ask-grok.sh` | Implementation source of truth if docs lag |
Read **this** file for *when*, *how hard*, and *what to trust*.
---
## 1. Who Grok is in this harness
| Fact | Detail |
|------|--------|
| Vendor / product | xAI **Grok** via the local **Grok CLI** (`grok.exe`), OIDC login (no API key) |
| Primary role | **Independent second model** + capabilities Claude/agy lack (image/video gen, X search) |
| Not the owner | **Claude owns codebase work** (edits, commits, production mutations, skill execution). Grok is fresh, skeptical eyes — not the operator of record. |
| Sibling peer | **agy** (Gemini via Antigravity CLI) is the other second-opinion router. Same *intent* (verify/review/text); different strengths. |
| Fleet hosts | Gated by `.claude/identity.json` → `grok.installed`. Today: **GURU-5070**, **GURU-BEAST-ROG**. Exit code **3** if not installed. |
Two invocation shapes:
1. **Headless peer call** (normal for Claude/agy) — `ask-grok.sh <mode> …`
2. **Interactive Grok TUI** (user opens Grok as the driver) — Grok loads
`CLAUDE.md` + `AGENTS.md` + `.grok/` coexistence. Still not a free hand on
production; same safety bar.
---
## 2. How to call Grok (always use the skill wrapper)
```bash
bash "$CLAUDETOOLS_ROOT/.claude/skills/grok/scripts/ask-grok.sh" <mode> ...
```
| Mode | Use when | Notes |
|------|----------|-------|
| `text` | One-shot answer, alternate draft, design critique | `--prompt-file` for long content |
| `verify` | Adversarial check of a claim/finding/plan | Grok is steered to **refute** first |
| `review` | Independent review of **one** file | Grok `read_file`s it; pass **absolute** paths for submodule files |
| `review-files` | Cross-file review of a change set | Same path rule; optional `-i "instructions"` |
| `review-diff` | Review a git range | `-C <submodule>` when the repo isn't the monorepo root |
| `image` | Generate a still image from text | Imagine `image_gen` → copies PNG/JPG to `out` |
| `video` | Animate an **existing** still into a short clip | `image_to_video`; needs input image; ~60–90s |
| `xsearch` | Live web + X facts past cutoff | May auto-fall back to **agy search** on timeout |
| `raw` | Escape hatch only | You own the flags and safety |
**Exact syntax, flags, timeouts, exit codes, embed fallbacks, raw CLI, and the
full abilities matrix:** **[HEADLESS.md](./HEADLESS.md)** (authoritative).
Do **not** hand-roll `grok -p …` from memory. The wrapper handles prompt files,
Windows path conversion, timeouts, JSON parse, media artifact recovery, model
pinning (`grok-4.5` for reasoning modes as of 2026-07), and errorlog.
**agy callers:** same wrapper. You do not need a separate Gemini→Grok bridge.
If you are Gemini/agy and need Grok's unique lanes (**media generation**, X
search, or a third vendor after Claude already reviewed), shell the same
`ask-grok.sh`.
Media is a first-class reason to call Grok — see **§3 Media generation** below.
---
## 3. Media generation (pictures, video, edits) — Grok-only lane
Claude and agy **cannot generate** images or video. Grok can. Treat media as a
primary peer capability, not a side note.
### Capability map
| Need | Who / how | Notes |
|------|-----------|--------|
| **New still image** from text | Grok `ask-grok.sh image "<prompt>" [out.png]` | Native tool: `image_gen` (Imagine). Default out: `grok-image.png`. |
| **Edit / transform** an existing image (style transfer, object change, keep likeness) | Grok native `image_edit` | **No dedicated wrapper mode yet.** Use interactive Grok, or `raw` / a careful prompt that forces `image_edit` with a path the session can read. Prefer interactive when quality matters. |
| **Animate one still** → short video | Grok `ask-grok.sh video "<motion>" <input-image> [out.mp4]` | Native tool: `image_to_video`. Input must exist on disk. ~60–90s. Default out: `grok-video.mp4`. |
| **Video from multiple reference images** + prompt | Grok native `reference_to_video` | **No dedicated wrapper mode yet.** Interactive or `raw`. Needs 2–7 reference images. |
| **Describe / QA an existing image** (no new pixels) | **agy** `image-analyze` | Vision only. Do **not** call Grok for "what is in this screenshot?" unless Grok is already interactive. |
| Icons, mockups, marketing art, UI concepts, client-facing graphics | Grok `image` | Claude owns placement into the repo/site after visual check. |
**Summary:** generate/edit/animate → **Grok**. Look-at / describe → **agy**
(or Claude's own vision if available). Never invent media with Ollama.
### How the wrapper delivers artifacts
1. Headless Grok runs Imagine / video tools.
2. Artifacts land under `~/.grok/sessions/<…>/<sessionId>/{images,videos}/`.
3. `ask-grok.sh` recovers by `sessionId` and **copies** to the path you passed
(even when headless reports a flaky `stopReason: Cancelled` — known quirk).
4. Stdout looks like: `[ask-grok] image OK -> ./out/icon.png (session …)`.
If exit code is non-zero or the out file is missing/empty, do not invent a
placeholder image — retry once or escalate to the user.
### Prompt craft for media
**Stills (`image`) — be specific:**
```
Subject + composition + style + constraints.
Example: "Flat vector app icon, blue shield with white checkmark, centered,
solid dark navy background, no text, no watermark, square, high contrast"
```
Useful knobs to put in the prompt (Imagine respects natural language, not a
separate style API via the wrapper):
- Aspect / framing: square icon, wide banner, portrait poster, UI mockup 16:9
- Style: flat vector, photoreal, isometric, wireframe, screenshot-like
- Negative constraints: "no text", "no watermark", "no extra limbs", "single object"
- Brand: only when the user supplied colors/logo rules — do not invent ACG branding
**Video (`video`) — motion prompt + still:**
```
Motion only (camera + subject action). The still already defines appearance.
Example: "Slow push-in, gentle parallax, subtle light flicker, no morphing faces"
```
- Always pass a real input path: `video "<motion>" ./assets/hero.png ./out/hero.mp4`
- Generate the still first (`image`) if you do not already have one
- Keep motion simple; complex multi-scene stories fail more often than a short loop
**Edits / multi-ref video (no wrapper mode):**
- Interactive Grok session is the reliable path for `image_edit` and
`reference_to_video`.
- If you must stay headless, use `raw` only with a human-approved prompt; recover
artifacts from the session dir the same way the wrapper does.
### Post-generation checklist (mandatory for peers)
1. Confirm the output file exists and size &gt; 0.
2. **Images:** Claude (or agy vision) **opens/views** the file — does it match the
brief? Wrong subject, text garbage, off-brand, NSFW/odd artifacts → regenerate
with a tighter prompt; do not ship.
3. **Video:** confirm container (ffprobe/header); spot-check if a player is
available. Duration is short (tool defaults ~6–10s class); do not promise
long-form film.
4. Place final assets under the **project path the user expects** (not only
`~/.grok/sessions/…`). The wrapper copy path is the handoff.
5. Client-facing or public site: human glance before publish when stakes are real.
### Media recipes
```bash
# Still → project path
bash .claude/skills/grok/scripts/ask-grok.sh image \
"flat blue shield icon, white check, no text, square" \
./projects/acg-website-showcase/design/icon-shield.png
# Still then animate
bash .claude/skills/grok/scripts/ask-grok.sh image \
"hero still, modern server room, soft light, no text, 16:9" \
./tmp-hero.png
bash .claude/skills/grok/scripts/ask-grok.sh video \
"slow dolly forward, subtle dust motes, cinematic" \
./tmp-hero.png \
./out/hero-loop.mp4
```
Then **view** `./projects/.../icon-shield.png` (and inspect the mp4) before any
commit, Discord post, or client send.
### What not to do with media
- Do not use agy/Claude "generate an image" paths — they do not own Imagine.
- Do not skip visual QA and paste a path into a ticket/site blindly.
- Do not put secrets, real customer PII, or internal credentials into image
prompts or burned-in text on graphics.
- Do not expect print-resolution catalogs or long-form video from these tools;
they are short-form / concept / web-asset grade unless proven otherwise.
---
## 4. When to route to Grok vs agy vs neither
### Prefer Grok
- **Any new pixels:** stills, edits, animate-from-still, multi-ref video
(`image` / `video` / native edit tools) — **Grok-only**
- X/Twitter-native search or social sentiment (`xsearch`)
- You already used **agy** and want a **different vendor** to triangulate
- User said "ask Grok" / "grok image" / "make a video" / "grok verify"
### Prefer agy (Gemini)
- Vision **analysis** of an existing image (`image-analyze`) — report only, no generation
- Live web search when you want Gemini's search path (`search`)
- You already used **Grok** and want a different vendor
- User said "ask Gemini" / "agy verify"
### Prefer neither (cheaper / local)
- Classify / extract / short summarize → **Tier-0 Ollama** (`.claude/OLLAMA.md`)
- Routine code edits and harness skill work → **Claude** (owner)
### Triangulate (high stakes)
For security, auth, credentials, migrations, production risk, or "are we about
to do something irreversible?":
1. Claude states the claim with evidence (files, commands, expected state).
2. `ask-grok.sh verify` **and/or** `ask-agy.sh verify` on the same claim.
3. **Disagreement is a stop signal** — do not average away conflict; investigate.
4. Human gate before any write that leaves the machine.
---
## 5. How to brief Grok (prompt craft)
Grok is strongest when the prompt is **concrete, bounded, and adversarial**.
Weak when given vague "look over this" or trusted to complete multi-step
production mutations unsupervised.
### Good `verify` brief
```
Claim: [one sentence]
Evidence Claude already has:
- file:line or command output (paste or path)
- expected end-state if this is true
Constraints:
- Try to REFUTE the claim first
- Verdict first: CONFIRMED | PARTIAL | REFUTED | INCONCLUSIVE
- Confidence 0-100
- Cite file:line or missing evidence
- No code edits, no production commands
```
### Good `review` / `review-files` brief
```
Scope: [what changed and why]
Focus: [bugs / security / API contract / missed edge cases]
Ignore: style nits unless they hide bugs
Output: findings ranked by severity with file:line; end with residual risks
Do not modify files.
```
### Good `text` brief
- One clear question or deliverable.
- Any hard constraints (tone, length, audience, "no emojis", ASCII markers).
- Context that is **not** already in a path Grok will read — or pass the path
via `review` / `--prompt-file` instead of pasting a novel.
### Bad briefs (avoid)
- "Make sure everything is fine" with no claim or files
- Dumping an entire monorepo into the prompt
- Asking Grok to "go fix production" or run MSP vendor APIs unsupervised
- Relative paths into a **submodule** without absolute resolution (see SKILL.md
path gotcha — this has failed repeatedly)
### Long content
Use `text --prompt-file path` or `verify --prompt-file path`. Never shove large
blobs through shell quoting. On Windows PowerShell, prefer the wrapper + prompt
file; do not embed nested double-quotes in `curl`/plink-style invocations.
---
## 6. What Grok will return (and how you should treat it)
### Headless modes
- **Stdout:** the answer text (or a path line for media).
- **stderr / prefixes:** diagnostics like
`[grok xsearch timed out -> answered via agy search]` — surface these to the user
when they change provenance.
- **Exit codes:** `0` ok · `1` no result · `2` usage · `3` not installed on this
machine · `127` binary missing.
### Expected tone from Grok
When steered as a reviewer (and when `AGENTS.md` applies), Grok aims for:
- No emojis; ASCII markers `[OK]` `[WARN]` `[ERROR]` `[INFO]`
- Verdict **first**, then reasoning
- Active refutation on verify
- `file:line` on code review
- Explicit **confidence**
If a headless call returns soft prose without a verdict, **re-prompt** with the
verify template above, or treat the answer as draft-quality only.
### Trust model (non-negotiable)
From the 2026-06-03 mspbackups post-mortem and standing harness rules:
1. **Never act on Grok output without review** when the next step is a write,
production call, billing, credential, or client-facing message.
2. **HTTP 200 ≠ done.** Grok (and any model) can over-claim. Require
read-back of end-state for mutations — Claude owns that loop.
3. **Media:** Claude must open/view generated images (and check video files);
do not ship uninspected art. See §3.
4. **xsearch provenance:** if the wrapper fell back to agy, say so — it is no
longer a pure xAI answer.
5. Grok can **over-claim and under-verify**. That is why you call it for
*critique*, not for *authority* (media is different: Grok *is* the generator,
but peers still QA the artifact).
---
## 7. What Grok must not be asked to own
| Task | Who owns it |
|------|-------------|
| Edit / commit / push this repo | Claude |
| Syncro, vault, RMM, Graph, UniFi, MSP360, etc. | Claude via **skills** (skill-first; never hand-roll) |
| Unsupervised production deletes / disables / purges | Human + Claude with confirm gates |
| Final "done" declaration on client work | Claude after check-skills |
| Cheap classify/summarize | Ollama Tier-0 |
Grok *can* run tools in interactive or poorly constrained headless runs
(`permission_mode` defaults elsewhere can be loose). The wrapper deliberately
uses `dontAsk` + `--no-subagents` for text/verify/review so peer calls stay
bounded. **Do not** expand peer calls into multi-step agentic production work
via `raw` unless a human is driving and watching.
---
## 8. Operational gotchas (peer callers)
| Gotcha | What to do |
|--------|------------|
| Submodule relative paths in `review*` | Pass **absolute** paths; for diffs use `-C projects/...` |
| Grok not installed here | Exit 3 — do not invent a local binary; note host routing gap |
| Auth errors | User runs `grok login` (OIDC, ~hours-scale refresh) |
| xsearch timeout | Accept agy fallback answer; label provenance |
| Empty review result | Wrapper may embed-fallback once if file &lt; ~256KB; if still empty, try `text --prompt-file` with a bounded excerpt |
| Backgrounding | Do **not** mix `ask-grok` with `&` + foreground probes in one shell; separate tool calls (see errorlog friction) |
| Model pin | Reasoning modes pin **`grok-4.5`** via wrapper (`GROK_MODEL=` override). **`grok-build` is invalid** on current CLI. Media/xsearch clear the pin |
| Do not pass `--effort` unless model advertises it | Unsupported effort levels error |
| Media missing after "OK-ish" run | Check `~/.grok/sessions/**/images` or `videos`; wrapper should have copied — if not, retry `image`/`video` once |
| `image_edit` / `reference_to_video` | No `ask-grok.sh` mode yet — interactive Grok or careful `raw` |
---
## 9. How Grok thinks about *you* (Claude / Gemini)
When Grok is asked for a second opinion, assume:
- **Claude** already explored the repo, ran skills, and holds the operational
plan. Grok's job is to stress-test claims and surface holes — not to re-derive
the entire harness from zero unless the prompt is a cold one-shot.
- **agy** is a peer, not a subordinate. Dual-model disagreement is valuable data.
- Prefer **short, decisive** feedback Claude can act on. Long essays without a
verdict waste the call.
- If evidence is missing, say **INCONCLUSIVE** and list what would change the
verdict — do not invent confirmation.
---
## 10. Minimal recipes
### Claude: adversarial verify before a risky step
```bash
bash .claude/skills/grok/scripts/ask-grok.sh verify --prompt-file ./.claim.md
```
Put the claim + evidence in `./.claim.md` (repo-relative; avoid `/tmp` on Windows).
### Claude: review a multi-file patch in a submodule
```bash
bash .claude/skills/grok/scripts/ask-grok.sh review-files -i "Focus on authz regressions" \
"$(pwd)/server/src/api/auth.rs" \
"$(pwd)/server/src/api/session.rs"
```
### Claude / agy: generate then inspect an image
```bash
bash .claude/skills/grok/scripts/ask-grok.sh image \
"flat icon, blue shield, no text" ./out/icon.png
# then Read/view ./out/icon.png before using it
```
### Claude / agy: still → short video
```bash
bash .claude/skills/grok/scripts/ask-grok.sh image \
"product hero, clean desk, soft light, no text, 16:9" ./out/hero.png
bash .claude/skills/grok/scripts/ask-grok.sh video \
"slow push-in, gentle light shift" ./out/hero.png ./out/hero.mp4
```
### agy session: need Grok media or a third-vendor check
Same `ask-grok.sh image` / `video` / `verify` commands. For pure second opinion
without media, either `ask-grok.sh verify` or stay on `ask-agy.sh verify` —
pick **one** unless stakes justify both. For "what is in this PNG?", use
`ask-agy.sh image-analyze`, not Grok gen.
### Triangulate high-stakes claim
```bash
bash .claude/skills/grok/scripts/ask-grok.sh verify --prompt-file ./.claim.md
bash .claude/skills/agy/scripts/ask-agy.sh verify --prompt-file ./.claim.md
# Compare; on disagreement, stop and investigate
```
---
## 11. Related paths
| Path | Role |
|------|------|
| **[HEADLESS.md](./HEADLESS.md)** | **Exact headless syntax + abilities** |
| [SKILL.md](./SKILL.md) | Modes, flags, fleet install, safety summary |
| `scripts/ask-grok.sh` | Implementation |
| [../agy/SKILL.md](../agy/SKILL.md) | Sibling second-opinion router |
| `AGENTS.md` (repo root) | What **interactive/reviewer Grok** is told about its own role |
| `GEMINI.md` (repo root) | Parallel reviewer brief for Gemini/agy |
| `.grok/README.md` | When Grok *drives* the harness (hooks, skills mirrors) |
| `docs/session-notes/2026-06-03-claude-postmortem-grok-mspbackups-sbs.md` | False-completion case study — required reading for trust model |
| `.claude/SKILL_ROUTING.md` | Request → skill map (`grok` / `agy` rows) |
---
## 12. One-line contract
**Call Grok for independent critique, live/X search, and all picture/video
generation; never for unsupervised ownership of ClaudeTools production work.
Brief tightly; for verify demand a verdict; for media QA the artifact; treat
disagreement with agy as a stop.**

14
.claude/skills/grok/SKILL.md
View File

@@ -10,6 +10,14 @@ for things Claude can't do natively, or for a genuinely independent second model
Verified working on this machine (2026-06-04): image gen, image->video, live Verified working on this machine (2026-06-04): image gen, image->video, live
web/X search, text reasoning. web/X search, text reasoning.
> **Peer contract (Claude + Gemini/agy):**
> - [PEER_GUIDE.md](./PEER_GUIDE.md) — when to call Grok, media product rules, trust model
> - [HEADLESS.md](./HEADLESS.md) — **exact headless syntax**, every wrapper mode,
> flags, timeouts, exit codes, raw CLI, abilities matrix, Windows paths
>
> Short mode table stays below; if syntax conflicts, **HEADLESS.md + `ask-grok.sh`
> win**.
**Auth:** Grok uses its own OIDC login (`~/.grok/auth.json`, grok.com, ~6h refresh) **Auth:** Grok uses its own OIDC login (`~/.grok/auth.json`, grok.com, ~6h refresh)
— **no API key**. If calls fail with auth errors, the user runs `grok login`. — **no API key**. If calls fail with auth errors, the user runs `grok login`.
@@ -85,10 +93,12 @@ Grok is **per-machine** — the skill syncs fleet-wide but the binary does not.
- `~/.grok/config.toml` defaults to `permission_mode = "always-approve"` (auto-runs tools). The wrapper's single-context modes (`text`/`verify`/`review*`) override with `--permission-mode dontAsk --no-subagents` (cheap, bounded, timeout-predictable). **`xsearch` is the deliberate exception:** it uses `--yolo` and leaves subagents ENABLED, because `web_search` runs the `grok-4.20-multi-agent` model — passing `--no-subagents` made it hang with zero output (the long-standing xsearch-empty bug; root-caused + fixed 2026-06-16). Don't re-add `--no-subagents` to xsearch. - `~/.grok/config.toml` defaults to `permission_mode = "always-approve"` (auto-runs tools). The wrapper's single-context modes (`text`/`verify`/`review*`) override with `--permission-mode dontAsk --no-subagents` (cheap, bounded, timeout-predictable). **`xsearch` is the deliberate exception:** it uses `--yolo` and leaves subagents ENABLED, because `web_search` runs the `grok-4.20-multi-agent` model — passing `--no-subagents` made it hang with zero output (the long-standing xsearch-empty bug; root-caused + fixed 2026-06-16). Don't re-add `--no-subagents` to xsearch.
- Prompts are passed via `--prompt-file` only (inline args break on shell quoting). - Prompts are passed via `--prompt-file` only (inline args break on shell quoting).
- `grok-build` does NOT support `--effort`/`--reasoning-effort` (`supports_reasoning_effort:false` in the model info) — passing them 400s. Don't. - `grok-build` does NOT support `--effort`/`--reasoning-effort` (`supports_reasoning_effort:false` in the model info) — passing them 400s. Don't.
- Models (verify live with `grok models`): `grok-build` ("Grok Build", xAI's latest coding model, 512k ctx — the **documented** default per `docs/user-guide/11-custom-models.md`) and `grok-composer-2.5-fast` ("Cursor's latest coding model", fast). **Gotcha:** on this machine the runtime default that `grok models` reports is `grok-composer-2.5-fast`, and the wrapper pins no `-m`, so it currently rides whatever the runtime default is (not necessarily grok-build). `web_search` uses a SEPARATE model, `grok-4.20-multi-agent` (set via `[tools] web_search` / `GROK_WEB_SEARCH_MODEL`). - Models (verify live with `grok models`): **2026-07 fleet host reports default `grok-4.5`** (usage may show `grok-4.5-build`). The wrapper pins **`-m grok-4.5`** for text/verify/review* (`GROK_MODEL` override). **`grok-build` is no longer a valid model id** (unknown model error). Image/video/xsearch clear the pin and use the runtime default. Do not pass `--effort` unless the live model advertises support.
- After media gen, Claude should **view the image** (Read tool) to confirm correctness; videos can be confirmed by header/ffprobe. - After media gen, Claude should **view the image** (Read tool) to confirm correctness; videos can be confirmed by header/ffprobe.
- **Full headless reference:** [HEADLESS.md](./HEADLESS.md).
## Reference ## Reference
- Binary: `~/.grok/bin/grok.exe` (not on PATH; the wrapper auto-locates it or honors `GROK=`). - Binary: `~/.grok/bin/grok.exe` (not on PATH; the wrapper auto-locates it or honors `GROK=`).
- Full capability investigation + verification: see the 2026-06-04 session log. - Headless syntax + abilities: [HEADLESS.md](./HEADLESS.md). Peer judgment: [PEER_GUIDE.md](./PEER_GUIDE.md).
- Vendor docs on machine: `~/.grok/docs/user-guide/14-headless-mode.md`.
- Grok native tools observed: `image_gen`, `image_edit`, `image_to_video`, `reference_to_video`, `web_search`, `web_fetch`, `x_keyword_search`, `x_semantic_search`, `x_user_search`, `x_thread_fetch`, `run_terminal_command`, file ops, `scheduler_*`, `monitor`, memory. - Grok native tools observed: `image_gen`, `image_edit`, `image_to_video`, `reference_to_video`, `web_search`, `web_fetch`, `x_keyword_search`, `x_semantic_search`, `x_user_search`, `x_thread_fetch`, `run_terminal_command`, file ops, `scheduler_*`, `monitor`, memory.

13
.claude/skills/grok/scripts/ask-grok.sh
View File

@@ -101,12 +101,13 @@ fi
# --no-subagents made it hang with zero output (root cause, 2026-06-16). See xsearch. # --no-subagents made it hang with zero output (root cause, 2026-06-16). See xsearch.
GROK_PERM_FLAGS=(--permission-mode dontAsk) GROK_PERM_FLAGS=(--permission-mode dontAsk)
GROK_SUBAGENT_FLAGS=(--no-subagents) GROK_SUBAGENT_FLAGS=(--no-subagents)
# Pin xAI's flagship grok-build for the reasoning modes (text/verify/review*) so the # Pin a known-good coding/reasoning model for text/verify/review* so second-opinion
# second-opinion quality is deterministic and not at the mercy of the runtime default # quality is deterministic. Live default drifts (2026-07: `grok models` reports
# (which drifts -- this machine's `grok models` reports grok-composer-2.5-fast, a fast # grok-4.5; older docs said grok-build / grok-composer-2.5-fast — grok-build is now
# Cursor coding model). xsearch + image/video clear this to "" to use the runtime # rejected as unknown model id). Override with GROK_MODEL= if needed.
# default (xsearch's searcher is a separate model; media gen was verified on default). # xsearch + image/video clear this to "" to use the runtime default (xsearch's
GROK_MODEL="${GROK_MODEL:-grok-build}" # searcher is a separate multi-agent path; media gen verified on default).
GROK_MODEL="${GROK_MODEL:-grok-4.5}"
run_grok() { run_grok() {
local to="$1"; shift local to="$1"; shift