@theokit/sdk 5.3.1 → 5.3.3

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 5.3.3
+
+### Patch Changes
+
+- [#624](https://github.com/usetheokit/theokit-sdk/pull/624) [`1ef64b0`](https://github.com/usetheokit/theokit-sdk/commit/1ef64b06f418d1194a699c2924286d87d5271b90) Thanks [@usetheodev](https://github.com/usetheodev)! - README: say that `.theokit/settings.json` is read, because it is
+  
+  Docs only. The `## Hooks` section named `.theokit/hooks.json` and nothing else, and the only mention of `settings.json` / `settings.local.json` sat in the Claude Code compatibility table — which reads as being about `.claude/`.
+  
+  So a reader asking *"what does this package read in `.theokit/`?"* got `hooks.json`, full stop. That answer is wrong: `hookConfigCandidates` reads `hooks.json`, `settings.json` and `settings.local.json` from **every** config root, and `theokitConfigRoot` is always one of them.
+  
+  This is not an omission that merely leaves someone uninformed — it returns the wrong answer to the person doing the right thing. Measured in 2026-09: a consumer put its own configuration in `.theokit/settings.json` with a `hooks` array of its own shape, and hit a hard refusal on **every turn**. The file parsed perfectly for the product that wrote it; the collision was one of shape, not of location, and nothing in this README would have warned them.
+  
+  The section now names all three files and states the consequence: `.theokit/` is this package's filebase, so a `hooks` key there is read and validated here, whatever else wrote the file.
+
+## 5.3.2
+
+### Patch Changes
+
+- [#619](https://github.com/usetheokit/theokit-sdk/pull/619) [`3f80bba`](https://github.com/usetheokit/theokit-sdk/commit/3f80bbaf0e7b1a6e7cd81a08f63aba243e1a0f18) Thanks [@usetheodev](https://github.com/usetheodev)! - A wrongly-shaped `hooks` block is refused with the shape that would work
+  
+  `hooks: expected an object at "hooks" in <path>` named the validator's expectation and nothing an operator could act on. It now carries the accepted shape:
+  
+  ```
+  hooks: expected an object at "hooks" in <path> — hooks are keyed by event,
+  e.g. { "hooks": { "PreToolUse": [ { "hooks": [ { "type": "command", "command": "…" } ] } ] } }
+  ```
+  
+  Measured on a consumer in 2026-09. A flat `hooks` array in a `.theokit/settings.json` made this loader throw on **every turn** — and the file parsed perfectly for the product that had written it. `.theokit/` is this package's filebase, so what failed was an independent read of a path another product had started using, and the collision was one of **shape**, not of location. With only the diagnosis to go on, the operator looked in the wrong file.
+  
+  Two tests ship with it: the refusal names the shape, and a control proves the shape it names is accepted. Without the control, "the error mentions `keyed by event`" would say nothing about whether that advice is correct.
+
+- [#619](https://github.com/usetheokit/theokit-sdk/pull/619) [`a75059c`](https://github.com/usetheokit/theokit-sdk/commit/a75059cb496e4655e571a703c937e4e71ff670d8) Thanks [@usetheodev](https://github.com/usetheodev)! - Document that `on_session_start` / `on_session_end` fire once per **run** ([#613](https://github.com/usetheokit/theokit-sdk/issues/613) follow-up)
+  
+  Docs and a test only; no behaviour change.
+  
+  `SessionLifecycleContext` is named for a session and carries a `runId` that changes on every firing. The hooks fire once per pass through the agent loop — which is per-message for any application that builds its agent per turn. Nothing a consumer could read said so: the only accurate sentence was an internal comment at the firing site (`loop.ts`, *"fires once per run"*).
+  
+  That gap was measured. In 2026-09 it cost two sessions several hours and produced a defect filed against this package for behaviour that is correct; the real answer turned out to be an architectural mismatch in a consumer that constructs an agent per turn, where "once per run" is not what a `SessionStart` handler assumes.
+  
+  Two changes:
+  
+  - The cadence is now stated on `SessionLifecycleContext` and in the `HookName` docblock, where a consumer meets the hook.
+  - `test_on_session_start_fires_once_per_run_and_again_on_the_next_run` pins it across two runs. The existing integration case could not: it collects into a `Set`, so a hook firing twice and a hook firing once are indistinguishable there by construction.
+
 ## 5.3.1
 
 ### Patch Changes

package/dist/{agent-CvmTR9uf.d.ts → agent-CTbU0O1R.d.ts}

@@ -689,6 +689,8 @@ interface ProviderProfile {
  *   `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
@@ -750,7 +752,24 @@ interface PostToolCallContext {
     agentId: string;
     runId: string;
 }
-/** #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
+ */
 interface SessionLifecycleContext {
     agentId: string;
     runId: string;

package/dist/{agent-UXU5AIOJ.cjs → agent-KJLAWKZB.cjs}

@@ -1,11 +1,11 @@
 'use strict';
 
-var chunk5XNRWMMD_cjs = require('./chunk-5XNRWMMD.cjs');
+var chunkY46VI73J_cjs = require('./chunk-Y46VI73J.cjs');
 require('./chunk-KVSAY6NZ.cjs');
 require('./chunk-Y2KYR2ED.cjs');
 require('./chunk-BUUUWQMB.cjs');
 require('./chunk-Z2JFX372.cjs');
-require('./chunk-SSIRPWWD.cjs');
+require('./chunk-65UMH5V3.cjs');
 require('./chunk-BV2MWEMV.cjs');
 require('./chunk-D6POWE7E.cjs');
 require('./chunk-GHX4P3V2.cjs');
@@ -61,7 +61,7 @@ require('./chunk-6LHQPOMI.cjs');
 
 Object.defineProperty(exports, "Agent", {
   enumerable: true,
-  get: function () { return chunk5XNRWMMD_cjs.Agent; }
+  get: function () { return chunkY46VI73J_cjs.Agent; }
 });
-//# sourceMappingURL=agent-UXU5AIOJ.cjs.map
-//# sourceMappingURL=agent-UXU5AIOJ.cjs.map
+//# sourceMappingURL=agent-KJLAWKZB.cjs.map
+//# sourceMappingURL=agent-KJLAWKZB.cjs.map

package/dist/{agent-UXU5AIOJ.cjs.map → agent-KJLAWKZB.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-UXU5AIOJ.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-KJLAWKZB.cjs"}

package/dist/{agent-G4OFQYLE.js → agent-PNYJ5S2Y.js}

@@ -1,9 +1,9 @@
-export { Agent } from './chunk-ZFEOAC52.js';
+export { Agent } from './chunk-363RBGIR.js';
 import './chunk-K2VMFZQ5.js';
 import './chunk-AWINL3ZC.js';
 import './chunk-K2BQQ445.js';
 import './chunk-7SZAV6QG.js';
-import './chunk-AI4MXACC.js';
+import './chunk-7L3MIW2F.js';
 import './chunk-2SFBB54R.js';
 import './chunk-55GB6JYQ.js';
 import './chunk-H73MEMQB.js';
@@ -54,5 +54,5 @@ import './chunk-V22DZIXO.js';
 import './chunk-NJWYQWDL.js';
 import './chunk-ALUN2B4W.js';
 import './chunk-CZJ6Q7CW.js';
-//# sourceMappingURL=agent-G4OFQYLE.js.map
-//# sourceMappingURL=agent-G4OFQYLE.js.map
+//# sourceMappingURL=agent-PNYJ5S2Y.js.map
+//# sourceMappingURL=agent-PNYJ5S2Y.js.map

package/dist/{agent-G4OFQYLE.js.map → agent-PNYJ5S2Y.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-G4OFQYLE.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-PNYJ5S2Y.js"}

package/dist/{agent-C3KO5LKm.d.cts → agent-QLwxhXY3.d.cts}

@@ -689,6 +689,8 @@ interface ProviderProfile {
  *   `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
@@ -750,7 +752,24 @@ interface PostToolCallContext {
     agentId: string;
     runId: string;
 }
-/** #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
+ */
 interface SessionLifecycleContext {
     agentId: string;
     runId: string;

package/dist/{chunk-ZFEOAC52.js → chunk-363RBGIR.js}

@@ -1,7 +1,7 @@
 import { submit, emitRunEvent } from './chunk-K2VMFZQ5.js';
 import { enqueueSessionWrite, hydrateSession, persistTurnToTranscript, flushSessionWrites, appendSessionMessage, getSessionMessages, discardSession, clearSession } from './chunk-AWINL3ZC.js';
 import { IndexManager } from './chunk-7SZAV6QG.js';
-import { loadHookConfig, warnOnce, currentPersonalityContext, warnPersonalitySwitchInsideFork } from './chunk-AI4MXACC.js';
+import { loadHookConfig, warnOnce, currentPersonalityContext, warnPersonalitySwitchInsideFork } from './chunk-7L3MIW2F.js';
 import { extractCodePlugins } from './chunk-2SFBB54R.js';
 import { createOpenAiCompatibleRuntime } from './chunk-55GB6JYQ.js';
 import { persistActiveMemoryTranscript } from './chunk-OR6XIWLB.js';
@@ -9122,7 +9122,7 @@ async function* localAgentStreamToCompletion(agent, message, options) {
 async function localAgentFork(parent, options) {
   const { forkAgentImpl } = await import('./fork-agent-S2EPIML7.js');
   const { getAgentFacade } = await import('./agent-factory-registry-ZVTABLEY.js');
-  const { withPersonalityContext } = await import('./context-XNREEC7M.js');
+  const { withPersonalityContext } = await import('./context-BUIE52VH.js');
   const create = getAgentFacade().create;
   return withPersonalityContext(
     { slug: parent.personalitySlugSnapshot, isFork: true },
@@ -11005,5 +11005,5 @@ async function openLocalStore(reg) {
 }
 
 export { Agent, AgentBuilder, DEFAULT_AGENTIC_MODEL_ID, MEMORY_EMBEDDING_ADAPTERS, Tool, ToolError, UsageAccumulator, computeCost, generateCronId, getPricingEntry, openRouterMemoryEmbeddingProviderAdapter, resolveSessionDir };
-//# sourceMappingURL=chunk-ZFEOAC52.js.map
-//# sourceMappingURL=chunk-ZFEOAC52.js.map
+//# sourceMappingURL=chunk-363RBGIR.js.map
+//# sourceMappingURL=chunk-363RBGIR.js.map