@intentic/sandbox-contract 1.242.0 → 1.244.0

package/src/events.ts

@@ -4,6 +4,7 @@ import { AgentSummarySchema, LandConflictSchema } from "./schemas/agents.js";
 import { RateLimitInfoSchema } from "./schemas/claude-gate.js";
 import { FastModeStateSchema } from "./schemas/fast-mode.js";
 import { AccountUsageSchema, AgentReplySchema, ProviderRefusalSchema, UsageWindowSchema } from "./schemas/plan-limits.js";
+import { CredentialGateKindSchema, CredentialGateScopeSchema, CredentialLaneSchema } from "./schemas/secrets.js";
 import { ShareDetailSchema } from "./schemas/share.js";
 import { MemberRoleSchema } from "./schemas/shared.js";
 import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "./schemas/terminal.js";
@@ -35,10 +36,16 @@ export type AskQuestion = z.infer<typeof AskQuestionSchema>;
  * card with no way to know it was holding four hundred characters of shell: it rendered them as a paragraph,
  * wrapped mid-flag, and the fragment that caused the hold was somewhere in the middle of it.
  *
- * `spans` is the gate's own evidence, computed by the classifier at the moment the rule fired (contract's
+ * `spans` is where the pattern match fired, computed by the classifier at the moment it did (contract's
  * command-classes.ts, matchCommand) and carried rather than re-derived: a browser that re-ran the patterns
- * would be a second classifier, and the day the two disagreed the card would be marking a fragment that is not
- * the one anybody was held for. Offsets are into `text` AFTER truncation, so they are always paintable.
+ * would be a second classifier, and the day the two disagreed the card would be marking a fragment the daemon
+ * never saw. Offsets are into `text` AFTER truncation, so they are always paintable.
+ *
+ * IT IS NOT A CLAIM ABOUT WHY THE CARD EXISTS, and the card no longer presents it as one. The reason is the
+ * judge's sentence in the title; these are the fragments TRIAGE noticed, all of the matched classes' rather
+ * than whichever sorts first — the card used to show one class's and label them "Stopped for", so a command
+ * that cleaned a build directory on its way to publishing offered `rm -rf …` as its reason under a sentence
+ * about npm. Under the hard rule the title DOES name a class, so there the marks are that class's alone.
  *
  * `language` is a Shiki grammar id, and the two are the two execution backends the gate reads (command-gate's
  * EXECUTION_SOURCES): a shell line and a script. */
@@ -52,7 +59,9 @@ export const ProgramAskSchema = z.object({
         ),
     spans: z
         .array(z.object({ start: z.number().int().nonnegative(), end: z.number().int().nonnegative() }))
-        .describe("Which fragments of the text put it in the class that held it. Offsets into text, in order, never overlapping."),
+        .describe(
+            "Which fragments of the text the pattern match fired on: every matched class's, or, under the hard rule, only the class the title names. Offsets into text, in order, never overlapping.",
+        ),
 });
 export type ProgramAsk = z.infer<typeof ProgramAskSchema>;
 
@@ -80,16 +89,20 @@ export const PermissionAskSchema = z.object({
     program: ProgramAskSchema.optional().describe(
         "The program this card is holding, when the card is about one. Present on a command gate's card and absent on every other permission ask.",
     ),
-    /* THE JUDGE'S OWN SENTENCE, and on a command card it is the reason the card exists rather than a note added
-     * to it: the judge read the owner's policy and the program and decided this needed asking, and this is what
-     * it decided. Written by the quick model from the program text and the policy, never by the agent being
-     * gated — a card whose persuasive half was authored by the thing it is stopping argues for its own approval,
-     * and the turns that raise cards are exactly the ones whose account of themselves may be a stranger's. */
+    /* THE JUDGE'S OWN SENTENCE, WHERE THE TITLE IS SOMEBODY ELSE'S. On an ordinary command card the sentence IS
+     * the title (the judge read the owner's policy and the program, and its account of why this needs asking is
+     * the only account there is), so this is left off rather than printing the same words twice. It carries the
+     * sentence on the two cards whose title says something the sentence cannot: the hard rule's, which names the
+     * consequence that stopped it, and a machine command's, which names the computer.
+     *
+     * Written by the quick model from the program text and the policy, never by the agent being gated — a card
+     * whose persuasive half was authored by the thing it is stopping argues for its own approval, and the turns
+     * that raise cards are exactly the ones whose account of themselves may be a stranger's. */
     explain: z
         .string()
         .optional()
         .describe(
-            "One plain sentence saying what the program does and why it is being asked about. Written by the judge that read your safety policy, never by the agent being gated.",
+            "One plain sentence saying what the program does and why it is being asked about, where the title says something else. Written by the judge that read your safety policy, never by the agent being gated.",
         ),
 });
 export type PermissionAsk = z.infer<typeof PermissionAskSchema>;
@@ -209,6 +222,39 @@ export const PaymentOfferSchema = z.object({
 });
 export type PaymentOffer = z.infer<typeof PaymentOfferSchema>;
 
