@theokit/agents 4.30.2 → 6.0.0

package/dist/{bridge-entry-BL74g1Em.d.ts → bridge-entry-DD_j60GX.d.ts}

@@ -721,6 +721,79 @@ interface AgentRouteContext {
 /** Generate HTTP routes for a single agent. Returns Web Standard handlers. */
 declare function generateAgentRoutes(ctx: AgentRouteContext): AgentRoute[];
 
+/**
+ * M4 (theokit-ai-first) — the HITL producer: a `pre_tool_call` plugin that pauses the SDK run
+ * for a human-in-the-loop tool approval.
+ *
+ * ADR 0038: this is the ADAPTER seam — it makes the shipped-but-dead `@HumanInTheLoop` decorator
+ * FUNCTIONAL by wiring the SDK's OWN async `pre_tool_call` veto hook (which the SDK loop `await`s,
+ * so returning a pending Promise genuinely PAUSES the run) to a human approval. It calls no LLM,
+ * dispatches no tool, and runs no second loop — the SDK owns all of that.
+ *
+ * Flow: gated tool about to run → emit an `ApprovalRequiredEvent` (which the translator maps to
+ * the ai-sdk `tool-approval-request` chunk) → `await awaitApproval(approvalId)` (resolved by the
+ * out-of-band approve route) → allow (`undefined`) or veto (`{ block, message }`, which the SDK
+ * surfaces as a tool result the model self-corrects on).
+ */
+
+/**
+ * M20 — a settled HITL decision. Structural mirror of the harness's `ApprovalDecision` (the agents
+ * package must not import from `theokit` — dependency direction). `awaitApproval` may resolve a bare
+ * boolean (legacy) OR this object; the plugin normalizes both.
+ */
+interface HitlDecision {
+    approved: boolean;
+    reason?: string;
+    payload?: unknown;
+}
+/** Injected wiring — the harness (mount-agent) supplies these; the plugin stays pure. */
+interface HitlWiring {
+    /** Tool name → its `@HumanInTheLoop` config. A tool absent here is NOT gated. */
+    gated: Map<string, HumanInTheLoopOptions>;
+    /** Push the approval-required event into the agent stream (the translator emits the chunk). */
+    emit: (event: ApprovalRequiredEvent) => void;
+    /**
+     * Await the human decision for `approvalId`; resolves approve/deny (or timeout). M20 — may resolve
+     * a bare boolean (legacy) OR a {@link HitlDecision} carrying an approver `reason` + `payload`.
+     */
+    awaitApproval: (approvalId: string, opts: HumanInTheLoopOptions, toolName: string) => Promise<boolean | HitlDecision>;
+}
+
+/**
+ * O que esta superfície faz quando uma tool gateada pede aprovação. Quatro variantes, nenhuma delas
+ * "omissão" — cada uma com um consumidor concreto e uma razão escrita.
+ */
+type ApprovalPosture = {
+    /** Há humano: o pedido é EMITIDO e a execução pausa até a decisão chegar. */
+    kind: 'interactive';
+    /**
+     * Empurra o `ApprovalRequiredEvent` para o stream da superfície. OBRIGATÓRIO: `toAgentFactory`
+     * devolve um handle cru, sem stream nem translator, então o sink vem de quem passa a postura —
+     * que é justamente a superfície dona do stream. Um default no-op devolveria o descarte
+     * silencioso pela porta dos fundos: o pedido seria "emitido" para lugar nenhum.
+     */
+    emit: (event: ApprovalRequiredEvent) => void;
+    /** Resolve a decisão humana; a execução fica pausada até isto resolver. */
+    awaitApproval: (approvalId: string, opts: HumanInTheLoopOptions, toolName: string) => Promise<boolean | HitlDecision>;
+} | {
+    /** Ninguém pergunta e a tool roda. Legítimo quando outra coisa confina a execução. */
+    kind: 'auto-approve';
+    reason: string;
+} | {
+    /** Ninguém pergunta e a tool NÃO roda — a leitura segura da omissão (codex `GranularApprovalConfig`). */
+    kind: 'auto-reject';
+    reason: string;
+} | {
+    /**
+     * O gate é conduzido pela SUPERFÍCIE servidora (o cliente ACP, pelo próprio protocolo), então
+     * a camada não instala plugin nenhum. É um bypass — mas um bypass NOMEADO, com razão escrita,
+     * que aparece no `match`, aparece em log e pode ser contado por um gate. O que ele substitui é
+     * pior: hoje o mesmo efeito acontece por omissão, sem nada disso.
+     */
+    kind: 'owned-by-surface';
+    reason: string;
+};
+
 /**
  * M82 — the typed shape of `AgentBuilder.create().hooks({...})`.
  *
@@ -1057,12 +1130,13 @@ interface SdkAgentHandle {
  * model / `assembleM8CreateOptions`), so the served agent has identical tools, model, system prompt,
  * skills, and `mcpServers`. Keyed per `sessionId` via `Agent.getOrCreate` (matches the run path).
  *
- * NOTE: HITL approvals (`.approval(...)`) are driven by the framework's streaming runner, not by
- * `Agent.create`; a raw `SDKAgent` from this factory does not auto-pause gated tools — the serving
- * surface (e.g. the ACP client) owns approval. Tools still execute; they are simply not HITL-gated here.
+ * M96 — a superfície DECLARA sua {@link ApprovalPosture} e o factory instala o plugin que a variante
+ * exige. Antes, o mapa `compiled.hitl` era compilado e DESCARTADO aqui. Rationale em
+ * `./approval-posture.ts`.
  */
 declare function toAgentFactory(def: DefinicaoOuThunk, opts: {
     apiKey: string | (() => string | Promise<string>);
+    approvals: ApprovalPosture;
     overrides?: RuntimeOverrides;
 }): (sessionId: string) => Promise<SdkAgentHandle>;
 
@@ -1342,44 +1416,6 @@ declare const AgentBuilder: {
     create(): AgentBuilder;
 };
 
-/**
- * M4 (theokit-ai-first) — the HITL producer: a `pre_tool_call` plugin that pauses the SDK run
- * for a human-in-the-loop tool approval.
- *
- * ADR 0038: this is the ADAPTER seam — it makes the shipped-but-dead `@HumanInTheLoop` decorator
- * FUNCTIONAL by wiring the SDK's OWN async `pre_tool_call` veto hook (which the SDK loop `await`s,
- * so returning a pending Promise genuinely PAUSES the run) to a human approval. It calls no LLM,
- * dispatches no tool, and runs no second loop — the SDK owns all of that.
- *
- * Flow: gated tool about to run → emit an `ApprovalRequiredEvent` (which the translator maps to
- * the ai-sdk `tool-approval-request` chunk) → `await awaitApproval(approvalId)` (resolved by the
- * out-of-band approve route) → allow (`undefined`) or veto (`{ block, message }`, which the SDK
- * surfaces as a tool result the model self-corrects on).
- */
-
-/**
- * M20 — a settled HITL decision. Structural mirror of the harness's `ApprovalDecision` (the agents
- * package must not import from `theokit` — dependency direction). `awaitApproval` may resolve a bare
- * boolean (legacy) OR this object; the plugin normalizes both.
- */
-interface HitlDecision {
-    approved: boolean;
-    reason?: string;
-    payload?: unknown;
-}
-/** Injected wiring — the harness (mount-agent) supplies these; the plugin stays pure. */
-interface HitlWiring {
-    /** Tool name → its `@HumanInTheLoop` config. A tool absent here is NOT gated. */
-    gated: Map<string, HumanInTheLoopOptions>;
-    /** Push the approval-required event into the agent stream (the translator emits the chunk). */
-    emit: (event: ApprovalRequiredEvent) => void;
-    /**
-     * Await the human decision for `approvalId`; resolves approve/deny (or timeout). M20 — may resolve
-     * a bare boolean (legacy) OR a {@link HitlDecision} carrying an approver `reason` + `payload`.
-     */
-    awaitApproval: (approvalId: string, opts: HumanInTheLoopOptions, toolName: string) => Promise<boolean | HitlDecision>;
-}
-
 /**
  * M2 (theokit-ai-first) — the file-convention runtime bridge.
  *
@@ -2182,4 +2218,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
     register(app: PluginApp): void;
 };
 
-export { DelegationBudgetExceededError as $, type ApprovalOptions as A, type ApiErrorPolicy as B, type CompiledAgentOptions as C, type DelegationResult as D, type ApprovalRequiredEvent as E, type ArtifactChunkEvent as F, type Guardrail as G, type HumanInTheLoopOptions as H, type ArtifactStartEvent as I, type BackgroundDelegation as J, type BeforeToolCallContext as K, type LoopStrategy as L, type MainLoopMeta as M, BudgetExceededError as N, type BudgetOptions as O, type CheckpointSavedEvent as P, type CompiledContextWindow as Q, type ReflectionStrategy as R, type StreamEvent as S, type ToolOptions as T, ContextualTool as U, CostBudgetExceededError as V, DEFAULT_MAX_ITERATIONS as W, type DefineAgentConfig as X, type DefinicaoOuThunk as Y, type DelegateFn as Z, type DelegateOptions as _, type CompiledTool as a, delegate as a$, DelegationError as a0, type DoneEvent as a1, type ErrorEvent as a2, type FileEditEvent as a3, type GuardrailAction as a4, type GuardrailPhase as a5, type GuardrailResult as a6, GuardrailViolationError as a7, type HookHandlers as a8, type InferAgentInput as a9, type SkillsRequestContext as aA, type SkillsSelection as aB, type StateUpdateEvent as aC, type TextDeltaEvent as aD, type ThinkingEvent as aE, type TimeoutAction as aF, type ToolCallEvent as aG, type ToolCallVeto as aH, type ToolHooks as aI, type ToolHooksPlugin as aJ, type ToolResultEvent as aK, type ToolWalkResult as aL, type ToolboxOptions as aM, type ToolboxWalkResult as aN, agentsPlugin as aO, buildModelSelection as aP, compileAgentDefinition as aQ, compileAgentModule as aR, compileContextWindow as aS, compileProjectContext as aT, compileSkills as aU, compileTools as aV, createAgentExecutionContext as aW, createApiErrorHandler as aX, createSdkAgentStream as aY, createThinkTagExtractor as aZ, createToolHooksPlugin as a_, type InferAgentToolNames as aa, type IterationEvent as ab, type LLMCallContext as ac, type LoopFinishReason as ad, type LoopOutcome as ae, type LoopStrategyConfig as af, type MainLoopOptions as ag, type McpApprovalSpec as ah, type McpRegistryConfig as ai, type McpRequestContext as aj, type McpSelection as ak, type PartialToolCallEvent as al, type PolicyHandler as am, type ProcessInputContext as an, type ReflectionContext as ao, type ReflectionResult as ap, type ReflectionStrategyConfig as aq, type RunStartedEvent as ar, type ScoreVerdict as as, type ScoredDelegation as at, type Scorer as au, type SdkAgentHandle as av, type SdkMessage as aw, type SdkSendOptions as ax, type SdkTurnHandle as ay, type Segment as az, type ReasoningEffort as b, delegateBackground as b0, delegateWithScoring as b1, extractThinkTagStream as b2, generateAgentManifest as b3, generateAgentRoutes as b4, isAgentContext as b5, isAgentDefinition as b6, isApprovalRequired as b7, isDone as b8, isError as b9, isPartialToolCall as ba, isTextDelta as bb, isToolCall as bc, isToolResult as bd, ladderReflectionStrategy as be, loopStrategyConfigSchema as bf, mcpRegistry as bg, mcpToolApprovals as bh, noopReflectionStrategy as bi, presentUIMessageStream as bj, projectContextMetadataOnlyKnobs as bk, reflectionStrategyConfigSchema as bl, resolveEnabledSkills as bm, resolveLoopStrategy as bn, resolveMcpServers as bo, runWithApiErrorHandling as bp, streamAgentResponse as bq, toAgentFactory as br, translateSdkEvent as bs, type RoundStreamFactory as c, type ContextWindowOptions as d, type SkillsOptions as e, type AgentManifestEntry as f, type HitlDecision as g, AGENT_BRAND as h, type AfterToolCallContext as i, AgentBuilder as j, type AgentDefinition as k, AgentDefinitionError as l, type AgentExecutionContext as m, type AgentManifest as n, type AgentManifestSource as o, type AgentManifestTool as p, type AgentOptions as q, type AgentRoute as r, streamAgentUIMessages as s, type AgentRouteContext as t, type AgentRunInfo as u, type AgentStreamEvent as v, type AgentTurnMetadata as w, type AgentsPluginOptions as x, type ApiErrorContext as y, type ApiErrorDecision as z };
+export { type DelegateOptions as $, type ApprovalOptions as A, type ApiErrorDecision as B, type CompiledAgentOptions as C, type DelegationResult as D, type ApiErrorPolicy as E, type ApprovalRequiredEvent as F, type Guardrail as G, type HumanInTheLoopOptions as H, type ArtifactChunkEvent as I, type ArtifactStartEvent as J, type BackgroundDelegation as K, type LoopStrategy as L, type MainLoopMeta as M, type BeforeToolCallContext as N, BudgetExceededError as O, type BudgetOptions as P, type CheckpointSavedEvent as Q, type ReflectionStrategy as R, type StreamEvent as S, type ToolOptions as T, type CompiledContextWindow as U, ContextualTool as V, CostBudgetExceededError as W, DEFAULT_MAX_ITERATIONS as X, type DefineAgentConfig as Y, type DefinicaoOuThunk as Z, type DelegateFn as _, type CompiledTool as a, createToolHooksPlugin as a$, DelegationBudgetExceededError as a0, DelegationError as a1, type DoneEvent as a2, type ErrorEvent as a3, type FileEditEvent as a4, type GuardrailAction as a5, type GuardrailPhase as a6, type GuardrailResult as a7, GuardrailViolationError as a8, type HookHandlers as a9, type Segment as aA, type SkillsRequestContext as aB, type SkillsSelection as aC, type StateUpdateEvent as aD, type TextDeltaEvent as aE, type ThinkingEvent as aF, type TimeoutAction as aG, type ToolCallEvent as aH, type ToolCallVeto as aI, type ToolHooks as aJ, type ToolHooksPlugin as aK, type ToolResultEvent as aL, type ToolWalkResult as aM, type ToolboxOptions as aN, type ToolboxWalkResult as aO, agentsPlugin as aP, buildModelSelection as aQ, compileAgentDefinition as aR, compileAgentModule as aS, compileContextWindow as aT, compileProjectContext as aU, compileSkills as aV, compileTools as aW, createAgentExecutionContext as aX, createApiErrorHandler as aY, createSdkAgentStream as aZ, createThinkTagExtractor as a_, type InferAgentInput as aa, type InferAgentToolNames as ab, type IterationEvent as ac, type LLMCallContext as ad, type LoopFinishReason as ae, type LoopOutcome as af, type LoopStrategyConfig as ag, type MainLoopOptions as ah, type McpApprovalSpec as ai, type McpRegistryConfig as aj, type McpRequestContext as ak, type McpSelection as al, type PartialToolCallEvent as am, type PolicyHandler as an, type ProcessInputContext as ao, type ReflectionContext as ap, type ReflectionResult as aq, type ReflectionStrategyConfig as ar, type RunStartedEvent as as, type ScoreVerdict as at, type ScoredDelegation as au, type Scorer as av, type SdkAgentHandle as aw, type SdkMessage as ax, type SdkSendOptions as ay, type SdkTurnHandle as az, type ReasoningEffort as b, delegate as b0, delegateBackground as b1, delegateWithScoring as b2, extractThinkTagStream as b3, generateAgentManifest as b4, generateAgentRoutes as b5, isAgentContext as b6, isAgentDefinition as b7, isApprovalRequired as b8, isDone as b9, isError as ba, isPartialToolCall as bb, isTextDelta as bc, isToolCall as bd, isToolResult as be, ladderReflectionStrategy as bf, loopStrategyConfigSchema as bg, mcpRegistry as bh, mcpToolApprovals as bi, noopReflectionStrategy as bj, presentUIMessageStream as bk, projectContextMetadataOnlyKnobs as bl, reflectionStrategyConfigSchema as bm, resolveEnabledSkills as bn, resolveLoopStrategy as bo, resolveMcpServers as bp, runWithApiErrorHandling as bq, streamAgentResponse as br, toAgentFactory as bs, translateSdkEvent as bt, type RoundStreamFactory as c, type ContextWindowOptions as d, type SkillsOptions as e, type AgentManifestEntry as f, type HitlDecision as g, type ApprovalPosture as h, AGENT_BRAND as i, type AfterToolCallContext as j, AgentBuilder as k, type AgentDefinition as l, AgentDefinitionError as m, type AgentExecutionContext as n, type AgentManifest as o, type AgentManifestSource as p, type AgentManifestTool as q, type AgentOptions as r, streamAgentUIMessages as s, type AgentRoute as t, type AgentRouteContext as u, type AgentRunInfo as v, type AgentStreamEvent as w, type AgentTurnMetadata as x, type AgentsPluginOptions as y, type ApiErrorContext as z };

package/dist/bridge.d.ts

@@ -1,4 +1,4 @@
-export { h as AGENT_BRAND, i as AfterToolCallContext, j as AgentBuilder, k as AgentDefinition, l as AgentDefinitionError, m as AgentExecutionContext, n as AgentManifest, f as AgentManifestEntry, o as AgentManifestSource, p as AgentManifestTool, r as AgentRoute, t as AgentRouteContext, u as AgentRunInfo, v as AgentStreamEvent, w as AgentTurnMetadata, x as AgentsPluginOptions, y as ApiErrorContext, z as ApiErrorDecision, B as ApiErrorPolicy, E as ApprovalRequiredEvent, F as ArtifactChunkEvent, I as ArtifactStartEvent, J as BackgroundDelegation, K as BeforeToolCallContext, N as BudgetExceededError, P as CheckpointSavedEvent, C as CompiledAgentOptions, Q as CompiledContextWindow, a as CompiledTool, U as ContextualTool, X as DefineAgentConfig, Y as DefinicaoOuThunk, Z as DelegateFn, _ as DelegateOptions, $ as DelegationBudgetExceededError, a0 as DelegationError, D as DelegationResult, a1 as DoneEvent, a2 as ErrorEvent, a3 as FileEditEvent, a9 as InferAgentInput, aa as InferAgentToolNames, ab as IterationEvent, ac as LLMCallContext, ah as McpApprovalSpec, ai as McpRegistryConfig, aj as McpRequestContext, ak as McpSelection, al as PartialToolCallEvent, an as ProcessInputContext, ar as RunStartedEvent, as as ScoreVerdict, at as ScoredDelegation, au as Scorer, av as SdkAgentHandle, aw as SdkMessage, ax as SdkSendOptions, ay as SdkTurnHandle, az as Segment, aC as StateUpdateEvent, S as StreamEvent, aD as TextDeltaEvent, aE as ThinkingEvent, aG as ToolCallEvent, aH as ToolCallVeto, aI as ToolHooks, aJ as ToolHooksPlugin, aK as ToolResultEvent, aL as ToolWalkResult, aN as ToolboxWalkResult, aO as agentsPlugin, aP as buildModelSelection, aQ as compileAgentDefinition, aR as compileAgentModule, aS as compileContextWindow, aT as compileProjectContext, aU as compileSkills, aV as compileTools, aW as createAgentExecutionContext, aX as createApiErrorHandler, aY as createSdkAgentStream, aZ as createThinkTagExtractor, a_ as createToolHooksPlugin, a$ as delegate, b0 as delegateBackground, b1 as delegateWithScoring, b2 as extractThinkTagStream, b3 as generateAgentManifest, b4 as generateAgentRoutes, b5 as isAgentContext, b6 as isAgentDefinition, b7 as isApprovalRequired, b8 as isDone, b9 as isError, ba as isPartialToolCall, bb as isTextDelta, bc as isToolCall, bd as isToolResult, bg as mcpRegistry, bh as mcpToolApprovals, bj as presentUIMessageStream, bk as projectContextMetadataOnlyKnobs, bo as resolveMcpServers, bp as runWithApiErrorHandling, bq as streamAgentResponse, s as streamAgentUIMessages, br as toAgentFactory, bs as translateSdkEvent } from './bridge-entry-BL74g1Em.js';
+export { i as AGENT_BRAND, j as AfterToolCallContext, k as AgentBuilder, l as AgentDefinition, m as AgentDefinitionError, n as AgentExecutionContext, o as AgentManifest, f as AgentManifestEntry, p as AgentManifestSource, q as AgentManifestTool, t as AgentRoute, u as AgentRouteContext, v as AgentRunInfo, w as AgentStreamEvent, x as AgentTurnMetadata, y as AgentsPluginOptions, z as ApiErrorContext, B as ApiErrorDecision, E as ApiErrorPolicy, h as ApprovalPosture, F as ApprovalRequiredEvent, I as ArtifactChunkEvent, J as ArtifactStartEvent, K as BackgroundDelegation, N as BeforeToolCallContext, O as BudgetExceededError, Q as CheckpointSavedEvent, C as CompiledAgentOptions, U as CompiledContextWindow, a as CompiledTool, V as ContextualTool, Y as DefineAgentConfig, Z as DefinicaoOuThunk, _ as DelegateFn, $ as DelegateOptions, a0 as DelegationBudgetExceededError, a1 as DelegationError, D as DelegationResult, a2 as DoneEvent, a3 as ErrorEvent, a4 as FileEditEvent, aa as InferAgentInput, ab as InferAgentToolNames, ac as IterationEvent, ad as LLMCallContext, ai as McpApprovalSpec, aj as McpRegistryConfig, ak as McpRequestContext, al as McpSelection, am as PartialToolCallEvent, ao as ProcessInputContext, as as RunStartedEvent, at as ScoreVerdict, au as ScoredDelegation, av as Scorer, aw as SdkAgentHandle, ax as SdkMessage, ay as SdkSendOptions, az as SdkTurnHandle, aA as Segment, aD as StateUpdateEvent, S as StreamEvent, aE as TextDeltaEvent, aF as ThinkingEvent, aH as ToolCallEvent, aI as ToolCallVeto, aJ as ToolHooks, aK as ToolHooksPlugin, aL as ToolResultEvent, aM as ToolWalkResult, aO as ToolboxWalkResult, aP as agentsPlugin, aQ as buildModelSelection, aR as compileAgentDefinition, aS as compileAgentModule, aT as compileContextWindow, aU as compileProjectContext, aV as compileSkills, aW as compileTools, aX as createAgentExecutionContext, aY as createApiErrorHandler, aZ as createSdkAgentStream, a_ as createThinkTagExtractor, a$ as createToolHooksPlugin, b0 as delegate, b1 as delegateBackground, b2 as delegateWithScoring, b3 as extractThinkTagStream, b4 as generateAgentManifest, b5 as generateAgentRoutes, b6 as isAgentContext, b7 as isAgentDefinition, b8 as isApprovalRequired, b9 as isDone, ba as isError, bb as isPartialToolCall, bc as isTextDelta, bd as isToolCall, be as isToolResult, bh as mcpRegistry, bi as mcpToolApprovals, bk as presentUIMessageStream, bl as projectContextMetadataOnlyKnobs, bp as resolveMcpServers, bq as runWithApiErrorHandling, br as streamAgentResponse, s as streamAgentUIMessages, bs as toAgentFactory, bt as translateSdkEvent } from './bridge-entry-DD_j60GX.js';
 import '@theokit/http';
 import '@theokit/sdk';
 import 'zod';

package/dist/bridge.js

@@ -44,7 +44,7 @@ import {
   streamAgentUIMessages,
   toAgentFactory,
   translateSdkEvent
-} from "./chunk-GGB5WXHS.js";
+} from "./chunk-JXR45RAW.js";
 import "./chunk-7QVYU63E.js";
 export {
   AGENT_BRAND,

package/dist/{chunk-GGB5WXHS.js → chunk-JXR45RAW.js}

@@ -455,6 +455,59 @@ function generateAgentRoutes(ctx) {
 }
 __name(generateAgentRoutes, "generateAgentRoutes");
 
+// src/bridge/tool-hooks-plugin.ts
+function createToolHooksPlugin(hooks) {
+  return {
+    name: "theokit-tool-hooks",
+    version: "1.0.0",
+    // `kind: 'general'` is load-bearing — without it the SDK's isCodePlugin() drops this plugin and
+    // no hook fires (M10/M19 latent bug, proven via a real OpenRouter run).
+    kind: "general",
+    register(ctx) {
+      const { beforeToolCall, afterToolCall, beforeLLMCall, afterLLMCall, processInput } = hooks;
+      if (beforeToolCall) {
+        ctx.on("pre_tool_call", (c) => beforeToolCall({
+          name: c.name ?? "",
+          args: c.args ?? {}
+        }));
+      }
+      if (afterToolCall) {
+        ctx.on("post_tool_call", (c) => afterToolCall({
+          name: c.name ?? "",
+          result: c.result
+        }));
+      }
+      if (beforeLLMCall) {
+        ctx.on("pre_llm_call", (c) => beforeLLMCall({
+          agentId: c.agentId,
+          runId: c.runId,
+          iteration: c.iteration
+        }));
+      }
+      if (afterLLMCall) {
+        ctx.on("post_llm_call", (c) => afterLLMCall({
+          agentId: c.agentId,
+          runId: c.runId,
+          iteration: c.iteration
+        }));
+      }
+      if (processInput) {
+        ctx.on("pre_user_send", async (c) => {
+          const injected = await processInput({
+            prompt: c.prompt ?? "",
+            agentId: c.agentId,
+            runId: c.runId
+          });
+          return injected !== void 0 && injected.length > 0 ? {
+            recalledContext: injected
+          } : void 0;
+        });
+      }
+    }
+  };
+}
+__name(createToolHooksPlugin, "createToolHooksPlugin");
+
 // src/bridge/event-translator.ts
 function asString(value, fallback) {
   if (typeof value === "string") return value;
@@ -766,6 +819,116 @@ function debugLog(marker, data) {
 }
 __name(debugLog, "debugLog");
 
+// src/bridge/hitl-plugin.ts
+function createHitlPlugin(wiring) {
+  return {
+    name: "theokit-hitl",
+    version: "1.0.0",
+    // `kind: 'general'` is load-bearing — without it the SDK's isCodePlugin() drops this plugin and
+    // the HITL veto never fires (the run would proceed WITHOUT waiting for human approval).
+    kind: "general",
+    register(ctx) {
+      ctx.on("pre_tool_call", async (c) => {
+        const opts = wiring.gated.get(c.name);
+        if (!opts) return void 0;
+        const approvalId = crypto.randomUUID();
+        wiring.emit({
+          type: "approval_required",
+          callId: approvalId,
+          toolName: c.name,
+          question: opts.question,
+          input: c.args,
+          callbackUrl: `approve/${approvalId}`,
+          timeoutMs: opts.timeout ?? 3e5,
+          // M20 — carry the declared custom-payload schema so the UI knows what to collect.
+          ...opts.payloadSchema !== void 0 ? {
+            payloadSchema: opts.payloadSchema
+          } : {}
+        });
+        const raw = await wiring.awaitApproval(approvalId, opts, c.name);
+        const decision = typeof raw === "boolean" ? {
+          approved: raw
+        } : raw;
+        if (decision.approved) return void 0;
+        let message = `Tool '${c.name}' denied by human approver`;
+        if (decision.reason) message += `: ${decision.reason}`;
+        if (decision.payload !== void 0) {
+          message += ` (payload: ${JSON.stringify(decision.payload)})`;
+        }
+        return {
+          block: true,
+          message
+        };
+      });
+    }
+  };
+}
+__name(createHitlPlugin, "createHitlPlugin");
+
+// src/bridge/approval-posture.ts
+function razaoDe(postura) {
+  return postura.kind === "interactive" ? "human approver on this surface" : postura.reason;
+}
+__name(razaoDe, "razaoDe");
+function aplicarPostura(extra, m8, postura, gated) {
+  const daPostura = pluginsDaPostura(postura, gated);
+  if (daPostura.length === 0) return;
+  const atuais = extra.plugins ?? m8.plugins;
+  if (atuais !== void 0 && !Array.isArray(atuais)) {
+    throw new Error(`[@theokit/agents] approval posture "${postura.kind}" needs to install a plugin, but \`plugins\` was supplied in the legacy object form, which cannot carry both. Pass \`plugins\` as an array so the approval gate is not dropped.`);
+  }
+  extra.plugins = [
+    ...atuais ?? [],
+    ...daPostura
+  ];
+}
+__name(aplicarPostura, "aplicarPostura");
+function pluginsDaPostura(postura, gated) {
+  debugLog("[theokit] approval posture", {
+    kind: postura.kind,
+    reason: razaoDe(postura)
+  });
+  if (gated === void 0 || gated.size === 0) return [];
+  switch (postura.kind) {
+    case "interactive":
+      return [
+        createHitlPlugin({
+          gated,
+          emit: postura.emit,
+          awaitApproval: postura.awaitApproval
+        })
+      ];
+    case "auto-approve":
+      return [
+        createToolHooksPlugin({
+          beforeToolCall: /* @__PURE__ */ __name((ctx) => {
+            if (gated.has(ctx.name)) {
+              debugLog("[theokit] gated tool auto-approved", {
+                tool: ctx.name,
+                reason: postura.reason
+              });
+            }
+            return void 0;
+          }, "beforeToolCall")
+        })
+      ];
+    case "auto-reject":
+      return [
+        createToolHooksPlugin({
+          // Só as tools GATEADAS são recusadas: a postura descreve o gate, não um bloqueio universal.
+          // Recusar tudo quebraria todo agente que tem uma tool livre ao lado de uma gateada.
+          beforeToolCall: /* @__PURE__ */ __name((ctx) => gated.has(ctx.name) ? {
+            block: true,
+            message: `Tool '${ctx.name}' requires human approval, and this surface has no approver (approval posture: auto-reject \u2014 ${postura.reason}). Refused (fail-closed).`
+          } : void 0, "beforeToolCall")
+        })
+      ];
+    case "owned-by-surface":
+      return [];
+  }
+}
+__name(pluginsDaPostura, "pluginsDaPostura");
+
 // src/bridge/definicao-ou-thunk.ts
 function projetar(def, overrides) {
   const compiled = compileAgentDefinition(def);
@@ -1342,6 +1505,7 @@ function toAgentFactory(def, opts) {
       baseDir: overrides.baseDir
     };
     const extra = buildExtraCreateOptions(overrides, compiled);
+    aplicarPostura(extra, m8, opts.approvals, compiled.hitl);
     const agent = await rt.Agent.getOrCreate(sessionId, {
       apiKey: await resolverApiKey(opts.apiKey),
       model: buildModelSelection(model, reasoningEffort),
@@ -2098,52 +2262,6 @@ var AgentBuilder = {
   }
 };
 
-// src/bridge/hitl-plugin.ts
-function createHitlPlugin(wiring) {
-  return {
-    name: "theokit-hitl",
-    version: "1.0.0",
-    // `kind: 'general'` is load-bearing — without it the SDK's isCodePlugin() drops this plugin and
-    // the HITL veto never fires (the run would proceed WITHOUT waiting for human approval).
-    kind: "general",
-    register(ctx) {
-      ctx.on("pre_tool_call", async (c) => {
-        const opts = wiring.gated.get(c.name);
-        if (!opts) return void 0;
-        const approvalId = crypto.randomUUID();
-        wiring.emit({
-          type: "approval_required",
-          callId: approvalId,
-          toolName: c.name,
-          question: opts.question,
-          input: c.args,
-          callbackUrl: `approve/${approvalId}`,
-          timeoutMs: opts.timeout ?? 3e5,
-          // M20 — carry the declared custom-payload schema so the UI knows what to collect.
-          ...opts.payloadSchema !== void 0 ? {
-            payloadSchema: opts.payloadSchema
-          } : {}
-        });
-        const raw = await wiring.awaitApproval(approvalId, opts, c.name);
-        const decision = typeof raw === "boolean" ? {
-          approved: raw
-        } : raw;
-        if (decision.approved) return void 0;
-        let message = `Tool '${c.name}' denied by human approver`;
-        if (decision.reason) message += `: ${decision.reason}`;
-        if (decision.payload !== void 0) {
-          message += ` (payload: ${JSON.stringify(decision.payload)})`;
-        }
-        return {
-          block: true,
-          message
-        };
-      });
-    }
-  };
-}
-__name(createHitlPlugin, "createHitlPlugin");
-
 // src/bridge/agent-endpoint.ts
 var AgentDefinitionError = class extends Error {
   static {
@@ -3140,59 +3258,6 @@ async function delegate(spec, message, opts = {}) {
 }
 __name(delegate, "delegate");
 
-// src/bridge/tool-hooks-plugin.ts
-function createToolHooksPlugin(hooks) {
-  return {
-    name: "theokit-tool-hooks",
-    version: "1.0.0",
-    // `kind: 'general'` is load-bearing — without it the SDK's isCodePlugin() drops this plugin and
-    // no hook fires (M10/M19 latent bug, proven via a real OpenRouter run).
-    kind: "general",
-    register(ctx) {
-      const { beforeToolCall, afterToolCall, beforeLLMCall, afterLLMCall, processInput } = hooks;
-      if (beforeToolCall) {
-        ctx.on("pre_tool_call", (c) => beforeToolCall({
-          name: c.name ?? "",
-          args: c.args ?? {}
-        }));
-      }
-      if (afterToolCall) {
-        ctx.on("post_tool_call", (c) => afterToolCall({
-          name: c.name ?? "",
-          result: c.result
-        }));
-      }
-      if (beforeLLMCall) {
-        ctx.on("pre_llm_call", (c) => beforeLLMCall({
-          agentId: c.agentId,
-          runId: c.runId,
-          iteration: c.iteration
-        }));
-      }
-      if (afterLLMCall) {
-        ctx.on("post_llm_call", (c) => afterLLMCall({
-          agentId: c.agentId,
-          runId: c.runId,
-          iteration: c.iteration
-        }));
-      }
-      if (processInput) {
-        ctx.on("pre_user_send", async (c) => {
-          const injected = await processInput({
-            prompt: c.prompt ?? "",
-            agentId: c.agentId,
-            runId: c.runId
-          });
-          return injected !== void 0 && injected.length > 0 ? {
-            recalledContext: injected
-          } : void 0;
-        });
-      }
-    }
-  };
-}
-__name(createToolHooksPlugin, "createToolHooksPlugin");
-
 // src/bridge/api-error-handler.ts
 var DEFAULT_MAX_ATTEMPTS = 3;
 async function runWithApiErrorHandling(thunk, policy) {
@@ -3497,6 +3562,7 @@ export {
   isError,
   isApprovalRequired,
   generateAgentRoutes,
+  createToolHooksPlugin,
   translateSdkEvent,
   buildModelSelection,
   createThinkTagExtractor,
@@ -3538,7 +3604,6 @@ export {
   GoalRunner,
   JudgeCredentialError,
   delegate,
-  createToolHooksPlugin,
   runWithApiErrorHandling,
   createApiErrorHandler,
   delegateBackground,
@@ -3549,4 +3614,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-GGB5WXHS.js.map
+//# sourceMappingURL=chunk-JXR45RAW.js.map