From 728308de6221e318aaa24ec4def7c9c6501df9dd Mon Sep 17 00:00:00 2001 From: Mike Swanson Date: Thu, 23 Jul 2026 18:28:22 -0700 Subject: [PATCH] =?UTF-8?q?grok:=20fix=20headless=20reasoning=20modes=20?= =?UTF-8?q?=E2=80=94=20pin=20grok-4.5=20(was=20stale=20grok-build)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- .claude/skills/grok/HEADLESS.md | 724 ++++++++++++++++++++++++ .claude/skills/grok/PEER_GUIDE.md | 437 ++++++++++++++ .claude/skills/grok/SKILL.md | 14 +- .claude/skills/grok/scripts/ask-grok.sh | 13 +- 4 files changed, 1180 insertions(+), 8 deletions(-) create mode 100644 .claude/skills/grok/HEADLESS.md create mode 100644 .claude/skills/grok/PEER_GUIDE.md diff --git a/.claude/skills/grok/HEADLESS.md b/.claude/skills/grok/HEADLESS.md new file mode 100644 index 00000000..21421f8a --- /dev/null +++ b/.claude/skills/grok/HEADLESS.md @@ -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 …` | **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\\.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" [args...] +``` + +Short form when CWD is repo root: + +```bash +bash .claude/skills/grok/scripts/ask-grok.sh [args...] +``` + +### Modes (complete) + +| Mode | Syntax | Stdout success | Typical wall time | +|------|--------|----------------|-------------------| +| `text` | `text ""` **or** `text --prompt-file ` | Answer text | ≤ ~180s budget | +| `verify` | `verify ""` **or** `verify --prompt-file ` | Verdict + reasons | ≤ ~180s | +| `review` | `review ["instructions"]` | Review text | ≤ ~240s (+ optional embed retry) | +| `review-files` | `review-files [-i\|--instr "…"] [f2 …]` | Review text | ≤ ~300s | +| `review-diff` | `review-diff [-C ] [-i "…"] [-- ]` | Review text | ≤ ~300s | +| `image` | `image "" [out.png]` | `[ask-grok] image OK -> (session )` | ≤ ~240s | +| `video` | `video "" [out.mp4]` | `[ask-grok] video OK -> (session )` | ≤ ~360s | +| `xsearch` | `xsearch ""` | Answer text (or agy fallback) | ≤ ~240s then possible agy | +| `raw` | `raw ` | 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 \ + --prompt-file \ + --output-format json \ + [-m ] \ # omitted if GROK_MODEL is empty + --permission-mode dontAsk \ + --no-subagents \ + --no-plan \ + --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` +- 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 `` exists as given (relative to **caller CWD**) → use it +2. Else if `$CLAUDETOOLS_ROOT/` 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 diff [-- 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: **``** (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/*//images/*` + and `cp` to `out` +- Success line: `[ask-grok] image OK -> (session )` +- 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 -> (session )` + +#### `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 \ + --prompt-file \ + --output-format streaming-json \ + --yolo \ + --no-plan \ + --cwd \ + --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 ""` 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 '' +``` + +**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": { "": { "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 ` | 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///images/ +~/.grok/sessions///videos/ +``` + +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 `. +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" "" --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/**//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.* diff --git a/.claude/skills/grok/PEER_GUIDE.md b/.claude/skills/grok/PEER_GUIDE.md new file mode 100644 index 00000000..7bec5015 --- /dev/null +++ b/.claude/skills/grok/PEER_GUIDE.md @@ -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 …` +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 | 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 ` 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 "" [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 "" [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/<…>//{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 "" ./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 > 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 < ~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.** diff --git a/.claude/skills/grok/SKILL.md b/.claude/skills/grok/SKILL.md index b5777693..62915bc9 100644 --- a/.claude/skills/grok/SKILL.md +++ b/.claude/skills/grok/SKILL.md @@ -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 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) — **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. - 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. -- 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. +- **Full headless reference:** [HEADLESS.md](./HEADLESS.md). ## Reference - 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. diff --git a/.claude/skills/grok/scripts/ask-grok.sh b/.claude/skills/grok/scripts/ask-grok.sh index b5c8255f..a2a1de25 100644 --- a/.claude/skills/grok/scripts/ask-grok.sh +++ b/.claude/skills/grok/scripts/ask-grok.sh @@ -101,12 +101,13 @@ fi # --no-subagents made it hang with zero output (root cause, 2026-06-16). See xsearch. GROK_PERM_FLAGS=(--permission-mode dontAsk) GROK_SUBAGENT_FLAGS=(--no-subagents) -# Pin xAI's flagship grok-build for the reasoning modes (text/verify/review*) so the -# second-opinion quality is deterministic and not at the mercy of the runtime default -# (which drifts -- this machine's `grok models` reports grok-composer-2.5-fast, a fast -# Cursor coding model). xsearch + image/video clear this to "" to use the runtime -# default (xsearch's searcher is a separate model; media gen was verified on default). -GROK_MODEL="${GROK_MODEL:-grok-build}" +# Pin a known-good coding/reasoning model for text/verify/review* so second-opinion +# quality is deterministic. Live default drifts (2026-07: `grok models` reports +# grok-4.5; older docs said grok-build / grok-composer-2.5-fast — grok-build is now +# rejected as unknown model id). Override with GROK_MODEL= if needed. +# xsearch + image/video clear this to "" to use the runtime default (xsearch's +# searcher is a separate multi-agent path; media gen verified on default). +GROK_MODEL="${GROK_MODEL:-grok-4.5}" run_grok() { local to="$1"; shift