@theokit/sdk 3.2.2 → 3.3.0

package/dist/internal/persistence/pagination.d.cts

@@ -5,4 +5,17 @@
  *
  * @internal
  */
-export {};
+/**
+ * Apply an optional `{ offset, limit }` window to an ordered list.
+ * `undefined` opts returns the list unchanged; undefined offset ⇒ 0; undefined
+ * limit ⇒ to the end. An out-of-range (but valid) offset yields an empty slice.
+ *
+ * Invalid input FAILS FAST (error-handling.md): `offset`/`limit` must be a
+ * non-negative integer — a `NaN`, negative, fractional, or non-finite value is a
+ * caller mistake and throws `ConfigurationError` rather than being silently
+ * coerced (a `NaN` offset previously returned the whole list).
+ */
+export declare function paginate<T>(items: readonly T[], opts?: {
+    offset?: number;
+    limit?: number;
+}): readonly T[];

package/dist/internal/persistence/pagination.d.ts

@@ -5,4 +5,17 @@
  *
  * @internal
  */
-export {};
+/**
+ * Apply an optional `{ offset, limit }` window to an ordered list.
+ * `undefined` opts returns the list unchanged; undefined offset ⇒ 0; undefined
+ * limit ⇒ to the end. An out-of-range (but valid) offset yields an empty slice.
+ *
+ * Invalid input FAILS FAST (error-handling.md): `offset`/`limit` must be a
+ * non-negative integer — a `NaN`, negative, fractional, or non-finite value is a
+ * caller mistake and throws `ConfigurationError` rather than being silently
+ * coerced (a `NaN` offset previously returned the whole list).
+ */
+export declare function paginate<T>(items: readonly T[], opts?: {
+    offset?: number;
+    limit?: number;
+}): readonly T[];

package/dist/internal/plugins/types.d.cts

