@sema-agent/core 7.60.0 → 7.61.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 (482) hide show
  1. package/CHANGELOG.md +605 -0
  2. package/README.md +2 -2
  3. package/dist/agents/agent-transcript-tool.d.ts +2 -2
  4. package/dist/agents/agent-transcript-tool.js +1 -1
  5. package/dist/agents/cascade.d.ts +61 -10
  6. package/dist/agents/cascade.js +60 -20
  7. package/dist/agents/composition-allowance.d.ts +53 -0
  8. package/dist/agents/composition-allowance.js +49 -0
  9. package/dist/agents/composition-placement.d.ts +29 -0
  10. package/dist/agents/composition-placement.js +24 -0
  11. package/dist/agents/cumulative-stats.d.ts +4 -0
  12. package/dist/agents/cumulative-stats.js +3 -0
  13. package/dist/agents/inherited-tool-pool.d.ts +5 -3
  14. package/dist/agents/inherited-tool-pool.js +2 -2
  15. package/dist/agents/list-agents-tool.d.ts +1 -1
  16. package/dist/agents/peer-notice-route.d.ts +1 -1
  17. package/dist/agents/peer-notice-route.js +4 -3
  18. package/dist/agents/peer-notices.d.ts +4 -4
  19. package/dist/agents/peer-notices.js +8 -4
  20. package/dist/agents/peer-session-drain.d.ts +8 -1
  21. package/dist/agents/peer-session-drain.js +36 -7
  22. package/dist/agents/repair-loop.js +16 -6
  23. package/dist/agents/retain-ledger.js +3 -1
  24. package/dist/agents/roster-store.d.ts +1 -1
  25. package/dist/agents/roster-store.js +7 -4
  26. package/dist/agents/send-message-tool.d.ts +8 -10
  27. package/dist/agents/send-message-tool.js +43 -23
  28. package/dist/agents/subagent-completion-gate.d.ts +35 -0
  29. package/dist/agents/subagent-completion-gate.js +62 -0
  30. package/dist/agents/subagent-steps.d.ts +7 -6
  31. package/dist/agents/subagent.d.ts +30 -40
  32. package/dist/agents/subagent.js +187 -196
  33. package/dist/agents/suspend-guard.d.ts +9 -0
  34. package/dist/agents/suspend-guard.js +4 -0
  35. package/dist/agents/verify.d.ts +41 -14
  36. package/dist/agents/verify.js +37 -27
  37. package/dist/brain/anthropic.js +1 -0
  38. package/dist/brain/errors.d.ts +7 -1
  39. package/dist/brain/errors.js +6 -0
  40. package/dist/brain/failover.js +2 -1
  41. package/dist/brain/open-responses.js +1 -0
  42. package/dist/brain/openai.js +1 -0
  43. package/dist/brain/provider-dialect.d.ts +10 -0
  44. package/dist/brain/provider-dialect.js +13 -2
  45. package/dist/brain/stream-engine.d.ts +3 -0
  46. package/dist/brain/stream-engine.js +4 -0
  47. package/dist/core/agent-state.d.ts +1 -1
  48. package/dist/core/allow-entry.d.ts +59 -23
  49. package/dist/core/allow-entry.js +131 -38
  50. package/dist/core/ask-origin.d.ts +79 -0
  51. package/dist/core/ask-origin.js +76 -0
  52. package/dist/core/ask-question.d.ts +19 -13
  53. package/dist/core/ask-question.js +8 -2
  54. package/dist/core/auto-compaction.d.ts +2 -0
  55. package/dist/core/auto-compaction.js +2 -1
  56. package/dist/core/auto-mode.js +3 -5
  57. package/dist/core/background-agent-store.d.ts +7 -5
  58. package/dist/core/background-agent-store.js +12 -11
  59. package/dist/core/checkpoint-requirements.d.ts +24 -3
  60. package/dist/core/checkpoint-requirements.js +9 -1
  61. package/dist/core/checkpoint-store.d.ts +78 -19
  62. package/dist/core/checkpoint-store.js +8 -4
  63. package/dist/core/child-clamp-seats.d.ts +3 -2
  64. package/dist/core/child-clamp-seats.js +4 -3
  65. package/dist/core/closest-name.d.ts +13 -0
  66. package/dist/core/closest-name.js +35 -0
  67. package/dist/core/context-settings.js +3 -5
  68. package/dist/core/cross-boundary-taint.d.ts +1 -1
  69. package/dist/core/decision-receipt.d.ts +14 -1
  70. package/dist/core/decision-receipt.js +6 -3
  71. package/dist/core/delegation-frames.d.ts +13 -9
  72. package/dist/core/effective-path-target.js +2 -3
  73. package/dist/core/engine-attestation.d.ts +11 -1
  74. package/dist/core/engine-attestation.js +2 -0
  75. package/dist/core/engine-notice.d.ts +49 -18
  76. package/dist/core/file-history-retention.d.ts +8 -0
  77. package/dist/core/file-history-retention.js +14 -11
  78. package/dist/core/file-history-store.d.ts +31 -1
  79. package/dist/core/file-history-store.js +31 -2
  80. package/dist/core/frame-settlement.d.ts +10 -0
  81. package/dist/core/frame-settlement.js +6 -1
  82. package/dist/core/fs-write-gate-policy.d.ts +3 -3
  83. package/dist/core/fs-write-gate-policy.js +8 -7
  84. package/dist/core/gate-fold.js +2 -1
  85. package/dist/core/gate-lanes.js +7 -4
  86. package/dist/core/gate-outcome.d.ts +40 -1
  87. package/dist/core/gate-outcome.js +10 -0
  88. package/dist/core/git-worktree-env.d.ts +7 -3
  89. package/dist/core/git-worktree-env.js +16 -13
  90. package/dist/core/governance-codes.d.ts +12 -4
  91. package/dist/core/governance-codes.js +16 -4
  92. package/dist/core/hooks.d.ts +12 -4
  93. package/dist/core/hooks.js +11 -4
  94. package/dist/core/host-floor.js +3 -5
  95. package/dist/core/image-admission.d.ts +48 -8
  96. package/dist/core/image-admission.js +35 -4
  97. package/dist/core/input-author.d.ts +36 -0
  98. package/dist/core/input-author.js +39 -0
  99. package/dist/core/leg-identity.d.ts +62 -0
  100. package/dist/core/leg-identity.js +18 -0
  101. package/dist/core/locked-config.d.ts +2 -1
  102. package/dist/core/locked-config.js +5 -3
  103. package/dist/core/lsp.d.ts +5 -3
  104. package/dist/core/lsp.js +3 -2
  105. package/dist/core/mailbox-store.d.ts +85 -10
  106. package/dist/core/mailbox-store.js +31 -10
  107. package/dist/core/mcp-connection-pool.d.ts +6 -20
  108. package/dist/core/mcp-connection-pool.js +10 -28
  109. package/dist/core/mcp-failure.d.ts +76 -15
  110. package/dist/core/mcp-failure.js +60 -33
  111. package/dist/core/mcp-host-seat.d.ts +92 -53
  112. package/dist/core/mcp-host-seat.js +220 -46
  113. package/dist/core/mcp-probe.js +2 -2
  114. package/dist/core/mcp-server-link.d.ts +18 -6
  115. package/dist/core/mcp-server-link.js +19 -4
  116. package/dist/core/mcp-server-spec.d.ts +2 -1
  117. package/dist/core/mcp-session-end.d.ts +1 -2
  118. package/dist/core/mcp-session-end.js +1 -1
  119. package/dist/core/mcp.d.ts +6 -49
  120. package/dist/core/mcp.js +115 -111
  121. package/dist/core/media-byte-cap.d.ts +21 -46
  122. package/dist/core/media-byte-cap.js +55 -55
  123. package/dist/core/member-group.d.ts +7 -0
  124. package/dist/core/member-group.js +35 -0
  125. package/dist/core/memory-engine/consolidation.d.ts +1 -1
  126. package/dist/core/memory-engine/consolidation.js +7 -1
  127. package/dist/core/memory-engine/dual-root.d.ts +31 -0
  128. package/dist/core/memory-engine/dual-root.js +59 -11
  129. package/dist/core/memory-engine/engine.js +27 -24
  130. package/dist/core/memory-engine/file-backend.d.ts +13 -0
  131. package/dist/core/memory-engine/file-backend.js +35 -15
  132. package/dist/core/memory-engine/layout.d.ts +3 -0
  133. package/dist/core/memory-engine/layout.js +13 -3
  134. package/dist/core/memory-engine/memory-deployment.d.ts +110 -0
  135. package/dist/core/memory-engine/memory-deployment.js +182 -0
  136. package/dist/core/memory-engine/sync-client.d.ts +39 -18
  137. package/dist/core/memory-engine/sync-client.js +72 -14
  138. package/dist/core/memory-engine/sync-report.d.ts +7 -4
  139. package/dist/core/memory-engine/sync.d.ts +9 -1
  140. package/dist/core/mode-policy.d.ts +8 -8
  141. package/dist/core/mode-policy.js +7 -5
  142. package/dist/core/mods/agent-stations.d.ts +39 -4
  143. package/dist/core/mods/agent-stations.js +59 -10
  144. package/dist/core/mods/dollar.d.ts +62 -0
  145. package/dist/core/mods/extension-call.d.ts +15 -1
  146. package/dist/core/mods/extension-call.js +7 -2
  147. package/dist/core/mods/kernel/dispatch.d.ts +4 -3
  148. package/dist/core/mods/kernel/dispatch.js +4 -4
  149. package/dist/core/mods/kernel/events.d.ts +4 -1
  150. package/dist/core/mods/kernel/events.js +6 -6
  151. package/dist/core/mods/kernel/registration.d.ts +3 -0
  152. package/dist/core/mods/kernel/registration.js +5 -0
  153. package/dist/core/mods/kernel/site-rules.d.ts +6 -3
  154. package/dist/core/mods/kernel/site-rules.js +10 -2
  155. package/dist/core/mods/session-append.d.ts +115 -0
  156. package/dist/core/mods/session-append.js +311 -0
  157. package/dist/core/mods/session-compact.d.ts +48 -0
  158. package/dist/core/mods/session-compact.js +194 -0
  159. package/dist/core/mods/session-receive.d.ts +93 -0
  160. package/dist/core/mods/session-receive.js +141 -0
  161. package/dist/core/mods/session-send.d.ts +72 -0
  162. package/dist/core/mods/session-send.js +88 -0
  163. package/dist/core/mods/stations.d.ts +38 -16
  164. package/dist/core/mods/stations.js +25 -11
  165. package/dist/core/mods/tool-call.d.ts +2 -0
  166. package/dist/core/mods/tool-call.js +4 -4
  167. package/dist/core/output-style.js +3 -4
  168. package/dist/core/own-property-receipt.d.ts +61 -2
  169. package/dist/core/own-property-receipt.js +42 -2
  170. package/dist/core/park-selfcheck.js +4 -2
  171. package/dist/core/path-identity.d.ts +11 -0
  172. package/dist/core/path-identity.js +4 -0
  173. package/dist/core/path-rule-binding.d.ts +3 -1
  174. package/dist/core/path-rule-binding.js +3 -1
  175. package/dist/core/peer-seat.d.ts +3 -3
  176. package/dist/core/peer-seat.js +20 -8
  177. package/dist/core/permission-rule-consent.d.ts +21 -5
  178. package/dist/core/permission-rule-consent.js +21 -1
  179. package/dist/core/permission-rule-model.d.ts +34 -11
  180. package/dist/core/permission-rule-model.js +47 -10
  181. package/dist/core/permission-rule-org.d.ts +1 -1
  182. package/dist/core/permission-rule-provider.js +4 -1
  183. package/dist/core/permission-rules.d.ts +4 -0
  184. package/dist/core/permission-rules.js +11 -16
  185. package/dist/core/remote-env.d.ts +74 -26
  186. package/dist/core/remote-env.js +20 -0
  187. package/dist/core/retention-policy.d.ts +24 -23
  188. package/dist/core/retention-policy.js +36 -2
  189. package/dist/core/retention.d.ts +4 -1
  190. package/dist/core/retired-keys.d.ts +4 -4
  191. package/dist/core/row-admission.d.ts +10 -0
  192. package/dist/core/row-admission.js +5 -0
  193. package/dist/core/runner/advisor-instructions.d.ts +2 -1
  194. package/dist/core/runner/advisor-instructions.js +2 -1
  195. package/dist/core/runner/announce-once-ledger.d.ts +4 -4
  196. package/dist/core/runner/assemble-result.d.ts +13 -3
  197. package/dist/core/runner/assemble-result.js +12 -7
  198. package/dist/core/runner/caller-roster.d.ts +12 -9
  199. package/dist/core/runner/caller-roster.js +5 -2
  200. package/dist/core/runner/checkpoint-scope.d.ts +16 -1
  201. package/dist/core/runner/checkpoint-scope.js +21 -0
  202. package/dist/core/runner/compact-session.js +14 -2
  203. package/dist/core/runner/compaction-call-options.d.ts +1 -1
  204. package/dist/core/runner/compaction-restate.d.ts +2 -2
  205. package/dist/core/runner/compaction-restate.js +4 -3
  206. package/dist/core/runner/construction-doors.d.ts +2 -2
  207. package/dist/core/runner/construction-doors.js +2 -2
  208. package/dist/core/runner/contracts.d.ts +98 -26
  209. package/dist/core/runner/cross-boundary-lane.d.ts +1 -1
  210. package/dist/core/runner/decide-continuation.d.ts +4 -2
  211. package/dist/core/runner/decide-continuation.js +7 -4
  212. package/dist/core/runner/denial-limit-arms.d.ts +15 -21
  213. package/dist/core/runner/denial-limit-arms.js +17 -10
  214. package/dist/core/runner/expire-settle.d.ts +44 -0
  215. package/dist/core/runner/expire-settle.js +55 -0
  216. package/dist/core/runner/git-status-frame.d.ts +3 -3
  217. package/dist/core/runner/git-status-frame.js +2 -1
  218. package/dist/core/runner/halt-attribution.d.ts +2 -1
  219. package/dist/core/runner/halt-attribution.js +2 -1
  220. package/dist/core/runner/local-claims.d.ts +17 -0
  221. package/dist/core/runner/local-claims.js +18 -0
  222. package/dist/core/runner/media-removed-seat.d.ts +46 -0
  223. package/dist/core/runner/media-removed-seat.js +88 -0
  224. package/dist/core/runner/park-commit.d.ts +2 -2
  225. package/dist/core/runner/permission-rule-lanes.d.ts +5 -1
  226. package/dist/core/runner/permission-rule-lanes.js +28 -9
  227. package/dist/core/runner/person-path-rows.js +1 -1
  228. package/dist/core/runner/placement-fence.d.ts +26 -0
  229. package/dist/core/runner/placement-fence.js +38 -0
  230. package/dist/core/runner/prepare-ask-lane.d.ts +6 -12
  231. package/dist/core/runner/prepare-ask-lane.js +4 -4
  232. package/dist/core/runner/prepare-boundary-parks.d.ts +4 -1
  233. package/dist/core/runner/prepare-boundary-parks.js +2 -2
  234. package/dist/core/runner/prepare-caps-and-workflow.d.ts +2 -0
  235. package/dist/core/runner/prepare-caps-and-workflow.js +1 -0
  236. package/dist/core/runner/prepare-config-doors.js +16 -17
  237. package/dist/core/runner/prepare-context-lane.d.ts +6 -2
  238. package/dist/core/runner/prepare-context-lane.js +13 -13
  239. package/dist/core/runner/prepare-delegation-surface.d.ts +9 -9
  240. package/dist/core/runner/prepare-delegation-surface.js +4 -5
  241. package/dist/core/runner/prepare-execution-env.d.ts +5 -2
  242. package/dist/core/runner/prepare-execution-env.js +7 -4
  243. package/dist/core/runner/prepare-gate-stations.d.ts +19 -14
  244. package/dist/core/runner/prepare-gate-stations.js +6 -4
  245. package/dist/core/runner/prepare-hands-readface.d.ts +5 -5
  246. package/dist/core/runner/prepare-hands-readface.js +4 -4
  247. package/dist/core/runner/prepare-inherited-gate.d.ts +6 -0
  248. package/dist/core/runner/prepare-inherited-gate.js +3 -0
  249. package/dist/core/runner/prepare-lsp.d.ts +3 -0
  250. package/dist/core/runner/prepare-lsp.js +2 -2
  251. package/dist/core/runner/prepare-park-ask.d.ts +5 -2
  252. package/dist/core/runner/prepare-park-ask.js +4 -5
  253. package/dist/core/runner/prepare-policy-chain.d.ts +10 -21
  254. package/dist/core/runner/prepare-policy-chain.js +16 -25
  255. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  256. package/dist/core/runner/prepare-prompt-inputs.d.ts +5 -4
  257. package/dist/core/runner/prepare-prompt-inputs.js +3 -2
  258. package/dist/core/runner/prepare-question-face.d.ts +6 -4
  259. package/dist/core/runner/prepare-question-face.js +2 -2
  260. package/dist/core/runner/prepare-run-refs.d.ts +3 -0
  261. package/dist/core/runner/prepare-run-refs.js +2 -2
  262. package/dist/core/runner/prepare-suspend-saga.d.ts +11 -7
  263. package/dist/core/runner/prepare-suspend-saga.js +17 -7
  264. package/dist/core/runner/prepare-task.d.ts +1 -1
  265. package/dist/core/runner/prepare-task.js +56 -28
  266. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +6 -0
  267. package/dist/core/runner/prepare-tool-disclosure-mount.js +3 -1
  268. package/dist/core/runner/prepare-wiring-manifest.d.ts +3 -0
  269. package/dist/core/runner/prepare-wiring-manifest.js +2 -1
  270. package/dist/core/runner/prepare-workspace-restore.d.ts +5 -0
  271. package/dist/core/runner/prepare-workspace-restore.js +10 -6
  272. package/dist/core/runner/read-root-grant.d.ts +1 -1
  273. package/dist/core/runner/read-root-grant.js +2 -1
  274. package/dist/core/runner/resume-admission.d.ts +5 -3
  275. package/dist/core/runner/resume-admission.js +17 -3
  276. package/dist/core/runner/resume-apply.js +3 -1
  277. package/dist/core/runner/resume-claim.d.ts +8 -3
  278. package/dist/core/runner/resume-claim.js +28 -12
  279. package/dist/core/runner/resume-internals-and-config.d.ts +2 -2
  280. package/dist/core/runner/resume-internals-and-config.js +10 -1
  281. package/dist/core/runner/resume-preflight.d.ts +3 -2
  282. package/dist/core/runner/resume-preflight.js +13 -26
  283. package/dist/core/runner/retired-runner-deps.js +2 -0
  284. package/dist/core/runner/run-git-lane.js +2 -1
  285. package/dist/core/runner/run-harness-handlers.js +2 -2
  286. package/dist/core/runner/run-identity-wiring.d.ts +2 -2
  287. package/dist/core/runner/run-identity-wiring.js +14 -5
  288. package/dist/core/runner/run-leg.d.ts +3 -3
  289. package/dist/core/runner/run-leg.js +40 -29
  290. package/dist/core/runner/run-notification-lane.js +20 -2
  291. package/dist/core/runner/run-recovery-lanes.js +3 -2
  292. package/dist/core/runner/run-settle-and-teardown.js +9 -7
  293. package/dist/core/runner/run-telemetry-and-budget-seats.d.ts +1 -1
  294. package/dist/core/runner/run-terminal-adoption.d.ts +1 -1
  295. package/dist/core/runner/run-terminal-adoption.js +26 -17
  296. package/dist/core/runner/run-turn-boundary.js +27 -14
  297. package/dist/core/runner/runtask.d.ts +18 -3
  298. package/dist/core/runner/runtask.js +27 -11
  299. package/dist/core/runner/session-rule-policy.d.ts +1 -1
  300. package/dist/core/runner/session-rule-policy.js +6 -1
  301. package/dist/core/runner/shell-env-withheld.d.ts +1 -1
  302. package/dist/core/runner/stream-halt-verbs.d.ts +1 -14
  303. package/dist/core/runner/stream-halt-verbs.js +4 -3
  304. package/dist/core/runner/stream-reap.d.ts +7 -6
  305. package/dist/core/runner/stream-reap.js +13 -16
  306. package/dist/core/runner/stream-settle-backstop.d.ts +3 -2
  307. package/dist/core/runner/stream-settle-backstop.js +5 -3
  308. package/dist/core/runner/stream-steer-verb.d.ts +5 -2
  309. package/dist/core/runner/stream-steer-verb.js +8 -7
  310. package/dist/core/runner/terminal-account.d.ts +11 -1
  311. package/dist/core/runner/terminal-account.js +20 -0
  312. package/dist/core/runner/terminal-projection.d.ts +8 -2
  313. package/dist/core/runner/terminal-projection.js +2 -2
  314. package/dist/core/runner/tool-disclosure.d.ts +3 -0
  315. package/dist/core/runner/tool-disclosure.js +5 -2
  316. package/dist/core/runner/tool-end-body.d.ts +3 -3
  317. package/dist/core/runner/tool-end-body.js +1 -1
  318. package/dist/core/runner/tool-output-projection.d.ts +3 -3
  319. package/dist/core/runner/tool-output-projection.js +7 -6
  320. package/dist/core/runner/tool-table-view.d.ts +56 -0
  321. package/dist/core/runner/tool-table-view.js +51 -0
  322. package/dist/core/runner/turn-attachments.d.ts +3 -2
  323. package/dist/core/runner/turn-attachments.js +1 -1
  324. package/dist/core/runner/void-verifier-pause.d.ts +33 -0
  325. package/dist/core/runner/void-verifier-pause.js +41 -0
  326. package/dist/core/runner-deps.d.ts +24 -25
  327. package/dist/core/secret-env.d.ts +11 -11
  328. package/dist/core/secret-env.js +8 -9
  329. package/dist/core/session-log-transfer.js +9 -10
  330. package/dist/core/session-policy-store.d.ts +1 -1
  331. package/dist/core/session-policy-store.js +5 -2
  332. package/dist/core/session-reconcile.d.ts +3 -2
  333. package/dist/core/session-reconcile.js +7 -4
  334. package/dist/core/session-store.d.ts +2 -0
  335. package/dist/core/session-store.js +5 -7
  336. package/dist/core/session.d.ts +2 -1
  337. package/dist/core/shell-confinement.d.ts +37 -0
  338. package/dist/core/shell-confinement.js +56 -0
  339. package/dist/core/skill-grant.js +1 -1
  340. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +2 -2
  341. package/dist/core/store-contracts/checkpoint-store-contract.js +15 -2
  342. package/dist/core/store-contracts/file-history-store-contract.d.ts +5 -2
  343. package/dist/core/store-contracts/file-history-store-contract.js +25 -1
  344. package/dist/core/store-contracts/mailbox-store-contract.d.ts +12 -5
  345. package/dist/core/store-contracts/mailbox-store-contract.js +156 -9
  346. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  347. package/dist/core/store-contracts/tool-result-store-contract.js +30 -0
  348. package/dist/core/task-event.d.ts +17 -8
  349. package/dist/core/task-limits.d.ts +5 -0
  350. package/dist/core/task-notification.d.ts +89 -12
  351. package/dist/core/task-notification.js +87 -13
  352. package/dist/core/task-registry-agent.d.ts +5 -43
  353. package/dist/core/task-registry-agent.js +24 -51
  354. package/dist/core/task-registry-monitor.d.ts +1 -1
  355. package/dist/core/task-registry-monitor.js +15 -60
  356. package/dist/core/task-registry-shared.d.ts +15 -112
  357. package/dist/core/task-registry-shared.js +3 -41
  358. package/dist/core/task-registry-workflow.js +4 -21
  359. package/dist/core/task-registry.d.ts +19 -60
  360. package/dist/core/task-registry.js +19 -106
  361. package/dist/core/task-result.d.ts +24 -7
  362. package/dist/core/task-spec-members.d.ts +39 -0
  363. package/dist/core/task-spec-members.js +92 -0
  364. package/dist/core/task-spec.d.ts +10 -10
  365. package/dist/core/task-tool-shape.d.ts +7 -57
  366. package/dist/core/task-tool-shape.js +7 -66
  367. package/dist/core/terminal-cause.d.ts +30 -0
  368. package/dist/core/terminal-cause.js +1 -0
  369. package/dist/core/tool-catalog-entries.js +2 -5
  370. package/dist/core/tool-check-reading.js +16 -10
  371. package/dist/core/tool-conformance.js +1 -2
  372. package/dist/core/tool-errors.d.ts +6 -3
  373. package/dist/core/tool-errors.js +2 -0
  374. package/dist/core/tool-face-reader.js +3 -2
  375. package/dist/core/tool-face.d.ts +2 -3
  376. package/dist/core/tool-name-aliases.d.ts +5 -29
  377. package/dist/core/tool-name-aliases.js +9 -5
  378. package/dist/core/tool-name-readings.d.ts +14 -3
  379. package/dist/core/tool-name-readings.js +2 -0
  380. package/dist/core/tool-policy.d.ts +108 -18
  381. package/dist/core/tool-policy.js +84 -14
  382. package/dist/core/tool-result-store.d.ts +23 -0
  383. package/dist/core/tool-result-store.js +3 -2
  384. package/dist/core/tool-spec.d.ts +19 -6
  385. package/dist/core/trace.d.ts +18 -1
  386. package/dist/core/user-attachment.js +26 -21
  387. package/dist/core/workflow-journal-store.d.ts +1 -1
  388. package/dist/core/workflow-run-store.d.ts +2 -0
  389. package/dist/core/workflow-run-store.js +6 -5
  390. package/dist/core/workflow-settled-run.d.ts +5 -0
  391. package/dist/core/workflow-settled-run.js +7 -0
  392. package/dist/engine/execution-env/node-execution-env.d.ts +34 -9
  393. package/dist/engine/execution-env/node-execution-env.js +213 -21
  394. package/dist/engine/harness/agent-harness.d.ts +65 -18
  395. package/dist/engine/harness/agent-harness.js +90 -23
  396. package/dist/engine/harness/messages.d.ts +4 -3
  397. package/dist/engine/harness/messages.js +2 -2
  398. package/dist/engine/harness/types.d.ts +41 -7
  399. package/dist/engine/llm/media-removed.d.ts +14 -0
  400. package/dist/engine/llm/media-removed.js +9 -0
  401. package/dist/engine/llm/rejected-images.d.ts +35 -25
  402. package/dist/engine/llm/rejected-images.js +59 -10
  403. package/dist/engine/llm/types.d.ts +24 -3
  404. package/dist/engine/llm/types.js +7 -3
  405. package/dist/engine/loop/agent-loop.d.ts +6 -1
  406. package/dist/engine/loop/agent-loop.js +20 -11
  407. package/dist/engine/loop/types.d.ts +12 -3
  408. package/dist/engine/session/import-validate.js +7 -0
  409. package/dist/fixtures/index.d.ts +7 -5
  410. package/dist/fixtures/index.js +5 -3
  411. package/dist/index.d.ts +21 -11
  412. package/dist/index.js +15 -7
  413. package/dist/internal/harness-types.d.ts +2 -0
  414. package/dist/internal/llm.d.ts +2 -1
  415. package/dist/internal/llm.js +1 -0
  416. package/dist/orchestration/goal.d.ts +6 -2
  417. package/dist/orchestration/goal.js +6 -3
  418. package/dist/orchestration/run-workflow-tool.d.ts +11 -17
  419. package/dist/orchestration/run-workflow-tool.js +19 -42
  420. package/dist/orchestration/workflow-governance.d.ts +1 -1
  421. package/dist/orchestration/workflow-types.d.ts +2 -2
  422. package/dist/orchestration/workflow.d.ts +4 -0
  423. package/dist/orchestration/workflow.js +8 -5
  424. package/dist/stores/file/background-agent-store.js +18 -15
  425. package/dist/stores/file/checkpoint-store.js +7 -4
  426. package/dist/stores/file/file-history-store.js +3 -2
  427. package/dist/stores/file/index.d.ts +5 -3
  428. package/dist/stores/file/index.js +23 -8
  429. package/dist/stores/file/ledger-tuning.d.ts +23 -0
  430. package/dist/stores/file/ledger-tuning.js +21 -0
  431. package/dist/stores/file/mailbox-store.js +42 -22
  432. package/dist/stores/file/memory-store.js +3 -2
  433. package/dist/stores/file/permission-rule-adopt.js +24 -21
  434. package/dist/stores/file/permission-rule-store.js +6 -3
  435. package/dist/stores/file/session-policy-store.js +3 -2
  436. package/dist/stores/file/session-store.d.ts +16 -3
  437. package/dist/stores/file/session-store.js +21 -20
  438. package/dist/stores/file/tool-result-store.d.ts +11 -0
  439. package/dist/stores/file/tool-result-store.js +57 -3
  440. package/dist/stores/file/usage-window-store.js +3 -2
  441. package/dist/stores/file/workflow-journal-store.d.ts +0 -2
  442. package/dist/stores/file/workflow-journal-store.js +3 -18
  443. package/dist/stores/file/workflow-run-store.d.ts +1 -1
  444. package/dist/stores/file/workflow-run-store.js +15 -10
  445. package/dist/tools/fs/dead-cwd.d.ts +5 -5
  446. package/dist/tools/fs/dead-cwd.js +4 -11
  447. package/dist/tools/fs/fs-bash-background-text.d.ts +6 -0
  448. package/dist/tools/fs/fs-bash-background-text.js +6 -0
  449. package/dist/tools/fs/fs-bash.d.ts +3 -18
  450. package/dist/tools/fs/fs-bash.js +37 -124
  451. package/dist/tools/fs/fs-pdf.js +8 -6
  452. package/dist/tools/fs/fs-read.js +2 -2
  453. package/dist/tools/fs/fs-shared.d.ts +28 -3
  454. package/dist/tools/fs/fs-shared.js +15 -0
  455. package/dist/tools/fs/index.d.ts +1 -1
  456. package/dist/tools/fs/index.js +4 -14
  457. package/dist/tools/fs/pdf.d.ts +4 -4
  458. package/dist/tools/fs/pdf.js +6 -6
  459. package/dist/tools/fs/read-deny-home.js +8 -1
  460. package/dist/tools/fs/read-deny.d.ts +26 -2
  461. package/dist/tools/fs/read-deny.js +9 -2
  462. package/dist/tools/fs/read-floor.d.ts +13 -5
  463. package/dist/tools/fs/read-floor.js +206 -2
  464. package/dist/tools/fs/search.d.ts +3 -2
  465. package/dist/tools/fs/search.js +6 -6
  466. package/dist/tools/fs/shell-read-establish.js +3 -1
  467. package/dist/tools/fs/shell-read-identity.d.ts +3 -1
  468. package/dist/tools/fs/shell-read-identity.js +4 -2
  469. package/dist/tools/fs/shell-read-judge.d.ts +7 -1
  470. package/dist/tools/fs/shell-read-judge.js +1 -1
  471. package/dist/tools/monitor.d.ts +8 -7
  472. package/dist/tools/monitor.js +12 -10
  473. package/dist/tools/worktree.d.ts +5 -1
  474. package/dist/tools/worktree.js +20 -17
  475. package/package.json +6 -3
  476. package/test/export-surface.snapshot.json +92 -10
  477. package/wire-changes/core-stores-sql@7.61.0.json +480 -0
  478. package/wire-changes/core@7.61.0.json +4405 -0
  479. package/wire-changes/mods-kernel@7.61.0.json +65 -0
  480. package/wire-changes/primitives@7.61.0.json +30 -0
  481. package/dist/core/runner/image-removed-seat.d.ts +0 -12
  482. package/dist/core/runner/image-removed-seat.js +0 -19
