@draht/coding-agent 2026.5.12 → 2026.6.11

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 (605) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/bin/draht-tools.cjs +3756 -1
  3. package/dist/bun/cli.d.ts.map +1 -1
  4. package/dist/bun/cli.js +4 -2
  5. package/dist/bun/cli.js.map +1 -1
  6. package/dist/bun/restore-sandbox-env.d.ts +13 -0
  7. package/dist/bun/restore-sandbox-env.d.ts.map +1 -0
  8. package/dist/bun/restore-sandbox-env.js +32 -0
  9. package/dist/bun/restore-sandbox-env.js.map +1 -0
  10. package/dist/cli/args.d.ts +9 -4
  11. package/dist/cli/args.d.ts.map +1 -1
  12. package/dist/cli/args.js +88 -35
  13. package/dist/cli/args.js.map +1 -1
  14. package/dist/cli/config-selector.d.ts +2 -2
  15. package/dist/cli/config-selector.d.ts.map +1 -1
  16. package/dist/cli/config-selector.js +1 -1
  17. package/dist/cli/config-selector.js.map +1 -1
  18. package/dist/cli/file-processor.d.ts.map +1 -1
  19. package/dist/cli/file-processor.js +2 -3
  20. package/dist/cli/file-processor.js.map +1 -1
  21. package/dist/cli/initial-message.d.ts +1 -1
  22. package/dist/cli/initial-message.d.ts.map +1 -1
  23. package/dist/cli/initial-message.js.map +1 -1
  24. package/dist/cli/list-models.d.ts +1 -1
  25. package/dist/cli/list-models.d.ts.map +1 -1
  26. package/dist/cli/list-models.js +7 -1
  27. package/dist/cli/list-models.js.map +1 -1
  28. package/dist/cli/project-trust.d.ts +10 -0
  29. package/dist/cli/project-trust.d.ts.map +1 -0
  30. package/dist/cli/project-trust.js +48 -0
  31. package/dist/cli/project-trust.js.map +1 -0
  32. package/dist/cli/session-picker.d.ts +1 -1
  33. package/dist/cli/session-picker.d.ts.map +1 -1
  34. package/dist/cli/session-picker.js.map +1 -1
  35. package/dist/cli/startup-ui.d.ts +16 -0
  36. package/dist/cli/startup-ui.d.ts.map +1 -0
  37. package/dist/cli/startup-ui.js +112 -0
  38. package/dist/cli/startup-ui.js.map +1 -0
  39. package/dist/cli.d.ts.map +1 -1
  40. package/dist/cli.js +7 -4
  41. package/dist/cli.js.map +1 -1
  42. package/dist/config.d.ts +23 -13
  43. package/dist/config.d.ts.map +1 -1
  44. package/dist/config.js +264 -62
  45. package/dist/config.js.map +1 -1
  46. package/dist/core/agent-session-runtime.d.ts +45 -9
  47. package/dist/core/agent-session-runtime.d.ts.map +1 -1
  48. package/dist/core/agent-session-runtime.js +100 -33
  49. package/dist/core/agent-session-runtime.js.map +1 -1
  50. package/dist/core/agent-session-services.d.ts +6 -4
  51. package/dist/core/agent-session-services.d.ts.map +1 -1
  52. package/dist/core/agent-session-services.js +7 -4
  53. package/dist/core/agent-session-services.js.map +1 -1
  54. package/dist/core/agent-session.d.ts +47 -31
  55. package/dist/core/agent-session.d.ts.map +1 -1
  56. package/dist/core/agent-session.js +470 -443
  57. package/dist/core/agent-session.js.map +1 -1
  58. package/dist/core/auth-guidance.d.ts +5 -0
  59. package/dist/core/auth-guidance.d.ts.map +1 -0
  60. package/dist/core/auth-guidance.js +21 -0
  61. package/dist/core/auth-guidance.js.map +1 -0
  62. package/dist/core/auth-storage.d.ts +10 -1
  63. package/dist/core/auth-storage.d.ts.map +1 -1
  64. package/dist/core/auth-storage.js +27 -6
  65. package/dist/core/auth-storage.js.map +1 -1
  66. package/dist/core/bash-executor.d.ts +1 -15
  67. package/dist/core/bash-executor.d.ts.map +1 -1
  68. package/dist/core/bash-executor.js +10 -24
  69. package/dist/core/bash-executor.js.map +1 -1
  70. package/dist/core/builtins/subagent.d.ts.map +1 -1
  71. package/dist/core/builtins/subagent.js +1 -2
  72. package/dist/core/builtins/subagent.js.map +1 -1
  73. package/dist/core/compaction/branch-summarization.d.ts +6 -4
  74. package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
  75. package/dist/core/compaction/branch-summarization.js +9 -3
  76. package/dist/core/compaction/branch-summarization.js.map +1 -1
  77. package/dist/core/compaction/compaction.d.ts +5 -5
  78. package/dist/core/compaction/compaction.d.ts.map +1 -1
  79. package/dist/core/compaction/compaction.js +43 -37
  80. package/dist/core/compaction/compaction.js.map +1 -1
  81. package/dist/core/compaction/index.d.ts +3 -3
  82. package/dist/core/compaction/index.d.ts.map +1 -1
  83. package/dist/core/compaction/index.js.map +1 -1
  84. package/dist/core/compaction/utils.d.ts +1 -1
  85. package/dist/core/compaction/utils.d.ts.map +1 -1
  86. package/dist/core/compaction/utils.js +1 -1
  87. package/dist/core/compaction/utils.js.map +1 -1
  88. package/dist/core/exec.d.ts.map +1 -1
  89. package/dist/core/exec.js.map +1 -1
  90. package/dist/core/experimental.d.ts +2 -0
  91. package/dist/core/experimental.d.ts.map +1 -0
  92. package/dist/core/experimental.js +4 -0
  93. package/dist/core/experimental.js.map +1 -0
  94. package/dist/core/export-html/ansi-to-html.d.ts.map +1 -1
  95. package/dist/core/export-html/ansi-to-html.js +1 -1
  96. package/dist/core/export-html/ansi-to-html.js.map +1 -1
  97. package/dist/core/export-html/index.d.ts +1 -1
  98. package/dist/core/export-html/index.d.ts.map +1 -1
  99. package/dist/core/export-html/index.js +13 -11
  100. package/dist/core/export-html/index.js.map +1 -1
  101. package/dist/core/export-html/template.css +69 -4
  102. package/dist/core/export-html/template.js +231 -57
  103. package/dist/core/export-html/tool-renderer.d.ts +0 -6
  104. package/dist/core/export-html/tool-renderer.d.ts.map +1 -1
  105. package/dist/core/export-html/tool-renderer.js +15 -2
  106. package/dist/core/export-html/tool-renderer.js.map +1 -1
  107. package/dist/core/extensions/index.d.ts +8 -8
  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 +3 -3
  111. package/dist/core/extensions/loader.d.ts.map +1 -1
  112. package/dist/core/extensions/loader.js +27 -35
  113. package/dist/core/extensions/loader.js.map +1 -1
  114. package/dist/core/extensions/runner.d.ts +30 -12
  115. package/dist/core/extensions/runner.d.ts.map +1 -1
  116. package/dist/core/extensions/runner.js +215 -32
  117. package/dist/core/extensions/runner.js.map +1 -1
  118. package/dist/core/extensions/types.d.ts +163 -35
  119. package/dist/core/extensions/types.d.ts.map +1 -1
  120. package/dist/core/extensions/types.js.map +1 -1
  121. package/dist/core/extensions/wrapper.d.ts.map +1 -1
  122. package/dist/core/extensions/wrapper.js +2 -2
  123. package/dist/core/extensions/wrapper.js.map +1 -1
  124. package/dist/core/footer-data-provider.d.ts +7 -1
  125. package/dist/core/footer-data-provider.d.ts.map +1 -1
  126. package/dist/core/footer-data-provider.js +78 -54
  127. package/dist/core/footer-data-provider.js.map +1 -1
  128. package/dist/core/http-dispatcher.d.ts +21 -0
  129. package/dist/core/http-dispatcher.d.ts.map +1 -0
  130. package/dist/core/http-dispatcher.js +48 -0
  131. package/dist/core/http-dispatcher.js.map +1 -0
  132. package/dist/core/index.d.ts +9 -8
  133. package/dist/core/index.d.ts.map +1 -1
  134. package/dist/core/index.js +2 -1
  135. package/dist/core/index.js.map +1 -1
  136. package/dist/core/keybindings.d.ts +66 -1
  137. package/dist/core/keybindings.d.ts.map +1 -1
  138. package/dist/core/keybindings.js +56 -1
  139. package/dist/core/keybindings.js.map +1 -1
  140. package/dist/core/model-registry.d.ts +22 -4
  141. package/dist/core/model-registry.d.ts.map +1 -1
  142. package/dist/core/model-registry.js +216 -44
  143. package/dist/core/model-registry.js.map +1 -1
  144. package/dist/core/model-resolver.d.ts +2 -1
  145. package/dist/core/model-resolver.d.ts.map +1 -1
  146. package/dist/core/model-resolver.js +48 -21
  147. package/dist/core/model-resolver.js.map +1 -1
  148. package/dist/core/output-guard.d.ts +1 -0
  149. package/dist/core/output-guard.d.ts.map +1 -1
  150. package/dist/core/output-guard.js +52 -22
  151. package/dist/core/output-guard.js.map +1 -1
  152. package/dist/core/package-manager.d.ts +17 -2
  153. package/dist/core/package-manager.d.ts.map +1 -1
  154. package/dist/core/package-manager.js +363 -121
  155. package/dist/core/package-manager.js.map +1 -1
  156. package/dist/core/project-trust.d.ts +15 -0
  157. package/dist/core/project-trust.d.ts.map +1 -0
  158. package/dist/core/project-trust.js +58 -0
  159. package/dist/core/project-trust.js.map +1 -0
  160. package/dist/core/prompt-templates.d.ts +13 -11
  161. package/dist/core/prompt-templates.d.ts.map +1 -1
  162. package/dist/core/prompt-templates.js +67 -76
  163. package/dist/core/prompt-templates.js.map +1 -1
  164. package/dist/core/provider-attribution.d.ts +4 -0
  165. package/dist/core/provider-attribution.d.ts.map +1 -0
  166. package/dist/core/provider-attribution.js +72 -0
  167. package/dist/core/provider-attribution.js.map +1 -0
  168. package/dist/core/provider-display-names.d.ts +2 -0
  169. package/dist/core/provider-display-names.d.ts.map +1 -0
  170. package/dist/core/provider-display-names.js +36 -0
  171. package/dist/core/provider-display-names.js.map +1 -0
  172. package/dist/core/resolve-config-value.d.ts +9 -1
  173. package/dist/core/resolve-config-value.d.ts.map +1 -1
  174. package/dist/core/resolve-config-value.js +134 -11
  175. package/dist/core/resolve-config-value.js.map +1 -1
  176. package/dist/core/resource-loader.d.ts +34 -14
  177. package/dist/core/resource-loader.d.ts.map +1 -1
  178. package/dist/core/resource-loader.js +165 -76
  179. package/dist/core/resource-loader.js.map +1 -1
  180. package/dist/core/sdk.d.ts +26 -10
  181. package/dist/core/sdk.d.ts.map +1 -1
  182. package/dist/core/sdk.js +45 -16
  183. package/dist/core/sdk.js.map +1 -1
  184. package/dist/core/session-manager.d.ts +11 -12
  185. package/dist/core/session-manager.d.ts.map +1 -1
  186. package/dist/core/session-manager.js +245 -132
  187. package/dist/core/session-manager.js.map +1 -1
  188. package/dist/core/settings-manager.d.ts +52 -5
  189. package/dist/core/settings-manager.d.ts.map +1 -1
  190. package/dist/core/settings-manager.js +202 -38
  191. package/dist/core/settings-manager.js.map +1 -1
  192. package/dist/core/skills.d.ts +10 -10
  193. package/dist/core/skills.d.ts.map +1 -1
  194. package/dist/core/skills.js +13 -35
  195. package/dist/core/skills.js.map +1 -1
  196. package/dist/core/slash-commands.d.ts +1 -1
  197. package/dist/core/slash-commands.d.ts.map +1 -1
  198. package/dist/core/slash-commands.js +7 -4
  199. package/dist/core/slash-commands.js.map +1 -1
  200. package/dist/core/source-info.d.ts +1 -1
  201. package/dist/core/source-info.d.ts.map +1 -1
  202. package/dist/core/source-info.js.map +1 -1
  203. package/dist/core/system-prompt.d.ts +4 -4
  204. package/dist/core/system-prompt.d.ts.map +1 -1
  205. package/dist/core/system-prompt.js +14 -10
  206. package/dist/core/system-prompt.js.map +1 -1
  207. package/dist/core/telemetry.d.ts +3 -0
  208. package/dist/core/telemetry.d.ts.map +1 -0
  209. package/dist/core/telemetry.js +9 -0
  210. package/dist/core/telemetry.js.map +1 -0
  211. package/dist/core/tools/bash.d.ts +11 -16
  212. package/dist/core/tools/bash.d.ts.map +1 -1
  213. package/dist/core/tools/bash.js +162 -177
  214. package/dist/core/tools/bash.js.map +1 -1
  215. package/dist/core/tools/edit-diff.d.ts +3 -1
  216. package/dist/core/tools/edit-diff.d.ts.map +1 -1
  217. package/dist/core/tools/edit-diff.js +11 -3
  218. package/dist/core/tools/edit-diff.js.map +1 -1
  219. package/dist/core/tools/edit.d.ts +22 -24
  220. package/dist/core/tools/edit.d.ts.map +1 -1
  221. package/dist/core/tools/edit.js +199 -111
  222. package/dist/core/tools/edit.js.map +1 -1
  223. package/dist/core/tools/file-mutation-queue.d.ts.map +1 -1
  224. package/dist/core/tools/file-mutation-queue.js +27 -12
  225. package/dist/core/tools/file-mutation-queue.js.map +1 -1
  226. package/dist/core/tools/find.d.ts +7 -18
  227. package/dist/core/tools/find.d.ts.map +1 -1
  228. package/dist/core/tools/find.js +134 -95
  229. package/dist/core/tools/find.js.map +1 -1
  230. package/dist/core/tools/grep.d.ts +11 -30
  231. package/dist/core/tools/grep.d.ts.map +1 -1
  232. package/dist/core/tools/grep.js +23 -12
  233. package/dist/core/tools/grep.js.map +1 -1
  234. package/dist/core/tools/index.d.ts +26 -101
  235. package/dist/core/tools/index.d.ts.map +1 -1
  236. package/dist/core/tools/index.js +78 -52
  237. package/dist/core/tools/index.js.map +1 -1
  238. package/dist/core/tools/ls.d.ts +6 -15
  239. package/dist/core/tools/ls.d.ts.map +1 -1
  240. package/dist/core/tools/ls.js +12 -17
  241. package/dist/core/tools/ls.js.map +1 -1
  242. package/dist/core/tools/output-accumulator.d.ts +52 -0
  243. package/dist/core/tools/output-accumulator.d.ts.map +1 -0
  244. package/dist/core/tools/output-accumulator.js +184 -0
  245. package/dist/core/tools/output-accumulator.js.map +1 -0
  246. package/dist/core/tools/path-utils.d.ts +2 -0
  247. package/dist/core/tools/path-utils.d.ts.map +1 -1
  248. package/dist/core/tools/path-utils.js +40 -22
  249. package/dist/core/tools/path-utils.js.map +1 -1
  250. package/dist/core/tools/read.d.ts +7 -18
  251. package/dist/core/tools/read.d.ts.map +1 -1
  252. package/dist/core/tools/read.js +100 -36
  253. package/dist/core/tools/read.js.map +1 -1
  254. package/dist/core/tools/render-utils.d.ts +5 -2
  255. package/dist/core/tools/render-utils.d.ts.map +1 -1
  256. package/dist/core/tools/render-utils.js +18 -2
  257. package/dist/core/tools/render-utils.js.map +1 -1
  258. package/dist/core/tools/tool-definition-wrapper.d.ts.map +1 -1
  259. package/dist/core/tools/tool-definition-wrapper.js +2 -0
  260. package/dist/core/tools/tool-definition-wrapper.js.map +1 -1
  261. package/dist/core/tools/truncate.d.ts.map +1 -1
  262. package/dist/core/tools/truncate.js +12 -2
  263. package/dist/core/tools/truncate.js.map +1 -1
  264. package/dist/core/tools/write.d.ts +5 -14
  265. package/dist/core/tools/write.d.ts.map +1 -1
  266. package/dist/core/tools/write.js +27 -46
  267. package/dist/core/tools/write.js.map +1 -1
  268. package/dist/core/trust-manager.d.ts +31 -0
  269. package/dist/core/trust-manager.d.ts.map +1 -0
  270. package/dist/core/trust-manager.js +187 -0
  271. package/dist/core/trust-manager.js.map +1 -0
  272. package/dist/index.d.ts +31 -29
  273. package/dist/index.d.ts.map +1 -1
  274. package/dist/index.js +9 -8
  275. package/dist/index.js.map +1 -1
  276. package/dist/main.d.ts +5 -1
  277. package/dist/main.d.ts.map +1 -1
  278. package/dist/main.js +170 -87
  279. package/dist/main.js.map +1 -1
  280. package/dist/migrations.d.ts +2 -2
  281. package/dist/migrations.d.ts.map +1 -1
  282. package/dist/migrations.js +127 -5
  283. package/dist/migrations.js.map +1 -1
  284. package/dist/modes/index.d.ts +5 -5
  285. package/dist/modes/index.d.ts.map +1 -1
  286. package/dist/modes/index.js.map +1 -1
  287. package/dist/modes/interactive/components/assistant-message.d.ts +2 -0
  288. package/dist/modes/interactive/components/assistant-message.d.ts.map +1 -1
  289. package/dist/modes/interactive/components/assistant-message.js +14 -0
  290. package/dist/modes/interactive/components/assistant-message.js.map +1 -1
  291. package/dist/modes/interactive/components/bash-execution.d.ts +1 -1
  292. package/dist/modes/interactive/components/bash-execution.d.ts.map +1 -1
  293. package/dist/modes/interactive/components/bash-execution.js +3 -3
  294. package/dist/modes/interactive/components/bash-execution.js.map +1 -1
  295. package/dist/modes/interactive/components/bordered-loader.d.ts.map +1 -1
  296. package/dist/modes/interactive/components/bordered-loader.js +3 -0
  297. package/dist/modes/interactive/components/bordered-loader.js.map +1 -1
  298. package/dist/modes/interactive/components/config-selector.d.ts +4 -4
  299. package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
  300. package/dist/modes/interactive/components/config-selector.js +38 -11
  301. package/dist/modes/interactive/components/config-selector.js.map +1 -1
  302. package/dist/modes/interactive/components/countdown-timer.d.ts +2 -2
  303. package/dist/modes/interactive/components/countdown-timer.d.ts.map +1 -1
  304. package/dist/modes/interactive/components/countdown-timer.js +2 -2
  305. package/dist/modes/interactive/components/countdown-timer.js.map +1 -1
  306. package/dist/modes/interactive/components/custom-editor.d.ts +1 -1
  307. package/dist/modes/interactive/components/custom-editor.d.ts.map +1 -1
  308. package/dist/modes/interactive/components/custom-editor.js.map +1 -1
  309. package/dist/modes/interactive/components/custom-message.d.ts +2 -2
  310. package/dist/modes/interactive/components/custom-message.d.ts.map +1 -1
  311. package/dist/modes/interactive/components/custom-message.js.map +1 -1
  312. package/dist/modes/interactive/components/diff.d.ts.map +1 -1
  313. package/dist/modes/interactive/components/diff.js.map +1 -1
  314. package/dist/modes/interactive/components/earendil-announcement.d.ts.map +1 -1
  315. package/dist/modes/interactive/components/earendil-announcement.js.map +1 -1
  316. package/dist/modes/interactive/components/extension-editor.d.ts.map +1 -1
  317. package/dist/modes/interactive/components/extension-editor.js +14 -6
  318. package/dist/modes/interactive/components/extension-editor.js.map +1 -1
  319. package/dist/modes/interactive/components/extension-input.d.ts.map +1 -1
  320. package/dist/modes/interactive/components/extension-input.js.map +1 -1
  321. package/dist/modes/interactive/components/extension-selector.d.ts +2 -0
  322. package/dist/modes/interactive/components/extension-selector.d.ts.map +1 -1
  323. package/dist/modes/interactive/components/extension-selector.js +8 -3
  324. package/dist/modes/interactive/components/extension-selector.js.map +1 -1
  325. package/dist/modes/interactive/components/first-time-setup.d.ts +25 -0
  326. package/dist/modes/interactive/components/first-time-setup.d.ts.map +1 -0
  327. package/dist/modes/interactive/components/first-time-setup.js +103 -0
  328. package/dist/modes/interactive/components/first-time-setup.js.map +1 -0
  329. package/dist/modes/interactive/components/footer.d.ts +2 -1
  330. package/dist/modes/interactive/components/footer.d.ts.map +1 -1
  331. package/dist/modes/interactive/components/footer.js +23 -7
  332. package/dist/modes/interactive/components/footer.js.map +1 -1
  333. package/dist/modes/interactive/components/index.d.ts +33 -31
  334. package/dist/modes/interactive/components/index.d.ts.map +1 -1
  335. package/dist/modes/interactive/components/index.js +2 -0
  336. package/dist/modes/interactive/components/index.js.map +1 -1
  337. package/dist/modes/interactive/components/keybinding-hints.d.ts +5 -0
  338. package/dist/modes/interactive/components/keybinding-hints.d.ts.map +1 -1
  339. package/dist/modes/interactive/components/keybinding-hints.js +19 -5
  340. package/dist/modes/interactive/components/keybinding-hints.js.map +1 -1
  341. package/dist/modes/interactive/components/login-dialog.d.ts +12 -2
  342. package/dist/modes/interactive/components/login-dialog.d.ts.map +1 -1
  343. package/dist/modes/interactive/components/login-dialog.js +46 -11
  344. package/dist/modes/interactive/components/login-dialog.js.map +1 -1
  345. package/dist/modes/interactive/components/model-selector.d.ts +2 -2
  346. package/dist/modes/interactive/components/model-selector.d.ts.map +1 -1
  347. package/dist/modes/interactive/components/model-selector.js +8 -5
  348. package/dist/modes/interactive/components/model-selector.js.map +1 -1
  349. package/dist/modes/interactive/components/oauth-selector.d.ts +18 -6
  350. package/dist/modes/interactive/components/oauth-selector.d.ts.map +1 -1
  351. package/dist/modes/interactive/components/oauth-selector.js +93 -25
  352. package/dist/modes/interactive/components/oauth-selector.js.map +1 -1
  353. package/dist/modes/interactive/components/scoped-models-selector.d.ts +5 -12
  354. package/dist/modes/interactive/components/scoped-models-selector.d.ts.map +1 -1
  355. package/dist/modes/interactive/components/scoped-models-selector.js +45 -30
  356. package/dist/modes/interactive/components/scoped-models-selector.js.map +1 -1
  357. package/dist/modes/interactive/components/session-selector.d.ts +2 -1
  358. package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
  359. package/dist/modes/interactive/components/session-selector.js +20 -7
  360. package/dist/modes/interactive/components/session-selector.js.map +1 -1
  361. package/dist/modes/interactive/components/settings-selector.d.ts +13 -0
  362. package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
  363. package/dist/modes/interactive/components/settings-selector.js +113 -4
  364. package/dist/modes/interactive/components/settings-selector.js.map +1 -1
  365. package/dist/modes/interactive/components/skill-invocation-message.d.ts +1 -1
  366. package/dist/modes/interactive/components/skill-invocation-message.d.ts.map +1 -1
  367. package/dist/modes/interactive/components/skill-invocation-message.js.map +1 -1
  368. package/dist/modes/interactive/components/thinking-selector.d.ts.map +1 -1
  369. package/dist/modes/interactive/components/thinking-selector.js +1 -1
  370. package/dist/modes/interactive/components/thinking-selector.js.map +1 -1
  371. package/dist/modes/interactive/components/tool-execution.d.ts +6 -1
  372. package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
  373. package/dist/modes/interactive/components/tool-execution.js +57 -14
  374. package/dist/modes/interactive/components/tool-execution.js.map +1 -1
  375. package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
  376. package/dist/modes/interactive/components/tree-selector.js +18 -9
  377. package/dist/modes/interactive/components/tree-selector.js.map +1 -1
  378. package/dist/modes/interactive/components/trust-selector.d.ts +23 -0
  379. package/dist/modes/interactive/components/trust-selector.d.ts.map +1 -0
  380. package/dist/modes/interactive/components/trust-selector.js +91 -0
  381. package/dist/modes/interactive/components/trust-selector.js.map +1 -0
  382. package/dist/modes/interactive/components/user-message-selector.d.ts +2 -2
  383. package/dist/modes/interactive/components/user-message-selector.d.ts.map +1 -1
  384. package/dist/modes/interactive/components/user-message-selector.js +8 -7
  385. package/dist/modes/interactive/components/user-message-selector.js.map +1 -1
  386. package/dist/modes/interactive/components/user-message.d.ts +1 -0
  387. package/dist/modes/interactive/components/user-message.d.ts.map +1 -1
  388. package/dist/modes/interactive/components/user-message.js +8 -7
  389. package/dist/modes/interactive/components/user-message.js.map +1 -1
  390. package/dist/modes/interactive/interactive-mode.d.ts +68 -13
  391. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  392. package/dist/modes/interactive/interactive-mode.js +1100 -319
  393. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  394. package/dist/modes/interactive/theme/dark.json +5 -4
  395. package/dist/modes/interactive/theme/light.json +5 -4
  396. package/dist/modes/interactive/theme/theme.d.ts +22 -3
  397. package/dist/modes/interactive/theme/theme.d.ts.map +1 -1
  398. package/dist/modes/interactive/theme/theme.js +160 -105
  399. package/dist/modes/interactive/theme/theme.js.map +1 -1
  400. package/dist/modes/print-mode.d.ts.map +1 -1
  401. package/dist/modes/print-mode.js +40 -20
  402. package/dist/modes/print-mode.js.map +1 -1
  403. package/dist/modes/rpc/rpc-client.d.ts +11 -1
  404. package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
  405. package/dist/modes/rpc/rpc-client.js +73 -8
  406. package/dist/modes/rpc/rpc-client.js.map +1 -1
  407. package/dist/modes/rpc/rpc-mode.d.ts +2 -2
  408. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  409. package/dist/modes/rpc/rpc-mode.js +96 -30
  410. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  411. package/dist/modes/rpc/rpc-types.d.ts +16 -4
  412. package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
  413. package/dist/modes/rpc/rpc-types.js.map +1 -1
  414. package/dist/package-manager-cli.d.ts +6 -2
  415. package/dist/package-manager-cli.d.ts.map +1 -1
  416. package/dist/package-manager-cli.js +396 -21
  417. package/dist/package-manager-cli.js.map +1 -1
  418. package/dist/prompts/commands/map-codebase.md +14 -0
  419. package/dist/utils/ansi.d.ts +2 -0
  420. package/dist/utils/ansi.d.ts.map +1 -0
  421. package/dist/utils/ansi.js +52 -0
  422. package/dist/utils/ansi.js.map +1 -0
  423. package/dist/utils/changelog.d.ts +2 -1
  424. package/dist/utils/changelog.d.ts.map +1 -1
  425. package/dist/utils/changelog.js +78 -0
  426. package/dist/utils/changelog.js.map +1 -1
  427. package/dist/utils/child-process.d.ts +5 -1
  428. package/dist/utils/child-process.d.ts.map +1 -1
  429. package/dist/utils/child-process.js +10 -0
  430. package/dist/utils/child-process.js.map +1 -1
  431. package/dist/utils/clipboard-image.d.ts.map +1 -1
  432. package/dist/utils/clipboard-image.js +2 -2
  433. package/dist/utils/clipboard-image.js.map +1 -1
  434. package/dist/utils/clipboard-native.d.ts +3 -1
  435. package/dist/utils/clipboard-native.d.ts.map +1 -1
  436. package/dist/utils/clipboard-native.js +14 -8
  437. package/dist/utils/clipboard-native.js.map +1 -1
  438. package/dist/utils/clipboard.d.ts.map +1 -1
  439. package/dist/utils/clipboard.js +84 -45
  440. package/dist/utils/clipboard.js.map +1 -1
  441. package/dist/utils/deprecation.d.ts +4 -0
  442. package/dist/utils/deprecation.d.ts.map +1 -0
  443. package/dist/utils/deprecation.js +13 -0
  444. package/dist/utils/deprecation.js.map +1 -0
  445. package/dist/utils/exif-orientation.d.ts +1 -1
  446. package/dist/utils/exif-orientation.d.ts.map +1 -1
  447. package/dist/utils/exif-orientation.js.map +1 -1
  448. package/dist/utils/fs-watch.d.ts +5 -0
  449. package/dist/utils/fs-watch.d.ts.map +1 -0
  450. package/dist/utils/fs-watch.js +25 -0
  451. package/dist/utils/fs-watch.js.map +1 -0
  452. package/dist/utils/git.d.ts.map +1 -1
  453. package/dist/utils/git.js +54 -22
  454. package/dist/utils/git.js.map +1 -1
  455. package/dist/utils/html.d.ts +7 -0
  456. package/dist/utils/html.d.ts.map +1 -0
  457. package/dist/utils/html.js +40 -0
  458. package/dist/utils/html.js.map +1 -0
  459. package/dist/utils/image-convert.d.ts.map +1 -1
  460. package/dist/utils/image-convert.js.map +1 -1
  461. package/dist/utils/image-resize-core.d.ts +30 -0
  462. package/dist/utils/image-resize-core.d.ts.map +1 -0
  463. package/dist/utils/image-resize-core.js +124 -0
  464. package/dist/utils/image-resize-core.js.map +1 -0
  465. package/dist/utils/image-resize-worker.d.ts +2 -0
  466. package/dist/utils/image-resize-worker.d.ts.map +1 -0
  467. package/dist/utils/image-resize-worker.js +31 -0
  468. package/dist/utils/image-resize-worker.js.map +1 -0
  469. package/dist/utils/image-resize.d.ts +7 -27
  470. package/dist/utils/image-resize.d.ts.map +1 -1
  471. package/dist/utils/image-resize.js +75 -115
  472. package/dist/utils/image-resize.js.map +1 -1
  473. package/dist/utils/json.d.ts +3 -0
  474. package/dist/utils/json.d.ts.map +1 -0
  475. package/dist/utils/json.js +7 -0
  476. package/dist/utils/json.js.map +1 -0
  477. package/dist/utils/mime.d.ts +1 -0
  478. package/dist/utils/mime.d.ts.map +1 -1
  479. package/dist/utils/mime.js +59 -16
  480. package/dist/utils/mime.js.map +1 -1
  481. package/dist/utils/open-browser.d.ts +9 -0
  482. package/dist/utils/open-browser.d.ts.map +1 -0
  483. package/dist/utils/open-browser.js +22 -0
  484. package/dist/utils/open-browser.js.map +1 -0
  485. package/dist/utils/paths.d.ts +25 -1
  486. package/dist/utils/paths.d.ts.map +1 -1
  487. package/dist/utils/paths.js +75 -2
  488. package/dist/utils/paths.js.map +1 -1
  489. package/dist/utils/pi-user-agent.d.ts +2 -0
  490. package/dist/utils/pi-user-agent.d.ts.map +1 -0
  491. package/dist/utils/pi-user-agent.js +5 -0
  492. package/dist/utils/pi-user-agent.js.map +1 -0
  493. package/dist/utils/shell.d.ts +10 -6
  494. package/dist/utils/shell.d.ts.map +1 -1
  495. package/dist/utils/shell.js +35 -26
  496. package/dist/utils/shell.js.map +1 -1
  497. package/dist/utils/syntax-highlight.d.ts +12 -0
  498. package/dist/utils/syntax-highlight.d.ts.map +1 -0
  499. package/dist/utils/syntax-highlight.js +118 -0
  500. package/dist/utils/syntax-highlight.js.map +1 -0
  501. package/dist/utils/tools-manager.d.ts.map +1 -1
  502. package/dist/utils/tools-manager.js +86 -10
  503. package/dist/utils/tools-manager.js.map +1 -1
  504. package/dist/utils/version-check.d.ts +15 -0
  505. package/dist/utils/version-check.d.ts.map +1 -0
  506. package/dist/utils/version-check.js +82 -0
  507. package/dist/utils/version-check.js.map +1 -0
  508. package/dist/utils/windows-self-update.d.ts +3 -0
  509. package/dist/utils/windows-self-update.d.ts.map +1 -0
  510. package/dist/utils/windows-self-update.js +77 -0
  511. package/dist/utils/windows-self-update.js.map +1 -0
  512. package/docs/compaction.md +12 -12
  513. package/docs/containerization.md +111 -0
  514. package/docs/custom-provider.md +187 -47
  515. package/docs/development.md +5 -5
  516. package/docs/docs.json +156 -0
  517. package/docs/extensions.md +465 -71
  518. package/docs/index.md +82 -0
  519. package/docs/json.md +4 -4
  520. package/docs/keybindings.md +23 -1
  521. package/docs/models.md +119 -17
  522. package/docs/packages.md +17 -9
  523. package/docs/prompt-templates.md +30 -2
  524. package/docs/providers.md +83 -22
  525. package/docs/quickstart.md +165 -0
  526. package/docs/rpc.md +41 -10
  527. package/docs/sdk.md +68 -50
  528. package/docs/security.md +55 -0
  529. package/docs/{session.md → session-format.md} +11 -11
  530. package/docs/sessions.md +145 -0
  531. package/docs/settings.md +61 -11
  532. package/docs/skills.md +16 -17
  533. package/docs/terminal-setup.md +44 -2
  534. package/docs/termux.md +4 -4
  535. package/docs/themes.md +3 -3
  536. package/docs/tmux.md +4 -2
  537. package/docs/tui.md +44 -4
  538. package/docs/usage.md +305 -0
  539. package/examples/extensions/border-status-editor.ts +145 -0
  540. package/examples/extensions/built-in-tool-renderer.ts +3 -0
  541. package/examples/extensions/custom-header.ts +1 -1
  542. package/examples/extensions/custom-provider-anthropic/index.ts +1 -1
  543. package/examples/extensions/custom-provider-anthropic/package-lock.json +2 -2
  544. package/examples/extensions/custom-provider-anthropic/package.json +2 -2
  545. package/examples/extensions/custom-provider-gitlab-duo/index.ts +55 -4
  546. package/examples/extensions/custom-provider-gitlab-duo/package.json +1 -1
  547. package/examples/extensions/custom-provider-gitlab-duo/test.ts +1 -1
  548. package/examples/extensions/doom-overlay/doom-component.ts +2 -2
  549. package/examples/extensions/doom-overlay/index.ts +1 -1
  550. package/examples/extensions/dynamic-resources/dynamic.json +1 -1
  551. package/examples/extensions/dynamic-tools.ts +2 -2
  552. package/examples/extensions/git-merge-and-resolve.ts +115 -0
  553. package/examples/extensions/github-issue-autocomplete.ts +185 -0
  554. package/examples/extensions/gondolin/index.ts +531 -0
  555. package/examples/extensions/gondolin/package-lock.json +185 -0
  556. package/examples/extensions/gondolin/package.json +19 -0
  557. package/examples/extensions/handoff.ts +50 -12
  558. package/examples/extensions/input-transform-streaming.ts +39 -0
  559. package/examples/extensions/interactive-shell.ts +1 -1
  560. package/examples/extensions/notify.ts +2 -9
  561. package/examples/extensions/overlay-qa-tests.ts +240 -138
  562. package/examples/extensions/overlay-test.ts +7 -4
  563. package/examples/extensions/plan-mode/utils.ts +1 -1
  564. package/examples/extensions/preset.ts +36 -3
  565. package/examples/extensions/project-trust.ts +64 -0
  566. package/examples/extensions/prompt-customizer.ts +97 -0
  567. package/examples/extensions/provider-payload.ts +4 -0
  568. package/examples/extensions/qna.ts +1 -1
  569. package/examples/extensions/question.ts +2 -2
  570. package/examples/extensions/questionnaire.ts +2 -2
  571. package/examples/extensions/reload-runtime.ts +1 -1
  572. package/examples/extensions/sandbox/index.ts +4 -4
  573. package/examples/extensions/sandbox/package-lock.json +5 -5
  574. package/examples/extensions/sandbox/package.json +2 -2
  575. package/examples/extensions/shutdown-command.ts +1 -1
  576. package/examples/extensions/snake.ts +1 -1
  577. package/examples/extensions/space-invaders.ts +1 -1
  578. package/examples/extensions/structured-output.ts +65 -0
  579. package/examples/extensions/subagent/index.ts +51 -28
  580. package/examples/extensions/summarize.ts +1 -1
  581. package/examples/extensions/tic-tac-toe.ts +1008 -0
  582. package/examples/extensions/titlebar-spinner.ts +2 -2
  583. package/examples/extensions/todo.ts +2 -2
  584. package/examples/extensions/tool-override.ts +1 -1
  585. package/examples/extensions/tools.ts +5 -0
  586. package/examples/extensions/truncated-tool.ts +1 -1
  587. package/examples/extensions/with-deps/index.ts +1 -1
  588. package/examples/extensions/with-deps/package-lock.json +2 -2
  589. package/examples/extensions/with-deps/package.json +3 -3
  590. package/examples/extensions/working-indicator.ts +123 -0
  591. package/examples/extensions/working-message-test.ts +25 -0
  592. package/examples/sdk/01-minimal.ts +14 -10
  593. package/examples/sdk/02-custom-model.ts +12 -8
  594. package/examples/sdk/03-custom-prompt.ts +32 -17
  595. package/examples/sdk/04-skills.ts +5 -2
  596. package/examples/sdk/05-tools.ts +23 -31
  597. package/examples/sdk/06-extensions.ts +14 -8
  598. package/examples/sdk/07-context-files.ts +5 -3
  599. package/examples/sdk/08-prompt-templates.ts +5 -2
  600. package/examples/sdk/09-api-keys-and-oauth.ts +8 -4
  601. package/examples/sdk/10-settings.ts +8 -6
  602. package/examples/sdk/11-sessions.ts +4 -0
  603. package/examples/sdk/12-full-control.ts +13 -17
  604. package/package.json +13 -6
  605. package/prompts/commands/map-codebase.md +14 -0
