@intentic/sandbox-contract 1.224.0 → 1.226.0

package/src/agent-catalog.test.ts

@@ -26,7 +26,7 @@ import type { AgentHarness, AgentProvider, PermissionMode } from "./schemas.js";
  * drops the field. The record is what fixed that, and this is what keeps it honest.
  *
  * By SHAPE, not by a list: PROVIDERS × HARNESSES comes from the catalog itself, so a provider added tomorrow is
- * covered the day it is added. If a pair fails here, the answer is a row in capabilitiesOf — never a special
+ * covered the day it is added. If a pair fails here, the answer is a row in capabilitiesOf: never a special
  * case in the surface that asked. */
 
 const pairs: { provider: AgentProvider; harness: AgentHarness }[] = PROVIDERS.flatMap((provider) =>
@@ -42,20 +42,29 @@ describe("every provider/harness pair declares what it can do", () => {
         expect(["claude-code", "codex", "opencode", "opencode-gemini", "acp", "pi"]).toContain(capabilities.runtime);
         expect(["modes", "plan"]).toContain(capabilities.permissions);
         expect(["full", "browser", "http", "none"]).toContain(capabilities.mcp);
-        // Every runtime executes SOMETHING — a record listing no backend would hide the shell every loop has.
+        // Every runtime executes SOMETHING: a record listing no backend would hide the shell every loop has.
         expect(capabilities.execution).toContain("shell");
         for (const backend of capabilities.execution) {
             expect(["shell", "js"]).toContain(backend);
         }
         expect(["namespace", "cwd"]).toContain(capabilities.isolation);
         expect(["replace", "append", "none"]).toContain(capabilities.instructions);
-        // The permission modes offered must include the mode a clamp falls back to — a floor that isn't in the
+        expect(["hooks", "approval", "refuse-only", "none"]).toContain(capabilities.rulebook);
+        expect(["masked", "none"]).toContain(capabilities.secrets);
+        /* Masking is a PostToolUse hook and nothing else can edit what a model reads, so a record claiming
+         * masked without hooks would be claiming a seam that does not exist (see the axis doc). The one
+         * direction that IS legal is hooks without masking, which is why this is an implication and not
+         * equality. */
+        if (capabilities.secrets === "masked") {
+            expect(capabilities.rulebook).toBe("hooks");
+        }
+        // The permission modes offered must include the mode a clamp falls back to: a floor that isn't in the
         // list would leave the composer showing a posture the runtime can't hold.
         expect(modesFor(capabilities)).toContain(clampMode("default", capabilities));
     });
 });
 
