@draht/coding-agent 2026.7.13 → 2026.9.5-1

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 (614) hide show
  1. package/CHANGELOG.md +241 -0
  2. package/README.md +47 -2
  3. package/agents/debugger.md +12 -1
  4. package/agents/git-committer.md +1 -0
  5. package/agents/implementer.md +20 -0
  6. package/agents/investigator.md +75 -0
  7. package/agents/reviewer.md +7 -0
  8. package/agents/spec-reviewer.md +66 -0
  9. package/agents/verifier.md +4 -3
  10. package/bin/draht-tools.cjs +472 -41
  11. package/dist/agents/debugger.md +12 -1
  12. package/dist/agents/git-committer.md +1 -0
  13. package/dist/agents/implementer.md +20 -0
  14. package/dist/agents/investigator.md +75 -0
  15. package/dist/agents/reviewer.md +7 -0
  16. package/dist/agents/spec-reviewer.md +66 -0
  17. package/dist/agents/verifier.md +4 -3
  18. package/dist/bun/cli.js +2 -0
  19. package/dist/bun/cli.js.map +1 -1
  20. package/dist/cli/args.d.ts +10 -0
  21. package/dist/cli/args.d.ts.map +1 -1
  22. package/dist/cli/args.js +80 -3
  23. package/dist/cli/args.js.map +1 -1
  24. package/dist/cli/attach-mode.d.ts +61 -0
  25. package/dist/cli/attach-mode.d.ts.map +1 -1
  26. package/dist/cli/attach-mode.js +243 -5
  27. package/dist/cli/attach-mode.js.map +1 -1
  28. package/dist/cli/config-selector.js +1 -1
  29. package/dist/cli/config-selector.js.map +1 -1
  30. package/dist/cli/credential-print.d.ts +23 -0
  31. package/dist/cli/credential-print.d.ts.map +1 -0
  32. package/dist/cli/credential-print.js +117 -0
  33. package/dist/cli/credential-print.js.map +1 -0
  34. package/dist/cli/list-models.d.ts +2 -2
  35. package/dist/cli/list-models.d.ts.map +1 -1
  36. package/dist/cli/list-models.js +3 -3
  37. package/dist/cli/list-models.js.map +1 -1
  38. package/dist/cli/startup-ui.js +1 -1
  39. package/dist/cli/startup-ui.js.map +1 -1
  40. package/dist/config.d.ts +9 -0
  41. package/dist/config.d.ts.map +1 -1
  42. package/dist/config.js +31 -4
  43. package/dist/config.js.map +1 -1
  44. package/dist/core/agent-session-runtime.d.ts +17 -1
  45. package/dist/core/agent-session-runtime.d.ts.map +1 -1
  46. package/dist/core/agent-session-runtime.js +90 -30
  47. package/dist/core/agent-session-runtime.js.map +1 -1
  48. package/dist/core/agent-session-services.d.ts +4 -7
  49. package/dist/core/agent-session-services.d.ts.map +1 -1
  50. package/dist/core/agent-session-services.js +24 -9
  51. package/dist/core/agent-session-services.js.map +1 -1
  52. package/dist/core/agent-session.d.ts +87 -27
  53. package/dist/core/agent-session.d.ts.map +1 -1
  54. package/dist/core/agent-session.js +337 -154
  55. package/dist/core/agent-session.js.map +1 -1
  56. package/dist/core/auth-storage.d.ts +20 -104
  57. package/dist/core/auth-storage.d.ts.map +1 -1
  58. package/dist/core/auth-storage.js +104 -260
  59. package/dist/core/auth-storage.js.map +1 -1
  60. package/dist/core/builtins/checkpoints.d.ts +20 -0
  61. package/dist/core/builtins/checkpoints.d.ts.map +1 -0
  62. package/dist/core/builtins/checkpoints.js +161 -0
  63. package/dist/core/builtins/checkpoints.js.map +1 -0
  64. package/dist/core/builtins/duet.d.ts +26 -0
  65. package/dist/core/builtins/duet.d.ts.map +1 -0
  66. package/dist/core/builtins/duet.js +660 -0
  67. package/dist/core/builtins/duet.js.map +1 -0
  68. package/dist/core/builtins/index.d.ts.map +1 -1
  69. package/dist/core/builtins/index.js +7 -1
  70. package/dist/core/builtins/index.js.map +1 -1
  71. package/dist/core/builtins/subagent.d.ts +24 -4
  72. package/dist/core/builtins/subagent.d.ts.map +1 -1
  73. package/dist/core/builtins/subagent.js +278 -35
  74. package/dist/core/builtins/subagent.js.map +1 -1
  75. package/dist/core/cache-stats.d.ts +2 -2
  76. package/dist/core/cache-stats.d.ts.map +1 -1
  77. package/dist/core/cache-stats.js +1 -1
  78. package/dist/core/cache-stats.js.map +1 -1
  79. package/dist/core/checkpoints/checkpoint-cli.d.ts +17 -0
  80. package/dist/core/checkpoints/checkpoint-cli.d.ts.map +1 -0
  81. package/dist/core/checkpoints/checkpoint-cli.js +78 -0
  82. package/dist/core/checkpoints/checkpoint-cli.js.map +1 -0
  83. package/dist/core/checkpoints/checkpoint-manager.d.ts +294 -0
  84. package/dist/core/checkpoints/checkpoint-manager.d.ts.map +1 -0
  85. package/dist/core/checkpoints/checkpoint-manager.js +865 -0
  86. package/dist/core/checkpoints/checkpoint-manager.js.map +1 -0
  87. package/dist/core/checkpoints/rewind.d.ts +141 -0
  88. package/dist/core/checkpoints/rewind.d.ts.map +1 -0
  89. package/dist/core/checkpoints/rewind.js +246 -0
  90. package/dist/core/checkpoints/rewind.js.map +1 -0
  91. package/dist/core/compaction/branch-summarization.d.ts +9 -3
  92. package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
  93. package/dist/core/compaction/branch-summarization.js +16 -14
  94. package/dist/core/compaction/branch-summarization.js.map +1 -1
  95. package/dist/core/compaction/compaction.d.ts +24 -3
  96. package/dist/core/compaction/compaction.d.ts.map +1 -1
  97. package/dist/core/compaction/compaction.js +96 -30
  98. package/dist/core/compaction/compaction.js.map +1 -1
  99. package/dist/core/compaction/utils.d.ts +1 -1
  100. package/dist/core/compaction/utils.d.ts.map +1 -1
  101. package/dist/core/compaction/utils.js +6 -17
  102. package/dist/core/compaction/utils.js.map +1 -1
  103. package/dist/core/context-windows.d.ts +7 -0
  104. package/dist/core/context-windows.d.ts.map +1 -0
  105. package/dist/core/context-windows.js +35 -0
  106. package/dist/core/context-windows.js.map +1 -0
  107. package/dist/core/extensions/index.d.ts +1 -1
  108. package/dist/core/extensions/index.d.ts.map +1 -1
  109. package/dist/core/extensions/index.js.map +1 -1
  110. package/dist/core/extensions/loader.d.ts.map +1 -1
  111. package/dist/core/extensions/loader.js +101 -23
  112. package/dist/core/extensions/loader.js.map +1 -1
  113. package/dist/core/extensions/runner.d.ts +19 -3
  114. package/dist/core/extensions/runner.d.ts.map +1 -1
  115. package/dist/core/extensions/runner.js +117 -2
  116. package/dist/core/extensions/runner.js.map +1 -1
  117. package/dist/core/extensions/types.d.ts +236 -9
  118. package/dist/core/extensions/types.d.ts.map +1 -1
  119. package/dist/core/extensions/types.js.map +1 -1
  120. package/dist/core/extensions/wrapper.d.ts.map +1 -1
  121. package/dist/core/extensions/wrapper.js +22 -3
  122. package/dist/core/extensions/wrapper.js.map +1 -1
  123. package/dist/core/footer-data-provider.d.ts +10 -0
  124. package/dist/core/footer-data-provider.d.ts.map +1 -1
  125. package/dist/core/footer-data-provider.js +1 -1
  126. package/dist/core/footer-data-provider.js.map +1 -1
  127. package/dist/core/http-dispatcher.d.ts.map +1 -1
  128. package/dist/core/http-dispatcher.js +7 -0
  129. package/dist/core/http-dispatcher.js.map +1 -1
  130. package/dist/core/index.d.ts +1 -1
  131. package/dist/core/index.d.ts.map +1 -1
  132. package/dist/core/index.js.map +1 -1
  133. package/dist/core/keybindings.d.ts +18 -3
  134. package/dist/core/keybindings.d.ts.map +1 -1
  135. package/dist/core/keybindings.js +12 -3
  136. package/dist/core/keybindings.js.map +1 -1
  137. package/dist/core/model-config.d.ts +542 -0
  138. package/dist/core/model-config.d.ts.map +1 -0
  139. package/dist/core/model-config.js +247 -0
  140. package/dist/core/model-config.js.map +1 -0
  141. package/dist/core/model-registry.d.ts +19 -124
  142. package/dist/core/model-registry.d.ts.map +1 -1
  143. package/dist/core/model-registry.js +56 -727
  144. package/dist/core/model-registry.js.map +1 -1
  145. package/dist/core/model-resolver.d.ts +7 -6
  146. package/dist/core/model-resolver.d.ts.map +1 -1
  147. package/dist/core/model-resolver.js +74 -27
  148. package/dist/core/model-resolver.js.map +1 -1
  149. package/dist/core/model-runtime.d.ts +89 -0
  150. package/dist/core/model-runtime.d.ts.map +1 -0
  151. package/dist/core/model-runtime.js +451 -0
  152. package/dist/core/model-runtime.js.map +1 -0
  153. package/dist/core/models-store.d.ts +17 -0
  154. package/dist/core/models-store.d.ts.map +1 -0
  155. package/dist/core/models-store.js +46 -0
  156. package/dist/core/models-store.js.map +1 -0
  157. package/dist/core/multi-agent/permission-gate.d.ts.map +1 -1
  158. package/dist/core/multi-agent/permission-gate.js +4 -3
  159. package/dist/core/multi-agent/permission-gate.js.map +1 -1
  160. package/dist/core/multi-agent/worktree.d.ts +2 -0
  161. package/dist/core/multi-agent/worktree.d.ts.map +1 -1
  162. package/dist/core/multi-agent/worktree.js +2 -2
  163. package/dist/core/multi-agent/worktree.js.map +1 -1
  164. package/dist/core/package-manager.d.ts +7 -1
  165. package/dist/core/package-manager.d.ts.map +1 -1
  166. package/dist/core/package-manager.js +41 -45
  167. package/dist/core/package-manager.js.map +1 -1
  168. package/dist/core/permission-relay/index.d.ts +19 -0
  169. package/dist/core/permission-relay/index.d.ts.map +1 -0
  170. package/dist/core/permission-relay/index.js +49 -0
  171. package/dist/core/permission-relay/index.js.map +1 -0
  172. package/dist/core/permission-relay/relay-ui-context.d.ts +39 -0
  173. package/dist/core/permission-relay/relay-ui-context.d.ts.map +1 -0
  174. package/dist/core/permission-relay/relay-ui-context.js +788 -0
  175. package/dist/core/permission-relay/relay-ui-context.js.map +1 -0
  176. package/dist/core/permission-relay/types.d.ts +222 -0
  177. package/dist/core/permission-relay/types.d.ts.map +1 -0
  178. package/dist/core/permission-relay/types.js +15 -0
  179. package/dist/core/permission-relay/types.js.map +1 -0
  180. package/dist/core/pi-manifest.d.ts +14 -0
  181. package/dist/core/pi-manifest.d.ts.map +1 -0
  182. package/dist/core/pi-manifest.js +35 -0
  183. package/dist/core/pi-manifest.js.map +1 -0
  184. package/dist/core/project-trust.js +2 -2
  185. package/dist/core/project-trust.js.map +1 -1
  186. package/dist/core/prompt-templates.d.ts +1 -0
  187. package/dist/core/prompt-templates.d.ts.map +1 -1
  188. package/dist/core/prompt-templates.js +4 -4
  189. package/dist/core/prompt-templates.js.map +1 -1
  190. package/dist/core/provider-composer.d.ts +55 -0
  191. package/dist/core/provider-composer.d.ts.map +1 -0
  192. package/dist/core/provider-composer.js +375 -0
  193. package/dist/core/provider-composer.js.map +1 -0
  194. package/dist/core/radius.d.ts +2 -0
  195. package/dist/core/radius.d.ts.map +1 -0
  196. package/dist/core/radius.js +2 -0
  197. package/dist/core/radius.js.map +1 -0
  198. package/dist/core/remote-catalog-provider.d.ts +5 -0
  199. package/dist/core/remote-catalog-provider.d.ts.map +1 -0
  200. package/dist/core/remote-catalog-provider.js +115 -0
  201. package/dist/core/remote-catalog-provider.js.map +1 -0
  202. package/dist/core/resource-loader.d.ts +36 -0
  203. package/dist/core/resource-loader.d.ts.map +1 -1
  204. package/dist/core/resource-loader.js +159 -27
  205. package/dist/core/resource-loader.js.map +1 -1
  206. package/dist/core/runtime-credentials.d.ts +15 -0
  207. package/dist/core/runtime-credentials.d.ts.map +1 -0
  208. package/dist/core/runtime-credentials.js +35 -0
  209. package/dist/core/runtime-credentials.js.map +1 -0
  210. package/dist/core/sandbox/bash-operations.d.ts +149 -0
  211. package/dist/core/sandbox/bash-operations.d.ts.map +1 -0
  212. package/dist/core/sandbox/bash-operations.js +163 -0
  213. package/dist/core/sandbox/bash-operations.js.map +1 -0
  214. package/dist/core/sandbox/env.d.ts +83 -0
  215. package/dist/core/sandbox/env.d.ts.map +1 -0
  216. package/dist/core/sandbox/env.js +123 -0
  217. package/dist/core/sandbox/env.js.map +1 -0
  218. package/dist/core/sandbox/executor.d.ts +104 -0
  219. package/dist/core/sandbox/executor.d.ts.map +1 -0
  220. package/dist/core/sandbox/executor.js +92 -0
  221. package/dist/core/sandbox/executor.js.map +1 -0
  222. package/dist/core/sandbox/index.d.ts +36 -0
  223. package/dist/core/sandbox/index.d.ts.map +1 -0
  224. package/dist/core/sandbox/index.js +36 -0
  225. package/dist/core/sandbox/index.js.map +1 -0
  226. package/dist/core/sandbox/linux.d.ts +121 -0
  227. package/dist/core/sandbox/linux.d.ts.map +1 -0
  228. package/dist/core/sandbox/linux.js +260 -0
  229. package/dist/core/sandbox/linux.js.map +1 -0
  230. package/dist/core/sandbox/policy.d.ts +142 -0
  231. package/dist/core/sandbox/policy.d.ts.map +1 -0
  232. package/dist/core/sandbox/policy.js +297 -0
  233. package/dist/core/sandbox/policy.js.map +1 -0
  234. package/dist/core/sandbox/real-path.d.ts +112 -0
  235. package/dist/core/sandbox/real-path.d.ts.map +1 -0
  236. package/dist/core/sandbox/real-path.js +158 -0
  237. package/dist/core/sandbox/real-path.js.map +1 -0
  238. package/dist/core/sandbox/seatbelt-profile.d.ts +95 -0
  239. package/dist/core/sandbox/seatbelt-profile.d.ts.map +1 -0
  240. package/dist/core/sandbox/seatbelt-profile.js +239 -0
  241. package/dist/core/sandbox/seatbelt-profile.js.map +1 -0
  242. package/dist/core/sandbox/seatbelt.d.ts +95 -0
  243. package/dist/core/sandbox/seatbelt.d.ts.map +1 -0
  244. package/dist/core/sandbox/seatbelt.js +154 -0
  245. package/dist/core/sandbox/seatbelt.js.map +1 -0
  246. package/dist/core/sandbox/self-test.d.ts +109 -0
  247. package/dist/core/sandbox/self-test.d.ts.map +1 -0
  248. package/dist/core/sandbox/self-test.js +369 -0
  249. package/dist/core/sandbox/self-test.js.map +1 -0
  250. package/dist/core/sandbox/spawn.d.ts +33 -0
  251. package/dist/core/sandbox/spawn.d.ts.map +1 -0
  252. package/dist/core/sandbox/spawn.js +87 -0
  253. package/dist/core/sandbox/spawn.js.map +1 -0
  254. package/dist/core/sdk.d.ts +3 -6
  255. package/dist/core/sdk.d.ts.map +1 -1
  256. package/dist/core/sdk.js +25 -22
  257. package/dist/core/sdk.js.map +1 -1
  258. package/dist/core/session-manager.d.ts +74 -7
  259. package/dist/core/session-manager.d.ts.map +1 -1
  260. package/dist/core/session-manager.js +169 -34
  261. package/dist/core/session-manager.js.map +1 -1
  262. package/dist/core/settings-manager.d.ts +22 -1
  263. package/dist/core/settings-manager.d.ts.map +1 -1
  264. package/dist/core/settings-manager.js +36 -16
  265. package/dist/core/settings-manager.js.map +1 -1
  266. package/dist/core/skills.d.ts +3 -1
  267. package/dist/core/skills.d.ts.map +1 -1
  268. package/dist/core/skills.js +19 -6
  269. package/dist/core/skills.js.map +1 -1
  270. package/dist/core/slash-commands.d.ts.map +1 -1
  271. package/dist/core/slash-commands.js +1 -0
  272. package/dist/core/slash-commands.js.map +1 -1
  273. package/dist/core/soak/soak-log.d.ts +298 -0
  274. package/dist/core/soak/soak-log.d.ts.map +1 -0
  275. package/dist/core/soak/soak-log.js +660 -0
  276. package/dist/core/soak/soak-log.js.map +1 -0
  277. package/dist/core/soak/soak-reader.d.ts +60 -0
  278. package/dist/core/soak/soak-reader.d.ts.map +1 -0
  279. package/dist/core/soak/soak-reader.js +106 -0
  280. package/dist/core/soak/soak-reader.js.map +1 -0
  281. package/dist/core/socket-server/discovery.d.ts +78 -1
  282. package/dist/core/socket-server/discovery.d.ts.map +1 -1
  283. package/dist/core/socket-server/discovery.js +356 -37
  284. package/dist/core/socket-server/discovery.js.map +1 -1
  285. package/dist/core/socket-server/index.d.ts +10 -4
  286. package/dist/core/socket-server/index.d.ts.map +1 -1
  287. package/dist/core/socket-server/index.js +6 -3
  288. package/dist/core/socket-server/index.js.map +1 -1
  289. package/dist/core/socket-server/permission-delivery.d.ts +125 -0
  290. package/dist/core/socket-server/permission-delivery.d.ts.map +1 -0
  291. package/dist/core/socket-server/permission-delivery.js +152 -0
  292. package/dist/core/socket-server/permission-delivery.js.map +1 -0
  293. package/dist/core/socket-server/permission-registry.d.ts +301 -0
  294. package/dist/core/socket-server/permission-registry.d.ts.map +1 -0
  295. package/dist/core/socket-server/permission-registry.js +410 -0
  296. package/dist/core/socket-server/permission-registry.js.map +1 -0
  297. package/dist/core/socket-server/permission-relay.d.ts +81 -0
  298. package/dist/core/socket-server/permission-relay.d.ts.map +1 -0
  299. package/dist/core/socket-server/permission-relay.js +528 -0
  300. package/dist/core/socket-server/permission-relay.js.map +1 -0
  301. package/dist/core/socket-server/safe-text.d.ts +83 -0
  302. package/dist/core/socket-server/safe-text.d.ts.map +1 -0
  303. package/dist/core/socket-server/safe-text.js +277 -0
  304. package/dist/core/socket-server/safe-text.js.map +1 -0
  305. package/dist/core/socket-server/session-integration.d.ts +65 -2
  306. package/dist/core/socket-server/session-integration.d.ts.map +1 -1
  307. package/dist/core/socket-server/session-integration.js +434 -32
  308. package/dist/core/socket-server/session-integration.js.map +1 -1
  309. package/dist/core/socket-server/socket-client.d.ts +21 -2
  310. package/dist/core/socket-server/socket-client.d.ts.map +1 -1
  311. package/dist/core/socket-server/socket-client.js +52 -1
  312. package/dist/core/socket-server/socket-client.js.map +1 -1
  313. package/dist/core/socket-server/socket-server.d.ts +152 -1
  314. package/dist/core/socket-server/socket-server.d.ts.map +1 -1
  315. package/dist/core/socket-server/socket-server.js +775 -26
  316. package/dist/core/socket-server/socket-server.js.map +1 -1
  317. package/dist/core/socket-server/types.d.ts +106 -2
  318. package/dist/core/socket-server/types.d.ts.map +1 -1
  319. package/dist/core/socket-server/types.js +13 -1
  320. package/dist/core/socket-server/types.js.map +1 -1
  321. package/dist/core/system-prompt.d.ts.map +1 -1
  322. package/dist/core/system-prompt.js +10 -21
  323. package/dist/core/system-prompt.js.map +1 -1
  324. package/dist/core/tools/bash.d.ts +3 -1
  325. package/dist/core/tools/bash.d.ts.map +1 -1
  326. package/dist/core/tools/bash.js +39 -7
  327. package/dist/core/tools/bash.js.map +1 -1
  328. package/dist/core/tools/edit.d.ts.map +1 -1
  329. package/dist/core/tools/edit.js +17 -2
  330. package/dist/core/tools/edit.js.map +1 -1
  331. package/dist/core/tools/find.d.ts +3 -0
  332. package/dist/core/tools/find.d.ts.map +1 -1
  333. package/dist/core/tools/find.js +11 -18
  334. package/dist/core/tools/find.js.map +1 -1
  335. package/dist/core/tools/read.js +1 -1
  336. package/dist/core/tools/read.js.map +1 -1
  337. package/dist/core/tools/tool-definition-wrapper.d.ts.map +1 -1
  338. package/dist/core/tools/tool-definition-wrapper.js +3 -1
  339. package/dist/core/tools/tool-definition-wrapper.js.map +1 -1
  340. package/dist/core/trust-manager.d.ts +6 -4
  341. package/dist/core/trust-manager.d.ts.map +1 -1
  342. package/dist/core/trust-manager.js +55 -21
  343. package/dist/core/trust-manager.js.map +1 -1
  344. package/dist/core/usage-totals.d.ts +19 -0
  345. package/dist/core/usage-totals.d.ts.map +1 -0
  346. package/dist/core/usage-totals.js +52 -0
  347. package/dist/core/usage-totals.js.map +1 -0
  348. package/dist/extensions/index.d.ts +3 -0
  349. package/dist/extensions/index.d.ts.map +1 -0
  350. package/dist/extensions/index.js +7 -0
  351. package/dist/extensions/index.js.map +1 -0
  352. package/dist/extensions/llama/client.d.ts +61 -0
  353. package/dist/extensions/llama/client.d.ts.map +1 -0
  354. package/dist/extensions/llama/client.js +300 -0
  355. package/dist/extensions/llama/client.js.map +1 -0
  356. package/dist/extensions/llama/huggingface.d.ts +23 -0
  357. package/dist/extensions/llama/huggingface.d.ts.map +1 -0
  358. package/dist/extensions/llama/huggingface.js +139 -0
  359. package/dist/extensions/llama/huggingface.js.map +1 -0
  360. package/dist/extensions/llama/index.d.ts +3 -0
  361. package/dist/extensions/llama/index.d.ts.map +1 -0
  362. package/dist/extensions/llama/index.js +208 -0
  363. package/dist/extensions/llama/index.js.map +1 -0
  364. package/dist/extensions/llama/provider.d.ts +10 -0
  365. package/dist/extensions/llama/provider.d.ts.map +1 -0
  366. package/dist/extensions/llama/provider.js +111 -0
  367. package/dist/extensions/llama/provider.js.map +1 -0
  368. package/dist/extensions/llama/ui.d.ts +42 -0
  369. package/dist/extensions/llama/ui.d.ts.map +1 -0
  370. package/dist/extensions/llama/ui.js +400 -0
  371. package/dist/extensions/llama/ui.js.map +1 -0
  372. package/dist/extensions/stub-provider/index.d.ts +9 -0
  373. package/dist/extensions/stub-provider/index.d.ts.map +1 -0
  374. package/dist/extensions/stub-provider/index.js +13 -0
  375. package/dist/extensions/stub-provider/index.js.map +1 -0
  376. package/dist/extensions/stub-provider/provider.d.ts +77 -0
  377. package/dist/extensions/stub-provider/provider.d.ts.map +1 -0
  378. package/dist/extensions/stub-provider/provider.js +193 -0
  379. package/dist/extensions/stub-provider/provider.js.map +1 -0
  380. package/dist/hooks/gsd/draht-quality-gate.js +3 -3
  381. package/dist/index.d.ts +4 -3
  382. package/dist/index.d.ts.map +1 -1
  383. package/dist/index.js +3 -3
  384. package/dist/index.js.map +1 -1
  385. package/dist/main.d.ts.map +1 -1
  386. package/dist/main.js +305 -61
  387. package/dist/main.js.map +1 -1
  388. package/dist/modes/interactive/components/assistant-message.d.ts.map +1 -1
  389. package/dist/modes/interactive/components/assistant-message.js +22 -10
  390. package/dist/modes/interactive/components/assistant-message.js.map +1 -1
  391. package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
  392. package/dist/modes/interactive/components/config-selector.js +3 -2
  393. package/dist/modes/interactive/components/config-selector.js.map +1 -1
  394. package/dist/modes/interactive/components/custom-editor.js +1 -1
  395. package/dist/modes/interactive/components/custom-editor.js.map +1 -1
  396. package/dist/modes/interactive/components/custom-message.d.ts +3 -1
  397. package/dist/modes/interactive/components/custom-message.d.ts.map +1 -1
  398. package/dist/modes/interactive/components/custom-message.js +9 -2
  399. package/dist/modes/interactive/components/custom-message.js.map +1 -1
  400. package/dist/modes/interactive/components/extension-editor.d.ts +1 -2
  401. package/dist/modes/interactive/components/extension-editor.d.ts.map +1 -1
  402. package/dist/modes/interactive/components/extension-editor.js +16 -46
  403. package/dist/modes/interactive/components/extension-editor.js.map +1 -1
  404. package/dist/modes/interactive/components/extension-selector.d.ts +49 -0
  405. package/dist/modes/interactive/components/extension-selector.d.ts.map +1 -1
  406. package/dist/modes/interactive/components/extension-selector.js +202 -5
  407. package/dist/modes/interactive/components/extension-selector.js.map +1 -1
  408. package/dist/modes/interactive/components/footer.d.ts.map +1 -1
  409. package/dist/modes/interactive/components/footer.js +24 -23
  410. package/dist/modes/interactive/components/footer.js.map +1 -1
  411. package/dist/modes/interactive/components/login-dialog.d.ts +5 -5
  412. package/dist/modes/interactive/components/login-dialog.d.ts.map +1 -1
  413. package/dist/modes/interactive/components/login-dialog.js +17 -8
  414. package/dist/modes/interactive/components/login-dialog.js.map +1 -1
  415. package/dist/modes/interactive/components/model-selector.d.ts +11 -4
  416. package/dist/modes/interactive/components/model-selector.d.ts.map +1 -1
  417. package/dist/modes/interactive/components/model-selector.js +74 -41
  418. package/dist/modes/interactive/components/model-selector.js.map +1 -1
  419. package/dist/modes/interactive/components/oauth-selector.d.ts +4 -4
  420. package/dist/modes/interactive/components/oauth-selector.d.ts.map +1 -1
  421. package/dist/modes/interactive/components/oauth-selector.js +14 -25
  422. package/dist/modes/interactive/components/oauth-selector.js.map +1 -1
  423. package/dist/modes/interactive/components/scoped-models-selector.d.ts.map +1 -1
  424. package/dist/modes/interactive/components/scoped-models-selector.js +22 -13
  425. package/dist/modes/interactive/components/scoped-models-selector.js.map +1 -1
  426. package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
  427. package/dist/modes/interactive/components/session-selector.js +10 -2
  428. package/dist/modes/interactive/components/session-selector.js.map +1 -1
  429. package/dist/modes/interactive/components/settings-selector.d.ts +2 -0
  430. package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
  431. package/dist/modes/interactive/components/settings-selector.js +10 -0
  432. package/dist/modes/interactive/components/settings-selector.js.map +1 -1
  433. package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
  434. package/dist/modes/interactive/components/tool-execution.js +10 -1
  435. package/dist/modes/interactive/components/tool-execution.js.map +1 -1
  436. package/dist/modes/interactive/components/tree-selector.d.ts +25 -2
  437. package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
  438. package/dist/modes/interactive/components/tree-selector.js +68 -17
  439. package/dist/modes/interactive/components/tree-selector.js.map +1 -1
  440. package/dist/modes/interactive/external-editor.d.ts +12 -0
  441. package/dist/modes/interactive/external-editor.d.ts.map +1 -0
  442. package/dist/modes/interactive/external-editor.js +37 -0
  443. package/dist/modes/interactive/external-editor.js.map +1 -0
  444. package/dist/modes/interactive/interactive-mode.d.ts +107 -10
  445. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  446. package/dist/modes/interactive/interactive-mode.js +763 -285
  447. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  448. package/dist/modes/rpc/rpc-client.d.ts +4 -0
  449. package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
  450. package/dist/modes/rpc/rpc-client.js +7 -0
  451. package/dist/modes/rpc/rpc-client.js.map +1 -1
  452. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  453. package/dist/modes/rpc/rpc-mode.js +185 -9
  454. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  455. package/dist/modes/rpc/rpc-types.d.ts +79 -1
  456. package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
  457. package/dist/modes/rpc/rpc-types.js.map +1 -1
  458. package/dist/package-manager-cli.d.ts.map +1 -1
  459. package/dist/package-manager-cli.js +67 -5
  460. package/dist/package-manager-cli.js.map +1 -1
  461. package/dist/prompts/commands/atomic-commit.md +1 -12
  462. package/dist/prompts/commands/brainstorm.md +12 -15
  463. package/dist/prompts/commands/create-verification-skill.md +108 -0
  464. package/dist/prompts/commands/discuss-phase.md +3 -14
  465. package/dist/prompts/commands/execute-phase.md +3 -11
  466. package/dist/prompts/commands/fix.md +41 -18
  467. package/dist/prompts/commands/grill.md +66 -0
  468. package/dist/prompts/commands/init-project.md +5 -15
  469. package/dist/prompts/commands/map-codebase.md +1 -13
  470. package/dist/prompts/commands/new-project.md +5 -15
  471. package/dist/prompts/commands/next-milestone.md +1 -13
  472. package/dist/prompts/commands/orchestrate.md +1 -1
  473. package/dist/prompts/commands/pause-work.md +1 -13
  474. package/dist/prompts/commands/plan-phase.md +2 -11
  475. package/dist/prompts/commands/progress.md +0 -13
  476. package/dist/prompts/commands/quick.md +3 -11
  477. package/dist/prompts/commands/resolve-conflicts.md +71 -0
  478. package/dist/prompts/commands/resume-work.md +0 -13
  479. package/dist/prompts/commands/review.md +4 -13
  480. package/dist/prompts/commands/triage.md +159 -0
  481. package/dist/prompts/commands/verify-work.md +4 -14
  482. package/dist/prompts/commands/why.md +135 -0
  483. package/dist/skills/atomic-reasoning/SKILL.md +115 -0
  484. package/dist/skills/blast-radius/SKILL.md +55 -0
  485. package/dist/skills/epistemics/SKILL.md +99 -0
  486. package/dist/skills/hexagon-animation/SKILL.md +49 -0
  487. package/dist/skills/hexagon-animation/generate.mjs +81 -0
  488. package/dist/skills/hexagon-animation/template.html +361 -0
  489. package/dist/skills/typescript-discipline/SKILL.md +50 -0
  490. package/dist/skills/typescript-discipline/references/patterns.md +294 -0
  491. package/dist/skills/unslop/SKILL.md +101 -0
  492. package/dist/utils/canonical-path.d.ts +28 -0
  493. package/dist/utils/canonical-path.d.ts.map +1 -0
  494. package/dist/utils/canonical-path.js +90 -0
  495. package/dist/utils/canonical-path.js.map +1 -0
  496. package/dist/utils/child-process.d.ts +12 -1
  497. package/dist/utils/child-process.d.ts.map +1 -1
  498. package/dist/utils/child-process.js +25 -8
  499. package/dist/utils/child-process.js.map +1 -1
  500. package/dist/utils/clipboard-native.d.ts +1 -0
  501. package/dist/utils/clipboard-native.d.ts.map +1 -1
  502. package/dist/utils/clipboard-native.js.map +1 -1
  503. package/dist/utils/clipboard.d.ts +2 -0
  504. package/dist/utils/clipboard.d.ts.map +1 -1
  505. package/dist/utils/clipboard.js +53 -9
  506. package/dist/utils/clipboard.js.map +1 -1
  507. package/dist/utils/exif-orientation.d.ts.map +1 -1
  508. package/dist/utils/exif-orientation.js +2 -3
  509. package/dist/utils/exif-orientation.js.map +1 -1
  510. package/dist/utils/paths.d.ts +2 -7
  511. package/dist/utils/paths.d.ts.map +1 -1
  512. package/dist/utils/paths.js +13 -15
  513. package/dist/utils/paths.js.map +1 -1
  514. package/dist/utils/shell.d.ts.map +1 -1
  515. package/dist/utils/shell.js +6 -4
  516. package/dist/utils/shell.js.map +1 -1
  517. package/dist/utils/tools-manager.d.ts.map +1 -1
  518. package/dist/utils/tools-manager.js +3 -5
  519. package/dist/utils/tools-manager.js.map +1 -1
  520. package/dist/utils/version-check.d.ts.map +1 -1
  521. package/dist/utils/version-check.js +3 -1
  522. package/dist/utils/version-check.js.map +1 -1
  523. package/docs/attachable-sessions.md +79 -0
  524. package/docs/compaction.md +29 -24
  525. package/docs/containerization.md +23 -23
  526. package/docs/custom-provider.md +66 -32
  527. package/docs/development.md +9 -9
  528. package/docs/docs.json +6 -2
  529. package/docs/duet.md +42 -0
  530. package/docs/environment-variables.md +88 -0
  531. package/docs/extensions.md +278 -65
  532. package/docs/index.md +12 -10
  533. package/docs/json.md +12 -8
  534. package/docs/keybindings.md +8 -5
  535. package/docs/llama-cpp.md +99 -0
  536. package/docs/models.md +19 -8
  537. package/docs/packages.md +43 -42
  538. package/docs/prompt-templates.md +5 -4
  539. package/docs/providers.md +45 -11
  540. package/docs/quickstart.md +33 -33
  541. package/docs/rpc.md +190 -19
  542. package/docs/sdk.md +18 -15
  543. package/docs/security.md +18 -18
  544. package/docs/session-format.md +53 -15
  545. package/docs/sessions.md +17 -14
  546. package/docs/settings.md +26 -19
  547. package/docs/shell-aliases.md +2 -2
  548. package/docs/skills.md +12 -11
  549. package/docs/terminal-setup.md +12 -12
  550. package/docs/termux.md +6 -6
  551. package/docs/themes.md +11 -11
  552. package/docs/tmux.md +4 -4
  553. package/docs/tui.md +46 -31
  554. package/docs/usage.md +53 -63
  555. package/docs/windows.md +2 -2
  556. package/examples/extensions/custom-compaction.ts +4 -0
  557. package/examples/extensions/custom-provider-anthropic/index.ts +9 -3
  558. package/examples/extensions/custom-provider-anthropic/package.json +1 -1
  559. package/examples/extensions/custom-provider-gitlab-duo/package.json +1 -1
  560. package/examples/extensions/custom-provider-qwen-cli/package.json +1 -1
  561. package/examples/extensions/gondolin/package.json +2 -2
  562. package/examples/extensions/handoff.ts +9 -1
  563. package/examples/extensions/kimi-deferred-tools.ts +61 -0
  564. package/examples/extensions/message-renderer.ts +2 -2
  565. package/examples/extensions/overlay-qa-tests.ts +3 -3
  566. package/examples/extensions/sandbox/package.json +1 -1
  567. package/examples/extensions/summarize.ts +3 -0
  568. package/examples/extensions/with-deps/package.json +1 -1
  569. package/examples/sdk/02-custom-model.ts +5 -8
  570. package/examples/sdk/09-api-keys-and-oauth.ts +15 -31
  571. package/examples/sdk/12-full-control.ts +9 -12
  572. package/hooks/gsd/draht-quality-gate.js +3 -3
  573. package/package.json +14 -11
  574. package/prompts/commands/atomic-commit.md +1 -12
  575. package/prompts/commands/brainstorm.md +12 -15
  576. package/prompts/commands/create-verification-skill.md +108 -0
  577. package/prompts/commands/discuss-phase.md +3 -14
  578. package/prompts/commands/execute-phase.md +3 -11
  579. package/prompts/commands/fix.md +41 -18
  580. package/prompts/commands/grill.md +66 -0
  581. package/prompts/commands/init-project.md +5 -15
  582. package/prompts/commands/map-codebase.md +1 -13
  583. package/prompts/commands/new-project.md +5 -15
  584. package/prompts/commands/next-milestone.md +1 -13
  585. package/prompts/commands/orchestrate.md +1 -1
  586. package/prompts/commands/pause-work.md +1 -13
  587. package/prompts/commands/plan-phase.md +2 -11
  588. package/prompts/commands/progress.md +0 -13
  589. package/prompts/commands/quick.md +3 -11
  590. package/prompts/commands/resolve-conflicts.md +71 -0
  591. package/prompts/commands/resume-work.md +0 -13
  592. package/prompts/commands/review.md +4 -13
  593. package/prompts/commands/triage.md +159 -0
  594. package/prompts/commands/verify-work.md +4 -14
  595. package/prompts/commands/why.md +135 -0
  596. package/skills/atomic-reasoning/SKILL.md +115 -0
  597. package/skills/blast-radius/SKILL.md +55 -0
  598. package/skills/epistemics/SKILL.md +99 -0
  599. package/skills/hexagon-animation/SKILL.md +49 -0
  600. package/skills/hexagon-animation/generate.mjs +81 -0
  601. package/skills/hexagon-animation/template.html +361 -0
  602. package/skills/typescript-discipline/SKILL.md +50 -0
  603. package/skills/typescript-discipline/references/patterns.md +294 -0
  604. package/skills/unslop/SKILL.md +101 -0
  605. package/dist/core/provider-display-names.d.ts +0 -2
  606. package/dist/core/provider-display-names.d.ts.map +0 -1
  607. package/dist/core/provider-display-names.js +0 -36
  608. package/dist/core/provider-display-names.js.map +0 -1
  609. package/dist/prompts/agents/build.md +0 -86
  610. package/dist/prompts/agents/plan.md +0 -79
  611. package/dist/prompts/agents/verify.md +0 -69
  612. package/prompts/agents/build.md +0 -86
  613. package/prompts/agents/plan.md +0 -79
  614. package/prompts/agents/verify.md +0 -69
