@draht/coding-agent 2026.5.12 → 2026.7.7-1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (680) hide show
  1. package/CHANGELOG.md +47 -0
  2. package/README.md +1 -4
  3. package/bin/draht-tools.cjs +3756 -1
  4. package/dist/bun/cli.d.ts.map +1 -1
  5. package/dist/bun/cli.js +4 -2
  6. package/dist/bun/cli.js.map +1 -1
  7. package/dist/bun/register-bedrock.d.ts.map +1 -1
  8. package/dist/bun/register-bedrock.js +1 -1
  9. package/dist/bun/register-bedrock.js.map +1 -1
  10. package/dist/bun/restore-sandbox-env.d.ts +17 -0
  11. package/dist/bun/restore-sandbox-env.d.ts.map +1 -0
  12. package/dist/bun/restore-sandbox-env.js +36 -0
  13. package/dist/bun/restore-sandbox-env.js.map +1 -0
  14. package/dist/cli/args.d.ts +9 -4
  15. package/dist/cli/args.d.ts.map +1 -1
  16. package/dist/cli/args.js +91 -38
  17. package/dist/cli/args.js.map +1 -1
  18. package/dist/cli/config-selector.d.ts +5 -3
  19. package/dist/cli/config-selector.d.ts.map +1 -1
  20. package/dist/cli/config-selector.js +1 -1
  21. package/dist/cli/config-selector.js.map +1 -1
  22. package/dist/cli/file-processor.d.ts.map +1 -1
  23. package/dist/cli/file-processor.js +13 -26
  24. package/dist/cli/file-processor.js.map +1 -1
  25. package/dist/cli/initial-message.d.ts +1 -1
  26. package/dist/cli/initial-message.d.ts.map +1 -1
  27. package/dist/cli/initial-message.js.map +1 -1
  28. package/dist/cli/list-models.d.ts +1 -1
  29. package/dist/cli/list-models.d.ts.map +1 -1
  30. package/dist/cli/list-models.js +7 -1
  31. package/dist/cli/list-models.js.map +1 -1
  32. package/dist/cli/project-trust.d.ts +10 -0
  33. package/dist/cli/project-trust.d.ts.map +1 -0
  34. package/dist/cli/project-trust.js +48 -0
  35. package/dist/cli/project-trust.js.map +1 -0
  36. package/dist/cli/session-picker.d.ts +3 -2
  37. package/dist/cli/session-picker.d.ts.map +1 -1
  38. package/dist/cli/session-picker.js +5 -4
  39. package/dist/cli/session-picker.js.map +1 -1
  40. package/dist/cli/startup-ui.d.ts +20 -0
  41. package/dist/cli/startup-ui.d.ts.map +1 -0
  42. package/dist/cli/startup-ui.js +184 -0
  43. package/dist/cli/startup-ui.js.map +1 -0
  44. package/dist/cli.d.ts.map +1 -1
  45. package/dist/cli.js +7 -4
  46. package/dist/cli.js.map +1 -1
  47. package/dist/config.d.ts +27 -13
  48. package/dist/config.d.ts.map +1 -1
  49. package/dist/config.js +284 -63
  50. package/dist/config.js.map +1 -1
  51. package/dist/core/agent-session-runtime.d.ts +45 -9
  52. package/dist/core/agent-session-runtime.d.ts.map +1 -1
  53. package/dist/core/agent-session-runtime.js +100 -33
  54. package/dist/core/agent-session-runtime.js.map +1 -1
  55. package/dist/core/agent-session-services.d.ts +6 -4
  56. package/dist/core/agent-session-services.d.ts.map +1 -1
  57. package/dist/core/agent-session-services.js +7 -4
  58. package/dist/core/agent-session-services.js.map +1 -1
  59. package/dist/core/agent-session.d.ts +55 -33
  60. package/dist/core/agent-session.d.ts.map +1 -1
  61. package/dist/core/agent-session.js +560 -492
  62. package/dist/core/agent-session.js.map +1 -1
  63. package/dist/core/auth-guidance.d.ts +5 -0
  64. package/dist/core/auth-guidance.d.ts.map +1 -0
  65. package/dist/core/auth-guidance.js +21 -0
  66. package/dist/core/auth-guidance.js.map +1 -0
  67. package/dist/core/auth-storage.d.ts +21 -13
  68. package/dist/core/auth-storage.d.ts.map +1 -1
  69. package/dist/core/auth-storage.js +48 -28
  70. package/dist/core/auth-storage.js.map +1 -1
  71. package/dist/core/bash-executor.d.ts +1 -15
  72. package/dist/core/bash-executor.d.ts.map +1 -1
  73. package/dist/core/bash-executor.js +10 -24
  74. package/dist/core/bash-executor.js.map +1 -1
  75. package/dist/core/builtins/subagent.d.ts.map +1 -1
  76. package/dist/core/builtins/subagent.js +1 -2
  77. package/dist/core/builtins/subagent.js.map +1 -1
  78. package/dist/core/compaction/branch-summarization.d.ts +9 -5
  79. package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
  80. package/dist/core/compaction/branch-summarization.js +10 -4
  81. package/dist/core/compaction/branch-summarization.js.map +1 -1
  82. package/dist/core/compaction/compaction.d.ts +8 -7
  83. package/dist/core/compaction/compaction.d.ts.map +1 -1
  84. package/dist/core/compaction/compaction.js +56 -47
  85. package/dist/core/compaction/compaction.js.map +1 -1
  86. package/dist/core/compaction/index.d.ts +3 -3
  87. package/dist/core/compaction/index.d.ts.map +1 -1
  88. package/dist/core/compaction/index.js.map +1 -1
  89. package/dist/core/compaction/utils.d.ts +1 -1
  90. package/dist/core/compaction/utils.d.ts.map +1 -1
  91. package/dist/core/compaction/utils.js +1 -1
  92. package/dist/core/compaction/utils.js.map +1 -1
  93. package/dist/core/exec.d.ts.map +1 -1
  94. package/dist/core/exec.js.map +1 -1
  95. package/dist/core/experimental.d.ts +2 -0
  96. package/dist/core/experimental.d.ts.map +1 -0
  97. package/dist/core/experimental.js +4 -0
  98. package/dist/core/experimental.js.map +1 -0
  99. package/dist/core/export-html/ansi-to-html.d.ts.map +1 -1
  100. package/dist/core/export-html/ansi-to-html.js +1 -1
  101. package/dist/core/export-html/ansi-to-html.js.map +1 -1
  102. package/dist/core/export-html/index.d.ts +1 -1
  103. package/dist/core/export-html/index.d.ts.map +1 -1
  104. package/dist/core/export-html/index.js +13 -11
  105. package/dist/core/export-html/index.js.map +1 -1
  106. package/dist/core/export-html/template.css +69 -4
  107. package/dist/core/export-html/template.js +231 -57
  108. package/dist/core/export-html/tool-renderer.d.ts +0 -6
  109. package/dist/core/export-html/tool-renderer.d.ts.map +1 -1
  110. package/dist/core/export-html/tool-renderer.js +15 -2
  111. package/dist/core/export-html/tool-renderer.js.map +1 -1
  112. package/dist/core/export-html/vendor/marked.min.js +75 -3
  113. package/dist/core/extensions/index.d.ts +8 -8
  114. package/dist/core/extensions/index.d.ts.map +1 -1
  115. package/dist/core/extensions/index.js.map +1 -1
  116. package/dist/core/extensions/loader.d.ts +5 -6
  117. package/dist/core/extensions/loader.d.ts.map +1 -1
  118. package/dist/core/extensions/loader.js +98 -43
  119. package/dist/core/extensions/loader.js.map +1 -1
  120. package/dist/core/extensions/runner.d.ts +31 -12
  121. package/dist/core/extensions/runner.d.ts.map +1 -1
  122. package/dist/core/extensions/runner.js +248 -33
  123. package/dist/core/extensions/runner.js.map +1 -1
  124. package/dist/core/extensions/types.d.ts +191 -36
  125. package/dist/core/extensions/types.d.ts.map +1 -1
  126. package/dist/core/extensions/types.js.map +1 -1
  127. package/dist/core/extensions/wrapper.d.ts.map +1 -1
  128. package/dist/core/extensions/wrapper.js +2 -2
  129. package/dist/core/extensions/wrapper.js.map +1 -1
  130. package/dist/core/footer-data-provider.d.ts +7 -1
  131. package/dist/core/footer-data-provider.d.ts.map +1 -1
  132. package/dist/core/footer-data-provider.js +78 -54
  133. package/dist/core/footer-data-provider.js.map +1 -1
  134. package/dist/core/http-dispatcher.d.ts +22 -0
  135. package/dist/core/http-dispatcher.d.ts.map +1 -0
  136. package/dist/core/http-dispatcher.js +91 -0
  137. package/dist/core/http-dispatcher.js.map +1 -0
  138. package/dist/core/index.d.ts +9 -8
  139. package/dist/core/index.d.ts.map +1 -1
  140. package/dist/core/index.js +2 -1
  141. package/dist/core/index.js.map +1 -1
  142. package/dist/core/keybindings.d.ts +67 -2
  143. package/dist/core/keybindings.d.ts.map +1 -1
  144. package/dist/core/keybindings.js +59 -7
  145. package/dist/core/keybindings.js.map +1 -1
  146. package/dist/core/model-registry.d.ts +24 -5
  147. package/dist/core/model-registry.d.ts.map +1 -1
  148. package/dist/core/model-registry.js +188 -51
  149. package/dist/core/model-registry.js.map +1 -1
  150. package/dist/core/model-resolver.d.ts +12 -1
  151. package/dist/core/model-resolver.d.ts.map +1 -1
  152. package/dist/core/model-resolver.js +84 -39
  153. package/dist/core/model-resolver.js.map +1 -1
  154. package/dist/core/output-guard.d.ts +1 -0
  155. package/dist/core/output-guard.d.ts.map +1 -1
  156. package/dist/core/output-guard.js +52 -22
  157. package/dist/core/output-guard.js.map +1 -1
  158. package/dist/core/package-manager.d.ts +22 -4
  159. package/dist/core/package-manager.d.ts.map +1 -1
  160. package/dist/core/package-manager.js +455 -157
  161. package/dist/core/package-manager.js.map +1 -1
  162. package/dist/core/project-trust.d.ts +15 -0
  163. package/dist/core/project-trust.d.ts.map +1 -0
  164. package/dist/core/project-trust.js +59 -0
  165. package/dist/core/project-trust.js.map +1 -0
  166. package/dist/core/prompt-templates.d.ts +13 -11
  167. package/dist/core/prompt-templates.d.ts.map +1 -1
  168. package/dist/core/prompt-templates.js +67 -76
  169. package/dist/core/prompt-templates.js.map +1 -1
  170. package/dist/core/provider-attribution.d.ts +4 -0
  171. package/dist/core/provider-attribution.d.ts.map +1 -0
  172. package/dist/core/provider-attribution.js +72 -0
  173. package/dist/core/provider-attribution.js.map +1 -0
  174. package/dist/core/provider-display-names.d.ts +2 -0
  175. package/dist/core/provider-display-names.d.ts.map +1 -0
  176. package/dist/core/provider-display-names.js +36 -0
  177. package/dist/core/provider-display-names.js.map +1 -0
  178. package/dist/core/resolve-config-value.d.ts +13 -6
  179. package/dist/core/resolve-config-value.d.ts.map +1 -1
  180. package/dist/core/resolve-config-value.js +143 -22
  181. package/dist/core/resolve-config-value.js.map +1 -1
  182. package/dist/core/resource-loader.d.ts +36 -15
  183. package/dist/core/resource-loader.d.ts.map +1 -1
  184. package/dist/core/resource-loader.js +178 -79
  185. package/dist/core/resource-loader.js.map +1 -1
  186. package/dist/core/sdk.d.ts +34 -18
  187. package/dist/core/sdk.d.ts.map +1 -1
  188. package/dist/core/sdk.js +47 -16
  189. package/dist/core/sdk.js.map +1 -1
  190. package/dist/core/session-manager.d.ts +32 -14
  191. package/dist/core/session-manager.d.ts.map +1 -1
  192. package/dist/core/session-manager.js +366 -209
  193. package/dist/core/session-manager.js.map +1 -1
  194. package/dist/core/settings-manager.d.ts +62 -6
  195. package/dist/core/settings-manager.d.ts.map +1 -1
  196. package/dist/core/settings-manager.js +230 -40
  197. package/dist/core/settings-manager.js.map +1 -1
  198. package/dist/core/skills.d.ts +10 -10
  199. package/dist/core/skills.d.ts.map +1 -1
  200. package/dist/core/skills.js +13 -35
  201. package/dist/core/skills.js.map +1 -1
  202. package/dist/core/slash-commands.d.ts +1 -1
  203. package/dist/core/slash-commands.d.ts.map +1 -1
  204. package/dist/core/slash-commands.js +7 -4
  205. package/dist/core/slash-commands.js.map +1 -1
  206. package/dist/core/source-info.d.ts +1 -1
  207. package/dist/core/source-info.d.ts.map +1 -1
  208. package/dist/core/source-info.js.map +1 -1
  209. package/dist/core/system-prompt.d.ts +4 -4
  210. package/dist/core/system-prompt.d.ts.map +1 -1
  211. package/dist/core/system-prompt.js +20 -16
  212. package/dist/core/system-prompt.js.map +1 -1
  213. package/dist/core/telemetry.d.ts +3 -0
  214. package/dist/core/telemetry.d.ts.map +1 -0
  215. package/dist/core/telemetry.js +9 -0
  216. package/dist/core/telemetry.js.map +1 -0
  217. package/dist/core/timings.d.ts +4 -2
  218. package/dist/core/timings.d.ts.map +1 -1
  219. package/dist/core/timings.js +24 -14
  220. package/dist/core/timings.js.map +1 -1
  221. package/dist/core/tools/bash.d.ts +11 -16
  222. package/dist/core/tools/bash.d.ts.map +1 -1
  223. package/dist/core/tools/bash.js +187 -178
  224. package/dist/core/tools/bash.js.map +1 -1
  225. package/dist/core/tools/edit-diff.d.ts +26 -5
  226. package/dist/core/tools/edit-diff.d.ts.map +1 -1
  227. package/dist/core/tools/edit-diff.js +110 -23
  228. package/dist/core/tools/edit-diff.js.map +1 -1
  229. package/dist/core/tools/edit.d.ts +22 -24
  230. package/dist/core/tools/edit.d.ts.map +1 -1
  231. package/dist/core/tools/edit.js +201 -113
  232. package/dist/core/tools/edit.js.map +1 -1
  233. package/dist/core/tools/file-mutation-queue.d.ts.map +1 -1
  234. package/dist/core/tools/file-mutation-queue.js +27 -12
  235. package/dist/core/tools/file-mutation-queue.js.map +1 -1
  236. package/dist/core/tools/find.d.ts +7 -18
  237. package/dist/core/tools/find.d.ts.map +1 -1
  238. package/dist/core/tools/find.js +148 -101
  239. package/dist/core/tools/find.js.map +1 -1
  240. package/dist/core/tools/grep.d.ts +11 -30
  241. package/dist/core/tools/grep.d.ts.map +1 -1
  242. package/dist/core/tools/grep.js +23 -12
  243. package/dist/core/tools/grep.js.map +1 -1
  244. package/dist/core/tools/index.d.ts +26 -101
  245. package/dist/core/tools/index.d.ts.map +1 -1
  246. package/dist/core/tools/index.js +78 -52
  247. package/dist/core/tools/index.js.map +1 -1
  248. package/dist/core/tools/ls.d.ts +6 -15
  249. package/dist/core/tools/ls.d.ts.map +1 -1
  250. package/dist/core/tools/ls.js +12 -17
  251. package/dist/core/tools/ls.js.map +1 -1
  252. package/dist/core/tools/output-accumulator.d.ts +52 -0
  253. package/dist/core/tools/output-accumulator.d.ts.map +1 -0
  254. package/dist/core/tools/output-accumulator.js +184 -0
  255. package/dist/core/tools/output-accumulator.js.map +1 -0
  256. package/dist/core/tools/path-utils.d.ts +2 -0
  257. package/dist/core/tools/path-utils.d.ts.map +1 -1
  258. package/dist/core/tools/path-utils.js +40 -22
  259. package/dist/core/tools/path-utils.js.map +1 -1
  260. package/dist/core/tools/read.d.ts +7 -18
  261. package/dist/core/tools/read.d.ts.map +1 -1
  262. package/dist/core/tools/read.js +103 -52
  263. package/dist/core/tools/read.js.map +1 -1
  264. package/dist/core/tools/render-utils.d.ts +5 -2
  265. package/dist/core/tools/render-utils.d.ts.map +1 -1
  266. package/dist/core/tools/render-utils.js +18 -2
  267. package/dist/core/tools/render-utils.js.map +1 -1
  268. package/dist/core/tools/tool-definition-wrapper.d.ts.map +1 -1
  269. package/dist/core/tools/tool-definition-wrapper.js +2 -0
  270. package/dist/core/tools/tool-definition-wrapper.js.map +1 -1
  271. package/dist/core/tools/truncate.d.ts.map +1 -1
  272. package/dist/core/tools/truncate.js +12 -2
  273. package/dist/core/tools/truncate.js.map +1 -1
  274. package/dist/core/tools/write.d.ts +5 -14
  275. package/dist/core/tools/write.d.ts.map +1 -1
  276. package/dist/core/tools/write.js +27 -46
  277. package/dist/core/tools/write.js.map +1 -1
  278. package/dist/core/trust-manager.d.ts +36 -0
  279. package/dist/core/trust-manager.d.ts.map +1 -0
  280. package/dist/core/trust-manager.js +202 -0
  281. package/dist/core/trust-manager.js.map +1 -0
  282. package/dist/index.d.ts +33 -29
  283. package/dist/index.d.ts.map +1 -1
  284. package/dist/index.js +12 -9
  285. package/dist/index.js.map +1 -1
  286. package/dist/main.d.ts +5 -1
  287. package/dist/main.d.ts.map +1 -1
  288. package/dist/main.js +208 -93
  289. package/dist/main.js.map +1 -1
  290. package/dist/migrations.d.ts +2 -2
  291. package/dist/migrations.d.ts.map +1 -1
  292. package/dist/migrations.js +4 -4
  293. package/dist/migrations.js.map +1 -1
  294. package/dist/modes/index.d.ts +5 -5
  295. package/dist/modes/index.d.ts.map +1 -1
  296. package/dist/modes/index.js.map +1 -1
  297. package/dist/modes/interactive/assets/clankolas.png +0 -0
  298. package/dist/modes/interactive/components/assistant-message.d.ts +5 -1
  299. package/dist/modes/interactive/components/assistant-message.d.ts.map +1 -1
  300. package/dist/modes/interactive/components/assistant-message.js +37 -15
  301. package/dist/modes/interactive/components/assistant-message.js.map +1 -1
  302. package/dist/modes/interactive/components/bash-execution.d.ts +1 -1
  303. package/dist/modes/interactive/components/bash-execution.d.ts.map +1 -1
  304. package/dist/modes/interactive/components/bash-execution.js +3 -3
  305. package/dist/modes/interactive/components/bash-execution.js.map +1 -1
  306. package/dist/modes/interactive/components/bordered-loader.d.ts.map +1 -1
  307. package/dist/modes/interactive/components/bordered-loader.js +3 -0
  308. package/dist/modes/interactive/components/bordered-loader.js.map +1 -1
  309. package/dist/modes/interactive/components/config-selector.d.ts +36 -5
  310. package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
  311. package/dist/modes/interactive/components/config-selector.js +318 -36
  312. package/dist/modes/interactive/components/config-selector.js.map +1 -1
  313. package/dist/modes/interactive/components/countdown-timer.d.ts +2 -2
  314. package/dist/modes/interactive/components/countdown-timer.d.ts.map +1 -1
  315. package/dist/modes/interactive/components/countdown-timer.js +2 -2
  316. package/dist/modes/interactive/components/countdown-timer.js.map +1 -1
  317. package/dist/modes/interactive/components/custom-editor.d.ts +1 -1
  318. package/dist/modes/interactive/components/custom-editor.d.ts.map +1 -1
  319. package/dist/modes/interactive/components/custom-editor.js.map +1 -1
  320. package/dist/modes/interactive/components/custom-entry.d.ts +19 -0
  321. package/dist/modes/interactive/components/custom-entry.d.ts.map +1 -0
  322. package/dist/modes/interactive/components/custom-entry.js +52 -0
  323. package/dist/modes/interactive/components/custom-entry.js.map +1 -0
  324. package/dist/modes/interactive/components/custom-message.d.ts +2 -2
  325. package/dist/modes/interactive/components/custom-message.d.ts.map +1 -1
  326. package/dist/modes/interactive/components/custom-message.js.map +1 -1
  327. package/dist/modes/interactive/components/diff.d.ts.map +1 -1
  328. package/dist/modes/interactive/components/diff.js.map +1 -1
  329. package/dist/modes/interactive/components/earendil-announcement.d.ts.map +1 -1
  330. package/dist/modes/interactive/components/earendil-announcement.js.map +1 -1
  331. package/dist/modes/interactive/components/extension-editor.d.ts +3 -1
  332. package/dist/modes/interactive/components/extension-editor.d.ts.map +1 -1
  333. package/dist/modes/interactive/components/extension-editor.js +26 -9
  334. package/dist/modes/interactive/components/extension-editor.js.map +1 -1
  335. package/dist/modes/interactive/components/extension-input.d.ts.map +1 -1
  336. package/dist/modes/interactive/components/extension-input.js.map +1 -1
  337. package/dist/modes/interactive/components/extension-selector.d.ts +2 -0
  338. package/dist/modes/interactive/components/extension-selector.d.ts.map +1 -1
  339. package/dist/modes/interactive/components/extension-selector.js +8 -3
  340. package/dist/modes/interactive/components/extension-selector.js.map +1 -1
  341. package/dist/modes/interactive/components/first-time-setup.d.ts +25 -0
  342. package/dist/modes/interactive/components/first-time-setup.d.ts.map +1 -0
  343. package/dist/modes/interactive/components/first-time-setup.js +103 -0
  344. package/dist/modes/interactive/components/first-time-setup.js.map +1 -0
  345. package/dist/modes/interactive/components/footer.d.ts +4 -3
  346. package/dist/modes/interactive/components/footer.d.ts.map +1 -1
  347. package/dist/modes/interactive/components/footer.js +27 -7
  348. package/dist/modes/interactive/components/footer.js.map +1 -1
  349. package/dist/modes/interactive/components/index.d.ts +33 -31
  350. package/dist/modes/interactive/components/index.d.ts.map +1 -1
  351. package/dist/modes/interactive/components/index.js +2 -0
  352. package/dist/modes/interactive/components/index.js.map +1 -1
  353. package/dist/modes/interactive/components/keybinding-hints.d.ts +5 -0
  354. package/dist/modes/interactive/components/keybinding-hints.d.ts.map +1 -1
  355. package/dist/modes/interactive/components/keybinding-hints.js +19 -5
  356. package/dist/modes/interactive/components/keybinding-hints.js.map +1 -1
  357. package/dist/modes/interactive/components/login-dialog.d.ts +12 -2
  358. package/dist/modes/interactive/components/login-dialog.d.ts.map +1 -1
  359. package/dist/modes/interactive/components/login-dialog.js +45 -11
  360. package/dist/modes/interactive/components/login-dialog.js.map +1 -1
  361. package/dist/modes/interactive/components/model-selector.d.ts +2 -2
  362. package/dist/modes/interactive/components/model-selector.d.ts.map +1 -1
  363. package/dist/modes/interactive/components/model-selector.js +10 -6
  364. package/dist/modes/interactive/components/model-selector.js.map +1 -1
  365. package/dist/modes/interactive/components/oauth-selector.d.ts +18 -6
  366. package/dist/modes/interactive/components/oauth-selector.d.ts.map +1 -1
  367. package/dist/modes/interactive/components/oauth-selector.js +93 -25
  368. package/dist/modes/interactive/components/oauth-selector.js.map +1 -1
  369. package/dist/modes/interactive/components/scoped-models-selector.d.ts +5 -12
  370. package/dist/modes/interactive/components/scoped-models-selector.d.ts.map +1 -1
  371. package/dist/modes/interactive/components/scoped-models-selector.js +49 -31
  372. package/dist/modes/interactive/components/scoped-models-selector.js.map +1 -1
  373. package/dist/modes/interactive/components/session-selector.d.ts +2 -2
  374. package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
  375. package/dist/modes/interactive/components/session-selector.js +33 -14
  376. package/dist/modes/interactive/components/session-selector.js.map +1 -1
  377. package/dist/modes/interactive/components/settings-selector.d.ts +17 -0
  378. package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
  379. package/dist/modes/interactive/components/settings-selector.js +301 -20
  380. package/dist/modes/interactive/components/settings-selector.js.map +1 -1
  381. package/dist/modes/interactive/components/skill-invocation-message.d.ts +1 -1
  382. package/dist/modes/interactive/components/skill-invocation-message.d.ts.map +1 -1
  383. package/dist/modes/interactive/components/skill-invocation-message.js.map +1 -1
  384. package/dist/modes/interactive/components/status-indicator.d.ts +28 -0
  385. package/dist/modes/interactive/components/status-indicator.d.ts.map +1 -0
  386. package/dist/modes/interactive/components/status-indicator.js +60 -0
  387. package/dist/modes/interactive/components/status-indicator.js.map +1 -0
  388. package/dist/modes/interactive/components/thinking-selector.d.ts.map +1 -1
  389. package/dist/modes/interactive/components/thinking-selector.js +1 -1
  390. package/dist/modes/interactive/components/thinking-selector.js.map +1 -1
  391. package/dist/modes/interactive/components/tool-execution.d.ts +6 -1
  392. package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
  393. package/dist/modes/interactive/components/tool-execution.js +57 -14
  394. package/dist/modes/interactive/components/tool-execution.js.map +1 -1
  395. package/dist/modes/interactive/components/tree-selector.d.ts +1 -1
  396. package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
  397. package/dist/modes/interactive/components/tree-selector.js +137 -13
  398. package/dist/modes/interactive/components/tree-selector.js.map +1 -1
  399. package/dist/modes/interactive/components/trust-selector.d.ts +23 -0
  400. package/dist/modes/interactive/components/trust-selector.d.ts.map +1 -0
  401. package/dist/modes/interactive/components/trust-selector.js +91 -0
  402. package/dist/modes/interactive/components/trust-selector.js.map +1 -0
  403. package/dist/modes/interactive/components/user-message-selector.d.ts +2 -2
  404. package/dist/modes/interactive/components/user-message-selector.d.ts.map +1 -1
  405. package/dist/modes/interactive/components/user-message-selector.js +8 -7
  406. package/dist/modes/interactive/components/user-message-selector.js.map +1 -1
  407. package/dist/modes/interactive/components/user-message.d.ts +6 -1
  408. package/dist/modes/interactive/components/user-message.d.ts.map +1 -1
  409. package/dist/modes/interactive/components/user-message.js +22 -8
  410. package/dist/modes/interactive/components/user-message.js.map +1 -1
  411. package/dist/modes/interactive/interactive-mode.d.ts +76 -19
  412. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  413. package/dist/modes/interactive/interactive-mode.js +1294 -494
  414. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  415. package/dist/modes/interactive/model-search.d.ts +12 -0
  416. package/dist/modes/interactive/model-search.d.ts.map +1 -0
  417. package/dist/modes/interactive/model-search.js +15 -0
  418. package/dist/modes/interactive/model-search.js.map +1 -0
  419. package/dist/modes/interactive/theme/dark.json +5 -4
  420. package/dist/modes/interactive/theme/light.json +5 -4
  421. package/dist/modes/interactive/theme/theme-controller.d.ts +29 -0
  422. package/dist/modes/interactive/theme/theme-controller.d.ts.map +1 -0
  423. package/dist/modes/interactive/theme/theme-controller.js +102 -0
  424. package/dist/modes/interactive/theme/theme-controller.js.map +1 -0
  425. package/dist/modes/interactive/theme/theme-schema.json +2 -1
  426. package/dist/modes/interactive/theme/theme.d.ts +41 -3
  427. package/dist/modes/interactive/theme/theme.d.ts.map +1 -1
  428. package/dist/modes/interactive/theme/theme.js +183 -106
  429. package/dist/modes/interactive/theme/theme.js.map +1 -1
  430. package/dist/modes/print-mode.d.ts.map +1 -1
  431. package/dist/modes/print-mode.js +40 -20
  432. package/dist/modes/print-mode.js.map +1 -1
  433. package/dist/modes/rpc/rpc-client.d.ts +30 -5
  434. package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
  435. package/dist/modes/rpc/rpc-client.js +87 -8
  436. package/dist/modes/rpc/rpc-client.js.map +1 -1
  437. package/dist/modes/rpc/rpc-mode.d.ts +2 -2
  438. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  439. package/dist/modes/rpc/rpc-mode.js +113 -31
  440. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  441. package/dist/modes/rpc/rpc-types.d.ts +42 -4
  442. package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
  443. package/dist/modes/rpc/rpc-types.js.map +1 -1
  444. package/dist/package-manager-cli.d.ts +6 -2
  445. package/dist/package-manager-cli.d.ts.map +1 -1
  446. package/dist/package-manager-cli.js +504 -25
  447. package/dist/package-manager-cli.js.map +1 -1
  448. package/dist/prompts/agents/build.md +38 -0
  449. package/dist/prompts/agents/plan.md +36 -0
  450. package/dist/prompts/agents/verify.md +36 -4
  451. package/dist/prompts/commands/brainstorm.md +162 -0
  452. package/dist/prompts/commands/discuss-phase.md +1 -1
  453. package/dist/prompts/commands/execute-phase.md +4 -1
  454. package/dist/prompts/commands/fix.md +12 -0
  455. package/dist/prompts/commands/init-project.md +1 -0
  456. package/dist/prompts/commands/map-codebase.md +15 -1
  457. package/dist/prompts/commands/new-project.md +1 -0
  458. package/dist/prompts/commands/next-milestone.md +2 -0
  459. package/dist/prompts/commands/orchestrate.md +4 -4
  460. package/dist/prompts/commands/plan-phase.md +5 -0
  461. package/dist/prompts/commands/quick.md +4 -0
  462. package/dist/prompts/commands/review.md +4 -1
  463. package/dist/prompts/commands/verify-work.md +10 -8
  464. package/dist/rpc-entry.d.ts +3 -0
  465. package/dist/rpc-entry.d.ts.map +1 -0
  466. package/dist/rpc-entry.js +10 -0
  467. package/dist/rpc-entry.js.map +1 -0
  468. package/dist/utils/ansi.d.ts +2 -0
  469. package/dist/utils/ansi.d.ts.map +1 -0
  470. package/dist/utils/ansi.js +52 -0
  471. package/dist/utils/ansi.js.map +1 -0
  472. package/dist/utils/changelog.d.ts +2 -1
  473. package/dist/utils/changelog.d.ts.map +1 -1
  474. package/dist/utils/changelog.js +78 -0
  475. package/dist/utils/changelog.js.map +1 -1
  476. package/dist/utils/child-process.d.ts +12 -5
  477. package/dist/utils/child-process.d.ts.map +1 -1
  478. package/dist/utils/child-process.js +33 -5
  479. package/dist/utils/child-process.js.map +1 -1
  480. package/dist/utils/clipboard-image.d.ts.map +1 -1
  481. package/dist/utils/clipboard-image.js +2 -2
  482. package/dist/utils/clipboard-image.js.map +1 -1
  483. package/dist/utils/clipboard-native.d.ts +3 -1
  484. package/dist/utils/clipboard-native.d.ts.map +1 -1
  485. package/dist/utils/clipboard-native.js +14 -8
  486. package/dist/utils/clipboard-native.js.map +1 -1
  487. package/dist/utils/clipboard.d.ts.map +1 -1
  488. package/dist/utils/clipboard.js +84 -45
  489. package/dist/utils/clipboard.js.map +1 -1
  490. package/dist/utils/deprecation.d.ts +4 -0
  491. package/dist/utils/deprecation.d.ts.map +1 -0
  492. package/dist/utils/deprecation.js +13 -0
  493. package/dist/utils/deprecation.js.map +1 -0
  494. package/dist/utils/exif-orientation.d.ts +1 -1
  495. package/dist/utils/exif-orientation.d.ts.map +1 -1
  496. package/dist/utils/exif-orientation.js.map +1 -1
  497. package/dist/utils/fs-watch.d.ts +5 -0
  498. package/dist/utils/fs-watch.d.ts.map +1 -0
  499. package/dist/utils/fs-watch.js +25 -0
  500. package/dist/utils/fs-watch.js.map +1 -0
  501. package/dist/utils/git.d.ts.map +1 -1
  502. package/dist/utils/git.js +54 -22
  503. package/dist/utils/git.js.map +1 -1
  504. package/dist/utils/html.d.ts +7 -0
  505. package/dist/utils/html.d.ts.map +1 -0
  506. package/dist/utils/html.js +40 -0
  507. package/dist/utils/html.js.map +1 -0
  508. package/dist/utils/image-convert.d.ts +1 -0
  509. package/dist/utils/image-convert.d.ts.map +1 -1
  510. package/dist/utils/image-convert.js +21 -15
  511. package/dist/utils/image-convert.js.map +1 -1
  512. package/dist/utils/image-process.d.ts +18 -0
  513. package/dist/utils/image-process.d.ts.map +1 -0
  514. package/dist/utils/image-process.js +83 -0
  515. package/dist/utils/image-process.js.map +1 -0
  516. package/dist/utils/image-resize-core.d.ts +30 -0
  517. package/dist/utils/image-resize-core.d.ts.map +1 -0
  518. package/dist/utils/image-resize-core.js +124 -0
  519. package/dist/utils/image-resize-core.js.map +1 -0
  520. package/dist/utils/image-resize-worker.d.ts +2 -0
  521. package/dist/utils/image-resize-worker.d.ts.map +1 -0
  522. package/dist/utils/image-resize-worker.js +31 -0
  523. package/dist/utils/image-resize-worker.js.map +1 -0
  524. package/dist/utils/image-resize.d.ts +7 -27
  525. package/dist/utils/image-resize.d.ts.map +1 -1
  526. package/dist/utils/image-resize.js +75 -115
  527. package/dist/utils/image-resize.js.map +1 -1
  528. package/dist/utils/json.d.ts +3 -0
  529. package/dist/utils/json.d.ts.map +1 -0
  530. package/dist/utils/json.js +7 -0
  531. package/dist/utils/json.js.map +1 -0
  532. package/dist/utils/mime.d.ts +1 -0
  533. package/dist/utils/mime.d.ts.map +1 -1
  534. package/dist/utils/mime.js +100 -16
  535. package/dist/utils/mime.js.map +1 -1
  536. package/dist/utils/open-browser.d.ts +9 -0
  537. package/dist/utils/open-browser.d.ts.map +1 -0
  538. package/dist/utils/open-browser.js +22 -0
  539. package/dist/utils/open-browser.js.map +1 -0
  540. package/dist/utils/paths.d.ts +25 -1
  541. package/dist/utils/paths.d.ts.map +1 -1
  542. package/dist/utils/paths.js +75 -2
  543. package/dist/utils/paths.js.map +1 -1
  544. package/dist/utils/pi-user-agent.d.ts +2 -0
  545. package/dist/utils/pi-user-agent.d.ts.map +1 -0
  546. package/dist/utils/pi-user-agent.js +5 -0
  547. package/dist/utils/pi-user-agent.js.map +1 -0
  548. package/dist/utils/shell.d.ts +11 -6
  549. package/dist/utils/shell.d.ts.map +1 -1
  550. package/dist/utils/shell.js +42 -26
  551. package/dist/utils/shell.js.map +1 -1
  552. package/dist/utils/syntax-highlight.d.ts +12 -0
  553. package/dist/utils/syntax-highlight.d.ts.map +1 -0
  554. package/dist/utils/syntax-highlight.js +118 -0
  555. package/dist/utils/syntax-highlight.js.map +1 -0
  556. package/dist/utils/tools-manager.d.ts.map +1 -1
  557. package/dist/utils/tools-manager.js +86 -10
  558. package/dist/utils/tools-manager.js.map +1 -1
  559. package/dist/utils/version-check.d.ts +15 -0
  560. package/dist/utils/version-check.d.ts.map +1 -0
  561. package/dist/utils/version-check.js +59 -0
  562. package/dist/utils/version-check.js.map +1 -0
  563. package/dist/utils/windows-self-update.d.ts +3 -0
  564. package/dist/utils/windows-self-update.d.ts.map +1 -0
  565. package/dist/utils/windows-self-update.js +77 -0
  566. package/dist/utils/windows-self-update.js.map +1 -0
  567. package/docs/compaction.md +12 -12
  568. package/docs/containerization.md +111 -0
  569. package/docs/custom-provider.md +187 -47
  570. package/docs/development.md +5 -5
  571. package/docs/docs.json +156 -0
  572. package/docs/extensions.md +520 -79
  573. package/docs/index.md +82 -0
  574. package/docs/json.md +4 -4
  575. package/docs/keybindings.md +24 -2
  576. package/docs/models.md +119 -17
  577. package/docs/packages.md +19 -11
  578. package/docs/prompt-templates.md +30 -2
  579. package/docs/providers.md +85 -23
  580. package/docs/quickstart.md +165 -0
  581. package/docs/rpc.md +99 -10
  582. package/docs/sdk.md +118 -50
  583. package/docs/security.md +55 -0
  584. package/docs/{session.md → session-format.md} +29 -19
  585. package/docs/sessions.md +145 -0
  586. package/docs/settings.md +71 -11
  587. package/docs/skills.md +16 -17
  588. package/docs/terminal-setup.md +44 -2
  589. package/docs/termux.md +4 -4
  590. package/docs/themes.md +3 -3
  591. package/docs/tmux.md +4 -2
  592. package/docs/tui.md +44 -4
  593. package/docs/usage.md +305 -0
  594. package/examples/extensions/README.md +1 -0
  595. package/examples/extensions/border-status-editor.ts +145 -0
  596. package/examples/extensions/built-in-tool-renderer.ts +3 -0
  597. package/examples/extensions/custom-compaction.ts +2 -1
  598. package/examples/extensions/custom-header.ts +1 -1
  599. package/examples/extensions/custom-provider-anthropic/index.ts +2 -2
  600. package/examples/extensions/custom-provider-anthropic/package-lock.json +2 -2
  601. package/examples/extensions/custom-provider-anthropic/package.json +2 -2
  602. package/examples/extensions/custom-provider-gitlab-duo/index.ts +63 -8
  603. package/examples/extensions/custom-provider-gitlab-duo/package.json +1 -1
  604. package/examples/extensions/custom-provider-gitlab-duo/test.ts +2 -2
  605. package/examples/extensions/doom-overlay/doom-component.ts +2 -2
  606. package/examples/extensions/doom-overlay/index.ts +1 -1
  607. package/examples/extensions/dynamic-resources/dynamic.json +1 -1
  608. package/examples/extensions/dynamic-tools.ts +2 -2
  609. package/examples/extensions/entry-renderer.ts +41 -0
  610. package/examples/extensions/git-merge-and-resolve.ts +115 -0
  611. package/examples/extensions/github-issue-autocomplete.ts +185 -0
  612. package/examples/extensions/gondolin/index.ts +531 -0
  613. package/examples/extensions/gondolin/package-lock.json +185 -0
  614. package/examples/extensions/gondolin/package.json +19 -0
  615. package/examples/extensions/handoff.ts +52 -14
  616. package/examples/extensions/input-transform-streaming.ts +39 -0
  617. package/examples/extensions/interactive-shell.ts +1 -1
  618. package/examples/extensions/notify.ts +2 -9
  619. package/examples/extensions/overlay-qa-tests.ts +240 -138
  620. package/examples/extensions/overlay-test.ts +7 -4
  621. package/examples/extensions/plan-mode/index.ts +87 -37
  622. package/examples/extensions/plan-mode/utils.ts +1 -1
  623. package/examples/extensions/preset.ts +46 -7
  624. package/examples/extensions/project-trust.ts +64 -0
  625. package/examples/extensions/prompt-customizer.ts +97 -0
  626. package/examples/extensions/provider-payload.ts +8 -4
  627. package/examples/extensions/qna.ts +3 -3
  628. package/examples/extensions/question.ts +34 -20
  629. package/examples/extensions/questionnaire.ts +43 -30
  630. package/examples/extensions/reload-runtime.ts +1 -1
  631. package/examples/extensions/sandbox/index.ts +6 -6
  632. package/examples/extensions/sandbox/package-lock.json +5 -5
  633. package/examples/extensions/sandbox/package.json +2 -2
  634. package/examples/extensions/shutdown-command.ts +1 -1
  635. package/examples/extensions/snake.ts +1 -1
  636. package/examples/extensions/space-invaders.ts +1 -1
  637. package/examples/extensions/structured-output.ts +65 -0
  638. package/examples/extensions/subagent/agents.ts +2 -2
  639. package/examples/extensions/subagent/index.ts +58 -29
  640. package/examples/extensions/summarize.ts +3 -2
  641. package/examples/extensions/tic-tac-toe.ts +1008 -0
  642. package/examples/extensions/titlebar-spinner.ts +2 -2
  643. package/examples/extensions/todo.ts +2 -2
  644. package/examples/extensions/tool-override.ts +1 -1
  645. package/examples/extensions/tools.ts +5 -0
  646. package/examples/extensions/truncated-tool.ts +1 -1
  647. package/examples/extensions/with-deps/index.ts +1 -1
  648. package/examples/extensions/with-deps/package-lock.json +2 -2
  649. package/examples/extensions/with-deps/package.json +3 -3
  650. package/examples/extensions/working-indicator.ts +123 -0
  651. package/examples/extensions/working-message-test.ts +25 -0
  652. package/examples/sdk/01-minimal.ts +14 -10
  653. package/examples/sdk/02-custom-model.ts +13 -9
  654. package/examples/sdk/03-custom-prompt.ts +32 -17
  655. package/examples/sdk/04-skills.ts +5 -2
  656. package/examples/sdk/05-tools.ts +23 -31
  657. package/examples/sdk/06-extensions.ts +14 -8
  658. package/examples/sdk/07-context-files.ts +5 -3
  659. package/examples/sdk/08-prompt-templates.ts +5 -2
  660. package/examples/sdk/09-api-keys-and-oauth.ts +8 -4
  661. package/examples/sdk/10-settings.ts +8 -6
  662. package/examples/sdk/11-sessions.ts +4 -0
  663. package/examples/sdk/12-full-control.ts +15 -19
  664. package/package.json +22 -16
  665. package/prompts/agents/build.md +38 -0
  666. package/prompts/agents/plan.md +36 -0
  667. package/prompts/agents/verify.md +36 -4
  668. package/prompts/commands/brainstorm.md +162 -0
  669. package/prompts/commands/discuss-phase.md +1 -1
  670. package/prompts/commands/execute-phase.md +4 -1
  671. package/prompts/commands/fix.md +12 -0
  672. package/prompts/commands/init-project.md +1 -0
  673. package/prompts/commands/map-codebase.md +15 -1
  674. package/prompts/commands/new-project.md +1 -0
  675. package/prompts/commands/next-milestone.md +2 -0
  676. package/prompts/commands/orchestrate.md +4 -4
  677. package/prompts/commands/plan-phase.md +5 -0
  678. package/prompts/commands/quick.md +4 -0
  679. package/prompts/commands/review.md +4 -1
  680. package/prompts/commands/verify-work.md +10 -8
