@theokit/sdk 5.5.0 → 5.7.0

package/dist/index.d.cts

@@ -2,15 +2,15 @@ import { T as TheokitAgentError, E as ErrorMetadata } from './errors-base-B5g01n
 export { a as ErrorCode } from './errors-base-B5g01neU.cjs';
 import { F as RunEvent, j as CostBreakdown, at as TokenUsage, R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, T as ToolResultContentBlock, b as Run, P as Processor, c as PermissionMode, d as RunEventSink$1, S as SDKMessage } from './run-CTAdRU3U.cjs';
 export { A as AgentConversationTurn, e as AssistantMessage, f as CompletionCheck, g as CompletionCheckResult, h as ConversationStep, i as ConversationTurn, j as CostBreakdown, k as CostSource, l as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, m as GenerateRunResult, I as ImageBlock, n as InputProcessorContext, o as InteractionUpdate, p as McpAuthConfig, q as McpHttpServerConfig, r as McpOAuthConfig, s as McpStdioServerConfig, t as MessageOrigin, u as ModelParameterValue, O as OutputProcessorContext, v as PartialToolCallUpdate, w as ProcessorControls, x as ProcessorTripwire, y as ProcessorViolation, z as RunCompactBoundaryEvent, B as RunCompletionCheckEvent, E as RunErrorDetail, F as RunEvent, H as RunGitInfo, J as RunMemoryDegradedEvent, K as RunOperation, L as RunPermissionDeniedEvent, N as RunRateLimitEvent, Q as RunStatus, U as RunTaskCompletedEvent, V as RunTaskStartedEvent, W as RunTaskUpdatedEvent, X as RunTimelineEvent, Y as RunToCompletionOptions, Z as RunToCompletionResult, _ as RunToolProgressEvent, $ as RunTripwireEvent, a0 as SDKAssistantMessage, a1 as SDKImage, a2 as SDKImageDimension, a3 as SDKObjectDelta, a4 as SDKRequestMessage, a5 as SDKStatusMessage, a6 as SDKSystemMessage, a7 as SDKTaskMessage, a8 as SDKThinkingMessage, a9 as SDKToolUseMessage, aa as SDKUserMessage, ab as SDKUserMessageEvent, ac as SendOptions, ad as ShellCommand, ae as ShellConversationTurn, af as ShellOutput, ag as ShellOutputDeltaUpdate, ah as StepCompletedUpdate, ai as StepStartedUpdate, aj as StreamToCompletionResult, ak as SummaryCompletedUpdate, al as SummaryStartedUpdate, am as SummaryUpdate, an as TextBlock, ao as TextDeltaUpdate, ap as ThinkingCompletedUpdate, aq as ThinkingDeltaUpdate, ar as ThinkingMessage, as as TokenDeltaUpdate, at as TokenUsage, au as ToolCall, av as ToolCallCompletedUpdate, aw as ToolCallStartedUpdate, ax as ToolContextMessage, ay as ToolResult, az as ToolResultGuardOptions, aA as ToolUseBlock, aB as TurnEndedUpdate, aC as UserMessage, aD as UserMessageAppendedUpdate } from './run-CTAdRU3U.cjs';
-import { A as AgentOptions, L as LocalOptions, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as SkillsSettings, c as ListAgentsOptions, d as ListResult, e as SDKAgentInfo, G as GetAgentOptions, f as ListRunsOptions, g as GetRunOptions, h as AgentOperationOptions, i as AgentDescription, P as Plugin$1, j as ProviderProfile, I as InlineSkill, B as BudgetTracker, k as MemoryProvider, l as PreToolCallDecision } from './agent-DyB_lzrx.cjs';
-export { m as ActiveMemoryPassArgs, n as ActiveMemoryPassResult, o as AgentSubagentDescription, p as AgentToolDescription, q as BudgetCheck, r as BudgetTotal, s as BudgetUsageEvent, t as BuiltinToolName, u as CloudEnv, v as CloudRepo, w as CompatSource, x as CompatSourceAdapter, y as CompatSurface, z as CreateSkillSpec, H as HookName, D as MemoryProviderAgentRef, E as MemoryProviderFactory, F as MemoryProviderHandle, J as MemoryProviderInitOptions, K as PluginContext, N as PluginHookDisposer, O as PostAssistantReplyContext, Q as PostToolCallContext, R as PreToolCallContext, T as PreUserSendContext, U as PreUserSendResult, V as ProviderTransform, W as ProviderTransformContext, X as RecordSessionSummaryArgs, Y as SessionLifecycleContext, Z as SessionRecord, _ as SessionStore, $ as SettingSource, a0 as Skill, a1 as SkillsResolver, a2 as SkillsResolverContext, a3 as SystemPromptContext, a4 as SystemPromptMemoryFact, a5 as TelemetrySettings, a6 as ToolCallSummary, a7 as ToolResultTransformContext, a8 as TransformContext } from './agent-DyB_lzrx.cjs';
+import { A as AgentOptions, L as LocalOptions, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as SkillsSettings, c as ListAgentsOptions, d as ListResult, e as SDKAgentInfo, G as GetAgentOptions, f as ListRunsOptions, g as GetRunOptions, h as AgentOperationOptions, i as AgentDescription, P as Plugin$1, j as ProviderProfile, I as InlineSkill, k as Skill, B as BudgetTracker, l as MemoryProvider, m as PreToolCallDecision } from './agent-Dya5SmhY.cjs';
+export { n as ActiveMemoryPassArgs, o as ActiveMemoryPassResult, p as AgentSubagentDescription, q as AgentToolDescription, r as BudgetCheck, s as BudgetTotal, t as BudgetUsageEvent, u as BuiltinToolName, v as CloudEnv, w as CloudRepo, x as CompatSource, y as CompatSourceAdapter, z as CompatSurface, D as CreateSkillSpec, H as HookName, E as MemoryProviderAgentRef, F as MemoryProviderFactory, J as MemoryProviderHandle, K as MemoryProviderInitOptions, N as PluginContext, O as PluginHookDisposer, Q as PostAssistantReplyContext, R as PostToolCallContext, T as PreToolCallContext, U as PreUserSendContext, V as PreUserSendResult, W as ProviderTransform, X as ProviderTransformContext, Y as RecordSessionSummaryArgs, Z as SessionLifecycleContext, _ as SessionRecord, $ as SessionStore, a0 as SettingSource, a1 as Skill, a2 as SkillsResolver, a3 as SkillsResolverContext, a4 as SystemPromptContext, a5 as SystemPromptMemoryFact, a6 as TelemetrySettings, a7 as ToolCallSummary, a8 as ToolResultTransformContext, a9 as TransformContext } from './agent-Dya5SmhY.cjs';
 import * as zod from 'zod';
 import { ZodType, z } from 'zod';
 import { S as StructuredOutputError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot } from './errors-DrDEgyz1.cjs';
 export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, I as IntegrationNotConnectedError, m as InvalidTaskIdError, M as MemoryAdapterError, n as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, T as TaskNotFoundError, U as UnknownAgentError, o as UnsupportedBudgetOperationError, p as UnsupportedRunOperationError, q as UnsupportedTaskOperationError, r as isTransientError } from './errors-DrDEgyz1.cjs';
 import { P as ProviderRoutingSettings, S as SDKAgent, C as ContextSettings, a as PluginsSettings, J as JudgeResult, G as GoalOptions, b as GoalEvent, c as GoalResult, M as MemoryId, d as SDKProvider } from './sdk-agent-BOiKqOgL.cjs';
 export { A as AgentMemory, e as AgentOperation, f as ContextBudget, g as ContextManagerKind, h as ContextSnapshot, i as ContextSource, j as ContextSourceStatus, I as InvalidateCacheOptions, k as MemoryAdapter, l as MemoryAdapterCapabilities, m as MemoryContext, n as MemoryFact, o as MemoryRevision, p as MemoryToolSchema, q as MemoryTurnMessage, r as PersonalityPreset, s as ProviderCapability, t as ProviderRoute, R as ResolvedProviderRoute, u as RunUntilIterator, v as SDKAgentPlugins, w as SDKAgentSkillDetail, x as SDKAgentSkills, y as SDKArtifact, z as SDKContextManager, B as SDKPluginMetadata, D as SDKProvidersManager, E as SystemPromptSkillRef, V as Verdict } from './sdk-agent-BOiKqOgL.cjs';