@@ -1,7 +1,7 @@
1
1
  import { type AskOrigin, type AssertAllKeysHandled } from "./ask-origin.js";
2
2
  import { type EngineAttestation } from "./engine-attestation.js";
3
3
  import { type ReadRootGrantScreen } from "./read-root-grant-screen.js";
4
- import { type Settlement } from "./gate-outcome.js";
4
+ import { type DecidedVia, type Settlement } from "./gate-outcome.js";
5
5
  export { policyCannotAnswer, rowDemandsAPerson } from "./real-approval.js";
6
6
  import { type BindingFault } from "./canonical-json.js";
7
7
  import { type DecisionReason } from "./decision-receipt.js";
@@ -293,6 +293,20 @@ export declare function screenApproverAttribution(v: unknown): {
293
293
  approver?: string;
294
294
  defect?: string;
295
295
  };
296
+ /**
297
+ * Screen the `decidedVia` member — the ONE screen both entry points hold it to (the synchronous `AskOutcome` object and
298
+ * the durable `hostDecision`), so one value cannot meet two standards depending on its door. `word` is the decider word
299
+ * the same answer reported (`settledBy`, folded; `hostDecision.decidedBy`): both closed sets spell the policy decider
300
+ * `"policy"`, and that is the only word the member refines.
301
+ *
302
+ * Returns `{}` for absent, `{ decidedVia }` for a member of {@link DECIDED_VIA} beside `"policy"`, or `{ defect }` with the
303
+ * sentence the caller puts in its own refusal. A closed word is exact: the empty string is outside the set, and the
304
+ * defect names the member and the set, never the supplied value (a host string is not echoed into a refusal).
305
+ */
306
+ export declare function screenDecidedVia(v: unknown, word: string): {
307
+ decidedVia?: DecidedVia;
308
+ defect?: string;
309
+ };
296
310
  /** An integrity guard an ask stands on — an engine finding, carried on the ask's record ({@link EngineAttestation.guards}). */
