@theokit/agents 13.1.0 → 13.3.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # @theokit/agents
 
+## 13.3.0
+
+### Minor Changes
+
+- b6e135e: Let a consumer read what the operator policy refuses
+
+  `disableAllHooks` shipped in 13.2.0 working and unreadable. `OperatorPolicy` and
+  `currentOperatorPolicy` were never exported, so nothing downstream could ask whether a policy was in
+  force — a diagnostic could report `hooks: none` and never `hooks: refused by operator policy`, which
+  is the ambiguity the switch exists to remove, restored one layer up in the type system.
+
+  Found by auditing all 628 exported symbols against the built `.d.ts`, distinguishing DECLARED from
+  merely MENTIONED: `OperatorPolicy` was declared in none of them, and `currentOperatorPolicy` appeared
+  only inside a docblock, where a grep reads it as present.
+
+  `OperatorPolicy`, `currentOperatorPolicy` and `mcpServerAdmitted` are now exported from
+  `@theokit/agents/config`. Nothing about the policy's enforcement changes; what changes is that a
+  consumer can see it and say so.
+
+## 13.2.0
+
+### Minor Changes
+
+- af53600: Read the settings files the declared layers correspond to
+
+  `SETTINGS_LAYERS` published a precedence stack — `user` 10, `project-shared` 20, `project-local` 30 —
+  and opened no file. Measured with controls (`loadMcpJson` 5 files, an invented term 0):
+  `settings.local.json` appeared once in this package, as a comment; `outputStyle` appeared zero times
+  here and zero times in the SDK's built output.
+
+  Three documented features were unreachable for that one reason. `settings.local.json` had a
+  precedence and no reader. `outputStyle` had a loader — shipped in this same line of work — with no
+  caller and no source for the name it takes. The session `env` had neither.
+
+  `loadSettings` opens the three files, folds them through the existing `LayeredConfig` (rather than
+  deriving a second answer to "which layer wins"), and reports which declared layers contributed
+  nothing. `resolveOutputStyle` joins the two halves so the documented path works end to end: name a
+  style in settings, get the style — and a named style with no file behind it still refuses, because
+  returning nothing there would restore the silence this work removed.
+
+  Unknown keys pass through untouched. The brief is the same mechanisms, not every configuration, and
+  a reader that dropped what it did not recognise would silently discard an operator's settings.
+
+- 88dd1ca: Translate a settings `permissions` block into rules the engine evaluates
+
+  The SDK ships a real permission engine — `PermissionEngine(rules, { defaultAction })`,
+  `PermissionRule`, `PermissionAction` — and it is a code surface: you construct it with rules. What
+  was missing was the path from the FILE to those rules. Measured: `permissions` appears in 13 SDK
+  files, and the SDK reads `settings.json` in three, of which two are sourcemaps and the third
+  describes the hooks shape. An operator writing `{ "permissions": { "deny": ["Bash(curl:*)"] } }` got
+  a file nothing translated.
+
+  `permissionRulesFromSettings` renders `Tool` and `Tool(prefix:*)` / `Tool(exact)` into anchored
+  rules, emitted deny-before-ask-before-allow because the engine is first-match-wins and an operator
+  reading their own file top to bottom has no reason to expect an `allow` above a `deny` to win.
+
+  Anything it cannot render faithfully — path globs, `~` expansion, per-tool argument names — is
+  RETURNED as unsupported with a reason, never quietly turned into a matcher that almost fires. A
+  `deny` an operator believes is in force and is not is strictly more dangerous than no rule, because
+  without one they would have written the guard themselves.
+
+- 6022a2a: An operator can refuse every hook a foreign configuration root declares
+
+  `.claude/hooks.json` runs shell commands out of a working directory that usually arrived with the
+  clone, and the operator tier had no switch for it: an operator who inherited an untrusted checkout
+  could not decline hook execution without editing files inside it. `disableAllHooks` in the managed
+  policy now drops the `hooks` surface where `resolveCompatSources` grants the root — one place, and
+  the place whose own refusal message already says that root "includes hooks.json, which executes
+  shell". It applies whether the consumer took the whole root or narrowed it, and when hooks were the
+  only surface asked for, nothing is granted at all.
+
+  Unlike every other key in this policy, a malformed value fails CLOSED: `"disableAllHooks": "true"`
+  as a string is read as `true`, with a warning naming what happened. The asymmetry is the reason —
+  fail-open is silent and unsafe, fail-closed is loud and recoverable. An absent key still means hooks
+  run, so no existing consumer changes behaviour.
+
+### Patch Changes
+
+- c692b54: Report a malformed operator policy to every reader, not just whichever ran first
+
+  `currentOperatorPolicy` memoises, and the memo took the warn channel with it: the first caller in the
+  process received the warnings and every caller after passed a channel that was never invoked.
+  Measured with a policy declaring `disableSkillShellExecution: "true"` — a string where a boolean is
+  required — the first reader heard one warning and the second heard none.
+
+  Three modules read this policy and nothing orders them, so whether an operator learned their policy
+  was malformed depended on which code path a given application happened to run first. The whole
+  operator tier is a set of refusals; one that silently fails to apply, in a process where nobody is
+  told, is the failure the tier exists to remove.
+
+  The warnings are now kept beside the policy and replayed to each reader. A well-formed policy
+  collects nothing, so nothing is replayed and no new noise appears.
+
 ## 13.1.0
 
 ### Minor Changes

package/dist/{agent-compiler-B_Z3OZel.d.ts → agent-compiler-BaOZzU7Q.d.ts}