-export { C as Cron, a as CronCreateOptions, b as CronGetOptions, c as CronJob, d as CronJobStatus, e as CronListOptions, f as CronOperationOptions, g as CronRunOptions, h as CronRuntime, i as CronSchedulerStatus, j as CronStartOptions } from './cron-Bgivg88c.cjs';
+export { C as Cron, a as CronCreateOptions, b as CronGetOptions, c as CronJob, d as CronJobStatus, e as CronListOptions, f as CronOperationOptions, g as CronRunOptions, h as CronRuntime, i as CronSchedulerStatus, j as CronStartOptions } from './cron-BwxDUscv.cjs';
 import { StepResult } from './workflow.cjs';
 export { Workflow, agentStep, fn } from './workflow.cjs';
 
@@ -79,6 +79,24 @@ interface CompactResult {
     preTokens: number;
     postTokens: number;
 }
+/**
+ * What a pre-compaction handler is told, and what it is given to bail out with.
+ *
+ * `trigger` is READ from the compaction that is happening, never inferred from the call site: the
+ * inference would be right today and silently wrong the first time a third caller appears.
+ *
+ * @public
+ */
+interface PreCompactContext {
+    /** The messages about to be summarised — what the handler gets a last look at. */
+    readonly messages: readonly CompressibleMessage[];
+    /** `manual` when a person asked, `auto` when a usage threshold did. */
+    readonly trigger: "manual" | "auto";
+    /** Aborted when the bound fires, so a long handler can stop rather than be merely ignored. */
+    readonly signal: AbortSignal;
+}
+/** @public */
+type PreCompactHandler = (ctx: PreCompactContext) => void | Promise<void>;
 
 /**
  * Owner: `src/` (2 of 5 importers). Derived from the import graph, not declared —
@@ -822,6 +840,17 @@ declare class Agent {
     static compact(agentId: string, options?: {
         trigger?: "manual" | "auto";
         summarize?: (messages: readonly CompressibleMessage[]) => Promise<string>;
+        /**
+         * B-082 — work to run before the transcript is rewritten, on THIS path.
+         *
+         * `/compact` reaches here, and before this option the seam existed only on the agents-layer
+         * strategy, which this path never touches. The handler is awaited, bounded, and its failure is
+         * reported without stopping compaction — the same contract `withPreCompaction` carries, not a
+         * second one.
+         */
+        onPreCompact?: PreCompactHandler;
+        onPreCompactError?: (error: unknown) => void;
+        preCompactTimeoutMs?: number;
     }): Promise<CompactResult>;
     /**
      * M51 — inject a SYNTHETIC user+assistant pair into a LOCAL session's persisted transcript WITHOUT
@@ -1596,13 +1625,22 @@ declare class Provider {
  * @public
  */
 
+/**
+ * What `skill_read` can read: a skill that carries its body, or one that knows where its body is.
+ *
+ * The tool used to take `InlineSkill` alone. A skill discovered on disk is a `Skill`, whose own
+ * declaration says "the skill BODY is never included" — so it did not fit through the door at all,
+ * and the entire on-disk surface was advertised to the model and unreadable by it: a `SKILL.md`
+ * listed by name and description, with the instructions under the frontmatter unable to arrive.
+ */
+type ReadableSkill = InlineSkill | Skill;
 /** SE36 — `SkillReadTool.create` replaces `defineSkillReadTool` (ADR 0015). @public  *
  * `SkillReadTool.create` returns a **`CustomTool`** — a skill-reading tool, not a
  * `SkillReadTool` instance.
  */
 declare class SkillReadTool {
     private constructor();
-    static create(skills: ReadonlyArray<InlineSkill>): CustomTool;
+    static create(skills: ReadonlyArray<ReadableSkill>): CustomTool;
 }
 
 /**
@@ -2114,6 +2152,87 @@ declare function emitRunEvent(sink: RunEventSink$1 | undefined, event: RunEvent)
  */
 declare function withCwdMutex<T>(key: string, fn: () => Promise<T>): Promise<T>;
 
