@theokit/agents 13.0.0-next.11 → 13.0.0-next.13

package/CHANGELOG.md

@@ -1,5 +1,349 @@
 # @theokit/agents
 
+## 13.0.0-next.13
+
+### Minor Changes
+
+- 6b07960: New `grantGate(store, classify)` in `@theokit/agents/auth` — the supported way to put a
+  `PermissionStore` in force.
+
+  The store shipped with a careful grant key, a "deny by default, always" docblock and no reader.
+  Measured: `isGranted` had zero callers outside its own unit test, and `PermissionStore` appeared in
+  zero files across six sibling repositories. An operator reading `.theokit/tool-permissions.json` to
+  learn what an agent may run was reading a control that was not in force — a grant and its revocation
+  produced identical behaviour.
+
+  `grantGate` adapts the store to `pre_tool_call`, which is documented as the only hook with veto
+  power and runs before the tool by construction, so a refusal is a refusal before the side effect. No
+  new gate and no framework wiring: nothing is enforced unless a consumer attaches the handler, and an
+  agent that does not is unaffected.
+
+  `classify` returns `{ governed: true, query }` **or** `{ governed: false }` — a tagged union whose
+  BOTH arms carry the discriminant. A bare `undefined` would say "this tool needs no permission" and
+  "I forgot this tool" in the same word, and on a security gate the second must not silently pass.
+
+  The discriminant is on both arms because the first shape — discriminated by whether a `governed` KEY
+  was present — **failed open**: a consumer writing a policy record `{ governed: true, scope }` and
+  spreading it into the query got the tool waved through, and so did `governed: undefined`. TypeScript
+  does not stop that; excess properties pass freely through a variable or a spread. Fail-closed is now
+  measured across `true` / `undefined` / `false` / `null`, and only `false` passes.
+
+  Named `grantGate`, not `permissionGate`, because `@theokit/sdk` already exports `PermissionGate`,
+  `PermissionGateContext`, `PermissionGateDecision`, `PermissionEngine` and `PermissionPlugin`. The
+  rename also says something true: this gates on a standing grant the operator made, and the SDK's
+  permission engine is a separate system — neither satisfies the other.
+
+  A classifier that throws DENIES, naming the throw, rather than ending the turn. A corrupt store
+  denies with a message that says so — "the permission store could not be read, so no grant applies" —
+  distinct from "no standing grant matches", so an operator can tell the two apart.
+
+  The read error's own text is deliberately NOT in that message: the veto travels to the model, and
+  `lastReadError.message` carries the absolute store path and its file mode. It stays on
+  `store.lastReadError` for the operator, which is where the actionable remedy (`chmod 600 …`) lives.
+  The scope IS still interpolated, so this narrows the exposure rather than eliminating it.
+
+  **Composing with a `pre_tool_call` you already have**: the field is singular, so assigning the gate
+  over an existing handler loses one of the two silently. Compose explicitly —
+  `async (ctx) => (await gate(ctx)) ?? (await mine(ctx))`; first veto wins.
+
+  `PermissionStore`'s docblock now states that the class enforces nothing on its own, and records the
+  precedence among the surfaces IN THIS PACKAGE that can refuse a tool — saying plainly that the list
+  is not exhaustive, because `@theokit/sdk` has its own permission system that neither knows about
+  these nor is known by them.
+
+- 5211721: `moderateOutputStream` now delivers the redacted text to the client instead of computing it and
+  replaying the original events.
+
+  It called `runOutputGuards` and discarded the return value, so a guard that redacted correctly had
+  its work thrown away: measured against the built artifact, a guard returning `[REDACTED]` delivered
+  `sk-abc123`. Only `block` reached the client honestly.
+
+  **Signature change**: `moderateOutputStream` takes a fourth argument,
+  `rebuildText: (text: string, replaced: E) => E`, which builds one event carrying the
+  moderated text, given the text-carrying event it replaces. It is required rather than optional —
+  optional would let the function compute a redaction it cannot apply, which is the defect being
+  removed. Only the caller knows how to construct its own events.
+
+  **`extractText` MUST match exactly one event kind.** When it matches several, they COLLAPSE INTO
+  ONE — measured: `[thinking('CoT: the key is sk-abc'), message(' Here you go.')]` yields a single
+  `message` reading `"CoT: the key is [R] Here you go."`, with no `thinking` event surviving. A
+  consumer who wants reasoning moderated runs a SECOND pass over that kind rather than widening one
+  extractor.
+
+  `replaced` does not prevent that collapse, and an earlier draft of this entry said it did. What it
+  buys is narrower: the surviving event keeps the KIND and metadata of the text-carrying event it
+  replaces, instead of being rebuilt from the text alone. `replaced` is ALWAYS the event being replaced.
+  It was typed `E | undefined` for a case that cannot happen — a stream where no event carried text
+  returns from the absence check before the guards run, so `rebuildText` is not reached at all. It is
+  also never a non-text event, because a caller spreading one would emit a duplicate of it.
+
+  **Second signature change**: a fifth argument, `rebuildResult: (text, result) => R`, applies the
+  moderated text to the generator's RETURN value. A stream has two channels and the first release of
+  this fix moderated one: the events were redacted while `step.value` — the aggregate `run()` returns
+  — still carried the original text. Measured: the guard computed `"the key is [R]"` and
+  `run().response` was `"the key is sk-abc123"`, so **`run()`, the primary non-streaming API, kept
+  delivering the secret**. That was this fix's own defect one channel over. Required for the same
+  reason `rebuildText` is; passed rather than re-derived, because re-running the guards on the
+  aggregate would apply a non-idempotent guard twice.
+
+  When the text is unchanged, the buffered events are replayed verbatim as before. When it changed,
+  the **last** text-carrying event is REPLACED by a newly built event carrying the whole moderated
+  string, and the earlier text events are dropped. Events carrying no text are never dropped. Note
+  "replaced", not "modified": any non-text payload the surviving event carried is lost, as is that of
+  the dropped ones — a consumer whose text events carry per-event metadata should moderate one kind
+  only, or rebuild from `replaced`. An event whose extracted text is the EMPTY STRING is still
+  text-carrying and can be the one replaced.
+
+  **Known consequence:** when text events straddle a non-text event, their relative order does not
+  survive a redaction. Given `text('tok ') , tool_call , text('sk-abc')` the client now receives
+  `tool_call , text('tok [R]')` — text that preceded the tool call follows it. Landing on the last
+  text-carrying event keeps a trailing terminator in place and keeps any completion claim after the
+  work that produced it; what it cannot keep is the interleaving, because the redaction is about the
+  whole string and the boundaries are gone by the time it exists. A test pins this so it is found
+  here rather than in a transcript that stopped making sense.
+
+  A guard that rewrites **unconditionally** — a disclaimer appender, a trim, an NFC normaliser —
+  takes this path on every stream that DOES carry text. The cost is not proportional to how much the
+  guard changed. It does NOT add a text event to a round that produced none — this entry claimed so,
+  and the absence check refuses it: a tool-only round yields its tool call and nothing else.
+
+- 98b2565: `resolveSettingSources` now returns `readonly GatedSettingSource[]`, and
+  `CompiledAgentOptions.settingSources` takes that type — so a setting root no `TrustPosture`
+  authorised no longer fits the field.
+
+  `define-agent.ts` claimed that field "can only ever hold roots that some posture authorized".
+  Measured against the emitted `.d.ts`: `setOnce(draft, 'settingSources', ['mdm','team','user','plugins'], 'cap')`
+  typechecked **cast-free**. Writing a `Capability` is the documented way to extend the builder, and a
+  capability writes the draft directly — so the gate was reachable around, for `project`, the root it
+  exists to protect.
+
+  A brand rather than a runtime check, because the obvious runtime check does not work: reading
+  `draft.provenance` to refuse a capability's write would also refuse the LEGITIMATE builder path,
+  which writes through `setOnce` too. What differs is where the value came from, and that is what a
+  brand carries.
+
+  **It refuses the accident, not the determined caller** — `as never` defeats it, like every brand.
+  Saying so is the point: the comment it replaces claimed an invariant nothing enforced.
+
+  **New: `settingSources.plugins`**, taking the same `ProjectSettingsGrant` as `project`.
+  `PluginsManager.refresh` loads executable bundles from the same cwd-controlled tree, usually
+  arriving with the clone, so it gets the same gate and not a weaker one. This is the root the SDK
+  genuinely reads and the facade withheld.
+
+  `team` and `mdm` stay absent, and that is the item's original premise dying under measurement: the
+  SDK never reads them — `includesSetting` is called with exactly `"project"` and `"plugins"` — so
+  forwarding them would be a capability in the type and nothing at runtime.
+
+  **Migration**: a consumer constructing `CompiledAgentOptions` by hand must build roots through
+  `resolveSettingSources` instead of a string array. That is the supported construction and always was.
+
+  **Also: a narrowed `claudeCode.import` is now REFUSED on an SDK that cannot read it.**
+
+  That field's docblock said the narrowed form was "refused at resolve time" below `@theokit/sdk`
+  5.4.0. Nothing read a version for it — the only checks in this layer are the hook gate (a different
+  option) and a `compatSources` warning that returns silently for any major ≥ 5. So on
+  5.0.0 ≤ SDK < 5.4.0, inside this package's declared `^4.52.1 || ^5.0.0`, a narrowed `import` was
+  forwarded, dropped by the runtime in silence, and the foreign root was **not read at all** — a
+  consumer asking for "the skills but not the hooks" got nothing, which is further from what they
+  asked for than the un-narrowed form. `compatSources` landed in 5.0.0 and the narrowing in 5.4.0;
+  treating the two versions as one was the defect.
+
+  `CompatImportUnsupportedError` now refuses, naming both versions and what would otherwise happen.
+  It refuses rather than warns because a silent nothing is discovered by wondering why a skill is
+  missing. An unreadable version is refused too: "cannot tell" and "is supported" must not collapse.
+
+  **And `commands` is subtracted before the compat sources reach the SDK.** The two vocabularies
+  diverge by one name on purpose — `.claude/commands/*.md` is read by this package and never by the
+  SDK — and `setting-sources-gate.ts` prescribed the subtraction as advice to consumers while the
+  projection that needed it did not do it. Measured: `import: ['commands']` forwarded a list
+  containing zero names the SDK defines, which is its own empty-list case — the exact ambiguity
+  `resolveCompatSources` refuses one layer up. A source whose surfaces all belong to this layer
+  is now dropped from the SDK's list rather than sent empty.
+
+  `CompatImportUnsupportedError` is exported from `@theokit/agents/bridge`, so a consumer can catch the
+  refusal by class rather than by matching its message.
+
+- 2bc5d84: `delegate()` now applies the guardrails its spec declares. It accepted them and never consulted them.
+
+  Measured against the built artifact with a guard declaring both halves: the input reached the model
+  with its injection intact and the caller received `sk-abc123`. `bridge/agent-orchestrator.ts`
+  contained **zero** occurrences of `guardrail` — control on the same sweep: `loop/agent-runner.ts`
+  has 9 — and called `runReflectiveLoop` bare. The operator had declared guardrails and the run was
+  green.
+
+  This is the same defect class as the streamed-redaction fix in this release, on a sibling public
+  API, and it is model-reachable: `tools/delegate-tool.ts` wraps `delegate()`, so an agent can invoke
+  a sub-agent whose declared guards do nothing.
+
+  `checkInput` runs after `onDelegationStart` and `checkOutput` after `onDelegationComplete` — each
+  moderating what actually crosses the boundary rather than a string a hook may then rewrite. A
+  blocking input guard throws before the model is called at all, so a refused delegation costs
+  nothing.
+
+  `response` only. `toolCalls[].output` is tool output rather than model text, and `agent-runner.ts`
+  excludes it from `extractText` on the same reasoning; the docblock says so, because leaving it alone
+  should be a decision somebody reads rather than an omission somebody discovers.
+
+  A spec declaring no guardrails behaves byte-identically.
+
+  **A guardrail block now crosses the delegate tool as a refusal, not a crash.** `errorCodeOf` mapped
+  only the three delegation errors, so `GuardrailViolationError` — reachable from `delegate()` for the
+  first time because of this change — hit the "not a delegation outcome, a defect" arm and was
+  rethrown, ending the parent's turn. The tool's own description, shipped to the model, promises
+  `{ ok: false, error, message }` on a refusal.
+
+  It crosses as `guardrail_violation` with a FIXED message: `the delegated task was refused by a
+policy guard`. The message travels only for codes on an explicit ALLOWLIST — a budget or a timeout
+  is a fact about the work, and the number in it is what the model acts on. A code nobody lists
+  withholds, so forgetting is safe in the direction that matters. A guardrail message is not — it reads
+  `Guardrail "pii-detector" blocked output: ssn found`, naming the guard and its exact trigger, and a
+  model given that learns which words to avoid rather than that it should stop. The operator keeps the
+  full typed error, which carries `guardName`, `phase` and `reason`.
+
+- 019f828: Output guards now moderate `thinking` events, not only `text_delta`.
+
+  `AgentRunner` handed `moderateOutputStream` an extractor matching `text_delta` and nothing else,
+  while `thinking` is a public `AgentStreamEvent` that reaches the client like any other. Measured: a
+  guard declared over the agent's output delivered `thinking "the key is sk-abc123"` verbatim.
+
+  **This closes one channel and does not close all of them.** `DoneEvent.result` carries the model's
+  whole answer and is still unmoderated — measured on the same turn, `text_delta` came out
+  `"here: [R]"` while `done.result` came out `"here: sk-abc123"`. `task_progress.text` is a fourth and
+  reaches the web wire. A third pass does not extend to them: there is one `done` per round, so a pass
+  keyed on it would collapse every round's into one, and they need a different mechanism. Tracked
+  separately; stated here because a security note that overstates its coverage is worse than one that
+  does not exist.
+
+  The third channel of a shape fixed twice already in this release — a streamed redaction that was
+  computed and discarded, and `delegate()` consulting no guards at all.
+
+  **Two passes, not one wider extractor.** Widening `extractText` to match both kinds is the obvious
+  move and the wrong one: two kinds under one extractor COLLAPSE into a single event, so the reasoning
+  would be promoted into a visible one — the moderation creating the disclosure it exists to close.
+  Composing two passes is what `moderateOutputStream`'s own docblock prescribes, and each pass seeing
+  one kind is what keeps them apart.
+
+  The visible pass owns the aggregate: `DelegationResult.response` accumulates from `text_delta`
+  upstream, so the reasoning pass passes the result through rather than replacing it.
+
+  A blocking guard on either channel still throws before any event is emitted. An agent with no output
+  guard is byte-identical.
+
+- 0731584: `resolveCompatSources` now returns `readonly GatedCompatSource[]`, and
+  `CompiledAgentOptions.compatSources` takes that type — so a compat source no `TrustPosture`
+  authorised no longer fits the field.
+
+  **BREAKING for hand-built compiled options**, exactly as its sibling was. Build compat sources
+  through `resolveCompatSources`.
+
+  The twin of the `settingSources` brand, and it exists because that fix closed one of the two fields
+  one `SettingSourcesSelection` feeds and left the other bare. Measured, with the `settingSources`
+  route as the control: the control errored, and `setOnce(draft, 'compatSources', ['claude-code'],
+'cap')` compiled cast-free — while `agent-compiler.ts` told the reader that field "can only hold a
+  source some posture granted".
+
+  It carries more authority than its twin, not less. `applyLocalSources` forwards it to
+  `Agent.create({ local: { compatSources } })`, which reads `<cwd>/.claude/` — `hooks.json` included,
+  and that executes shell.
+
+  **Signature narrowing**: `moderateOutputStream`'s `rebuildText` is now
+  `(text: string, replaced: E) => E`. It was typed `E | undefined` for a case that cannot happen — a
+  stream where no event carried text returns from the absence check before the guards run, so
+  `rebuildText` is never reached. The branch handling that case was dead code, and three shipping
+  artifacts described it as live.
+
+  **Fixed**: `isPort` discriminated on the presence of `run`, so an object carrying both `compiled`
+  and a `run` — reachable through a spread, which is how targets are built in practice — took the port
+  branch and skipped `delegate()` entirely: no declared guardrails, no inherited parent veto, no
+  budget clamp. A tie now goes to the spec, because the spec branch is the guarded one.
+
+### Patch Changes
+
+- bb0f451: A guardrail refusal thrown inside a round is no longer renamed into a delegation failure.
+
+  `runReflectiveLoop` wrapped any error that was not already a delegation error into
+  `DelegationError`, whose message reads `Delegation to agent "X" failed: ${cause.message}`. That code
+  is on the delegate tool's message allowlist — a delegation failure's text is a fact about the work —
+  so the wrapper carried the guard's own words to the model: `Guardrail "pii-detector" blocked output:
+ssn found`, naming the guard and its exact trigger.
+
+  Measured through `createDelegateTool` with a consumer-supplied `streamFactory` that throws
+  mid-round. `streamFactory` is a public option, so this was reachable rather than theoretical.
+
+  `GuardrailViolationError` now passes through as itself, alongside the two delegation errors that
+  already did, so the tool classifies it `guardrail_violation` and withholds the message.
+
+  Fixed by classification rather than by suppressing text downstream: a guard refusal is not a
+  delegation failure, and a layer that renames an error cannot be expected to maintain a list of what
+  the new name must hide.
+
+- ac29eff: A permission-gate veto now emits a debug line.
+
+  `grantGate` refused and emitted nothing — no log, no counter, no debug line. An operator could
+  observe the refusal only through the tool result the model received, and the two causes the veto
+  message distinguishes ("no standing grant matches" versus "the permission store could not be read,
+  so no grant applies") are indistinguishable from there.
+
+  That is pillar 3 of the wiring triad missing on a refusal seam. `bridge/approval-posture.ts`, the
+  sibling gate, already logged through this exact seam.
+
+  The QUERY is logged — tool, scope, and which of the two causes fired — and the grant is not: a query
+  names what an operator needs to diagnose, while the store's contents are the thing being protected.
+  A classifier that threw logs as its own event rather than as an ordinary veto, so a consumer-code
+  defect is not read as a denied tool.
+
+## 13.0.0-next.12
+
+### Minor Changes
+
+- a7e35bb: A guardrail returning `action: 'redact'` with no replacement `text` now throws
+  `MalformedGuardrailResultError` instead of silently redacting nothing.
+
+  `GuardrailResult.text` is optional, so such a guard compiles and reads like a working one. The
+  pipeline tested `r.text !== undefined` and moved on, so the caller received the original text and
+  believed a guard had run on it — the operator believing a protection is in place when none is.
+
+  **This is a behaviour change.** A guard relying on the previous no-op will now throw. That is
+  deliberate: the alternative is unredacted output reaching a model because a guard was written wrong.
+  `text: ''` is unaffected and always was a real redaction — a guard choosing to erase everything.
+
+  `MalformedGuardrailResultError` is exported from `@theokit/agents`, carries the guard's name and the
+  phase, and is not retryable.
+
+  This also reaches the streaming path (`moderateOutputStream`), which shares the same pipeline: a
+  malformed guard there now throws where it previously continued.
+
+### Patch Changes
+
+- 2bc27d3: `inheritHooks` no longer lets a member's `transform_tool_result` or `pre_user_send` handler replace
+  its parent's — both now chain parent-first, matching the six events that already composed.
+
+  `inheritHooks` documents its security property as "the parent's refusal is evaluated first, and a
+  member can only ever ADD a reason to refuse". For these two events the plain object spread did the
+  opposite: a member declaring either handler silently discarded the parent's. The reachable surface is the EXPORTED `inheritHooks`, called with two handler maps.
+  `delegate()` passes `undefined` for the member (`agent-orchestrator.ts:175`), so that path composed
+  nothing and was never affected — a distinction the first version of this note got wrong.
+
+  `pre_user_send` composes additively — both contributions reach the model, parent first — because
+  `PreUserSendResult` carries only `recalledContext` and the seam exposes no prompt mutation.
+
+- eaac7b0: The "will NOT fire" warning for a declared-but-unwired hook event now names where the capability
+  already lives, instead of ending "the handler does not exist yet".
+
+  Two of the three unwired events are served today by purpose-built seams — `Guardrail.checkOutput`
+  for `transform_llm_output`, and `createToolHooksPlugin({ processInput })` for `pre_user_send` — so
+  the old message told consumers to wait for work that will not come. The third, `on_session_end`, is
+  named as genuinely uncovered, with the reason: its handler returns `void` and cannot refuse an
+  ending, so wiring it would produce a hook that runs and cannot decide.
+
+  Nothing is wired. `HOOK_EVENTS`, `WIRED_EVENTS` and `OBSERVATIONAL_EVENTS` keep the same members.
+
+- ec899f4: An observational hook handler is now assigned to its own key rather than chosen by comparison.
+
+  The dispatch loop used a two-branch conditional over a list of two event names, so a third
+  observational event would have landed on `post_assistant_reply` — silently, with no test objecting.
+  No behaviour changes for the events wired today; the fix removes the trap for the next one added.
+
 ## 13.0.0-next.11
 
 ### Patch Changes

package/dist/{agent-compiler-DRfBbirH.d.ts → agent-compiler-BztdbNPn.d.ts}

@@ -1,7 +1,7 @@
-import { InlineSkill, SystemPromptResolver, SettingSource, MemorySettings, SkillsSettings, ContextSettings } from '@theokit/sdk';
+import { InlineSkill, SystemPromptResolver, MemorySettings, SkillsSettings, ContextSettings } from '@theokit/sdk';
 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 { R as ResolvedCompatSource } from './setting-sources-gate-D2NS1GsB.js';
+import { G as GatedSettingSource, a as GatedCompatSource } from './setting-sources-gate-DFu51i50.js';
 
 /**
  * M9 (theokit-ai-first) — guardrail contract + typed errors.
@@ -36,15 +36,36 @@ interface Guardrail {
 }
 /** Which boundary phase a violation happened in. */
 type GuardrailPhase = 'input' | 'output';
-/** Thrown (fail-fast) when a guard returns `action: 'block'`. Typed per error-handling.md. */
 /**
- * M80 — extends {@link TheokitAgentError}, not plain `Error`.
+ * A guard declared `redact` and supplied no replacement text.
  *
- * `isTransientError` is defined over `TheokitAgentError`, so a class outside that hierarchy is
- * INVISIBLE to it and the only recourse left to a consumer is matching on message text — a regex
- * over an eight-level `cause` chain, which is what one actually wrote. `code` is stable across a
- * rename of the class; `isRetryable` is DECLARED rather than defaulted, because a default would be a
- * retry policy nobody chose.
+ * Distinct from {@link GuardrailViolationError} on purpose: that one says the guard REFUSED
+ * something, which is a decision working as designed. This says the guard is MALFORMED — it asked
+ * for a redaction and gave nothing to redact with, so nothing was redacted.
+ *
+ * Until B-008 this condition was silent: `pipeline.ts` tested `r.text !== undefined` and moved on, so
+ * the caller received the original text and believed a guard had run on it. That is the shape this
+ * package's hook engine calls "worse than no hook at all" — a belief in a protection that is not
+ * there. Throwing is fail-fast per `rules/error-handling.md § 2`, and the alternative was leaving
+ * unredacted output to reach a model because a guard was written wrong.
+ *
+ * `''` is NOT this case. An empty replacement is a guard choosing to erase everything, which is the
+ * strongest redaction available, and treating it as absent would invert the defect.
+ */
+declare class MalformedGuardrailResultError extends TheokitAgentError {
+    readonly guardName: string;
+    readonly phase: GuardrailPhase;
+    readonly name = "MalformedGuardrailResultError";
+    constructor(guardName: string, phase: GuardrailPhase);
+}
+/**
+ * Thrown (fail-fast) when a guard returns `action: 'block'`. Typed per error-handling.md.
+ *
+ * M80 — extends {@link TheokitAgentError}, not plain `Error`. `isTransientError` is defined over
+ * `TheokitAgentError`, so a class outside that hierarchy is INVISIBLE to it and the only recourse
+ * left to a consumer is matching on message text — a regex over an eight-level `cause` chain, which
+ * is what one actually wrote. `code` is stable across a rename of the class; `isRetryable` is
+ * DECLARED rather than defaulted, because a default would be a retry policy nobody chose.
  */
 declare class GuardrailViolationError extends TheokitAgentError {
     readonly guardName: string;
@@ -149,6 +170,33 @@ declare class HookGateUnsupportedError extends TheokitAgentError {
     readonly name = "HookGateUnsupportedError";
     constructor(version: string | undefined);
 }
+/**
+ * A narrowed `import` on an SDK that cannot read it.
+ *
+ * Refuses rather than warns, and the asymmetry with {@link warnIfSdkCannotReadCompatSources} is
+ * deliberate: an unrecognised `compatSources` shape means the foreign root is not read, so a
+ * consumer who asked for "the skills but not the hooks" silently gets NOTHING — strictly further
+ * from what they asked for than the un-narrowed form, which at least reads something. Failing loud
+ * is recoverable; a silent nothing is discovered by wondering why a skill is missing.
+ *
+ * ## The cost, which this file argues against two functions above
+ *
+ * An unreadable version is refused too, on the principle {@link assertSdkCanGateHooks} states:
+ * "cannot tell" and "is supported" must not collapse. The sibling WARNING takes the opposite view
+ * for itself — *"a bundled or vendored SDK may not resolve that subpath, and refusing to create an
+ * agent over a diagnostic would be the cure being worse than the disease."*
+ *
+ * Both are right for what they guard, and the difference is what the check IS. A diagnostic that
+ * cannot read a version should stay quiet; a GATE that cannot read one has not established the
+ * thing it exists to establish. But the cost is real and belongs here rather than in a reviewer's
+ * report: a consumer who bundles the SDK so `@theokit/sdk/package.json` does not resolve cannot
+ * create an agent with a narrowed `import`, even on 5.4.0+. Their exit is to omit `import` and read
+ * the whole root.
+ */
+declare class CompatImportUnsupportedError extends TheokitAgentError {
+    readonly name = "CompatImportUnsupportedError";
+    constructor(version: string | undefined);
+}
 
 /**
  * Agent compiler — transforms decorator metadata into SDK calls.
@@ -239,14 +287,14 @@ interface CompiledAgentOptions {
      * Projected into `Agent.create({ local: { settingSources } })` by `assembleM8CreateOptions`
      * (merged with `cwd`, decoupled from inline skills). Absent ⇒ inline (code) config only.
      */
-    settingSources?: readonly SettingSource[];
+    settingSources?: readonly GatedSettingSource[];
     /**
      * Foreign configuration dialects, already authorised (usetheokit/theokit#634).
      *
      * Resolved at compile time by `resolveCompatSources`, exactly like `settingSources`: a value here
      * can only hold a source some posture granted, so the adapter projects rather than decides.
      */
-    compatSources?: readonly ResolvedCompatSource[];
+    compatSources?: readonly GatedCompatSource[];
     /**
      * #686 — the consumer's pre-spawn approval gate, forwarded to `Agent.create({ local: { hooks } })`.
      *
@@ -299,4 +347,4 @@ interface CompiledAgentOptions {
     skillsResolver?: SkillsSelection;
 }
 
-export { type CompiledAgentOptions as C, type Guardrail as G, type HookApprovalGate as H, type SkillsSelection as S, type ToolWalkResult as T, type CompiledTool as a, CostBudgetExceededError as b, type GuardrailAction as c, type GuardrailPhase as d, type GuardrailResult as e, GuardrailViolationError as f, type HookApprovalRequest as g, HookGateUnsupportedError as h, type SkillsRequestContext as i, type ToolboxWalkResult as j, compileTools as k, resolveEnabledSkills as r };
+export { type CompiledAgentOptions as C, type Guardrail as G, type HookApprovalGate as H, MalformedGuardrailResultError as M, type SkillsSelection as S, type ToolWalkResult as T, type CompiledTool as a, CompatImportUnsupportedError as b, CostBudgetExceededError as c, type GuardrailAction as d, type GuardrailPhase as e, type GuardrailResult as f, GuardrailViolationError as g, type HookApprovalRequest as h, HookGateUnsupportedError as i, type SkillsRequestContext as j, type ToolboxWalkResult as k, compileTools as l, resolveEnabledSkills as r };

package/dist/auth.d.ts

@@ -443,4 +443,89 @@ declare class PermissionStore {
     expired(): readonly Grant[];
 }
 
-export { type AgentCredentialInput, type AuthMethod, AuthProvider, CODEX_CLIENT_ID_ENV_VAR, CODEX_PROVIDER, CredentialNotFoundError, type ProviderDescriptor as CredentialProviderDescriptor, type CredentialResolution, type CredentialSourcesInput, DEFAULT_PROVIDERS, DeclaredProviderError, type DeviceAuthProvider, type Grant, type GrantOptions, type PermissionQuery, PermissionStore, type PermissionStoreOptions, type PromptHooks, ProviderKeyMismatchError, ProviderPrefixMismatchError, type ResolveCredentialInput, type SourceOrigin, credentialSources, loginWithDevice, requireCredential, resolveAgentCredential, resolveCredential };
+/**
+ * Minimal shape mirrored from `@theokit/sdk`.
+ *
+ * The reason used to read "type-only, no runtime import, so the SDK peer stays optional", and that
+ * does not justify mirroring anything: `bridge/hook-handlers.ts` imports these very two SDK types
+ * (`PreToolCallContext`, `PreToolCallDecision`) with `import type` and costs the optional peer
+ * nothing. A type-only import IS type-only.
+ *
+ * The real reason is the NAME, and it is written out three paragraphs down: `@theokit/sdk` already
+ * exports `PermissionGateContext` with a different shape, so a consumer importing both would get a
+ * duplicate identifier or silently the wrong one. What is mirrored here is also a deliberate
+ * SUBSET — the fields this gate reads — rather than a copy kept in step with the SDK's.
+ *
+ * A mirror can drift into a consumer-side compile error that no gate here would see first, so the
+ * assignment this docblock instructs a consumer to make is pinned by
+ * `tests/type/the-grant-gate-fits-the-hook-it-is-for.test-d.ts`.
+ *
+ * NOT named `PermissionGateContext`: `@theokit/sdk` already exports a type by that name, with a
+ * different shape (`{ toolName, mode }`), alongside `PermissionGate`, `PermissionGateDecision`,
+ * `PermissionEngine` and `PermissionPlugin`. A consumer importing both would get a duplicate
+ * identifier, or silently the wrong shape.
+ *
+ * The rename says something true rather than merely avoiding a clash. This gates on a STANDING
+ * GRANT the operator made; the SDK's permission engine is a separate system with its own rules, and
+ * the two do not consult each other — an engine `allow` does not satisfy a missing grant, and a
+ * grant does not satisfy the engine.
+ */
+interface GrantGateContext {
+    readonly name: string;
+    readonly args: Record<string, unknown>;
+    readonly agentId: string;
+    readonly runId: string;
+    /**
+     * The run's resolved permission mode, carried by the real context. Mirrored so the shapes match
+     * and so its absence from the gate's logic is a decision rather than an oversight: `bypass` does
+     * NOT disable this gate, because a standing grant is the operator's, not the run's.
+     */
+    readonly permissionMode?: string;
+}
+/** This tool is deliberately outside the gate's remit — distinct from "I forgot to map it". */
+interface NotGoverned {
+    readonly governed: false;
+}
+/** This tool IS governed, by the grant key inside. */
+interface Governed {
+    readonly governed: true;
+    readonly query: PermissionQuery;
+}
+/**
+ * BOTH arms carry `governed`, and that is the whole point.
+ *
+ * The first version was `PermissionQuery | NotGoverned` — discriminated by whether the `governed`
+ * KEY was present. It failed open, measured against the built artifact: a consumer who writes a
+ * policy record `{ governed: true, scope }` and spreads it into the query — the most natural
+ * reading of "yes, govern this" — got `undefined` back, and an ungranted destructive command ran.
+ * `governed: undefined` did the same. TypeScript does not stop it: a fresh literal with an excess
+ * property errors, the same object through a variable or a spread does not.
+ *
+ * The presence check arrived by obeying a linter. `'governed' in c && c.governed === false` was
+ * flagged as "always true given the type", which was true of the DECLARED type and false of every
+ * value that reaches it. A type-based lint rule cannot see excess properties, and the safety of a
+ * gate is not a type-level fact.
+ *
+ * With the discriminant on both arms there is no key to be accidentally present: `governed` is
+ * declared either way, the check is on its VALUE, and `governed: true` without a `query` is a
+ * compile error rather than a silent pass.
+ */
+type Classification = Governed | NotGoverned;
+/**
+ * A veto, in the shape `pre_tool_call` returns.
+ *
+ * Exported because it appears in {@link grantGate}'s public signature — an unexported type there
+ * leaves a consumer unable to name the return value. `hooks/secure-store.ts` documents the same
+ * case.
+ */
+interface Veto {
+    readonly block: true;
+    readonly message: string;
+}
+/**
+ * @param store the grants to consult; re-read per call, so a grant made mid-run is seen
+ * @param classify maps a tool call to the grant key it needs, or declares it ungoverned
+ */
+declare function grantGate(store: PermissionStore, classify: (ctx: GrantGateContext) => Classification): (ctx: GrantGateContext) => Promise<Veto | undefined>;
+
+export { type AgentCredentialInput, type AuthMethod, AuthProvider, CODEX_CLIENT_ID_ENV_VAR, CODEX_PROVIDER, type Classification, CredentialNotFoundError, type ProviderDescriptor as CredentialProviderDescriptor, type CredentialResolution, type CredentialSourcesInput, DEFAULT_PROVIDERS, DeclaredProviderError, type DeviceAuthProvider, type Governed, type Grant, type GrantGateContext, type GrantOptions, type NotGoverned, type PermissionQuery, PermissionStore, type PermissionStoreOptions, type PromptHooks, ProviderKeyMismatchError, ProviderPrefixMismatchError, type ResolveCredentialInput, type SourceOrigin, type Veto, credentialSources, grantGate, loginWithDevice, requireCredential, resolveAgentCredential, resolveCredential };

package/dist/auth.js

@@ -2,6 +2,9 @@ import {
   readSecureJson,
   writeSecureJson
 } from "./chunk-D2EFYZBV.js";
+import {
+  debugLog
+} from "./chunk-M5J3Q6YC.js";
 import {
   __name
 } from "./chunk-Z4QWC7IK.js";
@@ -572,6 +575,38 @@ var PermissionStore = class {
 `);
   }
 };
