chainlesschain 0.162.174 → 0.162.176

package/src/lib/session-hooks.js

@@ -1,236 +1,219 @@
 /**
- * Session-level hook firing helpers — the "三件套 +1" that complements
- * the tool-level PreToolUse/PostToolUse hooks already wired in
- * `runtime/agent-core.js`.
+ * Session hooks - 会话级钩子触发工具
  *
- * Four session-level events are fired from `repl/agent-repl.js`:
- *
- *   - SessionStart       — once, after sessionId is established
- *   - UserPromptSubmit   — per user line, before agentLoop()
- *   - AssistantResponse  — per agent reply, after agentLoop() returns
- *   - SessionEnd         — once, on rl.close() before shutdown
- *
- * Semantics (matches existing PreToolUse convention):
- *   - Fire-and-forget by default: hook failures NEVER break the host flow
- *   - `fireUserPromptSubmit` / `fireAssistantResponse` are opt-in helpers
- *     that parse stdout JSON directives ({rewrittenPrompt,abort} /
- *     {rewrittenResponse,suppress}) for callers that want control flow
- *   - No-op when hookDb is null (REPL without DB)
- *   - Helper-side timeout protects against runaway hooks even if
- *     hook-manager's per-hook timeout is misconfigured
- *   - Swallowed errors are persisted to hook_execution_log when possible
+ * 用于 agent-repl 的三件套会话级钩子：
+ * - SessionStart
+ * - UserPromptSubmit
+ * - AssistantResponse
+ * - SessionEnd
+ * - Notification
  */
 
-import { executeHooks, HookEvents } from "./hook-manager.js";
+import { HookEvents, executeHooks } from "./hook-manager.js";
 
-/**
- * Events this helper is allowed to fire. Guards against typos that
- * would otherwise silently no-op inside executeHooks' event filter.
- */
+// 会话钩子白名单
 export const SESSION_HOOK_EVENTS = Object.freeze([
   HookEvents.SessionStart,
   HookEvents.UserPromptSubmit,
   HookEvents.AssistantResponse,
   HookEvents.SessionEnd,
+  HookEvents.Notification,
 ]);
 