+/**
+ * What an operator may impose. One key today, and the shape is the point: each addition is a control
+ * that already exists somewhere below and is being lifted into a tier the project cannot reach.
+ *
+ * Deliberately NOT a passthrough of arbitrary keys. A policy file whose unknown keys were carried
+ * along would let an organisation believe it had imposed something this runtime never reads — the
+ * exact belief-in-an-absent-protection this tier exists to remove.
+ */
+interface ManagedSettings {
+    /**
+     * Refuse to execute the `` !`command` `` form in a skill or command body.
+     *
+     * A skill is a markdown file a repository can carry, and its body can run shell at expansion time.
+     * Without this the only way to decline was to stop reading skills entirely.
+     */
+    disableSkillShellExecution?: boolean;
+    /**
+     * The permission posture the operator imposes on every run.
+     *
+     * `plan` is the one this exists for: an explore-only posture where edits are structurally refused.
+     * A `createPlanModeTool` already existed and it is a tool the MODEL may call — the difference is
+     * who decides. A never-prompt posture (`bypass`) is the other end, for a locked-down CI run where
+     * there is nobody to ask.
+     *
+     * It does NOT reach the standing-grant gate. `bypass` allows what the RULES would have asked
+     * about; a grant an operator recorded is not the run's to clear.
+     */
+    permissionMode?: "default" | "plan" | "acceptEdits" | "bypass";
+    /**
+     * The permission policy, as rule strings an operator writes and reviews.
+     *
+     * `{ "permissions": { "deny": ["Read(path:./.env)"] } }` — the spec's own paste-ready
+     * secret-exclusion example, which could not be expressed at all while every policy was a compiled
+     * predicate. Parsed by `parsePermissionRules` into the rules `PermissionEngine` already evaluates;
+     * the engine is unchanged and keeps its fail-closed default and its immune-to-un-deny explicit
+     * deny.
+     */
+    permissions?: {
+        readonly deny?: readonly string[];
+        readonly ask?: readonly string[];
+        readonly allow?: readonly string[];
+    };
+    /**
+     * Refuse to run ANY hook, whatever the project declared.
+     *
+     * The first control lifted, because it is the one whose absence is hardest to notice: a hook that
+     * does not run looks identical to a hook that ran and approved.
+     */
+    disableAllHooks?: boolean;
+}
+/**
+ * Where the platform keeps its managed settings.
+ *
+ * `root` exists so the precedence rule is testable: the real directories are platform-owned and a
+ * test must not write to `/etc`. Hard-coding the path inside the reader would make the thing that
+ * actually matters — that a project cannot override this file — unreachable by any test not running
+ * as root.
+ *
+ * The paths are Claude Code's own, because the file is Claude Code's format: an organisation that
+ * already deployed one should not have to deploy a second copy under a different name to get the
+ * same policy honoured here.
+ */
+declare function managedSettingsPathFor(root?: string): string;
+/**
+ * Read the deployed policy, or `{}` when none is.
+ *
+ * Absent is the ordinary case and not an error — most machines have no operator tier, and a reader
+ * that failed without one would make the feature a prerequisite for running at all.
+ *
+ * A file that EXISTS and cannot be read is different, and says so — through `diagFailure`, not
+ * `diag`. `diag` returns immediately when no sink is installed, and most consumers never install
+ * one: an organisation that deployed a policy with a typo in it would get complete silence, which is
+ * the same defect this repository just fixed for dropped hook events. A policy channel that is
+ * silent by default reports nothing about the one thing the tier exists to make certain. An organisation that deployed a
+ * policy and got silence would believe it applied; that belief is what this tier removes.
+ *
+ * SYNC for the same reason `readCompatConfigFile` is: the caller resolves this before any submanager
+ * exists to await a promise, and a once-per-agent read of one small file is the same class of work.
+ */
+declare function readManagedSettings(root?: string): ManagedSettings;
+
 /**
  * Reference `MemoryProvider` impl — no-op fallback (SDK 2.0 Phase 1 /
  * T1.2 reference implementation, mirrors `createCounterBudgetTracker`).
@@ -2780,6 +2899,22 @@ declare class PermissionEngine {
     evaluate(toolName: string, args?: Record<string, unknown>, mode?: PermissionMode): PermissionAction;
 }
 
+/** Where the floor is anchored. Defaults to the real environment; overridable so it is testable. */
+interface PermissionFloorContext {
+    readonly cwd?: string;
+    readonly home?: string;
+}
+/**
+ * Why this call may not be approved, or `undefined` when the floor has no objection.
+ *
+ * The reason NAMES the path or the target and says which tier refused, so it is not mistaken for a
+ * permissions misconfiguration — an operator who reads "denied" goes looking at their rules, and
+ * would not find anything wrong with them.
+ */
+declare function permissionFloorReason(toolName: string, args: Record<string, unknown> | undefined, context?: PermissionFloorContext): string | undefined;
+/** Whether `child` is inside `parent`. Kept for callers that need the containment question. */
+declare function isInside(parent: string, child: string): boolean;
+
 /**
  * M7-5 — `createPermissionPlugin`: wire a {@link PermissionEngine} into the
  * `definePlugin` `pre_tool_call` veto seam. This is the canonical exemplar that
@@ -2850,6 +2985,63 @@ declare class PermissionPlugin {
     static create(engine: PermissionEngine, opts?: PermissionPluginOptions): Plugin;
 }
 
+/**
+ * The permission rule LANGUAGE — a policy an operator can ship, review and diff.
+ *
+ * A policy could previously only be a compiled-in function. Measured: `allowedTools` and
+ * `disallowedTools` returned 0 files in the agents layer, and the closest facility was
+ * `CommandPolicy = (command: string) => string | null` — a code predicate. So no policy could be
+ * audited, diffed, reviewed in a pull request, or varied per environment, and `Read(./.env)` — the
+ * spec's own paste-ready secret-exclusion example — could not be expressed at all.
+ *
+ * This turns the spec's rule strings into {@link PermissionRule}s the existing engine already
+ * evaluates. The engine is unchanged: first-match, fail-closed by default, explicit deny immune to
+ * every auto-approve mode.
+ *
+ * ## The grammar, decided as a whole rather than one specifier at a time
+ *
+ * | Written | Matches |
+ * |---|---|
+ * | `Bash` | every call to `Bash` |
+ * | `Bash(npm run test:*)` | the primary argument STARTS WITH `npm run test:` |
+ * | `Read(path:./.env)` | the primary argument, read as a path, matches the glob |
+ * | `WebFetch(domain:example.com)` | the primary argument's HOST equals `example.com` |
+ * | `Bash(npm audit)` | the primary argument EQUALS `npm audit` |
+ *
+ * The specifier says how to read ITSELF. The alternative — knowing that `Read` means a path and
+ * `WebFetch` means a URL — cannot work in a runtime where the consumer brings their own tools: a
+ * rule naming a tool this SDK has never heard of must still be readable, and under a prefixed
+ * grammar it is.
+ *
+ * WHICH argument a specifier reads is the one part that cannot be derived, so the set is DECLARED:
+ * `command`, `file_path`, `path`, `url`, `query`. A tool whose argument is named something else
+ * cannot be narrowed by specifier, and that limit is stated rather than guessed around. "Read
+ * whichever argument is the only string" was the alternative, and it is worse: a rule would match an
+ * argument the operator never named, widening an allow rule exactly as often as it narrows a deny
+ * one. The escape that always works is a BARE tool name, which matches every call whatever its
+ * shape.
+ *
+ * @public
+ */
+
+/** A policy as an operator writes it: three lists of rule strings. */
+interface PermissionRuleSet {
+    readonly deny?: readonly string[];
+    readonly ask?: readonly string[];
+    readonly allow?: readonly string[];
+}
+/**
+ * Parse a rule set into engine rules, DENY first.
+ *
+ * The engine is first-match, so the order emitted here IS the precedence — and a narrow deny must
+ * survive a broad allow, or `Read` + `Read(path:./.env)` would read the secret the second line
+ * exists to protect. `ask` sits between them: it is a restriction on something otherwise allowed.
+ *
+ * @throws ConfigurationError on a rule this grammar cannot read. A policy line an operator wrote and
+ *   this runtime silently ignored is the belief-in-an-absent-protection the whole tier removes.
+ */
+declare function parsePermissionRules(set: PermissionRuleSet): PermissionRule[];
+
 /**
  * Load a project's `.env` without letting it move the credential store or switch off a trust
  * decision.
@@ -4246,4 +4438,4 @@ interface WiringRecordInput<K extends string> {
  */
 declare function recordWiring<K extends string>(input: WiringRecordInput<K>): Readonly<Record<K, WiredEntity>>;
 
