@theokit/sdk 5.3.1 → 5.3.3

package/dist/subagents-loader.d.cts

@@ -1,4 +1,4 @@
-import { a as AgentDefinition } from './agent-C3KO5LKm.cjs';
+import { a as AgentDefinition } from './agent-QLwxhXY3.cjs';
 import './sdk-agent-BOiKqOgL.cjs';
 import './run-CTAdRU3U.cjs';
 import 'zod';

package/dist/subagents-loader.d.ts

@@ -1,4 +1,4 @@
-import { a as AgentDefinition } from './agent-CvmTR9uf.js';
+import { a as AgentDefinition } from './agent-CTbU0O1R.js';
 import './sdk-agent-D4a_BR_6.js';
 import './run-CTAdRU3U.js';
 import 'zod';

package/dist/types/plugin.d.ts

@@ -41,6 +41,8 @@ import type { ProviderProfile } from "./provider-profile.js";
  *   `on_session_end`, `post_assistant_reply`) is fire-and-forget: the return value is DISCARDED. A
  *   policy that needs to change a tool result belongs on `transform_tool_result` — put it on
  *   `post_tool_call` and it quietly degrades to observation.
+ * - `on_session_start` / `on_session_end` fire once per **run**, not once per agent lifetime — see
+ *   {@link SessionLifecycleContext}. Build an agent per turn and they fire on every message.
  *
  * Failure is asymmetric too. A fire-and-forget or transform handler that throws is caught, logged to
  * stderr, and the run continues. A `pre_tool_call` handler that throws is NOT caught by the hook
@@ -120,7 +122,24 @@ export interface LlmCallContext {
     /** Iteration index (0-based) of the current turn, when available. */
     iteration?: number;
 }
