@ottimis/jack-provider-sdk 0.1.0 → 0.3.0

package/dist/usage.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Usage / billing capability — provider-owned data flow.
+ *
+ * Each provider knows how to talk to its own billing surface (Claude
+ * cookie API for Pro/Max, OpenAI usage endpoints for Codex, Gemini's
+ * Google Cloud quotas, …) and how to map its SDK's per-message token
+ * counts into a canonical shape. The host runs a generic poll loop and
+ * a generic chip — it never special-cases any provider.
+ *
+ * Two surfaces:
+ *
+ *   - `fetch()` for **account-level** snapshots. Pulled by a host poller
+ *     on `recommendedPollIntervalSec` cadence (clamped to host bounds).
+ *     What "account" means is provider-defined: Claude → org, Codex →
+ *     OpenAI project, Gemini → Cloud Billing project.
+ *
+ *   - `formatSessionMetrics()` for **per-session** translation. The
+ *     manager already calls `backend.getContextUsage()` after every
+ *     `assistant` message; that returns a loose `AgentContextUsage`
+ *     bag. This hook lets the provider lift it into canonical
+ *     {@link UsageMetric}[] without the host trying to interpret
+ *     provider-specific fields.
+ *
+ * Single source of truth: the provider. Host plumbs, never decodes.
+ *
+ * Optional everywhere — providers without billing visibility (Codex
+ * without admin keys, Gemini without OAuth) leave `fetch()` returning
+ * an empty `metrics: []`. The capability flag stays `true` if the
+ * provider can format per-session metrics, `false` if it has nothing
+ * to say at all.
+ */
+import type { AgentContextUsage } from './backend';
+/**
+ * Canonical metric kinds. New kinds extend this union additively when a
+ * provider has a meaningfully different shape (e.g. a future
+ * `quarterly_burn` for enterprise billing). Adding a kind is a minor
+ * SDK bump; the renderer's dispatch table grows alongside.
+ */
+export type UsageMetric = TimeWindowMetric | TokenUtilizationMetric | MonthlySpendMetric;
+/**
+ * Rolling-window utilization. The classic Claude Pro/Max bucket
+ * (5-hour, 7-day) — utilization 0..1 with a hard reset boundary.
+ *
+ * Optional `used` / `limit` / `unit` carry raw counts when the
+ * provider exposes them (Gemini free-tier daily quota: 12 of 50
+ * requests). Claude's cookie API gives only `utilization`, so those
+ * stay undefined and the chip falls back to "X% of N-hour usage".
+ */
+export type TimeWindowMetric = {
+    kind: 'time_window';
+    /** Stable, provider-defined key. e.g. `'five_hour'`, `'seven_day_opus'`, `'daily'`. */
+    id: string;
+    /** Human-readable label for UI. Provider supplies (i18n is its concern). */
+    label: string;
+    /** Window utilization in [0, 1]. */
+    utilization: number;
+    /** Optional: raw count consumed in the window (when known). */
+    used?: number;
+    /** Optional: raw cap of the window (when known). */
+    limit?: number;
+    /** Optional: unit of `used`/`limit`. Default `'tokens'`. Chip uses for formatting. */
+    unit?: 'tokens' | 'requests' | (string & {});
+    /** ISO 8601 timestamp when the window resets. */
+    resetsAt: string;
+    /** Window length in seconds. Used for elapsed-progress UI. */
+    windowSeconds: number;
+};
+/**
+ * Count-based utilization without a time boundary. Used for context
+ * window pressure ("X tokens of Y max") and any cumulative provider
+ * metric that doesn't reset on a clock (lifetime / billing-period
+ * tokens, etc).
+ *
+ * `max` is optional — a provider tracking total token consumption
+ * without a hard cap (analytics, not gating) leaves it undefined and
+ * the chip shows just the count.
+ */
+export type TokenUtilizationMetric = {
+    kind: 'token_utilization';
+    /** Stable, provider-defined key. e.g. `'context'`, `'session_total'`. */
+    id: string;
+    /** Human-readable label for UI. */
+    label: string;
+    /** Tokens consumed. */
+    used: number;
+    /** Optional cap. Undefined = no cap, chip hides the ratio. */
+    max?: number;
+};
+/**
+ * Spend on a billing cycle (typically monthly). Only meaningful for
+ * providers using API-key auth — subscription users have rolling-window
+ * quotas, not $-spend.
+ *
+ * `budgetUsd` is optional: most users don't set a budget, so the chip
+ * shows raw spend without a denominator. When present, chip can render
+ * a budget bar.
+ */
+export type MonthlySpendMetric = {
+    kind: 'monthly_spend';
+    id: string;
+    /** Cycle label, e.g. "May 2026" or "Current cycle". */
+    label: string;
+    spentUsd: number;
+    budgetUsd?: number;
+    /** ISO 8601 — start of the billing cycle. */
+    cycleStart: string;
+    /** ISO 8601 — end of the billing cycle. */
+    cycleEnd: string;
+};
+/**
+ * One snapshot of provider-side usage data, as returned by
+ * {@link UsageApi.fetch}. `metrics` may be empty when the provider has
+ * no account-level data to report (Codex without billing key, etc.).
+ */
+export type UsageSnapshot = {
+    metrics: UsageMetric[];
+    /** ISO 8601 — when this snapshot was observed. */
+    observedAt: string;
+    /** Verbatim provider payload, kept for debug / future analytics.
+     *  Never consumed by host or chip directly. */
+    raw?: unknown;
+};
+/**
+ * Connection / authorization state of the provider's usage surface.
+ * Surface in the chip's pop-over so the user knows whether they're
+ * tracking real numbers or seeing a cached / disconnected snapshot.
+ */
+export type UsageStatus = {
+    connected: boolean;
+    /** Optional human-readable identity (org name, email, project id). */
+    identity?: string;
+    /**
+     * Provider-defined auth-mode hint. Lets the renderer adapt copy
+     * (e.g. "Connected as API user" vs "Pro subscription"). Stable
+     * provider-supplied strings; host doesn't interpret beyond
+     * passthrough.
+     */
+    authMode?: 'subscription' | 'api_key' | (string & {});
+    /** Last error message, when not connected. */
+    error?: string;
+};
+/**
+ * Result of {@link UsageApi.connect}. The `'choose'` branch covers
+ * multi-org / multi-project accounts where the user must pick one
+ * (Claude's multi-org case). Generalising to a generic option list
+ * means the chip's UI doesn't special-case any provider.
+ */
+export type UsageConnectResult = {
+    kind: 'ready';
+    identity: string;
+} | {
+    kind: 'choose';
+    options: UsageConnectOption[];
+} | {
+    kind: 'error';
+    error: string;
+} | {
+    kind: 'cancelled';
+};
+export type UsageConnectOption = {
+    id: string;
+    label: string;
+};
+/**
+ * Context handed to {@link UsageApi.connect}. Currently just a parent
+ * window for Electron-coupled flows (Claude opens a child BrowserWindow
+ * on `claude.ai/login`). Typed as `unknown` here so the SDK doesn't
+ * pull in `electron` as a peer dep — the host narrows to
+ * `BrowserWindow` at the call site.
+ */
+export type UsageConnectContext = {
+    /** Parent window for any modal flow the provider needs to open. */
+    parentWindow?: unknown;
+};
+/**
+ * Provider-owned usage capability. Optional on {@link JackProvider};
+ * absent = host hides the chip's "Connect" affordance and the
+ * capability flag is `false`.
+ */
+export type UsageApi = {
+    /** Current connection state — used for chip display + gating. */
+    status(): Promise<UsageStatus>;
+    /**
+     * Open the provider's connect flow. Whatever modality the provider
+     * needs (login window, API-key picker, OAuth redirect) lives here.
+     */
+    connect(ctx: UsageConnectContext): Promise<UsageConnectResult>;
+    /**
+     * When `connect()` returned `'choose'`, host calls this with the
+     * user's pick. Optional — providers that never choose omit it.
+     */
+    selectOption?(optionId: string): Promise<UsageConnectResult>;
+    /** Drop credentials and stop any provider-side polling. */
+    disconnect(): Promise<void>;
+    /**
+     * Fetch one fresh account-level snapshot. Empty `metrics: []` is
+     * fine when the provider has no billing surface yet — the capability
+     * stays `true` for the per-session bridge.
+     */
+    fetch(): Promise<UsageSnapshot>;
+    /**
+     * Recommended poll cadence (seconds). Host clamps to its bounds.
+     * Optional — host falls back to its own default if unset.
+     */
+    recommendedPollIntervalSec?: number;
+    /**
+     * Translate the loose {@link AgentContextUsage} the manager pulls from
+     * `backend.getContextUsage()` into canonical {@link UsageMetric}[].
+     *
+     * Pure function (no side effects) — provider knows its own SDK's
+     * shape and lifts it. Empty array OK when the raw bag has nothing
+     * useful (e.g. fresh session before any message lands).
+     *
+     * Optional. Providers without per-session token visibility omit it
+     * and the chip skips the per-session row.
+     */
+    formatSessionMetrics?(raw: AgentContextUsage): UsageMetric[];
+};
+//# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"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"}