-export { Agent, AgentBuilder, AgentDefinition, type AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type ApprovalDecision, type ApprovalInput, type ApprovalMode, type ApprovalOutcome, type ApprovalReason, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, type BlastRadiusDecision, type BlastRadiusInput, type BlastRadiusOutcome, type BlastRadiusReason, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, type BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, type CredentialInput, type CredentialReport, type CustomTool, type DeclaredAction, type DeclaredLayer, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, type EffectiveToolCatalog, type EnvOptOut, type EnvReachabilityAudit, type EnvReachabilityInput, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, type JudgeResult, type KeepReason, type KeptArtifact, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, type LiveAgentRegistry, LiveSessionError, type LiveSessionReason, LocalOptions, McpServerConfig, Memory, MemoryId, type MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, type OTelSpan, type PermissionAction, PermissionEngine, type PermissionEngineOptions, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, type PermissionRule, Plugin, PluginsSettings, PreToolCallDecision, type Processor, Provider, type ProviderProfile, ProviderRoutingSettings, type ReadSessionMessagesOptions, type ReapPlan, type ReapPlanInput, type ReapableArtifact, type RetentionPolicy, RetentionPolicyError, Run, RunEventSink$1 as RunEventSink, RunResult, type SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, SOVEREIGN_ENV_KEYS, Security, type SecurityFloorInput, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, type SovereignEnvKey, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, type TelemetryHandle, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, type ToolResultContentBlock, type TrustLevel, type TrustPosture, type TrustPostureInput, type TrustSource, UngatedCapabilityError, UnicodeNormalizer, type UnicodeNormalizerOptions, type UnresolvedToolSource, UsageAccumulator, type WiredEntity, type WiringRecordInput, type WithBlastRadius, applyMode, applySecurityFloor, auditEnvReachability, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, decideApproval, describeAction, describeCredential, effectiveToolNames, emitRunEvent, estimateTokens, evaluateBlastRadius, extractRawId, foldLayers, getPricingEntry, guardSessionDestruction, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, planReaping, preflightCheck, readSessionMessages, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, verifyLayerOrdering, withBlastRadius, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, type AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type ApprovalDecision, type ApprovalInput, type ApprovalMode, type ApprovalOutcome, type ApprovalReason, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, type BlastRadiusDecision, type BlastRadiusInput, type BlastRadiusOutcome, type BlastRadiusReason, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, type BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, type CredentialInput, type CredentialReport, type CustomTool, type DeclaredAction, type DeclaredLayer, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, type EffectiveToolCatalog, type EnvOptOut, type EnvReachabilityAudit, type EnvReachabilityInput, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, type JudgeResult, type KeepReason, type KeptArtifact, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, type LiveAgentRegistry, LiveSessionError, type LiveSessionReason, LocalOptions, type ManagedSettings, McpServerConfig, Memory, MemoryId, type MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, type OTelSpan, type PermissionAction, PermissionEngine, type PermissionEngineOptions, type PermissionFloorContext, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, type PermissionRule, type PermissionRuleSet, Plugin, PluginsSettings, PreToolCallDecision, type Processor, Provider, type ProviderProfile, ProviderRoutingSettings, type ReadSessionMessagesOptions, type ReapPlan, type ReapPlanInput, type ReapableArtifact, type RetentionPolicy, RetentionPolicyError, Run, RunEventSink$1 as RunEventSink, RunResult, type SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, SOVEREIGN_ENV_KEYS, Security, type SecurityFloorInput, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, type SovereignEnvKey, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, type TelemetryHandle, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, type ToolResultContentBlock, type TrustLevel, type TrustPosture, type TrustPostureInput, type TrustSource, UngatedCapabilityError, UnicodeNormalizer, type UnicodeNormalizerOptions, type UnresolvedToolSource, UsageAccumulator, type WiredEntity, type WiringRecordInput, type WithBlastRadius, applyMode, applySecurityFloor, auditEnvReachability, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, decideApproval, describeAction, describeCredential, effectiveToolNames, emitRunEvent, estimateTokens, evaluateBlastRadius, extractRawId, foldLayers, getPricingEntry, guardSessionDestruction, inferApiMode, isInside, isValidTaskId, loadProjectEnv, managedSettingsPathFor, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, parsePermissionRules, permissionFloorReason, planReaping, preflightCheck, readManagedSettings, readSessionMessages, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, verifyLayerOrdering, withBlastRadius, withCwdMutex };

