@sema-agent/core 7.60.0 → 7.62.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 (560) hide show
  1. package/CHANGELOG.md +917 -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 +71 -12
  6. package/dist/agents/cascade.js +61 -21
  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-held-queue.d.ts +27 -4
  17. package/dist/agents/peer-held-queue.js +81 -36
  18. package/dist/agents/peer-notice-route.d.ts +1 -1
  19. package/dist/agents/peer-notice-route.js +4 -3
  20. package/dist/agents/peer-notices.d.ts +4 -4
  21. package/dist/agents/peer-notices.js +8 -4
  22. package/dist/agents/peer-session-drain.d.ts +8 -1
  23. package/dist/agents/peer-session-drain.js +49 -10
  24. package/dist/agents/repair-loop.js +16 -6
  25. package/dist/agents/retain-ledger.js +3 -1
  26. package/dist/agents/roster-store.d.ts +1 -1
  27. package/dist/agents/roster-store.js +7 -4
  28. package/dist/agents/send-message-tool.d.ts +8 -10
  29. package/dist/agents/send-message-tool.js +43 -23
  30. package/dist/agents/subagent-completion-gate.d.ts +35 -0
  31. package/dist/agents/subagent-completion-gate.js +62 -0
  32. package/dist/agents/subagent-steps.d.ts +7 -6
  33. package/dist/agents/subagent.d.ts +36 -41
  34. package/dist/agents/subagent.js +245 -200
  35. package/dist/agents/suspend-guard.d.ts +47 -16
  36. package/dist/agents/suspend-guard.js +13 -4
  37. package/dist/agents/verify.d.ts +41 -14
  38. package/dist/agents/verify.js +41 -30
  39. package/dist/brain/anthropic.js +1 -0
  40. package/dist/brain/errors.d.ts +7 -1
  41. package/dist/brain/errors.js +6 -0
  42. package/dist/brain/failover.js +2 -1
  43. package/dist/brain/open-responses.js +1 -0
  44. package/dist/brain/openai.js +1 -0
  45. package/dist/brain/provider-dialect.d.ts +10 -0
  46. package/dist/brain/provider-dialect.js +13 -2
  47. package/dist/brain/stream-engine.d.ts +3 -0
  48. package/dist/brain/stream-engine.js +4 -0
  49. package/dist/core/agent-state.d.ts +1 -1
  50. package/dist/core/allow-entry.d.ts +59 -23
  51. package/dist/core/allow-entry.js +131 -38
  52. package/dist/core/ask-origin.d.ts +79 -0
  53. package/dist/core/ask-origin.js +76 -0
  54. package/dist/core/ask-question.d.ts +19 -13
  55. package/dist/core/ask-question.js +8 -2
  56. package/dist/core/auto-compaction.d.ts +2 -0
  57. package/dist/core/auto-compaction.js +2 -1
  58. package/dist/core/auto-mode.js +3 -5
  59. package/dist/core/background-agent-store.d.ts +7 -5
  60. package/dist/core/background-agent-store.js +12 -11
  61. package/dist/core/checkpoint-features.d.ts +722 -0
  62. package/dist/core/checkpoint-features.js +98 -0
  63. package/dist/core/checkpoint-requirements.d.ts +33 -5
  64. package/dist/core/checkpoint-requirements.js +18 -5
  65. package/dist/core/checkpoint-row-verdict.d.ts +99 -0
  66. package/dist/core/checkpoint-row-verdict.js +225 -0
  67. package/dist/core/checkpoint-store.d.ts +107 -738
  68. package/dist/core/checkpoint-store.js +45 -143
  69. package/dist/core/child-clamp-seats.d.ts +3 -2
  70. package/dist/core/child-clamp-seats.js +4 -3
  71. package/dist/core/closest-name.d.ts +13 -0
  72. package/dist/core/closest-name.js +35 -0
  73. package/dist/core/context-settings.js +3 -5
  74. package/dist/core/cross-boundary-taint.d.ts +1 -1
  75. package/dist/core/decision-receipt.d.ts +14 -1
  76. package/dist/core/decision-receipt.js +6 -3
  77. package/dist/core/delegation-frames.d.ts +13 -9
  78. package/dist/core/effective-path-target.js +2 -3
  79. package/dist/core/engine-attestation.d.ts +11 -1
  80. package/dist/core/engine-attestation.js +2 -0
  81. package/dist/core/engine-notice.d.ts +68 -21
  82. package/dist/core/engine-notice.js +9 -2
  83. package/dist/core/file-history-retention.d.ts +8 -0
  84. package/dist/core/file-history-retention.js +14 -11
  85. package/dist/core/file-history-store.d.ts +31 -1
  86. package/dist/core/file-history-store.js +31 -2
  87. package/dist/core/frame-settlement.d.ts +10 -0
  88. package/dist/core/frame-settlement.js +6 -1
  89. package/dist/core/fs-write-gate-policy.d.ts +3 -3
  90. package/dist/core/fs-write-gate-policy.js +8 -7
  91. package/dist/core/gate-fold.js +4 -3
  92. package/dist/core/gate-lanes.js +7 -4
  93. package/dist/core/gate-outcome.d.ts +40 -1
  94. package/dist/core/gate-outcome.js +10 -0
  95. package/dist/core/git-worktree-env.d.ts +7 -3
  96. package/dist/core/git-worktree-env.js +16 -13
  97. package/dist/core/governance-codes.d.ts +14 -4
  98. package/dist/core/governance-codes.js +19 -4
  99. package/dist/core/hooks.d.ts +25 -4
  100. package/dist/core/hooks.js +11 -4
  101. package/dist/core/host-floor.js +3 -5
  102. package/dist/core/human-input-projection.d.ts +1 -0
  103. package/dist/core/human-input-projection.js +3 -0
  104. package/dist/core/image-admission.d.ts +47 -7
  105. package/dist/core/image-admission.js +35 -4
  106. package/dist/core/input-author.d.ts +36 -0
  107. package/dist/core/input-author.js +39 -0
  108. package/dist/core/leg-identity.d.ts +62 -0
  109. package/dist/core/leg-identity.js +18 -0
  110. package/dist/core/locked-config.d.ts +4 -3
  111. package/dist/core/locked-config.js +5 -3
  112. package/dist/core/lsp.d.ts +5 -3
  113. package/dist/core/lsp.js +3 -2
  114. package/dist/core/mailbox-store.d.ts +85 -10
  115. package/dist/core/mailbox-store.js +31 -10
  116. package/dist/core/mcp-connection-pool.d.ts +6 -20
  117. package/dist/core/mcp-connection-pool.js +10 -28
  118. package/dist/core/mcp-failure.d.ts +76 -15
  119. package/dist/core/mcp-failure.js +60 -33
  120. package/dist/core/mcp-host-seat.d.ts +92 -53
  121. package/dist/core/mcp-host-seat.js +225 -46
  122. package/dist/core/mcp-probe.js +2 -2
  123. package/dist/core/mcp-server-link.d.ts +18 -6
  124. package/dist/core/mcp-server-link.js +19 -4
  125. package/dist/core/mcp-server-spec.d.ts +2 -1
  126. package/dist/core/mcp-session-end.d.ts +1 -2
  127. package/dist/core/mcp-session-end.js +1 -1
  128. package/dist/core/mcp.d.ts +6 -49
  129. package/dist/core/mcp.js +115 -111
  130. package/dist/core/media-byte-cap.d.ts +21 -46
  131. package/dist/core/media-byte-cap.js +55 -55
  132. package/dist/core/member-group.d.ts +7 -0
  133. package/dist/core/member-group.js +35 -0
  134. package/dist/core/memory-engine/consolidation-driver.d.ts +1 -1
  135. package/dist/core/memory-engine/consolidation.d.ts +1 -1
  136. package/dist/core/memory-engine/consolidation.js +7 -1
  137. package/dist/core/memory-engine/dual-root.d.ts +31 -0
  138. package/dist/core/memory-engine/dual-root.js +59 -11
  139. package/dist/core/memory-engine/engine.js +27 -24
  140. package/dist/core/memory-engine/file-backend.d.ts +13 -0
  141. package/dist/core/memory-engine/file-backend.js +35 -15
  142. package/dist/core/memory-engine/layout.d.ts +3 -0
  143. package/dist/core/memory-engine/layout.js +13 -3
  144. package/dist/core/memory-engine/memory-deployment.d.ts +110 -0
  145. package/dist/core/memory-engine/memory-deployment.js +182 -0
  146. package/dist/core/memory-engine/sync-client.d.ts +39 -18
  147. package/dist/core/memory-engine/sync-client.js +72 -14
  148. package/dist/core/memory-engine/sync-report.d.ts +7 -4
  149. package/dist/core/memory-engine/sync.d.ts +9 -1
  150. package/dist/core/memory-vector.d.ts +1 -1
  151. package/dist/core/memory.d.ts +10 -10
  152. package/dist/core/mode-policy.d.ts +8 -8
  153. package/dist/core/mode-policy.js +8 -6
  154. package/dist/core/mods/agent-stations.d.ts +39 -4
  155. package/dist/core/mods/agent-stations.js +59 -10
  156. package/dist/core/mods/classic-events.d.ts +9 -1
  157. package/dist/core/mods/dollar.d.ts +94 -1
  158. package/dist/core/mods/dollar.js +13 -1
  159. package/dist/core/mods/extension-call.d.ts +15 -1
  160. package/dist/core/mods/extension-call.js +7 -2
  161. package/dist/core/mods/kernel/dispatch.d.ts +4 -3
  162. package/dist/core/mods/kernel/dispatch.js +4 -4
  163. package/dist/core/mods/kernel/events.d.ts +14 -3
  164. package/dist/core/mods/kernel/events.js +18 -15
  165. package/dist/core/mods/kernel/registration.d.ts +3 -0
  166. package/dist/core/mods/kernel/registration.js +5 -0
  167. package/dist/core/mods/kernel/site-rules.d.ts +6 -3
  168. package/dist/core/mods/kernel/site-rules.js +10 -2
  169. package/dist/core/mods/lifecycle-stations.d.ts +36 -4
  170. package/dist/core/mods/lifecycle-stations.js +44 -9
  171. package/dist/core/mods/session-append.d.ts +118 -0
  172. package/dist/core/mods/session-append.js +318 -0
  173. package/dist/core/mods/session-compact.d.ts +48 -0
  174. package/dist/core/mods/session-compact.js +194 -0
  175. package/dist/core/mods/session-receive.d.ts +93 -0
  176. package/dist/core/mods/session-receive.js +138 -0
  177. package/dist/core/mods/session-send.d.ts +72 -0
  178. package/dist/core/mods/session-send.js +88 -0
  179. package/dist/core/mods/stations.d.ts +88 -21
  180. package/dist/core/mods/stations.js +149 -11
  181. package/dist/core/mods/tool-call.d.ts +2 -0
  182. package/dist/core/mods/tool-call.js +4 -4
  183. package/dist/core/output-style.js +3 -4
  184. package/dist/core/own-property-receipt.d.ts +68 -2
  185. package/dist/core/own-property-receipt.js +45 -2
  186. package/dist/core/park-selfcheck.js +4 -2
  187. package/dist/core/path-identity.d.ts +11 -0
  188. package/dist/core/path-identity.js +4 -0
  189. package/dist/core/path-rule-binding.d.ts +3 -1
  190. package/dist/core/path-rule-binding.js +3 -1
  191. package/dist/core/peer-seat.d.ts +3 -3
  192. package/dist/core/peer-seat.js +20 -8
  193. package/dist/core/permission-rule-consent.d.ts +21 -5
  194. package/dist/core/permission-rule-consent.js +21 -1
  195. package/dist/core/permission-rule-model.d.ts +34 -11
  196. package/dist/core/permission-rule-model.js +47 -10
  197. package/dist/core/permission-rule-org.d.ts +1 -1
  198. package/dist/core/permission-rule-provider.js +4 -1
  199. package/dist/core/permission-rules.d.ts +4 -0
  200. package/dist/core/permission-rules.js +11 -16
  201. package/dist/core/read-root-candidate.js +1 -1
  202. package/dist/core/remote-env.d.ts +74 -26
  203. package/dist/core/remote-env.js +20 -0
  204. package/dist/core/resume-startup-cause.d.ts +5 -4
  205. package/dist/core/retention-policy.d.ts +24 -23
  206. package/dist/core/retention-policy.js +36 -2
  207. package/dist/core/retention.d.ts +4 -1
  208. package/dist/core/retired-keys.d.ts +4 -4
  209. package/dist/core/row-admission.d.ts +10 -0
  210. package/dist/core/row-admission.js +5 -0
  211. package/dist/core/runner/advisor-instructions.d.ts +2 -1
  212. package/dist/core/runner/advisor-instructions.js +2 -1
  213. package/dist/core/runner/announce-once-ledger.d.ts +4 -4
  214. package/dist/core/runner/assemble-result.d.ts +13 -3
  215. package/dist/core/runner/assemble-result.js +12 -7
  216. package/dist/core/runner/caller-roster.d.ts +12 -9
  217. package/dist/core/runner/caller-roster.js +5 -2
  218. package/dist/core/runner/checkpoint-scope.d.ts +16 -1
  219. package/dist/core/runner/checkpoint-scope.js +21 -0
  220. package/dist/core/runner/compact-session.js +18 -3
  221. package/dist/core/runner/compaction-call-options.d.ts +1 -1
  222. package/dist/core/runner/compaction-restate.d.ts +2 -2
  223. package/dist/core/runner/compaction-restate.js +4 -3
  224. package/dist/core/runner/construction-doors.d.ts +2 -2
  225. package/dist/core/runner/construction-doors.js +2 -2
  226. package/dist/core/runner/contracts.d.ts +116 -34
  227. package/dist/core/runner/cross-boundary-lane.d.ts +1 -1
  228. package/dist/core/runner/decide-continuation.d.ts +4 -2
  229. package/dist/core/runner/decide-continuation.js +7 -4
  230. package/dist/core/runner/delegation-owner.d.ts +43 -0
  231. package/dist/core/runner/delegation-owner.js +59 -0
  232. package/dist/core/runner/denial-limit-arms.d.ts +15 -21
  233. package/dist/core/runner/denial-limit-arms.js +17 -10
  234. package/dist/core/runner/expire-settle.d.ts +44 -0
  235. package/dist/core/runner/expire-settle.js +55 -0
  236. package/dist/core/runner/git-status-frame.d.ts +3 -3
  237. package/dist/core/runner/git-status-frame.js +2 -1
  238. package/dist/core/runner/halt-attribution.d.ts +2 -1
  239. package/dist/core/runner/halt-attribution.js +2 -1
  240. package/dist/core/runner/lineage-reroot-view.d.ts +56 -0
  241. package/dist/core/runner/lineage-reroot-view.js +108 -0
  242. package/dist/core/runner/local-claims.d.ts +17 -0
  243. package/dist/core/runner/local-claims.js +18 -0
  244. package/dist/core/runner/media-removed-seat.d.ts +46 -0
  245. package/dist/core/runner/media-removed-seat.js +88 -0
  246. package/dist/core/runner/park-commit.d.ts +2 -2
  247. package/dist/core/runner/permission-rule-lanes.d.ts +7 -2
  248. package/dist/core/runner/permission-rule-lanes.js +28 -9
  249. package/dist/core/runner/person-path-rows.d.ts +15 -0
  250. package/dist/core/runner/person-path-rows.js +27 -4
  251. package/dist/core/runner/placement-fence.d.ts +26 -0
  252. package/dist/core/runner/placement-fence.js +38 -0
  253. package/dist/core/runner/prepare-acquire-reconcile.d.ts +4 -1
  254. package/dist/core/runner/prepare-acquire-reconcile.js +7 -2
  255. package/dist/core/runner/prepare-ask-lane.d.ts +6 -12
  256. package/dist/core/runner/prepare-ask-lane.js +4 -4
  257. package/dist/core/runner/prepare-boundary-parks.d.ts +4 -1
  258. package/dist/core/runner/prepare-boundary-parks.js +2 -2
  259. package/dist/core/runner/prepare-caps-and-workflow.d.ts +3 -0
  260. package/dist/core/runner/prepare-caps-and-workflow.js +2 -1
  261. package/dist/core/runner/prepare-config-doors.d.ts +6 -6
  262. package/dist/core/runner/prepare-config-doors.js +19 -21
  263. package/dist/core/runner/prepare-context-lane.d.ts +6 -2
  264. package/dist/core/runner/prepare-context-lane.js +13 -13
  265. package/dist/core/runner/prepare-delegation-surface.d.ts +9 -9
  266. package/dist/core/runner/prepare-delegation-surface.js +4 -5
  267. package/dist/core/runner/prepare-execution-env.d.ts +5 -2
  268. package/dist/core/runner/prepare-execution-env.js +7 -4
  269. package/dist/core/runner/prepare-gate-stations.d.ts +19 -14
  270. package/dist/core/runner/prepare-gate-stations.js +6 -4
  271. package/dist/core/runner/prepare-hands-readface.d.ts +6 -6
  272. package/dist/core/runner/prepare-hands-readface.js +32 -11
  273. package/dist/core/runner/prepare-inherited-gate.d.ts +8 -0
  274. package/dist/core/runner/prepare-inherited-gate.js +10 -3
  275. package/dist/core/runner/prepare-lsp.d.ts +3 -0
  276. package/dist/core/runner/prepare-lsp.js +2 -2
  277. package/dist/core/runner/prepare-park-ask.d.ts +5 -2
  278. package/dist/core/runner/prepare-park-ask.js +4 -5
  279. package/dist/core/runner/prepare-policy-chain.d.ts +10 -21
  280. package/dist/core/runner/prepare-policy-chain.js +16 -25
  281. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  282. package/dist/core/runner/prepare-prompt-inputs.d.ts +5 -4
  283. package/dist/core/runner/prepare-prompt-inputs.js +3 -2
  284. package/dist/core/runner/prepare-question-face.d.ts +6 -4
  285. package/dist/core/runner/prepare-question-face.js +2 -2
  286. package/dist/core/runner/prepare-run-refs.d.ts +3 -0
  287. package/dist/core/runner/prepare-run-refs.js +2 -2
  288. package/dist/core/runner/prepare-suspend-saga.d.ts +11 -7
  289. package/dist/core/runner/prepare-suspend-saga.js +17 -7
  290. package/dist/core/runner/prepare-task.d.ts +1 -1
  291. package/dist/core/runner/prepare-task.js +61 -30
  292. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +6 -0
  293. package/dist/core/runner/prepare-tool-disclosure-mount.js +3 -1
  294. package/dist/core/runner/prepare-wiring-manifest.d.ts +3 -0
  295. package/dist/core/runner/prepare-wiring-manifest.js +2 -1
  296. package/dist/core/runner/prepare-workspace-restore.d.ts +5 -0
  297. package/dist/core/runner/prepare-workspace-restore.js +10 -6
  298. package/dist/core/runner/read-root-grant.d.ts +1 -1
  299. package/dist/core/runner/read-root-grant.js +2 -1
  300. package/dist/core/runner/resume-admission.d.ts +8 -6
  301. package/dist/core/runner/resume-admission.js +23 -6
  302. package/dist/core/runner/resume-apply.d.ts +4 -0
  303. package/dist/core/runner/resume-apply.js +14 -5
  304. package/dist/core/runner/resume-checkpoint-screen.d.ts +9 -0
  305. package/dist/core/runner/resume-checkpoint-screen.js +4 -84
  306. package/dist/core/runner/resume-claim.d.ts +8 -3
  307. package/dist/core/runner/resume-claim.js +28 -12
  308. package/dist/core/runner/resume-internals-and-config.d.ts +2 -2
  309. package/dist/core/runner/resume-internals-and-config.js +10 -1
  310. package/dist/core/runner/resume-preflight.d.ts +3 -2
  311. package/dist/core/runner/resume-preflight.js +13 -26
  312. package/dist/core/runner/retired-runner-deps.js +2 -0
  313. package/dist/core/runner/run-git-lane.d.ts +2 -0
  314. package/dist/core/runner/run-git-lane.js +6 -2
  315. package/dist/core/runner/run-harness-handlers.d.ts +2 -0
  316. package/dist/core/runner/run-harness-handlers.js +5 -4
  317. package/dist/core/runner/run-identity-wiring.d.ts +2 -2
  318. package/dist/core/runner/run-identity-wiring.js +14 -5
  319. package/dist/core/runner/run-leg.d.ts +3 -3
  320. package/dist/core/runner/run-leg.js +64 -36
  321. package/dist/core/runner/run-notification-lane.js +20 -2
  322. package/dist/core/runner/run-recovery-lanes.js +3 -2
  323. package/dist/core/runner/run-settle-and-teardown.js +12 -9
  324. package/dist/core/runner/run-stop-and-final-verify.js +2 -1
  325. package/dist/core/runner/run-telemetry-and-budget-seats.d.ts +1 -1
  326. package/dist/core/runner/run-terminal-adoption.d.ts +1 -1
  327. package/dist/core/runner/run-terminal-adoption.js +26 -17
  328. package/dist/core/runner/run-turn-boundary.js +34 -18
  329. package/dist/core/runner/runtask.d.ts +18 -3
  330. package/dist/core/runner/runtask.js +33 -17
  331. package/dist/core/runner/session-rule-policy.d.ts +1 -1
  332. package/dist/core/runner/session-rule-policy.js +6 -1
  333. package/dist/core/runner/shell-env-withheld.d.ts +1 -1
  334. package/dist/core/runner/steering-preview.d.ts +9 -0
  335. package/dist/core/runner/steering-preview.js +5 -0
  336. package/dist/core/runner/stream-halt-verbs.d.ts +1 -14
  337. package/dist/core/runner/stream-halt-verbs.js +4 -3
  338. package/dist/core/runner/stream-reap.d.ts +7 -6
  339. package/dist/core/runner/stream-reap.js +13 -16
  340. package/dist/core/runner/stream-settle-backstop.d.ts +3 -2
  341. package/dist/core/runner/stream-settle-backstop.js +5 -3
  342. package/dist/core/runner/stream-steer-verb.d.ts +5 -2
  343. package/dist/core/runner/stream-steer-verb.js +16 -7
  344. package/dist/core/runner/terminal-account.d.ts +11 -1
  345. package/dist/core/runner/terminal-account.js +20 -0
  346. package/dist/core/runner/terminal-projection.d.ts +8 -2
  347. package/dist/core/runner/terminal-projection.js +2 -2
  348. package/dist/core/runner/tool-disclosure.d.ts +3 -0
  349. package/dist/core/runner/tool-disclosure.js +5 -2
  350. package/dist/core/runner/tool-end-body.d.ts +3 -3
  351. package/dist/core/runner/tool-end-body.js +1 -1
  352. package/dist/core/runner/tool-face-overlay.js +2 -0
  353. package/dist/core/runner/tool-output-projection.d.ts +3 -3
  354. package/dist/core/runner/tool-output-projection.js +7 -6
  355. package/dist/core/runner/tool-table-view.d.ts +56 -0
  356. package/dist/core/runner/tool-table-view.js +51 -0
  357. package/dist/core/runner/turn-attachments.d.ts +8 -2
  358. package/dist/core/runner/turn-attachments.js +2 -2
  359. package/dist/core/runner/void-verifier-pause.d.ts +33 -0
  360. package/dist/core/runner/void-verifier-pause.js +41 -0
  361. package/dist/core/runner-deps.d.ts +26 -27
  362. package/dist/core/secret-env.d.ts +19 -16
  363. package/dist/core/secret-env.js +45 -27
  364. package/dist/core/session-log-transfer.js +9 -10
  365. package/dist/core/session-policy-store.d.ts +1 -1
  366. package/dist/core/session-policy-store.js +5 -2
  367. package/dist/core/session-reconcile.d.ts +3 -2
  368. package/dist/core/session-reconcile.js +7 -4
  369. package/dist/core/session-store.d.ts +3 -1
  370. package/dist/core/session-store.js +10 -8
  371. package/dist/core/session.d.ts +16 -5
  372. package/dist/core/shell-confinement.d.ts +37 -0
  373. package/dist/core/shell-confinement.js +56 -0
  374. package/dist/core/skill-grant.js +1 -1
  375. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +8 -2
  376. package/dist/core/store-contracts/checkpoint-store-contract.js +83 -2
  377. package/dist/core/store-contracts/file-history-store-contract.d.ts +5 -2
  378. package/dist/core/store-contracts/file-history-store-contract.js +25 -1
  379. package/dist/core/store-contracts/mailbox-store-contract.d.ts +12 -5
  380. package/dist/core/store-contracts/mailbox-store-contract.js +156 -9
  381. package/dist/core/store-contracts/session-store-contract.js +22 -8
  382. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  383. package/dist/core/store-contracts/tool-result-store-contract.js +30 -0
  384. package/dist/core/task-event.d.ts +24 -9
  385. package/dist/core/task-limits.d.ts +5 -0
  386. package/dist/core/task-notification.d.ts +89 -12
  387. package/dist/core/task-notification.js +89 -14
  388. package/dist/core/task-registry-agent.d.ts +32 -50
  389. package/dist/core/task-registry-agent.js +36 -56
  390. package/dist/core/task-registry-monitor.d.ts +1 -1
  391. package/dist/core/task-registry-monitor.js +15 -60
  392. package/dist/core/task-registry-shared.d.ts +22 -112
  393. package/dist/core/task-registry-shared.js +3 -41
  394. package/dist/core/task-registry-workflow.js +5 -21
  395. package/dist/core/task-registry.d.ts +32 -62
  396. package/dist/core/task-registry.js +30 -110
  397. package/dist/core/task-result.d.ts +29 -12
  398. package/dist/core/task-spec-members.d.ts +39 -0
  399. package/dist/core/task-spec-members.js +92 -0
  400. package/dist/core/task-spec.d.ts +11 -11
  401. package/dist/core/task-tool-shape.d.ts +7 -57
  402. package/dist/core/task-tool-shape.js +7 -66
  403. package/dist/core/terminal-cause.d.ts +36 -6
  404. package/dist/core/terminal-cause.js +1 -0
  405. package/dist/core/tool-catalog-entries.js +2 -5
  406. package/dist/core/tool-check-reading.js +16 -10
  407. package/dist/core/tool-conformance.js +1 -2
  408. package/dist/core/tool-errors.d.ts +6 -3
  409. package/dist/core/tool-errors.js +2 -0
  410. package/dist/core/tool-face-reader.js +3 -2
  411. package/dist/core/tool-face.d.ts +8 -5
  412. package/dist/core/tool-face.js +1 -1
  413. package/dist/core/tool-name-aliases.d.ts +5 -29
  414. package/dist/core/tool-name-aliases.js +9 -5
  415. package/dist/core/tool-name-readings.d.ts +14 -3
  416. package/dist/core/tool-name-readings.js +2 -0
  417. package/dist/core/tool-policy.d.ts +109 -18
  418. package/dist/core/tool-policy.js +84 -14
  419. package/dist/core/tool-result-store.d.ts +23 -0
  420. package/dist/core/tool-result-store.js +3 -2
  421. package/dist/core/tool-roster.d.ts +4 -4
  422. package/dist/core/tool-spec.d.ts +23 -6
  423. package/dist/core/trace.d.ts +18 -1
  424. package/dist/core/types.d.ts +1 -1
  425. package/dist/core/types.js +1 -1
  426. package/dist/core/user-attachment.js +26 -21
  427. package/dist/core/workflow-journal-store.d.ts +1 -1
  428. package/dist/core/workflow-run-store.d.ts +2 -0
  429. package/dist/core/workflow-run-store.js +6 -5
  430. package/dist/core/workflow-settled-run.d.ts +5 -0
  431. package/dist/core/workflow-settled-run.js +7 -0
  432. package/dist/engine/execution-env/node-execution-env.d.ts +37 -9
  433. package/dist/engine/execution-env/node-execution-env.js +221 -22
  434. package/dist/engine/harness/agent-harness.d.ts +65 -18
  435. package/dist/engine/harness/agent-harness.js +90 -23
  436. package/dist/engine/harness/messages.d.ts +4 -3
  437. package/dist/engine/harness/messages.js +2 -2
  438. package/dist/engine/harness/types.d.ts +52 -7
  439. package/dist/engine/llm/media-removed.d.ts +14 -0
  440. package/dist/engine/llm/media-removed.js +9 -0
  441. package/dist/engine/llm/rejected-images.d.ts +35 -25
  442. package/dist/engine/llm/rejected-images.js +59 -10
  443. package/dist/engine/llm/types.d.ts +24 -3
  444. package/dist/engine/llm/types.js +7 -3
  445. package/dist/engine/loop/agent-loop.d.ts +6 -1
  446. package/dist/engine/loop/agent-loop.js +20 -11
  447. package/dist/engine/loop/types.d.ts +12 -3
  448. package/dist/engine/session/import-validate.js +7 -0
  449. package/dist/engine/session/parent-chain-guard.d.ts +3 -3
  450. package/dist/engine/session/parent-chain-guard.js +1 -1
  451. package/dist/engine/session/path-to-root.d.ts +18 -3
  452. package/dist/engine/session/path-to-root.js +15 -1
  453. package/dist/engine/session/repo-utils.d.ts +12 -1
  454. package/dist/engine/session/repo-utils.js +41 -0
  455. package/dist/engine/session/session.js +1 -1
  456. package/dist/engine/session/storage-base.d.ts +20 -0
  457. package/dist/engine/session/storage-base.js +28 -9
  458. package/dist/fixtures/index.d.ts +7 -5
  459. package/dist/fixtures/index.js +5 -3
  460. package/dist/index.d.ts +29 -18
  461. package/dist/index.js +19 -11
  462. package/dist/internal/harness-types.d.ts +2 -0
  463. package/dist/internal/harness.d.ts +4 -3
  464. package/dist/internal/harness.js +3 -2
  465. package/dist/internal/llm.d.ts +2 -1
  466. package/dist/internal/llm.js +1 -0
  467. package/dist/orchestration/goal.d.ts +6 -2
  468. package/dist/orchestration/goal.js +6 -3
  469. package/dist/orchestration/run-workflow-tool.d.ts +14 -17
  470. package/dist/orchestration/run-workflow-tool.js +43 -50
  471. package/dist/orchestration/workflow-types.d.ts +2 -2
  472. package/dist/orchestration/workflow.d.ts +7 -0
  473. package/dist/orchestration/workflow.js +10 -12
  474. package/dist/stores/file/background-agent-store.js +18 -15
  475. package/dist/stores/file/checkpoint-store.d.ts +2 -0
  476. package/dist/stores/file/checkpoint-store.js +13 -9
  477. package/dist/stores/file/file-history-store.js +3 -2
  478. package/dist/stores/file/fs-atomic.d.ts +0 -22
  479. package/dist/stores/file/fs-atomic.js +0 -17
  480. package/dist/stores/file/index.d.ts +7 -12
  481. package/dist/stores/file/index.js +25 -12
  482. package/dist/stores/file/ledger-tuning.d.ts +23 -0
  483. package/dist/stores/file/ledger-tuning.js +21 -0
  484. package/dist/stores/file/mailbox-store.js +42 -22
  485. package/dist/stores/file/memory-store.js +3 -2
  486. package/dist/stores/file/permission-rule-adopt.js +24 -21
  487. package/dist/stores/file/permission-rule-store.js +6 -3
  488. package/dist/stores/file/session-policy-store.js +3 -2
  489. package/dist/stores/file/session-store.d.ts +26 -7
  490. package/dist/stores/file/session-store.js +59 -35
  491. package/dist/stores/file/tool-result-store.d.ts +11 -0
  492. package/dist/stores/file/tool-result-store.js +57 -3
  493. package/dist/stores/file/usage-window-store.js +3 -2
  494. package/dist/stores/file/workflow-journal-store.d.ts +0 -2
  495. package/dist/stores/file/workflow-journal-store.js +3 -18
  496. package/dist/stores/file/workflow-run-store.d.ts +1 -1
  497. package/dist/stores/file/workflow-run-store.js +15 -10
  498. package/dist/tools/fs/bash-program-position.d.ts +3 -2
  499. package/dist/tools/fs/bash-program-position.js +7 -7
  500. package/dist/tools/fs/dead-cwd.d.ts +5 -5
  501. package/dist/tools/fs/dead-cwd.js +4 -11
  502. package/dist/tools/fs/fs-bash-background-text.d.ts +6 -0
  503. package/dist/tools/fs/fs-bash-background-text.js +6 -0
  504. package/dist/tools/fs/fs-bash.d.ts +3 -18
  505. package/dist/tools/fs/fs-bash.js +37 -124
  506. package/dist/tools/fs/fs-pdf.js +8 -6
  507. package/dist/tools/fs/fs-read.js +2 -2
  508. package/dist/tools/fs/fs-shared.d.ts +28 -3
  509. package/dist/tools/fs/fs-shared.js +15 -0
  510. package/dist/tools/fs/index.d.ts +1 -1
  511. package/dist/tools/fs/index.js +4 -14
  512. package/dist/tools/fs/pdf.d.ts +4 -4
  513. package/dist/tools/fs/pdf.js +6 -6
  514. package/dist/tools/fs/read-deny-home.js +8 -1
  515. package/dist/tools/fs/read-deny.d.ts +26 -2
  516. package/dist/tools/fs/read-deny.js +9 -2
  517. package/dist/tools/fs/read-floor.d.ts +13 -5
  518. package/dist/tools/fs/read-floor.js +206 -2
  519. package/dist/tools/fs/removal-targets.js +2 -2
  520. package/dist/tools/fs/search.d.ts +3 -2
  521. package/dist/tools/fs/search.js +6 -6
  522. package/dist/tools/fs/shell-read-argv.d.ts +4 -2
  523. package/dist/tools/fs/shell-read-argv.js +14 -3
  524. package/dist/tools/fs/shell-read-bindings.d.ts +18 -2
  525. package/dist/tools/fs/shell-read-bindings.js +148 -68
  526. package/dist/tools/fs/shell-read-check.js +20 -4
  527. package/dist/tools/fs/shell-read-establish.js +25 -9
  528. package/dist/tools/fs/shell-read-functions.js +2 -2
  529. package/dist/tools/fs/shell-read-identity.d.ts +3 -1
  530. package/dist/tools/fs/shell-read-identity.js +4 -2
  531. package/dist/tools/fs/shell-read-judge.d.ts +7 -1
  532. package/dist/tools/fs/shell-read-judge.js +1 -1
  533. package/dist/tools/fs/shell-read-object-path.d.ts +59 -0
  534. package/dist/tools/fs/shell-read-object-path.js +119 -0
  535. package/dist/tools/fs/shell-read-plan.d.ts +8 -0
  536. package/dist/tools/fs/shell-read-plan.js +47 -30
  537. package/dist/tools/fs/shell-read-start.d.ts +66 -13
  538. package/dist/tools/fs/shell-read-start.js +89 -17
  539. package/dist/tools/fs/shell-read-workdir.d.ts +29 -8
  540. package/dist/tools/fs/shell-read-workdir.js +31 -8
  541. package/dist/tools/monitor.d.ts +8 -7
  542. package/dist/tools/monitor.js +12 -10
  543. package/dist/tools/worktree.d.ts +5 -1
  544. package/dist/tools/worktree.js +20 -17
  545. package/package.json +6 -3
  546. package/test/export-surface.snapshot.json +112 -42
  547. package/wire-changes/core-stores-sql@7.61.0.json +480 -0
  548. package/wire-changes/core-stores-sql@7.62.0.json +30 -0
  549. package/wire-changes/core@7.61.0.json +4405 -0
  550. package/wire-changes/core@7.62.0.json +2181 -0
  551. package/wire-changes/mods-kernel@7.61.0.json +65 -0
  552. package/wire-changes/mods-kernel@7.62.0.json +42 -0
  553. package/wire-changes/primitives@7.61.0.json +30 -0
  554. package/wire-changes/primitives@7.62.0.json +30 -0
  555. package/dist/core/consolidate-scope.d.ts +0 -93
  556. package/dist/core/consolidate-scope.js +0 -98
  557. package/dist/core/runner/image-removed-seat.d.ts +0 -12
  558. package/dist/core/runner/image-removed-seat.js +0 -19
  559. package/dist/core/runner/memory-consolidation.d.ts +0 -109
  560. package/dist/core/runner/memory-consolidation.js +0 -251