@@ -40,6 +40,7 @@ See [examples/extensions/](../examples/extensions/) for working implementations.
40
40
  - [Resource Events](#resource-events)
41
41
  - [Session Events](#session-events)
42
42
  - [Agent Events](#agent-events)
43
+ - [Model Events](#model-events)
43
44
  - [Tool Events](#tool-events)
44
45
  - [ExtensionContext](#extensioncontext)
45
46
  - [ExtensionCommandContext](#extensioncommandcontext)
@@ -57,7 +58,7 @@ Create `~/.pi/agent/extensions/my-extension.ts`:
57
58
 
58
59
  ```typescript
59
60
  import type { ExtensionAPI } from "@draht/coding-agent";
60
- import { Type } from "@sinclair/typebox";
61
+ import { Type } from "typebox";
61
62
 
62
63
  export default function (pi: ExtensionAPI) {
63
64
  // React to events
@@ -108,7 +109,7 @@ pi -e ./my-extension.ts
108
109
 
109
110
  > **Security:** Extensions run with your full system permissions and can execute arbitrary code. Only install from sources you trust.
110
111
 
111
- Extensions are auto-discovered from:
112
+ Extensions are auto-discovered from trusted locations. Project-local `.pi/extensions` entries load only after the project is trusted.
112
113
 
113
114
  | Location | Scope |
114
115
  |----------|-------|
@@ -139,17 +140,19 @@ To share extensions via npm or git as pi packages, see [packages.md](packages.md
139
140
  | Package | Purpose |
140
141
  |---------|---------|
141
142
  | `@draht/coding-agent` | Extension types (`ExtensionAPI`, `ExtensionContext`, events) |
142
- | `@sinclair/typebox` | Schema definitions for tool parameters |
143
+ | `typebox` | Schema definitions for tool parameters |
143
144
  | `@draht/ai` | AI utilities (`StringEnum` for Google-compatible enums) |
144
145
  | `@draht/tui` | TUI components for custom rendering |
145
146
 
146
147
  npm dependencies work too. Add a `package.json` next to your extension (or in a parent directory), run `npm install`, and imports from `node_modules/` are resolved automatically.
147
148
 
149
+ For distributed pi packages installed with `pi install` (npm or git), runtime deps must be in `dependencies`. Package installation uses production installs (`npm install --omit=dev`) by default, so `devDependencies` are not available at runtime; when `npmCommand` is configured, git packages use plain `install` for compatibility with wrappers.
150
+
148
151
  Node.js built-ins (`node:fs`, `node:path`, etc.) are also available.
149
152
 
150
153
  ## Writing an Extension
151
154
 
152
- An extension exports a default function that receives `ExtensionAPI`:
155
+ An extension exports a default factory function that receives `ExtensionAPI`. The factory can be synchronous or asynchronous:
153
156
 
154
157
  ```typescript
155
158
  import type { ExtensionAPI } from "@draht/coding-agent";
@@ -159,7 +162,7 @@ export default function (pi: ExtensionAPI) {
159
162
  pi.on("event_name", async (event, ctx) => {
160
163
  // ctx.ui for user interaction
161
164
  const ok = await ctx.ui.confirm("Title", "Are you sure?");
162
- ctx.ui.notify("Done!", "success");
165
+ ctx.ui.notify("Done!", "info");
163
166
  ctx.ui.setStatus("my-ext", "Processing..."); // Footer status
164
167
  ctx.ui.setWidget("my-ext", ["Line 1", "Line 2"]); // Widget above editor (default)
165
168
  });
@@ -174,6 +177,45 @@ export default function (pi: ExtensionAPI) {
174
177
 
175
178
  Extensions are loaded via [jiti](https://github.com/unjs/jiti), so TypeScript works without compilation.
176
179
 
180
+ If the factory returns a `Promise`, pi awaits it before continuing startup. That means async initialization completes before `session_start`, before `resources_discover`, and before provider registrations queued via `pi.registerProvider()` are flushed.
181
+
182
+ ### Async factory functions
183
+
184
+ Use an async factory for one-time startup work such as fetching remote configuration or dynamically discovering available models.
185
+
186
+ ```typescript
187
+ import type { ExtensionAPI } from "@draht/coding-agent";
188
+
189
+ export default async function (pi: ExtensionAPI) {
190
+ const response = await fetch("http://localhost:1234/v1/models");
191
+ const payload = (await response.json()) as {
192
+ data: Array<{
193
+ id: string;
194
+ name?: string;
195
+ context_window?: number;
196
+ max_tokens?: number;
197
+ }>;
198
+ };
199
+
200
+ pi.registerProvider("local-openai", {
201
+ baseUrl: "http://localhost:1234/v1",
202
+ apiKey: "$LOCAL_OPENAI_API_KEY",
203
+ api: "openai-completions",
204
+ models: payload.data.map((model) => ({
205
+ id: model.id,
206
+ name: model.name ?? model.id,
207
+ reasoning: false,
208
+ input: ["text"],
209
+ cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
210
+ contextWindow: model.context_window ?? 128000,
211
+ maxTokens: model.max_tokens ?? 4096,
212
+ })),
213
+ });
214
+ }
215
+ ```
216
+
217
+ This pattern makes the fetched models available during normal startup and to `pi --list-models`.
218
+
177
219
  ### Extension Styles
178
220
 
179
221
  **Single file** - simplest, for small extensions:
@@ -213,7 +255,7 @@ Extensions are loaded via [jiti](https://github.com/unjs/jiti), so TypeScript wo
213
255
  "zod": "^3.0.0",
214
256
  "chalk": "^5.0.0"
215
257
  },
216
- "draht": {
258
+ "pi": {
217
259
  "extensions": ["./src/index.ts"]
218
260
  }
219
261
  }
@@ -228,6 +270,7 @@ Run `npm install` in the extension directory, then imports from `node_modules/`
228
270
  ```
229
271
  pi starts
230
272
  │
273
+ ├─► project_trust (user/global and CLI extensions only, before project resources load)
231
274
  ├─► session_start { reason: "startup" }
232
275
  └─► resources_discover { reason: "startup" }
233
276
  │
@@ -246,6 +289,7 @@ user sends prompt ────────────────────
246
289
  │ ├─► turn_start │ │
247
290
  │ ├─► context (can modify messages) │ │
248
291
  │ ├─► before_provider_request (can inspect or replace payload)
292
+ │ ├─► after_provider_response (status + headers, before stream consume)
249
293
  │ │ │ │
250
294
  │ │ LLM responds, may call tools: │ │
251
295
  │ │ ├─► tool_execution_start │ │
@@ -266,7 +310,7 @@ user sends another prompt ◄─────────────────
266
310
  ├─► session_start { reason: "new" | "resume", previousSessionFile? }
267
311
  └─► resources_discover { reason: "startup" }
268
312
 
269
- /fork
313
+ /fork or /clone
270
314
  ├─► session_before_fork (can cancel)
271
315
  ├─► session_shutdown
272
316
  ├─► session_start { reason: "fork", previousSessionFile }
@@ -281,12 +325,35 @@ user sends another prompt ◄─────────────────
281
325
  └─► session_tree
282
326
 
283
327
  /model or Ctrl+P (model selection/cycling)
328
+ ├─► thinking_level_select (if model change changes/clamps thinking level)
284
329
  └─► model_select
285
330
 
286
- exit (Ctrl+C, Ctrl+D)
331
+ thinking level changes (settings, keybinding, pi.setThinkingLevel())
332
+ └─► thinking_level_select
333
+
334
+ exit (Ctrl+C, Ctrl+D, SIGHUP, SIGTERM)
287
335
  └─► session_shutdown
288
336
  ```
289
337
 
338
+ ### Startup Events
339
+
340
+ #### project_trust
341
+
342
+ Fired before pi decides whether to trust a project with dynamic configs (`.pi` or `.agents/skills`). It runs during startup and when session replacement (for example `/resume`) enters a cwd whose trust has not been resolved in the current process. Only user/global extensions and CLI `-e` extensions participate; project-local extensions are not loaded until after trust is resolved.
343
+
344
+ ```typescript
345
+ pi.on("project_trust", async (event, ctx) => {
346
+ // event.cwd - current working directory
347
+ // ctx has a limited trust context: cwd, mode, hasUI, and select/confirm/input/notify UI helpers
348
+ if (await ctx.ui.confirm("Trust project?", event.cwd)) {
349
+ return { trusted: "yes", remember: true };
350
+ }
351
+ return { trusted: "undecided" };
352
+ });
353
+ ```
354
+
355
+ A `project_trust` handler must return `{ trusted: "yes" | "no" | "undecided" }`. A user/global or CLI extension that returns `"yes"` or `"no"` owns the decision; the first yes/no decision wins and suppresses the built-in trust prompt. Use `remember: true` to persist a yes/no decision; otherwise it applies only to the current process. Return `"undecided"` to let later handlers or the built-in trust flow decide. Check `ctx.hasUI` before prompting. If no handler returns yes/no, normal trust resolution continues: saved `trust.json` decisions apply first, then `defaultProjectTrust` controls whether pi asks, trusts, or declines by default.
356
+
290
357
  ### Resource Events
291
358
 
292
359
  #### resources_discover
@@ -308,7 +375,7 @@ pi.on("resources_discover", async (event, _ctx) => {
308
375
 
309
376
  ### Session Events
310
377
 
311
- See [session.md](session.md) for session storage internals and the SessionManager API.
378
+ See [Session Format](session-format.md) for session storage internals and the SessionManager API.
312
379
 
313
380
  #### session_start
314
381
 
@@ -343,18 +410,19 @@ Do cleanup work in `session_shutdown`, then reestablish any in-memory state in `
343
410
 
344
411
  #### session_before_fork
345
412
 
346
- Fired when forking via `/fork`.
413
+ Fired when forking via `/fork` or cloning via `/clone`.
347
414
 
348
415
  ```typescript
349
416
  pi.on("session_before_fork", async (event, ctx) => {
350
- // event.entryId - ID of the entry being forked from
351
- return { cancel: true }; // Cancel fork
417
+ // event.entryId - ID of the selected entry
418
+ // event.position - "before" for /fork, "at" for /clone
419
+ return { cancel: true }; // Cancel fork/clone
352
420
  // OR
353
- return { skipConversationRestore: true }; // Fork but don't rewind messages
421
+ return { skipConversationRestore: true }; // Reserved for future conversation restore control
354
422
  });
355
423
  ```
356
424
 
357
- After a successful fork, pi emits `session_shutdown` for the old extension instance, reloads and rebinds extensions for the new session, then emits `session_start` with `reason: "fork"` and `previousSessionFile`.
425
+ After a successful fork or clone, pi emits `session_shutdown` for the old extension instance, reloads and rebinds extensions for the new session, then emits `session_start` with `reason: "fork"` and `previousSessionFile`.
358
426
  Do cleanup work in `session_shutdown`, then reestablish any in-memory state in `session_start`.
359
427
 
360
428
  #### session_before_compact / session_compact
@@ -386,7 +454,7 @@ pi.on("session_compact", async (event, ctx) => {
386
454
 
387
455
  #### session_before_tree / session_tree
388
456
 
389
- Fired on `/tree` navigation. See [tree.md](tree.md) for tree navigation concepts.
457
+ Fired on `/tree` navigation. See [Sessions](sessions.md) for tree navigation concepts.
390
458
 
391
459
  ```typescript
392
460
  pi.on("session_before_tree", async (event, ctx) => {
@@ -403,10 +471,12 @@ pi.on("session_tree", async (event, ctx) => {
403
471
 
404
472
  #### session_shutdown
405
473
 
406
- Fired on exit (Ctrl+C, Ctrl+D, SIGTERM).
474
+ Fired before an extension runtime is torn down.
407
475
 
408
476
  ```typescript
409
- pi.on("session_shutdown", async (_event, ctx) => {
477
+ pi.on("session_shutdown", async (event, ctx) => {
478
+ // event.reason - "quit" | "reload" | "new" | "resume" | "fork"
479
+ // event.targetSessionFile - destination session for session replacement flows
410
480
  // Cleanup, save state, etc.
411
481
  });
412
482
  ```
@@ -421,7 +491,17 @@ Fired after user submits prompt, before agent loop. Can inject a message and/or
421
491
  pi.on("before_agent_start", async (event, ctx) => {
422
492
  // event.prompt - user's prompt text
423
493
  // event.images - attached images (if any)
424
- // event.systemPrompt - current system prompt
494
+ // event.systemPrompt - current chained system prompt for this handler
495
+ // (includes changes from earlier before_agent_start handlers)
496
+ // event.systemPromptOptions - structured options used to build the system prompt
497
+ // .customPrompt - any custom system prompt (from --system-prompt, SYSTEM.md, or custom templates)
498
+ // .selectedTools - tools currently active in the prompt
499
+ // .toolSnippets - one-line descriptions for each tool
500
+ // .promptGuidelines - custom guideline bullets
501
+ // .appendSystemPrompt - text from --append-system-prompt flags
502
+ // .cwd - working directory
503
+ // .contextFiles - AGENTS.md files and other loaded context files
504
+ // .skills - loaded skills
425
505
 
426
506
  return {
427
507
  // Inject a persistent message (stored in session, sent to LLM)
@@ -436,6 +516,10 @@ pi.on("before_agent_start", async (event, ctx) => {
436
516
  });
437
517
  ```
438
518
 
519
+ The `systemPromptOptions` field gives extensions access to the same structured data Pi uses to build the system prompt. This lets you inspect what Pi has loaded — custom prompts, guidelines, tool snippets, context files, skills — without re-discovering resources or re-parsing flags. Use it when your extension needs to make deep, informed changes to the system prompt while respecting user-provided configuration.
520
+
521
+ Inside `before_agent_start`, `event.systemPrompt` and `ctx.getSystemPrompt()` both reflect the chained system prompt as of the current handler. Later `before_agent_start` handlers can still modify it again.
522
+
439
523
  #### agent_start / agent_end
440
524
 
441
525
  Fired once per user prompt.
@@ -468,6 +552,7 @@ Fired for message lifecycle updates.
468
552
 
469
553
  - `message_start` and `message_end` fire for user, assistant, and toolResult messages.
470
554
  - `message_update` fires for assistant streaming updates.
555
+ - `message_end` handlers can return `{ message }` to replace the finalized message. The replacement must keep the same `role`.
471
556
 
472
557
  ```typescript
473
558
  pi.on("message_start", async (event, ctx) => {
@@ -480,7 +565,20 @@ pi.on("message_update", async (event, ctx) => {
480
565
  });
481
566
 
482
567
  pi.on("message_end", async (event, ctx) => {
483
- // event.message
568
+ if (event.message.role !== "assistant") return;
569
+
570
+ return {
571
+ message: {
572
+ ...event.message,
573
+ usage: {
574
+ ...event.message.usage,
575
+ cost: {
576
+ ...event.message.usage.cost,
577
+ total: 0.123,
578
+ },
579
+ },
580
+ },
581
+ };
484
582
  });
485
583
  ```
486
584
 
@@ -491,7 +589,8 @@ Fired for tool execution lifecycle updates.
491
589
  In parallel tool mode:
492
590
  - `tool_execution_start` is emitted in assistant source order during the preflight phase
493
591
  - `tool_execution_update` events may interleave across tools
494
- - `tool_execution_end` is emitted in assistant source order, matching final tool result message order
592
+ - `tool_execution_end` is emitted in tool completion order after each tool is finalized
593
+ - final `toolResult` message events are still emitted later in assistant source order
495
594
 
496
595
  ```typescript
497
596
  pi.on("tool_execution_start", async (event, ctx) => {
@@ -509,7 +608,7 @@ pi.on("tool_execution_end", async (event, ctx) => {
509
608
 
510
609
  #### context
511
610
 
512
- Fired before each LLM call. Modify messages non-destructively. See [session.md](session.md) for message types.
611
+ Fired before each LLM call. Modify messages non-destructively. See [Session Format](session-format.md) for message types.
513
612
 
514
613
  ```typescript
515
614
  pi.on("context", async (event, ctx) => {
@@ -523,6 +622,8 @@ pi.on("context", async (event, ctx) => {
523
622
 
524
623
  Fired after the provider-specific payload is built, right before the request is sent. Handlers run in extension load order. Returning `undefined` keeps the payload unchanged. Returning any other value replaces the payload for later handlers and for the actual request.
525
624
 
625
+ This hook can rewrite provider-level system instructions or remove them entirely. Those payload-level changes are not reflected by `ctx.getSystemPrompt()`, which reports Pi's system prompt string rather than the final serialized provider payload.
626
+
526
627
  ```typescript
527
628
  pi.on("before_provider_request", (event, ctx) => {
528
629
  console.log(JSON.stringify(event.payload, null, 2));
@@ -534,6 +635,22 @@ pi.on("before_provider_request", (event, ctx) => {
534
635
 
535
636
  This is mainly useful for debugging provider serialization and cache behavior.
536
637
 
638
+ #### after_provider_response
639
+
640
+ Fired after an HTTP response is received and before its stream body is consumed. Handlers run in extension load order.
641
+
642
+ ```typescript
643
+ pi.on("after_provider_response", (event, ctx) => {
644
+ // event.status - HTTP status code
645
+ // event.headers - normalized response headers
646
+ if (event.status === 429) {
647
+ console.log("rate limited", event.headers["retry-after"]);
648
+ }
649
+ });
650
+ ```
651
+
652
+ Header availability depends on provider and transport. Providers that abstract HTTP responses may not expose headers.
653
+
537
654
  ### Model Events
538
655
 
539
656
  #### model_select
@@ -557,6 +674,21 @@ pi.on("model_select", async (event, ctx) => {
557
674
 
558
675
  Use this to update UI elements (status bars, footers) or perform model-specific initialization when the active model changes.
559
676
 
677
+ #### thinking_level_select
678
+
679
+ Fired when the thinking level changes. This is notification-only; handler return values are ignored.
680
+
681
+ ```typescript
682
+ pi.on("thinking_level_select", async (event, ctx) => {
683
+ // event.level - newly selected thinking level
684
+ // event.previousLevel - previous thinking level
685
+
686
+ ctx.ui.setStatus("thinking", `thinking: ${event.level}`);
687
+ });
688
+ ```
689
+
690
+ Use this to update extension UI when `pi.setThinkingLevel()`, model changes, or built-in thinking-level controls change the active thinking level.
691
+
560
692
  ### Tool Events
561
693
 
562
694
  #### tool_call
@@ -626,6 +758,8 @@ pi.on("tool_call", (event) => {
626
758
 
627
759
  Fired after tool execution finishes and before `tool_execution_end` plus the final tool result message events are emitted. **Can modify result.**
628
760
 
761
+ In parallel tool mode, `tool_result` and `tool_execution_end` may interleave in tool completion order, while final `toolResult` message events are still emitted later in assistant source order.
762
+
629
763
  `tool_result` handlers chain like middleware:
630
764
  - Handlers run in extension load order
631
765
  - Each handler sees the latest result after previous handler changes
@@ -705,6 +839,9 @@ pi.on("input", async (event, ctx) => {
705
839
  // event.text - raw input (before skill/template expansion)
706
840
  // event.images - attached images, if any
707
841
  // event.source - "interactive" (typed), "rpc" (API), or "extension" (via sendUserMessage)
842
+ // event.streamingBehavior - "steer" | "followUp" | undefined
843
+ // undefined when idle, "steer" for mid-stream interrupts,
844
+ // "followUp" for messages queued until the agent finishes
708
845
 
709
846
  // Transform: rewrite input before expansion
710
847
  if (event.text.startsWith("?quick "))
@@ -733,7 +870,7 @@ pi.on("input", async (event, ctx) => {
733
870
  - `transform` - modify text/images, then continue to expansion
734
871
  - `handled` - skip agent entirely (first handler to return this wins)
735
872
 
736
- Transforms chain across handlers. See [input-transform.ts](../examples/extensions/input-transform.ts).
873
+ Transforms chain across handlers. See [input-transform.ts](../examples/extensions/input-transform.ts) and [input-transform-streaming.ts](../examples/extensions/input-transform-streaming.ts) for `streamingBehavior`-aware routing.
737
874
 
738
875
  ## ExtensionContext
739
876
 
@@ -743,17 +880,27 @@ All handlers receive `ctx: ExtensionContext`.
743
880
 
744
881
  UI methods for user interaction. See [Custom UI](#custom-ui) for full details.
745
882
 
883
+ ### ctx.mode
884
+
885
+ Current run mode: `"tui"`, `"rpc"`, `"json"`, or `"print"`. Use `ctx.mode === "tui"` to guard terminal-only features such as `custom()`, component factories, terminal input, and direct TUI rendering.
886
+
746
887
  ### ctx.hasUI
747
888
 
748
- `false` in print mode (`-p`) and JSON mode. `true` in interactive and RPC mode. In RPC mode, dialog methods (`select`, `confirm`, `input`, `editor`) work via the extension UI sub-protocol, and fire-and-forget methods (`notify`, `setStatus`, `setWidget`, `setTitle`, `setEditorText`) emit requests to the client. Some TUI-specific methods are no-ops or return defaults (see [rpc.md](rpc.md#extension-ui-protocol)).
889
+ `true` in TUI and RPC modes. `false` in print mode (`-p`) and JSON mode. Use this to guard dialog methods (`select`, `confirm`, `input`, `editor`) and fire-and-forget methods (`notify`, `setStatus`, `setWidget`, `setTitle`, `setEditorText`) that work in both TUI and RPC modes. In RPC mode, some TUI-specific methods are no-ops or return defaults (see [rpc.md](rpc.md#extension-ui-protocol)).
749
890
 
750
891
  ### ctx.cwd
751
892
 
752
893
  Current working directory.
753
894
 
895
+ ### ctx.isProjectTrusted()
896
+
897
+ Returns whether project-local trust is active for the current session context. This includes temporary trust decisions and CLI trust overrides, not just saved decisions in the global trust store.
898
+
899
+ Use this before reading project-local extension configuration that should only be honored for trusted projects.
900
+
754
901
  ### ctx.sessionManager
755
902
 
756
- Read-only access to session state. See [session.md](session.md) for the full SessionManager API and entry types.
903
+ Read-only access to session state. See [Session Format](session-format.md) for the full SessionManager API and entry types.
757
904
 
758
905
  For `tool_call`, this state is synchronized through the current assistant message before handlers run. In parallel tool execution mode it is still not guaranteed to include sibling tool results from the same assistant message.
759
906
 
@@ -843,7 +990,12 @@ ctx.compact({
843
990
 
844
991
  ### ctx.getSystemPrompt()
845
992
 
846
- Returns the current effective system prompt. This includes any modifications made by `before_agent_start` handlers for the current turn.
993
+ Returns Pi's current system prompt string.
994
+
995
+ - During `before_agent_start`, this reflects chained system-prompt changes made so far for the current turn.
996
+ - It does not include later `context` message mutations.
997
+ - It does not include `before_provider_request` payload rewrites.
998
+ - If later-loaded extensions run after yours, they can still change what is ultimately sent.
847
999
 
848
1000
  ```typescript
849
1001
  pi.on("before_agent_start", (event, ctx) => {
@@ -856,6 +1008,19 @@ pi.on("before_agent_start", (event, ctx) => {
856
1008
 
857
1009
  Command handlers receive `ExtensionCommandContext`, which extends `ExtensionContext` with session control methods. These are only available in commands because they can deadlock if called from event handlers.
858
1010
 
1011
+ ### ctx.getSystemPromptOptions()
1012
+
1013
+ Returns the base inputs Pi currently uses to build the system prompt.
1014
+
1015
+ ```typescript
1016
+ const options = ctx.getSystemPromptOptions();
1017
+ const contextPaths = options.contextFiles?.map((file) => file.path) ?? [];
1018
+ ```
1019
+
1020
+ This has the same shape and mutability as `before_agent_start` `event.systemPromptOptions`: custom prompt, active tools, tool snippets, prompt guidelines, appended system prompt text, cwd, loaded context files, and loaded skills. It may include full context file contents, so treat it as sensitive extension-local data and avoid exposing it through command lists, logs, or autocomplete metadata.
1021
+
1022
+ This reports the current base prompt inputs. It does not include per-turn `before_agent_start` chained system-prompt changes, later `context` event message mutations, or `before_provider_request` payload rewrites.
1023
+
859
1024
  ### ctx.waitForIdle()
860
1025
 
861
1026
  Wait for the agent to finish streaming:
@@ -874,8 +1039,11 @@ pi.registerCommand("my-cmd", {
874
1039
  Create a new session:
875
1040
 
876
1041
  ```typescript
1042
+ const parentSession = ctx.sessionManager.getSessionFile();
1043
+ const kickoff = "Continue in the replacement session";
1044
+
877
1045
  const result = await ctx.newSession({
878
- parentSession: ctx.sessionManager.getSessionFile(),
1046
+ parentSession,
879
1047
  setup: async (sm) => {
880
1048
  sm.appendMessage({
881
1049
  role: "user",
@@ -883,6 +1051,10 @@ const result = await ctx.newSession({
883
1051
  timestamp: Date.now(),
884
1052
  });
885
1053
  },
1054
+ withSession: async (ctx) => {
1055
+ // Use only the replacement-session ctx here.
1056
+ await ctx.sendUserMessage(kickoff);
1057
+ },
886
1058
  });
887
1059
 
888
1060
  if (result.cancelled) {
@@ -890,17 +1062,37 @@ if (result.cancelled) {
890
1062
  }
891
1063
  ```
892
1064
 
893
- ### ctx.fork(entryId)
1065
+ Options:
1066
+ - `parentSession`: parent session file to record in the new session header
1067
+ - `setup`: mutate the new session's `SessionManager` before `withSession` runs
1068
+ - `withSession`: run post-switch work against a fresh replacement-session context. Do not use captured old `pi` / command `ctx`; see [Session replacement lifecycle and footguns](#session-replacement-lifecycle-and-footguns).
1069
+
1070
+ ### ctx.fork(entryId, options?)
894
1071
 
895
1072
  Fork from a specific entry, creating a new session file:
896
1073
 
897
1074
  ```typescript
898
- const result = await ctx.fork("entry-id-123");
899
- if (!result.cancelled) {
900
- // Now in the forked session
1075
+ const result = await ctx.fork("entry-id-123", {
1076
+ withSession: async (ctx) => {
1077
+ // Use only the replacement-session ctx here.
1078
+ ctx.ui.notify("Now in the forked session", "info");
1079
+ },
1080
+ });
1081
+ if (result.cancelled) {
1082
+ // An extension cancelled the fork
1083
+ }
1084
+
1085
+ const cloneResult = await ctx.fork("entry-id-456", { position: "at" });
1086
+ if (cloneResult.cancelled) {
1087
+ // An extension cancelled the clone
901
1088
  }
902
1089
  ```
903
1090
 
1091
+ Options:
1092
+ - `position`: `"before"` (default) forks before the selected user message, restoring that prompt into the editor
1093
+ - `position`: `"at"` duplicates the active path through the selected entry without restoring editor text
1094
+ - `withSession`: run post-switch work against a fresh replacement-session context. Do not use captured old `pi` / command `ctx`; see [Session replacement lifecycle and footguns](#session-replacement-lifecycle-and-footguns).
1095
+
904
1096
  ### ctx.navigateTree(targetId, options?)
905
1097
 
906
1098
  Navigate to a different point in the session tree:
@@ -920,17 +1112,24 @@ Options:
920
1112
  - `replaceInstructions`: If true, `customInstructions` replaces the default prompt instead of being appended
921
1113
  - `label`: Label to attach to the branch summary entry (or target entry if not summarizing)
922
1114
 
923
- ### ctx.switchSession(sessionPath)
1115
+ ### ctx.switchSession(sessionPath, options?)
924
1116
 
925
1117
  Switch to a different session file:
926
1118
 
927
1119
  ```typescript
928
- const result = await ctx.switchSession("/path/to/session.jsonl");
1120
+ const result = await ctx.switchSession("/path/to/session.jsonl", {
1121
+ withSession: async (ctx) => {
1122
+ await ctx.sendUserMessage("Resume work in the replacement session");
1123
+ },
1124
+ });
929
1125
  if (result.cancelled) {
930
1126
  // An extension cancelled the switch via session_before_switch
931
1127
  }
932
1128
  ```
933
1129
 
1130
+ Options:
1131
+ - `withSession`: run post-switch work against a fresh replacement-session context. Do not use captured old `pi` / command `ctx`; see [Session replacement lifecycle and footguns](#session-replacement-lifecycle-and-footguns).
1132
+
934
1133
  To discover available sessions, use the static `SessionManager.list()` or `SessionManager.listAll()` methods:
935
1134
 
936
1135
  ```typescript
@@ -946,12 +1145,59 @@ pi.registerCommand("switch", {
946
1145
  sessions.map(s => s.file),
947
1146
  );
948
1147
  if (choice) {
949
- await ctx.switchSession(choice);
1148
+ await ctx.switchSession(choice, {
1149
+ withSession: async (ctx) => {
1150
+ ctx.ui.notify("Switched session", "info");
1151
+ },
1152
+ });
950
1153
  }
951
1154
  },
952
1155
  });
953
1156
  ```
954
1157
 
1158
+ ### Session replacement lifecycle and footguns
1159
+
1160
+ `withSession` receives a fresh `ReplacedSessionContext`, which extends `ExtensionCommandContext` with async `sendMessage()` and `sendUserMessage()` helpers bound to the replacement session.
1161
+
1162
+ Lifecycle and footguns:
1163
+ - `withSession` runs only after the old session has emitted `session_shutdown`, the old runtime has been torn down, the replacement session has been rebound, and the new extension instance has already received `session_start`.
1164
+ - The callback still executes in the original closure, not inside the new extension instance. That means your old extension instance may already have run its shutdown cleanup before `withSession` starts.
1165
+ - Captured old `pi` / old command `ctx` session-bound objects are stale after replacement and will throw if used. Use only the `ctx` passed to `withSession` for session-bound work.
1166
+ - Previously extracted raw objects are still your responsibility. For example, if you capture `const sm = ctx.sessionManager` before replacement, `sm` is still the old `SessionManager` object. Do not reuse it after replacement.
1167
+ - Code in `withSession` should assume any state invalidated by your `session_shutdown` handler is already gone. Only capture plain data that survives shutdown cleanly, such as strings, ids, and serialized config.
1168
+
1169
+ Safe pattern:
1170
+
1171
+ ```typescript
1172
+ pi.registerCommand("handoff", {
1173
+ handler: async (_args, ctx) => {
1174
+ const kickoff = "Continue from the replacement session";
1175
+ await ctx.newSession({
1176
+ withSession: async (ctx) => {
1177
+ await ctx.sendUserMessage(kickoff);
1178
+ },
1179
+ });
1180
+ },
1181
+ });
1182
+ ```
1183
+
1184
+ Unsafe pattern:
1185
+
1186
+ ```typescript
1187
+ pi.registerCommand("handoff", {
1188
+ handler: async (_args, ctx) => {
1189
+ const oldSessionManager = ctx.sessionManager;
1190
+ await ctx.newSession({
1191
+ withSession: async (_ctx) => {
1192
+ // stale old objects: do not do this
1193
+ oldSessionManager.getSessionFile();
1194
+ pi.sendUserMessage("wrong");
1195
+ },
1196
+ });
1197
+ },
1198
+ });
1199
+ ```
1200
+
955
1201
  ### ctx.reload()
956
1202
 
957
1203
  Run the same reload flow as `/reload`.
@@ -982,7 +1228,7 @@ Example tool the LLM can call to trigger reload:
982
1228
 
983
1229
  ```typescript
984
1230
  import type { ExtensionAPI } from "@draht/coding-agent";
985
- import { Type } from "@sinclair/typebox";
1231
+ import { Type } from "typebox";
986
1232
 
987
1233
  export default function (pi: ExtensionAPI) {
988
1234
  pi.registerCommand("reload-runtime", {
@@ -1024,10 +1270,12 @@ Use `pi.setActiveTools()` to enable or disable tools (including dynamically adde
1024
1270
 
1025
1271
  Use `promptSnippet` to opt a custom tool into a one-line entry in `Available tools`, and `promptGuidelines` to append tool-specific bullets to the default `Guidelines` section when the tool is active.
1026
1272
 
1273
+ **Important:** `promptGuidelines` bullets are appended flat to the `Guidelines` section with no tool name prefix. Each guideline must name the tool it refers to — avoid "Use this tool when..." because the LLM cannot tell which tool "this" means. Write "Use my_tool when..." instead.
1274
+
1027
1275
  See [dynamic-tools.ts](../examples/extensions/dynamic-tools.ts) for a full example.
1028
1276
 
1029
1277
  ```typescript
1030
- import { Type } from "@sinclair/typebox";
1278
+ import { Type } from "typebox";
1031
1279
  import { StringEnum } from "@draht/ai";
1032
1280
 
1033
1281
  pi.registerTool({
@@ -1035,7 +1283,7 @@ pi.registerTool({
1035
1283
  label: "My Tool",
1036
1284
  description: "What this tool does",
1037
1285
  promptSnippet: "Summarize or transform text according to action",
1038
- promptGuidelines: ["Use this tool when the user asks to summarize previously generated text."],
1286
+ promptGuidelines: ["Use my_tool when the user asks to summarize previously generated text."],
1039
1287
  parameters: Type.Object({
1040
1288
  action: StringEnum(["list", "add"] as const),
1041
1289
  text: Type.Optional(Type.String()),
@@ -1264,7 +1512,7 @@ pi.registerFlag("plan", {
1264
1512
  });
1265
1513
 
1266
1514
  // Check value
1267
- if (pi.getFlag("--plan")) {
1515
+ if (pi.getFlag("plan")) {
1268
1516
  // Plan mode enabled
1269
1517
  }
1270
1518
  ```
@@ -1288,7 +1536,8 @@ const all = pi.getAllTools();
1288
1536
  // [{
1289
1537
  // name: "read",
1290
1538
  // description: "Read file contents...",
1291
- // parameters: ...,
1539
+ // parameters: ...,
1540
+ // promptGuidelines: ["Use read to examine files instead of cat or sed."],
1292
1541
  // sourceInfo: { path: "<builtin:read>", source: "builtin", scope: "temporary", origin: "top-level" }
1293
1542
  // }, ...]
1294
1543
  const names = all.map(t => t.name);
@@ -1297,7 +1546,7 @@ const extensionTools = all.filter((t) => t.sourceInfo.source !== "builtin" && t.
1297
1546
  pi.setActiveTools(["read", "bash"]); // Switch to read-only
1298
1547
  ```
1299
1548
 
1300
- `pi.getAllTools()` returns `name`, `description`, `parameters`, and `sourceInfo`.
1549
+ `pi.getAllTools()` returns `name`, `description`, `parameters`, `promptGuidelines`, and `sourceInfo`.
1301
1550
 
1302
1551
  Typical `sourceInfo.source` values:
1303
1552
  - `builtin` for built-in tools
@@ -1320,7 +1569,7 @@ if (model) {
1320
1569
 
1321
1570
  ### pi.getThinkingLevel() / pi.setThinkingLevel(level)
1322
1571
 
1323
- Get or set the thinking level. Level is clamped to model capabilities (non-reasoning models always use "off").
1572
+ Get or set the thinking level. Level is clamped to model capabilities (non-reasoning models always use "off"). Changes emit `thinking_level_select`.
1324
1573
 
1325
1574
  ```typescript
1326
1575
  const current = pi.getThinkingLevel(); // "off" | "minimal" | "low" | "medium" | "high" | "xhigh"
@@ -1342,11 +1591,14 @@ Register or override a model provider dynamically. Useful for proxies, custom en
1342
1591
 
1343
1592
  Calls made during the extension factory function are queued and applied once the runner initialises. Calls made after that — for example from a command handler following a user setup flow — take effect immediately without requiring a `/reload`.
1344
1593
 
1594
+ If you need to discover models from a remote endpoint, prefer an async extension factory over deferring the fetch to `session_start`. pi waits for the factory before startup continues, so the registered models are available immediately, including to `pi --list-models`.
1595
+
1345
1596
  ```typescript
1346
1597
  // Register a new provider with custom models
1347
1598
  pi.registerProvider("my-proxy", {
1599
+ name: "My Proxy",
1348
1600
  baseUrl: "https://proxy.example.com",
1349
- apiKey: "PROXY_API_KEY", // env var name or literal
1601
+ apiKey: "$PROXY_API_KEY", // env var reference
1350
1602
  api: "anthropic-messages",
1351
1603
  models: [
1352
1604
  {
@@ -1391,12 +1643,13 @@ pi.registerProvider("corporate-ai", {
1391
1643
  ```
1392
1644
 
1393
1645
  **Config options:**
1646
+ - `name` - Display name for the provider in UI such as `/login`.
1394
1647
  - `baseUrl` - API endpoint URL. Required when defining models.
1395
- - `apiKey` - API key or environment variable name. Required when defining models (unless `oauth` provided).
1648
+ - `apiKey` - API key literal, environment interpolation (`$ENV_VAR` or `${ENV_VAR}`), or leading `!command`. Required when defining models (unless `oauth` provided). `$$` escapes `$`, and `$!` escapes a literal `!` without triggering command execution.
1396
1649
  - `api` - API type: `"anthropic-messages"`, `"openai-completions"`, `"openai-responses"`, etc.
1397
1650
  - `headers` - Custom headers to include in requests.
1398
1651
  - `authHeader` - If true, adds `Authorization: Bearer` header automatically.
1399
- - `models` - Array of model definitions. If provided, replaces all existing models for this provider.
1652
+ - `models` - Array of model definitions. If provided, replaces all existing models for this provider. Model definitions can set `baseUrl` to override the provider endpoint for that model.
1400
1653
  - `oauth` - OAuth provider config for `/login` support. When provided, the provider appears in the login menu.
1401
1654
  - `streamSimple` - Custom streaming implementation for non-standard APIs.
1402
1655
 
@@ -1459,6 +1712,8 @@ Use `promptSnippet` for a short one-line entry in the `Available tools` section
1459
1712
 
1460
1713
  Use `promptGuidelines` to add tool-specific bullets to the default system prompt `Guidelines` section. These bullets are included only while the tool is active (for example, after `pi.setActiveTools([...])`).
1461
1714
 
1715
+ **Important:** `promptGuidelines` bullets are appended flat to the `Guidelines` section with no tool name prefix or grouping. Each guideline must name the tool it refers to — avoid "Use this tool when..." because the LLM cannot tell which tool "this" means. Write "Use my_tool when..." instead.
1716
+
1462
1717
  Note: Some models are idiots and include the @ prefix in tool path arguments. Built-in tools strip a leading @ before resolving paths. If your custom tool accepts a path, normalize a leading @ as well.
1463
1718
 
1464
1719
  If your custom tool mutates files, use `withFileMutationQueue()` so it participates in the same per-file queue as built-in `edit` and `write`. This matters because tool calls run in parallel by default. Without the queue, two tools can read the same old file contents, compute different updates, and then whichever write lands last overwrites the other.
@@ -1494,7 +1749,7 @@ async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
1494
1749
  ### Tool Definition
1495
1750
 
1496
1751
  ```typescript
1497
- import { Type } from "@sinclair/typebox";
1752
+ import { Type } from "typebox";
1498
1753
  import { StringEnum } from "@draht/ai";
1499
1754
  import { Text } from "@draht/tui";
1500
1755
 
@@ -1504,7 +1759,7 @@ pi.registerTool({
1504
1759
  description: "What this tool does (shown to LLM)",
1505
1760
  promptSnippet: "List or add items in the project todo list",
1506
1761
  promptGuidelines: [
1507
- "Use this tool for todo planning instead of direct file edits when the user asks for a task list."
1762
+ "Use my_tool for todo planning instead of direct file edits when the user asks for a task list."
1508
1763
  ],
1509
1764
  parameters: Type.Object({
1510
1765
  action: StringEnum(["list", "add"] as const), // Use StringEnum for Google compatibility
@@ -1538,6 +1793,9 @@ pi.registerTool({
1538
1793
  return {
1539
1794
  content: [{ type: "text", text: "Done" }], // Sent to LLM
1540
1795
  details: { data: result }, // For rendering & state
1796
+ // Optional: stop after this tool batch when every finalized tool result
1797
+ // in the batch also returns terminate: true.
1798
+ terminate: true,
1541
1799
  };
1542
1800
  },
1543
1801
 
@@ -1549,6 +1807,8 @@ pi.registerTool({
1549
1807
 
1550
1808
  **Signaling errors:** To mark a tool execution as failed (sets `isError: true` on the result and reports it to the LLM), throw an error from `execute`. Returning a value never sets the error flag regardless of what properties you include in the return object.
1551
1809
 
1810
+ **Early termination:** Return `terminate: true` from `execute()` to hint that the automatic follow-up LLM call should be skipped after the current tool batch. This only takes effect when every finalized tool result in that batch is terminating. See [examples/extensions/structured-output.ts](../examples/extensions/structured-output.ts) for a minimal example where the agent ends on a final structured-output tool call.
1811
+
1552
1812
  ```typescript
1553
1813
  // Correct: throw to signal an error
1554
1814
  async execute(toolCallId, params) {
@@ -1617,10 +1877,10 @@ Extensions can override built-in tools (`read`, `bash`, `edit`, `write`, `grep`,
1617
1877
  pi -e ./tool-override.ts
1618
1878
  ```
1619
1879
 
1620
- Alternatively, use `--no-tools` to start without any built-in tools:
1880
+ Alternatively, use `--no-builtin-tools` to start without any built-in tools while keeping extension tools enabled:
1621
1881
  ```bash
1622
1882
  # No built-in tools, only extension tools
1623
- pi --no-tools -e ./my-extension.ts
1883
+ pi --no-builtin-tools -e ./my-extension.ts
1624
1884
  ```
1625
1885
 
1626
1886
  See [examples/extensions/tool-override.ts](../examples/extensions/tool-override.ts) for a complete example that overrides `read` with logging and access control.
@@ -1632,13 +1892,13 @@ See [examples/extensions/tool-override.ts](../examples/extensions/tool-override.
1632
1892
  **Your implementation must match the exact result shape**, including the `details` type. The UI and session logic depend on these shapes for rendering and state tracking.
1633
1893
 
1634
1894
  Built-in tool implementations:
1635
- - [read.ts](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/core/tools/read.ts) - `ReadToolDetails`
1636
- - [bash.ts](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/core/tools/bash.ts) - `BashToolDetails`
1637
- - [edit.ts](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/core/tools/edit.ts)
1638
- - [write.ts](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/core/tools/write.ts)
1639
- - [grep.ts](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/core/tools/grep.ts) - `GrepToolDetails`
1640
- - [find.ts](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/core/tools/find.ts) - `FindToolDetails`
1641
- - [ls.ts](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/core/tools/ls.ts) - `LsToolDetails`
1895
+ - [read.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/read.ts) - `ReadToolDetails`
1896
+ - [bash.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/bash.ts) - `BashToolDetails`
1897
+ - [edit.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/edit.ts)
1898
+ - [write.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/write.ts)
1899
+ - [grep.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/grep.ts) - `GrepToolDetails`
1900
+ - [find.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/find.ts) - `FindToolDetails`
1901
+ - [ls.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/ls.ts) - `LsToolDetails`
1642
1902
 
1643
1903
  ### Remote Execution
1644
1904
 
@@ -1761,9 +2021,27 @@ export default function (pi: ExtensionAPI) {
1761
2021
 
1762
2022
  ### Custom Rendering
1763
2023
 
1764
- Tools can provide `renderCall` and `renderResult` for custom TUI display. See [tui.md](tui.md) for the full component API and [tool-execution.ts](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/modes/interactive/components/tool-execution.ts) for how tool rows are composed.
2024
+ Tools can provide `renderCall` and `renderResult` for custom TUI display. See [tui.md](tui.md) for the full component API and [tool-execution.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/modes/interactive/components/tool-execution.ts) for how tool rows are composed.
2025
+
2026
+ By default, tool output is wrapped in a `Box` that handles padding and background. A defined `renderCall` or `renderResult` must return a `Component`. If a slot renderer is not defined, `tool-execution.ts` uses fallback rendering for that slot.
1765
2027
 
1766
- Tool output is wrapped in a `Box` that handles padding and background. A defined `renderCall` or `renderResult` must return a `Component`. If a slot renderer is not defined, `tool-execution.ts` uses fallback rendering for that slot.
2028
+ Set `renderShell: "self"` when the tool should render its own shell instead of using the default `Box`. This is useful for tools that need complete control over framing or background behavior, for example large previews that must stay visually stable after the tool settles.
2029
+
2030
+ ```typescript
2031
+ pi.registerTool({
2032
+ name: "my_tool",
2033
+ label: "My Tool",
2034
+ description: "Custom shell example",
2035
+ parameters: Type.Object({}),
2036
+ renderShell: "self",
2037
+ async execute() {
2038
+ return { content: [{ type: "text", text: "ok" }], details: undefined };
2039
+ },
2040
+ renderCall(args, theme, context) {
2041
+ return new Text(theme.fg("accent", "my custom shell"), 0, 0);
2042
+ },
2043
+ });
2044
+ ```
1767
2045
 
1768
2046
  `renderCall` and `renderResult` each receive a `context` object with:
1769
2047
  - `args` - the current tool call arguments
@@ -1850,7 +2128,7 @@ Custom editors and `ctx.ui.custom()` components receive `keybindings: Keybinding
1850
2128
 
1851
2129
  #### Best Practices
1852
2130
 
1853
- - Use `Text` with padding `(0, 0)`. The Box handles padding.
2131
+ - Use `Text` with padding `(0, 0)`. The default Box handles padding.
1854
2132
  - Use `\n` for multi-line content.
1855
2133
  - Handle `isPartial` for streaming progress.
1856
2134
  - Support `expanded` for detail on demand.
@@ -1858,6 +2136,7 @@ Custom editors and `ctx.ui.custom()` components receive `keybindings: Keybinding
1858
2136
  - Read `context.args` in `renderResult` instead of copying args into `context.state`.
1859
2137
  - Use `context.state` only for data that must be shared across call and result slots.
1860
2138
  - Reuse `context.lastComponent` when the same component instance can be updated in place.
2139
+ - Use `renderShell: "self"` only when the default boxed shell gets in the way. In self-shell mode the tool is responsible for its own framing, padding, and background.
1861
2140
 
1862
2141
  #### Fallback
1863
2142
 
@@ -1874,8 +2153,9 @@ Extensions can interact with users via `ctx.ui` methods and customize how messag
1874
2153
  - Async operations with cancel (BorderedLoader)
1875
2154
  - Settings toggles (SettingsList)
1876
2155
  - Status indicators (setStatus)
1877
- - Working message during streaming (setWorkingMessage)
2156
+ - Working message, visibility, and indicator during streaming (`setWorkingMessage`, `setWorkingVisible`, `setWorkingIndicator`)
1878
2157
  - Widgets above/below editor (setWidget)
2158
+ - Autocomplete providers layered on top of built-in slash/path completion (addAutocompleteProvider)
1879
2159
  - Custom footers (setFooter)
1880
2160
 
1881
2161
  ### Dialogs
@@ -1955,9 +2235,25 @@ See [examples/extensions/timed-confirm.ts](../examples/extensions/timed-confirm.
1955
2235
  ctx.ui.setStatus("my-ext", "Processing...");
1956
2236
  ctx.ui.setStatus("my-ext", undefined); // Clear
1957
2237
 
1958
- // Working message (shown during streaming)
2238
+ // Working loader (shown during streaming)
1959
2239
  ctx.ui.setWorkingMessage("Thinking deeply...");
1960
2240
  ctx.ui.setWorkingMessage(); // Restore default
2241
+ ctx.ui.setWorkingVisible(false); // Hide the built-in working loader row entirely
2242
+ ctx.ui.setWorkingVisible(true); // Show the built-in working loader row
2243
+
2244
+ // Working indicator (shown during streaming)
2245
+ ctx.ui.setWorkingIndicator({ frames: [ctx.ui.theme.fg("accent", "●")] }); // Static dot
2246
+ ctx.ui.setWorkingIndicator({
2247
+ frames: [
2248
+ ctx.ui.theme.fg("dim", "·"),
2249
+ ctx.ui.theme.fg("muted", "•"),
2250
+ ctx.ui.theme.fg("accent", "●"),
2251
+ ctx.ui.theme.fg("muted", "•"),
2252
+ ],
2253
+ intervalMs: 120,
2254
+ });
2255
+ ctx.ui.setWorkingIndicator({ frames: [] }); // Hide indicator
2256
+ ctx.ui.setWorkingIndicator(); // Restore default spinner
1961
2257
 
1962
2258
  // Widget above editor (default)
1963
2259
  ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"]);
@@ -1983,6 +2279,29 @@ const current = ctx.ui.getEditorText();
1983
2279
  // Paste into editor (triggers paste handling, including collapse for large content)
1984
2280
  ctx.ui.pasteToEditor("pasted content");
1985
2281
 
2282
+ // Stack custom autocomplete behavior on top of the built-in provider
2283
+ ctx.ui.addAutocompleteProvider((current) => ({
2284
+ triggerCharacters: ["#"],
2285
+ async getSuggestions(lines, line, col, options) {
2286
+ const beforeCursor = (lines[line] ?? "").slice(0, col);
2287
+ const match = beforeCursor.match(/(?:^|[ \t])#([^\s#]*)$/);
2288
+ if (!match) {
2289
+ return current.getSuggestions(lines, line, col, options);
2290
+ }
2291
+
2292
+ return {
2293
+ prefix: `#${match[1] ?? ""}`,
2294
+ items: [{ value: "#2983", label: "#2983", description: "Extension API for autocomplete" }],
2295
+ };
2296
+ },
2297
+ applyCompletion(lines, line, col, item, prefix) {
2298
+ return current.applyCompletion(lines, line, col, item, prefix);
2299
+ },
2300
+ shouldTriggerFileCompletion(lines, line, col) {
2301
+ return current.shouldTriggerFileCompletion?.(lines, line, col) ?? true;
2302
+ },
2303
+ }));
2304
+
1986
2305
  // Tool output expansion
1987
2306
  const wasExpanded = ctx.ui.getToolsExpanded();
1988
2307
  ctx.ui.setToolsExpanded(true);
@@ -1990,6 +2309,10 @@ ctx.ui.setToolsExpanded(wasExpanded);
1990
2309
 
1991
2310
  // Custom editor (vim mode, emacs mode, etc.)
1992
2311
  ctx.ui.setEditorComponent((tui, theme, keybindings) => new VimEditor(tui, theme, keybindings));
2312
+ const currentEditor = ctx.ui.getEditorComponent();
2313
+ ctx.ui.setEditorComponent((tui, theme, keybindings) =>
2314
+ new WrappedEditor(tui, theme, keybindings, currentEditor?.(tui, theme, keybindings))
2315
+ );
1993
2316
  ctx.ui.setEditorComponent(undefined); // Restore default editor
1994
2317
 
1995
2318
  // Theme management (see themes.md for creating themes)
@@ -2003,6 +2326,53 @@ ctx.ui.setTheme(lightTheme!); // Or switch by Theme object
2003
2326
  ctx.ui.theme.fg("accent", "styled text"); // Access current theme
2004
2327
  ```
2005
2328
 
2329
+ Custom working-indicator frames are rendered verbatim. If you want colors, add them to the frame strings yourself, for example with `ctx.ui.theme.fg(...)`.
2330
+
2331
+ ### Autocomplete Providers
2332
+
2333
+ Use `ctx.ui.addAutocompleteProvider()` to stack custom autocomplete logic on top of the built-in slash-command and path provider. Set `triggerCharacters` for custom natural triggers such as `$`.
2334
+
2335
+ Typical pattern:
2336
+
2337
+ - inspect the text before the cursor
2338
+ - return your own suggestions when your extension-specific syntax matches
2339
+ - otherwise delegate to `current.getSuggestions(...)`
2340
+ - delegate `applyCompletion(...)` unless you need custom insertion behavior
2341
+
2342
+ ```typescript
2343
+ pi.on("session_start", (_event, ctx) => {
2344
+ ctx.ui.addAutocompleteProvider((current) => ({
2345
+ triggerCharacters: ["#"],
2346
+ async getSuggestions(lines, cursorLine, cursorCol, options) {
2347
+ const line = lines[cursorLine] ?? "";
2348
+ const beforeCursor = line.slice(0, cursorCol);
2349
+ const match = beforeCursor.match(/(?:^|[ \t])#([^\s#]*)$/);
2350
+ if (!match) {
2351
+ return current.getSuggestions(lines, cursorLine, cursorCol, options);
2352
+ }
2353
+
2354
+ return {
2355
+ prefix: `#${match[1] ?? ""}`,
2356
+ items: [
2357
+ { value: "#2983", label: "#2983", description: "Extension API for registering custom @ autocomplete providers" },
2358
+ { value: "#2753", label: "#2753", description: "Reload stale resource settings" },
2359
+ ],
2360
+ };
2361
+ },
2362
+
2363
+ applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
2364
+ return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
2365
+ },
2366
+
2367
+ shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
2368
+ return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
2369
+ },
2370
+ }));
2371
+ });
2372
+ ```
2373
+
2374
+ See [github-issue-autocomplete.ts](../examples/extensions/github-issue-autocomplete.ts) for a complete example that preloads the latest open GitHub issues with `gh issue list` and filters them locally for fast `#...` completion. It requires GitHub CLI (`gh`) and a GitHub repository checkout.
2375
+
2006
2376
  ### Custom Components
2007
2377
 
2008
2378
  For complex UI, use `ctx.ui.custom()`. This temporarily replaces the editor with your component until `done()` is called:
@@ -2046,7 +2416,7 @@ const result = await ctx.ui.custom<string | null>(
2046
2416
  );
2047
2417
  ```
2048
2418
 
2049
- For advanced positioning (anchors, margins, percentages, responsive visibility), pass `overlayOptions`. Use `onHandle` to control visibility programmatically:
2419
+ For advanced positioning (anchors, margins, percentages, responsive visibility), pass `overlayOptions`. Use `onHandle` to control focus or visibility programmatically:
2050
2420
 
2051
2421
  ```typescript
2052
2422
  const result = await ctx.ui.custom<string | null>(
@@ -2054,12 +2424,19 @@ const result = await ctx.ui.custom<string | null>(
2054
2424
  {
2055
2425
  overlay: true,
2056
2426
  overlayOptions: { anchor: "top-right", width: "50%", margin: 2 },
2057
- onHandle: (handle) => { /* handle.setHidden(true/false) */ }
2427
+ onHandle: (handle) => {
2428
+ handle.focus(); // focus this overlay and bring it to the visual front
2429
+ // handle.unfocus({ target: editorComponent }); // release input to a specific component
2430
+ // handle.setHidden(true/false); // toggle visibility
2431
+ // handle.hide(); // permanently remove
2432
+ }
2058
2433
  }
2059
2434
  );
2060
2435
  ```
2061
2436
 
2062
- See [tui.md](tui.md) for the full `OverlayOptions` API and [overlay-qa-tests.ts](../examples/extensions/overlay-qa-tests.ts) for examples.
2437
+ A focused visible overlay can reclaim input after temporary non-overlay custom UI closes. If you intentionally want another component to keep input while the overlay stays visible, call `handle.unfocus({ target })`. Passing `{ target: null }` releases the overlay without focusing another component.
2438
+
2439
+ See [tui.md](tui.md) for the full `OverlayOptions` and `OverlayHandle` API and [overlay-qa-tests.ts](../examples/extensions/overlay-qa-tests.ts) for examples.
2063
2440
 
2064
2441
  ### Custom Editor
2065
2442
 
@@ -2098,8 +2475,18 @@ export default function (pi: ExtensionAPI) {
2098
2475
  - Extend `CustomEditor` (not base `Editor`) to get app keybindings (escape to abort, ctrl+d, model switching)
2099
2476
  - Call `super.handleInput(data)` for keys you don't handle
2100
2477
  - Factory receives `theme` and `keybindings` from the app
2478
+ - Use `ctx.ui.getEditorComponent()` before `setEditorComponent()` to wrap the previously configured custom editor
2101
2479
  - Pass `undefined` to restore default: `ctx.ui.setEditorComponent(undefined)`
2102
2480
 
2481
+ To compose with another extension that already replaced the editor, capture the previous factory before setting yours:
2482
+
2483
+ ```typescript
2484
+ const previous = ctx.ui.getEditorComponent();
2485
+ ctx.ui.setEditorComponent((tui, theme, keybindings) =>
2486
+ new MyEditor(tui, theme, keybindings, { base: previous?.(tui, theme, keybindings) })
2487
+ );
2488
+ ```
2489
+
2103
2490
  See [tui.md](tui.md) Pattern 7 for a complete example with mode indicator.
2104
2491
 
2105
2492
  ### Message Rendering
@@ -2174,14 +2561,14 @@ const highlighted = highlightCode(code, lang, theme);
2174
2561
 
2175
2562
  ## Mode Behavior
2176
2563
 
2177
- | Mode | UI Methods | Notes |
2178
- |------|-----------|-------|
2179
- | Interactive | Full TUI | Normal operation |
2180
- | RPC (`--mode rpc`) | JSON protocol | Host handles UI, see [rpc.md](rpc.md) |
2181
- | JSON (`--mode json`) | No-op | Event stream to stdout, see [json.md](json.md) |
2182
- | Print (`-p`) | No-op | Extensions run but can't prompt |
2564
+ | Mode | `ctx.mode` | `ctx.hasUI` | Notes |
2565
+ |------|------------|-------------|-------|
2566
+ | Interactive | `"tui"` | `true` | Full TUI with terminal rendering |
2567
+ | RPC (`--mode rpc`) | `"rpc"` | `true` | Dialogs and notifications via JSON protocol; `custom()` returns `undefined`. See [rpc.md](rpc.md) |
2568
+ | JSON (`--mode json`) | `"json"` | `false` | Event stream to stdout; UI methods are no-ops |
2569
+ | Print (`-p`) | `"print"` | `false` | Extensions run but can't prompt |
2183
2570
 
2184
- In non-interactive modes, check `ctx.hasUI` before using UI methods.
2571
+ Use `ctx.mode === "tui"` before TUI-specific features (`custom()`, component factories, terminal input). Use `ctx.hasUI` before dialog and notification methods that work in both TUI and RPC modes.
2185
2572
 
2186
2573
  ## Examples Reference
2187
2574
 
@@ -2195,6 +2582,7 @@ All examples in [examples/extensions/](../examples/extensions/).
2195
2582
  | `questionnaire.ts` | Multi-step wizard tool | `registerTool`, `ui.custom` |
2196
2583
  | `todo.ts` | Stateful tool with persistence | `registerTool`, `appendEntry`, `renderResult`, session events |
2197
2584
  | `dynamic-tools.ts` | Register tools after startup and during commands | `registerTool`, `session_start`, `registerCommand` |
2585
+ | `structured-output.ts` | Final structured-output tool with `terminate: true` | `registerTool`, terminating tool results |
2198
2586
  | `truncated-tool.ts` | Output truncation example | `registerTool`, `truncateHead` |
2199
2587
  | `tool-override.ts` | Override built-in read tool | `registerTool` (same name as built-in) |
2200
2588
  | **Commands** |||
@@ -2207,22 +2595,28 @@ All examples in [examples/extensions/](../examples/extensions/).
2207
2595
  | `shutdown-command.ts` | Graceful shutdown command | `registerCommand`, `shutdown()` |
2208
2596
  | **Events & Gates** |||
2209
2597
  | `permission-gate.ts` | Block dangerous commands | `on("tool_call")`, `ui.confirm` |
2598
+ | `project-trust.ts` | Decide or defer project trust from a user/global or CLI extension | `on("project_trust")`, trust UI, required trust result |
2210
2599
  | `protected-paths.ts` | Block writes to specific paths | `on("tool_call")` |
2211
2600
  | `confirm-destructive.ts` | Confirm session changes | `on("session_before_switch")`, `on("session_before_fork")` |
2212
2601
  | `dirty-repo-guard.ts` | Warn on dirty git repo | `on("session_before_*")`, `exec` |
2213
2602
  | `input-transform.ts` | Transform user input | `on("input")` |
2603
+ | `input-transform-streaming.ts` | Streaming-aware input transform | `on("input")`, `streamingBehavior` |
2214
2604
  | `model-status.ts` | React to model changes | `on("model_select")`, `setStatus` |
2215
- | `provider-payload.ts` | Inspect or patch provider payloads | `on("before_provider_request")` |
2605
+ | `provider-payload.ts` | Inspect payloads and provider response headers | `on("before_provider_request")`, `on("after_provider_response")` |
2216
2606
  | `system-prompt-header.ts` | Display system prompt info | `on("agent_start")`, `getSystemPrompt` |
2217
2607
  | `claude-rules.ts` | Load rules from files | `on("session_start")`, `on("before_agent_start")` |
2608
+ | `prompt-customizer.ts` | Add context-aware tool guidance using `systemPromptOptions` | `on("before_agent_start")`, `BuildSystemPromptOptions` |
2218
2609
  | `file-trigger.ts` | File watcher triggers messages | `sendMessage` |
2219
2610
  | **Compaction & Sessions** |||
2220
2611
  | `custom-compaction.ts` | Custom compaction summary | `on("session_before_compact")` |
2221
2612
  | `trigger-compact.ts` | Trigger compaction manually | `compact()` |
2222
2613
  | `git-checkpoint.ts` | Git stash on turns | `on("turn_start")`, `on("session_before_fork")`, `exec` |
2614
+ | `git-merge-and-resolve.ts` | Fetch, merge, and resolve conflicts | `on("agent_end")`, `exec`, `sendUserMessage` |
2223
2615
  | `auto-commit-on-exit.ts` | Commit on shutdown | `on("session_shutdown")`, `exec` |
2224
2616
  | **UI Components** |||
2225
2617
  | `status-line.ts` | Footer status indicator | `setStatus`, session events |
2618
+ | `working-indicator.ts` | Customize the streaming working indicator | `setWorkingIndicator`, `registerCommand` |
2619
+ | `github-issue-autocomplete.ts` | Add `#1234` issue completions on top of built-in autocomplete by preloading recent open issues from `gh issue list` | `addAutocompleteProvider`, `on("session_start")`, `exec` |
2226
2620
  | `custom-footer.ts` | Replace footer entirely | `registerCommand`, `setFooter` |
2227
2621
  | `custom-header.ts` | Replace startup header | `on("session_start")`, `setHeader` |
2228
2622
  | `modal-editor.ts` | Vim-style modal editor | `setEditorComponent`, `CustomEditor` |
@@ -2241,6 +2635,7 @@ All examples in [examples/extensions/](../examples/extensions/).
2241
2635
  | `ssh.ts` | SSH remote execution | `registerFlag`, `on("user_bash")`, `on("before_agent_start")`, tool operations |
2242
2636
  | `interactive-shell.ts` | Persistent shell session | `on("user_bash")` |
2243
2637
  | `sandbox/` | Sandboxed tool execution | Tool operations |
2638
+ | `gondolin/` | Route built-in tools and `!` commands into a Gondolin micro-VM | Tool operations, built-in tool overrides, `on("user_bash")` |
2244
2639
  | `subagent/` | Spawn sub-agents | `registerTool`, `exec` |
2245
2640
  | **Games** |||
2246
2641
  | `snake.ts` | Snake game | `registerCommand`, `ui.custom`, keyboard handling |
@@ -2256,7 +2651,6 @@ All examples in [examples/extensions/](../examples/extensions/).
2256
2651
  | `session-name.ts` | Name sessions for selector | `setSessionName`, `getSessionName` |
2257
2652
  | `bookmark.ts` | Bookmark entries for /tree | `setLabel` |
2258
2653
  | **Misc** |||
2259
- | `antigravity-image-gen.ts` | Image generation tool | `registerTool`, Google Antigravity |
2260
2654
  | `inline-bash.ts` | Inline bash in tool calls | `on("tool_call")` |
2261
2655
  | `bash-spawn-hook.ts` | Adjust bash command, cwd, and env before execution | `createBashTool`, `spawnHook` |
2262
2656
  | `with-deps/` | Extension with npm dependencies | Package structure with `package.json` |