package/dist/index.d.ts

@@ -2,15 +2,15 @@ import { T as TheokitAgentError, E as ErrorMetadata } from './errors-base-B5g01n
 export { a as ErrorCode } from './errors-base-B5g01neU.js';
 import { F as RunEvent, j as CostBreakdown, at as TokenUsage, R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, T as ToolResultContentBlock, b as Run, P as Processor, c as PermissionMode, d as RunEventSink$1, S as SDKMessage } from './run-CTAdRU3U.js';
 export { A as AgentConversationTurn, e as AssistantMessage, f as CompletionCheck, g as CompletionCheckResult, h as ConversationStep, i as ConversationTurn, j as CostBreakdown, k as CostSource, l as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, m as GenerateRunResult, I as ImageBlock, n as InputProcessorContext, o as InteractionUpdate, p as McpAuthConfig, q as McpHttpServerConfig, r as McpOAuthConfig, s as McpStdioServerConfig, t as MessageOrigin, u as ModelParameterValue, O as OutputProcessorContext, v as PartialToolCallUpdate, w as ProcessorControls, x as ProcessorTripwire, y as ProcessorViolation, z as RunCompactBoundaryEvent, B as RunCompletionCheckEvent, E as RunErrorDetail, F as RunEvent, H as RunGitInfo, J as RunMemoryDegradedEvent, K as RunOperation, L as RunPermissionDeniedEvent, N as RunRateLimitEvent, Q as RunStatus, U as RunTaskCompletedEvent, V as RunTaskStartedEvent, W as RunTaskUpdatedEvent, X as RunTimelineEvent, Y as RunToCompletionOptions, Z as RunToCompletionResult, _ as RunToolProgressEvent, $ as RunTripwireEvent, a0 as SDKAssistantMessage, a1 as SDKImage, a2 as SDKImageDimension, a3 as SDKObjectDelta, a4 as SDKRequestMessage, a5 as SDKStatusMessage, a6 as SDKSystemMessage, a7 as SDKTaskMessage, a8 as SDKThinkingMessage, a9 as SDKToolUseMessage, aa as SDKUserMessage, ab as SDKUserMessageEvent, ac as SendOptions, ad as ShellCommand, ae as ShellConversationTurn, af as ShellOutput, ag as ShellOutputDeltaUpdate, ah as StepCompletedUpdate, ai as StepStartedUpdate, aj as StreamToCompletionResult, ak as SummaryCompletedUpdate, al as SummaryStartedUpdate, am as SummaryUpdate, an as TextBlock, ao as TextDeltaUpdate, ap as ThinkingCompletedUpdate, aq as ThinkingDeltaUpdate, ar as ThinkingMessage, as as TokenDeltaUpdate, at as TokenUsage, au as ToolCall, av as ToolCallCompletedUpdate, aw as ToolCallStartedUpdate, ax as ToolContextMessage, ay as ToolResult, az as ToolResultGuardOptions, aA as ToolUseBlock, aB as TurnEndedUpdate, aC as UserMessage, aD as UserMessageAppendedUpdate } from './run-CTAdRU3U.js';
-import { A as AgentOptions, L as LocalOptions, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as SkillsSettings, c as ListAgentsOptions, d as ListResult, e as SDKAgentInfo, G as GetAgentOptions, f as ListRunsOptions, g as GetRunOptions, h as AgentOperationOptions, i as AgentDescription, P as Plugin$1, j as ProviderProfile, I as InlineSkill, B as BudgetTracker, k as MemoryProvider, l as PreToolCallDecision } from './agent-CjMVbhhY.js';
-export { m as ActiveMemoryPassArgs, n as ActiveMemoryPassResult, o as AgentSubagentDescription, p as AgentToolDescription, q as BudgetCheck, r as BudgetTotal, s as BudgetUsageEvent, t as BuiltinToolName, u as CloudEnv, v as CloudRepo, w as CompatSource, x as CompatSourceAdapter, y as CompatSurface, z as CreateSkillSpec, H as HookName, D as MemoryProviderAgentRef, E as MemoryProviderFactory, F as MemoryProviderHandle, J as MemoryProviderInitOptions, K as PluginContext, N as PluginHookDisposer, O as PostAssistantReplyContext, Q as PostToolCallContext, R as PreToolCallContext, T as PreUserSendContext, U as PreUserSendResult, V as ProviderTransform, W as ProviderTransformContext, X as RecordSessionSummaryArgs, Y as SessionLifecycleContext, Z as SessionRecord, _ as SessionStore, $ as SettingSource, a0 as Skill, a1 as SkillsResolver, a2 as SkillsResolverContext, a3 as SystemPromptContext, a4 as SystemPromptMemoryFact, a5 as TelemetrySettings, a6 as ToolCallSummary, a7 as ToolResultTransformContext, a8 as TransformContext } from './agent-CjMVbhhY.js';
+import { A as AgentOptions, L as LocalOptions, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as SkillsSettings, c as ListAgentsOptions, d as ListResult, e as SDKAgentInfo, G as GetAgentOptions, f as ListRunsOptions, g as GetRunOptions, h as AgentOperationOptions, i as AgentDescription, P as Plugin$1, j as ProviderProfile, I as InlineSkill, k as Skill, B as BudgetTracker, l as MemoryProvider, m as PreToolCallDecision } from './agent-Bqzdhkqr.js';
+export { n as ActiveMemoryPassArgs, o as ActiveMemoryPassResult, p as AgentSubagentDescription, q as AgentToolDescription, r as BudgetCheck, s as BudgetTotal, t as BudgetUsageEvent, u as BuiltinToolName, v as CloudEnv, w as CloudRepo, x as CompatSource, y as CompatSourceAdapter, z as CompatSurface, D as CreateSkillSpec, H as HookName, E as MemoryProviderAgentRef, F as MemoryProviderFactory, J as MemoryProviderHandle, K as MemoryProviderInitOptions, N as PluginContext, O as PluginHookDisposer, Q as PostAssistantReplyContext, R as PostToolCallContext, T as PreToolCallContext, U as PreUserSendContext, V as PreUserSendResult, W as ProviderTransform, X as ProviderTransformContext, Y as RecordSessionSummaryArgs, Z as SessionLifecycleContext, _ as SessionRecord, $ as SessionStore, a0 as SettingSource, a1 as Skill, a2 as SkillsResolver, a3 as SkillsResolverContext, a4 as SystemPromptContext, a5 as SystemPromptMemoryFact, a6 as TelemetrySettings, a7 as ToolCallSummary, a8 as ToolResultTransformContext, a9 as TransformContext } from './agent-Bqzdhkqr.js';
 import * as zod from 'zod';
 import { ZodType, z } from 'zod';
 import { S as StructuredOutputError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot } from './errors-CLOAyuiv.js';
 export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, I as IntegrationNotConnectedError, m as InvalidTaskIdError, M as MemoryAdapterError, n as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, T as TaskNotFoundError, U as UnknownAgentError, o as UnsupportedBudgetOperationError, p as UnsupportedRunOperationError, q as UnsupportedTaskOperationError, r as isTransientError } from './errors-CLOAyuiv.js';
 import { P as ProviderRoutingSettings, S as SDKAgent, C as ContextSettings, a as PluginsSettings, J as JudgeResult, G as GoalOptions, b as GoalEvent, c as GoalResult, M as MemoryId, d as SDKProvider } from './sdk-agent-D4a_BR_6.js';
 export { A as AgentMemory, e as AgentOperation, f as ContextBudget, g as ContextManagerKind, h as ContextSnapshot, i as ContextSource, j as ContextSourceStatus, I as InvalidateCacheOptions, k as MemoryAdapter, l as MemoryAdapterCapabilities, m as MemoryContext, n as MemoryFact, o as MemoryRevision, p as MemoryToolSchema, q as MemoryTurnMessage, r as PersonalityPreset, s as ProviderCapability, t as ProviderRoute, R as ResolvedProviderRoute, u as RunUntilIterator, v as SDKAgentPlugins, w as SDKAgentSkillDetail, x as SDKAgentSkills, y as SDKArtifact, z as SDKContextManager, B as SDKPluginMetadata, D as SDKProvidersManager, E as SystemPromptSkillRef, V as Verdict } from './sdk-agent-D4a_BR_6.js';
