@robota-sdk/agent-core 3.0.0-beta.79 → 3.0.0-beta.81

package/dist/node/types-gNrckgFE.d.cts

@@ -0,0 +1,335 @@
+//#region src/interfaces/universal-value.d.ts
+/**
+ * Universal value type axis (recursive, JSON-like + Date).
+ *
+ * Extracted from `types.ts` into its own leaf module: several foundational modules (e.g.
+ * `provider.ts`) need only this axis, not the rest of `types.ts` (which itself depends on
+ * plugin-execution types) — importing the whole barrel there created a module-level import
+ * cycle. `types.ts` re-exports these names, so existing `from './types'` imports are unaffected.
+ *
+ * IMPORTANT:
+ * - This axis is the single source of truth for payload/context/result values.
+ * - It must support nested objects/arrays without `any`/`unknown`.
+ */
+/**
+ * Primitive value types - foundation for all other types
+ * Extended to include null/undefined for agent contexts
+ */
+type TPrimitiveValue = string | number | boolean | null | undefined;
+type TUniversalValue = TPrimitiveValue | Date | TUniversalArrayValue | IUniversalObjectValue;
+type TUniversalArrayValue = TUniversalValue[];
+interface IUniversalObjectValue {
+  [key: string]: TUniversalValue;
+}
+//#endregion
+//#region src/interfaces/model-effort-capability.d.ts
+/** Provider-neutral native effort controls. `auto` is selection state, not a control. */
+type TModelEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/** Runtime boundary vocabulary for a concrete provider-native effort control. */
+declare const MODEL_EFFORT_VALUES: readonly ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+declare function isModelEffort(value: TUniversalValue | undefined): value is TModelEffort;
+/** A caller can preserve provider-default selection without serializing a native control. */
+type TModelEffortSelection = TModelEffort | 'auto';
+/** The verified effort facts an adapter declares for one exact model identifier. */
+interface IModelEffortCapability {
+  supportedEfforts: readonly TModelEffort[];
+  defaultEffort: TModelEffort;
+  /** Adapter-owned opaque identity for the verified native control. */
+  nativeControlId: string;
+}
+/** Source-dated provider data. Core owns the shape but never provides the data. */
+interface IProviderModelEffortTable {
+  verifiedAt: string;
+  sourceUrl: string;
+  models: Readonly<Record<string, IModelEffortCapability>>;
+}
+type TModelEffortDisposition = 'exact' | 'clamped' | 'model-default' | 'not-applied';
+/** Serializable output of resolving a selection against a verified provider table. */
+interface IModelEffortResolution {
+  selection: TModelEffortSelection;
+  effective: TModelEffort | null;
+  disposition: TModelEffortDisposition;
+  fingerprint: string;
+}
+/** Whether the adapter serialized a verified native effort control. */
+type TModelEffortNativeControl = {
+  readonly state: 'sent';
+  readonly id: string;
+} | {
+  readonly state: 'omitted';
+  readonly reason: string;
+};
+/** Whether an endpoint dispatch occurred after the effort decision. */
+type TModelEffortProviderDispatch = {
+  readonly state: 'sent';
+} | {
+  readonly state: 'not-dispatched';
+  readonly reason: string;
+};
+/** Serializable terminal result of one effort-bearing provider request. */
+interface IModelEffortOutcome {
+  readonly resolution: IModelEffortResolution;
+  readonly nativeControl: TModelEffortNativeControl;
+  readonly providerDispatch: TModelEffortProviderDispatch;
+}
+/** Local observer for a request's one terminal provider effort outcome. */
+type TModelEffortOutcomeCallback = (outcome: IModelEffortOutcome) => void;
+/** Construct the three-fact terminal outcome without conflating its states. */
+declare function createModelEffortOutcome(resolution: IModelEffortResolution, outcome: Omit<IModelEffortOutcome, 'resolution'>): IModelEffortOutcome;
+/**
+ * Resolve only adapter-declared facts. Missing provider/model data never becomes a guessed default.
+ */
+declare function resolveModelEffort(table: IProviderModelEffortTable | undefined, modelId: string, selection: TModelEffortSelection): IModelEffortResolution;
+//#endregion
+//#region src/interfaces/trace-context.d.ts
+/**
+ * Trusted W3C trace context for a run's provider calls and child processes.
+ *
+ * A host that exports a trace for a prompt hands the run the trace it owns, the exact origins it
+ * trusts with that trace's identifiers, and the subprocess classes it lets inherit them. Nothing
+ * here is adopted from the ambient environment: the host decides, and a run without this context
+ * sends nothing.
+ */
+/** A class of child process a host may let receive `TRACEPARENT`. */
+type TSubprocessTraceClass = 'shell' | 'hooks';
+/** What one child process receives: exactly one environment variable, never `TRACESTATE`. */
+interface ISubprocessTraceEnv {
+  readonly TRACEPARENT: string;
+}
+/** The trace a host hands one run. */
+interface IRunTraceContext {
+  /** The host-owned trace ID (32 lowercase hex) every provider call of this run belongs to. */
+  readonly traceId: string;
+  /** The host's span under which each provider-call span is exported. */
+  readonly parentSpanId: string;
+  /** Exact origins (`scheme://host[:port]`) that may receive `traceparent`; may be empty. */
+  readonly allowedOrigins: readonly string[];
+  /**
+   * Child-process classes that receive `TRACEPARENT` in their environment. Derived separately from
+   * the origins, so a host may enable either without the other.
+   */
+  readonly subprocessClasses?: readonly TSubprocessTraceClass[];
+  /**
+   * Told when an invoked call's provider cannot carry trace context, and only when origins are
+   * listed: a run that propagates to subprocesses alone has nothing to tell. Receives the provider ID only,
+   * never an origin, URL or identifier, so a host can surface it without disclosing either.
+   */
+  readonly onPropagationUnavailable?: (providerId: string) => void;
+}
+/** What one invoked provider call carries: the header value and where it may go. */
+interface IOutboundTraceContext {
+  /** `00-<trace-id>-<provider-call-span-id>-01`. */
+  readonly traceparent: string;
+  /** Exact origins the adapter may send `traceparent` to; any other origin gets nothing. */
+  readonly allowedOrigins: readonly string[];
+}
+//#endregion
+//#region src/hooks/types.d.ts
+/**
+ * Hook lifecycle events.
+ *
+ * `PreModelCall`, `PostModelCall`, and `PermissionDecision` (SELFHOST-009) are
+ * INFORMATIONAL-ONLY: they are fired fire-and-forget from the turn owner at points it already
+ * observes and their `runHooks` result is NOT awaited or consulted for gating. The sole BLOCKING
+ * event is `PreToolUse`. The deny causes are enumerated once, in the catalog SSOT
+ * `packages/agent-core/docs/HOOK-CATALOG.md` § "Blocking semantics" — cited here rather than
+ * recounted, because two different groupings of the same set were in circulation and a second copy
+ * is what let them drift. Which events enforce is recorded in `HOOK_ENFORCEMENT_POLICY`
+ * (`./enforcement-policy.ts`); see the catalog SSOT `packages/agent-core/docs/HOOK-CATALOG.md` for
+ * per-event timing, fire-site, and blocking semantics.
+ */
+type THookEvent = 'PreToolUse' | 'PostToolUse' | 'SessionStart' | 'SessionEnd' | 'Stop' | 'StopFailure' | 'PreCompact' | 'PostCompact' | 'UserPromptSubmit' | 'SubagentStart' | 'SubagentStop' | 'WorktreeCreate' | 'WorktreeRemove' | 'PreModelCall' | 'PostModelCall' | 'PermissionDecision';
+/** Claude Code compatible session end reasons. */
+type TSessionEndReason = 'clear' | 'resume' | 'logout' | 'prompt_input_exit' | 'bypass_permissions_disabled' | 'other';
+/** Command hook — executes a shell command */
+interface ICommandHookDefinition {
+  type: 'command';
+  command: string;
+  timeout?: number;
+}
+/** HTTP hook — sends an HTTP request */
+interface IHttpHookDefinition {
+  type: 'http';
+  url: string;
+  headers?: Record<string, string>;
+  timeout?: number;
+}
+/** Prompt hook — evaluates a prompt via an AI model */
+interface IPromptHookDefinition {
+  type: 'prompt';
+  prompt: string;
+  model?: string;
+}
+/** Agent hook — delegates to a subagent */
+interface IAgentHookDefinition {
+  type: 'agent';
+  agent: string;
+  maxTurns?: number;
+  timeout?: number;
+}
+/**
+ * Guardrail hook (SELFHOST-005) — runs the registered guardrail SET in parallel and fails the turn
+ * fast. The guardrail functions live in the `GuardrailExecutor` (registered by the consumer); this
+ * data-only definition just selects which to run. Any failure maps onto the existing exit-code-2 /
+ * `blocked` contract, so enforcement reuses the single `runHooks` → `runPreToolHook` path.
+ */
+interface IGuardrailHookDefinition {
+  type: 'guardrail';
+  /** Names of registered guardrails to run; omitted = run ALL registered guardrails. */
+  guardrails?: string[];
+}
+/** Discriminated union of all hook definition types */
+type THookDefinition = ICommandHookDefinition | IHttpHookDefinition | IPromptHookDefinition | IAgentHookDefinition | IGuardrailHookDefinition;
+/**
+ * SELFHOST-005: the verdict a guardrail returns. `pass: false` fails the turn fast (mapped to the
+ * exit-code-2 / `blocked` hook contract).
+ */
+interface IGuardrailResult {
+  pass: boolean;
+  /** Human-readable reason surfaced when `pass === false`. */
+  reason?: string;
+}
+/**
+ * SELFHOST-005: a registerable guardrail — a pure MECHANISM that inspects the turn's hook input and
+ * votes pass/block. The POLICY (what to check) is the consumer's. Guardrails in a set run in parallel
+ * and the first `!pass` (or a thrown error — fail-safe) fails the turn fast.
+ */
+type TGuardrail = (input: IHookInput) => IGuardrailResult | Promise<IGuardrailResult>;
+/** A hook group — matcher + array of hook definitions */
+interface IHookGroup {
+  /** Regex pattern to match tool name (empty string = match all) */
+  matcher: string;
+  hooks: THookDefinition[];
+  /** Environment variables injected into hook child processes for this group */
+  env?: Record<string, string>;
+}
+/** Complete hooks configuration: event → array of hook groups */
+type THooksConfig = Partial<Record<THookEvent, IHookGroup[]>>;
+/** Input passed to hook commands via stdin */
+interface IHookInput {
+  session_id: string;
+  cwd: string;
+  hook_event_name: THookEvent;
+  tool_name?: string;
+  tool_input?: Record<string, string | number | boolean | object>;
+  tool_output?: string;
+  /** Compaction trigger source (PreCompact/PostCompact only) */
+  trigger?: 'auto' | 'manual';
+  /** Compaction summary text (PostCompact only) */
+  compact_summary?: string;
+  /** User message text (UserPromptSubmit only) */
+  user_message?: string;
+  /** User prompt text — Claude Code compatible alias for user_message (UserPromptSubmit only) */
+  prompt?: string;
+  /** Assistant response text (Stop only) */
+  response?: string;
+  /** Last assistant message text (StopFailure only) */
+  last_assistant_message?: string;
+  /** Stop hook recursion guard (Stop/StopFailure only) */
+  stop_hook_active?: boolean;
+  /** Session end reason (SessionEnd only) */
+  reason?: TSessionEndReason | string;
+  /** Session transcript path when available (SessionEnd/SubagentStop only) */
+  transcript_path?: string;
+  /** Subagent identifier (SubagentStart/SubagentStop only) */
+  agent_id?: string;
+  /** Subagent type/name (SubagentStart/SubagentStop only) */
+  agent_type?: string;
+  /** Subagent transcript path when available (SubagentStop only) */
+  agent_transcript_path?: string;
+  /** Claude Code permission mode at time of event (e.g. "default", "plan", "acceptEdits", "bypassPermissions") */
+  permission_mode?: string;
+  /**
+   * Provider model identifier for the model call (PreModelCall/PostModelCall only).
+   * SELFHOST-009 — informational.
+   */
+  model?: string;
+  /**
+   * Provider name for the model call (PreModelCall/PostModelCall only).
+   * SELFHOST-009 — informational.
+   */
+  provider?: string;
+  /**
+   * Model-effort selection for the model call (PreModelCall/PostModelCall only).
+   * API-001 — informational; `auto` remains provider-default selection.
+   */
+  effort?: TModelEffortSelection;
+  /** Agentic round index for the model call (PreModelCall/PostModelCall only). SELFHOST-009 — informational. */
+  round?: number;
+  /**
+   * Reported permission decision (PermissionDecision only) — the value `evaluatePermission` returned
+   * (`'auto' | 'approve' | 'deny'`). SELFHOST-009 — informational. This REPORTS a decision already made;
+   * it neither extends `TPermissionDecision` nor the internal `IRunHooksResult.permissionDecision`, and
+   * the hook cannot change the outcome.
+   */
+  permission_decision?: string;
+  /** Additional environment variables to pass to hook child processes */
+  env?: Record<string, string>;
+}
+/**
+ * Why a hook execution could not produce a verdict (SEC-015).
+ *
+ * The distinction these six names carry is the one the exit-code channel could not: a hook that
+ * DECIDED versus one that never got to. Which of the six it was is diagnostic detail; that it was
+ * any of them is what an enforcing consumer acts on.
+ */
+type THookErrorKind =
+/** The executor's own deadline elapsed before the hook answered. */
+'timeout' |
+/** The process or transport never started (ENOENT, EACCES, a refused handshake). */
+'spawn-failure' |
+/** It started and failed mid-flight — network drop, provider error, session failure. */
+'transport-failure' |
+/** A well-formed response carrying a non-2xx status. */
+'http-status' |
+/** A response arrived and could not be decoded into a verdict. */
+'malformed-response' |
+/** The process exited with a code that is neither 0 nor 2, or was killed by a signal. */
+'nonzero-exit';
+/** The hook approved. Its stdout carries the Claude Code response protocol, which the runner decodes. */
+interface IHookAllowOutcome {
+  readonly outcome: 'allow';
+  /** Which executor produced this outcome — preserved for diagnostics. */
+  readonly source: THookDefinition['type'];
+  readonly stdout: string;
+}
+/** The hook decided to block, and said why. */
+interface IHookDenyOutcome {
+  readonly outcome: 'deny';
+  /** Which executor produced this outcome — preserved for diagnostics. */
+  readonly source: THookDefinition['type'];
+  readonly reason: string;
+}
+/**
+ * The hook rendered no verdict.
+ *
+ * This is NOT a third verdict — it is the absence of one, and the policy for what an enforcing event
+ * does about it is deliberately not encoded here.
+ */
+interface IHookErrorOutcome {
+  readonly outcome: 'error';
+  /** Which executor produced this outcome — preserved for diagnostics. */
+  readonly source: THookDefinition['type'];
+  readonly kind: THookErrorKind;
+  readonly reason: string;
+}
+/**
+ * The decoded result of one hook execution (SEC-015).
+ *
+ * It replaces an `{ exitCode, stdout, stderr }` record whose only channel for a failure was a
+ * number, which forced every failure to be coerced into a verdict: a truthy non-boolean `ok` read
+ * as allow and disabled the gate, while a falsy or missing one read as deny and blocked the user's
+ * tool call on a decision no hook made. Making the third outcome representable is what removes the
+ * coercion — a malformed response is now `error`, which is neither.
+ */
+type THookOutcome = IHookAllowOutcome | IHookDenyOutcome | IHookErrorOutcome;
+/** Strategy interface for hook type executors */
+interface IHookTypeExecutor {
+  /** The hook type this executor handles */
+  type: THookDefinition['type'];
+  /** Execute a hook definition with the given input */
+  execute(definition: THookDefinition, input: IHookInput): Promise<THookOutcome>;
+}
+//#endregion
+export { TModelEffortProviderDispatch as A, IModelEffortResolution as C, TModelEffortDisposition as D, TModelEffort as E, IUniversalObjectValue as F, TPrimitiveValue as I, TUniversalArrayValue as L, createModelEffortOutcome as M, isModelEffort as N, TModelEffortNativeControl as O, resolveModelEffort as P, TUniversalValue as R, IModelEffortOutcome as S, MODEL_EFFORT_VALUES as T, IOutboundTraceContext as _, IHookErrorOutcome as a, TSubprocessTraceClass as b, IHookTypeExecutor as c, TGuardrail as d, THookDefinition as f, TSessionEndReason as g, THooksConfig as h, IGuardrailResult as i, TModelEffortSelection as j, TModelEffortOutcomeCallback as k, IHttpHookDefinition as l, THookOutcome as m, ICommandHookDefinition as n, IHookGroup as o, THookEvent as p, IGuardrailHookDefinition as r, IHookInput as s, IAgentHookDefinition as t, IPromptHookDefinition as u, IRunTraceContext as v, IProviderModelEffortTable as w, IModelEffortCapability as x, ISubprocessTraceEnv as y };
+//# sourceMappingURL=types-gNrckgFE.d.cts.map

