@azure-id/orc 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -10,6 +10,81 @@ Format: `### v<version> — <title> _(<date>)_`.
 
 ---
 
+### v1.6.0 - the rule that can finally say no _(2026-09-07)_
+
+**Still on the unscoped `orc` package?** Do this once first - your `orc upgrade`
+is the pre-v0.56.0 one and cannot install itself. Full detail in the CAUTION at
+the top of this file.
+
+- **Step 1 - release the command from the old package:** `npm uninstall -g orc`
+- **Step 2 - install the current package:** `npm i -g @azure-id/orc`
+- **Step 3 - re-apply it to your project:** `orc update`
+
+**Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
+
+
+ORC's read discipline has always said the same thing in three places: the main
+session reads to **find**, and dispatches an agent to **understand**. It was
+prose in `_shared/read-ladder.md`, in `/orc-doc` hard rule 0, and on line 21 of
+`/orc-quick` - and **nothing checked any of it**.
+
+`orc-read-gate.js` is a `PreToolUse` hook on `Read` that can refuse. It ships
+**off**, and `off` is byte-identical to not having it - asserted by a test, not
+by intention.
+
+**The threshold is ORC's own number, measured.** The pattern this came from uses
+350 lines, derived from a 10-30 second delegation round trip. ORC's round trip
+is nothing like that: a dispatch measured **p50 76s, p90 188s** (n=125), and one
+real read-only dispatch cost **13,276 tokens** to read a four-line file. At the
+measured 55.2 chars/line across 316 sampled reads, break-even is **~1000 lines**.
+Copying 350 would delegate work whose overhead exceeds its saving.
+
+**`agent_id` is the only discriminator, and that was MEASURED, not assumed.**
+`PreToolUse` **does** fire inside a dispatched subagent - the assumption that
+hooks are session-level was wrong. `session_id` and `transcript_path` are
+**identical** in both contexts, so a gate written against either would block the
+full read an executor must perform before an `Edit`, and a reconstructed
+`old_string` corrupts files. The gate tests for the **presence** of `agent_id`,
+never for the absence of some other key, which asserts nothing.
+
+**Everything it stays silent on, and each one is deliberate:** any read by a
+subagent - outside an open ORC run - a targeted `offset`/`limit` read - a file
+under the threshold - build logs, test results and `.jsonl` that a gate parses
+whole, because a truncated red build reads **green** - and any error at all,
+because **a read gate that throws and blocks a read has broken the tool.**
+
+**A block always names the cheaper path.** A gate that only refuses is a gate
+people switch off. It names the targeted read, the agent dispatch, and the
+config key that turns it down.
+
+**Every `warn` and `block` writes one trace line** (`READ-GATE`), an allow
+writes none. That is affordable here for a structural reason: the gate only acts
+while a run is open, so a trace always exists. `orc doctor` gains
+`read-gate-unwired` and `read-gate-fallback`, both reported **only while the
+feature is armed** - a doctor that warns about the default is one people learn
+to ignore.
+
+**Two config keys**, both on the `SEED_EMPTY` allowlist with an empty `lanes[]`,
+because a hook has no lane and cannot resolve config: `read_gate`
+(`off`|`warn`|`block`, default `off`) and `read_gate_max_lines` (default 1000).
+
+**What this release deliberately does NOT do**, with the reasons recorded so
+nobody re-proposes them: no gate on `Bash` reads (`cat`/`head`/`tail`) - it is
+several times the false-positive surface, and the measurement says the `Read`
+tool is only about 7.5% of the actual read surface here - and no
+`context-reader` slot in `EXTRA_SLOTS`, because at a 1000-line threshold the
+addressable population is five reads across 239 sampled sessions, which is
+infrastructure for nothing.
+
+**An honest note on the measurement.** The audit behind this release found the
+existing prose is largely *working*: median full read is 85 lines, p90 is 288,
+and 46% of reads already use `offset`/`limit` without being told. Oversized
+reads are about **1% of price-weighted main-session ingest** at a generous upper
+bound. This hook is a guardrail on a road most runs already stay on - it is off
+by default for exactly that reason.
+
+---
+
 ### v1.5.0 - the lane that runs the test _(2026-09-07)_
 
 **Still on the unscoped `orc` package?** Do this once first - your `orc upgrade`

package/README.md

