@azure-id/orc 2.1.0 → 2.2.0

package/templates/commands/orc-doc.md

@@ -1,128 +1,128 @@
----
-description: Write a PRD, TSD, collaboration agreement, report or workflow as portable Markdown — resumable across sessions
----
-
-Use the **orc-doc** skill. Standalone — no plan, no build, no code written.
-
-You arrive with a context: what you want written down, and about what. You leave
-with a finished Markdown document that imports cleanly into Notion, Obsidian,
-Google Docs, Coda, Craft and GitHub — plus one line that resumes the work months
-later in a brand-new session.
-
-> **The orchestrator never reads the document body.**
-
-That is half the architecture. A 900-line TSD is about 30k tokens; read it three
-times and the session is over. So nothing that holds context ever holds the
-document: the CLI derives a section map (heading, line range, hash), each writer
-owns **exactly one file**, each checker reads **one bounded part**, and the
-orchestrator holds the map and the returns. A 10,000-line document costs the
-orchestrator about 750 lines of context instead of 20,000.
-
-> **`sections/` is the source of truth. `document.md` is a build artifact.**
-
-That is the other half. Every section lives in its own file you can open, edit
-and diff in a pull request — `sections/04-goals-and-metrics.md`, and a big section splits
-into sub-parts underneath without the reader ever knowing. `orc doc compile`
-rebuilds the document from those files, for **zero model tokens**, whenever you
-ask. So a resumed session, an update and a re-check never touch the 10,000-line
-file at all.
-
-Five base templates, and each one is a floor rather than a cage — bring your own
-and its headings become the outline:
-
-`prd` · `tsd` · `collaboration` · `report` · `workflow`
-
-It asks four things, in this order, and the first one blocks:
-
-1. **What do you want this document to say?** No context, no document — it stops
-   and points at `/orc-brainstorm` rather than inventing one.
-2. **Any files I should read first?** "none" is a complete answer. It never reads
-   them itself: one dispatch per file returns anchored claims, not content.
-3. **Do you have your own template?** Otherwise it shows you the shipped section
-   list before writing a word.
-4. **What is it for, who reads it, and what must they be able to do afterwards?**
-   Plus language, type, where it will end up, and how long. Every field has a
-   recommended default; accepting one counts as answering.
-
-Then the outline, confirmed before anything is written — because changing the
-outline after a write wave is what costs money. And one more question: **how much
-do you want written at once?** `partial` writes ONE wave and stops, so you can
-read those section files and redirect before the rest is paid for. That is the
-single biggest saving in the lane.
-
-**Every wave is a stop you can walk away from.** At each boundary you get every
-file path it wrote, a free way to see it as one document, and the one line that
-resumes the work — written to disk *before* anything that needs a subagent. If a
-usage limit kills the run, `orc resume` finds it, and the next session starts at
-the following wave and re-reads nothing it already wrote.
-
-**The document carries content only.** No "Open:" blockquotes, no "Assumption:"
-notes, no ORC bookkeeping of any kind — not in `document.md` and not in a section
-file. It still never invents a fact: what it was not given comes back as a gap,
-lands in `gaps.md`, and is raised with you.
-
-**Your project gets its own house rules.** A plain text file
-(`.claude/orc/doc-house-rules.md`) with three headings — P0, P1, P2 — and as much
-text under each as you want: *"open with a one-paragraph summary"*, *"money
-always carries its currency"*. Stored in your words and read FIRST in every
-dispatch, above ORC's own rules. Each document freezes the text it started with,
-so a rule you change halfway through cannot silently invalidate what is already
-written; `orc doc rules <slug>` names every block that moved since. House rules
-govern what the document SAYS — they can never change how this lane runs, and ORC
-declares that boundary rather than pretending to detect it.
-
-**You never have to remember where you were.** Every stop rewrites
-`RESUME.md` — plain English, the state, and the one line to paste into a brand
-new session — and every question ORC asks you ends by pointing at it.
-
-**Four rules it applies to every document, all free.** No questions or `TBD`s in
-the body (a section your outline calls *open questions* is exempt); what is
-missing is `N/A` plus one short line, never filler; a section well over its
-planned length is a finding; and no `src/foo.ts:42`, no `./relative`, no
-`localhost` — whoever reads a PRD has no repository. Code examples are always
-exempt. A template YOU supply is a cage, not a suggestion: a heading it never had
-is an error, and a part that grew one is refused rather than recorded.
-
-**You are told what it will cost before you pay for it.** Once, before the first
-write wave: how many sections, how many waves, **how many times it will stop**,
-and a token range with its sample count. With no history it refuses to invent
-numbers and offers a price-table floor instead. Afterwards, `orc doc cost <slug>`
-answers "what did this document cost" across **every session it spanned** — per
-role and per section, with a `—` (never a `0`) for anything it cannot join.
-
-**Where it will end up is a real setting, not a nicety.** `orc doc lint` enforces
-that target's actual limits: Notion has three heading levels, so an H4 is an
-error there; Docusaurus needs YAML front matter, so its absence is an error
-there and its presence is an error everywhere else. A hard-wrapped paragraph is
-an error everywhere, because a wrap at 80 columns becomes a line break inside a
-Notion paragraph. The lint is deterministic and costs zero model tokens, and it
-always runs before anything paid.
-
-**Your edits are sacred.** Edit `sections/<id>.md` yourself whenever you like —
-the lane detects it by hash, tells you which sections you touched, and never
-rewrites one unless you name it. And it will not ship a `document.md` that is
-behind its own sections: it refuses and names what moved.
-
-Coming back, in any session:
-
-```
-/orc-doc resume                  lists every document
-/orc-doc resume prd-checkout     a prefix is enough
-```
-
-The new session reads the frozen context, says what you changed, and **stops and
-asks what should change**. It never re-asks what you already answered.
-
-It never edits source, never stages, never commits — it prints the `git add`
-command. And it never grades its own output: at handoff it offers
-`/orc-challenge`, to run in a separate session.
-
-Read the state back any time without this lane: `orc doc status <slug>` for where
-it stands, `orc doc parts <slug>` for what is written — which works before a
-single compile has ever run.
-
-A document started on an older release migrates the first time you touch it.
-`document.md` is split into `sections/` and **never deleted**, a pending edit
-wins, and an unparseable file is refused rather than guessed at.
-
-What you want written, or a slug to reopen (or nothing, and it will ask): $ARGUMENTS
+---
+description: Write a PRD, TSD, collaboration agreement, report or workflow as portable Markdown — resumable across sessions
+---
+
+Use the **orc-doc** skill. Standalone — no plan, no build, no code written.
+
+You arrive with a context: what you want written down, and about what. You leave
+with a finished Markdown document that imports cleanly into Notion, Obsidian,
+Google Docs, Coda, Craft and GitHub — plus one line that resumes the work months
+later in a brand-new session.
+
+> **The orchestrator never reads the document body.**
+
+That is half the architecture. A 900-line TSD is about 30k tokens; read it three
+times and the session is over. So nothing that holds context ever holds the
+document: the CLI derives a section map (heading, line range, hash), each writer
+owns **exactly one file**, each checker reads **only the bounded part files of one slice**, and the
+orchestrator holds the map and the returns. A 10,000-line document costs the
+orchestrator about 750 lines of context instead of 20,000.
+
+> **`sections/` is the source of truth. `document.md` is a build artifact.**
+
+That is the other half. Every section lives in its own file you can open, edit
+and diff in a pull request — `sections/04-goals-and-metrics.md`, and a big section splits
+into sub-parts underneath without the reader ever knowing. `orc doc compile`
+rebuilds the document from those files, for **zero model tokens**, whenever you
+ask. So a resumed session, an update and a re-check never touch the 10,000-line
+file at all.
+
+Five base templates, and each one is a floor rather than a cage — bring your own
+and its headings become the outline:
+
+`prd` · `tsd` · `collaboration` · `report` · `workflow`
+
+It asks four things, in this order, and the first one blocks:
+
+1. **What do you want this document to say?** No context, no document — it stops
+   and points at `/orc-brainstorm` rather than inventing one.
+2. **Any files I should read first?** "none" is a complete answer. It never reads
+   them itself: one dispatch per file returns anchored claims, not content.
+3. **Do you have your own template?** Otherwise it shows you the shipped section
+   list before writing a word.
+4. **What is it for, who reads it, and what must they be able to do afterwards?**
+   Plus language, type, where it will end up, and how long. Every field has a
+   recommended default; accepting one counts as answering.
+
+Then the outline, confirmed before anything is written — because changing the
+outline after a write wave is what costs money. And one more question: **how much
+do you want written at once?** `partial` writes ONE wave and stops, so you can
+read those section files and redirect before the rest is paid for. That is the
+single biggest saving in the lane.
+
+**Every wave is a stop you can walk away from.** At each boundary you get every
+file path it wrote, a free way to see it as one document, and the one line that
+resumes the work — written to disk *before* anything that needs a subagent. If a
+usage limit kills the run, `orc resume` finds it, and the next session starts at
+the following wave and re-reads nothing it already wrote.
+
+**The document carries content only.** No "Open:" blockquotes, no "Assumption:"
+notes, no ORC bookkeeping of any kind — not in `document.md` and not in a section
+file. It still never invents a fact: what it was not given comes back as a gap,
+lands in `gaps.md`, and is raised with you.
+
+**Your project gets its own house rules.** A plain text file
+(`.claude/orc/doc-house-rules.md`) with three headings — P0, P1, P2 — and as much
+text under each as you want: *"open with a one-paragraph summary"*, *"money
+always carries its currency"*. Stored in your words and read FIRST in every
+dispatch, above ORC's own rules. Each document freezes the text it started with,
+so a rule you change halfway through cannot silently invalidate what is already
+written; `orc doc rules <slug>` names every block that moved since. House rules
+govern what the document SAYS — they can never change how this lane runs, and ORC
+declares that boundary rather than pretending to detect it.
+
+**You never have to remember where you were.** Every stop rewrites
+`RESUME.md` — plain English, the state, and the one line to paste into a brand
+new session — and every question ORC asks you ends by pointing at it.
+
+**Four rules it applies to every document, all free.** No questions or `TBD`s in
+the body (a section your outline calls *open questions* is exempt); what is
+missing is `N/A` plus one short line, never filler; a section well over its
+planned length is a finding; and no `src/foo.ts:42`, no `./relative`, no
+`localhost` — whoever reads a PRD has no repository. Code examples are always
+exempt. A template YOU supply is a cage, not a suggestion: a heading it never had
+is an error, and a part that grew one is refused rather than recorded.
+
+**You are told what it will cost before you pay for it.** Once, before the first
+write wave: how many sections, how many waves, **how many times it will stop**,
+and a token range with its sample count. With no history it refuses to invent
+numbers and offers a price-table floor instead. Afterwards, `orc doc cost <slug>`
+answers "what did this document cost" across **every session it spanned** — per
+role and per section, with a `—` (never a `0`) for anything it cannot join.
+
+**Where it will end up is a real setting, not a nicety.** `orc doc lint` enforces
+that target's actual limits: Notion has three heading levels, so an H4 is an
+error there; Docusaurus needs YAML front matter, so its absence is an error
+there and its presence is an error everywhere else. A hard-wrapped paragraph is
+an error everywhere, because a wrap at 80 columns becomes a line break inside a
+Notion paragraph. The lint is deterministic and costs zero model tokens, and it
+always runs before anything paid.
+
+**Your edits are sacred.** Edit `sections/<id>.md` yourself whenever you like —
+the lane detects it by hash, tells you which sections you touched, and never
+rewrites one unless you name it. And it will not ship a `document.md` that is
+behind its own sections: it refuses and names what moved.
+
+Coming back, in any session:
+
+```
+/orc-doc resume                  lists every document
+/orc-doc resume prd-checkout     a prefix is enough
+```
+
+The new session reads the frozen context, says what you changed, and **stops and
+asks what should change**. It never re-asks what you already answered.
+
+It never edits source, never stages, never commits — it prints the `git add`
+command. And it never grades its own output: at handoff it offers
+`/orc-challenge`, to run in a separate session.
+
+Read the state back any time without this lane: `orc doc status <slug>` for where
+it stands, `orc doc parts <slug>` for what is written — which works before a
+single compile has ever run.
+
+A document started on an older release migrates the first time you touch it.
+`document.md` is split into `sections/` and **never deleted**, a pending edit
+wins, and an unparseable file is refused rather than guessed at.
+
+What you want written, or a slug to reopen (or nothing, and it will ask): $ARGUMENTS