-/** #65 — context for the `on_session_start` / `on_session_end` hooks. @public */
+/**
+ * #65 — context for the `on_session_start` / `on_session_end` hooks.
+ *
+ * **These fire once per RUN, not once per agent lifetime**, and the `runId` on this very context is
+ * the tell: it changes every time they fire. "Session" here means one pass through the agent loop.
+ *
+ * The distinction is invisible to an application that creates an agent once and sends many messages
+ * — there, per-run and per-session coincide. It is decisive for one that builds an agent **per
+ * turn**: `on_session_start` then fires on every message, which is the opposite of what a handler
+ * named for a session start usually assumes.
+ *
+ * Stated here because it was not stated anywhere a consumer could read it. The only accurate
+ * sentence lived in an internal comment at the firing site, and in 2026-09 that cost two people
+ * hours and produced a defect report filed against this package for behaviour that is correct.
+ * `test_on_session_start_fires_once_per_run_and_again_on_the_next_run` now pins it.
+ *
+ * @public
+ */
 export interface SessionLifecycleContext {
     agentId: string;
     runId: string;

package/docs/error-codes.md

@@ -79,10 +79,10 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `handoff_target_required` | domain | ConfigurationError | `packages/sdk-handoff/src/handoff.ts:111` |
 | `hitl_timeout` | domain | HitlTimeoutError | `packages/sdk/src/internal/runtime/tools/hitl-middleware.ts:42` +1 |
 | `hook_denied` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent.ts:454` |
-| `hooks_invalid_command` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:272` |
+| `hooks_invalid_command` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:295` |
 | `hooks_json_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:190` +2 |
 | `hooks_read_error` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:181` |
-| `hooks_unsupported_type` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:266` |
+| `hooks_unsupported_type` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:289` |
 | `interactive_unavailable` | domain | InteractiveUnavailableError | `packages/sdk/src/interactive/types.ts:28` +1 |
 | `INTERNAL_SERVER_ERROR` | domain | — | `packages/sdk/src/server/errors-envelope.ts:100` |
 | `invalid_argument` | domain | TheokitAgentError | `packages/sdk/src/compaction.ts:79` |

package/docs/harness-capability-map.md

@@ -357,7 +357,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `Security` | class | Public security namespace (T2.1, ADR D68).  |
 | `SecurityFloorInput` | interface | The vocabulary, the layer names, and the values to resolve.  |
 | `SendOptions` | interface | Per-send overrides and callbacks.  |
-| `SessionLifecycleContext` | interface | #65 — context for the `on_session_start` / `on_session_end` hooks. |
+| `SessionLifecycleContext` | interface | #65 — context for the `on_session_start` / `on_session_end` hooks.  |
 | `SessionMessage` | interface | One turn of a session.  |
 | `SessionMessagePart` | type | One structured element of a {@link SessionMessage } .  |
 | `SessionRecord` | interface | One transcript record — a single line of the session JSONL file, and the unit the pluggable `SessionStore` seam reads and writes.  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "5.3.1",
+  "version": "5.3.3",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheokit/theokit-sdk#readme",

package/dist/chunk-AI4MXACC.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/internal/runtime/hooks/hooks-source.ts","../src/internal/personality/context.ts"],"names":[],"mappings":"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","file":"chunk-AI4MXACC.js","sourcesContent":["/**\n * Single source of truth for loading the hooks config (ADR 0016 — reverses\n * D74/D77 for hooks: JSON is canonical again, in the Claude Code shape).\n *\n * `.theokit/hooks.json` (Claude-Code-shaped JSON) is the only supported form.\n * A stray legacy `.theokit/hooks/*.md` dir (no hooks.json) is NOT loaded — it\n * warns to migrate and yields no hooks. Absent both → empty config.\n *\n * Consumed by `hooks-executor.ts` (runtime dispatch).\n *\n * Config shape (identical to Claude Code's `settings.json` hooks):\n *   { \"hooks\": { \"PreToolUse\": [ { \"matcher\": \"shell\",\n *       \"hooks\": [ { \"type\": \"command\", \"command\": \"…\", \"timeout\": 30 } ] } ] } }\n *\n * @internal\n */\n\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { ConfigurationError } from \"../../../errors.js\";\nimport { diag } from \"../../diagnostics.js\";\nimport { projectConfigRoots, theokitConfigRoot } from \"../../persistence/paths.js\";\nimport type { CompatSourceDeclaration } from \"../compat/foreign-config-sources.js\";\n\n/** The five lifecycle events the SDK runtime actually fires. */\nexport type HookEvent = \"preRun\" | \"postRun\" | \"preToolUse\" | \"postToolUse\" | \"stop\";\n\n/**\n * Claude Code event name → the SDK firing event. Only events the runtime\n * genuinely emits are mapped; a Claude Code event with no SDK firing point\n * (SessionStart / SubagentStop / PreCompact / Notification / SessionEnd) is\n * skipped with a warn rather than silently accepted (it would never run).\n */\nconst CLAUDE_CODE_EVENT_MAP: Readonly<Record<string, HookEvent>> = {\n  PreToolUse: \"preToolUse\",\n  PostToolUse: \"postToolUse\",\n  UserPromptSubmit: \"preRun\",\n  Stop: \"stop\",\n};\n\nexport interface HookCommand {\n  command: string;\n  matcher?: string;\n  timeoutMs?: number;\n  /**\n   * The config file this command was declared in.\n   *\n   * Carried so the executor can supply the runtime contract the declaring DIALECT presumes — a\n   * command from `.claude/settings.json` is written against Claude Code's runtime and expects\n   * `$CLAUDE_PROJECT_DIR` to exist (#522). Absent for a command built in memory, which is native by\n   * construction.\n   */\n  sourcePath?: string;\n}\n\nexport interface HookConfig {\n  hooks?: Partial<Record<HookEvent, HookCommand[]>>;\n}\n\nconst warned = new Set<string>();\n\n/**\n * Emit a stderr warn once per process per unique key. Helps surface the\n * deprecation path without spamming when the loader is called many times\n * during a session (cron + send + skills all hit this).\n *\n * Note: spawned workers (cron, subagent) start fresh processes — warn\n * re-emits there, by design (1 per process boot, not per call).\n *\n * @internal\n */\nexport function warnOnce(key: string, message: string): void {\n  if (warned.has(key)) return;\n  warned.add(key);\n  diag(`${message}\\n`);\n}\n\n/** Reset for tests; not exported via barrel. @internal */\nexport function _resetWarnOnceForTests(): void {\n  warned.clear();\n}\n\n/**\n * Load hooks from `.theokit/hooks.json` (Claude-Code-shaped — the only supported\n * form). A stray legacy `.theokit/hooks/*.md` markdown dir (no `hooks.json`) is\n * NOT loaded — it emits a one-time migration warn and yields no hooks.\n *\n * @internal\n */\nexport async function loadHookConfig(\n  cwd: string,\n  compatSources: readonly CompatSourceDeclaration[] = [],\n): Promise<HookConfig> {\n  const merged: HookConfig = {};\n  let sawAny = false;\n  for (const path of hookConfigCandidates(cwd, compatSources)) {\n    if (!existsSync(path)) continue;\n    sawAny = true;\n    // Stamped at merge, where the file is still known. One line later the commands are pooled per\n    // event and every trace of which dialect declared them is gone — which is how a Claude Code\n    // command came to be run without Claude Code's runtime (#522).\n    mergeInto(merged, stampSource(await readHookFile(path), path));\n  }\n  if (!sawAny && existsSync(join(theokitConfigRoot(cwd), \"hooks\"))) {\n    warnOnce(\n      \"hooks-md-unsupported\",\n      \"[theokit-sdk] .theokit/hooks/*.md hooks are no longer supported (ADR 0016) — migrate to a Claude-Code-shaped .theokit/hooks.json\",\n    );\n  }\n  return merged;\n}\n\n/**\n * Every file that may declare hooks, in precedence order.\n *\n * `hooks.json` under each project config root, then the Claude Code CLI's own settings files — which\n * is where the CLI actually keeps hooks, so a repository set up for it presents its hooks here\n * without being converted. `settings.local.json` is the CLI's personal-override file and sits beside\n * the shared one rather than replacing it.\n *\n * The shape never needed translating: `parseClaudeCodeConfig` reads the `hooks` key off whatever\n * object it is given, and a settings file is that same object with other keys alongside.\n */\nfunction hookConfigCandidates(\n  cwd: string,\n  compatSources: readonly CompatSourceDeclaration[],\n): string[] {\n  const roots = projectConfigRoots(cwd, compatSources, \"hooks\");\n  return [\n    ...roots.map((root) => join(root, \"hooks.json\")),\n    ...roots.map((root) => join(root, \"settings.json\")),\n    ...roots.map((root) => join(root, \"settings.local.json\")),\n  ];\n}\n\n/**\n * Record which file each command came from.\n *\n * A command already carrying a `sourcePath` keeps it: nothing produces that today, and a nested\n * config that declared its own origin would be describing something this function cannot see.\n */\nfunction stampSource(config: HookConfig, sourcePath: string): HookConfig {\n  if (config.hooks === undefined) return config;\n  const hooks: NonNullable<HookConfig[\"hooks\"]> = {};\n  for (const [event, commands] of Object.entries(config.hooks) as [\n    HookEvent,\n    HookCommand[] | undefined,\n  ][]) {\n    if (commands === undefined) continue;\n    hooks[event] = commands.map((c) => ({ sourcePath, ...c }));\n  }\n  return { hooks };\n}\n\n/**\n * Append one source's commands onto the accumulator, per event.\n *\n * MERGED, not first-wins, and the distinction is deliberate. An agent or a skill is a NAMED\n * declaration: two files claiming one name collide, and the explicit namespace should win. Hooks are\n * unnamed lists — two files declaring `PreToolUse` are two sets of commands an operator wrote, and\n * keeping only one drops the other in silence, which is the failure class this package guards\n * against everywhere else.\n */\nfunction mergeInto(target: HookConfig, source: HookConfig): void {\n  for (const [event, commands] of Object.entries(source.hooks ?? {}) as [\n    HookEvent,\n    HookCommand[] | undefined,\n  ][]) {\n    if (commands === undefined || commands.length === 0) continue;\n    target.hooks ??= {};\n    target.hooks[event] = [...(target.hooks[event] ?? []), ...commands];\n  }\n}\n\nasync function readHookFile(jsonPath: string): Promise<HookConfig> {\n  let raw: string;\n  try {\n    raw = await readFile(jsonPath, \"utf8\");\n  } catch (cause) {\n    throw new ConfigurationError(`Failed to read hooks config: ${jsonPath}`, {\n      code: \"hooks_read_error\",\n      cause,\n    });\n  }\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch (cause) {\n    throw new ConfigurationError(`Invalid JSON in hooks config: ${jsonPath}`, {\n      code: \"hooks_json_invalid\",\n      cause,\n    });\n  }\n  return parseClaudeCodeConfig(parsed, jsonPath);\n}\n\n/** Narrow an unknown to a record, or throw a typed config error. */\nfunction asRecord(value: unknown, path: string, where: string): Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new ConfigurationError(`hooks: expected an object at ${where} in ${path}`, {\n      code: \"hooks_json_invalid\",\n    });\n  }\n  return value as Record<string, unknown>;\n}\n\n/** Narrow an unknown to an array, or throw a typed config error. */\nfunction asArray(value: unknown, path: string, where: string): unknown[] {\n  if (!Array.isArray(value)) {\n    throw new ConfigurationError(`hooks: expected an array at ${where} in ${path}`, {\n      code: \"hooks_json_invalid\",\n    });\n  }\n  return value;\n}\n\n/**\n * Parse Claude Code's nested hooks config into the SDK's flat internal shape:\n * `{ hooks: { PreToolUse: [{ matcher?, hooks: [{ type:\"command\", command, timeout? }] }] } }`\n * → `{ hooks: { preToolUse: [{ command, matcher?, timeoutMs? }] } }`. Each group's\n * `matcher` applies to every command it wraps; `timeout` (seconds) → `timeoutMs`.\n */\nfunction parseClaudeCodeConfig(raw: unknown, path: string): HookConfig {\n  const root = asRecord(raw, path, \"the root\");\n  if (root.hooks === undefined) return {};\n  const hooksRec = asRecord(root.hooks, path, `\"hooks\"`);\n  const grouped: Partial<Record<HookEvent, HookCommand[]>> = {};\n\n  for (const [ccEvent, groups] of Object.entries(hooksRec)) {\n    const event = CLAUDE_CODE_EVENT_MAP[ccEvent];\n    if (event === undefined) {\n      warnOnce(\n        `hooks-event-${ccEvent}`,\n        `[theokit-sdk] hooks: event \"${ccEvent}\" is not fired by the SDK runtime (supported: ${Object.keys(CLAUDE_CODE_EVENT_MAP).join(\", \")}) — skipping`,\n      );\n      continue;\n    }\n    grouped[event] = [...(grouped[event] ?? []), ...flattenEventGroups(groups, path, ccEvent)];\n  }\n  return { hooks: grouped };\n}\n\n/** Flatten one Claude Code event's matcher-groups into internal HookCommands. */\nfunction flattenEventGroups(groups: unknown, path: string, ccEvent: string): HookCommand[] {\n  const commands: HookCommand[] = [];\n  for (const rawGroup of asArray(groups, path, `hooks.${ccEvent}`)) {\n    const group = asRecord(rawGroup, path, `hooks.${ccEvent}[]`);\n    const matcher = group.matcher === undefined ? undefined : String(group.matcher);\n    for (const rawCmd of asArray(group.hooks, path, `hooks.${ccEvent}[].hooks`)) {\n      commands.push(parseClaudeCodeCommand(rawCmd, matcher, path, ccEvent));\n    }\n  }\n  return commands;\n}\n\n/** One `{ type:\"command\", command, timeout? }` entry → an internal HookCommand. */\nfunction parseClaudeCodeCommand(\n  raw: unknown,\n  matcher: string | undefined,\n  path: string,\n  ccEvent: string,\n): HookCommand {\n  const cmd = asRecord(raw, path, `hooks.${ccEvent}[].hooks[]`);\n  if (cmd.type !== \"command\") {\n    throw new ConfigurationError(\n      `hooks: only { \"type\": \"command\" } is supported (got ${JSON.stringify(cmd.type)}) in ${path}`,\n      { code: \"hooks_unsupported_type\" },\n    );\n  }\n  if (typeof cmd.command !== \"string\" || cmd.command.length === 0) {\n    throw new ConfigurationError(`hooks: \"command\" must be a non-empty string in ${path}`, {\n      code: \"hooks_invalid_command\",\n    });\n  }\n  const hc: HookCommand = { command: cmd.command };\n  if (matcher !== undefined) hc.matcher = matcher;\n  if (typeof cmd.timeout === \"number\" && cmd.timeout > 0) {\n    hc.timeoutMs = Math.round(cmd.timeout * 1000);\n  }\n  return hc;\n}\n","/**\n * Personality fork-context (ADR D168 + EC-A snapshot semantic).\n *\n * Uses Node's `AsyncLocalStorage` so a fork's execution chain can know\n * that it is running inside a fork AND can see the slug that was active\n * on the parent **at fork-construction time**.\n *\n * **EC-A:** The slug stored here is captured ONCE at the wrap site\n * (`localAgentFork`) — passing `parentStore.active(parentAgentId)`\n * returns a primitive `string | undefined`, which is then frozen\n * inside the ALS context object. Subsequent `usePersonality` calls on\n * the parent do NOT mutate the fork's view, because the fork reads from\n * its own ALS frame, not from the parent's store.\n *\n * @internal\n */\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\nimport { warnOnce } from \"../runtime/hooks/hooks-source.js\";\n\n/**\n * Snapshot data carried into a fork's async context.\n *\n * @internal\n */\nexport interface PersonalityForkContext {\n  /** Parent's active personality slug at fork-construction time. */\n  readonly slug: string | undefined;\n  /** Always `true` inside this scope (used by guards). */\n  readonly isFork: true;\n}\n\nconst storage = new AsyncLocalStorage<PersonalityForkContext>();\n\n/**\n * Run `fn` with `ctx` bound as the active fork context. Nested calls\n * shadow the outer context (EC-22).\n *\n * @internal\n */\nexport function withPersonalityContext<T>(\n  ctx: PersonalityForkContext,\n  fn: () => Promise<T>,\n): Promise<T> {\n  return storage.run(ctx, fn);\n}\n\n/**\n * Return the active fork context, or `undefined` when called outside a\n * fork scope.\n *\n * @internal\n */\nexport function currentPersonalityContext(): PersonalityForkContext | undefined {\n  return storage.getStore();\n}\n\n/**\n * Emit one warning per agentId stating that personality switches inside\n * a fork are no-ops. The fork inherits the parent snapshot — runtime\n * mutation is intentionally rejected to keep fork voice deterministic.\n *\n * @internal\n */\nexport function warnPersonalitySwitchInsideFork(agentId: string): void {\n  warnOnce(\n    `personality-switch-in-fork-${agentId}`,\n    `[theokit-sdk] usePersonality is a no-op inside a fork (D168). Subagents inherit the parent's active personality at fork-construction time.`,\n  );\n}\n"]}

