ask_user tool, prompt-JSON CLI repair loop, tool-loop research archive

- New ask_user core tool: mid-turn user question with option picking,
  refusing cleanly in autonomous mode, for background workers, and
  without a tty; system prompt points at it instead of prose questions.
- Structural loop control for prompt-JSON CLI backends (opencode,
  grok, claude, codex, gemini): shared cli_json_turn repairs a
  missing JSON envelope exactly once, then accepts prose; prompt
  contract hardened against narrate-without-calling.
- research/agentic-tool-loop-design: 74 sources plus 2 conclusions
  backing the loop-control decisions; INDEX updated to 6 subjects.

research/INDEX.md

@@ -6,13 +6,13 @@
 
 | Metric | Value |
 |---|---|
-| Subjects | 5 |
-| Total source documents | 347 |
-| — Tier 1 (Source Dossier, independently analyzed) | 104 |
-| — Tier 2 (Source Citation Card, listed only) | 243 |
-| Total conclusion documents | 6 |
+| Subjects | 6 |
+| Total source documents | 421 |
+| — Tier 1 (Source Dossier, independently analyzed) | 111 |
+| — Tier 2 (Source Citation Card, listed only) | 310 |
+| Total conclusion documents | 8 |
 | Archive opened | 2026-10-09 |
-| Last updated | 2026-10-10 |
+| Last updated | 2026-10-11 |
 
 ## Subjects
 
@@ -23,6 +23,7 @@
 | [`async-pty-process-testing`](async-pty-process-testing/) | 59 (20 / 39) | 1 | 2026-10-09 | 2026-10-09 | Designing tai_test.py (pty vs. pipes, non-blocking stdin, process-group cleanup, test-framework shape) — backfilled after it was initially skipped, see activity log |
 | [`shell-multiplexer-auto-attach`](shell-multiplexer-auto-attach/) | 138 (48 / 90) | 2 | 2026-10-09 | 2026-10-10 | Designing a tai-managed terminal multiplexer + bashrc auto-attach: tmux-as-substrate recommendation, interactive-vs-automation shell detection; extended 2026-10-10 to cover zsh/fish hook syntax |
 | [`tui-framework-design`](tui-framework-design/) | 55 (10 / 45) | 1 | 2026-10-10 | 2026-10-10 | Designing tai's in-house TUI framework (retained DOM, cuts/chops compositor, SGR mouse, bubbling events, VT sub-terminals); extended 2026-10-10 with synchronized-output verification (DEC 2026); implemented in working-tree tai.py and verified the same session; same-day follow-up fixed the 19 failures natively, deleted tai_pkg/, suite 320/320 green, committed; extended again for kitty keyboard protocol (double-Shift prompt dialog) |
+| [`agentic-tool-loop-design`](agentic-tool-loop-design/) | 74 (7 / 67) | 2 | 2026-10-11 | 2026-10-11 | Fixing stop-after-narration on prompt-JSON CLI backends without intent regexes; decided structural loop control plus exactly-once JSON-contract repair plus prompt contract, implemented in tai.py the same session (suite 357/357 + 16/16 green); approval tiers judged already industry-standard, no change |
 
 ## Recent activity log
 
@@ -40,6 +41,7 @@
 | 2026-10-10 | `tui-framework-design` | Implementation finished and verified (no new sources): framework in working-tree `tai.py`, `tui.md` docs, `/demo` + `--demo` + `--demo-shot` wiring, 49 TUI unit tests green, 21/21 headless interaction checks green, 10/10 live pty e2e checks green, `test_seal.py` green. The 19 remaining `test_tai.py` failures are the pre-existing monolith/facade working-tree mismatch, proven unrelated via stash comparison. Conclusion document updated. |
 | 2026-10-10 | `tui-framework-design` | Follow-up (no new sources): the 19 failures from the previous row were fixed natively — five classes (`Consts`, `Install`, `Sandbox`, `Opencode`, `SysInfo`) defined directly in standalone `tai.py` with module functions delegating, four test patch-targets corrected to the real `tai.*` seams (assertions unchanged) — then `tai_pkg/` deleted outright per retoor's call. Suite now 320/320 green (`test_tai.py`) + 16/16 (`test_seal.py`); `tui.md` focus rules updated (Tab always cycles, auto-focus, focus memory); committed. Conclusion document forward-corrected. |
 | 2026-10-10 | `tui-framework-design` | Extended with 1 more source (Tier 1: the kitty keyboard protocol specification, direct fetch) to settle double-Shift detection for a prompt dialog: bare modifier presses need flag 8, press is `57441;2u`, filter `:2`/`:3` via flag 2, push `CSI > 10 u` best-effort with no query round-trip, pop on teardown. Subject total now 55 sources (10 Tier 1 / 45 Tier 2), 1 conclusion. |
+| 2026-10-11 | `agentic-tool-loop-design` | New subject: 74 sources (7 Tier 1 / 67 Tier 2) + 2 conclusions, covering 7 searches plus 7 direct fetches on agentic loop control (Anthropic stop_reason docs, Building Effective Agents, Agent SDK loop, Writing Tools for Agents, ReAct pattern, tool-calling playbook, small-model narration field report). Decisions: keep loop control structural (tool_calls presence is the stop_reason equivalent, never text parsing), repair a missing JSON envelope exactly once per CLI-backend call, harden the prompt contract, leave approval tiers unchanged. Backed a same-session implementation (tai.py `opencode_find_answer`/`cli_json_repair_prompt`/`cli_json_turn`, prompt-contract sentences, 7 new tests) with suite 357/357 + 16/16 green. Counts verified directly against the written files. |
 
 ## How to use this index