+/* ONE GATED CREDENTIAL, ASKED FOR, the card the daemon raises when the agent reaches for a secret or a
+ * connected account the owner put behind a named person (secrets/credential-gate.ts).
+ *
+ * Every field but `why` is the daemon's own: the subject and its approvers come off the gate policy the owner
+ * wrote (which lives off the workspace, where the agent cannot edit it), the lane and detail come from the
+ * exit that was about to spend the credential, and the scope is the policy's, not the asker's. The model
+ * contributes one line of rationale and nothing else, which is what makes the card impossible to
+ * misrepresent: a prompt-injected turn can ask for the production password and cannot make the card say it is
+ * asking for the staging one.
+ *
+ * THE APPROVERS ARE ON THE CARD because the card is not addressed to "the owner" the way every other offer
+ * here is — it is addressed to a LIST, the server checks the clicker's verified identity against it, and a
+ * click from anybody else is refused with the card left standing. So the names have to be visible: a card
+ * whose buttons do nothing for the person looking at it must say who it is waiting for. */
+export const CredentialOfferSchema = z.object({
+    // The gate's subject: a secret's reference name (`DATABASE_URL`) or a capability id (`reddit`).
+    subject: z.string().describe("Which credential is being asked for."),
+    kind: CredentialGateKindSchema,
+    lane: CredentialLaneSchema,
+    // Where it would go, in the reader's terms: the head of the agent's command line, the page's host, or the
+    // capability's own name. Reference-form by construction on the secret lanes (resolution is what fires the
+    // ask), so this can be shown without leaking anything.
+    detail: z
+        .string()
+        .optional()
+        .describe("Where it would go: the start of the command, the site, or what is being mounted. Never a value: the command still reads as a reference at this point."),
+    // The agent's one-line case, the only prose on the card that is the model's.
+    why: z.string().optional().describe("The agent's case for using it, and the only words on this card that are the agent's."),
+    approvers: z.array(z.string()).describe("Who may release it. A click from anyone else is refused and leaves the card standing."),
+    scope: CredentialGateScopeSchema,
+});
+export type CredentialOffer = z.infer<typeof CredentialOfferSchema>;
+
 // One provider-advertised slash command, an ACP agent's available_commands entry, or a Claude Code session's
 // supportedCommands() (its built-ins plus the workspace's own .claude/commands and any plugin/skill commands).
 // `hint` is the argument placeholder the popover shows after the name.