package/dist/usage.js

@@ -0,0 +1,33 @@
+/**
+ * Usage / billing capability — provider-owned data flow.
+ *
+ * Each provider knows how to talk to its own billing surface (Claude
+ * cookie API for Pro/Max, OpenAI usage endpoints for Codex, Gemini's
+ * Google Cloud quotas, …) and how to map its SDK's per-message token
+ * counts into a canonical shape. The host runs a generic poll loop and
+ * a generic chip — it never special-cases any provider.
+ *
+ * Two surfaces:
+ *
+ *   - `fetch()` for **account-level** snapshots. Pulled by a host poller
+ *     on `recommendedPollIntervalSec` cadence (clamped to host bounds).
+ *     What "account" means is provider-defined: Claude → org, Codex →
+ *     OpenAI project, Gemini → Cloud Billing project.
+ *
+ *   - `formatSessionMetrics()` for **per-session** translation. The
+ *     manager already calls `backend.getContextUsage()` after every
+ *     `assistant` message; that returns a loose `AgentContextUsage`
+ *     bag. This hook lets the provider lift it into canonical
+ *     {@link UsageMetric}[] without the host trying to interpret
+ *     provider-specific fields.
+ *
+ * Single source of truth: the provider. Host plumbs, never decodes.
+ *
+ * Optional everywhere — providers without billing visibility (Codex
+ * without admin keys, Gemini without OAuth) leave `fetch()` returning
+ * an empty `metrics: []`. The capability flag stays `true` if the
+ * provider can format per-session metrics, `false` if it has nothing
+ * to say at all.
+ */
+export {};
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ottimis/jack-provider-sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Plugin contract for AI provider integrations in Jack — backend interface, capability matrix, spawner primitives, knowledge context. Consumed both by in-tree providers and external packages.",
   "license": "MIT",
   "repository": {
@@ -29,12 +29,14 @@
     "clean": "rm -rf dist"
   },
   "peerDependencies": {
-    "@ottimis/jack-chat-core": ">=0.5.5"
+    "@ottimis/jack-chat-core": ">=0.5.5",
+    "zod": ">=3.22.0"
   },
   "devDependencies": {
     "@ottimis/jack-chat-core": "^0.5.5",
     "@types/node": "^22.14.1",
     "tsx": "^4.19.2",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "zod": "^4.3.6"
   }
 }