-/**
- * Helper-side wall-clock cap. Per-hook timeout still lives in the
- * registered hook row; this is a belt-and-suspenders bound so a
- * misconfigured hook can never wedge the REPL.
- */
-const HELPER_TIMEOUT_MS = Number(
-  process.env.CC_SESSION_HOOK_TIMEOUT_MS || 15000,
-);
-
-/**
- * Internal deps — exposed for tests via `_deps` injection.
- * Keeping this mutable lets vitest swap out timer/log writers without
- * resorting to vi.mock (which doesn't intercept inlined CJS).
- */
+// 依赖注入点（用于测试）
 export const _deps = {
   executeHooks,
-  now: () => Date.now(),
-  logFailure: (hookDb, eventName, err) => {
-    // Best-effort persistence to hook_execution_log; never throws.
-    if (!hookDb || typeof hookDb.prepare !== "function") return;
-    try {
-      const stmt = hookDb.prepare(
-        `INSERT INTO hook_execution_log
-           (hook_id, event, success, error, executed_at)
-         VALUES (?, ?, ?, ?, ?)`,
-      );
-      stmt.run(
-        null,
-        eventName,
-        0,
-        String(err && err.message ? err.message : err),
-        new Date().toISOString(),
-      );
-    } catch {
-      /* table may not exist yet — silent */
-    }
+  logFailure: (_db, event, error) => {
+    console.error(`[session-hooks] Failed to fire ${event}:`, error);
   },
 };
 
 /**
- * Fire a session-level hook. Returns the raw results from executeHooks
- * (array of {hookId, hookName, success, ...}) or an empty array if
- * hookDb is missing, event is not allowed, or execution throws.
- *
- * @param {object|null} hookDb  better-sqlite3 handle, or null to no-op
- * @param {string}      eventName  one of SESSION_HOOK_EVENTS
- * @param {object}      [context]  forwarded to hook matcher + handler env
- * @returns {Promise<Array>}
+ * 通用会话钩子触发函数
+ * @param {object} db - 数据库实例
+ * @param {string} event - 钩子事件名
+ * @param {object} [context={}] - 钩子上下文
+ * @returns {Promise<Array>} 钩子执行结果数组
  */
-export async function fireSessionHook(hookDb, eventName, context = {}) {
-  if (!hookDb) return [];
-  if (!SESSION_HOOK_EVENTS.includes(eventName)) {
-    throw new Error(
-      `fireSessionHook: event "${eventName}" is not a session hook. ` +
-        `Use one of: ${SESSION_HOOK_EVENTS.join(", ")}`,
-    );
+export async function fireSessionHook(db, event, context = {}) {
+  // 白名单验证
+  if (!SESSION_HOOK_EVENTS.includes(event)) {
+    throw new Error(`"${event}" is not a session hook event`);
+  }
+
+  // 如果没有数据库，空操作
+  if (!db) {
+    return [];
   }
 
   try {
-    const enriched = {
+    // 注入时间戳
+    const ctxWithTimestamp = {
       timestamp: new Date().toISOString(),
       ...context,
     };
-    return await withTimeout(
-      _deps.executeHooks(hookDb, eventName, enriched),
-      HELPER_TIMEOUT_MS,
-      `${eventName} session hook`,
-    );
-  } catch (err) {
-    // Hook failures must never break the REPL — but we record them
-    _deps.logFailure(hookDb, eventName, err);
+
+    // 执行钩子
+    const results = await _deps.executeHooks(db, event, ctxWithTimestamp);
+    return Array.isArray(results) ? results : [];
+  } catch (error) {
+    _deps.logFailure(db, event, error);
     return [];
   }
 }
 
 /**
- * Fire UserPromptSubmit with rewrite/abort support.
- *
- * A hook may control the prompt by emitting a single JSON line to stdout:
- *   {"rewrittenPrompt": "..."}   — replace the user prompt
- *   {"abort": true, "reason": "..."} — skip agentLoop entirely
- *
- * First matching directive wins (priority order from executeHooks).
- * Malformed JSON / no directive → no change (pure observation).
- *
+ * 触发用户提交提示词钩子
+ * @param {object} db - 数据库实例
+ * @param {string} prompt - 用户提示词
+ * @param {object} [context={}] - 上下文
  * @returns {Promise<{prompt: string, abort: boolean, reason?: string, results: Array}>}
  */
-export async function fireUserPromptSubmit(
-  hookDb,
-  originalPrompt,
-  context = {},
-) {
-  const results = await fireSessionHook(hookDb, HookEvents.UserPromptSubmit, {
+export async function fireUserPromptSubmit(db, prompt, context = {}) {
+  const results = await fireSessionHook(db, HookEvents.UserPromptSubmit, {
+    prompt,
     ...context,
-    prompt: originalPrompt,
   });
 
-  let prompt = originalPrompt;
+  let rewrittenPrompt = prompt;
   let abort = false;
-  let reason;
+  let abortReason;
 
-  for (const r of results) {
-    if (!r || !r.success) continue;
-    const directive = extractDirective(r);
-    if (!directive) continue;
-    if (directive.abort) {
-      abort = true;
-      reason = directive.reason;
-      break;
-    }
-    if (
-      typeof directive.rewrittenPrompt === "string" &&
-      directive.rewrittenPrompt.trim()
-    ) {
-      prompt = directive.rewrittenPrompt;
-      break;
+  // 处理钩子返回的指令
+  for (const result of results) {
+    if (!result.success) continue;
+    try {
+      const output = result.stdout ? JSON.parse(result.stdout) : {};
+      if (output.rewrittenPrompt) {
+        rewrittenPrompt = output.rewrittenPrompt;
+      }
+      if (output.abort) {
+        abort = true;
+        abortReason = output.reason || "aborted by hook";
+      }
+    } catch {
+      // 忽略解析错误
     }
   }
 
-  return { prompt, abort, reason, results };
+  return {
+    prompt: rewrittenPrompt,
+    abort,
+    reason: abortReason,
+    results,
+  };
 }
 
 /**
- * Fire AssistantResponse with rewrite/suppress support.
- *
- * Symmetric to fireUserPromptSubmit but on the way out. A hook may emit:
- *   {"rewrittenResponse": "..."} — replace the response shown to the user
- *   {"suppress": true, "reason": "..."} — drop the response entirely
- *
- * Common use: PII / secret scrubbing, watermark injection, profanity
- * filter on the model's final string before it reaches the terminal.
- *
+ * 触发助手响应钩子（已存在，重写增强）
+ * @param {object} db - 数据库实例
+ * @param {string} response - 助手响应
+ * @param {object} [context={}] - 上下文
  * @returns {Promise<{response: string, suppress: boolean, reason?: string, results: Array}>}
  */
-export async function fireAssistantResponse(
-  hookDb,
-  originalResponse,
-  context = {},
-) {
-  const results = await fireSessionHook(hookDb, HookEvents.AssistantResponse, {
+export async function fireAssistantResponse(db, response, context = {}) {
+  const results = await fireSessionHook(db, HookEvents.AssistantResponse, {
+    response,
     ...context,
-    response: originalResponse,
   });
 
-  let response = originalResponse;
+  let rewrittenResponse = response;
   let suppress = false;
-  let reason;
+  let suppressReason;
 
-  for (const r of results) {
-    if (!r || !r.success) continue;
-    const directive = extractDirective(r);
-    if (!directive) continue;
-    if (directive.suppress) {
-      suppress = true;
-      reason = directive.reason;
-      break;
-    }
-    if (
-      typeof directive.rewrittenResponse === "string" &&
-      directive.rewrittenResponse.length > 0
-    ) {
-      response = directive.rewrittenResponse;
-      break;
+  for (const result of results) {
+    if (!result.success) continue;
+    try {
+      const output = result.stdout ? JSON.parse(result.stdout) : {};
+      if (output.rewrittenResponse) {
+        rewrittenResponse = output.rewrittenResponse;
+      }
+      if (output.suppress) {
+        suppress = true;
+        suppressReason = output.reason || "suppressed by hook";
+      }
+    } catch {
+      // 忽略解析错误
     }
   }
 
-  return { response, suppress, reason, results };
+  return {
+    response: rewrittenResponse,
+    suppress,
+    reason: suppressReason,
+    results,
+  };
 }
 
-function extractDirective(result) {
-  const raw = result.stdout ?? result.output ?? result.result;
-  if (raw == null) return null;
-  if (typeof raw === "object") return raw;
-  if (typeof raw !== "string") return null;
-  const trimmed = raw.trim();
-  if (!trimmed.startsWith("{")) return null;
-  try {
-    return JSON.parse(trimmed);
-  } catch {
-    return null;
-  }
+/**
+ * 触发会话开始钩子
+ * @param {object} db - 数据库实例
+ * @param {object} [context={}] - 上下文
+ * @returns {Promise<Array>}
+ */
+export async function fireSessionStart(db, context = {}) {
+  return fireSessionHook(db, HookEvents.SessionStart, context);
 }
 
-function withTimeout(promise, ms, label) {
-  if (!ms || ms <= 0) return promise;
-  let t;
-  const timeout = new Promise((_, reject) => {
-    t = setTimeout(
-      () => reject(new Error(`${label} exceeded ${ms}ms helper timeout`)),
-      ms,
-    );
-    if (typeof t.unref === "function") t.unref();
+/**
+ * 触发会话结束钩子
+ * @param {object} db - 数据库实例
+ * @param {object} [context={}] - 上下文
+ * @returns {Promise<Array>}
+ */
+export async function fireSessionEnd(db, context = {}) {
+  return fireSessionHook(db, HookEvents.SessionEnd, context);
+}
+
+// Historical callers use "Stop" for the terminal lifecycle event; retain the
+// alias while the canonical hook event remains SessionEnd.
+export const fireSessionStop = fireSessionEnd;
+
+/**
+ * 获取钩子数据库实例
+ * @returns {null} 暂未实现
+ */
+export function getHookDb() {
+  return null;
+}
+
+/**
+ * 触发设置钩子
+ * @param {object} db - 数据库实例
+ * @param {object} context - 上下文
+ * @returns {Promise<{abort: boolean}>}
+ */
+export async function fireSetup(db, context) {
+  return { abort: false };
+}
+
+/** Fire Notification hooks. Notifications are best-effort and may return a
+ * suppress/message directive without ever breaking the host session. */
+export async function fireNotification(db, message, context = {}) {
+  const results = await fireSessionHook(db, HookEvents.Notification, {
+    message,
+    ...context,
   });
-  return Promise.race([promise, timeout]).finally(() => clearTimeout(t));
+  for (const result of results) {
+    if (!result?.success) continue;
+    const raw = result.stdout ?? result.output ?? result.result;
+    let directive = raw && typeof raw === "object" ? raw : null;
+    if (!directive && typeof raw === "string") {
+      try {
+        directive = JSON.parse(raw.trim());
+      } catch {
+        directive = null;
+      }
+    }
+    if (directive && typeof directive === "object") {
+      return { directive, results };
+    }
+  }
+  return { directive: null, results };
 }
 
-// ===== V2 Surface: Session Hooks governance overlay (CLI v0.142.0) =====
+// Session Hooks V2 governance overlay. Kept in this module so the command and
+// the library expose one stable surface to the CLI and its consumers.
 export const SHOK_PROFILE_MATURITY_V2 = Object.freeze({
   PENDING: "pending",
   ACTIVE: "active",
@@ -244,209 +227,150 @@ export const SHOK_INVOCATION_LIFECYCLE_V2 = Object.freeze({
   FAILED: "failed",
   CANCELLED: "cancelled",
 });
-const _shokPTrans = new Map([
-  [
-    SHOK_PROFILE_MATURITY_V2.PENDING,
-    new Set([
-      SHOK_PROFILE_MATURITY_V2.ACTIVE,
-      SHOK_PROFILE_MATURITY_V2.RETIRED,
-    ]),
-  ],
-  [
-    SHOK_PROFILE_MATURITY_V2.ACTIVE,
-    new Set([
-      SHOK_PROFILE_MATURITY_V2.DISABLED,
-      SHOK_PROFILE_MATURITY_V2.RETIRED,
-    ]),
-  ],
-  [
-    SHOK_PROFILE_MATURITY_V2.DISABLED,
-    new Set([
-      SHOK_PROFILE_MATURITY_V2.ACTIVE,
-      SHOK_PROFILE_MATURITY_V2.RETIRED,
-    ]),
-  ],
-  [SHOK_PROFILE_MATURITY_V2.RETIRED, new Set()],
-]);
-const _shokPTerminal = new Set([SHOK_PROFILE_MATURITY_V2.RETIRED]);
-const _shokITrans = new Map([
-  [
-    SHOK_INVOCATION_LIFECYCLE_V2.QUEUED,
-    new Set([
-      SHOK_INVOCATION_LIFECYCLE_V2.RUNNING,
-      SHOK_INVOCATION_LIFECYCLE_V2.CANCELLED,
-    ]),
-  ],
-  [
-    SHOK_INVOCATION_LIFECYCLE_V2.RUNNING,
-    new Set([
-      SHOK_INVOCATION_LIFECYCLE_V2.COMPLETED,
-      SHOK_INVOCATION_LIFECYCLE_V2.FAILED,
-      SHOK_INVOCATION_LIFECYCLE_V2.CANCELLED,
-    ]),
-  ],
-  [SHOK_INVOCATION_LIFECYCLE_V2.COMPLETED, new Set()],
-  [SHOK_INVOCATION_LIFECYCLE_V2.FAILED, new Set()],
-  [SHOK_INVOCATION_LIFECYCLE_V2.CANCELLED, new Set()],
-]);
-const _shokPsV2 = new Map();
-const _shokIsV2 = new Map();
-let _shokMaxActive = 12,
-  _shokMaxPending = 25,
-  _shokIdleMs = 30 * 24 * 60 * 60 * 1000,
-  _shokStuckMs = 30 * 1000;
-function _shokPos(n, label) {
+const _sp = new Map(),
+  _si = new Map();
+let _maxActive = 12,
+  _maxPending = 25,
+  _idleMs = 30 * 24 * 60 * 60 * 1000,
+  _stuckMs = 30000;
+const clone = (x) => ({ ...x, metadata: { ...(x.metadata || {}) } });
+const pos = (n, name) => {
   const v = Math.floor(Number(n));
   if (!Number.isFinite(v) || v <= 0)
-    throw new Error(`${label} must be positive integer`);
+    throw new Error(`${name} must be positive integer`);
   return v;
-}
-function _shokCheckP(from, to) {
-  const a = _shokPTrans.get(from);
-  if (!a || !a.has(to))
-    throw new Error(`invalid shok profile transition ${from} → ${to}`);
-}
-function _shokCheckI(from, to) {
-  const a = _shokITrans.get(from);
-  if (!a || !a.has(to))
-    throw new Error(`invalid shok invocation transition ${from} → ${to}`);
-}
-export function setMaxActiveShokProfilesPerOwnerV2(n) {
-  _shokMaxActive = _shokPos(n, "maxActiveShokProfilesPerOwner");
-}
-export function getMaxActiveShokProfilesPerOwnerV2() {
-  return _shokMaxActive;
-}
-export function setMaxPendingShokInvocationsPerProfileV2(n) {
-  _shokMaxPending = _shokPos(n, "maxPendingShokInvocationsPerProfile");
-}
-export function getMaxPendingShokInvocationsPerProfileV2() {
-  return _shokMaxPending;
-}
-export function setShokProfileIdleMsV2(n) {
-  _shokIdleMs = _shokPos(n, "shokProfileIdleMs");
-}
-export function getShokProfileIdleMsV2() {
-  return _shokIdleMs;
-}
-export function setShokInvocationStuckMsV2(n) {
-  _shokStuckMs = _shokPos(n, "shokInvocationStuckMs");
-}
-export function getShokInvocationStuckMsV2() {
-  return _shokStuckMs;
-}
+};
+const profile = (id) => {
+  const p = _sp.get(id);
+  if (!p) throw new Error(`shok profile ${id} not found`);
+  return p;
+};
+const invocation = (id) => {
+  const i = _si.get(id);
+  if (!i) throw new Error(`shok invocation ${id} not found`);
+  return i;
+};
+const transition = (map, from, to, label) => {
+  if (!map[from]?.includes(to))
+    throw new Error(`invalid ${label} transition ${from} → ${to}`);
+};
+const PT = {
+  pending: ["active", "retired"],
+  active: ["disabled", "retired"],
+  disabled: ["active", "retired"],
+  retired: [],
+};
+const IT = {
+  queued: ["running", "cancelled"],
+  running: ["completed", "failed", "cancelled"],
+  completed: [],
+  failed: [],
+  cancelled: [],
+};
+export const setMaxActiveShokProfilesPerOwnerV2 = (n) => {
+  _maxActive = pos(n, "maxActiveShokProfilesPerOwner");
+};
+export const getMaxActiveShokProfilesPerOwnerV2 = () => _maxActive;
+export const setMaxPendingShokInvocationsPerProfileV2 = (n) => {
+  _maxPending = pos(n, "maxPendingShokInvocationsPerProfile");
+};
+export const getMaxPendingShokInvocationsPerProfileV2 = () => _maxPending;
+export const setShokProfileIdleMsV2 = (n) => {
+  _idleMs = pos(n, "shokProfileIdleMs");
+};
+export const getShokProfileIdleMsV2 = () => _idleMs;
+export const setShokInvocationStuckMsV2 = (n) => {
+  _stuckMs = pos(n, "shokInvocationStuckMs");
+};
+export const getShokInvocationStuckMsV2 = () => _stuckMs;
 export function _resetStateSessionHooksV2() {
-  _shokPsV2.clear();
-  _shokIsV2.clear();
-  _shokMaxActive = 12;
-  _shokMaxPending = 25;
-  _shokIdleMs = 30 * 24 * 60 * 60 * 1000;
-  _shokStuckMs = 30 * 1000;
-}
-export function registerShokProfileV2({ id, owner, event, metadata } = {}) {
-  if (!id) throw new Error("shok profile id required");
-  if (!owner) throw new Error("shok profile owner required");
-  if (_shokPsV2.has(id))
-    throw new Error(`shok profile ${id} already registered`);
+  _sp.clear();
+  _si.clear();
+  _maxActive = 12;
+  _maxPending = 25;
+  _idleMs = 30 * 24 * 60 * 60 * 1000;
+  _stuckMs = 30000;
+}
+export function registerShokProfileV2({
+  id,
+  owner,
+  event = "preTurn",
+  metadata = {},
+} = {}) {
+  if (!id || !owner) throw new Error("shok profile id and owner required");
+  if (_sp.has(id)) throw new Error(`shok profile ${id} already registered`);
   const now = Date.now();
   const p = {
     id,
     owner,
-    event: event || "preTurn",
-    status: SHOK_PROFILE_MATURITY_V2.PENDING,
+    event,
+    status: "pending",
     createdAt: now,
     updatedAt: now,
     activatedAt: null,
     retiredAt: null,
     lastTouchedAt: now,
-    metadata: { ...(metadata || {}) },
+    metadata: { ...metadata },
   };
-  _shokPsV2.set(id, p);
-  return { ...p, metadata: { ...p.metadata } };
-}
-function _shokCountActive(owner) {
-  let n = 0;
-  for (const p of _shokPsV2.values())
-    if (p.owner === owner && p.status === SHOK_PROFILE_MATURITY_V2.ACTIVE) n++;
-  return n;
+  _sp.set(id, p);
+  return clone(p);
 }
 export function activateShokProfileV2(id) {
-  const p = _shokPsV2.get(id);
-  if (!p) throw new Error(`shok profile ${id} not found`);
-  _shokCheckP(p.status, SHOK_PROFILE_MATURITY_V2.ACTIVE);
-  const recovery = p.status === SHOK_PROFILE_MATURITY_V2.DISABLED;
-  if (!recovery && _shokCountActive(p.owner) >= _shokMaxActive)
+  const p = profile(id);
+  transition(PT, p.status, "active", "shok profile");
+  const active = [..._sp.values()].filter(
+    (x) => x.owner === p.owner && x.status === "active",
+  ).length;
+  if (p.status !== "disabled" && active >= _maxActive)
     throw new Error(`max active shok profiles for owner ${p.owner} reached`);
   const now = Date.now();
-  p.status = SHOK_PROFILE_MATURITY_V2.ACTIVE;
+  p.status = "active";
   p.updatedAt = now;
   p.lastTouchedAt = now;
-  if (!p.activatedAt) p.activatedAt = now;
-  return { ...p, metadata: { ...p.metadata } };
+  p.activatedAt ||= now;
+  return clone(p);
 }
 export function disableShokProfileV2(id) {
-  const p = _shokPsV2.get(id);
-  if (!p) throw new Error(`shok profile ${id} not found`);
-  _shokCheckP(p.status, SHOK_PROFILE_MATURITY_V2.DISABLED);
-  p.status = SHOK_PROFILE_MATURITY_V2.DISABLED;
+  const p = profile(id);
+  transition(PT, p.status, "disabled", "shok profile");
+  p.status = "disabled";
   p.updatedAt = Date.now();
-  return { ...p, metadata: { ...p.metadata } };
+  return clone(p);
 }
 export function retireShokProfileV2(id) {
-  const p = _shokPsV2.get(id);
-  if (!p) throw new Error(`shok profile ${id} not found`);
-  _shokCheckP(p.status, SHOK_PROFILE_MATURITY_V2.RETIRED);
+  const p = profile(id);
+  transition(PT, p.status, "retired", "shok profile");
   const now = Date.now();
-  p.status = SHOK_PROFILE_MATURITY_V2.RETIRED;
+  p.status = "retired";
   p.updatedAt = now;
-  if (!p.retiredAt) p.retiredAt = now;
-  return { ...p, metadata: { ...p.metadata } };
+  p.retiredAt ||= now;
+  return clone(p);
 }
 export function touchShokProfileV2(id) {
-  const p = _shokPsV2.get(id);
-  if (!p) throw new Error(`shok profile ${id} not found`);
-  if (_shokPTerminal.has(p.status))
+  const p = profile(id);
+  if (p.status === "retired")
     throw new Error(`cannot touch terminal shok profile ${id}`);
-  const now = Date.now();
-  p.lastTouchedAt = now;
-  p.updatedAt = now;
-  return { ...p, metadata: { ...p.metadata } };
-}
-export function getShokProfileV2(id) {
-  const p = _shokPsV2.get(id);
-  if (!p) return null;
-  return { ...p, metadata: { ...p.metadata } };
-}
-export function listShokProfilesV2() {
-  return [..._shokPsV2.values()].map((p) => ({
-    ...p,
-    metadata: { ...p.metadata },
-  }));
-}
-function _shokCountPending(profileId) {
-  let n = 0;
-  for (const i of _shokIsV2.values())
-    if (
-      i.profileId === profileId &&
-      (i.status === SHOK_INVOCATION_LIFECYCLE_V2.QUEUED ||
-        i.status === SHOK_INVOCATION_LIFECYCLE_V2.RUNNING)
-    )
-      n++;
-  return n;
+  p.lastTouchedAt = p.updatedAt = Date.now();
+  return clone(p);
 }
+export const getShokProfileV2 = (id) =>
+  _sp.has(id) ? clone(_sp.get(id)) : null;
+export const listShokProfilesV2 = () => [..._sp.values()].map(clone);
 export function createShokInvocationV2({
   id,
   profileId,
-  payload,
-  metadata,
+  payload = "",
+  metadata = {},
 } = {}) {
-  if (!id) throw new Error("shok invocation id required");
-  if (!profileId) throw new Error("shok invocation profileId required");
-  if (_shokIsV2.has(id))
-    throw new Error(`shok invocation ${id} already exists`);
-  if (!_shokPsV2.has(profileId))
-    throw new Error(`shok profile ${profileId} not found`);
-  if (_shokCountPending(profileId) >= _shokMaxPending)
+  if (!id || !profileId)
+    throw new Error("shok invocation id and profileId required");
+  if (_si.has(id) || !_sp.has(profileId))
+    throw new Error("invalid shok invocation");
+  const pending = [..._si.values()].filter(
+    (x) =>
+      x.profileId === profileId && ["queued", "running"].includes(x.status),
+  ).length;
+  if (pending >= _maxPending)
     throw new Error(
       `max pending shok invocations for profile ${profileId} reached`,
     );
@@ -454,159 +378,90 @@ export function createShokInvocationV2({
   const i = {
     id,
     profileId,
-    payload: payload || "",
-    status: SHOK_INVOCATION_LIFECYCLE_V2.QUEUED,
+    payload,
+    status: "queued",
     createdAt: now,
     updatedAt: now,
     startedAt: null,
     settledAt: null,
-    metadata: { ...(metadata || {}) },
+    metadata: { ...metadata },
   };
-  _shokIsV2.set(id, i);
-  return { ...i, metadata: { ...i.metadata } };
-}
-export function runningShokInvocationV2(id) {
-  const i = _shokIsV2.get(id);
-  if (!i) throw new Error(`shok invocation ${id} not found`);
-  _shokCheckI(i.status, SHOK_INVOCATION_LIFECYCLE_V2.RUNNING);
-  const now = Date.now();
-  i.status = SHOK_INVOCATION_LIFECYCLE_V2.RUNNING;
-  i.updatedAt = now;
-  if (!i.startedAt) i.startedAt = now;
-  return { ...i, metadata: { ...i.metadata } };
-}
-export function completeShokInvocationV2(id) {
-  const i = _shokIsV2.get(id);
-  if (!i) throw new Error(`shok invocation ${id} not found`);
-  _shokCheckI(i.status, SHOK_INVOCATION_LIFECYCLE_V2.COMPLETED);
-  const now = Date.now();
-  i.status = SHOK_INVOCATION_LIFECYCLE_V2.COMPLETED;
-  i.updatedAt = now;
-  if (!i.settledAt) i.settledAt = now;
-  return { ...i, metadata: { ...i.metadata } };
-}
-export function failShokInvocationV2(id, reason) {
-  const i = _shokIsV2.get(id);
-  if (!i) throw new Error(`shok invocation ${id} not found`);
-  _shokCheckI(i.status, SHOK_INVOCATION_LIFECYCLE_V2.FAILED);
-  const now = Date.now();
-  i.status = SHOK_INVOCATION_LIFECYCLE_V2.FAILED;
-  i.updatedAt = now;
-  if (!i.settledAt) i.settledAt = now;
-  if (reason) i.metadata.failReason = String(reason);
-  return { ...i, metadata: { ...i.metadata } };
+  _si.set(id, i);
+  return clone(i);
 }
-export function cancelShokInvocationV2(id, reason) {
-  const i = _shokIsV2.get(id);
-  if (!i) throw new Error(`shok invocation ${id} not found`);
-  _shokCheckI(i.status, SHOK_INVOCATION_LIFECYCLE_V2.CANCELLED);
+function setInvocation(id, to, extra = {}) {
+  const i = invocation(id);
+  transition(IT, i.status, to, "shok invocation");
   const now = Date.now();
-  i.status = SHOK_INVOCATION_LIFECYCLE_V2.CANCELLED;
-  i.updatedAt = now;
-  if (!i.settledAt) i.settledAt = now;
-  if (reason) i.metadata.cancelReason = String(reason);
-  return { ...i, metadata: { ...i.metadata } };
-}
-export function getShokInvocationV2(id) {
-  const i = _shokIsV2.get(id);
-  if (!i) return null;
-  return { ...i, metadata: { ...i.metadata } };
-}
-export function listShokInvocationsV2() {
-  return [..._shokIsV2.values()].map((i) => ({
-    ...i,
-    metadata: { ...i.metadata },
-  }));
-}
-export function autoDisableIdleShokProfilesV2({ now } = {}) {
-  const t = now ?? Date.now();
+  Object.assign(i, extra, { status: to, updatedAt: now });
+  if (to === "running") i.startedAt ||= now;
+  if (["completed", "failed", "cancelled"].includes(to)) i.settledAt ||= now;
+  return clone(i);
+}
+export const runningShokInvocationV2 = (id) => setInvocation(id, "running");
+export const completeShokInvocationV2 = (id) => setInvocation(id, "completed");
+export const failShokInvocationV2 = (id, reason) =>
+  setInvocation(
+    id,
+    "failed",
+    reason
+      ? { metadata: { ...invocation(id).metadata, failReason: String(reason) } }
+      : {},
+  );
+export const cancelShokInvocationV2 = (id, reason) =>
+  setInvocation(
+    id,
+    "cancelled",
+    reason
+      ? {
+          metadata: {
+            ...invocation(id).metadata,
+            cancelReason: String(reason),
+          },
+        }
+      : {},
+  );
+export const getShokInvocationV2 = (id) =>
+  _si.has(id) ? clone(_si.get(id)) : null;
+export const listShokInvocationsV2 = () => [..._si.values()].map(clone);
+export function autoDisableIdleShokProfilesV2({ now = Date.now() } = {}) {
   const flipped = [];
-  for (const p of _shokPsV2.values())
-    if (
-      p.status === SHOK_PROFILE_MATURITY_V2.ACTIVE &&
-      t - p.lastTouchedAt >= _shokIdleMs
-    ) {
-      p.status = SHOK_PROFILE_MATURITY_V2.DISABLED;
-      p.updatedAt = t;
+  for (const p of _sp.values())
+    if (p.status === "active" && now - p.lastTouchedAt >= _idleMs) {
+      p.status = "disabled";
+      p.updatedAt = now;
       flipped.push(p.id);
     }
   return { flipped, count: flipped.length };
 }
-export function autoFailStuckShokInvocationsV2({ now } = {}) {
-  const t = now ?? Date.now();
+export function autoFailStuckShokInvocationsV2({ now = Date.now() } = {}) {
   const flipped = [];
-  for (const i of _shokIsV2.values())
-    if (
-      i.status === SHOK_INVOCATION_LIFECYCLE_V2.RUNNING &&
-      i.startedAt != null &&
-      t - i.startedAt >= _shokStuckMs
-    ) {
-      i.status = SHOK_INVOCATION_LIFECYCLE_V2.FAILED;
-      i.updatedAt = t;
-      if (!i.settledAt) i.settledAt = t;
+  for (const i of _si.values())
+    if (i.status === "running" && now - i.startedAt >= _stuckMs) {
+      i.status = "failed";
+      i.updatedAt = i.settledAt = now;
       i.metadata.failReason = "auto-fail-stuck";
       flipped.push(i.id);
     }
   return { flipped, count: flipped.length };
 }
 export function getSessionHooksGovStatsV2() {
-  const profilesByStatus = {};
-  for (const v of Object.values(SHOK_PROFILE_MATURITY_V2))
-    profilesByStatus[v] = 0;
-  for (const p of _shokPsV2.values()) profilesByStatus[p.status]++;
-  const invocationsByStatus = {};
-  for (const v of Object.values(SHOK_INVOCATION_LIFECYCLE_V2))
-    invocationsByStatus[v] = 0;
-  for (const i of _shokIsV2.values()) invocationsByStatus[i.status]++;
+  const profilesByStatus = Object.fromEntries(
+    Object.values(SHOK_PROFILE_MATURITY_V2).map((x) => [x, 0]),
+  );
+  const invocationsByStatus = Object.fromEntries(
+    Object.values(SHOK_INVOCATION_LIFECYCLE_V2).map((x) => [x, 0]),
+  );
+  for (const p of _sp.values()) profilesByStatus[p.status]++;
+  for (const i of _si.values()) invocationsByStatus[i.status]++;
   return {
-    totalShokProfilesV2: _shokPsV2.size,
-    totalShokInvocationsV2: _shokIsV2.size,
-    maxActiveShokProfilesPerOwner: _shokMaxActive,
-    maxPendingShokInvocationsPerProfile: _shokMaxPending,
-    shokProfileIdleMs: _shokIdleMs,
-    shokInvocationStuckMs: _shokStuckMs,
+    totalShokProfilesV2: _sp.size,
+    totalShokInvocationsV2: _si.size,
+    maxActiveShokProfilesPerOwner: _maxActive,
+    maxPendingShokInvocationsPerProfile: _maxPending,
+    shokProfileIdleMs: _idleMs,
+    shokInvocationStuckMs: _stuckMs,
     profilesByStatus,
     invocationsByStatus,
   };
 }
-
-/**
- * Fire settings.json Stop hooks (observe-only) — fires at the END of EVERY
- * agent turn/loop iteration, BEFORE waiting for the next user input.
- * Aligns with Claude Code hook spec.
- *
- * Fires regardless of outcome: normal completion, error, max iterations,
- * user interrupt, or tool stop. Does NOT fire on final process exit
- * (use SessionEnd/Shutdown hooks for that case).
- *
- * @param {Object} opts
- * @param {string} opts.sessionId - Current session ID
- * @param {string} opts.transcriptPath - Path to transcript file
- * @param {string} [opts.stopReason="end_turn"] - Reason the turn stopped:
- *   "end_turn", "error", "max_iterations", "user_interrupt", "tool_stop"
- * @param {string} [opts.finalResponse=""] - Final assistant response text
- * @param {number} [opts.toolCount=0] - Number of tool calls made this turn
- * @param {number} [opts.durationMs=0] - Turn duration in milliseconds
- * @param {Error|string} [opts.error] - Error object if stopReason is "error"
- * @returns {Promise<Array>} Hook execution results
- */
-export async function fireSessionStop({
-  sessionId,
-  transcriptPath,
-  stopReason = "end_turn",
-  finalResponse = "",
-  toolCount = 0,
-  durationMs = 0,
-  error = null,
-}) {
-  return runSettingsHooks("Stop", {
-    session_id: sessionId,
-    transcript_path: transcriptPath,
-    stop_reason: stopReason,
-    final_response: finalResponse,
-    tool_count: toolCount,
-    duration_ms: durationMs,
-    error: error ? String(error.message ?? error) : "",
-    timestamp: new Date().toISOString(),
-  });
-}