package/dist/chunk-SSIRPWWD.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/internal/runtime/hooks/hooks-source.ts","../src/internal/personality/context.ts"],"names":["diag","existsSync","join","theokitConfigRoot","projectConfigRoots","readFile","ConfigurationError","AsyncLocalStorage"],"mappings":"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","file":"chunk-SSIRPWWD.cjs","sourcesContent":["/**\n * Single source of truth for loading the hooks config (ADR 0016 — reverses\n * D74/D77 for hooks: JSON is canonical again, in the Claude Code shape).\n *\n * `.theokit/hooks.json` (Claude-Code-shaped JSON) is the only supported form.\n * A stray legacy `.theokit/hooks/*.md` dir (no hooks.json) is NOT loaded — it\n * warns to migrate and yields no hooks. Absent both → empty config.\n *\n * Consumed by `hooks-executor.ts` (runtime dispatch).\n *\n * Config shape (identical to Claude Code's `settings.json` hooks):\n *   { \"hooks\": { \"PreToolUse\": [ { \"matcher\": \"shell\",\n *       \"hooks\": [ { \"type\": \"command\", \"command\": \"…\", \"timeout\": 30 } ] } ] } }\n *\n * @internal\n */\n\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { ConfigurationError } from \"../../../errors.js\";\nimport { diag } from \"../../diagnostics.js\";\nimport { projectConfigRoots, theokitConfigRoot } from \"../../persistence/paths.js\";\nimport type { CompatSourceDeclaration } from \"../compat/foreign-config-sources.js\";\n\n/** The five lifecycle events the SDK runtime actually fires. */\nexport type HookEvent = \"preRun\" | \"postRun\" | \"preToolUse\" | \"postToolUse\" | \"stop\";\n\n/**\n * Claude Code event name → the SDK firing event. Only events the runtime\n * genuinely emits are mapped; a Claude Code event with no SDK firing point\n * (SessionStart / SubagentStop / PreCompact / Notification / SessionEnd) is\n * skipped with a warn rather than silently accepted (it would never run).\n */\nconst CLAUDE_CODE_EVENT_MAP: Readonly<Record<string, HookEvent>> = {\n  PreToolUse: \"preToolUse\",\n  PostToolUse: \"postToolUse\",\n  UserPromptSubmit: \"preRun\",\n  Stop: \"stop\",\n};\n\nexport interface HookCommand {\n  command: string;\n  matcher?: string;\n  timeoutMs?: number;\n  /**\n   * The config file this command was declared in.\n   *\n   * Carried so the executor can supply the runtime contract the declaring DIALECT presumes — a\n   * command from `.claude/settings.json` is written against Claude Code's runtime and expects\n   * `$CLAUDE_PROJECT_DIR` to exist (#522). Absent for a command built in memory, which is native by\n   * construction.\n   */\n  sourcePath?: string;\n}\n\nexport interface HookConfig {\n  hooks?: Partial<Record<HookEvent, HookCommand[]>>;\n}\n\nconst warned = new Set<string>();\n\n/**\n * Emit a stderr warn once per process per unique key. Helps surface the\n * deprecation path without spamming when the loader is called many times\n * during a session (cron + send + skills all hit this).\n *\n * Note: spawned workers (cron, subagent) start fresh processes — warn\n * re-emits there, by design (1 per process boot, not per call).\n *\n * @internal\n */\nexport function warnOnce(key: string, message: string): void {\n  if (warned.has(key)) return;\n  warned.add(key);\n  diag(`${message}\\n`);\n}\n\n/** Reset for tests; not exported via barrel. @internal */\nexport function _resetWarnOnceForTests(): void {\n  warned.clear();\n}\n\n/**\n * Load hooks from `.theokit/hooks.json` (Claude-Code-shaped — the only supported\n * form). A stray legacy `.theokit/hooks/*.md` markdown dir (no `hooks.json`) is\n * NOT loaded — it emits a one-time migration warn and yields no hooks.\n *\n * @internal\n */\nexport async function loadHookConfig(\n  cwd: string,\n  compatSources: readonly CompatSourceDeclaration[] = [],\n): Promise<HookConfig> {\n  const merged: HookConfig = {};\n  let sawAny = false;\n  for (const path of hookConfigCandidates(cwd, compatSources)) {\n    if (!existsSync(path)) continue;\n    sawAny = true;\n    // Stamped at merge, where the file is still known. One line later the commands are pooled per\n    // event and every trace of which dialect declared them is gone — which is how a Claude Code\n    // command came to be run without Claude Code's runtime (#522).\n    mergeInto(merged, stampSource(await readHookFile(path), path));\n  }\n  if (!sawAny && existsSync(join(theokitConfigRoot(cwd), \"hooks\"))) {\n    warnOnce(\n      \"hooks-md-unsupported\",\n      \"[theokit-sdk] .theokit/hooks/*.md hooks are no longer supported (ADR 0016) — migrate to a Claude-Code-shaped .theokit/hooks.json\",\n    );\n  }\n  return merged;\n}\n\n/**\n * Every file that may declare hooks, in precedence order.\n *\n * `hooks.json` under each project config root, then the Claude Code CLI's own settings files — which\n * is where the CLI actually keeps hooks, so a repository set up for it presents its hooks here\n * without being converted. `settings.local.json` is the CLI's personal-override file and sits beside\n * the shared one rather than replacing it.\n *\n * The shape never needed translating: `parseClaudeCodeConfig` reads the `hooks` key off whatever\n * object it is given, and a settings file is that same object with other keys alongside.\n */\nfunction hookConfigCandidates(\n  cwd: string,\n  compatSources: readonly CompatSourceDeclaration[],\n): string[] {\n  const roots = projectConfigRoots(cwd, compatSources, \"hooks\");\n  return [\n    ...roots.map((root) => join(root, \"hooks.json\")),\n    ...roots.map((root) => join(root, \"settings.json\")),\n    ...roots.map((root) => join(root, \"settings.local.json\")),\n  ];\n}\n\n/**\n * Record which file each command came from.\n *\n * A command already carrying a `sourcePath` keeps it: nothing produces that today, and a nested\n * config that declared its own origin would be describing something this function cannot see.\n */\nfunction stampSource(config: HookConfig, sourcePath: string): HookConfig {\n  if (config.hooks === undefined) return config;\n  const hooks: NonNullable<HookConfig[\"hooks\"]> = {};\n  for (const [event, commands] of Object.entries(config.hooks) as [\n    HookEvent,\n    HookCommand[] | undefined,\n  ][]) {\n    if (commands === undefined) continue;\n    hooks[event] = commands.map((c) => ({ sourcePath, ...c }));\n  }\n  return { hooks };\n}\n\n/**\n * Append one source's commands onto the accumulator, per event.\n *\n * MERGED, not first-wins, and the distinction is deliberate. An agent or a skill is a NAMED\n * declaration: two files claiming one name collide, and the explicit namespace should win. Hooks are\n * unnamed lists — two files declaring `PreToolUse` are two sets of commands an operator wrote, and\n * keeping only one drops the other in silence, which is the failure class this package guards\n * against everywhere else.\n */\nfunction mergeInto(target: HookConfig, source: HookConfig): void {\n  for (const [event, commands] of Object.entries(source.hooks ?? {}) as [\n    HookEvent,\n    HookCommand[] | undefined,\n  ][]) {\n    if (commands === undefined || commands.length === 0) continue;\n    target.hooks ??= {};\n    target.hooks[event] = [...(target.hooks[event] ?? []), ...commands];\n  }\n}\n\nasync function readHookFile(jsonPath: string): Promise<HookConfig> {\n  let raw: string;\n  try {\n    raw = await readFile(jsonPath, \"utf8\");\n  } catch (cause) {\n    throw new ConfigurationError(`Failed to read hooks config: ${jsonPath}`, {\n      code: \"hooks_read_error\",\n      cause,\n    });\n  }\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch (cause) {\n    throw new ConfigurationError(`Invalid JSON in hooks config: ${jsonPath}`, {\n      code: \"hooks_json_invalid\",\n      cause,\n    });\n  }\n  return parseClaudeCodeConfig(parsed, jsonPath);\n}\n\n/** Narrow an unknown to a record, or throw a typed config error. */\nfunction asRecord(value: unknown, path: string, where: string): Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new ConfigurationError(`hooks: expected an object at ${where} in ${path}`, {\n      code: \"hooks_json_invalid\",\n    });\n  }\n  return value as Record<string, unknown>;\n}\n\n/** Narrow an unknown to an array, or throw a typed config error. */\nfunction asArray(value: unknown, path: string, where: string): unknown[] {\n  if (!Array.isArray(value)) {\n    throw new ConfigurationError(`hooks: expected an array at ${where} in ${path}`, {\n      code: \"hooks_json_invalid\",\n    });\n  }\n  return value;\n}\n\n/**\n * Parse Claude Code's nested hooks config into the SDK's flat internal shape:\n * `{ hooks: { PreToolUse: [{ matcher?, hooks: [{ type:\"command\", command, timeout? }] }] } }`\n * → `{ hooks: { preToolUse: [{ command, matcher?, timeoutMs? }] } }`. Each group's\n * `matcher` applies to every command it wraps; `timeout` (seconds) → `timeoutMs`.\n */\nfunction parseClaudeCodeConfig(raw: unknown, path: string): HookConfig {\n  const root = asRecord(raw, path, \"the root\");\n  if (root.hooks === undefined) return {};\n  const hooksRec = asRecord(root.hooks, path, `\"hooks\"`);\n  const grouped: Partial<Record<HookEvent, HookCommand[]>> = {};\n\n  for (const [ccEvent, groups] of Object.entries(hooksRec)) {\n    const event = CLAUDE_CODE_EVENT_MAP[ccEvent];\n    if (event === undefined) {\n      warnOnce(\n        `hooks-event-${ccEvent}`,\n        `[theokit-sdk] hooks: event \"${ccEvent}\" is not fired by the SDK runtime (supported: ${Object.keys(CLAUDE_CODE_EVENT_MAP).join(\", \")}) — skipping`,\n      );\n      continue;\n    }\n    grouped[event] = [...(grouped[event] ?? []), ...flattenEventGroups(groups, path, ccEvent)];\n  }\n  return { hooks: grouped };\n}\n\n/** Flatten one Claude Code event's matcher-groups into internal HookCommands. */\nfunction flattenEventGroups(groups: unknown, path: string, ccEvent: string): HookCommand[] {\n  const commands: HookCommand[] = [];\n  for (const rawGroup of asArray(groups, path, `hooks.${ccEvent}`)) {\n    const group = asRecord(rawGroup, path, `hooks.${ccEvent}[]`);\n    const matcher = group.matcher === undefined ? undefined : String(group.matcher);\n    for (const rawCmd of asArray(group.hooks, path, `hooks.${ccEvent}[].hooks`)) {\n      commands.push(parseClaudeCodeCommand(rawCmd, matcher, path, ccEvent));\n    }\n  }\n  return commands;\n}\n\n/** One `{ type:\"command\", command, timeout? }` entry → an internal HookCommand. */\nfunction parseClaudeCodeCommand(\n  raw: unknown,\n  matcher: string | undefined,\n  path: string,\n  ccEvent: string,\n): HookCommand {\n  const cmd = asRecord(raw, path, `hooks.${ccEvent}[].hooks[]`);\n  if (cmd.type !== \"command\") {\n    throw new ConfigurationError(\n      `hooks: only { \"type\": \"command\" } is supported (got ${JSON.stringify(cmd.type)}) in ${path}`,\n      { code: \"hooks_unsupported_type\" },\n    );\n  }\n  if (typeof cmd.command !== \"string\" || cmd.command.length === 0) {\n    throw new ConfigurationError(`hooks: \"command\" must be a non-empty string in ${path}`, {\n      code: \"hooks_invalid_command\",\n    });\n  }\n  const hc: HookCommand = { command: cmd.command };\n  if (matcher !== undefined) hc.matcher = matcher;\n  if (typeof cmd.timeout === \"number\" && cmd.timeout > 0) {\n    hc.timeoutMs = Math.round(cmd.timeout * 1000);\n  }\n  return hc;\n}\n","/**\n * Personality fork-context (ADR D168 + EC-A snapshot semantic).\n *\n * Uses Node's `AsyncLocalStorage` so a fork's execution chain can know\n * that it is running inside a fork AND can see the slug that was active\n * on the parent **at fork-construction time**.\n *\n * **EC-A:** The slug stored here is captured ONCE at the wrap site\n * (`localAgentFork`) — passing `parentStore.active(parentAgentId)`\n * returns a primitive `string | undefined`, which is then frozen\n * inside the ALS context object. Subsequent `usePersonality` calls on\n * the parent do NOT mutate the fork's view, because the fork reads from\n * its own ALS frame, not from the parent's store.\n *\n * @internal\n */\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\nimport { warnOnce } from \"../runtime/hooks/hooks-source.js\";\n\n/**\n * Snapshot data carried into a fork's async context.\n *\n * @internal\n */\nexport interface PersonalityForkContext {\n  /** Parent's active personality slug at fork-construction time. */\n  readonly slug: string | undefined;\n  /** Always `true` inside this scope (used by guards). */\n  readonly isFork: true;\n}\n\nconst storage = new AsyncLocalStorage<PersonalityForkContext>();\n\n/**\n * Run `fn` with `ctx` bound as the active fork context. Nested calls\n * shadow the outer context (EC-22).\n *\n * @internal\n */\nexport function withPersonalityContext<T>(\n  ctx: PersonalityForkContext,\n  fn: () => Promise<T>,\n): Promise<T> {\n  return storage.run(ctx, fn);\n}\n\n/**\n * Return the active fork context, or `undefined` when called outside a\n * fork scope.\n *\n * @internal\n */\nexport function currentPersonalityContext(): PersonalityForkContext | undefined {\n  return storage.getStore();\n}\n\n/**\n * Emit one warning per agentId stating that personality switches inside\n * a fork are no-ops. The fork inherits the parent snapshot — runtime\n * mutation is intentionally rejected to keep fork voice deterministic.\n *\n * @internal\n */\nexport function warnPersonalitySwitchInsideFork(agentId: string): void {\n  warnOnce(\n    `personality-switch-in-fork-${agentId}`,\n    `[theokit-sdk] usePersonality is a no-op inside a fork (D168). Subagents inherit the parent's active personality at fork-construction time.`,\n  );\n}\n"]}