@@ -20,6 +20,13 @@ export interface PreToolCallContext {
     args: Record<string, unknown>;
     agentId: string;
     runId: string;
+    /**
+     * SE1 — the run's resolved `PermissionMode` (from `SendOptions.permissionMode`
+     * ?? `AgentOptions.permissionMode`), threaded so a permission-style plugin can
+     * gate per-run rather than at construction time. Absent ⇒ the plugin's own
+     * default applies. Ignored by non-permission plugins.
+     */
+    permissionMode?: import("../../permission-engine.js").PermissionMode;
 }
 export interface PreToolCallDecision {
     block: true;

package/dist/internal/plugins/types.d.ts

@@ -20,6 +20,13 @@ export interface PreToolCallContext {
     args: Record<string, unknown>;
     agentId: string;
     runId: string;
+    /**
+     * SE1 — the run's resolved `PermissionMode` (from `SendOptions.permissionMode`
+     * ?? `AgentOptions.permissionMode`), threaded so a permission-style plugin can
+     * gate per-run rather than at construction time. Absent ⇒ the plugin's own
+     * default applies. Ignored by non-permission plugins.
+     */
+    permissionMode?: import("../../permission-engine.js").PermissionMode;
 }
 export interface PreToolCallDecision {
     block: true;

package/dist/permission-engine.d.ts

@@ -23,10 +23,11 @@ export type PermissionAction = "allow" | "deny" | "ask";
  *   for full read-only behavior.
  * - `acceptEdits` — auto-approve the UNMATCHED verdict, but STILL honor an explicit
  *   `ask` rule (a caller gates a risky tool with an ask rule). Codex `UnlessTrusted`.
- * - `bypass` — everything ⇒ `allow` EXCEPT an explicit `deny` rule. Never asks.
- *   OpenCode `dangerously-skip-permissions` / Codex `Never`.
+ * - `bypass` (alias `bypassPermissions`, the Anthropic-exact name) — everything ⇒
+ *   `allow` EXCEPT an explicit `deny` rule. Never asks. OpenCode
+ *   `dangerously-skip-permissions` / Codex `Never` / Anthropic `bypassPermissions`.
  */
-export type PermissionMode = "default" | "plan" | "acceptEdits" | "bypass";
+export type PermissionMode = "default" | "plan" | "acceptEdits" | "bypass" | "bypassPermissions";
 /**
  * SE1 — apply a {@link PermissionMode} to a rule-engine verdict. Pure.
  *

package/dist/{run-CrHz9BAP.d.cts → run-CL5Rw6a5.d.cts}

@@ -69,6 +69,93 @@ interface ToolResultGuardOptions {
     redactPii?: boolean;
 }
 
+/**
+ * `PermissionEngine` — first-match permission rules for tool invocations.
+ *
+ * Evaluates a tool name (and optional arguments, #55) against an ordered list
+ * of rules. First matching rule wins; when no rule matches the `defaultAction`
+ * is returned. #55 — the default is now `"ask"` (FAIL-CLOSED): a permission
+ * engine that cannot positively allow must not silently allow. Opt back into
+ * the previous fail-open behavior with `{ defaultAction: "allow" }`.
+ */
+type PermissionAction = "allow" | "deny" | "ask";
+/**
+ * SE1 — a per-run permission MODE that adjusts the rule-engine verdict globally.
+ * A PURE post-processor of the verdict (no tool-safety metadata needed, so it fits
+ * a bring-your-own-tools runtime). Grounded in OpenCode (plan agent = deny-all,
+ * `dangerously-skip-permissions`) + Codex (`AskForApproval`: `OnRequest` default,
+ * `Never`, `UnlessTrusted`). See {@link applyMode} for the exact table.
+ *
+ * - `default` — verdict as-is (rules decide; unmatched ⇒ `ask`, fail-closed).
+ * - `plan` — read-only: `allow` rules pass, everything else ⇒ `deny` (mutations blocked).
+ *   NOTE: `plan` gates on the resolved verdict, so an engine configured with
+ *   `{ defaultAction: "allow" }` still yields `allow` for UNMATCHED calls under
+ *   `plan` — pair `plan` with the default fail-closed engine (`defaultAction: "ask"`)
+ *   for full read-only behavior.
+ * - `acceptEdits` — auto-approve the UNMATCHED verdict, but STILL honor an explicit
+ *   `ask` rule (a caller gates a risky tool with an ask rule). Codex `UnlessTrusted`.
+ * - `bypass` (alias `bypassPermissions`, the Anthropic-exact name) — everything ⇒
+ *   `allow` EXCEPT an explicit `deny` rule. Never asks. OpenCode
+ *   `dangerously-skip-permissions` / Codex `Never` / Anthropic `bypassPermissions`.
+ */
+type PermissionMode = "default" | "plan" | "acceptEdits" | "bypass" | "bypassPermissions";
+/**
+ * SE1 — apply a {@link PermissionMode} to a rule-engine verdict. Pure.
+ *
+ * `explicit` is `true` when the verdict came from a rule that matched by name (and
+ * args), `false` when it is the fail-closed default for an unmatched call. The flag
+ * is load-bearing for `acceptEdits`, which auto-approves the unmatched default but
+ * keeps honoring an explicit `ask` rule (unlike `bypass`, which allows even that).
+ *
+ * INVARIANT (both OpenCode + Codex): an explicit `deny` is immune to EVERY
+ * auto-approve mode — `bypass`/`acceptEdits` never un-deny.
+ */
+declare function applyMode(verdict: PermissionAction, mode: PermissionMode, explicit: boolean): PermissionAction;
+/**
+ * #55 — an argument matcher. A rule with `args` gates on the tool's argument
+ * VALUES, not just its name: an exact string, a RegExp (tested against the
+ * stringified value), or a predicate. Every declared arg must match for the
+ * rule to apply — so `{ tool: "shell", args: { command: /rm\s+-rf/ } }` denies
+ * a destructive shell call while leaving `ls` to fall through.
+ */
+type ArgMatcher = string | RegExp | ((value: unknown) => boolean);
+interface PermissionRule {
+    /** Tool name (exact string) or pattern (RegExp). */
+    tool: string | RegExp;
+    /**
+     * #55 — optional per-argument matchers. When present, the rule matches only
+     * if the tool name matches AND every declared arg predicate matches the
+     * corresponding call argument. A missing/undefined arg fails its predicate
+     * (the rule does not match) — never throws.
+     */
+    args?: Record<string, ArgMatcher>;
+    /** Action to take when rule matches. */
+    action: PermissionAction;
+}
+/** Options for {@link PermissionEngine}. */
+interface PermissionEngineOptions {
+    /**
+     * Action when no rule matches. #55 — default is now `"ask"` (fail-closed): a
+     * permission engine that cannot positively allow must not silently allow.
+     * Pass `"allow"` to restore the previous fail-open behavior.
+     */
+    readonly defaultAction?: PermissionAction;
+}
+declare class PermissionEngine {
+    #private;
+    private readonly rules;
+    private readonly defaultAction;
+    constructor(rules: PermissionRule[], options?: PermissionEngineOptions);
+    /**
+     * Evaluate a tool name (and optional arguments) against the rules. First
+     * match wins; falls back to the configured `defaultAction` (default `"ask"`,
+     * fail-closed) when no rule matches. #55 — a rule with `args` gates on the
+     * argument values, so the same tool name can resolve to different actions
+     * depending on what it is asked to do.
+     */
+    evaluate(toolName: string, args?: Record<string, unknown>, mode?: PermissionMode): PermissionAction;
+}
+
 /**
  * SE2 — typed runtime EVENT stream, ADDITIVE to the `SDKMessage` content stream.
  *
@@ -1251,6 +1338,16 @@ interface SendOptions {
      * snapshot is untouched). Matching is glob-based (`**`, `*`, `?`).
      */
     contextPaths?: readonly string[];
+    /**
+     * SE1 — the permission mode for THIS run, threaded to a registered
+     * `PermissionPlugin`'s pre-tool gate. Precedence: this per-send value wins over
+     * `AgentOptions.permissionMode` (creation-time default). Modes: `default` (rules
+     * decide; unmatched ⇒ fail-closed ask), `plan` (read-only — allow rules pass,
+     * everything else denied), `acceptEdits` (auto-approve unmatched, honor explicit
+     * ask rules), `bypass` / `bypassPermissions` (allow all except an explicit deny).
+     * Absent ⇒ the plugin's own construction-time mode applies. Local runtime.
+     */
+    permissionMode?: PermissionMode;
     onStep?: (args: {
         step: ConversationStep;
     }) => void | Promise<void>;
@@ -1475,4 +1572,4 @@ interface GenerateRunResult<O> {
     };
 }
 
-export { type SDKImageDimension as $, type AgentConversationTurn as A, type RunEvent as B, type CustomTool as C, type DoomLoopThresholds as D, type RunEventSink as E, type RunGitInfo as F, type GenerateOptions as G, type RunOperation as H, type ImageBlock as I, type RunPermissionDeniedEvent as J, type RunRateLimitEvent as K, type RunStatus as L, type ModelSelection as M, type RunTaskCompletedEvent as N, type OutputProcessorContext as O, type Processor as P, type RunTaskStartedEvent as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type RunTaskUpdatedEvent as U, type RunToCompletionOptions as V, type RunToCompletionResult as W, type RunToolProgressEvent as X, type RunTripwireEvent as Y, type SDKAssistantMessage as Z, type SDKImage as _, type McpServerConfig as a, type SDKObjectDelta as a0, type SDKRequestMessage as a1, type SDKStatusMessage as a2, type SDKSystemMessage as a3, type SDKTaskMessage as a4, type SDKThinkingMessage as a5, type SDKToolUseMessage as a6, type SDKUserMessage as a7, type SDKUserMessageEvent as a8, type SendOptions as a9, type UserMessageAppendedUpdate as aA, emitRunEvent as aB, type ShellCommand as aa, type ShellConversationTurn as ab, type ShellOutput as ac, type ShellOutputDeltaUpdate as ad, type StepCompletedUpdate as ae, type StepStartedUpdate as af, type StreamToCompletionResult as ag, type SummaryCompletedUpdate as ah, type SummaryStartedUpdate as ai, type SummaryUpdate as aj, type TextBlock as ak, type TextDeltaUpdate as al, type ThinkingCompletedUpdate as am, type ThinkingDeltaUpdate as an, type ThinkingMessage as ao, type TokenDeltaUpdate as ap, type TokenUsage as aq, type ToolCall as ar, type ToolCallCompletedUpdate as as, type ToolCallStartedUpdate as at, type ToolContextMessage as au, type ToolResult as av, type ToolResultGuardOptions as aw, type ToolUseBlock as ax, type TurnEndedUpdate as ay, type UserMessage as az, type Run as b, type AssistantMessage as c, type CompletionCheck as d, type CompletionCheckResult as e, type ConversationStep as f, type ConversationTurn as g, type CostBreakdown as h, type CostSource as i, type CostStatus as j, type GenerateRunResult as k, type InputProcessorContext as l, type InteractionUpdate as m, type McpAuthConfig as n, type McpHttpServerConfig as o, type McpOAuthConfig as p, type McpStdioServerConfig as q, type MessageOrigin as r, type ModelParameterValue as s, type PartialToolCallUpdate as t, type ProcessorControls as u, type ProcessorTripwire as v, type ProcessorViolation as w, type RunCompactBoundaryEvent as x, type RunCompletionCheckEvent as y, type RunErrorDetail as z };
+export { type RunToCompletionResult as $, type AgentConversationTurn as A, type ProcessorTripwire as B, type CustomTool as C, type DoomLoopThresholds as D, type ProcessorViolation as E, type RunCompactBoundaryEvent as F, type GenerateOptions as G, type RunCompletionCheckEvent as H, type ImageBlock as I, type RunErrorDetail as J, type RunEvent as K, type RunEventSink as L, type ModelSelection as M, type RunGitInfo as N, type OutputProcessorContext as O, type Processor as P, type RunOperation as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type RunPermissionDeniedEvent as U, type RunRateLimitEvent as V, type RunStatus as W, type RunTaskCompletedEvent as X, type RunTaskStartedEvent as Y, type RunTaskUpdatedEvent as Z, type RunToCompletionOptions as _, type McpServerConfig as a, type RunToolProgressEvent as a0, type RunTripwireEvent as a1, type SDKAssistantMessage as a2, type SDKImage as a3, type SDKImageDimension as a4, type SDKObjectDelta as a5, type SDKRequestMessage as a6, type SDKStatusMessage as a7, type SDKSystemMessage as a8, type SDKTaskMessage as a9, type ToolResult as aA, type ToolResultGuardOptions as aB, type ToolUseBlock as aC, type TurnEndedUpdate as aD, type UserMessage as aE, type UserMessageAppendedUpdate as aF, applyMode as aG, emitRunEvent as aH, type SDKThinkingMessage as aa, type SDKToolUseMessage as ab, type SDKUserMessage as ac, type SDKUserMessageEvent as ad, type SendOptions as ae, type ShellCommand as af, type ShellConversationTurn as ag, type ShellOutput as ah, type ShellOutputDeltaUpdate as ai, type StepCompletedUpdate as aj, type StepStartedUpdate as ak, type StreamToCompletionResult as al, type SummaryCompletedUpdate as am, type SummaryStartedUpdate as an, type SummaryUpdate as ao, type TextBlock as ap, type TextDeltaUpdate as aq, type ThinkingCompletedUpdate as ar, type ThinkingDeltaUpdate as as, type ThinkingMessage as at, type TokenDeltaUpdate as au, type TokenUsage as av, type ToolCall as aw, type ToolCallCompletedUpdate as ax, type ToolCallStartedUpdate as ay, type ToolContextMessage as az, type Run as b, type PermissionMode as c, PermissionEngine as d, type AssistantMessage as e, type CompletionCheck as f, type CompletionCheckResult as g, type ConversationStep as h, type ConversationTurn as i, type CostBreakdown as j, type CostSource as k, type CostStatus as l, type GenerateRunResult as m, type InputProcessorContext as n, type InteractionUpdate as o, type McpAuthConfig as p, type McpHttpServerConfig as q, type McpOAuthConfig as r, type McpStdioServerConfig as s, type MessageOrigin as t, type ModelParameterValue as u, type PartialToolCallUpdate as v, type PermissionAction as w, type PermissionEngineOptions as x, type PermissionRule as y, type ProcessorControls as z };

package/dist/{run-CrHz9BAP.d.ts → run-CL5Rw6a5.d.ts}

@@ -69,6 +69,93 @@ interface ToolResultGuardOptions {
     redactPii?: boolean;
 }
 
+/**
+ * `PermissionEngine` — first-match permission rules for tool invocations.
+ *
+ * Evaluates a tool name (and optional arguments, #55) against an ordered list
+ * of rules. First matching rule wins; when no rule matches the `defaultAction`
+ * is returned. #55 — the default is now `"ask"` (FAIL-CLOSED): a permission
+ * engine that cannot positively allow must not silently allow. Opt back into
+ * the previous fail-open behavior with `{ defaultAction: "allow" }`.
+ */
+type PermissionAction = "allow" | "deny" | "ask";
+/**
+ * SE1 — a per-run permission MODE that adjusts the rule-engine verdict globally.
+ * A PURE post-processor of the verdict (no tool-safety metadata needed, so it fits
+ * a bring-your-own-tools runtime). Grounded in OpenCode (plan agent = deny-all,
+ * `dangerously-skip-permissions`) + Codex (`AskForApproval`: `OnRequest` default,
+ * `Never`, `UnlessTrusted`). See {@link applyMode} for the exact table.
+ *
+ * - `default` — verdict as-is (rules decide; unmatched ⇒ `ask`, fail-closed).
+ * - `plan` — read-only: `allow` rules pass, everything else ⇒ `deny` (mutations blocked).
+ *   NOTE: `plan` gates on the resolved verdict, so an engine configured with
+ *   `{ defaultAction: "allow" }` still yields `allow` for UNMATCHED calls under
+ *   `plan` — pair `plan` with the default fail-closed engine (`defaultAction: "ask"`)
+ *   for full read-only behavior.
+ * - `acceptEdits` — auto-approve the UNMATCHED verdict, but STILL honor an explicit
+ *   `ask` rule (a caller gates a risky tool with an ask rule). Codex `UnlessTrusted`.
+ * - `bypass` (alias `bypassPermissions`, the Anthropic-exact name) — everything ⇒
+ *   `allow` EXCEPT an explicit `deny` rule. Never asks. OpenCode
+ *   `dangerously-skip-permissions` / Codex `Never` / Anthropic `bypassPermissions`.
+ */
+type PermissionMode = "default" | "plan" | "acceptEdits" | "bypass" | "bypassPermissions";
+/**
+ * SE1 — apply a {@link PermissionMode} to a rule-engine verdict. Pure.
+ *
+ * `explicit` is `true` when the verdict came from a rule that matched by name (and
+ * args), `false` when it is the fail-closed default for an unmatched call. The flag
+ * is load-bearing for `acceptEdits`, which auto-approves the unmatched default but
+ * keeps honoring an explicit `ask` rule (unlike `bypass`, which allows even that).
+ *
+ * INVARIANT (both OpenCode + Codex): an explicit `deny` is immune to EVERY
+ * auto-approve mode — `bypass`/`acceptEdits` never un-deny.
+ */
+declare function applyMode(verdict: PermissionAction, mode: PermissionMode, explicit: boolean): PermissionAction;
+/**
+ * #55 — an argument matcher. A rule with `args` gates on the tool's argument
+ * VALUES, not just its name: an exact string, a RegExp (tested against the
+ * stringified value), or a predicate. Every declared arg must match for the
+ * rule to apply — so `{ tool: "shell", args: { command: /rm\s+-rf/ } }` denies
+ * a destructive shell call while leaving `ls` to fall through.
+ */
+type ArgMatcher = string | RegExp | ((value: unknown) => boolean);
+interface PermissionRule {
+    /** Tool name (exact string) or pattern (RegExp). */
+    tool: string | RegExp;
+    /**
+     * #55 — optional per-argument matchers. When present, the rule matches only
+     * if the tool name matches AND every declared arg predicate matches the
+     * corresponding call argument. A missing/undefined arg fails its predicate
+     * (the rule does not match) — never throws.
+     */
+    args?: Record<string, ArgMatcher>;
+    /** Action to take when rule matches. */
+    action: PermissionAction;
+}
+/** Options for {@link PermissionEngine}. */
+interface PermissionEngineOptions {
+    /**
+     * Action when no rule matches. #55 — default is now `"ask"` (fail-closed): a
+     * permission engine that cannot positively allow must not silently allow.
+     * Pass `"allow"` to restore the previous fail-open behavior.
+     */
+    readonly defaultAction?: PermissionAction;
+}
+declare class PermissionEngine {
+    #private;
+    private readonly rules;
+    private readonly defaultAction;
+    constructor(rules: PermissionRule[], options?: PermissionEngineOptions);
+    /**
+     * Evaluate a tool name (and optional arguments) against the rules. First
+     * match wins; falls back to the configured `defaultAction` (default `"ask"`,
+     * fail-closed) when no rule matches. #55 — a rule with `args` gates on the
+     * argument values, so the same tool name can resolve to different actions
+     * depending on what it is asked to do.
+     */
+    evaluate(toolName: string, args?: Record<string, unknown>, mode?: PermissionMode): PermissionAction;
+}
+
 /**
  * SE2 — typed runtime EVENT stream, ADDITIVE to the `SDKMessage` content stream.
  *
@@ -1251,6 +1338,16 @@ interface SendOptions {
      * snapshot is untouched). Matching is glob-based (`**`, `*`, `?`).
      */
     contextPaths?: readonly string[];
+    /**
+     * SE1 — the permission mode for THIS run, threaded to a registered
+     * `PermissionPlugin`'s pre-tool gate. Precedence: this per-send value wins over
+     * `AgentOptions.permissionMode` (creation-time default). Modes: `default` (rules
+     * decide; unmatched ⇒ fail-closed ask), `plan` (read-only — allow rules pass,
+     * everything else denied), `acceptEdits` (auto-approve unmatched, honor explicit
+     * ask rules), `bypass` / `bypassPermissions` (allow all except an explicit deny).
+     * Absent ⇒ the plugin's own construction-time mode applies. Local runtime.
+     */
+    permissionMode?: PermissionMode;
     onStep?: (args: {
         step: ConversationStep;
     }) => void | Promise<void>;
@@ -1475,4 +1572,4 @@ interface GenerateRunResult<O> {
     };
 }
 
