@hasna/hooks 0.3.10 → 0.3.11

package/bin/index.js

@@ -861,7 +861,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          } else {}
+          }
         };
       }
       return this;

package/hooks/hook-fleet-blockers-gate/README.md

@@ -1,6 +1,8 @@
 # hook-fleet-blockers-gate
 
-A PreToolUse hook that stops an agent from working through a fleet freeze. While an unread `[FREEZE]` blocking message is active, mutating tools are denied with a clear reason; read-only tools stay allowed so the agent can read the freeze and react. Part of the Hasna fleet comms workflow (every-turn insurance).
+A PreToolUse hook that stops an agent from working through a real fleet stop. While an unread **`blocking=1` blocker** is active, mutating tools are denied with a clear reason; read-only tools stay allowed so the agent can read the blocker and react. Part of the Hasna fleet comms workflow (every-turn insurance).
+
+To halt the fleet, the owner creates a `blocking=1` blocker (tag it `[FREEZE]` by convention); to lift it, the owner resolves/removes that blocker. Freeze **text** posted to channels is informational and never stops work.
 
 ## Installation
 
@@ -12,22 +14,32 @@ hooks install fleet-blockers-gate
 
 On each `PreToolUse` event:
 
-1. **Read-only tools pass immediately** — `Read`, `Glob`, `Grep`, `WebFetch`, MCP `get_*`/`list_*`/`search_*`-style operations, etc. A frozen agent must stay able to orient itself.
-2. **Freeze state is TTL-cached** (`~/.hasna/hooks/state/fleet-blockers-gate.json`, default 60s) so the common path never spawns a process per tool call.
-3. On cache expiry it runs `conversations blockers -j` with a hard 500ms timeout and scans unread blocking messages for the `[FREEZE]` severity tag.
-4. If frozen, mutating tools are denied via `permissionDecision: "deny"` with the freeze reason; the agent is told to read the blocker and wait for `[UNFREEZE]`.
+1. **Read-only tools pass immediately** — `Read`, `Glob`, `Grep`, `WebFetch`, MCP `get_*`/`list_*`/`search_*`-style operations, etc. A frozen agent must stay able to orient itself. **Exception:** `conversations` `read_*` tools (`read_messages`, `read_channel`, `read_digest`, `read_thread`, …) are **gated** during a freeze, because they mark messages read by default and would clear the blocker's unread state — self-lifting the stop just by browsing. A frozen agent inspects the blocker with the read-only `mcp__conversations__get_blockers` (and `get_message`/`search_messages`/`list_*`/`get_thread_replies`), none of which mark messages read.
+2. **Freeze state is TTL-cached** (`~/.hasna/hooks/state/fleet-blockers-gate.json`) so the common path never spawns a process per tool call. The TTL is asymmetric — a freeze is held for the full TTL (default 60s) but a "clear" is re-checked quickly (default 5s), so a freshly-issued freeze engages fast while a lift disengages slowly (the safe direction).
+3. On cache miss it runs `conversations blockers -j` once (default 1500ms timeout) and denies if the result contains **any** `blocking=1` blocker. `conversations blockers` (`getUnreadBlockers`) returns every unread, in-scope blocker with no limit window, so the check is order-independent and cannot be truncated.
+4. If frozen, mutating tools are denied via `permissionDecision: "deny"` with the blocker's author and text as **advisory** context; the agent is told the blocker must be resolved/removed to lift the stop.
+
+**Freeze text is never scanned.** Denial is driven solely by the `blocking=1` flag — this kills the phantom-freeze bug where any `[FREEZE]` string from any author wedged the fleet, and it stops ignoring real blockers that lacked the `[FREEZE]` text.
+
+**Author is not a security gate.** `conversations` does not authenticate `from_agent`, so the author is shown only as advisory context and is never used to allow or deny (gating on a spoofable field would be false assurance).
+
+**Fail-open by design:** if the `conversations` CLI is missing, the service is down, or the check times out, tools are allowed — the gate must never wedge an agent. An unverified (comms-failure) "clear" is not cached, so the check retries on the next mutating tool.
 
-Fail-open by design: if the `conversations` CLI is missing, the service is down, or the check times out, tools are allowed — the gate must never wedge an agent.
+## Operating notes & limitations
 
