From e290a6eb4b2cbae2bc3d999ec9a1bda2c58f86ed Mon Sep 17 00:00:00 2001 From: Codeman maintainer Date: Sun, 18 Oct 2026 08:14:39 +0200 Subject: [PATCH] fix(#648): move Antigravity into the screen-checked group in five more docs docs/api-reference.md (the signal notes and the idle/working rows), and the wiki's Notifications-And-Approvals, Keeping-Agents-Running and Troubleshooting pages, plus docs/grok-integration.md, still called Antigravity's working and idle status unreliable. It now declares a working line and prompt marker like Codex, OpenCode, Gemini, Pi and OMP, so only Grok stays on generic cues. The Troubleshooting entry for a session stuck showing busy also says that an Antigravity session waiting on a shell-command approval shows busy until it is answered, and the API reference says the same of its idle signal. Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/api-reference.md | 6 +++--- docs/grok-integration.md | 6 +++--- docs/wiki/Keeping-Agents-Running.md | 15 +++++++-------- docs/wiki/Notifications-And-Approvals.md | 4 ++-- docs/wiki/Troubleshooting.md | 14 ++++++++------ 5 files changed, 23 insertions(+), 22 deletions(-) diff --git a/docs/api-reference.md b/docs/api-reference.md index 847df3ca..7db48c8a 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -217,7 +217,7 @@ runs no agent, and the external CLIs render their own TUIs and post no hooks is `blocked` on `codex`: Codeman reads codex's approval, question and trust dialogs off its screen and raises `blocked` for them (see [Signals](#signals)). For every other mode only `idle`, `working` and `exit` are accepted. `exit` is dependable everywhere; `idle` and -`working` are screen-checked for `opencode`, `gemini`, `pi` and `omp` (as for `claude` and +`working` are screen-checked for `opencode`, `gemini`, `pi`, `omp` and `antigravity` (as for `claude` and `codex`) and not guaranteed elsewhere: see the caveats under [Signals](#signals) before building on `idle`. Requesting a signal the session can never emit **explicitly** is a `400` (`stop` on @@ -246,8 +246,8 @@ contract is a **marker unique to each call** (`MARK="DONE_$RANDOM"`, send | Signal | Source | Actually fires for | |--------|--------|--------------------| -| `idle` | the session's own `idle` event | `claude`: yes, on ❯-prompt detection after activity. `codex`, `opencode`, `gemini`, `pi`, `omp`: yes, the same screen check through the prompt marker and working line each declares (`capabilities.workDetect`). `shell`: **once only**, ~500 ms after start, and never again. Other external CLIs (`antigravity`, `grok`, `deepseek`): not guaranteed (they render their own TUIs and readiness is output stabilization) | -| `working` | the session's own `working` event | `claude`, plus `codex`, `opencode`, `gemini`, `pi` and `omp` through the working line each declares. Elsewhere not guaranteed: it rests on generic output heuristics such as a braille spinner glyph | +| `idle` | the session's own `idle` event | `claude`: yes, on ❯-prompt detection after activity. `codex`, `opencode`, `gemini`, `pi`, `omp`, `antigravity`: yes, the same screen check through the prompt marker and working line each declares (`capabilities.workDetect`); an `antigravity` session waiting on a shell-command approval stays `working` until it is answered. `shell`: **once only**, ~500 ms after start, and never again. Other external CLIs (`grok`, `deepseek`): not guaranteed (they render their own TUIs and readiness is output stabilization) | +| `working` | the session's own `working` event | `claude`, plus `codex`, `opencode`, `gemini`, `pi`, `omp` and `antigravity` through the working line each declares. Elsewhere not guaranteed: it rests on generic output heuristics such as a braille spinner glyph | | `stop` | the Claude Code `stop` hook, the definitive end-of-turn signal | `claude` (and `deepseek`) only | | `blocked` | a `permission_prompt` or `elicitation_dialog` hook; on `codex`, a dialog read off its screen | `claude`, `deepseek` and `codex`; on `claude` rarer than it looks: see below | | `exit` | no process is behind the session | every mode | diff --git a/docs/grok-integration.md b/docs/grok-integration.md index 81a00803..a78d1d1c 100644 --- a/docs/grok-integration.md +++ b/docs/grok-integration.md @@ -122,11 +122,11 @@ the remote host, `grok login --device-auth` exists for exactly this. ## Known gaps - **No idle/completion hook yet.** The registry entry declares no `workDetect` prompt - marker or working line, which is what gives Codex, OpenCode, Gemini, Pi and OMP a - screen check. So Codeman calls a new grok pane idle 3 seconds after launch, and after + marker or working line, which is what gives Codex, OpenCode, Gemini, Pi, OMP and + Antigravity a screen check. So Codeman calls a new grok pane idle 3 seconds after launch, and after that it has only generic cues: Claude's `❯` marker, which grok does not print (see the cron item below), and a braille spinner glyph. Working and idle are unreliable for - grok, as for Antigravity. Grok has a hooks system, so a Codeman hook POSTing to + grok. Grok has a hooks system, so a Codeman hook POSTing to `/api/hook-event` is the highest-value follow-up. - **No response viewer.** Grok writes ACP JSONL sessions under `~/.grok/sessions///updates.jsonl`; nothing reads them yet. diff --git a/docs/wiki/Keeping-Agents-Running.md b/docs/wiki/Keeping-Agents-Running.md index 715d02c3..dfa4fc10 100644 --- a/docs/wiki/Keeping-Agents-Running.md +++ b/docs/wiki/Keeping-Agents-Running.md @@ -28,14 +28,13 @@ There are several layers stacked on that: a completion message from the CLI, an output silence, and token stability. **For the other CLIs** it depends on what the CLI tells Codeman. Codex, OpenCode, Gemini -CLI, Pi and OMP each declare their own prompt marker and working line, so they get the same -screen check Claude does (before 1.26.1 every Codex session reported idle for its whole -life). DeepSeek Harness reports its end of turn and its dialogs to Codeman itself, which is -as precise as hooks; its working and idle display still comes from its output. Antigravity -and Grok Build declare neither. Codeman calls a new pane of theirs idle 3 seconds after -launch, and after that it has only generic cues to go on (Claude's `❯` prompt marker, a -braille spinner glyph), which these CLIs may not draw, so their working and idle status is -unreliable. +CLI, Pi, OMP and Antigravity each declare their own prompt marker and working line, so they +get the same screen check Claude does (before 1.26.1 every Codex session reported idle for +its whole life). DeepSeek Harness reports its end of turn and its dialogs to Codeman itself, +which is as precise as hooks; its working and idle display still comes from its output. +Grok Build declares neither. Codeman calls a new grok pane idle 3 seconds after launch, and +after that it has only generic cues to go on (Claude's `❯` prompt marker, a braille spinner +glyph), which grok may not draw, so its working and idle status is unreliable. ## The Respawn Controller diff --git a/docs/wiki/Notifications-And-Approvals.md b/docs/wiki/Notifications-And-Approvals.md index ca5976ec..fcdd7f93 100644 --- a/docs/wiki/Notifications-And-Approvals.md +++ b/docs/wiki/Notifications-And-Approvals.md @@ -39,8 +39,8 @@ hooks, but its dialogs are distinctive enough to read off the screen, so a Codex waiting on an approval, a question or the "Trust this folder?" prompt turns red too, and clears a few seconds after you answer. For the other CLIs there are no hooks and no dialog reading, so you get only the coarser working and idle state: read off the screen for -OpenCode, Gemini CLI, Pi and OMP, and unreliable for Antigravity and Grok Build, which -declare nothing Codeman can read it from. +OpenCode, Gemini CLI, Pi, OMP and Antigravity, and unreliable for Grok Build, which +declares nothing Codeman can read it from. ## Window title and OS notifications diff --git a/docs/wiki/Troubleshooting.md b/docs/wiki/Troubleshooting.md index fdfb22e6..114ca37d 100644 --- a/docs/wiki/Troubleshooting.md +++ b/docs/wiki/Troubleshooting.md @@ -116,12 +116,14 @@ seconds in. Current versions confirm against the actual screen before believing ### A session is stuck showing busy -For Antigravity and Grok Build the busy and idle status is unreliable: those CLIs expose no -hooks and declare no working line, so after launch Codeman has only generic cues to go on -(Claude's `❯` prompt marker, a braille spinner glyph), which they may not draw. Codex, -OpenCode, Gemini CLI, Pi and OMP get the same screen check Claude does, so a session of -theirs that has genuinely gone quiet will settle. If it never does, interrupt it (`Ctrl+C` -with nothing selected). +For Grok Build the busy and idle status is unreliable: it exposes no hooks and declares no +working line, so after launch Codeman has only generic cues to go on (Claude's `❯` prompt +marker, a braille spinner glyph), which it may not draw. Codex, OpenCode, Gemini CLI, Pi, +OMP and Antigravity get the same screen check Claude does, so a session of theirs that has +genuinely gone quiet will settle. An Antigravity session waiting on a shell-command approval +("Run this command?") shows busy until you answer it: `agy` draws nothing Codeman reads as +"at rest" while that list is up. If a session never settles, interrupt it (`Ctrl+C` with +nothing selected). ### The agent asks about bypass permissions every time