@@ -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,12 +310,15 @@ 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 }
273
317
  └─► resources_discover { reason: "startup" }
274
318
 
319
+ /name or pi.setSessionName()
320
+ └─► session_info_changed
321
+
275
322
  /compact or auto-compaction
276
323
  ├─► session_before_compact (can cancel or customize)
277
324
  └─► session_compact
@@ -281,12 +328,35 @@ user sends another prompt ◄─────────────────
281
328
  └─► session_tree
282
329
 
283
330
  /model or Ctrl+P (model selection/cycling)
331
+ ├─► thinking_level_select (if model change changes/clamps thinking level)
284
332
  └─► model_select
285
333
 
286
- exit (Ctrl+C, Ctrl+D)
334
+ thinking level changes (settings, keybinding, pi.setThinkingLevel())
335
+ └─► thinking_level_select
336
+
337
+ exit (Ctrl+C, Ctrl+D, SIGHUP, SIGTERM)
287
338
  └─► session_shutdown
288
339
  ```
289
340
 
341
+ ### Startup Events
342
+
343
+ #### project_trust
344
+
345
+ 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.
346
+
347
+ ```typescript
348
+ pi.on("project_trust", async (event, ctx) => {
349
+ // event.cwd - current working directory
350
+ // ctx has a limited trust context: cwd, mode, hasUI, and select/confirm/input/notify UI helpers
351
+ if (await ctx.ui.confirm("Trust project?", event.cwd)) {
352
+ return { trusted: "yes", remember: true };
353
+ }
354
+ return { trusted: "undecided" };
355
+ });
356
+ ```
357
+
358
+ 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.
359
+
290
360
  ### Resource Events
291
361
 
292
362
  #### resources_discover
@@ -308,7 +378,7 @@ pi.on("resources_discover", async (event, _ctx) => {
308
378
 
309
379
  ### Session Events
310
380
 
311
- See [session.md](session.md) for session storage internals and the SessionManager API.
381
+ See [Session Format](session-format.md) for session storage internals and the SessionManager API.
312
382
 
313
383
  #### session_start
314
384
 
@@ -322,6 +392,17 @@ pi.on("session_start", async (event, ctx) => {
322
392
  });
323
393
  ```