-export { C as Cron, a as CronCreateOptions, b as CronGetOptions, c as CronJob, d as CronJobStatus, e as CronListOptions, f as CronOperationOptions, g as CronRunOptions, h as CronRuntime, i as CronSchedulerStatus, j as CronStartOptions } from './cron-CNUa7PDo.js';
+export { C as Cron, a as CronCreateOptions, b as CronGetOptions, c as CronJob, d as CronJobStatus, e as CronListOptions, f as CronOperationOptions, g as CronRunOptions, h as CronRuntime, i as CronSchedulerStatus, j as CronStartOptions } from './cron-D8uB1Xh5.js';
 import { StepResult } from './workflow.js';
 export { Workflow, agentStep, fn } from './workflow.js';
 
@@ -79,6 +79,24 @@ interface CompactResult {
     preTokens: number;
     postTokens: number;
 }
+/**
+ * What a pre-compaction handler is told, and what it is given to bail out with.
+ *
+ * `trigger` is READ from the compaction that is happening, never inferred from the call site: the
+ * inference would be right today and silently wrong the first time a third caller appears.
+ *
+ * @public
+ */
+interface PreCompactContext {
+    /** The messages about to be summarised — what the handler gets a last look at. */
+    readonly messages: readonly CompressibleMessage[];
+    /** `manual` when a person asked, `auto` when a usage threshold did. */
+    readonly trigger: "manual" | "auto";
+    /** Aborted when the bound fires, so a long handler can stop rather than be merely ignored. */
+    readonly signal: AbortSignal;
+}
+/** @public */
+type PreCompactHandler = (ctx: PreCompactContext) => void | Promise<void>;
 
 /**
  * Owner: `src/` (2 of 5 importers). Derived from the import graph, not declared —
@@ -822,6 +840,17 @@ declare class Agent {
     static compact(agentId: string, options?: {
         trigger?: "manual" | "auto";
         summarize?: (messages: readonly CompressibleMessage[]) => Promise<string>;
+        /**
+         * B-082 — work to run before the transcript is rewritten, on THIS path.
+         *
+         * `/compact` reaches here, and before this option the seam existed only on the agents-layer
+         * strategy, which this path never touches. The handler is awaited, bounded, and its failure is
+         * reported without stopping compaction — the same contract `withPreCompaction` carries, not a
+         * second one.
+         */
+        onPreCompact?: PreCompactHandler;
+        onPreCompactError?: (error: unknown) => void;
+        preCompactTimeoutMs?: number;
     }): Promise<CompactResult>;
     /**
      * M51 — inject a SYNTHETIC user+assistant pair into a LOCAL session's persisted transcript WITHOUT
@@ -1596,13 +1625,22 @@ declare class Provider {
  * @public
  */
 
+/**
+ * What `skill_read` can read: a skill that carries its body, or one that knows where its body is.
+ *
+ * The tool used to take `InlineSkill` alone. A skill discovered on disk is a `Skill`, whose own
+ * declaration says "the skill BODY is never included" — so it did not fit through the door at all,
+ * and the entire on-disk surface was advertised to the model and unreadable by it: a `SKILL.md`
+ * listed by name and description, with the instructions under the frontmatter unable to arrive.
+ */
+type ReadableSkill = InlineSkill | Skill;
 /** SE36 — `SkillReadTool.create` replaces `defineSkillReadTool` (ADR 0015). @public  *
  * `SkillReadTool.create` returns a **`CustomTool`** — a skill-reading tool, not a
  * `SkillReadTool` instance.
  */
 declare class SkillReadTool {
     private constructor();
-    static create(skills: ReadonlyArray<InlineSkill>): CustomTool;
+    static create(skills: ReadonlyArray<ReadableSkill>): CustomTool;
 }
 
 /**
@@ -2114,6 +2152,87 @@ declare function emitRunEvent(sink: RunEventSink$1 | undefined, event: RunEvent)
  */
 declare function withCwdMutex<T>(key: string, fn: () => Promise<T>): Promise<T>;
 
