[ericlitman]

Summary

A Grok CLI session becomes a pstack parent harness, next to Claude Code, Codex and T3 Code. This takes over draft PR #282 by @max-metaplanet. Their three commits are kept with their authorship, and the routing rule is reworked after live probes of Grok 1.0.77.

Grok parent, per lane:
  inherit-parent | auto -> native spawn_subagent, subagent_type pstack:poteto-agent
  grok:<model>@<effort> -> pstack-runner --parent grok --provider grok   (registered or not)
  any other provider    -> pstack-runner --parent grok
  native lane failed    -> dropout, never retried through the runner
Claude / Codex parents: unchanged (their own provider stays native; the runner refuses it)

 plugins/pstack/
 ├── .claude-plugin/plugin.json
 ├── .codex-plugin/plugin.json
+├── .grok-plugin/plugin.json   # Grok reads this first: skills ./skills/, agents ./grok-agents/
 ├── agents/                    # Claude lane agents (model: opus, ...), unchanged
+├── grok-agents/               # generated copies of poteto-agent and comment-sicko only
 └── skills/                    # one shared tree
 .claude/skills/verify-open-pstack/
+└── scripts/grok.ts            # ACP transport: grok agent --plugin-dir <candidate> stdio

• The runner flag is explicitLaneRoute: "native" | "runner", which replaces feat/no-ticket(runner): accept grok as a parent harness #282's externalSelf. Grok's session markers GROK_SESSION_ID and GROK_AGENT are stripped from children, and GROK_HOME is kept.
• The model sheet is ${GROK_HOME:-$HOME/.grok}/rules/pstack-models.md, which Grok loads as a home rule. /setup-pstack on Grok probes and then writes it.
• codex-tools.md gains a Grok column and a "Waits on Grok" section covering waits, cancellation, writer checkouts, MCP, read-only and depth-one children.
• pstack's startup hook does not fire in Grok, because Grok's SessionStart sources are new and load. The docs say to invoke /pstack:poteto-mode by name, as on Codex.
• The verifier gains a grok harness and two recipes. grok:dispatch runs one native lane, one Grok runner lane and one Claude runner lane, and checks that Grok offers only the model-free agents. grok:setup checks that setup writes the Grok sheet, and restores the operator's Grok sheet byte for byte.

Closes #281.

Evidence

Grok 1.0.77 on studio1, headless probes. The served model was read from each child's Grok session record (summary.json, usage.json).

• Before (main, today on any host whose Grok sees the Claude Code install): Grok spawned pstack:pstack-opus-low, and the child ran on grok-4.7-build with no error.
  After: with the Grok manifest, Grok's runtime discovery (grok inspect --json, from a scratch GROK_HOME install) lists only pstack:poteto-agent and pstack:comment-sicko, plus 65 skills. Without an agents key it listed all 27 agents.
• Why explicit Grok lanes use the runner: a Grok agent file with model: grok-4.6 / effort: medium ran grok-4.6 at medium. One naming grok-4.9, a model that does not exist, silently ran the parent's grok-4.7 and returned OK. A native pin has no failure signal. The runner's receipt verifies the served model.
• Manifest form: Grok reads every agents list entry as a directory. A list of the two files loaded 0 agents, so the manifest points at a generated directory instead, covered by the registry's drift check.
• Verifier transport, one live run against main's plugin:
  • Grok's _x.ai/plugins/list showed the --plugin-dir candidate (origin: cli_override) shadowing the installed pstack 1.20.0.
  • The tree hash matched, the skill loaded from the candidate path, and the parent ran as grok-4.7@low.
  • The per-run marker came back.
  • The model-free agent check correctly refused main's 27-agent list.

Merge Danger

Door: two-way

Reverting this PR returns everything to main's behaviour. No user file is migrated.

Blast Radius: Grok-only

• Claude Code and Codex routing is unchanged; their runner refusal and route-table cells are the same.
• Grok users get a new manifest. On a host where Grok discovers pstack through the Claude Code install, the Claude lane agents disappear from Grok's subagent list, which is the intent.
• The verifier gains a harness that runs only when a grok: feature is named.

Acceptance criteria

The criteria come from the scope comment on #281: #281 (comment)

