@cratis/pi 3.2.1 → 3.3.0

package/package/corpus/harnesses/pi/extensions/cratis-hooks/index.ts

@@ -7,13 +7,18 @@
  * events and drives the SAME scripts, synthesizing the Claude hook JSON they read on stdin:
  *
  *   Claude PreToolUse  (Write|Edit)  →  Pi `tool_call`      →  cratis-guard-writes.sh  (exit 2 = block)
+ *   Claude PreToolUse  (Bash)        →  Pi `tool_call`      →  cratis-guard-store-mutations.sh  (exit 2 = block)
  *   Claude PostToolUse (Write|Edit)  →  Pi `tool_result`    →  cratis-pattern-scan.sh  (advisory context)
  *   Claude Stop                       →  Pi `agent_settled`  →  cratis-quality-gate.sh  (exit 2 = keep going)
  *
  * Nothing here duplicates corpus content: it is adapter machinery, the Pi peer of the Claude
  * `hooks` block in `.claude/settings.json`. Every environment escape hatch the scripts honor
- * (CRATIS_HOOKS_ALLOW_PROTECTED_WRITES, CRATIS_HOOKS_SKIP_SCAN, CRATIS_HOOKS_SKIP_GATE, …) still
- * works because the scripts are executed unchanged.
+ * (CRATIS_HOOKS_ALLOW_PROTECTED_WRITES, CRATIS_HOOKS_ALLOW_STORE_MUTATIONS, CRATIS_HOOKS_SKIP_SCAN,
+ * CRATIS_HOOKS_SKIP_GATE, …) still works because the scripts are executed unchanged, in the environment
+ * Pi was started from.
+ *
+ * Only Pi's `bash` tool is bridged to the store-mutation guard. A command the user types directly (`!cmd`,
+ * the `user_bash` event) is the person's own action and is deliberately not guarded.
  */
 
 import { spawn } from "node:child_process";
@@ -85,6 +90,37 @@ function writeTarget(toolName: string, input: any): { filePath?: string; content
 	return { filePath };
 }
 