@@ -360,6 +406,7 @@ const terminalHelpCard = {
 const serviceOfferCard = { requestId: z.string(), offer: ServiceOfferSchema };
 const capabilityOfferCard = { requestId: z.string(), offer: CapabilityOfferSchema };
 const paymentOfferCard = { requestId: z.string(), offer: PaymentOfferSchema };
+const credentialOfferCard = { requestId: z.string(), offer: CredentialOfferSchema };
 
 /* HOW AN OFFER'S ACCEPTED HALF ENDED, the follow-up that lands on the card after the click. Each is the body of
  * the frame that reports it (`service_receipt`, `capability_outcome`, `payment_receipt`) and the field the
@@ -382,6 +429,15 @@ export const PaymentReceiptSchema = z.object({
     network: z.string().optional(),
 });
 export type PaymentReceipt = z.infer<typeof PaymentReceiptSchema>;
+/* WHO RELEASED A GATED CREDENTIAL, or that a person refused it. `released` carries the approver's own address,
+ * read off the VERIFIED identity on the reply rather than off anything the click claimed, which is what makes
+ * the row an audit line rather than a rendering. There is no receipt for a card nobody answered: `resolved`
+ * already says so, and inventing "refused" for a deadline would put words in a person's mouth. */
+export const CredentialReceiptSchema = z.object({
+    outcome: z.enum(["released", "refused"]),
+    approvedBy: z.string().optional(),
+});
+export type CredentialReceipt = z.infer<typeof CredentialReceiptSchema>;
 
 /* THE THREE RESTORABLE CARDS, named so the turn journal can hold them verbatim: a parked turn's raised cards
  * are written down beside its prompt (sandbox turn-journal.ts), and a daemon death under the park restores the
@@ -468,6 +524,12 @@ export const TranscriptPaymentOfferSchema = z.object({
     receipt: PaymentReceiptSchema.optional().describe("How the approved payment ended (the payment_receipt frame)."),
 });
 export type TranscriptPaymentOffer = z.infer<typeof TranscriptPaymentOfferSchema>;
+export const TranscriptCredentialOfferSchema = z.object({
+    ...credentialOfferCard,
+    status: OfferStatusSchema.describe("Where the decision stands."),
+    receipt: CredentialReceiptSchema.optional().describe("Who released it, or that somebody refused (the credential_receipt frame)."),
+});
+export type TranscriptCredentialOffer = z.infer<typeof TranscriptCredentialOfferSchema>;
 
 // ---- transcript rows ----
 // What a conversation is made of, on every surface: the rows the daemon folds a turn's frames into as they
@@ -664,13 +726,26 @@ export const TranscriptRowSchema = z.object({
     serviceOffer: TranscriptServiceOfferSchema.optional().describe("The priced service run this row offered, the decision, and the receipt."),
     capabilityOffer: TranscriptCapabilityOfferSchema.optional().describe("The capability setup this row asked for, the decision, and the outcome."),
     paymentOffer: TranscriptPaymentOfferSchema.optional().describe("The payment this row asked for, the decision, and the receipt."),
+    credentialOffer: TranscriptCredentialOfferSchema.optional().describe(
+        "The gated credential this row asked to use, who may release it, and who did.",
+    ),
 });
 export type TranscriptRow = z.infer<typeof TranscriptRowSchema>;
 
 /* THE CARD FIELDS A ROW CAN CARRY, as one list, for every reader that has to ask "does this row hold a card":
  * the fold that counts a card-only bubble as a row, the chat's row count (a branch is cut by it), and the
  * surfaces that draw whichever card a bubble is waiting on. */
-export const CARD_FIELDS = ["plan", "question", "permission", "browserHelp", "terminalHelp", "serviceOffer", "capabilityOffer", "paymentOffer"] as const;
+export const CARD_FIELDS = [
+    "plan",
+    "question",
+    "permission",
+    "browserHelp",
+    "terminalHelp",
+    "serviceOffer",
+    "capabilityOffer",
+    "paymentOffer",
+    "credentialOffer",
+] as const;
 export type CardField = (typeof CARD_FIELDS)[number];
 export type TranscriptCards = Pick<TranscriptRow, CardField>;
 // Whether a row holds a card at all, answered or not.
@@ -1164,6 +1239,20 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
      * case the signed authorization expires unused and NOTHING left the wallet. A skip needs no receipt,
      * nothing moved, and `resolved` already says so. */
     PaymentReceiptSchema.extend({ kind: z.literal("payment_receipt"), requestId: z.string() }),
+    /* A GATED CREDENTIAL awaiting a NAMED person's click, the one card on this stream that is not addressed to
+     * the owner: the daemon holds an exit (a `{{secret:…}}` about to resolve, a browser field about to be
+     * typed into, a connected account about to be mounted) parked until one of the gate's approvers releases
+     * it (secrets/credential-gate.ts). Raised OUTSIDE the turn generator like the offers above — the exits run
+     * inside a PreToolUse hook and inside the daemon's own `secrets request` route — so it is not journalled
+     * for restore: its waiter is a held hook or a held connection, both of which die with the daemon, and the
+     * next use after a restart simply asks again. Settles through the same `POST /agent/reply`, which is where
+     * the clicker's identity is checked against `offer.approvers`. */
+    z.object({ kind: z.literal("credential_offer"), ...credentialOfferCard }),
+    /* WHO RELEASED IT, pushed the moment a person decided, so the settled card names them rather than saying
+     * only that something was approved: `released` with the approver's verified address, or `refused` when a
+     * person said no. Nothing is pushed for a card nobody answered — `resolved` already says that, and a
+     * deadline is not a refusal by anybody. */
+    CredentialReceiptSchema.extend({ kind: z.literal("credential_receipt"), requestId: z.string() }),
     // The card above named by `requestId` is released, the user answered (or dismissed it, or the turn was
     // stopped out from under it), so the turn is executing again. Emitted by whoever parked, the moment its
     // waiter settles, because the park's END is otherwise invisible on this stream: nothing else here says

package/src/plan-pools.ts

@@ -13,6 +13,16 @@ import type { AccountUsage, UsageWindow, WindowGates } from "./schemas/plan-limi
  * chosen a model yet is asking. Pools gated to `none` are left out of that too: a code-review limit is the
  * account's to see, never the thing that decides whether a chat turn can run. */
 
+/* WHEN A POOL HAS NOTHING LEFT IN IT, on the wire's own scale, read the same way by both sides.
+ *
+ * 100, and deliberately not the browser's 90 (usageStatus' SPENT_PERCENT): the two thresholds answer different
+ * questions. 90 is a WARNING — the point at which a surface stops recommending an account for a long turn, and
+ * what the rings and the bands take their red from. This is EXHAUSTION: the point past which a call is certain
+ * to be refused, which is what the daemon needs before it steers a turn elsewhere and the only line a list of
+ * offers may hide an account behind. A subscription with a tenth of its week left can still run the next task,
+ * and dropping it off a rail titled "Ready to run" answers the reader's question with the wrong one. */
+export const SPENT_UTILIZATION = 100;
+
 export interface ModelRef {
     // The wire id ("claude-opus-4-6", "gemini-3-pro").
     readonly id: string;

package/src/safety-policy.ts

@@ -46,6 +46,29 @@ import type { CommandClass } from "./schemas/agent.js";
  * set shrinks to block devices when that lands. */
 export const HARD_RULE_CLASSES: ReadonlySet<CommandClass> = new Set<CommandClass>(["system.destructive"]);
 
+/* WHETHER THE JUDGE RUNS AT ALL, and whether its answer is allowed to stop anything. The owner's switch over
+ * everything below, and the reason it exists is that a tier which spends a model call and can interrupt you is a
+ * tier somebody is entitled to decline — the old rulebook could be set to allow everything, and losing that when
+ * the judge arrived made the redesign a thing you could only opt further INTO.
+ *
+ * THREE STATES, and the middle one is the one worth arguing for. Nobody trusts a judge they have not watched,
+ * and the only evidence that it asks about the right things is a log of what it decided while it could not
+ * interrupt them. Same shape, and the same reasoning, as the tier judge's own Measure state (settings.autoTier).
+ *
+ *   off    nothing is judged. No model call, no cards, nothing written to the log. Triage still runs, because
+ *          the hard rule below is built on it and costs nothing.
+ *   watch  the judge runs on every triage hit and every verdict is recorded, and NOTHING is ever held: an `ask`
+ *          is logged as an ask and the command runs anyway. What it costs is one model call per triage hit;
+ *          what it buys is the Recent decisions list, read against a policy nobody has tested yet.
+ *   on     the verdict decides, which is the behaviour this design describes everywhere else.
+ *
+ * THE HARD RULE IS NOT UNDER THIS SWITCH, at any setting. HARD_RULE_CLASSES is a typed verdict rather than a
+ * judgment, it never needed a model, and the Safety page promises in as many words that it cannot be edited
+ * away. So `off` and `watch` still raise a card for wiping a block device or deleting under /history — with a
+ * sentence saying the judge did not weigh in, rather than one pretending it did. */
+export const CommandJudgeModeSchema = z.enum(["off", "watch", "on"]);
+export type CommandJudgeMode = z.infer<typeof CommandJudgeModeSchema>;
+
 /* WHAT THE JUDGE ANSWERS. Three verdicts, and each is a different instruction to the gate:
  *
  *   allow   run it, say nothing, nobody is interrupted. The ordinary answer for a triage false positive,

package/src/schemas/agents.ts

@@ -86,6 +86,12 @@ export const AgentAttentionSchema = z.object({
     // A missing capability parked on the owner's setup (capabilities/capability-offer.ts), the agent is
     // waiting for something to be connected, so the lane can say "setup needed" rather than a generic pause.
     capability: z.boolean().describe("It needs something connected that is not connected yet."),
+    // A gated credential parked on a NAMED person's click (secrets/credential-gate.ts). Its own lane because
+    // it is the one pause the person reading the board may not be able to clear: every other card here waits
+    // for whoever is looking at it, this one waits for the specific people the gate names.
+    credential: z
+        .boolean()
+        .describe("It is waiting for a named person to release a credential. The one pause that may not be yours to clear, whatever your role."),
     conflict: z.boolean().describe("Its work cannot be merged without somebody resolving a clash."),
 });
 export type AgentAttention = z.infer<typeof AgentAttentionSchema>;

package/src/schemas/computers.ts

@@ -244,6 +244,12 @@ export type MachinePort = z.infer<typeof MachinePortSchema>;
 export const MachineWatcherSchema = z.object({
     running: z.boolean(),
     pid: z.number().int().optional(),
+    /* WHICH BUILD IS ACTUALLY SERVING, stamped into the pidfile by the loop that claimed it, which is the only
+     * place the fact exists: replacing the binary does not touch the running process, so a machine can hold a
+     * current agent and go on serving a months-old one indefinitely. `agents.sync` is the file, this is the
+     * process, and the two differing is a restart somebody is owed (see watcherBuildSkew). Absent when no loop
+     * is running, and when the one running predates the stamp. */
+    build: z.string().optional(),
     /* When the watcher last FINISHED a pass, the field that makes `running` mean something. The agent holds its
      * SSH transport listeners on its own event loop, so a failure that escapes the loop leaves a process that is
      * alive and a loop that is gone: pid present, unit "active", mirroring and the git bridge stopped. Absent
@@ -268,10 +274,18 @@ export const MachineReportSchema = z.object({
      * the same box, so it is what dedupes them into a single row. */
     hostname: z.string(),
     os: z.string(),
-    // Which of this machine's agents are installed, and at what version, a machine running an old build is
-    // visible rather than mysteriously lacking a field. Same argument as HostSummary.version. `host` is filled
-    // by the daemon at merge time (it already knows it from the socket), not by the sync agent, which would have
-    // to go reading another agent's config to guess at it.
+    /* Which agents this machine has, and at what version, so one on an old build is visible rather than
+     * mysteriously lacking a field. Same argument as HostSummary.version.
+     *
+     * `sync` is the agent INSTALLED here — the file on disk — and `watcher.build` beside it is the loop running
+     * from that file. It used to be neither: whichever process happened to build the report stamped its own
+     * version here, so the same machine answered its running build to a sandbox its loop posted to and its
+     * installed build to one that ran `status --json` over a host capability. One field, two meanings, and the
+     * gap between them — a machine updated but never restarted — invisible in both.
+     *
+     * `host` is what the live socket announced (so: what is running), filled by the daemon at merge time from
+     * the hello frame it already holds, never by the sync agent, which would have to go reading another agent's
+     * config to guess at it. */
     agents: z.object({ sync: z.string().optional(), host: z.string().optional() }),
     // Filled by the READER, never the agent (see above). Empty is the resting state: no Docker on the machine,
     // or nothing has looked. Neither is an error, and neither means "no sandboxes exist".
@@ -284,6 +298,27 @@ export const MachineReportSchema = z.object({
     capturedAt: z.number(),
 });
 export type MachineReport = z.infer<typeof MachineReportSchema>;
+
+/* THE AGENT THIS MACHINE INSTALLED AND THE ONE IT IS RUNNING, when they are not the same build — the whole of
+ * "you updated the agent and nothing changed", as a value.
+ *
+ * It is one comparison, and it lives HERE for the same reason watcherStalled does: the terminal (`intentic-machine
+ * status`) and the browser (the Computers row) both answer this question, and a machine that is behind in one and
+ * fine in the other is worse than either answer alone. The remedy is the same in both: restart the loop.
+ *
+ * Silent whenever either half is unknown, which covers a loop that is stopped (nothing is serving, and the row
+ * already says so in louder words), an agent too old to stamp its build, and a machine with no installed agent to
+ * compare against — none of which is a skew, and each of which would otherwise nag about a difference nobody can
+ * act on. */
+export const watcherBuildSkew = (report: MachineReport): { readonly running: string; readonly installed: string } | undefined => {
+    const running = report.watcher.build;
+    const installed = report.agents.sync;
+    if (!report.watcher.running || running === undefined || installed === undefined || running === installed) {
+        return undefined;
+    }
+    return { running, installed };
+};
+
 // Why a computer that is plainly THERE has no report to show. Each is a different errand for the reader, which is
 // the whole reason they are not collapsed into one "unavailable".
 export const ComputerGapSchema = z.enum([

package/src/schemas/engines.ts

@@ -82,6 +82,7 @@ export const EngineRowSchema = z.object({
     previous: z.string().optional().describe("The version kept one step back, which is what going back means."),
     quarantined: z.array(EngineQuarantineSchema).describe("Versions the store installed and then refused, with the reason."),
     diskBytes: z.number().int().nonnegative().describe("What this engine's kept versions cost on the daemon's volume."),
+    installing: z.boolean().optional().describe("Whether this engine is currently being installed in the background."),
 });
 export type EngineRow = z.infer<typeof EngineRowSchema>;
 

package/src/schemas/plan-limits.ts

@@ -259,6 +259,25 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
             .boolean()
             .describe("Yes releases exactly one payment. Anything else spends nothing. This click is the only way the money can move."),
     }),
+    /* A GATED CREDENTIAL's release, and the one reply on this list whose sender is CHECKED. Every other card
+     * here is answered by whoever holds a session, because every other card is the owner's to decide; this one
+     * is addressed to a named list, so the daemon reads the verified identity off the request and refuses a
+     * click from anybody else with the card left standing for whoever can answer it. The refusal covers `no`
+     * as well: a stranger may not skip a release on the approver's behalf either, or the gate would be a
+     * denial-of-service anybody with a session could aim at a turn.
+     *
+     * `approve` carries no qualifiers because the gate's own policy decides how far one yes goes: a per-use
+     * gate releases exactly this use and the next one asks again, a conversation-scoped gate covers the rest
+     * of the conversation. The card says which, so the click is never wider than it reads. */
+    z.object({
+        kind: z.literal("credential_offer").describe("Releasing a credential the agent may only use once a named person says so."),
+        requestId: z.string().min(1).describe("Which card you are answering."),
+        approve: z
+            .boolean()
+            .describe(
+                "Yes releases it, as far as the card says (this one use, or the rest of the conversation). Only the people the card names can answer at all, yes or no.",
+            ),
+    }),
 ]);
 export type AgentReply = z.infer<typeof AgentReplySchema>;
 // Steering: a user message delivered INTO the running turn (injected between tool calls, Claude Code style),