@@ -0,0 +1,142 @@
1
+ /**
2
+ * `SandboxPolicy` v1 (R44-SBX.2) and its resolution (R44-SBX.3).
3
+ *
4
+ * The policy is a **plain declarative value**: a resolved write allowlist, a
5
+ * read mode, a network toggle, and a privilege-escalation invariant. Backends
6
+ * translate it into an SBPL profile / a Landlock ruleset; they do not extend it.
7
+ * Keeping it plain is what makes it reviewable, serialisable, diffable and
8
+ * testable independently of any platform.
9
+ *
10
+ * v1 shape, deliberately small (see
11
+ * `.planning/specs/2026-07-12-bash-sandbox-confinement.md`):
12
+ *
13
+ * - **Write allowlist** -- project cwd, session scratch dir, OS temp,
14
+ * `extraWritePaths` from settings, plus a curated set of cache roots that dev
15
+ * toolchains write to outside the project. Everything else is read-only.
16
+ * - **Read** -- allow-all. Dev workflows read toolchains, caches and dotfiles
17
+ * constantly; a read-deny list is a v2 concern and must not block v1.
18
+ * - **Network** -- one on/off toggle, default **on** (`npm install`, `git fetch`).
19
+ * - **Privilege escalation** -- not representable. `allowPrivilegeEscalation` is
20
+ * the literal `false`, not a boolean, so no caller can widen it and every
21
+ * backend must render a profile in which `sudo` cannot work by construction.
22
+ *
23
+ * ## Resolution rules
24
+ *
25
+ * Every path is real-path resolved *before* it lands in the policy (see
26
+ * `real-path.ts` for why). The two classes of input are treated differently on
27
+ * failure, and the difference is deliberate:
28
+ *
29
+ * - **Agent-supplied paths** (`cwd`, `sessionScratchDir`, `tmpDir`) that cannot
30
+ * be resolved throw `SandboxPolicyError`. A session whose own working
31
+ * directory does not resolve is broken; backends catch this and report
32
+ * `unavailable`, which is the fail-closed outcome.
33
+ * - **User-configured paths** (`extraWritePaths`) that cannot be resolved are
34
+ * dropped and reported in `rejected`. Dropping narrows the writable set, so it
35
+ * is safe; it is never silent, so it is debuggable.
36
+ *
37
+ * ## Excluded roots: the exclusions apply to *every* entry, cwd included
38
+ *
39
+ * The curated cache roots below deliberately exclude `~` itself. That exclusion
40
+ * used to be trivially defeated: `cwd` was pushed into the allowlist with no
41
+ * check at all, so running the agent from `$HOME` (or `/Users`, or macOS's
42
+ * `/System/Volumes/Data`) produced a policy whose allowlist *was* the home
43
+ * directory -- silently, with no `rejected` entry, and reported `available`. A
44
+ * sandbox whose allowlist is `$HOME` confines nothing, and the user had no way
45
+ * to know.
46
+ *
47
+ * So `excludedWriteRootReason` is applied uniformly, and the two input classes
48
+ * keep their documented failure modes: an excluded **agent-supplied** path
49
+ * throws, an excluded **configured** path lands in `rejected` and is surfaced.
50
+ * The check is not purely lexical -- `/System/Volumes/Data/Users/alice` is
51
+ * `realpath`-stable on macOS yet is the same directory as `/Users/alice`, so
52
+ * candidates are also compared to the home directory and its ancestors by
53
+ * device+inode identity.
54
+ */
55
+ export declare const SANDBOX_POLICY_VERSION = 1;
56
+ export type SandboxNetworkMode = "on" | "off";
57
+ /** Resolved, declarative sandbox policy. Frozen: backends read it, never edit it. */
58
+ export interface SandboxPolicy {
59
+ readonly version: typeof SANDBOX_POLICY_VERSION;
60
+ /**
61
+ * Absolute, real-path resolved, deduplicated, minimal (no entry nested under
62
+ * another) and sorted. The sort makes generated profiles byte-stable, which
63
+ * matters for profile caching and for diffing what a session was allowed to do.
64
+ */
65
+ readonly writePaths: readonly string[];
66
+ /** v1 is read allow-all. A union so v2 can add modes without changing the field. */
67
+ readonly read: "allow-all";
68
+ readonly network: SandboxNetworkMode;
69
+ /**
70
+ * Always `false`, and typed as the literal so it cannot be set otherwise.
71
+ * Backends must render a profile where privilege escalation is impossible,
72
+ * and the R44-SBX.4 self-test probes it before any backend reports
73
+ * `available` (see `self-test.ts`).
74
+ */
75
+ readonly allowPrivilegeEscalation: false;
76
+ }
77
+ export interface SandboxPolicyInput {
78
+ /** Project working directory. Must exist, resolve, and not be an excluded root. */
79
+ cwd: string;
80
+ /** The session's scratch directory, when it has one. */
81
+ sessionScratchDir?: string;
82
+ /** OS temp dir. Defaults to `os.tmpdir()`; overridable for tests. */
83
+ tmpDir?: string;
84
+ /** Additional writable roots from settings / `permissions.yml`. */
85
+ extraWritePaths?: readonly string[];
86
+ /** Include the curated cache roots below. Defaults to `true`. */
87
+ includeDefaultCacheRoots?: boolean;
88
+ /** Home directory used to expand cache roots and to compute exclusions. Defaults to `os.homedir()`. */
89
+ homeDir?: string;
90
+ /** Defaults to `"on"`. */
91
+ network?: SandboxNetworkMode;
92
+ /** Platform the exclusion list is curated for. Defaults to `process.platform`. */
93
+ platform?: NodeJS.Platform;
94
+ }
95
+ export interface RejectedWritePath {
96
+ /** The entry exactly as configured, so the user can find it in their settings. */
97
+ readonly input: string;
98
+ readonly reason: string;
99
+ }
100
+ export interface SandboxPolicyResolution {
101
+ readonly policy: SandboxPolicy;
102
+ /**
103
+ * Configured write paths that were dropped. Never empty-but-ignored: surfacing
104
+ * these is what keeps "we narrowed your policy" from being a silent behaviour.
105
+ */
106
+ readonly rejected: readonly RejectedWritePath[];
107
+ }
108
+ /** Thrown when an agent-supplied policy path cannot be resolved or is an excluded root (see module doc). */
109
+ export declare class SandboxPolicyError extends Error {
110
+ constructor(message: string);
111
+ }
112
+ /**
113
+ * Why `path` must not enter the write allowlist, or `null` when it may.
114
+ *
115
+ * `path` must already be real-path resolved. The reason is a sentence fragment
116
+ * that reads after "refusing ...: <reason>".
117
+ */
118
+ export declare function excludedWriteRootReason(path: string, home: string | undefined, platform: NodeJS.Platform): string | null;
119
+ /**
120
+ * Builds a v1 policy from `input`, real-path resolving every path first.
121
+ *
122
+ * Throws `SandboxPolicyError` when an agent-supplied path cannot be resolved or
123
+ * is an excluded root; drops unresolvable or excluded `extraWritePaths` into
124
+ * `rejected`.
125
+ */
126
+ export declare function resolveSandboxPolicy(input: SandboxPolicyInput): SandboxPolicyResolution;
127
+ /**
128
+ * Whether `policy` permits writing to `candidate`.
129
+ *
130
+ * Resolves `candidate` to a real path first -- a lexical `startsWith` against
131
+ * `writePaths` is exactly the bug this exists to prevent, since a symlink or a
132
+ * `..` hop makes an in-project-looking string name a file outside the project.
133
+ * Use this anywhere an in-process pre-check is needed; the kernel backend
134
+ * remains the enforcement boundary, this mirrors it.
135
+ *
136
+ * `candidate` must be absolute unless a `base` is given. Anything unresolvable
137
+ * answers `false` -- an undecidable path is not a writable one.
138
+ */
139
+ export declare function isPathWritable(policy: SandboxPolicy, candidate: string, options?: {
140
+ base?: string;
141
+ }): boolean;
142
+ //# sourceMappingURL=policy.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAOH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,KAAK,CAAC;AAE9C,qFAAqF;AACrF,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,sBAAsB,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,wBAAwB,EAAE,KAAK,CAAC;CACzC;AAED,MAAM,WAAW,kBAAkB;IAClC,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IACZ,wDAAwD;IACxD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,iEAAiE;IACjE,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,uGAAuG;IACvG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IACjC,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAChD;AAED,4GAA4G;AAC5G,qBAAa,kBAAmB,SAAQ,KAAK;IAC5C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACD;AAkGD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACtC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,QAAQ,EAAE,MAAM,CAAC,QAAQ,GACvB,MAAM,GAAG,IAAI,CAoBf;AAsBD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,uBAAuB,CAkEvF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAK7G"}
@@ -0,0 +1,297 @@
1
+ /**
2
+ * `SandboxPolicy` v1 (R44-SBX.2) and its resolution (R44-SBX.3).
3
+ *
4
+ * The policy is a **plain declarative value**: a resolved write allowlist, a
5
+ * read mode, a network toggle, and a privilege-escalation invariant. Backends
6
+ * translate it into an SBPL profile / a Landlock ruleset; they do not extend it.
7
+ * Keeping it plain is what makes it reviewable, serialisable, diffable and
8
+ * testable independently of any platform.
9
+ *
10
+ * v1 shape, deliberately small (see
11
+ * `.planning/specs/2026-07-12-bash-sandbox-confinement.md`):
12
+ *
13
+ * - **Write allowlist** -- project cwd, session scratch dir, OS temp,
14
+ * `extraWritePaths` from settings, plus a curated set of cache roots that dev
15
+ * toolchains write to outside the project. Everything else is read-only.
16
+ * - **Read** -- allow-all. Dev workflows read toolchains, caches and dotfiles
17
+ * constantly; a read-deny list is a v2 concern and must not block v1.
18
+ * - **Network** -- one on/off toggle, default **on** (`npm install`, `git fetch`).
19
+ * - **Privilege escalation** -- not representable. `allowPrivilegeEscalation` is
20
+ * the literal `false`, not a boolean, so no caller can widen it and every
21
+ * backend must render a profile in which `sudo` cannot work by construction.
22
+ *
23
+ * ## Resolution rules
24
+ *
25
+ * Every path is real-path resolved *before* it lands in the policy (see
26
+ * `real-path.ts` for why). The two classes of input are treated differently on
27
+ * failure, and the difference is deliberate:
28
+ *
29
+ * - **Agent-supplied paths** (`cwd`, `sessionScratchDir`, `tmpDir`) that cannot
30
+ * be resolved throw `SandboxPolicyError`. A session whose own working
31
+ * directory does not resolve is broken; backends catch this and report
32
+ * `unavailable`, which is the fail-closed outcome.
33
+ * - **User-configured paths** (`extraWritePaths`) that cannot be resolved are
34
+ * dropped and reported in `rejected`. Dropping narrows the writable set, so it
35
+ * is safe; it is never silent, so it is debuggable.
36
+ *
37
+ * ## Excluded roots: the exclusions apply to *every* entry, cwd included
38
+ *
39
+ * The curated cache roots below deliberately exclude `~` itself. That exclusion
40
+ * used to be trivially defeated: `cwd` was pushed into the allowlist with no
41
+ * check at all, so running the agent from `$HOME` (or `/Users`, or macOS's
42
+ * `/System/Volumes/Data`) produced a policy whose allowlist *was* the home
43
+ * directory -- silently, with no `rejected` entry, and reported `available`. A
44
+ * sandbox whose allowlist is `$HOME` confines nothing, and the user had no way
45
+ * to know.
46
+ *
47
+ * So `excludedWriteRootReason` is applied uniformly, and the two input classes
48
+ * keep their documented failure modes: an excluded **agent-supplied** path
49
+ * throws, an excluded **configured** path lands in `rejected` and is surfaced.
50
+ * The check is not purely lexical -- `/System/Volumes/Data/Users/alice` is
51
+ * `realpath`-stable on macOS yet is the same directory as `/Users/alice`, so
52
+ * candidates are also compared to the home directory and its ancestors by
53
+ * device+inode identity.
54
+ */
55
+ import { statSync } from "node:fs";
56
+ import { homedir, tmpdir } from "node:os";
57
+ import { dirname, isAbsolute, join } from "node:path";
58
+ import { isContainedIn, resolveRealPath } from "./real-path.js";
59
+ export const SANDBOX_POLICY_VERSION = 1;
60
+ /** Thrown when an agent-supplied policy path cannot be resolved or is an excluded root (see module doc). */
61
+ export class SandboxPolicyError extends Error {
62
+ constructor(message) {
63
+ super(message);
64
+ this.name = "SandboxPolicyError";
65
+ }
66
+ }
67
+ /**
68
+ * Cache roots dev toolchains write to outside the project.
69
+ *
70
+ * The bar an entry has to clear is **not** "regenerable". Every package cache is
71
+ * regenerable, and every package cache also holds code that a later,
72
+ * *unsandboxed* `npm install` / `cargo build` / `npx` links into a tree and
73
+ * runs. Granting one of those is a persistence route straight out of the
74
+ * sandbox, so the bar is:
75
+ *
76
+ * > tampering with an entry must be **detected**, or the entry must be
77
+ * > unreachable by a later lookup, by a mechanism that is on **by default**.
78
+ *
79
+ * What that leaves, and why:
80
+ *
81
+ * | root | why it stays |
82
+ * |--------------------------|------------------------------------------------------------------------------------|
83
+ * | `~/.npm/_cacache` | content-addressed; npm verifies the SRI hash from the lockfile on read, and a mismatch is a cache miss, so a planted blob is unreachable |
84
+ * | `~/.npm/_logs` | plain-text run logs, no code, and npm writes them on every command |
85
+ * | `~/.pnpm-store` | content-addressable store keyed by file hash; `verify-store-integrity` is on by default |
86
+ * | `~/.yarn/berry/cache` | zips checksummed against `yarn.lock`; `checksumBehavior` defaults to `throw` |
87
+ * | `~/.cargo/registry` | `.cargo-checksum.json` is verified on use; a modified crate source is a hard error |
88
+ *
89
+ * Removed in the Phase 44 review, and why each one is a persistence route rather
90
+ * than a cache:
91
+ *
92
+ * - `~/.cache` and `$XDG_CACHE_HOME` -- an unowned catch-all. Playwright browser
93
+ * binaries, pre-commit hook virtualenvs and toolchains installed by `uv` /
94
+ * bazelisk live under it and are executed directly by the next unsandboxed run.
95
+ * - `~/Library/Caches` (macOS) -- same, and worse: Sparkle-style auto-updaters
96
+ * stage the installer they will later launch under `~/Library/Caches/<bundle-id>/`,
97
+ * and Homebrew caches downloaded bottles and `.pkg` installers there.
98
+ * - `~/.npm` as a whole -- narrowed to the two subtrees above because
99
+ * `~/.npm/_npx` holds fully installed package trees that `npx` executes
100
+ * verbatim, with no integrity check at run time.
101
+ * - `~/.bun/install/cache` -- keyed by name@version and hard-linked into
102
+ * `node_modules`; there is no default re-verification step to point at.
103
+ * - `~/.yarn/cache` -- yarn classic's cache does not live here anyway (it is
104
+ * under the XDG / `~/Library/Caches` roots that are now excluded).
105
+ * - `~/.cargo/git` -- git checkouts of dependencies carry no checksum file, and a
106
+ * planted `build.rs` runs at the next unsandboxed `cargo build`.
107
+ * - `~/go/pkg/mod` -- `go.sum` is verified when the module zip is *downloaded*,
108
+ * not when the already-extracted tree is compiled.
109
+ * - `~/.gradle/caches` and `~/.m2/repository` -- jars and compiled build scripts
110
+ * executed by the next unsandboxed `gradle` / `mvn`; dependency verification is
111
+ * opt-in in Gradle and warn-only by default in Maven.
112
+ *
113
+ * Nothing here is a parent of user documents, credentials or shell config, and
114
+ * `~` itself, `~/.config`, `~/.local` and `~/.ssh` remain absent -- see
115
+ * `excludedWriteRootReason`, which now enforces that rather than trusting this
116
+ * list to be the only way in. The long tail is handled by `extraWritePaths` and
117
+ * (Phase 45) the rerun-unsandboxed escalation prompt, not by growing this list.
118
+ */
119
+ function defaultCacheRoots(home) {
120
+ return [
121
+ join(home, ".npm", "_cacache"),
122
+ join(home, ".npm", "_logs"),
123
+ join(home, ".pnpm-store"),
124
+ join(home, ".yarn", "berry", "cache"),
125
+ join(home, ".cargo", "registry"),
126
+ ];
127
+ }
128
+ /**
129
+ * Directories that alias the whole filesystem under another spelling, so that
130
+ * granting one is granting `/`. macOS mounts the data volume at
131
+ * `/System/Volumes/Data` and firmlinks it into `/`, and `realpath` keeps both
132
+ * spellings, so a string comparison against `/` does not see it.
133
+ */
134
+ const SYSTEM_VOLUME_ROOTS = {
135
+ darwin: ["/System/Volumes/Data"],
136
+ };
137
+ /** Device+inode identity, so firmlinks and bind mounts cannot spell their way past a string check. */
138
+ function isSameDirectory(a, b) {
139
+ try {
140
+ const left = statSync(a);
141
+ const right = statSync(b);
142
+ return left.dev === right.dev && left.ino === right.ino;
143
+ }
144
+ catch {
145
+ // A path that cannot be stat'ed is not the home directory under another name.
146
+ return false;
147
+ }
148
+ }
149
+ /** `path` and every directory above it, ending at the filesystem root. */
150
+ function selfAndAncestors(path) {
151
+ const out = [];
152
+ let cursor = path;
153
+ for (;;) {
154
+ out.push(cursor);
155
+ const parent = dirname(cursor);
156
+ if (parent === cursor)
157
+ return out;
158
+ cursor = parent;
159
+ }
160
+ }
161
+ /**
162
+ * Why `path` must not enter the write allowlist, or `null` when it may.
163
+ *
164
+ * `path` must already be real-path resolved. The reason is a sentence fragment
165
+ * that reads after "refusing ...: <reason>".
166
+ */
167
+ export function excludedWriteRootReason(path, home, platform) {
168
+ if (path === "/")
169
+ return "it is the filesystem root, so the allowlist would not be an allowlist";
170
+ for (const root of SYSTEM_VOLUME_ROOTS[platform] ?? []) {
171
+ if (isContainedIn(root, path)) {
172
+ return `it is ${JSON.stringify(root)} or an ancestor of it, which aliases the entire filesystem`;
173
+ }
174
+ }
175
+ if (home === undefined || home === "")
176
+ return null;
177
+ if (path === home)
178
+ return "it is the home directory, which would make every dotfile, key and credential writable";
179
+ if (isContainedIn(home, path)) {
180
+ return `it contains the home directory ${JSON.stringify(home)}, which would make every dotfile, key and credential writable`;
181
+ }
182
+ for (const ancestor of selfAndAncestors(home)) {
183
+ if (isSameDirectory(path, ancestor)) {
184
+ return ancestor === home
185
+ ? `it is the home directory ${JSON.stringify(home)} reached by another spelling`
186
+ : `it is ${JSON.stringify(ancestor)} reached by another spelling, and that contains the home directory`;
187
+ }
188
+ }
189
+ return null;
190
+ }
191
+ function rejectionFor(result) {
192
+ return { input: result.input, reason: result.reason };
193
+ }
194
+ /**
195
+ * Deduplicates, drops entries already covered by another entry, and sorts.
196
+ *
197
+ * Sorting ascending puts every ancestor before its descendants (an ancestor is a
198
+ * proper string prefix), so a single forward pass is enough to collapse nesting.
199
+ */
200
+ function normalizeWriteSet(paths) {
201
+ const unique = [...new Set(paths)].sort();
202
+ const minimal = [];
203
+ for (const path of unique) {
204
+ if (minimal.some((existing) => isContainedIn(path, existing)))
205
+ continue;
206
+ minimal.push(path);
207
+ }
208
+ return minimal;
209
+ }
210
+ /**
211
+ * Builds a v1 policy from `input`, real-path resolving every path first.
212
+ *
213
+ * Throws `SandboxPolicyError` when an agent-supplied path cannot be resolved or
214
+ * is an excluded root; drops unresolvable or excluded `extraWritePaths` into
215
+ * `rejected`.
216
+ */
217
+ export function resolveSandboxPolicy(input) {
218
+ const platform = input.platform ?? process.platform;
219
+ // Resolved so the comparison happens between real paths; an unresolvable home
220
+ // still participates as a plain string rather than disabling the exclusion.
221
+ const configuredHome = input.homeDir ?? homedir();
222
+ const resolvedHome = configuredHome ? resolveRealPath(configuredHome, { base: "/" }) : undefined;
223
+ const home = resolvedHome?.ok ? resolvedHome.path : configuredHome || undefined;
224
+ /** Agent-supplied path: unresolvable or excluded is fatal, never silent. */
225
+ const requireAllowedRoot = (label, entry, base) => {
226
+ const result = resolveRealPath(entry, { base });
227
+ if (!result.ok) {
228
+ throw new SandboxPolicyError(`cannot build a sandbox policy: ${label} ${result.reason}`);
229
+ }
230
+ const excluded = excludedWriteRootReason(result.path, home, platform);
231
+ if (excluded) {
232
+ throw new SandboxPolicyError(`cannot build a sandbox policy: refusing to put ${label} ${JSON.stringify(result.path)} in the write allowlist because ${excluded}. Run from a project directory, or grant the specific subtrees you need with extraWritePaths.`);
233
+ }
234
+ return result.path;
235
+ };
236
+ const cwd = requireAllowedRoot("the project cwd", input.cwd, process.cwd());
237
+ const rejected = [];
238
+ const writePaths = [cwd];
239
+ writePaths.push(requireAllowedRoot("the OS temp dir", input.tmpDir ?? tmpdir(), cwd));
240
+ if (input.sessionScratchDir !== undefined) {
241
+ writePaths.push(requireAllowedRoot("the session scratch dir", input.sessionScratchDir, cwd));
242
+ }
243
+ const configured = [...(input.extraWritePaths ?? [])];
244
+ if (input.includeDefaultCacheRoots ?? true) {
245
+ // No home dir means no cache roots -- there is nothing to expand them against,
246
+ // and the fail-closed answer is a narrower policy, not a guessed one.
247
+ if (home)
248
+ configured.push(...defaultCacheRoots(home));
249
+ }
250
+ for (const entry of configured) {
251
+ const result = resolveRealPath(entry, { base: cwd });
252
+ if (!result.ok) {
253
+ rejected.push(rejectionFor(result));
254
+ continue;
255
+ }
256
+ const excluded = excludedWriteRootReason(result.path, home, platform);
257
+ if (excluded) {
258
+ // Configured input: narrow the policy and say so. Silently accepting this
259
+ // is what made the exclusions above decorative.
260
+ rejected.push({
261
+ input: entry,
262
+ reason: `refusing to add ${JSON.stringify(result.path)} to the write allowlist because ${excluded}`,
263
+ });
264
+ continue;
265
+ }
266
+ writePaths.push(result.path);
267
+ }
268
+ const policy = Object.freeze({
269
+ version: SANDBOX_POLICY_VERSION,
270
+ writePaths: Object.freeze(normalizeWriteSet(writePaths)),
271
+ read: "allow-all",
272
+ network: input.network ?? "on",
273
+ allowPrivilegeEscalation: false,
274
+ });
275
+ return { policy, rejected };
276
+ }
277
+ /**
278
+ * Whether `policy` permits writing to `candidate`.
279
+ *
280
+ * Resolves `candidate` to a real path first -- a lexical `startsWith` against
281
+ * `writePaths` is exactly the bug this exists to prevent, since a symlink or a
282
+ * `..` hop makes an in-project-looking string name a file outside the project.
283
+ * Use this anywhere an in-process pre-check is needed; the kernel backend
284
+ * remains the enforcement boundary, this mirrors it.
285
+ *
286
+ * `candidate` must be absolute unless a `base` is given. Anything unresolvable
287
+ * answers `false` -- an undecidable path is not a writable one.
288
+ */
289
+ export function isPathWritable(policy, candidate, options) {
290
+ if (options?.base === undefined && !isAbsolute(candidate))
291
+ return false;
292
+ const result = resolveRealPath(candidate, { base: options?.base ?? candidate });
293
+ if (!result.ok)
294
+ return false;
295
+ return policy.writePaths.some((root) => isContainedIn(result.path, root));
296
+ }
297
+ //# sourceMappingURL=policy.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../src/core/sandbox/policy.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `SandboxPolicy` v1 (R44-SBX.2) and its resolution (R44-SBX.3).\n *\n * The policy is a **plain declarative value**: a resolved write allowlist, a\n * read mode, a network toggle, and a privilege-escalation invariant. Backends\n * translate it into an SBPL profile / a Landlock ruleset; they do not extend it.\n * Keeping it plain is what makes it reviewable, serialisable, diffable and\n * testable independently of any platform.\n *\n * v1 shape, deliberately small (see\n * `.planning/specs/2026-07-12-bash-sandbox-confinement.md`):\n *\n * - **Write allowlist** -- project cwd, session scratch dir, OS temp,\n * `extraWritePaths` from settings, plus a curated set of cache roots that dev\n * toolchains write to outside the project. Everything else is read-only.\n * - **Read** -- allow-all. Dev workflows read toolchains, caches and dotfiles\n * constantly; a read-deny list is a v2 concern and must not block v1.\n * - **Network** -- one on/off toggle, default **on** (`npm install`, `git fetch`).\n * - **Privilege escalation** -- not representable. `allowPrivilegeEscalation` is\n * the literal `false`, not a boolean, so no caller can widen it and every\n * backend must render a profile in which `sudo` cannot work by construction.\n *\n * ## Resolution rules\n *\n * Every path is real-path resolved *before* it lands in the policy (see\n * `real-path.ts` for why). The two classes of input are treated differently on\n * failure, and the difference is deliberate:\n *\n * - **Agent-supplied paths** (`cwd`, `sessionScratchDir`, `tmpDir`) that cannot\n * be resolved throw `SandboxPolicyError`. A session whose own working\n * directory does not resolve is broken; backends catch this and report\n * `unavailable`, which is the fail-closed outcome.\n * - **User-configured paths** (`extraWritePaths`) that cannot be resolved are\n * dropped and reported in `rejected`. Dropping narrows the writable set, so it\n * is safe; it is never silent, so it is debuggable.\n *\n * ## Excluded roots: the exclusions apply to *every* entry, cwd included\n *\n * The curated cache roots below deliberately exclude `~` itself. That exclusion\n * used to be trivially defeated: `cwd` was pushed into the allowlist with no\n * check at all, so running the agent from `$HOME` (or `/Users`, or macOS's\n * `/System/Volumes/Data`) produced a policy whose allowlist *was* the home\n * directory -- silently, with no `rejected` entry, and reported `available`. A\n * sandbox whose allowlist is `$HOME` confines nothing, and the user had no way\n * to know.\n *\n * So `excludedWriteRootReason` is applied uniformly, and the two input classes\n * keep their documented failure modes: an excluded **agent-supplied** path\n * throws, an excluded **configured** path lands in `rejected` and is surfaced.\n * The check is not purely lexical -- `/System/Volumes/Data/Users/alice` is\n * `realpath`-stable on macOS yet is the same directory as `/Users/alice`, so\n * candidates are also compared to the home directory and its ancestors by\n * device+inode identity.\n */\n\nimport { statSync } from \"node:fs\";\nimport { homedir, tmpdir } from \"node:os\";\nimport { dirname, isAbsolute, join } from \"node:path\";\nimport { isContainedIn, type RealPathResolution, resolveRealPath } from \"./real-path.ts\";\n\nexport const SANDBOX_POLICY_VERSION = 1;\n\nexport type SandboxNetworkMode = \"on\" | \"off\";\n\n/** Resolved, declarative sandbox policy. Frozen: backends read it, never edit it. */\nexport interface SandboxPolicy {\n\treadonly version: typeof SANDBOX_POLICY_VERSION;\n\t/**\n\t * Absolute, real-path resolved, deduplicated, minimal (no entry nested under\n\t * another) and sorted. The sort makes generated profiles byte-stable, which\n\t * matters for profile caching and for diffing what a session was allowed to do.\n\t */\n\treadonly writePaths: readonly string[];\n\t/** v1 is read allow-all. A union so v2 can add modes without changing the field. */\n\treadonly read: \"allow-all\";\n\treadonly network: SandboxNetworkMode;\n\t/**\n\t * Always `false`, and typed as the literal so it cannot be set otherwise.\n\t * Backends must render a profile where privilege escalation is impossible,\n\t * and the R44-SBX.4 self-test probes it before any backend reports\n\t * `available` (see `self-test.ts`).\n\t */\n\treadonly allowPrivilegeEscalation: false;\n}\n\nexport interface SandboxPolicyInput {\n\t/** Project working directory. Must exist, resolve, and not be an excluded root. */\n\tcwd: string;\n\t/** The session's scratch directory, when it has one. */\n\tsessionScratchDir?: string;\n\t/** OS temp dir. Defaults to `os.tmpdir()`; overridable for tests. */\n\ttmpDir?: string;\n\t/** Additional writable roots from settings / `permissions.yml`. */\n\textraWritePaths?: readonly string[];\n\t/** Include the curated cache roots below. Defaults to `true`. */\n\tincludeDefaultCacheRoots?: boolean;\n\t/** Home directory used to expand cache roots and to compute exclusions. Defaults to `os.homedir()`. */\n\thomeDir?: string;\n\t/** Defaults to `\"on\"`. */\n\tnetwork?: SandboxNetworkMode;\n\t/** Platform the exclusion list is curated for. Defaults to `process.platform`. */\n\tplatform?: NodeJS.Platform;\n}\n\nexport interface RejectedWritePath {\n\t/** The entry exactly as configured, so the user can find it in their settings. */\n\treadonly input: string;\n\treadonly reason: string;\n}\n\nexport interface SandboxPolicyResolution {\n\treadonly policy: SandboxPolicy;\n\t/**\n\t * Configured write paths that were dropped. Never empty-but-ignored: surfacing\n\t * these is what keeps \"we narrowed your policy\" from being a silent behaviour.\n\t */\n\treadonly rejected: readonly RejectedWritePath[];\n}\n\n/** Thrown when an agent-supplied policy path cannot be resolved or is an excluded root (see module doc). */\nexport class SandboxPolicyError extends Error {\n\tconstructor(message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"SandboxPolicyError\";\n\t}\n}\n\n/**\n * Cache roots dev toolchains write to outside the project.\n *\n * The bar an entry has to clear is **not** \"regenerable\". Every package cache is\n * regenerable, and every package cache also holds code that a later,\n * *unsandboxed* `npm install` / `cargo build` / `npx` links into a tree and\n * runs. Granting one of those is a persistence route straight out of the\n * sandbox, so the bar is:\n *\n * > tampering with an entry must be **detected**, or the entry must be\n * > unreachable by a later lookup, by a mechanism that is on **by default**.\n *\n * What that leaves, and why:\n *\n * | root | why it stays |\n * |--------------------------|------------------------------------------------------------------------------------|\n * | `~/.npm/_cacache` | content-addressed; npm verifies the SRI hash from the lockfile on read, and a mismatch is a cache miss, so a planted blob is unreachable |\n * | `~/.npm/_logs` | plain-text run logs, no code, and npm writes them on every command |\n * | `~/.pnpm-store` | content-addressable store keyed by file hash; `verify-store-integrity` is on by default |\n * | `~/.yarn/berry/cache` | zips checksummed against `yarn.lock`; `checksumBehavior` defaults to `throw` |\n * | `~/.cargo/registry` | `.cargo-checksum.json` is verified on use; a modified crate source is a hard error |\n *\n * Removed in the Phase 44 review, and why each one is a persistence route rather\n * than a cache:\n *\n * - `~/.cache` and `$XDG_CACHE_HOME` -- an unowned catch-all. Playwright browser\n * binaries, pre-commit hook virtualenvs and toolchains installed by `uv` /\n * bazelisk live under it and are executed directly by the next unsandboxed run.\n * - `~/Library/Caches` (macOS) -- same, and worse: Sparkle-style auto-updaters\n * stage the installer they will later launch under `~/Library/Caches/<bundle-id>/`,\n * and Homebrew caches downloaded bottles and `.pkg` installers there.\n * - `~/.npm` as a whole -- narrowed to the two subtrees above because\n * `~/.npm/_npx` holds fully installed package trees that `npx` executes\n * verbatim, with no integrity check at run time.\n * - `~/.bun/install/cache` -- keyed by name@version and hard-linked into\n * `node_modules`; there is no default re-verification step to point at.\n * - `~/.yarn/cache` -- yarn classic's cache does not live here anyway (it is\n * under the XDG / `~/Library/Caches` roots that are now excluded).\n * - `~/.cargo/git` -- git checkouts of dependencies carry no checksum file, and a\n * planted `build.rs` runs at the next unsandboxed `cargo build`.\n * - `~/go/pkg/mod` -- `go.sum` is verified when the module zip is *downloaded*,\n * not when the already-extracted tree is compiled.\n * - `~/.gradle/caches` and `~/.m2/repository` -- jars and compiled build scripts\n * executed by the next unsandboxed `gradle` / `mvn`; dependency verification is\n * opt-in in Gradle and warn-only by default in Maven.\n *\n * Nothing here is a parent of user documents, credentials or shell config, and\n * `~` itself, `~/.config`, `~/.local` and `~/.ssh` remain absent -- see\n * `excludedWriteRootReason`, which now enforces that rather than trusting this\n * list to be the only way in. The long tail is handled by `extraWritePaths` and\n * (Phase 45) the rerun-unsandboxed escalation prompt, not by growing this list.\n */\nfunction defaultCacheRoots(home: string): string[] {\n\treturn [\n\t\tjoin(home, \".npm\", \"_cacache\"),\n\t\tjoin(home, \".npm\", \"_logs\"),\n\t\tjoin(home, \".pnpm-store\"),\n\t\tjoin(home, \".yarn\", \"berry\", \"cache\"),\n\t\tjoin(home, \".cargo\", \"registry\"),\n\t];\n}\n\n/**\n * Directories that alias the whole filesystem under another spelling, so that\n * granting one is granting `/`. macOS mounts the data volume at\n * `/System/Volumes/Data` and firmlinks it into `/`, and `realpath` keeps both\n * spellings, so a string comparison against `/` does not see it.\n */\nconst SYSTEM_VOLUME_ROOTS: Partial<Record<NodeJS.Platform, readonly string[]>> = {\n\tdarwin: [\"/System/Volumes/Data\"],\n};\n\n/** Device+inode identity, so firmlinks and bind mounts cannot spell their way past a string check. */\nfunction isSameDirectory(a: string, b: string): boolean {\n\ttry {\n\t\tconst left = statSync(a);\n\t\tconst right = statSync(b);\n\t\treturn left.dev === right.dev && left.ino === right.ino;\n\t} catch {\n\t\t// A path that cannot be stat'ed is not the home directory under another name.\n\t\treturn false;\n\t}\n}\n\n/** `path` and every directory above it, ending at the filesystem root. */\nfunction selfAndAncestors(path: string): string[] {\n\tconst out: string[] = [];\n\tlet cursor = path;\n\tfor (;;) {\n\t\tout.push(cursor);\n\t\tconst parent = dirname(cursor);\n\t\tif (parent === cursor) return out;\n\t\tcursor = parent;\n\t}\n}\n\n/**\n * Why `path` must not enter the write allowlist, or `null` when it may.\n *\n * `path` must already be real-path resolved. The reason is a sentence fragment\n * that reads after \"refusing ...: <reason>\".\n */\nexport function excludedWriteRootReason(\n\tpath: string,\n\thome: string | undefined,\n\tplatform: NodeJS.Platform,\n): string | null {\n\tif (path === \"/\") return \"it is the filesystem root, so the allowlist would not be an allowlist\";\n\tfor (const root of SYSTEM_VOLUME_ROOTS[platform] ?? []) {\n\t\tif (isContainedIn(root, path)) {\n\t\t\treturn `it is ${JSON.stringify(root)} or an ancestor of it, which aliases the entire filesystem`;\n\t\t}\n\t}\n\tif (home === undefined || home === \"\") return null;\n\tif (path === home) return \"it is the home directory, which would make every dotfile, key and credential writable\";\n\tif (isContainedIn(home, path)) {\n\t\treturn `it contains the home directory ${JSON.stringify(home)}, which would make every dotfile, key and credential writable`;\n\t}\n\tfor (const ancestor of selfAndAncestors(home)) {\n\t\tif (isSameDirectory(path, ancestor)) {\n\t\t\treturn ancestor === home\n\t\t\t\t? `it is the home directory ${JSON.stringify(home)} reached by another spelling`\n\t\t\t\t: `it is ${JSON.stringify(ancestor)} reached by another spelling, and that contains the home directory`;\n\t\t}\n\t}\n\treturn null;\n}\n\nfunction rejectionFor(result: Extract<RealPathResolution, { ok: false }>): RejectedWritePath {\n\treturn { input: result.input, reason: result.reason };\n}\n\n/**\n * Deduplicates, drops entries already covered by another entry, and sorts.\n *\n * Sorting ascending puts every ancestor before its descendants (an ancestor is a\n * proper string prefix), so a single forward pass is enough to collapse nesting.\n */\nfunction normalizeWriteSet(paths: readonly string[]): string[] {\n\tconst unique = [...new Set(paths)].sort();\n\tconst minimal: string[] = [];\n\tfor (const path of unique) {\n\t\tif (minimal.some((existing) => isContainedIn(path, existing))) continue;\n\t\tminimal.push(path);\n\t}\n\treturn minimal;\n}\n\n/**\n * Builds a v1 policy from `input`, real-path resolving every path first.\n *\n * Throws `SandboxPolicyError` when an agent-supplied path cannot be resolved or\n * is an excluded root; drops unresolvable or excluded `extraWritePaths` into\n * `rejected`.\n */\nexport function resolveSandboxPolicy(input: SandboxPolicyInput): SandboxPolicyResolution {\n\tconst platform = input.platform ?? process.platform;\n\t// Resolved so the comparison happens between real paths; an unresolvable home\n\t// still participates as a plain string rather than disabling the exclusion.\n\tconst configuredHome = input.homeDir ?? homedir();\n\tconst resolvedHome = configuredHome ? resolveRealPath(configuredHome, { base: \"/\" }) : undefined;\n\tconst home = resolvedHome?.ok ? resolvedHome.path : configuredHome || undefined;\n\n\t/** Agent-supplied path: unresolvable or excluded is fatal, never silent. */\n\tconst requireAllowedRoot = (label: string, entry: string, base: string): string => {\n\t\tconst result = resolveRealPath(entry, { base });\n\t\tif (!result.ok) {\n\t\t\tthrow new SandboxPolicyError(`cannot build a sandbox policy: ${label} ${result.reason}`);\n\t\t}\n\t\tconst excluded = excludedWriteRootReason(result.path, home, platform);\n\t\tif (excluded) {\n\t\t\tthrow new SandboxPolicyError(\n\t\t\t\t`cannot build a sandbox policy: refusing to put ${label} ${JSON.stringify(result.path)} in the write allowlist because ${excluded}. Run from a project directory, or grant the specific subtrees you need with extraWritePaths.`,\n\t\t\t);\n\t\t}\n\t\treturn result.path;\n\t};\n\n\tconst cwd = requireAllowedRoot(\"the project cwd\", input.cwd, process.cwd());\n\tconst rejected: RejectedWritePath[] = [];\n\tconst writePaths: string[] = [cwd];\n\n\twritePaths.push(requireAllowedRoot(\"the OS temp dir\", input.tmpDir ?? tmpdir(), cwd));\n\tif (input.sessionScratchDir !== undefined) {\n\t\twritePaths.push(requireAllowedRoot(\"the session scratch dir\", input.sessionScratchDir, cwd));\n\t}\n\n\tconst configured = [...(input.extraWritePaths ?? [])];\n\tif (input.includeDefaultCacheRoots ?? true) {\n\t\t// No home dir means no cache roots -- there is nothing to expand them against,\n\t\t// and the fail-closed answer is a narrower policy, not a guessed one.\n\t\tif (home) configured.push(...defaultCacheRoots(home));\n\t}\n\n\tfor (const entry of configured) {\n\t\tconst result = resolveRealPath(entry, { base: cwd });\n\t\tif (!result.ok) {\n\t\t\trejected.push(rejectionFor(result));\n\t\t\tcontinue;\n\t\t}\n\t\tconst excluded = excludedWriteRootReason(result.path, home, platform);\n\t\tif (excluded) {\n\t\t\t// Configured input: narrow the policy and say so. Silently accepting this\n\t\t\t// is what made the exclusions above decorative.\n\t\t\trejected.push({\n\t\t\t\tinput: entry,\n\t\t\t\treason: `refusing to add ${JSON.stringify(result.path)} to the write allowlist because ${excluded}`,\n\t\t\t});\n\t\t\tcontinue;\n\t\t}\n\t\twritePaths.push(result.path);\n\t}\n\n\tconst policy: SandboxPolicy = Object.freeze({\n\t\tversion: SANDBOX_POLICY_VERSION,\n\t\twritePaths: Object.freeze(normalizeWriteSet(writePaths)),\n\t\tread: \"allow-all\",\n\t\tnetwork: input.network ?? \"on\",\n\t\tallowPrivilegeEscalation: false,\n\t});\n\treturn { policy, rejected };\n}\n\n/**\n * Whether `policy` permits writing to `candidate`.\n *\n * Resolves `candidate` to a real path first -- a lexical `startsWith` against\n * `writePaths` is exactly the bug this exists to prevent, since a symlink or a\n * `..` hop makes an in-project-looking string name a file outside the project.\n * Use this anywhere an in-process pre-check is needed; the kernel backend\n * remains the enforcement boundary, this mirrors it.\n *\n * `candidate` must be absolute unless a `base` is given. Anything unresolvable\n * answers `false` -- an undecidable path is not a writable one.\n */\nexport function isPathWritable(policy: SandboxPolicy, candidate: string, options?: { base?: string }): boolean {\n\tif (options?.base === undefined && !isAbsolute(candidate)) return false;\n\tconst result = resolveRealPath(candidate, { base: options?.base ?? candidate });\n\tif (!result.ok) return false;\n\treturn policy.writePaths.some((root) => isContainedIn(result.path, root));\n}\n"]}
@@ -0,0 +1,112 @@
1
+ /**
2
+ * Real-path resolution for sandbox policy paths (R44-SBX.3).
3
+ *
4
+ * Every path that reaches a sandbox profile must first become the path the
5
+ * *kernel* sees, not the path a string spells. This is a security property, not
6
+ * tidiness: the write allowlist is the whole policy, so anything that lets one
7
+ * string name two different places lets the allowlist be widened silently.
8
+ *
9
+ * Two such mechanisms exist, and both are handled here:
10
+ *
11
+ * 1. **Symlinks.** A link inside the project pointing outside it (`<project>/link
12
+ * -> /somewhere/else`) makes `<project>/link/x` pass any `startsWith(project)`
13
+ * check while actually writing to `/somewhere/else/x`.
14
+ * 2. **`..` traversal.** `..` is *not* a lexical operation once symlinks are in
15
+ * play: `<project>/link/../x` is `/somewhere/x`, not `<project>/x`. Node's
16
+ * `path.join`/`path.resolve` collapse `..` lexically and would therefore
17
+ * produce exactly the wrong answer, so this module deliberately never uses
18
+ * them to build the path it resolves.
19
+ *
20
+ * ## Why `..` is walked here instead of being handed to `realpath(3)`
21
+ *
22
+ * The obvious implementation -- hand the raw spelling to `realpathSync.native`
23
+ * and let the OS walk it -- is **not portable, and the runtime it is wrong on is
24
+ * the one that ships**. Measured, same machine, same fixture
25
+ * (`<project>/link -> <outside>/sub`):
26
+ *
27
+ * | call | node 26 | bun 1.4 |
28
+ * |-----------------------------------------------|---------|------------|
29
+ * | `realpathSync(<project>/link/..)` | `<project>` (lexical, wrong) | `<project>` (lexical, wrong) |
30
+ * | `realpathSync.native(<project>/link/..)` | `<outside>` (POSIX, right) | `<project>` (lexical, **wrong**) |
31
+ *
32
+ * Bun's `realpathSync.native` collapses `..` lexically before resolving, exactly
33
+ * like the JS variant. The released `draht` binaries are built with `bun build
34
+ * --compile` (see `packages/coding-agent` `build:binary`), so delegating `..` to
35
+ * the OS would have meant `isPathWritable()` answering **true** for
36
+ * `<project>/link/../evil.txt` in every shipped binary -- a path the kernel
37
+ * writes to `<outside>/evil.txt`, outside the allowlist. That is R44-SBX.3
38
+ * defeated by the very call that was supposed to enforce it.
39
+ *
40
+ * So the guarantee this module actually makes, and the one the walk below
41
+ * implements, is:
42
+ *
43
+ * > `..` is never passed to the platform's `realpath`. The path is walked one
44
+ * > segment at a time by the shared `resolveRealSegment` primitive
45
+ * > (`src/utils/canonical-path.ts`) against an already fully-resolved prefix (a
46
+ * > single name, no `..`, so both runtimes agree and symlink chasing, `ELOOP` and
47
+ * > permission checks stay in the kernel); each `..` is applied to that resolved
48
+ * > prefix, which is where POSIX says it applies.
49
+ *
50
+ * That primitive also carries bun's second divergence — a backslash in a name is
51
+ * rewritten to `/` before the syscall, so `<dir>/a\b` resolves to a *different* real
52
+ * directory, one the kernel will never traverse for that spelling.
53
+ *
54
+ * `test/sandbox-real-path-runtime.test.ts` executes the same assertions under
55
+ * **both** node and bun and fails if the two disagree, so this claim is checked
56
+ * against the runtime that ships rather than only the one the tests run in.
57
+ *
58
+ * ## Paths that do not exist yet
59
+ *
60
+ * A configured write path may legitimately not exist yet (a build output dir, a
61
+ * cache root on a fresh machine). `realpath(3)` fails on those, and guessing is
62
+ * how allowlists get widened by accident. The rule here:
63
+ *
64
+ * - Resolve every segment that *does* exist (so no symlink anywhere in the
65
+ * existing prefix can widen anything).
66
+ * - Re-attach the remaining segments literally, since they name nothing yet.
67
+ * - If any remaining segment is `..`, **refuse**: `..` below a non-existent
68
+ * directory has no determinable target (it depends on what that directory
69
+ * turns out to be when created), and inventing one is precisely the silent
70
+ * widening this requirement forbids.
71
+ *
72
+ * The resolved leaf is only an *ancestor* guarantee -- someone could later create
73
+ * that leaf as a symlink pointing elsewhere. That is why `isPathWritable`
74
+ * (see `policy.ts`) re-resolves the candidate at check time rather than trusting
75
+ * the stored string, and why the kernel backends, not this module, are the
76
+ * enforcement boundary.
77
+ */
78
+ export interface ResolveRealPathOptions {
79
+ /** Absolute directory that relative inputs resolve against (normally the project cwd). */
80
+ base: string;
81
+ }
82
+ export type RealPathResolution = {
83
+ readonly ok: true;
84
+ /** The path as given. */
85
+ readonly input: string;
86
+ /** Absolute, fully symlink-resolved path. Contains no `.` or `..` segments. */
87
+ readonly path: string;
88
+ /** True when the whole path already existed; false when only its ancestor did. */
89
+ readonly existed: boolean;
90
+ } | {
91
+ readonly ok: false;
92
+ readonly input: string;
93
+ /** Human-readable explanation, safe to surface in diagnostics. */
94
+ readonly reason: string;
95
+ };
96
+ /**
97
+ * Resolves `input` to a real, absolute path. Never throws -- failures come back
98
+ * as `{ ok: false, reason }` so callers can drop the entry (narrowing the
99
+ * writable set) instead of falling back to an unresolved spelling.
100
+ */
101
+ export declare function resolveRealPath(input: string, options: ResolveRealPathOptions): RealPathResolution;
102
+ /**
103
+ * True when `candidate` is `root` itself or lies underneath it. Both arguments
104
+ * must already be real paths -- this is a pure string comparison and makes no
105
+ * claim about symlinks; resolve first.
106
+ *
107
+ * Comparison is exact-case. On case-sensitive filesystems that is correct; on a
108
+ * case-insensitive one (default APFS/HFS+) it is stricter than the kernel, which
109
+ * can only produce a false "not contained", never a false "contained".
110
+ */
111
+ export declare function isContainedIn(candidate: string, root: string): boolean;
112
+ //# sourceMappingURL=real-path.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"real-path.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/real-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AAKH,MAAM,WAAW,sBAAsB;IACtC,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,kBAAkB,GAC3B;IACA,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,yBAAyB;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CACzB,GACD;IACA,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACvB,CAAC;AAQL;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,GAAG,kBAAkB,CA0DlG;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAItE"}