297
311
  export type AskGuard = "dangerous_delete" | "unverifiable_delete" | "unverifiable_shell_text" | "transcript_write" | "artifact_shared_read";
298
312
  /**
@@ -455,6 +469,11 @@ export type PermissionResult = {
455
469
  /** The ask's whole class set, in {@link import("./ask-origin.js").ASK_CLASSES} order (see
456
470
  * {@link AskRequest.classes}). Stamped beside {@link askClass}, under the same rule. */
457
471
  classes?: readonly import("./ask-origin.js").AskClass[];
472
+ /** WHO asked about this call and what each said, in its own words — see {@link AskRequest.askReasons}. A STAMP member:
473
+ * the gate writes it where it receives a policy chain's ask ({@link import("./ask-origin.js").chainAskReasonsOf}) and
474
+ * where a hook or an extension asks ({@link import("./ask-origin.js").hookAskReasonOf}); a decision that states it is
475
+ * refused at the receipt. A layer that spreads the ask keeps it. */
476
+ askReasons?: readonly import("./ask-origin.js").AskReason[];
458
477
  /** The call could not be READ against a rule that may reach it — a content-form deny row, a content-form
459
478
  * ask row, a persisted-rule row (the lexer's word), or rows the shell read station's boundary stands on that
460
479
  * could not be read (`persisted_rows`). ENGINE-STAMPED at the four unreadable mint sites;
@@ -633,13 +652,27 @@ export interface ToolPolicy {
633
652
  * name refuses the run, an unmounted one is advised). Carried through {@link combinePolicies} (the union of the
634
653
  * members' groups); read with {@link toolPolicyNameSets}. */