+/**
+ * What an operator may impose. One key today, and the shape is the point: each addition is a control
+ * that already exists somewhere below and is being lifted into a tier the project cannot reach.
+ *
+ * Deliberately NOT a passthrough of arbitrary keys. A policy file whose unknown keys were carried
+ * along would let an organisation believe it had imposed something this runtime never reads — the
+ * exact belief-in-an-absent-protection this tier exists to remove.
+ */
+interface ManagedSettings {
+    /**
+     * Refuse to execute the `` !`command` `` form in a skill or command body.
+     *
+     * A skill is a markdown file a repository can carry, and its body can run shell at expansion time.
+     * Without this the only way to decline was to stop reading skills entirely.
+     */
+    disableSkillShellExecution?: boolean;
+    /**
+     * The permission posture the operator imposes on every run.
+     *
+     * `plan` is the one this exists for: an explore-only posture where edits are structurally refused.
+     * A `createPlanModeTool` already existed and it is a tool the MODEL may call — the difference is
+     * who decides. A never-prompt posture (`bypass`) is the other end, for a locked-down CI run where
+     * there is nobody to ask.
+     *
+     * It does NOT reach the standing-grant gate. `bypass` allows what the RULES would have asked
+     * about; a grant an operator recorded is not the run's to clear.
+     */
+    permissionMode?: "default" | "plan" | "acceptEdits" | "bypass";
+    /**
+     * The permission policy, as rule strings an operator writes and reviews.
+     *
+     * `{ "permissions": { "deny": ["Read(path:./.env)"] } }` — the spec's own paste-ready
+     * secret-exclusion example, which could not be expressed at all while every policy was a compiled
+     * predicate. Parsed by `parsePermissionRules` into the rules `PermissionEngine` already evaluates;
+     * the engine is unchanged and keeps its fail-closed default and its immune-to-un-deny explicit
+     * deny.
+     */
+    permissions?: {
+        readonly deny?: readonly string[];
+        readonly ask?: readonly string[];
+        readonly allow?: readonly string[];
+    };
+    /**
+     * Refuse to run ANY hook, whatever the project declared.
+     *
+     * The first control lifted, because it is the one whose absence is hardest to notice: a hook that
+     * does not run looks identical to a hook that ran and approved.
+     */
+    disableAllHooks?: boolean;
+}
+/**
+ * Where the platform keeps its managed settings.
+ *
+ * `root` exists so the precedence rule is testable: the real directories are platform-owned and a
+ * test must not write to `/etc`. Hard-coding the path inside the reader would make the thing that
+ * actually matters — that a project cannot override this file — unreachable by any test not running
+ * as root.
+ *
+ * The paths are Claude Code's own, because the file is Claude Code's format: an organisation that
+ * already deployed one should not have to deploy a second copy under a different name to get the
+ * same policy honoured here.
+ */
+declare function managedSettingsPathFor(root?: string): string;
+/**
+ * Read the deployed policy, or `{}` when none is.
+ *
+ * Absent is the ordinary case and not an error — most machines have no operator tier, and a reader
+ * that failed without one would make the feature a prerequisite for running at all.
+ *
+ * A file that EXISTS and cannot be read is different, and says so — through `diagFailure`, not
+ * `diag`. `diag` returns immediately when no sink is installed, and most consumers never install
+ * one: an organisation that deployed a policy with a typo in it would get complete silence, which is
+ * the same defect this repository just fixed for dropped hook events. A policy channel that is
+ * silent by default reports nothing about the one thing the tier exists to make certain. An organisation that deployed a
+ * policy and got silence would believe it applied; that belief is what this tier removes.
+ *
+ * SYNC for the same reason `readCompatConfigFile` is: the caller resolves this before any submanager
+ * exists to await a promise, and a once-per-agent read of one small file is the same class of work.
+ */
+declare function readManagedSettings(root?: string): ManagedSettings;
+
 /**
  * Reference `MemoryProvider` impl — no-op fallback (SDK 2.0 Phase 1 /
  * T1.2 reference implementation, mirrors `createCounterBudgetTracker`).
@@ -2780,6 +2899,22 @@ declare class PermissionEngine {
     evaluate(toolName: string, args?: Record<string, unknown>, mode?: PermissionMode): PermissionAction;
 }
 
+/** Where the floor is anchored. Defaults to the real environment; overridable so it is testable. */
+interface PermissionFloorContext {
+    readonly cwd?: string;
+    readonly home?: string;
+}
+/**
+ * Why this call may not be approved, or `undefined` when the floor has no objection.
+ *
+ * The reason NAMES the path or the target and says which tier refused, so it is not mistaken for a
+ * permissions misconfiguration — an operator who reads "denied" goes looking at their rules, and
+ * would not find anything wrong with them.
+ */
+declare function permissionFloorReason(toolName: string, args: Record<string, unknown> | undefined, context?: PermissionFloorContext): string | undefined;
+/** Whether `child` is inside `parent`. Kept for callers that need the containment question. */
+declare function isInside(parent: string, child: string): boolean;
+
 /**
  * M7-5 — `createPermissionPlugin`: wire a {@link PermissionEngine} into the
  * `definePlugin` `pre_tool_call` veto seam. This is the canonical exemplar that
@@ -2850,6 +2985,63 @@ declare class PermissionPlugin {
     static create(engine: PermissionEngine, opts?: PermissionPluginOptions): Plugin;
 }
 
+/**
+ * The permission rule LANGUAGE — a policy an operator can ship, review and diff.
+ *
+ * A policy could previously only be a compiled-in function. Measured: `allowedTools` and
+ * `disallowedTools` returned 0 files in the agents layer, and the closest facility was
+ * `CommandPolicy = (command: string) => string | null` — a code predicate. So no policy could be
+ * audited, diffed, reviewed in a pull request, or varied per environment, and `Read(./.env)` — the
+ * spec's own paste-ready secret-exclusion example — could not be expressed at all.
+ *
+ * This turns the spec's rule strings into {@link PermissionRule}s the existing engine already
+ * evaluates. The engine is unchanged: first-match, fail-closed by default, explicit deny immune to
+ * every auto-approve mode.
+ *
+ * ## The grammar, decided as a whole rather than one specifier at a time
+ *
+ * | Written | Matches |
+ * |---|---|
+ * | `Bash` | every call to `Bash` |
+ * | `Bash(npm run test:*)` | the primary argument STARTS WITH `npm run test:` |
+ * | `Read(path:./.env)` | the primary argument, read as a path, matches the glob |
+ * | `WebFetch(domain:example.com)` | the primary argument's HOST equals `example.com` |
+ * | `Bash(npm audit)` | the primary argument EQUALS `npm audit` |
+ *
+ * The specifier says how to read ITSELF. The alternative — knowing that `Read` means a path and
+ * `WebFetch` means a URL — cannot work in a runtime where the consumer brings their own tools: a
+ * rule naming a tool this SDK has never heard of must still be readable, and under a prefixed
+ * grammar it is.
+ *
+ * WHICH argument a specifier reads is the one part that cannot be derived, so the set is DECLARED:
+ * `command`, `file_path`, `path`, `url`, `query`. A tool whose argument is named something else
+ * cannot be narrowed by specifier, and that limit is stated rather than guessed around. "Read
+ * whichever argument is the only string" was the alternative, and it is worse: a rule would match an
+ * argument the operator never named, widening an allow rule exactly as often as it narrows a deny
+ * one. The escape that always works is a BARE tool name, which matches every call whatever its
+ * shape.
+ *
+ * @public
+ */
+
+/** A policy as an operator writes it: three lists of rule strings. */
+interface PermissionRuleSet {
+    readonly deny?: readonly string[];
+    readonly ask?: readonly string[];
+    readonly allow?: readonly string[];
+}
+/**
+ * Parse a rule set into engine rules, DENY first.
+ *
+ * The engine is first-match, so the order emitted here IS the precedence — and a narrow deny must
+ * survive a broad allow, or `Read` + `Read(path:./.env)` would read the secret the second line
+ * exists to protect. `ask` sits between them: it is a restriction on something otherwise allowed.
+ *
+ * @throws ConfigurationError on a rule this grammar cannot read. A policy line an operator wrote and
+ *   this runtime silently ignored is the belief-in-an-absent-protection the whole tier removes.
+ */
+declare function parsePermissionRules(set: PermissionRuleSet): PermissionRule[];
+
 /**
  * Load a project's `.env` without letting it move the credential store or switch off a trust
  * decision.
@@ -4246,4 +4438,4 @@ interface WiringRecordInput<K extends string> {
  */
 declare function recordWiring<K extends string>(input: WiringRecordInput<K>): Readonly<Record<K, WiredEntity>>;
 