package/src/backend.ts

@@ -65,10 +65,18 @@ export type AgentSystemPrompt =
   | { type: 'preset'; preset: string; append?: string }
 
 /**
- * MCP server configuration — opaque to the host. The host never inspects
- * the inner shape; each provider validates / consumes its own format.
+ * MCP server configuration handed to the provider via
+ * {@link AgentQueryOptions.mcpServers}. Mirrors the official MCP wire
+ * format (the same shape Anthropic, OpenAI, and Google all consume).
+ *
+ * Replaces the legacy opaque `AgentMcpServerConfig = unknown` so the
+ * type system enforces the contract end-to-end and the host can inspect
+ * the bag for telemetry / preview without double-translating.
  */
-export type AgentMcpServerConfig = unknown
+export type McpServerSpec =
+  | { type: 'stdio'; command: string; args?: string[]; env?: Record<string, string> }
+  | { type: 'http'; url: string; headers?: Record<string, string> }
+  | { type: 'sse'; url: string; headers?: Record<string, string> }
 
 /** Reasoning-effort knob. Provider-validated; not all providers honor every value. */
 export type AgentEffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max'
@@ -161,7 +169,7 @@ export type AgentQueryOptions = {
    * knowledge sources).
    */
   additionalDirectories?: string[]
-  mcpServers?: Record<string, AgentMcpServerConfig>
+  mcpServers?: Record<string, McpServerSpec>
   resume?: string
   /**
    * Initial model for the spawn. Live switches use
@@ -231,16 +239,24 @@ export interface AgentSession extends AsyncIterable<NormalizedMessage> {
    */
   setModel(model?: string): Promise<void>
   /**
-   * Merge arbitrary settings into the flag-settings layer at runtime.
-   * Used for values the provider exposes only as persisted flags
-   * (notably `effortLevel` on Claude).
+   * Switch the reasoning-effort tier live, without respawning the child
+   * process. Pass `undefined` to clear any override and let the provider
+   * fall back to its default. Gated by `CapabilityMatrix.liveEffortSwitch`
+   * — providers without live switching declare `false` and the renderer
+   * hides the inline Effort dropdown.
+   *
+   * Replaces the legacy `applyFlagSettings({ effortLevel })` bag — Claude
+   * was the only producer and Codex/Gemini both threw `UNSUPPORTED`. The
+   * host now calls this method by name and the type system tells the
+   * provider author exactly what to wire.
    */