635
654
  readonly nameSets?: readonly ToolPolicyNameSets[];
655
+ /** The tools this policy refuses EVERY call of — its deny rules that name a whole tool (no content: `Tool`, `Tool(*)`, a
656
+ * protocol peer, a covering glob), whatever the call carries: one read of the rules (a policy whose rules move reads them
657
+ * then), and the judge of a tool by every name it answers to. The model's tool table leaves such a tool out; `check` still
658
+ * refuses its calls (the member answers no call). A policy that declares it names only tools its own `check` refuses every
659
+ * call of. Carried through {@link combinePolicies} (a tool any member refuses whole); read with {@link toolPolicyWholeToolRefusals}. */
660
+ readonly wholeToolRefusals?: (signal?: AbortSignal) => Promise<WholeToolRefusal>;
636
661
  }
662
+ /** A tool as a rule names it: its name and the face the roster stamps (every name it answers to). */
663
+ export type ToolIdentity = Pick<ToolCallRequest, "toolName" | "face">;
664
+ /** Whether a policy (or a lane) refuses every call of the tool — the judge one read of its whole-tool deny rules yields. */
665
+ export type WholeToolRefusal = (tool: ToolIdentity) => boolean;
666
+ /** The judge of a policy with no whole-tool deny rule. */
667
+ export declare const REFUSES_NO_WHOLE_TOOL: WholeToolRefusal;
668
+ /** The id a whole-tool judge's read carries — no call of the leg, so every rule reader takes a read of its own for it. */
669
+ export declare const TOOL_TABLE_VIEW_READ = "tool-table-view";
637
670
  /**
638
671
  * The members a policy carries beside `check` — one table for every seat that carries them: {@link wrapToolPolicy} reads
639
672
  * each by name off the wrapped policy, {@link combinePolicies} folds each. The fence makes a new {@link ToolPolicy} member
640
673
  * a compile error until the table names it.
641
674
  */
642
- declare const TOOL_POLICY_CARRIED_MEMBERS: readonly ["projection", "pathRules", "writeGuardRows", "nameSets"];
675
+ declare const TOOL_POLICY_CARRIED_MEMBERS: readonly ["projection", "pathRules", "writeGuardRows", "nameSets", "wholeToolRefusals"];
643
676
  type ToolPolicyCarriedMember = (typeof TOOL_POLICY_CARRIED_MEMBERS)[number];
644
677
  export type ToolPolicyCarriesEveryMember = AssertAllKeysHandled<Exclude<Exclude<keyof ToolPolicy, "check">, ToolPolicyCarriedMember>>;
645
678
  /** The carried members that are set on `p`, each read by name — an accessor or a non-enumerable member included. A
@@ -666,6 +699,10 @@ export declare function toolPolicyPathRules(policies: readonly (ToolPolicy | und
666
699
  * judgment, in member order (a member that throws throws here — the judgment leaves the target unplaced). `undefined`
667
700
  * when none carries any. */
668
701
  export declare function toolPolicyWriteGuardRows(policies: readonly (ToolPolicy | undefined)[]): ToolPolicy["writeGuardRows"];
702
+ /** The whole-tool refusals the given holders carry together (combined policies included): one read of every reading they stand
703
+ * for, side by side, each settled ({@link settledWholeToolRead}) — a reading the fold holds twice (a layer re-appended) once; a
704
+ * tool refused whole when any reading refuses it whole (a deny in the fold refuses the call). `undefined` when none carries any. */
705
+ export declare function toolPolicyWholeToolRefusals(holders: readonly (Pick<ToolPolicy, "wholeToolRefusals"> | undefined)[]): ToolPolicy["wholeToolRefusals"];
669
706
  /**
670
707
  * One deterministic DENY component of a {@link ToolPolicyProjection} (F-012 L1). All fields are plain
671
708
  * serializable data — a component round-trips JSON/`structuredClone` unchanged, which is what lets a
@@ -1372,21 +1409,27 @@ export interface AskRequest {
1372
1409
  * durable suspend/checkpoint flow does NOT invoke `onAsk` on the suspend side, so v1 ask-aggregation
1373
1410
  * requires `checkpointStore` unset (design S1d §1.4 P-a). */
1374
1411
  readonly principal?: string;