+type ToolCallContext = { cwd: string; signal?: AbortSignal };
+
+/**
+ * Run a blocking PreToolUse guard and translate its verdict into Pi's `tool_call` result.
+ *
+ * Exit 2 blocks with the script's stderr as the reason. A guard that is installed but could not run blocks too:
+ * allowing there would let the one case the guard exists to catch pass silently precisely because the guard
+ * is broken, so a broken guard is loud rather than permissive.
+ */
+async function runBlockingGuard(
+	script: string,
+	name: string,
+	subject: string,
+	payload: object,
+	ctx: ToolCallContext,
+	fixTarget = "this guard",
+): Promise<{ block: true; reason: string } | undefined> {
+	const run = await runScript(script, JSON.stringify(payload), ctx.cwd, ctx.signal);
+	if (run.failed) {
+		return {
+			block: true,
+			reason:
+				`${name} is installed at ${script} but could not be run, so this ${subject} cannot be checked.` +
+				`${run.stderr.trim() ? `\n\n${run.stderr.trim()}` : ""}` +
+				`\n\nFix the script (or remove it if this repository is not meant to enforce ${fixTarget}) and retry.`,
+		};
+	}
+	if (run.code === 2) return { block: true, reason: run.stderr.trim() || `Blocked by ${name}.` };
+	return undefined;
+}
+
 /**
  * Whether a hook script is installed at all.
  *
@@ -109,6 +145,7 @@ export default function (pi: ExtensionAPI) {
 	const managedScriptsDir = path.join(process.cwd(), ".cratis", "ai", "hooks", "scripts");
 	const scriptsDir = fs.existsSync(managedScriptsDir) ? managedScriptsDir : path.join(bundledCorpusRoot, "hooks", "scripts");
 	const guardWrites = path.join(scriptsDir, "cratis-guard-writes.sh");
+	const guardStoreMutations = path.join(scriptsDir, "cratis-guard-store-mutations.sh");
 	const patternScan = path.join(scriptsDir, "cratis-pattern-scan.sh");
 	const qualityGate = path.join(scriptsDir, "cratis-quality-gate.sh");
 
@@ -119,28 +156,21 @@ export default function (pi: ExtensionAPI) {
 		if (event.source !== "extension") gateActive = false; // a fresh user turn resets the guard
 	});
 
-	// ── PreToolUse → guard writes (blocking) ──
+	// ── PreToolUse → guard writes and store-mutating cratis commands (blocking) ──
 	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName === "bash") {
+			const command = (event as any).input?.command;
+			if (typeof command !== "string" || !command.trim()) return;
+			if (!isInstalled(guardStoreMutations)) return; // no guard installed in this repository - nothing to enforce
+			const payload = { cwd: ctx.cwd, tool_name: "Bash", tool_input: { command } };
+			return runBlockingGuard(guardStoreMutations, "cratis-guard-store-mutations", "command", payload, ctx);
+		}
 		if (event.toolName !== "write" && event.toolName !== "edit") return;
 		const { filePath, content, newString } = writeTarget(event.toolName, (event as any).input);
 		if (!filePath) return;
 		if (!isInstalled(guardWrites)) return; // no guard installed in this repository - nothing to enforce
-		const payload = JSON.stringify({ cwd: ctx.cwd, tool_input: { file_path: filePath, content, new_string: newString } });
-		const run = await runScript(guardWrites, payload, ctx.cwd, ctx.signal);
-
-		// The guard is installed but could not run. Allowing here would mean the one case the guard
-		// exists to catch - a protected write - passes silently precisely because the guard is broken.
-		// Block instead, and say why, so a broken guard is loud rather than permissive.
-		if (run.failed) {
-			return {
-				block: true,
-				reason:
-					`cratis-guard-writes is installed at ${guardWrites} but could not be run, so this write cannot be checked.` +
-					`${run.stderr.trim() ? `\n\n${run.stderr.trim()}` : ""}` +
-					"\n\nFix the script (or remove it if this repository is not meant to enforce write guards) and retry.",
-			};
-		}
-		if (run.code === 2) return { block: true, reason: run.stderr.trim() || "Blocked by cratis-guard-writes." };
+		const payload = { cwd: ctx.cwd, tool_input: { file_path: filePath, content, new_string: newString } };
+		return runBlockingGuard(guardWrites, "cratis-guard-writes", "write", payload, ctx, "write guards");
 	});
 
 	// ── PostToolUse → deterministic pattern scan (advisory; injects reminders the model sees) ──

package/package/corpus/hooks/README.md

@@ -10,6 +10,7 @@ Three layers:
 |---|---|---|---|---|
 | Pattern pass | `PostToolUse` on a write | `scripts/cratis-pattern-scan.sh` | zero tokens until a match | appends a one-line reminder to context, never blocks |
 | Hard block | `PreToolUse` on a write | `scripts/cratis-guard-writes.sh` | zero | exits **2** — the write does not happen |
+| Hard block | `PreToolUse` on `Bash` | `scripts/cratis-guard-store-mutations.sh` | zero; parses only commands that mention `cratis` | exits **2** — the store-changing `cratis chronicle` command does not run |
 | Quality gate | `Stop` | `scripts/cratis-quality-gate.sh` | one build/test run, only when relevant files changed | exits **2** — the turn does not end |
 
 The Claude Code wiring that fires them is tracked here, in
@@ -31,8 +32,9 @@ The markdown files in this folder (`agent-stop.md`, `pre-commit.md`) remain *lif
 they describe what a hook should do for tools that have no wiring yet.
 
 > Hooks are the one surface with no folder adapter: Claude Code reads `.claude/settings.json`;
-> the Pi harness bridges the same three scripts to its own events through the `cratis-hooks`
-> extension under `../harnesses/pi/extensions/`; Copilot would read `.github/hooks/*.json`, and no
+> the Pi harness bridges the same scripts to its own events through the `cratis-hooks`
+> extension under `../harnesses/pi/extensions/` (its `bash` tool feeds the store-mutation guard, its
+> `write` and `edit` tools the write guard); Copilot would read `.github/hooks/*.json`, and no
 > Copilot wiring ships yet.
 
 ## What is enforced
@@ -50,6 +52,42 @@ Rule numbers refer to the numbered list in [`../rules/general.md`](../rules/gene
 The generated-file check is anchored: the marker must be a comment opener at the start of one of
 the first five lines. A rule file or a document that merely *mentions* the marker is not blocked.
 
+**Blocked outright** (`PreToolUse` on `Bash`, exit 2): a `cratis chronicle` command that is not
+read-only. The **cratis-chronicle-cli-operations** skill makes `--yes` the authorization boundary for
+a live store and says a request to diagnose does not authorize a mutation; this guard enforces that.
+
+- **Allowlist, failing closed.** Every command below `cratis chronicle` is checked against the
+  read-only allowlist in `scripts/cratis-store-mutations.json`. A known mutation (replay,
+  retry-partition, clear-quarantine, jobs stop/resume, recommendations perform/ignore, users,
+  applications and subscriptions add/remove, plus login, logout, report-error and the interactive
+  workbench) is blocked with what it changes; a command on neither list — including one a newer CLI
+  adds — is blocked as unknown. `-h`/`--help` and `-v`/`--version` are always allowed.
+- **Where it looks.** Every `cratis` in command position: at the start, after `;` `&&` `||` `|`
+  `&`, inside `$( )`, backticks and `( )`, behind environment assignments
+  (`CHRONICLE_CONNECTION_STRING=… cratis …`), keywords (`if`, `then`, `do`, …) and wrappers (`rtk
+  proxy`, `env`, `sudo`, `timeout`, `xargs`, `nohup`, …), in the script of `bash -c` / `sh -c` /
+  `eval`, and in text piped, redirected or here-documented into a shell. A path segment
+  (`~/repos/cratis/Chronicle`), a file name (`cratis.json`), a quoted argument
+  (`grep 'cratis chronicle …'`) and a here-document fed to anything but a shell are not commands.
+- **Options before the command path.** The global and group options (`--server`, `-o`, `-q`,
+  `-y`, `-e`, `-n`, `--debug`) are skipped with their values wherever they appear. An option the
+  guard does not know, placed before the command path, makes the command impossible to classify, so
+  it is blocked.
+- **Out of scope.** Every other group — `ai`, `arc`, `context`, `llm`, `screenplay`, `prologue`,
+  `completions` — and the top-level commands (`init`, `new`, `render`, `run`, `update`, `version`,
+  `get-started`, `llm-context`) are always allowed. Several of them change local files or
+  configuration; guarding them is a separate decision, not part of this one.
+- **What it cannot see.** It reads the command text, so `cratis` reached through a variable, an
+  alias, a shell function, a script file, or another language's process API is invisible. It is a
+  guardrail against an agent reaching for `--yes`, not a sandbox.
+- **The block message** lists each refused command path and its effect, tells the agent not to retry
+  or work around the guard, and asks it to report the exact command, the target context or server,
+  what it changes and why, and to ask the user.
+
+A person who has authorized a mutation sets `CRATIS_HOOKS_ALLOW_STORE_MUTATIONS=1` in the
+environment the harness was started from. The hook reads its own environment, so an assignment
+inside the command (`CRATIS_HOOKS_ALLOW_STORE_MUTATIONS=1 cratis …`) changes nothing.
+
 **Flagged** (`PostToolUse`, exit 0 + context):
 
 | Pattern id | Rule | Detects |
@@ -271,14 +309,16 @@ how it resolved rather than only the failures.
 
 ## Configuration is data, not code
 
-Neither the pattern list nor the gate commands live in a script. A consuming repository
-customises both without forking anything:
+Neither the pattern list, the gate commands nor the `cratis` command classification live in a
+script. A consuming repository customises all three without forking anything:
 
 | File | Purpose |
 |---|---|
 | `scripts/cratis-patterns.json` | shipped pattern set; its header `$comment` documents every field |
 | `scripts/cratis-patterns.local.json` | optional; merged over the above by `id` — add patterns, or set `"enabled": false` to silence one |
 | `scripts/quality-gates.json` | shipped gates; `changed` globs decide when a gate runs, `requires` and `workingDirectoryFrom` decide whether it *can* |
+| `scripts/cratis-store-mutations.json` | the store-mutation guard's read-only allowlist and known-mutating list, each entry with its reason or effect, and the CLI options it skips; its header `$comment` documents every field and the CLI version the lists were derived from |
+| `scripts/cratis-store-mutations.local.json` | optional; its lists are appended to the above. It can classify a command a newer CLI adds, or list a shipped read-only command as mutating (a command on the mutating list always blocks); only a replacement file can make a known mutation read-only |
 
 A gate whose `requires.commands` are not on `PATH`, whose `requires.paths` do not exist, or whose
 `workingDirectoryFrom` matches nothing in the repository, is a **no-op with a message on stderr**
@@ -325,6 +365,8 @@ Each is an explicit, auditable opt-out — none of them is a default.
 | `CRATIS_HOOKS_GATE_DRYRUN=1` | prints which gates would run, and why, then exits 0 |
 | `CRATIS_HOOKS_PATTERNS=<path>` | replaces the pattern file |
 | `CRATIS_HOOKS_GATES=<path>` | replaces the gate file (the project override still merges over it) |
+| `CRATIS_HOOKS_ALLOW_STORE_MUTATIONS=1` | allows `cratis chronicle` commands that change a live store; set by the person who authorized the mutation, in the environment the harness was started from |
+| `CRATIS_HOOKS_STORE_MUTATIONS=<path>` | replaces the store-mutation guard's command lists (the `.local.json` beside the script still extends them) |
 | `CRATIS_HOOKS_SUBPATH_REPORT=1` | prints every `@cratis/*` subpath reference and how it resolved, not only the failures |
 | `CRATIS_HOOKS_IMPORT_REPORT=1` | prints every `@cratis/*` named import binding and how it resolved, not only the failures |
 | `CRATIS_HOOKS_TYPE_REPORT=1` | prints every .NET type/attribute name the corpus mentions and how it resolved, not only the failures |
@@ -338,7 +380,10 @@ Each is an explicit, auditable opt-out — none of them is a default.
 - **`jq` is the only dependency.** Every script
   degrades to a silent no-op when it is missing — a hook must never break a session.
 - **Fail safe.** Malformed config, empty stdin, a missing file, a binary file, a file over 2 MB:
-  all exit 0 silently.
+  all exit 0 silently. The one deliberate exception is the store-mutation guard's command lists:
+  an unreadable shipped or local list is not an empty allowlist that happens to pass, so every `cratis chronicle`
+  command is then blocked with a message naming the file, and a classifier that fails to run blocks
+  the command it was given. Commands that never mention `cratis` are unaffected either way.
 - **No secrets, no file dumps.** Gate output is capped at `maxOutputLines`; the pattern pass
   prints a path, a line number and a fixed message — never file content.
 - **No re-entry.** The `Stop` hook returns immediately when `stop_hook_active` is true, so a
@@ -367,6 +412,12 @@ jq -nc '{session_id:"t", cwd:"'"$PWD"'", tool_name:"Edit",
          tool_input:{file_path:"'"$PWD"'/Directory.Packages.props", new_string:"x"}}' \
   | .cratis/ai/hooks/scripts/cratis-guard-writes.sh; echo "exit=$?"
 
+# Store-mutation guard, both directions: expect exit 2, then exit 0 for the read-only neighbor
+jq -nc '{tool_name:"Bash", tool_input:{command:"cratis chronicle observers replay my-observer --yes"}}' \
+  | .cratis/ai/hooks/scripts/cratis-guard-store-mutations.sh; echo "exit=$?"
+jq -nc '{tool_name:"Bash", tool_input:{command:"cratis chronicle observers list -o plain"}}' \
+  | .cratis/ai/hooks/scripts/cratis-guard-store-mutations.sh; echo "exit=$?"
+
 # Quality gate — show the dispatch plan without running anything
 jq -nc '{session_id:"t", cwd:"'"$PWD"'", stop_hook_active:false}' \
   | CRATIS_HOOKS_GATE_DRYRUN=1 .cratis/ai/hooks/scripts/cratis-quality-gate.sh

package/package/corpus/hooks/scripts/cratis-guard-store-mutations.sh

@@ -0,0 +1,470 @@
+#!/usr/bin/env bash
+# PreToolUse hook (Bash) — hard block on `cratis chronicle` commands that are not read-only.
+#
+# The cratis-chronicle-cli-operations skill makes `--yes` the authorization boundary for changing a
+# live Chronicle store, and says a request to diagnose does not authorize a mutation. This guard is
+# what enforces that: every `cratis` invocation in the shell command is found and, for the
+# `chronicle` group, classified against cratis-store-mutations.json. Anything that is not on the
+# read-only allowlist — replay, retry, quarantine clearing, job control, recommendations, users,
+# applications, subscriptions, and any command a newer CLI adds — exits 2 (block the tool call,
+# stderr goes back to the model). Unknown commands fail closed.
+#
+# Other groups (ai, arc, context, llm, screenplay, prologue, completions) and the top-level commands
+# (init, new, render, run, update, version, ...) are out of scope and always allowed.
+#
+# What it sees is the command text. A `cratis` reached through a variable, an alias, a function or a
+# script file is invisible to it; see .cratis/ai/hooks/README.md for the full list of limits.
+#
+# Escape hatch for a human who authorized the mutation — set in the environment the agent harness was
+# started from, never inside the command (an assignment in the command is ignored):
+#   CRATIS_HOOKS_ALLOW_STORE_MUTATIONS=1
+# Data file override (replaces the shipped lists; a .local.json beside this script only adds to them):
+#   CRATIS_HOOKS_STORE_MUTATIONS=<path>
+set -euo pipefail
+
+# SCRIPTDIR, not a path relative to the caller: shellcheck resolves a plain relative `source=`
+# against the current working directory, and these hooks are linted from wherever CI happens to run.
+# shellcheck source=SCRIPTDIR/hook-lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/hook-lib.sh"
+
+[ "${CRATIS_HOOKS_ALLOW_STORE_MUTATIONS:-0}" = "1" ] && exit 0
+
+input="$(hook_read_stdin)"
+[ -n "$input" ] || exit 0
+hook_have jq || exit 0
+
+command_text="$(hook_json "$input" '.tool_input.command')"
+[ -n "$command_text" ] || exit 0
+
+# Cheap exit for the overwhelming majority of shell commands, which never mention the CLI.
+case "$(printf '%s' "$command_text" | tr '[:upper:]' '[:lower:]')" in
+    *cratis*) ;;
+    *) exit 0 ;;
+esac
+
+# ── Command lists: shipped defaults + optional local extension, or a replacement ─────────
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+data_file="${CRATIS_HOOKS_STORE_MUTATIONS:-$here/cratis-store-mutations.json}"
+local_file="$here/cratis-store-mutations.local.json"
+
+merged=""
+error_file="$data_file"
+if [ -f "$data_file" ]; then
+    merged="$(jq -ce 'select(type == "object" and (.group | type == "string") and
+        (.readOnly | type == "array") and (.mutating | type == "array") and
+        (.helpOptions | type == "array") and (.versionOptions | type == "array") and
+        (.flagOptions | type == "array") and (.valueOptions | type == "array"))' "$data_file" 2>/dev/null || true)"
+fi
+if [ -n "$merged" ] && [ -f "$local_file" ]; then
+    # A local file adds entries; it never removes one. A command it lists as mutating is blocked even
+    # when the shipped file calls it read-only, because the classifier checks "mutating" first.
+    extended="$(printf '%s' "$merged" | jq -c --slurpfile local "$local_file" '
+        . as $base | $local[0] as $add
+        | if ($add | type) != "object" or
+             (["readOnly", "mutating", "helpOptions", "versionOptions", "flagOptions", "valueOptions"]
+              | any(. as $key | ($add[$key] != null and ($add[$key] | type) != "array")))
+          then error("invalid local list") else . end
+        | $base + (["readOnly", "mutating", "helpOptions", "versionOptions", "flagOptions", "valueOptions"]
+            | map({key: ., value: (($base[.] // []) + ($add[.] // []))}) | from_entries)
+    ' 2>/dev/null || true)"
+    if [ -n "$extended" ]; then
+        merged="$extended"
+    else
+        merged=""
+        error_file="$local_file"
+    fi
+fi
+
+# An unreadable list is not an empty allowlist that happens to pass: every chronicle command is then
+# refused, and the message says why.
+data_ok=1
+[ -n "$merged" ] || { data_ok=0; merged='{}'; }
+
+list() {
+    printf '%s' "$merged" | jq -r "$1" 2>/dev/null || true
+}
+
+group="$(list '.group // "chronicle"')"
+read_only="$(list '(.readOnly // [])[] | .command // empty')"
+mutating="$(list '(.mutating // [])[] | select(.command) | "\(.command)\t\(.effect // "")"')"
+help_options="$(list '(.helpOptions // [])[]')"
+version_options="$(list '(.versionOptions // [])[]')"
+flag_options="$(list '(.flagOptions // [])[]')"
+value_options="$(list '(.valueOptions // [])[]')"
+
+tab_char="$(printf '\t')"
+
+# ── Find and classify every cratis invocation ─────────────────────────────────────────────
+# One awk pass: a small shell tokenizer (quotes, escapes, $( ) and backticks, subshells, pipelines
+# and lists, redirections, here-documents) splits the command into simple commands; each is checked
+# for `cratis` in command position, behind env assignments, keywords and wrappers (rtk proxy, env,
+# sudo, timeout, xargs, ...). `bash -c '...'`, `eval ...` and scripts piped or redirected into a
+# shell are queued and tokenized again. Output: one line per blocked invocation,
+#   <kind> TAB <command path> TAB <effect>
+# where kind is mutating, unknown or unparsed.
+findings="$(
+    CSM_COMMAND="$command_text" \
+    CSM_GROUP="$group" \
+    CSM_READONLY="$read_only" \
+    CSM_MUTATING="$mutating" \
+    CSM_HELP="$help_options" \
+    CSM_VERSION="$version_options" \
+    CSM_FLAGS="$flag_options" \
+    CSM_VALUES="$value_options" \
+    LC_ALL=C awk '
+    function toset(text, set,    parts, n, k) {
+        n = split(text, parts, "\n")
+        for (k = 1; k <= n; k++) if (parts[k] != "") set[tolower(parts[k])] = 1
+    }
+    function words_in(text,    parts) { return split(text, parts, " ") }
+    function norm(text) {
+        text = tolower(text); gsub(/[ \t]+/, " ", text); sub(/^ /, "", text); sub(/ $/, "", text)
+        return text
+    }
+    function report(kind, path, effect,    key) {
+        key = kind SUBSEP path
+        if (key in reported) return
+        reported[key] = 1
+        printf "%s\t%s\t%s\n", kind, path, effect
+    }
+    function enqueue(text) {
+        if (text == "" || !index(tolower(text), "cratis")) return
+        queue[++queued] = text
+    }
+    function base(word) { word = tolower(word); sub(/.*\//, "", word); return word }
+
+    # ── tokenizer state ──
+    function end_word() {
+        if (inword) {
+            if (index(tolower(word), "cratis") && candidates < 256) candidate[++candidates] = word
+            if (skip_next) skip_next = 0
+            else current = current (current == "" ? "" : SEP) (quoted ? "Q" : "U") word
+        }
+        word = ""; quoted = 0; inword = 0
+    }
+    function emit() {
+        end_word()
+        if (current != "") analyze(current)
+        current = ""
+    }
+    function push(kind) {
+        depth++
+        s_current[depth] = current; s_word[depth] = word; s_quoted[depth] = quoted
+        s_inword[depth] = inword; s_dq[depth] = in_dq; s_kind[depth] = frame
+        s_parens[depth] = parens; s_skip[depth] = skip_next
+        current = ""; word = ""; quoted = 0; inword = 0; in_dq = 0
+        frame = kind; parens = 0; skip_next = 0
+    }
+    function pop() {
+        emit()
+        current = s_current[depth]; word = s_word[depth] "$()"; quoted = s_quoted[depth]
+        inword = 1; in_dq = s_dq[depth]; frame = s_kind[depth]
+        parens = s_parens[depth]; skip_next = s_skip[depth]
+        depth--
+    }
+    # Index just past the parenthesis (or brace) group opening at i.
+    function skip_group(s, i, opener, closer,    n, level, c) {
+        n = length(s); level = 0
+        for (; i <= n; i++) {
+            c = substr(s, i, 1)
+            if (c == opener) level++
+            else if (c == closer) { level--; if (level == 0) return i + 1 }
+        }
+        return n + 1
+    }
+    # Read the bodies of the pending here-documents, which start at i. A body is data unless a
+    # shell reads it as a script, so it becomes a candidate rather than a command.
+    function heredocs(s, i,    n, k, nl, line, body, test) {
+        n = length(s)
+        for (k = 1; k <= pending; k++) {
+            body = ""
+            while (i <= n) {
+                nl = index(substr(s, i), "\n")
+                if (nl == 0) { line = substr(s, i); i = n + 1 } else { line = substr(s, i, nl - 1); i += nl }
+                test = line
+                if (strip[k]) sub(/^\t+/, "", test)
+                if (test == delimiter[k]) break
+                body = body line "\n"
+            }
+            if (index(tolower(body), "cratis") && candidates < 256) candidate[++candidates] = body
+        }
+        pending = 0
+        return i
+    }
+
+    function parse(s,    n, i, c, c2, j, k) {
+        current = ""; word = ""; quoted = 0; inword = 0; skip_next = 0
+        in_sq = 0; in_dq = 0; depth = 0; frame = "top"; parens = 0
+        pending = 0; candidates = 0; stdin_shell = 0
+        n = length(s); i = 1
+        while (i <= n) {
+            c = substr(s, i, 1)
+            if (in_sq) {
+                if (c == "\047") in_sq = 0; else word = word c
+                i++; continue
+            }
+            if (in_dq) {
+                if (c == "\\") {
+                    c2 = substr(s, i + 1, 1)
+                    if (c2 == "\n") { i += 2; continue }
+                    if (c2 == "\"" || c2 == "\\" || c2 == "$" || c2 == "`") { word = word c2; i += 2; continue }
+                    word = word c; i++; continue
+                }
+                if (c == "\"") { in_dq = 0; i++; continue }
+                if (c == "$" && substr(s, i + 1, 1) == "(") {
+                    if (substr(s, i + 2, 1) == "(") { j = skip_group(s, i + 1, "(", ")"); word = word substr(s, i, j - i); i = j; continue }
+                    push("subst"); i += 2; continue
+                }
+                if (c == "`") { if (frame == "backtick") pop(); else push("backtick"); i++; continue }
+                word = word c; i++; continue
+            }
+            if (c == "\\") {
+                c2 = substr(s, i + 1, 1)
+                if (c2 != "\n") { word = word c2; inword = 1 }
+                i += 2; continue
+            }
+            if (c == "\047") { in_sq = 1; inword = 1; quoted = 1; i++; continue }
+            if (c == "\"") { in_dq = 1; inword = 1; quoted = 1; i++; continue }
+            if (c == "#" && !inword) { while (i <= n && substr(s, i, 1) != "\n") i++; continue }
+            if (c == "$") {
+                c2 = substr(s, i + 1, 1)
+                if (c2 == "(" && substr(s, i + 2, 1) == "(") { j = skip_group(s, i + 1, "(", ")"); word = word substr(s, i, j - i); inword = 1; i = j; continue }
+                if (c2 == "(") { push("subst"); i += 2; continue }
+                if (c2 == "{") { j = skip_group(s, i + 1, "{", "}"); word = word substr(s, i, j - i); inword = 1; i = j; continue }
+                word = word c; inword = 1; i++; continue
+            }
+            if (c == "`") { if (frame == "backtick") pop(); else push("backtick"); i++; continue }
+            if (c == "(") {
+                if (!inword && substr(s, i + 1, 1) == "(") { i = skip_group(s, i, "(", ")"); continue }
+                emit(); parens++; i++; continue
+            }
+            if (c == ")") {
+                if (parens > 0) { emit(); parens--; i++; continue }
+                if (frame == "subst") { pop(); i++; continue }
+                emit(); i++; continue
+            }
+            if (c == "<" || c == ">") {
+                c2 = substr(s, i + 1, 1)
+                if (c2 == "(") { end_word(); push("subst"); i += 2; continue }
+                if (inword && !quoted && word ~ /^[0-9]+$/) { word = ""; inword = 0 } else end_word()
+                if (c == "<" && c2 == "<") {
+                    if (substr(s, i + 2, 1) == "<") { skip_next = 2; i += 3; continue }
+                    i += 2; pending++; strip[pending] = 0; delimiter[pending] = ""
+                    if (substr(s, i, 1) == "-") { strip[pending] = 1; i++ }
+                    while (substr(s, i, 1) == " " || substr(s, i, 1) == "\t") i++
+                    while (i <= n) {
+                        c2 = substr(s, i, 1)
+                        if (c2 ~ /[ \t\n;&|<>()]/) break
+                        if (c2 != "\047" && c2 != "\"" && c2 != "\\") delimiter[pending] = delimiter[pending] c2
+                        i++
+                    }
+                    continue
+                }
+                i++
+                if (c2 == "&") {
+                    i++
+                    if (substr(s, i, 1) ~ /[0-9-]/) { while (i <= n && substr(s, i, 1) ~ /[0-9-]/) i++; continue }
+                    skip_next = 1; continue
+                }
+                if (c2 == ">" || c2 == "|" || (c == "<" && c2 == ">")) i++
+                skip_next = 1; continue
+            }
+            if (c == "&" && substr(s, i + 1, 1) == ">") {
+                end_word(); i += 2
+                if (substr(s, i, 1) == ">") i++
+                skip_next = 1; continue
+            }
+            if (c == "&" || c == ";" || c == "|") { emit(); i++; continue }
+            if (c == "\n") { emit(); i++; if (pending > 0) i = heredocs(s, i); continue }
+            if (c == " " || c == "\t" || c == "\r") { end_word(); i++; continue }
+            word = word c; inword = 1; i++
+        }
+        emit()
+        while (depth > 0) pop()
+        emit()
+        # A shell reading its script from stdin (a pipe, a here-document, a here-string, a redirect)
+        # runs text the tokenizer only saw as data; re-read every such text that mentions cratis.
+        if (stdin_shell) for (k = 1; k <= candidates; k++) enqueue(candidate[k])
+    }
+
+    # ── simple commands ──
+    function analyze(text,    parts, n, k) {
+        n = split(text, parts, SEP)
+        for (k = 1; k <= n; k++) { Q[k] = substr(parts[k], 1, 1); W[k] = substr(parts[k], 2) }
+        count = n
+        from(1)
+    }
+    function joined(first,    k, out) {
+        out = ""
+        for (k = first; k <= count; k++) out = out (out == "" ? "" : " ") W[k]
+        return out
+    }
+    function from(first,    i, b, j, bj) {
+        i = first
+        while (i <= count) {
+            if (W[i] ~ /^[A-Za-z_][A-Za-z0-9_]*\+?=/) { i++; continue }
+            if (Q[i] == "U" && (W[i] in keyword)) { i++; continue }
+            break
+        }
+        if (i > count) return
+        b = base(W[i])
+        if (b == "cratis") { classify(i + 1); return }
+        if (b in shell) { shell_command(i); return }
+        if (b == "eval") { enqueue(joined(i + 1)); return }
+        if (b in wrapper) {
+            for (j = i + 1; j <= count; j++) {
+                bj = base(W[j])
+                if (bj == "cratis" || bj == "eval" || (bj in shell)) { from(j); return }
+                if (W[j] ~ /[ \t\n;&|]/) enqueue(W[j])
+            }
+        }
+    }
+    function shell_command(i,    j) {
+        for (j = i + 1; j <= count; j++) {
+            if (W[j] ~ /^-[A-Za-z]*c[A-Za-z]*$/ || W[j] == "--command") {
+                if (j < count) enqueue(W[j + 1])
+                return
+            }
+        }
+        for (j = i + 1; j <= count; j++) {
+            if (W[j] == "-o" || W[j] == "+o" || W[j] == "-O" || W[j] == "+O" || W[j] == "--rcfile" || W[j] == "--init-file") { j++; continue }
+            if (W[j] == "--") return (j < count) ? 0 : stdin_script()
+            if (W[j] ~ /^[-+]/) continue
+            return
+        }
+        stdin_script()
+    }
+    function stdin_script() { stdin_shell = 1; return 0 }
+
+    # ── one cratis invocation: the words after `cratis` start at first ──
+    function is_option(lower) { return lower ~ /^-./ }
+    function known_value(lower,    eq) {
+        eq = index(lower, "=")
+        return eq > 1 && (substr(lower, 1, eq - 1) in value_option)
+    }
+    function classify(first,    j, m, x, t, lower, name, values, only_options, count_words, path, shown, key) {
+        values = " "
+        for (j = first; j <= count; j++) {
+            lower = tolower(W[j])
+            if (!is_option(lower)) break
+            if (Q[j] == "U" && ((lower in help_option) || (lower in version_option))) return
+            if (lower in flag_option) continue
+            if (lower in value_option) { j++; if (j <= count) values = values tolower(W[j]) " "; continue }
+            if (known_value(lower)) { values = values substr(lower, index(lower, "=") + 1) " "; continue }
+            # An option this guard does not know, before the command group: it cannot tell which word is
+            # the group, so any mention of the guarded group fails closed.
+            for (m = j + 1; m <= count; m++) {
+                if (tolower(W[m]) == group) { t = W[j]; sub(/=.*/, "=...", t); report("unparsed", "cratis " t " ... " group, ""); return }
+            }
+            return
+        }
+        if (j > count) return
+        name = tolower(W[j])
+        if (index(name, "$") || index(name, "`") || index(name, "*") || index(name, "?") || index(name, "[")) {
+            report("unparsed", "cratis " W[j], ""); return
+        }
+        if (name != group) {
+            if (index(values, " " group " ")) report("unparsed", "cratis ... " group, "")
+            return
+        }
+        for (m = j + 1; m <= count; m++) {
+            if (W[m] == "--") break
+            if (Q[m] == "U" && ((tolower(W[m]) in help_option) || (tolower(W[m]) in version_option))) return
+        }
+        count_words = 0; only_options = 1
+        for (m = j + 1; m <= count && count_words < max_depth; m++) {
+            lower = tolower(W[m])
+            if (lower == "--") { only_options = 0; continue }
+            if (only_options && is_option(lower)) {
+                if (lower in flag_option) continue
+                if (lower in value_option) { m++; continue }
+                if (known_value(lower)) continue
+                break
+            }
+            count_words++; path[count_words] = lower; shown[count_words] = W[m]
+        }
+        if (count_words == 0) { report("unknown", "cratis " W[j], ""); return }
+        for (m = count_words; m >= 1; m--) {
+            key = path[1]; t = shown[1]
+            for (x = 2; x <= m; x++) { key = key " " path[x]; t = t " " shown[x] }
+            if (key in mutating) { report("mutating", "cratis " W[j] " " t, mutating[key]); return }
+            if (key in read_only) return
+        }
+        t = shown[1]
+        for (x = 2; x <= count_words; x++) t = t " " shown[x]
+        report("unknown", "cratis " W[j] " " t, "")
+    }
+
+    BEGIN {
+        SEP = "\037"
+        group = tolower(ENVIRON["CSM_GROUP"]); if (group == "") group = "chronicle"
+        max_depth = 0
+        n = split(ENVIRON["CSM_READONLY"], lines, "\n")
+        for (k = 1; k <= n; k++) {
+            key = norm(lines[k]); if (key == "") continue
+            read_only[key] = 1
+            if (words_in(key) > max_depth) max_depth = words_in(key)
+        }
+        n = split(ENVIRON["CSM_MUTATING"], lines, "\n")
+        for (k = 1; k <= n; k++) {
+            tab = index(lines[k], "\t"); if (tab == 0) continue
+            key = norm(substr(lines[k], 1, tab - 1)); if (key == "") continue
+            mutating[key] = substr(lines[k], tab + 1)
+            if (words_in(key) > max_depth) max_depth = words_in(key)
+        }
+        if (max_depth < 2) max_depth = 2
+        toset(ENVIRON["CSM_HELP"], help_option)
+        toset(ENVIRON["CSM_VERSION"], version_option)
+        toset(ENVIRON["CSM_FLAGS"], flag_option)
+        toset(ENVIRON["CSM_VALUES"], value_option)
+        toset("bash\nsh\nzsh\ndash\nksh\nmksh\nfish\nsu", shell)
+        toset("!\n{\n}\nif\nthen\nelse\nelif\ndo\nwhile\nuntil\ntime", keyword)
+        toset("env\ncommand\nexec\nbuiltin\nnohup\ntime\nnice\nionice\nsudo\ndoas\ntimeout\ngtimeout\nxargs\nparallel\nstdbuf\nunbuffer\ncaffeinate\nwatch\nrtk\ndotnet\narch\nssh\nnoglob\nnocorrect\ntaskset\nflock\nsetsid\nchronic", wrapper)
+
+        queued = 1; queue[1] = ENVIRON["CSM_COMMAND"]
+        for (done = 1; done <= queued; done++) {
+            if (done > 64) { report("unparsed", "(more than 64 nested shell scripts)", ""); break }
+            if (index(tolower(queue[done]), "cratis")) parse(queue[done])
+        }
+    }
+    '
+)" || findings="unparsed${tab_char}(the classifier failed, so no cratis command in it can be checked)${tab_char}"
+
+[ -n "$findings" ] || exit 0
+
+# ── Block ─────────────────────────────────────────────────────────────────────────────────
+{
+    printf 'BLOCKED by cratis-guard-store-mutations: this command runs cratis %s commands that are not read-only.\n\n' "$group"
+    while IFS="$tab_char" read -r kind path effect; do
+        [ -n "$kind" ] || continue
+        case "$kind" in
+            mutating) printf '  - %s: %s.\n' "$path" "$effect" ;;
+            unparsed) printf '  - %s: the guard cannot tell which command this runs, so it is treated as a mutation.\n' "$path" ;;
+            *) printf '  - %s: not on the read-only allowlist, so it is treated as a mutation.\n' "$path" ;;
+        esac
+    done <<EOF
+$findings
+EOF
+    if [ "$data_ok" = "1" ]; then
+        printf '\nRead-only inspection commands and --help are allowed.\n'
+    else
+        printf '\nThe command lists could not be read from %s, so every cratis %s command is refused until they can.\n' "$error_file" "$group"
+    fi
+    cat <<EOF
+
+The cratis-chronicle-cli-operations skill makes --yes the authorization boundary for a live Chronicle
+store: a request to inspect or diagnose does not authorize a replay, a retry, clearing quarantine, job
+control, a recommendation, or adding or removing users, applications or subscriptions.
+
+Do not retry this, rephrase it, or work around the guard (another wrapper, a script file, a variable,
+an alias, the terminal Workbench). Stop and report to the user:
+  1. the exact command you intended to run;
+  2. the target it resolves to: the context ('cratis context show'), or the --server /
+     CHRONICLE_CONNECTION_STRING it uses - never print credentials;
+  3. what it changes and why that is needed, and how the change is undone;
+then ask the user to run it themselves or to authorize it. A person who authorizes it sets
+CRATIS_HOOKS_ALLOW_STORE_MUTATIONS=1 in the environment the agent harness was started from; setting it
+inside the command has no effect.
+EOF
+} >&2
+exit 2

package/package/corpus/hooks/scripts/cratis-store-mutations.json

@@ -0,0 +1,85 @@
+{
+    "$comment": [
+        "Command classification for the Cratis PreToolUse Bash guard (cratis-guard-store-mutations.sh).",
+        "Data, not code: a consuming repository extends or replaces this without touching the script.",
+        "  - drop a cratis-store-mutations.local.json next to this file to ADD entries (merged, never replaces)",
+        "  - or point CRATIS_HOOKS_STORE_MUTATIONS at a replacement file",
+        "A command listed in \"mutating\" is blocked even when a local file also lists it in \"readOnly\", so a",
+        "local file can tighten the shipped lists but only a replacement file can loosen them.",
+        "",
+        "Scope: only the \"group\" command group is guarded. Every other cratis group (ai, arc, context, llm,",
+        "screenplay, prologue, completions) and every top-level command (init, new, render, run, update,",
+        "version, get-started, llm-context) is out of scope and always allowed.",
+        "",
+        "Fields:",
+        "  verifiedAgainst  the cratis CLI version whose `cratis llm-context` these lists were derived from",
+        "  group            the guarded command group",
+        "  helpOptions      options that print help instead of running; allowed wherever they appear",
+        "  versionOptions   options that print the version instead of running a command; allowed wherever they appear",
+        "  flagOptions      global/group options that take no value, skipped while reading the command path",
+        "  valueOptions     global/group options that take a value, skipped with that value",
+        "  readOnly         the allowlist: command paths below the group that only read state",
+        "                     command  the command path, space-separated, e.g. \"observers list\"",
+        "                     reason   why it is safe to run without a human's authorization",
+        "  mutating         known command paths that change server, client or external state",
+        "                     command  the command path",
+        "                     effect   what it changes; shown to the agent in the block message",
+        "",
+        "Anything under the group that is on neither list is blocked as unknown: the guard fails closed, so a",
+        "command added by a newer CLI is refused until someone classifies it here."
+    ],
+    "verifiedAgainst": "cratis 3.13.1",
+    "group": "chronicle",
+    "helpOptions": ["-h", "--help"],
+    "versionOptions": ["-v", "--version"],
+    "flagOptions": ["-q", "--quiet", "-y", "--yes", "--debug"],
+    "valueOptions": ["--server", "-o", "--output", "-e", "--event-store", "-n", "--namespace"],
+    "readOnly": [
+        { "command": "diagnose", "reason": "runs a health check and returns a diagnostic report" },
+        { "command": "auth status", "reason": "shows the cached token's expiry and identity" },
+        { "command": "applications list", "reason": "lists registered applications" },
+        { "command": "event-stores list", "reason": "lists event stores" },
+        { "command": "event-types list", "reason": "lists registered event types" },
+        { "command": "event-types show", "reason": "shows one event type registration and its schema" },
+        { "command": "events get", "reason": "reads events from an event sequence" },
+        { "command": "events tail", "reason": "returns the highest used sequence number" },
+        { "command": "failed-partitions list", "reason": "lists failed observer partitions" },
+        { "command": "failed-partitions show", "reason": "shows one failed partition and its error" },
+        { "command": "identities list", "reason": "lists known identities" },
+        { "command": "jobs get", "reason": "shows one background job" },
+        { "command": "jobs list", "reason": "lists background jobs" },
+        { "command": "namespaces list", "reason": "lists namespaces in an event store" },
+        { "command": "observers list", "reason": "lists observers" },
+        { "command": "observers show", "reason": "shows one observer's state" },
+        { "command": "projections list", "reason": "lists projection definitions" },
+        { "command": "projections show", "reason": "shows one projection definition" },
+        { "command": "read-models get", "reason": "reads one read model instance" },
+        { "command": "read-models instances", "reason": "lists read model instances" },
+        { "command": "read-models list", "reason": "lists read model definitions" },
+        { "command": "read-models occurrences", "reason": "lists a read model's replay history" },
+        { "command": "read-models snapshots", "reason": "reads snapshots of one read model instance" },
+        { "command": "recommendations list", "reason": "lists active recommendations" },
+        { "command": "subscriptions list", "reason": "lists event store subscriptions" },
+        { "command": "users list", "reason": "lists registered users" }
+    ],
+    "mutating": [
+        { "command": "observers replay", "effect": "replays an observer from the beginning of the event log, resetting all state it has built" },
+        { "command": "observers replay-partition", "effect": "replays one partition of an observer from the beginning, resetting that partition's state" },
+        { "command": "observers retry-partition", "effect": "retries a failed partition from the sequence number where it failed" },
+        { "command": "observers clear-quarantine", "effect": "clears an observer's quarantine so it resumes processing" },
+        { "command": "jobs stop", "effect": "stops a running background job" },
+        { "command": "jobs resume", "effect": "resumes a stopped or failed background job" },
+        { "command": "recommendations perform", "effect": "executes a server recommendation, such as a schema or replay maintenance action" },
+        { "command": "recommendations ignore", "effect": "marks a recommendation as ignored so it no longer appears" },
+        { "command": "subscriptions add", "effect": "adds an event store subscription to a target event store" },
+        { "command": "subscriptions remove", "effect": "removes an event store subscription from a target event store" },
+        { "command": "users add", "effect": "adds a user to the server's user store" },
+        { "command": "users remove", "effect": "removes a user from the server" },
+        { "command": "applications add", "effect": "registers an application with the server" },
+        { "command": "applications remove", "effect": "removes an application registration from the server" },
+        { "command": "login", "effect": "authenticates with a username and password and caches a token that later commands use" },
+        { "command": "logout", "effect": "clears the cached authentication token" },
+        { "command": "report-error", "effect": "opens a pre-filled GitHub issue in the browser" },
+        { "command": "workbench", "effect": "opens the interactive terminal Workbench, whose keys replay observers and retry or replay failed partitions; only a human at a terminal can drive it" }
+    ]
+}