package/dist/node/types-gNrckgFE.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-gNrckgFE.d.cts","names":[],"sources":["../../src/interfaces/universal-value.ts","../../src/interfaces/model-effort-capability.ts","../../src/interfaces/trace-context.ts","../../src/hooks/types.ts"],"mappings":";;;;;;;;;;;;;;;;;KAiBY;KAEA,kBAAkB,kBAAkB,OAAO,uBAAuB;KAElE,uBAAuB;UAElB;GACd,cAAc;;;;;KCvBL;;cAGC;iBAUG,cAAc,OAAO,8BAA8B,SAAS;;KAKhE,wBAAwB;;UAGnB;EACf,2BAA2B;EAC3B,eAAe;;EAEf;;;UAIe;EACf;EACA;EACA,QAAQ,SAAS,eAAe;;KAGtB;;UAGK;EACf,WAAW;EACX,WAAW;EACX,aAAa;EACb;;;KAIU;WACG;WAAwB;;WACxB;WAA2B;;;KAG9B;WACC;;WAA6B;WAAkC;;;UAG3D;WACN,YAAY;WACZ,eAAe;WACf,kBAAkB;;;KAIjB,+BAA+B,SAAS;;iBAGpC,yBACd,YAAY,wBACZ,SAAS,KAAK,qCACb;;;;iBAkBa,mBACd,OAAO,uCACP,iBACA,WAAW,wBACV;;;;;;;;;;;;KCjFS;;UAGK;WACN;;;UAIM;;WAEN;;WAEA;;WAEA;;;;;WAKA,6BAA6B;;;;;;WAM7B,4BAA4B;;;UAItB;;WAEN;;WAEA;;;;;;;;;;;;;;;;;KCxBC;;KAmBA;;UAIK;EACf;EACA;EACA;;;UAIe;EACf;EACA;EACA,UAAU;EACV;;;UAIe;EACf;EACA;EACA;;;UAIe;EACf;EACA;EACA;EACA;;;;;;;;UASe;EACf;;EAEA;;;KAIU,kBACR,yBACA,sBACA,wBACA,uBACA;;;;;UAMa;EACf;;EAEA;;;;;;;KAQU,cAAc,OAAO,eAAe,mBAAmB,QAAQ;;UAG1D;;EAEf;EACA,OAAO;;EAEP,MAAM;;;KAII,eAAe,QAAQ,OAAO,YAAY;;UAGrC;EACf;EACA;EACA,iBAAiB;EACjB;EACA,aAAa;EACb;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA,SAAS;;EAET;;EAEA;;EAEA;;EAEA;;EAEA;;;;;EAKA;;;;;EAKA;;;;;EAKA,SAAS;;EAET;;;;;;;EAOA;;EAEA,MAAM;;;;;;;;;KAUI;;;;;;;;;;;;;;UAeK;WACN;;WAEA,QAAQ;WACR;;;UAIM;WACN;;WAEA,QAAQ;WACR;;;;;;;;UASM;WACN;;WAEA,QAAQ;WACR,MAAM;WACN;;;;;;;;;;;KAYC,eAAe,oBAAoB,mBAAmB;;UAGjD;;EAEf,MAAM;;EAEN,QAAQ,YAAY,iBAAiB,OAAO,aAAa,QAAQ"}

