@desplega.ai/agent-swarm 2.5.2 → 2.5.4

package/src/extensions/catalog.generated.json

@@ -4,17 +4,17 @@
     "manifest": {
       "$schema": "../manifest.schema.json",
       "name": "comms-adherence-gate",
-      "description": "Judges every Slack-facing store-progress completion against the requester's comms preferences and latest request with Jev (TypeSafe or OpenRouter), and in enforce blocks a non-adherent completion once per task",
-      "version": "1.5.0",
+      "description": "Judges every Slack-facing store-progress completion and agent Slack post against the comms preferences of the requester, or of the person it @-mentions, their latest request and a plain-language rubric with Jev (TypeSafe or OpenRouter), and in enforce blocks a failing call once per task",
+      "version": "1.7.0",
       "runtime": "api",
       "assets": {
         "hooks": "hooks.ts"
       }
     },
     "files": {
-      "hooks.ts": "import { type ApiCtx, block, type SwarmExtension } from \"swarm-extension\";\nimport { z } from \"zod\";\n\n/**\n * comms-adherence-gate\n *\n * When an agent calls `store-progress` with status \"completed\" on a task that\n * reaches a human in Slack, judge the `output` against the requesting user's\n * stored comms preferences (users.metadata.$.comms) with Jev, and against what\n * that user actually asked for in their latest message. An explicit request\n * (\"tell me a long joke\", \"explain in detail\") outranks the stored default, so\n * a requested long answer is not a verbosity failure.\n *\n * Transport (config.provider): Jev is served by TypeSafe directly and by\n * OpenRouter's Decisions endpoint. Both take the same {model, state, questions}\n * body and return the same `answers` shape. `auto` uses TYPESAFE_API_KEY when\n * set, else OPENROUTER_API_KEY.\n *\n * modes (config.mode):\n *   off     -> never evaluate\n *   shadow  -> evaluate + record, never block (default)\n *   enforce -> record, and block the completion up to maxBlocksPerTask times\n *              per task with actionable feedback\n *\n * Fails OPEN on every error: a judge outage must never wall the swarm.\n * Every verdict lands in KV namespace `ext:comms-gate`.\n */\n\nexport const config = z.object({\n  mode: z.enum([\"off\", \"shadow\", \"enforce\"]).default(\"shadow\"),\n  /** A dimension scoring below this fails. */\n  threshold: z.number().min(0).max(1).default(0.5),\n  timeoutMs: z.number().int().positive().default(4000),\n  maxBlocksPerTask: z.number().int().min(0).default(1),\n  provider: z.enum([\"auto\", \"typesafe\", \"openrouter\"]).default(\"auto\"),\n  /** Jev model on the TypeSafe transport. */\n  model: z.string().default(\"jev-latest\"),\n  /** Jev model on the OpenRouter transport. */\n  openrouterModel: z.string().default(\"typesafe/jev-1.13\"),\n  /** Explicit TypeSafe key; otherwise TYPESAFE_API_KEY from the API process env. */\n  apiKey: z.string().optional(),\n});\n\ntype Cfg = z.infer<typeof config>;\ntype Swarm = ApiCtx[\"swarm\"];\n\nconst NS = \"ext:comms-gate\";\nconst TYPESAFE_ENDPOINT = \"https://api.typesafe.ai/v1/systemone\";\nconst OPENROUTER_ENDPOINT = \"https://openrouter.ai/api/alpha/decisions\";\nconst UUID_RE = /^[0-9a-fA-F-]{36}$/;\n// The dispatcher cancels a handler after 5 s; leave room for the DB read and KV writes.\nconst MAX_TIMEOUT_MS = 4000;\n\nexport const cfgOf = (raw: unknown): Cfg => {\n  const parsed = config.safeParse(raw ?? {});\n  return parsed.success ? parsed.data : config.parse({});\n};\n\n// kv keys accept [a-zA-Z0-9._:/%-]\nconst safeKey = (raw: string | undefined | null): string =>\n  (raw && raw.length > 0 ? raw : \"unknown\").replace(/[^a-zA-Z0-9._-]/g, \"_\").slice(0, 120);\n\n/** SDK envelopes: {success, data:{...}} or the bare payload. */\ntype Envelope = {\n  data?: { rows?: unknown[]; value?: unknown };\n  rows?: unknown[];\n  value?: unknown;\n} | null;\n\nconst cell = (row: unknown, i: number, key: string): unknown =>\n  Array.isArray(row) ? row[i] : (row as Record<string, unknown>)?.[key];\n\n/**\n * The newest human message sits at the END of a Slack task: the\n * `<thread_context>` blob comes first and can run to thousands of chars, so a\n * leading slice of `agent_tasks.task` shows the judge everything except the\n * actual request. Take the tail, then the part after the last `</thread_context>`.\n */\nconst CTX_END = \"</thread_context>\";\nexport const latestAsk = (tail: string): string => {\n  const end = tail.lastIndexOf(CTX_END);\n  let out = (end >= 0 ? tail.slice(end + CTX_END.length) : tail)\n    .replace(/\\[Thread follow-up[^\\]]*\\]/g, \"\")\n    .trim();\n  // Some tasks end with the context block; fall back to the last messages in it.\n  if (out.length < 8) out = (end >= 0 ? tail.slice(0, end) : tail).trim().slice(-800);\n  return out.slice(0, 900);\n};\n\n// Preferences are the DEFAULT. A direct request outranks them.\nconst JUDGING_RULES = [\n  \"The requester's explicit instruction in latest_request OUTRANKS requester_preferences. Preferences describe the DEFAULT; they never override a direct request.\",\n  \"If latest_request asks for something long, detailed, creative, a story, a joke, a full explanation or a document, then length and structure serving that request are CORRECT and must NOT be penalized.\",\n  \"Judge whether agent_message serves what latest_request actually asked for, written in the requester's manner. Do not judge it against the default preference when the request overrides it.\",\n];\n\ntype Prefs = { verbosity?: unknown; tone?: unknown; language?: unknown } & Record<string, unknown>;\n\n/** One `noul` question per stated preference the gate knows how to judge. */\nexport const buildQuestions = (prefs: Prefs): Record<string, unknown> => {\n  const questions: Record<string, unknown> = {};\n  if (prefs.verbosity) {\n    questions.verbosity = {\n      type: \"noul\",\n      instructions:\n        \"Does agent_message respect the requester's verbosity preference, AS OVERRIDDEN by any explicit instruction in latest_request? Apply judging_rules.\",\n      criteria: {\n        true: \"Length and structure fit what latest_request asked for (or the stated preference when the request does not override it), and it leads with the result.\",\n        false:\n          \"Too long for what was asked, or it opens with preamble, recaps the request, narrates the process, or ends with an offer to elaborate. Length explicitly requested in latest_request is NOT a failure.\",\n      },\n    };\n  }\n  if (prefs.tone) {\n    questions.tone = {\n      type: \"noul\",\n      instructions:\n        \"Does agent_message match the requester's stated tone preference, as overridden by any explicit instruction in latest_request? Apply judging_rules.\",\n      criteria: {\n        true: \"The tone matches what the requester asked for.\",\n        false:\n          \"The tone conflicts with it (for example hedging, flattery or filler when the requester asked for direct and plain). A voice appropriate to an explicitly requested creative or narrative form is NOT a failure.\",\n      },\n    };\n  }\n  if (prefs.language) {\n    questions.language = {\n      type: \"noul\",\n      instructions: \"Is agent_message written in the requester's stated language?\",\n      criteria: {\n        true: \"Written in the stated language.\",\n        false: \"Written in a different language.\",\n      },\n    };\n  }\n  return questions;\n};\n\nconst secretCache = new Map<string, { value: string; at: number }>();\nconst KEY_TTL_MS = 5 * 60 * 1000;\nconst usable = (v: string): boolean => Boolean(v) && !v.startsWith(\"[REDACTED\");\nconst envOf = (name: string): string => String(process.env[name] ?? \"\");\n\n/**\n * Resolve a secret: explicit value, then the API process env. The API process loads\n * global swarm_config rows into process.env at boot and on config reload.\n * ctx.swarm.config_get cannot serve it: the SDK scrubs secrets to \"[REDACTED:<name>]\".\n */\nconst secret = (name: string, explicit?: string): string => {\n  const cached = secretCache.get(name);\n  if (cached && Date.now() - cached.at < KEY_TTL_MS) return cached.value;\n  const value = [String(explicit ?? \"\"), envOf(name)].find(usable) ?? \"\";\n  if (usable(value)) secretCache.set(name, { value, at: Date.now() });\n  return value;\n};\n\n/** Test hook: forget cached secrets. */\nexport const resetKeyCache = (): void => {\n  secretCache.clear();\n};\n\nexport type JevTransport = {\n  provider: \"typesafe\" | \"openrouter\";\n  endpoint: string;\n  key: string;\n  model: string;\n};\n\n/**\n * Pick the Jev transport. `auto` prefers TypeSafe and falls back to OpenRouter.\n * Throws when the chosen provider has no usable key; the handler fails open.\n */\nexport const resolveTransport = (cfg: Cfg): JevTransport => {\n  const typesafe = (): JevTransport | null => {\n    const key = secret(\"TYPESAFE_API_KEY\", cfg.apiKey);\n    return usable(key)\n      ? { provider: \"typesafe\", endpoint: TYPESAFE_ENDPOINT, key, model: cfg.model }\n      : null;\n  };\n  const openrouter = (): JevTransport | null => {\n    const key = secret(\"OPENROUTER_API_KEY\");\n    return usable(key)\n      ? { provider: \"openrouter\", endpoint: OPENROUTER_ENDPOINT, key, model: cfg.openrouterModel }\n      : null;\n  };\n  const transport =\n    cfg.provider === \"typesafe\"\n      ? typesafe()\n      : cfg.provider === \"openrouter\"\n        ? openrouter()\n        : (typesafe() ?? openrouter());\n  if (transport) return transport;\n  throw new Error(\n    cfg.provider === \"typesafe\"\n      ? \"no TYPESAFE_API_KEY\"\n      : cfg.provider === \"openrouter\"\n        ? \"no OPENROUTER_API_KEY\"\n        : \"no TYPESAFE_API_KEY or OPENROUTER_API_KEY\",\n  );\n};\n\n/** One Jev call; returns the `noul` score per question. Throws on any failure. */\nexport const askJev = async (\n  state: Record<string, unknown>,\n  questions: Record<string, unknown>,\n  transport: JevTransport,\n  cfg: Cfg,\n  outer?: AbortSignal,\n): Promise<{ scores: Record<string, number>; latencyMs: number }> => {\n  const controller = new AbortController();\n  const timer = setTimeout(() => controller.abort(), Math.min(cfg.timeoutMs, MAX_TIMEOUT_MS));\n  const onOuterAbort = () => controller.abort();\n  outer?.addEventListener(\"abort\", onOuterAbort);\n  const t0 = Date.now();\n  try {\n    const res = await fetch(transport.endpoint, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\", Authorization: `Bearer ${transport.key}` },\n      body: JSON.stringify({ state, model: transport.model, questions }),\n      signal: controller.signal,\n    });\n    if (!res.ok) throw new Error(`${transport.provider} ${res.status}`);\n    const body = (await res.json()) as { answers?: Record<string, { noul?: unknown }> } | null;\n    const answers = body?.answers;\n    if (!answers || typeof answers !== \"object\") throw new Error(\"no answers in response\");\n    const scores: Record<string, number> = {};\n    for (const [id, a] of Object.entries(answers)) {\n      if (typeof a?.noul === \"number\") scores[id] = a.noul;\n    }\n    if (Object.keys(scores).length === 0) throw new Error(\"no scores in response\");\n    return { scores, latencyMs: Date.now() - t0 };\n  } finally {\n    clearTimeout(timer);\n    outer?.removeEventListener(\"abort\", onOuterAbort);\n  }\n};\n\nconst SELFTEST = \"comms-gate-selftest\";\nconst SELFTEST_PREFS = {\n  tone: \"direct, plain, no hedging\",\n  language: \"English\",\n  verbosity:\n    \"very terse - answer in the first sentence, ~400 chars max. No preamble, no recap, no closing offer.\",\n};\nconst SELFTEST_BAD =\n  \"Great question! Let me walk you through what I did here. First I looked at the task, then I reviewed the relevant files, and after careful consideration I decided to go with option B. I hope this helps - let me know if you would like me to elaborate further on any of the above!\";\nconst SELFTEST_GOOD =\n  \"Went with option B: it is the only one that keeps the migration reversible. PR #123.\";\n\n/**\n * Run the judge on a known-bad (positive control, must score below threshold) and a\n * known-good (negative control, must score at or above it) message and record both\n * under `selftest:last`. Proves key, egress and KV from inside the API runtime\n * without touching real traffic.\n */\nconst selfTest = async (swarm: Swarm, cfg: Cfg, signal?: AbortSignal): Promise<void> => {\n  const started = Date.now();\n  try {\n    const transport = resolveTransport(cfg);\n    const questions = { verbosity: buildQuestions(SELFTEST_PREFS).verbosity };\n    const judge = (message: string) =>\n      askJev(\n        { requester_preferences: SELFTEST_PREFS, agent_message: message },\n        questions,\n        transport,\n        cfg,\n        signal,\n      ).then((r) => r.scores.verbosity ?? null);\n    const [bad, good] = await Promise.all([judge(SELFTEST_BAD), judge(SELFTEST_GOOD)]);\n    await swarm.kv_set({\n      namespace: NS,\n      key: \"selftest:last\",\n      value: {\n        at: new Date().toISOString(),\n        provider: transport.provider,\n        threshold: cfg.threshold,\n        positiveControlBadScore: bad,\n        negativeControlGoodScore: good,\n        controlsOk:\n          typeof bad === \"number\" &&\n          typeof good === \"number\" &&\n          bad < cfg.threshold &&\n          good >= cfg.threshold,\n        latencyMs: Date.now() - started,\n      },\n    });\n  } catch (err) {\n    await swarm\n      .kv_set({\n        namespace: NS,\n        key: \"selftest:last\",\n        value: {\n          at: new Date().toISOString(),\n          error: String(err).slice(0, 400),\n          latencyMs: Date.now() - started,\n        },\n      })\n      .catch(() => {});\n  }\n};\n\nconst TASK_SQL = `SELECT t.source, t.slackThreadTs, t.agentId, t.requestedByUserId,\n       json_extract(u.metadata, '$.comms') AS comms, u.name,\n       substr(t.task, 1, 400) AS askHead,\n       substr(t.task, -1400) AS askTail\nFROM agent_tasks t\nLEFT JOIN users u ON u.id = t.requestedByUserId\nWHERE t.id = ?`;\n\nconst LEAD_SQL = \"SELECT isLead FROM agents WHERE id = ?\";\n\n/**\n * Mirrors the `task.progress.write` rule store-progress enforces\n * (src/rbac/legacy-policy.ts): the caller owns the task, the task is\n * unassigned, or the caller is a lead. Lead status comes from the caller's\n * agents row, never from tool args. Extension callers return before this.\n */\nconst mayWriteProgress = async (\n  swarm: Swarm,\n  callerId: string | undefined,\n  taskAgentId: string,\n): Promise<boolean> => {\n  if (!callerId) return false;\n  if (!taskAgentId || taskAgentId === callerId) return true;\n  const q = (await swarm.db_query({ sql: LEAD_SQL, params: [callerId] })) as Envelope;\n  const row = (q?.data?.rows ?? q?.rows ?? [])[0];\n  return Number(cell(row, 0, \"isLead\") ?? 0) === 1;\n};\n\nconst extension: SwarmExtension = (api) => {\n  api.on(\"pre.tool.call\", async (event, ctx) => {\n    if (event.tool !== \"store-progress\") return;\n    if (event.requestInfo?.callOrigin === \"extension\") return;\n\n    const cfg = cfgOf(ctx.config);\n    if (cfg.mode === \"off\") return;\n\n    const args = (event.args ?? {}) as Record<string, unknown>;\n\n    // Self-test hatch: a progress call whose text starts with the sentinel runs\n    // the controls and records them under `selftest:last`.\n    if (args.status !== \"completed\") {\n      if (typeof args.progress === \"string\" && args.progress.startsWith(SELFTEST)) {\n        await selfTest(ctx.swarm, cfg, ctx.signal);\n      }\n      return;\n    }\n\n    const output = typeof args.output === \"string\" ? args.output.trim() : \"\";\n    if (!output) return;\n\n    const taskId = String(args.taskId ?? event.requestInfo?.sourceTaskId ?? \"\");\n    if (!UUID_RE.test(taskId)) return;\n\n    try {\n      const q = (await ctx.swarm.db_query({ sql: TASK_SQL, params: [taskId] })) as Envelope;\n      const row = (q?.data?.rows ?? q?.rows ?? [])[0];\n      if (!row) return;\n\n      const source = String(cell(row, 0, \"source\") ?? \"\");\n      const slackThreadTs = cell(row, 1, \"slackThreadTs\");\n      const agentId = String(cell(row, 2, \"agentId\") ?? \"\");\n      const requesterId = String(cell(row, 3, \"requestedByUserId\") ?? \"\");\n      const commsRaw = cell(row, 4, \"comms\");\n      const requesterName = String(cell(row, 5, \"name\") ?? requesterId);\n      const threadOpening = String(cell(row, 6, \"askHead\") ?? \"\");\n      const ask = latestAsk(String(cell(row, 7, \"askTail\") ?? \"\"));\n\n      // Judge only a completion store-progress will accept, so no agent can ship\n      // another task's thread and preferences to the external judge.\n      if (!(await mayWriteProgress(ctx.swarm, event.requestInfo?.agentId, agentId))) return;\n\n      // Only where the text actually reaches a human in Slack.\n      if (source !== \"slack\" && !slackThreadTs) return;\n      if (!commsRaw) return; // no stated preferences -> nothing to judge against\n      const prefs = (typeof commsRaw === \"string\" ? JSON.parse(commsRaw) : commsRaw) as Prefs;\n      if (!prefs || typeof prefs !== \"object\") return;\n\n      const questions = buildQuestions(prefs);\n      if (Object.keys(questions).length === 0) return;\n\n      const transport = resolveTransport(cfg);\n      const { scores, latencyMs } = await askJev(\n        {\n          role: \"You audit an AI agent's final message to the human who requested the work.\",\n          requester: requesterName,\n          requester_preferences: prefs,\n          latest_request: ask,\n          thread_opening: threadOpening,\n          judging_rules: JUDGING_RULES,\n          agent_message: output,\n        },\n        questions,\n        transport,\n        cfg,\n        ctx.signal,\n      );\n\n      const failed = Object.entries(scores)\n        .filter(([, v]) => v < cfg.threshold)\n        .map(([k]) => k);\n\n      const verdict = {\n        at: new Date().toISOString(),\n        taskId,\n        agentId,\n        source,\n        requester: requesterName,\n        requesterId,\n        provider: transport.provider,\n        scores,\n        failed,\n        threshold: cfg.threshold,\n        mode: cfg.mode,\n        latencyMs,\n        preferences: prefs,\n        askPreview: ask.slice(0, 400),\n        outputPreview: output.slice(0, 700),\n      };\n\n      await ctx.swarm.kv_incr({ namespace: NS, key: \"total\" });\n      await ctx.swarm.kv_set({ namespace: NS, key: \"last\", value: verdict });\n\n      if (failed.length === 0) {\n        await ctx.swarm.kv_incr({ namespace: NS, key: \"pass\" });\n        return;\n      }\n\n      await ctx.swarm.kv_incr({ namespace: NS, key: \"fail\" });\n      for (const dim of failed) {\n        await ctx.swarm.kv_incr({ namespace: NS, key: `dim:${safeKey(dim)}` });\n      }\n\n      const blocksKey = `blocks:${safeKey(taskId)}`;\n      // kv_get answers {success, data:{value}}, and {success:false} when absent.\n      const prior = (await ctx.swarm.kv_get({ namespace: NS, key: blocksKey })) as Envelope;\n      const priorBlocks = Number(prior?.data?.value ?? prior?.value ?? 0) || 0;\n      const willBlock = cfg.mode === \"enforce\" && priorBlocks < cfg.maxBlocksPerTask;\n\n      await ctx.swarm.kv_set({\n        namespace: NS,\n        key: `fail:${Date.now()}:${safeKey(taskId)}`,\n        value: { ...verdict, action: willBlock ? \"blocked\" : \"recorded\" },\n      });\n\n      if (!willBlock) {\n        await ctx.swarm.kv_incr({\n          namespace: NS,\n          key: cfg.mode === \"enforce\" ? \"escaped\" : \"shadowed\",\n        });\n        return;\n      }\n\n      await ctx.swarm.kv_incr({ namespace: NS, key: \"blocked\" });\n      await ctx.swarm.kv_incr({ namespace: NS, key: blocksKey });\n\n      const detail = failed\n        .map(\n          (d) =>\n            `${d} (${scores[d]!.toFixed(2)} vs ${cfg.threshold}) — requested: ${String(prefs[d] ?? \"\").slice(0, 220)}`,\n        )\n        .join(\"\\n\");\n\n      return block(\n        [\n          `Comms gate: this output does not match ${requesterName}'s stated preferences.`,\n          detail,\n          \"Rewrite the output to match and call store-progress again. Do not change the facts, only how they are said.\",\n        ].join(\"\\n\"),\n      );\n    } catch (err) {\n      // Fail open, always.\n      try {\n        await ctx.swarm.kv_incr({ namespace: NS, key: \"error\" });\n        await ctx.swarm.kv_set({\n          namespace: NS,\n          key: \"error:last\",\n          value: { at: new Date().toISOString(), taskId, error: String(err).slice(0, 400) },\n        });\n      } catch {\n        /* ignore */\n      }\n      ctx.log.warn(\"comms-adherence-gate: failing open\", { error: String(err) });\n      return;\n    }\n  });\n};\n\nexport default extension;\n"
+      "hooks.ts": "import { type ApiCtx, block, type SwarmExtension } from \"swarm-extension\";\nimport { z } from \"zod\";\n\n/**\n * comms-adherence-gate\n *\n * When an agent calls `store-progress` with status \"completed\" on a task that\n * reaches a human in Slack, or posts to Slack itself (`slack-reply`,\n * `slack-post`, `slack-start-thread`, `slack-update`), judge the text with Jev:\n * against the requesting user's stored comms preferences\n * (users.metadata.$.comms) and what that user actually asked for in their\n * latest message, and against a plain-language rubric that applies to every\n * message whatever preferences exist. An explicit request (\"tell me a long\n * joke\", \"explain in detail\") outranks the stored default, so a requested long\n * answer is not a verbosity failure.\n *\n * Threads with several people: a message that @-mentions someone is judged\n * against the first mentioned person with stored preferences, skipping a\n * requester without preferences; otherwise against the requester. `plain` applies to everyone.\n *\n * Transport (config.provider): Jev is served by TypeSafe directly and by\n * OpenRouter's Decisions endpoint. Both take the same {model, state, questions}\n * body and return the same `answers` shape. `auto` uses TYPESAFE_API_KEY when\n * set, else OPENROUTER_API_KEY.\n *\n * modes (config.mode for the preference dimensions, config.plainMode for `plain`):\n *   off     -> never evaluate\n *   shadow  -> evaluate + record, never block (default)\n *   enforce -> record, and block the call up to maxBlocksPerTask times per task\n *              with actionable feedback. The budget is shared by both modes and\n *              by every gated tool.\n *\n * Fails OPEN on every error: a judge outage must never wall the swarm.\n * Every verdict lands in KV namespace `ext:comms-gate`.\n */\n\nexport const config = z.object({\n  mode: z.enum([\"off\", \"shadow\", \"enforce\"]).default(\"shadow\"),\n  /** A preference dimension scoring below this fails. */\n  threshold: z.number().min(0).max(1).default(0.5),\n  /** The `plain` dimension, judged on every message. Independent of `mode`. */\n  plainMode: z.enum([\"off\", \"shadow\", \"enforce\"]).default(\"shadow\"),\n  /**\n   * `plain` scoring below this fails. Jev scores dense status text low and\n   * plain text high with little in between, so this sits far below `threshold`.\n   */\n  plainThreshold: z.number().min(0).max(1).default(0.25),\n  timeoutMs: z.number().int().positive().default(4000),\n  maxBlocksPerTask: z.number().int().min(0).default(1),\n  provider: z.enum([\"auto\", \"typesafe\", \"openrouter\"]).default(\"auto\"),\n  /** Jev model on the TypeSafe transport. */\n  model: z.string().default(\"jev-latest\"),\n  /** Jev model on the OpenRouter transport. */\n  openrouterModel: z.string().default(\"typesafe/jev-1.13\"),\n  /** Explicit TypeSafe key; otherwise TYPESAFE_API_KEY from the API process env. */\n  apiKey: z.string().optional(),\n});\n\ntype Cfg = z.infer<typeof config>;\ntype Swarm = ApiCtx[\"swarm\"];\n\nconst NS = \"ext:comms-gate\";\nconst TYPESAFE_ENDPOINT = \"https://api.typesafe.ai/v1/systemone\";\nconst OPENROUTER_ENDPOINT = \"https://openrouter.ai/api/alpha/decisions\";\nconst UUID_RE = /^[0-9a-fA-F-]{36}$/;\n/** MCP tools that post agent-authored text to Slack, all with a `message` arg. */\nexport const SLACK_TOOLS = new Set([\n  \"slack-reply\",\n  \"slack-post\",\n  \"slack-start-thread\",\n  \"slack-update\",\n]);\n// The dispatcher cancels a handler after 5 s; leave room for the DB read and KV writes.\nconst MAX_TIMEOUT_MS = 4000;\n\nexport const cfgOf = (raw: unknown): Cfg => {\n  const parsed = config.safeParse(raw ?? {});\n  return parsed.success ? parsed.data : config.parse({});\n};\n\n// kv keys accept [a-zA-Z0-9._:/%-]\nconst safeKey = (raw: string | undefined | null): string =>\n  (raw && raw.length > 0 ? raw : \"unknown\").replace(/[^a-zA-Z0-9._-]/g, \"_\").slice(0, 120);\n\n/** SDK envelopes: {success, data:{...}} or the bare payload. */\ntype Envelope = {\n  data?: { rows?: unknown[]; value?: unknown };\n  rows?: unknown[];\n  value?: unknown;\n} | null;\n\nconst cell = (row: unknown, i: number, key: string): unknown =>\n  Array.isArray(row) ? row[i] : (row as Record<string, unknown>)?.[key];\n\n/**\n * The newest human message sits at the END of a Slack task: the\n * `<thread_context>` blob comes first and can run to thousands of chars, so a\n * leading slice of `agent_tasks.task` shows the judge everything except the\n * actual request. Take the tail, then the part after the last `</thread_context>`.\n */\nconst CTX_END = \"</thread_context>\";\nexport const latestAsk = (tail: string): string => {\n  const end = tail.lastIndexOf(CTX_END);\n  let out = (end >= 0 ? tail.slice(end + CTX_END.length) : tail)\n    .replace(/\\[Thread follow-up[^\\]]*\\]/g, \"\")\n    .trim();\n  // Some tasks end with the context block; fall back to the last messages in it.\n  if (out.length < 8) out = (end >= 0 ? tail.slice(0, end) : tail).trim().slice(-800);\n  return out.slice(0, 900);\n};\n\n// Preferences are the DEFAULT. A direct request outranks them.\nconst JUDGING_RULES = [\n  \"The requester's explicit instruction in latest_request OUTRANKS requester_preferences. Preferences describe the DEFAULT; they never override a direct request.\",\n  \"If latest_request asks for something long, detailed, creative, a story, a joke, a full explanation or a document, then length and structure serving that request are CORRECT and must NOT be penalized.\",\n  \"Judge whether agent_message serves what latest_request actually asked for, written in the requester's manner. Do not judge it against the default preference when the request overrides it.\",\n];\n\ntype Prefs = { verbosity?: unknown; tone?: unknown; language?: unknown } & Record<string, unknown>;\n\n/**\n * The `plain` rubric, from the `comms` skill (Simpler and Precise modes). Jev\n * separates dense from plain text reliably only with contrasting examples; a\n * prose-only rubric scored a plain rewrite as low as the dense original.\n */\nexport const PLAIN_RULES = [\n  \"Examples of NOT plain: 'p50 Δ +120ms vs baseline (n=37)', 'error rate 2.1% → 0.4% (cohort B, ±0.3 at 95%)', 'cost $-42/day', 'first-call hit ratio 0.61', 'drift unmeasured; 2 flaky'.\",\n  \"Examples of plain: 'Pages load 120 ms slower than last week, across 37 runs', 'Errors dropped from 2 in 100 requests to 4 in 1,000', 'We spend $42 a day less', 'PR #123 keeps the migration reversible', 'Lead saves about $75 a week'.\",\n  \"Code identifiers, task ids, PR numbers, links, file paths and version numbers are fine as they are.\",\n];\n\nexport const PLAIN_QUESTION = {\n  type: \"noul\",\n  instructions:\n    \"Is agent_message written like the plain examples in plain_language_rules rather than like the NOT plain ones? Ignore length and tone.\",\n  criteria: {\n    true: \"Written like the plain examples: everyday words and numbers with units and direction.\",\n    false:\n      \"Written like the NOT plain examples: statistics shorthand, abbreviations, signed or cryptic numbers.\",\n  },\n};\n\n/** Structured output (an outputSchema answer) is for machines; `plain` skips it. */\nexport const looksLikeJson = (text: string): boolean => {\n  if (!/^[[{]/.test(text)) return false;\n  try {\n    JSON.parse(text);\n    return true;\n  } catch {\n    return false;\n  }\n};\n\n/** One `noul` question per stated preference the gate knows how to judge. */\nexport const buildQuestions = (prefs: Prefs): Record<string, unknown> => {\n  const questions: Record<string, unknown> = {};\n  if (prefs.verbosity) {\n    questions.verbosity = {\n      type: \"noul\",\n      instructions:\n        \"Does agent_message respect the requester's verbosity preference, AS OVERRIDDEN by any explicit instruction in latest_request? Apply judging_rules.\",\n      criteria: {\n        true: \"Length and structure fit what latest_request asked for (or the stated preference when the request does not override it), and it leads with the result.\",\n        false:\n          \"Too long for what was asked, or it opens with preamble, recaps the request, narrates the process, or ends with an offer to elaborate. Length explicitly requested in latest_request is NOT a failure.\",\n      },\n    };\n  }\n  if (prefs.tone) {\n    questions.tone = {\n      type: \"noul\",\n      instructions:\n        \"Does agent_message match the requester's stated tone preference, as overridden by any explicit instruction in latest_request? Apply judging_rules.\",\n      criteria: {\n        true: \"The tone matches what the requester asked for.\",\n        false:\n          \"The tone conflicts with it (for example hedging, flattery or filler when the requester asked for direct and plain). A voice appropriate to an explicitly requested creative or narrative form is NOT a failure.\",\n      },\n    };\n  }\n  if (prefs.language) {\n    questions.language = {\n      type: \"noul\",\n      instructions: \"Is agent_message written in the requester's stated language?\",\n      criteria: {\n        true: \"Written in the stated language.\",\n        false: \"Written in a different language.\",\n      },\n    };\n  }\n  return questions;\n};\n\nconst secretCache = new Map<string, { value: string; at: number }>();\nconst KEY_TTL_MS = 5 * 60 * 1000;\nconst usable = (v: string): boolean => Boolean(v) && !v.startsWith(\"[REDACTED\");\nconst envOf = (name: string): string => String(process.env[name] ?? \"\");\n\n/**\n * Resolve a secret: explicit value, then the API process env. The API process loads\n * global swarm_config rows into process.env at boot and on config reload.\n * ctx.swarm.config_get cannot serve it: the SDK scrubs secrets to \"[REDACTED:<name>]\".\n */\nconst secret = (name: string, explicit?: string): string => {\n  const cached = secretCache.get(name);\n  if (cached && Date.now() - cached.at < KEY_TTL_MS) return cached.value;\n  const value = [String(explicit ?? \"\"), envOf(name)].find(usable) ?? \"\";\n  if (usable(value)) secretCache.set(name, { value, at: Date.now() });\n  return value;\n};\n\n/** Test hook: forget cached secrets. */\nexport const resetKeyCache = (): void => {\n  secretCache.clear();\n};\n\nexport type JevTransport = {\n  provider: \"typesafe\" | \"openrouter\";\n  endpoint: string;\n  key: string;\n  model: string;\n};\n\n/**\n * Pick the Jev transport. `auto` prefers TypeSafe and falls back to OpenRouter.\n * Throws when the chosen provider has no usable key; the handler fails open.\n */\nexport const resolveTransport = (cfg: Cfg): JevTransport => {\n  const typesafe = (): JevTransport | null => {\n    const key = secret(\"TYPESAFE_API_KEY\", cfg.apiKey);\n    return usable(key)\n      ? { provider: \"typesafe\", endpoint: TYPESAFE_ENDPOINT, key, model: cfg.model }\n      : null;\n  };\n  const openrouter = (): JevTransport | null => {\n    const key = secret(\"OPENROUTER_API_KEY\");\n    return usable(key)\n      ? { provider: \"openrouter\", endpoint: OPENROUTER_ENDPOINT, key, model: cfg.openrouterModel }\n      : null;\n  };\n  const transport =\n    cfg.provider === \"typesafe\"\n      ? typesafe()\n      : cfg.provider === \"openrouter\"\n        ? openrouter()\n        : (typesafe() ?? openrouter());\n  if (transport) return transport;\n  throw new Error(\n    cfg.provider === \"typesafe\"\n      ? \"no TYPESAFE_API_KEY\"\n      : cfg.provider === \"openrouter\"\n        ? \"no OPENROUTER_API_KEY\"\n        : \"no TYPESAFE_API_KEY or OPENROUTER_API_KEY\",\n  );\n};\n\n/** One Jev call; returns the `noul` score per question. Throws on any failure. */\nexport const askJev = async (\n  state: Record<string, unknown>,\n  questions: Record<string, unknown>,\n  transport: JevTransport,\n  cfg: Cfg,\n  outer?: AbortSignal,\n): Promise<{ scores: Record<string, number>; latencyMs: number }> => {\n  const controller = new AbortController();\n  const timer = setTimeout(() => controller.abort(), Math.min(cfg.timeoutMs, MAX_TIMEOUT_MS));\n  const onOuterAbort = () => controller.abort();\n  outer?.addEventListener(\"abort\", onOuterAbort);\n  const t0 = Date.now();\n  try {\n    const res = await fetch(transport.endpoint, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\", Authorization: `Bearer ${transport.key}` },\n      body: JSON.stringify({ state, model: transport.model, questions }),\n      signal: controller.signal,\n    });\n    if (!res.ok) throw new Error(`${transport.provider} ${res.status}`);\n    const body = (await res.json()) as { answers?: Record<string, { noul?: unknown }> } | null;\n    const answers = body?.answers;\n    if (!answers || typeof answers !== \"object\") throw new Error(\"no answers in response\");\n    const scores: Record<string, number> = {};\n    for (const [id, a] of Object.entries(answers)) {\n      if (typeof a?.noul === \"number\") scores[id] = a.noul;\n    }\n    if (Object.keys(scores).length === 0) throw new Error(\"no scores in response\");\n    return { scores, latencyMs: Date.now() - t0 };\n  } finally {\n    clearTimeout(timer);\n    outer?.removeEventListener(\"abort\", onOuterAbort);\n  }\n};\n\nconst SELFTEST = \"comms-gate-selftest\";\nconst SELFTEST_PREFS = {\n  tone: \"direct, plain, no hedging\",\n  language: \"English\",\n  verbosity:\n    \"very terse - answer in the first sentence, ~400 chars max. No preamble, no recap, no closing offer.\",\n};\nconst SELFTEST_BAD =\n  \"Great question! Let me walk you through what I did here. First I looked at the task, then I reviewed the relevant files, and after careful consideration I decided to go with option B. I hope this helps - let me know if you would like me to elaborate further on any of the above!\";\nconst SELFTEST_GOOD =\n  \"Went with option B: it is the only one that keeps the migration reversible. PR #123.\";\n// A real dense monitor post a requester had to ask to have rewritten, and that rewrite.\nconst SELFTEST_PLAIN_BAD =\n  \"Prompt cache monitor, day 7 verdict for v2.0.0: partial. Lead first-call read median 12.4k (baseline v1.173.0, n 410) → 19.1k tokens (n 2234; expected 25.0k-40.0k). First-call saving about $75/week on Lead vs v1.173.0 (expected $129; sampling noise ±$24 at 95%, one baseline version, day-to-day drift not measured); session $ change $-167/week; fleet first-call saving $-7/week.\";\nconst SELFTEST_PLAIN_GOOD =\n  \"Cheaper, but half what we hoped: Lead saves about $75 a week, not $129. Whole Lead tasks still cost $167 a week more, probably from other releases and heavier work, not this change.\";\n\nconst below = (bad: unknown, good: unknown, threshold: number): boolean =>\n  typeof bad === \"number\" && typeof good === \"number\" && bad < threshold && good >= threshold;\n\n/**\n * Run the judge on known-bad (positive control, must score below threshold) and\n * known-good (negative control, must score at or above it) messages and record\n * them under `selftest:last`: one pair for verbosity, one for `plain`. Proves key,\n * egress and KV from inside the API runtime without touching real traffic.\n */\nconst selfTest = async (swarm: Swarm, cfg: Cfg, signal?: AbortSignal): Promise<void> => {\n  const started = Date.now();\n  try {\n    const transport = resolveTransport(cfg);\n    const judge = (message: string, dim: \"verbosity\" | \"plain\") =>\n      askJev(\n        dim === \"plain\"\n          ? { plain_language_rules: PLAIN_RULES, agent_message: message }\n          : { requester_preferences: SELFTEST_PREFS, agent_message: message },\n        { [dim]: dim === \"plain\" ? PLAIN_QUESTION : buildQuestions(SELFTEST_PREFS).verbosity },\n        transport,\n        cfg,\n        signal,\n      ).then((r) => r.scores[dim] ?? null);\n    const [bad, good, plainBad, plainGood] = await Promise.all([\n      judge(SELFTEST_BAD, \"verbosity\"),\n      judge(SELFTEST_GOOD, \"verbosity\"),\n      judge(SELFTEST_PLAIN_BAD, \"plain\"),\n      judge(SELFTEST_PLAIN_GOOD, \"plain\"),\n    ]);\n    await swarm.kv_set({\n      namespace: NS,\n      key: \"selftest:last\",\n      value: {\n        at: new Date().toISOString(),\n        provider: transport.provider,\n        threshold: cfg.threshold,\n        positiveControlBadScore: bad,\n        negativeControlGoodScore: good,\n        controlsOk: below(bad, good, cfg.threshold),\n        plainThreshold: cfg.plainThreshold,\n        plainPositiveControlBadScore: plainBad,\n        plainNegativeControlGoodScore: plainGood,\n        plainControlsOk: below(plainBad, plainGood, cfg.plainThreshold),\n        latencyMs: Date.now() - started,\n      },\n    });\n  } catch (err) {\n    await swarm\n      .kv_set({\n        namespace: NS,\n        key: \"selftest:last\",\n        value: {\n          at: new Date().toISOString(),\n          error: String(err).slice(0, 400),\n          latencyMs: Date.now() - started,\n        },\n      })\n      .catch(() => {});\n  }\n};\n\nconst TASK_SQL = `SELECT t.source, t.slackThreadTs, t.agentId, t.requestedByUserId,\n       json_extract(u.metadata, '$.comms') AS comms, u.name,\n       substr(t.task, 1, 400) AS askHead,\n       substr(t.task, -1400) AS askTail,\n       t.creatorAgentId\nFROM agent_tasks t\nLEFT JOIN users u ON u.id = t.requestedByUserId\nWHERE t.id = ?`;\n\nconst LEAD_SQL = \"SELECT isLead FROM agents WHERE id = ?\";\n\n/** Slack user mentions in agent text: `<@U123>` or `<@U123|name>`. */\nconst MENTION_RE = /<@([UW][A-Z0-9]+)(?:\\|[^>]*)?>/g;\nconst MAX_MENTIONS = 5;\n\n/** Mentioned Slack user ids in order of first appearance, capped. */\nexport const mentionedSlackIds = (text: string): string[] => {\n  const ids: string[] = [];\n  for (const m of text.matchAll(MENTION_RE)) {\n    if (!ids.includes(m[1]!)) ids.push(m[1]!);\n    if (ids.length >= MAX_MENTIONS) break;\n  }\n  return ids;\n};\n\nconst addresseeSql = (n: number) => `SELECT x.externalId, u.id, u.name,\n       json_extract(u.metadata, '$.comms') AS comms\nFROM user_external_ids x\nJOIN users u ON u.id = x.userId\nWHERE x.kind = 'slack' AND x.externalId IN (${Array(n).fill(\"?\").join(\", \")})`;\n\nconst parsePrefs = (raw: unknown): Prefs | null => {\n  if (!raw) return null;\n  const parsed = typeof raw === \"string\" ? JSON.parse(raw) : raw;\n  return parsed && typeof parsed === \"object\" && Object.keys(parsed).length > 0\n    ? (parsed as Prefs)\n    : null;\n};\n\ntype Audience = { id: string; name: string; prefs: Prefs; via: \"mention\" | \"requester\" };\n\n/**\n * Whose preferences a message is judged against. In a thread with several\n * people, the message is for whoever it @-mentions: the first mentioned person\n * with stored preferences wins, including the requester only if they have prefs.\n * Without such a mention, the task requester (the\n * person whose message created this task). One SQL read, only when the text\n * mentions someone; no judge call.\n */\nconst resolveAudience = async (\n  swarm: Swarm,\n  text: string,\n  requester: Audience,\n): Promise<Audience> => {\n  const ids = mentionedSlackIds(text);\n  if (ids.length === 0) return requester;\n  const q = (await swarm.db_query({ sql: addresseeSql(ids.length), params: ids })) as Envelope;\n  const rows = q?.data?.rows ?? q?.rows ?? [];\n  for (const slackId of ids) {\n    const row = rows.find((r) => String(cell(r, 0, \"externalId\")) === slackId);\n    if (!row) continue;\n    const userId = String(cell(row, 1, \"id\") ?? \"\");\n    // A requester with stored preferences keeps their own task context.\n    if (userId && userId === requester.id) {\n      if (Object.keys(requester.prefs).length > 0) return requester;\n      continue;\n    }\n    const prefs = parsePrefs(cell(row, 3, \"comms\"));\n    if (!prefs) continue;\n    return { id: userId, name: String(cell(row, 2, \"name\") ?? userId), prefs, via: \"mention\" };\n  }\n  return requester;\n};\n\n/**\n * Mirrors the `task.progress.write` rule store-progress enforces\n * (src/rbac/legacy-policy.ts): the caller owns the task, the task is\n * unassigned, or the caller is a lead. Lead status comes from the caller's\n * agents row, never from tool args. Extension callers return before this.\n */\nconst mayWriteProgress = async (\n  swarm: Swarm,\n  callerId: string | undefined,\n  taskAgentId: string,\n): Promise<boolean> => {\n  if (!callerId) return false;\n  if (!taskAgentId || taskAgentId === callerId) return true;\n  const q = (await swarm.db_query({ sql: LEAD_SQL, params: [callerId] })) as Envelope;\n  const row = (q?.data?.rows ?? q?.rows ?? [])[0];\n  return Number(cell(row, 0, \"isLead\") ?? 0) === 1;\n};\n\n/** The text a gated call would put in front of a human, and the task it belongs to. */\nconst gatedText = (\n  tool: string,\n  args: Record<string, unknown>,\n  sourceTaskId: string | undefined,\n): { text: string; taskId: string } | null => {\n  if (tool === \"store-progress\") {\n    if (args.status !== \"completed\") return null;\n    return {\n      text: typeof args.output === \"string\" ? args.output.trim() : \"\",\n      taskId: String(args.taskId ?? sourceTaskId ?? \"\"),\n    };\n  }\n  if (SLACK_TOOLS.has(tool)) {\n    // slack-reply names its task; the other tools post from the caller's task context.\n    const named = tool === \"slack-reply\" ? args.taskId : undefined;\n    return {\n      text: typeof args.message === \"string\" ? args.message.trim() : \"\",\n      taskId: String(named ?? sourceTaskId ?? \"\"),\n    };\n  }\n  return null;\n};\n\nconst extension: SwarmExtension = (api) => {\n  api.on(\"pre.tool.call\", async (event, ctx) => {\n    if (event.tool !== \"store-progress\" && !SLACK_TOOLS.has(event.tool)) return;\n    const origin = event.requestInfo?.callOrigin;\n    if (origin === \"extension\") return;\n\n    const cfg = cfgOf(ctx.config);\n    if (cfg.mode === \"off\" && cfg.plainMode === \"off\") return;\n\n    const args = (event.args ?? {}) as Record<string, unknown>;\n\n    // Self-test hatch: a progress call whose text starts with the sentinel runs\n    // the controls and records them under `selftest:last`.\n    if (\n      event.tool === \"store-progress\" &&\n      args.status !== \"completed\" &&\n      typeof args.progress === \"string\" &&\n      args.progress.startsWith(SELFTEST)\n    ) {\n      await selfTest(ctx.swarm, cfg, ctx.signal);\n      return;\n    }\n\n    const gated = gatedText(event.tool, args, event.requestInfo?.sourceTaskId);\n    if (!gated?.text) return;\n    const { text, taskId } = gated;\n    if (!UUID_RE.test(taskId)) return;\n\n    try {\n      const q = (await ctx.swarm.db_query({ sql: TASK_SQL, params: [taskId] })) as Envelope;\n      const row = (q?.data?.rows ?? q?.rows ?? [])[0];\n      if (!row) return;\n\n      const source = String(cell(row, 0, \"source\") ?? \"\");\n      const slackThreadTs = cell(row, 1, \"slackThreadTs\");\n      const agentId = String(cell(row, 2, \"agentId\") ?? \"\");\n      const requesterId = String(cell(row, 3, \"requestedByUserId\") ?? \"\");\n      const commsRaw = cell(row, 4, \"comms\");\n      const requesterName = String(cell(row, 5, \"name\") ?? (requesterId || \"the requester\"));\n      const threadOpening = String(cell(row, 6, \"askHead\") ?? \"\");\n      const ask = latestAsk(String(cell(row, 7, \"askTail\") ?? \"\"));\n\n      // Judge only a call the tool itself will accept, so no agent can ship another\n      // task's thread and preferences to the external judge. store-progress follows\n      // its write rule; the Slack tools follow slack-reply's: the caller is the\n      // task's assignee or its creator.\n      const callerId = event.requestInfo?.agentId;\n      const creatorAgentId = String(cell(row, 8, \"creatorAgentId\") ?? \"\");\n      const allowed =\n        event.tool === \"store-progress\"\n          ? await mayWriteProgress(ctx.swarm, callerId, agentId)\n          : Boolean(callerId) && (callerId === agentId || callerId === creatorAgentId);\n      if (!allowed) return;\n\n      // A completion reaches a human only on a Slack task; a Slack tool always does.\n      if (event.tool === \"store-progress\" && source !== \"slack\" && !slackThreadTs) return;\n\n      const requester: Audience = {\n        id: requesterId,\n        name: requesterName,\n        prefs: parsePrefs(commsRaw) ?? {},\n        via: \"requester\",\n      };\n      // `plain` alone judges no one's preferences, so it skips the lookup.\n      const audience =\n        cfg.mode === \"off\" ? requester : await resolveAudience(ctx.swarm, text, requester);\n      const { prefs, name: audienceName } = audience;\n\n      const questions: Record<string, unknown> = cfg.mode === \"off\" ? {} : buildQuestions(prefs);\n      // Only a store-progress outputSchema answer is machine JSON; a Slack post is\n      // always read by a human, JSON or not.\n      if (cfg.plainMode !== \"off\" && (event.tool !== \"store-progress\" || !looksLikeJson(text)))\n        questions.plain = PLAIN_QUESTION;\n      if (Object.keys(questions).length === 0) return;\n\n      const transport = resolveTransport(cfg);\n      const { scores, latencyMs } = await askJev(\n        {\n          role: \"You audit an AI agent's message to the human who requested the work.\",\n          requester: audienceName,\n          requester_preferences: prefs,\n          latest_request: ask,\n          thread_opening: threadOpening,\n          judging_rules: JUDGING_RULES,\n          plain_language_rules: PLAIN_RULES,\n          agent_message: text,\n        },\n        questions,\n        transport,\n        cfg,\n        ctx.signal,\n      );\n\n      const limitOf = (dim: string) => (dim === \"plain\" ? cfg.plainThreshold : cfg.threshold);\n      const failed = Object.entries(scores)\n        .filter(([k, v]) => v < limitOf(k))\n        .map(([k]) => k);\n      // Script SDK calls never reach pre.tool.call today; if one does, record it only.\n      const blocking =\n        origin === \"script-sdk\"\n          ? []\n          : failed.filter((d) => (d === \"plain\" ? cfg.plainMode : cfg.mode) === \"enforce\");\n\n      const verdict = {\n        at: new Date().toISOString(),\n        tool: event.tool,\n        taskId,\n        agentId,\n        source,\n        requester: requesterName,\n        requesterId,\n        judgedFor: audience.via,\n        audienceId: audience.id,\n        audience: audienceName,\n        provider: transport.provider,\n        scores,\n        failed,\n        threshold: cfg.threshold,\n        plainThreshold: cfg.plainThreshold,\n        mode: cfg.mode,\n        plainMode: cfg.plainMode,\n        latencyMs,\n        preferences: prefs,\n        askPreview: ask.slice(0, 400),\n        outputPreview: text.slice(0, 700),\n      };\n\n      await ctx.swarm.kv_incr({ namespace: NS, key: \"total\" });\n      await ctx.swarm.kv_set({ namespace: NS, key: \"last\", value: verdict });\n\n      if (failed.length === 0) {\n        await ctx.swarm.kv_incr({ namespace: NS, key: \"pass\" });\n        return;\n      }\n\n      await ctx.swarm.kv_incr({ namespace: NS, key: \"fail\" });\n      for (const dim of failed) {\n        await ctx.swarm.kv_incr({ namespace: NS, key: `dim:${safeKey(dim)}` });\n      }\n\n      const blocksKey = `blocks:${safeKey(taskId)}`;\n      // kv_get answers {success, data:{value}}, and {success:false} when absent.\n      const prior = (await ctx.swarm.kv_get({ namespace: NS, key: blocksKey })) as Envelope;\n      const priorBlocks = Number(prior?.data?.value ?? prior?.value ?? 0) || 0;\n      const willBlock = blocking.length > 0 && priorBlocks < cfg.maxBlocksPerTask;\n\n      await ctx.swarm.kv_set({\n        namespace: NS,\n        key: `fail:${Date.now()}:${safeKey(taskId)}`,\n        value: { ...verdict, action: willBlock ? \"blocked\" : \"recorded\" },\n      });\n\n      if (!willBlock) {\n        await ctx.swarm.kv_incr({\n          namespace: NS,\n          key: blocking.length > 0 ? \"escaped\" : \"shadowed\",\n        });\n        return;\n      }\n\n      await ctx.swarm.kv_incr({ namespace: NS, key: \"blocked\" });\n      await ctx.swarm.kv_incr({ namespace: NS, key: blocksKey });\n\n      const lines = [\n        blocking.includes(\"plain\")\n          ? `Comms gate: this message is not in plain words for ${audienceName}.`\n          : `Comms gate: this output does not match ${audienceName}'s stated preferences.`,\n      ];\n      for (const d of blocking) {\n        const score = `${d} (${scores[d]!.toFixed(2)} vs ${limitOf(d)})`;\n        lines.push(\n          d === \"plain\"\n            ? `${score}: a reader outside the swarm cannot follow it on first read.`\n            : `${score}: requested ${String(prefs[d] ?? \"\").slice(0, 220)}`,\n        );\n      }\n      lines.push(\n        blocking.includes(\"plain\")\n          ? `Rewrite the message with the \\`comms\\` skill (Simpler mode): common words, one idea per sentence, every number with a unit and a direction word, shorthand explained or replaced. Keep every number, name, link and hedge verbatim, then call ${event.tool} again.`\n          : `Rewrite the message to match and call ${event.tool} again. Do not change the facts, only how they are said.`,\n      );\n      return block(lines.join(\"\\n\"));\n    } catch (err) {\n      // Fail open, always.\n      try {\n        await ctx.swarm.kv_incr({ namespace: NS, key: \"error\" });\n        await ctx.swarm.kv_set({\n          namespace: NS,\n          key: \"error:last\",\n          value: {\n            at: new Date().toISOString(),\n            tool: event.tool,\n            taskId,\n            error: String(err).slice(0, 400),\n          },\n        });\n      } catch {\n        /* ignore */\n      }\n      ctx.log.warn(\"comms-adherence-gate: failing open\", { error: String(err) });\n      return;\n    }\n  });\n};\n\nexport default extension;\n"
     },
