@sema-agent/core 7.56.0 → 7.58.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (319) hide show
  1. package/CHANGELOG.md +926 -0
  2. package/LICENSE +1 -1
  3. package/dist/agents/org-delivery-gate.js +3 -4
  4. package/dist/agents/peer-held-queue.d.ts +69 -49
  5. package/dist/agents/peer-held-queue.js +255 -106
  6. package/dist/agents/peer-session-drain.js +63 -43
  7. package/dist/agents/send-message-tool.js +3 -2
  8. package/dist/agents/subagent-steps.js +2 -4
  9. package/dist/agents/subagent.js +8 -8
  10. package/dist/brain/anthropic.js +16 -8
  11. package/dist/brain/open-responses.js +10 -8
  12. package/dist/brain/openai.js +11 -9
  13. package/dist/brain/provider-dialect.d.ts +3 -2
  14. package/dist/brain/provider-dialect.js +2 -2
  15. package/dist/brain/request-params.d.ts +6 -0
  16. package/dist/brain/request-params.js +14 -1
  17. package/dist/brain/route-adjudicator.js +2 -1
  18. package/dist/brain/stream-engine.d.ts +9 -0
  19. package/dist/brain/stream-engine.js +24 -10
  20. package/dist/brain/stream-shared.d.ts +5 -4
  21. package/dist/brain/stream-shared.js +4 -4
  22. package/dist/core/a2a.d.ts +2 -1
  23. package/dist/core/a2a.js +23 -10
  24. package/dist/core/allow-entry.d.ts +5 -11
  25. package/dist/core/allow-entry.js +19 -26
  26. package/dist/core/approval-object.d.ts +21 -5
  27. package/dist/core/approval-object.js +44 -17
  28. package/dist/core/ask-origin.d.ts +23 -4
  29. package/dist/core/ask-origin.js +5 -1
  30. package/dist/core/auto-compaction.d.ts +75 -6
  31. package/dist/core/auto-compaction.js +43 -27
  32. package/dist/core/auto-mode-directive.d.ts +29 -5
  33. package/dist/core/auto-mode-directive.js +38 -8
  34. package/dist/core/background-agent-store.d.ts +6 -2
  35. package/dist/core/background-agent-store.js +1 -1
  36. package/dist/core/checkpoint-requirements.d.ts +13 -1
  37. package/dist/core/checkpoint-requirements.js +4 -0
  38. package/dist/core/checkpoint-store.d.ts +44 -40
  39. package/dist/core/checkpoint-store.js +32 -14
  40. package/dist/core/cross-boundary-taint.js +4 -2
  41. package/dist/core/engine-notice.d.ts +4 -3
  42. package/dist/core/engine-notice.js +6 -0
  43. package/dist/core/file-history-store.d.ts +14 -8
  44. package/dist/core/file-history-store.js +14 -4
  45. package/dist/core/fs-write-gate-policy.d.ts +4 -2
  46. package/dist/core/fs-write-gate-policy.js +7 -3
  47. package/dist/core/gate-fold.js +6 -3
  48. package/dist/core/gate-lanes.js +13 -5
  49. package/dist/core/git-worktree-env.d.ts +53 -11
  50. package/dist/core/git-worktree-env.js +96 -12
  51. package/dist/core/hooks.d.ts +6 -3
  52. package/dist/core/hooks.js +12 -5
  53. package/dist/core/human-input-projection.d.ts +1 -0
  54. package/dist/core/human-input-projection.js +3 -0
  55. package/dist/core/locked-config.d.ts +15 -1
  56. package/dist/core/locked-config.js +38 -2
  57. package/dist/core/mailbox-store.d.ts +62 -1
  58. package/dist/core/mailbox-store.js +59 -0
  59. package/dist/core/mcp-call-meta.d.ts +66 -0
  60. package/dist/core/mcp-call-meta.js +103 -0
  61. package/dist/core/mcp-connection-pool.d.ts +3 -1
  62. package/dist/core/mcp-connection-pool.js +3 -1
  63. package/dist/core/mcp-failure.d.ts +7 -1
  64. package/dist/core/mcp-failure.js +10 -0
  65. package/dist/core/mcp-name-judge.d.ts +46 -0
  66. package/dist/core/mcp-name-judge.js +61 -0
  67. package/dist/core/mcp-probe.d.ts +5 -1
  68. package/dist/core/mcp-probe.js +3 -6
  69. package/dist/core/mcp-server-link.d.ts +5 -2
  70. package/dist/core/mcp-server-spec.d.ts +46 -18
  71. package/dist/core/mcp-server-spec.js +1 -18
  72. package/dist/core/mcp.d.ts +6 -14
  73. package/dist/core/mcp.js +85 -65
  74. package/dist/core/memory-engine/consolidation-driver.js +4 -3
  75. package/dist/core/memory-engine/distiller.js +26 -17
  76. package/dist/core/memory-engine/layout.js +5 -2
  77. package/dist/core/memory-engine/scope-contract.d.ts +45 -4
  78. package/dist/core/memory-engine/scope-contract.js +80 -11
  79. package/dist/core/mode-policy.d.ts +8 -5
  80. package/dist/core/mode-policy.js +5 -4
  81. package/dist/core/mods/host.js +1 -1
  82. package/dist/core/mods/kernel/dispatch.d.ts +3 -0
  83. package/dist/core/mods/kernel/dispatch.js +10 -8
  84. package/dist/core/mods/kernel/events.d.ts +5 -1
  85. package/dist/core/mods/kernel/events.js +1 -1
  86. package/dist/core/mods/kernel/registration.d.ts +5 -1
  87. package/dist/core/mods/kernel/site-rules.d.ts +3 -0
  88. package/dist/core/mods/kernel/site-rules.js +10 -0
  89. package/dist/core/mods/package.d.ts +23 -0
  90. package/dist/core/mods/package.js +118 -0
  91. package/dist/core/mods/stations.d.ts +2 -2
  92. package/dist/core/mods/stations.js +1 -1
  93. package/dist/core/mods/tool-call.d.ts +5 -1
  94. package/dist/core/mods/tool-call.js +12 -3
  95. package/dist/core/park-selfcheck.js +2 -0
  96. package/dist/core/path-guard-rows.d.ts +20 -0
  97. package/dist/core/path-guard-rows.js +11 -0
  98. package/dist/core/peer-seat.d.ts +186 -0
  99. package/dist/core/peer-seat.js +307 -0
  100. package/dist/core/permission-rule-consent.d.ts +5 -3
  101. package/dist/core/permission-rule-consent.js +20 -15
  102. package/dist/core/permission-rule-model.d.ts +43 -2
  103. package/dist/core/permission-rule-model.js +52 -8
  104. package/dist/core/permission-rule-org.js +1 -1
  105. package/dist/core/present-plan-tool.d.ts +10 -1
  106. package/dist/core/present-plan-tool.js +46 -2
  107. package/dist/core/protocol-http-auth.d.ts +56 -31
  108. package/dist/core/protocol-http-auth.js +71 -42
  109. package/dist/core/protocol-naming.d.ts +20 -0
  110. package/dist/core/protocol-naming.js +20 -3
  111. package/dist/core/read-only-shell.d.ts +20 -5
  112. package/dist/core/read-only-shell.js +29 -14
  113. package/dist/core/redaction-marks.d.ts +16 -0
  114. package/dist/core/redaction-marks.js +16 -0
  115. package/dist/core/redaction-passes.js +8 -9
  116. package/dist/core/remote-env.d.ts +37 -1
  117. package/dist/core/remote-env.js +11 -0
  118. package/dist/core/resume-startup-cause.d.ts +24 -2
  119. package/dist/core/resume-startup-cause.js +20 -1
  120. package/dist/core/retention.d.ts +41 -15
  121. package/dist/core/retention.js +59 -12
  122. package/dist/core/rewrite-rejudge.d.ts +37 -0
  123. package/dist/core/rewrite-rejudge.js +40 -0
  124. package/dist/core/roles.js +50 -7
  125. package/dist/core/run-origin.d.ts +40 -0
  126. package/dist/core/run-origin.js +37 -0
  127. package/dist/core/runner/advertised-writable-dirs.d.ts +57 -38
  128. package/dist/core/runner/advertised-writable-dirs.js +126 -0
  129. package/dist/core/runner/compact-session.d.ts +10 -0
  130. package/dist/core/runner/compact-session.js +202 -0
  131. package/dist/core/runner/compaction-call-options.d.ts +2 -2
  132. package/dist/core/runner/compaction-restate.d.ts +15 -6
  133. package/dist/core/runner/compaction-restate.js +28 -2
  134. package/dist/core/runner/compaction-seams.d.ts +21 -1
  135. package/dist/core/runner/compaction-seams.js +11 -8
  136. package/dist/core/runner/contracts.d.ts +36 -21
  137. package/dist/core/runner/derived-route-fallback.d.ts +13 -0
  138. package/dist/core/runner/derived-route-fallback.js +6 -0
  139. package/dist/core/runner/env-capability-census.d.ts +3 -2
  140. package/dist/core/runner/env-capability-census.js +9 -3
  141. package/dist/core/runner/gate-exit.d.ts +18 -4
  142. package/dist/core/runner/gate-exit.js +5 -1
  143. package/dist/core/runner/permission-rule-lanes.d.ts +7 -7
  144. package/dist/core/runner/permission-rule-lanes.js +17 -11
  145. package/dist/core/runner/prepare-acquire-reconcile.d.ts +3 -0
  146. package/dist/core/runner/prepare-acquire-reconcile.js +2 -1
  147. package/dist/core/runner/prepare-caps-and-workflow.d.ts +2 -0
  148. package/dist/core/runner/prepare-caps-and-workflow.js +1 -1
  149. package/dist/core/runner/prepare-config-doors.d.ts +14 -5
  150. package/dist/core/runner/prepare-config-doors.js +16 -13
  151. package/dist/core/runner/prepare-delegation-surface.d.ts +4 -0
  152. package/dist/core/runner/prepare-delegation-surface.js +15 -18
  153. package/dist/core/runner/prepare-gate-stations.js +1 -1
  154. package/dist/core/runner/prepare-hands-readface.d.ts +10 -4
  155. package/dist/core/runner/prepare-hands-readface.js +6 -1
  156. package/dist/core/runner/prepare-memory.d.ts +3 -0
  157. package/dist/core/runner/prepare-memory.js +19 -23
  158. package/dist/core/runner/prepare-park-ask.d.ts +2 -0
  159. package/dist/core/runner/prepare-park-ask.js +2 -2
  160. package/dist/core/runner/prepare-policy-chain.d.ts +4 -4
  161. package/dist/core/runner/prepare-policy-chain.js +4 -6
  162. package/dist/core/runner/prepare-protocol-tools.d.ts +4 -2
  163. package/dist/core/runner/prepare-protocol-tools.js +3 -3
  164. package/dist/core/runner/prepare-suspend-saga.d.ts +2 -0
  165. package/dist/core/runner/prepare-suspend-saga.js +2 -1
  166. package/dist/core/runner/prepare-task.d.ts +4 -1
  167. package/dist/core/runner/prepare-task.js +46 -37
  168. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +13 -0
  169. package/dist/core/runner/prepare-tool-disclosure-mount.js +13 -7
  170. package/dist/core/runner/prepare-wiring-manifest.d.ts +1 -0
  171. package/dist/core/runner/prepare-wiring-manifest.js +2 -2
  172. package/dist/core/runner/prepare-workspace-restore.d.ts +3 -0
  173. package/dist/core/runner/prepare-workspace-restore.js +4 -4
  174. package/dist/core/runner/resume-admission.js +1 -1
  175. package/dist/core/runner/resume-checkpoint-screen.js +2 -0
  176. package/dist/core/runner/rewind-files.d.ts +2 -5
  177. package/dist/core/runner/rewind-files.js +9 -51
  178. package/dist/core/runner/run-harness-handlers.d.ts +3 -4
  179. package/dist/core/runner/run-harness-handlers.js +1 -8
  180. package/dist/core/runner/run-identity-wiring.js +1 -0
  181. package/dist/core/runner/run-leg.js +15 -22
  182. package/dist/core/runner/run-notification-lane.d.ts +2 -0
  183. package/dist/core/runner/run-notification-lane.js +5 -2
  184. package/dist/core/runner/run-recovery-lanes.js +3 -4
  185. package/dist/core/runner/run-settle-and-teardown.js +5 -11
  186. package/dist/core/runner/run-terminal-adoption.js +3 -4
  187. package/dist/core/runner/run-turn-boundary.js +3 -5
  188. package/dist/core/runner/runtask.d.ts +8 -1
  189. package/dist/core/runner/runtask.js +28 -34
  190. package/dist/core/runner/send-message-continuation.js +1 -1
  191. package/dist/core/runner/session-verb-doors.d.ts +28 -0
  192. package/dist/core/runner/session-verb-doors.js +48 -0
  193. package/dist/core/runner/session-write-ledger.d.ts +30 -0
  194. package/dist/core/runner/session-write-ledger.js +101 -0
  195. package/dist/core/runner/stream-settle-backstop.js +11 -14
  196. package/dist/core/runner/sub-agent-deny-lists.d.ts +25 -3
  197. package/dist/core/runner/sub-agent-deny-lists.js +21 -10
  198. package/dist/core/runner/teardown-bounded.d.ts +1 -0
  199. package/dist/core/runner/teardown-bounded.js +1 -0
  200. package/dist/core/runner/terminal-account.js +3 -3
  201. package/dist/core/runner/tool-end-body.js +1 -0
  202. package/dist/core/runner/tool-occurrence.d.ts +4 -1
  203. package/dist/core/runner/tool-occurrence.js +2 -1
  204. package/dist/core/runner/write-protection-station.d.ts +8 -2
  205. package/dist/core/runner/write-protection-station.js +2 -0
  206. package/dist/core/runner-deps.d.ts +4 -4
  207. package/dist/core/secret-env.d.ts +4 -0
  208. package/dist/core/secret-env.js +3 -0
  209. package/dist/core/sensitive-path-policy.js +6 -7
  210. package/dist/core/session-log-transfer.d.ts +24 -0
  211. package/dist/core/session-log-transfer.js +166 -0
  212. package/dist/core/session-policy-store.d.ts +7 -2
  213. package/dist/core/session-policy-store.js +1 -1
  214. package/dist/core/session-store.d.ts +84 -19
  215. package/dist/core/session-store.js +162 -24
  216. package/dist/core/session.d.ts +92 -1
  217. package/dist/core/shell-read-silence.js +1 -0
  218. package/dist/core/shell-wrapper-projection.d.ts +1 -1
  219. package/dist/core/steer-replay.d.ts +4 -2
  220. package/dist/core/steer-replay.js +2 -1
  221. package/dist/core/store-contracts/background-agent-store-contract.js +1 -0
  222. package/dist/core/store-contracts/checkpoint-store-contract.js +19 -1
  223. package/dist/core/store-contracts/file-history-store-contract.js +9 -0
  224. package/dist/core/store-contracts/mailbox-store-contract.js +49 -1
  225. package/dist/core/store-contracts/session-repo-contract.js +112 -5
  226. package/dist/core/store-contracts/session-store-contract.d.ts +4 -1
  227. package/dist/core/store-contracts/session-store-contract.js +236 -2
  228. package/dist/core/task-event.d.ts +68 -8
  229. package/dist/core/task-registry-agent.d.ts +8 -4
  230. package/dist/core/task-registry-agent.js +14 -8
  231. package/dist/core/task-registry-shared.d.ts +36 -6
  232. package/dist/core/task-registry-shared.js +11 -0
  233. package/dist/core/task-registry.d.ts +1 -1
  234. package/dist/core/task-registry.js +1 -1
  235. package/dist/core/task-spec.d.ts +37 -0
  236. package/dist/core/task-stream.d.ts +2 -1
  237. package/dist/core/terminal-cause.d.ts +1 -1
  238. package/dist/core/tool-catalog-entries.d.ts +6 -0
  239. package/dist/core/tool-catalog-entries.js +2 -0
  240. package/dist/core/tool-name-aliases.d.ts +32 -2
  241. package/dist/core/tool-name-aliases.js +23 -0
  242. package/dist/core/tool-name-readings.d.ts +4 -0
  243. package/dist/core/tool-name-readings.js +1 -0
  244. package/dist/core/tool-policy.d.ts +10 -6
  245. package/dist/core/tool-policy.js +4 -7
  246. package/dist/core/tool-result-store.d.ts +17 -10
  247. package/dist/core/tool-result-store.js +3 -1
  248. package/dist/core/trace.d.ts +4 -1
  249. package/dist/core/trace.js +2 -1
  250. package/dist/core/types.d.ts +1 -1
  251. package/dist/core/untrusted-egress.d.ts +18 -0
  252. package/dist/core/untrusted-egress.js +82 -12
  253. package/dist/core/wiring-manifest.d.ts +12 -3
  254. package/dist/core/wiring-manifest.js +4 -3
  255. package/dist/core/workspace-snapshot.d.ts +44 -0
  256. package/dist/core/workspace-snapshot.js +34 -0
  257. package/dist/core/write-protect.d.ts +43 -3
  258. package/dist/core/write-protect.js +43 -16
  259. package/dist/engine/execution-env/node-execution-env.js +15 -11
  260. package/dist/engine/execution-env/symlink-chain.d.ts +7 -5
  261. package/dist/engine/harness/agent-harness.d.ts +12 -5
  262. package/dist/engine/harness/agent-harness.js +13 -2
  263. package/dist/engine/harness/types.d.ts +48 -7
  264. package/dist/engine/harness/types.js +5 -1
  265. package/dist/engine/llm/types.d.ts +12 -3
  266. package/dist/engine/llm/types.js +1 -1
  267. package/dist/engine/loop/agent-loop.d.ts +1 -4
  268. package/dist/engine/loop/agent-loop.js +26 -4
  269. package/dist/engine/session/import-validate.js +3 -0
  270. package/dist/engine/session/memory-repo.d.ts +17 -9
  271. package/dist/engine/session/memory-repo.js +44 -34
  272. package/dist/engine/session/repo-utils.d.ts +22 -4
  273. package/dist/engine/session/repo-utils.js +49 -1
  274. package/dist/engine/session/storage-base.d.ts +10 -1
  275. package/dist/engine/session/storage-base.js +7 -1
  276. package/dist/index.d.ts +23 -11
  277. package/dist/index.js +15 -6
  278. package/dist/internal/harness-types.d.ts +1 -1
  279. package/dist/internal/harness.d.ts +4 -3
  280. package/dist/internal/harness.js +3 -2
  281. package/dist/stores/file/checkpoint-store.d.ts +0 -4
  282. package/dist/stores/file/checkpoint-store.js +0 -1
  283. package/dist/stores/file/file-history-store.js +12 -4
  284. package/dist/stores/file/index.d.ts +4 -1
  285. package/dist/stores/file/index.js +4 -1
  286. package/dist/stores/file/mailbox-store.d.ts +2 -1
  287. package/dist/stores/file/mailbox-store.js +26 -1
  288. package/dist/stores/file/session-store.d.ts +15 -8
  289. package/dist/stores/file/session-store.js +28 -13
  290. package/dist/tools/fs/bash-readonly-classifier.d.ts +15 -19
  291. package/dist/tools/fs/bash-readonly-classifier.js +5 -10
  292. package/dist/tools/fs/fs-bash.js +10 -3
  293. package/dist/tools/fs/fs-write.d.ts +6 -3
  294. package/dist/tools/fs/fs-write.js +8 -7
  295. package/dist/tools/fs/index.d.ts +3 -0
  296. package/dist/tools/fs/index.js +1 -1
  297. package/dist/tools/fs/pattern-kill-guard.d.ts +3 -2
  298. package/dist/tools/fs/pattern-kill-guard.js +68 -36
  299. package/dist/tools/fs/safety.js +40 -8
  300. package/dist/tools/fs/search.js +6 -24
  301. package/dist/tools/fs/shell-read-check.d.ts +18 -1
  302. package/dist/tools/fs/shell-read-check.js +66 -16
  303. package/dist/tools/fs/shell-read-establish.js +2 -1
  304. package/dist/tools/fs/shell-read-identity.d.ts +12 -9
  305. package/dist/tools/fs/shell-read-identity.js +10 -5
  306. package/dist/tools/fs/shell-read-judge.d.ts +10 -1
  307. package/dist/tools/web.js +9 -7
  308. package/dist/tools/worktree.d.ts +42 -15
  309. package/dist/tools/worktree.js +60 -32
  310. package/package.json +4 -2
  311. package/test/export-surface.snapshot.json +141 -3
  312. package/wire-changes/core-stores-sql@7.57.0.json +29 -0
  313. package/wire-changes/core-stores-sql@7.58.0.json +29 -0
  314. package/wire-changes/core@7.57.0.json +1487 -0
  315. package/wire-changes/core@7.58.0.json +2188 -0
  316. package/wire-changes/mods-kernel@7.57.0.json +29 -0
  317. package/wire-changes/mods-kernel@7.58.0.json +81 -0
  318. package/wire-changes/primitives@7.57.0.json +245 -0
  319. package/wire-changes/primitives@7.58.0.json +29 -0
