@intentic/sandbox-contract 1.322.0 → 1.324.0

package/src/schemas/approvals.ts

@@ -133,8 +133,11 @@ const hookDigest = z.string().regex(/^[0-9a-f]{64}$/);
 
 export const SettingsHookSchema = z.object({
     source: z
-        .enum(["user", "project"])
-        .describe("Whose configuration declares it: the sandbox's own (~/.claude) or the workspace's (.claude/ in the project)."),
+        .enum(["user", "project", "plugin"])
+        .describe(
+            "Whose configuration declares it: the sandbox's own (~/.claude), the workspace's (.claude/ in the project), or a Claude Code plugin the turn loads.",
+        ),
+    plugin: z.string().optional().describe("The plugin that declares it, by the name the request's plugin list gives it. Present only for a plugin's hook."),
     declaredIn: z
         .string()
         .optional()
@@ -143,7 +146,11 @@ export const SettingsHookSchema = z.object({
         ),
     event: z.string().describe("When it runs, in Claude Code's own words: before a tool, after one, when a prompt is sent, when a session starts."),
     matcher: z.string().optional().describe("Which tools it is limited to, when it is limited at all."),
-    type: z.string().describe("What kind of hook it is: a shell command, an address it calls, a prompt it asks a model."),
+    type: z
+        .string()
+        .describe(
+            "What kind of hook it is: a shell command, an address it calls, a prompt it asks a model, or a module: a plugin's code that runs inside Claude Code itself.",
+        ),
     run: z.string().describe("Exactly what it runs: the command line, the address, the prompt."),
 });
 export type SettingsHook = z.infer<typeof SettingsHookSchema>;
@@ -162,6 +169,46 @@ export const HookScriptSchema = z.object({
 });
 export type HookScript = z.infer<typeof HookScriptSchema>;
 
+export const HookModuleSchema = z.object({
+    path: z.string().describe("The plugin's hooks module, as its hooks.json names it."),
+    hooks: z
+        .array(z.string())
+        .describe("The moments it acts on, in Claude Code's own words: a tool call, a prompt being sent, the system prompt being put together. Empty when it could not be read."),
+    calls: z
+        .array(z.string())
+        .describe(
+            "What it reaches for while it runs, as Claude Code names its methods: starting programs, network requests, reading and writing files. Empty when it could not be read, or when it reaches for nothing.",
+        ),
+    unreadable: z
+        .string()
+        .optional()
+        .describe("Why the sandbox could not tell what the module does. The approval still covers its code byte for byte. Present only when that is the case."),
+});
+export type HookModule = z.infer<typeof HookModuleSchema>;
+
+export const HookPluginSchema = z.object({
+    name: z.string().describe("The plugin, as the sandbox lists it: the connection, extension or persona that brought it, or the name settings enable it under."),
+    from: z
+        .enum(["plugin", "extension", "persona", "skills", "settings"])
+        .describe(
+            "What brought it into the turn: a plugin connection, an extension, a persona's kit, a plugin folder among Claude Code's skills, or Claude Code's own settings enabling it.",
+        ),
+    source: z
+        .enum(["user", "project"])
+        .optional()
+        .describe("Which settings enable it or hold it, the sandbox's own or the workspace's. Present only for a plugin settings or a skills folder bring in."),
+    dir: z.string().optional().describe("Where its files were read. Absent for one settings enable that this sandbox has not installed."),
+    module: HookModuleSchema.optional().describe("Its hooks module, code that runs inside Claude Code with everything the agent's session holds. Absent when it has none."),
+});
+export type HookPlugin = z.infer<typeof HookPluginSchema>;
+
+export const HookMarketplaceSchema = z.object({
+    source: z.enum(["user", "project"]).describe("Whose settings add it: the sandbox's own or the workspace's."),
+    name: z.string().describe("The marketplace's name in those settings."),
+    location: z.string().describe("Where Claude Code fetches it from, as the settings spell it."),
+});
+export type HookMarketplace = z.infer<typeof HookMarketplaceSchema>;
+
 export const HookRequestSchema = z.object({
     digest: hookDigest.describe(
         "The set's fingerprint: every hook as declared plus the bytes of every file they run. Approving it approves exactly this, and nothing that differs from it by a character.",
@@ -171,7 +218,15 @@ export const HookRequestSchema = z.object({
     hooks: z
         .array(SettingsHookSchema)
         .describe("Every hook in the set. Until it is approved, turns run with all of them off, and so with every other hook the agent would load."),
-    scripts: z.array(HookScriptSchema).describe("The files those hooks run by name, which the approval pins byte for byte."),
+    scripts: z.array(HookScriptSchema).describe("The files those hooks run by name, and a plugin module's code, which the approval pins byte for byte."),
+    plugins: z
+        .array(HookPluginSchema)
+        .optional()
+        .describe("The plugins whose hooks or modules are in the set, and those Claude Code's settings enable. Absent when none is."),
+    marketplaces: z
+        .array(HookMarketplaceSchema)
+        .optional()
+        .describe("Plugin marketplaces Claude Code's settings add, which it may install enabled plugins from. Absent when none is."),
     dismissed: z
         .boolean()
         .optional()

package/src/schemas/automations.ts

@@ -9,10 +9,10 @@ import { ZoneSchema } from "../time/zone.js";
 // (non-zero exit skips the wake), then runs one turn with the prompt. The manifest is user config; run history is
 // daemon-recorded.
 
-// schedule: fires on its cron
-// once: fires a single time at `at`, then retires itself (the daemon switches it off as it fires). Unlike a cron, a
-// fire missed while the sandbox was down still lands, late, on the next poll: a recurring wake that skips a beat has
-// another one coming, a one-time wake has nothing behind it
+// schedule: fires on its cron. Moments missed while the sandbox was down fire once, late, as the daemon starts, however
+// many there were: a recurring wake is owed its work, not a backlog
+// once: fires a single time at `at`, then retires itself (the daemon switches it off as it fires). A fire missed while
+// the sandbox was down still lands, late, on the next poll
 // event: fires when an external system POSTs /automations/{id}/fire; its auth token lives outside the manifest
 // (.intentic/secrets/doors.json), never in this versioned, widely-readable file
 // listener: fires from a realtime source's own connection (an extension's gateway), no cron, no token, never reachable

package/src/schemas/capabilities.ts

@@ -57,8 +57,12 @@ export const CliConfigSchema = z
 // internals. `path` is a subdirectory for a plugin inside a larger checkout; `token` is https auth for a private repo.
 export const PluginConfigSchema = z.object({
     url: z.url().describe("The repository to take the plugin from."),
-    // Branch / tag / commit sha to pin; absent = the default branch's HEAD.
-    ref: z.string().min(1).optional().describe("A branch, tag or commit to pin to. Leave it out to follow the default branch."),
+    // Branch / tag / commit sha to install from; absent = the default branch's HEAD. Either way `commit` pins it.
+    ref: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("A branch, tag or commit to install from. Leave it out for the default branch. The install pins the commit it names at that moment."),
     path: z
         .string()
         .min(1)
@@ -66,6 +70,15 @@ export const PluginConfigSchema = z.object({
         .optional()
         .describe("Where inside the repository the plugin lives, for one that sits in a larger checkout."),
     token: z.string().min(1).optional().describe("A credential for a private repository. Stored, never echoed back."),
+    // Set by the sandbox at install, never by the form: re-applying a stored entry (a rotated token, a migration)
+    // checks this out again, and only adding the plugin anew moves it.
+    commit: z
+        .string()
+        .regex(/^[0-9a-f]{40}$/, "commit must be a full 40-character commit sha")
+        .optional()
+        .describe(
+            "The exact commit installed, in full, resolved from the branch, tag or commit when the plugin was added. Its hooks run inside the agent's session, so it stays at this commit until it is added again.",
+        ),
 });
 // An intentic extension from a git repo (UI bundle + agent contributions + processes). Unlike `plugin`, `ref` must be a
 // full commit sha, since extension code runs trusted in the owner's browser and every update is a deliberate re-add at

package/src/schemas/ci.ts

@@ -113,7 +113,7 @@ export type CiRepo = z.infer<typeof CiRepoSchema>;
 export const CI_POLL_INTERVAL_MS = 2 * 60_000;
 // What was decided about a main-line branch while its CI fails, in the order it was decided (ci/main-fixer.ts).
 export const MainFailureDecisionKindSchema = z.enum([
-    // Its one fix agent was put on it: by the sandbox at the first job that failed, or by a person's Fix press, which
+    // Its one fix agent was put on it: by the sandbox with the first run that failed, or by a person's Fix press, which
     // gives the agent its turns back.
     "fix-up",
     // Nobody was sent: repairs are switched off, or nothing could take it.

package/src/schemas/git/git.ts

@@ -379,6 +379,7 @@ export type WorkspaceModules = z.infer<typeof WorkspaceModulesSchema>;
 // One file an agent touched that still differs from main, plus whether main's working tree already holds it:
 // in main's history: accepted, no longer a difference — no row (see `absorbed`).
 // in main's tree, uncommitted: `landed: true`.
+// taken by the last land and edited in main since (committed or not): `landed: true`, since no land has anything to apply.
 // neither (never landed, or landed then discarded): `landed: false` — what "Land now" applies to.
 // A landed row stays until committed; that is the only act that retires it.
 export const AgentChangeSchema = GitChangeSchema.extend({

package/src/schemas/logs.ts

@@ -65,6 +65,12 @@ export const ClientDiagnosticsAcceptedSchema = z.object({
 export const PresenceReportSchema = z.object({
     clientId: z.string().describe("This connection's own id, the same one it gave the event stream."),
     idle: z.boolean().describe("Whether the person has stopped doing anything."),
+    // Narrower than `idle`, which is the window being off screen: a window left on screen with nobody touching it for
+    // minutes. What an automatic update reads to tell a person at the editor from an editor left open overnight.
+    away: z
+        .boolean()
+        .optional()
+        .describe("Whether the window is on screen but nobody has touched it for several minutes. Absent from a page older than it, which reads as not away."),
     view: z.string().optional().describe("Which view they are on."),
     sessionId: z.string().optional().describe("Which conversation they have open."),
     path: z

package/src/schemas/loops.ts

@@ -186,7 +186,8 @@ export type LoopIteration = z.infer<typeof LoopIterationSchema>;
 // overspent: maxSpendUsd reached.
 // stopped: the user pressed Stop.
 // error: the loop itself failed, not a turn inside it (see `LoopIteration.outcome`).
-export const LoopStateSchema = z.enum(["running", "done", "exhausted", "stalled", "overspent", "stopped", "error"]);
+// unpriced: a spend ceiling was set but the runtime does not report cost, so the ceiling cannot be enforced.
+export const LoopStateSchema = z.enum(["running", "done", "exhausted", "stalled", "overspent", "stopped", "error", "unpriced"]);
 export type LoopState = z.infer<typeof LoopStateSchema>;
 export const LoopRecordSchema = LoopSchema.extend({
     state: LoopStateSchema.describe(

package/src/schemas/needs.ts

@@ -262,6 +262,17 @@ export const ConversationGrantSchema = z.object({
         .boolean()
         .default(false)
         .describe("Whether its own dependency installs run without asking, where the owner's setting would otherwise ask first."),
+    // Answered on a host guard's card, "Allow <secret> anywhere in this conversation", read live by the host guard.
+    secrets: z
+        .array(z.string())
+        .default([])
+        .describe("Secrets whose host guard it may send past without asking, by registry name."),
+    // Answered on any permission card's Allow menu, read live by the card registry: every later request a person could
+    // have allowed once settles as allowed. A request that always asks still asks.
+    everything: z
+        .boolean()
+        .default(false)
+        .describe("Whether every request an allow-once could settle is allowed without asking, until somebody takes it back."),
     updatedAt: z.number().describe("When it last changed, in milliseconds."),
     by: z.string().optional().describe("Who last allowed something here."),
 });
@@ -277,6 +288,8 @@ export const StandingGrantsSchema = z.object({
             folders: z.array(z.string()).describe("Workspace folders its file tools may touch beyond its fence."),
             shelves: z.array(GrantShelfSchema).describe("Shelves of tools opened for it."),
             installs: z.boolean().default(false).describe("Whether its own dependency installs run without asking."),
+            secrets: z.array(z.string()).default([]).describe("Secrets it may send past their host guard without asking."),
+            everything: z.boolean().default(false).describe("Whether every request an allow-once could settle is allowed without asking."),
             by: z.string().optional().describe("Who last allowed one of those."),
             updatedAt: z.number().optional().describe("When one of those last changed, in milliseconds."),
             releases: z
@@ -290,9 +303,11 @@ export type StandingGrants = z.infer<typeof StandingGrantsSchema>;
 export const GrantRevokeSchema = z.object({
     conversationId: z.string(),
     kind: z
-        .enum(["capability", "folder", "shelf", "release", "install"])
-        .describe("Which kind of yes: a grant past the persona or area, a credential's release, or letting its installs run unasked."),
-    what: z.string().describe("The capability id, folder, shelf or released credential it named; empty for installs."),
+        .enum(["capability", "folder", "shelf", "release", "install", "secret", "everything"])
+        .describe(
+            "Which kind of yes: a grant past the persona or area, a credential's release, letting its installs run unasked, a secret sent past its host guard, or allowing everything.",
+        ),
+    what: z.string().describe("The capability id, folder, shelf, released credential or secret it named; empty for installs and everything."),
 });
 export type GrantRevoke = z.infer<typeof GrantRevokeSchema>;
 

package/src/schemas/platform-link.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+
+// THE DAEMON'S LINK WITH THE PLATFORM, as /health reports it (`announce`) and as the owner's Reconnect renews it (POST
+// /platform/relink). The one link nothing outside the container can probe: whether this daemon's registration was
+// taken, and, when it was refused, whether the platform has no record of the sandbox (`unknown`, which a platform that
+// forgot it says too) or deleted it (`deleted`). `ic sandbox doctor`, the setup wizard and the editor's recovery screen
+// read it.
+export const AnnounceStateSchema = z.object({
+    // off: nothing to register with; pending: the first attempt is in flight; registered: the platform took it;
+    // rejected: it answered no; unreachable: it could not be reached.
+    state: z.enum(["off", "pending", "registered", "rejected", "unreachable"]),
+    // Why, for the failing states, already in the owner's terms.
+    detail: z.string().optional(),
+    // On a failing state: false only once the platform said the sandbox was deleted; every other failure is retried.
+    retrying: z.boolean().optional(),
+    // Which no: `unknown` the platform has no record of this sandbox, and its owner's Reconnect can have it adopted;
+    // `deleted` it holds a deletion record, which ends the retrying.
+    reason: z.enum(["unknown", "deleted"]).optional(),
+    // The identity of the database that took the registration (the platform's GET /api/identity), when it said.
+    identity: z.string().optional(),
+    // When this state was last confirmed, ms since epoch.
+    at: z.number().optional(),
+});
+export type AnnounceState = z.infer<typeof AnnounceStateSchema>;
+
+// The owner's Reconnect: registers now, and with a ticket (the platform's adoption ticket, carried opaque), first asks a
+// platform that has no record of the sandbox to make one (its POST /sandbox/adopt). `name` and `image` are what the
+// owner's browser remembers of it, since only the platform held them.
+export const RelinkRequestSchema = z.object({
+    ticket: z.string().min(1).optional(),
+    name: z.string().max(60).optional(),
+    image: z.string().max(150_000).optional(),
+});
+export type RelinkRequest = z.infer<typeof RelinkRequestSchema>;
+
+export const RelinkAnswerSchema = z.object({
+    announce: AnnounceStateSchema,
+    // What the platform said to the adoption, when one was asked for and needed: its HTTP status (0 when it could not
+    // be reached) and its reason, in the owner's terms.
+    adoption: z.object({ status: z.number(), detail: z.string() }).optional(),
+});
+export type RelinkAnswer = z.infer<typeof RelinkAnswerSchema>;

package/src/schemas/privacy.ts

@@ -0,0 +1,204 @@
+// The privacy shield: personal data (names, national ids, document numbers, accounts…) kept away from model providers
+// the owner does not trust. The daemon puts a gateway between every runtime it can point at one and the provider, which
+// replaces what it finds with stable tokens on the way out and puts the real values back on the way in, so the agent
+// works on real data while an untrusted provider only ever reads tokens. Off unless the owner turns it on.
+
+import { z } from "zod";
+
+// What the shield looks for, one switch each. `known` values (a dataset the owner taught it) carry the class they were
+// taught under, so there is no class of their own.
+export const PERSONAL_DATA_CLASSES = [
+    "person-name",
+    "national-id",
+    "tax-id",
+    "identity-document",
+    "bank-account",
+    "payment-card",
+    "email",
+    "phone",
+    "address",
+] as const;
+export const PersonalDataClassSchema = z.enum(PERSONAL_DATA_CLASSES);
+export type PersonalDataClass = z.infer<typeof PersonalDataClassSchema>;
+
+// off: nothing is routed or read. watch: every shieldable turn goes through the gateway, which reads and records what it
+// would have masked and sends everything unchanged. on: untrusted providers get tokens, and a turn that cannot be
+// shielded (a runtime the gateway cannot sit in front of) is refused unless its provider is trusted.
+export const PrivacyShieldModeSchema = z.enum(["off", "watch", "on"]);
+export type PrivacyShieldMode = z.infer<typeof PrivacyShieldModeSchema>;
+
+// What an image bound for an untrusted provider becomes. mask: it is sent, with every stretch of its text the shield
+// reads on this machine (OCR) and finds to be personal data painted over with that value's token; one that cannot be
+// read is held back with a note, never sent unchecked. allow: sent as it is. (Before 2026-10, `withhold` sent a note
+// in place of every image and `read` sent its masked text instead of the picture; both read as `mask` now.)
+export const PrivacyImagesSchema = z.enum(["mask", "allow"]);
+export type PrivacyImages = z.infer<typeof PrivacyImagesSchema>;
+
+// How names are found. dictionary: the first-name and surname lists, with titles and inflection. model: those plus a
+// local named-entity model, where one is installed; without it, the dictionary alone.
+export const PrivacyNamesSchema = z.enum(["dictionary", "model"]);
+export type PrivacyNames = z.infer<typeof PrivacyNamesSchema>;
+
+export const PRIVACY_TRUSTED_MAX = 200;
+export const PRIVACY_ALLOW_MAX = 1000;
+export const PRIVACY_CONVERSATIONS_MAX = 200;
+
+// One conversation the owner let an untrusted provider read as it is, granted from that conversation's own composer:
+// narrower than the trusted list, and the way on for a provider whose runtime the gateway cannot sit in front of
+// (Cursor's own wire, an ACP agent, Pi), which the shield otherwise refuses outright.
+export const PrivacyConversationTrustSchema = z.object({
+    conversationId: z.string().min(1).max(200),
+    provider: z.string().min(1).max(200).describe("Provider id, as the trusted list names it."),
+});
+export type PrivacyConversationTrust = z.infer<typeof PrivacyConversationTrustSchema>;
+
+export const PrivacyShieldPolicySchema = z.object({
+    mode: PrivacyShieldModeSchema.default("off").describe("Whether the shield is off, only watching, or masking."),
+    trusted: z
+        .array(z.string().min(1).max(200))
+        .max(PRIVACY_TRUSTED_MAX)
+        .default([])
+        .describe(
+            "Providers that may read personal data as it is, by provider id (`claude`, `codex`, `endpoint/<id>`). A local model is always trusted.",
+        ),
+    classes: z
+        .array(PersonalDataClassSchema)
+        .default([...PERSONAL_DATA_CLASSES])
+        .describe("Which kinds of personal data are looked for."),
+    images: PrivacyImagesSchema.default("mask").describe("What an image bound for an untrusted provider becomes."),
+    names: PrivacyNamesSchema.default("dictionary").describe("How names are found."),
+    allow: z
+        .array(z.string().min(1).max(200))
+        .max(PRIVACY_ALLOW_MAX)
+        .default([])
+        .describe("Values never masked: your own company, a public figure, a word the detector keeps mistaking for a name."),
+    conversations: z
+        .array(PrivacyConversationTrustSchema)
+        .max(PRIVACY_CONVERSATIONS_MAX)
+        .default([])
+        .describe("Providers that may read one conversation's personal data as it is, each granted from that conversation; oldest first."),
+});
+export type PrivacyShieldPolicy = z.infer<typeof PrivacyShieldPolicySchema>;
+
+// Whether the owner let this provider read this conversation as it is. A turn outside any conversation (a helper job)
+// never is.
+export const trustedInConversation = (
+    policy: Pick<PrivacyShieldPolicy, "conversations">,
+    provider: string,
+    conversationId: string | undefined,
+): boolean => conversationId !== undefined && policy.conversations.some((entry) => entry.conversationId === conversationId && entry.provider === provider);
+
+// The policy with that grant made or taken back. A full list drops its oldest grant to make room, since the newest is
+// the one somebody is waiting on.
+export const withConversationTrust = (policy: PrivacyShieldPolicy, conversationId: string, provider: string, on: boolean): PrivacyShieldPolicy => {
+    const others = policy.conversations.filter((entry) => !(entry.conversationId === conversationId && entry.provider === provider));
+    return { ...policy, conversations: on ? [...others, { conversationId, provider }].slice(-PRIVACY_CONVERSATIONS_MAX) : others };
+};
+
+// The policy a sandbox that never wrote one runs on.
+export const DEFAULT_PRIVACY_SHIELD: PrivacyShieldPolicy = PrivacyShieldPolicySchema.parse({});
+
+// How a provider stands against the gateway, for the trusted list: whether its traffic can be shielded at all, and
+// whether it never leaves this machine.
+export const PrivacyProviderSchema = z.object({
+    id: z.string().describe("Provider id, as the trusted list names it."),
+    label: z.string(),
+    shieldable: z.boolean().describe("Its runtime can be put behind the gateway; one that cannot is refused while the shield is on, unless trusted."),
+    local: z.boolean().describe("It runs on this machine, so it is trusted whatever the list says."),
+});
+export type PrivacyProvider = z.infer<typeof PrivacyProviderSchema>;
+
+export const PrivacyShieldStatusSchema = z.object({
+    policy: PrivacyShieldPolicySchema,
+    known: z.number().int().describe("Values taught from your datasets, matched exactly wherever they appear."),
+    tokens: z.number().int().describe("Values the shield has given a token so far."),
+    readers: z.object({
+        ocr: z.boolean().describe("The local text reader (PaddleOCR) that finds personal data in images is installed."),
+        model: z.boolean().describe("A local named-entity model for names is installed."),
+    }),
+    providers: z.array(PrivacyProviderSchema),
+});
+export type PrivacyShieldStatus = z.infer<typeof PrivacyShieldStatusSchema>;
+
+// One request the gateway handled, as the log keeps it: counts and kinds, never a value.
+export const PrivacyLedgerActionSchema = z.enum(["masked", "watched", "passed", "refused"]);
+export type PrivacyLedgerAction = z.infer<typeof PrivacyLedgerActionSchema>;
+
+export const PrivacyLedgerEntrySchema = z.object({
+    at: z.string().describe("When, as an ISO timestamp."),
+    conversationId: z.string().optional(),
+    provider: z.string(),
+    trusted: z.boolean(),
+    action: PrivacyLedgerActionSchema,
+    counts: z.partialRecord(PersonalDataClassSchema, z.number().int()).describe("How many of each kind were found in what this request added."),
+    images: z.number().int().describe("Images the shield changed: personal data painted over, or held back when they could not be read."),
+    documents: z.number().int().describe("Documents replaced by their masked text."),
+    protocol: z.string().describe("Which wire format the request spoke."),
+    detail: z.string().optional().describe("Why it was refused, when it was."),
+});
+export type PrivacyLedgerEntry = z.infer<typeof PrivacyLedgerEntrySchema>;
+
+// A dataset taught to the shield: each value is matched exactly from then on, in every form it is written.
+export const PRIVACY_KNOWN_BATCH_MAX = 50_000;
+
+export const PrivacyKnownValueSchema = z.object({
+    value: z.string().min(2).max(500),
+    class: PersonalDataClassSchema,
+});
+export type PrivacyKnownValue = z.infer<typeof PrivacyKnownValueSchema>;
+
+export const PrivacyKnownSourceSchema = z.object({
+    source: z.string().describe("Where the values came from, as whoever taught them named it."),
+    count: z.number().int(),
+    at: z.string().describe("When they were last taught."),
+});
+export type PrivacyKnownSource = z.infer<typeof PrivacyKnownSourceSchema>;
+
+// The name lists the shield finds names by when no model is asked for (and alongside one when it is): what each list
+// holds, how many, and where it came from.
+export const PrivacyNameListSchema = z.object({
+    id: z.string().describe("Stable id of the list."),
+    kind: z.enum(["first-name", "surname", "ambiguous", "title", "never"]).describe("What a word on it says about a name."),
+    languages: z.array(z.enum(["pl", "en"])).describe("The languages its words come from."),
+    count: z.number().int().describe("How many words it holds."),
+    matching: z
+        .enum(["inflected", "as-written"])
+        .describe("inflected: matched in every grammatical form of a listed word; as-written: matched only exactly as listed."),
+    source: z.string().describe("Where the words come from: the register or dataset, or that they were written by hand."),
+    url: z.string().optional().describe("The source's page, where it has one."),
+    license: z.string().optional(),
+});
+export type PrivacyNameList = z.infer<typeof PrivacyNameListSchema>;
+
+// What the lists say of one word.
+export const PrivacyNameWordSchema = z.object({
+    word: z.string(),
+    firstName: z.boolean().describe("A listed first name, in this form or as an inflection of one."),
+    surname: z.boolean().describe("A listed surname, in this form or as an inflection of one."),
+    surnameForm: z.boolean().describe("Shaped like a Polish surname (-ski, -cki, -wicz…), listed or not."),
+    ambiguous: z.boolean().describe("Also an ordinary word, so found only beside other evidence (a surname, a title)."),
+    never: z.boolean().describe("Never taken as part of a name (a title, an institution, a function word)."),
+});
+export type PrivacyNameWord = z.infer<typeof PrivacyNameWordSchema>;
+
+// What the dictionary makes of a word or a full name, for checking whether it would be found.
+export const PrivacyNameLookupSchema = z.object({
+    text: z.string().describe("The query as a name is written: each word capitalized."),
+    found: z.boolean().describe("Whether the dictionary alone masks it as a name, written so on its own."),
+    words: z.array(PrivacyNameWordSchema),
+});
+export type PrivacyNameLookup = z.infer<typeof PrivacyNameLookupSchema>;
+
+export const PRIVACY_DICTIONARY_SAMPLE_MAX = 200;
+
+export const PrivacyDictionarySchema = z.object({
+    lists: z.array(PrivacyNameListSchema),
+    totals: z
+        .object({ firstNames: z.number().int(), surnames: z.number().int() })
+        .describe("Distinct words across the first-name lists, and across the surname lists."),
+    // Words of the lists that start with a one-word query, for browsing; empty without one.
+    matches: z.array(z.object({ word: z.string(), lists: z.array(z.string()).describe("Ids of the lists holding it.") })),
+    // The query read as a name, when there is one.
+    lookup: PrivacyNameLookupSchema.optional(),
+});
+export type PrivacyDictionary = z.infer<typeof PrivacyDictionarySchema>;

package/src/schemas/providers/plan-limits.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { ChildRunSchema } from "../../events/requests.js";
 import { TRANSLATOR_PROVIDERS, type TranslatorProvider } from "../../models/provider-specs.js";
-import { AgentHarnessSchema, AgentProviderSchema, EditorContextSchema } from "../agent.js";
+import { AgentHarnessSchema, AgentProviderSchema, ConversationIdSchema, EditorContextSchema } from "../agent.js";
 import { MENTION_LIMIT } from "../../text/mentions.js";
 // Headroom is one shape shared by every provider, not a Claude idea others imitate: a native account and a routed
 // subscription differ in who holds the credential, never in what a reading is. Every surface that draws a percentage
@@ -32,7 +32,9 @@ export const UsageUnreadSchema = z.object({
     since: z.number().describe("When re-reading this account first failed, in milliseconds. It has failed on every attempt since."),
     reason: z
         .string()
-        .describe("Why, in the provider's own words where it gave some (\"Verify your account to continue.\"). Short enough to print; never a pasted response body."),
+        .describe(
+            'Why, in the provider\'s own words where it gave some ("Verify your account to continue."). Short enough to print; never a pasted response body.',
+        ),
 });
 export type UsageUnread = z.infer<typeof UsageUnreadSchema>;
 // Every window kept, not just the binding one, since which pool binds changes between turns. Utilization only climbs
@@ -202,18 +204,27 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
             .record(z.string(), z.array(z.string()))
             .optional()
             .describe("What you chose, keyed by the question, with the chosen labels or your own words."),
+        attachments: z
+            .record(z.string(), z.array(z.string()))
+            .optional()
+            .describe(
+                "Files that go with your own-words answer, keyed by the question, as workspace-relative paths of files already uploaded (a screenshot, a mock-up).",
+            ),
         cancelled: z
             .boolean()
             .optional()
             .describe("Dismissing it instead, which tells the agent to carry on using sensible defaults rather than leaving it waiting."),
     }),
-    // "always" may be narrowed further by the SDK's own suggestions.
+    // "always" may be narrowed further by the SDK's own suggestions. "everything" is the conversation-wide yes the card's
+    // Allow menu offers: this call, and every later request in the conversation a person could have allowed once.
     z.object({
         kind: z.literal("permission").describe("Answering a request to use a tool."),
         requestId: z.string().min(1).describe("Which card you are answering."),
         decision: z
-            .enum(["once", "always", "deny"])
-            .describe("Once allows this call alone; always allows that whole tool for the rest of the conversation; no blocks it."),
+            .enum(["once", "always", "everything", "deny"])
+            .describe(
+                "Once allows this call alone; always allows what the request's always-label names (a tool, a rule, a secret) for the rest of the conversation; everything allows this call and every later request in this conversation that an allow-once could settle, until it is taken back on Grants; no blocks it. A request that always asks (alwaysAsks) reads everything as once.",
+            ),
         feedback: z.string().optional().describe("Why not, which goes back to the model as the reason."),
         // Whole, not a patch: effort or an account named for one model means nothing on another.
         child: ChildRunSchema.optional().describe(
@@ -401,6 +412,28 @@ export const QueueResumeSchema = z.object({
     ),
 });
 export type QueueResume = z.infer<typeof QueueResumeSchema>;
+// Re-times what a conversation's queue holds: the same messages, booked for another instant or for after another
+// conversation's work lands. One of the two, never both, since a hold waits on exactly one thing.
+export const QueueScheduleSchema = z
+    .object({
+        conversationId: z.string().min(1).describe("Whose queue."),
+        sendAt: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Send what waits at this instant (epoch milliseconds) instead. At most a month ahead; an instant already past sends it now."),
+        sendAfter: ConversationIdSchema.optional().describe(
+            "Send what waits once that conversation has finished and all of its work has landed in the workspace, instead. Sent now when it has nothing running and nothing left to land.",
+        ),
+    })
+    .refine((input) => (input.sendAt === undefined) !== (input.sendAfter === undefined), {
+        message: "name exactly one of sendAt and sendAfter",
+    })
+    .refine((input) => input.sendAfter !== input.conversationId, {
+        message: "a conversation cannot wait for its own work to land",
+    });
+export type QueueSchedule = z.infer<typeof QueueScheduleSchema>;
 // Moves a conversation to another account of the provider it runs on: the one command that changes who pays, so the
 // account a conversation runs on is always the daemon's record and never a window's guess.
 export const SwitchAccountSchema = z.object({

package/src/schemas/providers/usage.ts

@@ -42,11 +42,16 @@ export const UsageTurnSchema = z.object({
     turns: z
         .number()
         .describe("The provider's own count for the request, since one exchange can be several under the hood. One when it reported none."),
-    inputTokens: z.number().describe("Tokens sent."),
+    inputTokens: z.number().describe("Uncached input tokens, excluding cache reads and cache writes."),
     outputTokens: z.number().describe("Tokens received."),
     cacheReadTokens: z.number().describe("Tokens served from cache, which cost less."),
     cacheCreationTokens: z.number().describe("Tokens written to cache, which cost more up front and less afterwards."),
     costUsd: z.number().describe("What it cost, in dollars."),
+    // Whether `costUsd` was reported by the vendor (true or absent) or is zero only because the vendor does not price
+    // its calls (false). Old rows before this field was added carry no marker, which readers treat as known: they
+    // already recorded a real number. Runtimes like Codex and Cursor report tokens but no cost, so their turns land
+    // with `costUsd: 0, costKnown: false` rather than silently claiming they were free.
+    costKnown: z.boolean().optional().describe("False when the vendor did not report a cost and the recorded zero is a placeholder, not a price. Absent or true means the cost is real."),
     durationMs: z.number().describe("How long it took, in milliseconds."),
     // Arm of the search-teaching experiment; stable per conversation. Absent means unmeasured.
     iqSearchArm: z.boolean().optional(),
@@ -75,6 +80,9 @@ export const UsageTurnSchema = z.object({
     // Arm of the lean-guidance experiment, stable per conversation; true is the short form. The cohort hashes both forms.
     guidanceArm: z.boolean().optional(),
     guidanceCohort: z.string().optional(),
+    // Arm of the tool-result clearing experiment, stable per conversation; true is a conversation whose old tool results
+    // the gateway drops. Native Claude turns only: no other runtime's requests pass a gateway that clears.
+    clearingArm: z.boolean().optional(),
     // What became of pre-turn retrieval on this turn, and how long it took. Assignment and DELIVERY are different
     // facts: the first version of this mechanism was assigned to every eligible turn and reached four in five of them,
     // which is the difference between a null result and a mechanism that never ran. Absent means the flag was off, so
@@ -126,11 +134,14 @@ export const UsageRollupRowSchema = z.object({
     harness: z.string().describe("Which agentic loop."),
     conversationId: z.string().optional().describe("Which conversation."),
     turns: z.number().describe("Turns in this group."),
-    inputTokens: z.number().describe("Tokens sent."),
+    inputTokens: z.number().describe("Uncached input tokens, excluding cache reads and cache writes."),
     outputTokens: z.number().describe("Tokens received."),
     cacheReadTokens: z.number().describe("Tokens served from cache."),
     cacheCreationTokens: z.number().describe("Tokens written to cache."),
     costUsd: z.number().describe("What the group cost, in dollars."),
+    // True when every turn in the group reported its cost; false when at least one did not, making `costUsd` a
+    // lower bound rather than the true total. Absent on rollups from before this field existed.
+    costKnown: z.boolean().optional().describe("False when the cost includes unpriced turns and is a lower bound rather than the true total."),
     durationMs: z.number().describe("Time spent, in milliseconds."),
 });
 export type UsageRollupRow = z.infer<typeof UsageRollupRowSchema>;

package/src/schemas/push.ts

@@ -52,6 +52,13 @@ export const PushNotificationSchema = z.object({
         .describe(
             "Keep it on screen until it is dismissed. Used when the agent is waiting for you, where one that fades away is a question that went unanswered in silence.",
         ),
+    // Optional so an older service worker or relay, which ignores it, still shows the replacement under the same tag.
+    silent: z
+        .boolean()
+        .optional()
+        .describe(
+            "Arrive without sound or vibration. Used for the replacement that says an ask stopped waiting: it takes the waiting one's place under the same tag, and is news nobody has to act on.",
+        ),
 });
 export type PushNotification = z.infer<typeof PushNotificationSchema>;
 export const PushConfigSchema = z.object({

package/src/schemas/settings-history.ts

@@ -23,9 +23,9 @@ const isRetiredRule = (rule: unknown): boolean => {
 
 const holdsRetiredRule = (value: unknown): value is readonly unknown[] => Array.isArray(value) && value.some(isRetiredRule);
 
-// A rule at the `turn.ending` moment reads and runs nothing since nothing checks inside a turn (its moment and the
-// `verify-ui-edits` built-in stay in the read schema so a file written before reads); dropped, so it stops showing as a
-// rule the owner has and stops travelling with the settings.
+// An owner's rule at the `turn.ending` moment reads and runs nothing, since only the checks a repository declares run
+// there (its moment and the `verify-ui-edits` built-in stay in the read schema so a file written before reads); dropped,
+// so it stops showing as a rule the owner has and stops travelling with the settings.
 const isInertRule = (rule: unknown): boolean =>
     isJsonObject(rule) &&
     (rule["moment"] === "turn.ending" || (isJsonObject(rule["action"]) && rule["action"]["kind"] === "builtin" && rule["action"]["name"] === "verify-ui-edits"));