324
394
 
395
+ #### session_info_changed
396
+
397
+ Fired when the current session display name is set via `/name`, RPC, or `pi.setSessionName()`.
398
+
399
+ ```typescript
400
+ pi.on("session_info_changed", async (event, ctx) => {
401
+ // event.name - current normalized name, or undefined if cleared
402
+ ctx.ui.notify(`Session renamed: ${event.name ?? "(none)"}`, "info");
403
+ });
404
+ ```
405
+
325
406
  #### session_before_switch
326
407
 
327
408
  Fired before starting a new session (`/new`) or switching sessions (`/resume`).
@@ -343,18 +424,19 @@ Do cleanup work in `session_shutdown`, then reestablish any in-memory state in `
343
424
 
344
425
  #### session_before_fork
345
426
 
346
- Fired when forking via `/fork`.
427
+ Fired when forking via `/fork` or cloning via `/clone`.
347
428
 
348
429
  ```typescript
349
430
  pi.on("session_before_fork", async (event, ctx) => {
350
- // event.entryId - ID of the entry being forked from
351
- return { cancel: true }; // Cancel fork
431
+ // event.entryId - ID of the selected entry
432
+ // event.position - "before" for /fork, "at" for /clone
433
+ return { cancel: true }; // Cancel fork/clone
352
434
  // OR
353
- return { skipConversationRestore: true }; // Fork but don't rewind messages
435
+ return { skipConversationRestore: true }; // Reserved for future conversation restore control
354
436
  });
