@geoqiao/pi-ask 1.2.2 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. package/CHANGELOG.md +67 -85
  2. package/README.md +22 -15
  3. package/docs/architecture.md +6 -1
  4. package/docs/configuration.md +4 -3
  5. package/docs/contract.md +34 -14
  6. package/docs/remote-events.md +14 -14
  7. package/package.json +20 -77
  8. package/skills/ask-user/SKILL.md +2 -0
  9. package/src/answer-commands.ts +37 -10
  10. package/src/answer-extraction.ts +155 -115
  11. package/src/ask-payload-store.ts +23 -1
  12. package/src/ask-tool-helpers.ts +12 -11
  13. package/src/ask-tool.ts +2 -0
  14. package/src/constants/ui.ts +1 -0
  15. package/src/index.ts +2 -0
  16. package/src/pending-ask.ts +128 -0
  17. package/src/remote-ask.ts +11 -6
  18. package/src/result-format.ts +13 -3
  19. package/src/result.ts +1 -1
  20. package/src/resume-pending-ask.ts +95 -0
  21. package/src/rpc/controller.ts +2 -1
  22. package/src/schema.ts +59 -24
  23. package/src/state/create.ts +1 -1
  24. package/src/state/normalize.ts +50 -31
  25. package/src/state/result.ts +3 -0
  26. package/src/types.ts +1 -0
  27. package/src/ui/render-helpers.ts +9 -2
  28. package/src/ui/render-question.ts +39 -7
  29. package/src/ui/view-models/question.ts +2 -0
package/CHANGELOG.md CHANGED
@@ -1,217 +1,199 @@
1
- ## [1.2.2](https://github.com/geoqiao/pi-ask/compare/v1.2.1...v1.2.2) (2026-08-16)
1
+ ## 1.3.0
2
+
3
+ ### Minor Changes
4
+
5
+ - 95d65c7: Align the public ask schema with Pi validation, recover interrupted TUI forms, surface unanswered questions, add recommendation metadata across TUI, RPC, results, and remote events, and use validated synthetic tool calls for `/answer` extraction.
6
+
7
+ ## 1.2.3
8
+
9
+ ### Patch Changes
2
10
 
11
+ - Publish `@geoqiao/pi-ask` independently from the new `geoqiao/pi-tools` workspace without changing its runtime contract.
12
+
13
+ ## [1.2.2](https://github.com/geoqiao/pi-ask/compare/v1.2.1...v1.2.2) (2026-08-16)
3
14
 
4
15
  ### Bug Fixes
5
16
 