package/dist/node/types-gNrckgFE.d.ts

@@ -0,0 +1,335 @@
+//#region src/interfaces/universal-value.d.ts
+/**
+ * Universal value type axis (recursive, JSON-like + Date).
+ *
+ * Extracted from `types.ts` into its own leaf module: several foundational modules (e.g.
+ * `provider.ts`) need only this axis, not the rest of `types.ts` (which itself depends on
+ * plugin-execution types) — importing the whole barrel there created a module-level import
+ * cycle. `types.ts` re-exports these names, so existing `from './types'` imports are unaffected.
+ *
+ * IMPORTANT:
+ * - This axis is the single source of truth for payload/context/result values.
+ * - It must support nested objects/arrays without `any`/`unknown`.
+ */
+/**
+ * Primitive value types - foundation for all other types
+ * Extended to include null/undefined for agent contexts
+ */
+type TPrimitiveValue = string | number | boolean | null | undefined;
+type TUniversalValue = TPrimitiveValue | Date | TUniversalArrayValue | IUniversalObjectValue;
+type TUniversalArrayValue = TUniversalValue[];
+interface IUniversalObjectValue {
+  [key: string]: TUniversalValue;
+}
+//#endregion
+//#region src/interfaces/model-effort-capability.d.ts
+/** Provider-neutral native effort controls. `auto` is selection state, not a control. */
+type TModelEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/** Runtime boundary vocabulary for a concrete provider-native effort control. */
+declare const MODEL_EFFORT_VALUES: readonly ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+declare function isModelEffort(value: TUniversalValue | undefined): value is TModelEffort;
+/** A caller can preserve provider-default selection without serializing a native control. */
+type TModelEffortSelection = TModelEffort | 'auto';
+/** The verified effort facts an adapter declares for one exact model identifier. */
+interface IModelEffortCapability {
+  supportedEfforts: readonly TModelEffort[];
+  defaultEffort: TModelEffort;
+  /** Adapter-owned opaque identity for the verified native control. */
+  nativeControlId: string;
+}
+/** Source-dated provider data. Core owns the shape but never provides the data. */
+interface IProviderModelEffortTable {
+  verifiedAt: string;
+  sourceUrl: string;
+  models: Readonly<Record<string, IModelEffortCapability>>;
+}
+type TModelEffortDisposition = 'exact' | 'clamped' | 'model-default' | 'not-applied';
+/** Serializable output of resolving a selection against a verified provider table. */
+interface IModelEffortResolution {
+  selection: TModelEffortSelection;
+  effective: TModelEffort | null;
+  disposition: TModelEffortDisposition;
+  fingerprint: string;
+}
+/** Whether the adapter serialized a verified native effort control. */
+type TModelEffortNativeControl = {
+  readonly state: 'sent';
+  readonly id: string;
+} | {
+  readonly state: 'omitted';
+  readonly reason: string;
+};
+/** Whether an endpoint dispatch occurred after the effort decision. */
+type TModelEffortProviderDispatch = {
+  readonly state: 'sent';
+} | {
+  readonly state: 'not-dispatched';
+  readonly reason: string;
+};
+/** Serializable terminal result of one effort-bearing provider request. */
+interface IModelEffortOutcome {
+  readonly resolution: IModelEffortResolution;
+  readonly nativeControl: TModelEffortNativeControl;
+  readonly providerDispatch: TModelEffortProviderDispatch;
+}
+/** Local observer for a request's one terminal provider effort outcome. */
+type TModelEffortOutcomeCallback = (outcome: IModelEffortOutcome) => void;
+/** Construct the three-fact terminal outcome without conflating its states. */
+declare function createModelEffortOutcome(resolution: IModelEffortResolution, outcome: Omit<IModelEffortOutcome, 'resolution'>): IModelEffortOutcome;
+/**
+ * Resolve only adapter-declared facts. Missing provider/model data never becomes a guessed default.
+ */
+declare function resolveModelEffort(table: IProviderModelEffortTable | undefined, modelId: string, selection: TModelEffortSelection): IModelEffortResolution;
+//#endregion
+//#region src/interfaces/trace-context.d.ts
+/**
+ * Trusted W3C trace context for a run's provider calls and child processes.
+ *
+ * A host that exports a trace for a prompt hands the run the trace it owns, the exact origins it
+ * trusts with that trace's identifiers, and the subprocess classes it lets inherit them. Nothing
+ * here is adopted from the ambient environment: the host decides, and a run without this context
+ * sends nothing.
+ */
+/** A class of child process a host may let receive `TRACEPARENT`. */
+type TSubprocessTraceClass = 'shell' | 'hooks';
+/** What one child process receives: exactly one environment variable, never `TRACESTATE`. */
+interface ISubprocessTraceEnv {
+  readonly TRACEPARENT: string;
+}
+/** The trace a host hands one run. */
+interface IRunTraceContext {
+  /** The host-owned trace ID (32 lowercase hex) every provider call of this run belongs to. */
+  readonly traceId: string;
+  /** The host's span under which each provider-call span is exported. */
+  readonly parentSpanId: string;
+  /** Exact origins (`scheme://host[:port]`) that may receive `traceparent`; may be empty. */
+  readonly allowedOrigins: readonly string[];
+  /**
+   * Child-process classes that receive `TRACEPARENT` in their environment. Derived separately from
+   * the origins, so a host may enable either without the other.
+   */
+  readonly subprocessClasses?: readonly TSubprocessTraceClass[];
+  /**
+   * Told when an invoked call's provider cannot carry trace context, and only when origins are
+   * listed: a run that propagates to subprocesses alone has nothing to tell. Receives the provider ID only,
+   * never an origin, URL or identifier, so a host can surface it without disclosing either.
+   */
+  readonly onPropagationUnavailable?: (providerId: string) => void;
+}
+/** What one invoked provider call carries: the header value and where it may go. */
+interface IOutboundTraceContext {
+  /** `00-<trace-id>-<provider-call-span-id>-01`. */
+  readonly traceparent: string;
+  /** Exact origins the adapter may send `traceparent` to; any other origin gets nothing. */
+  readonly allowedOrigins: readonly string[];
+}
+//#endregion
+//#region src/hooks/types.d.ts
+/**
+ * Hook lifecycle events.
+ *
+ * `PreModelCall`, `PostModelCall`, and `PermissionDecision` (SELFHOST-009) are
+ * INFORMATIONAL-ONLY: they are fired fire-and-forget from the turn owner at points it already
+ * observes and their `runHooks` result is NOT awaited or consulted for gating. The sole BLOCKING
+ * event is `PreToolUse`. The deny causes are enumerated once, in the catalog SSOT
+ * `packages/agent-core/docs/HOOK-CATALOG.md` § "Blocking semantics" — cited here rather than
+ * recounted, because two different groupings of the same set were in circulation and a second copy
+ * is what let them drift. Which events enforce is recorded in `HOOK_ENFORCEMENT_POLICY`
+ * (`./enforcement-policy.ts`); see the catalog SSOT `packages/agent-core/docs/HOOK-CATALOG.md` for
+ * per-event timing, fire-site, and blocking semantics.
+ */
+type THookEvent = 'PreToolUse' | 'PostToolUse' | 'SessionStart' | 'SessionEnd' | 'Stop' | 'StopFailure' | 'PreCompact' | 'PostCompact' | 'UserPromptSubmit' | 'SubagentStart' | 'SubagentStop' | 'WorktreeCreate' | 'WorktreeRemove' | 'PreModelCall' | 'PostModelCall' | 'PermissionDecision';
+/** Claude Code compatible session end reasons. */
+type TSessionEndReason = 'clear' | 'resume' | 'logout' | 'prompt_input_exit' | 'bypass_permissions_disabled' | 'other';
+/** Command hook — executes a shell command */
+interface ICommandHookDefinition {
+  type: 'command';
+  command: string;
+  timeout?: number;
+}
+/** HTTP hook — sends an HTTP request */
+interface IHttpHookDefinition {
+  type: 'http';
+  url: string;
+  headers?: Record<string, string>;
+  timeout?: number;
+}
+/** Prompt hook — evaluates a prompt via an AI model */
+interface IPromptHookDefinition {
+  type: 'prompt';
+  prompt: string;
+  model?: string;
+}
+/** Agent hook — delegates to a subagent */
+interface IAgentHookDefinition {
+  type: 'agent';
+  agent: string;
+  maxTurns?: number;
+  timeout?: number;
+}
+/**
+ * Guardrail hook (SELFHOST-005) — runs the registered guardrail SET in parallel and fails the turn
+ * fast. The guardrail functions live in the `GuardrailExecutor` (registered by the consumer); this
+ * data-only definition just selects which to run. Any failure maps onto the existing exit-code-2 /
+ * `blocked` contract, so enforcement reuses the single `runHooks` → `runPreToolHook` path.
+ */
+interface IGuardrailHookDefinition {
+  type: 'guardrail';
+  /** Names of registered guardrails to run; omitted = run ALL registered guardrails. */
+  guardrails?: string[];
+}
+/** Discriminated union of all hook definition types */
+type THookDefinition = ICommandHookDefinition | IHttpHookDefinition | IPromptHookDefinition | IAgentHookDefinition | IGuardrailHookDefinition;
+/**
+ * SELFHOST-005: the verdict a guardrail returns. `pass: false` fails the turn fast (mapped to the
+ * exit-code-2 / `blocked` hook contract).
+ */
+interface IGuardrailResult {
+  pass: boolean;
+  /** Human-readable reason surfaced when `pass === false`. */
+  reason?: string;
+}
+/**
+ * SELFHOST-005: a registerable guardrail — a pure MECHANISM that inspects the turn's hook input and
+ * votes pass/block. The POLICY (what to check) is the consumer's. Guardrails in a set run in parallel
+ * and the first `!pass` (or a thrown error — fail-safe) fails the turn fast.
+ */
+type TGuardrail = (input: IHookInput) => IGuardrailResult | Promise<IGuardrailResult>;
+/** A hook group — matcher + array of hook definitions */
+interface IHookGroup {
+  /** Regex pattern to match tool name (empty string = match all) */
+  matcher: string;
+  hooks: THookDefinition[];
+  /** Environment variables injected into hook child processes for this group */
+  env?: Record<string, string>;
+}
+/** Complete hooks configuration: event → array of hook groups */
+type THooksConfig = Partial<Record<THookEvent, IHookGroup[]>>;
+/** Input passed to hook commands via stdin */
+interface IHookInput {
+  session_id: string;
+  cwd: string;
+  hook_event_name: THookEvent;
+  tool_name?: string;
+  tool_input?: Record<string, string | number | boolean | object>;
+  tool_output?: string;
+  /** Compaction trigger source (PreCompact/PostCompact only) */
+  trigger?: 'auto' | 'manual';
+  /** Compaction summary text (PostCompact only) */
+  compact_summary?: string;
+  /** User message text (UserPromptSubmit only) */
+  user_message?: string;
+  /** User prompt text — Claude Code compatible alias for user_message (UserPromptSubmit only) */
+  prompt?: string;
+  /** Assistant response text (Stop only) */
+  response?: string;
+  /** Last assistant message text (StopFailure only) */
+  last_assistant_message?: string;
+  /** Stop hook recursion guard (Stop/StopFailure only) */
+  stop_hook_active?: boolean;
+  /** Session end reason (SessionEnd only) */
+  reason?: TSessionEndReason | string;
+  /** Session transcript path when available (SessionEnd/SubagentStop only) */
+  transcript_path?: string;
+  /** Subagent identifier (SubagentStart/SubagentStop only) */
+  agent_id?: string;
+  /** Subagent type/name (SubagentStart/SubagentStop only) */
+  agent_type?: string;
+  /** Subagent transcript path when available (SubagentStop only) */
+  agent_transcript_path?: string;
+  /** Claude Code permission mode at time of event (e.g. "default", "plan", "acceptEdits", "bypassPermissions") */
+  permission_mode?: string;
+  /**
+   * Provider model identifier for the model call (PreModelCall/PostModelCall only).
+   * SELFHOST-009 — informational.
+   */
+  model?: string;
+  /**
+   * Provider name for the model call (PreModelCall/PostModelCall only).
+   * SELFHOST-009 — informational.
+   */
+  provider?: string;
+  /**
+   * Model-effort selection for the model call (PreModelCall/PostModelCall only).
+   * API-001 — informational; `auto` remains provider-default selection.
+   */
+  effort?: TModelEffortSelection;
+  /** Agentic round index for the model call (PreModelCall/PostModelCall only). SELFHOST-009 — informational. */
+  round?: number;
+  /**
+   * Reported permission decision (PermissionDecision only) — the value `evaluatePermission` returned
+   * (`'auto' | 'approve' | 'deny'`). SELFHOST-009 — informational. This REPORTS a decision already made;
+   * it neither extends `TPermissionDecision` nor the internal `IRunHooksResult.permissionDecision`, and
+   * the hook cannot change the outcome.
+   */
+  permission_decision?: string;
+  /** Additional environment variables to pass to hook child processes */
+  env?: Record<string, string>;
+}
+/**
+ * Why a hook execution could not produce a verdict (SEC-015).
+ *
+ * The distinction these six names carry is the one the exit-code channel could not: a hook that
+ * DECIDED versus one that never got to. Which of the six it was is diagnostic detail; that it was
+ * any of them is what an enforcing consumer acts on.
+ */
+type THookErrorKind =
+/** The executor's own deadline elapsed before the hook answered. */
+'timeout' |
+/** The process or transport never started (ENOENT, EACCES, a refused handshake). */
+'spawn-failure' |
+/** It started and failed mid-flight — network drop, provider error, session failure. */
+'transport-failure' |
+/** A well-formed response carrying a non-2xx status. */
+'http-status' |
+/** A response arrived and could not be decoded into a verdict. */
+'malformed-response' |
+/** The process exited with a code that is neither 0 nor 2, or was killed by a signal. */
+'nonzero-exit';
+/** The hook approved. Its stdout carries the Claude Code response protocol, which the runner decodes. */
+interface IHookAllowOutcome {
+  readonly outcome: 'allow';
+  /** Which executor produced this outcome — preserved for diagnostics. */
+  readonly source: THookDefinition['type'];
+  readonly stdout: string;
+}
+/** The hook decided to block, and said why. */
+interface IHookDenyOutcome {
+  readonly outcome: 'deny';
+  /** Which executor produced this outcome — preserved for diagnostics. */
+  readonly source: THookDefinition['type'];
+  readonly reason: string;
+}
+/**
+ * The hook rendered no verdict.
+ *
+ * This is NOT a third verdict — it is the absence of one, and the policy for what an enforcing event
+ * does about it is deliberately not encoded here.
+ */
+interface IHookErrorOutcome {
+  readonly outcome: 'error';
+  /** Which executor produced this outcome — preserved for diagnostics. */
+  readonly source: THookDefinition['type'];
+  readonly kind: THookErrorKind;
+  readonly reason: string;
+}
+/**
+ * The decoded result of one hook execution (SEC-015).
+ *
+ * It replaces an `{ exitCode, stdout, stderr }` record whose only channel for a failure was a
+ * number, which forced every failure to be coerced into a verdict: a truthy non-boolean `ok` read
+ * as allow and disabled the gate, while a falsy or missing one read as deny and blocked the user's
+ * tool call on a decision no hook made. Making the third outcome representable is what removes the
+ * coercion — a malformed response is now `error`, which is neither.
+ */
+type THookOutcome = IHookAllowOutcome | IHookDenyOutcome | IHookErrorOutcome;
+/** Strategy interface for hook type executors */
+interface IHookTypeExecutor {
+  /** The hook type this executor handles */
+  type: THookDefinition['type'];
+  /** Execute a hook definition with the given input */
+  execute(definition: THookDefinition, input: IHookInput): Promise<THookOutcome>;
+}
+//#endregion
+export { TModelEffortProviderDispatch as A, IModelEffortResolution as C, TModelEffortDisposition as D, TModelEffort as E, IUniversalObjectValue as F, TPrimitiveValue as I, TUniversalArrayValue as L, createModelEffortOutcome as M, isModelEffort as N, TModelEffortNativeControl as O, resolveModelEffort as P, TUniversalValue as R, IModelEffortOutcome as S, MODEL_EFFORT_VALUES as T, IOutboundTraceContext as _, IHookErrorOutcome as a, TSubprocessTraceClass as b, IHookTypeExecutor as c, TGuardrail as d, THookDefinition as f, TSessionEndReason as g, THooksConfig as h, IGuardrailResult as i, TModelEffortSelection as j, TModelEffortOutcomeCallback as k, IHttpHookDefinition as l, THookOutcome as m, ICommandHookDefinition as n, IHookGroup as o, THookEvent as p, IGuardrailHookDefinition as r, IHookInput as s, IAgentHookDefinition as t, IPromptHookDefinition as u, IRunTraceContext as v, IProviderModelEffortTable as w, IModelEffortCapability as x, ISubprocessTraceEnv as y };
+//# sourceMappingURL=types-gNrckgFE.d.ts.map