package/src/schemas/secrets.ts

@@ -16,6 +16,102 @@ export const SecretKeysSchema = z.object({
 });
 export const SecretKeyParamSchema = z.object({ key: z.string().describe("Which secret, by name.") });
 export const SecretRevealSchema = z.object({ value: z.string().describe("The value itself. The only place in this API one is ever returned.") });
+
+/* A CREDENTIAL THE AGENT MAY NOT USE UNTIL A NAMED PERSON SAYS SO, and who that person is.
+ *
+ * Masking already answers "can the model SEE this value" (no: it reads a `{{secret:name}}` reference), and
+ * the answer was enough while the only question was disclosure. It is not the whole question. A reference the
+ * model can write is a credential the model can SPEND, at whatever moment its own reasoning arrives at, and
+ * for the small set of credentials where one wrong spend is the incident — the production database's
+ * password, the company X account, the card-shaped connector — the owner wants the moment itself decided by a
+ * person, not the storage of the value. That is what a gate is: not a second lock on the vault, a REQUIRED
+ * CLICK in front of the exit.
+ *
+ * WHAT IT IS NOT A WALL AGAINST. A shell in this container runs as the workspace's owner and the policy file
+ * sits beside the vault it guards; anything that can read one can read the other, and a compromised container
+ * is out of scope here exactly as it is for the vault (SECURITY.md). The gate is a wall against the AGENT's
+ * own judgment being the last word — a prompt-injected model can ask for a release and cannot grant itself
+ * one — and against the ordinary accident of a turn reaching for the live credential when the staging one was
+ * meant.
+ *
+ * THE APPROVERS ARE AN EXACT LIST, not a role floor, and the owner is not on it implicitly. "Only Bob may
+ * release the production password" is the sentence people actually mean, and a floor cannot say it: a floor of
+ * `maintainer` says "anyone senior enough", which is the thing the owner was trying to narrow. So the list is
+ * the list, the owner adds themselves when they mean themselves, and a click from anybody else is refused
+ * server-side with the card left standing for whoever can. */
+export const CredentialGateScopeSchema = z
+    .enum(["use", "conversation"])
+    .describe(
+        "How far one release goes: `use` asks again every single time (one click releases exactly one use), `conversation` covers the rest of this conversation and is forgotten when the daemon restarts.",
+    );
+export type CredentialGateScope = z.infer<typeof CredentialGateScopeSchema>;
+
+// What a gate is ABOUT: one stored secret by its reference name, or one whole connected capability (a
+// connector's env, a browser account's profile, an MCP server) by its id. Two kinds rather than one because
+// they are withheld differently — a secret is refused at the exit it would resolve at, a capability is simply
+// never mounted for the turn — and the subject namespaces are disjoint anyway (env keys are SCREAMING_SNAKE).
+export const CredentialGateKindSchema = z
+    .enum(["secret", "capability"])
+    .describe("Whether this gate covers one stored secret, by the name a reference carries, or one whole connected capability, by its id.");
+export type CredentialGateKind = z.infer<typeof CredentialGateKindSchema>;
+
+/* WHICH EXIT A RELEASE WAS ASKED FOR, so the card can say what is about to happen in the reader's terms
+ * rather than in the daemon's. The three secret exits are the ones the use ledger already names (a shell
+ * command, a JS run's script, a browser keystroke); `session` is a whole capability being mounted for the
+ * turn (a signed-in browser profile, a connector's env, an MCP server), and `otp` is one derived one-time
+ * code off a stored TOTP seed. */
+export const CredentialLaneSchema = z
+    .enum(["shell", "code", "browser", "session", "otp"])
+    .describe("What the credential was about to be used for: a shell command, a script, typing into a page, mounting a connected account, or one one-time code.");
+export type CredentialLane = z.infer<typeof CredentialLaneSchema>;
+
+export const CredentialGateSchema = z.object({
+    // An env/generated KEY (`DATABASE_URL`), or a capability id (`reddit`, `komodo`). A vault name's field
+    // half (`reddit/password`) is deliberately NOT a subject: gating one field of a connected account and not
+    // its neighbours would be a gate with a hole in it, so the whole capability is the unit.
+    subject: z.string().min(1).describe("What is gated: a secret's name, or a connected capability's id."),
+    kind: CredentialGateKindSchema,
+    approvers: z
+        .array(z.string().min(3))
+        .min(1)
+        .describe(
+            "Exactly who may release it, by email, from the people on the Access roster. Not a seniority floor: nobody outside this list can release it, the owner included, unless the owner is on it.",
+        ),
+    scope: CredentialGateScopeSchema,
+});
+export type CredentialGate = z.infer<typeof CredentialGateSchema>;
+
+export const CredentialGatesSchema = z.object({
+    gates: z
+        .array(CredentialGateSchema)
+        .describe("Every gate in force. Names, subjects and approver addresses only: this answer never carries a credential."),
+});
+export type CredentialGates = z.infer<typeof CredentialGatesSchema>;
+
+export const CredentialGateSubjectParamSchema = z.object({
+    subject: z.string().min(1).describe("Which gate, by the secret name or capability id it covers."),
+});
+
+/* THE AGENT'S OWN DOOR, `secrets request <subject> --why "…"`. A gated capability is ABSENT from a turn
+ * rather than refused inside it (its profile is not mounted, its env is not exported), so the model cannot
+ * discover the gate by tripping over it the way a secret reference does — it would conclude the account is
+ * disconnected and go looking for another road. This route is the road: it raises the same card the exits
+ * raise, and a release is worded as a grant for the REST OF THE CONVERSATION, because a session-shaped
+ * credential cannot be handed out for one use. */
+export const CredentialRequestSchema = z.object({
+    subject: z.string().min(1).describe("What to ask for: the secret's name, or the connected capability's id."),
+    why: z.string().max(280).optional().describe("One line on what it is for. The only words on the card that are the agent's."),
+    // Which conversation's chat the card goes up in, filled by the CLI from the turn's own environment, so
+    // the model cannot aim a card at somebody else's conversation.
+    conversationId: z.string().optional().describe("Which conversation to raise the card in. The CLI fills this from the running turn."),
+});
+
+export const CredentialGrantSchema = z.object({
+    granted: z.literal(true).describe("Always true: a refusal is an error with a sentence, never a `false` here."),
+    approvedBy: z.string().describe("Who released it."),
+    message: z.string().describe("What the grant means in practice, and what to do next."),
+});
+
 // One entry per secret the sandbox knows about, across every store: intent env secrets and intentic-generated
 // passwords (from the desired-state repo), capability credentials, and AI-provider accounts. Values never ride
 // this shape, `revealable` says whether `reveal` can return one (everything but provider accounts).
