@theokit/sdk 2.3.0 → 2.5.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot } from './errors-QDYUPABr.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, E as ErrorCode, m as ErrorMetadata, I as IntegrationNotConnectedError, n as InvalidTaskIdError, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-QDYUPABr.cjs';
-import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as MemoryContext, m as ConversationStorageAdapter, n as StoredMessage, B as BudgetTracker, o as MemoryProvider, p as MemoryId, q as SDKProvider } from './cron-B_H8rn-j.cjs';
-export { r as ActiveMemoryPassArgs, s as ActiveMemoryPassResult, t as AgentMemory, u as BudgetCheck, v as BudgetTotal, w as BudgetUsageEvent, x as CloudEnv, y as CloudRepo, z as ContextBudget, D as ContextManagerKind, E as ContextSnapshot, F as ContextSource, H as ContextSourceStatus, I as Cron, J as CronCreateOptions, K as CronGetOptions, N as CronJob, O as CronJobStatus, Q as CronListOptions, R as CronOperationOptions, T as CronRunOptions, U as CronRuntime, V as CronSchedulerStatus, W as CronStartOptions, X as GoalEvent, Y as GoalOptions, Z as GoalResult, _ as InvalidateCacheOptions, $ as MemoryAdapter, a0 as MemoryAdapterCapabilities, a1 as MemoryFact, a2 as MemoryProviderHandle, a3 as MemoryProviderInitOptions, a4 as MemoryRevision, a5 as MemoryToolSchema, a6 as MemoryTurnMessage, a7 as PersonalityPreset, a8 as ProviderCapability, a9 as ProviderRoute, aa as RecordSessionSummaryArgs, ab as ResolvedProviderRoute, ac as RunUntilIterator, ad as SDKAgentPlugins, ae as SDKAgentSkills, af as SDKArtifact, ag as SDKContextManager, ah as SDKPluginMetadata, ai as SDKProvidersManager, aj as SettingSource, ak as SystemPromptContext, al as SystemPromptMemoryFact, am as SystemPromptSkillRef, an as TelemetrySettings } from './cron-B_H8rn-j.cjs';
+import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as MemoryContext, m as ConversationStorageAdapter, n as StoredMessage, B as BudgetTracker, o as MemoryProvider, p as MemoryId, q as SDKProvider } from './cron-B656C3iq.cjs';
+export { r as ActiveMemoryPassArgs, s as ActiveMemoryPassResult, t as AgentMemory, u as BudgetCheck, v as BudgetTotal, w as BudgetUsageEvent, x as CloudEnv, y as CloudRepo, z as ContextBudget, D as ContextManagerKind, E as ContextSnapshot, F as ContextSource, H as ContextSourceStatus, I as Cron, J as CronCreateOptions, K as CronGetOptions, N as CronJob, O as CronJobStatus, Q as CronListOptions, R as CronOperationOptions, T as CronRunOptions, U as CronRuntime, V as CronSchedulerStatus, W as CronStartOptions, X as GoalEvent, Y as GoalOptions, Z as GoalResult, _ as InvalidateCacheOptions, $ as MemoryAdapter, a0 as MemoryAdapterCapabilities, a1 as MemoryFact, a2 as MemoryProviderHandle, a3 as MemoryProviderInitOptions, a4 as MemoryRevision, a5 as MemoryToolSchema, a6 as MemoryTurnMessage, a7 as PersonalityPreset, a8 as ProviderCapability, a9 as ProviderRoute, aa as RecordSessionSummaryArgs, ab as ResolvedProviderRoute, ac as RunUntilIterator, ad as SDKAgentPlugins, ae as SDKAgentSkills, af as SDKArtifact, ag as SDKContextManager, ah as SDKPluginMetadata, ai as SDKProvidersManager, aj as SettingSource, ak as SystemPromptContext, al as SystemPromptMemoryFact, am as SystemPromptSkillRef, an as TelemetrySettings } from './cron-B656C3iq.cjs';
 import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, S as SDKMessage } from './run-BPRYG1Id.cjs';
 export { A as AgentConversationTurn, c as AssistantMessage, d as ConversationStep, e as ConversationTurn, f as CostBreakdown, g as CostSource, h as CostStatus, I as InteractionUpdate, i as McpAuthConfig, j as McpHttpServerConfig, k as McpOAuthConfig, l as McpStdioServerConfig, m as ModelParameterValue, P as PartialToolCallUpdate, n as RunErrorDetail, o as RunGitInfo, p as RunOperation, q as RunStatus, r as RunToCompletionOptions, s as RunToCompletionResult, t as SDKAssistantMessage, u as SDKImage, v as SDKImageDimension, w as SDKObjectDelta, x as SDKRequestMessage, y as SDKStatusMessage, z as SDKSystemMessage, B as SDKTaskMessage, D as SDKThinkingMessage, E as SDKToolUseMessage, F as SDKUserMessage, G as SDKUserMessageEvent, H as SendOptions, J as ShellCommand, K as ShellConversationTurn, L as ShellOutput, N as ShellOutputDeltaUpdate, O as StepCompletedUpdate, Q as StepStartedUpdate, T as SummaryCompletedUpdate, U as SummaryStartedUpdate, V as SummaryUpdate, W as TextBlock, X as TextDeltaUpdate, Y as ThinkingCompletedUpdate, Z as ThinkingDeltaUpdate, _ as ThinkingMessage, $ as TokenDeltaUpdate, a0 as TokenUsage, a1 as ToolCall, a2 as ToolCallCompletedUpdate, a3 as ToolCallStartedUpdate, a4 as ToolResult, a5 as ToolUseBlock, a6 as TurnEndedUpdate, a7 as UserMessage, a8 as UserMessageAppendedUpdate } from './run-BPRYG1Id.cjs';
 import * as zod from 'zod';