1. Runner accepts --parent grok, strips Grok session markers and keeps GROK_HOME, with markers confirmed from a live Grok session. A live probe printed exactly GROK_AGENT and GROK_SESSION_ID. Tests: registry.test.ts (the parent-by-adapter matrix) and run.test.ts (childEnvironment). Live: pending grok:dispatch.
2. inherit-parent/auto use native spawn_subagent with pstack:poteto-agent; every explicit grok:* descriptor uses the runner; no rule depends on matching the parent; the flag is explicitLaneRoute: "runner"; Claude-on-Claude and Codex-on-Codex are still refused. The rules are in provider-dispatch.md, poteto-mode/SKILL.md, codex-tools.md and setup-pstack/SKILL.md, and the generated route cell carries them. Tests: registry.test.ts. Live: pending grok:dispatch.
3. A Grok-only manifest shares skills/; Grok does not offer the Claude lane agents and does offer poteto-agent and comment-sicko. Proved by runtime discovery (Evidence above) and grok plugin validate. Live: pending grok:dispatch (agent-list assertion). The criterion preferred listing the two files directly. That form loads nothing in Grok 1.0.77, so the manifest uses a generated directory.
4. The Grok tool mapping covers writer checkouts, bounded waits re-armed through IDs, cancellation reading the receipt, MCP on native lanes only, advisory read-only and depth-one children. Covered by the "Waits on Grok" section of codex-tools.md. It is a documentation-only item.
5. The Grok sheet is at ${GROK_HOME:-$HOME/.grok}/rules/pstack-models.md, is read first, and a malformed sheet is a visible stop; setup probes and writes it. Covered by provider-dispatch.md and setup-pstack/SKILL.md. Live: pending grok:setup.
6. No pstack startup hook in Grok; invoke by name. Covered by README and docs/reference.md. hooks/hooks.json is unchanged.
7. Verifier grok harness: ACP session-only load, cheap explicit model, non-interactive permissions, candidate load proof, grok:dispatch and grok:setup with byte-exact restore. Covered by scripts/grok.ts, features/grok.md and recipes.ts. Its unit tests pass, and the transport passed one live run (Evidence). The recipes are pending the live gate.
8. Classification, version and drift checks, and provenance docs. registry.json maps .grok-plugin/plugin.json and grok-agents/*. skill-collision-repro.sh compares 4 manifests, and package.json static parses the Grok manifest. UPSTREAM, CHANGES, NOTICE, README, reference and AGENTS name the Grok harness.

Gate results (head c33565d)

Check	Exit	Summary
bun run test	0	509 pass, 0 fail
bun run typecheck	0	clean
bun run static	0	shell checks ok, verifier 217 pass
claude plugin validate plugins/pstack	0	Validation passed
grok plugin validate plugins/pstack	0	manifest valid, 1 agent dir
verifier bun run test + typecheck	0	217 pass, clean

Not verified

• live-gate: not yet published. Planned features: grok:dispatch and grok:setup with --self-test, run from this candidate head because the PR changes the verifier.
• Grok discovering pstack through a Claude Code install (~/.claude/plugins) has not been probed. If Grok reads .grok-plugin there, the agent fix reaches existing users without a separate Grok install. This is checked on the host after release.
• Setup's write to ~/.grok/rules/: not yet observed under Grok's permission rules. grok:setup covers it.

🤖 Generated with Claude Code

[mergify]

Merge Protections

🟢 All 2 merge protections satisfied — ready to merge.

Show 2 satisfied protections

🟢 Queue ready pull requests

Automatically queue non-draft pull requests targeting main after verify and live-gate pass on the head and every review thread is resolved.

• #review-threads-unresolved = 0
• -draft
• check-success=live-gate
• check-success=verify

🟢 🚦 Auto-queue

When all merge protections are satisfied and these conditions match, this pull request will be queued automatically.

• -files~=^\.github/
• base = main

[ericlitman]

Live evidence: Open Pstack

• Candidate SHA: c33565d6f0350f3e362ccab9c49d42dc0c090e76
• Base SHA: 5b6ccced42cbab27adf45b8c256a26457b2af1d8
• Result: FAILED — verification did not complete; rerun required
• Self-test: required in both harnesses
• Planned sessions: 4 (limit 12)
• Publisher revision: c33565d6f0350f3e362ccab9c49d42dc0c090e76
• Evidence-set SHA-256: dbd2e95c0af7ae76995278d75abaa1c67e1691f0a8a762bae8a14fc940a15596
• Policy: every new head requires a fresh run; this verifier does not change PR state, queue, or merge.

[ericlitman]

Live evidence: Open Pstack

• Candidate SHA: 0d0c5d5a5f1b88d124f115fc172a826b35de6d4b
• Base SHA: 5b6ccced42cbab27adf45b8c256a26457b2af1d8
• Result: PASSED — named features verified
• Self-test: completed in both harnesses
• Planned sessions: 4 (limit 12)
• Publisher revision: 0d0c5d5a5f1b88d124f115fc172a826b35de6d4b
• Evidence-set SHA-256: 37960d2c33ed2d738c1c8df5d2c589cb07baa9db9ff81d3e371863fca5bb06e0
• Installation (claude): CLI 2.1.319 (Claude Code), plugin 1.20.0, candidate 0d0c5d5a5f1b88d124f115fc172a826b35de6d4b, tree 86a1dc7eb4d0f47e36968565eb2b4acb8ceccaf0f5abb8dbd0bf29b5fbb9b244.
• Installation (codex): CLI codex-cli 0.167.0, plugin 1.20.0, candidate 0d0c5d5a5f1b88d124f115fc172a826b35de6d4b, tree 86a1dc7eb4d0f47e36968565eb2b4acb8ceccaf0f5abb8dbd0bf29b5fbb9b244.
• Installation (grok): CLI grok 1.0.77 (50ca579fa996) [stable], plugin 1.20.0, candidate 0d0c5d5a5f1b88d124f115fc172a826b35de6d4b, tree 86a1dc7eb4d0f47e36968565eb2b4acb8ceccaf0f5abb8dbd0bf29b5fbb9b244.
• Observation (claude / project-skill): surface claude -p stream-json with the candidate plugin-dir; action recipe project-skill: doctor; result passed: doctor:exit-0 doctor:skill-loaded doctor:doctor-ran doctor:doctor-canonical-pass; 4 assertions machine-checked; transcript SHA-256 fbf3ee3a7df39773cf6b563bb5517e4d66fd8e8cda856e680d429fb987aac741; artifact-set SHA-256 67d71d015446af071b7ca427ec2af035daa8d8c928ca6ed4b9575c0d1a65a3df.
• Observation (codex / project-skill): surface codex exec --json with the run-owned candidate installation; action recipe project-skill: doctor; result passed: doctor:exit-0 doctor:skill-loaded doctor:doctor-ran doctor:doctor-canonical-pass; 4 assertions machine-checked; transcript SHA-256 5f722729818c761904275d27742d442519c941858d00ca77bacf3a696f072634; artifact-set SHA-256 948507404dcd7f6ebd01be2f51f456ef0d0148ce2b58948699a343002ac2dc3a.
• Observation (grok / dispatch): surface grok agent stdio (ACP) with the candidate plugin-dir; action recipe dispatch: dispatch; result passed 7 assertions; ids retained privately; 7 assertions machine-checked; transcript SHA-256 5d7e6c9c11d1c46e4d4a9a7f4af2b72fc4ffff790f7f100081fb200c849e7a94; artifact-set SHA-256 b5405d1c546e06050cb0b58121a96b321cb88b9716d6bae5ae7e8f4117ab1581.
• Observation (grok / setup): surface grok agent stdio (ACP) with the candidate plugin-dir; action recipe setup: configure; result passed: configure:exit-0 configure:skill-loaded-from-candidate configure:file:pstack-models.md configure:sheet:grok:grok-4.7@low configure:no-full-access; 5 assertions machine-checked; transcript SHA-256 9bc8a7fb25e031b595447b1ebf8f6fd0742043c2905ad6c7591944b49e006143; artifact-set SHA-256 c72521ce9f4eeb4b3d4c0991c519e473c5590bcaa16837a231d796f9e1291068.
• Policy: every new head requires a fresh run; this verifier does not change PR state, queue, or merge.

[mergify]

✅ Merged into main as eda73cc at 19:06 UTC

Less than a minute in the queue, with no time running CI.

So far

• ✅ Entered the queue Sun 8 Nov, 19:06 · rule default · triggered by merge protections
• ✅ Checks skipped · PR is already up-to-date
• ✅ Merged 19:06 · eda73cc · merge

8 merge conditions met

• github-review-approved · required by GitHub repository ruleset rule Protect main
• #review-threads-unresolved = 0 · required by Merge Protections rule Queue ready pull requests
• -draft · required by Merge Protections rule Queue ready pull requests
• check-success=live-gate · required by Merge Protections rule Queue ready pull requests
• check-success=verify · required by Merge Protections rule Queue ready pull requests
• any of · required by GitHub repository ruleset rule Protect main:
  • check-success = @github-actions/verify
  • check-neutral = @github-actions/verify
  • check-skipped = @github-actions/verify
• any of · required by GitHub repository ruleset rule Protect main:
  • check-success = live-gate
  • check-neutral = live-gate
  • check-skipped = live-gate
• any of · required by GitHub repository ruleset rule Review gate:
  • check-success = @mergify/Mergify Merge Protections
  • check-neutral = @mergify/Mergify Merge Protections
  • check-skipped = @mergify/Mergify Merge Protections

_{Times in UTC · dashboard · how the merge queue works}

[unfret-eal]

🛑 7 blocking findings

🔴 Critical · Resolve empty GROK_HOME to the default before snapshotting

🔴 High · Reflect is exposed without a Grok copy destination

🔴 High · Grok-only agent changes cannot select Grok verification

🔴 High · Grok live-test reach omits Grok runtime paths

🟡 Medium · Honor cancellation before spawning another Grok session

🟡 Medium · Recognize Grok's deployment-key authentication result

🟡 Medium · Preserve UTF-8 characters across ACP stream chunks

Walkthrough

This PR lets a Grok CLI session act as a pstack parent harness alongside Claude Code, Codex and T3 Code. It adds a Grok plugin manifest that shares the existing skills tree but exposes only the model-free `poteto-agent` and `comment-sicko` agents. In a Grok parent, `inherit-parent` and `auto` lanes run natively through `spawn_subagent`, and every explicit descriptor, Grok models included, goes through `pstack-runner --parent grok`. The author's probes found that a Grok agent file naming a model Grok cannot serve silently runs the parent's model, so only the runner's receipt proves which model served. The PR also documents the Grok tool mapping and sheet location, and adds a `grok` harness to the verifier with two recipes. The live gate for those recipes is not yet published.

Area	What changes	Review notes
Runner routing	`PARENTS` gains a `grok` entry with `explicitLaneRoute: "runner"`. The runner therefore accepts `--parent grok` for every provider, including Grok, while Claude-on-Claude and Codex-on-Codex are still refused. Grok children drop `GROK_SESSION_ID` and `GROK_AGENT` and keep `GROK_HOME`. The generated route table gets a Grok parent column. Adds tests for the parent/provider matrix and the child environment.
Grok plugin surface	Adds `.grok-plugin/plugin.json`, which points `agents` at a generated `grok-agents/` directory. The registry renderer copies the two agents into that directory and checks it for drift. The manifest joins the version-match and static JSON checks.
Docs and skills	`provider-dispatch.md`, `poteto-mode`, `setup-pstack` and `codex-tools.md` describe the Grok routes, the sheet at `${GROK_HOME:-$HOME/.grok}/rules/pstack-models.md`, a Grok tool column and a Waits on Grok section. The docs also note that the startup hook does not fire in Grok, so users invoke `/pstack:poteto-mode` by name. Review flagged gaps here: Reflect has no Grok copy destination, Claude built-ins have no Grok mapping, and new-file creation is mapped to `search_replace`.	Reflect is exposed without a Grok copy destination
Verifier harness	Adds an ACP transport (`grok.ts`), doctor checks, the `grok:dispatch` and `grok:setup` recipes, classification reach, and snapshot and restore of the Grok sheet, with unit tests. Review flagged several problems. An empty `GROK_HOME` is not resolved to the default before snapshotting. Classification reach omits Grok runtime paths, and Grok-only agent changes cannot select Grok verification. Cancellation is not honored before another Grok session spawns, UTF-8 characters can split across stream chunks, and deployment-key auth is not recognized.	Resolve empty GROK_HOME to the default before snapshotting Grok live-test reach omits Grok runtime paths Grok-only agent changes cannot select Grok verification Honor cancellation before spawning another Grok session Preserve UTF-8 characters across ACP stream chunks Recognize Grok's deployment-key authentication result

Advisories (2)

• 🔴 High · Claude built-ins have no Grok mapping · plugins/pstack/skills/poteto-mode/SKILL.md:11
  This line declares the shared skill tree usable on Grok but still directs Claude tool and built-in references only to a “Codex equivalent.” The referenced mapping adds Grok tool actions but no Grok substitutes for the Claude-only `run`, `verify`, `plugin-dev:skill-development`, or `loop` skills. A normal Grok CLI task therefore reaches poteto-mode's mandatory `run` driver and attempts an unavailable Claude skill instead of performing the required real-surface verification.
  Not blocking because: Established consequence is incomplete guidance: line 12 still routes Grok readers to the Codex substitutes, which are harness-neutral (run the app yourself and observe real output; do not claim done without the artifact), Grok has no Skill tool to invoke `run`, and Prove It Works still requires verification, so no workflow step is removed.
• 🔴 High · New-file creation is mapped to search_replace · plugins/pstack/skills/poteto-mode/references/codex-tools.md:57
  The Grok column maps creation, editing, and deletion solely to `search_replace`, despite Grok exposing a separate `write` tool. On a first `/setup-pstack` run the model sheet does not exist, so following this mapping invokes a replace operation with no existing target and the configuration write fails. Other workflows that create result or source files have the same failure.
  Not blocking because: Established consequence is an inaccurate tool hint: Grok sessions also expose `write` (verifier GROK_TOOLS), setup-pstack names no Claude write tool, and setup's readback plus snapshot restore turn any failed sheet write into a reported, restored failure, so no silent misconfiguration or data loss follows.

Since the last review

• New: Reflect is exposed without a Grok copy destination
• New: Grok-only agent changes cannot select Grok verification
• New: Resolve empty GROK_HOME to the default before snapshotting
• New: Honor cancellation before spawning another Grok session
• New: Recognize Grok's deployment-key authentication result
• New: Preserve UTF-8 characters across ACP stream chunks
• New: Grok live-test reach omits Grok runtime paths

Repair prompt

Read the Unfret check run for ericlitman/open-pstack#284 at head 0d0c5d5a5f1b88d124f115fc172a826b35de6d4b (run panel:0d0c5d5a5f1b88d124f115fc172a826b35de6d4b:Nnn73fsL1Zp:l2MFOMF5lfE, check). Use the check's App id and GET /repos/ericlitman/open-pstack/check-runs/128830733201; its output.text contains the structured result. Compare it with the current code and head, verify that each listed mandatory finding still applies, repair only those that do, honor the repository constraints, and validate the changes. Leave advisories and accepted risks alone. A manually resolved thread is not a waiver.

• v1:1c735e4dc9c2bfc567e0862905d3b9dd1156b2ab5bda3f60264378651c9c4d9f
• v1:1f3cdb66a99391a20d67babc61140fe4b5c7a1e28d519d1751d3e81140322fc5
• v1:21c02ebcbade747dea8dc40073534c8ee1a4d6d31499fc333752988a0c219c5c
• v1:3314e206c4cfa4f1c04cb0462827dd36d2a92639b5de2c424f5f03074cbd034e
• v1:48f7322e133bfcabbdbfa9856fda1b13dc2c98bb00c25cb79671111059cae727
• v1:a03cfcd2de906ead91d25aab18c375961156deb7f0b78e0b9e621e5042b872c7
• v1:ccdebf5cd766bf340f427a4643c6b3a9bec91a942da084aa6035854b91612f60

Details

Lane / stage	Model	Effort	Outcome	Duration
broad-gpt-5.6-sol-xhigh / review	openai/gpt-5.6-sol → gpt-5.6-sol · primary	xhigh	succeeded	9 min 1 s
broad-opus-5.5-max / review	anthropic/claude-opus-5-5 → claude-opus-5-5 · primary	max	succeeded	15 min 5 s
focal-gpt-5.6-sol-xhigh copy / review	openai/gpt-6.1-sol → gpt-6.1-sol · primary	xhigh	succeeded	13 min 1 s
focal-gpt-5.6-sol-xhigh copy 2 / review	openai/gpt-6.1-sol → gpt-6.1-sol · primary	xhigh	succeeded	16 min 41 s
judge / judge	openai/gpt-6-astra → gpt-6-astra · primary	high	succeeded	2 min 34 s
confirmation / confirmation	anthropic/claude-opus-5-5 → claude-opus-5-5 · primary	max	succeeded	3 min 29 s

First review of this pull request.
4 reviewers finished.
Commit 0d0c5d5.
Check run.
Run: GET /unfret/run/panel:0d0c5d5a5f1b88d124f115fc172a826b35de6d4b:Nnn73fsL1Zp:l2MFOMF5lfE.

_{@unfret review · @unfret status · @unfret help}

[unfret-eal]

🛑 7 blocking findings
🔴 Critical · Resolve empty GROK_HOME to the default before snapshotting
🔴 High · Reflect is exposed without a Grok copy destination
🔴 High · Grok-only agent changes cannot select Grok verification
🔴 High · Grok live-test reach omits Grok runtime paths
🟡 Medium · Honor cancellation before spawning another Grok session
🟡 Medium · Recognize Grok's deployment-key authentication result
🟡 Medium · Preserve UTF-8 characters across ACP stream chunks
Check