@@ -56,9 +152,23 @@ export const SecretInventoryEntrySchema = z.object({
                 .string()
                 .optional()
                 .describe("Where it went: the start of the command or script, or the site. Names and destinations only, never values."),
+            // Who released it, when a gate made that use somebody's decision. Absent on an ungated use, which
+            // is nearly all of them: the ledger row records a person only where a person was actually asked.
+            approvedBy: z.string().optional().describe("Who released it for that use, when it is gated. Absent when nothing had to be approved."),
         })
         .optional()
         .describe("The last time an agent actually spent this secret. Absent while it never has been, which most never are."),
+    /* THE APPROVAL THIS ENTRY IS BEHIND, joined on from the gate policy so the row can say "needs approval
+     * from Bob" without a second call. Absent on the overwhelming majority of entries: gating is for the few
+     * credentials where one wrong use is the incident, and a sandbox where everything asks is a sandbox where
+     * nobody reads the cards. */
+    gate: z
+        .object({
+            approvers: z.array(z.string()).describe("Who may release it, by email. Nobody else can, whatever their role."),
+            scope: CredentialGateScopeSchema,
+        })
+        .optional()
+        .describe("Who has to release this before the agent can use it, and for how long one release lasts. Absent when it is not gated."),
 });
 export type SecretInventoryEntry = z.infer<typeof SecretInventoryEntrySchema>;
 export const SecretInventorySchema = z.object({

package/src/schemas/settings.ts

@@ -1,5 +1,6 @@
 // settings: per-sandbox agent settings (.intentic/config/settings.json)
 import { z } from "zod";
+import { CommandJudgeModeSchema } from "../safety-policy.js";
 import { AdmissionPolicySchema, AdmissionRuleSchema, AgentRunPinSchema } from "./agent.js";
 // Which prompt the agent is, before this turn composes anything on top. Two built-in bases and an escape
 // hatch: Intentic's own (the default), Claude Code's preset, or the owner's text. Declared out here rather
@@ -715,17 +716,50 @@ export const SandboxSettingsSchema = z.object({
         .record(z.string(), AdmissionRuleSchema)
         .default({})
         .describe("What an agent may do out in the world, per kind of action: go ahead, ask first, or never."),
-    /* THE COMMAND GATE IS NOT CONFIGURED HERE. It used to be: `commandRules` was a verdict per CommandClass and
-     * `explainCommands` decided whether a card carried a sentence. Both are gone, and the reason is the whole
-     * safety redesign (safety-policy.ts argues it): a regex verdict per class asked about `echo "rm -rf /"` and
-     * an actual delete in the same words, and no setting of six switches fixes that, because telling the two
-     * apart is an act of understanding rather than a threshold. What replaced them is the owner's written
-     * policy at .intentic/config/safety.md, read by a judge that also sees what the daemon knows about the turn,
-     * plus one typed hard rule the judge cannot waive. The Safety page edits that document; nothing about the
-     * command gate belongs in this object.
-     *
-     * The sentence on a card is no longer optional either: it is the judge's own reason for the verdict, so a
-     * card without one would be a card that could not say why it exists. */
+    /* NO VERDICT FOR THE COMMAND GATE LIVES HERE, and the two settings that do are about the JUDGE rather than
+     * about what it should decide. `commandRules` used to be a verdict per CommandClass and `explainCommands`
+     * decided whether a card carried a sentence; both are gone, and the reason is the whole safety redesign
+     * (safety-policy.ts argues it). A regex verdict per class asked about `echo "rm -rf /"` and an actual delete
+     * in the same words, and no setting of six switches fixes that, because telling the two apart is an act of
+     * understanding rather than a threshold. What replaced them is the owner's written policy at
+     * .intentic/config/safety.md, read by a judge that also sees what the daemon knows about the turn, plus one
+     * typed hard rule the judge cannot waive. The Safety page edits that document; what a command may DO is
+     * settled there and nowhere in this object.
+     *
+     * WHETHER THE JUDGE RUNS AT ALL is a different question, and one this object has to answer, because it is
+     * the only tier of the design that spends money and interrupts people. An owner who does not want either is
+     * entitled to say so, and before this they could not: the old rulebook could be set to allow everything, and
+     * the redesign quietly made itself the one part of the sandbox you could only opt further into.
+     *
+     * Judged commands are also the one automatic job whose model choice genuinely differs from the rest of
+     * `quickModel`'s work, which is why the list below exists rather than a line in the comment above it: a
+     * commit message written by a model that misread the diff is a sentence somebody edits, and a verdict
+     * written by a model that misread a command is a card that should not have been raised or, worse, one that
+     * should have been. */
+    commandJudge: CommandJudgeModeSchema.default("on").describe(
+        "Whether a model reads your safety policy before a flagged command runs. Off judges nothing and asks about nothing; Watch judges everything and records it without ever interrupting you, which is how you find out what your policy actually does before you let it stop anything; On lets the verdict decide. Wiping a disk or deleting under /history asks at every setting — that rule is typed rather than judged, and cannot be turned off.",
+    ),
+    /* WHICH MODEL READS THE POLICY, an ordered list of `${provider}:${modelId}` keys (quickModelKey) walked top
+     * to bottom, or EMPTY for whatever the quick model would be.
+     *
+     * A LIST, for the reason every other model setting here is one: the head runs out and the whole feature goes
+     * with it. Falling back to the quick chain rather than to Auto is deliberate — it is what this did before the
+     * setting existed, so an owner who never opens the row keeps exactly the behaviour they had, and one who
+     * writes an entry is saying that command verdicts are worth a different model than commit messages.
+     *
+     * THE ARGUMENT FOR SETTING IT AT ALL, since the cheapest connected rung is the default: this prompt is the
+     * one quick job that is genuinely adversarial. Its input includes text the agent is about to run, which may
+     * have arrived from a stranger's web page, and a small model can be talked round by it (command-judge.ts is
+     * candid about that). It is also the job where being WRONG is expensive in both directions — a needless card
+     * teaches the owner to click through the next one. Neither is a reason for us to spend somebody's frontier
+     * allowance by default; both are reasons for them to be able to. */
+    commandJudgeModels: z
+        .array(z.string())
+        .max(10)
+        .default([])
+        .describe(
+            "Which models decide whether a flagged command should run, tried in order so one spent account does not take the gate down. Empty uses whatever the quick model is, which is what this did before the setting existed.",
+        ),
     /* HOW MUCH AN AGENT MAY DELEGATE, the three ceilings the Claude Code harness enforces on its own Agent
      * tool, surfaced here because their defaults are tuned for a laptop and this is a container the owner sized.
      *

package/src/transcript-fold.test.ts

@@ -392,6 +392,53 @@ describe("foldTurn", () => {
         ]);
     });
 
+    /* A GATED CREDENTIAL's card keeps WHO released it, not merely that something was approved: the approver is
+     * the whole point of the gate, and the reply cannot carry them (it is the daemon that verified the
+     * identity), so the receipt frame is the only place that name ever appears. */
+    it("keeps who released a gated credential on the card that asked for it", () => {
+        const offer = {
+            subject: "DATABASE_URL",
+            kind: "secret" as const,
+            lane: "shell" as const,
+            detail: "psql {{secret:DATABASE_URL}}",
+            why: "run the migration",
+            approvers: ["bob@corp.com"],
+            scope: "use" as const,
+        };
+        const events: AgentEvent[] = [
+            { kind: "credential_offer", requestId: "c1", offer },
+            { kind: "resolved", requestId: "c1", reply: { kind: "credential_offer", requestId: "c1", approve: true } },
+            { kind: "credential_receipt", requestId: "c1", outcome: "released", approvedBy: "bob@corp.com" },
+            { kind: "delta", text: "Migrated." },
+        ];
+        expect(foldOf("migrate", events).slice(1)).toEqual([
+            {
+                role: "assistant",
+                text: "",
+                credentialOffer: { requestId: "c1", offer, status: "approved", receipt: { outcome: "released", approvedBy: "bob@corp.com" } },
+            },
+            { role: "assistant", text: "Migrated." },
+        ]);
+    });
+
+    /* A release nobody answered is nobody's refusal. The deadline passing freezes the card `cancelled` and
+     * writes NO receipt, because "refused" would name a decision a person never made — the same split the
+     * gate's two refusal sentences make to the agent. */
+    it("freezes an unanswered release as nobody's decision, with no receipt", () => {
+        const offer = {
+            subject: "reddit",
+            kind: "capability" as const,
+            lane: "session" as const,
+            approvers: ["alice@corp.com"],
+            scope: "conversation" as const,
+        };
+        const events: AgentEvent[] = [{ kind: "credential_offer", requestId: "c1", offer }];
+        expect(foldTurn(openingOf("post it"), events, "stopped").slice(1)).toEqual([
+            { role: "assistant", text: "", credentialOffer: { requestId: "c1", offer, status: "cancelled" } },
+            { role: "notice", text: "Stopped." },
+        ]);
+    });
+
     // A turn the user stopped says so, after freezing whatever it was parked on.
     it("writes a stop down after cancelling what the turn was waiting on", () => {
         const events: AgentEvent[] = [