@@ -5,7 +5,7 @@ import { canAccessAgentRecord, BackgroundAgentStoreError, clearRevivedRowTermina
5
5
  import { shutdownDebug } from "./shutdown-debug.js";
6
6
  import { delimitUntrusted } from "./untrusted-text.js";
7
7
  import { boundedRedactedSummary } from "./untrusted-egress.js";
8
- import { mintCompletionId, commitCompletionIdIfEmpty, clipTaskOutput, assertOwnership, sleepPollStep, alreadyTerminalStopNote, canAccess, normalizeAgentName, closestName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, } from "./task-registry-shared.js";
8
+ import { mintCompletionId, commitCompletionIdIfEmpty, clipTaskOutput, assertOwnership, sleepPollStep, alreadyTerminalStopNote, canAccess, normalizeAgentName, engineAgentName, chosenAgentName, closestName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, } from "./task-registry-shared.js";
9
9
  import { buildToolResultRef, OFFLOAD_TOOL_NAME, toolResultProvenanceOf } from "./tool-result-store.js";
10
10
  import { thrownLabel } from "./thrown-value.js";
11
11
  import { agentStateSourceOfHandle, agentStateSummary, readAgentState } from "./agent-state.js";
@@ -367,6 +367,10 @@ export function registerBackgroundAgentLane(core, input) {
367
367
  if (core.handles.has(id))
368
368
  throw new Error(`TaskRegistry: task id already registered: ${id}`);
369
369
  const now = input.now ?? Date.now();
370
+ if (input.name !== undefined && (typeof input.name !== "string" || input.name === "")) {
371
+ throw new Error(`TaskRegistry: background-agent name must be a non-empty string (got ${JSON.stringify(input.name)}); omit it to take the derived one`);
372
+ }
373
+ const name = input.name ?? engineAgentName(id);
370
374
  core.handles.set(id, {
371
375
  id,
372
376
  type: "background_agent",
@@ -375,7 +379,7 @@ export function registerBackgroundAgentLane(core, input) {
375
379
  ...(input.resolveParkedStop !== undefined ? { resolveParkedStop: input.resolveParkedStop } : {}),
376
380
  ...(input.sessionScoped ? { sessionScoped: true } : {}),
377
381
  ...(input.description !== undefined ? { description: input.description } : {}),
378
- ...(input.name !== undefined ? { name: input.name } : {}),
382
+ name,
379
383
  ...(input.agentType !== undefined ? { agentType: input.agentType } : {}),
380
384
  ...(input.parentTaskId !== undefined ? { parentTaskId: input.parentTaskId } : {}),
381
385
  ...(input.parentSessionId !== undefined ? { parentSessionId: input.parentSessionId } : {}),
@@ -396,6 +400,7 @@ export function registerBackgroundAgentLane(core, input) {
396
400
  if (input.durableSeed !== undefined) {
397
401
  const seeded = structuredClone(input.durableSeed.record);
398
402
  seeded.rev = input.durableSeed.rev;
403
+ seeded.name = name;
399
404
  handle.durable = {
400
405
  store: input.store,
401
406
  record: seeded,
@@ -417,7 +422,7 @@ export function registerBackgroundAgentLane(core, input) {
417
422
  ...(input.parentSessionId !== undefined ? { parentSessionId: input.parentSessionId } : {}),
418
423
  ...(input.rootSessionId !== undefined ? { rootSessionId: input.rootSessionId } : {}),
419
424
  ...(input.parentTaskId !== undefined ? { parentTaskId: input.parentTaskId } : {}),
420
- ...(input.name !== undefined ? { name: input.name } : {}),
425
+ name,
421
426
  ...(input.agentType !== undefined ? { agentType: input.agentType } : {}),
422
427
  ...(input.description !== undefined ? { description: input.description } : {}),
423
428
  ...(input.model !== undefined ? { model: input.model } : {}),
@@ -892,7 +897,7 @@ export function resolveBackgroundAgentByNameLane(core, name, access, opts) {
892
897
  };
893
898
  const named = [];
894
899
  for (const h of core.handles.values()) {
895
- if (h.type !== "background_agent" || h.name === undefined || !canAccess(h, access))
900
+ if (h.type !== "background_agent" || !canAccess(h, access))
896
901
  continue;
897
902
  if (h.name === name || normalizeAgentName(h.name) === key)
898
903
  named.push(h);
@@ -902,7 +907,7 @@ export function resolveBackgroundAgentByNameLane(core, name, access, opts) {
902
907
  if (namedRunning.length > 1) {
903
908
  return {
904
909
  status: "ambiguous",
905
- message: `Multiple RUNNING background agents match "${name}": ${namedRunning.map((h) => `${h.id} (${h.name ?? h.description ?? "unnamed"})`).join(", ")}. Use the task ID.`,
910
+ message: `Multiple RUNNING background agents match "${name}": ${namedRunning.map((h) => `${h.id} (${h.name})`).join(", ")}. Use the task ID.`,
906
911
  };
907
912
  }
908
913
  if (namedRunning.length === 1)
@@ -1256,7 +1261,7 @@ export function runningBackgroundAgentLabelsLane(core, access) {
1256
1261
  for (const h of core.handles.values()) {
1257
1262
  if (h.type !== "background_agent" || h.status !== "running" || !canAccess(h, access))
1258
1263
  continue;
1259
- const label = h.name ?? h.description;
1264
+ const label = chosenAgentName(h.id, h.name) ?? h.description;
1260
1265
  out.push(label ? `${h.id} (${label})` : h.id);
1261
1266
  }
1262
1267
  return out;
@@ -1267,8 +1272,9 @@ export function runningAgentFooterLane(core, access) {
1267
1272
  for (const h of core.handles.values()) {
1268
1273
  if (h.type !== "background_agent" || h.status !== "running" || !canAccess(h, access))
1269
1274
  continue;
1270
- if (h.name !== undefined && h.name !== "") {
1271
- named.push(h.name);
1275
+ const chosen = chosenAgentName(h.id, h.name);
1276
+ if (chosen !== undefined) {
1277
+ named.push(chosen);
1272
1278
  continue;
1273
1279
  }
1274
1280
  background.push(h.description ? `${h.id} (${h.description})` : h.id);
@@ -321,11 +321,12 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
321
321
  reason: "not_found" | "not_running" | "no_channel";
322
322
  }) => void) | undefined)?
323
323
  ]>;
324
- /** [c209-D] the EXPLICIT addressing name (CC Agent.name parity, validated at spawn: charset regex +
325
- * "main" reserved). Distinct from `description` (the display/legacy-matching label): the name layer
326
- * resolves latest-wins ("a newer agent took the name"), the description layers keep their
327
- * running-preferred + ambiguous posture. Absent on pre-[c209] rows and unnamed spawns. */
328
- name?: string;
324
+ /** The addressing name: the spawner's explicit one (CC Agent.name parity, validated at spawn: charset
325
+ * regex + reserved set), or — when the spawn named none — the one {@link engineAgentName} derives from
326
+ * the handle, written by the registration itself, so every background agent has exactly one. Distinct
327
+ * from `description` (the display/legacy-matching label): the name layer resolves latest-wins ("a newer
328
+ * agent took the name"), the description layers keep their running-preferred + ambiguous posture. */
329
+ name: string;
329
330
  /** design/129: this child OUTLIVES its parent turn — owner is the SESSION id; the parent-teardown reap
330
331
  * skips it; `reapSessionBackground` is its terminal anchor. Explicit flag, never inferred from key values
331
332
  * (hostTaskId===sessionId deployments would otherwise be ambiguous). */
@@ -836,6 +837,33 @@ export declare const DURABLE_AGENT_HEARTBEAT_MS = 60000;
836
837
  * durable arm (a bare exact-key miss lets padded/legacy/name-shaped ids leak into live branches —
837
838
  * the server 1.250 HIGH) — one shared regex kills the drift, roster-normalize precedent. */
838
839
  export declare const DURABLE_AGENT_HANDLE_RE: RegExp;
840
+ /**
841
+ * The name a background agent carries when its spawner named none: `agent-` + the first twelve hex
842
+ * digits of its handle (`a3fa9c2d1b7e04a15` → `agent-3fa9c2d1b7e0`; a handle with fewer digits keeps
843
+ * them all). A pure function of the handle, so the same agent id reads the same name in every process
844
+ * and every store — a host that finds a row from an earlier version without a name derives it here, it
845
+ * does not invent one.
846
+ *
847
+ * Shorter than the id's sixteen digits on purpose: a name of the SHAPE of an agent id (`a`, an optional
848
+ * `<label>-`, sixteen hex) already addresses an agent directly and is refused as a name everywhere
849
+ * (`reservedPeerNameReason`), so a minted name is an ordinary admissible name — nothing in the name
850
+ * grammar singles it out. Twelve digits (48 bits) because the name layer resolves a name to the NEWEST
851
+ * agent that holds it: two agents of one caller would have to share twelve digits of their ids to collide.
852
+ *
853
+ * The registry's registration is the one place this is called (see `registerBackgroundAgentLane`); every
854
+ * reader that needs to know whether SOMEONE chose a name goes through {@link chosenAgentName}.
855
+ */
856
+ export declare function engineAgentName(handle: string): string;
857
+ /**
858
+ * The name SOMEONE chose for an agent — `undefined` when the agent's name is the one {@link engineAgentName}
859
+ * derives from its handle (or there is none). Every agent has a name to be addressed by; only a chosen one is
860
+ * also a spawn identity (the teammate key, `spawnName` on frames, a roster entry, the unnamed-child tool pool),
861
+ * and a reader that hands a row's name back into a place that reads it as an identity — a revival's `name`
862
+ * argument, a retained resume's row name — goes through here, so an agent nobody named stays unnamed in every
863
+ * later cycle. A reader that only needs to ADDRESS the agent reads `name` as it is. A serving layer's roster reads
864
+ * "chosen vs derived" back through here from the row's handle + name — it keeps no column of its own for it.
865
+ */
866
+ export declare function chosenAgentName(handle: string, name: string | undefined): string | undefined;
839
867
  /** Synthetic settle error the subagent reap path passes after a stop/parent teardown. It is NOT a
840
868
  * real child error — settleBackgroundAgent never stores it (status "killed" + stoppedBy already say
841
869
  * it); exported so the subagent call sites and the registry agree on the exact sentinel. */
@@ -937,7 +965,9 @@ export interface RegisterBackgroundAgentInput extends TaskAccess {
937
965
  description?: string;
938
966
  /** [c209-D] explicit addressing name (CC Agent.name parity) — the CALLER validates it (charset +
939
967
  * reserved "main") before registration; the registry stores it verbatim. Duplicate names are legal
940
- * (latest-wins at resolution; older rows stay task_id-addressable). */
968
+ * (latest-wins at resolution; older rows stay task_id-addressable). ABSENT = the spawner named none:
969
+ * the registration gives the agent the name {@link engineAgentName} derives from its handle (this is
970
+ * the only place a name is minted), on the live handle and the durable row alike. */
941
971
  name?: string;
942
972
  /** the RESOLVED subagent type ("general-purpose"/"fork"/a roster name), persisted
943
973
  * so a REVIVE cycle's observer frames can reproduce the row's TYPE column (never the description). */
@@ -279,6 +279,17 @@ export function formatWorkflowRun(run) {
279
279
  }
280
280
  export const DURABLE_AGENT_HEARTBEAT_MS = 60_000;
281
281
  export const DURABLE_AGENT_HANDLE_RE = /^a[0-9a-f]{6,32}$/;
282
+ export function engineAgentName(handle) {
283
+ if (!DURABLE_AGENT_HANDLE_RE.test(handle)) {
284
+ throw new TypeError(`engineAgentName: ${JSON.stringify(handle)} is not an agent handle (expected "a" followed by 6-32 hex digits)`);
285
+ }
286
+ return `agent-${handle.slice(1, 13)}`;
287
+ }
288
+ export function chosenAgentName(handle, name) {
289
+ if (name === undefined)
290
+ return undefined;
291
+ return DURABLE_AGENT_HANDLE_RE.test(handle) && name === engineAgentName(handle) ? undefined : name;
292
+ }
282
293
  export const BG_AGENT_REAP_STOP_ERROR = "stopped (parent task ended or TaskStop)";
283
294
  export function normalizeAgentName(s) {
284
295
  return s
@@ -7,7 +7,7 @@ import { type BackgroundAgentStore } from "./background-agent-store.js";
7
7
  import type { TaskNotificationPayload } from "./task-notification.js";
8
8
  import type { ToolResultStore } from "./tool-result-store.js";
9
9
  import { type SemaTaskType, type StopSource, type SemaTaskStatus, type TaskRetrievalStatus, type UnifiedTaskOutput, type UnifiedTaskResult, type SemaTaskHandle, type TaskAccess, type BackgroundAgentTaskHandle, type MonitorTimers, type RegisterMonitorInput, type RegisterWorkflowInput, canAccessWorkflowRun, clipTaskOutput, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE } from "./task-registry-shared.js";
10
- export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR } from "./task-registry-shared.js";
10
+ export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, engineAgentName, chosenAgentName } from "./task-registry-shared.js";
11
11
  export type { ParkedClaimTicket, RegisterBackgroundAgentInput } from "./task-registry-shared.js";
12
12
  import type { RegisterBackgroundAgentInput, ParkedClaimTicket } from "./task-registry-shared.js";
13
13
  import { type AgentStateSource } from "./agent-state.js";
@@ -9,7 +9,7 @@ import { stripCwdSentinel } from "../tools/fs/fs-shared.js";
9
9
  import { registerMonitorLane, pollMonitorLane, stopMonitorLane } from "./task-registry-monitor.js";
10
10
  import { registerWorkflowLane, pollWorkflowLane, stopWorkflowLane } from "./task-registry-workflow.js";
11
11
  import { mintCompletionId, canAccessWorkflowRun, formatWorkflowRun, clipTaskOutput, assertOwnership, sleepPollStep, statusFromBackground, rollSpoolText, accountDroppedBytes, renderSpoolBody, stdoutHeadingOf, REPLAY_FACE, SPOOL_REPLAY, INCREMENT_REPLAY, spoolDropNote, droppedGapNote, alreadyTerminalStopNote, terminalTaskSummary, TASK_OUTPUT_MAX_CHARS, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccess, DURABLE_AGENT_HANDLE_RE, } from "./task-registry-shared.js";
12
- export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR } from "./task-registry-shared.js";
12
+ export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, engineAgentName, chosenAgentName } from "./task-registry-shared.js";
13
13
  import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, REGISTRY_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "./task-tool-shape.js";
14
14
  import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, noteBackgroundAgentActivityLane, reapStaleSessionBackgroundAgentsLane, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, registerBackgroundAgentLane, recordBackgroundAgentOrgAdmissionLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, backgroundAgentCycleSeqLane, activeDelegationHandlesLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, runningAgentFooterLane, notFoundRunningAgentsTail, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
15
15
  import { mountRuleFace, toolFace } from "./tool-catalog-entries.js";
@@ -111,6 +111,22 @@ export interface TaskSpec {
111
111
  * honest one, because `hostAsserted` states whether the identity was ingress-derived.
112
112
  */
113
113
  actor?: ActorAssertion;
114
+ /**
115
+ * What started this task, when the host says so ({@link import("./run-origin.js").RunOrigin}): `"scheduled"` = the
116
+ * deployment's scheduler (cron, heartbeat, delayed wake-up, stored routine) fired an intent stored earlier — nobody submitted
117
+ * it just now. Absent = the host said nothing (never read as "a person sent it"). Attribution only, exactly like
118
+ * {@link actor}: no permission, approval, mode or scope decision reads it, and it never enters the model's context.
119
+ *
120
+ * It is the word of the objective, the input that opens the task's first leg: that leg's `wiring_manifest` reports it
121
+ * (`leg.runOrigin`), the objective's `human_input` frame and its message carry it, and a checkpoint the leg parks records it
122
+ * (`CheckpointSummary.runOrigin`). A resumed leg continues the row's word unless a wake opens it (with the newest input the
123
+ * wake hands over, which states its own); a resume config carries NO word — any value is refused, before the claim. A
124
+ * delegated child does not inherit it. A value outside the set is refused at the door (`config.run_origin_invalid`).
125
+ *
126
+ * 🔴 Trust contract: set it ONLY at the deployment's own scheduler fire path — never copy it from a request body, or any
127
+ * caller can mark its run as scheduled and the audit face reads the claim as the host's. The engine cannot verify it.
128
+ */
129
+ runOrigin?: import("./run-origin.js").RunOrigin;
114
130
  /**
115
131
  * design/173 §3/§8.3 — the caller's DECLARED interaction posture for this run. `"interactive"`
116
132
  * asserts a live human is reachable and makes prepare REFUSE the leg (fail-loud
@@ -178,6 +194,14 @@ export interface TaskSpec {
178
194
  userAttachments?: readonly UserAttachment[];
179
195
  /** Reuse an existing in-memory session for chat continuity; omit to start fresh. */
180
196
  sessionId?: string;
197
+ /**
198
+ * The project the host files this session under — a project UUID (the id a `.sema/project` marker carries; send it on
199
+ * every leg). The engine has ONE judge of a leg's project identity: when the leg's checkout carries a marker, the marker
200
+ * decides and this value must EQUAL it (else the leg is refused, `config.project_identity_mismatch`); in a checkout with
201
+ * no marker this value IS the identity. Not a UUID ⇒ `config.project_id_invalid`. The verdict rides
202
+ * `workspace_changed.project`; read it there rather than re-deriving it. Memory keys only by the marker.
203
+ */
204
+ projectId?: string;
181
205
  /**
182
206
  * design/114 Phase3 — with `sessionId` set, REQUIRE that session to already exist: if it is gone (e.g. a
183
207
  * non-durable store lost it across a restart, or a typo'd id), the run FAILS LOUD (`resume.session_not_found`)
@@ -972,6 +996,19 @@ export interface TaskSpec {
972
996
  * `requestReview` is a no-op). The tool is a thin composition over the general `requestReview` primitive.
973
997
  */
974
998
  enablePlanMode?: boolean;
999
+ /**
1000
+ * The absolute path of THIS session's plan file in the leg's execution environment (the reference's `<plans dir>/<slug>.md`).
1001
+ * Where the plan lives is one fact: declared, the plan is that file — admitted by the advertised-writable seat (its third
1002
+ * advertiser), so the file tools' root fence (write + read) and every mode's write gate admit it without a question, the
1003
+ * write-protection table does not demote it, `ExitPlanMode` takes no `plan` and reads it, and the planning frames name it;
1004
+ * absent, the plan is `ExitPlanMode`'s `plan` argument and no plan file exists (byte-identical to a run before this seat).
1005
+ * The fence and write gates admit the path and anything beneath it until #2746 (KL-1503-a); the table exempts exactly the
1006
+ * file; siblings, a link swapped in later and every deny row stay as they were. The host creates the file's directory
1007
+ * before the run. Refused with `config.plan_file_invalid` (the run never starts): not an absolute string in lexical normal
1008
+ * form that the model can be told verbatim; a link, directory or other non-file leaf; a parent that is not a directory;
1009
+ * hands absent or read-only; a key holding a fence root. Not inherited by a delegated child, a fork or a workflow step.
1010
+ */
1011
+ planFile?: string;
975
1012
  /**
976
1013
  * Interactive-tool mounting override (AskUserQuestion / ExitPlanMode /
977
1014
  * EnterPlanMode share one `isEnabled` gate — in non-interactive mode without an SDK permission-prompt
@@ -53,7 +53,8 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
53
53
  * evidence of a replay, and two callers colliding on one id must not silently lose the second
54
54
  * (the parked leg's `appendPendingSteer` judges and refuses it identically). The error carries
55
55
  * `detail.differs` — the facets that differ (closed `STEER_REPLAY_FACETS`: `text`, `trusted`,
56
- * `priority`, `actor`), compared on what the caller SENT, never on the framed bytes. With `text`
56
+ * `priority`, `actor`, `runOrigin` — this verb takes no run origin, so a repeat here never differs in it),
57
+ * compared on what the caller SENT, never on the framed bytes. With `text`
57
58
  * among them it is another instruction: re-issue it under a fresh id. Without, it is the accepted one
58
59
  * re-sent at another tier / trust / attribution, which acceptance does not change: a fresh id would
59
60
  * queue it twice, so replay it with its original values to confirm the receipt.
@@ -210,7 +210,7 @@ export type TerminalFailureDetail = {
210
210
  * The thrown error's own `detail`, as its throw site stated it — a snapshot of its JSON-plain members (strings,
211
211
  * finite numbers, booleans, null, and arrays / plain objects of those, bounded; a member of any other kind is left
212
212
  * out; bytes — an `ArrayBuffer` view, an index-keyed object — are never a record). A member under a credential
213
- * name (the env-credential judge's names: `password`, `apiKey`, `token` …) stands as `"[redacted]"`, unread; every
213
+ * name (the env-credential judge's names: `password`, `apiKey`, `token` …) stands as the redaction mark (`REDACTION_MARK`), unread; every
214
214
  * other string leaf passes the secret-tier redaction (credential shapes masked; a path is kept — it rides this
215
215
  * structured seat, never `message`); a member whose key is not JSON-safe (visible ASCII 1–128, nothing the
216
216
  * redaction would mask) is left out. Read off the same link of the error's `cause` chain whose `code` became
@@ -71,6 +71,12 @@ export declare const isEngineShellFace: (face: {
71
71
  readonly engineMounted?: true;
72
72
  readonly contractId: string;
73
73
  } | undefined) => boolean;
74
+ /** Is this call's face one of the content-routing tools the engine mounts (question, answer, blocked report)? They route content,
75
+ * act on nothing, and no stored rule governs them: the persisted-rule lane does not judge them and their card offers no rule. */
76
+ export declare const routesContent: (face: {
77
+ readonly engineMounted?: true;
78
+ readonly contractId: string;
79
+ } | undefined) => boolean;
74
80
  /**
75
81
  * The rule face a definition whose schema is BUILT PER MOUNT puts on its instance: its row's primaries only (none ⇒ no rule
76
82
  * face). The row's `params` is the static view's vocabulary, the fullest mount's; a mount's own is read off the schema it
@@ -139,6 +139,7 @@ export const TOOL_CATALOG_ENTRIES = [
139
139
  { id: "advisor", name: "advisor", source: "builtin", definedIn: "src/core/runner/advisor-tool.ts", mountedBy: ["optional"], cards: ["advisor"], face: { family: "scaffold", boundaryLegs: [], effect: "read", contentOrigin: "local", contract: c("core.advisor@1"), offload: false, budgetExempt: true, ruleFace: { params: [] } } },
140
140
  { id: "ask-user-question", name: "AskUserQuestion", source: "builtin", definedIn: "src/core/ask-question.ts", mountedBy: ["optional"], cards: ["ask-question"], face: { family: "other", boundaryLegs: [], effect: "read", contract: c("core.ask_user_question@1"), renderHints: { approvalCard: "question" }, ruleFace: { params: [] } } },
141
141
  { id: "exit-plan-mode", name: "ExitPlanMode", source: "builtin", definedIn: "src/core/present-plan-tool.ts", mountedBy: ["optional"], cards: ["exit-plan-mode"], face: { family: "plan", boundaryLegs: [], effect: "read", contract: c("core.exit_plan_mode@1"), renderHints: { userFacingName: "", approvalCard: "plan" }, ruleFace: { params: ["plan"] } } },
142
+ { id: "exit-plan-mode-file", name: "ExitPlanMode", source: "builtin", definedIn: "src/core/present-plan-tool.ts", mountedBy: ["optional"], cards: ["exit-plan-mode"], face: { family: "plan", boundaryLegs: [], effect: "read", contract: c("core.exit_plan_mode_file@1"), renderHints: { userFacingName: "", approvalCard: "plan" }, ruleFace: { params: [] } } },
142
143
  { id: "enter-plan-mode", name: "EnterPlanMode", source: "builtin", definedIn: "src/core/present-plan-tool.ts", mountedBy: ["optional"], cards: ["enter-plan-mode"], face: { family: "plan", boundaryLegs: [], effect: "read", contract: c("core.enter_plan_mode@1"), ruleFace: { params: [] } } },
143
144
  { id: "refresh-mcp-tools", name: REFRESH_MCP_TOOLS_TOOL_NAME, source: "builtin", definedIn: "src/core/runner/prepare-protocol-tools.ts", mountedBy: ["optional"], cards: [], face: { family: "protocol", boundaryLegs: ["outside_read"], effect: "read", ruleFace: { params: ["server"] } } },
144
145
  { id: "memory-search", name: "memory_search", source: "builtin", definedIn: "src/core/memory-engine/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", boundaryLegs: [], effect: "read", contentOrigin: "local", contract: c("core.memory_search@1", "7"), offload: false, ruleFace: { params: ["query", "limit", "includeSuperseded", "includeShadowed"] } } },
@@ -207,6 +208,7 @@ export function engineMountedAs(ids) {
207
208
  return (face) => face?.engineMounted === true && contracts.has(face.contractId);
208
209
  }
209
210
  export const isEngineShellFace = engineMountedAs(["bash", "bash-readonly"]);
211
+ export const routesContent = engineMountedAs(["ask-user-question", "structured-output", "report-blocked"]);
210
212
  export function mountRuleFace(id) {
211
213
  const primaryParams = toolFace(id).ruleFace?.primaryParams;
212
214
  return primaryParams === undefined ? undefined : { primaryParams: [...primaryParams] };
@@ -16,8 +16,8 @@ import type { RuleBehavior } from "./permission-rule-model.js";
16
16
  * with the successor, where any other unknown name stays the generic roster miss.
17
17
  *
18
18
  * What REMAINS is validation data: {@link RETIRED_TOOL_NAMES} maps every name the engine ever
19
- * retired to a one-line guidance string, and {@link judgeRuleToolName} is the ONE reading of it a rule's
20
- * tool name gets. They exist because deleting the mapping flips stale POLICY entries from "silently
19
+ * retired to a one-line guidance string, and {@link judgeRuleToolName} is the ONE judgment of it a rule's
20
+ * tool name gets ({@link toolNameFaultOf} adds the near-miss step: the one reading). They exist because deleting the mapping flips stale POLICY entries from "silently
21
21
  * matched" to "silently matches nothing" — and for a deny/requireApproval entry that direction WIDENS
22
22
  * the surface. `validatePermissionRules` (permission-rules.ts) does NOT classify retired names itself:
23
23
  * which names a deployment mounts its OWN tool under is a roster fact, and the judgment takes the roster.
@@ -100,6 +100,36 @@ export declare function grantWildcardRefusalOf(name: string): string | undefined
100
100
  * as a glob ({@link readsNameGlob}) — such a name outside every namespace, or with a glob in its peer segment, is a pattern and
101
101
  * `current`; with `allow` or none a wildcard peer names no peer and is `unmintable_segment`. */
102
102
  export declare function judgeRuleToolName(name: string, roster: ReadonlySet<string>, behavior?: RuleBehavior): RuleToolNameVerdict;
103
+ /**
104
+ * THE near-miss reading of a tool name the judgment calls current: the spelling the roster carries when it carries no tool of this
105
+ * exact name but one that differs from it only by case (`BASH` beside `Bash`), else `undefined`. Two kinds of name are never a near
106
+ * miss, because the roster they would be read against is not the final one: an engine tool's (the engine mounts some of its tools
107
+ * after a list is read) and a protocol tool's (a refresh mounts and unmounts them while the run goes on) — in both the exact
108
+ * spelling can be the right one by the time it matters. Every station that asks "is this name a case twin of a carried tool" reads
109
+ * this answer: an entry list and the persisted grammar's whole-tool rule through {@link toolNameFaultOf}, and a tool policy's name
110
+ * lists (the prepare-time policy-name audit, which reads two rosters and skips an inherited layer) directly.
111
+ */
112
+ export declare function nearMissSpellingOf(name: string, roster: ReadonlySet<string>): string | undefined;
113
+ /** What {@link toolNameFaultOf} finds wrong with a rule's tool name: the judgment's stale words (`tool_name`, with the verdict and
114
+ * its facts), or another spelling of a carried tool (`near_miss`, the spelling to write). */
115
+ export type ToolNameFault = {
116
+ readonly reason: "tool_name";
117
+ readonly verdict: Exclude<RuleToolNameVerdict["kind"], "current">;
118
+ readonly guidance?: string;
119
+ readonly currentName?: string;
120
+ } | {
121
+ readonly reason: "near_miss";
122
+ readonly currentName: string;
123
+ };
124
+ /**
125
+ * THE ONE reading of a rule's tool name against a roster — the name judgment's stale words, then, for a name the judgment calls
126
+ * current but the roster does not carry exactly, whether the roster carries it under another case ({@link nearMissSpellingOf}).
127
+ * `undefined` = no fault: the name is carried, or nothing carried is another spelling of it. A name the roster simply does not
128
+ * carry is silent: a tool of that name may be mounted later, and a list shared across runs is not wrong because one run lacks a
129
+ * tool. A list entry (`readRuleEntry`) and a stored whole-tool rule (`parseRuleText`) read a name through this and nothing else;
130
+ * the policy-name audit composes the same two steps itself over two rosters (a candidate to fold in).
131
+ */
132
+ export declare function toolNameFaultOf(name: string, roster: ReadonlySet<string>, behavior: RuleBehavior | undefined): ToolNameFault | undefined;
103
133
  /** The two kinds of tool-name miss — a closed set. `unknown`: the name is none the engine ever mounted (a typo, a
104
134
  * guess). `expected-absent`: the name is one the engine RETIRED ({@link RETIRED_TOOL_NAMES}), so its absence is no
105
135
  * surprise and the table says what replaced it (the reference spells the same two words for its render-time miss). */
@@ -1,5 +1,6 @@
1
1
  import { carriesNamespaceSeparator, protocolOf } from "./protocol-table.js";
2
2
  import { mintNamespacePrefix } from "./protocol-naming.js";
3
+ import { catalogToolNames } from "./tool-registry.js";
3
4
  export const RETIRED_TOOL_NAMES = new Map([
4
5
  ["read_file", 'renamed "Read"'],
5
6
  ["edit_file", 'renamed "Edit"'],
@@ -98,6 +99,28 @@ export function judgeRuleToolName(name, roster, behavior) {
98
99
  return carriesNamespaceSeparator(name) && !(readsNameGlob(behavior) && name.includes("*")) ? UNPREFIXED : CURRENT;
99
100
  return unmintableSegmentOf(split, behavior) ?? CURRENT;
100
101
  }
102
+ function mountedSpellingOf(name, roster) {
103
+ const folded = name.toLowerCase();
104
+ for (const mounted of roster)
105
+ if (mounted.toLowerCase() === folded)
106
+ return mounted;
107
+ return undefined;
108
+ }
109
+ export function nearMissSpellingOf(name, roster) {
110
+ if (roster.has(name) || catalogToolNames().has(name) || splitNamespacedName(name) !== undefined)
111
+ return undefined;
112
+ return mountedSpellingOf(name, roster);
113
+ }
114
+ export function toolNameFaultOf(name, roster, behavior) {
115
+ const verdict = judgeRuleToolName(name, roster, behavior);
116
+ if (verdict.kind === "unprefixed_namespace")
117
+ return { reason: "tool_name", verdict: verdict.kind };
118
+ if (verdict.kind !== "current") {
119
+ return { reason: "tool_name", verdict: verdict.kind, guidance: verdict.guidance, ...(verdict.currentName !== undefined ? { currentName: verdict.currentName } : {}) };
120
+ }
121
+ const mounted = nearMissSpellingOf(name, roster);
122
+ return mounted === undefined ? undefined : { reason: "near_miss", currentName: mounted };
123
+ }
101
124
  export const TOOL_MISS_KINDS = Object.freeze(["unknown", "expected-absent"]);
102
125
  const [UNKNOWN_MISS, ABSENT_MISS] = TOOL_MISS_KINDS;
103
126
  export function judgeToolNameMiss(name, roster) {
@@ -127,6 +127,10 @@ export declare const NAME_READINGS: {
127
127
  readonly kind: "any";
128
128
  readonly file: string;
129
129
  };
130
+ readonly "policy.persistedToolRule": {
131
+ readonly kind: "any";
132
+ readonly file: string;
133
+ };
130
134
  readonly "policy.sensitivePathGuardedByName": {
131
135
  readonly kind: "any";
132
136
  readonly file: string;
@@ -33,6 +33,7 @@ export const NAME_READINGS = {
33
33
  "gate.skillActivationSeat": wire(GATE),
34
34
  "policy.permissionRules": any("src/core/permission-rules.ts"),
35
35
  "policy.persistedGrammar": any("src/core/permission-rule-model.ts"),
36
+ "policy.persistedToolRule": any("src/core/permission-rule-model.ts"),
36
37
  "policy.sensitivePathGuardedByName": any("src/core/sensitive-path-policy.ts"),
37
38
  "floor.protectivePathTarget": seat("member", "src/core/tool-registry.ts"),
38
39
  "floor.protectiveHostTarget": seat("member", "src/core/host-target.ts"),
@@ -1125,7 +1125,8 @@ export declare function createUnverifiableDeletePolicy(opts?: {
1125
1125
  export declare function createTranscriptIntegrityPolicy(opts?: {
1126
1126
  /** Transcript directories to protect. Default: `($AGENT_DATA_DIR ?? ~/.ai-agent)/sessions`. */
1127
1127
  sessionsDirs?: readonly string[];
1128
- /** argv[0] allowlist for read-only access to the transcript dir (default {@link BASH_READONLY_DEFAULT_ALLOW}). */
1128
+ /** The programs a read-only command over the transcript dir may run (default {@link BASH_READONLY_DEFAULT_ALLOW}); it only
1129
+ * narrows the read-only reader — a listed program whose call writes still asks. */
1129
1130
  readAllow?: readonly string[];
1130
1131
  /** Override the shell tool names this gate parses (default {@link COARSE_SHELL_TOOLS}, the shell face). */
1131
1132
  tools?: string[];
@@ -1328,13 +1329,16 @@ export interface AskRequest {
1328
1329
  * command whose exact form the validator refuses offers nothing rather than promoting a lone
1329
1330
  * prefix to index 0 — see `suggestRulesForCommand`). The seat says "this card has no rule to
1330
1331
  * offer you", which is true of both; it does not claim the grammar is empty, and a surface must
1331
- * not word it as though no rule could ever be written for the command.
1332
+ * not word it as though no rule could ever be written for the command. It is also the word of a
1333
+ * card whose tool's form mints no offer: a path tool's, a shell-face sibling's, and a tool that
1334
+ * answers to one of those under an alias.
1332
1335
  *
1333
1336
  * ABSENT is not a claim, exactly as {@link previewWithheld}'s absence is not: it also covers the
1334
- * ordinary "there are offers" case and the three STRUCTURAL doors that answer with silence on
1335
- * purpose (no rule lane wired, a tool the lane does not speak for, a task that cannot hold a rule at
1336
- * all) — a reason line on every ask of a deployment that never had the feature would be noise about
1337
- * a lane that does not exist. Read presence, never absence.
1337
+ * ordinary "there are offers" case and the STRUCTURAL door that answers with silence on purpose — no
1338
+ * rule speaks for this call: no rule lane wired, a task that cannot hold a rule at all, or a call the
1339
+ * lane does not judge (a content-routing tool the engine mounts) — a reason line on every ask of a
1340
+ * deployment that never had the feature would be noise about a lane that does not exist. Read
1341
+ * presence, never absence.
1338
1342
  *
1339
1343
  * ADVISORY disclosure metadata, never adjudication input: it changes nothing about what is allowed,
1340
1344
  * and a surface that ignores it renders exactly the card it rendered before. The durable park row
@@ -12,6 +12,7 @@ export { policyCannotAnswer, rowDemandsAPerson } from "./real-approval.js";
12
12
  import { sanitizeAutoModeArmingRecipe } from "./auto-mode-arming.js";
13
13
  import { join, normalize as normalizePath, sep } from "node:path";
14
14
  import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
15
+ import { readOnlyShellVerdict } from "./read-only-shell.js";
15
16
  import { protectivePathTargetOf, shellFaceToolNames } from "./tool-registry.js";
16
17
  import { heldBy } from "./tool-name-readings.js";
17
18
  import { bindableValueOf, boundInputHashOf, describeBindingFault, exactBoundInputHashOf } from "./canonical-json.js";
@@ -830,14 +831,10 @@ export function createTranscriptIntegrityPolicy(opts) {
830
831
  const cwdInsideProtected = req.cwd !== undefined && inProtectedDir(req.cwd);
831
832
  if (!referencesProtectedDir(cmd) && !cwdInsideProtected)
832
833
  return ALLOW;
833
- const parsed = parseLeadingCommandName(command);
834
- if ("name" in parsed && readAllow.has(parsed.name))
834
+ const verdict = readOnlyShellVerdict(command, { cwd: req.cwd, readers: readAllow });
835
+ if (verdict.readOnly)
835
836
  return ALLOW;
836
- return askReason(req, "name" in parsed
837
- ? `\`${parsed.name}\` is not a read-only command${cwdInsideProtected ? " and the shell's working directory is inside the transcript directory" : ""}`
838
- : cwdInsideProtected
839
- ? "the shell's working directory is inside the transcript directory and this is not a single read-only command (fail-closed)"
840
- : "the command references the transcript directory and is not a single read-only command (fail-closed)");
837
+ return askReason(req, `${cwdInsideProtected ? "the shell's working directory is inside the transcript directory" : "the command references the transcript directory"} and is not read-only: ${verdict.reason}`);
841
838
  }
842
839
  const writeTarget = protectivePathTargetOf(req);
843
840
  if (writeTarget !== undefined && writeTarget.access !== "read") {
@@ -1,4 +1,5 @@
1
1
  import type { AgentTool } from "../internal/harness-types.js";
2
+ import { type RetentionDeclaration } from "./retention.js";
2
3
  /**
3
4
  * Pluggable backing store for **offloaded large tool results** (design/30). When a tool returns more
4
5
  * text than the threshold, the full content is moved here and the conversation keeps only a preview +
@@ -12,13 +13,14 @@ import type { AgentTool } from "../internal/harness-types.js";
12
13
  */
13
14
  export interface ToolResultStore {
14
15
  /**
15
- * Managed-retention declaration (ruled 2026-08-05, retention.ts): `"managed"` promises the
16
- * `ManagedRetentionCapability` contract (scheduled, tenant-scoped, audited deletion); `"none"` (or
17
- * ABSENT — read fail-closed as `"none"`) states the store cannot delete on schedule. A deployment
18
- * with a LOCKED retention policy refuses to start over a `"none"` store. Declaration, never
19
- * duck-typing.
16
+ * Managed-retention declaration (retention.ts): `"managed"` says this store's rows are deleted on
17
+ * schedule by the deployment (a `ManagedRetentionCapability` executor — scheduled, tenant-scoped,
18
+ * audited deletion — runs over them); `"none"` (or ABSENT — read fail-closed as `"none"`) says
19
+ * nothing deletes them on schedule. The party that runs the sweep states it when it constructs the
20
+ * store. A deployment with a LOCKED retention policy refuses to start over a `"none"` store.
21
+ * Declaration, never duck-typing.
20
22
  */
21
- readonly retention?: import("./retention.js").RetentionDeclaration;
23
+ readonly retention?: RetentionDeclaration;
22
24
  /**
23
25
  * Persist full content under a stable `ref`. **Write-once and idempotent**: if `ref` already exists,
24
26
  * keep the existing content and do nothing (the aggregate budget re-runs every query with the same
@@ -110,8 +112,9 @@ export interface ToolResultStore {
110
112
  * callback (a checkable fact, not a failure). Present ⇒ the store can complete a session
111
113
  * deletion; absent ⇒ the deployment owns that gap.
112
114
  *
113
- * Implementing it does NOT make a store `retention: "managed"` — that declaration promises the whole
114
- * {@link import("./retention.js").ManagedRetentionCapability} (domain enumeration, tombstones,
115
+ * Implementing it does NOT make a store `retention: "managed"` — that declaration says the
116
+ * deployment deletes this store's rows on schedule through a whole
117
+ * {@link import("./retention.js").ManagedRetentionCapability} executor (domain enumeration, tombstones,
115
118
  * audit receipts, scheduled execution), of which this is one caller-driven erase.
116
119
  */
117
120
  deleteBySession?(sessionId: string): Promise<ToolResultDeletionReport> | ToolResultDeletionReport;
@@ -318,14 +321,18 @@ export interface ToolResultSlice {
318
321
  * store (e.g. FileToolResultStore) via `RunnerDeps.toolResultStore`. */
319
322
  export declare class InMemoryToolResultStore implements ToolResultStore {
320
323
  private readonly opts?;
321
- /** put/get only — no scheduled deletion contract: honestly `"none"` (retention.ts). */
322
- readonly retention: "none";
324
+ /** Managed-retention declaration (retention.ts): whether this store's rows are deleted on schedule by the deployment — given by
325
+ * the party that runs the sweep (the `retention` option), `"none"` when none is given; the store itself is put/get only. */
326
+ readonly retention: RetentionDeclaration;
323
327
  /** The entry is content AND owner as ONE value — the write-once election that decides the
324
328
  * content decides the owner in the same step (no window where an entry exists ownerless). */
325
329
  private readonly map;
326
330
  private totalChars;
331
+ /** @param opts.retention the store's managed-retention declaration, default `"none"`; a word other than the two is refused
332
+ * (`config.retention_capability`). */
327
333
  constructor(opts?: {
328
334
  maxTotalChars?: number;
335
+ retention?: RetentionDeclaration;
329
336
  } | undefined);
330
337
  put(ref: string, content: string, provenance?: ToolResultProvenance): void;
331
338
  /** The owner recorded at the winning write; `undefined` for unknown AND for unowned entries,
@@ -6,6 +6,7 @@ import { deliverEngineNotice } from "./types.js";
6
6
  import { TOOL_SEARCH_NAME } from "./runner/tool-disclosure.js";
7
7
  import { mountRuleFace, toolFace } from "./tool-catalog-entries.js";
8
8
  import { thrownText } from "./thrown-value.js";
9
+ import { readRetentionDeclaration } from "./retention.js";
9
10
  import { carryNotStartedReceipt } from "./delegation-not-started.js";
10
11
  export const TOOL_RESULT_REF_CONFLICT_CODE = "tool_result.ref_conflict";
11
12
  export class ToolResultRefConflictError extends Error {
@@ -67,11 +68,12 @@ function digestOfString(s) {
67
68
  }
68
69
  export class InMemoryToolResultStore {
69
70
  opts;
70
- retention = "none";
71
+ retention;
71
72
  map = new Map();
72
73
  totalChars = 0;
73
74
  constructor(opts) {
74
75
  this.opts = opts;
76
+ this.retention = readRetentionDeclaration("InMemoryToolResultStore.retention", opts?.retention);
75
77
  const cap = opts?.maxTotalChars;
76
78
  if (cap !== undefined && Number.isNaN(cap)) {
77
79
  throw new Error("InMemoryToolResultStore: maxTotalChars must be a number (got NaN) — omit it for an unbounded store");
@@ -984,5 +984,8 @@ export type TraceEvent = {
984
984
  * await it; the default (absent) hook is a no-op the JIT can elide. Must not throw or do sync I/O.
985
985
  */
986
986
  export type TracerHook = (e: TraceEvent) => void;
987
- /** Invoke a tracer without ever letting it break the task (absent → no-op; throws swallowed). */
987
+ /** Invoke a tracer without ever letting it break the task (absent → no-op; throws swallowed). A frame is the engine's own account: it
988
+ * leaves minted HERE, the one throat — every string leaf through the same-principal tier's text pass, member names as written
989
+ * (`egressAccount`) — so a frame that carries a host's, a store's or a remote's words (a thrown text, a failure reason) needs no
990
+ * remembering at its mint site. */
988
991
  export declare function emitTrace(tracer: TracerHook | undefined, build: () => TraceEvent): void;
@@ -1,8 +1,9 @@
1
+ import { egressAccount } from "./untrusted-egress.js";
1
2
  export function emitTrace(tracer, build) {
2
3
  if (!tracer)
3
4
  return;
4
5
  try {
5
- tracer(build());
6
+ tracer(egressAccount("same-principal", build()));
6
7
  }
7
8
  catch {
8
9
  }
@@ -23,7 +23,7 @@ export { DECLARATION_PATH_RULES, NO_DECLARATION_PATH_RULES, dataKind, declaratio
23
23
  export type { TaskLimits } from "./task-limits.js";
24
24
  export type { TaskStatus, RemoteEnvFailureNote, EffectiveMemoryScopes, TaskResult, HumanReviewGateRow } from "./task-result.js";
25
25
  export type { TerminalCause, PausedCause } from "./terminal-cause.js";
26
- export type { TaskEventIdentity, BrainStatusPhase, BrainRetryErrClass, BrainStatus, ToolActivity, HumanInputSource, HumanInputDelivery, DelegationTaskType, TaskEvent, HumanInputEvent, HumanInputAttachment, CompactOutcome, ExtensionRequester } from "./task-event.js";
26
+ export type { TaskEventIdentity, BrainStatusPhase, BrainRetryErrClass, BrainStatus, ToolActivity, HumanInputSource, HumanInputDelivery, DelegationTaskType, TaskEvent, HumanInputEvent, HumanInputAttachment, CompactOutcome, ExtensionRequester, RewriteAuthor, ToolInputRewrite } from "./task-event.js";
27
27
  export type { TaskStream } from "./task-stream.js";
28
28
  export type { WorkflowGovernanceBaseline, RuntimeCaps, AutoModeDenySource } from "./runtime-caps.js";
29
29
  export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js";