@tranhoangnguyen0310/pi-flow-external 2.1.0-external.3 → 2.3.0-external.0

package/AGENTS.md

@@ -2,18 +2,19 @@
 
 ## pi-flow external contract
 
-This fork changes the original pi-flow contract: `Agent` is not a generic Pi subagent launcher. It delegates only to external Claude Code, Codex CLI, and Antigravity harnesses, plus named Pi harness configurations (below) — in-process, per-model configs registered by the user, not a fourth CLI.
+This fork changes the original pi-flow contract: `Agent` is not a generic Pi subagent launcher. It delegates only to external Claude Code, Codex CLI, Antigravity, and Grok Build CLI harnesses, plus named Pi harness configurations (below) — in-process, per-model configs registered by the user, not a spawned CLI.
 
 - Ordinary driver tools: `Agent`, read-only `external_help`, `external_runs`, and optional `workflow`. `pi_flow_profile_create` and `pi_flow_harness_create` are active only inside `/external profile create`.
 - User operations use `/external`; `/pi-flow-profile create` is a temporary deprecated alias.
 - Extension-owned concurrency, timeout, and global default-harness settings live in `$PI_CODING_AGENT_DIR/pi-flow-external/settings.json`. Profile backend/model/thinking metadata remains in `subagents/*.md`. Named Pi harness configurations live in the sibling `$PI_CODING_AGENT_DIR/pi-flow-external/harnesses.json` registry (one shared file, `pi-<label>` keys pinning `model`/`thinking`). Registry writes are atomic per file, but there is no inter-process lock: concurrent writers adding distinct names from separate sessions are last-writer-wins and may drop one update. This is an accepted v1 limitation shared with `settings.json` and `subagents/*.md`, not a bug to re-report. A trusted project may override `defaultHarness` via `.pi/pi-flow-external/settings.json` (that key only, read-only to the extension); explicit call harness > project default > global default. `defaultHarness` may itself name a registered `pi-*` harness.