@@ -2,7 +2,7 @@ import { InlineSkill, SystemPromptResolver, SessionStore, PermissionGate, Memory
 import { AgentDefinition } from '@theokit/sdk/subagents-loader';
 import { TheokitAgentError } from '@theokit/sdk/errors';
 import { R as ReasoningEffort, a as MemoryOptions, P as ProjectContextOptions, M as McpServersMap, H as HumanInTheLoopOptions, C as CheckpointOptions, T as ToolOptions, A as ApprovalOptions, B as BudgetOptions } from './types-C16Wuh9E.js';
-import { G as GatedSettingSource, a as GatedCompatSource } from './setting-sources-gate-DFu51i50.js';
+import { G as GatedSettingSource, a as GatedCompatSource } from './setting-sources-gate-BXdZmY78.js';
 
 /**
  * M9 (theokit-ai-first) — guardrail contract + typed errors.

package/dist/auth.js

@@ -2,15 +2,15 @@ import {
   readSecureJson,
   writeSecureJson
 } from "./chunk-D2EFYZBV.js";
-import {
-  currentOperatorPolicy
-} from "./chunk-M5DRNOIU.js";
 import {
   debugLog
 } from "./chunk-M5J3Q6YC.js";
 import {
   ConfigurationError
 } from "./chunk-U72XTMYB.js";
+import {
+  currentOperatorPolicy
+} from "./chunk-2SP5BB6U.js";
 import {
   __name
 } from "./chunk-Z4QWC7IK.js";

package/dist/{bridge-entry-vzdHNu_x.d.ts → bridge-entry-BgWauyLQ.d.ts}

@@ -1,14 +1,14 @@
 import { ExecutionContext } from '@theokit/http';
 import { c as AgentOptions, T as ToolOptions, P as ProjectContextOptions, H as HumanInTheLoopOptions, R as ReasoningEffort, M as McpServersMap } from './types-C16Wuh9E.js';
-import { a as CompiledAgentOptions, b as CompiledTool, G as Guardrail, S as SkillsSelection, H as HookApprovalGate, C as CodePlugin } from './agent-compiler-B_Z3OZel.js';
+import { a as CompiledAgentOptions, b as CompiledTool, G as Guardrail, S as SkillsSelection, H as HookApprovalGate, C as CodePlugin } from './agent-compiler-BaOZzU7Q.js';
 import { SkillsSettings, ContextSettings, SystemPromptResolver, ModelSelection, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, CustomTool, RunEventSink, MemorySettings, TelemetrySettings } from '@theokit/sdk';
-import { S as StreamEvent, f as ApprovalRequiredEvent, a4 as MaskError } from './delegation-scoring-195_ROT3.js';
+import { S as StreamEvent, f as ApprovalRequiredEvent, a4 as MaskError } from './delegation-scoring-DLsMQ4BJ.js';
 import { RetryOptions } from '@theokit/sdk/retry';
 import { SandboxPosture } from '@theokit/sdk/sandbox';
-import { A as AgentDefinition } from './define-agent-Cm7UGHx-.js';
+import { A as AgentDefinition } from './define-agent-DOZL_0uP.js';
 import { z } from 'zod';
 import { H as HookHandlers } from './hook-handlers-Cw2FsnE5.js';
-import { S as SettingSourcesSelection } from './setting-sources-gate-DFu51i50.js';
+import { S as SettingSourcesSelection } from './setting-sources-gate-BXdZmY78.js';
 import { WireChunk } from '@theokit/presenter/wire';
 import { TheokitAgentError } from '@theokit/sdk/errors';
 

package/dist/bridge.d.ts

@@ -1,8 +1,8 @@
-export { c as APPROVAL_MODES, d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinitionError, g as AgentExecutionContext, h as AgentManifest, A as AgentManifestEntry, i as AgentManifestSource, j as AgentManifestTool, b as AgentModule, k as AgentRoute, l as AgentRouteContext, m as AgentRunInfo, n as AgentsPluginOptions, o as ApiErrorContext, p as ApiErrorDecision, q as ApiErrorPolicy, r as ApprovalMode, a as ApprovalPosture, B as BeforeToolCallContext, u as CompiledContextWindow, v as ContextualTool, D as DefinitionOrThunk, w as DelegationTimeoutError, E as EphemeralAgent, L as LLMCallContext, M as McpApprovalSpec, x as McpFileError, y as McpRegistryConfig, z as McpRequestContext, F as McpSelection, P as ProcessInputContext, G as SdkAgentHandle, I as SdkMessage, J as SdkSendOptions, K as SdkTurnHandle, N as Segment, O as ShouldAutoApproveOptions, T as ToolCallVeto, Q as ToolHooks, U as ToolHooksPlugin, W as WRITE_SCOPED_TOOLS, V as agentsPlugin, X as applyPosture, Y as buildModelSelection, Z as compileAgentModule, _ as compileContextWindow, $ as compileLoadedAgentModule, a0 as compileProjectContext, a1 as compileSkills, a2 as createAgentExecutionContext, a3 as createApiErrorHandler, a4 as createSdkAgentStream, a5 as createThinkTagExtractor, a6 as createToolHooksPlugin, a7 as extractThinkTagStream, a8 as generateAgentManifest, a9 as generateAgentRoutes, aa as isAgentContext, ab as loadMcpJson, ac as mcpRegistry, ad as mcpToolApprovals, ae as projectContextMetadataOnlyKnobs, af as reasoningEffortOf, ag as resolveMcpServers, ah as runWithApiErrorHandling, ai as shouldAutoApprove, s as streamAgentUIMessages, aj as toAgentFactory, ak as translateSdkEvent, al as withClockCap, am as withEphemeralAgent } from './bridge-entry-vzdHNu_x.js';
-export { c as CompatImportUnsupportedError, a as CompiledAgentOptions, b as CompiledTool, H as HookApprovalGate, j as HookApprovalRequest, k as HookGateUnsupportedError, T as ToolWalkResult, m as ToolboxWalkResult, n as compileTools } from './agent-compiler-B_Z3OZel.js';
-export { A as AgentStopReason, d as AgentStreamEvent, e as AgentTurnMetadata, f as ApprovalRequiredEvent, g as ArtifactChunkEvent, h as ArtifactStartEvent, B as BackgroundDelegation, i as BudgetExceededError, C as CheckpointSavedEvent, k as DelegateFn, a as DelegateOptions, l as DelegationBudgetExceededError, m as DelegationError, n as DelegationPort, c as DelegationResult, D as DelegationTarget, o as DoneEvent, E as ErrorEvent, F as FileEditEvent, I as IterationEvent, P as PartialToolCallEvent, v as RunStartedEvent, w as ScoreVerdict, x as ScoredDelegation, y as Scorer, z as StateUpdateEvent, S as StreamEvent, T as TextDeltaEvent, G as ThinkingEvent, H as ToolCallEvent, J as ToolResultEvent, K as delegate, M as delegateBackground, N as delegateWithScoring, O as isApprovalRequired, Q as isDone, U as isError, V as isPartialToolCall, W as isTextDelta, X as isToolCall, Y as isToolResult, a0 as presentUIMessageStream, a3 as streamAgentResponse } from './delegation-scoring-195_ROT3.js';
-export { a as AGENT_BRAND, A as AgentDefinition, D as DefineAgentConfig, I as InferAgentInput, b as InferAgentToolNames, c as compileAgentDefinition, i as isAgentDefinition } from './define-agent-Cm7UGHx-.js';
-export { C as CompatSurface, a as GatedCompatSource, G as GatedSettingSource, P as ProjectSettingsGrant, R as ResolvedCompatSource, b as SettingSourceCapability, S as SettingSourcesSelection, U as UntrustedSettingSourceError, r as resolveCompatSources, c as resolveSettingSources } from './setting-sources-gate-DFu51i50.js';
+export { c as APPROVAL_MODES, d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinitionError, g as AgentExecutionContext, h as AgentManifest, A as AgentManifestEntry, i as AgentManifestSource, j as AgentManifestTool, b as AgentModule, k as AgentRoute, l as AgentRouteContext, m as AgentRunInfo, n as AgentsPluginOptions, o as ApiErrorContext, p as ApiErrorDecision, q as ApiErrorPolicy, r as ApprovalMode, a as ApprovalPosture, B as BeforeToolCallContext, u as CompiledContextWindow, v as ContextualTool, D as DefinitionOrThunk, w as DelegationTimeoutError, E as EphemeralAgent, L as LLMCallContext, M as McpApprovalSpec, x as McpFileError, y as McpRegistryConfig, z as McpRequestContext, F as McpSelection, P as ProcessInputContext, G as SdkAgentHandle, I as SdkMessage, J as SdkSendOptions, K as SdkTurnHandle, N as Segment, O as ShouldAutoApproveOptions, T as ToolCallVeto, Q as ToolHooks, U as ToolHooksPlugin, W as WRITE_SCOPED_TOOLS, V as agentsPlugin, X as applyPosture, Y as buildModelSelection, Z as compileAgentModule, _ as compileContextWindow, $ as compileLoadedAgentModule, a0 as compileProjectContext, a1 as compileSkills, a2 as createAgentExecutionContext, a3 as createApiErrorHandler, a4 as createSdkAgentStream, a5 as createThinkTagExtractor, a6 as createToolHooksPlugin, a7 as extractThinkTagStream, a8 as generateAgentManifest, a9 as generateAgentRoutes, aa as isAgentContext, ab as loadMcpJson, ac as mcpRegistry, ad as mcpToolApprovals, ae as projectContextMetadataOnlyKnobs, af as reasoningEffortOf, ag as resolveMcpServers, ah as runWithApiErrorHandling, ai as shouldAutoApprove, s as streamAgentUIMessages, aj as toAgentFactory, ak as translateSdkEvent, al as withClockCap, am as withEphemeralAgent } from './bridge-entry-BgWauyLQ.js';
+export { c as CompatImportUnsupportedError, a as CompiledAgentOptions, b as CompiledTool, H as HookApprovalGate, j as HookApprovalRequest, k as HookGateUnsupportedError, T as ToolWalkResult, m as ToolboxWalkResult, n as compileTools } from './agent-compiler-BaOZzU7Q.js';
+export { A as AgentStopReason, d as AgentStreamEvent, e as AgentTurnMetadata, f as ApprovalRequiredEvent, g as ArtifactChunkEvent, h as ArtifactStartEvent, B as BackgroundDelegation, i as BudgetExceededError, C as CheckpointSavedEvent, k as DelegateFn, a as DelegateOptions, l as DelegationBudgetExceededError, m as DelegationError, n as DelegationPort, c as DelegationResult, D as DelegationTarget, o as DoneEvent, E as ErrorEvent, F as FileEditEvent, I as IterationEvent, P as PartialToolCallEvent, v as RunStartedEvent, w as ScoreVerdict, x as ScoredDelegation, y as Scorer, z as StateUpdateEvent, S as StreamEvent, T as TextDeltaEvent, G as ThinkingEvent, H as ToolCallEvent, J as ToolResultEvent, K as delegate, M as delegateBackground, N as delegateWithScoring, O as isApprovalRequired, Q as isDone, U as isError, V as isPartialToolCall, W as isTextDelta, X as isToolCall, Y as isToolResult, a0 as presentUIMessageStream, a3 as streamAgentResponse } from './delegation-scoring-DLsMQ4BJ.js';
+export { a as AGENT_BRAND, A as AgentDefinition, D as DefineAgentConfig, I as InferAgentInput, b as InferAgentToolNames, c as compileAgentDefinition, i as isAgentDefinition } from './define-agent-DOZL_0uP.js';
+export { C as CompatSurface, a as GatedCompatSource, G as GatedSettingSource, P as ProjectSettingsGrant, R as ResolvedCompatSource, b as SettingSourceCapability, S as SettingSourcesSelection, U as UntrustedSettingSourceError, r as resolveCompatSources, c as resolveSettingSources } from './setting-sources-gate-BXdZmY78.js';
 import '@theokit/http';
 import './types-C16Wuh9E.js';
 import '@theokit/sdk';

package/dist/bridge.js

@@ -29,8 +29,7 @@ import {
   runWithApiErrorHandling,
   streamAgentResponse,
   streamAgentUIMessages
-} from "./chunk-AAW4I45J.js";
-import "./chunk-M5DRNOIU.js";
+} from "./chunk-SL3QW5WZ.js";
 import {
   APPROVAL_MODES,
   BudgetExceededError,
@@ -57,7 +56,7 @@ import {
   translateSdkEvent,
   withClockCap,
   withEphemeralAgent
-} from "./chunk-HBHZV3KL.js";
+} from "./chunk-CBP72LFM.js";
 import "./chunk-MJ6FRILJ.js";
 import {
   AGENT_BRAND,
@@ -66,9 +65,10 @@ import {
   isAgentDefinition,
   resolveCompatSources,
   resolveSettingSources
-} from "./chunk-PMMOOXR6.js";
+} from "./chunk-PYVLRSXZ.js";
 import "./chunk-M5J3Q6YC.js";
 import "./chunk-U72XTMYB.js";
+import "./chunk-2SP5BB6U.js";
 import "./chunk-OXNDJSAJ.js";
 import "./chunk-Z4QWC7IK.js";
 export {

package/dist/{chunk-M5DRNOIU.js → chunk-2SP5BB6U.js}

@@ -7,6 +7,7 @@ import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 var KNOWN_KEYS = /* @__PURE__ */ new Set([
   "disableSkillShellExecution",
+  "disableAllHooks",
   "deniedMcpServers",
   "allowedMcpServers",
   "apiKeyHelper"
@@ -73,13 +74,23 @@ function applyPolicyKey(out, key, value, path, warn) {
     if (key === "apiKeyHelper") out.apiKeyHelper = value.trim();
     return;
   }
-  if (typeof value !== "boolean") {
-    warn(`${path} declares "${key}" as ${typeof value}, not a boolean \u2014 it is NOT being applied.`);
+  applyBooleanKey(out, key, value, path, warn);
+}
+__name(applyPolicyKey, "applyPolicyKey");
+function applyBooleanKey(out, key, value, path, warn) {
+  if (typeof value === "boolean") {
+    if (key === "disableSkillShellExecution") out.disableSkillShellExecution = value;
+    if (key === "disableAllHooks") out.disableAllHooks = value;
+    return;
+  }
+  if (key === "disableAllHooks") {
+    out.disableAllHooks = true;
+    warn(`${path} declares "disableAllHooks" as ${typeof value}, not a boolean. It is being read as TRUE \u2014 hooks are refused \u2014 because a security switch that silently fails open is worse than one that fails visibly. Write \`true\` or \`false\` to say which you meant.`);
     return;
   }
-  if (key === "disableSkillShellExecution") out.disableSkillShellExecution = value;
+  warn(`${path} declares "${key}" as ${typeof value}, not a boolean \u2014 it is NOT being applied.`);
 }
-__name(applyPolicyKey, "applyPolicyKey");
+__name(applyBooleanKey, "applyBooleanKey");
 function readStringList(value, key, path, warn) {
   if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
     return value;
@@ -90,8 +101,18 @@ function readStringList(value, key, path, warn) {
 __name(readStringList, "readStringList");
 var cached;
 var rootOverride;
+var cachedWarnings = [];
 function currentOperatorPolicy(warn) {
-  cached ??= readOperatorPolicy(rootOverride, warn);
+  if (cached === void 0) {
+    const collected = [];
+    cached = readOperatorPolicy(rootOverride, (message) => {
+      collected.push(message);
+      warn(message);
+    });
+    cachedWarnings = collected;
+    return cached;
+  }
+  for (const message of cachedWarnings) warn(message);
   return cached;
 }
 __name(currentOperatorPolicy, "currentOperatorPolicy");
@@ -106,4 +127,4 @@ export {
   currentOperatorPolicy,
   mcpServerAdmitted
 };
-//# sourceMappingURL=chunk-M5DRNOIU.js.map
+//# sourceMappingURL=chunk-2SP5BB6U.js.map

package/dist/chunk-2SP5BB6U.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config/operator-policy.ts"],"mappings":";;;;;AA4BA,SAASA,YAAYC,oBAAoB;AACzC,SAASC,YAAY;AA8DrB,IAAMC,aAAa,oBAAIC,IAA0B;EAC/C;EACA;EACA;EACA;EACA;CACD;AAGD,IAAMC,cAAc,oBAAID,IAA0B;EAAC;CAAe;AAGlE,IAAME,YAAY,oBAAIF,IAA0B;EAAC;EAAoB;CAAoB;AASzF,SAASG,mBAAmBC,MAAa;AACvC,MAAIA,SAASC,OAAW,QAAOC,KAAKF,MAAM,eAAe,uBAAA;AACzD,MAAIG,QAAQC,aAAa,UAAU;AACjC,WAAO;EACT;AACA,MAAID,QAAQC,aAAa,SAAS;AAChC,WAAOF,KAAKC,QAAQE,IAAIC,eAAe,mBAAmB,cAAc,uBAAA;EAC1E;AACA,SAAO;AACT;AATSP;AAqBT,SAASQ,mBACPP,MACAQ,MAA+B;AAE/B,QAAMC,OAAOV,mBAAmBC,IAAAA;AAChC,QAAMU,SAASC,mBAAmBF,MAAMD,IAAAA;AACxC,MAAIE,WAAWT,OAAW,QAAO,CAAC;AAElC,QAAMW,MAAsB,CAAC;AAC7B,aAAW,CAACC,KAAKC,KAAAA,KAAUC,OAAOC,QAAQN,MAAAA,GAAS;AACjDO,mBAAeL,KAAKC,KAA6BC,OAAOL,MAAMD,IAAAA;EAChE;AACA,SAAOI;AACT;AAbSL;AA0BT,SAASI,mBACPF,MACAD,MAA+B;AAG/B,MAAI,CAACU,WAAWT,IAAAA,EAAO,QAAOR;AAE9B,MAAIS;AACJ,MAAI;AAEFA,aAASS,KAAKC,MAAMC,aAAaZ,MAAM,MAAA,CAAA;EACzC,SAASa,OAAO;AACdd,SACE,GAAGC,IAAAA,+BAAoCa,MAAgBC,OAAO,+CAA0C;AAE1G,WAAOtB;EACT;AACA,MAAI,OAAOS,WAAW,YAAYA,WAAW,QAAQc,MAAMC,QAAQf,MAAAA,GAAS;AAC1EF,SAAK,GAAGC,IAAAA,mEAAkE;AAC1E,WAAOR;EACT;AACA,SAAOS;AACT;AAtBSC;AAgCT,SAASM,eACPL,KACAC,KACAC,OACAL,MACAD,MAA+B;AAE/B,MAAI,CAACb,WAAW+B,IAAIb,GAAAA,EAAM;AAC1B,MAAIf,UAAU4B,IAAIb,GAAAA,GAAM;AACtB,UAAMc,OAAOC,eAAed,OAAOD,KAAKJ,MAAMD,IAAAA;AAC9C,QAAImB,SAAS1B,OAAW;AACxB,QAAIY,QAAQ,mBAAoBD,KAAIiB,mBAAmBF;AACvD,QAAId,QAAQ,oBAAqBD,KAAIkB,oBAAoBH;AACzD;EACF;AACA,MAAI9B,YAAY6B,IAAIb,GAAAA,GAAM;AAIxB,QAAI,OAAOC,UAAU,YAAYA,MAAMiB,KAAI,EAAGC,WAAW,GAAG;AAC1DxB,WACE,GAAGC,IAAAA,cAAkBI,GAAAA,QAChB,OAAOC,UAAU,WAAW,oBAAoB,OAAOA,KAAAA,sDACX;AAEnD;IACF;AACA,QAAID,QAAQ,eAAgBD,KAAIqB,eAAenB,MAAMiB,KAAI;AACzD;EACF;AACAG,kBAAgBtB,KAAKC,KAAKC,OAAOL,MAAMD,IAAAA;AACzC;AA/BSS;AA0CT,SAASiB,gBACPtB,KACAC,KACAC,OACAL,MACAD,MAA+B;AAE/B,MAAI,OAAOM,UAAU,WAAW;AAC9B,QAAID,QAAQ,6BAA8BD,KAAIuB,6BAA6BrB;AAC3E,QAAID,QAAQ,kBAAmBD,KAAIwB,kBAAkBtB;AACrD;EACF;AAIA,MAAID,QAAQ,mBAAmB;AAC7BD,QAAIwB,kBAAkB;AACtB5B,SACE,GAAGC,IAAAA,kCAAsC,OAAOK,KAAAA,wNAEoC;AAEtF;EACF;AACAN,OAAK,GAAGC,IAAAA,cAAkBI,GAAAA,QAAW,OAAOC,KAAAA,iDAAiD;AAC/F;AAzBSoB;AAiCT,SAASN,eACPd,OACAD,KACAJ,MACAD,MAA+B;AAE/B,MAAIgB,MAAMC,QAAQX,KAAAA,KAAUA,MAAMuB,MAAM,CAACC,MAAM,OAAOA,MAAM,QAAA,GAAW;AACrE,WAAOxB;EACT;AACAN,OACE,GAAGC,IAAAA,cAAkBI,GAAAA,QAChBW,MAAMC,QAAQX,KAAAA,IAAS,qCAAqC,OAAOA,KAAAA,2DAClB;AAExD,SAAOb;AACT;AAfS2B;AAwBT,IAAIW;AACJ,IAAIC;AAmBJ,IAAIC,iBAAoC,CAAA;AAEjC,SAASC,sBAAsBlC,MAA+B;AACnE,MAAI+B,WAAWtC,QAAW;AACxB,UAAM0C,YAAsB,CAAA;AAC5BJ,aAAShC,mBAAmBiC,cAAc,CAACjB,YAAAA;AACzCoB,gBAAUC,KAAKrB,OAAAA;AACff,WAAKe,OAAAA;IACP,CAAA;AACAkB,qBAAiBE;AACjB,WAAOJ;EACT;AAGA,aAAWhB,WAAWkB,eAAgBjC,MAAKe,OAAAA;AAC3C,SAAOgB;AACT;AAdgBG;AAwCT,SAASG,kBAAkBC,MAAcC,QAAsB;AACpE,MAAIA,OAAOC,kBAAkBC,SAASH,IAAAA,MAAU,KAAM,QAAO;AAC7D,MAAIC,OAAOG,sBAAsBC,OAAW,QAAO;AACnD,SAAOJ,OAAOG,kBAAkBD,SAASH,IAAAA;AAC3C;AAJgBD;","names":["existsSync","readFileSync","join","KNOWN_KEYS","Set","STRING_KEYS","LIST_KEYS","operatorPolicyPath","root","undefined","join","process","platform","env","PROGRAMDATA","readOperatorPolicy","warn","path","parsed","readPolicyDocument","out","key","value","Object","entries","applyPolicyKey","existsSync","JSON","parse","readFileSync","cause","message","Array","isArray","has","list","readStringList","deniedMcpServers","allowedMcpServers","trim","length","apiKeyHelper","applyBooleanKey","disableSkillShellExecution","disableAllHooks","every","v","cached","rootOverride","cachedWarnings","currentOperatorPolicy","collected","push","mcpServerAdmitted","name","policy","deniedMcpServers","includes","allowedMcpServers","undefined"]}

package/dist/{chunk-HBHZV3KL.js → chunk-CBP72LFM.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-MJ6FRILJ.js";
 import {
   compileAgentDefinition
-} from "./chunk-PMMOOXR6.js";
+} from "./chunk-PYVLRSXZ.js";
 import {
   debugLog
 } from "./chunk-M5J3Q6YC.js";
@@ -2777,4 +2777,4 @@ export {
   delegateBackground,
   delegateWithScoring
 };
-//# sourceMappingURL=chunk-HBHZV3KL.js.map
+//# sourceMappingURL=chunk-CBP72LFM.js.map

package/dist/{chunk-PMMOOXR6.js → chunk-PYVLRSXZ.js}

@@ -1,9 +1,20 @@
+import {
+  currentOperatorPolicy
+} from "./chunk-2SP5BB6U.js";
 import {
   __name
 } from "./chunk-Z4QWC7IK.js";
 
 // src/bridge/setting-sources-gate.ts
 import { TheokitAgentError } from "@theokit/sdk/errors";
+var EVERY_SURFACE = [
+  "commands",
+  "hooks",
+  "plugins",
+  "skills",
+  "subagents"
+];
+var IGNORE_WARNING = /* @__PURE__ */ __name(() => void 0, "IGNORE_WARNING");
 var UntrustedSettingSourceError = class extends TheokitAgentError {
   static {
     __name(this, "UntrustedSettingSourceError");
@@ -39,7 +50,7 @@ function resolveSettingSources(selection) {
   return sources;
 }
 __name(resolveSettingSources, "resolveSettingSources");
-function resolveCompatSources(selection) {
+function resolveCompatSources(selection, onWarn) {
   if (selection?.claudeCode === void 0) return [];
   const posture = selection.claudeCode.trustedBy;
   if (!posture.allows.projectSettings) {
@@ -50,6 +61,15 @@ function resolveCompatSources(selection) {
     throw new UntrustedSettingSourceError(`\`claudeCode.import\` is an empty list, which could mean "no surfaces" or "unset, so all of them" \u2014 and the two differ by whether <cwd>/.claude/hooks.json executes. Name the surfaces you want, or omit \`import\` to take the whole root (usetheokit/theokit#686).`, selection.claudeCode.trustedBy.source, "projectSettings");
   }
   const gated = /* @__PURE__ */ __name((source) => source, "gated");
+  if (currentOperatorPolicy(onWarn ?? IGNORE_WARNING).disableAllHooks === true) {
+    const kept = (surfaces ?? EVERY_SURFACE).filter((surface) => surface !== "hooks");
+    return kept.length === 0 ? [] : [
+      gated({
+        kind: "claude-code",
+        import: kept
+      })
+    ];
+  }
   if (surfaces !== void 0) return [
     gated({
       kind: "claude-code",
@@ -255,4 +275,4 @@ export {
   compileAgentDefinition,
   compileSkillsSelection
 };
-//# sourceMappingURL=chunk-PMMOOXR6.js.map
+//# sourceMappingURL=chunk-PYVLRSXZ.js.map

package/dist/chunk-PYVLRSXZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bridge/setting-sources-gate.ts","../src/bridge/define-agent.ts"],"mappings":"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","names":["TheokitAgentError","EVERY_SURFACE","IGNORE_WARNING","undefined","UntrustedSettingSourceError","TheokitAgentError","name","message","trustSource","capability","resolveSettingSources","selection","sources","gated","root","user","push","grant","project","posture","trustedBy","allows","projectSettings","level","source","pluginsGrant","plugins","resolveCompatSources","onWarn","claudeCode","surfaces","import","length","currentOperatorPolicy","disableAllHooks","kept","filter","surface","kind","AGENT_BRAND","Symbol","for","defineAgent","config","assertValidMaxIterations","maxIterations","value","undefined","Number","isInteger","Error","String","isAgentDefinition","toCompiledTool","tool","handler","compiled","name","description","inputSchema","input","ctx","sym","Object","getOwnPropertySymbols","compileAgentDefinition","def","model","reasoningEffort","systemPrompt","system","tools","map","agents","stream","context","runContext","guardrails","approvals","hitl","compileApprovals","compileSkillsSelection","skills","settingSources","resolveSettingSources","claudeCode","compatSources","resolveCompatSources","hookApproval","memory","telemetry","compileHooksAndPlugins","mcpServers","hooks","entries","filter","h","explicit","plugins","length","plugin","version","kind","register","hookName","on","skillsResolver","enabled","inline","entry","push","autoInject","toolNames","Set","t","gates","Map","toolName","options","has","join","set"]}

package/dist/{chunk-AAW4I45J.js → chunk-SL3QW5WZ.js}

@@ -1,22 +1,22 @@
-import {
-  currentOperatorPolicy,
-  mcpServerAdmitted
-} from "./chunk-M5DRNOIU.js";
 import {
   createHitlPlugin,
   createSdkAgentStream,
   moderateOutputStream,
   runInputGuards,
   textPayloadExtractor
-} from "./chunk-HBHZV3KL.js";
+} from "./chunk-CBP72LFM.js";
 import {
   compileAgentDefinition,
   defineAgent,
   isAgentDefinition
-} from "./chunk-PMMOOXR6.js";
+} from "./chunk-PYVLRSXZ.js";
 import {
   ConfigurationError
 } from "./chunk-U72XTMYB.js";
+import {
+  currentOperatorPolicy,
+  mcpServerAdmitted
+} from "./chunk-2SP5BB6U.js";
 import {
   __name
 } from "./chunk-Z4QWC7IK.js";
@@ -1340,4 +1340,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-AAW4I45J.js.map
+//# sourceMappingURL=chunk-SL3QW5WZ.js.map

package/dist/config.d.ts

@@ -1,8 +1,8 @@
 import { TheokitAgentError } from '@theokit/sdk/errors';
 import { z } from 'zod';
-import { TrustPosture, LayerValues } from '@theokit/sdk';
-export { DeclaredLayer, LayerValues } from '@theokit/sdk';
-import { R as ResolvedCompatSource } from './setting-sources-gate-DFu51i50.js';
+import { TrustPosture, LayerValues, PermissionRule } from '@theokit/sdk';
+export { DeclaredLayer, LayerValues, PermissionAction, PermissionRule } from '@theokit/sdk';
+import { R as ResolvedCompatSource } from './setting-sources-gate-BXdZmY78.js';
 export { resolveEffectiveContextWindow as effectiveContextWindow } from '@theokit/sdk/compaction';
 
 /**
@@ -724,6 +724,182 @@ interface LoadOutputStyleInput {
  * were searched.
  */
 declare function loadOutputStyle(input: LoadOutputStyleInput): OutputStyle | undefined;
+/**
+ * The style the project's settings name, read from the project's style files.
+ *
+ * The two halves of the documented mechanism, joined. `loadSettings` reads the `outputStyle` key and
+ * {@link loadOutputStyle} reads the file; until this existed nothing connected them, so a consumer
+ * had to find both modules and know that one feeds the other. Two halves each individually correct
+ * and jointly unreachable is the same defect as a capability with no caller — it just takes two
+ * files to make.
+ *
+ * Deliberately does NOT soften the loader: a style named in settings with no file behind it still
+ * throws {@link OutputStyleError}. Returning `undefined` there would restore the exact silence this
+ * work removed — configured, not applied, and no way to tell which.
+ *
+ * @throws OutputStyleError when settings name a style and no file backs it.
+ */
+declare function resolveOutputStyle(input: {
+    readonly cwd: string;
+    readonly homeDir?: string;
+    readonly onWarn?: (message: string) => void;
+}): OutputStyle | undefined;
+
+/** What an operator may impose on THIS layer. */
+interface OperatorPolicy {
+    /**
+     * 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 runs shell at expansion time.
+     * Without this the only way to decline was to stop reading skills at all.
+     */
+    disableSkillShellExecution?: boolean;
+    /**
+     * Refuse every hook declared under a foreign configuration root.
+     *
+     * B-042. `.claude/hooks.json` runs shell commands out of a working directory that usually arrived
+     * with the clone, and until this key existed an operator who inherited an untrusted checkout could
+     * not decline hook execution without editing files in it. `resolveCompatSources` reads this and
+     * drops the `hooks` surface from what it grants.
+     *
+     * ## It fails CLOSED, unlike every other key here
+     *
+     * The others ignore a value of the wrong shape and warn. For this one that is fail-OPEN: an
+     * operator who writes `"true"` as a string would get hooks running while believing they were off.
+     * The asymmetry decides it — fail-open is silent and unsafe, fail-closed is loud and recoverable:
+     * hooks stop, somebody notices, the typo is fixed. For a control whose purpose is refusing,
+     * failing toward the refusal is the only direction where the failure announces itself.
+     *
+     * An ABSENT key is not a malformed one and still means "hooks run": most machines have no operator
+     * tier, and refusing by default would remove hooks nobody asked to remove.
+     */
+    disableAllHooks?: boolean;
+    /**
+     * Servers from a project `.mcp.json` that may NOT start, by name.
+     *
+     * Deny wins over {@link OperatorPolicy.allowedMcpServers}. A server named in both is a
+     * contradiction, and the safe reading of a contradiction is the restrictive one — resolving it the
+     * other way would let an allow entry re-enable something an operator explicitly refused.
+     */
+    deniedMcpServers?: readonly string[];
+    /**
+     * When present, the ONLY servers from a project `.mcp.json` that may start.
+     *
+     * Absent means "no allow list", not "allow nothing": the file is the project's own declaration and
+     * the default stays permissive by CHOICE, because refusing it outright would break every existing
+     * consumer to protect against a file they wrote themselves. An empty ARRAY is a real decision and
+     * refuses everything.
+     */
+    allowedMcpServers?: readonly string[];
+    /**
+     * B-069 — a command that prints a credential on stdout, re-run whenever one is needed.
+     *
+     * An operator whose tokens rotate had no seam at all: a long-running agent failed mid-run and the
+     * only answer was a restart with a fresh environment variable. This is declared HERE rather than
+     * on `defineAgent` for the reason B-065 records — the person answerable for what runs on a machine
+     * is frequently not the person who wrote the code, and a command that mints a secret is the most
+     * operator-shaped thing in the system.
+     *
+     * Run by {@link runCredentialHelper}, which bounds it with a timeout and refuses an empty result.
+     */
+    apiKeyHelper?: string;
+}
+declare function currentOperatorPolicy(warn: (message: string) => void): OperatorPolicy;
+/**
+ * Whether a server declared in a project `.mcp.json` may start.
+ *
+ * Deny first: a server in both lists is refused. An allow list, once present, is EXHAUSTIVE —
+ * anything unnamed is refused — while an absent one means "no allow list", not "allow nothing".
+ */
+declare function mcpServerAdmitted(name: string, policy: OperatorPolicy): boolean;
+
+/**
+ * Translate a settings `permissions` block into rules the SDK's engine evaluates.
+ *
+ * The SDK ships `PermissionEngine(rules, { defaultAction })` and it is a CODE surface: you construct
+ * it with `PermissionRule[]`. What was missing was the path from the FILE to those rules. Measured
+ * 2026-09-11: `permissions` appears in 13 SDK files, and the SDK reads `settings.json` in three, of
+ * which two are sourcemaps and the third describes the hooks shape. An operator writing
+ * `{ "permissions": { "deny": ["Bash(curl:*)"] } }` got a file nothing translated.
+ *
+ * ## Partial fidelity would be worse than absence
+ *
+ * A `deny` that silently fails to match is a control the operator believes is in force — strictly
+ * more dangerous than no rule, because without one they would have written the guard themselves. So
+ * every entry this module cannot render faithfully is RETURNED as unsupported, with a reason, and
+ * excluded from the rules. Nothing is quietly turned into a matcher that does not bite.
+ *
+ * ## What it deliberately does not attempt
+ *
+ * The reference's specifier language is larger than this: path globs with `~` expansion, per-tool
+ * argument names, and matching semantics that differ by tool. Implementing a lookalike would produce
+ * rules that match *almost* the right calls, which is the failure above. Two forms are translated —
+ * a bare tool name, and `Tool(prefix:*)` / `Tool(exact)` — and everything else is reported.
+ */
+
+/** An entry that was understood well enough to refuse, but not well enough to translate. */
+interface UnsupportedPermissionEntry {
+    /** The entry as written, so the operator can find it in their file. */
+    readonly entry: string;
+    /** Why it was not translated. */
+    readonly reason: string;
+}
+interface PermissionTranslation {
+    readonly rules: readonly PermissionRule[];
+    readonly unsupported: readonly UnsupportedPermissionEntry[];
+}
+/** The `permissions` block as a settings file may carry it. */
+interface PermissionsBlock {
+    readonly allow?: readonly string[];
+    readonly deny?: readonly string[];
+    readonly ask?: readonly string[];
+}
+/**
+ * The rules a `permissions` block means, and the entries that could not be rendered.
+ *
+ * An absent or empty block yields nothing and reports nothing: most projects declare no permissions,
+ * and a translator that warned there would be noise in every one of them.
+ */
+declare function permissionRulesFromSettings(block: PermissionsBlock | undefined): PermissionTranslation;
+
+/**
+ * The keys this layer can act on today, plus everything else untouched.
+ *
+ * Typed narrowly on purpose: a key is listed here when something in this package reads it, not
+ * because the reference documents it. Declaring a field the code ignores would publish a control
+ * that does nothing, which is the shape every item in this batch had.
+ */
+declare const SETTINGS_SCHEMA: z.ZodObject<{
+    outputStyle: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    permissions: z.ZodOptional<z.ZodObject<{
+        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ask: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+type Settings = z.infer<typeof SETTINGS_SCHEMA>;
+interface LoadSettingsInput {
+    /** Project root. Its `.claude/settings.json` and `.claude/settings.local.json` are read. */
+    readonly cwd: string;
+    /** Home directory, for the user-level file. Omit to read the project only. */
+    readonly homeDir?: string;
+    /** Where a file that exists and cannot be parsed is reported. */
+    readonly onWarn?: (message: string) => void;
+}
+interface LoadSettingsResult {
+    readonly values: Settings;
+    /** Which layer each resolved key came from. */
+    readonly provenancePerKey: Readonly<Record<string, string>>;
+    /** Which declared layers contributed nothing — a file nobody is reading is named, not hidden. */
+    readonly precedenceReport: PrecedenceReport;
+}
+/**
+ * The settings as the declared layers resolve them.
+ *
+ * Never throws for a missing or malformed file; see {@link readLayer}.
+ */
+declare function loadSettings(input: LoadSettingsInput): LoadSettingsResult;
 
 /**
  * Split a markdown file into frontmatter lines and body.
@@ -814,4 +990,4 @@ declare class ContextPressureThresholdError extends TheokitAgentError {
  */
 declare function contextPressure(usedTokens: number, effectiveWindow: number, thresholds?: ContextPressureThresholds): ContextPressure;
 
-export { type ComposeInstructionsOptions, type ComposedInstructions, type ConfigLayer, type ContextPressure, ContextPressureThresholdError, type ContextPressureThresholds, type CustomCommand, type CustomCommandsResult, DEFAULT_CONTEXT_PRESSURE_THRESHOLDS, type ExpandImportsInput, FILE_INLINE_CAP, type InstructionBlock, type InstructionSource, type InstructionTree, type InstructionTreeBudget, LAYERS_ARE_POSITIONED, LayerOutOfOrderError, LayeredConfig, type LayeredConfigInput, type LayeredConfigResult, type LoadCustomCommandsInput, type LoadInstructionTreeInput, type LoadOutputStyleInput, type OutputStyle, OutputStyleError, type ParsedFrontmatter, type PrecedenceReport, type ProvenancePerKey, SETTINGS_LAYERS, type SettingsLayer, type ShellResult, type TemplateDeps, type TrustRecord, TrustStore, TrustStorePermissionsError, blockAppliesTo, composeInstructions, contextPressure, expandCommandTemplate, expandInstructionImports, frontmatterValue, layerPrecedence, loadCustomCommands, loadInstructionTree, loadOutputStyle, settingsLayerChain, splitFrontmatter, templateHints };
+export { type ComposeInstructionsOptions, type ComposedInstructions, type ConfigLayer, type ContextPressure, ContextPressureThresholdError, type ContextPressureThresholds, type CustomCommand, type CustomCommandsResult, DEFAULT_CONTEXT_PRESSURE_THRESHOLDS, type ExpandImportsInput, FILE_INLINE_CAP, type InstructionBlock, type InstructionSource, type InstructionTree, type InstructionTreeBudget, LAYERS_ARE_POSITIONED, LayerOutOfOrderError, LayeredConfig, type LayeredConfigInput, type LayeredConfigResult, type LoadCustomCommandsInput, type LoadInstructionTreeInput, type LoadOutputStyleInput, type LoadSettingsInput, type LoadSettingsResult, type OperatorPolicy, type OutputStyle, OutputStyleError, type ParsedFrontmatter, type PermissionTranslation, type PermissionsBlock, type PrecedenceReport, type ProvenancePerKey, SETTINGS_LAYERS, type Settings, type SettingsLayer, type ShellResult, type TemplateDeps, type TrustRecord, TrustStore, TrustStorePermissionsError, type UnsupportedPermissionEntry, blockAppliesTo, composeInstructions, contextPressure, currentOperatorPolicy, expandCommandTemplate, expandInstructionImports, frontmatterValue, layerPrecedence, loadCustomCommands, loadInstructionTree, loadOutputStyle, loadSettings, mcpServerAdmitted, permissionRulesFromSettings, resolveOutputStyle, settingsLayerChain, splitFrontmatter, templateHints };