-export { Agent, AgentBuilder, AgentDefinition, type AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type ApprovalDecision, type ApprovalInput, type ApprovalMode, type ApprovalOutcome, type ApprovalReason, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, type BlastRadiusDecision, type BlastRadiusInput, type BlastRadiusOutcome, type BlastRadiusReason, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, type BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, type CredentialInput, type CredentialReport, type CustomTool, type DeclaredAction, type DeclaredLayer, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, type EffectiveToolCatalog, type EnvOptOut, type EnvReachabilityAudit, type EnvReachabilityInput, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, type JudgeResult, type KeepReason, type KeptArtifact, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, type LiveAgentRegistry, LiveSessionError, type LiveSessionReason, LocalOptions, McpServerConfig, Memory, MemoryId, type MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, type OTelSpan, type PermissionAction, PermissionEngine, type PermissionEngineOptions, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, type PermissionRule, Plugin, PluginsSettings, PreToolCallDecision, type Processor, Provider, type ProviderProfile, ProviderRoutingSettings, type ReadSessionMessagesOptions, type ReapPlan, type ReapPlanInput, type ReapableArtifact, type RetentionPolicy, RetentionPolicyError, Run, RunEventSink$1 as RunEventSink, RunResult, type SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, SOVEREIGN_ENV_KEYS, Security, type SecurityFloorInput, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, type SovereignEnvKey, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, type TelemetryHandle, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, type ToolResultContentBlock, type TrustLevel, type TrustPosture, type TrustPostureInput, type TrustSource, UngatedCapabilityError, UnicodeNormalizer, type UnicodeNormalizerOptions, type UnresolvedToolSource, UsageAccumulator, type WiredEntity, type WiringRecordInput, type WithBlastRadius, applyMode, applySecurityFloor, auditEnvReachability, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, decideApproval, describeAction, describeCredential, effectiveToolNames, emitRunEvent, estimateTokens, evaluateBlastRadius, extractRawId, foldLayers, getPricingEntry, guardSessionDestruction, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, planReaping, preflightCheck, readSessionMessages, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, verifyLayerOrdering, withBlastRadius, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, type AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type ApprovalDecision, type ApprovalInput, type ApprovalMode, type ApprovalOutcome, type ApprovalReason, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, type BlastRadiusDecision, type BlastRadiusInput, type BlastRadiusOutcome, type BlastRadiusReason, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, type BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, type CredentialInput, type CredentialReport, type CustomTool, type DeclaredAction, type DeclaredLayer, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, type EffectiveToolCatalog, type EnvOptOut, type EnvReachabilityAudit, type EnvReachabilityInput, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, type JudgeResult, type KeepReason, type KeptArtifact, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, type LiveAgentRegistry, LiveSessionError, type LiveSessionReason, LocalOptions, type ManagedSettings, McpServerConfig, Memory, MemoryId, type MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, type OTelSpan, type PermissionAction, PermissionEngine, type PermissionEngineOptions, type PermissionFloorContext, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, type PermissionRule, type PermissionRuleSet, Plugin, PluginsSettings, PreToolCallDecision, type Processor, Provider, type ProviderProfile, ProviderRoutingSettings, type ReadSessionMessagesOptions, type ReapPlan, type ReapPlanInput, type ReapableArtifact, type RetentionPolicy, RetentionPolicyError, Run, RunEventSink$1 as RunEventSink, RunResult, type SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, SOVEREIGN_ENV_KEYS, Security, type SecurityFloorInput, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, type SovereignEnvKey, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, type TelemetryHandle, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, type ToolResultContentBlock, type TrustLevel, type TrustPosture, type TrustPostureInput, type TrustSource, UngatedCapabilityError, UnicodeNormalizer, type UnicodeNormalizerOptions, type UnresolvedToolSource, UsageAccumulator, type WiredEntity, type WiringRecordInput, type WithBlastRadius, applyMode, applySecurityFloor, auditEnvReachability, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, decideApproval, describeAction, describeCredential, effectiveToolNames, emitRunEvent, estimateTokens, evaluateBlastRadius, extractRawId, foldLayers, getPricingEntry, guardSessionDestruction, inferApiMode, isInside, isValidTaskId, loadProjectEnv, managedSettingsPathFor, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, parsePermissionRules, permissionFloorReason, planReaping, preflightCheck, readManagedSettings, readSessionMessages, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, verifyLayerOrdering, withBlastRadius, withCwdMutex };