-The freeze clears when the blocking message is no longer unread (read + resolved), after which the next cache refresh allows tools again.
+- **Identity and membership are effectively required.** The blockers query is scoped to the agent (`getUnreadBlockers`: `to_agent = me OR channel in my channels`). Set `HOOKS_FLEET_AGENT` to the agent's **real registered identity**, and ensure that identity is a **member of a broadly-subscribed freeze channel**, with the freeze posted using `--blocking`. If the identity is wrong or not subscribed, the blocker is never returned and the brake silently no-ops (fail-open). Wiring this correctly is a deployment responsibility.
+- **Author-agnostic = fail-safe, not tamper-proof.** `conversations` does not authenticate `from_agent`, so the gate does not (and cannot meaningfully) trust the author. Any agent that can set `blocking=1` can therefore cause a stop; recovery is to resolve/remove the blocker or use the kill switch. This is a deliberate fail-safe tradeoff, not an authenticated control.
+- **The deny reason echoes untrusted content.** Up to ~240 characters of the blocker's body are included in the deny message as advisory context. Treat that text as untrusted input (it originates from whoever posted the blocker).
+- **The MCP read-only classification is a prefix heuristic.** Operations whose last `__` segment starts with `get`/`list`/`read`/`search`/… are treated as read-only. A destructively-named op (e.g. a hypothetical `get_and_reset`) could be misclassified as read-only; the `conversations` `read_*` family is explicitly gated as an exception. For high-assurance servers, prefer an explicit per-server allowlist.
 
 ## Configuration
 
 ```bash
-export HOOKS_FLEET_GATE_DISABLE=1     # Kill switch — allow everything
-export HOOKS_FLEET_GATE_TTL_MS=60000  # Cache TTL (default 60000)
-export HOOKS_FLEET_TIMEOUT_MS=500     # Blockers check timeout (default 500)
-export HOOKS_FLEET_AGENT="chief"      # Identity passed as --from
+export HOOKS_FLEET_GATE_DISABLE=1        # Kill switch — allow everything
+export HOOKS_FLEET_GATE_TTL_MS=60000     # Frozen-state cache TTL (default 60000)
+export HOOKS_FLEET_GATE_CLEAR_TTL_MS=5000 # Clear-state cache TTL (default 5000)
+export HOOKS_FLEET_TIMEOUT_MS=1500       # Blockers check timeout (default 1500)
+export HOOKS_FLEET_AGENT="chief"         # Identity passed as --from to scope the query
 ```
 
 ## Requirements

