cohorte 2.1.0 → 2.3.0

package/core/commands/cohorte-ship.md

@@ -12,8 +12,7 @@ You are the **lead**. Ship feature **$ARGUMENTS**. This is the outward-facing ga
 >
 > **Kanban** (SCHEMA.md §Kanban) is mirrored in **explicit steps** below, not as an afterthought:
 > §1 moves the card → **Ship**; §4 moves it → **Shipped** and writes the PR number. Both are one
-> call to `<core>/pipeline/scripts/kanban-move.sh auto …` (`<core>` = `.claude` bundled / `~/.claude`
-> global — probe with `test -x`), which resolves the board from the config itself and exits 0 with a
+> call to `<core>/pipeline/scripts/kanban-move.sh auto …`, which resolves the board from the config itself and exits 0 with a
 > `kanban: <reason>` line when there is none. **Never decide "no board is configured" without running
 > it** — a ship session that inferred that, having opened neither the config nor `PIPELINE.md`, is
 > exactly how a merged feature's card stayed in "Ready to build". Do not skip §4's move either.
@@ -32,7 +31,10 @@ You are the **lead**. Ship feature **$ARGUMENTS**. This is the outward-facing ga
   §`Acceptance criteria / DoD`; if any item is still `- [ ]`, list the open ones and ask the human to
   confirm shipping anyway (they may be deferred on purpose — e.g. a UI item on a backend-only feature).
   All `- [x]` ⇒ proceed silently.
-- Show `git status` + `git diff --stat`; confirm the branch is `<feature_branch_prefix>$ARGUMENTS`.
+- Show `git status` + `git diff --stat`; confirm the branch is `<prefix>$ARGUMENTS`, where `<prefix>`
+  is `vcs.patch_branch_prefix` (falling back to `fix/` on a profile that predates the key) when the
+  spec front-matter carries `kind: patch`, and `vcs.feature_branch_prefix` otherwise. Resolve it once
+  here and pass the **literal** branch to §3's dispatch — the release agent must not re-derive it.
 - **Ask the human to confirm** they want to commit, push, and open the PR. Wait for yes.
 - After the yes: `<core>/pipeline/scripts/kanban-move.sh auto $ARGUMENTS ship`. Report what it
   printed — `moved #…` or `kanban: <reason>` — never a guess about which happened.
@@ -58,6 +60,9 @@ See SCHEMA.md §Release notes.
   `release_notes.forbid_levels` (a `0.x` repo forbidding `major` declares the rupture `minor`).
 - **Ambiguous between two defensible levels?** State your reading in one line and **ask the human to
   pick** before writing. A wrong bump becomes a published version number.
+- A `kind: patch` spec is a `patch` bump by default — that is what the level means. It is a default,
+  not a rule: a bug fix that changes documented behaviour is still a `minor`, and one that removes it
+  is still breaking. Say which you chose when it isn't `patch`.
 - The body describes what changed **for the user**, from the spec §1/§2 — no client names, no internal
   paths, no exploitable attack vector, no file lists.
 - If the feature genuinely must move no version, use `release_notes.empty_cmd` instead. Prefer that to
@@ -65,17 +70,18 @@ See SCHEMA.md §Release notes.
 - Then say in one line which level you chose and why — this is the human's last chance to correct it
   before it is committed.
 
-> **Why this is its own gate.** The requirement usually lives in the project's `CLAUDE.md`, which this
+> **Why this is its own gate.** The requirement usually lives in the project's `<memory>`, which this
 > flow never reads. Skip it and everything below still "succeeds": commit, push, PR opened, kanban card
 > moved to **Shipped** — and CI red on a job nobody watched. The feature reads as shipped while being
 > unmergeable.
 
 ## 3. Dispatch the `release` agent
 