+
+// src/auth/permission-gate.ts
+function grantGate(store, classify) {
+  return (ctx) => {
+    try {
+      const classification = classify(ctx);
+      if (classification.governed === false) return Promise.resolve(void 0);
+      if (store.isGranted(classification.query)) return Promise.resolve(void 0);
+      const because = store.lastReadError === void 0 ? "no standing grant matches" : "the permission store could not be read, so no grant applies";
+      debugLog("[theokit] permission gate vetoed", {
+        tool: ctx.name,
+        scope: classification.query.scope,
+        because
+      });
+      return Promise.resolve({
+        block: true,
+        message: `"${ctx.name}" is not permitted in ${classification.query.scope}: ${because}`
+      });
+    } catch (cause) {
+      const why = cause instanceof Error ? cause.message : String(cause);
+      debugLog("[theokit] permission gate could not classify", {
+        tool: ctx.name,
+        why
+      });
+      return Promise.resolve({
+        block: true,
+        message: `permission gate could not classify "${ctx.name}": ${why}`
+      });
+    }
+  };
+}
+__name(grantGate, "grantGate");
 export {
   AuthProvider,
   CODEX_CLIENT_ID_ENV_VAR,
@@ -590,6 +625,7 @@ export {
   deviceLogin,
   ensureFreshCredential2 as ensureFreshCredential,
   extractAccountId,
+  grantGate,
   loginWithDevice,
   openaiDeviceLogin3 as openaiDeviceLogin,
   persistOAuthTokens2 as persistOAuthTokens,