-export { type SDKImageDimension as $, type AgentConversationTurn as A, type RunEvent as B, type CustomTool as C, type DoomLoopThresholds as D, type RunEventSink as E, type RunGitInfo as F, type GenerateOptions as G, type RunOperation as H, type ImageBlock as I, type RunPermissionDeniedEvent as J, type RunRateLimitEvent as K, type RunStatus as L, type ModelSelection as M, type RunTaskCompletedEvent as N, type OutputProcessorContext as O, type Processor as P, type RunTaskStartedEvent as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type RunTaskUpdatedEvent as U, type RunToCompletionOptions as V, type RunToCompletionResult as W, type RunToolProgressEvent as X, type RunTripwireEvent as Y, type SDKAssistantMessage as Z, type SDKImage as _, type McpServerConfig as a, type SDKObjectDelta as a0, type SDKRequestMessage as a1, type SDKStatusMessage as a2, type SDKSystemMessage as a3, type SDKTaskMessage as a4, type SDKThinkingMessage as a5, type SDKToolUseMessage as a6, type SDKUserMessage as a7, type SDKUserMessageEvent as a8, type SendOptions as a9, type UserMessageAppendedUpdate as aA, emitRunEvent as aB, type ShellCommand as aa, type ShellConversationTurn as ab, type ShellOutput as ac, type ShellOutputDeltaUpdate as ad, type StepCompletedUpdate as ae, type StepStartedUpdate as af, type StreamToCompletionResult as ag, type SummaryCompletedUpdate as ah, type SummaryStartedUpdate as ai, type SummaryUpdate as aj, type TextBlock as ak, type TextDeltaUpdate as al, type ThinkingCompletedUpdate as am, type ThinkingDeltaUpdate as an, type ThinkingMessage as ao, type TokenDeltaUpdate as ap, type TokenUsage as aq, type ToolCall as ar, type ToolCallCompletedUpdate as as, type ToolCallStartedUpdate as at, type ToolContextMessage as au, type ToolResult as av, type ToolResultGuardOptions as aw, type ToolUseBlock as ax, type TurnEndedUpdate as ay, type UserMessage as az, type Run as b, type AssistantMessage as c, type CompletionCheck as d, type CompletionCheckResult as e, type ConversationStep as f, type ConversationTurn as g, type CostBreakdown as h, type CostSource as i, type CostStatus as j, type GenerateRunResult as k, type InputProcessorContext as l, type InteractionUpdate as m, type McpAuthConfig as n, type McpHttpServerConfig as o, type McpOAuthConfig as p, type McpStdioServerConfig as q, type MessageOrigin as r, type ModelParameterValue as s, type PartialToolCallUpdate as t, type ProcessorControls as u, type ProcessorTripwire as v, type ProcessorViolation as w, type RunCompactBoundaryEvent as x, type RunCompletionCheckEvent as y, type RunErrorDetail as z };
+export { type RunToCompletionResult as $, type AgentConversationTurn as A, type ProcessorTripwire as B, type CustomTool as C, type DoomLoopThresholds as D, type ProcessorViolation as E, type RunCompactBoundaryEvent as F, type GenerateOptions as G, type RunCompletionCheckEvent as H, type ImageBlock as I, type RunErrorDetail as J, type RunEvent as K, type RunEventSink as L, type ModelSelection as M, type RunGitInfo as N, type OutputProcessorContext as O, type Processor as P, type RunOperation as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type RunPermissionDeniedEvent as U, type RunRateLimitEvent as V, type RunStatus as W, type RunTaskCompletedEvent as X, type RunTaskStartedEvent as Y, type RunTaskUpdatedEvent as Z, type RunToCompletionOptions as _, type McpServerConfig as a, type RunToolProgressEvent as a0, type RunTripwireEvent as a1, type SDKAssistantMessage as a2, type SDKImage as a3, type SDKImageDimension as a4, type SDKObjectDelta as a5, type SDKRequestMessage as a6, type SDKStatusMessage as a7, type SDKSystemMessage as a8, type SDKTaskMessage as a9, type ToolResult as aA, type ToolResultGuardOptions as aB, type ToolUseBlock as aC, type TurnEndedUpdate as aD, type UserMessage as aE, type UserMessageAppendedUpdate as aF, applyMode as aG, emitRunEvent as aH, type SDKThinkingMessage as aa, type SDKToolUseMessage as ab, type SDKUserMessage as ac, type SDKUserMessageEvent as ad, type SendOptions as ae, type ShellCommand as af, type ShellConversationTurn as ag, type ShellOutput as ah, type ShellOutputDeltaUpdate as ai, type StepCompletedUpdate as aj, type StepStartedUpdate as ak, type StreamToCompletionResult as al, type SummaryCompletedUpdate as am, type SummaryStartedUpdate as an, type SummaryUpdate as ao, type TextBlock as ap, type TextDeltaUpdate as aq, type ThinkingCompletedUpdate as ar, type ThinkingDeltaUpdate as as, type ThinkingMessage as at, type TokenDeltaUpdate as au, type TokenUsage as av, type ToolCall as aw, type ToolCallCompletedUpdate as ax, type ToolCallStartedUpdate as ay, type ToolContextMessage as az, type Run as b, type PermissionMode as c, PermissionEngine as d, type AssistantMessage as e, type CompletionCheck as f, type CompletionCheckResult as g, type ConversationStep as h, type ConversationTurn as i, type CostBreakdown as j, type CostSource as k, type CostStatus as l, type GenerateRunResult as m, type InputProcessorContext as n, type InteractionUpdate as o, type McpAuthConfig as p, type McpHttpServerConfig as q, type McpOAuthConfig as r, type McpStdioServerConfig as s, type MessageOrigin as t, type ModelParameterValue as u, type PartialToolCallUpdate as v, type PermissionAction as w, type PermissionEngineOptions as x, type PermissionRule as y, type ProcessorControls as z };