package/hooks/hook-fleet-blockers-gate/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hasna/hook-fleet-blockers-gate",
-  "version": "0.1.0",
-  "description": "Claude Code PreToolUse hook that blocks mutating tools while an unread [FREEZE] blocker is active (TTL-cached, fail-open under 500ms)",
+  "version": "0.1.1",
+  "description": "Claude Code PreToolUse hook that blocks mutating tools while an unread blocking=1 blocker is active (TTL-cached, fail-open)",
   "type": "module",
   "main": "./dist/hook.js",
   "exports": {

package/hooks/hook-fleet-blockers-gate/src/hook.test.ts

@@ -1,5 +1,16 @@
 import { describe, test, expect } from "bun:test";
-import { isReadOnlyTool, detectFreeze, parseBlockersJson } from "./hook";
+import {
+  isReadOnlyTool,
+  isSafeArg,
+  marksReadState,
+  buildDenyReason,
+  detectFreeze,
+  parseBlockersJson,
+  computeFreezeState,
+  decide,
+} from "./hook";
+
+const NOW = new Date("2026-07-20T00:00:00.000Z");
 
 describe("hook-fleet-blockers-gate", () => {
   describe("isReadOnlyTool", () => {
@@ -43,40 +54,156 @@ describe("hook-fleet-blockers-gate", () => {
       expect(isReadOnlyTool("mcp__x__getaway_driver")).toBe(false);
       expect(isReadOnlyTool("mcp__x__listen_events")).toBe(false);
     });
+
+    // self-lift fix: conversations read_* tools mark messages read, which would
+    // clear the blocker's read_at and lift the freeze — so they must be GATED.
+    test("conversations read_* tools are GATED (they mark messages read → self-lift)", () => {
+      expect(isReadOnlyTool("mcp__conversations__read_messages")).toBe(false);
+      expect(isReadOnlyTool("mcp__conversations__read_channel")).toBe(false);
+      expect(isReadOnlyTool("mcp__conversations__read_digest")).toBe(false);
+      expect(isReadOnlyTool("mcp__conversations__read_thread")).toBe(false);
+      expect(isReadOnlyTool("mcp__conversations__read_channel_notifications")).toBe(false);
+    });
+
+    test("safe conversations orientation tools stay ALLOWED during a freeze", () => {
+      expect(isReadOnlyTool("mcp__conversations__get_blockers")).toBe(true);
+      expect(isReadOnlyTool("mcp__conversations__get_message")).toBe(true);
+      expect(isReadOnlyTool("mcp__conversations__search_messages")).toBe(true);
+      expect(isReadOnlyTool("mcp__conversations__list_channels")).toBe(true);
+      expect(isReadOnlyTool("mcp__conversations__get_thread_replies")).toBe(true);
+    });
+
+    test("read_* gating is scoped to conversations (other servers' read_ ops unaffected)", () => {
+      expect(marksReadState("mcp__conversations__read_messages")).toBe(true);
+      expect(marksReadState("mcp__conversations__get_blockers")).toBe(false);
+      expect(marksReadState("mcp__files__read_file")).toBe(false);
+      // a non-conversations read_ op still passes the generic prefix rule
+      expect(isReadOnlyTool("mcp__files__read_file")).toBe(true);
+    });
   });
 
-  describe("detectFreeze", () => {
-    test("finds [FREEZE] in blocker content", () => {
+  describe("buildDenyReason", () => {
+    const msg = buildDenyReason("Active blocking=1 blocker from bot: [FREEZE] cutover");
+
+    test("points at the read-only get_blockers tool", () => {
+      expect(msg).toContain("mcp__conversations__get_blockers");
+    });
+
+    test("warns against the self-lifting read_* tools", () => {
+      expect(msg).toContain("read_messages");
+      expect(msg).toContain("read_channel");
+    });
+
+    test("does not tell the agent to run the gated Bash `conversations blockers` command", () => {
+      // The phrase must not appear as a bare command instruction (it is the MCP tool that is referenced).
+      expect(msg).not.toContain("conversations blockers");
+    });
+
+    test("carries the underlying blocker reason", () => {
+      expect(msg).toContain("Active blocking=1 blocker from bot");
+    });
+  });
+
+  describe("isSafeArg (argument-injection guard)", () => {
+    test("accepts fleet agent names and email-style ids", () => {
+      expect(isSafeArg("lycurgus")).toBe(true);
+      expect(isSafeArg("andrei@hasna.com")).toBe(true);
+      expect(isSafeArg("agent_07.beta-1")).toBe(true);
+    });
+
+    test("rejects leading dash (flag injection), spaces, shell metachars, empty", () => {
+      expect(isSafeArg("--from")).toBe(false);
+      expect(isSafeArg("-j")).toBe(false);
+      expect(isSafeArg("a b")).toBe(false);
+      expect(isSafeArg("a;rm -rf /")).toBe(false);
+      expect(isSafeArg("a`whoami`")).toBe(false);
+      expect(isSafeArg("$(id)")).toBe(false);
+      expect(isSafeArg("")).toBe(false);
+      expect(isSafeArg(undefined)).toBe(false);
+    });
+  });
+
+  describe("detectFreeze — blocking=1 is the only trigger", () => {
+    // blocking=1 -> DENY
+    test("a blocking=1 blocker freezes (author- and text-agnostic)", () => {
       const result = detectFreeze([
-        { from: "chief", content: "[FREEZE] cutover in progress — stop all publishes" },
+        { from_agent: "andrei@hasna.com", content: "[FREEZE] fleet cutover", blocking: true },
       ]);
       expect(result.frozen).toBe(true);
-      expect(result.reason).toContain("chief");
-      expect(result.reason).toContain("[FREEZE]");
+      expect(result.reason).toContain("blocking=1");
+      expect(result.reason).toContain("andrei@hasna.com");
     });
 
-    test("finds [FREEZE] in preview field", () => {
-      const result = detectFreeze([{ from: "chief", preview: "[FREEZE] db migration" }]);
+    test("a blocking=1 blocker with NO freeze text still freezes", () => {
+      const result = detectFreeze([
+        { from_agent: "release-bot", content: "migration running, do not deploy", blocking: true },
+      ]);
       expect(result.frozen).toBe(true);
+      expect(result.reason).toContain("release-bot");
     });
 
-    test("non-freeze blockers do not freeze", () => {
-      const result = detectFreeze([
-        { from: "worker", content: "please review PR #42 when you can" },
-      ]);
-      expect(result.frozen).toBe(false);
+    test("a blocking=1 blocker from any author freezes (author is not a security gate)", () => {
+      expect(detectFreeze([{ from_agent: "some-agent", content: "hold", blocking: true }]).frozen).toBe(true);
+    });
+
+    // freeze TEXT with no blocking=1 -> ALLOW (phantom-freeze bug stays fixed)
+    test("[FREEZE] text without a blocking flag does NOT freeze (phantom-freeze fix)", () => {
+      expect(
+        detectFreeze([{ from_agent: "andrei@hasna.com", content: "[FREEZE] heads up", blocking: false }]).frozen
+      ).toBe(false);
+      expect(
+        detectFreeze([{ from_agent: "some-agent", content: "[FREEZE] cutover", blocking: false }]).frozen
+      ).toBe(false);
+    });
+
+    test("[UNFREEZE]/severity text is ignored entirely (no text scanning)", () => {
+      expect(
+        detectFreeze([{ from_agent: "andrei@hasna.com", content: "[UNFREEZE] all clear", blocking: false }]).frozen
+      ).toBe(false);
     });
 
+    // no blockers -> ALLOW
     test("empty list does not freeze", () => {
       expect(detectFreeze([]).frozen).toBe(false);
     });
 
+    test("non-blocking messages do not freeze", () => {
+      expect(detectFreeze([{ from_agent: "worker", content: "please review PR #42", blocking: false }]).frozen).toBe(false);
+    });
+
     test("garbage entries are ignored", () => {
       expect(detectFreeze([null, 42, "string", {}]).frozen).toBe(false);
     });
 
-    test("lowercase freeze tag does not trigger (exact uppercase per HACP)", () => {
-      expect(detectFreeze([{ content: "[freeze] not a real tag" }]).frozen).toBe(false);
+    test("blocking flag tolerates numeric/string encodings (1, '1', 'true')", () => {
+      expect(detectFreeze([{ from_agent: "x", content: "y", blocking: 1 }]).frozen).toBe(true);
+      expect(detectFreeze([{ from_agent: "x", content: "y", blocking: "1" }]).frozen).toBe(true);
+      expect(detectFreeze([{ from_agent: "x", content: "y", blocking: "true" }]).frozen).toBe(true);
+    });
+
+    test("false-y blocking encodings do not freeze", () => {
+      expect(detectFreeze([{ from_agent: "x", content: "y", blocking: 0 }]).frozen).toBe(false);
+      expect(detectFreeze([{ from_agent: "x", content: "y", blocking: "false" }]).frozen).toBe(false);
+      expect(detectFreeze([{ from_agent: "x", content: "y" }]).frozen).toBe(false);
+    });
+
+    // order-independence: a green suite must not be able to hide a "first item only" bug
+    test("a blocking=1 blocker anywhere in the list freezes (order-independent)", () => {
+      const result = detectFreeze([
+        { from_agent: "a", content: "note 1", blocking: false },
+        { from_agent: "b", content: "note 2", blocking: false },
+        { from_agent: "c", content: "note 3", blocking: false },
+        { from_agent: "d", content: "the real stop", blocking: true },
+      ]);
+      expect(result.frozen).toBe(true);
+      expect(result.reason).toContain("the real stop");
+    });
+
+    test("reads the real from_agent schema field for the advisory reason", () => {
+      const result = detectFreeze([
+        { from_agent: "coordinator", to_agent: "worker", channel: "announcements", content: "stop", blocking: true },
+      ]);
+      expect(result.reason).toContain("coordinator");
     });
   });
 
@@ -103,4 +230,73 @@ describe("hook-fleet-blockers-gate", () => {
     });
   });
 
+  describe("computeFreezeState — fail-open + verified", () => {
+    // comms error -> ALLOW (fail-open, unverified)
+    test("runner error → fail-open (not frozen, unverified)", () => {
+      const e = computeFreezeState(NOW, () => {
+        throw new Error("conversations CLI missing / timeout");
+      });
+      expect(e.state.frozen).toBe(false);
+      expect(e.verified).toBe(false);
+    });
+
+    // no blockers -> ALLOW (verified)
+    test("empty blockers → not frozen, verified", () => {
+      const e = computeFreezeState(NOW, () => "[]");
+      expect(e.state.frozen).toBe(false);
+      expect(e.verified).toBe(true);
+    });
+
+    // blocking=1 -> DENY
+    test("blocking=1 in CLI output → frozen, verified", () => {
+      const raw = JSON.stringify([{ from_agent: "bot", content: "deploy freeze", blocking: true }]);
+      const e = computeFreezeState(NOW, () => raw);
+      expect(e.state.frozen).toBe(true);
+      expect(e.verified).toBe(true);
+    });
+
+    test("parses the real wrapped shape and stays order-independent", () => {
+      const raw = JSON.stringify({
+        blockers: [
+          { from_agent: "a", content: "x", blocking: false },
+          { from_agent: "b", content: "stop now", blocking: true },
+        ],
+      });
+      const e = computeFreezeState(NOW, () => raw);
+      expect(e.state.frozen).toBe(true);
+    });
+
+    test("malformed CLI output → fail-open (not frozen) but verified", () => {
+      const e = computeFreezeState(NOW, () => "not-json-at-all");
+      expect(e.state.frozen).toBe(false);
+      expect(e.verified).toBe(true);
+    });
+  });
+
+  describe("decide — permission gate", () => {
+    const frozen = { frozen: true, reason: "Active blocking=1 blocker from bot: x" };
+    const clear = { frozen: false, reason: "" };
+
+    // HOOKS_FLEET_GATE_DISABLE=1 -> ALLOW
+    test("kill switch (disabled) → allow even under a freeze", () => {
+      expect(decide({ disabled: true, toolName: "Bash", freeze: frozen }).allow).toBe(true);
+    });
+
+    // read-only tool under a blocker -> ALLOW
+    test("read-only tool under an active freeze → allow", () => {
+      expect(decide({ disabled: false, toolName: "Read", freeze: frozen }).allow).toBe(true);
+      expect(decide({ disabled: false, toolName: "mcp__conversations__get_blockers", freeze: frozen }).allow).toBe(true);
+    });
+
+    // blocking=1 + mutating -> DENY
+    test("mutating tool under an active freeze → deny (with reason)", () => {
+      const d = decide({ disabled: false, toolName: "Bash", freeze: frozen });
+      expect(d.allow).toBe(false);
+      expect(d.reason).toContain("blocking=1");
+    });
+
+    test("mutating tool with no freeze → allow", () => {
+      expect(decide({ disabled: false, toolName: "Bash", freeze: clear }).allow).toBe(true);
+    });
+  });
 });

package/hooks/hook-fleet-blockers-gate/src/hook.ts

@@ -3,27 +3,54 @@
 /**
  * Claude Code Hook: fleet-blockers-gate
  *
- * PreToolUse hook — every-turn insurance against working through a fleet
- * freeze. While an unread [FREEZE] blocking message is active, mutating
- * tools are denied with a reason; read-only tools stay allowed so the agent
- * can read the freeze and react.
+ * PreToolUse hook — every-turn insurance against working through a real fleet
+ * stop. The brake has ONE tamper-resistant, correctly-retrieved signal:
+ *
+ *   A code-flagged blocker (blocking=1) returned by `conversations blockers`
+ *   denies mutating tools. That CLI runs `getUnreadBlockers`, which selects
+ *   `WHERE blocking = 1 AND read_at IS NULL AND (to_agent = me OR channel in my
+ *   channels)` with NO limit window — so every unread, in-scope blocker is
+ *   returned and evaluated (no oldest-first truncation to hide behind).
+ *
+ * To halt the fleet, the owner creates a blocking=1 blocker (tagged [FREEZE] by
+ * convention). The stop lifts when that blocker leaves the UNREAD set — i.e. it
+ * is MARKED READ or REMOVED (`getUnreadBlockers` filters `read_at IS NULL`).
+ * Because reading messages can mark them read, `conversations` read_* tools are
+ * gated during a freeze (see isReadOnlyTool) so an agent cannot SELF-LIFT the
+ * stop just by browsing its inbox/channel. Freeze TEXT posted to channels is
+ * informational and NEVER stops work — that kills the phantom-freeze bug where
+ * any "[FREEZE]" string from anyone wedged the fleet.
+ *
+ * IMPORTANT (why this is not author-gated): conversations does not authenticate
+ * `from_agent`; any agent can post as any name. Gating the brake on the author
+ * field would be false assurance (a spoofed [UNFREEZE]/owner post could lift or
+ * forge a stop). So the trigger is the blocking=1 flag alone, author-agnostic.
+ * The blocker's author is shown in the deny reason as ADVISORY context only.
+ *
+ * When frozen, mutating tools are denied with a reason; read-only tools stay
+ * allowed so the agent can read the blocker and react.
  *
  * Design constraints (fleet comms strategy §3):
- * - deterministic local CLI call (`conversations blockers -j`)
- * - hard 500ms fail-open timeout on the check
- * - TTL cache so the common path never spawns a process per tool call
+ * - deterministic local CLI call (`conversations blockers -j`), single spawn
+ * - hard fail-open timeout (default 1500ms; the `conversations` CLI has a ~0.5s
+ *   cold start, so a tighter budget flakes and the brake silently fails open)
+ * - fail-open on error: if the comms layer is unreachable, allow (never wedge)
+ * - TTL cache so the common path never spawns a process per tool call;
+ *   asymmetric TTL means a freeze ENGAGES fast and DISENGAGES slowly (safe)
  *
  * Environment:
- * - HOOKS_FLEET_GATE_DISABLE=1   → allow everything (kill switch)
- * - HOOKS_FLEET_GATE_TTL_MS=<n>  → cache TTL (default 60000)
- * - HOOKS_FLEET_TIMEOUT_MS=<n>   → blockers check exec timeout (default 500)
- * - HOOKS_FLEET_AGENT=<name>     → identity passed as --from
+ * - HOOKS_FLEET_GATE_DISABLE=1        → allow everything (kill switch)
+ * - HOOKS_FLEET_GATE_TTL_MS=<n>       → frozen-state cache TTL (default 60000)
+ * - HOOKS_FLEET_GATE_CLEAR_TTL_MS=<n> → clear-state cache TTL (default 5000)
+ * - HOOKS_FLEET_TIMEOUT_MS=<n>        → CLI exec timeout (default 1500)
+ * - HOOKS_FLEET_AGENT=<name>          → identity passed as --from to scope
+ *                                       the blockers query to this agent
  */
 
 import { readFileSync, existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
-import { execSync } from "child_process";
+import { execFileSync } from "child_process";
 
 interface HookInput {
   session_id: string;
@@ -48,8 +75,28 @@ export interface FreezeState {
   reason: string;
 }
 
+export interface FreezeDetection {
+  frozen: boolean;
+  reason: string;
+}
+
+export interface FreezeEvaluation {
+  state: FreezeState;
+  /** True when the blockers CLI produced a reading (vs. a comms failure). */
+  verified: boolean;
+}
+
+export interface HookDecision {
+  allow: boolean;
+  reason: string;
+}
+
 const DEFAULT_TTL_MS = 60_000;
-const DEFAULT_TIMEOUT_MS = 500;
+const DEFAULT_CLEAR_TTL_MS = 5_000;
+// The `conversations` CLI has a ~0.5s cold start, so a 500ms budget flakes and
+// the brake fails open in practice. Give headroom; the TTL cache keeps this
+// single spawn off the per-tool hot path.
+const DEFAULT_TIMEOUT_MS = 1_500;
 const STATE_DIR = join(homedir(), ".hasna", "hooks", "state");
 const CACHE_FILE = join(STATE_DIR, "fleet-blockers-gate.json");
 
@@ -96,19 +143,51 @@ function respond(output: HookOutput): void {
   console.log(JSON.stringify(output));
 }
 
+function positiveIntEnv(name: string, fallback: number): number {
+  const raw = Number(process.env[name]);
+  return Number.isFinite(raw) && raw > 0 ? raw : fallback;
+}
+
 function ttlMs(): number {
-  const raw = Number(process.env.HOOKS_FLEET_GATE_TTL_MS);
-  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TTL_MS;
+  return positiveIntEnv("HOOKS_FLEET_GATE_TTL_MS", DEFAULT_TTL_MS);
+}
+
+function clearTtlMs(): number {
+  return positiveIntEnv("HOOKS_FLEET_GATE_CLEAR_TTL_MS", DEFAULT_CLEAR_TTL_MS);
 }
 
 function timeoutMs(): number {
-  const raw = Number(process.env.HOOKS_FLEET_TIMEOUT_MS);
-  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TIMEOUT_MS;
+  return positiveIntEnv("HOOKS_FLEET_TIMEOUT_MS", DEFAULT_TIMEOUT_MS);
+}
+
+/**
+ * Reject values that could be argument-injected (leading dash) or contain
+ * shell/space/control characters. Even though we use execFileSync (no shell),
+ * a leading-dash value would be parsed as a flag by the CLI, so we forbid it.
+ */
+export function isSafeArg(value: string | undefined): value is string {
+  return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._@+-]{0,127}$/.test(value);
+}
+
+/**
+ * `conversations` "read_*" ops (read_messages, read_channel, read_digest,
+ * read_thread, read_channel_notifications, ...) mark messages read by default or
+ * on request. Because the freeze signal is an UNREAD blocking=1 blocker, letting
+ * a frozen agent call one of these would clear the blocker's `read_at` and
+ * SELF-LIFT the stop just by browsing. They are therefore gated during a freeze
+ * despite matching a read-only prefix. A frozen agent still orients via
+ * `get_blockers` / `get_message` / `search_messages` / `list_*` /
+ * `get_thread_replies` — none of which mark messages read.
+ */
+export function marksReadState(toolName: string): boolean {
+  return toolName.startsWith("mcp__conversations__read");
 }
 
 /** True when the tool cannot mutate anything and must stay usable during a freeze. */
 export function isReadOnlyTool(toolName: string | undefined): boolean {
   if (!toolName) return false;
+  // Gate conversations read_* even though it looks read-only — it consumes unread state.
+  if (marksReadState(toolName)) return false;
   if (READ_ONLY_TOOLS.has(toolName)) return true;
 
   if (toolName.startsWith("mcp__")) {
@@ -121,19 +200,44 @@ export function isReadOnlyTool(toolName: string | undefined): boolean {
   return false;
 }
 
-/** Detect an active [FREEZE] in the unread blocking messages list. */
-export function detectFreeze(blockers: unknown[]): { frozen: boolean; reason: string } {
+/** The author of a blocker (schema is `from_agent`; tolerate legacy shapes). Advisory only. */
+function authorOf(m: Record<string, unknown>): string {
+  for (const key of ["from_agent", "from", "author", "sender"]) {
+    const v = m[key];
+    if (typeof v === "string" && v.trim()) return v.trim();
+  }
+  return "unknown";
+}
+
+/** The scannable text body of a blocker (used only to describe the deny reason). */
+function bodyOf(m: Record<string, unknown>): string {
+  return [m.content, m.preview, m.message, m.title, m.body]
+    .filter((v): v is string => typeof v === "string")
+    .join(" ");
+}
+
+/** True when the blocker carries the code-flagged blocking bit (boolean, 1, or "1"/"true"). */
+function isBlockingFlagged(m: Record<string, unknown>): boolean {
+  const v = m.blocking;
+  return v === true || v === 1 || v === "1" || v === "true";
+}
+
+/**
+ * Decide whether the blockers list constitutes a freeze. The ONLY trigger is a
+ * code-flagged blocker (blocking=1); freeze TEXT is ignored entirely. Scans the
+ * whole list (order-independent) so a blocker anywhere in the result freezes.
+ * The author is included in the reason as advisory context, NOT as a gate.
+ */
+export function detectFreeze(blockers: unknown[]): FreezeDetection {
   for (const item of blockers) {
     if (!item || typeof item !== "object") continue;
     const m = item as Record<string, unknown>;
-    const body = [m.content, m.preview, m.message, m.title]
-      .filter((v): v is string => typeof v === "string")
-      .join(" ");
-    if (/\[FREEZE\]/.test(body)) {
-      const from = typeof m.from === "string" ? m.from : "unknown";
+    if (isBlockingFlagged(m)) {
+      const author = authorOf(m);
+      const body = bodyOf(m);
       return {
         frozen: true,
-        reason: `Unread [FREEZE] blocking message from ${from}: ${body.slice(0, 240)}`,
+        reason: `Active blocking=1 blocker from ${author}: ${body.slice(0, 240)}`,
       };
     }
   }
@@ -161,7 +265,10 @@ function readCache(now: Date): FreezeState | null {
     const state = JSON.parse(readFileSync(CACHE_FILE, "utf-8")) as FreezeState;
     const checkedAt = new Date(state.checked_at).getTime();
     if (Number.isNaN(checkedAt)) return null;
-    if (now.getTime() - checkedAt > ttlMs()) return null;
+    // Asymmetric TTL: hold a freeze for the full TTL, but re-check a "clear"
+    // quickly so a freshly-issued freeze engages fast (the safe direction).
+    const maxAge = state.frozen ? ttlMs() : clearTtlMs();
+    if (now.getTime() - checkedAt > maxAge) return null;
     return state;
   } catch {
     return null;
@@ -177,31 +284,87 @@ function writeCache(state: FreezeState): void {
   }
 }
 
+/** Run `conversations blockers -j` and return raw stdout, or throw on failure. */
+function defaultBlockersRunner(): string {
+  const agent = process.env.HOOKS_FLEET_AGENT;
+  const args = ["blockers", "-j"];
+  if (isSafeArg(agent)) args.push("--from", agent);
+  return execFileSync("conversations", args, {
+    encoding: "utf-8",
+    timeout: timeoutMs(),
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+}
+
+/**
+ * Evaluate freeze state from the blockers source. Injectable runner makes this
+ * pure and testable. Fail-open: a runner error (CLI missing / timeout / service
+ * down) yields not-frozen with `verified=false`, so the caller can avoid caching
+ * an unverified "clear" and retry on the next mutating tool.
+ */
+export function computeFreezeState(
+  now: Date,
+  runner: () => string = defaultBlockersRunner
+): FreezeEvaluation {
+  try {
+    const raw = runner();
+    const r = detectFreeze(parseBlockersJson(raw.trim()));
+    return { state: { checked_at: now.toISOString(), frozen: r.frozen, reason: r.reason }, verified: true };
+  } catch {
+    return { state: { checked_at: now.toISOString(), frozen: false, reason: "" }, verified: false };
+  }
+}
+
 function checkFreeze(now: Date): FreezeState {
   const cached = readCache(now);
   if (cached) return cached;
 
-  try {
-    const agent = process.env.HOOKS_FLEET_AGENT;
-    const from = agent && /^[A-Za-z0-9._-]{1,64}$/.test(agent) ? ` --from ${agent}` : "";
-    const raw = execSync(`conversations blockers -j${from}`, {
-      encoding: "utf-8",
-      timeout: timeoutMs(),
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-    const result = detectFreeze(parseBlockersJson(raw.trim()));
-    const state: FreezeState = { checked_at: now.toISOString(), frozen: result.frozen, reason: result.reason };
-    writeCache(state);
-    return state;
-  } catch {
-    // CLI missing / timeout / service down → fail open (never wedge the agent)
-    // Do not cache an unverified "not frozen" state; retry on the next mutating tool.
-    return { checked_at: now.toISOString(), frozen: false, reason: "" };
+  const evaluation = computeFreezeState(now);
+
+  // Cache a freeze for the full TTL, and a verified clear for the short TTL.
+  // Never cache an unverified (comms-failure) clear — retry on the next tool.
+  if (evaluation.state.frozen || evaluation.verified) {
+    writeCache(evaluation.state);
   }
+  return evaluation.state;
+}
+
+/**
+ * Build the deny reason. Points the agent at the read-only, non-mark-read
+ * `mcp__conversations__get_blockers` tool — NOT the Bash `conversations blockers`
+ * command (Bash is gated) and NOT any read_* tool (those mark the blocker read
+ * and would self-lift the stop). The echoed blocker text is UNTRUSTED input.
+ */
+export function buildDenyReason(reason: string): string {
+  return (
+    `[hook-fleet-blockers-gate] Mutating tools are blocked — an active blocking=1 blocker is in effect. ` +
+    `${reason} ` +
+    `Inspect it with the read-only mcp__conversations__get_blockers tool — do NOT use read_messages / read_channel (they mark it read and would clear the stop). ` +
+    `The stop lifts when the blocker is resolved/removed by whoever owns the freeze; then retry.`
+  );
+}
+
+/**
+ * Pure permission decision. Single source of truth for allow/deny:
+ * - kill switch disabled → allow
+ * - read-only tool → allow (agent must be able to read the blocker)
+ * - freeze active → deny
+ * - otherwise → allow
+ */
+export function decide(params: {
+  disabled: boolean;
+  toolName: string | undefined;
+  freeze: FreezeDetection;
+}): HookDecision {
+  if (params.disabled) return { allow: true, reason: "" };
+  if (isReadOnlyTool(params.toolName)) return { allow: true, reason: "" };
+  if (params.freeze.frozen) return { allow: false, reason: params.freeze.reason };
+  return { allow: true, reason: "" };
 }
 
 export function run(): void {
-  if (process.env.HOOKS_FLEET_GATE_DISABLE === "1") {
+  const disabled = process.env.HOOKS_FLEET_GATE_DISABLE === "1";
+  if (disabled) {
     respond({ continue: true });
     return;
   }
@@ -212,23 +375,21 @@ export function run(): void {
     return;
   }
 
-  // Read-only tools always pass — the agent must stay able to read the freeze.
+  // Read-only tools always pass — and must never trigger the CLI check.
   if (isReadOnlyTool(input.tool_name)) {
     respond({ continue: true });
     return;
   }
 
   const state = checkFreeze(new Date());
+  const decision = decide({ disabled, toolName: input.tool_name, freeze: state });
 
-  if (state.frozen) {
+  if (!decision.allow) {
     respond({
       hookSpecificOutput: {
         hookEventName: "PreToolUse",
         permissionDecision: "deny",
-        permissionDecisionReason:
-          `[hook-fleet-blockers-gate] Fleet freeze active — mutating tools are blocked. ` +
-          `${state.reason} ` +
-          `Read the blocking message (conversations blockers), resolve or wait for [UNFREEZE], then retry.`,
+        permissionDecisionReason: buildDenyReason(decision.reason),
       },
     });
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {