@sema-agent/core 7.56.0 → 7.58.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (319) hide show
  1. package/CHANGELOG.md +926 -0
  2. package/LICENSE +1 -1
  3. package/dist/agents/org-delivery-gate.js +3 -4
  4. package/dist/agents/peer-held-queue.d.ts +69 -49
  5. package/dist/agents/peer-held-queue.js +255 -106
  6. package/dist/agents/peer-session-drain.js +63 -43
  7. package/dist/agents/send-message-tool.js +3 -2
  8. package/dist/agents/subagent-steps.js +2 -4
  9. package/dist/agents/subagent.js +8 -8
  10. package/dist/brain/anthropic.js +16 -8
  11. package/dist/brain/open-responses.js +10 -8
  12. package/dist/brain/openai.js +11 -9
  13. package/dist/brain/provider-dialect.d.ts +3 -2
  14. package/dist/brain/provider-dialect.js +2 -2
  15. package/dist/brain/request-params.d.ts +6 -0
  16. package/dist/brain/request-params.js +14 -1
  17. package/dist/brain/route-adjudicator.js +2 -1
  18. package/dist/brain/stream-engine.d.ts +9 -0
  19. package/dist/brain/stream-engine.js +24 -10
  20. package/dist/brain/stream-shared.d.ts +5 -4
  21. package/dist/brain/stream-shared.js +4 -4
  22. package/dist/core/a2a.d.ts +2 -1
  23. package/dist/core/a2a.js +23 -10
  24. package/dist/core/allow-entry.d.ts +5 -11
  25. package/dist/core/allow-entry.js +19 -26
  26. package/dist/core/approval-object.d.ts +21 -5
  27. package/dist/core/approval-object.js +44 -17
  28. package/dist/core/ask-origin.d.ts +23 -4
  29. package/dist/core/ask-origin.js +5 -1
  30. package/dist/core/auto-compaction.d.ts +75 -6
  31. package/dist/core/auto-compaction.js +43 -27
  32. package/dist/core/auto-mode-directive.d.ts +29 -5
  33. package/dist/core/auto-mode-directive.js +38 -8
  34. package/dist/core/background-agent-store.d.ts +6 -2
  35. package/dist/core/background-agent-store.js +1 -1
  36. package/dist/core/checkpoint-requirements.d.ts +13 -1
  37. package/dist/core/checkpoint-requirements.js +4 -0
  38. package/dist/core/checkpoint-store.d.ts +44 -40
  39. package/dist/core/checkpoint-store.js +32 -14
  40. package/dist/core/cross-boundary-taint.js +4 -2
  41. package/dist/core/engine-notice.d.ts +4 -3
  42. package/dist/core/engine-notice.js +6 -0
  43. package/dist/core/file-history-store.d.ts +14 -8
  44. package/dist/core/file-history-store.js +14 -4
  45. package/dist/core/fs-write-gate-policy.d.ts +4 -2
  46. package/dist/core/fs-write-gate-policy.js +7 -3
  47. package/dist/core/gate-fold.js +6 -3
  48. package/dist/core/gate-lanes.js +13 -5
  49. package/dist/core/git-worktree-env.d.ts +53 -11
  50. package/dist/core/git-worktree-env.js +96 -12
  51. package/dist/core/hooks.d.ts +6 -3
  52. package/dist/core/hooks.js +12 -5
  53. package/dist/core/human-input-projection.d.ts +1 -0
  54. package/dist/core/human-input-projection.js +3 -0
  55. package/dist/core/locked-config.d.ts +15 -1
  56. package/dist/core/locked-config.js +38 -2
  57. package/dist/core/mailbox-store.d.ts +62 -1
  58. package/dist/core/mailbox-store.js +59 -0
  59. package/dist/core/mcp-call-meta.d.ts +66 -0
  60. package/dist/core/mcp-call-meta.js +103 -0
  61. package/dist/core/mcp-connection-pool.d.ts +3 -1
  62. package/dist/core/mcp-connection-pool.js +3 -1
  63. package/dist/core/mcp-failure.d.ts +7 -1
  64. package/dist/core/mcp-failure.js +10 -0
  65. package/dist/core/mcp-name-judge.d.ts +46 -0
  66. package/dist/core/mcp-name-judge.js +61 -0
  67. package/dist/core/mcp-probe.d.ts +5 -1
  68. package/dist/core/mcp-probe.js +3 -6
  69. package/dist/core/mcp-server-link.d.ts +5 -2
  70. package/dist/core/mcp-server-spec.d.ts +46 -18
  71. package/dist/core/mcp-server-spec.js +1 -18
  72. package/dist/core/mcp.d.ts +6 -14
  73. package/dist/core/mcp.js +85 -65
  74. package/dist/core/memory-engine/consolidation-driver.js +4 -3
  75. package/dist/core/memory-engine/distiller.js +26 -17
  76. package/dist/core/memory-engine/layout.js +5 -2
  77. package/dist/core/memory-engine/scope-contract.d.ts +45 -4
  78. package/dist/core/memory-engine/scope-contract.js +80 -11
  79. package/dist/core/mode-policy.d.ts +8 -5
  80. package/dist/core/mode-policy.js +5 -4
  81. package/dist/core/mods/host.js +1 -1
  82. package/dist/core/mods/kernel/dispatch.d.ts +3 -0
  83. package/dist/core/mods/kernel/dispatch.js +10 -8
  84. package/dist/core/mods/kernel/events.d.ts +5 -1
  85. package/dist/core/mods/kernel/events.js +1 -1
  86. package/dist/core/mods/kernel/registration.d.ts +5 -1
  87. package/dist/core/mods/kernel/site-rules.d.ts +3 -0
  88. package/dist/core/mods/kernel/site-rules.js +10 -0
  89. package/dist/core/mods/package.d.ts +23 -0
  90. package/dist/core/mods/package.js +118 -0
  91. package/dist/core/mods/stations.d.ts +2 -2
  92. package/dist/core/mods/stations.js +1 -1
  93. package/dist/core/mods/tool-call.d.ts +5 -1
  94. package/dist/core/mods/tool-call.js +12 -3
  95. package/dist/core/park-selfcheck.js +2 -0
  96. package/dist/core/path-guard-rows.d.ts +20 -0
  97. package/dist/core/path-guard-rows.js +11 -0
  98. package/dist/core/peer-seat.d.ts +186 -0
  99. package/dist/core/peer-seat.js +307 -0
  100. package/dist/core/permission-rule-consent.d.ts +5 -3
  101. package/dist/core/permission-rule-consent.js +20 -15
  102. package/dist/core/permission-rule-model.d.ts +43 -2
  103. package/dist/core/permission-rule-model.js +52 -8
  104. package/dist/core/permission-rule-org.js +1 -1
  105. package/dist/core/present-plan-tool.d.ts +10 -1
  106. package/dist/core/present-plan-tool.js +46 -2
  107. package/dist/core/protocol-http-auth.d.ts +56 -31
  108. package/dist/core/protocol-http-auth.js +71 -42
  109. package/dist/core/protocol-naming.d.ts +20 -0
  110. package/dist/core/protocol-naming.js +20 -3
  111. package/dist/core/read-only-shell.d.ts +20 -5
  112. package/dist/core/read-only-shell.js +29 -14
  113. package/dist/core/redaction-marks.d.ts +16 -0
  114. package/dist/core/redaction-marks.js +16 -0
  115. package/dist/core/redaction-passes.js +8 -9
  116. package/dist/core/remote-env.d.ts +37 -1
  117. package/dist/core/remote-env.js +11 -0
  118. package/dist/core/resume-startup-cause.d.ts +24 -2
  119. package/dist/core/resume-startup-cause.js +20 -1
  120. package/dist/core/retention.d.ts +41 -15
  121. package/dist/core/retention.js +59 -12
  122. package/dist/core/rewrite-rejudge.d.ts +37 -0
  123. package/dist/core/rewrite-rejudge.js +40 -0
  124. package/dist/core/roles.js +50 -7
  125. package/dist/core/run-origin.d.ts +40 -0
  126. package/dist/core/run-origin.js +37 -0
  127. package/dist/core/runner/advertised-writable-dirs.d.ts +57 -38
  128. package/dist/core/runner/advertised-writable-dirs.js +126 -0
  129. package/dist/core/runner/compact-session.d.ts +10 -0
  130. package/dist/core/runner/compact-session.js +202 -0
  131. package/dist/core/runner/compaction-call-options.d.ts +2 -2
  132. package/dist/core/runner/compaction-restate.d.ts +15 -6
  133. package/dist/core/runner/compaction-restate.js +28 -2
  134. package/dist/core/runner/compaction-seams.d.ts +21 -1
  135. package/dist/core/runner/compaction-seams.js +11 -8
  136. package/dist/core/runner/contracts.d.ts +36 -21
  137. package/dist/core/runner/derived-route-fallback.d.ts +13 -0
  138. package/dist/core/runner/derived-route-fallback.js +6 -0
  139. package/dist/core/runner/env-capability-census.d.ts +3 -2
  140. package/dist/core/runner/env-capability-census.js +9 -3
  141. package/dist/core/runner/gate-exit.d.ts +18 -4
  142. package/dist/core/runner/gate-exit.js +5 -1
  143. package/dist/core/runner/permission-rule-lanes.d.ts +7 -7
  144. package/dist/core/runner/permission-rule-lanes.js +17 -11
  145. package/dist/core/runner/prepare-acquire-reconcile.d.ts +3 -0
  146. package/dist/core/runner/prepare-acquire-reconcile.js +2 -1
  147. package/dist/core/runner/prepare-caps-and-workflow.d.ts +2 -0
  148. package/dist/core/runner/prepare-caps-and-workflow.js +1 -1
  149. package/dist/core/runner/prepare-config-doors.d.ts +14 -5
  150. package/dist/core/runner/prepare-config-doors.js +16 -13
  151. package/dist/core/runner/prepare-delegation-surface.d.ts +4 -0
  152. package/dist/core/runner/prepare-delegation-surface.js +15 -18
  153. package/dist/core/runner/prepare-gate-stations.js +1 -1
  154. package/dist/core/runner/prepare-hands-readface.d.ts +10 -4
  155. package/dist/core/runner/prepare-hands-readface.js +6 -1
  156. package/dist/core/runner/prepare-memory.d.ts +3 -0
  157. package/dist/core/runner/prepare-memory.js +19 -23
  158. package/dist/core/runner/prepare-park-ask.d.ts +2 -0
  159. package/dist/core/runner/prepare-park-ask.js +2 -2
  160. package/dist/core/runner/prepare-policy-chain.d.ts +4 -4
  161. package/dist/core/runner/prepare-policy-chain.js +4 -6
  162. package/dist/core/runner/prepare-protocol-tools.d.ts +4 -2
  163. package/dist/core/runner/prepare-protocol-tools.js +3 -3
  164. package/dist/core/runner/prepare-suspend-saga.d.ts +2 -0
  165. package/dist/core/runner/prepare-suspend-saga.js +2 -1
  166. package/dist/core/runner/prepare-task.d.ts +4 -1
  167. package/dist/core/runner/prepare-task.js +46 -37
  168. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +13 -0
  169. package/dist/core/runner/prepare-tool-disclosure-mount.js +13 -7
  170. package/dist/core/runner/prepare-wiring-manifest.d.ts +1 -0
  171. package/dist/core/runner/prepare-wiring-manifest.js +2 -2
  172. package/dist/core/runner/prepare-workspace-restore.d.ts +3 -0
  173. package/dist/core/runner/prepare-workspace-restore.js +4 -4
  174. package/dist/core/runner/resume-admission.js +1 -1
  175. package/dist/core/runner/resume-checkpoint-screen.js +2 -0
  176. package/dist/core/runner/rewind-files.d.ts +2 -5
  177. package/dist/core/runner/rewind-files.js +9 -51
  178. package/dist/core/runner/run-harness-handlers.d.ts +3 -4
  179. package/dist/core/runner/run-harness-handlers.js +1 -8
  180. package/dist/core/runner/run-identity-wiring.js +1 -0
  181. package/dist/core/runner/run-leg.js +15 -22
  182. package/dist/core/runner/run-notification-lane.d.ts +2 -0
  183. package/dist/core/runner/run-notification-lane.js +5 -2
  184. package/dist/core/runner/run-recovery-lanes.js +3 -4
  185. package/dist/core/runner/run-settle-and-teardown.js +5 -11
  186. package/dist/core/runner/run-terminal-adoption.js +3 -4
  187. package/dist/core/runner/run-turn-boundary.js +3 -5
  188. package/dist/core/runner/runtask.d.ts +8 -1
  189. package/dist/core/runner/runtask.js +28 -34
  190. package/dist/core/runner/send-message-continuation.js +1 -1
  191. package/dist/core/runner/session-verb-doors.d.ts +28 -0
  192. package/dist/core/runner/session-verb-doors.js +48 -0
  193. package/dist/core/runner/session-write-ledger.d.ts +30 -0
  194. package/dist/core/runner/session-write-ledger.js +101 -0
  195. package/dist/core/runner/stream-settle-backstop.js +11 -14
  196. package/dist/core/runner/sub-agent-deny-lists.d.ts +25 -3
  197. package/dist/core/runner/sub-agent-deny-lists.js +21 -10
  198. package/dist/core/runner/teardown-bounded.d.ts +1 -0
  199. package/dist/core/runner/teardown-bounded.js +1 -0
  200. package/dist/core/runner/terminal-account.js +3 -3
  201. package/dist/core/runner/tool-end-body.js +1 -0
  202. package/dist/core/runner/tool-occurrence.d.ts +4 -1
  203. package/dist/core/runner/tool-occurrence.js +2 -1
  204. package/dist/core/runner/write-protection-station.d.ts +8 -2
  205. package/dist/core/runner/write-protection-station.js +2 -0
  206. package/dist/core/runner-deps.d.ts +4 -4
  207. package/dist/core/secret-env.d.ts +4 -0
  208. package/dist/core/secret-env.js +3 -0
  209. package/dist/core/sensitive-path-policy.js +6 -7
  210. package/dist/core/session-log-transfer.d.ts +24 -0
  211. package/dist/core/session-log-transfer.js +166 -0
  212. package/dist/core/session-policy-store.d.ts +7 -2
  213. package/dist/core/session-policy-store.js +1 -1
  214. package/dist/core/session-store.d.ts +84 -19
  215. package/dist/core/session-store.js +162 -24
  216. package/dist/core/session.d.ts +92 -1
  217. package/dist/core/shell-read-silence.js +1 -0
  218. package/dist/core/shell-wrapper-projection.d.ts +1 -1
  219. package/dist/core/steer-replay.d.ts +4 -2
  220. package/dist/core/steer-replay.js +2 -1
  221. package/dist/core/store-contracts/background-agent-store-contract.js +1 -0
  222. package/dist/core/store-contracts/checkpoint-store-contract.js +19 -1
  223. package/dist/core/store-contracts/file-history-store-contract.js +9 -0
  224. package/dist/core/store-contracts/mailbox-store-contract.js +49 -1
  225. package/dist/core/store-contracts/session-repo-contract.js +112 -5
  226. package/dist/core/store-contracts/session-store-contract.d.ts +4 -1
  227. package/dist/core/store-contracts/session-store-contract.js +236 -2
  228. package/dist/core/task-event.d.ts +68 -8
  229. package/dist/core/task-registry-agent.d.ts +8 -4
  230. package/dist/core/task-registry-agent.js +14 -8
  231. package/dist/core/task-registry-shared.d.ts +36 -6
  232. package/dist/core/task-registry-shared.js +11 -0
  233. package/dist/core/task-registry.d.ts +1 -1
  234. package/dist/core/task-registry.js +1 -1
  235. package/dist/core/task-spec.d.ts +37 -0
  236. package/dist/core/task-stream.d.ts +2 -1
  237. package/dist/core/terminal-cause.d.ts +1 -1
  238. package/dist/core/tool-catalog-entries.d.ts +6 -0
  239. package/dist/core/tool-catalog-entries.js +2 -0
  240. package/dist/core/tool-name-aliases.d.ts +32 -2
  241. package/dist/core/tool-name-aliases.js +23 -0
  242. package/dist/core/tool-name-readings.d.ts +4 -0
  243. package/dist/core/tool-name-readings.js +1 -0
  244. package/dist/core/tool-policy.d.ts +10 -6
  245. package/dist/core/tool-policy.js +4 -7
  246. package/dist/core/tool-result-store.d.ts +17 -10
  247. package/dist/core/tool-result-store.js +3 -1
  248. package/dist/core/trace.d.ts +4 -1
  249. package/dist/core/trace.js +2 -1
  250. package/dist/core/types.d.ts +1 -1
  251. package/dist/core/untrusted-egress.d.ts +18 -0
  252. package/dist/core/untrusted-egress.js +82 -12
  253. package/dist/core/wiring-manifest.d.ts +12 -3
  254. package/dist/core/wiring-manifest.js +4 -3
  255. package/dist/core/workspace-snapshot.d.ts +44 -0
  256. package/dist/core/workspace-snapshot.js +34 -0
  257. package/dist/core/write-protect.d.ts +43 -3
  258. package/dist/core/write-protect.js +43 -16
  259. package/dist/engine/execution-env/node-execution-env.js +15 -11
  260. package/dist/engine/execution-env/symlink-chain.d.ts +7 -5
  261. package/dist/engine/harness/agent-harness.d.ts +12 -5
  262. package/dist/engine/harness/agent-harness.js +13 -2
  263. package/dist/engine/harness/types.d.ts +48 -7
  264. package/dist/engine/harness/types.js +5 -1
  265. package/dist/engine/llm/types.d.ts +12 -3
  266. package/dist/engine/llm/types.js +1 -1
  267. package/dist/engine/loop/agent-loop.d.ts +1 -4
  268. package/dist/engine/loop/agent-loop.js +26 -4
  269. package/dist/engine/session/import-validate.js +3 -0
  270. package/dist/engine/session/memory-repo.d.ts +17 -9
  271. package/dist/engine/session/memory-repo.js +44 -34
  272. package/dist/engine/session/repo-utils.d.ts +22 -4
  273. package/dist/engine/session/repo-utils.js +49 -1
  274. package/dist/engine/session/storage-base.d.ts +10 -1
  275. package/dist/engine/session/storage-base.js +7 -1
  276. package/dist/index.d.ts +23 -11
  277. package/dist/index.js +15 -6
  278. package/dist/internal/harness-types.d.ts +1 -1
  279. package/dist/internal/harness.d.ts +4 -3
  280. package/dist/internal/harness.js +3 -2
  281. package/dist/stores/file/checkpoint-store.d.ts +0 -4
  282. package/dist/stores/file/checkpoint-store.js +0 -1
  283. package/dist/stores/file/file-history-store.js +12 -4
  284. package/dist/stores/file/index.d.ts +4 -1
  285. package/dist/stores/file/index.js +4 -1
  286. package/dist/stores/file/mailbox-store.d.ts +2 -1
  287. package/dist/stores/file/mailbox-store.js +26 -1
  288. package/dist/stores/file/session-store.d.ts +15 -8
  289. package/dist/stores/file/session-store.js +28 -13
  290. package/dist/tools/fs/bash-readonly-classifier.d.ts +15 -19
  291. package/dist/tools/fs/bash-readonly-classifier.js +5 -10
  292. package/dist/tools/fs/fs-bash.js +10 -3
  293. package/dist/tools/fs/fs-write.d.ts +6 -3
  294. package/dist/tools/fs/fs-write.js +8 -7
  295. package/dist/tools/fs/index.d.ts +3 -0
  296. package/dist/tools/fs/index.js +1 -1
  297. package/dist/tools/fs/pattern-kill-guard.d.ts +3 -2
  298. package/dist/tools/fs/pattern-kill-guard.js +68 -36
  299. package/dist/tools/fs/safety.js +40 -8
  300. package/dist/tools/fs/search.js +6 -24
  301. package/dist/tools/fs/shell-read-check.d.ts +18 -1
  302. package/dist/tools/fs/shell-read-check.js +66 -16
  303. package/dist/tools/fs/shell-read-establish.js +2 -1
  304. package/dist/tools/fs/shell-read-identity.d.ts +12 -9
  305. package/dist/tools/fs/shell-read-identity.js +10 -5
  306. package/dist/tools/fs/shell-read-judge.d.ts +10 -1
  307. package/dist/tools/web.js +9 -7
  308. package/dist/tools/worktree.d.ts +42 -15
  309. package/dist/tools/worktree.js +60 -32
  310. package/package.json +4 -2
  311. package/test/export-surface.snapshot.json +141 -3
  312. package/wire-changes/core-stores-sql@7.57.0.json +29 -0
  313. package/wire-changes/core-stores-sql@7.58.0.json +29 -0
  314. package/wire-changes/core@7.57.0.json +1487 -0
  315. package/wire-changes/core@7.58.0.json +2188 -0
  316. package/wire-changes/mods-kernel@7.57.0.json +29 -0
  317. package/wire-changes/mods-kernel@7.58.0.json +81 -0
  318. package/wire-changes/primitives@7.57.0.json +245 -0
  319. package/wire-changes/primitives@7.58.0.json +29 -0