package/dist/types/agent.d.ts

@@ -384,6 +384,13 @@ export interface AgentOptions {
      * The two forms are mutually exclusive — pass one or the other.
      */
     plugins?: PluginsSettings | readonly Plugin[];
+    /**
+     * SE1 — the default permission mode for this agent's runs, threaded to a
+     * registered `PermissionPlugin`'s pre-tool gate. A per-send
+     * `SendOptions.permissionMode` overrides it. Absent ⇒ the plugin's own
+     * construction-time mode applies. Local runtime.
+     */
+    permissionMode?: import("../permission-engine.js").PermissionMode;
     /**
      * Skills configuration. Either a static {@link SkillsSettings} object or —
      * SE22 — a {@link SkillsResolver} evaluated per `send()` to pick skills from

package/dist/types/run.d.ts

@@ -343,6 +343,16 @@ export interface SendOptions {
      * snapshot is untouched). Matching is glob-based (`**`, `*`, `?`).
      */
     contextPaths?: readonly string[];
+    /**
+     * SE1 — the permission mode for THIS run, threaded to a registered
+     * `PermissionPlugin`'s pre-tool gate. Precedence: this per-send value wins over
+     * `AgentOptions.permissionMode` (creation-time default). Modes: `default` (rules
+     * decide; unmatched ⇒ fail-closed ask), `plan` (read-only — allow rules pass,
+     * everything else denied), `acceptEdits` (auto-approve unmatched, honor explicit
+     * ask rules), `bypass` / `bypassPermissions` (allow all except an explicit deny).
+     * Absent ⇒ the plugin's own construction-time mode applies. Local runtime.
+     */
+    permissionMode?: import("../permission-engine.js").PermissionMode;
     onStep?: (args: {
         step: ConversationStep;
     }) => void | Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "3.2.2",
+  "version": "3.3.0",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheo/theokit-sdk#readme",