@@ -1428,8 +1428,9 @@ declare function migrateSqliteToLance(options: MigrateOptions): Promise<MigrateR
 /**
  * `PermissionEngine` — first-match permission rules for tool invocations.
  *
- * Evaluates a tool name against an ordered list of rules.
- * First matching rule wins; default is "allow" when no rule matches.
+ * Evaluates a tool name against an ordered list of rules. First matching rule
+ * wins; when no rule matches the `defaultAction` is returned (M7-4 — default
+ * `"allow"`, opt into default-deny via `{ defaultAction: "deny" }`).
  */
 type PermissionAction = "allow" | "deny" | "ask";
 interface PermissionRule {
@@ -1438,15 +1439,49 @@ interface PermissionRule {
     /** Action to take when rule matches. */
     action: PermissionAction;
 }
+/** Options for {@link PermissionEngine}. */
+interface PermissionEngineOptions {
+    /** Action when no rule matches. Default `"allow"` (backward-compatible). M7-4. */
+    readonly defaultAction?: PermissionAction;
+}
 declare class PermissionEngine {
     private readonly rules;
-    constructor(rules: PermissionRule[]);
+    private readonly defaultAction;
+    constructor(rules: PermissionRule[], options?: PermissionEngineOptions);
     /**
-     * Evaluate a tool name against the rules. First match wins; default "allow".
+     * Evaluate a tool name against the rules. First match wins; falls back to the
+     * configured `defaultAction` (default `"allow"`) when no rule matches.
      */
     evaluate(toolName: string): PermissionAction;
 }
 
+/**
+ * M7-5 — `createPermissionPlugin`: wire a {@link PermissionEngine} into the
+ * `definePlugin` `pre_tool_call` veto seam. This is the canonical exemplar that
+ * gives `PermissionEngine` a real caller (it was previously exported-but-unwired):
+ * on each tool call the engine's verdict maps to the veto contract —
+ * `"deny"` -> block, `"ask"` -> the caller's `onAsk` resolver (or block, fail-closed),
+ * `"allow"` -> pass.
+ *
+ * @public
+ */
+
+/** Options for {@link createPermissionPlugin}. */
+interface PermissionPluginOptions {
+    /** Plugin name (default `"permission-engine"`). */
+    readonly name?: string;
+    /**
+     * Resolver for the `"ask"` verdict. Returns a veto (`{block,message}`) to deny
+     * or `undefined` to allow. Default: fail-closed (block with "requires approval").
+     */
+    readonly onAsk?: (toolName: string) => PreToolCallDecision | undefined;
+}
+/**
+ * Build a `general` plugin that vetoes tool calls per the engine's verdict.
+ * Register it on an agent's plugin manager (same as the ACP permission plugin).
+ */
+declare function createPermissionPlugin(engine: PermissionEngine, opts?: PermissionPluginOptions): Plugin;
+
 /**
  * Public security namespace (T2.1, ADR D68).
  *
@@ -2151,4 +2186,4 @@ declare function toShareGptTrajectory(result: BatchResult, options?: {
     model?: string;
 }): ShareGptTrajectory | null;
 
-export { Agent, AgentBuilder, AgentDefinition, type AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, ConversationStorageAdapter, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, EventBus, type EvictReason, FileSystemConversationStorage, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, type HookName, InMemoryConversationStorage, JobQueue, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryContext, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, PermissionEngine, type Plugin, type PluginContext, PluginsSettings, type PostAssistantReplyContext, type PreToolCallContext, type PreToolCallDecision, type PreUserSendContext, type PreUserSendResult, type ProviderProfile, ProviderRoutingSettings, type ReplayHistoryOptions, Run, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type ShareGptMessage, type ShareGptTrajectory, SkillsSettings, type Squad, type SquadOptions, type SquadRun, StoredMessage, 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, Theokit, TheokitAgentError, type TheokitRequestOptions, UsageAccumulator, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createSquad, definePlugin, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, toShareGptTrajectory, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, type AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, ConversationStorageAdapter, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, EventBus, type EvictReason, FileSystemConversationStorage, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, type HookName, InMemoryConversationStorage, JobQueue, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryContext, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, type PermissionAction, PermissionEngine, type PermissionEngineOptions, type PermissionPluginOptions, type PermissionRule, type Plugin, type PluginContext, PluginsSettings, type PostAssistantReplyContext, type PreToolCallContext, type PreToolCallDecision, type PreUserSendContext, type PreUserSendResult, type ProviderProfile, ProviderRoutingSettings, type ReplayHistoryOptions, Run, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type ShareGptMessage, type ShareGptTrajectory, SkillsSettings, type Squad, type SquadOptions, type SquadRun, StoredMessage, 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, Theokit, TheokitAgentError, type TheokitRequestOptions, UsageAccumulator, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createPermissionPlugin, createSquad, definePlugin, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, toShareGptTrajectory, withCwdMutex };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot } from './errors-DG_7CAUg.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, E as ErrorCode, m as ErrorMetadata, I as IntegrationNotConnectedError, n as InvalidTaskIdError, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-DG_7CAUg.js';
-import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as MemoryContext, m as ConversationStorageAdapter, n as StoredMessage, B as BudgetTracker, o as MemoryProvider, p as MemoryId, q as SDKProvider } from './cron-DX6HbHxd.js';
-export { r as ActiveMemoryPassArgs, s as ActiveMemoryPassResult, t as AgentMemory, u as BudgetCheck, v as BudgetTotal, w as BudgetUsageEvent, x as CloudEnv, y as CloudRepo, z as ContextBudget, D as ContextManagerKind, E as ContextSnapshot, F as ContextSource, H as ContextSourceStatus, I as Cron, J as CronCreateOptions, K as CronGetOptions, N as CronJob, O as CronJobStatus, Q as CronListOptions, R as CronOperationOptions, T as CronRunOptions, U as CronRuntime, V as CronSchedulerStatus, W as CronStartOptions, X as GoalEvent, Y as GoalOptions, Z as GoalResult, _ as InvalidateCacheOptions, $ as MemoryAdapter, a0 as MemoryAdapterCapabilities, a1 as MemoryFact, a2 as MemoryProviderHandle, a3 as MemoryProviderInitOptions, a4 as MemoryRevision, a5 as MemoryToolSchema, a6 as MemoryTurnMessage, a7 as PersonalityPreset, a8 as ProviderCapability, a9 as ProviderRoute, aa as RecordSessionSummaryArgs, ab as ResolvedProviderRoute, ac as RunUntilIterator, ad as SDKAgentPlugins, ae as SDKAgentSkills, af as SDKArtifact, ag as SDKContextManager, ah as SDKPluginMetadata, ai as SDKProvidersManager, aj as SettingSource, ak as SystemPromptContext, al as SystemPromptMemoryFact, am as SystemPromptSkillRef, an as TelemetrySettings } from './cron-DX6HbHxd.js';
+import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as MemoryContext, m as ConversationStorageAdapter, n as StoredMessage, B as BudgetTracker, o as MemoryProvider, p as MemoryId, q as SDKProvider } from './cron-CM2M9mhB.js';
+export { r as ActiveMemoryPassArgs, s as ActiveMemoryPassResult, t as AgentMemory, u as BudgetCheck, v as BudgetTotal, w as BudgetUsageEvent, x as CloudEnv, y as CloudRepo, z as ContextBudget, D as ContextManagerKind, E as ContextSnapshot, F as ContextSource, H as ContextSourceStatus, I as Cron, J as CronCreateOptions, K as CronGetOptions, N as CronJob, O as CronJobStatus, Q as CronListOptions, R as CronOperationOptions, T as CronRunOptions, U as CronRuntime, V as CronSchedulerStatus, W as CronStartOptions, X as GoalEvent, Y as GoalOptions, Z as GoalResult, _ as InvalidateCacheOptions, $ as MemoryAdapter, a0 as MemoryAdapterCapabilities, a1 as MemoryFact, a2 as MemoryProviderHandle, a3 as MemoryProviderInitOptions, a4 as MemoryRevision, a5 as MemoryToolSchema, a6 as MemoryTurnMessage, a7 as PersonalityPreset, a8 as ProviderCapability, a9 as ProviderRoute, aa as RecordSessionSummaryArgs, ab as ResolvedProviderRoute, ac as RunUntilIterator, ad as SDKAgentPlugins, ae as SDKAgentSkills, af as SDKArtifact, ag as SDKContextManager, ah as SDKPluginMetadata, ai as SDKProvidersManager, aj as SettingSource, ak as SystemPromptContext, al as SystemPromptMemoryFact, am as SystemPromptSkillRef, an as TelemetrySettings } from './cron-CM2M9mhB.js';
 import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, S as SDKMessage } from './run-BPRYG1Id.js';
 export { A as AgentConversationTurn, c as AssistantMessage, d as ConversationStep, e as ConversationTurn, f as CostBreakdown, g as CostSource, h as CostStatus, I as InteractionUpdate, i as McpAuthConfig, j as McpHttpServerConfig, k as McpOAuthConfig, l as McpStdioServerConfig, m as ModelParameterValue, P as PartialToolCallUpdate, n as RunErrorDetail, o as RunGitInfo, p as RunOperation, q as RunStatus, r as RunToCompletionOptions, s as RunToCompletionResult, t as SDKAssistantMessage, u as SDKImage, v as SDKImageDimension, w as SDKObjectDelta, x as SDKRequestMessage, y as SDKStatusMessage, z as SDKSystemMessage, B as SDKTaskMessage, D as SDKThinkingMessage, E as SDKToolUseMessage, F as SDKUserMessage, G as SDKUserMessageEvent, H as SendOptions, J as ShellCommand, K as ShellConversationTurn, L as ShellOutput, N as ShellOutputDeltaUpdate, O as StepCompletedUpdate, Q as StepStartedUpdate, T as SummaryCompletedUpdate, U as SummaryStartedUpdate, V as SummaryUpdate, W as TextBlock, X as TextDeltaUpdate, Y as ThinkingCompletedUpdate, Z as ThinkingDeltaUpdate, _ as ThinkingMessage, $ as TokenDeltaUpdate, a0 as TokenUsage, a1 as ToolCall, a2 as ToolCallCompletedUpdate, a3 as ToolCallStartedUpdate, a4 as ToolResult, a5 as ToolUseBlock, a6 as TurnEndedUpdate, a7 as UserMessage, a8 as UserMessageAppendedUpdate } from './run-BPRYG1Id.js';
 import * as zod from 'zod';
@@ -1428,8 +1428,9 @@ declare function migrateSqliteToLance(options: MigrateOptions): Promise<MigrateR
 /**
  * `PermissionEngine` — first-match permission rules for tool invocations.
  *
- * Evaluates a tool name against an ordered list of rules.
- * First matching rule wins; default is "allow" when no rule matches.
+ * Evaluates a tool name against an ordered list of rules. First matching rule
+ * wins; when no rule matches the `defaultAction` is returned (M7-4 — default
+ * `"allow"`, opt into default-deny via `{ defaultAction: "deny" }`).
  */
 type PermissionAction = "allow" | "deny" | "ask";
 interface PermissionRule {
@@ -1438,15 +1439,49 @@ interface PermissionRule {
     /** Action to take when rule matches. */
     action: PermissionAction;
 }
+/** Options for {@link PermissionEngine}. */
+interface PermissionEngineOptions {
+    /** Action when no rule matches. Default `"allow"` (backward-compatible). M7-4. */
+    readonly defaultAction?: PermissionAction;
+}
 declare class PermissionEngine {
     private readonly rules;
-    constructor(rules: PermissionRule[]);
+    private readonly defaultAction;
+    constructor(rules: PermissionRule[], options?: PermissionEngineOptions);
     /**
-     * Evaluate a tool name against the rules. First match wins; default "allow".
+     * Evaluate a tool name against the rules. First match wins; falls back to the
+     * configured `defaultAction` (default `"allow"`) when no rule matches.
      */
     evaluate(toolName: string): PermissionAction;
 }
 
+/**
+ * M7-5 — `createPermissionPlugin`: wire a {@link PermissionEngine} into the
+ * `definePlugin` `pre_tool_call` veto seam. This is the canonical exemplar that
+ * gives `PermissionEngine` a real caller (it was previously exported-but-unwired):
+ * on each tool call the engine's verdict maps to the veto contract —
+ * `"deny"` -> block, `"ask"` -> the caller's `onAsk` resolver (or block, fail-closed),
+ * `"allow"` -> pass.
+ *
+ * @public
+ */
+
+/** Options for {@link createPermissionPlugin}. */
+interface PermissionPluginOptions {
+    /** Plugin name (default `"permission-engine"`). */
+    readonly name?: string;
+    /**
+     * Resolver for the `"ask"` verdict. Returns a veto (`{block,message}`) to deny
+     * or `undefined` to allow. Default: fail-closed (block with "requires approval").
+     */
+    readonly onAsk?: (toolName: string) => PreToolCallDecision | undefined;
+}
+/**
+ * Build a `general` plugin that vetoes tool calls per the engine's verdict.
+ * Register it on an agent's plugin manager (same as the ACP permission plugin).
+ */
+declare function createPermissionPlugin(engine: PermissionEngine, opts?: PermissionPluginOptions): Plugin;
+
 /**
  * Public security namespace (T2.1, ADR D68).
  *
@@ -2151,4 +2186,4 @@ declare function toShareGptTrajectory(result: BatchResult, options?: {
     model?: string;
 }): ShareGptTrajectory | null;
 
-export { Agent, AgentBuilder, AgentDefinition, type AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, ConversationStorageAdapter, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, EventBus, type EvictReason, FileSystemConversationStorage, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, type HookName, InMemoryConversationStorage, JobQueue, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryContext, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, PermissionEngine, type Plugin, type PluginContext, PluginsSettings, type PostAssistantReplyContext, type PreToolCallContext, type PreToolCallDecision, type PreUserSendContext, type PreUserSendResult, type ProviderProfile, ProviderRoutingSettings, type ReplayHistoryOptions, Run, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type ShareGptMessage, type ShareGptTrajectory, SkillsSettings, type Squad, type SquadOptions, type SquadRun, StoredMessage, 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, Theokit, TheokitAgentError, type TheokitRequestOptions, UsageAccumulator, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createSquad, definePlugin, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, toShareGptTrajectory, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, type AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, ConversationStorageAdapter, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, EventBus, type EvictReason, FileSystemConversationStorage, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, type HookName, InMemoryConversationStorage, JobQueue, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryContext, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, type PermissionAction, PermissionEngine, type PermissionEngineOptions, type PermissionPluginOptions, type PermissionRule, type Plugin, type PluginContext, PluginsSettings, type PostAssistantReplyContext, type PreToolCallContext, type PreToolCallDecision, type PreUserSendContext, type PreUserSendResult, type ProviderProfile, ProviderRoutingSettings, type ReplayHistoryOptions, Run, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type ShareGptMessage, type ShareGptTrajectory, SkillsSettings, type Squad, type SquadOptions, type SquadRun, StoredMessage, 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, Theokit, TheokitAgentError, type TheokitRequestOptions, UsageAccumulator, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createPermissionPlugin, createSquad, definePlugin, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, toShareGptTrajectory, withCwdMutex };

package/dist/index.js

@@ -8956,6 +8956,8 @@ function parseSubagentMarkdown(raw, filename) {
   if (fields.model !== void 0) {
     definition.model = fields.model === "inherit" ? "inherit" : { id: fields.model };
   }
+  const tools = fields.tools?.split(/[\s,]+/).map((t) => t.trim()).filter((t) => t.length > 0);
+  if (tools !== void 0 && tools.length > 0) definition.tools = tools;
   return { name, definition };
 }
 function splitFrontmatter2(raw, filename) {
@@ -9119,21 +9121,24 @@ ${lines.join("\n")}
   }
 };
 
+// src/internal/runtime/skills/skills-block.ts
+function buildSkillsBlock(skills) {
+  if (skills.length === 0) return void 0;
+  const lines = skills.map(
+    (skill) => `  - ${escapeBlockBody(skill.name)}: ${escapeBlockBody(skill.description)}`
+  );
+  return `<skills>
+${lines.join("\n")}
+</skills>`;
+}
+
 // src/internal/runtime/system-prompt/sources/skills-provider.ts
 var SkillsPromptProvider = class {
   id = "skills";
   priority = 20;
   contribute(ctx) {
     if (ctx.skillsAutoInject === false) return Promise.resolve(void 0);
-    if (ctx.skills.length === 0) return Promise.resolve(void 0);
-    const lines = ctx.skills.map((skill) => {
-      const name = escapeBlockBody(skill.name);
-      const description = escapeBlockBody(skill.description);
-      return `  - ${name}: ${description}`;
-    });
-    return Promise.resolve(`<skills>
-${lines.join("\n")}
-</skills>`);
+    return Promise.resolve(buildSkillsBlock(ctx.skills));
   }
 };
 
@@ -10242,7 +10247,7 @@ async function loadPluginManifestFromMarkdown(pluginsRoot, folderName) {
   return metadata;
 }
 
-// src/internal/runtime/skills/skills-manager.ts
+// src/internal/runtime/skills/discover-skills.ts
 init_errors();
 init_path_guard();
 
@@ -10315,6 +10320,61 @@ function hasContent(value) {
   return value !== void 0 && value.trim().length > 0;
 }
 
+// src/internal/runtime/skills/discover-skills.ts
+async function discoverSkills(dir, options) {
+  let entries;
+  try {
+    entries = await readWorkspaceDir(dir, "skills_read_error", "skills directory");
+  } catch {
+    return [];
+  }
+  const skills = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    let skillDir;
+    try {
+      skillDir = safePathJoin(dir, entry.name);
+      assertNoSymlinkEscape(skillDir, dir);
+    } catch {
+      continue;
+    }
+    const skillPath = join(skillDir, "SKILL.md");
+    let raw;
+    try {
+      raw = await readFile(skillPath, "utf8");
+    } catch {
+      continue;
+    }
+    const skill = tryParseSkill(raw, entry.name, skillPath, options);
+    if (skill !== void 0) skills.push(skill);
+  }
+  return skills;
+}
+function tryParseSkill(raw, fallbackName, source, options) {
+  try {
+    const frontmatter = parseSkillFrontmatter(raw, fallbackName);
+    const skill = {
+      name: frontmatter.name,
+      description: frontmatter.description,
+      source
+    };
+    if (frontmatter.category !== void 0) skill.category = frontmatter.category;
+    if (frontmatter.dependencies !== void 0) skill.dependencies = frontmatter.dependencies;
+    return skill;
+  } catch (cause) {
+    if (cause instanceof ConfigurationError) {
+      options?.onInvalidSkill?.({
+        name: fallbackName,
+        source,
+        code: cause.code ?? "unknown",
+        message: cause.message
+      });
+      return void 0;
+    }
+    throw cause;
+  }
+}
+
 // src/internal/runtime/skills/skills-manager.ts
 var SkillsManager = class {
   constructor(cwd, _enabled, settingSourcesIncludeProject) {
@@ -10332,56 +10392,20 @@ var SkillsManager = class {
     await this.refresh();
   }
   async refresh() {
-    this.skills = [];
     const skillsRoot = join(this.cwd, ".theokit", "skills");
-    const entries = await readWorkspaceDir(skillsRoot, "skills_read_error", "skills directory");
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      let skillDir;
-      try {
-        skillDir = safePathJoin(skillsRoot, entry.name);
-        assertNoSymlinkEscape(skillDir, skillsRoot);
-      } catch {
-        continue;
-      }
-      const skillPath = join(skillDir, "SKILL.md");
-      let raw;
-      try {
-        raw = await readFile(skillPath, "utf8");
-      } catch {
-        continue;
+    this.skills = await discoverSkills(skillsRoot, {
+      onInvalidSkill: (info) => {
+        process.stderr.write(
+          `[theokit-sdk] skill ${info.name} skipped (${info.code}): ${info.message}
+`
+        );
       }
-      const metadata = tryParseSkill(raw, entry.name, skillPath);
-      if (metadata !== void 0) this.skills.push(metadata);
-    }
+    });
   }
   list() {
     return Promise.resolve(this.skills);
   }
 };
-function tryParseSkill(raw, fallbackName, source) {
-  try {
-    const frontmatter = parseSkillFrontmatter(raw, fallbackName);
-    const metadata = {
-      name: frontmatter.name,
-      description: frontmatter.description,
-      source
-    };
-    if (frontmatter.category !== void 0) metadata.category = frontmatter.category;
-    if (frontmatter.dependencies !== void 0) metadata.dependencies = frontmatter.dependencies;
-    return metadata;
-  } catch (cause) {
-    if (cause instanceof ConfigurationError) {
-      const code = cause.code ?? "unknown";
-      process.stderr.write(
-        `[theokit-sdk] skill ${fallbackName} skipped (${code}): ${cause.message}
-`
-      );
-      return void 0;
-    }
-    throw cause;
-  }
-}
 
 // src/internal/runtime/local-agent/local-agent-bootstrap.ts
 function registerLocalAgent(args) {
@@ -10794,6 +10818,7 @@ async function initLoopContext(inputs) {
     finalStatus: "finished",
     usage: new UsageAccumulator(),
     nudgeAttempts: 0,
+    stopFeedbackAttempts: 0,
     ...memoryProviderHandle !== void 0 ? { memoryProviderHandle } : {},
     ...memorySystemPromptAdditions !== void 0 ? { memorySystemPromptAdditions } : {}
   };
@@ -10938,8 +10963,9 @@ function registerLoopError(ctx, cause) {
   if (ctx.error !== void 0) return;
   const rawMessage = cause?.message;
   const message = typeof rawMessage === "string" ? rawMessage : cause instanceof Error ? cause.message : String(cause);
+  const metaCode = cause?.metadata?.code;
   const rawCode = cause?.code;
-  const code = typeof rawCode === "string" ? rawCode : void 0;
+  const code = typeof metaCode === "string" ? metaCode : typeof rawCode === "string" ? rawCode : void 0;
   ctx.error = code !== void 0 ? { message, code, cause } : { message, cause };
 }
 async function runCollectorLoop(generator, inputs, ctx) {
@@ -11735,6 +11761,7 @@ function computeUsageCost(inputs, usage) {
 
 // src/internal/agent-loop/loop.ts
 var MAX_NUDGE_ATTEMPTS = 2;
+var MAX_STOP_FEEDBACK_ATTEMPTS = 2;
 async function runAgentLoop(inputs) {
   const sendSpan = inputs.telemetry?.startSpan("agent.send", {
     agentId: inputs.agentId,
@@ -11892,6 +11919,28 @@ function shouldNudgeAndContinue(ctx, llmOutput) {
   });
   return true;
 }
+async function reflectAfterStop(inputs, ctx) {
+  const result = await inputs.hooks.run({
+    event: "stop",
+    agentId: inputs.agentId,
+    runId: inputs.runId
+  });
+  if (result.blocked) return false;
+  if (ctx.stopFeedbackAttempts >= MAX_STOP_FEEDBACK_ATTEMPTS) return false;
+  const feedback = result.decisions.find(
+    (d) => d.decision === "feedback" && (d.feedback ?? "").length > 0
+  )?.feedback;
+  if (feedback === void 0) return false;
+  ctx.stopFeedbackAttempts += 1;
+  ctx.messages.push({ role: "user", content: [{ type: "text", text: feedback }] });
+  return true;
+}
+async function finishOrReflect(inputs, ctx, llmOutput) {
+  if (shouldNudgeAndContinue(ctx, llmOutput)) return "continue";
+  if (await reflectAfterStop(inputs, ctx)) return "continue";
+  ctx.finalStatus = "finished";
+  return "done";
+}
 async function runIteration(inputs, ctx) {
   const llmOutput = await streamLlmTurn(inputs, ctx);
   accumulateUsage(ctx.usage, llmOutput);
@@ -11925,9 +11974,7 @@ async function continueOrTerminate(inputs, ctx, llmOutput) {
     await emitAssistantTextStep(inputs, ctx, llmOutput.text);
   }
   if (llmOutput.stopReason !== "tool_use" || llmOutput.toolCalls.length === 0) {
-    if (shouldNudgeAndContinue(ctx, llmOutput)) return "continue";
-    ctx.finalStatus = "finished";
-    return "done";
+    return finishOrReflect(inputs, ctx, llmOutput);
   }
   ctx.messages.push(buildAssistantTurn(llmOutput.text, llmOutput.toolCalls));
   const toolResults = await dispatchTools(inputs, ctx.tools, llmOutput.toolCalls, ctx.events);
@@ -18665,25 +18712,47 @@ async function migrateSqliteToLance2(options) {
 
 // src/permission-engine.ts
 var PermissionEngine = class {
-  constructor(rules) {
+  constructor(rules, options = {}) {
     this.rules = rules;
+    this.defaultAction = options.defaultAction ?? "allow";
   }
   rules;
+  defaultAction;
   /**
-   * Evaluate a tool name against the rules. First match wins; default "allow".
+   * Evaluate a tool name against the rules. First match wins; falls back to the
+   * configured `defaultAction` (default `"allow"`) when no rule matches.
    */
   evaluate(toolName) {
     for (const rule of this.rules) {
-      if (typeof rule.tool === "string") {
-        if (rule.tool === toolName) return rule.action;
-      } else {
-        if (rule.tool.test(toolName)) return rule.action;
-      }
+      const matches = typeof rule.tool === "string" ? rule.tool === toolName : rule.tool.test(toolName);
+      if (matches) return rule.action;
     }
-    return "allow";
+    return this.defaultAction;
   }
 };
 
+// src/permission-plugin.ts
+function createPermissionPlugin(engine, opts = {}) {
+  return definePlugin({
+    name: opts.name ?? "permission-engine",
+    version: "1.0.0",
+    kind: "general",
+    register(ctx) {
+      ctx.on("pre_tool_call", (rawCtx) => {
+        const { name } = rawCtx;
+        const action = engine.evaluate(name);
+        if (action === "deny") {
+          return { block: true, message: `denied by permission engine: ${name}` };
+        }
+        if (action === "ask") {
+          return opts.onAsk ? opts.onAsk(name) : { block: true, message: `requires approval: ${name}` };
+        }
+        return void 0;
+      });
+    }
+  });
+}
+
 // src/security.ts
 init_security();
 var Security = class {
@@ -19453,6 +19522,6 @@ function safeStringify2(v) {
   }
 }
 
-export { Agent, AgentBuilder, AgentDisposedError, AgentRunError, AuthenticationError, Budget, BudgetExceededError, ConfigurationError, Cron, EventBus, FileSystemConversationStorage, GenerateObjectError, InMemoryConversationStorage, IntegrationNotConnectedError, InvalidTaskIdError, JobQueue, Memory, MemoryAdapterError, NetworkError, PermissionEngine, RateLimitError, Security, StreamObjectError, Task, TaskNotFoundError, Theokit, TheokitAgentError, UnknownAgentError, UnsupportedBudgetOperationError, UnsupportedRunOperationError, UnsupportedTaskOperationError, UsageAccumulator, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createSquad, definePlugin, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isTransientError, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, toShareGptTrajectory, withCwdMutex };
+export { Agent, AgentBuilder, AgentDisposedError, AgentRunError, AuthenticationError, Budget, BudgetExceededError, ConfigurationError, Cron, EventBus, FileSystemConversationStorage, GenerateObjectError, InMemoryConversationStorage, IntegrationNotConnectedError, InvalidTaskIdError, JobQueue, Memory, MemoryAdapterError, NetworkError, PermissionEngine, RateLimitError, Security, StreamObjectError, Task, TaskNotFoundError, Theokit, TheokitAgentError, UnknownAgentError, UnsupportedBudgetOperationError, UnsupportedRunOperationError, UnsupportedTaskOperationError, UsageAccumulator, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createPermissionPlugin, createSquad, definePlugin, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isTransientError, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, toShareGptTrajectory, withCwdMutex };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map