-Spawn one agent (`subagent_type: release`): "Release feature `$ARGUMENTS` on branch
-`<feature_branch_prefix>$ARGUMENTS`. Read `PIPELINE.md` §vcs first. Spec: `specs/$ARGUMENTS.md` (already
+Spawn one agent (`subagent_type: release`, or the equivalent dispatch for this runtime):
+"Release feature `$ARGUMENTS` on branch
+`<the branch §1 resolved>`. Read `PIPELINE.md` §vcs first. Spec: `specs/$ARGUMENTS.md` (already
 `status: shipped` — stage it). Write conventional commit(s), push (no force), open the PR (use `gh` if
-`host: github` + available; else emit the compare URL + drafted PR body from `.claude/templates/pr-body.md`).
+`host: github` + available; else emit the compare URL + drafted PR body from `<core>/templates/pr-body.md`).
 Stage **all** the feature's changes including `specs/$ARGUMENTS.md` and, if `release_notes.enabled`, the
 release note at `<release_notes.dir>/<release_notes.filename>` — it is already written, stage it as-is and
 never author or edit one yourself. Never edit source, never force-push, never run migrations."
@@ -101,13 +107,6 @@ with a **grep for `#$ARGUMENTS`** on the board it named (with surrounding headin
 `grep -B20 '#$ARGUMENTS' | grep '^##'`, or an offset-limited Read around the match): exactly one card,
 under the `shipped` heading — never re-read the whole board into context.
 
-**Telemetry — the usage ping that closes the funnel.** Chain it onto the verify call above
-(`/cohorte-build` §4's shared form, `<phase>` = `ship`, `<seconds>` = `0` — the release agent's duration is
-not the pipeline's, `<results>` = `pr` when a PR was created / `compare` when only a compare URL was
-emitted). Fire it **after** the release agent reports success, never on an aborted ship — a `ship`
-event must mean the feature actually left the pipeline. No board ⇒ still ping, in its own `|| true`
-call. Silent no-op without consent; never ask about consent here.
-
 ## 5. After the PR — CI gate + teardown
 
 - If `host: github` and `gh` is available, watch the PR's checks (`gh pr checks <url> --watch`) and

package/core/commands/cohorte-spec.md

@@ -10,17 +10,13 @@ You run the **spec** step in the main thread — interactive, with the human. Pa
 > Read `PIPELINE.md` first: `contract` (mechanism/path — so §5 names the right schema types),
 > `design.enabled` (whether §8 matters), and §Conventions. Use `specs/_template.md` as the section list.
 >
-> Template paths below (`.claude/templates/…`) resolve to `~/.claude/templates/…` when the core is
-> installed globally — read whichever exists.
->
 > **Decision journal** (SCHEMA.md §Decisions): read `specs/_decisions.md` §Live if it exists — one
 > line per standing decision, so it is cheap. It is the ONLY place the project's transverse rules
 > live; a spec that contradicts one silently un-decides it. Absent ⇒ nothing to honour yet.
 >
 > **Kanban** (SCHEMA.md §Kanban): when the spec opens, run
 > `<core>/pipeline/scripts/kanban-move.sh auto <feature_id> spec --title "<human title>"`; on freeze
-> (`status: frozen`, Mode A), the same call with `ready`. `<core>` = `.claude` bundled / `~/.claude`
-> global — probe with `test -x`. `auto` resolves the board from the config itself and exits 0 with a
+> (`status: frozen`, Mode A), the same call with `ready`. `auto` resolves the board from the config itself and exits 0 with a
 > `kanban: <reason>` line when there is none — so **never decide "no board is configured" without
 > running it**.
 
@@ -55,19 +51,14 @@ Detect the mode from the pasted content:
    it. This is just so the human isn't surprised when `/cohorte-build` proposes a new agent.
 5. When the human validates, **freeze**: write `specs/<id>.md` (`status: frozen`, front-matter filled).
    Create the file — do not ask the human to. **Postcondition:** `grep -q '^status: frozen' specs/<id>.md`
