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.
2026-10-11 02:54:17 +02:00
parent 2e0e0547ed
commit afc88b8087
79 changed files with 2677 additions and 40 deletions
@@ -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

@@ -0,0 +1,28 @@
+# 100x-engineers100/zeno-wiki - Zeno - 100x's Second Brain/wiki/concepts/ai-agents-react.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | 100x-engineers100/zeno-wiki - Zeno - 100x's Second Brain/wiki/concepts/ai-agents-react.md |
+| Source URL | https://github.com/100x-engineers100/zeno-wiki/blob/HEAD/Zeno%20-%20100x's%20Second%20Brain/wiki/concepts/ai-agents-react.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the ReAct loop search; looked relevant for its Thought-Action-Observation loop summary with max-iterations guardrail.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# adilkalam/claude-vibe-code - _LLM-research/_Anthropic/building-agents-sdk.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | adilkalam/claude-vibe-code - _LLM-research/_Anthropic/building-agents-sdk.md |
+| Source URL | https://github.com/adilkalam/claude-vibe-code/blob/HEAD/_LLM-research/_Anthropic/building-agents-sdk.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the effective-agents search; looked relevant as research notes mirroring the Agent SDK feedback-loop article.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# agricidaniel/fablesecondbrain - wiki/entities/Claude Agent SDK.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | agricidaniel/fablesecondbrain - wiki/entities/Claude Agent SDK.md |
+| Source URL | https://github.com/agricidaniel/fablesecondbrain/blob/HEAD/wiki/entities/Claude%20Agent%20SDK.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the effective-agents search; looked relevant for summarizing the SDK loop (gather context, take action, verify work) with verification as the reliability lever.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# ReAct Agent Implementation: Comprehensive Specification & Research Documentation
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | ReAct Agent Implementation: Comprehensive Specification & Research Documentation |
+| Source URL | https://github.com/akib1689/eag-benchmarks/issues/3 |
+| Source type | other |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the ReAct loop search; looked relevant for its stopping-conditions table (FINISH action, max iterations, correction-prompt retry on invalid actions, duplicate-action warning).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# akjus/llm-zoomcamp - 01-agentic-rag/14-agentic-loop.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | akjus/llm-zoomcamp - 01-agentic-rag/14-agentic-loop.md |
+| Source URL | https://github.com/akjus/llm-zoomcamp/blob/HEAD/01-agentic-rag/14-agentic-loop.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the OpenAI function-calling loop search; looked relevant as a tutorial while-loop that keeps calling the model until no function calls remain.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# aloysathekge/pori - .agent/reference-studies/native-tool-calling-phase-b.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | aloysathekge/pori - .agent/reference-studies/native-tool-calling-phase-b.md |
+| Source URL | https://github.com/aloysathekge/pori/blob/HEAD/.agent/reference-studies/native-tool-calling-phase-b.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the harness-validation search; looked relevant for its coercion-heuristic plus one-shot malformed-JSON retry as the brittleness native tool calling removes.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# amangupta05/agent-engineering-curriculum - 03-Tool-Calling-and-Structured-Outputs.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | amangupta05/agent-engineering-curriculum - 03-Tool-Calling-and-Structured-Outputs.md |
+| Source URL | https://github.com/amangupta05/agent-engineering-curriculum/blob/HEAD/03-Tool-Calling-and-Structured-Outputs.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the harness-validation search; looked relevant for its structured-output survey (vLLM/xgrammar/guidance backends, named tool choice via structured outputs).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,56 @@
+# Building Effective Agents
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Building effective agents |
+| Source URL | https://www.anthropic.com/engineering/building-effective-agents |
+| Source publisher / author | Anthropic Engineering (Erik S. and Barry Zhang) |
+| Source type | blog post |
+| Source date (published) | 2024-12-19 |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+Anthropic's canonical engineering post on agentic systems, drawn from work with dozens of teams. It distinguishes workflows (predefined code paths) from agents (LLMs dynamically directing their own tool use), argues for starting with the simplest pattern that works, and defines the autonomous agent as typically just an LLM using tools in a loop driven by environmental feedback, with stopping conditions such as maximum iterations. Appendix 2 gives tool-design rules: formats close to what the model has seen in training data, no formatting overhead, and agent-computer interface effort equal to HCI effort.
+
+## Key findings
+
+- Agents are defined as systems where LLMs dynamically direct their own processes and tool usage; implementation is often straightforward: LLMs using tools based on environmental feedback in a loop.
+- During execution the agent must gain ground truth from the environment at each step (tool call results, code execution) to assess progress; tasks often terminate on completion but commonly also include stopping conditions such as a maximum number of iterations.
+- Three core principles for agents: simplicity of design, transparency of planning steps, and careful tool documentation and testing (the agent-computer interface, ACI).
+- Tool format guidance: give the model tokens to think before committing, keep formats close to naturally occurring text, avoid formatting overhead such as pre-counting changed lines or string-escaping code inside JSON.
+- A good tool definition includes example usage, edge cases, input format requirements, and clear boundaries from other tools; poka-yoke tools so mistakes are hard (example: requiring absolute file paths fixed relative-path errors in their SWE-bench agent).
+- More time was spent optimizing tools than the overall prompt in their SWE-bench agent.
+
+## Pros / strengths
+
+- Written from production experience across many deployments, not a toy demo; recommendations are concrete and falsifiable.
+- The workflows-vs-agents taxonomy gives a clean vocabulary for deciding how much autonomy a task needs.
+- Appendix 2 is directly actionable for tool-schema design.
+
+## Cons / limitations / caveats
+
+- Dated December 2024; the page itself notes the tooling landscape has changed and points to newer Managed Agents material.
+- Says little about the failure mode of weak models narrating instead of calling tools, since it assumes frontier models with native tool use.
+- No discussion of approval/permission tiers for destructive actions.
+
+## Relevance to tai
+
+- Directly load-bearing for the loop-control conclusion: tai's `Agent.run_turn` (loop while tool calls arrive, stop on plain content, bounded by step caps and stall detection) already matches the canonical agent shape this post describes; the fix belongs in the backend adapters and tool/prompt contracts, not in loop restructuring.
+- The ACI guidance (example usage, boundaries, poka-yoke) applies to tai's tool schemas and to the JSON contract given to prompt-based CLI backends.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,54 @@
+# Writing Effective Tools for AI Agents — Using AI Agents
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Writing effective tools for agents — with agents |
+| Source URL | https://www.anthropic.com/engineering/writing-tools-for-agents |
+| Source publisher / author | Anthropic Engineering (Ken Aizawa et al.) |
+| Source type | blog post |
+| Source date (published) | 2025-09-11 |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+Anthropic's follow-up to Building Effective Agents, focused entirely on tool quality: prototype tools quickly, measure them with evaluation harnesses built on simple agentic `while`-loops, and iterate with agent help. Its principles: few high-level tools over many overlapping ones, namespacing to disambiguate, high-signal token-efficient responses with pagination/truncation defaults, actionable error messages, and prompt-engineered tool descriptions treated with the same care as system prompts.
+
+## Key findings
+
+- Evaluation agents should run as simple agentic loops (`while`-loops wrapping alternating LLM API and tool calls), one loop per task; instructing agents to output reasoning before tool-call blocks may improve effective intelligence via chain-of-thought.
+- Build few thoughtful tools targeting high-impact workflows and scale from there; consolidate frequently chained multi-step operations into single tools (e.g. `schedule_event` instead of list/list/create).
+- Tool responses must return high-signal information only, prefer natural-language identifiers over cryptic IDs, and stay token-efficient via pagination, range selection, filtering, or truncation with sensible defaults (Claude Code caps tool responses at 25,000 tokens).
+- Truncation and error responses should steer the agent: encourage many small targeted searches over one broad one, and return specific actionable input corrections rather than opaque codes.
+- Tool descriptions steer behavior measurably: precise refinements to descriptions took Claude Sonnet 3.5 to state of the art on SWE-bench Verified; one launch bug (needless `2025` appended to a search query) was fixed purely by improving the tool description.
+- Metrics to collect per tool: call counts, errors, runtime, token consumption; redundant calls suggest pagination fixes, invalid-parameter errors suggest clearer descriptions.
+
+## Pros / strengths
+
+- Grounded in measured held-out evaluation results on real internal tools (Slack, Asana), not opinion.
+- The truncation/error-steering guidance is immediately applicable to any harness.
+
+## Cons / limitations / caveats
+
+- Assumes MCP-style native tool calling on frontier models; the weak-model narration failure mode is out of scope.
+- Vendor-flavored toward the Claude/Claude Code stack (workbench, interleaved thinking, MCP annotations).
+
+## Relevance to tai
+
+- Supports tai's existing output-truncation and spill-to-record behavior as industry-standard practice, and the per-tool error-as-result convention.
+- The "descriptions steer behavior" finding backs the prompt-contract half of tai's narration fix: an explicit never-narrate-without-a-call rule in the system prompt and CLI-backend instructions is the research-supported mitigation where structural enforcement is unavailable.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Prompt Engineering for Supervisors: Managing 24/7 Agents
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Prompt Engineering for Supervisors: Managing 24/7 Agents |
+| Source URL | https://nyc.cloud.appwrite.io/v1/storage/buckets/ai-com-ag/files/6a28b0910017663a4439/view?project=6a2721120010ef591e9a |
+| Source type | other |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the narration-fix search; a file-hosted doc on supervising agents, too thin in the listing to judge, kept as a low-value listing.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Why and When LLM-Based Assistants Can Go Wrong: Investigating the Effectiveness of Prompt-Based Interactions for Software Help-Seeking
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Why and When LLM-Based Assistants Can Go Wrong: Investigating the Effectiveness of Prompt-Based Interactions for Software Help-Seeking |
+| Source URL | https://dogeunblocker.net/proxy/https://arxiv.org/pdf/2402.08030 |
+| Source type | paper |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the narration-fix search via a proxy URL; a paper on prompt-based help-seeking failure modes, not directly about tool loops, kept as a low-value listing.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# avifenesh/tools - agent-knowledge/agent-tool-use-methods.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | avifenesh/tools - agent-knowledge/agent-tool-use-methods.md |
+| Source URL | https://github.com/avifenesh/tools/blob/HEAD/agent-knowledge/agent-tool-use-methods.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the OpenAI function-calling loop search; looked relevant for its deliberate tool_choice guidance (auto vs required vs none) across vendors.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# to LLMs Adding Knowledge
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | to LLMs Adding Knowledge |
+| Source URL | https://gitlab.bsc.es/ai-support/workshop-AddingKnowledgeToLLMs/-/raw/f2b7c59212e831781427124421b46b68b57a1524/AddingKnowledgeToLLMs.pdf |
+| Source type | other |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the narration-fix search; a workshop slide deck that looked only tangentially relevant (multi-step agent prompts), kept as a low-value listing.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# cemendes/anthropic-claude-certifications - certs/ccar-foundations/study-guide/domain-1-agentic-orchestration.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | cemendes/anthropic-claude-certifications - certs/ccar-foundations/study-guide/domain-1-agentic-orchestration.md |
+| Source URL | https://github.com/cemendes/anthropic-claude-certifications/blob/HEAD/certs/ccar-foundations/study-guide/domain-1-agentic-orchestration.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the stop_reason/agentic-loop search; looked relevant as a study guide summarizing Anthropic loop mechanics (tool_use vs end_turn) and human-in-the-loop approval gates.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# chaitu95p/stop-reason-end-turn - CLAUDE.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | chaitu95p/stop-reason-end-turn - CLAUDE.md |
+| Source URL | https://github.com/chaitu95p/stop-reason-end-turn/blob/HEAD/CLAUDE.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the stop_reason/agentic-loop search; looked relevant for its stated convention of always checking stop_reason and its tool_result message shape.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,55 @@
+# Building Agents with the Claude Agent SDK
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Building agents with the Claude Agent SDK |
+| Source URL | https://claude.com/blog/building-agents-with-the-claude-agent-sdk |
+| Source publisher / author | Anthropic (Claude blog) |
+| Source type | blog post |
+| Source date (published) | 2025-09-29 |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+Anthropic's SDK announcement post framing the Claude Code harness as a general agent loop: gather context, take action, verify work, repeat. It prescribes agentic file search over semantic search as the starting default, subagents for parallelization and context isolation, automatic compaction near context limits, bash/filesystem access as the core computer interface, and verification via rules-based feedback, visual checks, or LLM-as-judge.
+
+## Key findings
+
+- The canonical agent feedback loop is stated as: gather context -> take action -> verify work -> repeat.
+- Core design principle: give the agent a computer (terminal, file read/write/edit/search) so it works like a human; bash plus file tools cover most non-coding tasks too.
+- Prefer agentic search (grep/tail over the filesystem) first; add semantic/vector search only if faster results or more variations are needed, since it is less accurate, harder to maintain, and less transparent.
+- Subagents serve parallelization and context management: isolated context windows that return only relevant excerpts to the orchestrator.
+- Compaction: automatically summarize previous messages as the context limit approaches so long-running agents do not run out of context.
+- Verification makes agents reliable: rules-based feedback (linting, validators) is best, visual feedback for visual tasks, LLM-as-judge as a costly last resort.
+- Debugging guidance: when the agent fails, check whether it has the right tools before blaming the model or prompt.
+
+## Pros / strengths
+
+- Describes the production harness behind Claude Code, the closest industry reference to what tai is.
+- Concrete ordering advice (agentic search before semantic search, rules before LLM-judge) with stated reasons.
+
+## Cons / limitations / caveats
+
+- Product announcement, so SDK-framed; the loop itself is vendor-neutral but examples assume Claude models.
+- No treatment of multi-backend fallback or weak-model reliability.
+
+## Relevance to tai
+
+- Confirms tai's architecture is pointed the right way: shell/file tools as the computer interface, fork/poll subagents with isolated context, history compaction, and verify-by-execution all match this reference.
+- The verify-work phase supports tai's convention of checking tool results before reporting, and argues against ending turns on ungrounded prose.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,53 @@
+# Stop Reasons and Fallback
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Stop reasons and fallback |
+| Source URL | https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons |
+| Source publisher / author | Anthropic (platform documentation) |
+| Source type | vendor docs |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+The official Claude API reference for the `stop_reason` field. Every Messages API response carries a machine-readable reason generation stopped; the documented handler table maps each value to an action: `end_turn` means use the response, `tool_use` means run the tool and return the result, `pause_turn` means re-send content to continue a server-tool loop, and the rest (`max_tokens`, `stop_sequence`, `refusal`, `model_context_window_exceeded`) cover truncation and fallback paths.
+
+## Key findings
+
+- `stop_reason` is part of every successful response and tells the caller why generation stopped, distinct from errors.
+- `tool_use`: the model is calling a tool; the runtime must run it and return the result (a server tool call still missing its result block completes in a later response).
+- `end_turn`: the model finished naturally; the runtime should use the response as-is.
+- `pause_turn`: a server-tool loop hit its iteration limit; the runtime continues by sending the assistant content back.
+- `max_tokens` and `model_context_window_exceeded` both mean truncation and need explicit continuation handling, not silent acceptance.
+
+## Pros / strengths
+
+- Authoritative vendor contract: this is the deterministic loop-control signal the whole ecosystem keys on.
+- The quick-reference table is unambiguous about which values continue the loop and which end it.
+
+## Cons / limitations / caveats
+
+- Claude-specific wire format; OpenAI uses `finish_reason: tool_calls` and other vendors differ again, so a multi-backend harness must normalize per backend.
+- Documents the signal, not what to do when a weak model emits the wrong signal (e.g. ending the turn when it should have called a tool).
+
+## Relevance to tai
+
+- Load-bearing for the conclusion that loop control must stay structural: tai's normalized `tool_calls` presence/absence across its heterogeneous backends is exactly the `stop_reason` equivalent, and assistant text must never drive loop decisions.
+- Tai's CLI backends (opencode, grok, claude, codex, gemini) synthesize this signal by parsing model prose into `{content, tool_calls}`, which is where the narration-instead-of-call failure enters; the docs confirm the signal layer is the right place to harden.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# claude-yolo/claude-yolo - README.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | claude-yolo/claude-yolo - README.md |
+| Source URL | https://github.com/claude-yolo/claude-yolo/blob/HEAD/README.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the permissions/yolo search; looked relevant as a cautionary data point on blanket auto-approval of destructive commands and the isolation it demands.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# cleanexpo/pi-dev-ops - skills/pi-dev-ops-model-farm/SKILL.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | cleanexpo/pi-dev-ops - skills/pi-dev-ops-model-farm/SKILL.md |
+| Source URL | https://github.com/cleanexpo/pi-dev-ops/blob/HEAD/skills/pi-dev-ops-model-farm/SKILL.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the permissions/yolo search; looked relevant for its read-only-by-default farm workers with explicit yolo/auto-approve gating for edits.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,47 @@
+# Conclusion: Approval Tiers Already Match Industry Practice
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Conclusion |
+| Tier | N/A |
+| Date decided | 2026-10-11 |
+| Decided by | retoor, advised by tai (agent, Muse Spark) |
+| Status | Active |
+| Confidence | Medium |
+
+## Question / problem statement
+
+The same "stops every step" complaint could also have been about approval prompts: tai asks before running non-trivial shell commands, which in a long autonomous run means repeated manual confirmations. The question was whether tai's approval model matches how coding agents normally gate autonomy, or whether it needed redesigning.
+
+## Conclusion
+
+No code change: tai's approval tiers already match the industry default. Read-only operations run without prompting (safe shell commands, file reads, recall), side-effecting operations ask per command with an escalate-to-yolo path (`[Y]always` flips the session to approvals-off), and `--yolo`/`--auto`/`--yes` flags provide the bypass up front. That is the same shape as Claude Code's default posture (ask for everything except reads, bypass mode available) found across the permission sources. The residual friction in the reported transcript was the narration failure, fixed separately, not the approval model.
+
+## Supporting sources
+
+- [Anthropic: Building effective agents](../anthropic-building-effective-agents.md): agents pause for human feedback at checkpoints or blockers; autonomy with guardrails is the expected shape, not a defect.
+- Tier 2 permission listings (Claude Code posture tables, six permission modes, constrained-yolo and read-only-by-default designs) corroborate the read-free/ask-on-write/bypass-available shape without being independently analyzed.
+
+## Alternatives considered and rejected
+
+- Auto-approving everything by default: rejected; matches YOLO mode, which the sources uniformly frame as opt-in with isolation warnings, not a default.
+- Finer-grained modes (plan/acceptEdits/auto-classifier): not rejected on merit, just unneeded now; tai's three flags plus per-command prompt cover the observed use. "We didn't build it yet" is the honest status.
+
+## Risks / open questions
+
+- Discoverability: `--yolo`/`--auto` exist but are easy to miss; if "stops every step" complaints recur and turn out to be approvals rather than narration, the fix is surfacing the flags (banner hint, `/help` line), not changing gating.
+- The safe-command allowlist is small and syntactic; a destructive command phrased to look safe is a known residual risk of any allowlist approach.
+
+## Action taken
+
+None in code. Decision recorded so the next complaint can be triaged against it: check for narration failure first, approvals second.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial conclusion recorded. |
@@ -0,0 +1,56 @@
+# Conclusion: Structural Loop Control with JSON-Contract Repair
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Conclusion |
+| Tier | N/A |
+| Date decided | 2026-10-11 |
+| Decided by | retoor, advised by tai (agent, Muse Spark) |
+| Status | Active |
+| Confidence | High |
+
+## Question / problem statement
+
+In REPL use through the opencode backend, tai kept ending its turn after narrating an intended action ("Ik kijk even mee op je scherm...") instead of calling the tool, so the user had to type "doe dan..." to prod it forward step by step. The question was how to make the agent autonomous again without resorting to regexes that guess intent from assistant prose.
+
+## Conclusion
+
+Loop control stays purely structural: a turn continues if and only if the backend reply carries tool calls, and ends on content without them. Tai's normalized `tool_calls` presence/absence is its cross-backend equivalent of Anthropic's `stop_reason`, and assistant text must never drive loop decisions. The narration-instead-of-call failure is fixed at the layer that manufactures that signal: the prompt-JSON CLI adapters (opencode, grok, claude, codex, gemini) now treat a reply with no JSON envelope while tools are offered as a structural contract miss, retry exactly once with an explicit correction prompt, and only then accept prose as the final answer. The prompt contract is hardened alongside: both the default system message and the CLI-backend instructions now state that an empty `tool_calls` list ends the turn at once and that a planned action must never be narrated without its tool call.
+
+## Supporting sources
+
+- [Anthropic: Building effective agents](../anthropic-building-effective-agents.md): the canonical agent shape (LLM plus tools in a loop on environmental feedback, bounded by stopping conditions); tai's `run_turn` already matches it, so the fix belongs in adapters and contracts, not loop restructuring.
+- [Claude docs: Stop reasons and fallback](../claude-docs-handling-stop-reasons.md): the deterministic loop-control contract (`tool_use` continues, `end_turn` ends); tai's `tool_calls` signal is the multi-backend equivalent.
+- [Anthropic: Writing effective tools for agents](../anthropic-writing-tools-for-agents.md): descriptions and truncation steer behavior measurably; backs the prompt-contract half of the fix and error-as-result conventions.
+- [Claude: Building agents with the Claude Agent SDK](../claude-building-agents-with-claude-agent-sdk.md): gather-context/take-action/verify-work reference loop; validates tai's architecture direction.
+- [elsung: small-model-tool-reliability](../elsung-small-model-tool-reliability.md): measured 25% narration-instead-of-call on weak models, `tool_choice: required` not portable, grammar enforcement unavailable to CLI wrappers; forces the repair-retry plus prompt-contract route tai took.
+- [Internals Decoded: The ReAct Loop](../devto-react-loop-how-every-ai-agent-works.md): failure-as-observation and stuck-detector-as-observation patterns; the repair prompt lives in the observation channel, not in text scraping.
+- [AI Engineering Playbook: Tool Calling](../karthikreddy-ai-engineering-playbook-tool-calling.md): free-form text plus regex parsing breaks on wording drift; its failure-mode table (system-prompt nudge for not-calling, harness caps for runaway retry) is the template for this fix.
+
+## Alternatives considered and rejected
+
+- Regexes on assistant prose to detect "intent to act" and force continuation: rejected by retoor outright and by the research (wording drift across models and languages, false positives on genuine finals, unmaintainable pattern lists).
+- Grammar-constrained decoding (the elsung report's primary fix): impossible through tai's CLI backends, which expose no sampler access; documented as the preferred fix if a backend ever offers it.
+- Reordering backends to prefer native tool-call HTTP APIs over prompt-JSON CLI models: would trade away offline/free-first behavior and is a bigger product decision; left for later, noted as a risk below.
+- Failing the turn on a contract miss with no repair (the looprig position): rejected because one cheap retry recovers the common weak-model stumble, and the repair is bounded to a single attempt.
+- `tool_choice: required` on HTTP backends: not portable per the elsung measurements and risks the forced-call infinite loop the OpenAI example warns about; not adopted.
+
+## Risks / open questions
+
+- Valid JSON with narration content and empty `tool_calls` still ends the turn; no structural check can catch intent phrased as a compliant final answer. Mitigation is the prompt contract plus, eventually, stronger backends.
+- Each genuine prose final on a CLI backend costs nothing extra (repair fires only on missing JSON), but each contract miss costs one extra model call; on slow free models that is noticeable latency per stumble.
+- If free-model quality drops further, the single repair may often fail; the retry budget is deliberately one, and raising it needs fresh evidence, not hope.
+
+## Action taken
+
+Shipped in `tai.py` the same session: `opencode_parse` split into `opencode_find_answer` plus a behavior-identical lenient wrapper, new `cli_json_repair_prompt`, new `ChatClient.cli_json_turn` shared by all six prompt-JSON CLI turns with exactly-once repair (failed repair keeps the first answer), prompt-contract sentences in `DEFAULT_SYSTEM` and `opencode_prompt`, and a new `CliJsonRepairTests` class (7 tests) in `test_tai.py`. Full suite green: 357 `test_tai.py` plus 16 `test_seal.py`.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial conclusion recorded. |
@@ -0,0 +1,28 @@
+# Tutorial 5: Preventing Undesirable Outputs from a Customer Service Chatbot
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Tutorial 5: Preventing Undesirable Outputs from a Customer Service Chatbot |
+| Source URL | https://vss2.courseflix.net/towardai-llmforproductionbook/building-llms-for-production_53.pdf |
+| Source type | other |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the narration-fix search; a book chapter on constraining chatbot outputs, tangential to loop design, kept as a low-value listing.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# dair-ai/dair-workshops - agentic-engineering-wiki/wiki/tips/tool-use.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | dair-ai/dair-workshops - agentic-engineering-wiki/wiki/tips/tool-use.md |
+| Source URL | https://github.com/dair-ai/dair-workshops/blob/HEAD/agentic-engineering-wiki/wiki/tips/tool-use.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the stop_reason/agentic-loop search; looked relevant for its canonical while-loop-on-stop_reason description including pause_turn handling.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,54 @@
+# The ReAct Loop: How Every AI Agent Actually Works
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | The ReAct Loop: How Every AI Agent Actually Works |
+| Source URL | https://dev.to/internals_decoded/the-react-loop-how-every-ai-agent-actually-works-3jgg |
+| Source publisher / author | Internals Decoded |
+| Source type | blog post |
+| Source date (published) | 2026-10-05 |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | both |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A conversational explainer of the ReAct (Thought/Action/Observation) loop as the universal agent pattern: the model reasons, emits a structured tool call the runtime executes, reads the observation back, and repeats until it can ground a final answer. It covers iteration budgets (2-3 for simple tasks, 10-15 for complex, hard cap required), tool failure as just another observation, loop/stuck detection via action hashing, and context-window defenses (sliding window, truncation, chunked sub-loops).
+
+## Key findings
+
+- The loop has four phases: Thought (internal reasoning), Action (structured tool call executed by the runtime, not the model), Observation (tool output fed back verbatim), Final Answer (produced once observations support it).
+- Every production ReAct agent sets a hard `max_iterations` limit; hitting the cap must yield a partial answer or escalate to a human. Typical cap 20-30 depending on task.
+- Stuck-loop handling beyond the cap: hash recent actions, break on N repeats, and insert a "stuck detector" observation telling the model it repeated itself and should try a different approach or output what it has.
+- Tool failure becomes an observation: wrap every tool in an error handler that formats failures with enough context for the model to retry, fall back, or conclude gracefully; a generic "ERROR" string is useless.
+- Context defenses: sliding window with summarization of older turns, observation truncation, and restructuring big tasks into chunked sub-loops with external intermediate storage.
+- Each iteration costs a full LLM invocation plus tool time, so latency scales roughly linearly with iteration count.
+
+## Pros / strengths
+
+- Clear phase vocabulary (Thought/Action/Observation/Final Answer) that maps 1:1 onto harness code.
+- The stuck-detector-as-observation pattern and failure-as-observation rule are directly implementable.
+
+## Cons / limitations / caveats
+
+- Popular explainer, not a primary source; cites the original ReAct paper (arXiv 2210.03629) without adding new evidence.
+- Iteration-count guidance is folk wisdom ("typical values"), not measured.
+
+## Relevance to tai
+
+- Tai's `run_turn` plus its loop-nudge/stall/stop machinery is already this pattern almost verbatim (action hashing via `action_signature`, loop warning injection at 3 repeats, stop at 5, total step cap, compaction); the article validates keeping that shape.
+- The failure-as-observation rule supports tai's error-as-tool-result convention and argues the narration fix must also live in the observation channel (a repair prompt), not in text scraping.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# [ENHANCE] Analyze GPT model system prompt and tool-call behavior to improve GoClaw harness
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | [ENHANCE] Analyze GPT model system prompt and tool-call behavior to improve GoClaw harness |
+| Source URL | https://github.com/digitopvn/goclaw/issues/73 |
+| Source type | other |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the harness-validation search; looked relevant for its harness adaptations list (intent-specific call-immediately instructions, tool-choice nudges, malformed-call retry/repair).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# djd1m/dz-harness - packages/skills-book-ai-apps/aiagents-tool-design-and-selection/SKILL.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | djd1m/dz-harness - packages/skills-book-ai-apps/aiagents-tool-design-and-selection/SKILL.md |
+| Source URL | https://github.com/djd1m/dz-harness/blob/HEAD/packages/skills-book-ai-apps/aiagents-tool-design-and-selection/SKILL.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the harness-validation search; looked relevant for its post-response layer (schema validation, auto-trigger of missed calls, correction prompt for malformed JSON, bounded retries).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# drrozen-med/claude-launcher - docs/YOLO_MODE_VSCODE.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | drrozen-med/claude-launcher - docs/YOLO_MODE_VSCODE.md |
+| Source URL | https://github.com/drrozen-med/claude-launcher/blob/HEAD/docs/YOLO_MODE_VSCODE.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the permissions/yolo search; looked relevant for documenting yolo mode as auto-approve permissions (CLI flag vs allow-list settings).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,55 @@
+# Small Model Tool Reliability
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | small-model-tool-reliability |
+| Source URL | https://github.com/elsung/small-model-tool-reliability |
+| Source publisher / author | elsung (GitHub) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | both |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+A field report plus methodology survey on making small local models (Gemma-4-12B / Qwen3-14B class) reliable at tool calling. Its measured headline: on a real multi-tool write phase, a Gemma-4-12B-class model narrated completion instead of emitting the tool call about 25% of the time; `tool_choice: required` did not fix it because the serving parser treats it as an ignorable hint; grammar-constrained decoding fixed it completely (25% to 0% narration over ~45 runs) by making narration unreachable at the token-sampling level.
+
+## Key findings
+
+- Measured baseline: 4/16 trials narrated with no file written (~25% flake) on a real agent CLI with the real prompt; narration text alongside a real call is common and benign, narration *instead of* the call is the failure.
+- `tool_choice: required` is not portable: enforced only where the serving parser backs it with a grammar (Qwen3-style native parsers), ignored where it does not (Gemma-4 on the tested build); enforcement lives in the parser, not the API field, and must be verified per model and per build, adversarially.
+- Grammar-constrained decoding masks illegal tokens before sampling, so prose narration is not a reachable state; measured 20/20 clean runs after, 45/45 across three phases, with an adversarial "tell me a joke, do NOT write" check still producing valid JSON.
+- Grammar design rule: force only the structural skeleton and keep the body permissive, to avoid the "constraint tax" where over-tight formatting degrades small-model task quality.
+- Grammar sampling works even where the native templated-tool path is broken, since it is applied by the sampler independently of the chat-template/tool-parsing pipeline.
+- Reliability tracks the model family's serving tool-parser maturity, not its size; per-request `max_tokens` caps are required, not optional, with open-ended grammars.
+- Recommendation ladder: grammar-constrain single-output phases (skipping the fragile tool loop entirely) and route genuine multi-tool loops to a model whose parser enforces `tool_choice: required`.
+
+## Pros / strengths
+
+- Real measurements on a real agent loop with adversarial verification, including negative results (`tool_choice` failing) reported honestly.
+- Precisely names the mechanism (parser maturity, sampler-level masking) instead of hand-waving about "small models are bad at tools."
+
+## Cons / limitations / caveats
+
+- Single-author field report on mid-2026 llama.cpp builds; parser behavior is version-specific and moves fast.
+- Grammar-constrained decoding requires sampler access the caller may not have (API users, CLI wrappers), which bounds its applicability.
+
+## Relevance to tai
+
+- This is the exact failure tai users see on its prompt-JSON CLI backends (opencode free models saying "Ik kijk even..." with no tool call): weak-model narration-instead-of-call, with no portable `tool_choice` lever.
+- Tai cannot use the report's primary fix (no sampler access through the opencode/grok/claude/codex/gemini CLIs), so the conclusion routes around it: a structural JSON-contract repair retry plus routing genuine multi-tool turns toward backends with native tool-call support, per the report's own ladder.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# emvalencaf/certup-cca - data/questions/customer-support/agentic-architecture/cca-006.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | emvalencaf/certup-cca - data/questions/customer-support/agentic-architecture/cca-006.md |
+| Source URL | https://github.com/emvalencaf/certup-cca/blob/HEAD/data/questions/customer-support/agentic-architecture/cca-006.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the stop_reason/agentic-loop search; looked relevant for its crisp claim that only stop_reason is a reliable loop-control signal and text must never drive loop decisions.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# ezzy1630/etch - docs/superpowers/specs/2026-06-20-agentic-chat-home-design.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | ezzy1630/etch - docs/superpowers/specs/2026-06-20-agentic-chat-home-design.md |
+| Source URL | https://github.com/ezzy1630/etch/blob/HEAD/docs/superpowers/specs/2026-06-20-agentic-chat-home-design.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the stop_reason/agentic-loop search; looked relevant as a concrete streaming tool-use loop design (tool_use to tool_result until end_turn).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# fortemi/hotm - .aiwg/reports/agentic-coding-architectures-2026-02.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | fortemi/hotm - .aiwg/reports/agentic-coding-architectures-2026-02.md |
+| Source URL | https://github.com/fortemi/hotm/blob/HEAD/.aiwg/reports/agentic-coding-architectures-2026-02.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the effective-agents search; looked relevant for its claim that the ACI around the loop matters more than the loop itself, plus Claude Code loop phases.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# feat(llm): add tool-use support to Anthropic client
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | feat(llm): add tool-use support to Anthropic client |
+| Source URL | https://github.com/foundatron/octopusgarden/issues/194 |
+| Source type | other |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the stop_reason/agentic-loop search; looked relevant as an implementation plan for an AgentLoop with maxTurns and cost accumulation.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# haseebahmed-official/openai-agents-mastery
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | haseebahmed-official/openai-agents-mastery |
+| Source URL | https://github.com/haseebahmed-official/openai-agents-mastery |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the OpenAI function-calling loop search; looked relevant for its agent-lifecycle sketch (final_output ends, tool_calls continue, reset_tool_choice against infinite loops).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# itsablabla/garza-hive - docs/dev-notes/light-model-reliability.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | itsablabla/garza-hive - docs/dev-notes/light-model-reliability.md |
+| Source URL | https://github.com/itsablabla/garza-hive/blob/HEAD/docs/dev-notes/light-model-reliability.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the harness-validation search; looked relevant for reusing the existing multi-step loop as the repair-retry path (rejected call becomes the retry, bounded by maxSteps).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# jamessoubry/clawband
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | jamessoubry/clawband |
+| Source URL | https://github.com/jamessoubry/clawband |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the permissions/yolo search; looked relevant for its hook design (hard-block destructive patterns unconditionally, prompt on risky-but-legitimate outside bypass mode).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,56 @@
+# Tool Calling (AI Engineering Playbook)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Tool Calling |
+| Source URL | https://github.com/karthikreddy-7/ai-engineering-playbook/blob/HEAD/docs/05-agents/tool-calling.md |
+| Source publisher / author | karthikreddy-7 (GitHub) |
+| Source type | other |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | both |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A playbook chapter on function-calling mechanics: the model emits structured intent, the runtime validates, authorizes, executes, and returns keyed results, and the loop continues. Its key lines for tai: free-form text plus regex parsing is called out as fragile ("breaks on wording drift") versus native tool-call tokens as a trained contract; strict/constrained decoding kills syntax failures but never semantic or authorization errors; and the failure-mode table prescribes a system-prompt nudge for "not calling when it should" and harness caps for infinite retry.
+
+## Key findings
+
+- The model never executes anything: it emits structured intent, while auth, validation, side effects, and safety live in the runtime; tool definitions are prompts the model reads like any other instruction.
+- "Free-form text is a terrible API": prompting `Action: ...` and parsing with regex breaks on wording drift; native tool-call tokens plus JSON arguments are a contract the model is trained to emit.
+- Strict mode (OpenAI `strict: true`, Claude strict tool use) uses constrained decoding so arguments cannot leave the schema; it guarantees syntax, not semantics or safety, so authz stays runtime-side.
+- Standard round trip: schemas -> `tool_use` -> validate -> execute -> keyed `tool_result` -> answer or next call; failures return as the tool result (`is_error: true`) with actionable guidance instead of crashing the loop.
+- Failure-mode remedies: hallucinated names/args via strict mode plus validation plus error-as-result; calling when it shouldn't via tighter descriptions and `tool_choice`; not calling when it should via a system-prompt nudge; infinite retry of a failing tool via harness caps.
+- Scaling: keep the active tool set small (tens, not hundreds); beyond that use dynamic discovery (load definitions on demand) or subagents with focused toolsets.
+- Mutating tools should be idempotent or gated behind confirmation, since the model may repeat a call after an ambiguous result.
+
+## Pros / strengths
+
+- Dense, opinionated, and organized around production failure modes rather than hello-world flows.
+- The "tool definitions are prompts" framing and the explicit regex-parsing warning generalize beyond any one vendor.
+
+## Cons / limitations / caveats
+
+- Single-author playbook without stated measurements; several token/latency figures are marked illustrative by the author.
+- Assumes native tool-call APIs throughout; prompt-JSON fallback harnesses like tai's CLI backends are out of scope.
+
+## Relevance to tai
+
+- Directly settles the "no regex" question: loop decisions and intent detection must not rest on parsing assistant prose; tai's `tool_calls`-presence signal is the right control, matching this chapter's round-trip diagram.
+- Its failure-mode table is the template for tai's fix: a system-prompt nudge for not-calling-when-it-should, validation plus error-as-result for malformed calls, and harness caps (already present) against runaway retry.
+- The dynamic-discovery guidance validates tai's lazy tool loading (small active set, load on naming).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# kashifsabri/agentic-ai - agentic ai/Part 01 - Agent Foundations/05 - Agent Loop (Think → Act → Observe).md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | kashifsabri/agentic-ai - agentic ai/Part 01 - Agent Foundations/05 - Agent Loop (Think → Act → Observe).md |
+| Source URL | https://github.com/kashifsabri/agentic-ai/blob/HEAD/agentic%20ai/Part%2001%20-%20Agent%20Foundations/05%20-%20Agent%20Loop%20(Think%20→%20Act%20→%20Observe).md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the ReAct loop search; looked relevant for enumerating loop exits beyond goal completion (max iterations, timeout, no-progress detection).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# kenlau666/101 - module4_agent_loop_101.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | kenlau666/101 - module4_agent_loop_101.md |
+| Source URL | https://github.com/kenlau666/101/blob/HEAD/module4_agent_loop_101.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the ReAct loop search; looked relevant for distinguishing termination condition from iteration cap and defining ReAct vs chain-of-thought.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# kruxia/foundry - docs/research/2026-10-03-agentic-coding-harness-notes/harness_and_orchestration.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | kruxia/foundry - docs/research/2026-10-03-agentic-coding-harness-notes/harness_and_orchestration.md |
+| Source URL | https://github.com/kruxia/foundry/blob/HEAD/docs/research/2026-10-03-agentic-coding-harness-notes/harness_and_orchestration.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the effective-agents search; looked relevant as recent harness research citing the SDK loop and a long-running-agents follow-up post.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Complete Guide to Prompt Regression Testing Tools — ToolsInfo.com
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Complete Guide to Prompt Regression Testing Tools — ToolsInfo.com |
+| Source URL | https://legalitcost.com/c/prompt-regression-testing/guide/pdf |
+| Source type | other |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the narration-fix search; a low-value listing about prompt testing tools, not loop design, kept for completeness.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Permission system depth: lessons from Claude Code
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Permission system depth: lessons from Claude Code |
+| Source URL | https://github.com/lijunzh/koda/issues/589 |
+| Source type | other |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the permissions/yolo search; looked relevant for enumerating Claude Code's six permission modes (default, plan, acceptEdits, bypassPermissions, dontAsk, auto).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# looprig/harness - docs/plans/2026-07-11-structured-output-design.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | looprig/harness - docs/plans/2026-07-11-structured-output-design.md |
+| Source URL | https://github.com/looprig/harness/blob/HEAD/docs/plans/2026-07-11-structured-output-design.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the harness-validation search; looked relevant as the counter-position (fail the turn immediately on malformed finals, no hidden repair prompt) worth weighing against repair retries.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# macgregor/claude-code-toolbox - docs/research/web/2025-12-05-agentic-development-practices-claude-code.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | macgregor/claude-code-toolbox - docs/research/web/2025-12-05-agentic-development-practices-claude-code.md |
+| Source URL | https://github.com/macgregor/claude-code-toolbox/blob/HEAD/docs/research/web/2025-12-05-agentic-development-practices-claude-code.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the effective-agents search; looked relevant as research notes citing the Agent SDK article's loop plus context-gathering practices.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# mattbusel/llm-agent
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | mattbusel/llm-agent |
+| Source URL | https://github.com/mattbusel/llm-agent |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the OpenAI function-calling loop search; looked relevant as a minimal single-header tool-calling loop with step-trace output.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Mattbusel/wasm-agent
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Mattbusel/wasm-agent |
+| Source URL | https://github.com/Mattbusel/wasm-agent |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the ReAct loop search; looked relevant for its pluggable StopCondition design (goal reached, max steps, timeout, error threshold) plus step trace.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# maugx3/ai-tools - _thoughts/third-party/instructions/Building agents with the Claude Agent SDK  Anthropic.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | maugx3/ai-tools - _thoughts/third-party/instructions/Building agents with the Claude Agent SDK  Anthropic.md |
+| Source URL | https://github.com/maugx3/ai-tools/blob/HEAD/_thoughts/third-party/instructions/Building%20agents%20with%20the%20Claude%20Agent%20SDK%20%20Anthropic.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the effective-agents search; looked relevant as third-party notes mirroring the Agent SDK feedback-loop article.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# mikekelly/developing-openai-agents-sdk-agents - references/agents.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | mikekelly/developing-openai-agents-sdk-agents - references/agents.md |
+| Source URL | https://github.com/mikekelly/developing-openai-agents-sdk-agents/blob/HEAD/references/agents.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the OpenAI function-calling loop search; looked relevant for the SDK agent lifecycle (automatic tool loop until text output, guardrailed final output).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# mjs19971997/claude-code-ultimate-pack - skills/openai-sdk-expert/SKILL.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | mjs19971997/claude-code-ultimate-pack - skills/openai-sdk-expert/SKILL.md |
+| Source URL | https://github.com/mjs19971997/claude-code-ultimate-pack/blob/HEAD/skills/openai-sdk-expert/SKILL.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the OpenAI function-calling loop search; looked relevant as a compact reference for tools/tool_choice/parallel-calls mechanics.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# mylesfranklin/claude-agent-ecosystem-docs - official-docs/engineering-blog/building-effective-agents.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | mylesfranklin/claude-agent-ecosystem-docs - official-docs/engineering-blog/building-effective-agents.md |
+| Source URL | https://github.com/mylesfranklin/claude-agent-ecosystem-docs/blob/HEAD/official-docs/engineering-blog/building-effective-agents.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the effective-agents search; a mirror of the Tier 1 Anthropic article, logged for completeness since the original was fetched directly instead.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# nilanchal0107/web-development-miniprojects - 08. AI Engineering/05. AI Agents/01. ReAct Agent/README.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | nilanchal0107/web-development-miniprojects - 08. AI Engineering/05. AI Agents/01. ReAct Agent/README.md |
+| Source URL | https://github.com/nilanchal0107/web-development-miniprojects/blob/HEAD/08.%20AI%20Engineering/05.%20AI%20Agents/01.%20ReAct%20Agent/README.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the ReAct loop search; looked relevant as a small capped-iteration ReAct implementation, though its regex Action parser is exactly the approach this research rejects.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# 500 "no user query found in messages" for tool-only turns on /v1/messages and /v1/chat/completions (no truncation required) · Issue #18303 · ollama/ollama
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | 500 "no user query found in messages" for tool-only turns on /v1/messages and /v1/chat/completions (no truncation required) · Issue #18303 · ollama/ollama |
+| Source URL | https://github.com/ollama/ollama/issues/18303 |
+| Source type | other |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the narration-fix search; looked relevant as a serving-stack data point on tool-only turns where narration text rides alongside a real tool_use block.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Function Calling & Tool Selection — Free Study Guide 2026
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Function Calling & Tool Selection — Free Study Guide 2026 |
+| Source URL | https://open-exam-prep.com/study-guides/github-ai-developer/tool-use-mcp/function-calling-tools |
+| Source type | other |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the OpenAI function-calling loop search; looked relevant for the forced-function tool_choice object syntax.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# openai-agents-python/examples/agent_patterns/forcing_tool_use.py at main · openai/openai-agents-python · GitHub
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | openai-agents-python/examples/agent_patterns/forcing_tool_use.py at main · openai/openai-agents-python · GitHub |
+| Source URL | https://github.com/openai/openai-agents-python/blob/main/examples/agent_patterns/forcing_tool_use.py |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the harness-validation search; looked relevant for the tool_choice-required infinite-loop warning (forced tool use every turn never terminates).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# paulpas/agent-skill-router - skills/coding/agent-planning-reasoning/SKILL.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | paulpas/agent-skill-router - skills/coding/agent-planning-reasoning/SKILL.md |
+| Source URL | https://github.com/paulpas/agent-skill-router/blob/HEAD/skills/coding/agent-planning-reasoning/SKILL.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the ReAct loop search; looked relevant for its bounded ReAct design (max_iterations default 15, force vs graceful early stopping, Observation stop sequences).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# pr3m/claude-code-roam
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | pr3m/claude-code-roam |
+| Source URL | https://github.com/pr3m/claude-code-roam/blob/HEAD/README.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the permissions/yolo search; looked relevant for its constrained-yolo idea (hardcoded read-only dev tools auto-approve so routine work never stalls).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# pumpuni07/langchain-agent-basic-tools
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | pumpuni07/langchain-agent-basic-tools |
+| Source URL | https://github.com/pumpuni07/langchain-agent-basic-tools |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the ReAct loop search; looked relevant for its robust-agent config notes (stop sequences against hallucinated observations, handle_parsing_errors recovery, max_iterations termination).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# rsprowler/claude-code-telegram-bridge - README.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | rsprowler/claude-code-telegram-bridge - README.md |
+| Source URL | https://github.com/rsprowler/claude-code-telegram-bridge/blob/HEAD/README.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the permissions/yolo search; looked relevant for its posture table (read-only tools allowed everywhere, destructive shell asks except in yolo).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# rsprowler/claude-code-telegram-bridge
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | rsprowler/claude-code-telegram-bridge |
+| Source URL | https://github.com/rsprowler/claude-code-telegram-bridge |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the permissions/yolo search as the repo root of an already-listed README; same posture-table relevance, logged separately since it was a separate result.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# samueltillman/notes - AI/Anthropic/certification/cca-foundations-study-plan.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | samueltillman/notes - AI/Anthropic/certification/cca-foundations-study-plan.md |
+| Source URL | https://github.com/samueltillman/notes/blob/HEAD/AI/Anthropic/certification/cca-foundations-study-plan.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the stop_reason/agentic-loop search; looked relevant for its study checklist stating loop continuation must key on stop_reason, not text content.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# seabridge-sustainability/everything-claude-code - AGENTS_SYSTEM.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | seabridge-sustainability/everything-claude-code - AGENTS_SYSTEM.md |
+| Source URL | https://github.com/seabridge-sustainability/everything-claude-code/blob/HEAD/AGENTS_SYSTEM.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the permissions/yolo search; looked relevant for its safe-reads vs explicit-approval split (commits, pushes, installs, destructive ops all gated).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Guide
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Guide |
+| Source URL | https://www.servicenow.com/community/s/cgfwn76974/attachments/cgfwn76974/now-assist-articles/487/2/AI Agents Prompting Guide.pdf |
+| Source type | other |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the narration-fix search; looked marginally relevant for prompt wording that names tools explicitly instead of vague use-the-appropriate-tool instructions.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# sgiark/arkos - docs/specs/HARNESS_SPEC.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | sgiark/arkos - docs/specs/HARNESS_SPEC.md |
+| Source URL | https://github.com/sgiark/arkos/blob/HEAD/docs/specs/HARNESS_SPEC.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the harness-validation search; looked relevant as a cautionary spec (raw json.loads on the hot path, no retry, malformed payloads kill the run).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# shipiit/shipit_agent - CHANGELOG.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | shipiit/shipit_agent - CHANGELOG.md |
+| Source URL | https://github.com/shipiit/shipit_agent/blob/HEAD/CHANGELOG.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the narration-fix search; looked relevant for its prompt-instruction plus validate-with-retry pattern and final-report subagent contract.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# sidart10/orion-slackbot - docs/building-with-claude-agent-sdk.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | sidart10/orion-slackbot - docs/building-with-claude-agent-sdk.md |
+| Source URL | https://github.com/sidart10/orion-slackbot/blob/HEAD/docs/building-with-claude-agent-sdk.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the effective-agents search; looked relevant as notes mirroring the Agent SDK feedback-loop article.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# sivasankaramalan/claude-architect-playbook - architect/01_Anthropic_Philosophy/Core_Principles.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | sivasankaramalan/claude-architect-playbook - architect/01_Anthropic_Philosophy/Core_Principles.md |
+| Source URL | https://github.com/sivasankaramalan/claude-architect-playbook/blob/HEAD/architect/01_Anthropic_Philosophy/Core_Principles.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the stop_reason/agentic-loop search; looked relevant for its programmatic-enforcement-over-prompt rule and stop_reason loop-control statement.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# slavpetroff/yolo
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | slavpetroff/yolo |
+| Source URL | https://github.com/slavpetroff/yolo |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the permissions/yolo search; looked relevant for contrasting supervised mode (approve once per tool) with full-auto bypass-permissions mode.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# ssrjkk/agent-skills - .claude/skills/ai/function-calling/SKILL.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | ssrjkk/agent-skills - .claude/skills/ai/function-calling/SKILL.md |
+| Source URL | https://github.com/ssrjkk/agent-skills/blob/HEAD/.claude/skills/ai/function-calling/SKILL.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the OpenAI function-calling loop search; looked relevant for its calling-loop checklist (detect tool_calls, execute, append tool messages with call ids).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Writing effective tools for LLM agents—using LLM agents \ Anthropic
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Writing effective tools for LLM agents—using LLM agents \ Anthropic |
+| Source URL | https://www.thetermspot.com/sources/download/596c9f36b53b3d76654fa506c531bcea31aba7f8ae07b66aa3e264fda30840e9-6e720444-da54-4cb4-a593-83ccb3396928 |
+| Source type | other |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the narration-fix search; an unofficial mirror of the Tier 1 Anthropic tools article, logged for completeness since the original was fetched directly instead.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# trainergabrielcepeda/anthropic_training_vault - 05_Agentic_Workflows/Theory/01_Agent_Design.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | trainergabrielcepeda/anthropic_training_vault - 05_Agentic_Workflows/Theory/01_Agent_Design.md |
+| Source URL | https://github.com/trainergabrielcepeda/anthropic_training_vault/blob/HEAD/05_Agentic_Workflows/Theory/01_Agent_Design.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the stop_reason/agentic-loop search; looked relevant as training material showing the end_turn/tool_use loop-control code pattern.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# tvscoundrel/agentforge - packages/patterns/docs/react-agent-guide.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | tvscoundrel/agentforge - packages/patterns/docs/react-agent-guide.md |
+| Source URL | https://github.com/tvscoundrel/agentforge/blob/HEAD/packages/patterns/docs/react-agent-guide.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the ReAct loop search; looked relevant for its builder-style custom stop conditions (conclusion reached, iteration limit, error count).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# tyevans/novelizer - docs/agent-prompting/research-tech-digest.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | tyevans/novelizer - docs/agent-prompting/research-tech-digest.md |
+| Source URL | https://github.com/tyevans/novelizer/blob/HEAD/docs/agent-prompting/research-tech-digest.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the effective-agents search; looked relevant for its index-then-read loop prescription (locate via grep/glob, then read only the needed span).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Open, Closed and Broken: Prompt Fuzzing Finds LLMs Still Fragile Across Open and Closed Models
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Open, Closed and Broken: Prompt Fuzzing Finds LLMs Still Fragile Across Open and Closed Models |
+| Source URL | https://unit42.paloaltonetworks.com/genai-llm-prompt-fuzzing/?pdf=print&lg=en&_wpnonce=dcf0062f50 |
+| Source type | other |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the narration-fix search; looked relevant only for structured-prompting hygiene (separating data from instructions), not for loop design.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# vezril/claude-toolkit - skills/agentic-workflows/SKILL.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | vezril/claude-toolkit - skills/agentic-workflows/SKILL.md |
+| Source URL | https://github.com/vezril/claude-toolkit/blob/HEAD/skills/agentic-workflows/SKILL.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the effective-agents search; looked relevant as a distillation of Building Effective Agents plus SDK and LangGraph workflow patterns.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# yungkim/anthropiarch - docs/research/agentic_architecture/20260430_243b8f2b_agentic-architecture-subagents-tool-use-the-agentic-loop-anthropic-docs.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | yungkim/anthropiarch - docs/research/agentic_architecture/20260430_243b8f2b_agentic-architecture-subagents-tool-use-the-agentic-loop-anthropic-docs.md |
+| Source URL | https://github.com/yungkim/anthropiarch/blob/HEAD/docs/research/agentic_architecture/20260430_243b8f2b_agentic-architecture-subagents-tool-use-the-agentic-loop-anthropic-docs.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the stop_reason/agentic-loop search; looked relevant as research notes on the Anthropic agentic loop, parallel tool calls, and tool-description quality.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# za-kiu/ai-powered-software-dev - course-pack/labs/lab-8/guides/reAct-loop-guide.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | za-kiu/ai-powered-software-dev - course-pack/labs/lab-8/guides/reAct-loop-guide.md |
+| Source URL | https://github.com/za-kiu/ai-powered-software-dev/blob/HEAD/course-pack/labs/lab-8/guides/reAct-loop-guide.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the OpenAI function-calling loop search; looked relevant for its explicit no-tool-calls-means-final-answer check with tool_choice auto.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# zestones/hermes - _docs/spec/architecture/agent/tool-calling-loop.md
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agentic-tool-loop-design |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | zestones/hermes - _docs/spec/architecture/agent/tool-calling-loop.md |
+| Source URL | https://github.com/zestones/hermes/blob/HEAD/_docs/spec/architecture/agent/tool-calling-loop.md |
+| Source type | repository |
+| Date researched | 2026-10-11 |
+| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the OpenAI function-calling loop search; looked relevant for its OpenAI-compatible round-trip spec (finish_reason tool_calls, JSON-string arguments).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-11 | Logged as consulted-but-not-analyzed. |
@@ -410,7 +410,7 @@ SYSINFO_BINARIES = ("tmux", "git", "ffmpeg", "arecord", "sox", "whisper-cpp", "w

 DEFAULT_SYSTEM = (
    "You are tai, a professional autonomous assistant. You act with tools, verify results, and report concisely. "
-    "Rules: prefer the smallest change that solves the task; never silently ignore errors; ask when requirements are ambiguous; "
+    "Rules: prefer the smallest change that solves the task; never silently ignore errors; call ask_user when requirements are ambiguous (never end your turn with open questions in prose: one-shot runs exit and prose questions are never answered); "
    "keep answers short and factual. Tools: shell and file tools for the local machine, web_search and web_fetch for the internet, "
    "web_fetch handles every HTTP method with headers and bodies so never curl or wget through shell, "
    "speak for voice output, recall to search past session memory. Memory: call remember whenever you learn durable facts, "
@@ -421,7 +421,8 @@ DEFAULT_SYSTEM = (
    "Lazy tools: only everyday tools load by default; name any other tool or topic in your reply text and it becomes callable on your next step. "
    "Bots: one identity holds many bots; a bot is only a system message plus its own history, all vault data is shared. @name routes one turn to another bot and files the exchange in both histories; /bot switches, create_bot makes bots. "
    "Terminal: the user's question is very likely about what is visible in their terminal, especially right after a terminal capture or when launched with a single question straight from a shell; resolve vague references (this, that, it, the error) against that content, capture it with get_current_terminal_content instead of asking, and answer from what you see. "
-    "Retrieval: use search first for anything stored: one ranked full-text query across records, events, and audit plus graph expansion beats paging and guessing. Chain tool calls until the task is done."
+    "Retrieval: use search first for anything stored: one ranked full-text query across records, events, and audit plus graph expansion beats paging and guessing. Chain tool calls until the task is done. "
+    "Never narrate a planned action in text without emitting its tool call: text without tool calls ends your turn and the action will not happen."
 )
 MERGE_SYSTEM = (
    "You maintain an AI assistant system prompt. You receive the current system prompt and one memory instruction. "
@@ -434,7 +435,7 @@ COMPACT_SYSTEM = (
    "key decisions, files touched, errors and fixes, pending next steps. Output only the summary, no preamble."
 )
 AUTONOMOUS_NOTE = (
-    "Autonomous mode: never ask the user anything this session. When requirements are unclear, blocked, or need input, "
+    "Autonomous mode: never ask the user anything this session (the ask_user tool refuses, do not call it). When requirements are unclear, blocked, or need input, "
    "research deeply with web_search, web_fetch, shell, and subagents, then decide and proceed. State assumptions briefly in your reply."
 )

@@ -3038,16 +3039,14 @@ def opencode_prompt(messages, tools):
        "You are the model behind another agent. The transcript above is the whole conversation; lines starting with TOOL <id> are results of tool calls that already ran. "
        "Do not use any of your own tools and do not repeat a tool call whose result is already shown. "
        "If the results answer the user, put the final answer in content with an empty tool_calls list; otherwise request the next tool calls from TOOLS. "
+        "An empty tool_calls list ends the turn at once, nothing else runs. "
+        "Never narrate a planned action without its tool call in the same reply. "
        "Reply with one JSON object only, no code fence, matching this schema: "
    )
    return muse_prompt(messages, tools) + "\n\n" + rules + schema


-def opencode_parse(text):
-    text = (text or "").strip()
-    fenced = re.match(r"^```(?:json)?\s*(.*?)\s*```$", text, re.S)
-    if fenced:
-        text = fenced.group(1)
+def opencode_find_answer(text):
    # Scan every "{" last-first and decode one value at each spot: free
    # models often echo the prompt schema or tool JSON before the real
    # answer, and a first-"{"-to-last-"}" slice spans both into garbage.
@@ -3061,7 +3060,23 @@ def opencode_parse(text):
            continue
        if isinstance(answer, dict) and ("content" in answer or "tool_calls" in answer):
            return answer
-    return {"content": text, "tool_calls": []}
+    return None
+
+
+def opencode_parse(text):
+    text = (text or "").strip()
+    fenced = re.match(r"^```(?:json)?\s*(.*?)\s*```$", text, re.S)
+    if fenced:
+        text = fenced.group(1)
+    return opencode_find_answer(text) or {"content": text, "tool_calls": []}
+
+
+def cli_json_repair_prompt(messages, tools, bad_text):
+    return opencode_prompt(messages, tools) + (
+        "\n\nYour previous reply contained no JSON object, so no tool ran and the turn is about to end. "
+        "Reply now with exactly one JSON object matching the schema above and no other text. "
+        "Previous reply for reference:\n" + (bad_text or "").strip()[:2000]
+    )


 def opencode_parse_events(stdout_text, returncode, stderr_text):
@@ -4433,42 +4448,44 @@ class ChatClient:
        muse_transact(home, commit)
        return self.muse_reply(answer, label)

-    def opencode_turn(self, messages, tools, stream_sink, label, model, timeout=HTTP_TIMEOUT):
-        answer = opencode_parse(opencode_run(model, opencode_prompt(messages, tools), timeout))
+    def cli_json_turn(self, label, messages, tools, stream_sink, timeout, run, parse, raw_text):
+        # Shared by the prompt-JSON CLI backends (opencode, grok, claude,
+        # codex, gemini): the model must answer with one JSON object, and a
+        # reply with no JSON envelope while tools are offered is a structural
+        # contract miss, never a verdict on the prose itself. Repair once with
+        # an explicit correction prompt, then accept prose as the final answer.
+        # A failed repair keeps the first answer: it was already usable.
+        raw = run(opencode_prompt(messages, tools), timeout)
+        answer = parse(raw)
+        text = raw_text(raw)
+        if tools and text is not None and opencode_find_answer(text) is None:
+            try:
+                raw = run(cli_json_repair_prompt(messages, tools, text), timeout)
+            except BackendError:
+                pass
+            else:
+                answer = parse(raw)
        if stream_sink is not None and answer.get("content"):
            stream_sink(answer["content"])
        return self.muse_reply(answer, label)

+    def opencode_turn(self, messages, tools, stream_sink, label, model, timeout=HTTP_TIMEOUT):
+        return self.cli_json_turn(label, messages, tools, stream_sink, timeout, lambda prompt, secs: opencode_run(model, prompt, secs), opencode_parse, lambda raw: raw)
+
    def box_opencode_turn(self, messages, tools, stream_sink, label, model, engine, timeout=HTTP_TIMEOUT):
-        answer = opencode_parse(box_opencode_run(engine, model, opencode_prompt(messages, tools), timeout))
-        if stream_sink is not None and answer.get("content"):
-            stream_sink(answer["content"])
-        return self.muse_reply(answer, label + " (box)")
+        return self.cli_json_turn(label + " (box)", messages, tools, stream_sink, timeout, lambda prompt, secs: box_opencode_run(engine, model, prompt, secs), opencode_parse, lambda raw: raw)

    def grok_turn(self, messages, tools, stream_sink, label, timeout=HTTP_TIMEOUT):
-        answer = grok_parse_output(grok_run(opencode_prompt(messages, tools), timeout))
-        if stream_sink is not None and answer.get("content"):
-            stream_sink(answer["content"])
-        return self.muse_reply(answer, label)
+        return self.cli_json_turn(label, messages, tools, stream_sink, timeout, grok_run, grok_parse_output, lambda raw: raw)

    def claude_turn(self, messages, tools, stream_sink, label, timeout=HTTP_TIMEOUT):
-        answer = claude_parse_output(claude_run(opencode_prompt(messages, tools), timeout))
-        if stream_sink is not None and answer.get("content"):
-            stream_sink(answer["content"])
-        return self.muse_reply(answer, label)
+        return self.cli_json_turn(label, messages, tools, stream_sink, timeout, claude_run, claude_parse_output, lambda raw: raw)

    def codex_turn(self, messages, tools, stream_sink, label, timeout=HTTP_TIMEOUT):
-        stdout, outfile_text, used_schema = codex_run(opencode_prompt(messages, tools), timeout)
-        answer = codex_parse_output(stdout, outfile_text, used_schema)
-        if stream_sink is not None and answer.get("content"):
-            stream_sink(answer["content"])
-        return self.muse_reply(answer, label)
+        return self.cli_json_turn(label, messages, tools, stream_sink, timeout, codex_run, lambda raw: codex_parse_output(raw[0], raw[1], raw[2]), lambda raw: raw[1] if raw[1].strip() else raw[0])

    def gemini_turn(self, messages, tools, stream_sink, label, timeout=HTTP_TIMEOUT):
-        answer = gemini_parse_output(gemini_run(opencode_prompt(messages, tools), timeout))
-        if stream_sink is not None and answer.get("content"):
-            stream_sink(answer["content"])
-        return self.muse_reply(answer, label)
+        return self.cli_json_turn(label, messages, tools, stream_sink, timeout, gemini_run, gemini_parse_output, lambda raw: raw)

    def muse_reply(self, answer, label):
        calls = []
@@ -4867,6 +4884,7 @@ TOOL_SCHEMAS = [
    tool_schema("plexer_status", "Only available when a tai-managed terminal session is active. Reports which backend is managing the current session (tai's own native pty wrapper, or tmux) and backend-specific details (pid/socket/log, or pane id).", {}, []),
    tool_schema("fork", "Spawn a background subagent with its own context that works while you continue. Returns an agent id immediately. Collect its summarized result with poll. Subagents get a smaller step budget and a time limit.", {"task": {"type": "string"}, "timeout": {"type": "integer"}, "profile": {"type": "string"}}, ["task"]),
    tool_schema("poll", "Collect a background subagent result by id. Waits up to wait seconds, then reports running or the result.", {"id": {"type": "integer"}, "wait": {"type": "integer"}}, ["id"]),
+    tool_schema("ask_user", "Ask the user one question mid-turn and wait for their answer. Use this instead of ending your turn with questions in prose: an empty tool_calls list ends the turn at once and one-shot runs then exit, so prose questions are never answered. Pass the question plus optional options; the user picks an option (by number or text) or types free input, and their answer comes back as the tool result. Only for real blockers a human must decide; in autonomous mode and for background workers it is unavailable, so decide yourself and state the assumption.", {"question": {"type": "string"}, "options": {"type": "array"}}, ["question"]),
    tool_schema("sysinfo", "Inspect the host machine where tai runs. Runs os, python, venv, root, container, binaries, cpu, and disk checks in parallel and reports each with timing. Pass checks to run a named subset.", {"checks": {"type": "array"}}, []),
    tool_schema("create_skill", "Create a new agent skill by name from a brief. Runs a dedicated deep-research worker on this machine (it calls sysinfo first, then researches with web search and shell until it has verified information) and writes SKILL.md plus supporting files into the skill directory. Runs synchronously and can take many minutes. Scope project writes under ./.tai/skills (the default), scope home under ~/.tai/skills.", {"name": {"type": "string"}, "brief": {"type": "string"}, "scope": {"type": "string"}, "timeout": {"type": "integer"}}, ["name", "brief"]),
    tool_schema("install_skill", "Install a skill that already exists somewhere else, instead of building one from scratch. source can be a local directory containing SKILL.md (or one subdirectory that does), a bare SKILL.md file, a local .zip, or a git URL (needs git installed; most sources need nothing beyond the standard library). Validates the SKILL.md frontmatter, then lands it under tai's own skill directories: copy vendors a private snapshot, symlink points at the source in place (the default when the source already sits in a recognized skills folder like .claude/skills or .agents/skills, so there is one canonical copy instead of a drifting duplicate). Scope defaults like create_skill: project when the cwd looks like a project, else home. Overwriting an existing skill of the same name asks the user first unless force is set.", {"source": {"type": "string"}, "name": {"type": "string"}, "scope": {"type": "string"}, "mode": {"type": "string"}, "force": {"type": "boolean"}}, ["source"]),
@@ -4893,7 +4911,9 @@ TOOL_SCHEMAS = [
 ]


-CORE_TOOLS = ("shell", "read_file", "write_file", "remember", "recall", "load_skill", "fork", "poll")
+CORE_TOOLS = ("shell", "read_file", "write_file", "remember", "recall", "load_skill", "fork", "poll", "ask_user")
+ASK_USER_MAX_OPTIONS = 12
+ASK_USER_MAX_ANSWER = 2000
 LAZY_NAME_STOP = ("get", "set", "list", "add")

 # Tools gated on top of the lazy keyword match: a gate must pass before a tool can even be
@@ -4932,6 +4952,7 @@ TOOL_TAGS = {
    "plexer_status": ("plexer", "terminal", "tmux", "status", "session"),
    "fork": ("fork", "subagent", "background", "parallel", "delegate", "spawn"),
    "poll": ("poll", "collect"),
+    "ask_user": ("ask", "question", "clarify", "confirm", "choose", "answer", "input"),
    "sysinfo": ("sysinfo", "system", "host", "machine", "hardware", "specs", "installed", "python", "container"),
    "create_skill": ("skill", "create", "author", "blueprint"),
    "install_skill": ("skill", "install", "import", "adopt", "copy", "symlink"),
@@ -5683,6 +5704,7 @@ class Tools:
            "plexer_status": self.run_plexer_status,
            "fork": self.run_fork,
            "poll": self.run_poll,
+            "ask_user": self.run_ask_user,
            "sysinfo": self.run_sysinfo,
            "create_skill": self.run_create_skill,
            "install_skill": self.run_install_skill,
@@ -6348,6 +6370,55 @@ class Tools:
                return "[%s] %s" % (status, spilled_view(full, spilled, len(full)))
        return "[%s] %s" % (status, text)

+    def run_ask_user(self, args):
+        question = str(args.get("question") or "").strip()
+        if not question:
+            return "error: question must be a non-empty string"
+        raw_options = args.get("options") or []
+        if not isinstance(raw_options, list):
+            return "error: options must be a list of strings"
+        options = []
+        for item in raw_options[:ASK_USER_MAX_OPTIONS]:
+            if isinstance(item, dict):
+                label = item.get("label", item.get("value", ""))
+            else:
+                label = item
+            label = str(label or "").strip().replace("\n", " ")
+            if label:
+                options.append(label[:200])
+        if getattr(self.app, "auto", False):
+            return "ask_user unavailable in autonomous mode: decide yourself and state the assumption"
+        if not getattr(self.app, "persist", True) or getattr(self.app, "depth", 0) > 0:
+            return "ask_user unavailable to background workers: decide yourself and state the assumption"
+        if not sys.stdin.isatty():
+            return "error: no interactive user on this stdin, decide yourself and state the assumption"
+        print(paint("?- " + question, Ansi.CYAN, Ansi.BOLD))
+        for pos, label in enumerate(options, 1):
+            print(paint("   %d) %s" % (pos, label), Ansi.DIM))
+        try:
+            if options:
+                raw = input(paint("answer [1-%d, option text, or free input] " % len(options), Ansi.YELLOW))
+            else:
+                raw = input(paint("answer (free input, empty skips) ", Ansi.YELLOW))
+        except (EOFError, KeyboardInterrupt):
+            return "user gave no answer (input closed): proceed with your best assumption"
+        self.app.user_stepped_in = True
+        answer = raw.strip()
+        if not answer:
+            return "user gave no answer (empty): proceed with your best assumption"
+        if len(answer) > ASK_USER_MAX_ANSWER:
+            answer = answer[:ASK_USER_MAX_ANSWER] + "...[truncated]"
+        if options:
+            if answer.isdigit():
+                pos = int(answer)
+                if 1 <= pos <= len(options):
+                    return "user chose option %d: %s" % (pos, options[pos - 1])
+            lowered = answer.lower()
+            for pos, label in enumerate(options, 1):
+                if label.lower() == lowered:
+                    return "user chose option %d: %s" % (pos, label)
+        return "user answered: %s" % answer
+
    def run_sysinfo(self, args):
        names = args.get("checks")
        if names is None:
@@ -3,7 +3,9 @@ import io
 import json
 import os
 import re
+import shutil
 import sqlite3
+import subprocess
 import sys
 import tempfile
 import time
@@ -100,6 +102,120 @@ class ToolTests(unittest.TestCase):
        self.assertIn("Communicate", tai.BOX_TTS)


+class AskUserTests(unittest.TestCase):
+    def tools(self, **attrs):
+        app = FakeApp()
+        for key, value in attrs.items():
+            setattr(app, key, value)
+        return tai.Tools(app)
+
+    def tty(self):
+        fake_stdin = io.StringIO("")
+        fake_stdin.isatty = lambda: True
+        return mock.patch.object(sys, "stdin", fake_stdin)
+
+    def test_schema_registered_and_core(self):
+        schemas = {schema["function"]["name"]: schema["function"] for schema in tai.TOOL_SCHEMAS}
+        self.assertIn("ask_user", schemas)
+        self.assertIn("question", schemas["ask_user"]["parameters"]["required"])
+        self.assertIn("ask_user", tai.CORE_TOOLS)
+        self.assertIn("question", tai.TOOL_TAGS["ask_user"])
+        self.assertIn("ask_user", {schema["function"]["name"] for schema in tai.select_tools("hello")})
+
+    def test_system_prompt_points_at_tool(self):
+        self.assertIn("ask_user", tai.DEFAULT_SYSTEM)
+        self.assertIn("ask_user", tai.AUTONOMOUS_NOTE)
+
+    def test_validation(self):
+        tools = self.tools()
+        self.assertIn("non-empty string", tools.dispatch("ask_user", json.dumps({})))
+        self.assertIn("non-empty string", tools.dispatch("ask_user", json.dumps({"question": "  "})))
+        self.assertIn("must be a list", tools.dispatch("ask_user", json.dumps({"question": "q?", "options": "nope"})))
+
+    def test_free_input(self):
+        tools = self.tools()
+        with self.tty(), mock.patch("builtins.input", return_value="do the simple thing") as asked, mock.patch("builtins.print") as shown:
+            result = tools.dispatch("ask_user", json.dumps({"question": "Which approach?"}))
+        self.assertEqual(result, "user answered: do the simple thing")
+        self.assertTrue(tools.app.user_stepped_in)
+        asked.assert_called_once()
+        self.assertIn("free input", asked.call_args.args[0])
+        printed = "\n".join(str(call.args[0]) for call in shown.call_args_list)
+        self.assertIn("Which approach?", printed)
+
+    def test_option_by_number(self):
+        tools = self.tools()
+        with self.tty(), mock.patch("builtins.input", return_value="2"), mock.patch("builtins.print") as shown:
+            result = tools.dispatch("ask_user", json.dumps({"question": "Pick one", "options": ["Ship it", "Staging first", "Abort"]}))
+        self.assertEqual(result, "user chose option 2: Staging first")
+        printed = "\n".join(str(call.args[0]) for call in shown.call_args_list)
+        self.assertIn("1) Ship it", printed)
+        self.assertIn("3) Abort", printed)
+
+    def test_option_by_text_case_insensitive(self):
+        tools = self.tools()
+        with self.tty(), mock.patch("builtins.input", return_value="staging FIRST"), mock.patch("builtins.print"):
+            result = tools.dispatch("ask_user", json.dumps({"question": "Pick one", "options": ["Ship it", "Staging first"]}))
+        self.assertEqual(result, "user chose option 2: Staging first")
+
+    def test_out_of_range_number_is_free_text(self):
+        tools = self.tools()
+        with self.tty(), mock.patch("builtins.input", return_value="9"), mock.patch("builtins.print"):
+            result = tools.dispatch("ask_user", json.dumps({"question": "Pick one", "options": ["A", "B"]}))
+        self.assertEqual(result, "user answered: 9")
+
+    def test_empty_answer_keeps_turn_alive(self):
+        tools = self.tools()
+        with self.tty(), mock.patch("builtins.input", return_value="  "), mock.patch("builtins.print"):
+            result = tools.dispatch("ask_user", json.dumps({"question": "q?"}))
+        self.assertIn("no answer (empty)", result)
+        self.assertIn("proceed", result)
+
+    def test_eof_keeps_turn_alive(self):
+        tools = self.tools()
+        with self.tty(), mock.patch("builtins.input", side_effect=EOFError), mock.patch("builtins.print"):
+            result = tools.dispatch("ask_user", json.dumps({"question": "q?"}))
+        self.assertIn("no answer (input closed)", result)
+
+    def test_non_tty_refuses_without_blocking(self):
+        tools = self.tools()
+        fake_stdin = io.StringIO("")
+        fake_stdin.isatty = lambda: False
+        with mock.patch.object(sys, "stdin", fake_stdin), mock.patch("builtins.input") as asked:
+            result = tools.dispatch("ask_user", json.dumps({"question": "q?"}))
+        self.assertIn("no interactive user", result)
+        asked.assert_not_called()
+
+    def test_auto_mode_refuses(self):
+        tools = self.tools(auto=True)
+        with mock.patch("builtins.input") as asked:
+            result = tools.dispatch("ask_user", json.dumps({"question": "q?"}))
+        self.assertIn("autonomous mode", result)
+        asked.assert_not_called()
+
+    def test_background_worker_refuses(self):
+        tools = self.tools(persist=False)
+        with mock.patch("builtins.input") as asked:
+            result = tools.dispatch("ask_user", json.dumps({"question": "q?"}))
+        self.assertIn("background workers", result)
+        asked.assert_not_called()
+        deep = self.tools(persist=True, depth=1)
+        with mock.patch("builtins.input") as asked:
+            result = deep.dispatch("ask_user", json.dumps({"question": "q?"}))
+        self.assertIn("background workers", result)
+        asked.assert_not_called()
+
+    def test_options_capped(self):
+        tools = self.tools()
+        many = ["opt%d" % num for num in range(20)]
+        with self.tty(), mock.patch("builtins.input", return_value="1"), mock.patch("builtins.print") as shown:
+            result = tools.dispatch("ask_user", json.dumps({"question": "q?", "options": many}))
+        self.assertEqual(result, "user chose option 1: opt0")
+        printed = "\n".join(str(call.args[0]) for call in shown.call_args_list)
+        self.assertIn("12) opt11", printed)
+        self.assertNotIn("13) opt12", printed)
+
+
 class SysinfoTests(unittest.TestCase):
    def test_collect_all_checks_visible(self):
        report = tai.collect_sysinfo()
@@ -1514,7 +1630,7 @@ class LazyTests(unittest.TestCase):

    def test_core_minimal(self):
        self.assertEqual(self.names("hello"), set(tai.CORE_TOOLS))
-        self.assertEqual(len(tai.CORE_TOOLS), 8)
+        self.assertEqual(len(tai.CORE_TOOLS), 9)

    def test_synonym_triggers(self):
        pairs = [
@@ -3711,6 +3827,92 @@ class OpencodeParseTests(unittest.TestCase):
        self.assertEqual(json.loads(reply["tool_calls"][0]["arguments"]), {"command": "ls -lt"})


+class CliJsonRepairTests(unittest.TestCase):
+    def make_chat(self, tmp):
+        class FakeArgs:
+            profile = "t"
+            yes = True
+
+        os.environ["TAI_HOME"] = tmp
+        return tai.ChatClient(tai.Config(FakeArgs()))
+
+    def test_find_answer_none_on_prose(self):
+        self.assertIsNone(tai.opencode_find_answer("just some words"))
+        self.assertIsNone(tai.opencode_find_answer(""))
+        answer = {"content": "hi", "tool_calls": []}
+        self.assertEqual(tai.opencode_find_answer(json.dumps(answer)), answer)
+
+    def test_prose_then_json_repairs_once(self):
+        tools = [{"type": "function", "function": {"name": "shell"}}]
+        fixed = {"content": "checking", "tool_calls": [{"name": "shell", "arguments": '{"command": "ls"}'}]}
+        with tempfile.TemporaryDirectory() as tmp:
+            try:
+                chat = self.make_chat(tmp)
+                with mock.patch.object(tai.Opencode, "opencode_run", side_effect=["Ik kijk even mee op je scherm.", json.dumps(fixed)]) as runner:
+                    reply = chat.opencode_turn([{"role": "user", "content": "hi"}], tools, None, "opencode", "m")
+                self.assertEqual(runner.call_count, 2)
+                self.assertIn("no JSON object", runner.call_args_list[1][0][1])
+            finally:
+                os.environ.pop("TAI_HOME", None)
+        self.assertEqual(len(reply["tool_calls"]), 1)
+        self.assertEqual(reply["tool_calls"][0]["name"], "shell")
+
+    def test_prose_twice_accepts_second_as_final(self):
+        tools = [{"type": "function", "function": {"name": "shell"}}]
+        with tempfile.TemporaryDirectory() as tmp:
+            try:
+                chat = self.make_chat(tmp)
+                with mock.patch.object(tai.Opencode, "opencode_run", side_effect=["first prose", "second prose"]) as runner:
+                    reply = chat.opencode_turn([{"role": "user", "content": "hi"}], tools, None, "opencode", "m")
+                self.assertEqual(runner.call_count, 2)
+            finally:
+                os.environ.pop("TAI_HOME", None)
+        self.assertEqual(reply["content"], "second prose")
+        self.assertEqual(reply["tool_calls"], [])
+
+    def test_json_first_runs_no_repair(self):
+        tools = [{"type": "function", "function": {"name": "shell"}}]
+        answer = {"content": "checking", "tool_calls": [{"name": "shell", "arguments": '{"command": "ls"}'}]}
+        with tempfile.TemporaryDirectory() as tmp:
+            try:
+                chat = self.make_chat(tmp)
+                with mock.patch.object(tai.Opencode, "opencode_run", return_value=json.dumps(answer)) as runner:
+                    reply = chat.opencode_turn([{"role": "user", "content": "hi"}], tools, None, "opencode", "m")
+                self.assertEqual(runner.call_count, 1)
+            finally:
+                os.environ.pop("TAI_HOME", None)
+        self.assertEqual(len(reply["tool_calls"]), 1)
+
+    def test_no_repair_without_tools(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            try:
+                chat = self.make_chat(tmp)
+                with mock.patch.object(tai.Opencode, "opencode_run", return_value="just chatting") as runner:
+                    reply = chat.opencode_turn([{"role": "user", "content": "hi"}], None, None, "opencode", "m")
+                self.assertEqual(runner.call_count, 1)
+            finally:
+                os.environ.pop("TAI_HOME", None)
+        self.assertEqual(reply["content"], "just chatting")
+
+    def test_failed_repair_keeps_first_answer(self):
+        tools = [{"type": "function", "function": {"name": "shell"}}]
+        with tempfile.TemporaryDirectory() as tmp:
+            try:
+                chat = self.make_chat(tmp)
+                with mock.patch.object(tai.Opencode, "opencode_run", side_effect=["usable prose", tai.BackendError("boom")]) as runner:
+                    reply = chat.opencode_turn([{"role": "user", "content": "hi"}], tools, None, "opencode", "m")
+                self.assertEqual(runner.call_count, 2)
+            finally:
+                os.environ.pop("TAI_HOME", None)
+        self.assertEqual(reply["content"], "usable prose")
+
+    def test_prompt_contract_states_turn_ending(self):
+        self.assertIn("text without tool calls ends your turn", tai.DEFAULT_SYSTEM)
+        rules = tai.opencode_prompt([{"role": "user", "content": "hi"}], [])
+        self.assertIn("ends the turn at once", rules)
+        self.assertIn("Never narrate a planned action", rules)
+
+
 class RetrySummaryTests(unittest.TestCase):
    def test_empty_errors(self):
        self.assertEqual(tai.ChatClient.summarize_errors([]), "no details")