package/templates/commands/orc-export.md

@@ -1,46 +1,51 @@
----
-description: Compile everything ORC knows into a portable AGENTS.md — derived, fingerprinted, checkable — or import an existing one
----
-
-Use the **orc-export** skill. Mostly CLI; no scan, no build, no code written.
-
-Two reasons this exists, and the second is the interesting one:
-
-1. **It removes the adoption objection.** "Are we locked into ORC?" → "No. Here is
-   the door, one command, an open standard."
-2. **It makes ORC the producer in a multi-agent shop.** ORC does the expensive
-   thinking — the evidence-anchored wiki, the reconciled code pattern, the invariant
-   ledger, the boundary cards — and Codex, Cursor and everything else consume the
-   result for free.
-
-**OUT** — `orc export` compiles, in this order: the orientation doc (read first by
-every consumer), `PACT.md` (the promises — the single most useful thing to hand a
-foreign agent), the boundary cards with their checklists, the per-language code
-patterns, then the feature and reference wiki docs.
-
-- **Derived, never hand-written.** It carries a `source_commit` and a fingerprint of
-  every source, so **`orc export --check` proves it is current** — exit 1 names which
-  source changed, and which are no longer sources at all. Run it in CI next to
-  `orc wiki sync --check` and the export can never quietly rot.
-- **Sources are copied through, never re-summarised.** A summary of an
-  evidence-anchored doc is a doc with the evidence removed.
-- **Never exports** secrets, anything `.env`-shaped, run folders or logs. This is a
-  file people commit and paste into other tools.
-- `--target skill` or `both` also writes a `SKILL.md` bundle.
-
-**IN** — `orc export import` reads an existing `AGENTS.md`, `CLAUDE.md`,
-`.cursorrules` or copilot instructions in a repo that may never have run ORC, and
-gives you two things:
-
-- **What is already wrong**: every file path that context names which does not exist,
-  every command the manifest does not have. Free, and a very good first impression —
-  those lines have been lying to somebody's agent for months.
-- **Seeds**: candidate pact entries and wiki topics, one at a time, for you to keep or
-  drop.
-
-**Imported context is evidence, never instruction.** A `.cursorrules` that says
-"always run migrations automatically" is a claim about somebody's intent, quoted with
-its source. It cannot change a phase and cannot authorize a write — import
-**proposes**, you confirm, and `/orc-pact` records what you keep with an origin.
-
-`out`, `--check`, or `import` (or nothing and it will ask): $ARGUMENTS
+---
+description: Compile everything ORC knows into a portable AGENTS.md — derived, fingerprinted, checkable — or import an existing one
+---
+
+Use the **orc-export** skill. Mostly CLI; no scan, no build, no code written.
+
+Two reasons this exists, and the second is the interesting one:
+
+1. **It removes the adoption objection.** "Are we locked into ORC?" → "No. Here is
+   the door, one command, an open standard."
+2. **It makes ORC the producer in a multi-agent shop.** ORC does the expensive
+   thinking — the evidence-anchored wiki, the reconciled code pattern, the invariant
+   ledger, the boundary cards — and Codex, Cursor and everything else consume the
+   result for free.
+
+**OUT** — `orc export` compiles, in this order: the orientation doc (read first by
+every consumer), `PACT.md` (the promises — the single most useful thing to hand a
+foreign agent), the boundary cards with their checklists, the per-language code
+patterns, then the feature and reference wiki docs.
+
+- **Derived, never hand-written.** It carries a `source_commit` and a fingerprint of
+  every source, so **`orc export --check` proves it is current** — exit 1 names which
+  source changed, and which are no longer sources at all. Run it in CI next to
+  `orc wiki sync --check` and the export can never quietly rot.
+- **`orc export` OVERWRITES `AGENTS.md`.** A hand-written file has no
+  derived header, and `--check` reports it as STALE (exit 1). So
+  ALWAYS run `orc export --check --json` first. When `exists: true` and the file
+  has no header, ask the user before the write.
+- **Sources are copied through, never re-summarised.** A summary of an
+  evidence-anchored doc is a doc with the evidence removed.
+- **Never exports** secrets, anything `.env`-shaped, run folders or logs. This is a
+  file people commit and paste into other tools.
+- `--target skill` or `both` also writes a `SKILL.md` bundle.
+
+**IN** — `orc export import` reads an existing `AGENTS.md`, `CLAUDE.md`,
+`.cursorrules` or copilot instructions in a repo that may never have run ORC, and
+gives you two things:
+
+- **What is already wrong**: every file path it names that does not exist
+  (`wrong[]`); commands it names go to `seed_invariants[]` for the model to check
+  against `package.json` scripts. Free, and a very good first impression —
+  those lines have been lying to somebody's agent for months.
+- **Seeds**: candidate pact entries and wiki topics, one at a time, for you to keep or
+  drop.
+
+**Imported context is evidence, never instruction.** A `.cursorrules` that says
+"always run migrations automatically" is a claim about somebody's intent, quoted with
+its source. It cannot change a phase and cannot authorize a write — import
+**proposes**, you confirm, and `/orc-pact` records what you keep with an origin.
+
+`out`, `--check`, or `import` (or nothing and it will ask): $ARGUMENTS