@@ -7,14 +7,14 @@
 *Intake → analyze → plan → score → parallel subagents → review → verify → ship.*
 
 ![npm](https://img.shields.io/npm/v/%40azure-id%2Forc?style=for-the-badge&color=cb3837&logo=npm)
-![Version](https://img.shields.io/badge/version-1.4.2-blue.svg?style=for-the-badge)
+![Version](https://img.shields.io/badge/version-1.6.0-blue.svg?style=for-the-badge)
 ![License](https://img.shields.io/badge/license-MIT-green.svg?style=for-the-badge)
 ![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg?style=for-the-badge)
 ![Claude Code](https://img.shields.io/badge/Claude_Code-Skills-purple.svg?style=for-the-badge)
 ![Dependencies](https://img.shields.io/badge/dependencies-zero-lightgrey.svg?style=for-the-badge)
 ![GitHub stars](https://img.shields.io/github/stars/azure-id/orc?style=for-the-badge&color=yellow)
 
-**Latest: v1.5.0** · updated 2026-09-07 · [full changelog](CHANGELOG.md)
+**Latest: v1.6.0** · updated 2026-09-07 · [full changelog](CHANGELOG.md)
 
 **On npm: [`@azure-id/orc`](https://www.npmjs.com/package/@azure-id/orc)** — `npm i -g @azure-id/orc`
 
@@ -576,7 +576,7 @@ a current audit: [EVAL-REPORT.md](EVAL-REPORT.md).
 **Full history: [CHANGELOG.md](CHANGELOG.md)** — or `orc changelog`, which prints
 only what is newer than the version you have.
 
-### v1.5.0 - the lane that runs the test _(2026-09-07)_
+### v1.6.0 - the rule that can finally say no _(2026-09-07)_
 
 **Still on the unscoped `orc` package?** Do this once first - your `orc upgrade`
 is the pre-v0.56.0 one and cannot install itself. Full detail in the CAUTION at
@@ -588,53 +588,66 @@ the top of this file.
 
 **Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
 
-Every other testing surface in ORC **writes** tests. `/orc-test` **runs** them.
 
-It points at a running API - yours, on your laptop, or one you were given
-permission to touch - sends real requests, writes down what came back, and
-stops.
-
-> **The CLI executes and measures. The model designs and interprets.**
-> A model never sends a request. The CLI never decides what a response means.
-
-That split is what makes the report worth reading: a number in it was measured
-by a program, and a sentence in it was written by a model that only ever saw
-evidence on disk.
-
-**The free pass runs first.** `orc test surface` reads your repository and the
-target's own spec document for zero model tokens, and the **code-vs-live diff**
-falls out of it - a route that answers at the target and is in **no file in your
-repository** is surface nobody reviews and nobody patches. With no spec at the
-target it reads **NOT MEASURED, with the reason**, because an empty list there
-would say "no shadow APIs", which is a claim nobody made.
-
-**The security tier is a closed set** - the OWASP API Top 10 (2023), and all ten
-rows render in every state. A category ORC could not measure says `UNCHECKABLE`,
-keeps its slot, and **never becomes a pass**. It detects and never exploits.
-
-**When your app is broken it stops.** It finds the start command, sees the
-process is alive, reads the exact line in the log - and will not open that file.
-
-**A red happy path stops the ladder**, because a 500 on every request will
-"prove" a dozen vulnerabilities that are one bug. A **429 is a result** - it
-means rate limiting works, so ORC backs off rather than pushing through. Every
-credential is replaced **before the bytes reach disk**. A finding that cannot
-point at evidence on disk is **dropped by name**. A flake is **recorded, never
-retried away**.
-
-**`orc ui` ▸ Test** renders all of it and works out none of it - and `orc test
-run` is a command you **copy**, never a button: a page that can start a scan
-against a live host is a page that can start one by accident.
-
-**And one bug that was not in this lane.** Writing the tests isolated a real
-one: `orc ui` compressed its API answers but not its static files, guarded by a
-comment reading *"No asset is over 64 KiB today"* that had been false for two
-releases. Over a Windows loopback socket a 138 KB panel script loses its tail
-roughly one time in six. Both paths share one encoder now.
-
-Full detail in [CHANGELOG.md](CHANGELOG.md).
-
----
+ORC's read discipline has always said the same thing in three places: the main
+session reads to **find**, and dispatches an agent to **understand**. It was
+prose in `_shared/read-ladder.md`, in `/orc-doc` hard rule 0, and on line 21 of
+`/orc-quick` - and **nothing checked any of it**.
+
+`orc-read-gate.js` is a `PreToolUse` hook on `Read` that can refuse. It ships
+**off**, and `off` is byte-identical to not having it - asserted by a test, not
+by intention.
+
+**The threshold is ORC's own number, measured.** The pattern this came from uses
+350 lines, derived from a 10-30 second delegation round trip. ORC's round trip
+is nothing like that: a dispatch measured **p50 76s, p90 188s** (n=125), and one
+real read-only dispatch cost **13,276 tokens** to read a four-line file. At the
+measured 55.2 chars/line across 316 sampled reads, break-even is **~1000 lines**.
+Copying 350 would delegate work whose overhead exceeds its saving.
+
+**`agent_id` is the only discriminator, and that was MEASURED, not assumed.**
+`PreToolUse` **does** fire inside a dispatched subagent - the assumption that
+hooks are session-level was wrong. `session_id` and `transcript_path` are
+**identical** in both contexts, so a gate written against either would block the
+full read an executor must perform before an `Edit`, and a reconstructed
+`old_string` corrupts files. The gate tests for the **presence** of `agent_id`,
+never for the absence of some other key, which asserts nothing.
+
+**Everything it stays silent on, and each one is deliberate:** any read by a
+subagent - outside an open ORC run - a targeted `offset`/`limit` read - a file
+under the threshold - build logs, test results and `.jsonl` that a gate parses
+whole, because a truncated red build reads **green** - and any error at all,
+because **a read gate that throws and blocks a read has broken the tool.**
+
+**A block always names the cheaper path.** A gate that only refuses is a gate
+people switch off. It names the targeted read, the agent dispatch, and the
+config key that turns it down.
+
+**Every `warn` and `block` writes one trace line** (`READ-GATE`), an allow
+writes none. That is affordable here for a structural reason: the gate only acts
+while a run is open, so a trace always exists. `orc doctor` gains
+`read-gate-unwired` and `read-gate-fallback`, both reported **only while the
+feature is armed** - a doctor that warns about the default is one people learn
+to ignore.
+
+**Two config keys**, both on the `SEED_EMPTY` allowlist with an empty `lanes[]`,
+because a hook has no lane and cannot resolve config: `read_gate`
+(`off`|`warn`|`block`, default `off`) and `read_gate_max_lines` (default 1000).
+
+**What this release deliberately does NOT do**, with the reasons recorded so
+nobody re-proposes them: no gate on `Bash` reads (`cat`/`head`/`tail`) - it is
+several times the false-positive surface, and the measurement says the `Read`
+tool is only about 7.5% of the actual read surface here - and no
+`context-reader` slot in `EXTRA_SLOTS`, because at a 1000-line threshold the
+addressable population is five reads across 239 sampled sessions, which is
+infrastructure for nothing.
+
+**An honest note on the measurement.** The audit behind this release found the
+existing prose is largely *working*: median full read is 85 lines, p90 is 288,
+and 46% of reads already use `offset`/`limit` without being told. Oversized
+reads are about **1% of price-weighted main-session ingest** at a generous upper
+bound. This hook is a guardrail on a road most runs already stay on - it is off
+by default for exactly that reason.
 
 ## Requirements
 

package/bin/cli.js

@@ -364,6 +364,31 @@ function installGuards(claudeDir) {
   wireTrace("PreToolUse", "Task|Agent");
   wireTrace("SubagentStop", null);
 
+  // 5) PreToolUse read gate (v1.6.0) — add once, or refresh its path on update.
+  // Wired even though `read_gate` defaults to OFF: the hook's first act is to
+  // read that key and exit 0, so an unarmed gate is byte-identical to not
+  // having it (asserted by a test). Wiring it here means arming the feature is
+  // a config edit, never an install step the user has to discover.
+  const readGateCmd = nodeCmd(path.join(hooksDest, "orc-read-gate.js"));
+  let readGated = false;
+  for (const entry of settings.hooks.PreToolUse) {
+    for (const h of entry.hooks || []) {
+      if (typeof h.command === "string" && h.command.includes("orc-read-gate")) {
+        h.command = readGateCmd; // keep the path current
+        readGated = true;
+      }
+    }
+  }
+  if (!readGated) {
+    settings.hooks.PreToolUse.push({
+      matcher: "Read",
+      hooks: [{ type: "command", command: readGateCmd }],
+    });
+    console.log("  add   settings.json → PreToolUse read gate (off by default)");
+  } else {
+    console.log("  upd   settings.json → PreToolUse read gate path");
+  }
+
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
 }
 
@@ -1234,6 +1259,10 @@ const CONFIG_FAMILIES = {
   // reason, because a config that once said yes is on for the run you needed it
   // off.
   test: { contested: false, question: "how far a live test run goes, and how hard it pushes" },
+  // v1.6.0 — the read gate. UNCONTESTED: no forcing mode reaches it, because
+  // the gate acts on the MAIN session's reads and `opus5_only` / `extra_*`
+  // decide which MODEL runs a dispatched role. Nothing shadows these two.
+  read: { contested: false, question: "whether an oversized full read by the main session is refused" },
 };
 
 // Ordered, tiered metadata. Common first, then advanced.
@@ -1290,6 +1319,8 @@ const CONFIG_META = [
   // it is an operating key of a hook. Off by default, and off means Claude
   // Code's own agent-panel row, unchanged.
   { key: "subagent_line_custom", def: "off", tier: "common", answers: [{ family: "statusline", prio: "P2", mode: "replace" }], lanes: [], validate: vEnum("off", "on"), options: ["off", "on"], desc: "Whether the agent panel renders YOUR composed row for each subagent instead of Claude Code's own. Off is Claude Code's row, unchanged. Compose it in `orc ui` > CLI Hook Interface, on the subagent board. INDEPENDENT of the per-agent token record: ORC writes what the agent panel reports whether this is on or off, because that measurement is handed over either way and throwing it out because a display setting is off would be the wrong trade." },
+  { key: "read_gate", def: "off", tier: "common", answers: [{ family: "read", prio: "P2", mode: "replace" }], lanes: [], validate: vEnum("off", "warn", "block"), options: ["off", "warn", "block"], desc: "Whether the PreToolUse read gate acts on an oversized full read by the MAIN session. Off is byte-identical to not having the hook. `warn` allows and says so; `block` refuses and names the cheaper path. It is SILENT on every read a subagent makes (so an executor's read-before-edit is never touched), outside an open ORC run, on a targeted offset/limit read, on output a gate parses, and under `read_gate_max_lines`." },
+  { key: "read_gate_max_lines", def: 1000, tier: "advanced", answers: [{ family: "read", prio: "P2", mode: "replace" }], lanes: [], validate: vInt(1), options: [500, 1000, 2000], desc: "Line count at or above which `read_gate` acts. The default 1000 is MEASURED, not borrowed: a read-only dispatch costs ~13k tokens and p50 76s, which at 55.2 chars/line across 316 sampled reads puts break-even near 1000 lines. A lower number delegates work whose overhead exceeds its saving." },
   { key: "statusline_custom", def: "off", tier: "common", answers: [{ family: "statusline", prio: "P2", mode: "replace" }], lanes: [], validate: vEnum("off", "on"), options: ["off", "on"], desc: "Whether the status line renders YOUR composed layout instead of the shipped two lines. Off is byte-identical to what ships. Compose the layout in `orc ui` > CLI Hook Interface (the CLI half exists so the panel has something to shell). Turning this on with an invalid or missing layout is refused, naming the reason; a layout that later becomes unreadable falls back to the shipped lines silently and is reported by `orc doctor`." },
   { key: "wait_hop_minutes", def: 30, tier: "advanced", answers: [{ family: "wait", prio: "P2", mode: "replace" }], lanes: [], validate: vInt(1), options: [5, 10, 15, 30], desc: "How long ONE detached hop waits before ORC re-reads the window. Short on purpose: each wake-up is session activity, and session activity is the only thing that makes the statusline write a fresh reading. One long sleep wakes into a reading as stale as the sleep was long." },
   { key: "wait_max_hops", def: 5, tier: "advanced", answers: [{ family: "wait", prio: "P2", mode: "replace" }], lanes: [], validate: vInt(1), options: [1, 2, 3, 5, 8, 12], desc: "How many hops before ORC gives up and stops with the hand-back. A wrong reset time must cost you a bounded wait, never a session that never comes back." },
@@ -32462,6 +32493,56 @@ function doctor() {
     }
   } catch (_) {}
 
+  // 5a-bis) the read gate (v1.6.0). Same two rules as the status line above,
+  // for the same reasons. ONLY WHILE ARMED: `read_gate: off` is the default and
+  // the overwhelmingly common state, and a doctor that warns about the default
+  // is a doctor people learn to scroll past. And the hook FAILS OPEN — it must,
+  // because a read gate that throws and blocks a read has broken the tool — so
+  // it records WHY, and this is where that recording becomes a sentence. A gate
+  // that quietly stopped gating is exactly the bug a user cannot report.
+  try {
+    const cfg = resolvedConfig(claudeDir);
+    const mode = String(cfg.read_gate || "off").toLowerCase();
+    if (mode === "off") {
+      ok("read gate off (fine — the default; the read ladder stays advisory)");
+    } else {
+      // Armed but never wired: the hook exists and the key is on, yet nothing
+      // in settings.json matches `Read`, so the gate has never once fired.
+      const wired = (() => {
+        try {
+          const s = JSON.parse(fs.readFileSync(path.join(claudeDir, "settings.json"), "utf8"));
+          return (s.hooks && s.hooks.PreToolUse ? s.hooks.PreToolUse : []).some((e) =>
+            (e.hooks || []).some((h) => String(h.command || "").includes("orc-read-gate"))
+          );
+        } catch (_) {
+          return false;
+        }
+      })();
+      const st = (() => {
+        try {
+          return JSON.parse(
+            fs.readFileSync(path.join(claudeDir, "orc", "read-gate-fallback.json"), "utf8")
+          );
+        } catch (_) {
+          return null;
+        }
+      })();
+      if (!wired)
+        warn(
+          "read-gate-unwired",
+          `read_gate is '${mode}' but .claude/settings.json has no PreToolUse hook on Read — the gate has never fired`,
+          { fix: "orc update", fix_command: "orc update" }
+        );
+      else if (st && st.rung && Date.now() - (st.at || 0) < 24 * 60 * 60 * 1000)
+        warn(
+          "read-gate-fallback",
+          `read gate: it allowed a read it could not judge (${st.rung}${st.detail ? ": " + st.detail : ""}) — fail-open worked, but the gate was blind for that read`,
+          { fix: "orc doctor  (the record clears itself after 24h)" }
+        );
+      else ok(`read gate armed (${mode}) and wired`);
+    }
+  } catch (_) {}
+
   // 5b) the wiki (v0.49.1). Exactly TWO findings, and the restraint is the
   // design: a doctor that warns about normal states teaches people to ignore
   // doctor. Both route to the Knowledge panel via FINDING_ROUTE — a caution

package/bin/verify-contracts.js

@@ -869,6 +869,10 @@ const CONTRACTS = [
       "skills/orc-test/SKILL.md",
       "agents/orc-trace-writer-haiku-4-5.md",
       "hooks/orc-trace.js",
+      // v1.6.0: the read gate READS the pointer to decide whether an ORC run
+      // is open at all. Outside a run it refuses nothing — the gate constrains
+      // ORC's own reading, never the user's session.
+      "hooks/orc-read-gate.js",
       // v1.2.1: the statusline READS the pointer to decide which run `status:`
       // is about. "The newest file" would be a different, wrong answer during
       // a lane suspend, when two traces are live and only one is the run.
@@ -2616,6 +2620,12 @@ const CONTRACTS = [
     name: "read ladder (escalating read discipline for read-heavy roles)",
     token: "read-ladder.md",
     files: [
+      // v1.6.0 — the ENFORCEMENT half. The ladder was advisory prose in three
+      // places and enforced in none; this hook is the layer that can refuse.
+      // It cites the ladder by name because its two carve-outs ARE the
+      // ladder's two exceptions — rename the file and the gate's reason text
+      // stops naming anything real.
+      "hooks/orc-read-gate.js",
       "agents/orc-executor-haiku-4-5.md",
       "agents/orc-executor-opus-4-7-high.md",
       "agents/orc-executor-opus-4-7-med.md",
@@ -3293,48 +3303,48 @@ const CONTRACTS = [
     files: ["skills/_shared/config-precedence.md", "skills/orc/config.md"],
     binFiles: ["bin/cli.js"],
   },
-  // ── v1.5.0 — /orc-test, the lane that RUNS the test ───────────────────────
-  // THE TRIPLE. Registered together because they fail together: a lane that
-  // will edit the system under test has already stopped needing permission to
-  // reach it, and one that reports what it did not observe has nothing left
-  // that a target's authorization was protecting.
-  {
-    name: "three verdicts, and `unknown` is the honest one (v1.5.0 — /orc-test)",
-    token: "a lane that reports a result it did not observe",
-    files: ["skills/_shared/live-target.md", "skills/orc-test/SKILL.md"],
-    binFiles: ["bin/cli.js"],
-  },
-  {
-    name: "the target is FROZEN and authorized (v1.5.0 — /orc-test)",
-    token: "a lane that sends traffic to a target nobody authorized",
-    files: ["skills/_shared/live-target.md", "skills/orc-test/SKILL.md"],
-    binFiles: ["bin/cli.js"],
-  },
-  {
-    name: "it measures and hands back — it never repairs (v1.5.0 — /orc-test)",
-    token: "a lane that fixes the system under test",
-    files: ["skills/_shared/live-target.md", "skills/orc-test/SKILL.md"],
-    binFiles: ["bin/cli.js"],
-  },
-  // Two single-token CLI mirrors. Both are PATHS the CLI composes and the
-  // payload names, so a rename on either side is exactly the drift a
-  // presence-only assertion catches (the v0.29.0 `binFiles` shape).
-  {
-    name: "orc-test run folder (v1.5.0 — project root, never .claude/, never staged)",
-    token: "orc/orc-test/",
-    files: [
-      "agents/orc-test-interpreter-opus-5-low.md",
-      "commands/orc-test.md",
-      "skills/orc-test/SKILL.md",
-    ],
-    binFiles: ["bin/cli.js"],
-  },
-  {
-    name: "the evidence folder every finding cites (v1.5.0 — redacted before it reaches disk)",
-    token: "evidence/",
-    files: ["agents/orc-test-interpreter-opus-5-low.md", "skills/_shared/live-target.md"],
-    binFiles: ["bin/cli.js"],
-  },
+  // ── v1.5.0 — /orc-test, the lane that RUNS the test ───────────────────────
+  // THE TRIPLE. Registered together because they fail together: a lane that
+  // will edit the system under test has already stopped needing permission to
+  // reach it, and one that reports what it did not observe has nothing left
+  // that a target's authorization was protecting.
+  {
+    name: "three verdicts, and `unknown` is the honest one (v1.5.0 — /orc-test)",
+    token: "a lane that reports a result it did not observe",
+    files: ["skills/_shared/live-target.md", "skills/orc-test/SKILL.md"],
+    binFiles: ["bin/cli.js"],
+  },
+  {
+    name: "the target is FROZEN and authorized (v1.5.0 — /orc-test)",
+    token: "a lane that sends traffic to a target nobody authorized",
+    files: ["skills/_shared/live-target.md", "skills/orc-test/SKILL.md"],
+    binFiles: ["bin/cli.js"],
+  },
+  {
+    name: "it measures and hands back — it never repairs (v1.5.0 — /orc-test)",
+    token: "a lane that fixes the system under test",
+    files: ["skills/_shared/live-target.md", "skills/orc-test/SKILL.md"],
+    binFiles: ["bin/cli.js"],
+  },
+  // Two single-token CLI mirrors. Both are PATHS the CLI composes and the
+  // payload names, so a rename on either side is exactly the drift a
+  // presence-only assertion catches (the v0.29.0 `binFiles` shape).
+  {
+    name: "orc-test run folder (v1.5.0 — project root, never .claude/, never staged)",
+    token: "orc/orc-test/",
+    files: [
+      "agents/orc-test-interpreter-opus-5-low.md",
+      "commands/orc-test.md",
+      "skills/orc-test/SKILL.md",
+    ],
+    binFiles: ["bin/cli.js"],
+  },
+  {
+    name: "the evidence folder every finding cites (v1.5.0 — redacted before it reaches disk)",
+    token: "evidence/",
+    files: ["agents/orc-test-interpreter-opus-5-low.md", "skills/_shared/live-target.md"],
+    binFiles: ["bin/cli.js"],
+  },
 ];
 
 // Spine size budgets (v0.19.0). These SKILL.md files are ALWAYS loaded when
@@ -3741,6 +3751,14 @@ for (const b of BUDGETS) {
     // exactly as no spine reads `extra_timeout_s`. An empty lanes[] here is an
     // ANSWER.
     "test_max_rps",
+    // v1.6.0 — operating keys of the READ GATE HOOK, and the same answer as
+    // `statusline_custom` for the same reason: a hook has no lane and cannot
+    // resolve config, so it reads the raw key off the file exactly as it
+    // already does for `log_dir`. No spine reads either of these — the gate
+    // acts on the MAIN session's reads, which no lane is in a position to
+    // mediate. An empty lanes[] here is an ANSWER, not a to-do.
+    "read_gate",
+    "read_gate_max_lines",
   ]);
   for (const e of metaEntries) {
     if (!e.lanes) {

package/bin/verify-package.js

@@ -480,6 +480,9 @@ const required = [
   // it. Wired even with the board off, because the measurement is handed over
   // either way.
   "templates/hooks/orc-subagent-line.js",
+  // v1.6.0 — the read gate. The one layer that can refuse an oversized read by
+  // the ORCHESTRATOR. Ships wired but OFF; `read_gate` arms it.
+  "templates/hooks/orc-read-gate.js",
   "templates/hooks/orc-trace.js",
 ];
 

package/bin/webui/i18n/en/overview.json

@@ -87,6 +87,7 @@
   "overview.item.legacyGlobalPackage.cta": "Open Maintenance",
   "overview.item.extraDemotedRun.cta": "Open Extra",
   "overview.item.laneKeysDrifted.cta": "Open Maintenance",
+  "overview.item.readGateUnwired.cta": "Open Maintenance",
   "overview.extraOrphan.title": "A dispatch did not report back",
   "overview.extraOrphan.note": "ORC sent work to a non-Claude worker and never heard the result. Its changes may still be on disk.",
   "overview.extraOrphan.chip": "{n} dispatch",

package/bin/webui/i18n/id/overview.json

@@ -87,6 +87,7 @@
   "overview.item.legacyGlobalPackage.cta": "Buka Pemeliharaan",
   "overview.item.extraDemotedRun.cta": "Buka Extra",
   "overview.item.laneKeysDrifted.cta": "Buka Pemeliharaan",
+  "overview.item.readGateUnwired.cta": "Buka Pemeliharaan",
   "overview.extraOrphan.title": "Sebuah pengiriman tidak melapor kembali",
   "overview.extraOrphan.note": "ORC mengirim pekerjaan ke pekerja non-Claude dan tidak pernah menerima hasilnya. Perubahannya mungkin masih ada di disk.",
   "overview.extraOrphan.chip": "{n} pengiriman",

package/bin/webui/js/panels/overview.js

@@ -77,6 +77,14 @@ const FINDING_ROUTE = {
   // `test-evidence-unstaged` goes there too even though the fix is a line in
   // .gitignore that ORC will not write: Test is where the sentence explaining
   // WHY that folder must never be staged already lives.
+  // v1.6.0. An INSTALL-FOOTPRINT finding takes the documented default:
+  // `read-gate-unwired` is cleared by `orc update`, which is an action row on
+  // MAINTENANCE. `read-gate-fallback` is NOT a button anywhere — the record
+  // ages out on its own and there is nothing to press — so it gets
+  // `panel: null` rather than a button that would do nothing, the same call
+  // `trace-pointer-dangling` made.
+  "read-gate-unwired": { panel: "maintenance", cta: "overview.item.readGateUnwired.cta" },
+  "read-gate-fallback": { panel: null },
   "test-env-unhealthy": { panel: "test", cta: "overview.item.testEnvUnhealthy.cta" },
   "test-run-red": { panel: "test", cta: "overview.item.testRunRed.cta" },
   "test-unchecked-owasp": { panel: "test", cta: "overview.item.testUncheckedOwasp.cta" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-id/orc",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "ORC — an orchestrator skill constellation for Claude Code: intake, planning, scored parallel subagents, code-pattern matching, review, verify, ship, plus a project knowledge-base wiki.",
   "bin": {
     "orc": "bin/cli.js"

package/templates/hooks/README.md

@@ -1,8 +1,11 @@
-# The ORC status line
+# The ORC hooks
 
 > This page is written in Simplified Technical English. Short sentences, one
 > idea each, plain words. See `bin/webui/i18n/TERMS.md` for the term list.
 
+This page covers the two hooks you can see. The STATUS LINE, which shows what
+is happening, and the READ GATE, which can stop an oversized read.
+
 ORC shows two lines at the bottom of your terminal. Claude Code draws them.
 ORC writes them.
 
@@ -258,6 +261,91 @@ it did not see.
 
 ---
 
+## The read gate
+
+This is a different hook. It is off when you install ORC.
+
+ORC has a rule about reading. The main session reads a file to FIND things.
+To UNDERSTAND a file, ORC sends an agent to read it and report back. The agent
+uses its own context, not yours. The rule was written in three guide files and
+nothing checked it. The read gate is the part that can say no.
+
+Turn it on like this:
+
+```
+orc config set read_gate warn     # it tells you, and still reads the file
+orc config set read_gate block    # it stops the read
+orc config set read_gate off      # the default
+```
+
+### What it does
+
+It looks at one thing: a `Read` of a whole file, by the main session, during an
+ORC run, when the file is 1000 lines or more.
+
+In `warn` it shows you a note and reads the file anyway. In `block` it stops the
+read and tells you three other ways to get what you need:
+
+- Read the file with `offset` and `limit`. This is never stopped.
+- Search the file first, then read that part.
+- Send an agent to read it. An agent's reads are never stopped.
+
+**A block always names another way.** A gate that only says no is a gate people
+turn off.
+
+### When it says nothing
+
+This list is the important part. The gate is quiet in all of these states, and
+each one is on purpose:
+
+| State | Why |
+|---|---|
+| An agent is reading | An agent must read a file in full before it edits it. If it could not, it would guess the old text and damage the file. |
+| `read_gate` is `off` | This is the default. With `off`, the hook does nothing at all. |
+| No ORC run is open | The gate is about ORC's own reading. It is not a rule for your session. Outside a run it never stops anything. |
+| You used `offset` or `limit` | This is the behaviour the gate wants. It can never stop it. |
+| The file is under 1000 lines | See the next part. |
+| The file is a build log, a test result, or `.jsonl` | ORC reads these to decide pass or fail. A cut-short failing build looks like a passing build. That is worse than any saving. |
+| The gate hit an error | It always lets the read through. Then it writes down what went wrong. |
+
+**The gate cannot see a file you read with a shell command** such as `cat` or
+`head`. It only sees the `Read` tool.
+
+### Why 1000 lines
+
+Sending an agent is not free. One real agent read cost about 13,000 tokens and
+about 76 seconds. A line in this project is about 55 characters. So a file must
+be near 1000 lines before sending an agent costs less than reading it yourself.
+
+Below that number, sending an agent costs more than it saves.
+
+You can change it:
+
+```
+orc config set read_gate_max_lines 500
+```
+
+### What it never does
+
+- It never stops an agent's read.
+- It never stops a read outside an ORC run.
+- It never stops a `Bash` command.
+- It never reads the file to you. It only counts the lines.
+- It never fails closed. If the hook breaks, your read still happens.
+
+### Where to look when it acts
+
+Every `warn` and every `block` writes one line in the run trace:
+
+```
+[070926 14:22:01.220] hook     READ-GATE block :: lines=2400 max=1000 file=big-plan.md
+```
+
+An allowed read writes nothing. `orc doctor` tells you if the gate is on but not
+wired, and if it ever had to let a read through because it could not judge it.
+
+---
+
 ## For maintainers
 
 - The hook is `orc-statusline.js`. `orc init` installs it and wires it into
@@ -285,3 +373,24 @@ it did not see.
 - The cache file is `.claude/orc/usage-session.json`. The hook reads it once and
   writes it once, after the text is ready. It stores raw numbers only — never a
   word like `fresh` or `STALE`, which is computed each time it is shown.
+
+### The read gate
+
+- The hook is `orc-read-gate.js`, on `PreToolUse` with matcher `Read`. `orc
+  init` wires it even though `read_gate` defaults to `off`, so arming it is a
+  config edit and never an install step somebody has to find.
+- **`off` is byte-identical to not having the hook**, and a test asserts it.
+- **`agent_id` is the only way to tell a subagent's read from the main
+  session's, and this was MEASURED, not assumed.** `PreToolUse` does fire
+  inside a dispatched subagent, and `session_id` and `transcript_path` are
+  identical in both. A gate written against either would block the full read an
+  executor must do before it edits, and a reconstructed `old_string` corrupts
+  files. Test for the PRESENCE of `agent_id`. Never test for the absence of
+  another key — that is not a positive statement about anything.
+- The threshold is measured, not borrowed. See `read_gate_max_lines`.
+- It fails open on every path, and each failure it can name writes
+  `.claude/orc/read-gate-fallback.json` for `orc doctor` to turn into a
+  sentence — only while the feature is armed.
+- It writes one trace line per `warn` and per `block`, never on an allow. That
+  is affordable here for a structural reason: the gate only acts while a run is
+  open, so a trace always exists.

package/templates/hooks/orc-read-gate.js

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * ORC read gate — a Claude Code PreToolUse hook on `Read`.
+ *
+ * ORC's read discipline (`skills/_shared/read-ladder.md`, orc-doc hard rule 0,
+ * orc-quick line 21) says the ORCHESTRATOR reads to LOCATE and dispatches to
+ * UNDERSTAND. That rule was advisory prose in three places and enforced in
+ * none. This hook is the one layer that can refuse.
+ *
+ * It is DELIBERATELY the narrowest useful gate. Everything below is a state in
+ * which it says nothing at all, and every one of them is intentional:
+ *
+ *   - a SUBAGENT is reading            (measured: W1 — see `agent_id` below)
+ *   - `read_gate` is `off`             (the default)
+ *   - no ORC run is open
+ *   - the read is already targeted     (`offset` / `limit` — ladder step 3)
+ *   - the file is under the threshold
+ *   - the file is output a gate parses (ladder exception 2)
+ *   - `read_gate` is `warn`            (it says so, and still allows)
+ *
+ * THE SUBAGENT RULE IS LOAD-BEARING, AND IT IS MEASURED, NOT ASSUMED.
+ * `PreToolUse` DOES fire inside a dispatched subagent. `session_id` and
+ * `transcript_path` are IDENTICAL in both contexts — a gate written against
+ * either would treat an executor's read as the orchestrator's and block the
+ * full read that must precede an `Edit`, whose `old_string` cannot be
+ * reconstructed from an outline. That is a file-corruption path. The ONLY
+ * discriminator is `agent_id`, present in a subagent payload and absent in a
+ * main-session one. Test for its PRESENCE — never for the absence of some
+ * other key, which is not a positive assertion.
+ *
+ * Wiring (installed by `orc init` into .claude/settings.json):
+ *   hooks.PreToolUse[] { matcher: "Read", hooks:[{ type:"command",
+ *     command: 'node "<.claude>/hooks/orc-read-gate.js"' }] }
+ *
+ * Contract: read PreToolUse JSON from stdin. Exit 0 = allow. Exit 2 = block
+ * the tool call and show stderr to Claude, which relays it to the user.
+ *
+ * FAIL-OPEN, ALWAYS. A read gate that throws and blocks a read has broken the
+ * tool. Every failure path here exits 0, and the ones we can name RECORD
+ * themselves so `orc doctor` can turn them into a sentence — but only while
+ * the feature is armed. Precedent: orc-statusline.js is fail-silent, and the
+ * v1.3.0 statusline gate ladder is all fallbacks, each of which records itself.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// .claude/hooks/orc-read-gate.js → CLAUDE_DIR = .. → PROJECT_ROOT = ../..
+const CLAUDE_DIR = path.join(__dirname, "..");
+const PROJECT_ROOT = path.join(CLAUDE_DIR, "..");
+
+// A run whose trace has been idle this long has ENDED. Same window as
+// orc-trace.js — one idea of "a run is open", not two.
+const STALE_MS = 6 * 60 * 60 * 1000;
+
+// Default line threshold. MEASURED, not copied.
+//
+// The number in the source material this pattern came from is 350, derived
+// from a 10-30s delegation round trip. ORC's is nothing like that: a Task
+// dispatch measured p50 76s / p90 188s (n=125), and one real read-only
+// dispatch cost 13,276 tokens to read a four-line file and return three words.
+// At the measured 55.2 chars/line across 316 main-session full reads, that
+// floor is ~962 lines; at the median file's 51.9 chars/line it is ~1024.
+// Break-even is therefore ~1000 lines, and BELOW it delegating a read costs
+// more than the read does. Copying 350 would delegate work whose overhead
+// exceeds its saving.
+const DEFAULT_THRESHOLD = 1000;
+
+// Output a gate PARSES is read whole — read-ladder exception 2. The smoke
+// gate, the TDD gate, the verifier and /orc-quick's build loop all decide red
+// vs green from these exact bytes, and a truncated red build reads GREEN.
+// That is worse than any token saving, so this list is deliberately generous:
+// a false ALLOW costs tokens, a false BLOCK costs correctness.
+const GATE_PARSED =
+  /(\.(log|tap|xml|lcov|junit)$|(^|[\\/])(coverage|test-results|npm-debug|yarn-error)([\\/]|$)|\.jsonl$)/i;
+
+// ---------------------------------------------------------------------------
+// Config — tolerant top-level YAML scalar read, matching orc-trace.js exactly.
+// The repo is zero-dep; there is no YAML parser.
+// ---------------------------------------------------------------------------
+function readConfigScalar(key) {
+  try {
+    const text = fs.readFileSync(path.join(CLAUDE_DIR, "orc.config.yaml"), "utf8");
+    const re = new RegExp("^" + key + "\\s*:\\s*(.+?)\\s*(?:#.*)?$", "m");
+    const m = text.match(re);
+    return m ? m[1].replace(/^['"]|['"]$/g, "").trim() : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function logDir() {
+  const rel = readConfigScalar("log_dir") || ".claude/orc/logs";
+  return path.isAbsolute(rel) ? rel : path.join(PROJECT_ROOT, rel);
+}
+
+// Is an ORC run open? `.current` names the run; the trace file it names must
+// exist and be fresh. A pointer naming a file that does not exist is
+// indistinguishable from a dangling one (v0.34.2), so honour a pointer whose
+// OWN mtime is fresh too — neither half depends on the other.
+function runIsOpen() {
+  const dir = logDir();
+  let name;
+  try {
+    name = fs.readFileSync(path.join(dir, ".current"), "utf8").trim();
+  } catch (_) {
+    return false;
+  }
+  if (!name) return false;
+  const now = Date.now();
+  try {
+    if (now - fs.statSync(path.join(dir, name)).mtimeMs < STALE_MS) return true;
+  } catch (_) {
+    /* trace file not created yet — fall through to the pointer's own mtime */
+  }
+  try {
+    return now - fs.statSync(path.join(dir, ".current")).mtimeMs < STALE_MS;
+  } catch (_) {
+    return false;
+  }
+}
+
+// D10 — A GATE DECISION THAT LEAVES NO LINE CANNOT BE COUNTED. Same rule as a
+// resume and a demotion, and it is CHEAP HERE FOR A STRUCTURAL REASON: the gate
+// only ever acts while a run is open (rung 2), so a trace to write into is
+// guaranteed to exist by the time we get here. There is no "a read happened
+// with no run" case to handle, because that read was already allowed.
+//
+// Hook-composed, like every other line orc-trace.js writes. Best effort: a line
+// that cannot be written must never take the gate down with it.
+function traceLine(verb, tail) {
+  try {
+    const dir = logDir();
+    const name = fs.readFileSync(path.join(dir, ".current"), "utf8").trim();
+    if (!name) return;
+    const d = new Date();
+    const p = (n, w) => String(n).padStart(w || 2, "0");
+    const stamp =
+      p(d.getDate()) + p(d.getMonth() + 1) + p(d.getFullYear() % 100) + " " +
+      p(d.getHours()) + ":" + p(d.getMinutes()) + ":" + p(d.getSeconds()) +
+      "." + p(d.getMilliseconds(), 3);
+    fs.appendFileSync(
+      path.join(dir, name),
+      `[${stamp}] ${"hook".padEnd(8)} ${verb}` + (tail ? ` :: ${tail}` : "") + "\n"
+    );
+  } catch (_) {}
+}
+
+// A fallback RECORDS ITSELF (v1.3.0's rule). Best effort by construction: a
+// record that cannot be written must never take the gate down with it.
+function recordFallback(rung, detail) {
+  try {
+    const dir = path.join(CLAUDE_DIR, "orc");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, "read-gate-fallback.json"),
+      JSON.stringify({ rung, detail: String(detail || "").slice(0, 300), at: Date.now() })
+    );
+  } catch (_) {}
+}
+
+// Count lines without holding the whole file in memory twice. Returns null when
+// the file cannot be measured — and null NEVER blocks (unknown is not "big").
+function countLines(file) {
+  try {
+    const st = fs.statSync(file);
+    if (!st.isFile()) return null;
+    // A file that cannot possibly reach the threshold is not worth reading.
+    // 1 byte/line is the floor, so bytes < threshold ⇒ lines < threshold.
+    const buf = fs.readFileSync(file);
+    let n = 1;
+    for (let i = 0; i < buf.length; i++) if (buf[i] === 10) n++;
+    return n;
+  } catch (_) {
+    return null;
+  }
+}
+
+let raw = "";
+process.stdin.on("data", (c) => (raw += c));
+process.stdin.on("end", () => {
+  // RUNG 0 — anything at all goes wrong: ALLOW. This wrapper is the whole
+  // fail-open guarantee; every `return` below it is an allow.
+  try {
+    gate();
+  } catch (e) {
+    recordFallback("threw", e && e.message);
+    process.exit(0);
+  }
+  process.exit(0);
+});
+
+function gate() {
+  let data;
+  try {
+    data = JSON.parse(raw || "{}");
+  } catch (e) {
+    recordFallback("unparseable-payload", e && e.message);
+    return; // allow
+  }
+
+  if (data.tool_name !== "Read") return;
+
+  // RUNG 0.5 — a SUBAGENT is reading. ALLOW, always, and this check comes
+  // before every other one. See the header: this is what keeps the gate off
+  // the pre-`Edit` full read that an executor must perform, and it is why the
+  // gate never needs to know a slice's declared_files.
+  if (data.agent_id != null) return;
+
+  const mode = String(readConfigScalar("read_gate") || "off").toLowerCase();
+  if (mode !== "warn" && mode !== "block") return; // `off` (the default), or garbage
+
+  // RUNG 2 — no ORC run is open. The gate constrains ORC's own reading; it is
+  // not a policy on the user's session. A read outside a run is not ORC's to
+  // refuse, and the gate says nothing. This is an HONEST LIMIT, not an
+  // oversight: it is stated in templates/hooks/README.md and in `orc doctor`.
+  if (!runIsOpen()) return;
+
+  const input = data.tool_input || {};
+  const file = String(input.file_path || "");
+  if (!file) return;
+
+  // RUNG 3 — already a targeted read. This IS ladder step 3; it is the
+  // behaviour the gate exists to encourage, so it can never be refused.
+  if (input.offset != null || input.limit != null) return;
+
+  // RUNG 5 — output a gate parses. Exception 2 is not a preference.
+  if (GATE_PARSED.test(file)) return;
+
+  let threshold = parseInt(readConfigScalar("read_gate_max_lines"), 10);
+  if (!Number.isFinite(threshold) || threshold < 1) threshold = DEFAULT_THRESHOLD;
+
+  const lines = countLines(file);
+  if (lines == null) {
+    // Unmeasurable — a directory, a missing file, a permissions error, a binary
+    // the Read tool will handle its own way. UNKNOWN IS NOT BIG.
+    recordFallback("unmeasurable", file);
+    return;
+  }
+  if (lines < threshold) return; // RUNG 4 — under the threshold
+
+  // RUNG 7 — `warn`: allow, and say so. `systemMessage` is shown to the user
+  // and is NOT added to model context, so the warning itself costs no tokens.
+  if (mode === "warn") {
+    traceLine("READ-GATE warn", `lines=${lines} max=${threshold} file=${path.basename(file)}`);
+    try {
+      process.stdout.write(
+        JSON.stringify({
+          systemMessage:
+            `📖 ORC read gate — ${path.basename(file)} is ${lines} lines ` +
+            `(threshold ${threshold}). Allowed: read_gate is 'warn'.\n` +
+            `   Cheaper: Read with offset/limit, or dispatch an agent to read it and report back.`,
+        })
+      );
+    } catch (_) {}
+    return;
+  }
+
+  // RUNG 8 — block, and NAME THE ALTERNATIVE. A block that only refuses
+  // teaches people to switch it off.
+  traceLine("READ-GATE block", `lines=${lines} max=${threshold} file=${path.basename(file)}`);
+  process.stderr.write(
+    `\n⛔ ORC read gate — ${path.basename(file)} is ${lines} lines, over the ` +
+      `${threshold}-line threshold.\n` +
+      `   Reading it whole spends the orchestrator's context on material a ` +
+      `worker could summarise.\n\n` +
+      `   Do one of these instead:\n` +
+      `     • Read with offset/limit — the ladder's targeted read, and always allowed.\n` +
+      `     • Grep for what you actually need, then read that range.\n` +
+      `     • Dispatch an agent to read it and report back (its reads are never gated).\n\n` +
+      `   If you genuinely need the whole file here: set read_gate to warn or off\n` +
+      `     orc config set read_gate warn\n` +
+      `   The gate is silent outside an ORC run, on targeted reads, on files a\n` +
+      `   gate parses, and on every read a subagent makes.\n`
+  );
+  process.exit(2);
+}