package/package/corpus/hooks/scripts/hook-lib.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 # Shared helpers for the Cratis enforcement hooks.
 #
-# Sourced by cratis-guard-writes.sh, cratis-pattern-scan.sh and cratis-quality-gate.sh.
+# Sourced by cratis-guard-writes.sh, cratis-guard-store-mutations.sh, cratis-pattern-scan.sh and
+# cratis-quality-gate.sh.
 # Portable: bash 3.2 (macOS system bash) and up, BSD + GNU userland. No GNU-only flags,
 # no `mapfile`/`readarray`, no associative arrays, no `eval`.
 set -euo pipefail

package/package/corpus/hooks/settings.template.json

@@ -10,6 +10,15 @@
             "command": "\"$CLAUDE_PROJECT_DIR\"/.cratis/ai/hooks/scripts/cratis-guard-writes.sh"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.cratis/ai/hooks/scripts/cratis-guard-store-mutations.sh"
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/package/corpus/prompts/audit-hooks.prompt.md

@@ -5,9 +5,9 @@ description: Audit hook files for correctness, portability, and enforcement cove
 
 # Audit Hooks
 
-Review `.cratis/ai/hooks/` and report whether hooks are:
+Review `.cratis/ai/hooks/` — the write guard, store-mutation guard, pattern scan, and quality gate — and report whether hooks are:
 
-- enforcing the intended policy
+- enforcing the intended policy (including the `cratis chronicle` read-only allowlist and its fail-closed behavior)
 - portable across environments
 - aligned with canonical source rules
 - using bash-first commands for script execution

package/package/corpus/skills/cratis-chronicle-cli-operations/SKILL.md

@@ -152,6 +152,13 @@ These commands mutate the running store:
 - `chronicle users add`, `chronicle users remove`
 - `chronicle applications add`, `chronicle applications remove`
 
+Where the Cratis hooks are installed, this boundary is enforced: a `PreToolUse` guard on shell
+commands blocks every `cratis chronicle` command that is not on its read-only allowlist, unknown
+commands and the interactive `workbench` included, with or without `--yes`. When it blocks, do not
+retry or work around it; report the exact command, the target context or server, and what it
+changes and why, and ask. A person who authorizes the mutation runs it, or sets
+`CRATIS_HOOKS_ALLOW_STORE_MUTATIONS=1` in the environment the agent harness starts from.
+
 Before any of them:
 
 1. Name the exact server context, event store, namespace, observer, partition,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [