@soleur/opencode 0.0.0-stage → 1.0.0

package/commands/version.md

@@ -0,0 +1,103 @@
+---
+name: version
+description: "Show the installed Soleur plugin version and whether a newer release exists"
+argument-hint: ""
+disable-model-invocation: true
+---
+
+# Soleur Version
+
+Report which Soleur plugin version is installed, what the latest release is, and how to update. Run the shared resolver; never guess or infer a version yourself. This command is Claude Code only and is started by the user; it is not run automatically.
+
+This explicit run contacts github.com regardless of `SOLEUR_UPDATE_CHECK`, because you asked: one `git ls-remote --tags` against the public repo and, for a commit-hash or local-checkout install only, one unauthenticated GitHub compare API request whose URL includes the installed commit hash (for a local checkout that is the checkout's current commit, which may be one you have never pushed anywhere). It uses no tokens, no user git config and no credentials of its own (any proxy you configured in your environment is still used), and each request is time-limited.
+
+## Step 1: Run the resolver
+
+Run via the **Bash tool**:
+
+```bash
+if grep -q '"name"[[:space:]]*:[[:space:]]*"soleur"' "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" 2>/dev/null; then
+  if [ -f "${CLAUDE_PLUGIN_ROOT}/scripts/plugin-version.sh" ]; then
+    bash "${CLAUDE_PLUGIN_ROOT}/scripts/plugin-version.sh" --compare --refresh
+  else
+    echo "source=unknown"
+  fi
+else
+  echo "source=unknown"
+fi
+```
+
+If `CLAUDE_PLUGIN_ROOT` is not set or the script does not exist at that path, do not look for it anywhere else (a script from the current directory is not trusted): print `Installed:  unknown` and stop. The output is `key=value` lines: `source`, `version`, `commit`, `marketplace`, `cache`, `latest_status`, `latest`, `latest_commit`, `relation`, `reason`, `cache_dir`. Use only these values. `source=checkout` means the plugin is loaded in place from a local git checkout (a local-folder marketplace or `--plugin-dir`); `commit` is that checkout's HEAD commit, read from its files without running git.
+
+## Step 2: Print this block
+
+Print the block below, filling it from the resolver output. Keep it compact, no emoji.
+
+```text
+Soleur plugin version
+
+Installed:  <version, or "commit <sha12>", or "commit <sha12> (local checkout, HEAD commit, not uncommitted or unsynced files)">  (source: <manifest | commit | checkout>)
+Latest:     <latest, e.g. v3.4.5>   (or the WHY line from the rules below)
+Status:     <one status line from the rules below>
+
+Update (Claude Code):
+  <for source=checkout: the local-folder steps from "Update commands" below, never the GitHub marketplace pair>
+  <otherwise: the two commands from "Update commands" below>
+  Restart the CLI afterwards; plugin changes apply on restart.
+
+Session-start newer-release check (off by default): the version line itself is shown at
+every session start with no network. To also check for a newer release, set
+SOLEUR_UPDATE_CHECK=1 in your user-level Claude Code settings "env" block (not a checked-in
+project settings file, and not in CI or ephemeral containers); remove it to turn it off.
+```
+
+### Installed line
+
+- `source=manifest`: print `version`.
+- `source=commit`: print `commit <commit>` (the 12-character hash). Do not invent a version number for it.
+- `source=checkout`: print `commit <commit> (local checkout, HEAD commit, not uncommitted or unsynced files)` exactly as the template shows it (`<commit>` is the 12-character hash of the HEAD commit of the git checkout that contains the plugin folder, read from its files without running git). Do not invent a version number for it.
+- `source=unknown`, `source=none`, or any value other than `manifest`, `commit` and `checkout`: print `Installed:  unknown`, omit the `Update (Claude Code):` block, and say the plugin root could not be identified (not running from an installed plugin, a recognizable cache directory, or a local git checkout whose HEAD could be read: an unborn branch, a reftable or sha-256 repository or an unusual layout reads as unknown); tell the user they can compare with `claude plugin list` (you do not run it). Do not print a version.
+
+### Latest line (explain WHY when missing)
+
+When `latest=` is present, print it. Label it "(cached, may be out of date)" whenever `cache=stale` or `latest_status` is `offline` or `timeout`. When `latest=` is absent, print the first matching reason, never a blank:
+
+1. `latest_status=offline`: "Could not reach github.com (offline or blocked)."
+2. `latest_status=timeout`: "The lookup timed out."
+3. `latest_status=no-git`: "`git` is not installed, so the release lookup was skipped."
+4. `latest_status=no-tags`: "github.com answered but returned no release tags."
+5. `cache=corrupt`: "The version cache is unreadable; it is rewritten on the next successful lookup." (the file is `latest-release.<install id>` under `cache_dir`, or `latest-release.checkout` for a local checkout).
+6. Anything else: "The latest release could not be determined."
+
+### Status line (compare result)
+
+Read `relation` and `reason`:
+
+- `relation=older`: "A newer release exists."
+- `relation=current`: "No release newer than yours (latest tag vX.Y.Z)", with the `latest` value. This means only that no release tag newer than the installed commit or version was found. Never say "up to date" or "you are on the latest release".
+- `relation=unknown`: "Cannot compare" plus the reason: `installed-unknown` (the installed version could not be read), `diverged` (the installed commit is not on the release line), `compare-failed` or `compare-unparseable` (the GitHub compare call failed; a local checkout may also be on a commit that was never published), `no-curl` (curl is missing), `stale-cache` (the answer came from a cached or failed lookup, so it is not trusted; run this command again when online), `cache-invalid` (the cached answer was unusable; run this command again).
+- `relation` absent (no latest release is known): "Cannot compare: the latest release is not known", followed by the `latest_status` reason from the Latest line rules.
+
+Never say "up to date" when the relation is unknown or absent, and never infer a relation by comparing strings yourself.
+
+### Update commands
+
+Choose by `source` first, then (for `manifest` and `commit` only) by the `marketplace` value:
+
+- `source=checkout` (in place from a local git checkout; use this arm whatever `marketplace` says, and never print the GitHub marketplace pair for it, which would replace the in-place install with a published copy). **Print these steps for the user to run; never run any of them yourself** (no `git`, no `claude`, no `gh`). The marketplace is the local folder and is named `soleur`. Tell the user how to tell the two layouts apart: `git -C <folder> rev-parse --is-bare-repository` prints `true` for a bare layout (`<folder>` is the Source path in `claude plugin marketplace list`, or the `--plugin-dir` path).
+  1. Update the folder. Bare layout (`true`, files mirrored on disk): in the repository root run `git fetch --no-tags origin main:main`; if git refuses because `main` is checked out in a worktree, commit or stash there and run `git pull --ff-only origin main` inside that worktree instead (never force-move `main`: that can orphan unpushed commits). Then run `plugins/soleur/skills/git-worktree/scripts/worktree-manager.sh sync`, which mirrors the repository's HEAD to the files on disk (it overwrites tracked files there and does not fetch). Normal clone (`false`): update the branch you run from, for example `git pull --ff-only`.
+  2. If the plugin was added as a local-folder marketplace (the usual case): `claude plugin marketplace update soleur` then `claude plugin update soleur@soleur`, then restart. If it was started with `--plugin-dir <path>`, skip this step (no marketplace command applies) and just restart.
+  The resolver cannot tell those two launch modes apart, so print both lines, each labelled. If the plugin folder is vendored inside another project's repository, the identity shown is that project's HEAD and these steps do not update the vendored copy.
+- `source=manifest` or `source=commit`, with `marketplace` absent or `soleur-marketplace`:
+  `claude plugin marketplace update soleur-marketplace` then `claude plugin update soleur@soleur-marketplace`
+- `soleur`:
+  `claude plugin marketplace update soleur` then `claude plugin update soleur@soleur`
+- any other value: print the same pair with that marketplace name substituted.
+
+If the install is project-scoped (`claude plugin list` shows Scope), add `--scope project` to the update command. See `knowledge-base/engineering/operations/runbooks/plugin-delivery-recovery.md` if an update says "already at the latest version" but nothing changes.
+
+## Output Rules
+
+- Print only values the resolver returned or the fixed text above; never report a version you did not read.
+- Do not run `gh`, `curl`, `git` or `claude` yourself; the resolver owns every network call.
+- If the Bash tool is unavailable, say so and print only `Installed:` from the plugin root directory name if it is a 12-character hex commit hash; otherwise print `unknown`.

package/hooks/antigravity-hooks.json

@@ -0,0 +1,84 @@
+{
+  "description": "Soleur plugin hooks for Antigravity CLI",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^(run_command|Bash|exec)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${SOLEUR_PLUGIN_ROOT}/hooks/browser-snapshot-credential-guard.sh\""
+          }
+        ]
+      },
+      {
+        "matcher": "^(run_command|write_to_file|replace_file_content|Bash|Monitor|Write|Edit|MultiEdit|NotebookEdit)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${SOLEUR_PLUGIN_ROOT}/hooks/operator-stage-approval.sh\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "^(run_command|Bash)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${SOLEUR_PLUGIN_ROOT}/hooks/destructive-command-guard.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${SOLEUR_PLUGIN_ROOT}/hooks/antigravity-session-start.sh\""
+          }
+        ]
+      },
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${SOLEUR_PLUGIN_ROOT}/hooks/welcome-hook.sh\""
+          }
+        ]
+      },
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${SOLEUR_PLUGIN_ROOT}/hooks/version-banner.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${SOLEUR_PLUGIN_ROOT}/hooks/stop-hook.sh\""
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${SOLEUR_PLUGIN_ROOT}/hooks/unkept-promise-hook.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/antigravity-session-start.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+[[ -n "${ANTIGRAVITY_CLI:-}" || -n "${AGY_VERSION:-}" || -n "${GEMINI_CLI:-}" || -n "${PLUGIN_ROOT:-}" ]] || exit 0
+SOLEUR_PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+# Run session start worktree cleanup if available
+if [[ -f "$SOLEUR_PLUGIN_ROOT/skills/git-worktree/scripts/worktree-manager.sh" ]]; then
+  bash "$SOLEUR_PLUGIN_ROOT/skills/git-worktree/scripts/worktree-manager.sh" cleanup-merged 2>/dev/null || true
+fi
+
+jq -n --arg root "$SOLEUR_PLUGIN_ROOT" \
+  --rawfile instructions "$SOLEUR_PLUGIN_ROOT/antigravity/INSTRUCTIONS.md" \
+  '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext:
+    ("Soleur plugin root: " + $root + "\n" + $instructions)}}'