-- Every `Agent` call requires `description`, `prompt`, and either `role` with optional `harness` (`agy`, `claude`, `codex`, or a registered `pi-*` harness name) or the legacy exact-profile `subagent_type`. The selectors cannot be combined. Without `harness`, use the effective default harness; if that default names a `pi-*` harness that is no longer registered, the call fails with an actionable error rather than silently falling back to `agy`.
-- Valid profiles come from `~/.pi/agent/subagents/*.md` and set `backend: claude`, `backend: codex`, `backend: agy`, or (only when also declaring `harness: <registered pi-* name>`) `backend: pi`. Use matching names such as `claude-*`, `codex-*`, `agy-*`, or `<harness>-*`; the assisted creator enforces that convention.
-- A default roster ships with the extension and seeds once on session start: five code-oriented roles (explorer, planner, implementer, reviewer, qa) plus the generalist worker, one storage profile per CLI backend (18 files, but six advertised roles). Seeding never overwrites existing files and respects later deletions. Roles outside the default roster are user-created via `/external profile create`. Every registered named Pi harness automatically and immediately gets the same six roles too, synthesized in-memory from the identical canonical role source — no per-harness file needed, and no on-disk seeding for pi harnesses.
+- Every `Agent` call requires `description`, `prompt`, and either `role` with optional `harness` (`agy`, `claude`, `codex`, `grok`, or a registered `pi-*` harness name) or the legacy exact-profile `subagent_type`. The selectors cannot be combined. Without `harness`, use the effective default harness; if that default names a `pi-*` harness that is no longer registered, the call fails with an actionable error rather than silently falling back to `agy`.
+- Valid profiles come from `~/.pi/agent/subagents/*.md` and set `backend: claude`, `backend: codex`, `backend: agy`, `backend: grok`, or (only when also declaring `harness: <registered pi-* name>`) `backend: pi`. Use matching names such as `claude-*`, `codex-*`, `agy-*`, `grok-*`, or `<harness>-*`; the assisted creator enforces that convention.
+- A default roster ships with the extension and seeds once on session start: five code-oriented roles (explorer, planner, implementer, reviewer, qa) plus the generalist worker, one storage profile per CLI backend across four backends (24 files, but six advertised roles). Seeding never overwrites existing files and respects later deletions. Roles outside the default roster are user-created via `/external profile create`. Every registered named Pi harness automatically and immediately gets the same six roles too, synthesized in-memory from the identical canonical role source — no per-harness file needed, and no on-disk seeding for pi harnesses. An installation seeded before Grok support existed migrates forward by adding only the six new `grok-*` profiles on its next seed pass, never resurrecting a deleted or customized claude/codex/agy profile.
 - A `backend: pi` profile is external-delegation-eligible only when it also declares `harness: <name>` for a name present in the live `harnesses.json` registry; a bare `backend: pi` profile (no `harness`, or one naming an unregistered config) is filtered out and rejected exactly as before — it belongs to Pi's native subagent system and this extension never modifies it.
 - **Named Pi harness configuration:** a `pi-<label>` entry in `harnesses.json` pinning a `provider/model` id (resolved through Pi's own model registry) and a thinking level (`off|minimal|low|medium|high|xhigh`, always persisted explicitly). It runs in-process via Pi's own SDK, not as a spawned CLI. A pi child loads no project/user extensions, skills, prompt templates, or themes — its entire tool surface is the SDK's own builtins (`read`/`bash`/`edit`/`write`, plus `grep`/`find`/`ls` where a tier's default allow-list adds them), curated but never claimed to be an OS sandbox: `danger` tier `bash` is exactly as exposed as on any external CLI. Retry is disabled per child (in-memory, call-scoped, never touching the user's real settings) to honor this extension's no-auto-retry contract, since the underlying SDK otherwise retries transient provider errors on its own. Pi children cannot resume (no persisted session) and have no enforced budget cap — both are deliberate v1 limitations, not oversights. Custom (non-canonical) roles are still authored per harness via `/external profile create`, not shared across harnesses automatically. Follow-up capability expansion (trusted extensions/MCP/skills, shared custom roles, resumable sessions, real budget controls) is tracked in issue #43.
 - Use Pi's native subagent system for Pi-backed scout/reviewer/planner/worker/oracle work.
-- External CLI backends use their own tools and permission mechanisms. Codex tiers map to its `--sandbox` axis. Claude falls back to `--permission-mode auto` when its effective UID is 0 because Claude refuses bypass mode under root. Execution lanes (implementer, qa, worker) require shell command authority to inspect repositories and run tests; on Claude and on pi harnesses (where `edit` tier excludes `bash`), execution lanes maintain a danger floor so agents are not artificially handcuffed. Antigravity (`agy`) has no granular headless permission mode — its default sandbox denies even read-only tools — so every agy run is unsandboxed (`--dangerously-skip-permissions`) and `readonly`/`edit` on agy are advisory profile-body instructions, not a boundary. Run them only in trusted repositories and state whether the task is read-only or may edit files.
+- External CLI backends use their own tools and permission mechanisms. Codex tiers map to its `--sandbox` axis. Grok tiers also map to its `--sandbox` axis (`read-only`/`workspace`/`off`), always paired with `--permission-mode bypassPermissions`; bypass only skips the interactive prompt, and the kernel sandbox remains the enforced boundary at every tier. Grok's readonly network-blocking guarantee is Linux-only (a no-op on macOS), and sandbox startup can fail closed rather than silently downgrading on some macOS hosts (for example when `/var/run/docker.sock` resolves to a symlink). Claude falls back to `--permission-mode auto` when its effective UID is 0 because Claude refuses bypass mode under root. Execution lanes (implementer, qa, worker) require shell command authority to inspect repositories and run tests; on Claude and on pi harnesses (where `edit` tier excludes `bash`), execution lanes maintain a danger floor so agents are not artificially handcuffed. Grok needs no such floor: its `edit` tier (`--sandbox workspace`) already permits shell execution, sandboxed to writes within the workspace. Antigravity (`agy`) has no granular headless permission mode — its default sandbox denies even read-only tools — so every agy run is unsandboxed (`--dangerously-skip-permissions`) and `readonly`/`edit` on agy are advisory profile-body instructions, not a boundary. Run them only in trusted repositories and state whether the task is read-only or may edit files.
+- Grok supports `resume` via its own `--resume <sessionId>` flag and reports native cost (`total_cost_usd`) rather than an estimate. It has no budget-enforcement mechanism, so `max_budget_usd` is recorded but unenforceable, and — like codex — it is never automatically retried (agy's one infra-failure retry exception does not apply to Grok).
 - Children receive no parent history by default. `Agent` and workflow `agent()` can opt into `context: {mode: "recent", turns: N}` (last N user turns, including the current one) or `{mode: "full"}` (available post-compaction conversation). Snapshots exclude system instructions, thinking, tool-result metadata, and pending calls; unsupported content/images and more than 1 MiB fail explicitly. Use the smallest sufficient snapshot plus a clear task, absolute paths, and read-only/edit intent. Shared context goes to the external harness and private local evidence; avoid unnecessary sensitive history. `resume` continues an existing child and cannot be combined with sharing. Workflow children select from one frozen parent snapshot, and replay fingerprints include the transferred context.
 - Backend-native nested agents may use a different workspace. Include explicit absolute paths and required context when asking an external backend to delegate further.
 - `Agent` and `workflow` block by default; `background: true` returns a stable handle after validation/registration. Background work is owned by the originating session, not by the launching tool call or a daemon. Blocking-call interruption cancels work; wait interruption only stops waiting. Orderly session shutdown requests cancellation with bounded cleanup. A crash or unconfirmed shutdown leaves unfinished evidence interrupted/uncertain; restart never adopts live work.
@@ -36,7 +37,7 @@ This fork changes the original pi-flow contract: `Agent` is not a generic Pi sub
 - Settings retention automatically prunes eligible completed records beyond `maxRunRecords`; active, interrupted, incomplete, and damaged records are not eligible.
 - Structured nested-agent activity may extend the wall-clock deadline once, by one fresh base timeout, capped at twice the original deadline.
 - Do not automatically retry failed or aborted external runs. Preserve the receipt and retry only when the user asks. Exception: the agy backend retries once on infrastructure-classified failures (auth, eligibility, network); the retry is disclosed in the receipt details (`retries`, `retryOf`) and never applies to agent-level failures, aborts, or timeouts.
-- `external_runs` is session/project scoped. `list` pages runs and workflow roots; `inspect` pages summaries/output/diagnostics; `wait` returns outcomes only for the selected one/any/all target set and never cancels pending work; `cancel` targets one stable ID and preserves its reason. No routine run event sends a parent message or notification.
+- `external_runs` is session/project scoped. `list` pages runs and workflow roots, each carrying a shared timing projection (`queuedAt`/`executionStartedAt`/`processStartedAt`/activity timestamps plus derived `queueDelayMs`/`elapsedMs`/`activityAgeMs`/`processDurationMs`); `activityAgeMs` and a running `elapsedMs` are computed only for a target independently confirmed live by the registry, never inferred from a durable record's status field alone (an unowned "running"-looking record may be an orphaned/crashed run, not a live one). `inspect` pages `summary`/`output`/`diagnostics`/`final` for one `runId`; `final` returns only the same canonical terminal result every other view already reads (no separate backend parser, no narration promoted to final) and is empty with `finalAvailable: false` until a verified successful terminal boundary exists — including for workflows, where an intentional JSON `null` result still counts as available. `inspect` also accepts a bounded batch `runIds` (up to 20, deduplicated, order preserved, summary-only, mutually exclusive with `runId`): every requested ID's ownership is validated before any page returns, entries share one consistent nested shape regardless of live/durable/agent/workflow origin (a workflow entry omits its unbounded children array in favor of `outputRef`/`diagnosticsRef`), reuses the existing per-inspect `limitBytes` cap with no second budget, and fails with an actionable error naming the run rather than ever silently dropping a target or serving a page over the caller's own byte budget. `wait` returns outcomes only for the selected one/any/all target set and never cancels pending work; `cancel` targets one stable ID and preserves its reason. An unresolvable `wf_...` ID fails as unknown/unavailable across `inspect`/`cancel`/`wait`/batch `inspect`, never falling through to the agent-only durable reader. No routine run event sends a parent message or notification.
 
 ## Workflow contract
 
@@ -52,7 +53,7 @@ Use workflows for requested fan-out or multi-agent orchestration across Claude/C
 - Test public contracts, trust/security boundaries, process lifecycle, cancellation/timeouts, profile rollback, workflow execution/resume, and receipt integrity.
 - Do not test cosmetic rendering variations, prompt prose fragments, trivial accessors, or a model's interpretation of instructions.
 - Do not repeat the same behavior at unit, integration, and E2E levels. A regression test must replace or extend overlapping coverage.
-- `npm test` must remain deterministic and offline. Real-provider E2E is opt-in and change-triggered through `npm run e2e -- --backend <claude|codex|agy> [--workflow]`, or `npm run e2e -- --backend pi --harness <registered-name> [--workflow]` for a named Pi harness the caller has already registered in their own real `harnesses.json` with real credentials configured.
+- `npm test` must remain deterministic and offline. Real-provider E2E is opt-in and change-triggered. Its default lane never prompts a root LLM to pick the tool call — it builds an in-process Pi SDK session with a faux, never-streamed root model and calls the `Agent`/`workflow`/`external_runs` tool executors directly, so only the selected external backend's own child (a real spawned CLI process, or, for `pi`, a real in-process nested Pi child) is real: `npm run e2e -- --backend <claude|codex|agy|grok> [--workflow|--interrupt]`, or `npm run e2e -- --backend pi --harness <registered-name> [--workflow|--interrupt]` for a named Pi harness the caller has already registered in their own real `harnesses.json` with real credentials configured. A separate `--routing-smoke` lane spawns a real `pi` CLI process with a real root model and a plain-language instruction to exercise natural-language tool-call routing end to end; it requires real root Pi auth/config and is never the default.
 
 ## Verification and release
 

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to pi-flow external are documented here.
 
 ## Unreleased
 
+## [2.3.0-external.0] - 2026-09-21
+
+Adds `grok` as a fourth external CLI backend, delegating to the official Grok Build CLI alongside Claude Code, Codex CLI, and Antigravity. Investigation notes: `docs/plans/grok-backend-prep.md`; implementation plan: `docs/plans/2026-05-21-grok-cli-implementation.md`; ex-ante design issue: [#51](https://github.com/tranhoangnguyen03/pi-flow-external/issues/51).
+
+### Added
+
+- `grok` backend (`src/core/grok.ts`), verified against Grok Build CLI `1.0.40`, installed and authenticated independently of Pi. Normal runs use `--output-format streaming-messages-json` (a Claude-compatible `assistant`/`result` event envelope); structured output uses `--json-schema` and parses the single terminal document's `structuredOutput` field. Prompts are passed through a temporary `--prompt-file` since Grok does not read stdin. Terminal success requires an observed `result` event affirming `subtype: "success"`, `is_error: false`, and `stop_reason: "end_turn"` — never inferred from exit code or accumulated text alone.
+- Native kernel-sandbox permission tiers: `readonly` (`--sandbox read-only`), `edit` (`--sandbox workspace`), and `danger` (`--sandbox off`), always paired with `--permission-mode bypassPermissions` — bypass only skips the interactive approval prompt; the sandbox remains the real enforced boundary at every tier. `edit` already permits shell execution, so Grok execution-lane roles need no `edit`→`danger` floor. `readonly`'s network-blocking guarantee is Linux-only, and sandbox startup can fail closed on macOS hosts (for example, a symlinked `/var/run/docker.sock`) rather than silently running unsandboxed.
+- `resume` support via Grok's own `--resume <sessionId>` and native cost reporting (`total_cost_usd`); Grok has no budget-enforcement mechanism, so `max_budget_usd` is recorded but unenforceable, and — like codex — failed or aborted runs are never automatically retried (agy's one infra-failure retry exception does not apply to Grok).
+- Default roster migration: a pre-existing installation gains only the six new `grok-*` profiles on its next seed pass (24 default profiles total across four backends), without resurrecting any profile the user previously deleted or customized; a fresh installation seeds all 24 directly.
+- Offline coverage in `test/grok-backend.test.ts` plus extended permission/defaults/spawn/profile/run-inspection regression tests; opt-in real-provider coverage via `npm run e2e -- --backend grok` and `--backend grok --workflow`.
+
+### Fixed
+
+- Overhauled `scripts/e2e/external.mjs`: the default `npm run e2e -- --backend <...> [--workflow|--interrupt]` lane no longer routes tool selection through a real, paid, nondeterministic root Pi LLM. It now builds an in-process Pi SDK session with a faux, never-prompted root model (via the same public SDK/faux-provider patterns `test/helpers/pi-subagent-harness.ts` already uses) and calls the `Agent`/`workflow`/`external_runs` tool executors directly — only the selected external backend's own child (a real spawned CLI process, or, for `--backend pi`, a real in-process nested Pi child) is real. This also fixes two related failures the old design could hit: concurrent direct/workflow runs colliding on a `Date.now()`-only temporary role name (now `randomUUID()`), and an isolated agent directory hiding a real custom root model/auth and surfacing as an unrelated coordinator startup failure (the new default lane never needs a real root model at all). The prior natural-language, real-root-LLM routing check survives unchanged as an explicit, opt-in `--routing-smoke` flag for when role discovery, tool descriptions, or coordinator guidance changes.
+
+## [2.2.0-external.0] - 2026-09-20
+
+### Added
+
+- `external_runs` `inspect` now accepts a bounded `runIds` batch (up to 20, deduplicated, order preserved) returning one consistent normalized summary entry per target — live, durable, agent, or workflow — without waiting for completion.
+- Added a verified `view: "final"` projection that returns only a backend's own canonical terminal answer, separate from combined narration/output; unavailable is a bounded, narration-free empty page (`finalAvailable: false`), never a synthesized sentence.
+- Derived explicit queue/elapsed/activity timing (`queueDelayMs`, `elapsedMs`, `activityAgeMs`, `processDurationMs`) from existing evidence, computed only where the underlying timestamps genuinely exist; a registry-confirmed-live run is required before now-relative durations are computed, so an orphaned/crashed durable record is never misreported as actively running.
+- `/external runs` list rows now show status, queue/elapsed duration, live activity age, and output/final availability, plus a manual `Refresh` choice that re-reads the current page and resets stale cursors.
+
+### Fixed
+
+- Recorded an explicit `execution_started` evidence boundary (direct `Agent` calls and workflow `agent()` calls) so durable status classification and timing no longer depend solely on `processStartedAt`, which never exists for in-process Pi children.
+- A workflow child's own registry entry now transitions `queued` → `running` explicitly at limiter-acquisition time, instead of only incidentally once its backend's first progress event fires.
+- Settled `outcome.status` now wins over a possibly-stale ambient `observation.status` once a run has terminated.
+- An unresolvable `wf_...` ID now rejects consistently as unknown/unavailable across `inspect`, `cancel`, `wait`, and batch `inspect`, instead of falling through to the agent-only durable reader.
+
 ## [2.1.0-external.3] - 2026-09-18
 
 ### Fixed

package/CONTEXT.md

@@ -4,7 +4,7 @@ This package is a fork of pi-flow whose `Agent` and `workflow` tools are reserve
 
 ## Domain language
 
-- **External profile:** A markdown file under `~/.pi/agent/subagents/*.md` whose filename and frontmatter select `backend: claude`, `backend: codex`, `backend: agy`, or (only alongside a registered `harness:`) `backend: pi`.
+- **External profile:** A markdown file under `~/.pi/agent/subagents/*.md` whose filename and frontmatter select `backend: claude`, `backend: codex`, `backend: agy`, `backend: grok`, or (only alongside a registered `harness:`) `backend: pi`.
 - **Native Pi subagent:** A subagent exposed by Pi's native subagent system. This fork intentionally does not route it through `Agent`.
 - **Agent call:** A direct external delegation selected by `role` and optional `harness` (an external CLI or a registered named Pi harness), or by legacy exact-profile `subagent_type`.
 - **Named Pi harness configuration:** A `pi-<label>` entry in `harnesses.json` pinning a `provider/model` id and a thinking level, run in-process via Pi's own SDK rather than as a spawned CLI. `harness` selects *which* configuration; `backend` (always the literal `"pi"` for these) selects the execution mechanism. The six default roles are synthesized automatically for every registered pi harness from the same canonical source the three CLI backends' default files already come from.
@@ -24,7 +24,7 @@ This package is a fork of pi-flow whose `Agent` and `workflow` tools are reserve
 ## Routing rule
 
 - Native Pi work -> native subagent tool.
-- Claude Code / Codex CLI / Antigravity work, and named Pi harness work -> this extension's `Agent` or `workflow`.
+- Claude Code / Codex CLI / Antigravity / Grok Build CLI work, and named Pi harness work -> this extension's `Agent` or `workflow`.
 
 The split is global and intentional to avoid tool ambiguity across projects. The ordinary driver sees `Agent`, optional `workflow`, and read-only `external_help`; the profile finalizer is activated only by `/external profile create`. External children start in the requested working directory, but backend-native nested helpers may create or use a separate workspace; prompts that request further nesting should include explicit absolute paths and all required context. Named Pi harness children are the one exception to "backend-native nested helpers may use a different workspace": a pi child runs in-process with no extensions, skills, prompts, or themes loaded, so it structurally cannot itself launch a further nested agent.
 
@@ -32,7 +32,7 @@ The split is global and intentional to avoid tool ambiguity across projects. The
 
 User operations are namespaced under `/external`: status, Doctor, settings, profiles, profile creation, workflows, interactive run navigation, durable run summary/pruning, and help. `/external runs` uses the same registry/readers as `external_runs`, including every cursor-paged workflow child and output/diagnostic page. Extension-owned concurrency, timeout, and global default-harness settings live in `$PI_CODING_AGENT_DIR/pi-flow-external/settings.json`; profiles remain authoritative for downstream backend/model/thinking metadata. Named Pi harness configurations live in the sibling `pi-flow-external/harnesses.json` registry. A trusted project may override only `defaultHarness`, which may itself name a registered `pi-*` harness.
 
-> Next agent: full implementation map is `docs/ARCHITECTURE_SNAPSHOT.md` (verified 2026-09-16). Keep this file and `AGENTS.md` as the persistent breadcrumbs.
+> Next agent: full implementation map is `docs/ARCHITECTURE_SNAPSHOT.md` (verified 2026-09-21). Keep this file and `AGENTS.md` as the persistent breadcrumbs.
 
 ## Design stance
 
@@ -48,10 +48,12 @@ Applied to Antigravity (`agy`), that stance is absolute: the harness offers no g
 
 Applied to named Pi harness configurations, the same "get out of the way" stance takes a different, honestly-scoped shape: a curated, builtins-only tool surface (no project/user extensions, skills, prompts, or themes) genuinely bounds which tool *names* a pi child can reach — that claim is mechanically true because nothing else loads — but it is not a claim that `bash` at `danger` tier is any less dangerous than on an external CLI once it is granted. `readonly`/`edit` tiers get a real default tool allow-list (`read`/`grep`/`find`/`ls`, plus `edit`/`write` at `edit`) so those tiers are actually usable, not just technically restrictive. Execution-lane roles requested at `edit` are still elevated to `danger` (the same floor as Claude), because `edit` excludes `bash` entirely and an execution lane without shell access cannot do its job.
 
+Applied to the Grok Build CLI, permission tiers map onto its own kernel-enforced `--sandbox` axis (`read-only`/`workspace`/`off`), always paired with `--permission-mode bypassPermissions` — bypass only removes the interactive approval prompt, never the sandbox itself, so every tier is a genuine boundary rather than an advisory one. `edit` already permits shell execution (sandboxed to workspace writes), so, unlike Claude and pi, Grok execution-lane roles need no `edit`→`danger` floor. `readonly`'s network-blocking guarantee is Linux-only, and sandbox startup can fail closed on some macOS hosts rather than silently running unsandboxed; that fail-closed behavior is preserved rather than weakened for cross-platform convenience.
+
 ## Known inelegance
 
-<!-- ponytail: one-backend-per-file profile format forces role x backend file duplication; extend src/profiles.ts with multi-backend profiles (e.g. backends: [claude, codex, agy] plus per-backend model map) if maintaining N copies of identical role bodies ever hurts -->
-A standardized role roster needs one file per role per backend (e.g. `claude-qa`, `codex-qa`, `agy-qa` with identical bodies) because the profile format binds `backend:` and `model:` to a single file. The duplication is accepted for now; a future format extension could let one role file cover all backends. Named Pi harnesses partially resolve this for the six canonical roles specifically (synthesized once from a single shared source, applied identically to every registered `pi-*` config, with zero files written) — but a *custom* role outside the six still needs one file per pi harness, exactly like the three CLI backends; a user with several registered pi harnesses wanting the same custom role on all of them still duplicates one file per harness. The same applies to `permission:` tiers: one tier per profile, but backends interpret tiers differently (Claude and pi deny Bash at anything below `danger`), so command-running roles declare `danger` and maintain `danger` as their floor even if an explicit `edit` override is requested. Custom profiles outside the role-name convention get that floor only by declaring `permission: danger`; an undeclared custom profile that meets an `edit` tier still hits headless Bash denials (or, on pi, a curated tool set without `bash`), so `permission: danger` doubles as the lane's "needs shell" capability declaration. Named Pi harnesses also ship with no resume and no enforced budget cap in v1 — both deliberate limitations, tracked alongside the shared-custom-role gap in issue #43, not oversights.
+<!-- ponytail: one-backend-per-file profile format forces role x backend file duplication; extend src/profiles.ts with multi-backend profiles (e.g. backends: [claude, codex, agy, grok] plus per-backend model map) if maintaining N copies of identical role bodies ever hurts -->
+A standardized role roster needs one file per role per backend (e.g. `claude-qa`, `codex-qa`, `agy-qa`, `grok-qa` with identical bodies) because the profile format binds `backend:` and `model:` to a single file. The duplication is accepted for now; a future format extension could let one role file cover all backends. Named Pi harnesses partially resolve this for the six canonical roles specifically (synthesized once from a single shared source, applied identically to every registered `pi-*` config, with zero files written) — but a *custom* role outside the six still needs one file per pi harness, exactly like the four CLI backends; a user with several registered pi harnesses wanting the same custom role on all of them still duplicates one file per harness. The same applies to `permission:` tiers: one tier per profile, but backends interpret tiers differently (Claude and pi deny Bash at anything below `danger`), so command-running roles declare `danger` and maintain `danger` as their floor even if an explicit `edit` override is requested. Custom profiles outside the role-name convention get that floor only by declaring `permission: danger`; an undeclared custom profile that meets an `edit` tier still hits headless Bash denials (or, on pi, a curated tool set without `bash`), so `permission: danger` doubles as the lane's "needs shell" capability declaration. Named Pi harnesses also ship with no resume and no enforced budget cap in v1 — both deliberate limitations, tracked alongside the shared-custom-role gap in issue #43, not oversights.
 
 ## Evidence boundary
 

package/README.md

@@ -5,6 +5,7 @@ External agent delegation for [pi](https://github.com/earendil-works/pi) through
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) profiles with `backend: claude`
 - [Codex CLI](https://github.com/openai/codex) profiles with `backend: codex`
 - Antigravity profiles with `backend: agy`
+- [Grok Build CLI](https://github.com/xai-org/grok-build) profiles with `backend: grok`
 - Named Pi harness configurations (`pi-<label>`) — in-process, per-model configs you register yourself, not a spawned CLI
 
 The ordinary driver has four tools (`workflow` can be disabled):
@@ -14,7 +15,7 @@ The ordinary driver has four tools (`workflow` can be disabled):
 - `external_help` returns role details, permission behavior, or workflow guidance on demand.
 - `external_runs` lists, inspects, waits for, and cancels session-owned runs.
 
-`Agent` and `workflow` accept external roles with an optional harness override — one of the three CLIs, or a registered named Pi harness. Use pi's native subagent system for Pi-backed agents. The `pi_flow_profile_create` and `pi_flow_harness_create` finalizers are active only during `/external profile create`.
+`Agent` and `workflow` accept external roles with an optional harness override — one of the four CLIs, or a registered named Pi harness. Use pi's native subagent system for Pi-backed agents. The `pi_flow_profile_create` and `pi_flow_harness_create` finalizers are active only during `/external profile create`.
 
 ## Install
 
@@ -48,18 +49,20 @@ Install and authenticate each external CLI you intend to use:
 claude --version
 codex --version
 agy --version
+grok --version
 ```
 
-Pi's coordinator model and the external CLIs authenticate independently. A working Claude, Codex, or Antigravity login does not authenticate the root Pi model.
+Pi's coordinator model and the external CLIs authenticate independently. A working Claude, Codex, Antigravity, or Grok login does not authenticate the root Pi model. The Grok Build CLI installs and authenticates entirely separately from Pi: install with `curl -fsSL https://x.ai/cli/install.sh | bash`, then authenticate with `grok login` or an `XAI_API_KEY` environment variable. This integration is verified against Grok Build CLI `1.0.40`.
 
 External agents use the effective permission tier and each harness's native mechanism:
 
 - Claude: `--permission-mode plan`, `--permission-mode acceptEdits`, or `--dangerously-skip-permissions`
 - Codex: `--sandbox read-only`, `workspace-write`, or `danger-full-access`
 - Antigravity: always `--dangerously-skip-permissions`
+- Grok: `--sandbox read-only`, `workspace`, or `off`, always alongside `--permission-mode bypassPermissions` — bypass only skips the interactive approval prompt; the kernel sandbox remains the enforced boundary. `readonly`'s network-blocking guarantee is Linux-only (a no-op on macOS), and sandbox startup can fail closed on some macOS hosts (for example when `/var/run/docker.sock` resolves to a symlink) rather than silently running unsandboxed.
 - Named Pi harnesses: a curated `tools:` allow-list (`read`/`grep`/`find`/`ls` at `readonly`; those plus `edit`/`write` at `edit`), or the SDK's own default active tools (`read`/`bash`/`edit`/`write`) at `danger`
 
-Claude refuses bypass mode when its effective UID is `0`; in that case the extension uses `--permission-mode auto`. External execution lanes (like `implementer`, `qa`, and `worker`) require shell execution to inspect repositories, run tests, and verify code. On Claude Code and named Pi harnesses, headless/`edit`-tier access excludes shell entirely; therefore, execution lanes maintain a `danger` floor so the model is not artificially handcuffed by permission blocks. Run external agents only in repositories you trust and state whether each task is read-only or may edit files.
+Claude refuses bypass mode when its effective UID is `0`; in that case the extension uses `--permission-mode auto`. External execution lanes (like `implementer`, `qa`, and `worker`) require shell execution to inspect repositories, run tests, and verify code. On Claude Code and named Pi harnesses, headless/`edit`-tier access excludes shell entirely; therefore, execution lanes maintain a `danger` floor so the model is not artificially handcuffed by permission blocks. Grok needs no such floor: its `edit` tier (`--sandbox workspace`) already permits shell execution, sandboxed to writes within the workspace. Run external agents only in repositories you trust and state whether each task is read-only or may edit files.
 
 The TUI labels a direct run with its effective access, including `unsandboxed external CLI` for danger and all Agy runs, `Pi SDK child · host access · curated tools` for a danger-tier named Pi harness, and shows `external host access` while workflow work is active. These labels disclose actual execution authority; they do not turn a read-only prompt into an enforced permission boundary.
 
@@ -113,7 +116,7 @@ Profiles live in:
 ~/.pi/agent/subagents/<name>.md
 ```
 
-Names may contain lowercase letters, numbers, and hyphens. A profile must declare `backend: claude`, `backend: codex`, `backend: agy`, or (alongside `harness: <a registered pi-* name>`) `backend: pi`, and its name should start with the matching harness name.
+Names may contain lowercase letters, numbers, and hyphens. A profile must declare `backend: claude`, `backend: codex`, `backend: agy`, `backend: grok`, or (alongside `harness: <a registered pi-* name>`) `backend: pi`, and its name should start with the matching harness name.
 
 Example Claude profile, `~/.pi/agent/subagents/claude-explorer.md`:
 
@@ -140,11 +143,16 @@ backend: agy
 model: gemini-3.7-flash-high
 ```
 
+```yaml
+backend: grok
+model: grok-4.6
+```
+
 Profile instructions become the external agent's system instructions. A profile's `description` is also shown as the user-visible reason for its selection, so keep it concise and concrete. External CLIs use their own tools, so a profile's `tools:` field does not control them; a pi profile's `tools:` field does apply, intersected with its permission tier's curated tool table. A `backend: pi` profile is only available to this extension when it also declares `harness: <name>` for a name registered in `harnesses.json` (see below); a bare `backend: pi` profile, or no backend at all, belongs to Pi's native subagent system and is never modified by this extension.
 
 ### Default profiles
 
-On first session start the extension seeds a default roster — five code-oriented roles (explorer, planner, implementer, reviewer, qa) plus the generalist worker — as one storage profile per backend (18 files). The compact agent catalog advertises each role once rather than presenting 18 choices. Seeding happens once: it never overwrites existing files, and profiles you delete or customize afterwards stay that way. Default profiles leave `model` and `thinking` unpinned so they track the CLI's own model and the current Pi thinking level. Roles not in the default roster can be added with `/external profile create`.
+On first session start the extension seeds a default roster — five code-oriented roles (explorer, planner, implementer, reviewer, qa) plus the generalist worker — as one storage profile per backend across four backends (24 files). The compact agent catalog advertises each role once rather than presenting 24 choices. Seeding happens once: it never overwrites existing files, and profiles you delete or customize afterwards stay that way. Default profiles leave `model` and `thinking` unpinned so they track the CLI's own model and the current Pi thinking level. Roles not in the default roster can be added with `/external profile create`. An installation seeded before Grok support existed gains only the six new `grok-*` profiles the next time it seeds, without resurrecting any claude/codex/agy profile you previously deleted or customized.
 
 Project-local profiles are not supported; global profiles are used for both global and project-only package installations.
 
@@ -176,7 +184,7 @@ Agent({
 });
 ```
 
-A custom (non-canonical) role still needs its own profile file per harness, the same as for the three CLI backends: `~/.pi/agent/subagents/pi-deepseek-security-reviewer.md` with `backend: pi` and `harness: pi-deepseek`. That file's body/permission/tools may be customized; its `model`/`thinking` are not — they always come from the harness's registered config, and a file that tries to override them to a different value is rejected rather than silently honored.
+A custom (non-canonical) role still needs its own profile file per harness, the same as for the four CLI backends: `~/.pi/agent/subagents/pi-deepseek-security-reviewer.md` with `backend: pi` and `harness: pi-deepseek`. That file's body/permission/tools may be customized; its `model`/`thinking` are not — they always come from the harness's registered config, and a file that tries to override them to a different value is rejected rather than silently honored.
 
 **v1 scope, by design:** a pi child's entire tool surface is the SDK's own builtins (`read`/`bash`/`edit`/`write`, plus `grep`/`find`/`ls` at `readonly`/`edit` tiers) — no project/user extensions, skills, prompt templates, or themes load into it. This bounds which tool *names* exist; it does not make `bash` at `danger` tier any less exposed than on an external CLI. Retry is disabled per pi child (in-memory, never touching your real Pi settings) so a transient provider error fails immediately rather than silently retrying. Pi children cannot resume a prior conversation and have no enforced budget cap. Expanding this capability set (trusted extensions/MCP/skills, a shared custom-role format, resumable sessions, real budget controls) is tracked in [issue #43](https://github.com/tranhoangnguyen03/pi-flow-external/issues/43).
 
@@ -266,13 +274,39 @@ Agent({
 
 Use `external_runs` with these actions:
 
-- `list`: current session/project runs; use `cursor` for run pages and `workflowCursor` for workflow pages. `workflowRunId` filters children of one workflow.
-- `inspect`: `runId`, `view: "summary" | "output" | "diagnostics"`, and optional opaque `cursor`/`limitBytes`. Follow `nextCursor` to avoid truncation.
+- `list`: current session/project runs; use `cursor` for run pages and `workflowCursor` for workflow pages. `workflowRunId` filters children of one workflow. Rows carry a `timing` projection (`queueDelayMs`, `elapsedMs`, `activityAgeMs` when live, `processDurationMs`) plus `outputAvailable`/`finalAvailable`.
+- `inspect`: single `runId` with `view: "summary" | "output" | "diagnostics" | "final"`, and optional opaque `cursor`/`limitBytes` (max 64 KiB, same cap for every view). Follow `nextCursor` to avoid truncation. `summary` includes the same `timing` projection as `list`, plus `output.finalAvailable`. `final` returns only the verified canonical terminal answer — empty with `finalAvailable: false` until a successful terminal boundary exists; it never promotes partial/narration text. `output` stays the combined stream (assistant messages plus canonical result) and is unchanged.
+- `inspect` with `runIds` instead of `runId` (up to 20, deduplicated, order preserved): a single bounded batch of `summary`-only projections — one cheap request to see whether several selected background children are queued, running, or terminal, each with `outputRef`/`diagnosticsRef` for follow-up detail. Ownership of every requested ID is validated before any page is returned. Reuses the same `limitBytes` cap as single-run inspection; pages contain whole target entries and continue through `nextCursor`, without invalidation from ordinary live progress. If one compact entry cannot fit, an actionable error asks you to increase `limitBytes` or inspect that run individually; no target is silently dropped. `runId` and `runIds` are mutually exclusive, and batch `view` must stay `summary`.
 - `wait`: one `runId` or selected `runIds`, with `mode: "any" | "all"`. It returns terminal outcomes plus still-pending IDs; an unsuccessful workflow returns early even in `all` mode. It never chooses a winner or cancels pending work.
 - `cancel`: one `runId` and optional reason. Whole-workflow cancellation stops active children; targeted child cancellation remains a catchable workflow outcome. Cancellation does not roll back edits or other side effects.
 
 Interrupting a blocking `Agent`/`workflow` call cancels its work. Interrupting `external_runs wait` stops only that wait. Background work survives its launching tool return and ordinary parent turns, but not the owning session: orderly session shutdown requests cancellation and waits for bounded cleanup. This is not a daemon. After a host crash or unconfirmed shutdown, unfinished evidence is `interrupted_or_uncertain`; restart restores evidence access, never live ownership or guaranteed retrospective process termination. No routine activity wakes the parent, and live steering is not supported.
 
+A parent's own `sleep`/wait duration (or its process lifetime) is not a measurement of, and does not bound, how long a delegated command actually takes to run — a background child keeps running under the session's ownership regardless of what the parent does next. A realistic collection shape:
+
+```ts
+// Launch two independent background runs.
+const one = Agent({ description: "Audit auth module", prompt: "Audit /absolute/repo/auth read-only.", role: "reviewer", background: true }); // -> run_...
+const two = Agent({ description: "Audit billing module", prompt: "Audit /absolute/repo/billing read-only.", role: "reviewer", background: true }); // -> run_...
+
+// Optional: give both a head start before doing anything else. This sleep
+// bounds nothing about the children's own runtime — it is just the parent
+// choosing when to next check in, not a deadline or a proxy for command time.
+// sleep(30_000)
+
+// Do unrelated parent work here (read files, answer the user, plan next steps)
+// while both children continue running under the session, not the parent turn.
+
+// Check on both at once, without waiting for either to finish:
+// external_runs({ action: "inspect", runIds: [one.runId, two.runId] })
+
+// Leave them running and come back later in the conversation (or after
+// further parent work) to collect final output once each is actually done:
+// external_runs({ action: "inspect", runId: one.runId, view: "final" })
+```
+
+A task that sounds like a 30-second command can legitimately take substantially longer end-to-end once queueing and backend overhead are included — inspect and wait, do not assume.
+
 ## Workflow usage
 
 The `workflow` tool runs trusted JavaScript that calls one or more external roles and returns a JSON-serializable result. Workflows are for explicit fan-out — and for the case this extension was built to make explicit: running several children on the **same** harness at once. Example:
@@ -306,8 +340,8 @@ Every child selects from one parent snapshot and effective settings frozen at wo
 Every `Agent` call and workflow `agent()` child also accepts these optional run parameters (`context` is covered under agent usage above):
 
 - `permission`: `readonly` | `edit` | `danger` (default `danger`). Tiers map onto native harness mechanisms — Claude permission modes and Codex's single-axis `--sandbox`. Antigravity (`agy`) is different: its headless sandbox denies even read-only tools like `read_url_content`, and its only unsandboxed mode is `--dangerously-skip-permissions`, so **every agy run is unsandboxed** and `readonly`/`edit` on agy are advisory profile-body instructions, not a boundary. Getting out of the model's way is deliberate; every agy run discloses as `unsandboxed external CLI` rather than claiming a read-only boundary it cannot keep. Claude `readonly`/`edit` runs auto-deny shell commands headlessly; denials are surfaced in the receipt.
-- `max_budget_usd`: a spending cap. Claude Code enforces it mid-run with its native `--max-budget-usd` flag; codex and agy do not report cost, so the cap is recorded and marked `budget unenforceable` instead of pretended.
-- `resume`: a prior run id. Continues the same backend conversation (Claude `--resume`, Codex `exec resume`, agy `--conversation`) instead of starting from scratch. The prior run must use the same backend. Claude sessions persist in Claude Code's own local storage (this extension no longer passes `--no-session-persistence`) so recorded session ids stay resumable; remove old conversations from Claude Code itself if that matters to you. `resume` cannot be combined with `context` sharing — continue an existing child, or start a new one with a snapshot.
+- `max_budget_usd`: a spending cap. Claude Code enforces it mid-run with its native `--max-budget-usd` flag. Codex estimates cost from a price map and agy does not report cost at all; Grok reports its own native cost (`total_cost_usd`) but exposes no enforcement flag. For codex, agy, and grok alike, the cap is recorded and marked `budget unenforceable` instead of pretended.
+- `resume`: a prior run id. Continues the same backend conversation (Claude `--resume`, Codex `exec resume`, agy `--conversation`, Grok `--resume`) instead of starting from scratch. The prior run must use the same backend. Claude sessions persist in Claude Code's own local storage (this extension no longer passes `--no-session-persistence`) so recorded session ids stay resumable; remove old conversations from Claude Code itself if that matters to you. `resume` cannot be combined with `context` sharing — continue an existing child, or start a new one with a snapshot.
 
 Resolution order for tiers and budgets: call > profile frontmatter (`permission:`, `max_budget_usd:`) > settings defaults.
 
@@ -407,21 +441,29 @@ Run the deterministic offline checks:
 npm run check
 ```
 
-Real-provider checks consume tokens. Point the runner at the authenticated Pi agent directory:
+Real-provider checks consume tokens, but the default lane never prompts a root LLM to choose the tool call: it builds an in-process Pi SDK session with a faux, never-streamed root model and calls the `Agent`/`workflow`/`external_runs` tool executors directly, so only the selected external backend's own child (a real spawned CLI process, or, for `--backend pi`, a real in-process nested Pi child) is real:
 
 ```bash
-export PI_CODING_AGENT_DIR="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
 npm run e2e -- --backend claude
 npm run e2e -- --backend codex
 npm run e2e -- --backend agy
+npm run e2e -- --backend grok
 npm run e2e -- --backend claude --workflow
 npm run e2e -- --backend codex --workflow
 npm run e2e -- --backend agy --workflow
+npm run e2e -- --backend grok --workflow
 npm run e2e -- --backend pi --harness pi-deepseek
 npm run e2e -- --backend pi --harness pi-deepseek --workflow
 ```
 
-The `pi` backend requires a harness you have already registered yourself in your real `harnesses.json` with real credentials configured; the script never registers or pays for one on your behalf.
+The `pi` backend requires a harness you have already registered yourself in your real `harnesses.json` with real credentials configured; the script never registers, writes to, or pays for one on your behalf. `--interrupt` cancels a backgrounded `Agent` through `external_runs` instead of `--workflow`'s two-child check.
+
+A separate, explicit `--routing-smoke` lane spawns a real `pi` CLI process with a real root model and asks it, in plain language, to pick the right tool — useful only when role discovery, tool descriptions, or coordinator guidance changes, and never the default:
+
+```bash
+export PI_CODING_AGENT_DIR="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
+npm run e2e -- --routing-smoke --backend codex
+```
 
 See [`docs/field-testing.md`](docs/field-testing.md) for provider checks and [`docs/releasing.md`](docs/releasing.md) for the release process.
 

package/docs/field-testing.md

@@ -2,16 +2,24 @@
 
 Real-provider checks consume tokens and normally run external CLIs in dangerous/no-approval modes. Claude uses `auto` permission mode instead when its effective UID is 0. Use them only in a trusted checkout. Receipts can contain prompts and source excerpts despite best-effort redaction.
 
+`npm run e2e` has two lanes. The default lane is deterministic and root-model-free: it builds an in-process Pi SDK session with a faux, never-prompted root model and calls the `Agent`/`workflow`/`external_runs` tool executors directly, so tool selection is never left to a live LLM decision — only the selected external backend's own child call (a real spawned CLI process, or, for `--backend pi`, a real in-process nested Pi child) is real. `--routing-smoke` is a separate, explicit lane that spawns a real `pi` CLI process with a real root model and asks it, in plain language, to pick the right tool; see [Natural-language routing smoke](#natural-language-routing-smoke) below. Only `--routing-smoke` needs root Pi authentication or `--root-model`/`--root-thinking`.
+
 ## Preparation
 
 ```bash
 cd /path/to/pi-flow-external
-export PI_CODING_AGENT_DIR="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
-export ROOT_MODEL="openai-codex/gpt-5.6-sol"
-pi auth check --model "$ROOT_MODEL" --json
 claude --version
 codex --version
 agy --version
+grok --version
+```
+
+The default lane needs no root Pi authentication at all (its root model is a faux, never-prompted placeholder). Only `--routing-smoke` needs a working root model:
+
+```bash
+export PI_CODING_AGENT_DIR="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
+export ROOT_MODEL="openai-codex/gpt-5.6-sol"
+pi auth check --model "$ROOT_MODEL" --json
 ```
 
 Root Pi authentication is separate from each delegated CLI.
@@ -24,20 +32,23 @@ Run only the backend affected during development:
 npm run e2e -- --backend claude
 npm run e2e -- --backend codex
 npm run e2e -- --backend agy
+npm run e2e -- --backend grok
 ```
 
-Each run creates a collision-safe temporary profile and fixture, delegates once, requires the expected token, checks for one complete `done` receipt, verifies that the fixture stayed clean, and removes its temporary files.
+Each run creates a collision-safe (`randomUUID`-named) temporary profile and fixture in an isolated agent directory, calls the `Agent` tool executor directly with an explicit `role`/`harness`, requires the exact expected result in the child's real result, checks for one complete `done` receipt, verifies that the fixture stayed clean, and removes its temporary files. Isolation is unconditional: for every backend above, an inherited `PI_CODING_AGENT_DIR` (such as the one exported in [Preparation](#preparation)) is ignored unless you pass `--agent-dir` explicitly — only `--backend pi` and `--routing-smoke` ever default to your real agent directory, since they only read it and never write into it.
 
 Defaults:
 
 | Lane | Model | Thinking |
 |---|---|---|
-| Root Pi | `openai-codex/gpt-5.6-sol` | `high` |
 | Claude | `claude-sonnet-5` | `high` |
 | Codex | `gpt-5.6-sol` | `high` |
 | Agy | `gemini-3.7-flash-high` | `high` |
+| Grok | `grok-4.6` | `high` |
 
-Override with `--model`, `--thinking`, `--root-model`, or `--root-thinking`. Use `--keep` only when evidence inspection is necessary; it preserves sensitive output and the temporary profile path printed by the runner.
+Override with `--model`/`--thinking`. Use `--keep` only when evidence inspection is necessary; it preserves sensitive output and the temporary profile path printed by the runner.
+
+Grok's `readonly`/`edit` tiers run under its own kernel sandbox (`--sandbox read-only`/`workspace`). On a macOS host where `/var/run/docker.sock` resolves to a symlink, sandbox startup can fail closed before the child even runs the prompt — that is expected fail-closed behavior, not a bug; verify enforcement on Linux, or adjust the host's Docker socket if you need to reproduce it locally on macOS.
 
 ### Named Pi harness receipt
 
@@ -47,7 +58,7 @@ Run only when the pi runtime contract (§7 of the design), harness registry, or
 npm run e2e -- --backend pi --harness pi-deepseek
 ```
 
-This lane never registers a harness or writes a temporary profile — canonical synthesis already provides the `worker` role for any registered harness — it only delegates to the harness you name and requires the same one complete `done` receipt.
+This lane reads your real agent directory (harnesses.json, subagents) but never writes a temporary profile there — canonical synthesis already provides the `worker` role for any registered harness — and never mutates it: the faux root model is registered only in-process, and the harness's own real model/auth resolve normally through your real `models.json`/`auth.json`. It delegates to the harness you name and requires the same one complete `done` receipt.
 
 ## Supervised workflow receipt
 
@@ -57,10 +68,11 @@ When workflow runtime, scheduling, supervision, or tool integration changes, run
 npm run e2e -- --backend claude --workflow
 npm run e2e -- --backend codex --workflow
 npm run e2e -- --backend agy --workflow
+npm run e2e -- --backend grok --workflow
 npm run e2e -- --backend pi --harness pi-deepseek --workflow
 ```
 
-Each command declares `meta.apiVersion: 1`, starts a two-child workflow with `background: true`, waits for the selected workflow through `external_runs`, inspects its summary/output, requires two complete child receipts, and verifies the read-only fixture stayed clean. Forced multi-page cursor behavior remains covered by deterministic offline tests; this check exercises real workflow child handling without duplicating those semantics.
+Each command calls the `workflow` tool executor directly with a script declaring `meta.apiVersion: 1` and running two parallel `agent()` calls, blocking (`background: false`) rather than supervised through `external_runs` — workflow execution itself is what's under test here, not run-observability ceremony (the change-triggered background-run observability check below covers that separately). It requires the workflow to complete with two `done` child receipts, both results containing the expected token, and the read-only fixture staying clean.
 
 ## Change-triggered interruption and output check
 
@@ -70,15 +82,19 @@ When adapter cancellation, process-tree termination, partial output, or supervis
 npm run e2e -- --backend claude --interrupt
 npm run e2e -- --backend codex --interrupt
 npm run e2e -- --backend agy --interrupt
+npm run e2e -- --backend grok --interrupt
 ```
 
-The runner starts a background `Agent`, cancels its stable ID with an explicit reason, waits for its `cancelled` outcome, and asks `external_runs` for every available output and diagnostic page. A very early cancellation may legitimately have diagnostics but no assistant text; the durable receipt must still be `aborted`/`cancelled` with the exact reason. Do not retry a failure automatically. Use `--keep` for one deliberate evidence inspection, then remove the printed run root and temporary profile.
+The runner calls the `Agent` tool executor directly with `background: true`, polls `external_runs` until the run is observed `running`, cancels its stable ID with an explicit reason, waits for its `cancelled` outcome, and asks `external_runs` for every available output and diagnostic page. A very early cancellation may legitimately have diagnostics but no assistant text; the durable receipt must still be `aborted` with the exact reason. Do not retry a failure automatically. Use `--keep` for one deliberate evidence inspection, then remove the printed run root and temporary profile.
 
 ## Natural-language routing smoke
 
-When role discovery, tool descriptions, or coordinator guidance changes, run three fresh Pi sessions against the current checkout and a read-only fixture. Ask for two named harnesses to review, two named harnesses to research, and a task split between Pi plus two named harnesses. For each session, verify that each requested external harness produced one complete `done` receipt through `role` plus `harness`, no help/discovery call was needed for the built-in roles, and the fixture stayed unchanged.
+There are two levels of routing check:
+
+- `npm run e2e -- --routing-smoke --backend <claude|codex|agy|grok>` (optionally `--workflow`/`--interrupt`) spawns a real `pi` CLI process with a real root model and gives it a single plain-language instruction naming the exact tool, role, and harness to call. It is a mechanical, automated check that the natural-language call-and-relay path (real root LLM → real tool call → real backend child) still works end to end. It requires real root Pi authentication (see Preparation) and is opt-in only — never the default backend gate — because the root model's tool-call decision is a live, provider-billed, non-deterministic step. `--root-model`/`--root-thinking` only apply here.
+- The broader, still-manual qualitative check below covers *discovery*, not just one named call: when role discovery, tool descriptions, or coordinator guidance changes, run three fresh Pi sessions against the current checkout and a read-only fixture. Ask for two named harnesses to review, two named harnesses to research, and a task split between Pi plus two named harnesses. For each session, verify that each requested external harness produced one complete `done` receipt through `role` plus `harness`, no help/discovery call was needed for the built-in roles, and the fixture stayed unchanged.
 
-This is a qualitative trigger smoke, not a statistical regression comparison or a model-independent guarantee. It does not cover workflow routing or the omitted-`harness` default; use the workflow receipt above and a separate direct role request without `harness` for those paths.
+Neither is a statistical regression comparison or a model-independent guarantee. Neither covers workflow routing or the omitted-`harness` default; use the workflow receipt above and a separate direct role request without `harness` for those paths.
 
 ## Change-triggered nested timeout check
 
@@ -105,6 +121,17 @@ Local fixture tests own selection, boundary, and failure behavior; this check on
 
 Do not run damaged-record and expected-failure provider scenarios manually. Their behavior is deterministic and belongs in the local fixture tests.
 
+## Change-triggered background-run observability check
+
+Run only when batch inspection, the `final` view, timing projection, or `/external runs` browsing changes. In one fresh Pi session against a read-only fixture:
+
+1. Launch two independent `Agent({ ..., background: true })` calls back to back (do not wait on either), then do one unrelated piece of parent work (e.g. read a file) before checking on them — this exercises the actually-recommended usage shape (separate launches, other work in between), not a tight launch-then-immediately-inspect loop.
+2. Call `external_runs({ action: "inspect", runIds: [<first>, <second>] })` once and confirm both come back as one bounded batch of `summary` projections (queued/running/terminal, `outputRef`/`diagnosticsRef` per entry) without waiting for either to finish.
+3. After both children are confirmed terminal (`external_runs wait` or a later `inspect`), call `external_runs({ action: "inspect", runId: <runId>, view: "final" })` for a completed run and confirm it returns only the verified canonical answer; for a run cancelled mid-flight (or inspected before it settles), confirm the tool response reports `finalAvailable: false` with a deliberately empty, bounded projection (`items: []`, `integrity: "incomplete"`) rather than a fabricated success — this empty shape is correct at the tool layer, not a bug. The human-readable explanation ("No verified final answer is available yet for `<runId>`.") is a separate, UI-only notice that `/external runs` shows when Final is selected on an unsettled run; the tool response itself stays narration-free by design.
+4. Run `/external runs`, open the list, and manually select `Refresh`: confirm it re-reads the first page and resets any list cursor without navigating into a run or waiting/polling. Select a still-running row and confirm its queue/elapsed timing and final-availability marker are present and update only when you refresh again (never on a timer).
+
+Local fixture tests already cover batch pagination/cursor/byte-limit edge cases, the `final` view's success/unavailable/legitimate-null shapes, and `Refresh`'s cursor-reset behavior deterministically; this check only proves the real backend/registry timing (queued→running, activity age, terminal settlement) matches what those fixtures assume.
+
 ## Change-triggered project default-harness check
 
 Run only when project default-harness resolution changes. In a fresh Pi session against a trusted read-only fixture containing `.pi/pi-flow-external/settings.json` with `"defaultHarness": "claude"`, verify `/external settings` reports `defaultHarness: claude (project: ...)`, delegate one read-only task with `role` only (no `harness`) and verify the receipt names a `claude-*` profile, then confirm an explicit `harness: "codex"` call still routes to codex. Repeat once in the same fixture with trust removed and confirm the override is ignored with a warning.
@@ -114,9 +141,10 @@ Run only when project default-harness resolution changes. In a fresh Pi session
 Before a runtime release:
 
 1. Run `npm run check`.
-2. Run all three direct backend receipts.
-3. Run all three supervised workflow receipts.
+2. Run all four direct backend receipts.
+3. Run all four supervised workflow receipts.
 4. Run interruption checks for adapters whose cancellation/output path changed.
-5. Run the natural-language routing smoke only if role discovery, tool descriptions, or coordinator guidance changed.
+5. Run `--routing-smoke` (mechanical) and the manual qualitative routing smoke only if role discovery, tool descriptions, or coordinator guidance changed.
 6. Run the nested timeout check only if nested detection or timeout behavior changed.
-7. Remove temporary evidence and profiles.
+7. Run the background-run observability check only if batch inspection, the `final` view, timing projection, or `/external runs` browsing changed.
+8. Remove temporary evidence and profiles.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tranhoangnguyen0310/pi-flow-external",
-  "version": "2.1.0-external.3",
-  "description": "External Claude Code, Codex CLI, and Antigravity delegation for pi.",
+  "version": "2.3.0-external.0",
+  "description": "External Claude Code, Codex CLI, Antigravity, and Grok Build CLI delegation for pi.",
   "type": "module",
   "main": "./index.ts",
   "exports": "./index.ts",
@@ -28,13 +28,14 @@
     "codex",
     "claude",
     "agy",
-    "antigravity"
+    "antigravity",
+    "grok"
   ],
   "license": "MIT",
   "scripts": {
     "build": "tsc",
     "check": "tsc --noEmit && vitest run",
-    "e2e": "node scripts/e2e/external.mjs",
+    "e2e": "node --experimental-transform-types scripts/e2e/external.mjs",
     "field-report": "node scripts/field-report.mjs",
     "test": "vitest run"
   },

package/scripts/field-report.mjs

@@ -57,7 +57,7 @@ async function loadRecord(baseDirectory, runId) {
     const eventCount = finite(document.eventCount);
     const attemptedEventCount = finite(document.attemptedEventCount);
     const backendEventCount = events.filter((event) => event.type === "backend_event").length;
-    if (!["claude", "codex", "agy"].includes(summary.backend)) problems.push("missing or unknown backend");
+    if (!["claude", "codex", "agy", "grok"].includes(summary.backend)) problems.push("missing or unknown backend");
     if (typeof summary.profile !== "string" || !summary.profile) problems.push("missing profile");
     if (!["done", "error", "aborted"].includes(summary.status)) problems.push("missing or unknown status");
     if (writeErrorCount === undefined) problems.push("missing write error count");

package/src/core/agy.ts

@@ -266,6 +266,7 @@ export async function spawnAgySubagent(params: {
   permission?: PermissionTier;
   resumeConversationId?: string;
   timeoutMs?: number;
+  executionStartedAt?: number;
 }): Promise<AgentToolResult> {
   const subagentType = params.profile.name;
   const promptParts = [params.profile.systemPrompt, params.prompt, params.appendInstructions].filter(Boolean);
@@ -278,6 +279,7 @@ export async function spawnAgySubagent(params: {
     backend: params.profile.backend,
     enabled: params.progressEnabled,
     onProgress: params.onProgress,
+    executionStartedAt: params.executionStartedAt,
   });
   const progress = emitter.progress;
   const stderrBuffer = createBoundedBuffer(MAX_STDERR_CHARS);

package/src/core/claude.ts

@@ -340,6 +340,7 @@ export async function spawnClaudeSubagent(params: {
   permission?: PermissionTier;
   maxBudgetUsd?: number;
   resumeSessionId?: string;
+  executionStartedAt?: number;
 }): Promise<AgentToolResult> {
   const subagentType = params.profile.name;
   const taskPrompt = params.appendInstructions ? `${params.prompt}\n\n${params.appendInstructions}` : params.prompt;
@@ -350,6 +351,7 @@ export async function spawnClaudeSubagent(params: {
     backend: params.profile.backend,
     enabled: params.progressEnabled,
     onProgress: params.onProgress,
+    executionStartedAt: params.executionStartedAt,
   });
   const progress = emitter.progress;
   let latestRawUsage = emptyTokenUsage();

package/src/core/codex.ts

@@ -311,6 +311,7 @@ export async function spawnCodexSubagent(params: {
   outputSchema?: unknown;
   permission?: PermissionTier;
   resumeSessionId?: string;
+  executionStartedAt?: number;
 }): Promise<AgentToolResult> {
   const subagentType = params.profile.name;
   const taskPrompt = params.appendInstructions ? `${params.prompt}\n\n${params.appendInstructions}` : params.prompt;
@@ -321,6 +322,7 @@ export async function spawnCodexSubagent(params: {
     backend: params.profile.backend,
     enabled: params.progressEnabled,
     onProgress: params.onProgress,
+    executionStartedAt: params.executionStartedAt,
   });
   const progress = emitter.progress;
   let latestUsage = emptyUsage(params.profile.model);

package/src/core/display.ts

@@ -13,5 +13,8 @@ export function getBackendAgentLabel(backend: SubagentBackend | undefined): stri
   if (backend === "agy") {
     return "Antigravity";
   }
+  if (backend === "grok") {
+    return "Grok CLI";
+  }
   return "Agent";
 }