355
437
  ```
356
438
 
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`.
439
+ 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
440
  Do cleanup work in `session_shutdown`, then reestablish any in-memory state in `session_start`.
359
441
 
360
442
  #### session_before_compact / session_compact
@@ -386,7 +468,7 @@ pi.on("session_compact", async (event, ctx) => {
386
468
 
387
469
  #### session_before_tree / session_tree
388
470
 
389
- Fired on `/tree` navigation. See [tree.md](tree.md) for tree navigation concepts.
471
+ Fired on `/tree` navigation. See [Sessions](sessions.md) for tree navigation concepts.
390
472
 
391
473
  ```typescript
392
474
  pi.on("session_before_tree", async (event, ctx) => {
@@ -403,10 +485,12 @@ pi.on("session_tree", async (event, ctx) => {
403
485
 
404
486
  #### session_shutdown
405
487
 
406
- Fired on exit (Ctrl+C, Ctrl+D, SIGTERM).
488
+ Fired before an extension runtime is torn down.
407
489
 
408
490
  ```typescript
409
- pi.on("session_shutdown", async (_event, ctx) => {
491
+ pi.on("session_shutdown", async (event, ctx) => {
492
+ // event.reason - "quit" | "reload" | "new" | "resume" | "fork"
493
+ // event.targetSessionFile - destination session for session replacement flows
410
494
  // Cleanup, save state, etc.
411
495
  });
412
496
  ```
@@ -421,7 +505,17 @@ Fired after user submits prompt, before agent loop. Can inject a message and/or
421
505
  pi.on("before_agent_start", async (event, ctx) => {
422
506
  // event.prompt - user's prompt text
423
507
  // event.images - attached images (if any)
424
- // event.systemPrompt - current system prompt
508
+ // event.systemPrompt - current chained system prompt for this handler
509
+ // (includes changes from earlier before_agent_start handlers)
510
+ // event.systemPromptOptions - structured options used to build the system prompt
511
+ // .customPrompt - any custom system prompt (from --system-prompt, SYSTEM.md, or custom templates)
512
+ // .selectedTools - tools currently active in the prompt
513
+ // .toolSnippets - one-line descriptions for each tool
514
+ // .promptGuidelines - custom guideline bullets
515
+ // .appendSystemPrompt - text from --append-system-prompt flags
516
+ // .cwd - working directory
517
+ // .contextFiles - AGENTS.md files and other loaded context files
518
+ // .skills - loaded skills
425
519
 
426
520
  return {
427
521
  // Inject a persistent message (stored in session, sent to LLM)
@@ -436,6 +530,10 @@ pi.on("before_agent_start", async (event, ctx) => {
436
530
  });
437
531
  ```
438
532
 
533
+ 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.
534
+
535
+ 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.
536
+
439
537
  #### agent_start / agent_end
440
538
 
441
539
  Fired once per user prompt.
@@ -468,6 +566,7 @@ Fired for message lifecycle updates.
468
566
 
469
567
  - `message_start` and `message_end` fire for user, assistant, and toolResult messages.
470
568
  - `message_update` fires for assistant streaming updates.
569
+ - `message_end` handlers can return `{ message }` to replace the finalized message. The replacement must keep the same `role`.
471
570
 
472
571
  ```typescript
473
572
  pi.on("message_start", async (event, ctx) => {
@@ -480,7 +579,20 @@ pi.on("message_update", async (event, ctx) => {
480
579
  });
481
580
 
482
581
  pi.on("message_end", async (event, ctx) => {
483
- // event.message
582
+ if (event.message.role !== "assistant") return;
583
+
584
+ return {
585
+ message: {
586
+ ...event.message,
587
+ usage: {
588
+ ...event.message.usage,
589
+ cost: {
590
+ ...event.message.usage.cost,
591
+ total: 0.123,
592
+ },
593
+ },
594
+ },
595
+ };
484
596
  });
485
597
  ```
486
598
 
@@ -491,7 +603,8 @@ Fired for tool execution lifecycle updates.
491
603
  In parallel tool mode:
492
604
  - `tool_execution_start` is emitted in assistant source order during the preflight phase
493
605
  - `tool_execution_update` events may interleave across tools
494
- - `tool_execution_end` is emitted in assistant source order, matching final tool result message order
606
+ - `tool_execution_end` is emitted in tool completion order after each tool is finalized
607
+ - final `toolResult` message events are still emitted later in assistant source order
495
608
 
496
609
  ```typescript
497
610
  pi.on("tool_execution_start", async (event, ctx) => {
@@ -509,7 +622,7 @@ pi.on("tool_execution_end", async (event, ctx) => {
509
622
 
510
623
  #### context
511
624
 
512
- Fired before each LLM call. Modify messages non-destructively. See [session.md](session.md) for message types.
625
+ Fired before each LLM call. Modify messages non-destructively. See [Session Format](session-format.md) for message types.
513
626
 
514
627
  ```typescript
515
628
  pi.on("context", async (event, ctx) => {
@@ -523,6 +636,8 @@ pi.on("context", async (event, ctx) => {
523
636
 
524
637
  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
638
 
639
+ 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.
640
+
526
641
  ```typescript
527
642
  pi.on("before_provider_request", (event, ctx) => {
528
643
  console.log(JSON.stringify(event.payload, null, 2));
@@ -534,6 +649,22 @@ pi.on("before_provider_request", (event, ctx) => {
534
649
 
535
650
  This is mainly useful for debugging provider serialization and cache behavior.
536
651
 
652
+ #### after_provider_response
653
+
654
+ Fired after an HTTP response is received and before its stream body is consumed. Handlers run in extension load order.
655
+
656
+ ```typescript
657
+ pi.on("after_provider_response", (event, ctx) => {
658
+ // event.status - HTTP status code
659
+ // event.headers - normalized response headers
660
+ if (event.status === 429) {
661
+ console.log("rate limited", event.headers["retry-after"]);
662
+ }
663
+ });
664
+ ```
665
+
666
+ Header availability depends on provider and transport. Providers that abstract HTTP responses may not expose headers.
667
+
537
668
  ### Model Events
538
669
 
539
670
  #### model_select
@@ -557,6 +688,21 @@ pi.on("model_select", async (event, ctx) => {
557
688
 
558
689
  Use this to update UI elements (status bars, footers) or perform model-specific initialization when the active model changes.
559
690
 
691
+ #### thinking_level_select
692
+
693
+ Fired when the thinking level changes. This is notification-only; handler return values are ignored.
694
+
695
+ ```typescript
696
+ pi.on("thinking_level_select", async (event, ctx) => {
697
+ // event.level - newly selected thinking level
698
+ // event.previousLevel - previous thinking level
699
+
700
+ ctx.ui.setStatus("thinking", `thinking: ${event.level}`);
701
+ });
702
+ ```
703
+
704
+ Use this to update extension UI when `pi.setThinkingLevel()`, model changes, or built-in thinking-level controls change the active thinking level.
705
+
560
706
  ### Tool Events
561
707
 
562
708
  #### tool_call
@@ -626,6 +772,8 @@ pi.on("tool_call", (event) => {
626
772
 
627
773
  Fired after tool execution finishes and before `tool_execution_end` plus the final tool result message events are emitted. **Can modify result.**
628
774
 
775
+ 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.
776
+
629
777
  `tool_result` handlers chain like middleware:
630
778
  - Handlers run in extension load order
631
779
  - Each handler sees the latest result after previous handler changes
@@ -705,6 +853,9 @@ pi.on("input", async (event, ctx) => {
705
853
  // event.text - raw input (before skill/template expansion)
706
854
  // event.images - attached images, if any
707
855
  // event.source - "interactive" (typed), "rpc" (API), or "extension" (via sendUserMessage)
856
+ // event.streamingBehavior - "steer" | "followUp" | undefined
857
+ // undefined when idle, "steer" for mid-stream interrupts,
858
+ // "followUp" for messages queued until the agent finishes
708
859
 
709
860
  // Transform: rewrite input before expansion
710
861
  if (event.text.startsWith("?quick "))
@@ -733,7 +884,7 @@ pi.on("input", async (event, ctx) => {
733
884
  - `transform` - modify text/images, then continue to expansion
734
885
  - `handled` - skip agent entirely (first handler to return this wins)
735
886
 
736
- Transforms chain across handlers. See [input-transform.ts](../examples/extensions/input-transform.ts).
887
+ 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
888
 
738
889
  ## ExtensionContext
739
890
 
@@ -743,24 +894,35 @@ All handlers receive `ctx: ExtensionContext`.
743
894
 
744
895
  UI methods for user interaction. See [Custom UI](#custom-ui) for full details.
745
896
 
897
+ ### ctx.mode
898
+
899
+ 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.
900
+
746
901
  ### ctx.hasUI
747
902
 
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)).
903
+ `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
904
 
750
905
  ### ctx.cwd
751
906
 
752
907
  Current working directory.
753
908
 
909
+ ### ctx.isProjectTrusted()
910
+
911
+ 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.
912
+
913
+ Use this before reading project-local extension configuration that should only be honored for trusted projects.
914
+
754
915
  ### ctx.sessionManager
755
916
 
756
- Read-only access to session state. See [session.md](session.md) for the full SessionManager API and entry types.
917
+ Read-only access to session state. See [Session Format](session-format.md) for the full SessionManager API and entry types.
757
918
 
758
919
  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
920
 
760
921
  ```typescript
761
- ctx.sessionManager.getEntries() // All entries
762
- ctx.sessionManager.getBranch() // Current branch
763
- ctx.sessionManager.getLeafId() // Current leaf entry ID
922
+ ctx.sessionManager.getEntries() // All entries
923
+ ctx.sessionManager.getBranch() // Current branch
924
+ ctx.sessionManager.buildContextEntries() // Active branch entries with compaction applied
925
+ ctx.sessionManager.getLeafId() // Current leaf entry ID
764
926
  ```
765
927
 
766
928
  ### ctx.modelRegistry / ctx.model
@@ -843,7 +1005,12 @@ ctx.compact({
843
1005
 
844
1006
  ### ctx.getSystemPrompt()
845
1007
 
846
- Returns the current effective system prompt. This includes any modifications made by `before_agent_start` handlers for the current turn.
1008
+ Returns Pi's current system prompt string.
1009
+
1010
+ - During `before_agent_start`, this reflects chained system-prompt changes made so far for the current turn.
1011
+ - It does not include later `context` message mutations.
1012
+ - It does not include `before_provider_request` payload rewrites.
1013
+ - If later-loaded extensions run after yours, they can still change what is ultimately sent.
847
1014
 
848
1015
  ```typescript
849
1016
  pi.on("before_agent_start", (event, ctx) => {
@@ -856,6 +1023,19 @@ pi.on("before_agent_start", (event, ctx) => {
856
1023
 
857
1024
  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
1025
 
1026
+ ### ctx.getSystemPromptOptions()
1027
+
1028
+ Returns the base inputs Pi currently uses to build the system prompt.
1029
+
1030
+ ```typescript
1031
+ const options = ctx.getSystemPromptOptions();
1032
+ const contextPaths = options.contextFiles?.map((file) => file.path) ?? [];
1033
+ ```
1034
+
1035
+ 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.
1036
+
1037
+ 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.
1038
+
859
1039
  ### ctx.waitForIdle()
860
1040
 
861
1041
  Wait for the agent to finish streaming:
@@ -874,8 +1054,11 @@ pi.registerCommand("my-cmd", {
874
1054
  Create a new session:
875
1055
 
876
1056
  ```typescript
1057
+ const parentSession = ctx.sessionManager.getSessionFile();
1058
+ const kickoff = "Continue in the replacement session";
1059
+
877
1060
  const result = await ctx.newSession({
878
- parentSession: ctx.sessionManager.getSessionFile(),
1061
+ parentSession,
879
1062
  setup: async (sm) => {
880
1063
  sm.appendMessage({
881
1064
  role: "user",
@@ -883,6 +1066,10 @@ const result = await ctx.newSession({
883
1066
  timestamp: Date.now(),
884
1067
  });
885
1068
  },
1069
+ withSession: async (ctx) => {
1070
+ // Use only the replacement-session ctx here.
1071
+ await ctx.sendUserMessage(kickoff);
1072
+ },
886
1073
  });
887
1074
 
888
1075
  if (result.cancelled) {
@@ -890,17 +1077,37 @@ if (result.cancelled) {
890
1077
  }
891
1078
  ```
892
1079
 
893
- ### ctx.fork(entryId)
1080
+ Options:
1081
+ - `parentSession`: parent session file to record in the new session header
1082
+ - `setup`: mutate the new session's `SessionManager` before `withSession` runs
1083
+ - `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).
1084
+
1085
+ ### ctx.fork(entryId, options?)
894
1086
 
895
1087
  Fork from a specific entry, creating a new session file:
896
1088
 
897
1089
  ```typescript
898
- const result = await ctx.fork("entry-id-123");
899
- if (!result.cancelled) {
900
- // Now in the forked session
1090
+ const result = await ctx.fork("entry-id-123", {
1091
+ withSession: async (ctx) => {
1092
+ // Use only the replacement-session ctx here.
1093
+ ctx.ui.notify("Now in the forked session", "info");
1094
+ },
1095
+ });
1096
+ if (result.cancelled) {
1097
+ // An extension cancelled the fork
1098
+ }
1099
+
1100
+ const cloneResult = await ctx.fork("entry-id-456", { position: "at" });
1101
+ if (cloneResult.cancelled) {
1102
+ // An extension cancelled the clone
901
1103
  }
902
1104
  ```
903
1105
 
1106
+ Options:
1107
+ - `position`: `"before"` (default) forks before the selected user message, restoring that prompt into the editor
1108
+ - `position`: `"at"` duplicates the active path through the selected entry without restoring editor text
1109
+ - `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).
1110
+
904
1111
  ### ctx.navigateTree(targetId, options?)
905
1112
 
906
1113
  Navigate to a different point in the session tree:
@@ -920,17 +1127,24 @@ Options:
920
1127
  - `replaceInstructions`: If true, `customInstructions` replaces the default prompt instead of being appended
921
1128
  - `label`: Label to attach to the branch summary entry (or target entry if not summarizing)
922
1129
 
923
- ### ctx.switchSession(sessionPath)
1130
+ ### ctx.switchSession(sessionPath, options?)
924
1131
 
925
1132
  Switch to a different session file:
926
1133
 
927
1134
  ```typescript
928
- const result = await ctx.switchSession("/path/to/session.jsonl");
1135
+ const result = await ctx.switchSession("/path/to/session.jsonl", {
1136
+ withSession: async (ctx) => {
1137
+ await ctx.sendUserMessage("Resume work in the replacement session");
1138
+ },
1139
+ });
929
1140
  if (result.cancelled) {
930
1141
  // An extension cancelled the switch via session_before_switch
931
1142
  }
932
1143
  ```
933
1144
 
1145
+ Options:
1146
+ - `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).
1147
+
934
1148
  To discover available sessions, use the static `SessionManager.list()` or `SessionManager.listAll()` methods:
935
1149
 
936
1150
  ```typescript
@@ -946,12 +1160,59 @@ pi.registerCommand("switch", {
946
1160
  sessions.map(s => s.file),
947
1161
  );
948
1162
  if (choice) {
949
- await ctx.switchSession(choice);
1163
+ await ctx.switchSession(choice, {
1164
+ withSession: async (ctx) => {
1165
+ ctx.ui.notify("Switched session", "info");
1166
+ },
1167
+ });
950
1168
  }
951
1169
  },
952
1170
  });
953
1171
  ```
954
1172
 
1173
+ ### Session replacement lifecycle and footguns
1174
+
1175
+ `withSession` receives a fresh `ReplacedSessionContext`, which extends `ExtensionCommandContext` with async `sendMessage()` and `sendUserMessage()` helpers bound to the replacement session.
1176
+
1177
+ Lifecycle and footguns:
1178
+ - `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`.
1179
+ - 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.
1180
+ - 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.
1181
+ - 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.
1182
+ - 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.
1183
+
1184
+ Safe pattern:
1185
+
1186
+ ```typescript
1187
+ pi.registerCommand("handoff", {
1188
+ handler: async (_args, ctx) => {
1189
+ const kickoff = "Continue from the replacement session";
1190
+ await ctx.newSession({
1191
+ withSession: async (ctx) => {
1192
+ await ctx.sendUserMessage(kickoff);
1193
+ },
1194
+ });
1195
+ },
1196
+ });
1197
+ ```
1198
+
1199
+ Unsafe pattern:
1200
+
1201
+ ```typescript
1202
+ pi.registerCommand("handoff", {
1203
+ handler: async (_args, ctx) => {
1204
+ const oldSessionManager = ctx.sessionManager;
1205
+ await ctx.newSession({
1206
+ withSession: async (_ctx) => {
1207
+ // stale old objects: do not do this
1208
+ oldSessionManager.getSessionFile();
1209
+ pi.sendUserMessage("wrong");
1210
+ },
1211
+ });
1212
+ },
1213
+ });
1214
+ ```
1215
+
955
1216
  ### ctx.reload()
956
1217
 
957
1218
  Run the same reload flow as `/reload`.
@@ -982,7 +1243,7 @@ Example tool the LLM can call to trigger reload:
982
1243
 
983
1244
  ```typescript
984
1245
  import type { ExtensionAPI } from "@draht/coding-agent";
985
- import { Type } from "@sinclair/typebox";
1246
+ import { Type } from "typebox";
986
1247
 
987
1248
  export default function (pi: ExtensionAPI) {
988
1249
  pi.registerCommand("reload-runtime", {
@@ -1024,10 +1285,12 @@ Use `pi.setActiveTools()` to enable or disable tools (including dynamically adde
1024
1285
 
1025
1286
  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
1287
 
1288
+ **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.
1289
+
1027
1290
  See [dynamic-tools.ts](../examples/extensions/dynamic-tools.ts) for a full example.
1028
1291
 
1029
1292
  ```typescript
1030
- import { Type } from "@sinclair/typebox";
1293
+ import { Type } from "typebox";
1031
1294
  import { StringEnum } from "@draht/ai";
1032
1295
 
1033
1296
  pi.registerTool({
@@ -1035,7 +1298,7 @@ pi.registerTool({
1035
1298
  label: "My Tool",
1036
1299
  description: "What this tool does",
1037
1300
  promptSnippet: "Summarize or transform text according to action",
1038
- promptGuidelines: ["Use this tool when the user asks to summarize previously generated text."],
1301
+ promptGuidelines: ["Use my_tool when the user asks to summarize previously generated text."],
1039
1302
  parameters: Type.Object({
1040
1303
  action: StringEnum(["list", "add"] as const),
1041
1304
  text: Type.Optional(Type.String()),
@@ -1065,7 +1328,7 @@ pi.registerTool({
1065
1328
 
1066
1329
  ### pi.sendMessage(message, options?)
1067
1330
 
1068
- Inject a custom message into the session.
1331
+ Inject a custom message into the session. Custom messages participate in LLM context. For durable TUI-only content that should not be sent to the LLM, use [`pi.appendEntry()`](#piappendentrycustomtype-data) with [`pi.registerEntryRenderer()`](#piregisterentryrenderercustomtype-renderer).
1069
1332
 
1070
1333
  ```typescript
1071
1334
  pi.sendMessage({
@@ -1116,10 +1379,11 @@ See [send-user-message.ts](../examples/extensions/send-user-message.ts) for a co
1116
1379
 
1117
1380
  ### pi.appendEntry(customType, data?)
1118
1381
 
1119
- Persist extension state (does NOT participate in LLM context).
1382
+ Persist extension data. Custom entries do NOT participate in LLM context. In interactive mode, they can also render inside the chat transcript when paired with `pi.registerEntryRenderer()`.
1120
1383
 
1121
1384
  ```typescript
1122
1385
  pi.appendEntry("my-state", { count: 42 });
1386
+ pi.appendEntry("status-card", { title: "Indexed files", count: 17 });
1123
1387
 
1124
1388
  // Restore on reload
1125
1389
  pi.on("session_start", async (_event, ctx) => {
@@ -1237,7 +1501,27 @@ mode and would not execute if sent via `prompt`.
1237
1501
 
1238
1502
  ### pi.registerMessageRenderer(customType, renderer)
1239
1503
 
1240
- Register a custom TUI renderer for messages with your `customType`. See [Custom UI](#custom-ui).
1504
+ Register a custom TUI renderer for custom messages with your `customType`. Custom messages are created with `pi.sendMessage()` and participate in LLM context. See [Custom UI](#custom-ui).
1505
+
1506
+ ### pi.registerEntryRenderer(customType, renderer)
1507
+
1508
+ Register a custom TUI renderer for custom entries with your `customType`. Custom entries are created with `pi.appendEntry()` and do not participate in LLM context.
1509
+
1510
+ ```typescript
1511
+ import { Box, Text } from "@draht/tui";
1512
+
1513
+ pi.registerEntryRenderer("status-card", (entry, { expanded }, theme) => {
1514
+ const data = entry.data as { title: string; count: number };
1515
+ const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
1516
+ box.addChild(new Text(`${theme.bold(data.title)}: ${data.count}`));
1517
+ if (expanded) {
1518
+ box.addChild(new Text(theme.fg("dim", JSON.stringify(data, null, 2))));
1519
+ }
1520
+ return box;
1521
+ });
1522
+
1523
+ pi.appendEntry("status-card", { title: "Indexed files", count: 17 });
1524
+ ```
1241
1525
 
1242
1526
  ### pi.registerShortcut(shortcut, options)
1243
1527
 
@@ -1264,7 +1548,7 @@ pi.registerFlag("plan", {
1264
1548
  });
1265
1549
 
1266
1550
  // Check value
1267
- if (pi.getFlag("--plan")) {
1551
+ if (pi.getFlag("plan")) {
1268
1552
  // Plan mode enabled
1269
1553
  }
1270
1554
  ```
@@ -1288,7 +1572,8 @@ const all = pi.getAllTools();
1288
1572
  // [{
1289
1573
  // name: "read",
1290
1574
  // description: "Read file contents...",
1291
- // parameters: ...,
1575
+ // parameters: ...,
1576
+ // promptGuidelines: ["Use read to examine files instead of cat or sed."],
1292
1577
  // sourceInfo: { path: "<builtin:read>", source: "builtin", scope: "temporary", origin: "top-level" }
1293
1578
  // }, ...]
1294
1579
  const names = all.map(t => t.name);
@@ -1297,7 +1582,7 @@ const extensionTools = all.filter((t) => t.sourceInfo.source !== "builtin" && t.
1297
1582
  pi.setActiveTools(["read", "bash"]); // Switch to read-only
1298
1583
  ```
1299
1584
 
1300
- `pi.getAllTools()` returns `name`, `description`, `parameters`, and `sourceInfo`.
1585
+ `pi.getAllTools()` returns `name`, `description`, `parameters`, `promptGuidelines`, and `sourceInfo`.
1301
1586
 
1302
1587
  Typical `sourceInfo.source` values:
1303
1588
  - `builtin` for built-in tools
@@ -1320,7 +1605,7 @@ if (model) {
1320
1605
 
1321
1606
  ### pi.getThinkingLevel() / pi.setThinkingLevel(level)
1322
1607
 
1323
- Get or set the thinking level. Level is clamped to model capabilities (non-reasoning models always use "off").
1608
+ Get or set the thinking level. Level is clamped to model capabilities (non-reasoning models always use "off"). Changes emit `thinking_level_select`.
1324
1609
 
1325
1610
  ```typescript
1326
1611
  const current = pi.getThinkingLevel(); // "off" | "minimal" | "low" | "medium" | "high" | "xhigh"
@@ -1342,11 +1627,14 @@ Register or override a model provider dynamically. Useful for proxies, custom en
1342
1627
 
1343
1628
  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
1629
 
1630
+ 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`.
1631
+
1345
1632
  ```typescript
1346
1633
  // Register a new provider with custom models
1347
1634
  pi.registerProvider("my-proxy", {
1635
+ name: "My Proxy",
1348
1636
  baseUrl: "https://proxy.example.com",
1349
- apiKey: "PROXY_API_KEY", // env var name or literal
1637
+ apiKey: "$PROXY_API_KEY", // env var reference
1350
1638
  api: "anthropic-messages",
1351
1639
  models: [
1352
1640
  {
@@ -1391,12 +1679,13 @@ pi.registerProvider("corporate-ai", {
1391
1679
  ```
1392
1680
 
1393
1681
  **Config options:**
1682
+ - `name` - Display name for the provider in UI such as `/login`.
1394
1683
  - `baseUrl` - API endpoint URL. Required when defining models.
1395
- - `apiKey` - API key or environment variable name. Required when defining models (unless `oauth` provided).
1684
+ - `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
1685
  - `api` - API type: `"anthropic-messages"`, `"openai-completions"`, `"openai-responses"`, etc.
1397
1686
  - `headers` - Custom headers to include in requests.
1398
1687
  - `authHeader` - If true, adds `Authorization: Bearer` header automatically.
1399
- - `models` - Array of model definitions. If provided, replaces all existing models for this provider.
1688
+ - `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
1689
  - `oauth` - OAuth provider config for `/login` support. When provided, the provider appears in the login menu.
1401
1690
  - `streamSimple` - Custom streaming implementation for non-standard APIs.
1402
1691
 
@@ -1459,6 +1748,8 @@ Use `promptSnippet` for a short one-line entry in the `Available tools` section
1459
1748
 
1460
1749
  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
1750
 
1751
+ **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.
1752
+
1462
1753
  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
1754
 
1464
1755
  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 +1785,7 @@ async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
1494
1785
  ### Tool Definition
1495
1786
 
1496
1787
  ```typescript
1497
- import { Type } from "@sinclair/typebox";
1788
+ import { Type } from "typebox";
1498
1789
  import { StringEnum } from "@draht/ai";
1499
1790
  import { Text } from "@draht/tui";
1500
1791
 
@@ -1504,7 +1795,7 @@ pi.registerTool({
1504
1795
  description: "What this tool does (shown to LLM)",
1505
1796
  promptSnippet: "List or add items in the project todo list",
1506
1797
  promptGuidelines: [
1507
- "Use this tool for todo planning instead of direct file edits when the user asks for a task list."
1798
+ "Use my_tool for todo planning instead of direct file edits when the user asks for a task list."
1508
1799
  ],
1509
1800
  parameters: Type.Object({
1510
1801
  action: StringEnum(["list", "add"] as const), // Use StringEnum for Google compatibility
@@ -1538,6 +1829,9 @@ pi.registerTool({
1538
1829
  return {
1539
1830
  content: [{ type: "text", text: "Done" }], // Sent to LLM
1540
1831
  details: { data: result }, // For rendering & state
1832
+ // Optional: stop after this tool batch when every finalized tool result
1833
+ // in the batch also returns terminate: true.
1834
+ terminate: true,
1541
1835
  };
1542
1836
  },
1543
1837
 
@@ -1549,6 +1843,8 @@ pi.registerTool({
1549
1843
 
1550
1844
  **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
1845
 
1846
+ **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.
1847
+
1552
1848
  ```typescript
1553
1849
  // Correct: throw to signal an error
1554
1850
  async execute(toolCallId, params) {
@@ -1617,10 +1913,10 @@ Extensions can override built-in tools (`read`, `bash`, `edit`, `write`, `grep`,
1617
1913
  pi -e ./tool-override.ts
1618
1914
  ```
1619
1915
 
1620
- Alternatively, use `--no-tools` to start without any built-in tools:
1916
+ Alternatively, use `--no-builtin-tools` to start without any built-in tools while keeping extension tools enabled:
1621
1917
  ```bash
1622
1918
  # No built-in tools, only extension tools
1623
- pi --no-tools -e ./my-extension.ts
1919
+ pi --no-builtin-tools -e ./my-extension.ts
1624
1920
  ```
1625
1921
 
1626
1922
  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 +1928,13 @@ See [examples/extensions/tool-override.ts](../examples/extensions/tool-override.
1632
1928
  **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
1929
 
1634
1930
  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`
1931
+ - [read.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/read.ts) - `ReadToolDetails`
1932
+ - [bash.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/bash.ts) - `BashToolDetails`
1933
+ - [edit.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/edit.ts)
1934
+ - [write.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/write.ts)
1935
+ - [grep.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/grep.ts) - `GrepToolDetails`
1936
+ - [find.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/find.ts) - `FindToolDetails`
1937
+ - [ls.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/ls.ts) - `LsToolDetails`
1642
1938
 
1643
1939
  ### Remote Execution
1644
1940
 
@@ -1761,9 +2057,27 @@ export default function (pi: ExtensionAPI) {
1761
2057
 
1762
2058
  ### Custom Rendering
1763
2059
 
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.
2060
+ 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.
1765
2061
 
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.
2062
+ 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.
2063
+
2064
+ 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.
2065
+
2066
+ ```typescript
2067
+ pi.registerTool({
2068
+ name: "my_tool",
2069
+ label: "My Tool",
2070
+ description: "Custom shell example",
2071
+ parameters: Type.Object({}),
2072
+ renderShell: "self",
2073
+ async execute() {
2074
+ return { content: [{ type: "text", text: "ok" }], details: undefined };
2075
+ },
2076
+ renderCall(args, theme, context) {
2077
+ return new Text(theme.fg("accent", "my custom shell"), 0, 0);
2078
+ },
2079
+ });
2080
+ ```
1767
2081
 
1768
2082
  `renderCall` and `renderResult` each receive a `context` object with:
1769
2083
  - `args` - the current tool call arguments
@@ -1850,7 +2164,7 @@ Custom editors and `ctx.ui.custom()` components receive `keybindings: Keybinding
1850
2164
 
1851
2165
  #### Best Practices
1852
2166
 
1853
- - Use `Text` with padding `(0, 0)`. The Box handles padding.
2167
+ - Use `Text` with padding `(0, 0)`. The default Box handles padding.
1854
2168
  - Use `\n` for multi-line content.
1855
2169
  - Handle `isPartial` for streaming progress.
1856
2170
  - Support `expanded` for detail on demand.
@@ -1858,6 +2172,7 @@ Custom editors and `ctx.ui.custom()` components receive `keybindings: Keybinding
1858
2172
  - Read `context.args` in `renderResult` instead of copying args into `context.state`.
1859
2173
  - Use `context.state` only for data that must be shared across call and result slots.
1860
2174
  - Reuse `context.lastComponent` when the same component instance can be updated in place.
2175
+ - 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
2176
 
1862
2177
  #### Fallback
1863
2178
 
@@ -1874,8 +2189,9 @@ Extensions can interact with users via `ctx.ui` methods and customize how messag
1874
2189
  - Async operations with cancel (BorderedLoader)
1875
2190
  - Settings toggles (SettingsList)
1876
2191
  - Status indicators (setStatus)
1877
- - Working message during streaming (setWorkingMessage)
2192
+ - Working message, visibility, and indicator during streaming (`setWorkingMessage`, `setWorkingVisible`, `setWorkingIndicator`)
1878
2193
  - Widgets above/below editor (setWidget)
2194
+ - Autocomplete providers layered on top of built-in slash/path completion (addAutocompleteProvider)
1879
2195
  - Custom footers (setFooter)
1880
2196
 
1881
2197
  ### Dialogs
@@ -1955,9 +2271,25 @@ See [examples/extensions/timed-confirm.ts](../examples/extensions/timed-confirm.
1955
2271
  ctx.ui.setStatus("my-ext", "Processing...");
1956
2272
  ctx.ui.setStatus("my-ext", undefined); // Clear
1957
2273
 
1958
- // Working message (shown during streaming)
2274
+ // Working loader (shown during streaming)
1959
2275
  ctx.ui.setWorkingMessage("Thinking deeply...");
1960
2276
  ctx.ui.setWorkingMessage(); // Restore default
2277
+ ctx.ui.setWorkingVisible(false); // Hide the built-in working loader row entirely
2278
+ ctx.ui.setWorkingVisible(true); // Show the built-in working loader row
2279
+
2280
+ // Working indicator (shown during streaming)
2281
+ ctx.ui.setWorkingIndicator({ frames: [ctx.ui.theme.fg("accent", "●")] }); // Static dot
2282
+ ctx.ui.setWorkingIndicator({
2283
+ frames: [
2284
+ ctx.ui.theme.fg("dim", "·"),
2285
+ ctx.ui.theme.fg("muted", "•"),
2286
+ ctx.ui.theme.fg("accent", "●"),
2287
+ ctx.ui.theme.fg("muted", "•"),
2288
+ ],
2289
+ intervalMs: 120,
2290
+ });
2291
+ ctx.ui.setWorkingIndicator({ frames: [] }); // Hide indicator
2292
+ ctx.ui.setWorkingIndicator(); // Restore default spinner
1961
2293
 
1962
2294
  // Widget above editor (default)
1963
2295
  ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"]);
@@ -1983,6 +2315,29 @@ const current = ctx.ui.getEditorText();
1983
2315
  // Paste into editor (triggers paste handling, including collapse for large content)
1984
2316
  ctx.ui.pasteToEditor("pasted content");
1985
2317
 
2318
+ // Stack custom autocomplete behavior on top of the built-in provider
2319
+ ctx.ui.addAutocompleteProvider((current) => ({
2320
+ triggerCharacters: ["#"],
2321
+ async getSuggestions(lines, line, col, options) {
2322
+ const beforeCursor = (lines[line] ?? "").slice(0, col);
2323
+ const match = beforeCursor.match(/(?:^|[ \t])#([^\s#]*)$/);
2324
+ if (!match) {
2325
+ return current.getSuggestions(lines, line, col, options);
2326
+ }
2327
+
2328
+ return {
2329
+ prefix: `#${match[1] ?? ""}`,
2330
+ items: [{ value: "#2983", label: "#2983", description: "Extension API for autocomplete" }],
2331
+ };
2332
+ },
2333
+ applyCompletion(lines, line, col, item, prefix) {
2334
+ return current.applyCompletion(lines, line, col, item, prefix);
2335
+ },
2336
+ shouldTriggerFileCompletion(lines, line, col) {
2337
+ return current.shouldTriggerFileCompletion?.(lines, line, col) ?? true;
2338
+ },
2339
+ }));
2340
+
1986
2341
  // Tool output expansion
1987
2342
  const wasExpanded = ctx.ui.getToolsExpanded();
1988
2343
  ctx.ui.setToolsExpanded(true);
@@ -1990,6 +2345,10 @@ ctx.ui.setToolsExpanded(wasExpanded);
1990
2345
 
1991
2346
  // Custom editor (vim mode, emacs mode, etc.)
1992
2347
  ctx.ui.setEditorComponent((tui, theme, keybindings) => new VimEditor(tui, theme, keybindings));
2348
+ const currentEditor = ctx.ui.getEditorComponent();
2349
+ ctx.ui.setEditorComponent((tui, theme, keybindings) =>
2350
+ new WrappedEditor(tui, theme, keybindings, currentEditor?.(tui, theme, keybindings))
2351
+ );
1993
2352
  ctx.ui.setEditorComponent(undefined); // Restore default editor
1994
2353
 
1995
2354
  // Theme management (see themes.md for creating themes)
@@ -2003,6 +2362,53 @@ ctx.ui.setTheme(lightTheme!); // Or switch by Theme object
2003
2362
  ctx.ui.theme.fg("accent", "styled text"); // Access current theme
2004
2363
  ```
2005
2364
 
2365
+ 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(...)`.
2366
+
2367
+ ### Autocomplete Providers
2368
+
2369
+ 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 `$`.
2370
+
2371
+ Typical pattern:
2372
+
2373
+ - inspect the text before the cursor
2374
+ - return your own suggestions when your extension-specific syntax matches
2375
+ - otherwise delegate to `current.getSuggestions(...)`
2376
+ - delegate `applyCompletion(...)` unless you need custom insertion behavior
2377
+
2378
+ ```typescript
2379
+ pi.on("session_start", (_event, ctx) => {
2380
+ ctx.ui.addAutocompleteProvider((current) => ({
2381
+ triggerCharacters: ["#"],
2382
+ async getSuggestions(lines, cursorLine, cursorCol, options) {
2383
+ const line = lines[cursorLine] ?? "";
2384
+ const beforeCursor = line.slice(0, cursorCol);
2385
+ const match = beforeCursor.match(/(?:^|[ \t])#([^\s#]*)$/);
2386
+ if (!match) {
2387
+ return current.getSuggestions(lines, cursorLine, cursorCol, options);
2388
+ }
2389
+
2390
+ return {
2391
+ prefix: `#${match[1] ?? ""}`,
2392
+ items: [
2393
+ { value: "#2983", label: "#2983", description: "Extension API for registering custom @ autocomplete providers" },
2394
+ { value: "#2753", label: "#2753", description: "Reload stale resource settings" },
2395
+ ],
2396
+ };
2397
+ },
2398
+
2399
+ applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
2400
+ return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
2401
+ },
2402
+
2403
+ shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
2404
+ return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
2405
+ },
2406
+ }));
2407
+ });
2408
+ ```
2409
+
2410
+ 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.
2411
+
2006
2412
  ### Custom Components
2007
2413
 
2008
2414
  For complex UI, use `ctx.ui.custom()`. This temporarily replaces the editor with your component until `done()` is called:
@@ -2046,7 +2452,7 @@ const result = await ctx.ui.custom<string | null>(
2046
2452
  );
2047
2453
  ```
2048
2454
 
2049
- For advanced positioning (anchors, margins, percentages, responsive visibility), pass `overlayOptions`. Use `onHandle` to control visibility programmatically:
2455
+ For advanced positioning (anchors, margins, percentages, responsive visibility), pass `overlayOptions`. Use `onHandle` to control focus or visibility programmatically:
2050
2456
 
2051
2457
  ```typescript
2052
2458
  const result = await ctx.ui.custom<string | null>(
@@ -2054,12 +2460,19 @@ const result = await ctx.ui.custom<string | null>(
2054
2460
  {
2055
2461
  overlay: true,
2056
2462
  overlayOptions: { anchor: "top-right", width: "50%", margin: 2 },
2057
- onHandle: (handle) => { /* handle.setHidden(true/false) */ }
2463
+ onHandle: (handle) => {
2464
+ handle.focus(); // focus this overlay and bring it to the visual front
2465
+ // handle.unfocus({ target: editorComponent }); // release input to a specific component
2466
+ // handle.setHidden(true/false); // toggle visibility
2467
+ // handle.hide(); // permanently remove
2468
+ }
2058
2469
  }
2059
2470
  );
2060
2471
  ```
2061
2472
 
2062
- See [tui.md](tui.md) for the full `OverlayOptions` API and [overlay-qa-tests.ts](../examples/extensions/overlay-qa-tests.ts) for examples.
2473
+ 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.
2474
+
2475
+ 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
2476
 
2064
2477
  ### Custom Editor
2065
2478
 
@@ -2098,13 +2511,23 @@ export default function (pi: ExtensionAPI) {
2098
2511
  - Extend `CustomEditor` (not base `Editor`) to get app keybindings (escape to abort, ctrl+d, model switching)
2099
2512
  - Call `super.handleInput(data)` for keys you don't handle
2100
2513
  - Factory receives `theme` and `keybindings` from the app
2514
+ - Use `ctx.ui.getEditorComponent()` before `setEditorComponent()` to wrap the previously configured custom editor
2101
2515
  - Pass `undefined` to restore default: `ctx.ui.setEditorComponent(undefined)`
2102
2516
 
2517
+ To compose with another extension that already replaced the editor, capture the previous factory before setting yours:
2518
+
2519
+ ```typescript
2520
+ const previous = ctx.ui.getEditorComponent();
2521
+ ctx.ui.setEditorComponent((tui, theme, keybindings) =>
2522
+ new MyEditor(tui, theme, keybindings, { base: previous?.(tui, theme, keybindings) })
2523
+ );
2524
+ ```
2525
+
2103
2526
  See [tui.md](tui.md) Pattern 7 for a complete example with mode indicator.
2104
2527
 
2105
- ### Message Rendering
2528
+ ### Message and Entry Rendering
2106
2529
 
2107
- Register a custom renderer for messages with your `customType`:
2530
+ Register a custom renderer for messages with your `customType`. Use message renderers for content that should participate in LLM context:
2108
2531
 
2109
2532
  ```typescript
2110
2533
  import { Text } from "@draht/tui";
@@ -2133,6 +2556,16 @@ pi.sendMessage({
2133
2556
  });
2134
2557
  ```
2135
2558
 
2559
+ For TUI-only content that should not be sent to the LLM, render custom entries instead:
2560
+
2561
+ ```typescript
2562
+ pi.registerEntryRenderer("my-card", (entry, options, theme) => {
2563
+ return new Text(theme.fg("accent", JSON.stringify(entry.data)));
2564
+ });
2565
+
2566
+ pi.appendEntry("my-card", { status: "done" });
2567
+ ```
2568
+
2136
2569
  ### Theme Colors
2137
2570
 
2138
2571
  All render functions receive a `theme` object. See [themes.md](themes.md) for creating custom themes and the full color palette.
@@ -2174,14 +2607,14 @@ const highlighted = highlightCode(code, lang, theme);
2174
2607
 
2175
2608
  ## Mode Behavior
2176
2609
 
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 |
2610
+ | Mode | `ctx.mode` | `ctx.hasUI` | Notes |
2611
+ |------|------------|-------------|-------|
2612
+ | Interactive | `"tui"` | `true` | Full TUI with terminal rendering |
2613
+ | RPC (`--mode rpc`) | `"rpc"` | `true` | Dialogs and notifications via JSON protocol; `custom()` returns `undefined`. See [rpc.md](rpc.md) |
2614
+ | JSON (`--mode json`) | `"json"` | `false` | Event stream to stdout; UI methods are no-ops |
2615
+ | Print (`-p`) | `"print"` | `false` | Extensions run but can't prompt |
2183
2616
 
2184
- In non-interactive modes, check `ctx.hasUI` before using UI methods.
2617
+ 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
2618
 
2186
2619
  ## Examples Reference
2187
2620
 
@@ -2195,6 +2628,7 @@ All examples in [examples/extensions/](../examples/extensions/).
2195
2628
  | `questionnaire.ts` | Multi-step wizard tool | `registerTool`, `ui.custom` |
2196
2629
  | `todo.ts` | Stateful tool with persistence | `registerTool`, `appendEntry`, `renderResult`, session events |
2197
2630
  | `dynamic-tools.ts` | Register tools after startup and during commands | `registerTool`, `session_start`, `registerCommand` |
2631
+ | `structured-output.ts` | Final structured-output tool with `terminate: true` | `registerTool`, terminating tool results |
2198
2632
  | `truncated-tool.ts` | Output truncation example | `registerTool`, `truncateHead` |
2199
2633
  | `tool-override.ts` | Override built-in read tool | `registerTool` (same name as built-in) |
2200
2634
  | **Commands** |||
@@ -2207,22 +2641,28 @@ All examples in [examples/extensions/](../examples/extensions/).
2207
2641
  | `shutdown-command.ts` | Graceful shutdown command | `registerCommand`, `shutdown()` |
2208
2642
  | **Events & Gates** |||
2209
2643
  | `permission-gate.ts` | Block dangerous commands | `on("tool_call")`, `ui.confirm` |
2644
+ | `project-trust.ts` | Decide or defer project trust from a user/global or CLI extension | `on("project_trust")`, trust UI, required trust result |
2210
2645
  | `protected-paths.ts` | Block writes to specific paths | `on("tool_call")` |
2211
2646
  | `confirm-destructive.ts` | Confirm session changes | `on("session_before_switch")`, `on("session_before_fork")` |
2212
2647
  | `dirty-repo-guard.ts` | Warn on dirty git repo | `on("session_before_*")`, `exec` |
2213
2648
  | `input-transform.ts` | Transform user input | `on("input")` |
2649
+ | `input-transform-streaming.ts` | Streaming-aware input transform | `on("input")`, `streamingBehavior` |
2214
2650
  | `model-status.ts` | React to model changes | `on("model_select")`, `setStatus` |
2215
- | `provider-payload.ts` | Inspect or patch provider payloads | `on("before_provider_request")` |
2651
+ | `provider-payload.ts` | Inspect payloads and provider response headers | `on("before_provider_request")`, `on("after_provider_response")` |
2216
2652
  | `system-prompt-header.ts` | Display system prompt info | `on("agent_start")`, `getSystemPrompt` |
2217
2653
  | `claude-rules.ts` | Load rules from files | `on("session_start")`, `on("before_agent_start")` |
2654
+ | `prompt-customizer.ts` | Add context-aware tool guidance using `systemPromptOptions` | `on("before_agent_start")`, `BuildSystemPromptOptions` |
2218
2655
  | `file-trigger.ts` | File watcher triggers messages | `sendMessage` |
2219
2656
  | **Compaction & Sessions** |||
2220
2657
  | `custom-compaction.ts` | Custom compaction summary | `on("session_before_compact")` |
2221
2658
  | `trigger-compact.ts` | Trigger compaction manually | `compact()` |
2222
2659
  | `git-checkpoint.ts` | Git stash on turns | `on("turn_start")`, `on("session_before_fork")`, `exec` |
2660
+ | `git-merge-and-resolve.ts` | Fetch, merge, and resolve conflicts | `on("agent_end")`, `exec`, `sendUserMessage` |
2223
2661
  | `auto-commit-on-exit.ts` | Commit on shutdown | `on("session_shutdown")`, `exec` |
2224
2662
  | **UI Components** |||
2225
2663
  | `status-line.ts` | Footer status indicator | `setStatus`, session events |
2664
+ | `working-indicator.ts` | Customize the streaming working indicator | `setWorkingIndicator`, `registerCommand` |
2665
+ | `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
2666
  | `custom-footer.ts` | Replace footer entirely | `registerCommand`, `setFooter` |
2227
2667
  | `custom-header.ts` | Replace startup header | `on("session_start")`, `setHeader` |
2228
2668
  | `modal-editor.ts` | Vim-style modal editor | `setEditorComponent`, `CustomEditor` |
@@ -2241,6 +2681,7 @@ All examples in [examples/extensions/](../examples/extensions/).
2241
2681
  | `ssh.ts` | SSH remote execution | `registerFlag`, `on("user_bash")`, `on("before_agent_start")`, tool operations |
2242
2682
  | `interactive-shell.ts` | Persistent shell session | `on("user_bash")` |
2243
2683
  | `sandbox/` | Sandboxed tool execution | Tool operations |
2684
+ | `gondolin/` | Route built-in tools and `!` commands into a Gondolin micro-VM | Tool operations, built-in tool overrides, `on("user_bash")` |
2244
2685
  | `subagent/` | Spawn sub-agents | `registerTool`, `exec` |
2245
2686
  | **Games** |||
2246
2687
  | `snake.ts` | Snake game | `registerCommand`, `ui.custom`, keyboard handling |
@@ -2251,12 +2692,12 @@ All examples in [examples/extensions/](../examples/extensions/).
2251
2692
  | `custom-provider-gitlab-duo/` | GitLab Duo integration | `registerProvider` with OAuth |
2252
2693
  | **Messages & Communication** |||
2253
2694
  | `message-renderer.ts` | Custom message rendering | `registerMessageRenderer`, `sendMessage` |
2695
+ | `entry-renderer.ts` | TUI-only custom entry rendering | `registerEntryRenderer`, `appendEntry` |
2254
2696
  | `event-bus.ts` | Inter-extension events | `pi.events` |
2255
2697
  | **Session Metadata** |||
2256
2698
  | `session-name.ts` | Name sessions for selector | `setSessionName`, `getSessionName` |
2257
2699
  | `bookmark.ts` | Bookmark entries for /tree | `setLabel` |
2258
2700
  | **Misc** |||
2259
- | `antigravity-image-gen.ts` | Image generation tool | `registerTool`, Google Antigravity |
2260
2701
  | `inline-bash.ts` | Inline bash in tool calls | `on("tool_call")` |
2261
2702
  | `bash-spawn-hook.ts` | Adjust bash command, cwd, and env before execution | `createBashTool`, `spawnHook` |
2262
2703
  | `with-deps/` | Extension with npm dependencies | Package structure with `package.json` |