package/hooks/bare-root-cwd-guard.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# bare-root-cwd-guard.sh — PLUGIN-level SessionStart arm for the row-3 bare-repo-root
+# misanchor (#10392). Same basename as .claude/hooks/bare-root-cwd-guard.sh on purpose:
+# the dual-home naming convention lets the tree disambiguate the two arms (CTO ruling
+# 2026-10-20). The repo arm reaches only this repo's sessions; THIS arm ships in the
+# plugin payload and so reaches every other repository on a machine that installs it.
+#
+# Contract: always exits 0. On detection it emits exactly one SessionStart envelope
+#   {"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext": …}}
+# whose additionalContext carries one `SOLEUR_BARE_ROOT_CWD source=plugin-session-start`
+# marker line followed by a bounded [bare-root-cwd] redirect block. Every other path —
+# no jq, no .cwd, non-bare cwd, deduped repo — prints NOTHING: a SessionStart hook that
+# cannot emit valid JSON must emit nothing.
+#
+# cwd resolution: the envelope's `.cwd` first (jq-gated; some harnesses omit it), then
+# DEVIN_PROJECT_DIR → CLAUDE_PROJECT_DIR → $PWD.
+#
+# Detection is the SAME three-term config-FILE predicate as the repo arm, the
+# bare-head-self-heal copy, and the copy inlined in
+# plugins/soleur/skills/git-worktree/scripts/git-repo-readiness-diag.sh —
+# plugins/soleur/test/git-repo-readiness-diag.test.sh D5 pins the three-way parity:
+#   1. `root` is a repo ROOT in the ADR-099 row-3 layout: `<root>/.git` is a real
+#      directory (not a file or symlink — a `gitdir:` redirect, a linked worktree, and
+#      a symlinked .git all fail here), `core.bare` reads `true` from its config FILE
+#      (never `--is-bare-repository`: ADR-173 records that a masked config reports true
+#      for any normal clone — the exact false-positive #10392 forbids), and
+#   2. `--absolute-git-dir` resolves to exactly that directory.
+# A `git init --bare` repo (mirror, server repo) fails term 1 — its git dir IS the
+# root, there is no `<root>/.git` — so a genuinely bare customer repo never gets a
+# misapplied redirect (P2). A session in a real worktree exits earlier on
+# `--show-toplevel`, which also keeps a bare-root SUBDIRECTORY silent: that narrowing
+# is deliberate (go.md's --is-bare-repository routing guard is the in-bare-subdir
+# backstop).
+#
+# Dedup (CTO ruling 2026-10-20): when the target repo already carries its own arm —
+# BOTH a `SOLEUR_BARE_ROOT_CWD` marker under `.claude/hooks/*.sh` AND a settings/devin
+# registry referencing `session-rules-loader.sh` — the repo arm reports the session and
+# this arm stays silent. A vendored-but-unwired tree hits term 1 only, so this arm still
+# fires there; over-suppression is the worse failure direction.
+#
+# Redirect text is topology-generic (`git worktree add`) — a customer repo does not
+# carry this repo's .worktrees/ machinery. A soleur `worktree-manager.sh` hint line is
+# appended ONLY when the plugin-side script exists.
+#
+# No `set -e`, by design: every step is an explicit `|| exit 0`.
+set -uo pipefail
+
+# jq gates everything: it parses the incoming envelope AND emits the outgoing one, so
+# without it the only correct behavior is silence.
+command -v jq >/dev/null 2>&1 || exit 0
+
+# An inherited git-location variable overrides `cd` and `git -C` alike, and would aim
+# every probe below at a different repository than the one named (same unset list as
+# the repo arm and the readiness-diag copy — the parity suite pins the GIT_DIR arm).
+unset GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_INDEX_FILE GIT_OBJECT_DIRECTORY \
+  GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_NAMESPACE
+
+# Shared context sanitizer (#10395): the emitted path enters agent context, so the
+# strip runs through the lib when it is readable. Plugin-side copy lives under
+# scripts/lib/ (the plugin ships only plugins/soleur/**); the repo-side copy lives at
+# .claude/hooks/lib/ and is byte-equal (context-sanitize.test.sh pins `cmp`).
+_plugin_hooks_dir=$(cd -P "${BASH_SOURCE[0]%/*}" 2>/dev/null && pwd -P) || exit 0
+_ctx_lib="$_plugin_hooks_dir/../scripts/lib/context-sanitize.sh"
+# shellcheck source=/dev/null
+[[ -r "$_ctx_lib" ]] && . "$_ctx_lib" || true
+unset _ctx_lib _plugin_hooks_dir
+if ! declare -F soleur_ctx_sanitize >/dev/null 2>&1; then
+  # Fallback — identical byte contract to the lib (C0 + DEL + NEL/LS/PS) so an
+  # unreadable lib degrades to the same strip, never to zero protection. Octal
+  # \177 for DEL: tr does not interpret \xHH. $'…' ANSI-C quoting is REQUIRED on
+  # the sed patterns: BSD sed does not interpret bare '\xHH' and would silently
+  # strip nothing.
+  soleur_ctx_sanitize() {
+    LC_ALL=C tr -d '\000-\037\177' \
+      | LC_ALL=C sed -e $'s/\xc2\x85//g' -e $'s/\xe2\x80\xa8//g' -e $'s/\xe2\x80\xa9//g'
+  }
+fi
+
+input=$(cat 2>/dev/null || true)
+cwd=$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null || true)
+if [[ -z "$cwd" ]]; then
+  cwd="${DEVIN_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-$PWD}}"
+fi
+[[ -n "$cwd" ]] || exit 0
+cd -- "$cwd" 2>/dev/null || exit 0
+root=$(pwd -P) || exit 0
+
+# A worktree answers --show-toplevel; only a bare shape falls through to the
+# predicate. This is a worktree test, never a bareness test (Sharp Edges).
+[[ -n "$(git rev-parse --show-toplevel 2>/dev/null)" ]] && exit 0
+
+# Three-term ADR-099 row-3 predicate — fourth inline copy, parity-pinned.
+[[ -d "$root/.git" && ! -L "$root/.git" ]] || exit 0
+[[ "$(git config --file "$root/.git/config" --type=bool --get core.bare 2>/dev/null)" == "true" ]] || exit 0
+git_dir=$(git rev-parse --absolute-git-dir 2>/dev/null) || exit 0
+[[ "$git_dir" == "$root/.git" ]] || exit 0
+
+# Dedup: the repo's own arm reports when it is BOTH present and wired. `grep -l` on
+# the glob is the bounded, read-only probe; an unmatched glob or an absent registry
+# file simply fails the term and this arm still fires.
+if grep -lF 'SOLEUR_BARE_ROOT_CWD' "$root"/.claude/hooks/*.sh >/dev/null 2>&1 \
+  && { grep -qs 'session-rules-loader\.sh' "$root/.claude/settings.json" 2>/dev/null \
+    || grep -qs 'session-rules-loader\.sh' "$root/.devin/config.json" 2>/dev/null; }; then
+  exit 0
+fi
+
+# Sanitize the path for context: envelope-supplied, so strip control characters
+# (incl. DEL, NEL, and the U+2028/U+2029 line-break class — #10395) and cap it.
+safe_root=$(printf '%s' "$root" | soleur_ctx_sanitize | cut -c1-200)
+
+block="SOLEUR_BARE_ROOT_CWD source=plugin-session-start
+[bare-root-cwd] ${safe_root} is a bare repository root with a synced overlay of HEAD, not a worktree.
+[bare-root-cwd] Route file-touching work through a linked worktree:
+[bare-root-cwd]   git worktree add <path> <branch>
+[bare-root-cwd] then cd into the new worktree path before editing.
+[bare-root-cwd] A .env at this root is NOT project configuration — do not read it as one."
+
+# Soleur-hint line — gated on the plugin-side script existing on this machine
+# (CTO ruling: the manager ships in the plugin payload, but the text is only
+# emitted where it can actually run).
+if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" \
+  && -f "${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh" ]]; then
+  safe_wm=$(printf '%s' "${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh" \
+    | soleur_ctx_sanitize | cut -c1-300)
+  block+=$'\n'"[bare-root-cwd] Soleur worktree manager present: bash \"${safe_wm}\" --yes create <name>"
+fi
+
+jq -n --arg ctx "$block" \
+  '{hookSpecificOutput:{hookEventName:"SessionStart",additionalContext:$ctx}}' 2>/dev/null \
+  || exit 0
+exit 0

package/hooks/browser-snapshot-credential-guard.sh

@@ -0,0 +1,200 @@
+#!/usr/bin/env bash
+# PreToolUse hook on Bash.
+# Denies an `agent-browser ... snapshot` that is not routed through the
+# accessibility-snapshot redactor.
+#
+# WHY (#7947, measured -- see
+# knowledge-base/project/specs/feat-one-shot-7946-7947-sentry-org-token-and-snapshot-redaction/phase-0-measurement.md):
+# an accessibility snapshot serializes the VALUE of input fields. A value the
+# agent never supplied -- a password manager's autofill, a static value=, a JS
+# assignment, or a generated-credential panel -- is rendered into the transcript
+# and into any snapshot file written to disk. Nothing about the call looks
+# credential-adjacent: the natural reason to snapshot a login page is to find
+# out whether the flow advanced.
+#
+# Measured, and this is why the hook exists rather than a prose rule:
+#   * agent-browser 0.22.3 masks type=password (bullets) but renders a readonly
+#     type=text credential panel -- the "Token" class -- in CLEAR. That class
+#     has already fired in this repo (2026-05-19 Sentry token scope probe).
+#   * The Playwright MCP renders BOTH in clear.
+#
+# This hook covers the Bash path only. Property P7 ("the guards hold without the
+# acting agent having to remember them") holds on the Bash path via this
+# interceptor AND on a Playwright-MCP registration routed through
+# skills/agent-browser/scripts/playwright-mcp-redact-proxy.py (#7980), which
+# rewrites every tool result through the same redactor at the stdio boundary.
+# An unwrapped Playwright-MCP registration remains uncovered — #8156 shipped
+# the plugin's own wrapped registration (mcp__plugin_soleur_playwright__*), but
+# a customer's OWN playwright entry is still exactly as wrapped as they
+# configured it; the transcript-sink closer for that surface is Option C,
+# deferred at #8286. That gap is stated rather than implied.
+#
+# Disposition is DENY, not rewrite: ADR-162 permits exactly one PreToolUse
+# rewriter and grep-rewrite.sh holds it. Two hooks emitting updatedInput for the
+# same call have undefined precedence and one rewrite is silently discarded.
+#
+# Fail-open by construction: any parse failure exits 0 with no decision. A hook
+# that hard-fails on a malformed envelope would block every Bash call.
+set -uo pipefail
+
+# Operator kill-switch, matching the convention of the other PreToolUse hooks
+# (grep-rewrite.sh carries SOLEUR_DISABLE_GREP_REWRITE). A false deny must not
+# require editing the installed plugin to work around.
+[[ -n "${SOLEUR_DISABLE_SNAPSHOT_GUARD:-}" ]] && exit 0
+
+INPUT="$(cat 2>/dev/null || true)"
+[[ -z "$INPUT" ]] && exit 0
+
+# Fast path, before any subprocess. The deny predicate requires the literal
+# `agent-browser`, and JSON escaping cannot alter it, so it survives verbatim in
+# the envelope. This short-circuits ~every Bash call in a session without
+# spawning jq -- which matters because this hook is registered on the Bash
+# matcher and also loads on the hosted platform surface, so it runs on EVERY
+# Bash tool call, not only on browser ones.
+[[ "$INPUT" == *agent-browser* ]] || exit 0
+
+# The redactor is anchored on its FILENAME, not on a bare word like "python3" or
+# "redact". The assertion is on the anchor: a look-alike command name that does
+# not redact must not satisfy the allow-predicate.
+REDACTOR_ANCHOR='redact-a11y-snapshot'
+
+# Portable remedy path. `${CLAUDE_PLUGIN_ROOT}` resolves to the installed plugin
+# on a customer machine, where a repo-relative path does not exist at all -- the
+# operator would get `python3: can't open file`, and the natural next move is the
+# screenshot escape, which this very message says is unsafe for the one class
+# with a recorded incident.
+# The remedy this hook PRINTS is the form the operator will paste, so it must be
+# the canonical one: bare `${CLAUDE_PLUGIN_ROOT}`, quoted. ADR-179 rejects the
+# `:-default` variant precisely because the fallback resolves to a repo-relative
+# path that exists on no customer machine -- it turns a loud failure into a
+# silent one, which is the defect class this whole guard exists to remove.
+REDACTOR_CMD='python3 "${CLAUDE_PLUGIN_ROOT}/skills/agent-browser/scripts/redact-a11y-snapshot.py"'
+
+# `jq` unusable is NOT the same condition as a malformed envelope, and must not
+# get the same silent pass. Without this branch a machine whose jq is missing OR
+# BROKEN runs with the guard entirely off, forever, with no signal -- while
+# SKILL.md tells the agent the gate exists, so its own reasoning defers to a
+# control that is not there.
+#
+# Detected by RESULT, not by `command -v`: a jq that is present and exits
+# non-zero (wrong build, missing shared library, exec-format error) passes a
+# presence check and then fails exactly like an absent one. The first revision
+# of this branch used `command -v` and the suite caught it.
+# Canonical kind map (#8205): Devin wire names → Claude kinds. Absent lib
+# degrades to passthrough, preserving this hook's fail-open invariant.
+. "$(dirname "${BASH_SOURCE[0]}")/lib/hook-tool-kind.sh" 2>/dev/null || true
+if ! type hook_tool_kind >/dev/null 2>&1; then
+  hook_tool_kind() { printf '%s\n' "${1-}"; }
+  echo "WARN: hook-tool-kind.sh missing — kind gates degrade to raw-name passthrough (silent-off under Devin)" >&2
+fi
+
+jq_rc=0
+TOOL="$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)" || jq_rc=$?
+if [[ $jq_rc -ne 0 ]]; then
+  if grep -qE 'agent-browser([[:space:]]+[^|;&]*)?[[:space:]]snapshot\b' <<<"$INPUT" 2>/dev/null \
+     && ! grep -qF "$REDACTOR_ANCHOR" <<<"$INPUT" 2>/dev/null; then
+    printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"BLOCKED (degraded mode): jq is unusable on this machine (exit %s), so this hook cannot parse the tool envelope and fell back to a raw scan of stdin. That scan sees an unrouted `agent-browser snapshot`. Install a working jq, or route the snapshot through the redactor: %s"}}\n' "$jq_rc" "$REDACTOR_CMD"
+  fi
+  exit 0
+fi
+
+# Both names reach this check: hooks.json binds `^(Bash|exec)$` — Claude Code's
+# tool is `Bash`, Devin's is `exec`, and either envelope may arrive. The kind
+# map normalizes `exec` → `Bash`; dropping it here would silently no-op the
+# guard on exactly the surface the matcher was widened for.
+[[ "$(hook_tool_kind "$TOOL")" == "Bash" ]] || exit 0
+
+CMD="$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
+[[ -z "$CMD" ]] && exit 0
+
+# Split into sequential segments. A pipe is NOT a separator -- it is what carries
+# a snapshot into the redactor, so it must stay inside the segment being judged.
+#
+# A bare `&` IS a separator, and omitting it was a live bypass: the whole command
+# stayed one segment, the segment contained the anchor, and an unrouted second
+# invocation rode through. ADR-213 and the Article 30 register both assert this
+# guard is judged per shell segment, so that claim was false as written.
+#
+# `2>&1` is protected first -- its `&` is a redirect, not a separator, and the
+# approved form depends on it.
+# awk, not sed: `\n` in a sed REPLACEMENT and `\x01` in a sed pattern are GNU
+# extensions. On BSD sed (the macOS default) the replacement emits a literal
+# `n` and `\x01` matches a literal `x01`, so NOTHING SPLITS -- the whole command
+# stays one segment, the anchor is found somewhere in it, and every chained
+# bypass this splitter exists to catch is ALLOWED. The guard would have been
+# silently inert on macOS while its suite passed on Linux, which is the same
+# portability class as the `mapfile` defect already fixed here and the one the
+# repo's own 2026-09-07 learning records for `\x1b`.
+#
+# In awk's gsub REPLACEMENT an unescaped `&` means "the matched text", so
+# restoring the literal `>&` requires `\\&`. Getting that wrong silently
+# doubles the redirect and was caught by the round-trip row in the suite.
+SPLIT="$(printf '%s' "$CMD" | awk '
+  { gsub(/>&/, "\001"); gsub(/&&|\|\||;|&/, "\n"); gsub(/\001/, ">\\&"); print }
+')"
+
+offending=0
+reason_detail=''
+while IFS= read -r seg; do
+  # HERESTRING throughout (#6992/#7024): `grep -q` on a PIPE can die of SIGPIPE
+  # under pipefail and read as "no match", which in a policy gate is fail-OPEN.
+  #
+  # `snapshot` is word-anchored, so `screenshot` is never caught here.
+  grep -qE 'agent-browser([[:space:]]+[^|;&]*)?[[:space:]]snapshot\b' <<<"$seg" 2>/dev/null || continue
+
+  # The allow-predicate is NOT "the anchor appears somewhere". Substring
+  # presence was satisfied by a trailing COMMENT, and by a `tee` that writes the
+  # unredacted tree to disk on its way to the redactor -- which is precisely the
+  # sink this hook's own deny text names.
+  if ! grep -qE '\|[^|]*'"$REDACTOR_ANCHOR" <<<"$seg" 2>/dev/null; then
+    offending=1
+    reason_detail='the redactor is not downstream of a pipe in this command'
+    break
+  fi
+  # Judge sinks on the segment UPSTREAM of the redactor only. A `tee` or a
+  # redirect AFTER the redactor writes redacted bytes and is harmless; one
+  # BEFORE it writes the raw tree, which is the sink this hook's deny text
+  # names. Scoping to the prefix is what makes the difference decidable --
+  # without it the legitimate `... | redactor > snap.txt` is denied while the
+  # question the check means to ask goes unasked.
+  pre="${seg%%"$REDACTOR_ANCHOR"*}"
+
+  if grep -qE '(^|[|[:space:]])tee([[:space:]]|$)' <<<"$pre" 2>/dev/null; then
+    offending=1
+    reason_detail='`tee` writes the UNREDACTED snapshot to disk before the redactor sees it'
+    break
+  fi
+  # A file redirect of the snapshot itself, e.g. `snapshot -i > raw.txt`.
+  #
+  # Match a `>` (optionally `>>`, optionally with a leading fd digit) that is
+  # NOT followed by `&`, so an fd duplication such as `2>&1` -- the approved
+  # form -- is allowed while a file sink is not. The previous
+  # `[^0-9<>]>[^&|]` form excluded a digit BEFORE the `>` and a `|` AFTER it,
+  # so `1>/tmp/leak.txt` and `>|/tmp/leak.txt` were both measured ALLOWED.
+  if grep -qE '[0-9]?>>?([^&>]|$)' <<<"$pre" 2>/dev/null; then
+    offending=1
+    reason_detail='this command redirects the snapshot to a file, which bypasses the redactor'
+    break
+  fi
+done <<<"$SPLIT"
+
+[[ $offending -eq 1 ]] || exit 0
+
+reason="BLOCKED: this \`agent-browser snapshot\` is not routed through the credential redactor — ${reason_detail}.
+
+An accessibility snapshot serializes the VALUE of input fields. A value you never typed — a password manager's autofill, a static \`value=\`, or a generated-credential panel — is rendered into the transcript and into any snapshot file written to disk. Nothing about the call looks credential-adjacent, which is why this is a gate and not a guideline (#7947).
+
+Route it through the redactor:
+
+  agent-browser snapshot -i 2>&1 | ${REDACTOR_CMD}
+
+Or take a screenshot instead, which is safe for a \`type=password\` field — the browser renders it as dots.
+
+MEASURED CAVEAT, because the obvious advice is wrong here: a screenshot is NOT safe for a generated-credential panel (a readonly \`type=text\` box named \"Token\", \"API key\", …). The browser renders those in clear, so the screenshot leaks exactly as the snapshot does. On a page showing a freshly-minted credential, capture neither — read the value with \`agent-browser get value <sel>\` into a file and shred it.
+
+The redactor is defense-in-depth on one sink. It does not make snapshotting a credential page safe: it cannot see a localised field name, a credential outside a text-input role, or a value split across segmented inputs."
+
+jq -nc --arg r "$reason" \
+  '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: $r}}' 2>/dev/null
+
+exit 0

package/hooks/codex-session-start.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+[[ -n "${CODEX_THREAD_ID:-}" || -n "${PLUGIN_ROOT:-}" ]] || exit 0
+SOLEUR_PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+jq -n --arg root "$SOLEUR_PLUGIN_ROOT" \
+  --rawfile instructions "$SOLEUR_PLUGIN_ROOT/codex/INSTRUCTIONS.md" \
+  '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext:
+    ("Soleur plugin root: " + $root + "\n" + $instructions)}}'