1375
- /** Runner-filled source-task identity (= the issuing task's session id). An aggregating `onAsk` uses it
1376
- * to tell which worker an ask came from (nested grandchildren each carry their own session id).
1377
- * **worker-unforgeable for Runner-created delegated subagents** (a child never sets sessionId — the
1378
- * Runner mints it); a top-level caller MAY continue its own session id via `TaskSpec.sessionId`, so this
1379
- * is NOT a global "never forgeable" run id — aggregation only aggregates delegated workers, the context
1380
- * where it holds (design S1d §1.3). `readonly` + same sync-path-only / P-a caveat as `principal`.
1381
- * Undefined ⇒ no source task id. **NOT a subagent discriminator** (the HOST's own asks
1382
- * carry it too — it is always the issuing task's session id); "from a background agent" attribution
1383
- * keys on {@link fromSubagent}, never on this field's presence. */
1384
- readonly sourceTaskId?: string;
1412
+ /** Runner-filled: the issuing leg's session id — the conversation the ask was raised in, the address its
1413
+ * transcript and its parked row live at. An aggregating `onAsk` uses it to tell which worker an ask came from
1414
+ * (nested grandchildren each carry their own session). **worker-unforgeable for Runner-created delegated
1415
+ * subagents** (a child never sets sessionId — the Runner mints it); a top-level caller MAY continue its own
1416
+ * session via `TaskSpec.sessionId`, so this is NOT a global "never forgeable" run id — aggregation only
1417
+ * aggregates delegated workers, the context where it holds (design S1d §1.3). Present on every ask the
1418
+ * Runner mints, the host's included. It names a conversation, never a task: the delegated agent that asked
1419
+ * is {@link agentId}. `readonly` + same sync-path-only / P-a caveat as `principal`. */
1420
+ readonly sourceSessionId?: string;
1421
+ /** Runner-filled: the issuing leg's task id when that leg is a DELEGATED CHILD — a background sub-agent's
1422
+ * registry task id (`a…`, the string its row, `TaskStop`, `SendMessage` and `task_notification.task_id` use),
1423
+ * else the leg's own task id (a foreground sub-agent has no registry row: its session id). Present exactly
1424
+ * when {@link isDelegatedChild} is (a fork and a directly-started workflow's agent included — NOT the
1425
+ * {@link fromSubagent} set); absent on a host ask. The same value the leg's extension events carry as
1426
+ * `agentId`, read through the one predicate that mints it there. `readonly`, sync-path-only, S1d posture. */
1427
+ readonly agentId?: string;
1385
1428
  /** design/153 §1 (RB-39②) — Runner-filled: present (`true`) exactly when the gate raising this ask
1386
1429
  * belongs to a DELEGATED SUBAGENT (the prepareTask `isSubagent` fact — trusted `internals.parentTaskId`
1387
1430
  * presence; a child cannot self-declare or suppress it, internals never ride a TaskSpec). Undefined ⇒ the
1388
1431
  * host / a top-level task. THE explicit "from a background agent" discriminator (replaces presence-
1389
- * or equality-heuristics on {@link sourceTaskId}). `readonly`, sync-path-only, S1d posture. */
1432
+ * or equality-heuristics on {@link sourceSessionId}). `readonly`, sync-path-only, S1d posture. */
1390
1433
  readonly fromSubagent?: true;
1391
1434
  /** design/153 §1 — Runner-filled: the issuing task's display identity (a subagent's explicit agent
1392
1435
  * name, else its agent-type; undefined for the host and unnamed children). **UNTRUSTED-for-display**
@@ -1502,6 +1545,15 @@ export interface AskRequest {
1502
1545
  * reads the whole set — a class it will not answer anywhere in it is a question it does not answer. Present exactly
1503
1546
  * when {@link askClass} is. */
1504
1547
  readonly classes?: readonly import("./ask-origin.js").AskClass[];
1548
+ /** WHO asked about this call and what each said, in its OWN words, in fold order ({@link
1549
+ * import("./ask-origin.js").AskReason}): a deployment policy chain's ask sentence, a hook's or an extension's reason, a hook
1550
+ * host's cause word. Present ⇔ at least one asker said something of its own about this call; a generic question (the write
1551
+ * gate's default sentence, the permission mode's own) and a sentence the engine composes about a fact that rides a typed
1552
+ * member of this request are no entry. The structured approval surface renders this member and the typed members beside it,
1553
+ * never {@link message}; `words` is untrusted display text (one line, capped). Filled by the four mint stations from one
1554
+ * reader; the parked row carries the same value (`PendingAction.tool_approval.askReasons`). Never caller/worker-settable:
1555
+ * a policy or hook answer that states it is refused at the decision receipt. */
1556
+ readonly askReasons?: readonly import("./ask-origin.js").AskReason[];
1505
1557
  /** Engine-judged risk axes of the action awaiting approval, for the human decision surface: a
1506
1558
  * coarse `requiresRealApproval` cannot tell "cannot be undone" from "data leaves the machine",
1507
1559
  * and those call for different scrutiny. Filled by the gate from the SAME resolved axes the
@@ -1522,7 +1574,7 @@ export interface AskRequest {
1522
1574
  /** ruled 2026-08-04 — present exactly when this ask was raised inside a DELEGATED child whose approver
1523
1575
  * is the ancestor run's (the `ToolExecuteContext.onAsk` seat the delegation tool forwards). Additive:
1524
1576
  * an approver that ignores it is unaffected; a durable park/suspend flow never invokes `onAsk` at all,
1525
- * so this — like `principal`/`sourceTaskId` — exists only on the synchronous resolution path.
1577
+ * so this — like `principal`/`sourceSessionId` — exists only on the synchronous resolution path.
1526
1578
  * See {@link AskDelegationProvenance} for the trust posture of each member. */
1527
1579
  readonly delegation?: AskDelegationProvenance;
1528
1580
  /**
@@ -1551,7 +1603,7 @@ export interface AskRequest {
1551
1603
  * on the type because a deployment may invoke its approver function directly.
1552
1604
  *
1553
1605
  * SCOPE, stated so absence is not read as a clean bill on the other routes: this is the
1554
- * SYNCHRONOUS `onAsk` ask, like `principal`/`sourceTaskId` — the closure claim is over AskRequest
1606
+ * SYNCHRONOUS `onAsk` ask, like `principal`/`sourceSessionId` — the closure claim is over AskRequest
1555
1607
  * mint sites, not over every approval callback. The other two human-decision routes:
1556
1608
  * ① a durable park/suspend never invokes `onAsk` and never mints an AskRequest — its twin of this
1557
1609
  * bit is the PERSISTED `PendingAction.tool_approval.hasBidiControls` on the parked row (judged at
@@ -1568,6 +1620,8 @@ export interface AskRequest {
1568
1620
  */
1569
1621
  readonly hasBidiControls?: true;
1570
1622
  }
1623
+ /** The issuing leg's identity on a Runner-minted ask: minted once per leg, and every ask, question and park of the leg reads it. */
1624
+ export type AskSourceIdentity = Pick<AskRequest, "principal" | "sourceSessionId" | "agentId" | "fromSubagent" | "sourceAgentName" | "isDelegatedChild">;
1571
1625
  /**
1572
1626
  * How an `ask` decision is resolved when a policy/hook requests human confirmation (design/37):
1573
1627
  * - `"deny"` (and the default when omitted) — **headless auto-deny**: no approver, so `ask` resolves
@@ -1678,6 +1732,15 @@ export type OnAsk = "deny" | "allow" | ((req: AskRequest, signal?: AbortSignal)
1678
1732
  * produced (an abort, a throw, an unclonable edit): nobody approved those. A host's own elapsed window has
1679
1733
  * no attribution seat on its record (`approval_window_expired` names the host as a party, not a seat).
1680
1734
  *
1735
+ * `decidedVia` — WHICH MACHINE SEAT answered for `settledBy: "policy"`, a closed word
1736
+ * ({@link import("./gate-outcome.js").DECIDED_VIA}; the durable leg's `hostDecision.decidedVia` is the same word):
1737
+ * `"policy"` (the deployment's own policy; ABSENT reads the same) or `"permission_request_hook"` (a PermissionRequest
1738
+ * hook answered on the deployment's behalf). It picks the refusal SENTENCE ({@link policyRefusalMessage}) — a
1739
+ * hook's "no" is not "this run has no interactive approval channel" — and leaves the record as it is
1740
+ * (`policy_refused` / `policy_allowed`). Not `approver`: that seat is a transcription core never reads back; this one
1741
+ * is the closed word core reads. Read once with the other members; a value outside the closed set, or the member beside
1742
+ * any word but `"policy"` (a person, an elapsed window), is a loud fail-closed refusal at {@link resolveAsk}.
1743
+ *
1681
1744
  * `readRootGrant` — "yes, and add this directory": the card's {@link AskRequest.readRootCandidate} `dir`, sent back
1682
1745
  * byte for byte (`shell.read_boundary.grant_candidate_is_the_grant`). Beside `allow: true` on an ask carrying that
1683
1746
  * candidate, THIS run's read directories include it from then on (read faces only; `covers: "exact"` = that one
@@ -1691,6 +1754,7 @@ export type AskOutcome = boolean | "unavailable" | {
1691
1754
  settledBy?: "human" | "timeout" | "policy";
1692
1755
  reason?: string;
1693
1756
  approver?: string;
1757
+ decidedVia?: DecidedVia;
1694
1758
  readRootGrant?: string;
1695
1759
  };
1696
1760
  /**
@@ -1791,12 +1855,30 @@ export declare function tryCloneArgs<T>(v: T): {
1791
1855
  * exit reports (`finalInput`, the deny observer's `input`); a deny already carrying the args its own layers judged (a composed
1792
1856
  * chain's, nested ones included) keeps them. Read by the gate's lanes and by {@link combinePolicies}. Only a deny is changed. */
1793
1857
  export declare function refusalOf<D extends PermissionResult>(deny: D, judged: unknown): D;
1858
+ /** Who spoke an extension's verdict on a call, as a gate sentence names it (`extension "<registration>"`, else "an
1859
+ * extension"), and the reason it gave (`: <reason>`, else nothing) — read by every sentence about an extension's verdict,
1860
+ * a `tool.check` answer's and a `classic.PreToolUse` answer's alike. */
1861
+ export declare function extensionSpeaker(by: string | undefined, reason: string | undefined): {
1862
+ readonly who: string;
1863
+ readonly why: string;
1864
+ };
1865
+ /** `extension "<registration>"` — the registration's name as a quoted string, so a name can never end its own quotes and run on
1866
+ * into the sentence around it. A registered name has one form (`MOD_REGISTRATION_NAME`, the kernel's screen) and this reads
1867
+ * identically to it; the quoting is the second line, for a name no screen has judged here (one carried in from elsewhere). */
1868
+ export declare function extensionNamed(registration: string): string;
1869
+ /** An extension's own question about a call, as the text a reader of `message` reads it: which extension asks, and why — read
1870
+ * off the question's ONE entry ({@link import("./ask-origin.js").hookAskReasonOf}), so the sentence and the entry are one value.
1871
+ * The one sentence an ask raised by an extension carries, whichever event raised it (`tool.check`, `classic.PreToolUse`); when
1872
+ * the hook's host asks because the hook gave no verdict it could act on, the sentence says that instead of quoting anyone. */
1873
+ export declare function extensionQuestionText(toolName: string, entry: Extract<import("./ask-origin.js").AskReason, {
1874
+ by: "hook";
1875
+ }>): string;
1794
1876
  /**
1795
1877
  * A PreToolUse hook's `ask` folded over a verdict by `deny > ask > allow` — the ONE law for the gate's first screening and for
1796
1878
  * an approved edit's re-screen. A deny stands. Over an allow, the hook's own ask, RECONSTRUCTED rather than spread (its message,
1797
- * its real-approval demand and cross-boundary member, its rewrite) under the hook provenance the engine stamps. Over an ask, that ask keeps every member,
1879
+ * its real-approval demand and cross-boundary member, its rewrite, its askers' entries) under the hook provenance the engine stamps. Over an ask, that ask keeps every member,
1798
1880
  * takes the hook provenance and the hook's real-approval demand and cross-boundary member, and its message carries the hook's beside its own — a person
1799
- * clearing one ask that stands for two gates sees both reasons.
1881
+ * clearing one ask that stands for two gates sees both reasons: its `askReasons` are the standing ask's entries, then the hook's.
1800
1882
  */