-   — if it fails the freeze didn't land; fix it before pointing the human at `/cohorte-build`. Chain the
-   opt-in usage ping onto the postcondition's Bash call (`/cohorte-build` §4's shared form, `<phase>` =
-   `spec`, `<seconds>` = `0` — interactive time, not pipeline wall-clock, `<results>` = `frozen`).
-   Ping only on a **landed** freeze, so the funnel counts specs that exist, not attempts. Mode B does
-   not ping — it re-enters an already-counted spec, and `/cohorte-fix` covers that loop. Silent no-op without
-   consent; never ask about consent here.
+   — if it fails the freeze didn't land; fix it before pointing the human at `/cohorte-build`.
 5b. **Record the transverse decisions — the journal, not a summary.** Walk what the interview settled
    and keep ONLY the decisions that **outlive this feature**: a rule the next spec would otherwise
    re-litigate or contradict (auth model, id/naming scheme, where a kind of state lives, an error
    convention, a deliberate non-goal that binds future features). Typical yield: **0–3 lines**; zero
    is a normal, healthy outcome for a feature that decided nothing new — never invent lines to fill
    the section. Append them to `specs/_decisions.md` §Live (create the file from
-   `.claude/templates/decisions.template.md` on first use), each exactly:
+   `<core>/templates/decisions.template.md` on first use), each exactly:
    `- <YYYY-MM-DD> · <area> · <decision> — because <reason> · <feature_id>`
    - **Never** duplicate what §5, `PIPELINE.md` §Conventions or the code already states — the journal
      carries the *non-obvious rule*, not the feature's content. A line that restates a spec section is
@@ -78,7 +69,7 @@ Detect the mode from the pasted content:
    - Append with one `>>` Bash call, not a full-file rewrite (the file is append-only, and reading it
      back to re-write it is the one way to make a bounded file expensive).
 6. Author the **design brief** — `specs/design/<id>.md`, rendered via
-   `.claude/templates/design-brief.md` (resolves to `~/.claude/templates/…` on a global install).
+   `<core>/templates/design-brief.md`.
    _Only if `design.enabled` / the feature has UI; skip entirely for a backend-only feature._
    - **Write it to `specs/design/<id>.md`** (the authored artifact, versioned with the spec; spec §8
      holds the summary + pointer). Create the file — do not ask the human to. Keep it in the

package/core/commands/cohorte-update-pipeline.md

@@ -6,14 +6,14 @@ argument-hint: [path-to-local-checkout]
 
 You are the **pipeline updater**. Refresh the installed pipeline core to the latest version of the pipeline
 repo. The installer's `--update` mode never touches generated files: `PIPELINE.md`, rendered surface agents,
-`gate-config.json`, `settings.json`, and the filled `~/.claude/cohorte.config.yaml` are all preserved.
+`gate-config.json`, `settings.json`, and the filled `<config>` are all preserved.
 YOU then bring those generated files up to the new core yourself (§3.5) — additively, never clobbering
 the human's choices — so `/cohorte-init-pipeline` never needs re-running for an upgrade.
 
 ## 1. Detect the install scope + current version
 