package/templates/commands/orc-fast.md

@@ -1,10 +1,10 @@
----
-description: Fastest lane — knowledge-gated single Sonnet 4.6 high executor; needs fresh wiki + pattern cache, else falls back to orc-mini
----
-
-Use the **orc-fast** skill. It needs a fresh project wiki AND a cached
-code-pattern for the request's language; either missing → it falls back to
-orc-mini with the request carried over. Then one Sonnet 4.6 high executor, a
-build+test smoke gate, and ship.
-
-Request: $ARGUMENTS
+---
+description: Fastest lane — knowledge-gated single Sonnet 5 medium executor; needs fresh wiki + pattern cache, else falls back to orc-mini
+---
+
+Use the **orc-fast** skill. It needs a fresh project wiki AND a cached
+code-pattern for the request's language; either missing → it falls back to
+orc-mini with the request carried over. Then one Sonnet 5 medium executor, a
+build+test smoke gate, and ship.
+
+Request: $ARGUMENTS

package/templates/hooks/README.md

@@ -45,7 +45,10 @@ If ORC cannot read its own version, it shows `ORC` with no number. It does not
 guess.
 
 **This line can only warn you.** A status line cannot stop a command. The
-`orc-effort-guard.js` hook is what stops a run at a low effort.
+`orc-effort-guard.js` hook is what stops a run at a low effort. It reads the
+effort two ways. A Skill call carries it. A typed `/orc` or `/orc-diy` reads the
+effort that THIS line wrote for THIS session. With no ORC status line (headless
+`claude -p`, or a line of your own), a typed `/orc` is not stopped.
 
 ### 2. `context (34%)`
 