@@ -2,7 +2,7 @@
2
2
  * A background agent's CURRENT state — the one reading every read face renders.
3
3
  *
4
4
  * A parent model answers "how far along is it?" from what its read faces show. Three faces read a
5
- * background agent: AgentTranscript (its recent steps), ListAgents (the roster) and TaskOutput (the poll).
5
+ * background agent: AgentTranscript (its recent steps), ListAgents (the roster) and the host task poll.
6
6
  * Each one projects {@link readAgentState}'s result and renders it with {@link agentStateSummary} /
7
7
  * {@link agentActivityClause} / {@link agentApprovalClause}; none derives status, activity time or approval
8
8
  * facts on its own, so the three cannot disagree about one agent at one instant.
@@ -1,6 +1,6 @@
1
1
  import type { EditRewritten } from "./rewrite-rejudge.js";
2
2
  import { type RuleToolNameVerdict } from "./tool-name-aliases.js";
3
- import type { ToolCallRequest } from "./tool-policy.js";
3
+ import type { ToolCallRequest, ToolIdentity } from "./tool-policy.js";
4
4
  import { type AllowRuleMember, type AllowRuleShadow } from "./allow-rule-shadow.js";
5
5
  import { type AdmissionPosture, type PathRuleBases, type PersistedRule } from "./permission-rule-model.js";
6
6
  import { type AskClass, type AssertAllKeysHandled, type PermissionMode, type PersistedRuleMandate } from "./ask-origin.js";
@@ -142,15 +142,18 @@ export declare function autoStrippedRule(rule: PersistedRule, call: ToolCallRequ
142
142
  export declare function classifiesAllShell(spec: {
143
143
  readonly classifyAllShell?: boolean;
144
144
  }): boolean;
145
- /** One row a list matcher reads. */
145
+ /** One row a list matcher reads. `pathBases`: the anchors the row's RULE SET declares ({@link AllowListEntry}) — absent, the set
146
+ * declares none and its path rule reads at the list's installation ({@link AllowEntryJudgeContext.anchors}). */
146
147
  export interface AllowEntryRow {
147
148
  readonly behavior: "allow" | "deny";
148
149
  readonly entry: string;
149
150
  readonly compiled: CompiledAllowEntry;
151
+ readonly pathBases?: PathRuleBases;
150
152
  }
151
153
  /** The facts a list's content row is judged under: the leg's root and session (which rows apply), the live working
152
154
  * directory (where a command's `cd` lands), and the ANCHORS of the list's path rows — the leg the list was installed
153
- * on (its root and environment home): a path row of a list never moves with a `cd`. `classifyAllShell`: the leg's
155
+ * on (its root and environment home), which a row's own set declaration overrides word by word (`policyAnchors`, the one
156
+ * reading a deny / ask rule set's `pathBases` takes): a path row of a list never moves with a `cd`. `classifyAllShell`: the leg's
154
157
  * declaration ({@link classifiesAllShell}) the auto strip reads ({@link strippedInAuto}); absent ⇒ the leg declared nothing. */
155
158
  export interface AllowEntryJudgeContext {
156
159
  readonly root: string | undefined;
@@ -159,10 +162,19 @@ export interface AllowEntryJudgeContext {
159
162
  readonly anchors: PathRuleBases;
160
163
  readonly classifyAllShell?: boolean;
161
164
  }
165
+ /** Which of the call's names a list's NAME rows (a whole tool, a covering spelling) read: every name it answers to — a person's,
166
+ * a skill's or a session's list (the name written reaches the tool that answers to it, the reference's proxy expansion) — or the
167
+ * wire name alone: a list handed in at launch ({@link AllowEntryTable}, the reference's CLI-argument source, which it does not
168
+ * expand through an alias). */
169
+ export type ListNameReach = "every_name" | "wire_name";
162
170
  /** For a list whose allow rows admitted no call ({@link judgeAllowEntries}): the first segment of the call's command no command
163
171
  * row covers under `posture` — the word a refusal names; `undefined` when the call carries no command or no single segment is
164
172
  * to blame (a line the matcher cannot read at all). The same walk the matcher took. */
165
173
  export declare function uncoveredCommandSegment(rows: readonly AllowEntryRow[], req: ToolCallRequest, ctx: AllowEntryJudgeContext, posture: AdmissionPosture): string | undefined;
174
+ /** The list's first `behavior` row that names the tool WHOLE (a tool name, a covering spelling) and so speaks for every call of
175
+ * it, whatever the call carries — the list matcher's first step ({@link judgeAllowEntries}), and the whole-tool reading of a
176
+ * deny list (the model's tool table leaves such a tool out). */
177
+ export declare function wholeToolEntryOf<R extends AllowEntryRow>(rows: readonly R[], tool: ToolIdentity, behavior: "allow" | "deny", names?: ListNameReach): R | undefined;
166
178
  /**
167
179
  * The ONE list matcher, both directions — the rows that speak for the call, or undefined. A tool-name row first (the first
168
180
  * that reaches the call); then the content rows, each family by the predicate the stored rows of that grammar meet:
@@ -175,13 +187,29 @@ export declare function uncoveredCommandSegment(rows: readonly AllowEntryRow[],
175
187
  * face carries, `nameRuleReach`); a closed-set tool's call naming no value is refused by a deny list's row of the tool and granted
176
188
  * by no allow row (the persisted walk's reading, `nameValueAbsentReason`), a mounted tool's call whose face carries no values is
177
189
  * refused by a deny list's row of the tool and granted by no allow row, and a call whose host cannot be read is refused by a deny
178
- * list's host row and granted by no allow row (`adjudicatePersistedDomainRules`).
190
+ * list's host row and granted by no allow row (`adjudicatePersistedDomainRules`). A content row reaches the call under the words
191
+ * of its direction ({@link ruleWordsOf}: a deny under every name the call answers to, an allow under its wire name); a name row
192
+ * under the list's `names` ({@link ListNameReach}).
179
193
  */
180
- export declare function judgeAllowEntries<R extends AllowEntryRow>(rows: readonly R[], req: ToolCallRequest, behavior: "allow" | "deny", ctx: AllowEntryJudgeContext, posture?: AdmissionPosture): readonly R[] | undefined;
194
+ export declare function judgeAllowEntries<R extends AllowEntryRow>(rows: readonly R[], req: ToolCallRequest, behavior: "allow" | "deny", ctx: AllowEntryJudgeContext, posture?: AdmissionPosture, names?: ListNameReach): readonly R[] | undefined;
181
195
  /** The allow rows of a list, as the allow layer reads them in `mode`: the strip applied BEFORE the match (in `auto`). */
182
196
  export declare function allowingRows<R extends AllowEntryRow>(rows: readonly R[], req: ToolCallRequest, mode: PermissionMode | undefined, allShell: boolean): readonly R[];
183
197
  /** The two sources {@link AllowEntryTable} holds (a skill's list is the skill table's). */
184
198
  export type AllowEntrySource = "request" | "deployment";
199
+ /**
200
+ * One member of an allow list handed in at launch (`TaskSpec.allowedTools`, `RunnerDeps.allowedTools`): a rule — or a rule with
201
+ * the ANCHORS of the rule SET it belongs to, `pathBases`, the seat a deny / ask rule set declares
202
+ * (`PermissionRulePolicyOptions.pathBases`), read the same one way: each word the set declares, else the leg the list is installed
203
+ * on (`policyAnchors`). The members that declare the same anchors are one set — one settings layer's rules: `root` = that layer's
204
+ * root (the configuration directory for a user layer, the task root for a project or local layer) and `cwd` = the task root, so
205
+ * a user layer's `Read(/x)` allow reaches `<config>/x` and not `<task>/x`. A string declares nothing: its path rule reads at the
206
+ * anchors the list is installed with, as handed, as it always did — and a member that declares nothing is written as that
207
+ * string (an empty `pathBases` is refused). The anchors speak to a path rule only (a rule that names no path reads none of them).
208
+ */
209
+ export type AllowListEntry = string | {
210
+ readonly rule: string;
211
+ readonly pathBases: PathRuleBases;
212
+ };
185
213
  /** What spoke for a call: the entries it stands on, as the list spells them, and — for entries of the list the run received —
186
214
  * the index of every element of that list that is one of them (a string listed twice has both). */
187
215
  export interface AllowEntryHit {
@@ -220,22 +248,27 @@ export interface AllowEntryGateSeats {
220
248
  */
221
249
  export declare class AllowEntryTable {
222
250
  private held;
223
- private readonly heldEntries;
224
- /** Each entry of the list the run RECEIVED for this source, with its indices in that list — what a hit's `positions` read. */
251
+ /** The member key of every held row ({@link allowListMemberKey}: a rule and the anchors of its set). */
252
+ private readonly heldKeys;
253
+ /** Each member of the list the run RECEIVED for this source, by member key, with its indices in that list — what a hit's
254
+ * `positions` read. */
225
255
  private receivedAt;
226
- /** Write a list's rows (a row already held is not held twice). Returns the entries that read as nothing. `roster` as in
227
- * {@link readRuleEntry}: a list the leg itself wrote is read against it, a carried one (a delegating parent's capture) is not.
228
- * `received`: this list is the one the run received for the source (the request's `TaskSpec.allowedTools`, the deployment's
229
- * `RunnerDeps.allowedTools`), the list a hit's positions are read in; a carried capture is not. */
230
- seed(entries: readonly string[], reading?: {
256
+ /** Write a list's rows (a member already held — the same rule in the same set — is not held twice). Returns the entries that
257
+ * read as nothing. `roster` as in {@link readRuleEntry}: a list the leg itself wrote is read against it, a carried one (a
258
+ * delegating parent's capture) is not. `received`: this list is the one the run received for the source (the request's
259
+ * `TaskSpec.allowedTools`, the deployment's `RunnerDeps.allowedTools`), the list a hit's positions are read in; a carried
260
+ * capture is not. */
261
+ seed(entries: readonly AllowListEntry[], reading?: {
231
262
  readonly roster?: ReadonlySet<string>;
232
263
  readonly received?: true;
233
264
  }): readonly AllowEntryInert[];
234
- /** The entries held, as written (a copy) — what a delegated child is handed. */
235
- entries(): readonly string[];
265
+ /** The members held, as written (a copy) — what a delegated child is handed: a rule, with its set's anchors where the set
266
+ * declared them (the child reads its path rule at the same anchors). */
267
+ entries(): readonly AllowListEntry[];
236
268
  /** Does the table hold a path row — must the leg read each call's target views for it? */
237
269
  holdsPathRows(): boolean;
238
- /** The lane over this table, bound to the leg's call facts. */
270
+ /** The lane over this table, bound to the leg's call facts. Both sources are lists handed in at launch: every row reaches the
271
+ * call under its wire name ({@link ListNameReach} `wire_name`). */
239
272
  lane(ctx: AllowEntryJudgeContext): AllowEntryLane;
240
273
  }
241
274
  /**
@@ -253,14 +286,14 @@ export declare function seedAllowEntryTables(tables: {
253
286
  skill: string;
254
287
  list: "allowed-tools" | "disallowed-tools";
255
288
  } & AllowEntryInert>;
256
- inherited: readonly string[] | undefined;
257
- request: readonly string[] | undefined;
258
- deployment: readonly string[] | undefined;
289
+ inherited: readonly AllowListEntry[] | undefined;
290
+ request: readonly AllowListEntry[] | undefined;
291
+ deployment: readonly AllowListEntry[] | undefined;
259
292
  }, roster: ReadonlySet<string>): AllowEntryInertNote[];
260
293
  /** The deployment's allow rules, read ONCE at construction: screened (a value that is not a list of strings refuses), frozen,
261
294
  * and its dead entries announced once (no session). Returns the deps with the snapshot in place of the caller's list. */
262
295
  export declare function withDeploymentAllowedTools<D extends {
263
- readonly allowedTools?: readonly string[];
296
+ readonly allowedTools?: readonly AllowListEntry[];
264
297
  readonly onNotice?: ((n: EngineNotice) => void) | undefined;
265
298
  }>(deps: D): D;
266
299
  /** The code a list value that is not a list of strings refuses with — the policy compiler's family, with its issues. */
@@ -274,11 +307,14 @@ declare const ALLOW_LIST_SEATS: {
274
307
  type AllowedToolsSeat = keyof typeof ALLOW_LIST_SEATS;
275
308
  /**
276
309
  * Screen and snapshot one `allowedTools` value (`seat` is the seat it was handed at; the sentence says it in words, the issues'
277
- * `libraryOption` names it): absent ⇒ undefined; a list of strings ⇒ a frozen copy (the one read every later reader takes);
278
- * anything else refuses loudly with {@link INVALID_PERMISSION_RULES_CODE} and an issue per defect — never dropped, never read
279
- * as "no entries".
310
+ * `libraryOption` names it): absent ⇒ undefined; a list of {@link AllowListEntry} members ⇒ a frozen copy (the one read every
311
+ * later reader takes). Refused loudly, never dropped and never read as "no entries": a value that is not a list, or a member that
312
+ * is neither a string nor an object, with {@link INVALID_PERMISSION_RULES_CODE} and an issue per defect; an anchored member that
313
+ * cannot be received ({@link receiveAnchoredMember}) with `config.invalid_argument`; an anchored path rule whose set declares a
314
+ * base it cannot be read at — a relative spelling, one of no tree's family — with the code and issue (`unsupported.path_base`) a
315
+ * deny / ask rule set's declaration meets (`unusableDeclaredBase`, the one judgment).
280
316
  */
281
- export declare function screenAllowedToolsValue(value: unknown, seat: AllowedToolsSeat): readonly string[] | undefined;
317
+ export declare function screenAllowedToolsValue(value: unknown, seat: AllowedToolsSeat): readonly AllowListEntry[] | undefined;
282
318
  /** The disclosure record for one member, minted from the entries it matched: each sanitized (deployment or model-authored
283
319
  * text on a human trust boundary) and capped, the rest counted. */
284
320
  export declare function allowRuleShadowOf(member: AllowRuleMember, entries: readonly string[]): AllowRuleShadow;
@@ -1,4 +1,4 @@
1
- import { heldBy } from "./tool-name-readings.js";
1
+ import { heldBy, wireOf } from "./tool-name-readings.js";
2
2
  import { ruleIssue } from "./permission-rules.js";
3
3
  import { isCoveringRuleName, ruleNameCovers } from "./namespaced-rule-name.js";
4
4
  import { ruleSpellingOf } from "./permission-rule-syntax.js";
@@ -6,8 +6,10 @@ import { splitNamespacedName, toolNameFaultOf } from "./tool-name-aliases.js";
6
6
  import { catalogToolNames, isShellFaceToolName } from "./tool-registry.js";
7
7
  import { ALLOW_RULE_MEMBERS } from "./allow-rule-shadow.js";
8
8
  import { callHostTargetOf } from "./host-target.js";
9
- import { adjudicatePersistedDomainRules, wholeToolRuleReaches, adjudicatePersistedNameRules, commandCoverageOf, laneToolNamesOf, ruleContentOf, noticeRuleText, parseRuleText, programRunReachOf, ruleToolGrammarOf, commandPatternMayRun } from "./permission-rule-model.js";
9
+ import { adjudicatePersistedDomainRules, wholeToolRuleReaches, adjudicatePersistedNameRules, commandCoverageOf, ruleWordsOf, ruleContentOf, noticeRuleText, parseRuleText, programRunReachOf, ruleToolGrammarOf, unusableDeclaredBase, PATH_RULE_BASES, PATH_RULE_BASE_LABEL, commandPatternMayRun } from "./permission-rule-model.js";
10
10
  import { pathRuleLaneAnswer } from "./runner/permission-rule-lanes.js";
11
+ import { policyAnchors } from "./path-rule-binding.js";
12
+ import { receiptRefusal, receiveOwnProperties } from "./own-property-receipt.js";
11
13
  import { callTargetReadingOf } from "./effective-path-target.js";
12
14
  import { splitShellCompoundSegments } from "../tools/fs/bash-readonly-classifier.js";
13
15
  import { ASK_RULE_DISCLOSURE, MANDATE_DISCLOSURE, mandateDisclosureOf } from "./ask-origin.js";
@@ -167,13 +169,19 @@ export function classifiesAllShell(spec) {
167
169
  return spec.classifyAllShell === true;
168
170
  }
169
171
  const NO_LEADS = new Map();
170
- function nameRowReaches(compiled, req) {
172
+ function nameRowReaches(compiled, req, reach) {
173
+ if (reach === "wire_name") {
174
+ const wire = wireOf("allowEntry.launchListNames", req);
175
+ if (compiled.kind === "tool" || compiled.kind === "shell")
176
+ return compiled.name === wire;
177
+ return compiled.kind === "covering" && ruleNameCovers(compiled.pattern, wire);
178
+ }
171
179
  if (compiled.kind === "tool" || compiled.kind === "shell")
172
180
  return wholeToolRuleReaches(compiled.name, req);
173
181
  return compiled.kind === "covering" && answersTo(req, (n) => ruleNameCovers(compiled.pattern, n));
174
182
  }
175
- function commandOf(req) {
176
- const tool = laneToolNamesOf(req).find((n) => ruleToolGrammarOf(n) === "command");
183
+ function commandOf(req, behavior) {
184
+ const tool = ruleWordsOf(req, behavior).find((n) => ruleToolGrammarOf(n) === "command");
177
185
  const command = req.args?.command;
178
186
  return tool !== undefined && typeof command === "string" ? { tool, command } : undefined;
179
187
  }
@@ -181,21 +189,25 @@ function admissionCallOf(call, ctx, liveCwd, posture) {
181
189
  return { tool: call.tool, command: call.command, cwd: ctx.root, ...(ctx.sessionId !== undefined ? { sessionId: ctx.sessionId } : {}), ...(liveCwd !== undefined ? { execCwd: liveCwd } : {}), posture };
182
190
  }
183
191
  export function uncoveredCommandSegment(rows, req, ctx, posture) {
184
- const call = commandOf(req);
192
+ const call = commandOf(req, "allow");
185
193
  if (call === undefined)
186
194
  return undefined;
187
195
  const rules = rows.flatMap((r) => (r.behavior === "allow" && r.compiled.kind === "command" ? [r.compiled.rule] : []));
188
196
  const coverage = commandCoverageOf(rules, admissionCallOf(call, ctx, ctx.liveCwd(), posture));
189
197
  return "uncovered" in coverage ? coverage.uncovered : undefined;
190
198
  }
191
- export function judgeAllowEntries(rows, req, behavior, ctx, posture = "grant") {
199
+ export function wholeToolEntryOf(rows, tool, behavior, names = "every_name") {
200
+ return rows.find((r) => r.behavior === behavior && nameRowReaches(r.compiled, tool, names));
201
+ }
202
+ export function judgeAllowEntries(rows, req, behavior, ctx, posture = "grant", names = "every_name") {
192
203
  const live = rows.filter((r) => r.behavior === behavior);
193
204
  if (live.length === 0)
194
205
  return undefined;
195
- for (const row of live)
196
- if (nameRowReaches(row.compiled, req))
197
- return [row];
198
- const call = commandOf(req);
206
+ const nameRow = wholeToolEntryOf(live, req, behavior, names);
207
+ if (nameRow !== undefined)
208
+ return [nameRow];
209
+ const words = ruleWordsOf(req, behavior);
210
+ const call = commandOf(req, behavior);
199
211
  const liveCwd = ctx.liveCwd();
200
212
  if (call !== undefined) {
201
213
  const byRule = new Map();
@@ -217,14 +229,32 @@ export function judgeAllowEntries(rows, req, behavior, ctx, posture = "grant") {
217
229
  }
218
230
  const pathRows = live.filter((r) => r.compiled.kind === "path");
219
231
  if (pathRows.length > 0) {
220
- const table = pathRows.map((r) => r.compiled.rule);
221
- for (const name of laneToolNamesOf(req).filter((n) => ruleToolGrammarOf(n) === "path")) {
222
- const answer = pathRuleLaneAnswer(table, { ...req, toolName: name }, { root: ctx.root, sessionId: ctx.sessionId, anchorsOf: () => ctx.anchors, leads: callTargetReadingOf(req)?.leads ?? NO_LEADS });
223
- const spoke = answer !== undefined && ("unreadable" in answer ? behavior === "deny" : "behavior" in answer && answer.behavior === behavior);
224
- if (spoke) {
225
- const rule = answer !== undefined && "rules" in answer ? answer.rules[0]?.rule : undefined;
226
- return [pathRows.find((r) => r.compiled.rule.rule === rule) ?? pathRows[0]];
232
+ const sets = new Map();
233
+ for (const r of pathRows) {
234
+ const key = anchorsKey(r.pathBases);
235
+ const set = sets.get(key) ?? { anchors: key === UNDECLARED_SET ? ctx.anchors : policyAnchors(r.pathBases ?? {}, ctx.anchors), rows: [] };
236
+ sets.set(key, set);
237
+ set.rows.push(r);
238
+ }
239
+ for (const name of words.filter((n) => ruleToolGrammarOf(n) === "path")) {
240
+ let unreadable;
241
+ for (const set of sets.values()) {
242
+ const table = set.rows.map((r) => r.compiled.rule);
243
+ const answer = pathRuleLaneAnswer(table, { ...req, toolName: name }, { root: ctx.root, sessionId: ctx.sessionId, anchorsOf: () => set.anchors, leads: callTargetReadingOf(req)?.leads ?? NO_LEADS });
244
+ if (answer === undefined)
245
+ continue;
246
+ if ("unreadable" in answer) {
247
+ if (behavior === "deny")
248
+ unreadable ??= set.rows[0];
249
+ continue;
250
+ }
251
+ if ("behavior" in answer && answer.behavior === behavior) {
252
+ const rule = answer.rules[0]?.rule;
253
+ return [set.rows.find((r) => r.compiled.rule.rule === rule) ?? set.rows[0]];
254
+ }
227
255
  }
256
+ if (unreadable !== undefined)
257
+ return [unreadable];
228
258
  }
229
259
  }
230
260
  for (const grammar of ["name", "domain"]) {
@@ -232,7 +262,7 @@ export function judgeAllowEntries(rows, req, behavior, ctx, posture = "grant") {
232
262
  if (familyRows.length === 0)
233
263
  continue;
234
264
  const table = familyRows.map((r) => r.compiled.rule);
235
- for (const name of laneToolNamesOf(req).filter((n) => ruleToolGrammarOf(n) === grammar)) {
265
+ for (const name of words.filter((n) => ruleToolGrammarOf(n) === grammar)) {
236
266
  const at = { tool: name, cwd: ctx.root, ...(ctx.sessionId !== undefined ? { sessionId: ctx.sessionId } : {}) };
237
267
  const named = { ...req, toolName: name };
238
268
  const verdict = grammar === "name" ? adjudicatePersistedNameRules(table, { ...at, request: req }) : adjudicatePersistedDomainRules(table, { ...at, hosts: { tighten: callHostTargetOf(named, "tighten"), grant: callHostTargetOf(named, "grant") } });
@@ -245,32 +275,52 @@ export function judgeAllowEntries(rows, req, behavior, ctx, posture = "grant") {
245
275
  export function allowingRows(rows, req, mode, allShell) {
246
276
  return rows.filter((r) => !strippedInAuto(r.compiled, req, mode, allShell));
247
277
  }
278
+ function allowListMemberOf(entry) {
279
+ return typeof entry === "string" ? { rule: entry } : entry;
280
+ }
281
+ function anchorsKey(pathBases) {
282
+ return JSON.stringify(PATH_RULE_BASES.map((word) => pathBases?.[word] ?? null));
283
+ }
284
+ const UNDECLARED_SET = anchorsKey(undefined);
285
+ function allowListMemberKey(member) {
286
+ return JSON.stringify([member.rule, anchorsKey(member.pathBases)]);
287
+ }
248
288
  export class AllowEntryTable {
249
289
  held = [];
250
- heldEntries = new Set();
290
+ heldKeys = new Set();
251
291
  receivedAt = new Map();
252
292
  seed(entries, reading = {}) {
253
- const { rows, inert } = compileAllowList(entries, "allow", reading.roster);
293
+ const members = entries.map(allowListMemberOf);
254
294
  if (reading.received === true) {
255
295
  this.receivedAt = new Map();
256
- entries.forEach((e, i) => {
257
- const at = this.receivedAt.get(e);
296
+ members.forEach((m, i) => {
297
+ const key = allowListMemberKey(m);
298
+ const at = this.receivedAt.get(key);
258
299
  if (at === undefined)
259
- this.receivedAt.set(e, [i]);
300
+ this.receivedAt.set(key, [i]);
260
301
  else
261
302
  at.push(i);
262
303
  });
263
304
  }
264
- for (const r of rows) {
265
- if (this.heldEntries.has(r.entry))
305
+ const inert = [];
306
+ for (const member of members) {
307
+ const read = readRuleEntry(member.rule, "allow", reading.roster);
308
+ if (read.kind !== "row") {
309
+ const { kind: _kind, ...why } = read;
310
+ void _kind;
311
+ inert.push({ entry: member.rule, ...why });
312
+ continue;
313
+ }
314
+ const key = allowListMemberKey(member);
315
+ if (this.heldKeys.has(key))
266
316
  continue;
267
- this.heldEntries.add(r.entry);
268
- this.held.push({ behavior: "allow", entry: r.entry, compiled: r.compiled });
317
+ this.heldKeys.add(key);
318
+ this.held.push({ behavior: "allow", entry: member.rule, compiled: read.compiled, ...(member.pathBases !== undefined ? { pathBases: member.pathBases } : {}) });
269
319
  }
270
320
  return inert;
271
321
  }
272
322
  entries() {
273
- return this.held.map((r) => r.entry);
323
+ return this.held.map((r) => (r.pathBases === undefined ? r.entry : Object.freeze({ rule: r.entry, pathBases: r.pathBases })));
274
324
  }
275
325
  holdsPathRows() {
276
326
  return this.held.some((r) => r.compiled.kind === "path");
@@ -278,11 +328,11 @@ export class AllowEntryTable {
278
328
  lane(ctx) {
279
329
  return {
280
330
  allowing: (req, mode) => {
281
- const hit = judgeAllowEntries(allowingRows(this.held, req, mode, ctx.classifyAllShell === true), req, "allow", ctx);
331
+ const hit = judgeAllowEntries(allowingRows(this.held, req, mode, ctx.classifyAllShell === true), req, "allow", ctx, "grant", "wire_name");
282
332
  if (hit === undefined)
283
333
  return undefined;
284
334
  const entries = hit.map((r) => r.entry);
285
- const positions = entries.flatMap((e) => this.receivedAt.get(e) ?? []).sort((a, b) => a - b);
335
+ const positions = hit.flatMap((r) => this.receivedAt.get(allowListMemberKey({ rule: r.entry, ...(r.pathBases !== undefined ? { pathBases: r.pathBases } : {}) })) ?? []).sort((a, b) => a - b);
286
336
  return { entries, ...(positions.length > 0 ? { positions } : {}) };
287
337
  },
288
338
  };
@@ -302,7 +352,7 @@ export function withDeploymentAllowedTools(deps) {
302
352
  if (deps.allowedTools === undefined)
303
353
  return deps;
304
354
  const allowedTools = screenAllowedToolsValue(deps.allowedTools, "RunnerDeps.allowedTools");
305
- const inert = compileAllowList(allowedTools ?? [], "allow").inert;
355
+ const inert = new AllowEntryTable().seed(allowedTools ?? []);
306
356
  if (inert.length > 0)
307
357
  deliverEngineNotice(deps.onNotice, allowedToolsNotGrantedNotice(inert.map((e) => ({ source: "deployment", ...e })), undefined));
308
358
  return { ...deps, allowedTools };
@@ -312,20 +362,63 @@ const ALLOW_LIST_SEATS = {
312
362
  "TaskSpec.allowedTools": "the request's allow list",
313
363
  "RunnerDeps.allowedTools": "the deployment's allow list",
314
364
  };
365
+ const ANCHORED_MEMBER_KEYS = new Set(["rule", "pathBases"]);
366
+ const PATH_BASE_WORDS = new Set(PATH_RULE_BASES);
367
+ function receiveAnchoredMember(entry, at) {
368
+ const member = receiveOwnProperties(entry, { subject: at, unit: "member", moment: "when the list is read" });
369
+ for (const key of Object.keys(member)) {
370
+ if (!ANCHORED_MEMBER_KEYS.has(key))
371
+ throw receiptRefusal(`${at} carries ${inlineUntrusted(key, 80)}, which is not a member of an anchored entry (its members are rule and pathBases) — refused rather than read without it`);
372
+ }
373
+ const rule = Object.hasOwn(member, "rule") ? member.rule : undefined;
374
+ const pathBases = Object.hasOwn(member, "pathBases") ? member.pathBases : undefined;
375
+ if (typeof rule !== "string")
376
+ throw receiptRefusal(`${at}.rule must be a permission-rule string (got ${valueTypeLabel(rule)})`);
377
+ if (typeof pathBases !== "object" || pathBases === null || Array.isArray(pathBases))
378
+ throw receiptRefusal(`${at}.pathBases must be an object of base words (got ${valueTypeLabel(pathBases)})`);
379
+ const bases = receiveOwnProperties(pathBases, { subject: `${at}.pathBases`, unit: "base word", moment: "when the list is read" });
380
+ const held = Object.create(null);
381
+ for (const [word, value] of Object.entries(bases)) {
382
+ if (!PATH_BASE_WORDS.has(word))
383
+ throw receiptRefusal(`${at}.pathBases carries ${inlineUntrusted(word, 80)}, which is not a base word (${PATH_RULE_BASES.join(", ")}) — refused rather than read without it`);
384
+ if (typeof value !== "string")
385
+ throw receiptRefusal(`${at}.pathBases.${word} must be a path string (got ${valueTypeLabel(value)})`);
386
+ held[word] = value;
387
+ }
388
+ if (Object.keys(held).length === 0)
389
+ throw receiptRefusal(`${at}.pathBases declares no base word (${PATH_RULE_BASES.join(", ")}) — a member that declares no anchors is written as the rule string`);
390
+ return Object.freeze({ rule, pathBases: Object.freeze(held) });
391
+ }
315
392
  export function screenAllowedToolsValue(value, seat) {
316
393
  if (value === undefined)
317
394
  return undefined;
318
395
  const label = ALLOW_LIST_SEATS[seat];
319
396
  const issues = [];
397
+ const out = [];
320
398
  if (!Array.isArray(value)) {
321
- issues.push(ruleIssue("", "invalid.entry_type", `${label} must be a list of permission-rule strings (got ${value === null ? "null" : typeof value})`, { name: seat }));
399
+ issues.push(ruleIssue("", "invalid.entry_type", `${label} must be a list of permission-rule strings or anchored rule members (got ${value === null ? "null" : typeof value})`, { name: seat }));
322
400
  }
323
401
  else {
324
402
  const list = value;
325
- list.forEach((entry, i) => {
326
- if (typeof entry !== "string")
327
- issues.push(ruleIssue("", "invalid.entry_type", `entry ${i} of ${label} must be a permission-rule string (got ${entry === null ? "null" : typeof entry})`, { name: seat }));
328
- });
403
+ for (let i = 0; i < list.length; i++) {
404
+ const entry = list[i];
405
+ if (typeof entry === "string") {
406
+ out.push(entry);
407
+ continue;
408
+ }
409
+ if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
410
+ issues.push(ruleIssue("", "invalid.entry_type", `entry ${i} of ${label} must be a permission-rule string or an anchored rule member (got ${entry === null ? "null" : Array.isArray(entry) ? "an array" : typeof entry})`, { name: seat }));
411
+ continue;
412
+ }
413
+ const member = receiveAnchoredMember(entry, `${seat}[${i}]`);
414
+ const read = readRuleEntry(member.rule, "allow");
415
+ const bad = read.kind === "row" && read.compiled.kind === "path" ? unusableDeclaredBase(read.compiled.rule, member.pathBases) : undefined;
416
+ if (bad !== undefined) {
417
+ issues.push(ruleIssue(noticeRuleText(member.rule), "unsupported.path_base", `entry ${i} of ${label} is relative to ${PATH_RULE_BASE_LABEL[bad.base]}, and the one its set declares (pathBases.${bad.key}) is not an absolute path of its tree's family — the rule could not be judged on any call`, { name: seat }));
418
+ continue;
419
+ }
420
+ out.push(member);
421
+ }
329
422
  }
330
423
  if (issues.length > 0) {
331
424
  const e = new Error(`${label}: ${issues.length} invalid entr${issues.length === 1 ? "y" : "ies"} — refusing rather than running without them:\n${issues.map((i) => ` [${i.code}] ${i.message}`).join("\n")}`);
@@ -333,7 +426,7 @@ export function screenAllowedToolsValue(value, seat) {
333
426
  e.issues = issues;
334
427
  throw e;
335
428
  }
336
- return Object.freeze([...value]);
429
+ return Object.freeze(out);
337
430
  }
338
431
  const SHADOW_ENTRIES_MAX = 5;
339
432
  const SHADOW_ENTRY_MAX_CHARS = 200;
@@ -81,6 +81,85 @@ export type AskOrigin = (typeof ASK_ORIGINS)[number];
81
81
  /** Whether a value is a member of the closed origin set. Exported because the word crosses process
82
82
  * boundaries: a host validating one it received must not hand-roll the set. */
83
83
  export declare function isAskOrigin(v: unknown): v is AskOrigin;
84
+ /**
85
+ * WHY a hook asked about a call — the closed set a hook seat's answer states beside its `ask` (`questionCause`), read by the
86
+ * hook entry of {@link AskReason}: `asked` — the hook itself asks, in its own words (the answer's `message`); `verdict_unreadable`
87
+ * — the hook's host could not read the verdict the hook gave, so it asks a person instead; `verdict_unfinished` — the hook did not
88
+ * finish with a verdict (it timed out, exited, could not be run), so its host asks a person. On the two `verdict_*` words the
89
+ * answer's `message` is the host's own account and is not the hook's words: no entry carries it. An answer that states no cause
90
+ * reads as `asked`.
91
+ */
92
+ export declare const HOOK_QUESTION_CAUSES: readonly ["asked", "verdict_unreadable", "verdict_unfinished"];
93
+ export type HookQuestionCause = (typeof HOOK_QUESTION_CAUSES)[number];
94
+ /** Membership test for {@link HookQuestionCause} — the receipt's screen of the hook seat's member. */
95
+ export declare function isHookQuestionCause(v: unknown): v is HookQuestionCause;
96
+ /**
97
+ * One asker of a call and what it said, in its OWN words — an entry of `askReasons` on the approval request and its parked row.
98
+ * The one law: an entry carries a question's asker's own words (a policy chain's ask sentence — the deployment's, an integrity
99
+ * guard's, a rule's —, a hook's or an extension's reason, a hook host's cause word); a sentence the engine composes about a call
100
+ * whose fact already rides a typed member (a tool mark, an allow layer's shadow, a classifier's no-ruling, a generic question)
101
+ * is no entry. `by` names the asker with the {@link AskOrigin} word for it; a hook entry names its registration when the engine
102
+ * knows it and the {@link HookQuestionCause}, and carries `words` only when the hook itself asked (`asked`). `words` is
103
+ * untrusted display text, already one line and capped ({@link ASK_REASON_WORDS_MAX}).
104
+ */
105
+ export type AskReason = {
106
+ readonly by: "hook";
107
+ readonly registration?: string;
108
+ readonly cause: HookQuestionCause;
109
+ readonly words?: string;
110
+ } | {
111
+ readonly by: Exclude<AskOrigin, "hook">;
112
+ readonly words: string;
113
+ };
114
+ /** The cap on an entry's `words` — the one an extension's reason has always been shown under in the question's sentence. */
115
+ export declare const ASK_REASON_WORDS_MAX = 500;
116
+ /**
117
+ * The facts no layer BEFORE the gate holds about a call — the gate's org layer, its question-tool and marked-call lanes, its
118
+ * tightens and the tool seat's marks all read as absent. Two readers. An inherited station: the delegation half of the live
119
+ * gate's classifier eligibility — the SAME class row answers for the FROZEN classifier (an ask raised by a hook, minted by an
120
+ * explicit `ask` rule, or already a denial-limit fallback is as out of the frozen decider's reach as the live one's: the standing
121
+ * decision travels with the frozen entry); an ancestor's frozen classifier runs inside the policy fold, before the live gate's
122
+ * org layer has spoken and before its question-tool and marked-call lanes run, so those asks meet their exclusions downstream,
123
+ * where the facts exist, and excluded asks fall through to the frozen approver chain. The mandate marks are empty (the base
124
+ * names no seat): the policy-chain phase builds each call's facts over this base with THIS task's tool seat, so a marked tool's
125
+ * ask is classified at the station as at the gate; no call either (each station's own). And the receipt of a policy chain's ask,
126
+ * whose entry names the asker its own members say ({@link chainAskReasonsOf}) — not a word the gate's later layers would add.
127
+ */
128
+ export declare const INHERITED_STATION_FACTS: Omit<AskOriginFacts, "call">;
129
+ /** A hook's entry ({@link AskReason}): the registration that answered (when the engine knows it), the cause, and — only when the hook
130
+ * itself asked — its reason as untrusted display text. Every station that reads a hook's or an extension's `ask` mints it here. */
131
+ export declare function hookAskReasonOf(registration: string | undefined, cause: HookQuestionCause, reason: string | undefined): Extract<AskReason, {
132
+ by: "hook";
133
+ }>;
134
+ /**
135
+ * The entry of a policy chain's ask, minted where the ask is RECEIVED (the gate's adjudication and its approved-edit re-check, an
136
+ * inherited station's read of an ancestor's ask): the receipt's own words, under the asker its own members name (the origin
137
+ * ladder over {@link INHERITED_STATION_FACTS} — a rule it matched, a classifier fallback it replays, else the policy). None when
138
+ * the ask has no words, or when its engine record says its words are the engine's generic question for the call
139
+ * (`genericQuestion`, while the ask's sentence is still that one: a write gate's default question, the plan mode's — the
140
+ * call's arguments and the ask's class already say it).
141
+ */
142
+ export declare function chainAskReasonsOf(receipt: Extract<PermissionResult, {
143
+ action: "ask";
144
+ }>, call: AskOriginFacts["call"]): readonly AskReason[] | undefined;
145
+ /** A received decision with its policy chain's entry stamped ({@link chainAskReasonsOf}) — the gate's two adjudication receipts
146
+ * (the first judgment, an approved edit's re-check), right after the receipt. Not an ask, or no entry ⇒ the decision itself. */
147
+ export declare function withChainAskReasons(d: PermissionResult, call: AskOriginFacts["call"]): PermissionResult;
148
+ /** Two askers' entries in fold order — the standing ask's first, then the one folded over it; absent when neither has any. An
149
+ * entry is minted once, so the same entry reached twice (one ask relayed into the fold over itself) is one asker, listed once. */
150
+ export declare function joinAskReasons(standing: readonly AskReason[] | undefined, folded: readonly AskReason[] | undefined): readonly AskReason[] | undefined;
151
+ /** The `askReasons` member as a request, a carry and a parked row spread it — present ⇔ the ask carries at least one entry. The ONE
152
+ * reader of a surviving ask's entries for the four request mint stations and the park's carry (one value on the card and the row). */
153
+ export declare function askReasonsOf(d: PermissionResult): {
154
+ askReasons?: readonly AskReason[];
155
+ };
156
+ /**
157
+ * The entries as a boundary a host reads back holds them (the parked row): a list of well-formed entries copied fresh, else
158
+ * nothing — the row's twin is written from the gate's carry, but the row is a boundary, so the value is screened where it is
159
+ * published (the screen the row's `origin` and class pair take). A malformed list publishes no entry at all, never a partial one;
160
+ * an entry's members are read as its own data members (an inherited or accessor member is no member).
161
+ */
162
+ export declare function receiveAskReasons(v: unknown): readonly AskReason[] | undefined;
84
163
  /**
85
164
  * A compile-time fence: `T` must be `never`. Instantiate it with `Exclude<<closed set>, keyof <table>>`
86
165
  * beside a table that is meant to be TOTAL over the set — while every member has a row the argument is
@@ -1,10 +1,86 @@
1
1
  import { attestationOf } from "./engine-attestation.js";
2
2
  import { isShellFaceToolName } from "./tool-registry.js";
3
+ import { inlineUntrusted } from "./untrusted-text.js";
3
4
  export const ASK_ORIGINS = Object.freeze(["content_question", "plan_review", "ancestor_marked", "org_unavailable", "org_rule", "rule_store_unavailable", "hook", "ask_rule", "denial_limit_fallback", "shell_gate_tighten", "safety_tighten", "policy"]);
4
5
  const ASK_ORIGIN_SET = new Set(ASK_ORIGINS);
5
6
  export function isAskOrigin(v) {
6
7
  return ASK_ORIGIN_SET.has(v);
7
8
  }
9
+ export const HOOK_QUESTION_CAUSES = Object.freeze(["asked", "verdict_unreadable", "verdict_unfinished"]);
10
+ const HOOK_QUESTION_CAUSE_SET = new Set(HOOK_QUESTION_CAUSES);
11
+ export function isHookQuestionCause(v) {
12
+ return HOOK_QUESTION_CAUSE_SET.has(v);
13
+ }
14
+ export const ASK_REASON_WORDS_MAX = 500;
15
+ export const INHERITED_STATION_FACTS = { contentQuestion: false, markedUnresolvable: false, org: undefined, tightened: undefined, mandateMarks: {} };
16
+ export function hookAskReasonOf(registration, cause, reason) {
17
+ const words = cause === "asked" && reason !== undefined ? inlineUntrusted(reason, ASK_REASON_WORDS_MAX) : undefined;
18
+ return Object.freeze({ by: "hook", ...(registration !== undefined ? { registration } : {}), cause, ...(words !== undefined ? { words } : {}) });
19
+ }
20
+ export function chainAskReasonsOf(receipt, call) {
21
+ const message = receipt.message;
22
+ const record = attestationOf(receipt, call);
23
+ if (record?.receivedAskReasons !== undefined)
24
+ return record.receivedAskReasons.length > 0 ? record.receivedAskReasons : undefined;
25
+ if (message === undefined || message === record?.genericQuestion)
26
+ return undefined;
27
+ const by = askOriginOf(receipt, { ...INHERITED_STATION_FACTS, call });
28
+ const words = inlineUntrusted(message, ASK_REASON_WORDS_MAX);
29
+ return Object.freeze([Object.freeze(by === "hook" ? { by, cause: "asked", words } : { by, words })]);
30
+ }
31
+ export function withChainAskReasons(d, call) {
32
+ if (d.action !== "ask")
33
+ return d;
34
+ const askReasons = chainAskReasonsOf(d, call);
35
+ return askReasons === undefined ? d : { ...d, askReasons };
36
+ }
37
+ export function joinAskReasons(standing, folded) {
38
+ const joined = [...(standing ?? [])];
39
+ for (const e of folded ?? [])
40
+ if (!joined.includes(e))
41
+ joined.push(e);
42
+ return joined.length > 0 ? Object.freeze(joined) : undefined;
43
+ }
44
+ export function askReasonsOf(d) {
45
+ return d.action === "ask" && d.askReasons !== undefined && d.askReasons.length > 0 ? { askReasons: d.askReasons } : {};
46
+ }
47
+ const BAD = Symbol("malformed");
48
+ function ownEntryMember(e, k) {
49
+ const d = Object.getOwnPropertyDescriptor(e, k);
50
+ if (d === undefined)
51
+ return undefined;
52
+ return "value" in d ? d.value : BAD;
53
+ }
54
+ function receivedEntry(e) {
55
+ if (typeof e !== "object" || e === null || Array.isArray(e))
56
+ return undefined;
57
+ const by = ownEntryMember(e, "by");
58
+ const words = ownEntryMember(e, "words");
59
+ if (by === "hook") {
60
+ const cause = ownEntryMember(e, "cause");
61
+ const registration = ownEntryMember(e, "registration");
62
+ if (!isHookQuestionCause(cause) || (registration !== undefined && typeof registration !== "string"))
63
+ return undefined;
64
+ if (words !== undefined && (typeof words !== "string" || cause !== "asked"))
65
+ return undefined;
66
+ return Object.freeze({ by: "hook", ...(registration !== undefined ? { registration } : {}), cause, ...(words !== undefined ? { words } : {}) });
67
+ }
68
+ if (!isAskOrigin(by) || typeof words !== "string")
69
+ return undefined;
70
+ return Object.freeze({ by: by, words });
71
+ }
72
+ export function receiveAskReasons(v) {
73
+ if (!Array.isArray(v) || v.length === 0)
74
+ return undefined;
75
+ const out = [];
76
+ for (let i = 0; i < v.length; i++) {
77
+ const entry = Object.prototype.hasOwnProperty.call(v, i) ? receivedEntry(v[i]) : undefined;
78
+ if (entry === undefined)
79
+ return undefined;
80
+ out.push(entry);
81
+ }
82
+ return Object.freeze(out);
83
+ }
8
84
  export function askOriginOf(decision, facts) {
9
85
  const origin = originLadder(decision, facts);
10
86
  if (ORIGIN_IMPLIES_REAL_APPROVAL[origin] === "at_derivation" && decision.requiresRealApproval !== true) {