6
- * simplify RPC question flow ([68a0f29](https://github.com/geoqiao/pi-ask/commit/68a0f29cc88dae906fe4a105714eb71d45654776))
17
+ - simplify RPC question flow ([68a0f29](https://github.com/geoqiao/pi-ask/commit/68a0f29cc88dae906fe4a105714eb71d45654776))
7
18
 
8
19
  ## [1.2.1](https://github.com/geoqiao/pi-ask/compare/v1.2.0...v1.2.1) (2026-08-16)
9
20
 
10
-
11
21
  ### Bug Fixes
12
22
 
13
- * harden RPC fallback interactions ([4cceb3b](https://github.com/geoqiao/pi-ask/commit/4cceb3b2ab8d19b46f4688a53f8b7ae52e2b06ae))
23
+ - harden RPC fallback interactions ([4cceb3b](https://github.com/geoqiao/pi-ask/commit/4cceb3b2ab8d19b46f4688a53f8b7ae52e2b06ae))
14
24
 
15
25
  # [1.2.0](https://github.com/geoqiao/pi-ask/compare/v1.1.0...v1.2.0) (2026-08-16)
16
26
 
17
-
18
27
  ### Bug Fixes
19
28
 
20
- * preserve RPC yes-no cancellation semantics ([9e5265d](https://github.com/geoqiao/pi-ask/commit/9e5265dec7ef6a990a3ac8a8aca190429a942fb7))
21
-
29
+ - preserve RPC yes-no cancellation semantics ([9e5265d](https://github.com/geoqiao/pi-ask/commit/9e5265dec7ef6a990a3ac8a8aca190429a942fb7))
22
30
 
23
31
  ### Features
24
32
 
25
- * add portable RPC ask fallback ([6def4ed](https://github.com/geoqiao/pi-ask/commit/6def4ed1c803980b5da89ccfc2de1d56f54bef99))
33
+ - add portable RPC ask fallback ([6def4ed](https://github.com/geoqiao/pi-ask/commit/6def4ed1c803980b5da89ccfc2de1d56f54bef99))
26
34
 
27
35
  # [1.1.0](https://github.com/eko24ive/pi-ask/compare/v1.0.2...v1.1.0) (2026-06-22)
28
36
 
29
-
30
37
  ### Bug Fixes
31
38
 
32
- * refresh pi dependency compatibility ([d6db94a](https://github.com/eko24ive/pi-ask/commit/d6db94a39d37fda632d53147592af8f53aa50e4b))
33
-
39
+ - refresh pi dependency compatibility ([d6db94a](https://github.com/eko24ive/pi-ask/commit/d6db94a39d37fda632d53147592af8f53aa50e4b))
34
40
 
35
41
  ### Features
36
42
 
37
- * add remote ask event contract ([69e8bab](https://github.com/eko24ive/pi-ask/commit/69e8bab6efbc0394aecb9ce416eea27da755a5df)), closes [#6](https://github.com/eko24ive/pi-ask/issues/6)
43
+ - add remote ask event contract ([69e8bab](https://github.com/eko24ive/pi-ask/commit/69e8bab6efbc0394aecb9ce416eea27da755a5df)), closes [#6](https://github.com/eko24ive/pi-ask/issues/6)
38
44
 
39
45
  ## [1.0.2](https://github.com/eko24ive/pi-ask/compare/v1.0.1...v1.0.2) (2026-05-31)
40
46
 
41
-
42
47
  ### Bug Fixes
43
48
 
44
- * avoid destructive ask config writes ([fa89c15](https://github.com/eko24ive/pi-ask/commit/fa89c1551a509690dee767165124450aac322c58))
49
+ - avoid destructive ask config writes ([fa89c15](https://github.com/eko24ive/pi-ask/commit/fa89c1551a509690dee767165124450aac322c58))
45
50
 
46
51
  ## [1.0.1](https://github.com/eko24ive/pi-ask/compare/v1.0.0...v1.0.1) (2026-05-22)
47
52
 
48
-
49
53
  ### Bug Fixes
50
54
 
51
- * avoid config docs supply-chain false positive ([5d12c2f](https://github.com/eko24ive/pi-ask/commit/5d12c2fb8da82ca538999be65f58595c8aa54dde))
52
- * clarify ask_user prompt guidelines ([4afbe62](https://github.com/eko24ive/pi-ask/commit/4afbe62a42c80b13b8c77112a25cc68ab18ea3fa))
55
+ - avoid config docs supply-chain false positive ([5d12c2f](https://github.com/eko24ive/pi-ask/commit/5d12c2fb8da82ca538999be65f58595c8aa54dde))
56
+ - clarify ask_user prompt guidelines ([4afbe62](https://github.com/eko24ive/pi-ask/commit/4afbe62a42c80b13b8c77112a25cc68ab18ea3fa))
53
57
 
54
58
  # [1.0.0](https://github.com/eko24ive/pi-ask/compare/v0.9.0...v1.0.0) (2026-05-22)
55
59
 
56
-
57
- * feat!: migrate to latest pi packages ([a987406](https://github.com/eko24ive/pi-ask/commit/a9874062a50d4073a5379667620e1f2e457148a2))
58
-
60
+ - feat!: migrate to latest pi packages ([a987406](https://github.com/eko24ive/pi-ask/commit/a9874062a50d4073a5379667620e1f2e457148a2))
59
61
 
60
62
  ### BREAKING CHANGES
61
63
 
62
- * pi dependencies moved from @mariozechner/* to @earendil-works/*.
64
+ - pi dependencies moved from `@mariozechner/*` to `@earendil-works/*`.
63
65
 
64
66
  Consumers must use the latest pi package scope.
65
67
 
66
68
  # [0.9.0](https://github.com/eko24ive/pi-ask/compare/v0.8.1...v0.9.0) (2026-05-06)
67
69
 
68
-
69
70
  ### Bug Fixes
70
71
 
71
- * remove footer navigation hints ([45d8302](https://github.com/eko24ive/pi-ask/commit/45d8302e0a2e1527f0129bbb53fec38927a722ac))
72
-
72
+ - remove footer navigation hints ([45d8302](https://github.com/eko24ive/pi-ask/commit/45d8302e0a2e1527f0129bbb53fec38927a722ac))
73
73
 
74
74
  ### Features
75
75
 
76
- * add ask notifications ([43cee4c](https://github.com/eko24ive/pi-ask/commit/43cee4c0f0cbbaf9673b67ca300ff5b05117819c))
77
- * add context-aware ask keymaps ([808b62c](https://github.com/eko24ive/pi-ask/commit/808b62cc77ee23093f2f672679ada1c34ec1a978))
78
- * add guarded config reset ([b218b8b](https://github.com/eko24ive/pi-ask/commit/b218b8b1889b163e5bd21fcb5083250921404a02))
79
- * add question type presentation controls ([f1a0a5d](https://github.com/eko24ive/pi-ask/commit/f1a0a5d5e5eb3591b90200921e88660517830dec))
76
+ - add ask notifications ([43cee4c](https://github.com/eko24ive/pi-ask/commit/43cee4c0f0cbbaf9673b67ca300ff5b05117819c))
77
+ - add context-aware ask keymaps ([808b62c](https://github.com/eko24ive/pi-ask/commit/808b62cc77ee23093f2f672679ada1c34ec1a978))
78
+ - add guarded config reset ([b218b8b](https://github.com/eko24ive/pi-ask/commit/b218b8b1889b163e5bd21fcb5083250921404a02))
79
+ - add question type presentation controls ([f1a0a5d](https://github.com/eko24ive/pi-ask/commit/f1a0a5d5e5eb3591b90200921e88660517830dec))
80
80
 
81
81
  ## [0.8.1](https://github.com/eko24ive/pi-ask/compare/v0.8.0...v0.8.1) (2026-05-03)
82
82
 
83
-
84
83
  ### Bug Fixes
85
84
 
86
- * multi-select custom answer toggling ([780aac2](https://github.com/eko24ive/pi-ask/commit/780aac24cf58e144a8ab3ba6a29a75cf6fbf2656))
87
- * refine ask tool context typing ([cbabd44](https://github.com/eko24ive/pi-ask/commit/cbabd44acc0fadd4959602e8aa73c1c106856aad))
85
+ - multi-select custom answer toggling ([780aac2](https://github.com/eko24ive/pi-ask/commit/780aac24cf58e144a8ab3ba6a29a75cf6fbf2656))
86
+ - refine ask tool context typing ([cbabd44](https://github.com/eko24ive/pi-ask/commit/cbabd44acc0fadd4959602e8aa73c1c106856aad))
88
87
 
89
88
  # [0.8.0](https://github.com/eko24ive/pi-ask/compare/v0.7.0...v0.8.0) (2026-05-02)
90
89
 
91
-
92
90
  ### Bug Fixes
93
91
 
94
- * rename settings modal title ([4feeec9](https://github.com/eko24ive/pi-ask/commit/4feeec9f0f535b4a129c8ce5d0f310f1365c6010))
95
-
92
+ - rename settings modal title ([4feeec9](https://github.com/eko24ive/pi-ask/commit/4feeec9f0f535b4a129c8ce5d0f310f1365c6010))
96
93
 
97
94
  ### Features
98
95
 
99
- * add answer extraction replay commands ([5b70eca](https://github.com/eko24ive/pi-ask/commit/5b70eca306e15335e0a24754280c1ea6d9787bbf))
100
- * **config:** add migration framework ([288caf4](https://github.com/eko24ive/pi-ask/commit/288caf49de4a78e35845187f736b9685f732c5cc))
96
+ - add answer extraction replay commands ([5b70eca](https://github.com/eko24ive/pi-ask/commit/5b70eca306e15335e0a24754280c1ea6d9787bbf))
97
+ - **config:** add migration framework ([288caf4](https://github.com/eko24ive/pi-ask/commit/288caf49de4a78e35845187f736b9685f732c5cc))
101
98
 
102
99
  # [0.7.0](https://github.com/eko24ive/pi-ask/compare/v0.6.1...v0.7.0) (2026-04-29)
103
100
 
104
-
105
101
  ### Bug Fixes
106
102
 
107
- * **package:** declare bundled skills in pi manifest ([3c26bfa](https://github.com/eko24ive/pi-ask/commit/3c26bfa7c995fd4fb22d391db784ceaf76594e4c))
108
- * pass custom answers through elaborate output ([85962d9](https://github.com/eko24ive/pi-ask/commit/85962d985d7a8064093f8643f4706d8d98888050))
109
-
103
+ - **package:** declare bundled skills in pi manifest ([3c26bfa](https://github.com/eko24ive/pi-ask/commit/3c26bfa7c995fd4fb22d391db784ceaf76594e4c))
104
+ - pass custom answers through elaborate output ([85962d9](https://github.com/eko24ive/pi-ask/commit/85962d985d7a8064093f8643f4706d8d98888050))
110
105
 
111
106
  ### Features
112
107
 
113
- * add ask settings modal shell ([5c0d896](https://github.com/eko24ive/pi-ask/commit/5c0d8964fba099e85472c42ab442bd5b86480de1))
114
- * add config-backed ask keymaps ([e8a36b7](https://github.com/eko24ive/pi-ask/commit/e8a36b72eff4f43f8d3944846dbe58bb605210a9))
115
- * add dirty-dismiss and footer hint settings ([18120e8](https://github.com/eko24ive/pi-ask/commit/18120e880119cff23e2fdc2cf49cdf3fbb512829))
116
- * add review shortcut confirmation setting ([67891d1](https://github.com/eko24ive/pi-ask/commit/67891d147f4bde4bb84edc1e8eca4d91786c1056))
117
- * bootstrap ask config on first use ([2bf85b3](https://github.com/eko24ive/pi-ask/commit/2bf85b3f6f19a71972df8b989ccc6670397c4e38))
118
- * **ui:** add ask keymap help modal ([c9930b4](https://github.com/eko24ive/pi-ask/commit/c9930b494f89320498db9b9828415f331605c3ff))
108
+ - add ask settings modal shell ([5c0d896](https://github.com/eko24ive/pi-ask/commit/5c0d8964fba099e85472c42ab442bd5b86480de1))
109
+ - add config-backed ask keymaps ([e8a36b7](https://github.com/eko24ive/pi-ask/commit/e8a36b72eff4f43f8d3944846dbe58bb605210a9))
110
+ - add dirty-dismiss and footer hint settings ([18120e8](https://github.com/eko24ive/pi-ask/commit/18120e880119cff23e2fdc2cf49cdf3fbb512829))
111
+ - add review shortcut confirmation setting ([67891d1](https://github.com/eko24ive/pi-ask/commit/67891d147f4bde4bb84edc1e8eca4d91786c1056))
112
+ - bootstrap ask config on first use ([2bf85b3](https://github.com/eko24ive/pi-ask/commit/2bf85b3f6f19a71972df8b989ccc6670397c4e38))
113
+ - **ui:** add ask keymap help modal ([c9930b4](https://github.com/eko24ive/pi-ask/commit/c9930b494f89320498db9b9828415f331605c3ff))
119
114
 
120
115
  ## [0.6.1](https://github.com/eko24ive/pi-ask/compare/v0.6.0...v0.6.1) (2026-04-27)
121
116
 
122
-
123
117
  ### Bug Fixes
124
118
 
125
- * remove automatic lefthook install ([4f1c598](https://github.com/eko24ive/pi-ask/commit/4f1c59818137cbcd335d5153c835e3f420aab575))
119
+ - remove automatic lefthook install ([4f1c598](https://github.com/eko24ive/pi-ask/commit/4f1c59818137cbcd335d5153c835e3f420aab575))
126
120
 
127
121
  # [0.6.0](https://github.com/eko24ive/pi-ask/compare/v0.5.1...v0.6.0) (2026-04-25)
128
122
 
129
-
130
123
  ### Bug Fixes
131
124
 
132
- * **ui:** tighten ask layout rendering ([3515098](https://github.com/eko24ive/pi-ask/commit/351509838cd14ad251ca4b152c0bb4577c9d7b79))
133
-
125
+ - **ui:** tighten ask layout rendering ([3515098](https://github.com/eko24ive/pi-ask/commit/351509838cd14ad251ca4b152c0bb4577c9d7b79))
134
126
 
135
127
  ### Features
136
128
 
137
- * **ui:** improve narrow-screen tab and footer rendering ([1ce7210](https://github.com/eko24ive/pi-ask/commit/1ce721094c21faf6180098a7244b6f2abd13623e))
138
- * **ui:** split submit tab into actions and review ([b59c967](https://github.com/eko24ive/pi-ask/commit/b59c967d985a6f62dc32da3b4f2c5767d01608a9))
139
- * **ui:** support custom answers in preview questions ([7cca5eb](https://github.com/eko24ive/pi-ask/commit/7cca5eb54d1964d19ce17ebb45507f1939960b8b))
129
+ - **ui:** improve narrow-screen tab and footer rendering ([1ce7210](https://github.com/eko24ive/pi-ask/commit/1ce721094c21faf6180098a7244b6f2abd13623e))
130
+ - **ui:** split submit tab into actions and review ([b59c967](https://github.com/eko24ive/pi-ask/commit/b59c967d985a6f62dc32da3b4f2c5767d01608a9))
131
+ - **ui:** support custom answers in preview questions ([7cca5eb](https://github.com/eko24ive/pi-ask/commit/7cca5eb54d1964d19ce17ebb45507f1939960b8b))
140
132
 
141
133
  ## [0.5.1](https://github.com/eko24ive/pi-ask/compare/v0.5.0...v0.5.1) (2026-04-25)
142
134
 
143
-
144
135
  ### Bug Fixes
145
136
 
146
- * **skills:** align bundled skill name with folder ([005151f](https://github.com/eko24ive/pi-ask/commit/005151f79ba562c08e0fe9b5bccf59e964c02a32))
137
+ - **skills:** align bundled skill name with folder ([005151f](https://github.com/eko24ive/pi-ask/commit/005151f79ba562c08e0fe9b5bccf59e964c02a32))
147
138
 
148
139
  # [0.5.0](https://github.com/eko24ive/pi-ask/compare/v0.4.0...v0.5.0) (2026-04-24)
149
140
 
150
-
151
141
  ### Features
152
142
 
153
- * add submit screen number hotkeys ([c10c61f](https://github.com/eko24ive/pi-ask/commit/c10c61f1ebb061dab1daf7404089ce6b57c8917c))
154
- * **skill:** add ask-user decision gate profile ([6d9cb5b](https://github.com/eko24ive/pi-ask/commit/6d9cb5b7bfde54c7522f8e8321046161af296dad))
143
+ - add submit screen number hotkeys ([c10c61f](https://github.com/eko24ive/pi-ask/commit/c10c61f1ebb061dab1daf7404089ce6b57c8917c))
144
+ - **skill:** add ask-user decision gate profile ([6d9cb5b](https://github.com/eko24ive/pi-ask/commit/6d9cb5b7bfde54c7522f8e8321046161af296dad))
155
145
 
156
146
  # [0.4.0](https://github.com/eko24ive/pi-ask/compare/v0.3.0...v0.4.0) (2026-04-24)
157
147
 
158
-
159
148
  ### Features
160
149
 
161
- * improve ask flow elaboration and validation ([b7c7301](https://github.com/eko24ive/pi-ask/commit/b7c7301f974c81eb82070810304a9267f62d7699))
150
+ - improve ask flow elaboration and validation ([b7c7301](https://github.com/eko24ive/pi-ask/commit/b7c7301f974c81eb82070810304a9267f62d7699))
162
151
 
163
152
  # [0.3.0](https://github.com/eko24ive/pi-ask/compare/v0.2.0...v0.3.0) (2026-04-23)
164
153
 
165
-
166
154
  ### Bug Fixes
167
155
 
168
- * allow empty editor navigation shortcuts ([5d7ccc8](https://github.com/eko24ive/pi-ask/commit/5d7ccc8ce2e45c70a36932f048a90419dcb59304))
169
-
156
+ - allow empty editor navigation shortcuts ([5d7ccc8](https://github.com/eko24ive/pi-ask/commit/5d7ccc8ce2e45c70a36932f048a90419dcb59304))
170
157
 
171
158
  ### Features
172
159
 
173
- * harden ask tool validation and fallback ([050e880](https://github.com/eko24ive/pi-ask/commit/050e8800cdcd97be635bb95d9500a309d207f7f8))
160
+ - harden ask tool validation and fallback ([050e880](https://github.com/eko24ive/pi-ask/commit/050e8800cdcd97be635bb95d9500a309d207f7f8))
174
161
 
175
162
  # [0.2.0](https://github.com/eko24ive/pi-ask/compare/v0.1.1...v0.2.0) (2026-04-19)
176
163
 
177
-
178
164
  ### Bug Fixes
179
165
 
180
- * improve custom input editor rendering ([bc92712](https://github.com/eko24ive/pi-ask/commit/bc9271205335bb9e610f8cd0c6e86bea5ce22f4b))
181
- * keep arrow keys and tab inside editor mode ([cdea90b](https://github.com/eko24ive/pi-ask/commit/cdea90bbfe726f4edca131513cf96e81a5307782))
182
- * polish ask note spacing and styling ([e0e2b04](https://github.com/eko24ive/pi-ask/commit/e0e2b046883b9d07745a6178c49cfef25e771424))
183
- * preserve multi-select choices with custom answers ([8d8e7b6](https://github.com/eko24ive/pi-ask/commit/8d8e7b67c97e796de0e44b8935960a8d39b55360))
184
-
166
+ - improve custom input editor rendering ([bc92712](https://github.com/eko24ive/pi-ask/commit/bc9271205335bb9e610f8cd0c6e86bea5ce22f4b))
167
+ - keep arrow keys and tab inside editor mode ([cdea90b](https://github.com/eko24ive/pi-ask/commit/cdea90bbfe726f4edca131513cf96e81a5307782))
168
+ - polish ask note spacing and styling ([e0e2b04](https://github.com/eko24ive/pi-ask/commit/e0e2b046883b9d07745a6178c49cfef25e771424))
169
+ - preserve multi-select choices with custom answers ([8d8e7b6](https://github.com/eko24ive/pi-ask/commit/8d8e7b67c97e796de0e44b8935960a8d39b55360))
185
170
 
186
171
  ### Features
187
172
 
188
- * refine ask submit screen layout ([d5ca38e](https://github.com/eko24ive/pi-ask/commit/d5ca38e621f701af466a9b67005708ebd176bbf0))
189
- * sharpen ask_user tool guidance ([4a131f7](https://github.com/eko24ive/pi-ask/commit/4a131f7752f17f2f91fd6669e45a74888240d86e))
190
- * simplify ask UI copy and note shortcuts ([9ab368a](https://github.com/eko24ive/pi-ask/commit/9ab368ad6bebdf26d8a4be7de71ac415eea06285))
191
- * support @ file autocomplete in ask editor ([0386239](https://github.com/eko24ive/pi-ask/commit/0386239f5e4165281b40db540d129d86c8af63d4))
192
- * support ctrl+c dismissal in ask flow ([fcd1f1b](https://github.com/eko24ive/pi-ask/commit/fcd1f1bce5120af07c7d6499591295e4bccf6a55))
173
+ - refine ask submit screen layout ([d5ca38e](https://github.com/eko24ive/pi-ask/commit/d5ca38e621f701af466a9b67005708ebd176bbf0))
174
+ - sharpen ask_user tool guidance ([4a131f7](https://github.com/eko24ive/pi-ask/commit/4a131f7752f17f2f91fd6669e45a74888240d86e))
175
+ - simplify ask UI copy and note shortcuts ([9ab368a](https://github.com/eko24ive/pi-ask/commit/9ab368ad6bebdf26d8a4be7de71ac415eea06285))
176
+ - support @ file autocomplete in ask editor ([0386239](https://github.com/eko24ive/pi-ask/commit/0386239f5e4165281b40db540d129d86c8af63d4))
177
+ - support ctrl+c dismissal in ask flow ([fcd1f1b](https://github.com/eko24ive/pi-ask/commit/fcd1f1bce5120af07c7d6499591295e4bccf6a55))
193
178
 
194
179
  ## [0.1.1](https://github.com/eko24ive/pi-ask/compare/v0.1.0...v0.1.1) (2026-04-19)
195
180
 
196
-
197
181
  ### Bug Fixes
198
182
 
199
- * relax toolchain pinning for release workflow ([549c2c2](https://github.com/eko24ive/pi-ask/commit/549c2c26f04f5c2d6b7b3f6487a7a72303f998bb))
200
- * remove toolchain pinning from repo ([5b10568](https://github.com/eko24ive/pi-ask/commit/5b105683c35dc02df1e1e0fc6132a46283c25d1b))
201
- * specify pnpm version in workflows ([08e053f](https://github.com/eko24ive/pi-ask/commit/08e053f095ed5ccc68a367f03c07a30b31683b3c))
183
+ - relax toolchain pinning for release workflow ([549c2c2](https://github.com/eko24ive/pi-ask/commit/549c2c26f04f5c2d6b7b3f6487a7a72303f998bb))
184
+ - remove toolchain pinning from repo ([5b10568](https://github.com/eko24ive/pi-ask/commit/5b105683c35dc02df1e1e0fc6132a46283c25d1b))
185
+ - specify pnpm version in workflows ([08e053f](https://github.com/eko24ive/pi-ask/commit/08e053f095ed5ccc68a367f03c07a30b31683b3c))
202
186
 
203
187
  # [0.1.0](https://github.com/eko24ive/pi-ask/compare/v0.0.0...v0.1.0) (2026-04-19)
204
188
 
205
-
206
189
  ### Bug Fixes
207
190
 
208
- * skip git hooks during release commits ([32c2ae7](https://github.com/eko24ive/pi-ask/commit/32c2ae785c16ab2482f9f2a09d19c8eeed8cae8e))
209
- * update release tooling for trusted publishing ([85f4ec5](https://github.com/eko24ive/pi-ask/commit/85f4ec5128ba4554412e3409d9f353fb66981f35))
210
-
191
+ - skip git hooks during release commits ([32c2ae7](https://github.com/eko24ive/pi-ask/commit/32c2ae785c16ab2482f9f2a09d19c8eeed8cae8e))
192
+ - update release tooling for trusted publishing ([85f4ec5](https://github.com/eko24ive/pi-ask/commit/85f4ec5128ba4554412e3409d9f353fb66981f35))
211
193
 
212
194
  ### Features
213
195
 
214
- * bootstrap first public release ([552959f](https://github.com/eko24ive/pi-ask/commit/552959f7ad3b40a9f3f8443d301a2c6f2340477d))
196
+ - bootstrap first public release ([552959f](https://github.com/eko24ive/pi-ask/commit/552959f7ad3b40a9f3f8443d301a2c6f2340477d))
215
197
 
216
198
  # Changelog
217
199
 
package/README.md CHANGED
@@ -3,9 +3,9 @@
3
3
  # @geoqiao/pi-ask
4
4
 
5
5
  [![npm downloads](https://badgen.net/npm/dm/@geoqiao/pi-ask)](https://www.npmjs.com/package/@geoqiao/pi-ask)
6
- [![CI](https://github.com/geoqiao/pi-ask/actions/workflows/ci.yml/badge.svg)](https://github.com/geoqiao/pi-ask/actions/workflows/ci.yml)
7
- [![last commit](https://badgen.net/github/last-commit/geoqiao/pi-ask)](https://github.com/geoqiao/pi-ask/commits/main)
8
- [![stars](https://badgen.net/github/stars/geoqiao/pi-ask)](https://github.com/geoqiao/pi-ask/stargazers)
6
+ [![CI](https://github.com/geoqiao/pi-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/geoqiao/pi-tools/actions/workflows/ci.yml)
7
+ [![last commit](https://badgen.net/github/last-commit/geoqiao/pi-tools)](https://github.com/geoqiao/pi-tools/commits/main)
8
+ [![stars](https://badgen.net/github/stars/geoqiao/pi-tools)](https://github.com/geoqiao/pi-tools/stargazers)
9
9
 
10
10
  > [!IMPORTANT]
11
11
  > This is an independently maintained continuation of [`eko24ive/pi-ask`](https://github.com/eko24ive/pi-ask), with portable Pi RPC mode support while preserving the rich TUI experience.
@@ -20,7 +20,10 @@ High-quality video: [demo.mp4](https://github.com/user-attachments/assets/a8503c
20
20
 
21
21
  ## Upstream and contributions
22
22
 
23
- This project preserves the upstream Git history, MIT license, and author attribution. New development and releases are maintained independently in [`geoqiao/pi-ask`](https://github.com/geoqiao/pi-ask). Issues and contributions are welcome in this repository.
23
+ This project preserves the upstream Git history, MIT license, and author attribution. New
24
+ development and releases are maintained independently in the
25
+ [`geoqiao/pi-tools`](https://github.com/geoqiao/pi-tools/tree/main/packages/pi-ask) monorepo. Issues
26
+ and contributions are welcome there.
24
27
 
25
28
  ## Install
26
29
 
@@ -28,12 +31,6 @@ This project preserves the upstream Git history, MIT license, and author attribu
28
31
  pi install npm:@geoqiao/pi-ask
29
32
  ```
30
33
 
31
- You can also install from git:
32
-
33
- ```bash
34
- pi install git:github.com/geoqiao/pi-ask
35
- ```
36
-
37
34
  Or try it without installing (load once for the current run):
38
35
 
39
36
  ```bash
@@ -45,6 +42,7 @@ pi -e npm:@geoqiao/pi-ask
45
42
  Once installed, this package gives the agent a native way to ask for clarification instead of guessing. The rich interface is used in TUI mode.
46
43
 
47
44
  - 🧭 Familiar ask-style interface: tabbed questions, single/multi select, and preview mode
45
+ - ⭐ Optional warning-colored `(recommended)` markers that do not preselect answers
48
46
  - ✍️ Inline free-form `Type your own` answers
49
47
  - 📎 Native pi-style `@` file references inside answer and note editors
50
48
  - 📝 Question-level and option-level notes
@@ -58,6 +56,7 @@ Once installed, this package gives the agent a native way to ask for clarificati
58
56
  - `/answer` extracts questions from the latest assistant message into an ask flow
59
57
  - `/answer:again` reopens the latest `/answer` form on the current branch
60
58
  - `/ask:replay` replays the latest real `ask_user` form on the current branch
59
+ - 🛟 Automatic recovery of an unanswered `ask_user` form after startup, resume, or fork
61
60
  - 🗣️ You can talk to your agent to configure pi-ask; it will read the bundled configuration guide and tailor the config for you
62
61
 
63
62
  ## Feature walkthrough
@@ -195,7 +194,7 @@ Accepted notation follows pi-tui key ids. Common aliases are normalized, for exa
195
194
 
196
195
  After installation, the extension registers the `ask_user` tool plus `/ask-settings`, `/answer`, `/answer:again`, and `/ask:replay` commands.
197
196
 
198
- Agents can auto-discover and call `ask_user` when they need clarification instead of guessing. In interactive sessions, it opens a terminal UI flow for structured answers, supports native pi-style `@` file references while typing answers or notes, and returns normalized answers back to the agent. Ask settings are available both from `?` in the ask flow and from the `/ask-settings` command. Behaviour and notification settings are binary `on`/`off` toggles that save immediately when the config file is writable; save failures revert the toggle and show a manual-edit message. The settings overlay includes a guarded double-press reset-to-defaults action; keymaps, notification channels, and extraction settings are changed by editing the shown config file path.
197
+ Agents can auto-discover and call `ask_user` when they need clarification instead of guessing. They can mark any number of grounded preferences with `recommended: true` and use option descriptions for reasons. In interactive sessions, it opens a terminal UI flow for structured answers, supports native pi-style `@` file references while typing answers or notes, and returns normalized answers back to the agent. Ask settings are available both from `?` in the ask flow and from the `/ask-settings` command. Behaviour and notification settings are binary `on`/`off` toggles that save immediately when the config file is writable; save failures revert the toggle and show a manual-edit message. The settings overlay includes a guarded double-press reset-to-defaults action; keymaps, notification channels, and extraction settings are changed by editing the shown config file path.
199
198
 
200
199
  ### Pi RPC fallback
201
200
 
@@ -205,7 +204,7 @@ When Pi runs in RPC mode with portable extension UI support, `ask_user` keeps th
205
204
  - selecting a real option and submitting advances directly to the next question or completes the flow
206
205
  - `Type something…` opens one `input` dialog; on multi questions it is the fallback for entering multiple choices
207
206
  - dismissing a question or its input skips that question instead of cancelling the flow
208
- - descriptions and preview content are flattened into readable option strings
207
+ - recommendation markers, descriptions, and preview content are flattened into readable option strings without changing canonical values or labels
209
208
  - multiple questions include `[current/total]` progress in each dialog title
210
209
  - tool abort signals close portable `select`/`input` dialogs and return `cancelled: true`
211
210
 
@@ -213,7 +212,7 @@ RPC intentionally does not reproduce the tabbed same-screen form, native checkbo
213
212
 
214
213
  ### Answer and replay commands
215
214
 
216
- `/answer` is useful when the agent asked questions in plain text instead of using `ask_user`. It extracts questions from the latest completed assistant message and opens the same ask UI.
215
+ `/answer` is useful when the agent asked questions in plain text instead of using `ask_user`. It supplies the preceding user message as context, asks the configured extraction model for one synthetic `ask_user` tool call, validates the result, and opens the same ask UI. Missing or invalid tool calls are retried; raw and fenced JSON text remain supported as fallbacks.
217
216
 
218
217
  Replay commands are branch-aware. They read persisted entries from the current pi session branch, so they work naturally with `/resume`, `/tree`, and conversation branching:
219
218
 
@@ -222,6 +221,12 @@ Replay commands are branch-aware. They read persisted entries from the current p
222
221
 
223
222
  Cancellation is local to the UI: closing a replayed form does not start a new agent turn. Submitted answers are sent back as a normal user follow-up message.
224
223
 
224
+ ### Interrupted ask forms
225
+
226
+ If Pi stops while an `ask_user` form is open, the tool call remains without a result. Starting, resuming, or forking that session reopens the newest unanswered form once. Submitting sends the result as a user message because the original tool execution no longer exists. Cancelling dismisses the automatic recovery. Either outcome prevents another automatic reopen, while `/ask:replay` remains available.
227
+
228
+ New sessions, extension reloads, non-TUI modes, and RPC sessions do not trigger recovery.
229
+
225
230
  Kudos to [@k0valik](https://github.com/k0valik) for the `/answer` idea.
226
231
 
227
232
  You can also talk to pi to configure this extension. When asked to customize pi-ask settings, keymaps, notifications, or extraction behavior, the agent is instructed to read the bundled `docs/configuration.md` guide first and then edit the config file accordingly.
@@ -275,7 +280,7 @@ pnpm test
275
280
 
276
281
  ### Commit workflow
277
282
 
278
- This repo uses `lefthook`, Commitizen, conventional commitlint, and semantic-release.
283
+ This monorepo uses `lefthook`, Commitizen, conventional commitlint, and Changesets.
279
284
 
280
285
  If you want local hooks, install them once after `pnpm install`:
281
286
 
@@ -283,12 +288,14 @@ If you want local hooks, install them once after `pnpm install`:
283
288
  pnpm exec lefthook install
284
289
  ```
285
290
 
286
- Recommended flow:
291
+ From the repository root, the recommended flow is:
287
292
 
288
293
  ```bash
289
294
  pnpm commit
290
295
  ```
291
296
 
297
+ User-facing changes should also include a Changeset created with `pnpm changeset`.
298
+
292
299
  ## Project layout
293
300
 
294
301
  - `src/` — TypeScript extension implementation
package/docs/architecture.md CHANGED
@@ -17,8 +17,10 @@ The codebase is split so the implementation reads through file boundaries and na
17
17
  - `src/ask-tool.ts` — tool registration, mode routing, non-interactive fallback, transcript rendering, ask payload capture
18
18
  - `src/rpc/controller.ts` — sequential portable-dialog RPC flow and state assembly
19
19
  - `src/answer-commands.ts` — `/answer`, `/answer:again`, and `/ask:replay` command wiring
20
- - `src/answer-extraction.ts` — configured extraction model selection and raw-JSON extraction retries
20
+ - `src/answer-extraction.ts` — configured, session-scope-aware model selection, synthetic `ask_user` tool-call extraction, and tolerant text fallback
21
21
  - `src/ask-payload-store.ts` — branch-aware persisted ask payload lookup
22
+ - `src/pending-ask.ts` — active-branch unresolved tool-call detection and recovery dismissal persistence
23
+ - `src/resume-pending-ask.ts` — detached lifecycle wiring and recovered answer delivery
22
24
  - `src/notifications.ts` — best-effort ask notification payload rendering and channel execution
23
25
  - `src/remote-ask.ts` — package-prefixed local event contract, active-flow registry, and explicit remote submission validation
24
26
  - `src/schema.ts` — TypeBox schema
@@ -84,6 +86,9 @@ The codebase is split so the implementation reads through file boundaries and na
84
86
  - persisted ask settings are migrated to the current schema version in memory, validated, and normalized before use without rewriting the config file on load
85
87
  - config schema migrations preserve user-provided values and add new defaults only when fields are absent
86
88
  - replay payload lookup scans only the current session branch and revalidates payloads before use
89
+ - interrupted-ask recovery selects only the newest unresolved `ask_user` call on the active branch, prefers its valid persisted payload, and validates original arguments as fallback
90
+ - recovered forms open only for TUI `startup`, `resume`, and `fork` events; the flow stays detached from the lifecycle handler
91
+ - recovered submit and cancel both persist dismissal before the same call can reopen; manual `/ask:replay` ignores that recovery marker
87
92
  - invalid persisted keymaps fall back to default keymaps for the current session without discarding valid behaviour, notification, or answer settings
88
93
  - invalid notification channels are skipped and fall back to the default bell channel if none are valid
89
94
  - ask settings behaviour and notification enabled changes attempt to persist immediately from the settings list; save failures revert the change and show an error; config reset is guarded by a short double-press confirmation
package/docs/configuration.md CHANGED
@@ -101,8 +101,9 @@ These settings affect only the `/answer` command. Normal `ask_user` tool calls d
101
101
 
102
102
  - type: array of `{ "provider": string, "id": string }`
103
103
  - default: lightweight OpenAI Codex, GitHub Copilot, and Anthropic models
104
- - effect: `/answer` tries configured models in order and uses the first model with available auth
105
- - fallback: if no configured model is usable, `/answer` tries the current chat model after validating its auth
104
+ - effect: `/answer` tries configured models in order and uses the first model with available auth that is inside the current session model scope; an empty scope allows all available models
105
+ - fallback: if no configured model is usable, `/answer` tries the current chat model after validating its auth and scope
106
+ - auth check: use Pi's auth preflight before changing this list: `pi auth check --provider <provider> --model <id>`
106
107
 
107
108
  ### `answer.extractionTimeoutMs`
108
109
 
@@ -114,7 +115,7 @@ These settings affect only the `/answer` command. Normal `ask_user` tool calls d
114
115
 
115
116
  - type: integer from `0` to `3`
116
117
  - default: `1`
117
- - effect: number of retry attempts after raw JSON parsing fails; retries include the parse error and previous response as feedback
118
+ - effect: number of retry attempts after the model omits `ask_user`, returns invalid tool arguments, or produces an invalid JSON text fallback; retries include the previous error and response as feedback
118
119
 
119
120
  ## Behaviour
120
121
 
package/docs/contract.md CHANGED
@@ -20,6 +20,7 @@ This document defines the stable external behavior. It does not explain internal
20
20
  label: string;
21
21
  description?: string;
22
22
  preview?: string;
23
+ recommended?: boolean;
23
24
  }>;
24
25
  }>;
25
26
  }
@@ -32,8 +33,11 @@ This document defines the stable external behavior. It does not explain internal
32
33
  - every question must have at least one option
33
34
  - question ids must be unique within one tool call
34
35
  - option `value`s must be unique within a question
35
- - optional `label`, `description`, and `preview` fields must not be blank when provided
36
- - `label` falls back to `Q1`, `Q2`, ...
36
+ - blank optional `title`, question `label`, option `description`, and option `preview` fields are treated as omitted
37
+ - question `label` falls back to `Q1`, `Q2`, ...
38
+ - option `label` is required in the public schema; before schema validation, a missing or blank string label is derived from a non-empty `value` by replacing hyphens and underscores with spaces and capitalizing the first character
39
+ - `recommended` is optional presentation metadata; zero, one, or multiple options may set it to `true`
40
+ - recommended options render warning-colored `(recommended)` followed by muted ` | <description>`, or only `(recommended)` when no description exists, but are not preselected
37
41
  - `type` defaults to `single`
38
42
  - `required` defaults to `false`
39
43
  - `required` is metadata only; it never blocks submission
@@ -106,6 +110,7 @@ This document defines the stable external behavior. It does not explain internal
106
110
  label: string;
107
111
  description?: string;
108
112
  preview?: string;
113
+ recommended?: boolean;
109
114
  }>;
110
115
  };
111
116
  answered: boolean;
@@ -132,6 +137,7 @@ This document defines the stable external behavior. It does not explain internal
132
137
  label: string;
133
138
  description?: string;
134
139
  preview?: string;
140
+ recommended?: boolean;
135
141
  }>;
136
142
  };
137
143
  option: {
@@ -139,6 +145,7 @@ This document defines the stable external behavior. It does not explain internal
139
145
  label: string;
140
146
  description?: string;
141
147
  preview?: string;
148
+ recommended?: boolean;
142
149
  };
143
150
  selected: boolean;
144
151
  answered: boolean;
@@ -161,15 +168,17 @@ This document defines the stable external behavior. It does not explain internal
161
168
  ## Output rules
162
169
 
163
170
  - `cancelled: true` means the user dismissed a flow-level selection, chose Cancel, aborted the flow, UI was unavailable, or the payload was invalid before UI opened
164
- - invalid payloads return `error.kind === "invalid_input"` with structured `issues` and a transcript-friendly `Invalid ask_user payload:` message
171
+ - semantically invalid payloads that reach tool execution return `error.kind === "invalid_input"` with structured `issues` and a transcript-friendly `Invalid ask_user payload:` message; their rendered status is `Invalid tool payload`
172
+ - payloads missing schema-required fields fail Pi's schema validation before tool execution and use Pi's standard tool-error result without structured `details`
165
173
  - `mode: "submit"` is normal completion; `mode: "elaborate"` means the user asked the agent to continue with follow-up clarification based on notes
166
- - unanswered questions are omitted from `answers`
174
+ - unanswered questions without notes are omitted from `answers`; note-only entries remain in `answers` to carry their notes, but all non-cancelled submitted result text includes `<label>: (no answer)` in summary mode and `? <label>: (no answer)` in transcript rendering
167
175
  - in `mode: "elaborate"`, `answers` contains only committed answers; note-only entries move to `elaboration.items`
168
176
  - `continuation.strategy === "refine_only"` means the next ask should refine the current flow rather than restart it
169
177
  - `continuation.preservedAnswers` contains previously committed answers that should be kept as context and not re-asked
170
178
  - `continuation.affectedQuestionIds` lists the only questions that should be revisited
171
179
  - `continuation.questionStates` marks each question as `answered`, `needs_clarification`, or `unanswered`
172
180
  - single-select answers still use arrays
181
+ - recommendation markers never change canonical submitted labels or values
173
182
  - when `behaviour.presentSingleAsMulti` is enabled, requested single-select questions are presented and handled as multi-select in future/replayed ask flows; result question metadata keeps the requested `type`, adds `presentedType` when final presentation differs, and result text uses one compact note when any answered questions were presented differently
174
183
  - `indices` are 1-based rendered option positions
175
184
  - `customText` stores the free-form answer
@@ -197,6 +206,7 @@ This document defines the stable external behavior. It does not explain internal
197
206
 
198
207
  - tabbed multi-question flow
199
208
  - single-select, multi-select, and preview questions
209
+ - optional warning-colored recommendation subtitles in standard and preview option lists without automatic selection
200
210
  - active question type changes via configurable `main.changeQuestionType` hotkey, default `t`; non-preview questions toggle `single <-> multi`; preview questions toggle `preview <-> multi`
201
211
  - inline free-form answers for all question types
202
212
  - native pi-style `@` file path autocomplete inside free-form answer and note editors
@@ -207,10 +217,11 @@ This document defines the stable external behavior. It does not explain internal
207
217
  - on the review tab, `Submit` and `Cancel` preview notes only for answered questions
208
218
  - on the review tab, `Elaborate` preview expands to all question notes and all option notes, including notes on unselected options
209
219
  - transcript-friendly call and result rendering
210
- - `/answer` command to extract a raw-JSON `AskParams` form from the latest completed assistant message and open the ask UI
220
+ - `/answer` command to convert the latest completed assistant message into an `AskParams` form through a synthetic `ask_user` tool call and open the ask UI
211
221
  - `/answer` extraction may use an internal `freeform: true` option for open-ended questions with no explicit choices; these render as user-input-only questions with the label `Type your answer:`, no numbered option row, and no selection caret; this marker is not part of the public `ask_user` tool contract
212
222
  - `/answer:again` command to replay the latest `/answer`-extracted form on the current branch
213
223
  - `/ask:replay` command to replay the latest real `ask_user` form on the current branch
224
+ - automatic recovery of the newest unresolved `ask_user` form on startup, resume, or fork
214
225
  - ask settings list with binary behaviour/notification toggles and a guarded reset-to-defaults action
215
226
  - `?` in the ask flow and `/ask-settings` in pi open the same lightweight ask settings overlay
216
227
  - settings attempt to persist immediately when changed: `Auto-submit when answered without notes`, `Confirm dismiss when dirty`, `Double-press review shortcuts`, `Notifications`, and `Show footer hints`; `Present single-select as multi-select` persists immediately when saving succeeds but applies only to new/replayed ask flows; save failures revert the setting and show a manual-edit message; resetting config to defaults requires pressing the reset action twice within a short confirmation window
@@ -263,7 +274,7 @@ The rich ask flow uses `ctx.ui.custom()` only in TUI mode. RPC mode never calls
263
274
  - selecting and submitting a real option advances directly; no confirmation, notes, review, or continuation card follows it
264
275
  - `Type something…` opens one `input` dialog and serializes the entered text through the existing `customText`, `values`, `labels`, and `indices` result fields
265
276
  - RPC does not emulate native multi-select: choosing one real option records that option, while `Type something…` lets the user enter multiple choices as free-form text
266
- - descriptions and preview content are flattened into option strings instead of using a custom preview pane
277
+ - recommendation markers, descriptions, and preview content are flattened into option strings instead of using a custom preview pane; display text never changes canonical labels or values
267
278
  - multiple questions are sequential and every title includes `[current/total]` progress
268
279
  - dismissing a question card or its custom input skips that question; a dismissed required question is also left unanswered because required remains advisory
269
280
  - RPC does not add Skip or Cancel rows because the portable client's native Dismiss control already provides the skip behavior
@@ -273,7 +284,7 @@ RPC does not provide the tabbed same-screen form, native checkbox cards, repeate
273
284
 
274
285
  In print, JSON, other non-TUI modes, or RPC without portable UI availability, the tool returns a `Needs user input: ask_user requires interactive TUI mode.` message in `content` and a cancelled result in `details` instead of opening UI.
275
286
 
276
- Validation is handled inside the tool so malformed calls produce the same structured error shape as other invalid payloads instead of relying on pre-execution schema failures.
287
+ The public tool schema requires question `id` and `prompt` plus option `value` and `label`, and restricts question `type` to `single`, `multi`, or `preview`, so malformed structural fields fail before execution. The tool still validates trimmed text, uniqueness, option counts, and preview requirements during execution and returns structured issues for those failures. Result rendering falls back to Pi's raw tool-error text when schema validation prevents execution.
277
288
 
278
289
  The ask flow subscribes to runtime settings updates while open. In practice, this means changing `Auto-submit when answered without notes`, `Confirm dismiss when dirty`, `Double-press review shortcuts`, `Notifications`, `Show footer hints`, resetting config to defaults, or reloading config-backed keymaps can affect the in-progress ask flow immediately instead of only future asks when the change is saved or otherwise applied in memory. Load-time migrations and invalid config handling do not rewrite, rename, or back up the config file; invalid files load defaults for the session and show a notice. `Present single-select as multi-select` is applied when an ask flow is created and does not rewrite question semantics for an already-open flow; use `main.changeQuestionType` for live per-question changes.
279
290
 
@@ -287,12 +298,10 @@ pi-ask exposes a local `pi.events` contract for trusted Pi extensions. It does n
287
298
 
288
299
  Channels:
289
300
 
290
- The established event namespace is retained for compatibility with existing trusted integrations.
291
-
292
- - `@eko24ive/pi-ask:started`
293
- - `@eko24ive/pi-ask:completed`
294
- - `@eko24ive/pi-ask:submit`
295
- - `@eko24ive/pi-ask:submit-result`
301
+ - `@geoqiao/pi-ask:started`
302
+ - `@geoqiao/pi-ask:completed`
303
+ - `@geoqiao/pi-ask:submit`
304
+ - `@geoqiao/pi-ask:submit-result`
296
305
 
297
306
  Remote submissions must be explicit `{ kind: "answer" }` or `{ kind: "cancel" }` responses. Remote answers use question ids and normalized option values from the started event. pi-ask validates ids and values, recomputes labels/indices, and does not infer approval semantics from labels. The normal `ask_user` tool uses the portable-dialog fallback in RPC; the event bridge remains available for other trusted in-process integrations.
298
307
 
@@ -302,12 +311,23 @@ See [`remote-events.md`](remote-events.md) for payload shapes, examples, and a l
302
311
 
303
312
  - valid `ask_user` payloads are persisted as branch custom entries before the UI opens, so `/ask:replay` can reopen them after cancel, `/resume`, or `/tree`
304
313
  - `/answer` scans the current branch for the latest assistant message; if that message did not finish with `stop`, extraction is refused
305
- - `/answer` expects the extractor to return raw JSON only; JSON parse failures are retried according to `answer.extractionRetries`, then reported to the user without opening the ask UI
314
+ - `/answer` sends the preceding user message as context with the latest assistant text and asks the extractor for one synthetic `ask_user` tool call
315
+ - missing or invalid tool calls are retried according to `answer.extractionRetries`; raw or fenced JSON text remains supported as a last-resort fallback
306
316
  - `{ "questions": [] }` from extraction means no questions were found and is not treated as an invalid ask payload
307
317
  - command-flow cancellation closes with a notification and does not send a message to the agent
308
318
  - submitted or elaborated command-flow results are sent back with user-message semantics
309
319
  - replay commands scan only `ctx.sessionManager.getBranch()`, ignore sibling/future branch payloads, and revalidate stored payloads before opening the UI
310
320
 
321
+ ## Interrupted ask resume
322
+
323
+ - on `session_start` with reason `startup`, `resume`, or `fork`, pi-ask finds the newest `ask_user` tool call on the active branch that has neither a tool result nor an `ask:pending-dismissed` entry
324
+ - recovery does not run for `new`, `reload`, non-TUI, or RPC sessions
325
+ - the matching valid `ask:payload` supplies the form; if it is missing or invalid, pi-ask validates and uses the original tool call arguments instead
326
+ - the recovery flow is detached from `session_start`, so an open form does not block other lifecycle handlers
327
+ - because the interrupted `execute` promise no longer exists, submit sends the result with the same user-message semantics as replay commands
328
+ - submit and cancel both append `ask:pending-dismissed`, which prevents another automatic reopen; `/ask:replay` still works
329
+ - recovered flows emit remote lifecycle events with source `ask:resume`
330
+
311
331
  The non-interactive fallback message includes normalized pending questions and options so the caller can re-ask them manually. `details.questions` still contains normalized question metadata, while `details.answers` stays empty until a user responds.
312
332
 
313
333
  ## Skill alignment (advisory)