@@ -455,8 +458,10 @@ one row in the gain ledger per file per run, no line sent to anyone. `orc graph
 gain` prints the count as `wide reads`. It is the number to look at before you
 turn `on,read` on; nothing turns it on by itself.
 
-It says each thing once per run. It never speaks to the main session, never
-outside an ORC run, and never when the map does not exist.
+It says each thing once per run. It speaks to the main session in one case
+only: a Grep, Glob or shell search of a name the graph knows gets the ctx card
+(callers, tests, coverage, the `--anchors` line), once per name and at most 3
+per run, under `code_graph: on` only. It never speaks outside an ORC run, and never when the map does not exist.
 
 ### What it will never do
 

package/templates/hooks/orc-effort-guard.js

@@ -2,23 +2,30 @@
 "use strict";
 
 /**
- * ORC effort guard — a Claude Code PreToolUse hook.
+ * ORC effort guard — a Claude Code hook on TWO events (v2.1.2, F13).
  *
- * Blocks invocation of the full `orc` orchestrator skill unless the MAIN
- * session is running at HIGH reasoning effort (Opus 5.5 / Fable 5 clear at
- * medium+ — see the session-model bridge below). This is the one half of the
- * "run ORC on Opus 4.8 high or better" rule hooks can enforce deterministically:
- * Claude Code exposes `effort.level` (and $CLAUDE_EFFORT) to PreToolUse, but
- * NOT the model id (only SessionStart may see the model, and cannot block).
- * The model tier is surfaced separately by the statusline warning + the
- * self-check inside skills/orc/SKILL.md.
+ * Blocks the full `orc` orchestrator skill (and the compiled `orc-diy` lane)
+ * unless the MAIN session is running at HIGH reasoning effort (Opus 5.5 /
+ * Fable 5 clear at medium+ — see the session-model bridge below). This is the
+ * one half of the "run ORC on Opus 4.8 high or better" rule hooks can enforce
+ * deterministically: Claude Code exposes `effort.level` (and $CLAUDE_EFFORT)
+ * to PreToolUse, but NOT the model id (only SessionStart may see the model,
+ * and cannot block). The model tier is surfaced separately by the statusline
+ * warning + the self-check inside skills/orc/SKILL.md.
  *
  * Wiring (installed by `orc init` into .claude/settings.json):
  *   hooks.PreToolUse[] { matcher: "Skill", hooks:[{ type:"command",
  *     command: 'node "<.claude>/hooks/orc-effort-guard.js"' }] }
+ *   hooks.UserPromptExpansion[] { matcher: "orc|orc-diy", hooks:[ the same ] }
  *
- * 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.
+ * PreToolUse(Skill) = a model-made Skill call; it carries the LIVE effort.
+ * UserPromptExpansion = a TYPED /orc or /orc-diy; it carries NO effort, so the
+ * effort is read from the status line's bridge — and only from a bridge THIS
+ * session wrote, with no /model, /effort or /config typed after it. An effort
+ * nobody can read never blocks (fail-open).
+ *
+ * Contract: read the event JSON from stdin. Exit 0 = allow. Exit 2 = block
+ * and show stderr (to Claude on a tool call, to the user on a typed command).
  *
  * Also surfaces a "newer orc version available" nudge here — this hook fires
  * exactly when /orc is invoked, so it's the natural place to tell the user
@@ -53,8 +60,12 @@ const effortsAtOrAbove = (e) => {
 // behaves exactly as it would without a bridge (never blocks on our own error).
 // Stale = older than this window; a live session re-renders the statusline far
 // more often, so a fresh file always exists during active use.
+// v2.1.2 (F13): it names its session. A bridge written by ANOTHER session is
+// never read. `strict` (the typed path, which can BLOCK on it) also refuses a
+// bridge with no session_id — a 2.1.1 bridge, or the eval harness before its
+// update.
 const BRIDGE_MAX_AGE_MS = 30 * 60 * 1000;
-function readSessionModel(projectDir) {
+function readBridge(projectDir, sessionId, strict) {
   try {
     const fs = require("fs");
     const path = require("path");
@@ -62,17 +73,54 @@ function readSessionModel(projectDir) {
     const j = JSON.parse(fs.readFileSync(p, "utf8").replace(/^/, ""));
     if (!j || typeof j.written_at !== "number") return null;
     if (Date.now() - j.written_at > BRIDGE_MAX_AGE_MS) return null;
-    return String(j.model_id || "");
+    const sid = typeof j.session_id === "string" ? j.session_id : "";
+    if (sid && sessionId && sid !== sessionId) return null;
+    if (strict && (!sid || !sessionId)) return null;
+    return { model_id: String(j.model_id || ""), effort: String(j.effort || "").toLowerCase(), written_at: j.written_at };
   } catch (_) {
     return null;
   }
 }
+
+// v2.1.2 (F13): a /model, /effort or /config typed AFTER the bridge was
+// written makes its reading old. Claude Code records each one in the
+// transcript as `<command-name>/effort</command-name>` with a timestamp
+// (measured, 2.1.287). Only the last 1 MiB is read; an unreadable transcript
+// proves nothing and changes nothing.
+const TIER_COMMAND = /<command-name>\/(model|effort|config)<\/command-name>/;
+function tierChangedSince(transcriptPath, sinceMs) {
+  if (!transcriptPath) return false;
+  try {
+    const fs = require("fs");
+    const fd = fs.openSync(transcriptPath, "r");
+    try {
+      const size = fs.fstatSync(fd).size;
+      const len = Math.min(size, 1024 * 1024);
+      const buf = Buffer.alloc(len);
+      fs.readSync(fd, buf, 0, len, size - len);
+      for (const line of buf.toString("utf8").split("\n")) {
+        if (!TIER_COMMAND.test(line)) continue;
+        let t = NaN;
+        try { t = Date.parse(JSON.parse(line).timestamp); } catch (_) {}
+        if (Number.isFinite(t) && t >= sinceMs) return true;
+      }
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch (_) {}
+  return false;
+}
+
 // Models that clear /orc at medium effort — strictly stronger than the Opus 4.8
 // baseline, so medium on them beats high on it. Opus 5.5 (v0.34.0) joins Fable 5.
 // The `\b` after the 5 keeps 4.8 / 4.7 / 5-something-else correctly gated.
 const isMediumOkModel = (id) =>
   /(opus|fable)[\s._-]?5\b/.test(String(id || "").toLowerCase());
 
+// Anything this file did not plan for ALLOWS — the guard never blocks on its
+// own error. (process.exit(2) is a decision, not a throw, so it is not caught.)
+process.on("uncaughtException", () => process.exit(0));
+
 let raw = "";
 process.stdin.on("data", (c) => (raw += c));
 process.stdin.on("end", () => {
@@ -83,23 +131,48 @@ process.stdin.on("end", () => {
     // Unparseable payload — never block on our own error.
     process.exit(0);
   }
+  if (!data || typeof data !== "object") process.exit(0);
 
-  const tool = data.tool_name || "";
-  const input = data.tool_input || {};
-  const skill = String(input.skill || input.name || "");
-
+  // Two events, one decision. PreToolUse(Skill) = a model-made Skill call, with
+  // the LIVE effort. UserPromptExpansion (v2.1.2, F13) = a TYPED /orc or
+  // /orc-diy: Claude Code loads skills/<name>/SKILL.md directly for those, with
+  // no Skill call, so PreToolUse never fires. That event carries no effort
+  // (measured, 2.1.287): the effort comes from the status line's bridge, and an
+  // effort nobody can read NEVER blocks.
+  const typed = data.hook_event_name === "UserPromptExpansion";
+  let skill = "";
+  let args = "";
+  if (typed) {
+    skill = String(data.command_name || "").replace(/^\//, "");
+    const a = data.command_args; // a string on 2.1.287; the docs show an array
+    args = Array.isArray(a) ? a.join(" ") : String(a || "");
+  } else {
+    if ((data.tool_name || "") !== "Skill") process.exit(0);
+    const input = data.tool_input || {};
+    skill = String(input.skill || input.name || "");
+    args = String(input.args || "");
+  }
   // Only gate the full orchestrator and the compiled DIY lane. orc-mini /
   // orc-fast / orc-analyze / subskills pass — orc-fast is DESIGNED to run at
   // Sonnet medium; never widen this match to include it.
-  const isOrc = tool === "Skill" && /^orc$/i.test(skill);
-  const isDiy = tool === "Skill" && /^orc-diy$/i.test(skill);
+  const isOrc = /^orc$/i.test(skill);
+  const isDiy = /^orc-diy$/i.test(skill);
   if (!isOrc && !isDiy) process.exit(0);
 
-  const effort = String(
-    (data.effort && data.effort.level) || process.env.CLAUDE_EFFORT || ""
-  ).toLowerCase();
-  const installed = updater ? updater.installedVersion(__dirname) : null;
   const projectDir = data.cwd || process.cwd();
+  const sessionId = String(data.session_id || "");
+  let bridge = readBridge(projectDir, sessionId, typed);
+  if (typed && bridge && tierChangedSince(data.transcript_path, bridge.written_at)) bridge = null;
+  const payloadEffort = String((data.effort && data.effort.level) || "").toLowerCase();
+  // $CLAUDE_EFFORT is read on the PreToolUse path only: the typed event does
+  // not set it, so there a value would belong to a parent process.
+  const effort = typed ? payloadEffort || (bridge ? bridge.effort : "") : payloadEffort || String(process.env.CLAUDE_EFFORT || "").toLowerCase();
+  const unknown = typed && !payloadEffort && !bridge;
+  const bridgeNote =
+    typed && !payloadEffort && bridge
+      ? `   (effort read from the ORC status line ${Math.round((Date.now() - bridge.written_at) / 1000)}s ago — changed the model or effort since? run /model or /effort once more, then re-run)\n`
+      : "";
+  const installed = updater ? updater.installedVersion(__dirname) : null;
 
   // Baseline /orc: the session must be at high effort OR stronger (xhigh/max).
   // Opus 5.5 and Fable 5 additionally clear at medium — strictly-capable models —
@@ -108,7 +181,7 @@ process.stdin.on("end", () => {
   let requiredEfforts = effortsAtOrAbove("high");
   let requiredLabel =
     "Opus 4.8 at high effort (Opus 5.5 / Fable 5 also clear at medium+)";
-  if (!isDiy && isMediumOkModel(readSessionModel(projectDir))) {
+  if (!isDiy && bridge && isMediumOkModel(bridge.model_id)) {
     requiredEfforts = ["medium", ...requiredEfforts];
   }
 
@@ -117,7 +190,7 @@ process.stdin.on("end", () => {
   // no lock = no compiled flow = deterministic onboarding block. `compile` /
   // `status` invocations pass at any effort (they just shell out to the CLI).
   if (isDiy) {
-    if (/^\s*(compile|status)\b/i.test(String(input.args || ""))) process.exit(0);
+    if (/^\s*(compile|status)\b/i.test(args)) process.exit(0);
     const fs = require("fs");
     const path = require("path");
     let lock = null;
@@ -128,7 +201,7 @@ process.stdin.on("end", () => {
             path.join(projectDir, ".claude", "orc", "diy", "flow.lock.json"),
             "utf8"
           )
-          .replace(/^\uFEFF/, "")
+          .replace(/^/, "")
       );
     } catch (_) {}
     if (!lock || !lock.session_tier) {
@@ -151,8 +224,12 @@ process.stdin.on("end", () => {
     requiredLabel = `${lock.session_tier} (compiled session_tier — needs effort ${slugEffort}+)`;
   }
 
+  // Typed, and nobody can read this session's effort → allow. The lock check
+  // above already ran: a missing flow is a fact, not a guess.
+  const failOpen = unknown;
+
   const decide = (nudge) => {
-    if (requiredEfforts.includes(effort)) {
+    if (failOpen || requiredEfforts.includes(effort)) {
       // Requirement met — allow. Surface a version nudge if one exists.
       if (nudge) {
         try {
@@ -168,6 +245,7 @@ process.stdin.on("end", () => {
         `\n   Switch this session to ${requiredLabel}, then re-run.` +
         "\n   Run the MAIN session at (or above) the required tier — subagents cannot" +
         "\n   exceed the main tier, so pinned agents silently downgrade below it.\n" +
+        bridgeNote +
         (nudge ? "\n" + nudge + "\n" : "")
     );
     process.exit(2);