-    "readme": "# comms-adherence-gate\n\nAgents finish Slack tasks with a final message a human reads. This extension judges that message against the requester's stated comms preferences and their latest request with Jev, [TypeSafe](https://typesafe.ai)'s decision model. In `enforce` it blocks a non-adherent completion once and tells the agent what to fix.\n\nInstall config:\n\n```json\n{ \"mode\": \"shadow\" }\n```\n\nStart in `shadow`, read the verdicts in KV for a few days, then switch to `enforce`.\n\n## Modes\n\n| `mode` | Effect |\n|---|---|\n| `off` | Never evaluates. |\n| `shadow` (default) | Asks Jev and records the verdict. Never blocks. |\n| `enforce` | Asks Jev, records the verdict, and blocks the `store-progress` call when a dimension fails, at most `maxBlocksPerTask` times per task. The agent gets the failed dimensions, their scores and the stated preference, and calls again. |\n\n## What it gates\n\nHook: `pre.tool.call` on `store-progress` with `status: \"completed\"` and a non-empty `output`. Calls made by extensions are skipped. The task must:\n\n1. Come from Slack (`source = \"slack\"` or a `slackThreadTs`). Other tasks pass without a Jev call.\n2. Have a requester with stated preferences in `users.metadata.comms`. A requester with none passes. Set them with the `manage-user` tool.\n\n## Decision\n\nThe gate reads the task row and asks one `noul` question per stated preference it knows: `verbosity`, `tone`, `language`. Any other key in `comms` is context only.\n\nJev sees the preferences, the requester's latest message (the text after the last `</thread_context>`, from the last 1,400 characters of the task), the first 400 characters of the task, and the output. Its judging rules say an explicit request outranks the stored default. A requested long answer, story or document is not a verbosity failure.\n\nA dimension fails when its score is below `threshold`. Any failed dimension fails the output.\n\n## Jev transport\n\nJev is reachable two ways. Both take the same request and return the same answer.\n\n| `provider` | Endpoint | Key | Model |\n|---|---|---|---|\n| `typesafe` | `POST https://api.typesafe.ai/v1/systemone` | `TYPESAFE_API_KEY` (or `apiKey`) | `model`, default `jev-latest` |\n| `openrouter` | `POST https://openrouter.ai/api/alpha/decisions` | `OPENROUTER_API_KEY` | `openrouterModel`, default `typesafe/jev-1.13` |\n| `auto` (default) | TypeSafe when its key is set, else OpenRouter | | |\n\nEach verdict row records the `provider` that answered.\n\n## Fail open\n\nEvery error lets the completion through: a missing key, an HTTP error, a network error, a timeout, a malformed answer, or a failed DB read. The handler never throws, so an outage cannot auto-disable the extension. Each failure bumps the `error` counter and overwrites `error:last`.\n\n## Self-test\n\nCall `store-progress` with a non-completed status and `progress` starting with `comms-gate-selftest`. The gate judges a known-bad and a known-good message against a terse preference and writes `selftest:last`: both scores, the threshold, the provider, and `controlsOk` (bad below threshold and good at or above it). Real traffic is untouched.\n\n## Config\n\n| Key | Default | Notes |\n|---|---|---|\n| `mode` | `shadow` | `off`, `shadow`, or `enforce` |\n| `threshold` | `0.5` | A dimension scoring below this fails |\n| `timeoutMs` | `4000` | Jev call timeout, capped at 4000 (the dispatcher cancels a handler at 5 s) |\n| `maxBlocksPerTask` | `1` | Blocks per task in `enforce`; after that the gate records and lets it through |\n| `provider` | `auto` | `auto`, `typesafe`, or `openrouter`. See [Jev transport](#jev-transport) |\n| `model` | `jev-latest` | Jev model on TypeSafe |\n| `openrouterModel` | `typesafe/jev-1.13` | Jev model on OpenRouter |\n| `apiKey` | unset | Explicit TypeSafe key. Prefer the `TYPESAFE_API_KEY` secret below |\n\n## Required secrets\n\nRead from the API process environment at call time. Set them as global `swarm_config` secrets: the API process loads global rows into `process.env` at boot and on config reload.\n\n- `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY`: one is required for any evaluation. Under `auto`, TypeSafe wins when both are set. Without either, every completion fails open.\n\nNo key is written to config, KV, logs, or a block reason.\n\n## KV namespace `ext:comms-gate`\n\n- `last`: the latest verdict, with `scores`, `failed`, `provider`, `latencyMs`, the preferences, a 400-character `askPreview` and a 700-character `outputPreview`.\n- `fail:<epochMs>:<taskId>`: one row per failed verdict, with `action` (`blocked` or `recorded`).\n- `blocks:<taskId>`: blocks issued for that task.\n- `error:last`, `selftest:last`.\n- Counters: `total`, `pass`, `fail`, `blocked`, `escaped` (enforce, block budget spent), `shadowed`, `error`, and `dim:<dimension>`.\n\n## Known limits\n\n- Only the last 1,400 characters of the task are searched for the latest request. A very long final message is cut to its last 900 characters.\n- The block budget is per task, so a retried completion after a block goes through once the budget is spent, even if it still fails.\n"
+    "readme": "# comms-adherence-gate\n\nAgents finish Slack tasks with a final message a human reads, and post to Slack threads directly. This extension judges that text with Jev, [TypeSafe](https://typesafe.ai)'s decision model: against the requester's stated comms preferences and their latest request, and against a plain-language rubric that applies to every message. In `enforce` it blocks a failing call once and tells the agent what to fix. A `plain` failure points the agent at the `comms` skill.\n\nInstall config:\n\n```json\n{ \"mode\": \"shadow\", \"plainMode\": \"shadow\" }\n```\n\nStart in `shadow`, read the verdicts in KV for a few days, then switch to `enforce`. `mode` and `plainMode` move independently.\n\n## Modes\n\n| `mode` | Effect |\n|---|---|\n| `off` | Never evaluates. |\n| `shadow` (default) | Asks Jev and records the verdict. Never blocks. |\n| `enforce` | Asks Jev, records the verdict, and blocks the call when a dimension fails, at most `maxBlocksPerTask` times per task. The agent gets the failed dimensions, their scores and the stated preference, and calls again. |\n\n`mode` governs the preference dimensions (`verbosity`, `tone`, `language`). `plainMode` governs `plain`. A dimension blocks only when its own mode is `enforce`. Both share one block budget per task, across every gated tool.\n\n## What it gates\n\nHook: `pre.tool.call` on:\n\n- `store-progress` with `status: \"completed\"` and a non-empty `output`, on a task that came from Slack (`source = \"slack\"` or a `slackThreadTs`). Other completions pass without a Jev call.\n- `slack-reply`, `slack-post`, `slack-start-thread` and `slack-update`, judged on `message`. The task is `slack-reply`'s `taskId`, else the caller's task context. A post with no task context passes.\n\nOnly a call the tool itself accepts is judged, so no other task's text reaches Jev. For `store-progress` the caller must own the task, the task must be unassigned, or the caller must be a lead. For the Slack tools the caller must be the task's assignee or its creator, the rule `slack-reply` enforces. Calls made by extensions are skipped. Script SDK calls never reach `pre.tool.call` (the tool registrar dispatches it only for MCP calls); if one ever does, the gate records it and never blocks.\n\nA requester with no stated preferences in `users.metadata.comms` still gets the `plain` question. Set preferences with the `manage-user` tool.\n\nIn a thread with several people, the requester is the person whose message created the task. A message that @-mentions someone (`<@U123>`) is judged against the first mentioned person with stored preferences, resolved through their Slack identity in `user_external_ids`; otherwise against the requester. The lookup is one SQL read, only when the text mentions someone and `mode` is not `off`. The verdict records who was judged in `judgedFor` (`mention` or `requester`) and `audience`.\n\n## Decision\n\nThe gate reads the task row and asks one `noul` question per stated preference it knows: `verbosity`, `tone`, `language`. Any other key in `comms` is context only.\n\nJev sees the preferences, the requester's latest message (the text after the last `</thread_context>`, from the last 1,400 characters of the task), the first 400 characters of the task, and the output. Its judging rules say an explicit request outranks the stored default. A requested long answer, story or document is not a verbosity failure.\n\nIt also asks `plain` on every message unless `plainMode` is `off` or the text is a JSON document (structured output for an `outputSchema`). The rubric comes from the `comms` skill: everyday words, one idea per sentence, every number with a unit and a direction word, and no unexplained shorthand (n, median, p90, cohort, baseline, delta, `±X at 95%`). Code identifiers, task ids, PR numbers, links and versions are fine. Jev gets contrasting plain and dense examples in `plain_language_rules`; a prose-only rubric scored plain rewrites as low as the dense originals.\n\nAll questions go in one Jev request. A preference dimension fails below `threshold`; `plain` fails below `plainThreshold`. Any failed dimension fails the message.\n\n### Calibration of `plain`\n\nJev scores dense status text near 0 and plain text near 0.8 to 0.9, with a wide middle of compact but readable engineering notes. Measured on 400 Slack-facing completions over 7 days, at `threshold` 0.75 for preferences:\n\n| `plainThreshold` | Newly blocked (of messages that pass today) |\n|---|---|\n| 0.75 | 81% to 83% |\n| 0.3 | 9% to 13% |\n| 0.25 (default) | 5% to 7% |\n\nAt 0.25 the dense prompt-cache-monitor post scores about 0.15 and its plain rewrite about 0.81.\n\n## Jev transport\n\nJev is reachable two ways. Both take the same request and return the same answer.\n\n| `provider` | Endpoint | Key | Model |\n|---|---|---|---|\n| `typesafe` | `POST https://api.typesafe.ai/v1/systemone` | `TYPESAFE_API_KEY` (or `apiKey`) | `model`, default `jev-latest` |\n| `openrouter` | `POST https://openrouter.ai/api/alpha/decisions` | `OPENROUTER_API_KEY` | `openrouterModel`, default `typesafe/jev-1.13` |\n| `auto` (default) | TypeSafe when its key is set, else OpenRouter | | |\n\nEach verdict row records the `provider` that answered.\n\n## Fail open\n\nEvery error lets the completion through: a missing key, an HTTP error, a network error, a timeout, a malformed answer, or a failed DB read. The handler never throws, so an outage cannot auto-disable the extension. Each failure bumps the `error` counter and overwrites `error:last`.\n\n## Self-test\n\nCall `store-progress` with a non-completed status and `progress` starting with `comms-gate-selftest`. The gate judges a known-bad and a known-good message against a terse preference, and a dense and a plain message on `plain`, then writes `selftest:last`: every score, both thresholds, the provider, `controlsOk` (verbosity: bad below `threshold`, good at or above it) and `plainControlsOk` (the same against `plainThreshold`). Real traffic is untouched.\n\n## Config\n\n| Key | Default | Notes |\n|---|---|---|\n| `mode` | `shadow` | `off`, `shadow`, or `enforce` |\n| `threshold` | `0.5` | A preference dimension scoring below this fails |\n| `plainMode` | `shadow` | `off`, `shadow`, or `enforce` for the `plain` dimension |\n| `plainThreshold` | `0.25` | `plain` scoring below this fails. See [Calibration](#calibration-of-plain) |\n| `timeoutMs` | `4000` | Jev call timeout, capped at 4000 (the dispatcher cancels a handler at 5 s) |\n| `maxBlocksPerTask` | `1` | Blocks per task in `enforce`; after that the gate records and lets it through |\n| `provider` | `auto` | `auto`, `typesafe`, or `openrouter`. See [Jev transport](#jev-transport) |\n| `model` | `jev-latest` | Jev model on TypeSafe |\n| `openrouterModel` | `typesafe/jev-1.13` | Jev model on OpenRouter |\n| `apiKey` | unset | Explicit TypeSafe key. Prefer the `TYPESAFE_API_KEY` secret below |\n\n## Required secrets\n\nRead from the API process environment at call time. Set them as global `swarm_config` secrets: the API process loads global rows into `process.env` at boot and on config reload.\n\n- `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY`: one is required for any evaluation. Under `auto`, TypeSafe wins when both are set. Without either, every completion fails open.\n\nNo key is written to config, KV, logs, or a block reason.\n\n## KV namespace `ext:comms-gate`\n\n- `last`: the latest verdict, with `tool`, `scores`, `failed`, `mode`, `plainMode`, `provider`, `latencyMs`, the preferences, a 400-character `askPreview` and a 700-character `outputPreview`.\n- `fail:<epochMs>:<taskId>`: one row per failed verdict, with `action` (`blocked` or `recorded`).\n- `blocks:<taskId>`: blocks issued for that task.\n- `error:last`, `selftest:last`.\n- Counters: `total`, `pass`, `fail`, `blocked`, `escaped` (a blocking dimension failed, block budget spent), `shadowed` (only non-blocking dimensions failed), `error`, and `dim:<dimension>`.\n\n## Known limits\n\n- Only the last 1,400 characters of the task are searched for the latest request. A very long final message is cut to its last 900 characters.\n- The block budget is per task, so a retried call after a block goes through once the budget is spent, even if it still fails.\n- Each gated Slack post waits for one Jev call (about 0.2 s measured, capped by `timeoutMs`).\n"
   },
   "deploy-awareness": {
     "manifestFile": "manifest.json",

package/src/extensions/contract-types.generated.ts

@@ -1,4 +1,4 @@
 // Generated by scripts/bundle-extension-types.ts. Do not edit.
 // biome-ignore-all lint/suspicious/noTemplateCurlyInString: Type declarations contain literal template placeholders.
 export const EXTENSION_TYPE_DEFINITIONS =
-  '// biome-ignore-all lint/suspicious/noConfusingVoidType: Extension handlers may explicitly return no result.\ndeclare module "swarm-extension" {\n  export type CreateTaskOptions = {\n    key?: string | undefined;\n    agentId?: string | null | undefined;\n    creatorAgentId?: string | undefined;\n    source?:\n      | "workflow"\n      | "schedule"\n      | "slack"\n      | "agentmail"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "github"\n      | "gitlab"\n      | "azure-devops"\n      | "bitbucket"\n      | "system"\n      | "linear"\n      | "jira"\n      | "comb"\n      | "chat"\n      | undefined;\n    routingReason?:\n      | "skill"\n      | "continuity"\n      | "overflow"\n      | "human_pinned"\n      | "reroute_fault"\n      | undefined;\n    routingSource?: "declared" | "engine_default" | undefined;\n    routingNote?: string | undefined;\n    taskType?: string | undefined;\n    tags?: string[] | undefined;\n    priority?: number | undefined;\n    dependsOn?: string[] | undefined;\n    offeredTo?: string | undefined;\n    status?: "draft" | "backlog" | "unassigned" | undefined;\n    slackChannelId?: string | undefined;\n    slackThreadTs?: string | undefined;\n    slackTriggerMessageTs?: string | undefined;\n    slackUserId?: string | undefined;\n    overrideSlackContext?: boolean | undefined;\n    vcsProvider?: "github" | "gitlab" | "azure-devops" | "bitbucket" | undefined;\n    vcsRepo?: string | undefined;\n    vcsEventType?: string | undefined;\n    vcsNumber?: number | undefined;\n    vcsCommentId?: number | undefined;\n    vcsAuthor?: string | undefined;\n    vcsUrl?: string | undefined;\n    vcsInstallationId?: number | undefined;\n    vcsNodeId?: string | undefined;\n    agentmailInboxId?: string | undefined;\n    agentmailMessageId?: string | undefined;\n    agentmailThreadId?: string | undefined;\n    mentionMessageId?: string | undefined;\n    mentionChannelId?: string | undefined;\n    dir?: string | undefined;\n    parentTaskId?: string | undefined;\n    model?: string | undefined;\n    modelTier?: "smol" | "regular" | "smart" | "ultra" | undefined;\n    effort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    profile?: string | undefined;\n    scheduleId?: string | undefined;\n    workflowRunId?: string | undefined;\n    workflowRunStepId?: string | undefined;\n    sourceTaskId?: string | undefined;\n    outputSchema?: Record<string, unknown> | undefined;\n    inheritParentOutputSchema?: boolean | undefined;\n    inheritParentRequester?: boolean | undefined;\n    inheritParentRoutingAffinity?: boolean | undefined;\n    inheritParentFollowUpConfig?: boolean | undefined;\n    followUpConfig?:\n      | {\n          disabled?: boolean | undefined;\n          onCompleted?: string | undefined;\n          onFailed?: string | undefined;\n        }\n      | undefined;\n    requestedByUserId?: string | undefined;\n    contextKey?: string | undefined;\n    bypassTrackerContextDedup?: boolean | undefined;\n    routingAffinity?:\n      | {\n          capabilities: string[];\n          sourceAgentId?: string | undefined;\n          role?: string | undefined;\n          harnessProvider?:\n            | "claude"\n            | "codex"\n            | "pi"\n            | "devin"\n            | "claude-managed"\n            | "opencode"\n            | "acp"\n            | "dsh"\n            | "amp"\n            | "cursor"\n            | "grok"\n            | undefined;\n          leadOnly?: boolean | undefined;\n        }\n      | undefined;\n  };\n\n  export type AgentTask = {\n    id: string;\n    key: string;\n    agentId: string | null;\n    task: string;\n    status:\n      | "draft"\n      | "backlog"\n      | "unassigned"\n      | "offered"\n      | "reviewing"\n      | "pending"\n      | "in_progress"\n      | "paused"\n      | "completed"\n      | "failed"\n      | "cancelled"\n      | "superseded";\n    source:\n      | "workflow"\n      | "schedule"\n      | "slack"\n      | "agentmail"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "github"\n      | "gitlab"\n      | "azure-devops"\n      | "bitbucket"\n      | "system"\n      | "linear"\n      | "jira"\n      | "comb"\n      | "chat";\n    tags: string[];\n    priority: number;\n    dependsOn: string[];\n    createdAt: string;\n    lastUpdatedAt: string;\n    slackReplySent: boolean;\n    wasPaused: boolean;\n    creatorAgentId?: string | undefined;\n    title?: string | undefined;\n    routingReason?:\n      | "skill"\n      | "continuity"\n      | "overflow"\n      | "human_pinned"\n      | "reroute_fault"\n      | undefined;\n    routingSource?: "declared" | "engine_default" | undefined;\n    routingNote?: string | undefined;\n    poolWakeAt?: string | undefined;\n    taskType?: string | undefined;\n    offeredTo?: string | undefined;\n    offeredAt?: string | undefined;\n    acceptedAt?: string | undefined;\n    rejectionReason?: string | undefined;\n    finishedAt?: string | undefined;\n    notifiedAt?: string | undefined;\n    failureReason?: string | undefined;\n    output?: string | undefined;\n    progress?: string | undefined;\n    slackChannelId?: string | undefined;\n    slackThreadTs?: string | undefined;\n    slackTriggerMessageTs?: string | undefined;\n    slackUserId?: string | undefined;\n    slackProgressMessageTs?: string | undefined;\n    slackTreeRootMessageTs?: string | undefined;\n    vcsProvider?: "github" | "gitlab" | "azure-devops" | "bitbucket" | undefined;\n    vcsRepo?: string | undefined;\n    vcsEventType?: string | undefined;\n    vcsNumber?: number | undefined;\n    vcsCommentId?: number | undefined;\n    vcsAuthor?: string | undefined;\n    vcsUrl?: string | undefined;\n    vcsInstallationId?: number | undefined;\n    vcsNodeId?: string | undefined;\n    agentmailInboxId?: string | undefined;\n    agentmailMessageId?: string | undefined;\n    agentmailThreadId?: string | undefined;\n    mentionMessageId?: string | undefined;\n    mentionChannelId?: string | undefined;\n    dir?: string | undefined;\n    parentTaskId?: string | undefined;\n    claudeSessionId?: string | undefined;\n    model?: string | undefined;\n    modelTier?: "smol" | "regular" | "smart" | "ultra" | undefined;\n    effort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    resolvedModel?: string | undefined;\n    modelSource?: string | undefined;\n    modelAlias?: string | undefined;\n    resolvedEffort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    profile?: string | undefined;\n    resolvedProfile?: string | undefined;\n    scheduleId?: string | undefined;\n    workflowRunId?: string | null | undefined;\n    workflowRunStepId?: string | null | undefined;\n    contextKey?: string | undefined;\n    outputSchema?: Record<string, unknown> | undefined;\n    followUpConfig?:\n      | {\n          disabled?: boolean | undefined;\n          onCompleted?: string | undefined;\n          onFailed?: string | undefined;\n        }\n      | undefined;\n    deferredAt?: string | undefined;\n    compactionCount?: number | undefined;\n    peakContextPercent?: number | undefined;\n    peakContextTokens?: number | undefined;\n    contextWindowSize?: number | undefined;\n    credentialKeySuffix?: string | undefined;\n    credentialKeyType?: string | undefined;\n    requestedByUserId?: string | undefined;\n    swarmVersion?: string | undefined;\n    provider?:\n      | "claude"\n      | "codex"\n      | "pi"\n      | "devin"\n      | "claude-managed"\n      | "opencode"\n      | "acp"\n      | "dsh"\n      | "amp"\n      | "cursor"\n      | "grok"\n      | undefined;\n    providerMeta?: Record<string, unknown> | undefined;\n    harnessVariant?: string | undefined;\n    harnessVariantMeta?: Record<string, unknown> | undefined;\n    totalCostUsd?: number | undefined;\n    routingAffinity?:\n      | {\n          capabilities: string[];\n          sourceAgentId?: string | undefined;\n          role?: string | undefined;\n          harnessProvider?:\n            | "claude"\n            | "codex"\n            | "pi"\n            | "devin"\n            | "claude-managed"\n            | "opencode"\n            | "acp"\n            | "dsh"\n            | "amp"\n            | "cursor"\n            | "grok"\n            | undefined;\n          leadOnly?: boolean | undefined;\n        }\n      | undefined;\n    routingAffinityInvalid?: boolean | undefined;\n  };\n\n  export type ActiveSession = {\n    id: string;\n    agentId: string;\n    taskId: string | null;\n    triggerType: string;\n    inboxMessageId: string | null;\n    taskDescription: string | null;\n    runnerSessionId: string | null;\n    providerSessionId: string | null;\n    startedAt: string;\n    lastHeartbeatAt: string;\n    runtimeInstanceId?: string | null | undefined;\n  };\n\n  export type RequestInfo = {\n    sessionId: string | undefined;\n    agentId: string | undefined;\n    runtimeInstanceId: string | undefined;\n    sourceTaskId: string | undefined;\n    contextKey: string | undefined;\n    callOrigin: "mcp" | "extension" | "script-sdk";\n  };\n\n  import type { SwarmSdk } from "swarm-sdk";\n  import type { z } from "zod";\n  export type Runtime = "api" | "worker";\n  export interface ExtensionScriptAsset {\n    name: string;\n    file: string;\n    description: string;\n    intent?: string;\n  }\n  export interface ExtensionScheduleAsset {\n    name: string;\n    description?: string;\n    script: string;\n    cronExpression?: string;\n    intervalMs?: number;\n    timezone?: string;\n    args?: Record<string, unknown>;\n  }\n  export interface ExtensionWorkflowAsset {\n    file: string;\n  }\n  export interface ExtensionSkillAsset {\n    dir: string;\n  }\n  export interface ExtensionManifest {\n    $schema?: string;\n    name: string;\n    description: string;\n    version: string;\n    runtime: Runtime;\n    assets: {\n      hooks: string;\n      scripts?: readonly ExtensionScriptAsset[];\n      schedules?: readonly ExtensionScheduleAsset[];\n      workflows?: readonly ExtensionWorkflowAsset[];\n      skills?: readonly ExtensionSkillAsset[];\n    };\n    homepage?: string;\n    author?: string;\n  }\n  export interface HooksModule {\n    default: SwarmExtension;\n    config?: z.ZodTypeAny;\n  }\n  export interface ExtensionState {\n    get<T = unknown>(key: string): Promise<T | null>;\n    set<T>(key: string, value: T): Promise<void>;\n    incr(key: string, by?: number): Promise<number>;\n    del(key: string): Promise<void>;\n  }\n  export interface ExtensionLogger {\n    debug(message: string, data?: unknown): void;\n    info(message: string, data?: unknown): void;\n    warn(message: string, data?: unknown): void;\n    error(message: string, data?: unknown): void;\n  }\n  type ConfigFor<M extends ExtensionManifest> = M extends {\n    config: infer C extends z.ZodTypeAny;\n  }\n    ? z.infer<C>\n    : Record<string, unknown>;\n  export interface ApiCtx<Config = Record<string, unknown>> {\n    swarm: SwarmSdk;\n    state: ExtensionState;\n    config: Config;\n    log: ExtensionLogger;\n    signal: AbortSignal;\n    event: {\n      name: keyof SwarmEventMap;\n      at: string;\n      extension: {\n        id: string;\n        version: number;\n      };\n    };\n  }\n  export interface WorkerCtx<Config = Record<string, unknown>>\n    extends Omit<ApiCtx<Config>, "swarm"> {\n    swarm: SwarmSdk;\n    worker: {\n      agentId: string;\n      taskId: string;\n      harness: string;\n    };\n  }\n  export type CtxFor<M extends ExtensionManifest> = M["runtime"] extends "api"\n    ? ApiCtx<ConfigFor<M>>\n    : WorkerCtx<ConfigFor<M>>;\n  export type PreResult<Modify> =\n    | void\n    | {\n        action: "continue";\n      }\n    | {\n        action: "modify";\n        data: Modify;\n      }\n    | {\n        action: "block";\n        reason: string;\n      };\n  export type TaskCreateOrigin =\n    | "rest"\n    | "app"\n    | "mcp"\n    | "slack"\n    | "schedule"\n    | "workflow"\n    | "webhook"\n    | "followUp"\n    | `extension:${string}`;\n  export interface TaskCreateEvent {\n    options: CreateTaskOptions;\n    description: string;\n    origin: TaskCreateOrigin;\n    requestInfo?: RequestInfo;\n  }\n  export type TaskCreateModify = Partial<\n    Pick<\n      CreateTaskOptions,\n      | "agentId"\n      | "creatorAgentId"\n      | "source"\n      | "taskType"\n      | "tags"\n      | "priority"\n      | "dependsOn"\n      | "offeredTo"\n      | "vcsProvider"\n      | "vcsRepo"\n      | "vcsEventType"\n      | "vcsNumber"\n      | "vcsCommentId"\n      | "vcsAuthor"\n      | "vcsUrl"\n      | "vcsInstallationId"\n      | "vcsNodeId"\n      | "agentmailInboxId"\n      | "agentmailMessageId"\n      | "agentmailThreadId"\n      | "mentionMessageId"\n      | "mentionChannelId"\n      | "dir"\n      | "model"\n      | "modelTier"\n      | "effort"\n      | "outputSchema"\n      | "followUpConfig"\n      | "bypassTrackerContextDedup"\n    >\n  > & {\n    description?: string;\n  };\n  export interface TaskFollowUpEvent {\n    completedTask: AgentTask;\n    status: "completed" | "failed";\n    output?: string;\n    failureReason?: string;\n    workerAgentId: string;\n    leadAgentId: string;\n    summary: string;\n  }\n  export type TaskFollowUpModify = Partial<\n    Pick<CreateTaskOptions, "agentId" | "priority" | "followUpConfig">\n  > & {\n    description?: string;\n  };\n  export interface SlackRouteEvent {\n    channelId: string;\n    userId: string;\n    text: string;\n    threadTs?: string;\n    botMentioned: boolean;\n    threadContext?: {\n      channelId: string;\n      threadTs: string;\n    };\n  }\n  export interface SlackRouteModify {\n    target:\n      | {\n          kind: "agent";\n          agentId: string;\n        }\n      | {\n          kind: "lead";\n        }\n      | {\n          kind: "broadcast";\n        };\n  }\n  /** A Chat SDK message after its thread buffer flushed, before routing. */\n  export interface ChatRouteEvent {\n    /** Adapter name, such as `telegram` or `slack`. */\n    adapter: string;\n    channelId: string;\n    /** The Chat SDK thread id, prefixed with the adapter name. */\n    threadId: string;\n    /** The first buffered sender. */\n    userId: string;\n    userName?: string;\n    /** The buffered messages, joined. */\n    text: string;\n    /** True for an @mention and for a reply to one of the bot\'s messages. */\n    botMentioned: boolean;\n    isDirectMessage: boolean;\n    /** Platform chat type, such as Telegram `private`, `group`, `supergroup` or `channel`. */\n    chatType?: string;\n    /** Set for a Telegram supergroup with topics. */\n    isForum?: boolean;\n    /** A buffered message replies to one of the bot\'s own messages. */\n    replyToBot: boolean;\n    /** Set when earlier swarm tasks exist in this thread. */\n    threadContext?: {\n      adapter: string;\n      threadId: string;\n    };\n  }\n  export interface ChatRouteModify {\n    target:\n      | {\n          kind: "agent";\n          agentId: string;\n        }\n      | {\n          kind: "lead";\n        }\n      | {\n          kind: "broadcast";\n        }\n      | {\n          kind: "workflow";\n          workflowId: string;\n        };\n  }\n  export type HeartbeatClassification = "no-session" | "stale-session" | "fresh-stalled";\n  export type HeartbeatAction = "supersede-resume" | "fail" | "record";\n  export interface HeartbeatRemediateEvent {\n    task: AgentTask;\n    session?: ActiveSession;\n    classification: HeartbeatClassification;\n    proposedAction: HeartbeatAction;\n    reason: string;\n    taskAgeMs: number;\n    sessionHeartbeatAgeMs?: number;\n  }\n  export interface HeartbeatRemediateModify {\n    proposedAction: HeartbeatAction;\n  }\n  export interface ToolCallEvent {\n    tool: string;\n    args: unknown;\n    requestInfo: RequestInfo;\n  }\n  export interface ToolCallModify {\n    args: unknown;\n  }\n  export interface TaskEvent {\n    task: AgentTask;\n  }\n  export interface TaskCompletedEvent extends TaskEvent {\n    output: string;\n  }\n  export interface TaskFailedEvent extends TaskEvent {\n    failureReason: string;\n  }\n  export interface TaskSupersededEvent extends TaskEvent {\n    supersededBy: string;\n  }\n  export interface TaskProgressEvent extends TaskEvent {\n    progress: string;\n  }\n  export interface SlackMessageEvent {\n    channelId: string;\n    userId: string;\n    text: string;\n    threadTs?: string;\n    taskId?: string;\n  }\n  /** A Chat SDK message the swarm received or sent. */\n  export interface ChatMessageEvent {\n    adapter: string;\n    channelId: string;\n    threadId: string;\n    /** The sender, for an inbound message. */\n    userId?: string;\n    text: string;\n    direction: "inbound" | "outbound";\n    taskId?: string;\n    messageId?: string;\n  }\n  /**\n   * A person answered an approval request. Fires for workflow and standalone\n   * requests. Timeouts and cancellations do not emit it today.\n   */\n  export interface ApprovalResolvedEvent {\n    requestId: string;\n    status: "approved" | "rejected" | "timeout" | "cancelled";\n    responses: Record<string, unknown> | null;\n    /** Set when a workflow human-in-the-loop step asked. Absent for a standalone request. */\n    workflowRunId?: string;\n    workflowRunStepId?: string;\n    /** The task whose agent asked, for a standalone request. */\n    sourceTaskId?: string;\n  }\n  /** A task was refused because a daily spend budget is used up. */\n  export interface TaskBudgetRefusedEvent extends TaskEvent {\n    /** The agent the task was refused for. */\n    agentId: string;\n    /** Which budget refused it. The matching spend and budget fields are set. */\n    cause: "agent" | "global" | "user";\n    agentSpendUsd?: number;\n    agentBudgetUsd?: number;\n    globalSpendUsd?: number;\n    globalBudgetUsd?: number;\n    userSpendUsd?: number;\n    userBudgetUsd?: number;\n    /** ISO 8601 time the daily budget resets. */\n    resetAt: string;\n  }\n  /** An inbound AgentMail message. */\n  export interface EmailReceivedEvent {\n    inboxId: string;\n    /** The From header as sent. */\n    from: string;\n    subject: string;\n    /** The text body, or the HTML when there is no text, cut to 500 characters with `...` appended. */\n    body: string;\n    threadId: string;\n    messageId: string;\n  }\n  /** An inbound Kapso (WhatsApp) message. */\n  export interface KapsoMessageEvent {\n    phoneNumberId: string;\n    conversationId?: string;\n    messageId: string;\n    from?: string;\n    /** Kapso message type, such as `text` or `image`. */\n    type?: string;\n    /** The text, or a placeholder naming the type for a non-text message. */\n    text: string;\n  }\n  export type VcsProvider = "github" | "gitlab" | "azure-devops" | "bitbucket";\n  /**\n   * The provider object the event is about, as the provider names it. GitLab\n   * calls a pull request a merge request, and a comment a `note`.\n   */\n  export type VcsEventKind =\n    | "pull_request"\n    | "merge_request"\n    | "issue"\n    | "issue_comment"\n    | "note"\n    | "pull_request_review"\n    | "pipeline";\n  /**\n   * A webhook event from a connected code host. `action` is the provider\'s own\n   * value: `opened`, `closed`, `synchronize`, `merge`, `created`, `commented`, or,\n   * for a pipeline, its status such as `success` or `failed`. Fields a kind does\n   * not carry are absent.\n   */\n  export interface VcsEvent {\n    provider: VcsProvider;\n    kind: VcsEventKind;\n    action: string;\n    /** `owner/name` on GitHub and GitLab, `workspace/repo_slug` on Bitbucket, the repository URL on Azure DevOps. */\n    repo: string;\n    /** The PR, merge request, or issue number. Absent for a pipeline outside a merge request. */\n    number?: number;\n    title?: string;\n    body?: string | null;\n    /** Login of the user behind the event. Set for pull requests, merge requests, and Azure DevOps comments. */\n    author?: string;\n    url?: string;\n    merged?: boolean;\n    changedFiles?: number;\n    /** The review verdict, on a pull request review. */\n    reviewState?: string;\n  }\n  export interface ToolCallCompletedEvent extends ToolCallEvent {\n    result: unknown;\n    durationMs: number;\n  }\n  export interface SwarmEventMap {\n    "pre.task.create": {\n      event: TaskCreateEvent;\n      modify: TaskCreateModify;\n      result: PreResult<TaskCreateModify>;\n    };\n    "pre.task.followUp": {\n      event: TaskFollowUpEvent;\n      modify: TaskFollowUpModify;\n      result: PreResult<TaskFollowUpModify>;\n    };\n    "pre.slack.route": {\n      event: SlackRouteEvent;\n      modify: SlackRouteModify;\n      result: PreResult<SlackRouteModify>;\n    };\n    "pre.chat.route": {\n      event: ChatRouteEvent;\n      modify: ChatRouteModify;\n      result: PreResult<ChatRouteModify>;\n    };\n    "pre.heartbeat.remediate": {\n      event: HeartbeatRemediateEvent;\n      modify: HeartbeatRemediateModify;\n      result: PreResult<HeartbeatRemediateModify>;\n    };\n    "pre.tool.call": {\n      event: ToolCallEvent;\n      modify: ToolCallModify;\n      result: PreResult<ToolCallModify>;\n    };\n    "post.task.created": {\n      event: TaskEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.completed": {\n      event: TaskCompletedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.failed": {\n      event: TaskFailedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.cancelled": {\n      event: TaskEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.superseded": {\n      event: TaskSupersededEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.progress": {\n      event: TaskProgressEvent;\n      modify: never;\n      result: void;\n    };\n    "post.slack.message": {\n      event: SlackMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.chat.message": {\n      event: ChatMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.approval.resolved": {\n      event: ApprovalResolvedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.budgetRefused": {\n      event: TaskBudgetRefusedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.email.received": {\n      event: EmailReceivedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.kapso.message": {\n      event: KapsoMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.vcs.event": {\n      event: VcsEvent;\n      modify: never;\n      result: void;\n    };\n    "post.tool.call": {\n      event: ToolCallCompletedEvent;\n      modify: never;\n      result: void;\n    };\n  }\n  export interface ExtensionApi<\n    M extends ExtensionManifest = ExtensionManifest & {\n      runtime: "api";\n    },\n  > {\n    on<E extends keyof SwarmEventMap>(\n      event: E,\n      handler: (\n        event: SwarmEventMap[E]["event"],\n        ctx: CtxFor<M>,\n      ) => Promise<SwarmEventMap[E]["result"]> | SwarmEventMap[E]["result"],\n      opts?: {\n        priority?: number;\n      },\n    ): void;\n  }\n  export type SwarmExtension<\n    M extends ExtensionManifest = ExtensionManifest & {\n      runtime: "api";\n    },\n  > = (api: ExtensionApi<M>) => void;\n  export { block, modify } from "./contract-runtime";\n}\n';
+  '// biome-ignore-all lint/suspicious/noConfusingVoidType: Extension handlers may explicitly return no result.\ndeclare module "swarm-extension" {\n  export type CreateTaskOptions = {\n    key?: string | undefined;\n    agentId?: string | null | undefined;\n    creatorAgentId?: string | undefined;\n    source?:\n      | "workflow"\n      | "schedule"\n      | "slack"\n      | "agentmail"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "github"\n      | "gitlab"\n      | "azure-devops"\n      | "bitbucket"\n      | "system"\n      | "linear"\n      | "jira"\n      | "comb"\n      | "chat"\n      | undefined;\n    routingReason?:\n      | "skill"\n      | "continuity"\n      | "overflow"\n      | "human_pinned"\n      | "reroute_fault"\n      | undefined;\n    routingSource?: "declared" | "engine_default" | undefined;\n    routingNote?: string | undefined;\n    taskType?: string | undefined;\n    tags?: string[] | undefined;\n    priority?: number | undefined;\n    dependsOn?: string[] | undefined;\n    offeredTo?: string | undefined;\n    status?: "draft" | "backlog" | "unassigned" | undefined;\n    slackChannelId?: string | undefined;\n    slackThreadTs?: string | undefined;\n    slackTriggerMessageTs?: string | undefined;\n    slackUserId?: string | undefined;\n    overrideSlackContext?: boolean | undefined;\n    vcsProvider?: "github" | "gitlab" | "azure-devops" | "bitbucket" | undefined;\n    vcsRepo?: string | undefined;\n    vcsEventType?: string | undefined;\n    vcsNumber?: number | undefined;\n    vcsCommentId?: number | undefined;\n    vcsAuthor?: string | undefined;\n    vcsUrl?: string | undefined;\n    vcsInstallationId?: number | undefined;\n    vcsNodeId?: string | undefined;\n    agentmailInboxId?: string | undefined;\n    agentmailMessageId?: string | undefined;\n    agentmailThreadId?: string | undefined;\n    mentionMessageId?: string | undefined;\n    mentionChannelId?: string | undefined;\n    dir?: string | undefined;\n    parentTaskId?: string | undefined;\n    model?: string | undefined;\n    modelTier?: "smol" | "regular" | "smart" | "ultra" | undefined;\n    effort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    profile?: string | undefined;\n    scheduleId?: string | undefined;\n    workflowRunId?: string | undefined;\n    workflowRunStepId?: string | undefined;\n    sourceTaskId?: string | undefined;\n    outputSchema?: Record<string, unknown> | undefined;\n    inheritParentOutputSchema?: boolean | undefined;\n    inheritParentRequester?: boolean | undefined;\n    inheritParentRoutingAffinity?: boolean | undefined;\n    inheritParentFollowUpConfig?: boolean | undefined;\n    followUpConfig?:\n      | {\n          disabled?: boolean | undefined;\n          onCompleted?: string | undefined;\n          onFailed?: string | undefined;\n        }\n      | undefined;\n    requestedByUserId?: string | undefined;\n    contextKey?: string | undefined;\n    bypassTrackerContextDedup?: boolean | undefined;\n    routingAffinity?:\n      | {\n          capabilities: string[];\n          sourceAgentId?: string | undefined;\n          role?: string | undefined;\n          harnessProvider?:\n            | "claude"\n            | "codex"\n            | "pi"\n            | "devin"\n            | "claude-managed"\n            | "opencode"\n            | "acp"\n            | "dsh"\n            | "amp"\n            | "cursor"\n            | "grok"\n            | undefined;\n          leadOnly?: boolean | undefined;\n        }\n      | undefined;\n  };\n\n  export type AgentTask = {\n    id: string;\n    key: string;\n    agentId: string | null;\n    task: string;\n    status:\n      | "draft"\n      | "backlog"\n      | "unassigned"\n      | "offered"\n      | "reviewing"\n      | "pending"\n      | "in_progress"\n      | "paused"\n      | "completed"\n      | "failed"\n      | "cancelled"\n      | "superseded";\n    source:\n      | "workflow"\n      | "schedule"\n      | "slack"\n      | "agentmail"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "github"\n      | "gitlab"\n      | "azure-devops"\n      | "bitbucket"\n      | "system"\n      | "linear"\n      | "jira"\n      | "comb"\n      | "chat";\n    tags: string[];\n    priority: number;\n    dependsOn: string[];\n    createdAt: string;\n    lastUpdatedAt: string;\n    slackReplySent: boolean;\n    wasPaused: boolean;\n    creatorAgentId?: string | undefined;\n    title?: string | undefined;\n    routingReason?:\n      | "skill"\n      | "continuity"\n      | "overflow"\n      | "human_pinned"\n      | "reroute_fault"\n      | undefined;\n    routingSource?: "declared" | "engine_default" | undefined;\n    routingNote?: string | undefined;\n    poolWakeAt?: string | undefined;\n    taskType?: string | undefined;\n    offeredTo?: string | undefined;\n    offeredAt?: string | undefined;\n    acceptedAt?: string | undefined;\n    rejectionReason?: string | undefined;\n    finishedAt?: string | undefined;\n    notifiedAt?: string | undefined;\n    failureReason?: string | undefined;\n    output?: string | undefined;\n    progress?: string | undefined;\n    slackChannelId?: string | undefined;\n    slackThreadTs?: string | undefined;\n    slackTriggerMessageTs?: string | undefined;\n    slackUserId?: string | undefined;\n    slackProgressMessageTs?: string | undefined;\n    slackTreeRootMessageTs?: string | undefined;\n    vcsProvider?: "github" | "gitlab" | "azure-devops" | "bitbucket" | undefined;\n    vcsRepo?: string | undefined;\n    vcsEventType?: string | undefined;\n    vcsNumber?: number | undefined;\n    vcsCommentId?: number | undefined;\n    vcsAuthor?: string | undefined;\n    vcsUrl?: string | undefined;\n    vcsInstallationId?: number | undefined;\n    vcsNodeId?: string | undefined;\n    agentmailInboxId?: string | undefined;\n    agentmailMessageId?: string | undefined;\n    agentmailThreadId?: string | undefined;\n    mentionMessageId?: string | undefined;\n    mentionChannelId?: string | undefined;\n    dir?: string | undefined;\n    parentTaskId?: string | undefined;\n    claudeSessionId?: string | undefined;\n    model?: string | undefined;\n    modelTier?: "smol" | "regular" | "smart" | "ultra" | undefined;\n    effort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    resolvedModel?: string | undefined;\n    modelSource?: string | undefined;\n    modelAlias?: string | undefined;\n    resolvedEffort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    profile?: string | undefined;\n    resolvedProfile?: string | undefined;\n    scheduleId?: string | undefined;\n    workflowRunId?: string | null | undefined;\n    workflowRunStepId?: string | null | undefined;\n    contextKey?: string | undefined;\n    outputSchema?: Record<string, unknown> | undefined;\n    followUpConfig?:\n      | {\n          disabled?: boolean | undefined;\n          onCompleted?: string | undefined;\n          onFailed?: string | undefined;\n        }\n      | undefined;\n    deferredAt?: string | undefined;\n    compactionCount?: number | undefined;\n    peakContextPercent?: number | undefined;\n    peakContextTokens?: number | undefined;\n    contextWindowSize?: number | undefined;\n    credentialKeySuffix?: string | undefined;\n    credentialKeyType?: string | undefined;\n    requestedByUserId?: string | undefined;\n    swarmVersion?: string | undefined;\n    provider?:\n      | "claude"\n      | "codex"\n      | "pi"\n      | "devin"\n      | "claude-managed"\n      | "opencode"\n      | "acp"\n      | "dsh"\n      | "amp"\n      | "cursor"\n      | "grok"\n      | undefined;\n    providerMeta?: Record<string, unknown> | undefined;\n    harnessVariant?: string | undefined;\n    harnessVariantMeta?: Record<string, unknown> | undefined;\n    totalCostUsd?: number | undefined;\n    routingAffinity?:\n      | {\n          capabilities: string[];\n          sourceAgentId?: string | undefined;\n          role?: string | undefined;\n          harnessProvider?:\n            | "claude"\n            | "codex"\n            | "pi"\n            | "devin"\n            | "claude-managed"\n            | "opencode"\n            | "acp"\n            | "dsh"\n            | "amp"\n            | "cursor"\n            | "grok"\n            | undefined;\n          leadOnly?: boolean | undefined;\n        }\n      | undefined;\n    routingAffinityInvalid?: boolean | undefined;\n  };\n\n  export type ActiveSession = {\n    id: string;\n    agentId: string;\n    taskId: string | null;\n    triggerType: string;\n    inboxMessageId: string | null;\n    taskDescription: string | null;\n    runnerSessionId: string | null;\n    providerSessionId: string | null;\n    startedAt: string;\n    lastHeartbeatAt: string;\n    runtimeInstanceId?: string | null | undefined;\n  };\n\n  export type RequestInfo = {\n    sessionId: string | undefined;\n    agentId: string | undefined;\n    runtimeInstanceId: string | undefined;\n    sourceTaskId: string | undefined;\n    contextKey: string | undefined;\n    callOrigin: "mcp" | "extension" | "script-sdk";\n  };\n\n  import type { SwarmSdk } from "swarm-sdk";\n  import type { z } from "zod";\n  export type Runtime = "api" | "worker";\n  export interface ExtensionScriptAsset {\n    name: string;\n    file: string;\n    description: string;\n    intent?: string;\n  }\n  export interface ExtensionScheduleAsset {\n    name: string;\n    description?: string;\n    script: string;\n    cronExpression?: string;\n    intervalMs?: number;\n    timezone?: string;\n    args?: Record<string, unknown>;\n  }\n  export interface ExtensionWorkflowAsset {\n    file: string;\n  }\n  export interface ExtensionSkillAsset {\n    dir: string;\n  }\n  export interface ExtensionManifest {\n    $schema?: string;\n    name: string;\n    description: string;\n    version: string;\n    runtime: Runtime;\n    assets: {\n      hooks: string;\n      scripts?: readonly ExtensionScriptAsset[];\n      schedules?: readonly ExtensionScheduleAsset[];\n      workflows?: readonly ExtensionWorkflowAsset[];\n      skills?: readonly ExtensionSkillAsset[];\n    };\n    homepage?: string;\n    author?: string;\n  }\n  export interface HooksModule {\n    default: SwarmExtension;\n    config?: z.ZodTypeAny;\n  }\n  export interface ExtensionState {\n    get<T = unknown>(key: string): Promise<T | null>;\n    set<T>(key: string, value: T): Promise<void>;\n    incr(key: string, by?: number): Promise<number>;\n    del(key: string): Promise<void>;\n  }\n  export interface ExtensionLogger {\n    debug(message: string, data?: unknown): void;\n    info(message: string, data?: unknown): void;\n    warn(message: string, data?: unknown): void;\n    error(message: string, data?: unknown): void;\n  }\n  type ConfigFor<M extends ExtensionManifest> = M extends {\n    config: infer C extends z.ZodTypeAny;\n  }\n    ? z.infer<C>\n    : Record<string, unknown>;\n  export interface ApiCtx<Config = Record<string, unknown>> {\n    swarm: SwarmSdk;\n    state: ExtensionState;\n    config: Config;\n    log: ExtensionLogger;\n    signal: AbortSignal;\n    event: {\n      name: keyof SwarmEventMap;\n      at: string;\n      extension: {\n        id: string;\n        version: number;\n      };\n    };\n  }\n  export interface WorkerCtx<Config = Record<string, unknown>>\n    extends Omit<ApiCtx<Config>, "swarm"> {\n    swarm: SwarmSdk;\n    worker: {\n      agentId: string;\n      taskId: string;\n      harness: string;\n    };\n  }\n  export type CtxFor<M extends ExtensionManifest> = M["runtime"] extends "api"\n    ? ApiCtx<ConfigFor<M>>\n    : WorkerCtx<ConfigFor<M>>;\n  export type PreResult<Modify> =\n    | void\n    | {\n        action: "continue";\n      }\n    | {\n        action: "modify";\n        data: Modify;\n      }\n    | {\n        action: "block";\n        reason: string;\n      };\n  export type TaskCreateOrigin =\n    | "rest"\n    | "app"\n    | "mcp"\n    | "slack"\n    | "schedule"\n    | "workflow"\n    | "webhook"\n    | "followUp"\n    | `extension:${string}`;\n  export interface TaskCreateEvent {\n    options: CreateTaskOptions;\n    description: string;\n    origin: TaskCreateOrigin;\n    requestInfo?: RequestInfo;\n  }\n  /** A pre.task.create hook blocked a task before it was created. */\n  export interface TaskBlockedEvent {\n    /** The extension that blocked, or whose model/agent rewrite was rejected. */\n    extension: {\n      id: string;\n      name: string;\n    };\n    /** The scrubbed block reason. */\n    reason: string;\n    origin: TaskCreateOrigin;\n    source?: AgentTask["source"];\n    requester: {\n      userId?: string;\n      agentId?: string;\n      slackUserId?: string;\n    };\n    context?: {\n      contextKey?: string;\n      scheduleId?: string;\n      workflowRunId?: string;\n      workflowRunStepId?: string;\n      parentTaskId?: string;\n      vcsRepo?: string;\n      vcsNumber?: number;\n      slackChannelId?: string;\n      slackThreadTs?: string;\n    };\n    /** The original task description, scrubbed and cut to 500 characters. */\n    description: string;\n  }\n  export type TaskCreateModify = Partial<\n    Pick<\n      CreateTaskOptions,\n      | "agentId"\n      | "creatorAgentId"\n      | "source"\n      | "taskType"\n      | "tags"\n      | "priority"\n      | "dependsOn"\n      | "offeredTo"\n      | "vcsProvider"\n      | "vcsRepo"\n      | "vcsEventType"\n      | "vcsNumber"\n      | "vcsCommentId"\n      | "vcsAuthor"\n      | "vcsUrl"\n      | "vcsInstallationId"\n      | "vcsNodeId"\n      | "agentmailInboxId"\n      | "agentmailMessageId"\n      | "agentmailThreadId"\n      | "mentionMessageId"\n      | "mentionChannelId"\n      | "dir"\n      | "model"\n      | "modelTier"\n      | "effort"\n      | "outputSchema"\n      | "followUpConfig"\n      | "bypassTrackerContextDedup"\n    >\n  > & {\n    description?: string;\n  };\n  export interface TaskFollowUpEvent {\n    completedTask: AgentTask;\n    status: "completed" | "failed";\n    output?: string;\n    failureReason?: string;\n    workerAgentId: string;\n    leadAgentId: string;\n    summary: string;\n  }\n  export type TaskFollowUpModify = Partial<\n    Pick<CreateTaskOptions, "agentId" | "priority" | "followUpConfig">\n  > & {\n    description?: string;\n  };\n  export interface SlackRouteEvent {\n    channelId: string;\n    userId: string;\n    text: string;\n    threadTs?: string;\n    botMentioned: boolean;\n    threadContext?: {\n      channelId: string;\n      threadTs: string;\n    };\n  }\n  export interface SlackRouteModify {\n    target:\n      | {\n          kind: "agent";\n          agentId: string;\n        }\n      | {\n          kind: "lead";\n        }\n      | {\n          kind: "broadcast";\n        };\n  }\n  /** A Chat SDK message after its thread buffer flushed, before routing. */\n  export interface ChatRouteEvent {\n    /** Adapter name, such as `telegram` or `slack`. */\n    adapter: string;\n    channelId: string;\n    /** The Chat SDK thread id, prefixed with the adapter name. */\n    threadId: string;\n    /** The first buffered sender. */\n    userId: string;\n    userName?: string;\n    /** The buffered messages, joined. */\n    text: string;\n    /** True for an @mention and for a reply to one of the bot\'s messages. */\n    botMentioned: boolean;\n    isDirectMessage: boolean;\n    /** Platform chat type, such as Telegram `private`, `group`, `supergroup` or `channel`. */\n    chatType?: string;\n    /** Set for a Telegram supergroup with topics. */\n    isForum?: boolean;\n    /** A buffered message replies to one of the bot\'s own messages. */\n    replyToBot: boolean;\n    /** Set when earlier swarm tasks exist in this thread. */\n    threadContext?: {\n      adapter: string;\n      threadId: string;\n    };\n  }\n  export interface ChatRouteModify {\n    target:\n      | {\n          kind: "agent";\n          agentId: string;\n        }\n      | {\n          kind: "lead";\n        }\n      | {\n          kind: "broadcast";\n        }\n      | {\n          kind: "workflow";\n          workflowId: string;\n        };\n  }\n  export type HeartbeatClassification = "no-session" | "stale-session" | "fresh-stalled";\n  export type HeartbeatAction = "supersede-resume" | "fail" | "record";\n  export interface HeartbeatRemediateEvent {\n    task: AgentTask;\n    session?: ActiveSession;\n    classification: HeartbeatClassification;\n    proposedAction: HeartbeatAction;\n    reason: string;\n    taskAgeMs: number;\n    sessionHeartbeatAgeMs?: number;\n  }\n  export interface HeartbeatRemediateModify {\n    proposedAction: HeartbeatAction;\n  }\n  export interface ToolCallEvent {\n    tool: string;\n    args: unknown;\n    requestInfo: RequestInfo;\n  }\n  export interface ToolCallModify {\n    args: unknown;\n  }\n  export interface TaskEvent {\n    task: AgentTask;\n  }\n  export interface TaskCompletedEvent extends TaskEvent {\n    output: string;\n  }\n  export interface TaskFailedEvent extends TaskEvent {\n    failureReason: string;\n  }\n  export interface TaskSupersededEvent extends TaskEvent {\n    supersededBy: string;\n  }\n  export interface TaskProgressEvent extends TaskEvent {\n    progress: string;\n  }\n  export interface SlackMessageEvent {\n    channelId: string;\n    userId: string;\n    text: string;\n    threadTs?: string;\n    taskId?: string;\n  }\n  /** A Chat SDK message the swarm received or sent. */\n  export interface ChatMessageEvent {\n    adapter: string;\n    channelId: string;\n    threadId: string;\n    /** The sender, for an inbound message. */\n    userId?: string;\n    text: string;\n    direction: "inbound" | "outbound";\n    taskId?: string;\n    messageId?: string;\n  }\n  /**\n   * A person answered an approval request. Fires for workflow and standalone\n   * requests. Timeouts and cancellations do not emit it today.\n   */\n  export interface ApprovalResolvedEvent {\n    requestId: string;\n    status: "approved" | "rejected" | "timeout" | "cancelled";\n    responses: Record<string, unknown> | null;\n    /** Set when a workflow human-in-the-loop step asked. Absent for a standalone request. */\n    workflowRunId?: string;\n    workflowRunStepId?: string;\n    /** The task whose agent asked, for a standalone request. */\n    sourceTaskId?: string;\n  }\n  /** A task was refused because a daily spend budget is used up. */\n  export interface TaskBudgetRefusedEvent extends TaskEvent {\n    /** The agent the task was refused for. */\n    agentId: string;\n    /** Which budget refused it. The matching spend and budget fields are set. */\n    cause: "agent" | "global" | "user";\n    agentSpendUsd?: number;\n    agentBudgetUsd?: number;\n    globalSpendUsd?: number;\n    globalBudgetUsd?: number;\n    userSpendUsd?: number;\n    userBudgetUsd?: number;\n    /** ISO 8601 time the daily budget resets. */\n    resetAt: string;\n  }\n  /** An inbound AgentMail message. */\n  export interface EmailReceivedEvent {\n    inboxId: string;\n    /** The From header as sent. */\n    from: string;\n    subject: string;\n    /** The text body, or the HTML when there is no text, cut to 500 characters with `...` appended. */\n    body: string;\n    threadId: string;\n    messageId: string;\n  }\n  /** An inbound Kapso (WhatsApp) message. */\n  export interface KapsoMessageEvent {\n    phoneNumberId: string;\n    conversationId?: string;\n    messageId: string;\n    from?: string;\n    /** Kapso message type, such as `text` or `image`. */\n    type?: string;\n    /** The text, or a placeholder naming the type for a non-text message. */\n    text: string;\n  }\n  export type VcsProvider = "github" | "gitlab" | "azure-devops" | "bitbucket";\n  /**\n   * The provider object the event is about, as the provider names it. GitLab\n   * calls a pull request a merge request, and a comment a `note`.\n   */\n  export type VcsEventKind =\n    | "pull_request"\n    | "merge_request"\n    | "issue"\n    | "issue_comment"\n    | "note"\n    | "pull_request_review"\n    | "pipeline";\n  /**\n   * A webhook event from a connected code host. `action` is the provider\'s own\n   * value: `opened`, `closed`, `synchronize`, `merge`, `created`, `commented`, or,\n   * for a pipeline, its status such as `success` or `failed`. Fields a kind does\n   * not carry are absent.\n   */\n  export interface VcsEvent {\n    provider: VcsProvider;\n    kind: VcsEventKind;\n    action: string;\n    /** `owner/name` on GitHub and GitLab, `workspace/repo_slug` on Bitbucket, the repository URL on Azure DevOps. */\n    repo: string;\n    /** The PR, merge request, or issue number. Absent for a pipeline outside a merge request. */\n    number?: number;\n    title?: string;\n    body?: string | null;\n    /** Login of the user behind the event. Set for pull requests, merge requests, and Azure DevOps comments. */\n    author?: string;\n    url?: string;\n    merged?: boolean;\n    changedFiles?: number;\n    /** The review verdict, on a pull request review. */\n    reviewState?: string;\n  }\n  export interface ToolCallCompletedEvent extends ToolCallEvent {\n    result: unknown;\n    durationMs: number;\n  }\n  export interface SwarmEventMap {\n    "pre.task.create": {\n      event: TaskCreateEvent;\n      modify: TaskCreateModify;\n      result: PreResult<TaskCreateModify>;\n    };\n    "pre.task.followUp": {\n      event: TaskFollowUpEvent;\n      modify: TaskFollowUpModify;\n      result: PreResult<TaskFollowUpModify>;\n    };\n    "pre.slack.route": {\n      event: SlackRouteEvent;\n      modify: SlackRouteModify;\n      result: PreResult<SlackRouteModify>;\n    };\n    "pre.chat.route": {\n      event: ChatRouteEvent;\n      modify: ChatRouteModify;\n      result: PreResult<ChatRouteModify>;\n    };\n    "pre.heartbeat.remediate": {\n      event: HeartbeatRemediateEvent;\n      modify: HeartbeatRemediateModify;\n      result: PreResult<HeartbeatRemediateModify>;\n    };\n    "pre.tool.call": {\n      event: ToolCallEvent;\n      modify: ToolCallModify;\n      result: PreResult<ToolCallModify>;\n    };\n    "post.task.created": {\n      event: TaskEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.blocked": {\n      event: TaskBlockedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.completed": {\n      event: TaskCompletedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.failed": {\n      event: TaskFailedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.cancelled": {\n      event: TaskEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.superseded": {\n      event: TaskSupersededEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.progress": {\n      event: TaskProgressEvent;\n      modify: never;\n      result: void;\n    };\n    "post.slack.message": {\n      event: SlackMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.chat.message": {\n      event: ChatMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.approval.resolved": {\n      event: ApprovalResolvedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.budgetRefused": {\n      event: TaskBudgetRefusedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.email.received": {\n      event: EmailReceivedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.kapso.message": {\n      event: KapsoMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.vcs.event": {\n      event: VcsEvent;\n      modify: never;\n      result: void;\n    };\n    "post.tool.call": {\n      event: ToolCallCompletedEvent;\n      modify: never;\n      result: void;\n    };\n  }\n  export interface ExtensionApi<\n    M extends ExtensionManifest = ExtensionManifest & {\n      runtime: "api";\n    },\n  > {\n    on<E extends keyof SwarmEventMap>(\n      event: E,\n      handler: (\n        event: SwarmEventMap[E]["event"],\n        ctx: CtxFor<M>,\n      ) => Promise<SwarmEventMap[E]["result"]> | SwarmEventMap[E]["result"],\n      opts?: {\n        priority?: number;\n      },\n    ): void;\n  }\n  export type SwarmExtension<\n    M extends ExtensionManifest = ExtensionManifest & {\n      runtime: "api";\n    },\n  > = (api: ExtensionApi<M>) => void;\n  export { block, modify } from "./contract-runtime";\n}\n';

package/src/extensions/contract.ts

@@ -119,6 +119,30 @@ export interface TaskCreateEvent {
   requestInfo?: RequestInfo;
 }
 
+/** A pre.task.create hook blocked a task before it was created. */
+export interface TaskBlockedEvent {
+  /** The extension that blocked, or whose model/agent rewrite was rejected. */
+  extension: { id: string; name: string };
+  /** The scrubbed block reason. */
+  reason: string;
+  origin: TaskCreateOrigin;
+  source?: AgentTask["source"];
+  requester: { userId?: string; agentId?: string; slackUserId?: string };
+  context?: {
+    contextKey?: string;
+    scheduleId?: string;
+    workflowRunId?: string;
+    workflowRunStepId?: string;
+    parentTaskId?: string;
+    vcsRepo?: string;
+    vcsNumber?: number;
+    slackChannelId?: string;
+    slackThreadTs?: string;
+  };
+  /** The original task description, scrubbed and cut to 500 characters. */
+  description: string;
+}
+
 export type TaskCreateModify = Partial<
   Pick<
     CreateTaskOptions,
@@ -414,6 +438,7 @@ export interface SwarmEventMap {
     result: PreResult<ToolCallModify>;
   };
   "post.task.created": { event: TaskEvent; modify: never; result: void };
+  "post.task.blocked": { event: TaskBlockedEvent; modify: never; result: void };
   "post.task.completed": { event: TaskCompletedEvent; modify: never; result: void };
   "post.task.failed": { event: TaskFailedEvent; modify: never; result: void };
   "post.task.cancelled": { event: TaskEvent; modify: never; result: void };

package/src/extensions/dispatcher.ts

@@ -148,6 +148,10 @@ export function runContext(event: keyof SwarmEventMap, payload: unknown): RunCon
       agentId = requestAgent ?? stringField(payload, "options", "agentId");
       subject = `${stringField(payload, "origin") ?? "?"}: ${snippet(field(payload, "description"))}`;
       break;
+    case "post.task.blocked":
+      agentId = stringField(payload, "requester", "agentId");
+      subject = `${stringField(payload, "origin") ?? "?"}: ${stringField(payload, "extension", "name") ?? "?"}`;
+      break;
     case "pre.task.followUp":
       agentId = stringField(payload, "workerAgentId");
       subject =

package/src/extensions/post-bridge.ts

@@ -5,6 +5,7 @@ import type {
   ApprovalResolvedEvent,
   ChatMessageEvent,
   KapsoMessageEvent,
+  TaskBlockedEvent,
   TaskBudgetRefusedEvent,
   VcsEvent,
   VcsEventKind,
@@ -44,6 +45,11 @@ const onTaskCreated = observed("task.created", async (data) => {
     );
 });
 
+const onTaskBlocked = observed("task.create_blocked", async (data) => {
+  const { skipExtensionId, ...event } = data as TaskBlockedEvent & { skipExtensionId?: string };
+  await dispatchPost("post.task.blocked", event, { skipExtensionId });
+});
+
 const onTaskCompleted = observed("task.completed", async (data) => {
   const task = await taskFrom(data);
   if (!task) return;
@@ -358,6 +364,7 @@ export function initExtensionPostBridge(): void {
   if (subscribed) return;
   subscribed = true;
   workflowEventBus.on("task.created", onTaskCreated);
+  workflowEventBus.on("task.create_blocked", onTaskBlocked);
   workflowEventBus.on("task.completed", onTaskCompleted);
   workflowEventBus.on("task.failed", onTaskFailed);
   workflowEventBus.on("task.cancelled", onTaskCancelled);
@@ -377,6 +384,7 @@ export function teardownExtensionPostBridge(): void {
   if (!subscribed) return;
   subscribed = false;
   workflowEventBus.off("task.created", onTaskCreated);
+  workflowEventBus.off("task.create_blocked", onTaskBlocked);
   workflowEventBus.off("task.completed", onTaskCompleted);
   workflowEventBus.off("task.failed", onTaskFailed);
   workflowEventBus.off("task.cancelled", onTaskCancelled);

package/src/hooks/context-bound-note.ts

@@ -0,0 +1,196 @@
+import { renameSync, writeFileSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { renderContextBoundNote } from "../prompts/context-bound-note";
+
+/**
+ * One-time "keep this turn bounded" note for long worker sessions, on every
+ * harness.
+ *
+ * This module owns the threshold, the once-per-task claim and the rendering.
+ * A harness supplies only two things: the prompt size of its latest
+ * main-thread request (input + cache read + cache write tokens) and a way to
+ * put text in front of the model mid-session.
+ *
+ * - Claude: the session writes the size next to the task file
+ *   (`recordContextState`); the PostToolUse hook claims a marker file
+ *   (`claimContextBoundNote`) and returns the note as tool context.
+ * - In-process harnesses (codex, pi, opencode, amp, claude-managed): the session
+ *   feeds each request's size to `createContextBoundNote`, which injects the
+ *   note through the harness's own mid-turn input, and only while that input
+ *   still lands inside the current turn.
+ *
+ * Every failure path means "no note": nothing here throws into a session or
+ * blocks a tool call.
+ */
+
+/**
+ * Threshold from `CONTEXT_BOUND_NOTE_TOKENS`. Off by default: unset, empty,
+ * 0 or invalid returns 0 (off); a positive integer turns the note on at that
+ * many tokens.
+ */
+export function contextBoundNoteThreshold(
+  env: Record<string, string | undefined> = process.env,
+): number {
+  const raw = env.CONTEXT_BOUND_NOTE_TOKENS?.trim();
+  if (!raw || !/^\d+$/.test(raw)) return 0;
+  const parsed = Number(raw);
+  return Number.isSafeInteger(parsed) ? parsed : 0;
+}
+
+/** True when a valid token count reaches an enabled (> 0) threshold. */
+function reachesThreshold(contextTokens: unknown, threshold: number): contextTokens is number {
+  return (
+    threshold > 0 &&
+    typeof contextTokens === "number" &&
+    Number.isFinite(contextTokens) &&
+    contextTokens >= threshold
+  );
+}
+
+/** Render the note and hand it to `inject`. Fails open. */
+async function deliverContextBoundNote(
+  contextTokens: number,
+  model: string | undefined,
+  inject: (note: string) => unknown,
+): Promise<void> {
+  try {
+    const note = await renderContextBoundNote(contextTokens, model);
+    if (note) await inject(note);
+  } catch {
+    // Fail open.
+  }
+}
+
+export function contextStatePath(taskFilePath: string): string {
+  return `${taskFilePath}.context.json`;
+}
+
+export function contextBoundNoteMarkerPath(taskFilePath: string): string {
+  return `${taskFilePath}.bound-note`;
+}
+
+/** What the session records for the hook: the latest request's size and the session's model. */
+export interface ContextState {
+  contextTokens: number;
+  model?: string;
+}
+
+/**
+ * Record the latest request's context size (and the session's model, for the
+ * window share) for the hook. Synchronous so
+ * writes land in stream order; tmp + rename so the hook never reads a partial
+ * file. Errors are swallowed: a missing state file only means no note.
+ */
+export function recordContextState(
+  taskFilePath: string,
+  contextTokens: number,
+  model?: string,
+): void {
+  const path = contextStatePath(taskFilePath);
+  const tmp = `${path}.tmp`;
+  try {
+    writeFileSync(
+      tmp,
+      JSON.stringify({ contextTokens, model, updatedAt: new Date().toISOString() }),
+    );
+    renameSync(tmp, path);
+  } catch {
+    // Fail open.
+  }
+}
+
+/**
+ * Returns the recorded state when the note should fire now, else null. Fires at
+ * most once per task file: the marker is created with `wx`, so a second call
+ * (or a concurrent hook) loses the race and gets null.
+ */
+export async function claimContextBoundNote(
+  taskFilePath: string | undefined,
+  threshold: number,
+): Promise<ContextState | null> {
+  if (!taskFilePath || threshold <= 0) return null;
+  let contextTokens: unknown;
+  let model: unknown;
+  try {
+    const state = JSON.parse(await readFile(contextStatePath(taskFilePath), "utf8")) as {
+      contextTokens?: unknown;
+      model?: unknown;
+    };
+    contextTokens = state?.contextTokens;
+    model = state?.model;
+  } catch {
+    return null;
+  }
+  if (!reachesThreshold(contextTokens, threshold)) return null;
+  try {
+    await writeFile(contextBoundNoteMarkerPath(taskFilePath), new Date().toISOString(), {
+      flag: "wx",
+    });
+  } catch {
+    return null;
+  }
+  return { contextTokens, model: typeof model === "string" && model ? model : undefined };
+}
+
+/** Claude PostToolUse path: claim from the task file, then hand the note to `inject`. */
+export async function injectClaimedContextBoundNote(
+  taskFilePath: string | undefined,
+  threshold: number,
+  inject: (note: string) => unknown,
+): Promise<void> {
+  const state = await claimContextBoundNote(taskFilePath, threshold).catch(() => null);
+  if (state) await deliverContextBoundNote(state.contextTokens, state.model, inject);
+}
+
+/**
+ * In-process path. Returns an observer the session calls with each
+ * main-thread request's prompt size. The first size at or above `threshold`
+ * claims the note for this session (one session runs one task) and renders
+ * it; later sizes are ignored. The returned promise never rejects.
+ *
+ * Rendering is async (HTTP on workers), so the session may have moved on by
+ * the time the note is ready. `canDeliver` decides then: true injects it;
+ * false holds it, and each later call retries the held note instead of
+ * rendering a new one. A session that settles, aborts or ends its last turn
+ * first never gets it.
+ */
+export function createContextBoundNote(options: {
+  threshold: number;
+  /** The session's model, read when the note renders, for the window share. */
+  model?: () => string | undefined;
+  inject: (note: string) => unknown;
+  /** True while a note injected now reaches the model inside the current turn. */
+  canDeliver: () => boolean;
+}): (contextTokens: number | undefined) => Promise<void> {
+  let state: "idle" | "rendering" | "held" | "done" = "idle";
+  let held = "";
+  const tryDeliver = async (note: string): Promise<void> => {
+    try {
+      if (!options.canDeliver()) {
+        held = note;
+        state = "held";
+        return;
+      }
+      state = "done";
+      await options.inject(note);
+    } catch {
+      // Fail open.
+    }
+  };
+  return async (contextTokens) => {
+    if (state === "held") return tryDeliver(held);
+    if (state !== "idle" || !reachesThreshold(contextTokens, options.threshold)) return;
+    state = "rendering";
+    let note = "";
+    try {
+      note = await renderContextBoundNote(contextTokens, options.model?.());
+    } catch {
+      // Fail open.
+    }
+    if (!note) {
+      state = "done";
+      return;
+    }
+    await tryDeliver(note);
+  };
+}

package/src/hooks/hook.ts

@@ -24,6 +24,7 @@ import { getMcpBaseUrl, MAX_PROFILE_FILE_LENGTH } from "../utils/constants";
 import { isSessionSummarySkipped } from "../utils/env-flag";
 import { summarizeSession as runSummarize } from "../utils/internal-ai";
 import { scrubSecrets } from "../utils/secret-scrubber";
+import { contextBoundNoteThreshold, injectClaimedContextBoundNote } from "./context-bound-note";
 import { guardGhPrBody } from "./pr-body-guard";
 import { guardGhPrRoom } from "./pr-room-guard";
 import { checkToolLoop, clearToolHistory } from "./tool-loop-detection";
@@ -78,6 +79,8 @@ interface HookMessage {
   tool_input?: Record<string, unknown>;
   tool_response?: Record<string, unknown>;
   tool_use_id?: string;
+  /** Set only when the hook fires inside a subagent. */
+  agent_id?: string;
   prompt?: string;
   stop_hook_active?: boolean;
 }
@@ -1339,6 +1342,15 @@ export async function handleHook(): Promise<void> {
               `Task sent successfully.${maybeTaskId ? ` Task ID: ${maybeTaskId}.` : ""} Monitor progress using the get-task-details tool periodically.`,
             );
           }
+        } else if (!msg.agent_id) {
+          // One-time nudge once the session's context crosses the threshold.
+          // Main thread only: a subagent call must not consume the marker.
+          // Any failure means no note; it never blocks the tool call.
+          await injectClaimedContextBoundNote(
+            process.env.TASK_FILE,
+            contextBoundNoteThreshold(),
+            (note) => outputToolContext("PostToolUse", note),
+          );
         }
       }
       break;