-// An ACP provider is an installed capability's id — any string that isn't a native provider. It gets the ACP
+// An ACP provider is an installed capability's id: any string that isn't a native provider. It gets the ACP
 // floor whatever harness the client happened to send, because the agent IS its own loop.
 test("an unknown provider id is an ACP agent, on either harness", () => {
     for (const harness of HARNESSES) {
@@ -63,12 +72,12 @@ test("an unknown provider id is an ACP agent, on either harness", () => {
     }
 });
 
-/* THE `pi` ID IS RESERVED for the Pi coding agent's own RPC runtime — an `agent`-kind capability like any ACP
+/* THE `pi` ID IS RESERVED for the Pi coding agent's own RPC runtime: an `agent`-kind capability like any ACP
  * agent, but served over Pi's JSONL protocol, which carries abilities the ACP floor cannot: real mid-turn
  * steering, the thinking-level scale, a published command list. Falling to the ACP record instead would strip
  * exactly the abilities that justify a fifth runtime. */
 describe("the pi provider", () => {
-    it("runs the pi runtime on either harness — pi is its own loop", () => {
+    it("runs the pi runtime on either harness: pi is its own loop", () => {
         for (const harness of HARNESSES) {
             expect(capabilitiesOf("pi", harness.value).runtime).toBe("pi");
         }
@@ -96,7 +105,7 @@ describe("the pi provider", () => {
  * "there is nothing to choose". Claude is always its own Claude Code loop. Kimi has no native runtime at all
  * (Moonshot speaks the Anthropic protocol directly), so it runs Claude Code whatever the client sent. Gemini is
  * Kimi's mirror: it has no CLAUDE CODE road, because that loop announces itself in every request and Google's
- * Antigravity channel refuses on the announcement — every account, every time, reported as a spent quota it
+ * Antigravity channel refuses on the announcement: every account, every time, reported as a spent quota it
  * never was. */
 test("only codex and grok change runtime with the harness", () => {
     const switched = PROVIDERS.filter((provider) => capabilitiesOf(provider.value, "native") !== capabilitiesOf(provider.value, "claude-code"));
@@ -105,26 +114,26 @@ test("only codex and grok change runtime with the harness", () => {
 });
 
 /* THE RULE THAT KEEPS CLAUDE CODE TRAFFIC AWAY FROM GOOGLE, asserted where it is decided rather than at each of
- * the surfaces that obey it. Everything downstream — the adapter that serves a turn, the transcript store, the
- * quick helper's choice of loop — reads the runtime off this record, so a Gemini turn asking for Claude Code and
+ * the surfaces that obey it. Everything downstream: the adapter that serves a turn, the transcript store, the
+ * quick helper's choice of loop: reads the runtime off this record, so a Gemini turn asking for Claude Code and
  * getting it back would put the refused loop on the road again everywhere at once. */
 test("gemini answers with its own runtime whatever harness is asked for", () => {
     const native = capabilitiesOf("gemini", "native");
 
     expect(native.runtime).toBe("opencode-gemini");
     expect(capabilitiesOf("gemini", "claude-code")).toEqual(native);
-    // Same abilities as the Grok loop it shares — only the runtime id, which keys adapter health, differs.
+    // Same abilities as the Grok loop it shares: only the runtime id, which keys adapter health, differs.
     expect({ ...native, runtime: "opencode" }).toEqual(capabilitiesOf("grok", "native"));
 });
 
-test("codex and grok under the Claude Code harness get the full ceiling — it is the same loop", () => {
+test("codex and grok under the Claude Code harness get the full ceiling, it is the same loop", () => {
     for (const provider of ["codex", "grok"] as const) {
         expect(capabilitiesOf(provider, "claude-code")).toEqual(capabilitiesOf("claude", "native"));
     }
 });
 
 // The composer's four modes describe behaviours the Claude Code loop actually has. A runtime whose every tool
-// call is pre-approved has two postures, so it is offered two names — not four names for two behaviours.
+// call is pre-approved has two postures, so it is offered two names, not four names for two behaviours.
 test("a plan-only runtime offers the two postures it has", () => {
     expect(modesFor(capabilitiesOf("codex", "native"))).toEqual(["plan", "bypassPermissions"]);
     expect(modesFor(capabilitiesOf("claude", "native"))).toEqual(["default", "acceptEdits", "plan", "bypassPermissions"]);
@@ -138,7 +147,7 @@ test("a mode the runtime can't hold falls back to the one it runs; one it can ho
     expect(clampMode("acceptEdits", capabilitiesOf("claude", "native"))).toBe("acceptEdits");
 });
 
-/* The user-facing half. The full ceiling says nothing — an empty list is what hides the picker's block — and
+/* The user-facing half. The full ceiling says nothing: an empty list is what hides the picker's block, and
  * every axis the record carries has a sentence here, because a capability nobody can read is how this started. */
 test("the ceiling has nothing to disclose; a floor names what it lacks", () => {
     expect(limitationsOf(capabilitiesOf("claude", "native"))).toEqual([]);
@@ -149,15 +158,15 @@ test("the ceiling has nothing to disclose; a floor names what it lacks", () => {
     expect(grok).toContain("no effort control");
     expect(grok).toContain("worktree by working directory only");
 
-    // ACP takes our http MCP tools when it advertises them, so its line is a narrowing rather than an absence —
+    // ACP takes our http MCP tools when it advertises them, so its line is a narrowing rather than an absence:
     // and it publishes commands and terminals, which must NOT be listed as missing.
     const acp = limitationsOf(capabilitiesOf("some-installed-agent", "native"));
-    expect(acp).toContain("MCP tools only — no plugins or browser");
+    expect(acp).toContain("MCP tools only: no plugins or browser");
     expect(acp).not.toContain("no slash commands");
     expect(acp).not.toContain("no terminal panel");
 
     const codex = limitationsOf(capabilitiesOf("codex", "native"));
-    expect(codex).toContain("browser tools only — no plugins or other MCP tools");
+    expect(codex).toContain("browser tools only: no plugins or other MCP tools");
     expect(codex).not.toContain("no MCP tools or plugins");
 });
 
@@ -176,16 +185,52 @@ test("every axis a record can lack has words for it", () => {
         terminals: false,
         recovery: false,
         instructions: "none",
+        rulebook: "none",
+        secrets: "none",
     };
 
-    // Eleven DISCLOSABLE axes, eleven sentences: an axis added to the interface without one would silently
-    // never be disclosed. fastMode is the deliberate twelfth — a record alone can't tell the truth about it (a
+    // Thirteen DISCLOSABLE axes, thirteen sentences: an axis added to the interface without one would silently
+    // never be disclosed. fastMode is the deliberate exception: a record alone can't tell the truth about it (a
     // translator-routed turn reads true here and still can't go fast), so it is answered by fastAllowed
     // instead. Anything else added to the interface has to move this number.
-    expect(limitationsOf(nothing)).toHaveLength(11);
+    expect(limitationsOf(nothing)).toHaveLength(13);
     expect(limitationsOf(nothing).join(" ")).not.toContain("fast");
 });
 
+/* The two safety axes, checked the same way the instruction axis is below and for the same reason: `rulebook`
+ * has a middle value, and disclosing the floor's words for it would tell a Codex user their rules are ignored
+ * when they are in fact being applied to everything Codex asks about. */
+test("the safety axes disclose the middle answer differently from the floor", () => {
+    const claude = limitationsOf(capabilitiesOf("claude", "native")).join(" ");
+    const codex = limitationsOf(capabilitiesOf("codex", "native")).join(" ");
+    const pi = limitationsOf(capabilitiesOf("pi", "native")).join(" ");
+
+    // The ceiling says nothing about either axis.
+    expect(claude).not.toContain("command rules");
+    expect(claude).not.toContain("stored secrets");
+
+    // The middle: rules DO apply, to what the vendor raises. Never the floor's flat "aren't applied".
+    expect(codex).toContain("only to calls this agent asks about");
+    expect(codex).not.toContain("aren't applied");
+
+    // The floor: no seam at all, said plainly.
+    expect(pi).toContain("your command rules aren't applied");
+
+    /* The third answer, which exists because OpenCode's watchdog aborts a turn that pauses. Its sentence must
+     * say the rules DO bite (unlike Pi's) and that a hold cannot ask (unlike Codex's). */
+    const grok = limitationsOf(capabilitiesOf("grok", "native")).join(" ");
+    expect(grok).toContain("a rule set to hold refuses instead");
+    expect(grok).not.toContain("aren't applied");
+    expect(grok).not.toContain("only to calls this agent asks about");
+    // Gemini rides the same loop, so it must read the same way.
+    expect(limitationsOf(capabilitiesOf("gemini", "native")).join(" ")).toBe(grok);
+
+    // Masking is binary and structural, so every non-Claude runtime says the same thing.
+    for (const provider of ["codex", "grok", "gemini", "pi", "some-installed-agent"] as const) {
+        expect(limitationsOf(capabilitiesOf(provider, "native")).join(" ")).toContain("stored secrets reach the model unmasked");
+    }
+});
+
 /* The instruction axis has THREE values and only two of them are worth a sentence, which is the one shape the
  * count above cannot check: a middle value that discloses the same words as the floor would tell a Grok user
  * their prompt is ignored when it is in fact being sent. */
@@ -196,12 +241,12 @@ test("the instruction axis discloses its two weaker answers, differently", () =>
     expect(grok).toContain("added to theirs");
     expect(grok).not.toContain("isn't applied");
     expect(acp).toContain("isn't applied");
-    // Codex on its own runtime replaces, like the Claude Code loop — so it has nothing to disclose here.
+    // Codex on its own runtime replaces, like the Claude Code loop, so it has nothing to disclose here.
     expect(limitationsOf(capabilitiesOf("codex", "native")).join(" ")).not.toContain("system prompt");
 });
 
 /* The JS backend is hosted by the one loop the daemon can put its own execution seam through. Pinned as a test
- * rather than left to the records because turn planning gates the backend on this axis — a runtime gaining it
+ * rather than left to the records because turn planning gates the backend on this axis: a runtime gaining it
  * here without a seam behind it would advertise code runs that can never execute. */
 test("only the Claude Code loop hosts the js execution backend", () => {
     for (const { provider, harness } of pairs) {
@@ -230,7 +275,7 @@ describe("the max-effort rule", () => {
         expect(effortAllowed("high", "kimi", false)).toBe(true);
     });
 
-    it("is repaired, not refused, on the way to the API — the tier drops, the user's thinking choice does not", () => {
+    it("is repaired, not refused, on the way to the API: the tier drops, the user's thinking choice does not", () => {
         expect(sendableEffort("max", false)).toBe("high");
         expect(sendableEffort("max", undefined)).toBe("high");
         expect(sendableEffort("max", true)).toBe("max");
@@ -241,7 +286,7 @@ describe("the max-effort rule", () => {
 
 /* AN `endpoint/<id>` PROVIDER is a model API the user configured, and the one thing this record has to get right
  * about it is that it is NOT an ACP agent. Both are minted by installing a capability and both are unknown to
- * NATIVE_PROVIDERS, so the id is the only thing that tells them apart — and they want opposite records: an ACP
+ * NATIVE_PROVIDERS, so the id is the only thing that tells them apart, and they want opposite records: an ACP
  * agent brings its own loop and gets the documented floor, while an endpoint is driven BY the Claude Code loop
  * and gets its full ceiling. Getting this backwards would strip steering, per-tool approvals, MCP and the mount
  * namespace from every turn on a user's own model. */
@@ -262,7 +307,7 @@ describe("a configured model endpoint", () => {
         expect(endpointProvider("gpu-box")).toBe("endpoint/gpu-box");
         expect(endpointIdOf(endpointProvider("gpu-box"))).toBe("gpu-box");
         expect(isEndpointProvider("endpoint/gpu-box")).toBe(true);
-        // A bare id that merely starts with the word is not one — the separator is what makes the namespace.
+        // A bare id that merely starts with the word is not one: the separator is what makes the namespace.
         expect(isEndpointProvider("endpoints-r-us")).toBe(false);
         expect(endpointIdOf("claude")).toBeUndefined();
         // Its credential was configured with the endpoint, so there is nothing left for a connect gate to offer.
@@ -271,7 +316,7 @@ describe("a configured model endpoint", () => {
 });
 
 /* FAST SPEED IS OFFERED ON THREE CONDITIONS AT ONCE, and the interesting cases are the ones where two of them
- * hold. A translator-routed provider runs the Claude Code loop — same record, same ceiling — and still cannot go
+ * hold. A translator-routed provider runs the Claude Code loop: same record, same ceiling, and still cannot go
  * fast, because the harness refuses a non-Anthropic endpoint; a Claude model that publishes no `fast` badge
  * cannot either. Both would be silent failures if the composer offered the control anyway: the turn runs, the
  * answer arrives, and only the bill says it was standard speed. */
@@ -281,7 +326,7 @@ describe("offering fast speed", () => {
     });
 
     it("is refused for a routed provider on the Claude Code loop, whose endpoint is not first-party", () => {
-        // Grok under the claude-code harness reads the FULL Claude Code record — the capability alone would say
+        // Grok under the claude-code harness reads the FULL Claude Code record: the capability alone would say
         // yes. It is served through the sandbox's translator, so the harness would report `not_first_party`.
         expect(capabilitiesOf("grok", "claude-code").fastMode).toBe(true);
         expect(fastAllowed(capabilitiesOf("grok", "claude-code"), "grok", ["fast"])).toBe(false);
@@ -291,7 +336,7 @@ describe("offering fast speed", () => {
 
     it("is refused for a Claude model whose catalog row doesn't publish it", () => {
         expect(fastAllowed(capabilitiesOf("claude", "native"), "claude", ["reasoning"])).toBe(false);
-        // The seed floor and any provider that reports ids only — no capabilities published, nothing claimed.
+        // The seed floor and any provider that reports ids only: no capabilities published, nothing claimed.
         expect(fastAllowed(capabilitiesOf("claude", "native"), "claude", undefined)).toBe(false);
     });
 

package/src/agent-catalog.ts

@@ -286,6 +286,49 @@ export interface AgentCapabilities {
      * only the Claude Code loop's: Codex's own base describes Codex's own tools, so swapping it for a prompt
      * written about another harness is the owner's deliberate act (their custom text), never ours. */
     readonly instructions: "replace" | "append" | "none";
+    /* WHETHER THE OWNER'S COMMAND RULEBOOK REACHES THIS RUNTIME (SandboxSettings.commandRules, decided by
+     * guard/actions.ts commandRun, delivered by guard/command-gate.ts).
+     *
+     * It exists because the rulebook was silently a Claude Code rulebook. The gate is a PreToolUse hook, which
+     * is an Agent SDK seam, so an owner who set `files.destructive: hold` was asked on a Claude turn and never
+     * on a Codex, Grok, Gemini, Pi or ACP one, with nothing on screen saying so. Same failure mode as the
+     * `instructions` axis above, and the same fix: name it once, let every surface read it.
+     *
+     *   "hooks"      , the runtime's own pre-execution hook carries the verdict and a HOLD can park the call.
+     *                  The Claude Code loop, whose PreToolUse hook fires even under bypassPermissions.
+     *   "approval"   , the vendor publishes a per-call approval channel the daemon answers from the same
+     *                  rulebook, and a hold parks on a card because the vendor is blocked on the answer
+     *                  (Codex's `item/commandExecution/requestApproval`, ACP's `session/request_permission`).
+     *                  Weaker than "hooks" in one stated way: the vendor decides WHICH calls it asks about, so a
+     *                  class it never raises is a class the rulebook cannot see. What it does raise is judged by
+     *                  the same decide fn.
+     *   "refuse-only", the same channel, but the vendor puts a CLOCK on the wait, so a hold cannot park and
+     *                  arrives as a refusal instead. OpenCode's turn has an inactivity watchdog that reads a
+     *                  paused approval as a stalled turn; a card there would break the turn rather than gate it.
+     *                  `deny` rules work fully; `hold` rules stop the command and say they could not ask.
+     *   "none"       , the runtime publishes no seam before it runs a command, so no rule can apply. Pi runs its
+     *                  bash in-process with no approval channel at all.
+     *
+     * The taint floor rides this axis too: a runtime with no consult has no place to apply it, which is why
+     * `conversationTainted` must read a "none" runtime as tainted rather than as clean (guard/turn-taint.ts). */
+    readonly rulebook: "hooks" | "approval" | "refuse-only" | "none";
+    /* WHETHER A STORED CREDENTIAL IS MASKED IN WHAT THIS RUNTIME'S MODEL READS (secrets/secret-registry.ts and
+     * the two seams around it).
+     *
+     * "masked" is the full round trip: every stored value is replaced by its `{{secret:name}}` reference on the
+     * way into the model's context, and the same reference resolves back to the value at the two exits that
+     * spend it (a shell command, a script). The Claude Code loop, via PostToolUse and PreToolUse.
+     *
+     * "none" is a STRUCTURAL limit, not an unfinished wire, and it is the reason this axis is honest rather
+     * than aspirational. On every other runtime the tool runs inside the VENDOR'S own loop: the model has read
+     * the result before the daemon sees any frame about it, so there is no seam left to rewrite. A PostToolUse
+     * hook is the only thing that can edit what a model reads, and only the Claude Code loop has one. Nothing
+     * about wiring more transports changes that, which is why the answer here is a disclosure and the real fix
+     * is to stop putting credentials where a vendor's tool can read them at all.
+     *
+     * Read by limitationsOf, and by agent/system-prompt.ts, which must not teach the reference language to a
+     * runtime that has no exit for it. */
+    readonly secrets: "masked" | "none";
 }
 
 // The Claude Code Agent SDK loop, the ceiling every other runtime is measured against, and the only one that
@@ -307,6 +350,10 @@ const CLAUDE_CODE: AgentCapabilities = {
     terminals: true,
     recovery: true,
     instructions: "replace",
+    // The only runtime with a pre-execution hook of its own, which is why it is the only one where a HOLD can
+    // park the call and wait for a card rather than having to refuse it.
+    rulebook: "hooks",
+    secrets: "masked",
 };
 
 /* Codex app-server: item-level events, process-backed MCP servers, and the four interactive seams its protocol
@@ -336,6 +383,13 @@ const CODEX: AgentCapabilities = {
      * message ahead of its skills and team blocks. Verified against codex-cli 0.147 by reading what actually
      * reached the wire, the keys are undocumented, and a strings dump proves only that they parse. */
     instructions: "replace",
+    /* App-server publishes `item/commandExecution/requestApproval`, whose params carry the command text, and
+     * takes `accept`/`decline` back (codex-cli 0.147's own generated JSON Schema, read with
+     * `codex app-server generate-json-schema`). The daemon only asks Codex to raise those requests when the
+     * owner has written command rules, so an unconfigured workspace keeps `approvalPolicy: "never"` and pays
+     * nothing (codex/codex-agent.ts threadOptions). */
+    rulebook: "approval",
+    secrets: "none",
 };
 
 // OpenCode (the Grok runtime): its own agentic loop, its own tools, allow-all permissions. It takes a model id,
@@ -357,6 +411,16 @@ const OPENCODE: AgentCapabilities = {
     // replacing that, so a custom prompt lands here as extra instructions, and the settings page says so
     // rather than letting "replaces everything" quietly mean something else on two providers.
     instructions: "append",
+    /* OpenCode asks over its own permission channel (`permission.updated`, replied on
+     * `/session/{id}/permissions/{permissionID}`, vocabulary once/always/reject), and the daemon judges what it
+     * raises with the same decide fn every other runtime uses.
+     *
+     * REFUSE-ONLY because of its watchdog, not because of its protocol. A Grok/Gemini turn is aborted after two
+     * minutes without an event for its session (grok/grok-agent.ts GROK_INACTIVITY_MS), and a permission paused
+     * on a person is exactly that silence, so a parked card would turn "ask me" into a broken turn. A `deny`
+     * rule is enforced in full; a `hold` stops the command and tells the agent it could not be asked about. */
+    rulebook: "refuse-only",
+    secrets: "none",
 };
 
 /* The same OpenCode loop, serving Gemini instead of xAI, identical abilities, which is the point of giving it
@@ -396,6 +460,12 @@ const ACP: AgentCapabilities = {
     // ACP's `session/new` and `session/prompt` carry no system field: the agent owns its own instructions the
     // same way it owns its model and its permission posture. The persona note takes the user message instead.
     instructions: "none",
+    /* `session/request_permission` is in the protocol floor, so every conforming agent has the channel and the
+     * daemon answers it from the rulebook (acp/acp-permissions.ts). The caveat the "approval" value already
+     * carries is at its widest here: WHICH calls an agent asks about is entirely the agent's choice, and one
+     * that never asks is one no rule can reach. */
+    rulebook: "approval",
+    secrets: "none",
 };
 
 /* THE PI CAPABILITY ID IS RESERVED, the same way the five native ids are: an `agent`-kind capability installed
@@ -426,6 +496,12 @@ const PI: AgentCapabilities = {
     // Pi's RPC opens a session with a prompt and steers it; nothing in that protocol sets standing
     // instructions, so like ACP it hears the persona note through the user message.
     instructions: "none",
+    /* THE ONE RUNTIME WITH NO SEAM AT ALL. Pi runs bash in-process and its RPC publishes no approval request,
+     * so there is nothing to consult before a command runs and no rule the owner writes can apply here. Said
+     * out loud rather than left to be discovered: limitationsOf renders it, and the taint floor treats a "none"
+     * runtime as permanently tainted, because a bit nobody can act on is worse than no bit. */
+    rulebook: "none",
+    secrets: "none",
 };
 
 // The pair → its record. An `endpoint/<id>` provider is a model API the user configured, driven BY the Claude
@@ -486,11 +562,11 @@ export const limitationsOf = (capabilities: AgentCapabilities): string[] => [
     ...(capabilities.mcp === "none"
         ? ["no MCP tools or plugins"]
         : capabilities.mcp === "http"
-          ? ["MCP tools only — no plugins or browser"]
+          ? ["MCP tools only: no plugins or browser"]
           : capabilities.mcp === "browser"
-            ? ["browser tools only — no plugins or other MCP tools"]
+            ? ["browser tools only: no plugins or other MCP tools"]
             : []),
-    ...(capabilities.execution.includes("js") ? [] : ["no code runs — its shell is the one way to execute"]),
+    ...(capabilities.execution.includes("js") ? [] : ["no code runs, its shell is the one way to execute"]),
     ...(capabilities.effort ? [] : ["no effort control"]),
     ...(capabilities.commands ? [] : ["no slash commands"]),
     ...(capabilities.terminals ? [] : ["no terminal panel"]),
@@ -501,6 +577,18 @@ export const limitationsOf = (capabilities: AgentCapabilities): string[] => [
      * mechanism, because that is the thing they wrote and the thing that will or will not be in force. */
     ...(capabilities.instructions === "append" ? ["your system prompt is added to theirs, not replacing it"] : []),
     ...(capabilities.instructions === "none" ? ["your system prompt isn't applied"] : []),
+    /* THE TWO SAFETY AXES, phrased as what the OWNER loses rather than as which seam is missing, because both
+     * describe something they configured on a settings page and would otherwise assume was in force everywhere.
+     *
+     * "hooks" and "masked" are the ceiling and disclose nothing. The "approval" middle answer discloses the one
+     * thing that genuinely differs from a hook: the vendor picks which calls it asks about, so a rule can only
+     * reach what it chose to raise. */
+    ...(capabilities.rulebook === "approval" ? ["your command rules apply only to calls this agent asks about"] : []),
+    ...(capabilities.rulebook === "refuse-only"
+        ? ["your command rules can stop a command here but not pause to ask: a rule set to hold refuses instead"]
+        : []),
+    ...(capabilities.rulebook === "none" ? ["your command rules aren't applied"] : []),
+    ...(capabilities.secrets === "none" ? ["stored secrets reach the model unmasked, and `{{secret:name}}` isn't substituted"] : []),
 ];
 
 // Claude's compile-time model floor, shared by the daemon's catalog (claude-models.ts, its last rung, reached

package/src/agent-run-model.test.ts

@@ -3,7 +3,7 @@ import { resolveAgentRunModels } from "./agent-run-model.js";
 import type { QuickModelSource } from "./quick-model.js";
 
 /* Which model a run somebody's BUTTON started opens on. The rule answers the same two surfaces its quick-model
- * sibling does — the daemon walks it, the settings row names it — so what these pin is the pair of properties
+ * sibling does: the daemon walks it, the settings row names it, so what these pin is the pair of properties
  * that separate the two: an account this sandbox cannot reach never sits at the head of the chain, and an empty
  * answer stays empty rather than being filled in with a tier nobody chose. */
 
@@ -13,7 +13,7 @@ const GOOGLE: QuickModelSource = { provider: `gemini`, ready: true, models: [`ge
 
 const offline = (source: QuickModelSource): QuickModelSource => ({ ...source, ready: false });
 
-test("keeps the user's own order — this list is read, never ranked", () => {
+test("keeps the user's own order, this list is read, never ranked", () => {
     // The opposite of the quick chain, which sorts by tier and cost. Here the order IS the setting: someone who
     // put Opus above GPT wants Opus first, and a resolver that knew better would spend the wrong account.
     expect(resolveAgentRunModels([CLAUDE, CODEX], [`codex:gpt-5.6`, `claude:claude-opus-5`])).toEqual([
@@ -30,7 +30,7 @@ test("steps over a provider this sandbox has no credential for", () => {
     ]);
 });
 
-test("resolves to nothing when no pin is reachable — it does NOT fall back to whatever is connected", () => {
+test("resolves to nothing when no pin is reachable: it does NOT fall back to whatever is connected", () => {
     // The deliberate difference from resolveQuickModels, which lands on its Auto ladder here. An agent run is
     // billed in whole sessions, so an unreachable list hands the choice back to the caller's floor (the user's
     // own composer pick) rather than spending an account they never pointed at.

package/src/capability-ledger.test.ts

@@ -1,16 +1,16 @@
 import { describe, expect, it } from "vitest";
 import { type AgentCapabilities, capabilitiesOf, limitationsOf } from "./agent-catalog.js";
 
-/* THE CAPABILITY LEDGER — which claims in the record are backed by machinery, and which by prose.
+/* THE CAPABILITY LEDGER, which claims in the record are backed by machinery, and which by prose.
  *
  * agent-catalog.test.ts asks two other questions: does every provider/harness pair HAVE a row, and does every
  * axis a record can lack have words for it. A row can pass both and still be a lie. The ability is declared,
- * the sentence renders in the picker's footer, and nothing anywhere behaves differently — so the day the
+ * the sentence renders in the picker's footer, and nothing anywhere behaves differently, so the day the
  * runtime gains the ability (or loses it), the declaration keeps its old value and the footer keeps telling the
  * user something that stopped being true. Over-promising is the direction that hurts: told a runtime can be
  * steered, someone types a mid-turn correction into a queue that does not exist.
  *
- * The record's header already states the rule — "a capability is listed here only if something READS it". This
+ * The record's header already states the rule: "a capability is listed here only if something READS it". This
  * is the rule with teeth. Every field is ENFORCED (a seam opens or closes on it, and the entry cites where) or
  * DESCRIPTIVE (it gates nothing; its whole job is that one sentence). `Record<keyof AgentCapabilities, …>`
  * makes the split exhaustive at COMPILE time: a field added to the interface without an entry here does not
@@ -19,7 +19,7 @@ import { type AgentCapabilities, capabilitiesOf, limitationsOf } from "./agent-c
  *
  * WHAT THIS DOES NOT DO, deliberately: prove an ENFORCED gate exists. Those gates live in the daemon and the
  * web, which sit ABOVE this package and must not be imported back into it. So an enforced entry's citation is a
- * comment a reader checks, and the honest reading is "someone verified this once" — not "CI verifies it". The
+ * comment a reader checks, and the honest reading is "someone verified this once", not "CI verifies it". The
  * descriptive half IS machine-checked below, because it can be: those claims reach the user through
  * `limitationsOf`, which is right here.
  *
@@ -31,7 +31,7 @@ const LEDGER: Record<keyof AgentCapabilities, Backing> = {
     // adapter-registry.ts maps runtime → the adapter that serves the turn; getting it wrong runs the turn on
     // the wrong loop entirely. Also keys the daemon's per-runtime health probes (useSandboxVersion.ts).
     runtime: "enforced",
-    // conversation.ts's `steerable` — the composer offers mid-turn injection only where there is a queue.
+    // conversation.ts's `steerable`: the composer offers mid-turn injection only where there is a queue.
     steering: "enforced",
     // turn-plan.ts forwards `permissionMode` only under "modes" (bar plan); modesFor/clampMode build the
     // composer's mode list from it, so a plan-only runtime is offered two postures rather than four names.
@@ -47,27 +47,40 @@ const LEDGER: Record<keyof AgentCapabilities, Backing> = {
     // turn-plan.ts tells a "cwd" turn where its worktree is, because an absolute /work path still reaches the
     // shared checkout there. Under "namespace" the mount does it and the note would be noise.
     isolation: "enforced",
-    /* system-prompt.ts composes a turn's standing instructions AGAINST this value — a replacement where one may
+    /* system-prompt.ts composes a turn's standing instructions AGAINST this value: a replacement where one may
      * be sent, an addition where only that is possible, and the user-message door for the persona note where
-     * there is no system seam at all — and each adapter reads the field the composition set (codex-agent.ts's
+     * there is no system seam at all, and each adapter reads the field the composition set (codex-agent.ts's
      * two config keys, grok-agent.ts's per-message `system`). It is also the one axis whose absence was the bug
      * that produced it: before the field existed, every runtime was composed for as though it were the Claude
      * Code loop, and five of the six silently dropped the owner's prompt. */
     instructions: "enforced",
     // turn-plan.ts (honoured) plans the JS backend only where "js" is declared, so a runtime without it is
-    // handed no `jsExecution` and mounts no Code tool — the same drop-what-you-can't-honour rule as `effort`.
+    // handed no `jsExecution` and mounts no Code tool: the same drop-what-you-can't-honour rule as `effort`.
     execution: "enforced",
+    /* turn-plan.ts (honoured) carries this onto every request and guard/turn-gate.ts DERIVES the gate's shape
+     * from it: "none" gets no consult and a permanently-set taint bit, "refuse-only" cannot park so a hold
+     * refuses, the other two park on a card. So a row that lies about itself changes how its turns behave.
+     * It also decides whether Codex is asked to raise approvals at all (codex-agent.ts threadOptions). */
+    rulebook: "enforced",
 
-    /* DESCRIPTIVE — true of the runtime, and nothing consults them. Each describes behaviour that is emergent
+    /* DESCRIPTIVE: true of the runtime, and nothing consults them. Each describes behaviour that is emergent
      * rather than gated: an agent that never emits `question` frames simply never asks, one that publishes no
      * commands leaves the `/` popover empty. Nothing has to switch off, which is why nothing does. That also
      * means the declaration and the behaviour are two independent facts, and only the reader below keeps them
      * from disagreeing in the one place a user can see. Wiring one up (hiding the terminal tab, skipping
-     * auto-resume) moves it to ENFORCED — in the change that wires it. */
+     * auto-resume) moves it to ENFORCED: in the change that wires it. */
     questions: "descriptive",
     commands: "descriptive",
     terminals: "descriptive",
     recovery: "descriptive",
+    /* DESCRIPTIVE, and the one entry here whose gap cannot be closed by wiring. Masking a stored credential in
+     * what the model READS needs a seam that edits a tool result before the model sees it, and only the Claude
+     * Code loop has one (a PostToolUse hook). Every other runtime runs its tools inside the VENDOR'S loop: the
+     * model has read the result before the daemon sees any frame about it. So nothing consults this field, and
+     * nothing can: it exists so limitationsOf can say out loud what is true, instead of letting an owner who
+     * stored a credential assume it is hidden everywhere. Moving it to ENFORCED would take a runtime that
+     * publishes a result-rewriting seam, not a change here. */
+    secrets: "descriptive",
 };
 
 // The full ceiling: every ability real, so `limitationsOf` has nothing to say about it. Read from the catalog
@@ -86,25 +99,31 @@ it("classifies exactly the fields a live record carries", () => {
 /* A DESCRIPTIVE field earns its place by reaching the user, since by definition it does nothing else. Checked
  * per field rather than by counting sentences: an aggregate is satisfied by one axis contributing two lines
  * while another contributes none, which is exactly the case worth catching. Anything that survives here without
- * a sentence is decoration, and the fix is to delete the field or wire it up — not to add an exemption. */
+ * a sentence is decoration, and the fix is to delete the field or wire it up, not to add an exemption. */
 describe("a descriptive claim reaches the user", () => {
     it("has something to disclose against: the ceiling discloses nothing", () => {
         expect(limitationsOf(CEILING)).toEqual([]);
     });
 
+    /* What "lacking this axis" MEANS for a field that is not a boolean. A boolean diminishes to false; anything
+     * else has to name its own floor here, because only the axis knows which of its values is the weak one.
+     * Adding a non-boolean descriptive field without an entry fails below rather than silently testing nothing. */
+    const DIMINISHED: Partial<Record<keyof AgentCapabilities, unknown>> = { secrets: "none" };
+
     it.each(fieldsWhere("descriptive"))("%s puts its own sentence in the picker when the runtime lacks it", (field) => {
-        expect(typeof CEILING[field], `${field} is descriptive but not a boolean — teach the flip below how to diminish it`).toBe("boolean");
+        const floor = typeof CEILING[field] === "boolean" ? false : DIMINISHED[field];
+        expect(floor, `${field} is descriptive and not a boolean: add its weakest value to DIMINISHED above`).toBeDefined();
 
-        const lacking: AgentCapabilities = { ...CEILING, [field]: false };
+        const lacking: AgentCapabilities = { ...CEILING, [field]: floor };
 
         expect(limitationsOf(lacking)).toHaveLength(1);
     });
 });
 
 /* The ledger is a split, not a label: a set that swallowed everything would typecheck and prove nothing. Both
- * sides being occupied is what makes reading an entry informative — and if the descriptive side ever empties
+ * sides being occupied is what makes reading an entry informative, and if the descriptive side ever empties
  * because every axis got wired up, that is a real event, and deleting this file is the right response to it. */
-it("is a real split — neither side is empty", () => {
+it("is a real split: neither side is empty", () => {
     expect(fieldsWhere("enforced").length).toBeGreaterThan(0);
     expect(fieldsWhere("descriptive").length).toBeGreaterThan(0);
 });

package/src/chores/chores.test.ts

@@ -16,7 +16,7 @@ describe(`the chore book's order`, () => {
     });
 
     it(`keeps every chore in the book`, () => {
-        // The sort cannot drop an entry — but a future refactor to a filter-into-groups could, so the count is
+        // The sort cannot drop an entry, but a future refactor to a filter-into-groups could, so the count is
         // pinned to the ids rather than to a number, which says which one went missing.
         expect(new Set(CHORES.map((chore) => chore.id)).size).toBe(CHORES.length);
         expect(CHORES.length).toBe(17);