1801
1883
  export declare function foldHookAsk(verdict: Exclude<PermissionResult, {
1802
1884
  action: "deny";
@@ -1898,8 +1980,16 @@ export declare function humanRefusalSentence(subject: HumanRefusalSubject, reaso
1898
1980
  * as the user's guidance, because no user gave it. `askMessage` is the ask's own prompt where the caller
1899
1981
  * has one (the synchronous leg does); a durable decide answers a call parked in an earlier leg and has
1900
1982
  * none, and the head then simply names the call.
1983
+ *
1984
+ * WHICH MACHINE SEAT answered (`decidedVia`, read through {@link policyDeciderOf}) picks between two sentences
1985
+ * and nothing else. The deployment's own policy (the word, or its absence) gets the sentence above. Any other seat
1986
+ * DID answer, so "this run has no interactive approval channel" would be false about it: the head names the seat
1987
+ * that declined (`a PermissionRequest hook denied this call`), and the seat's own words ride the fence under its
1988
+ * label. The fence is a deliberate divergence from the reference, which hands a hook's message to the model as the
1989
+ * refusal text itself (`iPt` (cli309.js:288208), `runHooks` (cli309.js:295883)): here every decider's free text is
1990
+ * untrusted data and reaches the model only fenced, whoever typed it.
1901
1991
  */
1902
- export declare function policyRefusalMessage(toolName: string, askMessage: string | undefined, note: string | undefined): string;
1992
+ export declare function policyRefusalMessage(toolName: string, askMessage: string | undefined, note: string | undefined, decidedVia: DecidedVia | undefined): string;
1903
1993
  /**
1904
1994
  * A {@link resolveAsk} result: always a TERMINAL `allow`/`deny` (never `ask`). `approverUnavailable`
1905
1995
  * is the out-of-band G1 three-value marker: the live approver returned `"unavailable"` for this ask —
@@ -3,16 +3,17 @@ import { homedir } from "node:os";
3
3
  import { argsReadFrom, carryArgsReadFrom, withArgsReading } from "./effective-path-target.js";
4
4
  import { editRewrittenSentence, readRejudge, rewriteChasedSentence } from "./rewrite-rejudge.js";
5
5
  import { brandPolicyAskClass } from "./ask-class.js";
6
- import { decisionAskClassesOf, headlessDenialMessage } from "./ask-origin.js";
6
+ import { decisionAskClassesOf, headlessDenialMessage, joinAskReasons } from "./ask-origin.js";
7
7
  import { attest, attestationOf, isEngineAttestation, mergeAttestation, mintAttestation, withAttestation } from "./engine-attestation.js";
8
8
  import { ownReadRootCandidate, readRootGrantSeat } from "./read-root-grant-screen.js";
9
- import { decidersNote, settledByDecider } from "./gate-outcome.js";
9
+ import { DECIDED_VIA, decidersNote, isDecidedVia, policyDeciderOf, settledByDecider } from "./gate-outcome.js";
10
10
  import { unjudgedAllowRefused } from "./real-approval.js";
11
11
  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
15
  import { readOnlyShellVerdict } from "./read-only-shell.js";
16
+ import { DEFAULT_GATE_AWAIT_TIMEOUT_MS, withGateTimeout } from "./gate-bounded-await.js";
16
17
  import { protectivePathTargetOf, shellFaceToolNames } from "./tool-registry.js";
17
18
  import { heldBy } from "./tool-name-readings.js";
18
19
  import { bindableValueOf, boundInputHashOf, describeBindingFault, exactBoundInputHashOf } from "./canonical-json.js";
@@ -20,7 +21,7 @@ import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY } from "./unt
20
21
  import { describeRejectedValue } from "./tool-search-setting.js";
21
22
  import { egressText, egressThrownText } from "./untrusted-egress.js";
22
23
  import { assertNoRetiredKeys, assertNoRetiredToolPolicyKeys, RETIRED_DECISION_MEMBERS, RETIRED_TOOL_POLICY_KEYS } from "./retired-keys.js";
23
- import { DECISION_MEMBER_ARMS, isEngineRefusal, nestedRecordsOf, receiveContract, receiveNestedRecords, refusedOutOfContract, screenContractValues } from "./decision-receipt.js";
24
+ import { DECISION_MEMBER_ARMS, HOOK_SEAT_MEMBER_ARMS, isEngineRefusal, nestedRecordsOf, receiveContract, receiveNestedRecords, refusedOutOfContract, screenContractValues } from "./decision-receipt.js";
24
25
  export { isEngineRefusal } from "./decision-receipt.js";
25
26
  import { isCoveringRuleName, ruleNameCovers } from "./namespaced-rule-name.js";
26
27
  import { ruleContentOf } from "./permission-rule-model.js";
@@ -80,6 +81,19 @@ export function screenApproverAttribution(v) {
80
81
  }
81
82
  return { approver: v };
82
83
  }
84
+ export function screenDecidedVia(v, word) {
85
+ if (v === undefined)
86
+ return {};
87
+ if (!isDecidedVia(v)) {
88
+ return {
89
+ defect: `decidedVia is outside the closed set (got ${v === null ? "null" : typeof v === "string" ? "a string that is not a member" : typeof v}) — it is exactly ${DECIDED_VIA.map((w) => `"${w}"`).join(" or ")}, or omitted`,
90
+ };
91
+ }
92
+ if (word !== "policy") {
93
+ return { defect: `decidedVia names which machine seat answered for the deployment's policy, and this decision reports "${word}" — the member rides a "policy" decision only` };
94
+ }
95
+ return { decidedVia: v };
96
+ }
83
97
  export const ASK_EVIDENCE_ABSENCE_VALUES = ["not_wired", "not_adjudicated", "unavailable", "no_match", "not_reported"];
84
98
  export function decisionText(d) {
85
99
  return d.message;
@@ -106,7 +120,9 @@ export function answeredFor(d, call, runs) {
106
120
  const record = attestationOf(d, call);
107
121
  return record?.settlement !== undefined && licenseCovers(record.inputDigest, runs);
108
122
  }
109
- const TOOL_POLICY_CARRIED_MEMBERS = ["projection", "pathRules", "writeGuardRows", "nameSets"];
123
+ export const REFUSES_NO_WHOLE_TOOL = () => false;
124
+ export const TOOL_TABLE_VIEW_READ = "tool-table-view";
125
+ const TOOL_POLICY_CARRIED_MEMBERS = ["projection", "pathRules", "writeGuardRows", "nameSets", "wholeToolRefusals"];
110
126
  export function carriedMembersOf(p) {
111
127
  assertNoRetiredKeys(p, RETIRED_TOOL_POLICY_KEYS, "ToolPolicy");
112
128
  const out = {};
@@ -131,6 +147,31 @@ export function toolPolicyWriteGuardRows(policies) {
131
147
  return undefined;
132
148
  return async (at) => (await Promise.all(sources.map((rowsOf) => rowsOf(at)))).flat();
133
149
  }
150
+ const FOLDED_WHOLE_TOOL_READS = new WeakMap();
151
+ function settledWholeToolRead(read, signal) {
152
+ return withGateTimeout(Promise.resolve().then(() => read(signal)), DEFAULT_GATE_AWAIT_TIMEOUT_MS, signal, "a whole-tool reading").then((judge) => (tool) => {
153
+ try {
154
+ return judge(tool) === true;
155
+ }
156
+ catch {
157
+ return false;
158
+ }
159
+ }, () => REFUSES_NO_WHOLE_TOOL);
160
+ }
161
+ export function toolPolicyWholeToolRefusals(holders) {
162
+ const sources = [...new Set(holders.flatMap((h) => {
163
+ const read = h?.wholeToolRefusals;
164
+ return typeof read === "function" ? (FOLDED_WHOLE_TOOL_READS.get(read) ?? [read]) : [];
165
+ }))];
166
+ if (sources.length === 0)
167
+ return undefined;
168
+ const combined = async (signal) => {
169
+ const judges = await Promise.all(sources.map((read) => settledWholeToolRead(read, signal)));
170
+ return (tool) => judges.some((refuses) => refuses(tool));
171
+ };
172
+ FOLDED_WHOLE_TOOL_READS.set(combined, sources);
173
+ return combined;
174
+ }
134
175
  export function coveringRuleEntries(entries, behavior) {
135
176
  return (entries ?? []).filter((entry) => isCoveringRuleName(entry, behavior));
136
177
  }
@@ -220,7 +261,7 @@ export function constraintChainDigest(chain) {
220
261
  }
221
262
  const ALLOW = Object.freeze({ action: "allow" });
222
263
  export const DECISION_MEMBERS = Object.keys(DECISION_MEMBER_ARMS);
223
- const HOOK_RESULT_MEMBERS = [...DECISION_MEMBERS, "additionalContext"];
264
+ const HOOK_RESULT_MEMBERS = [...DECISION_MEMBERS, ...Object.keys(HOOK_SEAT_MEMBER_ARMS)];
224
265
  const HOOK_SEAM_UNREAD = new Set(["decisionReason"]);
225
266
  const HOOK_SEAM_OPTIONAL = new Set(["action"]);
226
267
  const HOOK_RECEIPTS = new WeakSet();
@@ -383,7 +424,9 @@ export function createAllowDenyPolicy(opts) {
383
424
  const deny = new Set(opts.deny ?? []);
384
425
  const denyCovering = coveringRuleEntries(opts.deny, "deny");
385
426
  const allowCovering = coveringRuleEntries(opts.allow, "allow");
427
+ const refusesWhole = (tool) => nameListHolds(deny, tool) || coveringRuleHit(denyCovering, tool);
386
428
  return {
429
+ ...(deny.size > 0 ? { wholeToolRefusals: () => Promise.resolve(refusesWhole) } : {}),
387
430
  projection: {
388
431
  components: [
389
432
  ...(opts.deny && opts.deny.length > 0 ? [{ kind: "tool_deny", names: [...opts.deny] }] : []),
@@ -393,9 +436,8 @@ export function createAllowDenyPolicy(opts) {
393
436
  },
394
437
  nameSets: [{ ...(opts.allow ? { allow: [...opts.allow] } : {}), ...(opts.deny ? { deny: [...opts.deny] } : {}) }],
395
438
  check(req) {
396
- if (nameListHolds(deny, req) || coveringRuleHit(denyCovering, req)) {
439
+ if (refusesWhole(req))
397
440
  return { action: "deny", message: `tool "${req.toolName}" is denied by policy` };
398
- }
399
441
  if (allow && !nameListHolds(allow, req) && !coveringRuleHit(allowCovering, req)) {
400
442
  return { action: "deny", message: `tool "${req.toolName}" is not in the allowlist` };
401
443
  }
@@ -428,7 +470,9 @@ export function createApprovalPolicy(opts) {
428
470
  const needCovering = coveringRuleEntries(opts.requireApproval, "ask");
429
471
  const denyCovering = coveringRuleEntries(opts.deny, "deny");
430
472
  const autoCovering = coveringRuleEntries(opts.autoAllow, "allow");
473
+ const refusesWhole = (tool) => nameListHolds(deny, tool) || coveringRuleHit(denyCovering, tool);
431
474
  return {
475
+ ...(deny.size > 0 ? { wholeToolRefusals: () => Promise.resolve(refusesWhole) } : {}),
432
476
  projection: {
433
477
  components: [
434
478
  ...(opts.deny && opts.deny.length > 0 ? [{ kind: "tool_deny", names: [...opts.deny] }] : []),
@@ -444,9 +488,8 @@ export function createApprovalPolicy(opts) {
444
488
  },
445
489
  ],
446
490
  async check(req, signal) {
447
- if (nameListHolds(deny, req) || coveringRuleHit(denyCovering, req)) {
491
+ if (refusesWhole(req))
448
492
  return { action: "deny", message: `tool "${req.toolName}" is denied by policy` };
449
- }
450
493
  if (nameListHolds(need, req) || coveringRuleHit(needCovering, req)) {
451
494
  const attestOver = (inputDigest) => (d, settlement, bindingRefusal) => ({ ...d, attestation: mintAttestation(req, { settlement, origin: "policy", ...(inputDigest !== undefined ? { inputDigest } : {}), ...(bindingRefusal !== undefined ? { bindingRefusal } : {}) }) });
452
495
  const unasked = unaskedSeatAnswer(req, signal, { aborted: `approval aborted for "${req.toolName}" (run or turn interrupted)`, unreachable: `approval for "${req.toolName}" was not requested: nobody can be asked about this call` }, "policy");
@@ -488,7 +531,7 @@ export function createApprovalPolicy(opts) {
488
531
  return attest({
489
532
  action: "deny",
490
533
  message: reading.word === "policy"
491
- ? policyRefusalMessage(req.toolName, undefined, reading.note)
534
+ ? policyRefusalMessage(req.toolName, undefined, reading.note, reading.via)
492
535
  : reading.word === "timeout"
493
536
  ? `no one answered the approval request for "${req.toolName}" — the approver reported its own window elapsed with no answer; denied fail-closed${reading.note !== undefined ? `\nReviewer note:\n${delimitUntrusted("reviewer note", reading.note, REVIEWER_NOTE_MAX_BODY)}` : ""}`
494
537
  : `approval denied for "${req.toolName}"${reading.note !== undefined ? `\nReviewer note:\n${delimitUntrusted("reviewer note", reading.note, REVIEWER_NOTE_MAX_BODY)}` : ""}`,
@@ -547,6 +590,7 @@ export function combinePolicies(...policies) {
547
590
  nameSets: nameSets.length > 0 ? nameSets : undefined,
548
591
  pathRules: pathRuled.length > 0 ? (anchors) => toolPolicyPathRules(pathRuled, anchors) : undefined,
549
592
  writeGuardRows,
593
+ wholeToolRefusals: toolPolicyWholeToolRefusals(policies),
550
594
  };
551
595
  return {
552
596
  ...carriedMembersOf(folded),
@@ -887,16 +931,28 @@ export function tryCloneArgs(v) {
887
931
  export function refusalOf(deny, judged) {
888
932
  return deny.action !== "deny" || deny.updatedInput !== undefined ? deny : { ...deny, updatedInput: judged };
889
933
  }
934
+ export function extensionSpeaker(by, reason) {
935
+ return { who: by !== undefined ? extensionNamed(by) : "an extension", why: reason !== undefined ? `: ${inlineUntrusted(reason, 500)}` : "" };
936
+ }
937
+ export function extensionNamed(registration) {
938
+ return `extension ${JSON.stringify(inlineUntrusted(registration, 80))}`;
939
+ }
940
+ export function extensionQuestionText(toolName, entry) {
941
+ const who = entry.registration !== undefined ? extensionNamed(entry.registration) : "an extension";
942
+ const why = entry.cause === "verdict_unreadable" ? ": the hook's verdict could not be read" : entry.cause === "verdict_unfinished" ? ": the hook did not finish with a verdict" : entry.words !== undefined ? `: ${entry.words}` : "";
943
+ return `tool "${toolName}" needs approval (asked by ${who}${why})`;
944
+ }
890
945
  export function foldHookAsk(verdict, hookAsk) {
891
946
  if (verdict.action === "deny")
892
947
  return verdict;
893
948
  const mandate = { ...(hookAsk.requiresRealApproval === true ? { requiresRealApproval: true } : {}), ...(hookAsk.crossBoundaryMandated === true ? { crossBoundaryMandated: true } : {}) };
894
949
  if (verdict.action === "allow") {
895
- return { action: "ask", ...(hookAsk.message !== undefined ? { message: hookAsk.message } : {}), decisionReason: "hook", ...mandate, ...(hookAsk.updatedInput !== undefined ? { updatedInput: hookAsk.updatedInput } : {}) };
950
+ return { action: "ask", ...(hookAsk.message !== undefined ? { message: hookAsk.message } : {}), decisionReason: "hook", ...mandate, ...(hookAsk.updatedInput !== undefined ? { updatedInput: hookAsk.updatedInput } : {}), ...(hookAsk.askReasons !== undefined ? { askReasons: hookAsk.askReasons } : {}) };
896
951
  }
897
952
  const hookMessage = hookAsk.message;
898
953
  const message = hookMessage !== undefined && hookMessage !== verdict.message ? `${verdict.message !== undefined ? `${verdict.message} ` : ""}(a PreToolUse hook also asks: ${hookMessage})` : verdict.message;
899
- return { ...verdict, decisionReason: "hook", ...(message !== undefined ? { message } : {}), ...mandate };
954
+ const askReasons = joinAskReasons(verdict.askReasons, hookAsk.askReasons);
955
+ return { ...verdict, decisionReason: "hook", ...(message !== undefined ? { message } : {}), ...mandate, ...(askReasons !== undefined ? { askReasons } : {}) };
900
956
  }
901
957
  const OWNED_ARGS = new WeakSet();
902
958
  export function ownArgs(v, root = "args") {
@@ -987,7 +1043,14 @@ export function humanRefusalSentence(subject, reason, delegatedChild) {
987
1043
  function humanRefusalMessage(req, reason) {
988
1044
  return `approval denied for "${req.toolName}": ${req.message}\n${humanRefusalSentence("tool use", reason, req.isDelegatedChild === true)}`;
989
1045
  }
990
- export function policyRefusalMessage(toolName, askMessage, note) {
1046
+ export function policyRefusalMessage(toolName, askMessage, note, decidedVia) {
1047
+ const decider = policyDeciderOf(decidedVia);
1048
+ if (decider.seat !== "policy") {
1049
+ const declined = `${decider.name} denied this call to "${toolName}"${askMessage !== undefined ? `: ${askMessage}` : ""}\nThe call did NOT run. Do not claim it ` +
1050
+ `succeeded and do not retry it unchanged; report what was blocked and why you needed it, then continue with the parts of ` +
1051
+ `the task it does not block.`;
1052
+ return note === undefined ? declined : `${declined}\nHook reason:\n${delimitUntrusted("hook reason", note, REVIEWER_NOTE_MAX_BODY)}`;
1053
+ }
991
1054
  const head = `approval required for "${toolName}" but this run has no interactive approval channel${askMessage !== undefined ? `: ${askMessage}` : ""}`;
992
1055
  const body = `${head}\nThe deployment's policy declined this tool use; the call did NOT run. Action requires interactive approval and ` +
993
1056
  `permission prompts are not available in this context. Do not claim it succeeded and do not retry it here; report what ` +
@@ -1126,12 +1189,14 @@ function readApproverOutcomeObject(ok, toolName, editLane) {
1126
1189
  let allowed;
1127
1190
  let suppliedEdit;
1128
1191
  let suppliedApprover;
1192
+ let suppliedVia;
1129
1193
  let grant;
1130
1194
  try {
1131
1195
  supplied = ok.settledBy;
1132
1196
  allowed = ok.allow;
1133
1197
  suppliedEdit = ok.updatedInput;
1134
1198
  suppliedApprover = ok.approver;
1199
+ suppliedVia = ok.decidedVia;
1135
1200
  grant = ok.readRootGrant;
1136
1201
  }
1137
1202
  catch (err) {
@@ -1150,6 +1215,10 @@ function readApproverOutcomeObject(ok, toolName, editLane) {
1150
1215
  if (attribution.defect !== undefined) {
1151
1216
  return refused(`the approver for "${toolName}" reported an attribution this seam refuses: ${attribution.defect}; denied fail-closed`, settledByNobody("approver_contract"));
1152
1217
  }
1218
+ const via = screenDecidedVia(suppliedVia, settledWord);
1219
+ if (via.defect !== undefined) {
1220
+ return refused(`the approver for "${toolName}" reported a decidedVia this seam refuses: ${via.defect}; denied fail-closed`, settledByNobody("approver_contract"));
1221
+ }
1153
1222
  if (editLane === "none" && grant !== undefined) {
1154
1223
  return refused(`the approver for "${toolName}" attached a readRootGrant on a seat that offers no directory — denied fail-closed (a grant answers an approval card's readRootCandidate)`, settledByNobody("approver_contract"));
1155
1224
  }
@@ -1172,6 +1241,7 @@ function readApproverOutcomeObject(ok, toolName, editLane) {
1172
1241
  kind: "deny",
1173
1242
  word: settledWord,
1174
1243
  note,
1244
+ via: via.decidedVia,
1175
1245
  grant,
1176
1246
  settlement: decider === undefined ? { kind: "approval_window_expired", who: { party: "host" }, when: Date.now() } : settledByDecider(decider, "refused", attribution.approver, note),
1177
1247
  };
@@ -1284,7 +1354,7 @@ async function resolveAskArms(req, onAsk, signal, onLateSettlement) {
1284
1354
  message: reading.word === "timeout"
1285
1355
  ? `approval for "${req.toolName}" was not answered before the approver's own window elapsed: ${req.message}${reading.note !== undefined ? `\nReviewer note:\n${delimitUntrusted("reviewer note", reading.note, REVIEWER_NOTE_MAX_BODY)}` : ""}`
1286
1356
  : reading.word === "policy"
1287
- ? policyRefusalMessage(req.toolName, req.message, reading.note)
1357
+ ? policyRefusalMessage(req.toolName, req.message, reading.note, reading.via)
1288
1358
  : humanRefusalMessage(req, reading.note),
1289
1359
  decisionReason: "mode",
1290
1360
  settlement: reading.settlement,
@@ -118,6 +118,29 @@ export interface ToolResultStore {
118
118
  * audit receipts, scheduled execution), of which this is one caller-driven erase.
119
119
  */
120
120
  deleteBySession?(sessionId: string): Promise<ToolResultDeletionReport> | ToolResultDeletionReport;
121
+ /**
122
+ * Age out the entries stored more than `opts.maxAgeMs` before `now` (epoch ms): the age bound a deployment states for
123
+ * offloaded results, read the same way by every backend — a SQL backend's sweep leg reads the same bound. An entry's
124
+ * age is the time its winning write stored it; the content and its owner record go together. Answers how many
125
+ * entries it removed.
126
+ *
127
+ * Rules every implementation follows:
128
+ * - **no bound, no deletion**: `opts` or `opts.maxAgeMs` absent ⇒ nothing is removed — the default keeps every
129
+ * entry, as a transcript is kept;
130
+ * - **a bound that cannot be evaluated is refused** before any entry is touched (`config.retention_policy_invalid`:
131
+ * a `maxAgeMs` that is not a finite number of milliseconds of 0 or more, a `now` that is not a finite number) —
132
+ * never read as "no bound";
133
+ * - **age only**: ownership is not consulted, and an entry still reachable from a transcript is removed when it
134
+ * is old enough — the model's read of it then says it may have expired (the honest degradation the read
135
+ * already has);
136
+ * - **idempotent**, and an entry that disappears between enumeration and removal is honest absence.
137
+ *
138
+ * Optional: absent ⇒ this store keeps entries until their session is deleted. An OPTIONAL leg of the contract kit
139
+ * (`toolResultStoreContract`), reported through its `onOptionalMember` callback.
140
+ */
141
+ reap?(now: number, opts?: {
142
+ maxAgeMs?: number;
143
+ }): Promise<number> | number;
121
144
  /**
122
145
  * The READ half of the same ownership coordinate {@link deleteBySession} erases by: every entry this store recorded as belonging to
123
146
  * `sessionId`, as the ref and the owner recorded at its winning write. Without it the offloaded results a session's transcript
@@ -8,7 +8,7 @@ import { mountRuleFace, toolFace } from "./tool-catalog-entries.js";
8
8
  import { thrownText } from "./thrown-value.js";
9
9
  import { readRetentionDeclaration } from "./retention.js";
10
10
  import { carryNotStartedReceipt } from "./delegation-not-started.js";
11
- import { receiveOptions } from "./own-property-receipt.js";
11
+ import { optionKeys, receiveOptions } from "./own-property-receipt.js";
12
12
  import { NON_NEGATIVE_SAFE_INTEGER, readIntegerOption } from "./integer-option.js";
13
13
  export const TOOL_RESULT_REF_CONFLICT_CODE = "tool_result.ref_conflict";
14
14
  export class ToolResultRefConflictError extends Error {
@@ -79,13 +79,14 @@ export function toolResultContentSegment(text) {
79
79
  function digestOfString(s) {
80
80
  return createHash("sha256").update(Buffer.from(s, "utf16le")).digest("hex");
81
81
  }
82
+ const IN_MEMORY_TOOL_RESULT_STORE_OPTION_KEYS = optionKeys()({ maxTotalChars: 0, retention: 0 });
82
83
  export class InMemoryToolResultStore {
83
84
  retention;
84
85
  map = new Map();
85
86
  totalChars = 0;
86
87
  maxTotalChars;
87
88
  constructor(options) {
88
- const opts = receiveOptions(options, "InMemoryToolResultStore");
89
+ const opts = receiveOptions(options, "InMemoryToolResultStore", IN_MEMORY_TOOL_RESULT_STORE_OPTION_KEYS);
89
90
  this.retention = readRetentionDeclaration("InMemoryToolResultStore.retention", opts.retention);
90
91
  this.maxTotalChars = readIntegerOption("InMemoryToolResultStore.maxTotalChars", opts.maxTotalChars, NON_NEGATIVE_SAFE_INTEGER, "characters", "an unbounded store");
91
92
  }
@@ -825,6 +825,13 @@ export interface ToolExecuteContext {
825
825
  * the tool runs outside a Runner task.
826
826
  */
827
827
  parentCwd?: string;
828
+ /**
829
+ * The RUNNING task's own placement target (Runner-filled, read-only, never a model argument): what its execution
830
+ * environment reported as its workspace settled. A delegation tool hands it, as is, to every agent it spawns or wakes
831
+ * (`RunInternals.placementTarget` — the fence that agent's env is minted under). Absent outside a Runner task, and when
832
+ * the environment reported none (not remote, or its handle could not answer yet).
833
+ */
834
+ placementTarget?: import("./remote-env.js").PlacementTarget;
828
835
  /** The deployment's compiled host floor (`RunnerDeps.hostFloor`; Runner-filled, read-only, never a model argument): an engine executor
829
836
  * that connects — the fetch tool on every hop, WebSearch's SearXNG backend (handed it in the backend's `opts.hostFloor`) — judges each URL
830
837
  * by it before the request. Absent outside a Runner, or when none is declared. */
@@ -964,8 +971,8 @@ export interface ToolExecuteContext {
964
971
  * from its roster, so a question it needed to ask silently became a guess.
965
972
  *
966
973
  * Forwarded VERBATIM, unlike `onAsk`'s provenance-stamped wrapper: a content ask carries its issuing
967
- * identity in the request itself (`AskQuestionRequest.principal` + `sourceTaskId`, which the child's
968
- * own prepare fills from the child's inherited principal and its Runner-minted session id), and
974
+ * identity in the request itself (`AskQuestionRequest.principal` + `sourceSessionId` + `agentId`, which the
975
+ * child's own prepare fills from the child's inherited principal, its Runner-minted session id and its task id), and
969
976
  * nothing in the question path does approver-identity collapse (the reason the permission wrapper
970
977
  * exists). Wrapping here would add a field no consumer reads and a second function identity for one
971
978
  * decision-maker.
@@ -1180,10 +1187,11 @@ export interface ToolExecuteContext {
1180
1187
  /**
1181
1188
  * A read-only CAPTURE of this (parent) task's request allow entries for the run ({@link import("./task-spec.js").TaskSpec.allowedTools},
1182
1189
  * its own and any it inherited), filled by the Runner beside {@link activeSkillGrants}: a delegation tool reads it AT SPAWN
1183
- * TIME and threads it into the child, which holds them as its own request rows until it ends. A copy; the model can
1184
- * neither read nor set it. Undefined when the tool runs outside a Runner task.
1190
+ * TIME and threads it into the child, which holds them as its own request rows until it ends — an anchored member with its
1191
+ * set's anchors, so the child reads its path rule where the parent did. A copy; the model can neither read nor set it.
1192
+ * Undefined when the tool runs outside a Runner task.
1185
1193
  */
1186
- activeRequestAllowedTools?: () => readonly string[];
1194
+ activeRequestAllowedTools?: () => readonly import("./allow-entry.js").AllowListEntry[];
1187
1195
  /**
1188
1196
  * Parent effective-policy inheritance (tighten-only) — the Runner-filled chain accessor a delegation tool
1189
1197
  * (`createSubagentTool` / the `run_workflow` spawn legs) calls AT SPAWN TIME and threads verbatim into the
@@ -1291,7 +1299,7 @@ export interface ToolExecuteContext {
1291
1299
  */
1292
1300
  checkpointScopeForChildren?: string;
1293
1301
  /**
1294
- * design/99 (nested-subagent live observability): the host run's stable taskId (`spec.taskId ?? sessionId`),
1302
+ * design/99 (nested-subagent live observability): the host run's stable taskId (the leg's single mint),
1295
1303
  * filled by the Runner. A delegation tool (`createSubagentTool`) reads it AT SPAWN TIME and threads it into the
1296
1304
  * child as the child's `parentTaskId`, so a UI can build the live nested-agent tree (child.parentTaskId === this
1297
1305
  * taskId). Undefined when the tool runs outside a Runner task.
@@ -1400,6 +1408,11 @@ export interface ToolExecuteContext {
1400
1408
  * outside a Runner: no station is raised and every type is offered.
1401
1409
  */
1402
1410
  agentStations?: import("./mods/agent-stations.js").AgentStations;
1411
+ /**
1412
+ * The sending leg's `session.send` station over its mods bus — raised by SendMessage before it delivers a message.
1413
+ * Runner-filled; never a model argument. Absent outside a Runner: no station is raised.
1414
+ */
1415
+ sendStation?: import("./mods/session-send.js").SendStation;
1403
1416
  /**
1404
1417
  * design/80 D-B — the general "a tool yields to a HUMAN review gate" primitive. A tool calls this to request
1405
1418
  * that, at the next SAFE turn boundary, the engine pause with a durable `plan_review` checkpoint