-  applyFlagSettings(settings: Record<string, unknown>): Promise<void>
+  setEffortLevel(effort: AgentEffortLevel | undefined): Promise<void>
   /**
-   * Read the effective merged settings layer. The response shape is
-   * `{ effective, sources }` where `effective` is the deep-merged result.
-   * The host uses it to discover the runtime `effortLevel` the provider
-   * booted with.
+   * Read the effective runtime settings the provider booted with. Today
+   * the host only consumes `effective.effortLevel` to populate the
+   * Effort dropdown's initial value; the rest of the bag is opaque so
+   * providers with richer settings layers can passthrough additional
+   * keys without an SDK bump.
    */
   getSettings(): Promise<AgentSettingsResponse>
 }

package/src/index.ts

@@ -24,6 +24,7 @@
 export * from './backend'
 export * from './spawner'
 export * from './provider'
+export * from './usage'
 
 /**
  * Re-export of `NormalizedMessage` from chat-core so consumers don't need

package/src/provider.ts

@@ -16,7 +16,9 @@
  * it free of provider-specific imports.
  */
 
-import type { AgentBackend, AgentQueryOptions } from './backend'
+import type { AgentBackend, AgentQueryOptions, McpServerSpec } from './backend'
+import type { UsageApi } from './usage'
+import type { ZodType } from 'zod'
 import type {
   ClientToolHandler,
   NormalizedMessage,
@@ -28,20 +30,48 @@ import type {
 export type ProviderId = string
 
 /**
- * Slash-command definition surfaced by a provider. Different providers
- * source these differently — Claude scans `.claude/commands/` and
- * declares a fixed list of CLI builtins; Codex / Gemini have their own
- * conventions or none at all. The rendered shape is the same.
+ * Where the provider sourced a slash command from. Drives the
+ * {@link SlashCommandDef} discriminated union below — file-sourced
+ * commands carry `body` + `filePath`, builtin and wire-sourced ones
+ * don't (they don't *have* a markdown file behind them).
  */
-export type SlashCommandDef = {
+export type SlashCommandScope = 'builtin' | 'wire' | 'user' | 'project' | (string & {})
+
+/**
+ * Common surface every slash command def carries regardless of source.
+ * The renderer uses these for autocomplete + chip rendering.
+ */
+type SlashCommandDefBase = {
   name: string
-  scope: 'user' | 'project' | 'builtin'
   description?: string
   argumentHint?: string
-  body: string
-  filePath: string
 }
 
+/**
+ * Slash-command definition surfaced by a provider. Three sources can
+ * coexist (see {@link SlashCommandSupport}):
+ *
+ *   - `'builtin'` — static catalog the runtime intercepts. The renderer
+ *     never opens the file (there is none); the executor is the agent.
+ *   - `'wire'` — pushed live by the agent over the wire (Gemini ACP
+ *     `available_commands_update`). Same render contract as builtin —
+ *     no on-disk artifact.
+ *   - `'user' | 'project'` — file-based commands the user authored
+ *     (Claude `.claude/commands/foo.md`, future per-provider analogs).
+ *     `filePath` + `body` are required so the renderer can offer "open
+ *     in editor" affordances and the host can expand `$ARGUMENTS` /
+ *     `$N` placeholders.
+ *
+ * Discriminated by `scope` so consumers narrow before reading the
+ * file-only fields. Replaces the legacy uniform shape that forced
+ * builtin/wire commands to ship synthetic empty `body: ''` /
+ * `filePath: ''`.
+ */
+export type SlashCommandDef =
+  | (SlashCommandDefBase & { scope: 'builtin' })
+  | (SlashCommandDefBase & { scope: 'wire' })
+  | (SlashCommandDefBase & { scope: 'user' | 'project'; body: string; filePath: string })
+
 /**
  * Parsed envelope a provider's CLI may wrap slash commands in when it logs
  * them into the session transcript. Claude uses
@@ -212,6 +242,14 @@ export type CapabilityMatrix = {
   resumeSession: boolean
   /** Switch model live without respawn (Claude control request `set_model`). */
   liveModelSwitch: boolean
+  /**
+   * Switch reasoning-effort tier live without respawn. Drives whether the
+   * inline Effort dropdown fires `setEffortLevel()` (true) or requires a
+   * spawn-time setting (false → dropdown hidden / annotated). Decoupled
+   * from `liveModelSwitch` because Codex has live model but spawn-time
+   * effort.
+   */
+  liveEffortSwitch: boolean
   /** Switch permission mode live without respawn. */
   livePermissionModeSwitch: boolean
   /**
@@ -228,6 +266,13 @@ export type CapabilityMatrix = {
    *     renderer hides it and only shows the post-fact audit log.
    */
   permissionGranularity: 'callback' | 'sandbox-only'
+  /**
+   * Provider exposes a usage / billing surface (account-level snapshot
+   * via `provider.usage.fetch()` and/or per-session metric translation
+   * via `formatSessionMetrics()`). When `false`, the chip hides the
+   * usage bars and no Connect affordance is offered.
+   */
+  usage: boolean
 }
 
 /**
@@ -353,17 +398,19 @@ export type PrepareSpawnContext = {
 }
 
 /**
- * MCP server registration in canonical Anthropic spec shape. Used by
- * {@link KnowledgeContext.mcpServers} as the cross-provider exchange format
- * for `kind=mcp` knowledge sources. Each provider's
- * {@link JackProvider.applyKnowledgeContext} translates this into whatever
- * its native runtime expects (Claude SDK `mcpServers` map; Codex
- * `mcp_servers.toml`; …).
+ * MCP server registration in canonical wire-format shape. Same type
+ * used at both ends of the knowledge pipeline: as
+ * {@link KnowledgeContext.mcpServers} (input to the provider) and as
+ * {@link AgentQueryOptions.mcpServers} (output from
+ * {@link JackProvider.applyKnowledgeContext}). Each provider's
+ * applyKnowledgeContext translates the merged context into its native
+ * runtime layout (Claude SDK `mcpServers` map; Codex `mcp_servers.toml`;
+ * Gemini ACP `session/new { mcpServers }`).
+ *
+ * Re-exported as `McpServerSpec` from `./backend` — same type, two names
+ * for ergonomics in different code paths.
  */
-export type KnowledgeMcpResolution =
-  | { type: 'stdio'; command: string; args?: string[]; env?: Record<string, string> }
-  | { type: 'http'; url: string; headers?: Record<string, string> }
-  | { type: 'sse'; url: string; headers?: Record<string, string> }
+export type KnowledgeMcpResolution = McpServerSpec
 
 /**
  * Provider-neutral container for everything the host has computed about the
@@ -400,6 +447,24 @@ export type KnowledgeContext = {
  * names the renderer maps to React components. Providers that don't
  * declare branding fall back to neutral defaults.
  */
+/**
+ * Curated icon catalog keys the renderer knows how to map to lucide React
+ * components. Hybrid closed/open: well-known values get autocomplete;
+ * arbitrary strings still type-check (the renderer falls back to a default
+ * icon for unknown keys, so a provider can ship a forward-looking key
+ * without breaking older hosts).
+ */
+export type ProviderIconKey =
+  | 'sparkles'
+  | 'cpu'
+  | 'gem'
+  | 'bot'
+  | 'brain'
+  | 'star'
+  | 'wand'
+  | 'zap'
+  | (string & {})
+
 export type ProviderBranding = {
   /**
    * Primary accent color. Used as a subtle border on the chat composer +
@@ -412,12 +477,13 @@ export type ProviderBranding = {
    */
   accentColor: string
   /**
-   * Curated icon key — one of the names the renderer maps to a lucide
-   * component. Keeping this an enum (instead of free-form SVG/asset)
-   * means providers don't ship rendering assets and the host stays in
-   * control of what shapes can land in the UI.
+   * Curated icon key — one of {@link ProviderIconKey}. Keeping this a
+   * closed/open enum (instead of free-form SVG/asset) means providers
+   * don't ship rendering assets and the host stays in control of what
+   * shapes can land in the UI. Unknown keys fall back to a default icon
+   * in the renderer.
    */
-  iconKey?: string
+  iconKey?: ProviderIconKey
 }
 
 export type JackProvider = {
@@ -572,16 +638,10 @@ export type JackProvider = {
    *
    * Pattern A providers (Claude, Codex) leave this undefined; the host
    * detects the pattern by absence and skips wiring.
-   *
-   * `ctx` carries the host's correlation ids the provider may want to
-   * bridge to wire-driven side channels (e.g. mapping
-   * `available_commands_update` notifications back to the renderer's
-   * slash command store via the host's session id). Optional for
-   * providers that don't need it.
    */
   attachClientToolHandler?(
     handler: ClientToolHandler,
-    ctx?: { jackSessionId?: string }
+    ctx: ClientToolHandlerAttachContext
   ): void
   /**
    * Persisted permission rules manager. The host's
@@ -590,6 +650,14 @@ export type JackProvider = {
    * leave it undefined and the host returns empty snapshots.
    */
   persistedPermissions?: PersistedPermissionsApi
+  /**
+   * Usage / billing capability — provider-owned data flow. See
+   * {@link UsageApi}. Optional; when undefined the chip degrades to
+   * showing nothing (and `capabilities.usage` MUST be `false`). The
+   * provider stays the single source of truth: host plumbs, never
+   * decodes.
+   */
+  usage?: UsageApi
 }
 
 /**
@@ -608,6 +676,34 @@ export type InProcessMcpServerSpec = {
   tools: InProcessMcpToolSpec[]
 }
 
+/**
+ * Context the host hands to {@link JackProvider.attachClientToolHandler}
+ * so the provider can bridge wire-driven side channels back to the host
+ * (e.g. mapping Gemini's `available_commands_update` notifications to
+ * the renderer's per-session slash command store).
+ *
+ * Today only `sessionId` is consumed. `actorId` is reserved for the
+ * future team-tier multi-user mode (north-star: every entity carries an
+ * actor id so coordination scales beyond single-user). Adding a new
+ * required field here would be a major bump; new optional fields ride
+ * on a minor.
+ */
+export type ClientToolHandlerAttachContext = {
+  /**
+   * Host correlation id for the session being spawned. Required —
+   * the provider stores it on its per-spawn slot so wire notifications
+   * can route back to the right host-side consumer.
+   */
+  sessionId: string
+  /**
+   * Actor identity placeholder for future multi-user / team-tier
+   * support. Today the host always passes `'self'` (or omits) since
+   * Jack runs single-user; future remote-agent flows will populate
+   * with `'user_xxx@team_yyy'` style strings.
+   */
+  actorId?: string
+}
+
 /**
  * Behaviour token the provider persists alongside each rule. Mirror of
  * Claude's `permissions.{allow,deny,ask}` arrays — providers with a
@@ -624,17 +720,33 @@ export type PermissionBehavior = 'allow' | 'deny' | 'ask'
 export type PermissionSource = 'user' | 'userLocal' | 'project' | 'projectLocal'
 
 /**
- * One persisted rule as the provider stores it. `tool` + `pattern` are a
- * convenience parse — `raw` is the source of truth for round-trip writes
- * (remove/add use the raw string verbatim).
+ * Optional human-readable parse hint for {@link PermissionRule}. Providers
+ * whose rule grammar has a recognisable "tool" + "pattern" decomposition
+ * (Claude's `Bash(npm install)`, `Edit(*.ts)`) populate this so the UI can
+ * render two columns instead of a raw string. Providers with a different
+ * grammar (Codex `approval_policy` keyed by command prefix) leave it
+ * undefined; the UI falls back to displaying `raw`.
+ */
+export type PermissionRuleHumanReadable = {
+  /** Best-effort tool name extracted by the provider (e.g. `Bash`, `Edit`). */
+  tool?: string
+  /** Best-effort pattern extracted by the provider (the bit inside the parens, etc.). */
+  pattern?: string
+}
+
+/**
+ * One persisted rule as the provider stores it. `raw` is the only
+ * field guaranteed across providers — it's the source of truth for
+ * round-trip writes (remove/add use the raw string verbatim) and the
+ * fallback display when no parse hint is available. The
+ * `humanReadable` sidecar is a Claude-style ergonomic split that
+ * other providers may opt out of.
  */
 export type PermissionRule = {
-  /** Tool name (e.g. `Bash`, `Edit`, `mcp__figma__authenticate`). */
-  tool: string
-  /** Content inside the parens (the glob / pattern), or null if the rule has no parens. */
-  pattern: string | null
-  /** Original string as stored in the settings file — source of truth for round-trip writes. */
+  /** Original string as stored by the provider — source of truth for round-trip writes. */
   raw: string
+  /** Optional parse hint for two-column UI rendering. */
+  humanReadable?: PermissionRuleHumanReadable
 }
 
 export type PermissionsSourceBlock = {
@@ -687,12 +799,17 @@ export type InProcessMcpToolSpec = {
   name: string
   description: string
   /**
-   * Zod schema for the tool arguments. Providers that don't speak zod
-   * natively can call `.shape` to inspect fields. We keep zod here
-   * instead of JSON Schema because the host already uses it everywhere
-   * (one source of truth for tool shapes).
+   * Zod schema for the tool arguments — a `Record<fieldName, ZodType>`
+   * (zod's "shape" form, what `z.object(...)` accepts). Provider
+   * implementations consume it via the SDK helper of their choice
+   * (Claude wraps with `tool(name, desc, schema, handler)` from
+   * `@anthropic-ai/claude-agent-sdk`).
+   *
+   * `zod` is a peer dep of this SDK so consumer + provider type-check
+   * against the same instance. The host always produces zod; trying
+   * to stuff JSON Schema here would silently break Claude's wrapper.
    */
-  schema: Record<string, unknown>
+  schema: Record<string, ZodType>
   handler: (args: Record<string, unknown>) => Promise<{
     content: Array<{ type: 'text'; text: string }>
     isError?: boolean