-- **Global** install ⇒ `~/.claude/pipeline/VERSION` exists. **Bundled** ⇒ this repo's
-  `.claude/pipeline/VERSION` exists. (Both can exist; prefer the bundled one when running inside such a
+- **Global** install ⇒ `<core>/pipeline/VERSION` exists. **Bundled** ⇒ this repo's
+  `<core>/pipeline/VERSION` exists. (Both can exist; prefer the bundled one when running inside such a
   repo, and update both if the human wants.)
 - **Never migrate a repo between bundled and global mode on your own.** Updating means refreshing the
   core *in its current mode*. Only migrate (e.g. delete a bundled core in favor of the global one) if
@@ -52,7 +52,7 @@ the human's choices — so `/cohorte-init-pipeline` never needs re-running for a
 
 Re-read the VERSION file(s) and print `old → new`. If unchanged, say the core was already up to date.
 
-**Sync the pointer — in BOTH modes.** If this repo has a `.claude/pipeline.json` whose `core_version`
+**Sync the pointer — in BOTH modes.** If this repo has a `<state>/pipeline.json` whose `core_version`
 differs from the core you just installed, rewrite that one field (leave every other field untouched)
 and tell the human to commit it. In **bundled** mode the installer already did it; in **global** mode
 **nothing does** — the installer refreshes one shared core and cannot know which repos point at it,
@@ -87,21 +87,22 @@ missing, say so. This is why `/cohorte-init-pipeline` never needs re-running for
 Four of the §Reconcile steps matter specifically here:
 
 - **Local-artifact hygiene** (§Reconcile step 8): gitignore + untrack the pipeline's runtime files
-  (`.claude/preflight.ok`, `.claude/pipeline-metrics.jsonl`, `specs/reports/`). A tracked
+  (`<state>/preflight.ok`, `<state>/pipeline-metrics.jsonl`, `specs/reports/`). A tracked
   `preflight.ok` — what every pre-2.0.0 install ends up with once a release agent stages `.claude/` —
   makes the phase gate ask on every single review dispatch, so fix it here and say so.
 
 - **Spec-template top-up** (§Reconcile step 7): `specs/_template.md` was seeded at install and never
   refreshed since, so add the front-matter fields the current `templates/spec.template.md` has and the
-  repo's copy lacks (1.6 added `loop_pass`/`loop_phase` and two states to the `status:` comment) —
+  repo's copy lacks — and drop `loop_pass`/`loop_phase`, retired with `/cohorte-loop` in 2.2.0 —
   front-matter only, never the body.
 
-- **Global config seed** (§Reconcile step 5): if `~/.claude/cohorte.config.yaml` is absent, seed it
+- **Global config seed** (§Reconcile step 5): if `<config>` is absent, seed it
   from the template so the kanban + shared-vault config has a home. Never clobber an existing filled
-  file. Report what was seeded. If the existing file has NO `telemetry:` block with a `consent_date`
-  (pre-telemetry install), top up the block from the template and ask the ONE opt-in consent
-  question defined in `templates/steps/init-pipeline/02-interview-gaps.md` §Telemetry — record the
-  answer either way so it is never re-asked. Consent is strictly opt-in; "No" is the default.
+  file. Report what was seeded. Then **scrub the retired `telemetry:` block** if the existing file
+  still has one (every install seeded before 2.3.0 does) — one targeted Edit deleting the block and
+  its comment header, nothing else touched. That capability was removed in 2.3.0, sender included,
+  so the block is dead config: nothing reads it, and an `enabled: true` left sitting in a file the
+  human may open reads as though data were still leaving the machine. Say you removed it.
 - **Kanban sync** (§Reconcile step 6): resolve this project's board with
   `<core>/pipeline/scripts/kanban-move.sh --check` — it prints either the board path or the exact
   missing link. **Not linked** → offer to link/create a board (confirm the vault + `<folder>/Tasks.md`,
@@ -125,5 +126,5 @@ Four of the §Reconcile steps matter specifically here:
   `/cohorte-update-pipeline` inside each (it will skip the already-done core update and just reconcile).
 - **Commit** the reconciled files (`PIPELINE.md`, `.claude/`, `.mcp.json` if added) so teammates get them.
 - The kanban config is global and user-scoped
-  (`~/.claude/cohorte.config.yaml`) — never committed. The core update never touches it; only the
+  (`<config>`) — never committed. The core update never touches it; only the
   reconcile above seeds the file and writes kanban board links (into that global file, not the repo).

package/core/hooks/gate.py

@@ -40,6 +40,33 @@ Two extra duties beyond Bash patterns:
 
 Protocol: reads the PreToolUse payload on stdin; emits a JSON permissionDecision
 of "deny" or "ask" on a match; otherwise exits 0 silently.
+
+Four runtimes can run this as a real blocking hook, and they disagree on the envelope —
+`--runtime <id>` (passed by the installer when it registers the hook) selects the dialect:
+
+    claude    PreToolUse           {"hookSpecificOutput": {"permissionDecision": "deny"|"ask", …}}
+    codex     PreToolUse           same envelope, but `ask` is parsed and NOT honoured
+    cursor    beforeShellExecution {"permission": "deny"|"ask", "user_message", "agent_message"}
+    gemini    BeforeTool           {"decision": "deny", "reason": …}         (no ask tier)
+
+Where a runtime has no `ask`, an `ask` verdict is escalated to `deny` with the reason
+attached rather than downgraded to allow: the whole point of the tier is that a human sees
+the command before it runs, and a runtime that cannot ask cannot deliver that — so the safe
+translation is to refuse and let the human re-run it deliberately. Same rule the
+bypassPermissions escalation has always used.
+
+Explicit mode (`--check`) — for OpenCode, whose extension point is plugins rather than a
+blocking hook. Same config, same patterns, same verdicts; the difference is who calls it.
+There the rendered commands instruct the agent to run the check itself before a gated
+command or a phase dispatch:
+
+    gate.py --check "git push --force"      # a Bash command
+    gate.py --check-dispatch review         # the preflight phase gate
+
+It prints ONE line (`gate: allow` / `gate: ask — <reason>` / `gate: deny — <reason>`)
+and exits 0 / 1 / 2 so a shell can branch on it. This is advisory by construction — an
+agent can decline to call it, which a hook makes impossible — so /cohorte-doctor reports
+the gate as "advisory" on those runtimes rather than pretending parity.
 """
 
 import json
@@ -54,13 +81,37 @@ import time
 SPLIT = re.compile(r"&&|\|\||[;|\n]")
 WS = re.compile(r"\s+")
 
+# How far to backdate the throwaway index in tree_digest(), in seconds. Anything modified
+# within this window of the digest is re-hashed by content instead of trusted from its cached
+# stat data. Must stay ≥ the filesystem's mtime granularity (1 s on ext4/HFS+); 5 s covers a
+# clock that ticks backwards a little without costing anything on a quiet tree.
+RACY_WINDOW_S = 5
+
 
 def project_root() -> str:
-    return os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    return os.environ.get("COHORTE_PROJECT_DIR") or os.environ.get("CLAUDE_PROJECT_DIR", ".")
+
+
+# The generated per-project files (gate config + preflight stamp) live under `.claude/`
+# on a Claude install and `.cohorte/` on every other runtime. Probe both, newest layout
+# first, so one gate serves a repo whichever agent is driving it — and so a repo that
+# adds a second runtime doesn't end up with two configs, one of them silently unread.
+STATE_DIRS = (".cohorte", ".claude")
+
+
+def state_path(name: str) -> str:
+    """Path to a per-project pipeline file: the first layout that has it, else `.claude`
+    (the historical default, so a fresh write lands where existing tooling looks)."""
+    root = project_root()
+    for d in STATE_DIRS:
+        p = os.path.join(root, d, name)
+        if os.path.exists(p):
+            return p
+    return os.path.join(root, ".claude", name)
 
 
 def load_config() -> dict:
-    path = os.path.join(project_root(), ".claude", "gate-config.json")
+    path = state_path("gate-config.json")
     empty = {"deny": [], "ask": [], "ask_on_default_branch": [], "default_branch": "main",
              "preflight": {}}
     try:
@@ -187,7 +238,7 @@ def worktree_dirs(cwd: str):
 
 def tree_digest(cwd: str):
     """The digest pipeline/scripts/preflight.sh stamps for the checkout at `cwd`: the git
-    tree id of the working tree, computed in a throwaway index (`.claude` and `specs`
+    tree id of the working tree, computed in a throwaway index (`.claude`, `.cohorte` and `specs`
     excluded — the pipeline writes those itself). Content-addressed, so a commit of the
     same code keeps the stamp valid and any real edit invalidates it. Must stay identical
     to the shell side. Returns None when git can't answer, and the caller falls back."""
@@ -206,17 +257,29 @@ def tree_digest(cwd: str):
         # what changed instead of the whole tree on every dispatch.
         if os.path.exists(real_index):
             shutil.copyfile(real_index, tmp)
+            # Age the copy by a few seconds. Git trusts an entry's cached stat data only when
+            # the entry's mtime is OLDER than the index file's; entries at or after it are
+            # "racily clean" and get re-hashed by content. copyfile stamps the temp index with
+            # `now`, so a file edited in the same second as the preflight — with an unchanged
+            # size — looked clean here and the gate greened code that had changed. Backdating
+            # forces a content check for anything touched inside that window, and leaves the
+            # stat-cache fast path (the whole point of seeding from the real index) intact for
+            # every older file.
+            old = time.time() - RACY_WINDOW_S
+            os.utime(tmp, (old, old))
         else:
             os.unlink(tmp)  # a 0-byte index is a corrupt index — let git create it
         env = dict(os.environ, GIT_INDEX_FILE=tmp)
         # Drop the excluded paths outright — an `add` exclude only stops them being
         # *updated*, so already-tracked ones would still shift the tree id.
         subprocess.run(
-            ["git", "rm", "--cached", "-r", "-q", "--ignore-unmatch", "--", ".claude", "specs"],
+            ["git", "rm", "--cached", "-r", "-q", "--ignore-unmatch", "--",
+             ".claude", ".cohorte", "specs"],
             cwd=cwd, capture_output=True, timeout=10, env=env,
         )
         add = subprocess.run(
-            ["git", "add", "-A", "--", ".", ":(exclude).claude", ":(exclude)specs"],
+            ["git", "add", "-A", "--", ".",
+             ":(exclude).claude", ":(exclude).cohorte", ":(exclude)specs"],
             cwd=cwd, capture_output=True, timeout=30, env=env,
         )
         if add.returncode != 0:
@@ -250,11 +313,17 @@ def check_preflight(payload: dict, cfg: dict) -> int:
     if not pf.get("enabled"):
         return 0
     agents = pf.get("agents") or ["review"]
+    # Runtimes name a subagent dispatch differently. Claude Code and Cursor send a `Task` tool
+    # carrying `subagent_type`; Gemini exposes each subagent as a tool of the SAME NAME, so the
+    # dispatch arrives as `tool_name: review`. Accept both rather than gating only the shape
+    # one vendor happens to use — a phase gate that silently never fires is the 1.3.0 bug.
     subagent = (payload.get("tool_input") or {}).get("subagent_type", "") or ""
+    if not subagent and payload.get("tool_name") in agents:
+        subagent = payload.get("tool_name")
     if subagent not in agents:
         return 0
 
-    stamp = os.path.join(project_root(), ".claude", "preflight.ok")
+    stamp = state_path("preflight.ok")
     why = None
     try:
         with open(stamp, "r", encoding="utf-8") as fh:
@@ -300,20 +369,65 @@ def check_preflight(payload: dict, cfg: dict) -> int:
     )
 
 
-def main() -> int:
-    try:
-        payload = json.load(sys.stdin)
-    except Exception:
-        return 0  # malformed input → don't block
-
-    tool = payload.get("tool_name")
+def check_cli(argv) -> int:
+    """Explicit gate for runtimes with no PreToolUse hook.
+
+    Builds the same payload the hook would have received and runs the same evaluation,
+    then translates the verdict into a line + exit code a shell (or an agent reading the
+    output) can act on. Exit 0 = allow, 1 = ask, 2 = deny — chosen so `&&` naturally
+    stops on anything that isn't a clean allow."""
+    mode = argv[0]
+    unattended = False
+    cwd = os.getcwd()
+    words = []
+    i = 1
+    while i < len(argv):
+        a = argv[i]
+        if a == "--unattended":
+            unattended = True
+        elif a == "--cwd" and i + 1 < len(argv):
+            cwd = argv[i + 1]
+            i += 1
+        elif a.startswith("--cwd="):
+            cwd = a[6:]
+        else:
+            words.append(a)
+        i += 1
+    subject = " ".join(words).strip()
+    if not subject:
+        print(f"gate: usage — gate.py {mode} <{'command' if mode == '--check' else 'agent'}>",
+              file=sys.stderr)
+        return 2
+
+    payload = {"cwd": cwd, "permission_mode": "bypassPermissions" if unattended else "default"}
+    if mode == "--check":
+        payload["tool_name"] = "Bash"
+        payload["tool_input"] = {"command": subject}
+    else:
+        payload["tool_name"] = "Task"
+        payload["tool_input"] = {"subagent_type": subject}
+
+    # Reuse the hook path verbatim — one evaluator, so the two modes can never drift into
+    # different verdicts on the same config. `decide()` records instead of printing while
+    # DECISIONS is armed, so the hook's JSON never leaks into the human-readable output.
+    global DECISIONS
+    DECISIONS = []
     cfg = load_config()
+    if payload["tool_name"] == "Task":
+        check_preflight(payload, cfg)
+    else:
+        check_bash(payload, cfg)
 
-    if tool == "Task":
-        return check_preflight(payload, cfg)
-    if tool != "Bash":
+    if not DECISIONS:
+        print("gate: allow")
         return 0
+    decision, reason = DECISIONS[0]
+    print(f"gate: {decision} — {reason}")
+    return 2 if decision == "deny" else 1
+
 
+def check_bash(payload: dict, cfg: dict) -> int:
+    """Pattern gate on a Bash command. Split out of main() so --check reuses it."""
     command = (payload.get("tool_input") or {}).get("command", "") or ""
     deny, ask, branch_gated = cfg["deny"], cfg["ask"], cfg["ask_on_default_branch"]
     default = cfg["default_branch"]
@@ -368,7 +482,80 @@ def main() -> int:
     return 0
 
 
+def main() -> int:
+    argv = sys.argv[1:]
+    if argv and argv[0] in ("--check", "--check-dispatch"):
+        return check_cli(argv)
+
+    global RUNTIME
+    for i, a in enumerate(argv):
+        if a == "--runtime" and i + 1 < len(argv):
+            RUNTIME = argv[i + 1]
+        elif a.startswith("--runtime="):
+            RUNTIME = a[10:]
+
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        return 0  # malformed input → don't block
+
+    tool = payload.get("tool_name")
+    # Cursor's shell hook carries the command at the top level rather than in tool_input, and
+    # names no tool. Normalise once here so every check below stays runtime-agnostic.
+    if RUNTIME == "cursor" and not tool:
+        tool = "Bash"
+        payload = dict(payload, tool_name="Bash",
+                       tool_input=payload.get("tool_input") or {"command": payload.get("command", "")})
+    cfg = load_config()
+
+    # A dispatch, in whichever shape this runtime sends it (see check_preflight).
+    if tool == "Task" or tool in ((cfg.get("preflight") or {}).get("agents") or ["review"]):
+        return check_preflight(payload, cfg)
+    # Bash is Claude's/Codex's name for the shell tool; Gemini calls it run_shell_command, and
+    # Cursor's beforeShellExecution was normalised to "Bash" above. Anything else is not a
+    # command we gate.
+    if tool not in ("Bash", "shell", "run_shell_command"):
+        return 0
+    return check_bash(payload, cfg)
+
+
+# Armed by --check: while it is a list, decide() records the verdict instead of emitting
+# a hook envelope, which only a hook host understands.
+DECISIONS = None
+
+# Which runtime is hosting this hook — set from `--runtime <id>`. Defaults to Claude Code:
+# it is the only host that ran this file before the flag existed, so an old registration
+# that predates the adapter keeps behaving exactly as it did.
+RUNTIME = "claude"
+
+# Runtimes whose hook contract has no "ask" tier. Codex parses `permissionDecision: ask` and
+# ignores it — which would let a gated command through — and Gemini's BeforeTool only
+# allows or denies. Escalate rather than downgrade: see the module docstring.
+NO_ASK = {"codex", "gemini"}
+
+
 def decide(decision: str, reason: str) -> int:
+    if DECISIONS is not None:
+        DECISIONS.append((decision, reason))
+        return 0
+
+    if decision == "ask" and RUNTIME in NO_ASK:
+        decision = "deny"
+        reason += (f" (denied outright: {RUNTIME} has no confirmation tier, so an \"ask\" here "
+                   f"would silently run. Re-run it yourself if you meant to.)")
+
+    if RUNTIME == "cursor":
+        # Cursor's own envelope. `agent_message` is what the model is told, `user_message`
+        # what the human sees — the reason serves both.
+        print(json.dumps({"permission": decision, "user_message": reason, "agent_message": reason}))
+        return 2 if decision == "deny" else 0
+
+    if RUNTIME == "gemini":
+        # BeforeTool speaks {"decision", "reason"}; anything else is read as allow.
+        print(json.dumps({"decision": decision, "reason": reason}))
+        return 0
+
+    # Claude Code and Codex share the PreToolUse envelope.
     print(
         json.dumps(
             {

package/core/runtimes/claude.json

@@ -0,0 +1,73 @@
+{
+  "id": "claude",
+  "label": "Claude Code",
+  "docs": "https://docs.claude.com/en/docs/claude-code/slash-commands",
+  "detect": [
+    "~/.claude",
+    "~/.config/claude"
+  ],
+  "scopes": {
+    "global": {
+      "root": "~/.claude",
+      "core": "~/.claude",
+      "commands": "~/.claude/commands",
+      "agents": "~/.claude/agents",
+      "hooks": "~/.claude/hooks",
+      "workflows": "~/.claude/workflows",
+      "settings": "~/.claude/settings.json",
+      "hooks_config": "~/.claude/settings.json"
+    },
+    "project": {
+      "root": ".claude",
+      "core": ".claude",
+      "commands": ".claude/commands",
+      "agents": ".claude/agents",
+      "hooks": ".claude/hooks",
+      "workflows": ".claude/workflows",
+      "settings": ".claude/settings.json",
+      "hooks_config": ".claude/settings.json"
+    }
+  },
+  "exclude_commands": [],
+  "command": {
+    "format": "md",
+    "ext": ".md",
+    "frontmatter": [
+      "model",
+      "description",
+      "argument-hint",
+      "allowed-tools",
+      "disable-model-invocation"
+    ],
+    "args": "$ARGUMENTS",
+    "invoke": "/<name>"
+  },
+  "agent": {
+    "format": "md",
+    "frontmatter": [
+      "name",
+      "description",
+      "tools",
+      "model"
+    ],
+    "dispatch": "Task tool, subagent_type: <name>",
+    "address": "<name>",
+    "ext": ".md"
+  },
+  "capabilities": {
+    "subagents": true,
+    "hooks": true,
+    "workflows": true,
+    "mcp": true,
+    "tool_restriction": true
+  },
+  "memory": "CLAUDE.md",
+  "headless": "claude -p",
+  "hook": {
+    "format": "claude",
+    "event": "PreToolUse",
+    "matcher": "Bash|Task",
+    "supports_ask": true,
+    "config_shape": "settings"
+  }
+}

package/core/runtimes/codex.json

@@ -0,0 +1,82 @@
+{
+  "id": "codex",
+  "label": "Codex CLI (OpenAI)",
+  "docs": "https://learn.chatgpt.com/docs/build-skills",
+  "detect": [
+    "~/.codex"
+  ],
+  "notes": [
+    "Commands ship as SKILLS (.agents/skills/<name>/SKILL.md), not as custom prompts. Prompts are",
+    "deprecated, and they are user-scoped only (~/.codex/prompts) \u2014 so a teammate cloning the repo",
+    "would get the profile but none of the commands. Skills are discovered from `.agents/skills` in",
+    "the repo, which means they travel with it. Invoked as $<name>, or implicitly from `description`.",
+    "Skills do NOT substitute arguments, so the preamble explains $ARGUMENTS rather than rewriting it.",
+    "Subagents are TOML, one file per agent, and the body lives in `developer_instructions`.",
+    "Hooks use the SAME PreToolUse envelope as Claude Code, with one difference that matters:",
+    "`permissionDecision: ask` is parsed but not honoured, so gate.py escalates ask to deny here.",
+    "Model pins are NOT carried across: the profile names Anthropic aliases (sonnet/haiku), which are meaningless here and would either error or be silently ignored. Agents and commands inherit this runtime's own model selection instead."
+  ],
+  "scopes": {
+    "global": {
+      "root": "~/.codex",
+      "core": "~/.cohorte/codex",
+      "commands": "~/.agents/skills",
+      "agents": "~/.codex/agents",
+      "hooks": "~/.cohorte/codex/hooks",
+      "hooks_config": "~/.codex/hooks.json",
+      "workflows": null,
+      "settings": null
+    },
+    "project": {
+      "root": ".codex",
+      "core": ".cohorte/codex",
+      "commands": ".agents/skills",
+      "agents": ".codex/agents",
+      "hooks": ".cohorte/codex/hooks",
+      "hooks_config": ".codex/hooks.json",
+      "workflows": null,
+      "settings": null
+    }
+  },
+  "exclude_commands": [],
+  "command": {
+    "format": "skill",
+    "ext": "/SKILL.md",
+    "frontmatter": [
+      "name",
+      "description"
+    ],
+    "args": null,
+    "args_note": "the text you typed after the skill name",
+    "invoke": "$<name>"
+  },
+  "agent": {
+    "format": "toml",
+    "ext": ".toml",
+    "body_key": "developer_instructions",
+    "frontmatter": [
+      "name",
+      "description"
+    ],
+    "readonly_key": "sandbox_mode",
+    "readonly_value": "read-only",
+    "dispatch": "spawn the named agent; several run in parallel and Codex returns a consolidated result",
+    "address": "<name>"
+  },
+  "hook": {
+    "format": "claude",
+    "event": "PreToolUse",
+    "matcher": "Bash|shell",
+    "supports_ask": false,
+    "config_shape": "json"
+  },
+  "capabilities": {
+    "subagents": true,
+    "hooks": true,
+    "workflows": false,
+    "mcp": true,
+    "tool_restriction": true
+  },
+  "memory": "AGENTS.md",
+  "headless": "codex exec"
+}