Files
gstack/bin/gstack-settings-hook
T
Garry Tanandcapy-ai[bot] 9610ba43db gstack's Codex hooks keep working with unusual folder paths and after uninstall (GST-3197) (#4528)
gstack's Codex hooks no longer block every prompt when your Codex
folder's path has a `(` or `&`, and uninstall keeps your own Codex hooks
trusted.

Why: both broke Codex sessions; setup also now matches Codex's hook
rules, and the /review checklist on Codex reads shell commands more
carefully.

Nothing to do: plain paths keep the exact hook command they had, so
Codex asks for no new trust.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Review-Finding: p1/specialist-batched#1 reader=red-team
Review-Finding: lib/codex-rollout.ts:217:functional-contract reader=qa
2026-11-19 15:42:21 +00:00

1330 lines
67 KiB
Bash
Executable File

#!/usr/bin/env bash
# gstack-settings-hook — manage Claude Code hooks in ~/.claude/settings.json
#
# Three shapes:
#
# 1. Legacy (SessionStart only — kept so old installs still clean up):
# gstack-settings-hook add <cmd> # adds SessionStart hook
# gstack-settings-hook remove <cmd> # removes gstack-session-update items
# # (the <cmd> arg is accepted for
# # interface compat; matching is by
# # the gstack-session-update basename)
#
# 2. Schema-aware (plan-tune cathedral T3):
# gstack-settings-hook add-event --event <name — see the validator in add-event> \
# --command <cmd> --source <tag> [--matcher <regex>] [--timeout <s>]
# gstack-settings-hook ensure-event --event ... --command ... --source ... [--matcher ...] [--timeout <s>]
# gstack-settings-hook remove-source --source <tag> [--event <name>]
# # removes items the table identifies as <tag>'s, tagged or not
# gstack-settings-hook diff-event --event ... --command ... --source ... [--matcher ...]
# gstack-settings-hook rollback # restore latest backup (single-step undo)
# gstack-settings-hook list-sources # show all gstack-tagged hook entries
# gstack-settings-hook list-items --event <name> [--owned-by <tag>] [--command-regex <js-re>]
# # read-only: one JSON string literal per matching hook COMMAND
# # (identity via KNOWN_HOOKS, never the tag); empty stdout = none
#
# 3. Self-heal (phantom-hooks fix):
# gstack-settings-hook prune-stale # prune dead gstack hook items
# gstack-settings-hook prune-stale --repoint <root> # re-point gstack items at <root>, prune still-dead
# gstack-settings-hook prune-stale --all # remove ALL gstack hook items (uninstall sweep)
#
# 4. Codex format (GSTACK_HOOKS_FORMAT=codex): the same verbs (but not the
# legacy add/remove) on ${CODEX_HOME:-~/.codex}/hooks.json, plus
# gstack-settings-hook trust-status # read-only: "<source>\t<event>\ttrusted|untrusted|disabled"
# Codex 0.170 skips the whole hooks.json when it holds a key it does not
# know, which would switch off the user's own hooks too. So this format
# never writes _gstack_source (identity is the KNOWN_HOOKS rows marked
# host codex), refuses a file that already fails the schema, re-reads the
# temp file against the schema before the rename, appends new groups after
# the user's (Codex keys trust by group index), and refuses ensure-event
# while config.toml declares a gstack hook under [hooks] (it would run twice).
#
# ensure-event is the update-in-place verb: same flags as add-event, but keyed
# on (event, source) — any entry carrying our source tag for the event is THE
# registration to compare/update, so a matcher change re-points in place
# instead of pushing a second entry, and duplicate same-source twins from the
# old matcher-keyed dedup collapse to one (reported on stderr). Identical
# payload → no write, no backup ("unchanged"); a re-run of ./setup stays a
# true no-op. This heals a stale absolute hook path (e.g. a deleted dev
# worktree) baked into settings.json by an earlier setup.
#
# Ownership model (KNOWN_HOOKS identity table): a hook ITEM is gstack-owned iff
# its command basename + relpath suffix + event (+ matcher where the table row
# defines one) match a table row. Entry-level `_gstack_source` tags are
# best-effort metadata — Claude Code strips unknown keys when it rewrites
# settings.json, so identity is intrinsic (the table), never tag-only. A tag
# NEVER claims foreign items: in a tagged multi-item entry, unrecognized items
# are always preserved; only a tagged SINGLE-item entry with no table match is
# treated as an owned legacy stray.
#
# Mutation safety:
# - every mutation runs under a lock directory (<settings>.lock/) whose owner
# token file is created with O_EXCL (gstack_lock_take, bin/gstack-lock.sh;
# mkdir's exit status is not a lock on Ubuntu 26.04's uutils mkdir);
# release is ownership-checked; stale locks (>30s) are taken over
# via atomic rename. On lock give-up the mutation is SKIPPED with a warning
# (the next setup retries — the system is convergent).
# - parse failure fails CLOSED: a corrupt settings.json is never overwritten
# (only ENOENT starts fresh). Exit 3.
# - backup-on-change: a backup (unique name, .bak-latest pointer) is written
# only when the file content actually changes. No-op mutations are silent
# on disk. `rollback` is a single-step undo of the last real mutation.
# - writes are atomic: unique tmp file + rename (a fixed tmp name would let
# two concurrent writers rename a half-written file into place).
# Heredoc delivery guard. bash 5.2+ writes a heredoc body <=64KiB through a
# pipe in the forked child before exec, with no reader on the other end. On
# macOS under pipe-KVA pressure a fresh pipe gets a 512-byte buffer, so any
# body >=512B blocks write() forever and the script hangs at startup with no
# output. Compat level 50 restores the tempfile path. These scripts are
# bash-3.2-clean, so the compat level costs them nothing. Not exported: the
# guard is per-script, and it survives `bash script.sh` call sites that
# bypass the shebang.
BASH_COMPAT=50
set -euo pipefail
GSTACK_BUN_CONFIG=/dev/null; case "${OSTYPE:-}" in msys*|cygwin*) if command -v cygpath >/dev/null 2>&1; then GSTACK_BUN_CONFIG=NUL; fi ;; esac
ACTION="${1:-}"
SETTINGS_FILE="${GSTACK_SETTINGS_FILE:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json}"
if [ "${GSTACK_HOOKS_FORMAT:-}" = codex ]; then
SETTINGS_FILE="${GSTACK_SETTINGS_FILE:-${CODEX_HOME:-$HOME/.codex}/hooks.json}"
# Codex reads config.toml from CODEX_HOME, beside the hooks.json path it was
# given, so take its directory before the symlink-resolving step below.
GSTACK_CODEX_CONFIG="${GSTACK_CODEX_CONFIG:-$(dirname "$SETTINGS_FILE")/config.toml}"
export GSTACK_CODEX_CONFIG
case "$ACTION" in
add|remove) echo "gstack-settings-hook: $ACTION is the legacy settings.json verb; use ensure-event or remove-source with GSTACK_HOOKS_FORMAT=codex" >&2; exit 1 ;;
esac
fi
if [ -z "$ACTION" ]; then
cat <<EOF >&2
Usage:
gstack-settings-hook add <hook-command> # legacy SessionStart add
gstack-settings-hook remove <hook-command> # legacy SessionStart remove
gstack-settings-hook add-event --event <name> --command <cmd> --source <tag> [--matcher <re>] [--timeout <s>]
gstack-settings-hook ensure-event --event <name> --command <cmd> --source <tag> [--matcher <re>] [--timeout <s>]
gstack-settings-hook remove-source --source <tag> [--event <name>] # tagged OR table-identified items of <tag>
gstack-settings-hook diff-event --event <name> --command <cmd> --source <tag> [--matcher <re>] [--timeout <s>]
gstack-settings-hook prune-stale [--repoint <root>] [--all]
gstack-settings-hook rollback
gstack-settings-hook list-sources
gstack-settings-hook list-items --event <name> [--owned-by <tag>] [--command-regex <js-re>]
GSTACK_HOOKS_FORMAT=codex gstack-settings-hook <verb> ... # Codex hooks.json; adds trust-status
EOF
exit 1
fi
if ! command -v bun >/dev/null 2>&1; then
echo "Error: bun is required but not installed." >&2
exit 1
fi
# ─── Shared JS prelude ────────────────────────────────────────────────
# Single source of truth for the KNOWN_HOOKS identity table and the
# ownership/liveness/IO helpers, interpolated into EVERY bun -e script as
# bun -e "$_HOOK_JS_PRELUDE"' <single-quoted body>'
# so the dedupe key and the prune predicate cannot drift. The prelude MUST NOT
# contain single quotes (this assignment is single-quoted).
_HOOK_JS_PRELUDE='
// Umbrella fail-closed guard: bun in -e mode swallows uncaught exceptions
// thrown after a require() call and exits 0 (verified on bun 1.3.13;
// uncaughtException handlers never fire in -e mode either). Every script body
// below runs inside gsMain so a runtime throw becomes a LOUD exit 4 instead
// of a silent success that reports a mutation as clean.
function gsMain(fn) {
try {
fn();
} catch (e) {
if (e && e.gstackUnreadableSettings === true) {
process.stderr.write("gstack-settings-hook: " + e.message + " -- refusing to mutate\n");
process.exit(3);
}
process.stderr.write("gstack-settings-hook: internal error (" + (e && e.message) + ") -- refusing to mutate\n");
process.exit(4);
}
}
var KNOWN_HOOKS = {
"question-log-hook": { source: "plan-tune-cathedral", event: "PostToolUse", matcher: "(AskUserQuestion|mcp__.*__AskUserQuestion)", relpath: "hosts/claude/hooks/question-log-hook" },
"question-preference-hook": { source: "plan-tune-cathedral", event: "PreToolUse", matcher: "(AskUserQuestion|mcp__.*__AskUserQuestion)", relpath: "hosts/claude/hooks/question-preference-hook" },
"auq-error-fallback-hook": { source: "auq-error-fallback", event: "PostToolUse", matcher: "(AskUserQuestion|mcp__.*__AskUserQuestion)", relpath: "hosts/claude/hooks/auq-error-fallback-hook" },
"timeline-stop-hook": { source: "gstack-timeline-stop", event: "Stop", matcher: "", relpath: "hosts/claude/hooks/timeline-stop-hook" },
"memorable-user-prompt-hook": { source: "gstack-memorable", event: "UserPromptSubmit", matcher: "", relpath: "hosts/claude/hooks/memorable-user-prompt-hook" },
"gstack-session-update": { source: "gstack-session-update", event: "SessionStart", matcher: "", relpath: "bin/gstack-session-update" },
"gstack-verify-gate": { source: "verify-gate", event: "Stop", matcher: "", relpath: "bin/gstack-verify-gate" },
"skill-route-hook": { source: "gstack-skill-route", event: "UserPromptSubmit", matcher: "", relpath: "hosts/claude/hooks/skill-route-hook" },
"skill-contract-stop-hook": { source: "gstack-skill-contract", event: "Stop", matcher: "", relpath: "hosts/claude/hooks/skill-contract-stop-hook" },
"destructive-guard-hook": { source: "gstack-destructive-guard", event: "PreToolUse", matcher: "Bash|PowerShell", relpath: "hosts/claude/hooks/destructive-guard-hook" },
"investigate-gate-pre": { source: "gstack-investigate-gate", event: "PreToolUse", matcher: "Edit|Write|MultiEdit|NotebookEdit|Bash", relpath: "hosts/claude/hooks/investigate-gate-pre" },
"investigate-gate-post": { source: "gstack-investigate-gate", event: "PostToolUse", matcher: "Bash", relpath: "hosts/claude/hooks/investigate-gate-post" },
"investigate-gate-post-failure": { source: "gstack-investigate-gate", event: "PostToolUseFailure", matcher: "Bash", relpath: "hosts/claude/hooks/investigate-gate-post-failure" },
"investigate-gate-stop": { source: "gstack-investigate-gate", event: "Stop", matcher: "", relpath: "hosts/claude/hooks/investigate-gate-stop" },
"ceo-review-gate-stop": { source: "gstack-ceo-review-gate", event: "Stop", matcher: "", relpath: "hosts/claude/hooks/ceo-review-gate-stop" },
"ceo-review-gate-subagent-stop": { source: "gstack-ceo-review-gate", event: "SubagentStop", matcher: "", relpath: "hosts/claude/hooks/ceo-review-gate-subagent-stop" },
"autoplan-stop-gate-stop": { source: "gstack-autoplan-gate", event: "Stop", matcher: "", relpath: "hosts/claude/hooks/autoplan-stop-gate-stop" },
"autoplan-stop-gate-publish": { source: "gstack-autoplan-gate", event: "PreToolUse", matcher: "Bash", relpath: "hosts/claude/hooks/autoplan-stop-gate-publish" },
"codex-skill-route-hook": { source: "gstack-skill-route", event: "UserPromptSubmit", matcher: "", relpath: "hosts/codex/hooks/codex-skill-route-hook", host: "codex" },
"codex-destructive-guard-hook": { source: "gstack-destructive-guard", event: "PreToolUse", matcher: "Bash", relpath: "hosts/codex/hooks/codex-destructive-guard-hook", host: "codex" },
"codex-skill-contract-stop-hook": { source: "gstack-skill-contract", event: "Stop", matcher: "", relpath: "hosts/codex/hooks/codex-skill-contract-stop-hook", host: "codex" }
};
// GSTACK_HOOKS_FORMAT=codex: the file is Codex hooks.json, and only rows with
// host codex identify gstack items in it; every other row belongs to
// settings.json. Codex skips the whole hooks.json when any key is unknown, so
// in this format nothing writes a _gstack_source tag and every write is
// checked against the Codex 0.170 schema (gsCodexProblem) before the rename.
var GS_CODEX = process.env.GSTACK_HOOKS_FORMAT === "codex";
var GS_CODEX_EVENTS = ["PreModelRequest", "PostModelRequest", "PreToolUse", "PermissionRequest", "PostToolUse", "PreCompact", "PostCompact", "SessionStart", "SessionEnd", "UserPromptSubmit", "SubagentStart", "SubagentStop", "Stop", "Interrupt"];
var GS_CODEX_HANDLER_KEYS = {
command: ["type", "command", "commandWindows", "command_windows", "timeout", "async", "statusMessage", "additionalContextLimit"],
mcp_tool: ["type", "server", "tool", "input", "timeout", "statusMessage"],
prompt: ["type"],
agent: ["type"]
};
function gsTag(entry, source) { if (!GS_CODEX) entry._gstack_source = source; }
function gsCodexProblem(doc) {
var isObj = function (v) { return v !== null && typeof v === "object" && !Array.isArray(v); };
var isCount = function (v) { return typeof v === "number" && Number.isInteger(v) && v >= 0; };
// Codex 0.170 deserialize_mcp_tool_input: no null and no u64 past i64::MAX at
// any depth. JSON.parse cannot tell 2^63-1 from 2^63 or 1e19 from an integer,
// so integers from 2^63-1 up are refused too: refusing only leaves the file alone.
var tomlSafe = function (v) {
if (v === null) return false;
if (typeof v === "number") return !(Number.isInteger(v) && v >= 9223372036854775807);
if (Array.isArray(v)) return v.every(tomlSafe);
if (typeof v === "object") return Object.keys(v).every(function (k) { return tomlSafe(v[k]); });
return true;
};
var extra = function (o, allowed, at) {
var k = Object.keys(o).find(function (x) { return allowed.indexOf(x) < 0; });
return k === undefined ? null : at + " has the key " + JSON.stringify(k) + ", which Codex does not know";
};
if (!isObj(doc)) return "the top level is not an object";
var bad = extra(doc, ["description", "hooks"], "the top level");
if (bad) return bad;
if (doc.description !== undefined && doc.description !== null && typeof doc.description !== "string") return "description is not a string";
if (doc.hooks === undefined) return null;
if (!isObj(doc.hooks)) return "hooks is not an object";
bad = extra(doc.hooks, GS_CODEX_EVENTS, "hooks");
if (bad) return bad;
for (var ev of Object.keys(doc.hooks)) {
var groups = doc.hooks[ev];
if (!Array.isArray(groups)) return "hooks." + ev + " is not an array";
for (var gi = 0; gi < groups.length; gi++) {
var g = groups[gi], at = "hooks." + ev + "[" + gi + "]";
if (!isObj(g)) return at + " is not an object";
bad = extra(g, ["matcher", "hooks"], at);
if (bad) return bad;
if (g.matcher !== undefined && g.matcher !== null && typeof g.matcher !== "string") return at + ".matcher is not a string";
if (g.hooks === undefined) continue;
if (!Array.isArray(g.hooks)) return at + ".hooks is not an array";
for (var hi = 0; hi < g.hooks.length; hi++) {
var h = g.hooks[hi], hat = at + ".hooks[" + hi + "]";
if (!isObj(h)) return hat + " is not an object";
var keys = Object.prototype.hasOwnProperty.call(GS_CODEX_HANDLER_KEYS, h.type) ? GS_CODEX_HANDLER_KEYS[h.type] : null;
if (!keys) return hat + ".type is " + JSON.stringify(h.type) + ", which Codex does not know";
bad = extra(h, keys, hat);
if (bad) return bad;
if (h.type === "command" && typeof h.command !== "string") return hat + ".command is not a string";
if (h.type === "mcp_tool" && (typeof h.server !== "string" || typeof h.tool !== "string")) return hat + " needs string server and tool";
if (h.type === "mcp_tool" && h.input !== undefined && !isObj(h.input)) return hat + ".input is not an object";
if (h.type === "mcp_tool" && h.input !== undefined && !tomlSafe(h.input)) return hat + ".input holds a null or an integer too large for TOML, which Codex rejects (MCP hook input must be representable as TOML)";
if (h.timeout !== undefined && !isCount(h.timeout)) return hat + ".timeout is not a whole number of seconds";
if (h.additionalContextLimit !== undefined && !isCount(h.additionalContextLimit)) return hat + ".additionalContextLimit is not a whole number";
if (h.async !== undefined && typeof h.async !== "boolean") return hat + ".async is not true or false";
for (var sk of ["statusMessage", "commandWindows", "command_windows"]) {
if (h[sk] !== undefined && typeof h[sk] !== "string") return hat + "." + sk + " is not a string";
}
}
}
}
return null;
}
function gsCodexConfigClash() {
// config.toml [hooks] tables load beside hooks.json in the same layer, so a
// gstack hook declared in both runs twice. Refuse instead of adding it.
var fs = require("fs");
var file = process.env.GSTACK_CODEX_CONFIG;
var raw;
try { raw = fs.readFileSync(file, "utf8"); }
catch (e) { if (e && e.code === "ENOENT") return; throw e; }
var cfg;
try { cfg = Bun.TOML.parse(raw); }
catch (e) {
throw Object.assign(new Error(file + " does not parse (" + e.message + "), so gstack cannot check it for hooks it already declares -- fix it and re-run ./setup"), { gstackUnreadableSettings: true });
}
var hooks = cfg && cfg.hooks;
if (!hooks || typeof hooks !== "object") return;
for (var ev of Object.keys(hooks)) {
if (ev === "state" || !Array.isArray(hooks[ev])) continue;
for (var g of hooks[ev]) {
for (var h of (g && Array.isArray(g.hooks) ? g.hooks : [])) {
var row = h && typeof h.command === "string" ? gsOwnedRow(h.command, ev, g.matcher || "") || gsCodexClashRow(h.command, ev, g.matcher) : null;
if (row) {
throw Object.assign(new Error(file + " already declares gstack hook " + row.source + " under [hooks." + ev + "], and Codex would run it twice -- remove it from config.toml (gstack keeps its hooks in hooks.json) and re-run ./setup"), { gstackUnreadableSettings: true });
}
}
}
}
}
// A gstack command declared under another matcher still runs twice when that
// matcher selects a tool the row names: Codex 0.170 matcher.rs treats empty
// or "*" as every tool, [A-Za-z0-9_|] as exact names and anything else as an
// unanchored regex (Rust syntax: a leading (?i), (?m) or (?s) group and \A / \z
// are translated). A matcher JS still cannot compile counts as a clash
// (refusal is the safe side). Bash, the only tool a Codex row names, has no matcher aliases.
function gsCodexClashRow(cmd, event, matcher) {
var b = gsBaseOf(cmd);
var row = Object.prototype.hasOwnProperty.call(KNOWN_HOOKS, b) ? KNOWN_HOOKS[b] : null;
if (!row || !gsOwnedRow(cmd, event, row.matcher)) return null;
if (!row.matcher || matcher === undefined || matcher === null || matcher === "" || matcher === "*") return row;
var tools = row.matcher.split("|");
if (/^[A-Za-z0-9_|]+$/.test(matcher)) {
var names = matcher.split("|");
return tools.some(function (t) { return names.indexOf(t) >= 0; }) ? row : null;
}
var src = matcher, flags = "";
var lead = /^\(\?([a-zA-Z]+)\)/.exec(src);
if (lead) {
if (/[^ims]/.test(lead[1])) return row;
flags = lead[1];
src = src.slice(lead[0].length);
}
src = src.replace(/(^|[^\\])((?:\\\\)*)\\A/g, "$1$2^").replace(/(^|[^\\])((?:\\\\)*)\\z/g, "$1$2$$");
var re;
try { re = new RegExp(src, flags); } catch (e) {
try { re = new RegExp(src, flags + "u"); } catch (e2) { return row; }
}
return tools.some(function (t) { return re.test(t); }) ? row : null;
}
function gsCodexRefuse(path, problem) {
throw Object.assign(new Error(path + " does not match the Codex hooks.json schema (" + problem + "); Codex skips that whole file, so gstack will not write it -- fix the file (or move it aside) and re-run ./setup"), { gstackUnreadableSettings: true });
}
function gsCodexMovedUserHooks(beforeText, settings) {
var before;
try { before = JSON.parse(beforeText); } catch (e) { return []; }
var bh = (before && before.hooks) || {};
var ah = (settings && settings.hooks) || {};
var moved = [];
Object.keys(bh).forEach(function (ev) {
(Array.isArray(bh[ev]) ? bh[ev] : []).forEach(function (g, gi) {
(g && Array.isArray(g.hooks) ? g.hooks : []).forEach(function (h, hi) {
if (h && h.type === "command" && gsOwnedRow(h.command, ev, g.matcher || "")) return;
var ag = (Array.isArray(ah[ev]) ? ah[ev] : [])[gi];
var same = ag && Array.isArray(ag.hooks) && JSON.stringify(ag.hooks[hi]) === JSON.stringify(h) && (ag.matcher || "") === (g.matcher || "");
if (!same && moved.indexOf(ev) < 0) moved.push(ev);
});
});
});
return moved;
}
// The gstack handlers in beforeText that this change removes or moves, named by
// position and command: the refusal below tells the user to delete only these,
// never the group around them (a group can hold their own handlers too).
function gsCodexGstackHandlers(beforeText, settings) {
var before;
try { before = JSON.parse(beforeText); } catch (e) { return []; }
var bh = (before && before.hooks) || {};
var ah = (settings && settings.hooks) || {};
var out = [];
Object.keys(bh).forEach(function (ev) {
(Array.isArray(bh[ev]) ? bh[ev] : []).forEach(function (g, gi) {
(g && Array.isArray(g.hooks) ? g.hooks : []).forEach(function (h, hi) {
if (!(h && h.type === "command" && gsOwnedRow(h.command, ev, g.matcher || ""))) return;
var ag = (Array.isArray(ah[ev]) ? ah[ev] : [])[gi];
if (ag && Array.isArray(ag.hooks) && JSON.stringify(ag.hooks[hi]) === JSON.stringify(h)) return;
out.push("hooks." + ev + "[" + gi + "].hooks[" + hi + "] (command " + JSON.stringify(h.command) + ")");
});
});
});
return out;
}
// Removing a Codex group shifts every later group of that event down one
// index, and Codex keys trust by index. A group gstack empties therefore stays
// as {"hooks": []} while any group follows it: Codex 0.170 enumerates empty
// groups when it numbers them (discovery.rs append_matcher_groups), loads one
// with no warning, and hashes only event, matcher and handler, so every later
// key and hash stays the same. Slots gstack makes at the end are dropped; the
// marker is not enumerable, so it never reaches the file.
function gsCodexSlot() {
var slot = { hooks: [] };
Object.defineProperty(slot, "gsSlot", { value: true });
return slot;
}
function gsCodexTrimSlots(groups) {
while (groups.length > 0 && groups[groups.length - 1] && groups[groups.length - 1].gsSlot === true) groups.pop();
return groups;
}
function gsHadBashPrefix(c) { return String(c == null ? "" : c).trim().indexOf("bash ") === 0; }
function gsStripWrap(c) {
var s = String(c == null ? "" : c).trim();
if (s.indexOf("bash ") === 0) s = s.slice(5).trim();
if (s.length >= 2 && s.charAt(0) === "\"" && s.charAt(s.length - 1) === "\"") {
// Unescape the gsQuoteCmd form so a re-pointed escaped command is still
// recognized as ours on later passes (identity round-trips).
s = s.slice(1, -1).replace(/\\([\\"$\x60])/g, "$1");
}
// Separator normalization is Windows-only (a rare-but-legal Unix path
// containing a backslash must not be rewritten and mis-stat-ed).
if (process.platform === "win32" || /^[A-Za-z]:[\\\/]/.test(s)) {
s = s.replace(/\\/g, "/");
}
return s;
}
function gsBaseOf(c) { var p = gsStripWrap(c); return p.split("/").pop(); }
function gsOwnedRow(cmd, event, matcher) {
var p = gsStripWrap(cmd);
var b = p.split("/").pop();
// hasOwnProperty guard: a foreign hook basename like "toString" or
// "constructor" must not resolve to an inherited Object.prototype member.
var row = Object.prototype.hasOwnProperty.call(KNOWN_HOOKS, b) ? KNOWN_HOOKS[b] : null;
if (!row) return null;
if (p !== row.relpath && p.slice(-(row.relpath.length + 1)) !== "/" + row.relpath) return null;
if (row.event !== event) return null;
if (row.matcher && (matcher || "") !== row.matcher) return null;
if ((row.host || "claude") !== (GS_CODEX ? "codex" : "claude")) return null;
return row;
}
function gsWinPath(p) {
// Git Bash writes MSYS-form paths (/c/Users/...) into settings.json, but
// native bun resolves them drive-relative (C:\c\Users\...) -- translate for
// fs calls only; stored commands keep the form the firing shell expects.
if (process.platform === "win32" && /^\/[A-Za-z]\//.test(p)) {
return p.charAt(1) + ":" + p.slice(2);
}
return p;
}
function gsResolveSettingsPath(input) {
var fs = require("fs");
var path = require("path");
var absolute = path.resolve(gsWinPath(input));
var resolved;
try { resolved = fs.realpathSync(absolute); }
catch (e) {
if (e && (e.code === "EACCES" || e.code === "EPERM")) {
throw Object.assign(new Error("cannot read " + absolute + " (" + e.code + ")"), { gstackUnreadableSettings: true });
}
if (!e || e.code !== "ENOENT") throw e;
try {
if (fs.lstatSync(absolute).isSymbolicLink()) throw new Error("settings link has no target");
} catch (missing) {
if (!missing || missing.code !== "ENOENT") throw missing;
}
resolved = path.join(gsResolveSettingsPath(path.dirname(absolute)), path.basename(absolute));
}
return process.platform === "win32" ? resolved.replace(/\\/g, "/") : resolved;
}
function gsAssertSettingsTarget(settingsPath) {
if (gsResolveSettingsPath(process.env.GSTACK_SETTINGS_INPUT) !== settingsPath) {
throw new Error("settings target changed while waiting or writing");
}
}
function gsSettingsIdentity(settingsPath) {
var fs = require("fs");
try {
var stat = fs.lstatSync(settingsPath, { bigint: true });
if (!stat.isFile()) throw new Error("settings target is not a regular file");
return [stat.dev, stat.ino, stat.size, stat.mode, stat.mtimeNs, stat.ctimeNs].join(":");
} catch (e) {
if (e && e.code === "ENOENT") return null;
throw e;
}
}
var gsLoadedIdentity;
function gsAssertSettingsUnchanged(settingsPath) {
gsAssertSettingsTarget(settingsPath);
if (gsSettingsIdentity(settingsPath) !== gsLoadedIdentity) {
throw new Error("settings changed during mutation");
}
}
function gsIsAlive(cmd) {
var fs = require("fs");
var p = gsWinPath(gsStripWrap(cmd));
if (!p) return false;
try {
if (process.platform === "win32") return fs.existsSync(p);
var st = fs.statSync(p);
if (!st.isFile()) return false;
fs.accessSync(p, fs.constants.X_OK);
return true;
} catch (e) {
// Only provable absence counts as dead. EACCES/EIO/unmounted-volume
// errors are transient unreachability -- pruning on those would be a
// one-way ratchet, so conservatively treat the item as alive.
var code = e && e.code;
return !(code === "ENOENT" || code === "ENOTDIR");
}
}
function gsQuoteCmd(target, hadBash) {
// Shell-metacharacter hardening: Claude Code and Codex both run the command
// string through a shell, so any path character outside the plain set
// (letters, digits, non-ASCII, and _ @ % + = : , . / -) is wrapped in double
// quotes, with $, backtick (x60 -- written as an escape so the prelude itself
// stays backtick-free), quote and backslash escaped. A bare ( or & is a
// syntax error, exit 2, which Codex reads as a block on every event.
var needsQuote = /[^A-Za-z0-9_@%+=:,.\/\x2d\u0080-\uffff]/.test(target);
var quoted = needsQuote
? "\"" + target.replace(/[\\"$\x60]/g, function (ch) { return "\\" + ch; }) + "\""
: target;
return (hadBash ? "bash " : "") + quoted;
}
function gsRotateBackups(settingsPath, keep) {
// Backup files are change-gated but unbounded across months of setups --
// keep the most recent N so ~/.claude does not accumulate forever.
var fs = require("fs");
var path = require("path");
try {
var dir = path.dirname(settingsPath);
var base = path.basename(settingsPath) + ".bak.";
var baks = fs.readdirSync(dir)
.filter(function (f) { return f.indexOf(base) === 0; })
.map(function (f) {
var full = path.join(dir, f);
var m = 0;
try { m = fs.statSync(full).mtimeMs; } catch (e3) {}
return { full: full, m: m };
})
.sort(function (a, b) { return a.m - b.m; });
for (var i = 0; i < baks.length - keep; i++) {
try { fs.unlinkSync(baks[i].full); } catch (e2) {}
}
} catch (e) {}
}
function gsLoadSettings(path) {
var fs = require("fs");
gsAssertSettingsTarget(path);
gsLoadedIdentity = gsSettingsIdentity(path);
var raw = null;
try { raw = fs.readFileSync(path, "utf8"); }
catch (e) {
if (e && e.code === "ENOENT") return { settings: {}, existed: false };
process.stderr.write("gstack-settings-hook: cannot read " + path + ": " + e.message + " -- refusing to mutate\n");
process.exit(3);
}
var parsed;
try { parsed = JSON.parse(raw); }
catch (e) {
process.stderr.write("gstack-settings-hook: " + path + " is not valid JSON (" + e.message + ") -- refusing to mutate; fix or restore it (.bak files / rollback)\n");
process.exit(3);
}
if (GS_CODEX) {
var problem = gsCodexProblem(parsed);
if (problem) gsCodexRefuse(path, problem);
}
return { settings: parsed, existed: true };
}
function gsWriteIfChanged(path, beforeText, settings, existed) {
var fs = require("fs");
var afterText = JSON.stringify(settings, null, 2);
if (afterText === beforeText) return false;
if (GS_CODEX) {
var moved = gsCodexMovedUserHooks(beforeText, settings);
if (moved.length > 0) {
var ours = gsCodexGstackHandlers(beforeText, settings);
throw Object.assign(new Error("left " + path + " unchanged: this change would move your own " + moved.join(", ") + " hooks, which come after the gstack hook there, to new positions. Codex keys hook trust by position, so they would stop running until you trust them again, and codex exec would skip them without asking. To remove the gstack hook yourself, delete only the gstack handler" + (ours.length === 1 ? " " : "s ") + ours.join(", ") + " from " + path + ", keeping your own handlers and groups as they are, then re-trust your hooks in Codex with /hooks"), { gstackUnreadableSettings: true });
}
}
gsAssertSettingsUnchanged(path);
// Preserve the live file mode across the tmp+rename (settings.json can
// carry API keys in its env block -- a user-tightened 0600 must never be
// silently broadened to the default 0644). Fresh files start 0600.
var mode = 0o600;
if (existed) {
try { mode = fs.statSync(path).mode & 0o777; } catch (e) {}
fs.copyFileSync(path, process.env.GSTACK_BACKUP_PATH);
fs.writeFileSync(process.env.GSTACK_BAK_LATEST, process.env.GSTACK_BACKUP_PATH + "\n");
gsRotateBackups(path, 10);
}
var tmp = process.env.GSTACK_TMP_PATH;
if (GS_CODEX) {
var before = gsCodexProblem(settings);
if (before) gsCodexRefuse(path, "the new content: " + before);
}
fs.writeFileSync(tmp, afterText + "\n", { mode: mode, flag: "wx" });
try {
fs.chmodSync(tmp, mode);
if (GS_CODEX) {
var reread = gsCodexProblem(JSON.parse(fs.readFileSync(tmp, "utf8")));
if (reread) gsCodexRefuse(path, "the written copy: " + reread);
}
gsAssertSettingsUnchanged(path);
fs.renameSync(tmp, path);
} finally {
try { fs.unlinkSync(tmp); } catch (e) { if (e.code !== "ENOENT") throw e; }
}
return true;
}
'
GSTACK_SETTINGS_INPUT="$SETTINGS_FILE"
export GSTACK_SETTINGS_INPUT
SETTINGS_FILE=$(bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
process.stdout.write(gsResolveSettingsPath(process.env.GSTACK_SETTINGS_INPUT));
});') || exit $?
# ─── Mutation lock ────────────────────────────────────────────────────
# Accepted tradeoffs (adversarial-reviewed): (1) the lock serializes gstack
# writers only -- Claude Code rewrites settings.json without honoring it, so a
# lost update against a live session remains possible (convergent: the next
# heal repairs); (2) stale takeover is mtime-based -- a holder legitimately
# slower than the stale window can be stolen from, and a fresh crash stalls
# callers for the give-up window. PID-aware takeover was considered and
# deferred (owner file already carries $$ if it becomes worth it).
_LOCK_DIR="$SETTINGS_FILE.lock"
_LOCK_TOKEN=""
_release_lock() {
if [ -n "$_LOCK_TOKEN" ] && [ -d "$_LOCK_DIR" ]; then
# Ownership-checked: never remove a lock another process re-acquired
# after a stale takeover.
_OWNER_CONTENT="$(cat "$_LOCK_DIR/owner" 2>/dev/null || true)"
if [ "$_OWNER_CONTENT" = "$_LOCK_TOKEN" ] || [ -z "$_OWNER_CONTENT" ]; then
rm -rf "$_LOCK_DIR" 2>/dev/null || true
fi
fi
_LOCK_TOKEN=""
}
_acquire_lock() {
# GSTACK_SETTINGS_LOCK_TIMEOUT_MS: test-only override for the give-up
# (a contention test should not stall the suite for 10 real seconds).
local waited_ms=0 token stale mtime now vanished=0
local give_up_ms="${GSTACK_SETTINGS_LOCK_TIMEOUT_MS:-10000}"
local stale_after_s=30 # lock older than this belongs to a crashed holder
local poll_ms=50 # retry cadence; sleep below derives from this
token="$$-$RANDOM$RANDOM"
. "$(cd "$(dirname "$0")" && pwd)/gstack-lock.sh" 2>/dev/null || { echo "gstack-settings-hook: $(dirname "$0")/gstack-lock.sh is missing -- skipping this mutation, exit 5 (fix: reinstall with ./setup)" >&2; return 1; }
while :; do
if gstack_lock_take "$_LOCK_DIR" owner "$token"; then
_LOCK_TOKEN="$token"
trap _release_lock EXIT
trap 'exit 129' INT
trap 'exit 143' TERM
return 0
fi
# The take failed but no lock dir exists: either a holder released between
# our take and this check, or NOT contention (unwritable parent, read-only
# fs, missing directory). Retry the take once; a second failure with still no
# lock dir is the environment, and waiting cannot help, so give up loudly
# now instead of spinning out the full timeout.
if [ ! -e "$_LOCK_DIR" ]; then
if [ "$vanished" -eq 0 ]; then vanished=1; continue; fi
echo "gstack-settings-hook: cannot create lock $_LOCK_DIR (unwritable parent?) -- skipping this mutation, exit 5" >&2
return 1
fi
vanished=0
# Stale takeover: atomic rename means exactly one contender wins; the
# loser loops and re-contends against the winner's fresh mkdir.
# GNU stat (-c %Y) first: on Linux, BSD-style `stat -f %m` prints a
# multi-line FILESYSTEM block to stdout before failing, and the || chain
# would capture that garbage alongside the real epoch. BSD stat rejects
# -c with no stdout, so macOS falls through cleanly. The numeric guard
# below makes any residual garbage inert (no takeover, normal give-up)
# instead of an arithmetic abort under set -e.
mtime=$(stat -c %Y "$_LOCK_DIR" 2>/dev/null || stat -f %m "$_LOCK_DIR" 2>/dev/null || echo "")
case "$mtime" in *[!0-9]*) mtime="" ;; esac
now=$(date +%s)
if [ -n "$mtime" ] && [ $(( now - mtime )) -gt "$stale_after_s" ]; then
stale="$_LOCK_DIR.stale.$$-$RANDOM"
if mv "$_LOCK_DIR" "$stale" 2>/dev/null; then rm -rf "$stale" 2>/dev/null || true; fi
continue
fi
if [ "$waited_ms" -ge "$give_up_ms" ]; then
echo "gstack-settings-hook: could not acquire lock $_LOCK_DIR -- skipping this mutation, exit 5 (the next setup retries it)" >&2
return 1
fi
sleep "$(printf '0.%03d' "$poll_ms")"
waited_ms=$(( waited_ms + poll_ms ))
done
}
# Per-invocation unique backup + tmp paths, exported for gsWriteIfChanged.
_mutation_env() {
GSTACK_BACKUP_PATH="$SETTINGS_FILE.bak.$(date +%Y%m%d-%H%M%S).$$.$RANDOM"
GSTACK_BAK_LATEST="$SETTINGS_FILE.bak-latest"
GSTACK_TMP_PATH="$SETTINGS_FILE.tmp.$$.$RANDOM"
export GSTACK_BACKUP_PATH GSTACK_BAK_LATEST GSTACK_TMP_PATH
}
case "$ACTION" in
# --- legacy SessionStart add/remove (backwards compat) -----------------
add)
HOOK_CMD="${2:-}"
if [ -z "$HOOK_CMD" ]; then
echo "Usage: gstack-settings-hook add <hook-command>" >&2
exit 1
fi
_acquire_lock || exit 5
_mutation_env
GSTACK_SETTINGS_PATH="$SETTINGS_FILE" GSTACK_HOOK_CMD="$HOOK_CMD" bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
const settingsPath = process.env.GSTACK_SETTINGS_PATH;
const hookCmd = process.env.GSTACK_HOOK_CMD;
const loaded = gsLoadSettings(settingsPath);
const settings = loaded.settings;
const before = JSON.stringify(settings, null, 2);
if (!settings.hooks) settings.hooks = {};
if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
const exists = settings.hooks.SessionStart.some(entry =>
entry.hooks && entry.hooks.some(h => h.command && h.command.includes("gstack-session-update"))
);
if (!exists) {
settings.hooks.SessionStart.push({
hooks: [{ type: "command", command: hookCmd }]
});
}
gsWriteIfChanged(settingsPath, before, settings, loaded.existed);
});
'
;;
remove)
HOOK_CMD="${2:-}"
if [ -z "$HOOK_CMD" ]; then
echo "Usage: gstack-settings-hook remove <hook-command>" >&2
exit 1
fi
[ -f "$SETTINGS_FILE" ] || exit 1
_acquire_lock || exit 5
_mutation_env
GSTACK_SETTINGS_PATH="$SETTINGS_FILE" bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
const settingsPath = process.env.GSTACK_SETTINGS_PATH;
const loaded = gsLoadSettings(settingsPath);
const settings = loaded.settings;
const before = JSON.stringify(settings, null, 2);
if (settings.hooks && settings.hooks.SessionStart) {
// Item-aware: remove only matching hook items; foreign items in the
// same entry survive; an entry is dropped ONLY when this pass emptied
// it. Malformed/foreign entries (hooks absent, non-array, or already
// empty) are preserved verbatim -- they are not ours to judge.
settings.hooks.SessionStart = settings.hooks.SessionStart
.filter(entry => {
if (!Array.isArray(entry.hooks)) return true;
const beforeLen = entry.hooks.length;
entry.hooks = entry.hooks.filter(h =>
!(h && h.command && h.command.includes("gstack-session-update"))
);
if (entry.hooks.length === 0 && beforeLen > 0) return false;
return true;
});
if (settings.hooks.SessionStart.length === 0) delete settings.hooks.SessionStart;
if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
}
gsWriteIfChanged(settingsPath, before, settings, loaded.existed);
});
'
;;
add-event|diff-event|ensure-event)
EVENT=""
COMMAND=""
SOURCE=""
MATCHER=""
TIMEOUT=""
shift
while [ $# -gt 0 ]; do
case "$1" in
--event) EVENT="$2"; shift 2 ;;
--command) COMMAND="$2"; shift 2 ;;
--source) SOURCE="$2"; shift 2 ;;
--matcher) MATCHER="$2"; shift 2 ;;
--timeout) TIMEOUT="$2"; shift 2 ;;
*) echo "unknown flag: $1" >&2; exit 1 ;;
esac
done
if [ -z "$EVENT" ] || [ -z "$COMMAND" ] || [ -z "$SOURCE" ]; then
echo "add-event/ensure-event/diff-event require --event, --command, --source" >&2
exit 1
fi
case "$EVENT" in
SessionStart|PreToolUse|PostToolUse|PostToolUseFailure|UserPromptSubmit|Stop|SubagentStop|Notification) ;;
*) echo "invalid --event '$EVENT'; must be one of SessionStart|PreToolUse|PostToolUse|PostToolUseFailure|UserPromptSubmit|Stop|SubagentStop|Notification" >&2; exit 1 ;;
esac
DIFF_ONLY=""
ENSURE=""
if [ "$ACTION" = "diff-event" ]; then
DIFF_ONLY=1
else
[ "$ACTION" = "ensure-event" ] && ENSURE=1
_acquire_lock || exit 5
fi
_mutation_env
GSTACK_SETTINGS_PATH="$SETTINGS_FILE" \
GSTACK_EVENT="$EVENT" \
GSTACK_COMMAND="$COMMAND" \
GSTACK_SOURCE="$SOURCE" \
GSTACK_MATCHER="$MATCHER" \
GSTACK_TIMEOUT="$TIMEOUT" \
GSTACK_DIFF_ONLY="$DIFF_ONLY" \
GSTACK_ENSURE="$ENSURE" \
bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
const settingsPath = process.env.GSTACK_SETTINGS_PATH;
const event = process.env.GSTACK_EVENT;
const cmd = process.env.GSTACK_COMMAND;
const source = process.env.GSTACK_SOURCE;
const matcher = process.env.GSTACK_MATCHER || "";
const timeoutRaw = process.env.GSTACK_TIMEOUT || "";
const diffOnly = process.env.GSTACK_DIFF_ONLY === "1";
const ensure = process.env.GSTACK_ENSURE === "1";
const loaded = gsLoadSettings(settingsPath);
const settings = loaded.settings;
const before = JSON.stringify(settings, null, 2);
if (GS_CODEX) gsCodexConfigClash();
if (!settings.hooks) settings.hooks = {};
if (!settings.hooks[event]) settings.hooks[event] = [];
// add-event is the single quoting authority: normalize the command
// through the same round-trip the healer uses so metachar paths are
// registered in the escaped-quoted form from the start (a caller-side
// quoting step would drift per call site).
const cmdNorm = gsQuoteCmd(gsStripWrap(cmd), gsHadBashPrefix(cmd));
const hookEntry = { type: "command", command: cmdNorm };
if (timeoutRaw) {
const n = Number(timeoutRaw);
if (Number.isFinite(n) && n > 0) hookEntry.timeout = n;
}
// Identity is item-level and two-layer:
// - a same-event entry carrying OUR source tag is ours even under a
// DIFFERENT matcher (a matcher change must re-point in place, never
// push a second registration -- the old matcher-keyed dedupe
// duplicated the entry on every matcher change), and
// - a same-matcher entry containing our exact command or a table-owned
// item with our basename is OUR registration under a stale path
// (Claude Code strips _gstack_source on its own rewrites, so
// tag-based dedupe degrades).
// A tag never claims foreign items: in a multi-item entry only the
// identified item is touched; entries where no item can be identified
// as ours are left alone entirely.
const ourItemIdx = (entry) => {
if (!Array.isArray(entry.hooks)) return -1;
let idx = entry.hooks.findIndex(h => h && h.command === cmdNorm);
if (idx < 0) {
idx = entry.hooks.findIndex(h => {
if (!h || !h.command) return false;
const row = gsOwnedRow(h.command, event, entry.matcher || "");
return !!row && gsBaseOf(h.command) === gsBaseOf(cmdNorm);
});
}
if (idx < 0 && entry._gstack_source === source && entry.hooks.length === 1 && entry.hooks[0] && entry.hooks[0].command) idx = 0;
return idx;
};
const cands = [];
for (const entry of settings.hooks[event]) {
const idx = ourItemIdx(entry);
if (idx < 0) continue;
if (entry._gstack_source === source || (entry.matcher || "") === matcher) cands.push({ entry: entry, idx: idx });
}
let placed = false;
let collapsed = 0;
if (cands.length > 0) {
const primary = cands[0];
if ((primary.entry.matcher || "") === matcher) {
primary.entry.hooks[primary.idx] = hookEntry;
// Mixed-version ratchet guard: tag ONLY single-item entries (the
// item we just placed). Old gstack versions in sibling worktrees do
// entry-level ownership (remove-source deletes the whole tagged
// entry; add-event clobbers entry.hooks wholesale) -- a tag on a
// mixed entry hands them permission to destroy the user items in it.
if (primary.entry.hooks.length === 1) gsTag(primary.entry, source);
else delete primary.entry._gstack_source;
placed = true;
} else if (primary.entry.hooks.length === 1) {
// Tagged single-item entry under a stale matcher: the entry is
// exclusively ours, so re-point payload AND matcher in place.
primary.entry.hooks = [hookEntry];
gsTag(primary.entry, source);
if (matcher) primary.entry.matcher = matcher;
else delete primary.entry.matcher;
placed = true;
} else {
// Our item sits in a MIXED entry under a different matcher: the
// entry-level matcher also governs the foreign siblings, so pull
// our item out and register separately below.
primary.entry.hooks.splice(primary.idx, 1);
delete primary.entry._gstack_source;
}
// Duplicate registrations (e.g. same-source twins from the old
// matcher-keyed dedupe): remove OUR item from every other candidate.
for (let i = 1; i < cands.length; i++) {
cands[i].entry.hooks.splice(cands[i].idx, 1);
delete cands[i].entry._gstack_source;
collapsed++;
}
// Drop only entries WE emptied; started-empty foreign entries are
// never candidates, so they are preserved verbatim.
const emptied = e => Array.isArray(e.hooks) && e.hooks.length === 0 && cands.some(c => c.entry === e);
settings.hooks[event] = GS_CODEX
? gsCodexTrimSlots(settings.hooks[event].map(e => (emptied(e) ? gsCodexSlot() : e)))
: settings.hooks[event].filter(e => !emptied(e));
}
if (!placed) {
const newEntry = {};
gsTag(newEntry, source);
if (GS_CODEX && matcher) newEntry.matcher = matcher;
newEntry.hooks = [hookEntry];
if (!GS_CODEX && matcher) newEntry.matcher = matcher;
settings.hooks[event].push(newEntry);
}
const after = JSON.stringify(settings, null, 2);
if (diffOnly) {
console.log("--- BEFORE");
console.log(before);
console.log("--- AFTER");
console.log(after);
process.exit(0);
}
if (ensure && before === after) {
// Registered payload already matches the canonical one -- no write,
// no backup, no churn. Re-running ./setup stays a true no-op.
console.log("OK: " + event + " hook unchanged (source: " + source + ")");
process.exit(0);
}
gsWriteIfChanged(settingsPath, before, settings, loaded.existed);
if (collapsed > 0) {
console.error("collapsed " + collapsed + " duplicate (event, source) hook entr" + (collapsed === 1 ? "y" : "ies") + " for " + event + " (source: " + source + ")");
}
if (ensure && cands.length > 0) {
console.log("OK: " + event + " hook re-pointed (source: " + source + ")");
} else {
console.log("OK: " + event + " hook registered (source: " + source + ")");
}
});
'
;;
remove-source)
SOURCE=""
RS_EVENT=""
shift
while [ $# -gt 0 ]; do
case "$1" in
--source) SOURCE="$2"; shift 2 ;;
--event) RS_EVENT="$2"; shift 2 ;;
*) echo "unknown flag: $1" >&2; exit 1 ;;
esac
done
if [ -z "$SOURCE" ]; then
echo "remove-source requires --source <tag>" >&2
exit 1
fi
[ -f "$SETTINGS_FILE" ] || exit 0
_acquire_lock || exit 5
_mutation_env
GSTACK_SETTINGS_PATH="$SETTINGS_FILE" GSTACK_SOURCE="$SOURCE" GSTACK_RS_EVENT="$RS_EVENT" bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
const settingsPath = process.env.GSTACK_SETTINGS_PATH;
const source = process.env.GSTACK_SOURCE;
const onlyEvent = process.env.GSTACK_RS_EVENT || "";
const loaded = gsLoadSettings(settingsPath);
const settings = loaded.settings;
if (!settings.hooks) { console.log("OK: removed 0 hook entry/entries tagged source=" + source); process.exit(0); }
const before = JSON.stringify(settings, null, 2);
let removed = 0;
// Identity-aware removal (tag OR table). Claude Code strips the
// _gstack_source tag when it rewrites settings.json, so a tag-only
// off switch silently no-ops on exactly the entries it was written
// for. Decision per item, identity first (D = drop, K = keep):
//
// item -> | row.source == SOURCE | row of another source | no table row
// entry tagged SOURCE | D | K | D if single item, else K
// untagged / other tag | D | K | K
//
// Entries with nothing of ours stay byte-identical (tag included);
// an entry we emptied is dropped; a tagged entry we trimmed loses
// the tag with its last owned item. Callers that need every gstack
// item gone still pair this with prune-stale --all.
for (const event of Object.keys(settings.hooks)) {
if (onlyEvent && event !== onlyEvent) continue; // --event scopes the removal (Q3)
const entries = settings.hooks[event];
if (!Array.isArray(entries)) continue; // foreign shape: not ours to judge
const kept = [];
for (const entry of entries) {
const tagged = !!entry && entry._gstack_source === source;
if (!entry || !Array.isArray(entry.hooks) || entry.hooks.length === 0) {
if (tagged) { removed++; continue; } // tagged but empty/malformed: legacy stray
kept.push(entry); continue;
}
const single = entry.hooks.length === 1;
let touched = 0;
const remain = entry.hooks.filter(h => {
// Command-less items cannot be ours (gstack only writes
// type:command items) -- preserve them.
const cmd = (h && typeof h.command === "string") ? h.command : "";
const row = cmd ? gsOwnedRow(cmd, event, entry.matcher || "") : null;
const ours = !!row && row.source === source;
const stray = tagged && single && !!cmd && !row;
if (ours || stray) { removed++; touched++; return false; }
return true;
});
if (touched === 0) { kept.push(entry); continue; }
if (remain.length === 0) { if (GS_CODEX) kept.push(gsCodexSlot()); continue; }
entry.hooks = remain;
if (tagged) delete entry._gstack_source;
kept.push(entry);
}
settings.hooks[event] = GS_CODEX ? gsCodexTrimSlots(kept) : kept;
if (settings.hooks[event].length === 0) delete settings.hooks[event];
}
if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
gsWriteIfChanged(settingsPath, before, settings, loaded.existed);
console.log("OK: removed " + removed + " hook entry/entries tagged source=" + source);
});
'
;;
prune-stale)
REPOINT_ROOT=""
PRUNE_ALL=""
shift
while [ $# -gt 0 ]; do
case "$1" in
--repoint) REPOINT_ROOT="$2"; shift 2 ;;
--all) PRUNE_ALL=1; shift ;;
*) echo "unknown flag: $1" >&2; exit 1 ;;
esac
done
if [ -n "$REPOINT_ROOT" ] && [ -n "$PRUNE_ALL" ]; then
echo "prune-stale: --repoint and --all are mutually exclusive" >&2
exit 1
fi
if [ ! -f "$SETTINGS_FILE" ]; then
echo "OK: removed 0 gstack hook entries (repointed 0)"
exit 0
fi
# Explicit plan_tune_hooks opt-out: dead plan-tune items are still pruned,
# but live ones are never re-pointed (re-activation needs consent; removal
# of live ones is --no-team/uninstall territory).
GSTACK_PT_OPTOUT=0
# The opt-out lookup is repoint/heal-only — the --all sweep never
# re-points, and uninstall must not depend on a sibling gstack-config.
if [ -z "$PRUNE_ALL" ]; then
_CFG_BIN="$(cd "$(dirname "$0")" && pwd)/gstack-config"
if [ -x "$_CFG_BIN" ] && "$_CFG_BIN" has plan_tune_hooks 2>/dev/null; then
_PT_VAL=$("$_CFG_BIN" get plan_tune_hooks 2>/dev/null || true)
_PT_VAL=$(printf '%s' "$_PT_VAL" | tr '[:upper:]' '[:lower:]' | tr -d '[:space:]')
case "$_PT_VAL" in
n|no|false|skip|off|0) GSTACK_PT_OPTOUT=1 ;;
esac
fi
fi
_acquire_lock || exit 5
_mutation_env
GSTACK_SETTINGS_PATH="$SETTINGS_FILE" \
GSTACK_REPOINT_ROOT="$REPOINT_ROOT" \
GSTACK_PRUNE_ALL="$PRUNE_ALL" \
GSTACK_PT_OPTOUT="$GSTACK_PT_OPTOUT" \
GSTACK_SWEEP_EXCLUDE_SOURCES="${GSTACK_SWEEP_EXCLUDE_SOURCES:-}" \
bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
const settingsPath = process.env.GSTACK_SETTINGS_PATH;
const root = (process.env.GSTACK_REPOINT_ROOT || "").replace(/\/+$/, "");
const all = process.env.GSTACK_PRUNE_ALL === "1";
const ptOptout = process.env.GSTACK_PT_OPTOUT === "1";
const PT_SOURCES = { "plan-tune-cathedral": true, "auq-error-fallback": true };
// Sources a sweep must leave alone (e.g. `setup --no-team` excludes the
// user-registered verify-gate hook: turning team mode off must not
// delete an unrelated opt-in whose binary still exists).
const sweepExclude = {};
(process.env.GSTACK_SWEEP_EXCLUDE_SOURCES || "").split(",").forEach(function (sName) {
if (sName.trim()) sweepExclude[sName.trim()] = true;
});
const loaded = gsLoadSettings(settingsPath);
const settings = loaded.settings;
const before = JSON.stringify(settings, null, 2);
let removed = 0;
let repointed = 0;
if (settings.hooks) {
for (const event of Object.keys(settings.hooks)) {
const rebuilt = [];
for (const entry of settings.hooks[event]) {
if (!Array.isArray(entry.hooks)) { rebuilt.push(entry); continue; }
const matcher = entry.matcher || "";
const wasSingle = entry.hooks.length === 1;
const remain = [];
const seenInEntry = new Set();
if (entry.hooks.length === 0) {
// Started-empty entries are foreign data we never touched --
// preserve them (only a gstack-tagged empty entry is claimable,
// and only by the --all sweep).
if (all && entry._gstack_source && !sweepExclude[entry._gstack_source]) { removed++; continue; }
rebuilt.push(entry);
continue;
}
for (const h of entry.hooks) {
const cmdRaw = h && h.command;
const row = cmdRaw ? gsOwnedRow(cmdRaw, event, matcher) : null;
// A tagged SINGLE-item entry with no table match is an owned
// legacy stray (command items only -- gstack never writes
// command-less items); tags never claim items in multi-item entries.
const stray = !row && !!cmdRaw && !!entry._gstack_source && wasSingle;
if (!row && !stray) { remain.push(h); continue; } // foreign: never touched
if (all) {
if ((row && sweepExclude[row.source]) || (!row && entry._gstack_source && sweepExclude[entry._gstack_source])) { remain.push(h); continue; }
removed++; continue;
}
if (row && root && !(ptOptout && PT_SOURCES[row.source])) {
const target = root + "/" + row.relpath;
if (gsIsAlive(target)) {
const newCmd = gsQuoteCmd(target, gsHadBashPrefix(cmdRaw));
if (h.command !== newCmd) { h.command = newCmd; repointed++; }
// Within-entry twin collapse: two dead copies of the same
// hook re-point to the same canonical command -- keeping
// both would fire the hook twice per event, forever.
if (seenInEntry.has(newCmd)) { removed++; continue; }
seenInEntry.add(newCmd);
if (wasSingle) gsTag(entry, row.source); // tag restore
remain.push(h);
continue;
}
}
// No re-point target (or plan-tune opt-out): keep live, prune dead.
if (gsIsAlive(cmdRaw)) remain.push(h); else { removed++; }
}
if (remain.length === 0) { if (GS_CODEX) rebuilt.push(gsCodexSlot()); continue; } // entry emptied → dropped (Codex: a slot)
entry.hooks = remain;
// Tag hygiene: a tag must never sit on an entry containing foreign
// items (old gstack versions in sibling worktrees treat tags as
// entry-level ownership and would destroy the user items). Drop
// the tag from any mixed entry; single-item strays keep theirs.
if (entry._gstack_source && entry.hooks.length > 0
&& !entry.hooks.every(h => h && h.command && gsOwnedRow(h.command, event, matcher))
&& !(entry.hooks.length === 1 && wasSingle)) {
delete entry._gstack_source;
}
rebuilt.push(entry);
}
// Collapse exact duplicates among FULLY-owned entries (same matcher,
// same item commands). Prefer the tagged twin so stripped tags heal.
const seen = new Map();
const out = [];
for (const entry of rebuilt) {
const items = Array.isArray(entry.hooks) ? entry.hooks : [];
const fullyOwned = items.length > 0 && items.every(h =>
h && h.command && gsOwnedRow(h.command, event, entry.matcher || ""));
if (!fullyOwned) { out.push(entry); continue; }
const key = JSON.stringify([entry.matcher || ""].concat(items.map(function (h) { return h.command; }).sort()));
const at = seen.get(key);
if (at === undefined) { seen.set(key, out.length); out.push(entry); }
else {
if (!out[at]._gstack_source && entry._gstack_source) out[at] = entry;
if (GS_CODEX) out.push(gsCodexSlot());
removed++;
}
}
settings.hooks[event] = GS_CODEX ? gsCodexTrimSlots(out) : out;
if (out.length === 0) delete settings.hooks[event];
}
if (settings.hooks && Object.keys(settings.hooks).length === 0) delete settings.hooks;
}
gsWriteIfChanged(settingsPath, before, settings, loaded.existed);
console.log("OK: removed " + removed + " gstack hook entries (repointed " + repointed + ")");
});
'
;;
rollback)
_acquire_lock || exit 1
if [ ! -f "$SETTINGS_FILE.bak-latest" ]; then
echo "rollback: no backup pointer at $SETTINGS_FILE.bak-latest" >&2
exit 1
fi
LATEST=$(cat "$SETTINGS_FILE.bak-latest")
LATEST=$(printf '%s' "$LATEST" | tr -d '\n')
# Defense in depth: only ever restore a sibling settings.json.bak.* file
# (a corrupted/hostile pointer must not install an arbitrary file as the
# live settings.json).
case "$LATEST" in
"$SETTINGS_FILE".bak.*) ;;
*)
echo "rollback: pointer target $LATEST is not a $SETTINGS_FILE.bak.* file -- refusing" >&2
exit 1
;;
esac
case "${LATEST#"$SETTINGS_FILE".bak.}" in
*/*)
echo "rollback: pointer suffix contains a path separator -- refusing" >&2
exit 1
;;
esac
if [ ! -f "$LATEST" ]; then
echo "rollback: pointer references missing backup $LATEST" >&2
exit 1
fi
_mutation_env
GSTACK_SETTINGS_PATH="$SETTINGS_FILE" GSTACK_RESTORE_PATH="$LATEST" \
bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
var fs = require("fs");
var target = process.env.GSTACK_SETTINGS_PATH;
var backup = process.env.GSTACK_RESTORE_PATH;
var tmp = process.env.GSTACK_TMP_PATH;
gsAssertSettingsTarget(target);
gsLoadedIdentity = gsSettingsIdentity(target);
if (GS_CODEX) {
// Restoring a backup Codex would skip switches off every hook in the
// file, the user ones too, so the backup passes the same schema check
// as any write before it replaces the live file.
var problem;
try { problem = gsCodexProblem(JSON.parse(fs.readFileSync(backup, "utf8"))); }
catch (e) { problem = "it is not valid JSON (" + e.message + ")"; }
if (problem) {
throw Object.assign(new Error("left " + target + " unchanged: the backup " + backup + " does not match the Codex hooks.json schema (" + problem + "), and Codex would skip that whole file"), { gstackUnreadableSettings: true });
}
}
try {
fs.copyFileSync(backup, tmp, fs.constants.COPYFILE_EXCL);
gsAssertSettingsUnchanged(target);
fs.renameSync(tmp, target);
} finally {
try { fs.unlinkSync(tmp); } catch (e) { if (e.code !== "ENOENT") throw e; }
}
});'
echo "OK: restored $SETTINGS_FILE from $LATEST"
;;
list-items)
# Read-only identity view: one JSON string literal per matching hook
# command (JSON.stringify, so a command containing tabs or newlines
# cannot split a line), filters applied inside the JS. Empty stdout
# means no match. Exit 1 usage, 3 unparseable settings, 4 unexpected
# shape -- the same codes the mutating verbs use, because callers
# (bin/gstack-memorable) decide mutations from this output.
LI_EVENT=""
LI_OWNED_BY=""
LI_CMD_RE=""
shift
while [ $# -gt 0 ]; do
case "$1" in
--event) LI_EVENT="$2"; shift 2 ;;
--owned-by) LI_OWNED_BY="$2"; shift 2 ;;
--command-regex) LI_CMD_RE="$2"; shift 2 ;;
*) echo "unknown flag: $1" >&2; exit 1 ;;
esac
done
if [ -z "$LI_EVENT" ]; then
echo "list-items requires --event <name>" >&2
exit 1
fi
[ -f "$SETTINGS_FILE" ] || exit 0
GSTACK_SETTINGS_PATH="$SETTINGS_FILE" GSTACK_LI_EVENT="$LI_EVENT" GSTACK_LI_OWNED_BY="$LI_OWNED_BY" GSTACK_LI_CMD_RE="$LI_CMD_RE" bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
const event = process.env.GSTACK_LI_EVENT;
const ownedBy = process.env.GSTACK_LI_OWNED_BY || "";
const reSrc = process.env.GSTACK_LI_CMD_RE || "";
let re = null;
if (reSrc) {
try { re = new RegExp(reSrc); }
catch (e) {
process.stderr.write("list-items: invalid --command-regex (" + e.message + ")\n");
process.exit(1);
}
}
const loaded = gsLoadSettings(process.env.GSTACK_SETTINGS_PATH);
const hooks = loaded.settings.hooks || {};
const entries = hooks[event];
if (entries === undefined || entries === null) process.exit(0);
if (!Array.isArray(entries)) throw new Error("hooks." + event + " is not an array");
for (const entry of entries) {
if (!entry || !Array.isArray(entry.hooks)) continue; // foreign shape, preserved by prune-stale too
for (const h of entry.hooks) {
const cmd = (h && typeof h.command === "string") ? h.command : "";
if (!cmd) continue;
const row = gsOwnedRow(cmd, event, entry.matcher || "");
if (ownedBy && (!row || row.source !== ownedBy)) continue;
// Alone, the regex only ever sees items no table row owns (the
// vendor-own probe). Combined with --owned-by it narrows THAT set:
// filters intersect, a regex never widens a selection.
if (re && !ownedBy && row) continue;
if (re && !re.test(cmd)) continue;
console.log(JSON.stringify(cmd));
}
}
});
'
;;
trust-status)
# Read-only, Codex only: one line per gstack handler in hooks.json,
# "<source>\t<event>\t<state>", where state is trusted (config.toml holds a
# trusted_hash under [hooks.state."<hooks.json path>:<event>:<group>:<handler>"],
# the key Codex 0.170 builds in codex-rs/hooks/src/lib.rs hook_key, from the
# canonical CODEX_HOME when that is set, else $HOME/.codex as written),
# untrusted (no entry yet: Codex skips the hook until the user trusts it) or
# disabled (enabled = false). It never computes a hash, so a trusted line
# means an entry exists, not that it matches the current definition.
if [ "${GSTACK_HOOKS_FORMAT:-}" != codex ]; then
echo "trust-status needs GSTACK_HOOKS_FORMAT=codex" >&2
exit 1
fi
[ -f "$SETTINGS_FILE" ] || exit 0
GSTACK_SETTINGS_PATH="$SETTINGS_FILE" GSTACK_CODEX_HOOKS_INPUT="$GSTACK_SETTINGS_INPUT" \
bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
const fs = require("fs");
const path = require("path");
const loaded = gsLoadSettings(process.env.GSTACK_SETTINGS_PATH);
let state = {};
try {
const cfg = Bun.TOML.parse(fs.readFileSync(process.env.GSTACK_CODEX_CONFIG, "utf8"));
state = (cfg && cfg.hooks && cfg.hooks.state) || {};
} catch (e) {
if (!e || e.code !== "ENOENT") throw Object.assign(new Error(process.env.GSTACK_CODEX_CONFIG + " does not parse (" + (e && e.message) + ")"), { gstackUnreadableSettings: true });
}
const label = (ev) => ev.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
// Codex 0.170 keys trust by the hooks.json path inside its home, never by
// where a symlinked hooks.json points: a CODEX_HOME that is set is
// canonicalized (utils/home-dir find_codex_home), the default
// $HOME/.codex is used as written.
const input = path.resolve(process.env.GSTACK_CODEX_HOOKS_INPUT);
const keyFile = process.env.CODEX_HOME ? path.join(fs.realpathSync(path.dirname(input)), path.basename(input)) : input;
const hooks = loaded.settings.hooks || {};
for (const ev of Object.keys(hooks)) {
hooks[ev].forEach((g, gi) => (g.hooks || []).forEach((h, hi) => {
const row = h && h.type === "command" ? gsOwnedRow(h.command, ev, g.matcher || "") : null;
if (!row) return;
const entry = state[keyFile + ":" + label(ev) + ":" + gi + ":" + hi];
const st = entry && entry.enabled === false ? "disabled" : entry && typeof entry.trusted_hash === "string" ? "trusted" : "untrusted";
console.log(row.source + "\t" + ev + "\t" + st);
}));
}
});
'
;;
list-sources)
[ -f "$SETTINGS_FILE" ] || { echo "(no settings file)"; exit 0; }
GSTACK_SETTINGS_PATH="$SETTINGS_FILE" bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e "$_HOOK_JS_PRELUDE"'gsMain(function () {
const fs = require("fs");
let settings = {};
try { settings = JSON.parse(fs.readFileSync(process.env.GSTACK_SETTINGS_PATH, "utf8")); }
catch (e) {
// Read-only surface: report loudly (setup guards read this output and
// must not mistake corrupt-file for no-hooks) but exit 0.
process.stderr.write("gstack-settings-hook: settings.json unparseable (" + e.message + ") -- fix or rollback\n");
process.exit(0);
}
const hooks = settings.hooks || {};
let any = false;
for (const event of Object.keys(hooks)) {
for (const entry of hooks[event]) {
if (entry._gstack_source) {
any = true;
console.log(event + "\t" + entry._gstack_source + "\t" + (entry.matcher || "(no matcher)"));
}
}
}
if (!any) console.log("(no gstack-tagged hooks)");
});
'
;;
*)
echo "Unknown action: $ACTION" >&2
exit 1
;;
esac