@@ -317,11 +317,13 @@ export declare function prepareCardApproval(opts: {
317
317
  principal?: string;
318
318
  /** design/182 §4.5 (additive): the structural owner — only the local-owner path needs it. */
319
319
  owner?: RuleOwner;
320
- /** The tool whose ask this card belongs to. Only the shell tool the rule lane speaks for, the name tools (the skill-activation
321
- * card) and the host tools (the fetch card) are accepted. */
320
+ /** The tool whose ask this card belongs to: a tool whose card the offer factory mints a rule on (`cardRuleFormOf`) — the shell
321
+ * tool, a name tool (the skill-activation card), a host tool (the fetch card), a tool with no rule grammar (the whole-tool card).
322
+ * Any other tool (a path tool, a shell-face sibling) draws no card. */
322
323
  toolName: string;
323
324
  /** The command as adjudicated — the same bytes the ask carried; for a name tool (`Skill`), the name its call carried (`args.skill`);
324
- * for a host tool (`WebFetch`), the host its call reaches (the offer's `command`). */
325
+ * for a host tool (`WebFetch`), the host its call reaches (the offer's `command`); for a tool with no rule grammar, `""` (the
326
+ * offer's `command`: the whole tool binds no value). */
325
327
  command: string;
326
328
  /** The ask's call id and argument digest, recorded for reconciliation. */
327
329
  toolCallId?: string;
@@ -1,5 +1,5 @@
1
1
  import { randomBytes } from "node:crypto";
2
- import { escapeForDisclosure, hasUnrenderableCharacters, parseRuleText, ruleAdmitsCommand, ruleBreadthWarningsOf, ruleToolGrammarOf, segmentCoverageOf, suggestRuleForHost, suggestRuleForName, suggestRulesForCommand, EDITED_RULE_BREADTH_WARNING_CODES, RULE_OFFER_KINDS, UNCOVERED_SEGMENT_REASONS, RULE_BEHAVIORS, RULE_BEHAVIOR_PRECEDENCE, isRuleBehavior, } from "./permission-rule-model.js";
2
+ import { COMMAND_RULE_TOOL, cardRuleFormOf, escapeForDisclosure, hasUnrenderableCharacters, parseRuleText, ruleAdmitsCommand, ruleBreadthWarningsOf, segmentCoverageOf, suggestRuleForHost, suggestRuleForName, suggestRuleForTool, suggestRulesForCommand, EDITED_RULE_BREADTH_WARNING_CODES, RULE_OFFER_KINDS, UNCOVERED_SEGMENT_REASONS, RULE_BEHAVIORS, RULE_BEHAVIOR_PRECEDENCE, isRuleBehavior, } from "./permission-rule-model.js";
3
3
  import { readRuleOwner, sameRuleOwner } from "./rule-owner.js";
4
4
  import { principalNameOf, readPrincipal } from "./principal-name.js";
5
5
  import { isPlainRecord } from "./mods/kernel/receive.js";
@@ -236,6 +236,12 @@ function approvalRecordDamageOf(rec) {
236
236
  if (rec.kind === "card" && cand.behavior !== "allow") {
237
237
  return `card offer ${at} references candidate ${member}, a ${cand.behavior} rule — a card mints allow candidates only`;
238
238
  }
239
+ if (rec.kind === "card") {
240
+ const read = parseRuleText(cand.rule, cand.behavior);
241
+ if ("rule" in read && read.rule.match === "tool" && (typeof rec.command === "string" || cardRuleFormOf(read.rule.tool) !== "tool")) {
242
+ return `card offer ${at} references candidate ${member}, the whole-tool rule "${escapeForDisclosure(read.rule.rule)}" — the engine mints one only on the whole-tool card of a tool with no rule grammar`;
243
+ }
244
+ }
239
245
  if (!isValidConsentScope(cand.scope)) {
240
246
  return `offer ${at} references candidate ${member}, whose scope is not a consent-face scope (global, project, or session)`;
241
247
  }
@@ -262,7 +268,7 @@ function approvalRecordDamageOf(rec) {
262
268
  }
263
269
  if (detail.length > 0) {
264
270
  const rows = detail;
265
- const table = typeof rec.command === "string" ? segmentCoverageOf(rec.command, { persisted: [] }, { tool: CARD_RULE_TOOL, cwd: undefined }) : undefined;
271
+ const table = typeof rec.command === "string" ? segmentCoverageOf(rec.command, { persisted: [] }, { tool: COMMAND_RULE_TOOL, cwd: undefined }) : undefined;
266
272
  if (table === undefined) {
267
273
  return `card batch offer ${at} carries reason rows but the record's command cannot back them — a row without a readable source command is a row nobody can audit`;
268
274
  }
@@ -379,10 +385,10 @@ export async function prepareCardApproval(opts) {
379
385
  e.code = "config.invalid_argument";
380
386
  throw e;
381
387
  }
382
- const grammar = ruleToolGrammarOf(opts.toolName);
383
- const oneRuleCard = grammar === "name" || grammar === "domain" ? grammar : undefined;
384
- if (opts.toolName !== CARD_RULE_TOOL && oneRuleCard === undefined)
388
+ const form = cardRuleFormOf(opts.toolName);
389
+ if (form === undefined)
385
390
  return undefined;
391
+ const oneRuleCard = form === "command" ? undefined : form;
386
392
  const scope = (() => {
387
393
  if (opts.scope !== undefined) {
388
394
  if (!isValidConsentScope(opts.scope)) {
@@ -409,14 +415,14 @@ export async function prepareCardApproval(opts) {
409
415
  try {
410
416
  const view = await effectiveOrThrow(storeForOwner(opts.deps.provider, owner), opts.sessionId !== undefined ? { sessionId: opts.sessionId } : undefined);
411
417
  const table = view.rules;
412
- coverage = segmentCoverageOf(opts.command, { persisted: table }, { tool: CARD_RULE_TOOL, cwd: opts.cwd, sessionId: opts.sessionId, ...(opts.execCwd !== undefined ? { execCwd: opts.execCwd } : {}) });
418
+ coverage = segmentCoverageOf(opts.command, { persisted: table }, { tool: COMMAND_RULE_TOOL, cwd: opts.cwd, sessionId: opts.sessionId, ...(opts.execCwd !== undefined ? { execCwd: opts.execCwd } : {}) });
413
419
  }
414
420
  catch {
415
421
  coverage = undefined;
416
422
  }
417
423
  }
418
424
  const suggested = oneRuleCard !== undefined
419
- ? [oneRuleCard === "name" ? suggestRuleForName(opts.toolName, opts.command) : suggestRuleForHost(opts.toolName, opts.command)].filter((o) => o !== undefined)
425
+ ? [oneRuleCard === "name" ? suggestRuleForName(opts.toolName, opts.command) : oneRuleCard === "domain" ? suggestRuleForHost(opts.toolName, opts.command) : opts.command === "" ? suggestRuleForTool(opts.toolName) : undefined].filter((o) => o !== undefined)
420
426
  : suggestRulesForCommand(opts.command, {
421
427
  ...(coverage !== undefined ? { coverage } : {}),
422
428
  scope,
@@ -468,7 +474,6 @@ export async function prepareCardApproval(opts) {
468
474
  candidates,
469
475
  };
470
476
  }
471
- const CARD_RULE_TOOL = "Bash";
472
477
  export async function confirmRuleApproval(opts) {
473
478
  const caller = resolveCallerOwner(opts.principal, opts.owner, "confirmRuleApproval");
474
479
  const no = (reason, detail) => ({
@@ -546,6 +551,9 @@ function checkEditedRuleText(text, command) {
546
551
  const parsed = parseSubmittedSpelling(text);
547
552
  if ("reject" in parsed)
548
553
  return { ok: false, code: parsed.reject.code, message: parsed.reject.message };
554
+ if (parsed.rule.match === "tool") {
555
+ return { ok: false, message: `the edited rule "${parsed.rule.rule}" names the whole tool — a card's edit names a command rule, and a standing yes to every command is not one a card mints` };
556
+ }
549
557
  if (!ruleAdmitsCommand(parsed.rule, command)) {
550
558
  return {
551
559
  ok: false,
@@ -838,18 +846,15 @@ export async function prepareCcImport(opts) {
838
846
  skipped.push({ rule: String(entry), reason: `settings ${behavior} entry is not a string` });
839
847
  continue;
840
848
  }
841
- if (!/^[A-Za-z][A-Za-z0-9_]*\(.*\)$/.test(entry)) {
842
- const reason = /^[A-Za-z][A-Za-z0-9_-]*$/.test(entry)
843
- ? "unsupported.form: a bare tool-name entry is a name-set item, not a command rule — it stays in the settings file, unimported"
844
- : "unsupported.form: not a command rule spelling this version imports — it stays in the settings file, unimported";
845
- skipped.push({ rule: entry, reason });
846
- continue;
847
- }
848
849
  const parsed = parseRuleText(entry, behavior);
849
850
  if ("reject" in parsed) {
850
851
  skipped.push({ rule: entry, reason: `${parsed.reject.code}: ${parsed.reject.message}` });
851
852
  continue;
852
853
  }
854
+ if (parsed.rule.match === "tool") {
855
+ skipped.push({ rule: entry, reason: "unsupported.form: a bare tool-name entry is a name-set item the host carries from the settings layer's own lists — it stays in the settings file, unimported" });
856
+ continue;
857
+ }
853
858
  if (candidates.some((c) => c.behavior === behavior && c.rule === parsed.rule.rule && sameScope(c.scope, scope)))
854
859
  continue;
855
860
  candidates.push({ behavior, rule: parsed.rule.rule, scope });
@@ -77,6 +77,7 @@ import { type DenyFace } from "../tools/fs/read-deny.js";
77
77
  import type { AssertAllKeysHandled, RuleOffersAbsence } from "./ask-origin.js";
78
78
  import { type ToolCallLike } from "./tool-registry.js";
79
79
  import { type HostReading } from "./host-target.js";
80
+ import { type NamedCall } from "./tool-name-readings.js";
80
81
  import { type PathDenialEvidence, type PathFamily, type PathIdentity } from "../tools/fs/safety.js";
81
82
  import { type TargetViews } from "./path-rule-binding.js";
82
83
  /**
@@ -284,6 +285,18 @@ export declare const DOMAIN_RULE_MARKER = "domain:";
284
285
  */
285
286
  export type RuleGrammar = "command" | "path" | "name" | "domain";
286
287
  export declare function ruleToolGrammarOf(toolName: string): RuleGrammar | undefined;
288
+ /**
289
+ * THE rule a tool's approval card mints a "don't ask again" option in — one answer, read by the offer factory and the consent door
290
+ * alike: `command` for the command rule word (the shell card's command rules), `name` / `domain` for a tool of those grammars (the one
291
+ * exact value rule), `tool` for a call no rule word speaks for under any name it answers to ({@link laneToolNamesOf} empty: the
292
+ * whole-tool rule, the reference's fallback card), and `undefined` for the rest — a path tool (no path offer is minted), a shell-face
293
+ * sibling of the command word (its commands are `Bash(…)` rules), and a tool that answers to one of those under an alias it declares
294
+ * (a caller's shell wearing `Bash`: a one-click whole-tool yes on it would be a licence for every program): its card names that it has
295
+ * no rule to offer. `toolName` is the wire name the card mints on; `call` the call's names (absent: the wire name alone — the
296
+ * consent door, which holds no face).
297
+ */
298
+ export type CardRuleForm = "command" | "name" | "domain" | "tool";
299
+ export declare function cardRuleFormOf(toolName: string, call?: NamedCall): CardRuleForm | undefined;
287
300
  /** The parameter a shell-face tool's rule content names as one of the tool's own scalar arguments (`Monitor(description:*)`,
288
301
  * `Bash(timeout:5)`), or undefined — the content is then a command spelling. */
289
302
  export declare function shellRuleParamOf(tool: string, content: string): string | undefined;
@@ -311,11 +324,11 @@ export declare function nameRuleSubjectOf(toolName: string, args: unknown): stri
311
324
  * domain tool's its own name — so a stored `Bash(…)` or `Edit(…)` row reaches a tool that answers to that name under another wire
312
325
  * name, as a policy's rule does. Every lane that judges a call by a rule's word reads it here: the policy compiler, the
313
326
  * person's stored rows, the org partition, the allow lists. Empty ⇒ no grammar speaks for the call. */
314
- export declare function laneToolNamesOf(req: Pick<import("./tool-policy.js").ToolCallRequest, "toolName" | "face">): readonly string[];
327
+ export declare function laneToolNamesOf(req: NamedCall): readonly string[];
315
328
  /** The match words a persisted rule is stored with, spelled once: {@link PersistedRuleMatch} is derived from this
316
329
  * tuple (each form is documented there). A store backend that checks a stored row's `match` reads this value
317
330
  * rather than keeping its own list. */
318
- export declare const PERSISTED_RULE_MATCHES: readonly ["exact", "prefix", "wildcard", "pattern", "subpath", "path", "name", "name_prefix", "host", "subdomain"];
331
+ export declare const PERSISTED_RULE_MATCHES: readonly ["exact", "prefix", "wildcard", "pattern", "subpath", "path", "name", "name_prefix", "host", "subdomain", "tool"];
319
332
  /**
320
333
  * Match forms, one family per grammar (`prefix` and `wildcard` are one predicate):
321
334
  * · `exact` — admits the one string the rule spells.
@@ -347,6 +360,8 @@ export declare const PERSISTED_RULE_MATCHES: readonly ["exact", "prefix", "wildc
347
360
  * · `name` / `name_prefix` — the NAME grammar ({@link parseNameRuleContent}).
348
361
  * · `host` / `subdomain` — the DOMAIN grammar ({@link parseDomainRuleContent}): one exact host, or every
349
362
  * host below one domain.
363
+ * · `tool` — the WHOLE-TOOL form, a rule with no content (`SendUserFile`, `Bash`, `mcp__srv__get_issue`), on any tool:
364
+ * `command` is empty and the rule reaches every call that answers to the name it spells ({@link wholeToolRuleReaches}).
350
365
  */
351
366
  export type PersistedRuleMatch = (typeof PERSISTED_RULE_MATCHES)[number];
352
367
  /**
@@ -1275,6 +1290,32 @@ export declare function adjudicatePersistedDomainRules(rules: readonly Persisted
1275
1290
  sessionId?: string;
1276
1291
  scopeIdentity?: ScopeRootIdentity;
1277
1292
  }): PersistedRuleVerdict | undefined;
1293
+ /**
1294
+ * THE predicate of a whole-tool rule (`match: "tool"`) over one call: the rule reaches the call iff the call answers to the name it
1295
+ * spells, under every name the call answers to (the model's spelling, the wire name, the aliases that resolve to it) — the
1296
+ * reference's tool-wide matcher. Every reader of a rule with no content asks it: an entry list's whole-tool row and a person's stored
1297
+ * whole-tool row alike.
1298
+ */
1299
+ export declare function wholeToolRuleReaches(tool: string, call: NamedCall): boolean;
1300
+ /**
1301
+ * The whole-tool sibling of {@link adjudicatePersistedRules}: the same precedence walk (deny > ask > allow) over the whole-tool rows
1302
+ * (`match: "tool"`) that reach the call ({@link wholeToolRuleReaches}) and are eligible under their own tool ({@link eligiblePersisted},
1303
+ * the one predicate); the first behavior with such a row decides, the first table-order row of it is the answer.
1304
+ */
1305
+ export declare function adjudicatePersistedToolRules(rules: readonly PersistedRule[], call: {
1306
+ request: NamedCall;
1307
+ cwd: string | undefined;
1308
+ sessionId?: string;
1309
+ scopeIdentity?: ScopeRootIdentity;
1310
+ }): PersistedRuleVerdict | undefined;
1311
+ /**
1312
+ * The ONE offer the card of a tool with no rule grammar carries ({@link cardRuleFormOf} `tool`): the whole-tool rule on its name (the
1313
+ * reference's fallback card, "don't ask again for <tool>"), or undefined when the name has no such rule (the round-trip law: the bare
1314
+ * name, parsed back as an allow, must be the whole-tool rule on that very name).
1315
+ */
1316
+ export declare function suggestRuleForTool(tool: string): Extract<RuleOffer, {
1317
+ kind: "single";
1318
+ }> | undefined;
1278
1319
  /**
1279
1320
  * The ONE offer a host tool's approval card carries: the exact rule for the host the call reaches (`WebFetch(domain:<host>)`, the
1280
1321
  * reference's "don't ask again for <host>" row), or undefined when no rule spells exactly that host (the round-trip law: the
@@ -2,13 +2,15 @@ import { homedir } from "node:os";
2
2
  import { shellWordsOf } from "../shell/shell-words.js";
3
3
  import { lexShell } from "../shell/lex.js";
4
4
  import { readProgramPosition } from "../tools/fs/bash-program-position.js";
5
- import { parsePermissionRule, ruleSpellingOf } from "./permission-rule-syntax.js";
5
+ import { isNameableToolName, parsePermissionRule, ruleSpellingOf } from "./permission-rule-syntax.js";
6
+ import { isCoveringRuleName } from "./namespaced-rule-name.js";
7
+ import { toolNameFaultOf } from "./tool-name-aliases.js";
6
8
  import { compileReadDeny } from "../tools/fs/read-deny.js";
7
9
  import { carriesShellRedirection, parseLeadingCommandName, splitShellCompoundSegments } from "../tools/fs/bash-readonly-classifier.js";
8
10
  import { INLINE_TRUNCATION_MARK, inlineUntrusted } from "./untrusted-text.js";
9
- import { catalogRuleFaceOf, hostTargetOf, isShellFaceToolName, pathTargetOf, protectivePathTargetOf } from "./tool-registry.js";
11
+ import { catalogRuleFaceOf, catalogToolNames, hostTargetOf, isShellFaceToolName, pathTargetOf, protectivePathTargetOf } from "./tool-registry.js";
10
12
  import { HOST_UNREADABLE_SENTENCE, hostPatternAdmits, readHostPattern, spelledHostPattern } from "./host-target.js";
11
- import { heldValues } from "./tool-name-readings.js";
13
+ import { heldBy, heldValues } from "./tool-name-readings.js";
12
14
  import { carriesDotSegment, isAbsoluteForFamily, isIdentityDir, isPathIdentity, isShellRootedSpellingUnmapped, isUncIdentity, pathFamilyOf, pathIdentityOf } from "../tools/fs/safety.js";
13
15
  import { bindPathRules, judgeRuleRows, rowsWhereTheyLead } from "./path-rule-binding.js";
14
16
  import { readShellCommand } from "./shell-run-candidates.js";
@@ -135,6 +137,14 @@ export function ruleToolGrammarOf(toolName) {
135
137
  return "domain";
136
138
  return pathTargetOf(toolName) !== undefined ? "path" : undefined;
137
139
  }
140
+ export function cardRuleFormOf(toolName, call = { toolName }) {
141
+ if (toolName === COMMAND_RULE_TOOL)
142
+ return "command";
143
+ const grammar = ruleToolGrammarOf(toolName);
144
+ if (grammar === "name" || grammar === "domain")
145
+ return grammar;
146
+ return grammar === undefined && laneToolNamesOf(call).length === 0 && laneToolNamesOf({ toolName }).length === 0 ? "tool" : undefined;
147
+ }
138
148
  export function shellRuleParamOf(tool, content) {
139
149
  const colon = content.indexOf(":");
140
150
  if (colon <= 0)
@@ -172,7 +182,7 @@ function ruleWordOf(name) {
172
182
  return COMMAND_RULE_TOOL;
173
183
  return ruleToolGrammarOf(name) !== undefined ? name : undefined;
174
184
  }
175
- export const PERSISTED_RULE_MATCHES = Object.freeze(["exact", "prefix", "wildcard", "pattern", "subpath", "path", "name", "name_prefix", "host", "subdomain"]);
185
+ export const PERSISTED_RULE_MATCHES = Object.freeze(["exact", "prefix", "wildcard", "pattern", "subpath", "path", "name", "name_prefix", "host", "subdomain", "tool"]);
176
186
  function isCommandMatch(match) {
177
187
  return match === "exact" || match === "prefix" || match === "wildcard" || match === "pattern";
178
188
  }
@@ -415,6 +425,19 @@ export function respelledRuleTextOf(text, behavior) {
415
425
  const read = parseRuleText(candidate, behavior);
416
426
  return "rule" in read ? read.rule.rule : undefined;
417
427
  }
428
+ function parseWholeToolRule(text, tool, behavior) {
429
+ if (!isNameableToolName(tool) || isCoveringRuleName(tool, behavior)) {
430
+ return reject("invalid.grammar", `"${text}" names a set of tools — a stored rule names one tool, or one tool's content; a set of tools is a list entry's form`);
431
+ }
432
+ const fault = toolNameFaultOf(tool, catalogToolNames(), behavior);
433
+ if (fault === undefined)
434
+ return { rule: { behavior, rule: tool, tool, match: "tool", command: "" } };
435
+ const why = fault.reason === "near_miss"
436
+ ? `is another spelling of "${fault.currentName}", which the engine's tool catalog names — a rule names its tool exactly as spelled, so this one would reach no tool`
437
+ : `names no tool under that name${fault.guidance !== undefined ? ` — ${fault.guidance}` : ""}`;
438
+ const write = fault.currentName !== undefined && !why.includes(`"${fault.currentName}"`) ? `; write "${fault.currentName}"` : "";
439
+ return reject("unsupported.tool", `"${text}" ${why}${write}`);
440
+ }
418
441
  export function parseRuleText(text, behavior) {
419
442
  if (!isRuleBehavior(behavior)) {
420
443
  return reject("invalid.grammar", `rule "${text}" was parsed under behavior ${escapeForDisclosure(behavior)}, which is not one of ${RULE_BEHAVIORS.join("/")}`);
@@ -438,9 +461,8 @@ export function parseRuleText(text, behavior) {
438
461
  };
439
462
  }
440
463
  const ruleContent = ruleContentOf(parsed);
441
- if (ruleContent === undefined) {
442
- return reject("invalid.grammar", `"${text}" is not a Tool(content) rule — a bare tool name claims the whole tool and is not a command rule`);
443
- }
464
+ if (ruleContent === undefined)
465
+ return parseWholeToolRule(text, parsed.toolName, behavior);
444
466
  if (parsed.toolName !== COMMAND_RULE_TOOL) {
445
467
  const grammar = ruleToolGrammarOf(parsed.toolName);
446
468
  if (grammar === undefined) {
@@ -510,6 +532,8 @@ export function parseRuleText(text, behavior) {
510
532
  return { rule: { behavior, rule: formatRuleText(command, match, COMMAND_RULE_TOOL), tool: COMMAND_RULE_TOOL, match, command } };
511
533
  }
512
534
  export function formatRuleText(command, match, tool) {
535
+ if (match === "tool")
536
+ return tool;
513
537
  if (match === "subpath")
514
538
  return `${tool}(//${command.startsWith("/") ? command.slice(1) : command}/**)`;
515
539
  if (match === "path")
@@ -1318,7 +1342,7 @@ export function commandCoverageOf(rules, call) {
1318
1342
  return covering.length > 0 ? { covering } : { uncovered: undefined };
1319
1343
  }
1320
1344
  function readsOnlyAsSegment(segment, lineObjection, whole) {
1321
- return lineObjection === undefined && !movesShellCursor(segment) && readOnlyShellVerdict(segment, undefined, undefined, () => lineDescriptorsOfText(whole)).readOnly;
1345
+ return lineObjection === undefined && !movesShellCursor(segment) && readOnlyShellVerdict(segment, { bound: () => lineDescriptorsOfText(whole) }).readOnly;
1322
1346
  }
1323
1347
  function firstEligibleDirectoryRule(rules, directory, call) {
1324
1348
  for (const rule of rules) {
@@ -1434,6 +1458,26 @@ export function adjudicatePersistedDomainRules(rules, call) {
1434
1458
  }
1435
1459
  return undefined;
1436
1460
  }
1461
+ export function wholeToolRuleReaches(tool, call) {
1462
+ return heldBy("policy.persistedToolRule", { has: (name) => name === tool }, call);
1463
+ }
1464
+ export function adjudicatePersistedToolRules(rules, call) {
1465
+ const at = { cwd: call.cwd, ...(call.sessionId !== undefined ? { sessionId: call.sessionId } : {}), ...(call.scopeIdentity !== undefined ? { scopeIdentity: call.scopeIdentity } : {}) };
1466
+ for (const behavior of RULE_BEHAVIORS_BY_PRECEDENCE) {
1467
+ const row = rules.find((rule) => rule.match === "tool" && wholeToolRuleReaches(rule.tool, call.request) && eligiblePersisted(rule, { ...at, tool: rule.tool }, behavior));
1468
+ if (row !== undefined)
1469
+ return { behavior, rules: [row] };
1470
+ }
1471
+ return undefined;
1472
+ }
1473
+ export function suggestRuleForTool(tool) {
1474
+ if (cardRuleFormOf(tool) !== "tool")
1475
+ return undefined;
1476
+ const parsed = parseRuleText(formatRuleText("", "tool", tool), "allow");
1477
+ if (!("rule" in parsed) || parsed.rule.match !== "tool" || parsed.rule.tool !== tool)
1478
+ return undefined;
1479
+ return { kind: "single", rule: parsed.rule.rule, match: "tool", command: "" };
1480
+ }
1437
1481
  export function suggestRuleForHost(tool, host) {
1438
1482
  if (ruleToolGrammarOf(tool) !== "domain")
1439
1483
  return undefined;
@@ -301,7 +301,7 @@ function readOrgRow(row, index) {
301
301
  const parsed = parseRuleText(text, said);
302
302
  if ("reject" in parsed)
303
303
  return unreadable(parsed.reject.code, undefined, parsed.reject.respelling);
304
- if (parsed.rule.tool !== COMMAND_RULE_TOOL)
304
+ if (parsed.rule.tool !== COMMAND_RULE_TOOL || parsed.rule.match === "tool")
305
305
  return unreadable("unsupported.tool");
306
306
  return { kind: "read", index, rule: text, behavior: said, parsed: parsed.rule };
307
307
  }
@@ -14,6 +14,15 @@ export declare const ENTER_PLAN_MODE_TOOL_NAME = "EnterPlanMode";
14
14
  * Exit is via `present_plan` (→ plan_review → human approve-resume), not by this tool.
15
15
  */
16
16
  export declare function createEnterPlanModeTool(enterPlanMode: () => Promise<void> | void): ToolSpec;
17
+ /** The plan file a leg declared (`TaskSpec.planFile`), as the plan-exit tool's file arm reads it: the declared spelling (the
18
+ * card's `filePath`), the same path as the seat tells it to the model (`shown` — `planFileShown`, one line, verbatim, at
19
+ * most 4096 characters: the seat refuses any other), and the seat's one reader of what the file holds (`readPlanFile`,
20
+ * advertised-writable-dirs.ts). Type-only import: this module is below the seat and must not load it. */
21
+ export interface PlanFileSource {
22
+ readonly path: string;
23
+ readonly shown: string;
24
+ readonly read: (signal?: AbortSignal) => Promise<import("./runner/advertised-writable-dirs.js").PlanFileReading>;
25
+ }
17
26
  /**
18
27
  * design/80 D-B — the first-party `present_plan` tool (CC `ExitPlanMode` parity). A THIN composition over the
19
28
  * general `ctx.requestReview()` primitive: the model calls it with a plan; the tool returns the plan as its
@@ -24,4 +33,4 @@ export declare function createEnterPlanModeTool(enterPlanMode: () => Promise<voi
24
33
  */
25
34
  export declare function createPresentPlanTool(requestReview: (opts?: {
26
35
  reason?: string;
27
- }) => void): ToolSpec;
36
+ }) => void, planFile?: PlanFileSource): ToolSpec;
@@ -1,6 +1,8 @@
1
1
  import { Type } from "typebox";
2
- import { delimitUntrusted } from "./untrusted-text.js";
2
+ import { delimitUntrusted, inlineUntrusted } from "./untrusted-text.js";
3
3
  import { mountRuleFace, toolFace } from "./tool-catalog-entries.js";
4
+ import { errorResult } from "./tools.js";
5
+ const READ_REASON_MAX = 600;
4
6
  export const PRESENT_PLAN_TOOL_NAME = "ExitPlanMode";
5
7
  export const ENTER_PLAN_MODE_TOOL_NAME = "EnterPlanMode";
6
8
  const ENTER_PLAN_MODE_DESCRIPTION = `Enter PLAN MODE (read-only): stop making changes and switch to exploration/planning. For the rest of this run, every write/edit/mutating tool call ASKS the user first ("Cannot write to <path> while in plan mode."; where nobody can answer, it is refused) while read-only tools (Read, Grep, Glob, etc.) still work. When your plan is ready, call ${PRESENT_PLAN_TOOL_NAME} with it — the run PAUSES for a human to approve it, then continues (read-only lifted) so you can execute.
@@ -59,7 +61,49 @@ const PRESENT_PLAN_DESCRIPTION = [
59
61
  "If the plan is approved, the run continues (and any read-only restriction is lifted) so you can execute it;",
60
62
  "if it is rejected or edited, follow the reviewer's feedback instead of the original plan.",
61
63
  ].join(" ");
62
- export function createPresentPlanTool(requestReview) {
64
+ const PRESENT_PLAN_FILE_DESCRIPTION = (shown) => `Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.
65
+
66
+ ## How This Tool Works
67
+ - You should have already written your plan to the plan file: ${shown}
68
+ - This tool does NOT take the plan content as a parameter - it will read the plan from the file you wrote
69
+ - This tool simply signals that you're done planning and ready for the user to review and approve; the run PAUSES for a human to approve, edit, or reject it
70
+ - The user will see the contents of your plan file when they review it
71
+
72
+ ## When to Use This Tool
73
+ IMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.
74
+
75
+ ## Before Using This Tool
76
+ Ensure your plan is complete and unambiguous:
77
+ - If you have unresolved questions about requirements or approach, resolve them first (in earlier phases)
78
+ - Once your plan is finalized, use THIS tool to request approval
79
+
80
+ **Important:** Do NOT separately ask "Is this plan okay?" or "Should I proceed?" - that's exactly what THIS tool does. ExitPlanMode inherently requests user approval of your plan.`;
81
+ function createPresentPlanFileTool(requestReview, planFile) {
82
+ return {
83
+ name: PRESENT_PLAN_TOOL_NAME,
84
+ ...toolFace("exit-plan-mode-file"),
85
+ ruleFace: mountRuleFace("exit-plan-mode-file"),
86
+ description: PRESENT_PLAN_FILE_DESCRIPTION(planFile.shown),
87
+ parameters: Type.Object({}),
88
+ execute: async (_args, ctx) => {
89
+ const read = await planFile.read(ctx?.signal);
90
+ if (!read.ok)
91
+ return errorResult(`The plan file ${planFile.shown} could not be read (${inlineUntrusted(read.reason, READ_REASON_MAX)}), so plan mode was not exited. Write your plan to this file and call ExitPlanMode again.`);
92
+ if (read.text === undefined)
93
+ return errorResult(`No plan file found at ${planFile.shown}. Please write your plan to this file before calling ExitPlanMode.`);
94
+ const plan = read.text;
95
+ requestReview({ reason: "ExitPlanMode" });
96
+ return {
97
+ content: `Plan presented for human review (from ${planFile.shown}):\n\n${delimitUntrusted("plan", plan)}\n\n` +
98
+ "(The run is pausing for approval — you will continue once the plan is approved, edited, or rejected.)",
99
+ details: { type: "exit-plan-mode", plan, isAgent: false, filePath: planFile.path },
100
+ };
101
+ },
102
+ };
103
+ }
104
+ export function createPresentPlanTool(requestReview, planFile) {
105
+ if (planFile !== undefined)
106
+ return createPresentPlanFileTool(requestReview, planFile);
63
107
  return {
64
108
  name: PRESENT_PLAN_TOOL_NAME,
65
109
  ...toolFace("exit-plan-mode"),
@@ -1,48 +1,59 @@
1
1
  /**
2
- * The HTTP credentials a protocol declaration carries — its static `headers` and the per-task principal
3
- * header (`principalHeader`) — and the one rule they obey, for MCP and A2A alike: they travel only to the
4
- * endpoints the declaration names, and every header name has exactly one owner, compared the way HTTP
5
- * compares names (case-insensitively). The principal header's owner is the engine: it sends the task's
6
- * principal under that name, or nothing under it when the task has none. A static header the credential vocabulary
7
- * reads as a credential is one the engine holds from the moment it resolves it: no child spawned on this host inherits
8
- * a variable whose value equals it (`holdOwnCredentialValues`, src/core/secret-env.ts).
2
+ * The HTTP headers one send to a protocol peer carries — the pieces the deployment's peer seat answered for it
3
+ * (src/core/peer-seat.ts) and the per-task principal header the declaration names (`principalHeader`) — and the one
4
+ * rule they obey, for MCP and A2A alike: they travel only to the endpoints the declaration names, and every header name
5
+ * has exactly one owner, compared the way HTTP compares names (case-insensitively). The principal header's owner is the
6
+ * engine: it sends the task's principal under that name, or nothing under it when the task has none. A name a protocol's
7
+ * transport writes itself (an MCP request's session, protocol version, content type, accept and resume headers) is the
8
+ * protocol's: neither a seat's answer nor the principal header owns it. The hosted-connector assertion header
9
+ * ({@link MCP_ASSERTION_HEADER}) is the seat's to answer and never the principal header's name. A header the credential
10
+ * vocabulary reads as a credential is one the engine holds from the moment it resolves it: no child spawned on this host
11
+ * inherits a variable whose value equals it (`holdOwnCredentialValues`, src/core/secret-env.ts).
9
12
  *
10
- * A declaration that breaks the rule is that peer's defect: the resolver throws inside the peer's own dial,
11
- * so the peer is skipped with a coded warning and its siblings still mount. The MCP transport binds its
12
- * endpoint by dialing only the declared URL with redirects not followed (`declaredEndpointFetch`); the A2A
13
- * peer, whose card may name another endpoint, is bound by {@link assertEndpointBound} and by its follow law (a request carrying
14
- * declared headers follows no redirect, {@link carriesDeclaredHeaders}).
13
+ * A principal header that breaks the rule is that peer's defect: the resolver throws inside the peer's own dial, so the
14
+ * peer is skipped with a coded warning and its siblings still mount; an answer that breaks it is the seat's, and that send
15
+ * is not made. The MCP transport binds its endpoint by dialing only the declared URL with redirects not followed (the seat's
16
+ * fetch, `peerFetch`); the A2A peer, whose card may name another endpoint, is bound at each send that carries pieces by
17
+ * {@link assertEndpointBound} and by its follow law (a request carrying them follows no redirect, {@link carriesDeclaredHeaders}).
15
18
  */
16
19
  import type { ProtocolId } from "./protocol-table.js";
17
- /** The per-peer HTTP auth declaration every protocol spec carries in the same two fields. */
20
+ import { type Egress } from "./untrusted-egress.js";
21
+ /**
22
+ * The HTTP header NAME a hosted connector reads the principal assertion from: the engine's one definition of that name, exported from
23
+ * the package root so a deployment, a host and a connector each read it here instead of spelling it again. The name only — the
24
+ * value (the assertion itself) is not minted or held by this constant: the deployment's peer seat answers it under this name, per
25
+ * send. It is never the principal header's name (in any letter case): a declaration naming it so is refused at its dial with
26
+ * `config.protocol_header_collision`.
27
+ */
28
+ export declare const MCP_ASSERTION_HEADER = "connector-assertion";
29
+ /** The headers one send carries: the seat's answered `headers` and the declaration's `principalHeader` name. */
18
30
  export interface ProtocolHttpAuth {
19
31
  headers?: Record<string, string>;
20
32
  principalHeader?: string;
21
33
  }
22
- /** The first header name (any case) the declaration gives two owners, with both spellings. */
23
- export declare function headerOwnershipCollision(t: ProtocolHttpAuth): {
34
+ /**
35
+ * The first header name (any case) one send to a `protocol` peer would give two owners, with both spellings: two spellings among the
36
+ * answered `headers`, an answered header under the principal header's name, a name the protocol's transport writes itself (`first` is
37
+ * then the protocol's spelling, `engineOwned` true), or a principal header named as the engine's {@link MCP_ASSERTION_HEADER}
38
+ * (`first` the engine's spelling, `engineOwned` true). The assertion header among the answered headers is the seat's to send.
39
+ */
40
+ export declare function headerOwnershipCollision(t: ProtocolHttpAuth, protocol: ProtocolId): {
24
41
  readonly first: string;
25
42
  readonly second: string;
43
+ readonly engineOwned: boolean;
26
44
  } | undefined;
27
45
  /**
28
- * Resolve the HTTP request headers for one remote peer of `protocol`: the static headers, plus the
46
+ * Resolve the HTTP request headers of one send to a peer of `protocol`: the seat's answered headers, plus the
29
47
  * principal under `principalHeader` when both are present. Throws `config.protocol_header_collision` when
30
- * one header name has two owners (two static spellings, or a static entry under the principal header's
31
- * name — which would otherwise be sent merged beside the principal, or alone when the task has none), and
32
- * on a principal carrying CR/LF. Callers invoke it INSIDE their per-peer boundary.
48
+ * one header name would have two owners ({@link headerOwnershipCollision}: two spellings of one answered name, an
49
+ * answered header under the principal header's name — which would otherwise be sent merged beside the principal, or
50
+ * alone when the task has none — a name the protocol's transport writes, or a principal header named as the engine's
51
+ * {@link MCP_ASSERTION_HEADER}), and on a principal carrying CR/LF. Callers invoke it INSIDE their per-peer boundary.
33
52
  */
34
53
  export declare function resolveProtocolHttpHeaders(protocol: ProtocolId, t: ProtocolHttpAuth, principal?: string): Readonly<Record<string, string>> | undefined;
35
54
  /** The engine's default request headers under the declared ones: a declared name, in any case, owns that header
36
55
  * (the default of the same name is not sent beside it). */
37
56
  export declare function underDeclaredHeaders(defaults: Readonly<Record<string, string>>, declared: Record<string, string> | undefined): Record<string, string>;
38
- /**
39
- * Every header VALUE one HTTP peer's requests carry, whatever the header's NAME: each string value of the declaration's static
40
- * `headers` and the principal the engine sends under `principalHeader`, as declared. The transport knows these; the credential vocabulary
41
- * can only guess by name. How an endpoint can print one back — edges dropped, its credentials part, percent-encoded — is derived from
42
- * each value by {@link requestEchoSpellings}, once, and nowhere else.
43
- * Total: a declaration whose members cannot be read yields what could be read, because it is called on a failure path.
44
- */
45
- export declare function declaredHeaderValues(transport: unknown, principal?: string): readonly string[];
46
57
  /**
47
58
  * A peer's error text with what the peer was SENT taken out of it. Both kinds of removal are found on the ORIGINAL text (so no marker is
48
59
  * rescanned and no replacement can disturb what another one reads) and the ranges they take are merged, one marker per merged range: every
@@ -53,15 +64,29 @@ export declare function declaredHeaderValues(transport: unknown, principal?: str
53
64
  * from outside takes its own range and the member's value goes with it. A declared value that is also an ordinary word or number (`en`, `1`,
54
65
  * `application/json`) goes wherever it occurs in the remote's words, in any case — a legibility cost, never a leak; the failure's closed
55
66
  * fields (code, status, delivery) are not text. A declaration too large for one matcher (tens of thousands of characters, which no header
56
- * carries) makes the whole text the marker: the pass never throws and never shows what it could not match. Run BEFORE the credential
57
- * vocabulary: that pass rewrites parts of a value, after which the value no longer matches whole.
67
+ * carries) makes the whole text the marker: the pass never throws and never shows what it could not match. A hit that lies wholly inside
68
+ * a marker a pass already wrote (the exact literals, `redactionMarkerSpans`) is no hit, and one that reaches into a marker takes the
69
+ * whole marker with it, so the pass over its own output answers the same text.
58
70
  */
59
71
  export declare function scrubRequestEcho(text: string, declared: readonly string[]): string;
72
+ /**
73
+ * THE one form a remote endpoint's words take when the engine carries them in its own words — an MCP server's failure, a model
74
+ * provider's error body, frame or transport failure, a memory distiller seat's failure: what the request was declared with
75
+ * ({@link scrubRequestEcho}: `declared` is required, so no mint reads a remote's words without naming its request), then the credential
76
+ * vocabulary. Words with no declared value in them read exactly as the vocabulary renders them. Where a declared value is there, the
77
+ * values the vocabulary finds in the ORIGINAL words are taken out with it, so neither disarms the other: removing a declared `Bearer`
78
+ * cannot hide the token after it from the vocabulary, and the vocabulary rewriting part of a declared value cannot leave the rest. A
79
+ * caller that bounds the text for display cuts what this returns, never the remote's raw words, so a cut can leave no part of a value.
80
+ * The function is a fixed point (its own output answers the same text). A store, a log or an event lane that receives the result does
81
+ * not redact again: persistence is not an exit, the mint is.
82
+ */
83
+ export declare function remoteWords(text: string, declared: readonly string[]): Egress<"same-principal">;
60
84
  /** Whether a resolved header set carries anything the declaration bound to its endpoints — a request that does follows no redirect (the
61
85
  * next hop is not a declared endpoint; A2A's follow law reads this). */
62
86
  export declare function carriesDeclaredHeaders(headers: Record<string, string> | undefined): boolean;
63
87
  /**
64
- * Refuse an endpoint a peer advertised (an A2A card's interface URL) when it lies outside every origin the
65
- * declaration names and the peer's requests carry declared headers: `config.protocol_endpoint_unbound`.
88
+ * Refuse a send to `endpoint` (an A2A card's interface URL, judged at every send) when it lies outside every origin the
89
+ * declaration names and the send carries pieces the peer seat answered: `config.protocol_endpoint_unbound`. A send that
90
+ * carries none goes where the card says.
66
91
  */
67
92
  export declare function assertEndpointBound(protocol: ProtocolId, peer: string, endpoint: string, declared: readonly string[], headers: Record<string, string> | undefined): void;