@ssheleg/agent-stack 0.18.2 → 0.19.0

package/CHANGELOG.md

@@ -1,3 +1,63 @@
+## v0.19.0 — the prompt cache is an architectural constraint, and the gate that never watched the body
+
+Fourteen findings from nine independent bundles of the 2026-08-31 harvest said the same
+thing, and this pack had **zero** coverage of it: `grep -riE 'kv.cache|prefix cache|prompt
+cach|cache hit|cacheable'` over all four skills returned nothing.
+
+**`agent-orchestrator/references/kv-cache.md`** is the missing layer. Its spine is one
+directional rule — *the earlier a change lands, the more cache it invalidates* — from which
+the append-only discipline stops being a style preference and becomes arithmetic:
+
+- A `Current time: {{now}}` line added to a system prompt at **100,000 conversations/day**
+  took TTFT from **0.5 s to 3–5 s** and **nearly doubled the monthly bill**. Nothing else
+  changed; the line simply sat early in the prefix.
+- **N binary runtime conditions in front of the cache boundary produce 2^N cache
+  populations.** Three innocuous ones — OS × debug × locale — turn one warm cache into eight
+  cold ones.
+- The named invalidators, including the two that read as architecture rather than mistakes:
+  a **role switch that replaces the system prompt** buys a hard tool boundary and pays the
+  prefix for it, where a skill keeps the prefix and gives an instruction the model may
+  ignore; and a **hot-loaded plugin** owes its documentation a KV-cache impact, not only a
+  behavioural one.
+- Four things that look like optimisations and are not, with the measurement that settles
+  each: sorting tools by usage frequency costs the prefix and buys **almost no
+  tool-selection accuracy**; per-request few-shot retrieval guarantees a permanent miss;
+  `defer_loading` works by keeping definitions out of the *prefix* rather than out of the
+  request; and "manual concatenation breaks the cache" is **false** — caching is over bytes,
+  and the real cost of flattening is an out-of-distribution format.
+
+**The architectural error it corrects.** SKILL.md §10 said the prompt is rebuilt per request
+from live capability flags "so the two can never disagree" — right for correctness, silent
+on cost. It now states that rebuilding is free **only while it is byte-identical**, and that
+a capability change mid-session is appended rather than written into the prefix.
+
+**Four of the compaction ladder's five rungs were labelled `free`, and none of them is.**
+`context-engineering.md` gains a **Cache** column: every rung edits history, so every rung
+invalidates from its replacement point. The consequence is a scheduling rule — compact in
+batch at a threshold, never every round — because a per-round compactor pays a full
+re-prefill each round to save tokens it had already paid for once.
+
+**Displacement, not deletion.** The body sat at **4749 of the 4750-token working limit** —
+one token of headroom — so the §10 correction was paid for by moving the Data Verification
+Protocol into `agent-harness/references/system-prompt.md`, which is where §10's own text
+says prompt *content* belongs. A protocol sitting in the wiring section had contradicted the
+boundary its section drew.
+
+**The ceiling was enforced, but only where nobody was looking.** CI's *House skill audit*
+job runs `make-skill`'s auditor and fails on the headroom GAP — it caught this very release
+and is why the body was displaced rather than shipped over the line. What was missing is the
+**local** half: `npm test` measured nothing, so a file could sit one token from the edge
+through any number of local runs and only find out on a push. `test/validate.py` now fails
+hard at the 5000 platform budget and **reports** at the 4750 working limit, on every run,
+pass or fail — a warning printed only beside a failure is invisible on exactly the runs where
+it can still be acted on. Its estimator is deliberately cruder than the auditor's and errs
+high (~4947 against ~4804 for the same file), so it warns early and never late.
+
+**Headroom went up, not just under the bar.** The §2 tool-calling listing moved to
+`references/patterns.md` — the body keeps the six steps and the guard, the reference carries
+the code — taking the body from **4749/4750 before this release to 4609/4750 after**, with
+the cache reference added rather than at its expense.
+
 ## v0.18.2 — the card lost eleven characters and the check that watched it counted bytes
 
 `docs/assets/social-preview.png` — the image every link to this repository renders —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssheleg/agent-stack",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "scripts": {
     "test": "python3 test/validate.py && python3 test/plant_guard_test.py && node test/installer_test.js"
   },

package/plugins/agent-stack/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "agent-stack",
   "displayName": "Agent Stack",
   "description": "Four skills: agent-orchestrator — tool-calling loops, pipelines with checkpoints, provider routing with fallback, memory architecture, plus the wallet side of reselling LLM access; agent-evals — run/trace/thread evals, LLM judges, and fixtures grown from production; agent-interop — MCP servers and clients, A2A agent cards, the MCP Registry, and gateways; agent-harness — system prompts, tool shaping, workflow-vs-agent, and auditing an agent system.",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/agent-stack/skills/agent-harness/references/system-prompt.md

@@ -68,6 +68,20 @@ current date, environment, tenant, available capabilities, the user's locale —
 not assumed. A capability-aware prompt that lists only the tools actually connected beats a
 static prompt describing tools that may be absent.
 
+**A worked injection, because the shape is the lesson.** A data-verification protocol added
+only when a database is connected:
+
+> - First-time metrics: ask the user *"Do these numbers match expectations?"*
+> - Financial figures: mention units (cents vs dollars) and ask for confirmation
+> - Anomalies: explain proactively and ask the user to verify
+> - Rejected data: investigate the discrepancy, and record the finding as a learning
+
+Note what makes it injectable rather than permanent: every line is conditional on a
+capability the agent may or may not have. It arrived here from `agent-orchestrator`'s §10,
+which owns the *wiring* that assembles a prompt and says in its own text that the content
+belongs in this file — so a protocol sitting there contradicted the boundary its section
+had drawn.
+
 ## Flexible while learning, strict in production
 
 The same instruction should not survive the whole lifecycle.

package/plugins/agent-stack/skills/agent-interop/references/mcp-scale.md

@@ -84,6 +84,13 @@ Most providers cache the prompt prefix — **including the `tools` array**. Addi
 a definition mid-conversation **invalidates that cache**, and the resulting miss can cost more
 tokens than the definitions you so carefully removed.
 
+**This is one instance of a general rule**, and the platform now has a cache-safe path the three
+mitigations below were approximating: `defer_loading` keeps deferred definitions out of the
+system-prompt prefix and appends discovered ones inline as `tool_reference` blocks, leaving the
+cached prefix untouched (at least one tool must stay non-deferred — all-deferred is a 400). The
+economics, the arithmetic and the other invalidators are in `agent-orchestrator`'s
+`references/kv-cache.md`.
+
 Three mitigations, in the order they are usually right:
 
 - **Append** newly discovered definitions after the cache breakpoint rather than re-sorting

package/plugins/agent-stack/skills/agent-orchestrator/SKILL.md

@@ -86,45 +86,20 @@ Typed result subclasses per agent (e.g. `SQLAgentResult` with `query`, `results`
 
 ## 2. Tool-Calling Loop (Simple Path)
 
-The core agent loop pattern:
+The loop, in six steps, and every one of them is load-bearing:
+
+1. **Manage context pressure first** — trim, and inject a wrap-up instruction if the
+   window is nearly full, *before* spending the call.
+2. **Call the model with retry**, tools attached.
+3. **No tool calls means the answer** — that is the loop's only clean exit.
+4. **Append the assistant turn** with its tool calls, unedited.
+5. **Dispatch** — `asyncio.gather` for independent tools, sequentially for stateful ones.
+6. **Append every result** keyed by `tool_call_id`, then iterate.
+
+The `else` on the `for` is the guard: on exhaustion, compose a best-effort answer from what
+was gathered rather than returning nothing. The full listing is in
+[`references/patterns.md`](references/patterns.md) → *The tool-calling loop, in full*.
 
-```python
-max_iter = settings.max_orchestrator_iterations  # e.g. 10
-for iteration in range(max_iter):
-    # 1. Context pressure management
-    messages, did_trim = trim_loop_messages(messages, context_window)
-    if should_wrap_up(messages, context_window):
-        messages.append(Message(role="system",
-            content="IMPORTANT: Stop making tool calls. Compose final answer now."))
-
-    # 2. LLM call with retry
-    llm_resp = await llm_call_with_retry(messages, tools, provider, model)
-
-    # 3. No tool calls = final answer
-    if not llm_resp.tool_calls:
-        final_text = llm_resp.content
-        break
-
-    # 4. Dispatch tool calls
-    messages.append(Message(role="assistant", content=llm_resp.content,
-                            tool_calls=llm_resp.tool_calls))
-
-    # 5. Parallel execution (except sequential-only tools)
-    if len(llm_resp.tool_calls) > 1 and not has_sequential_tool:
-        results = await asyncio.gather(
-            *(handle_tool(tc, context) for tc in llm_resp.tool_calls),
-            return_exceptions=True)
-    else:
-        results = [await handle_tool(tc, context) for tc in llm_resp.tool_calls]
-
-    # 6. Append tool results
-    for tc, (text, sub_result) in zip(llm_resp.tool_calls, results):
-        messages.append(Message(role="tool", content=text,
-                                tool_call_id=tc.id, name=tc.name))
-else:
-    # Max iterations reached — compose partial answer from gathered data
-    final_text = "I reached maximum analysis steps. Here is what I found..."
-```
 
 **Critical details:**
 - **Parallel tool dispatch**: Use `asyncio.gather` for independent tools, sequential for stateful ones (e.g. data processing that depends on prior query results)
@@ -280,13 +255,9 @@ What belongs in that text, at what altitude, and how to enumerate the vocabulary
 agent stops inventing status values is the **`agent-harness`** skill's
 `agent-harness/references/system-prompt.md` — one home, and it is not this one. What is *this* skill's
 is the wiring: the prompt is rebuilt per request from the same capability flags the tool
-list is built from, so the two can never disagree.
-
-**Data Verification Protocol** (inject when DB connected):
-- First-time metrics: ask user "Do these numbers match expectations?"
-- Financial figures: mention units (cents vs dollars), ask for confirmation
-- Anomalies: proactively explain and ask user to verify
-- Rejected data: investigate discrepancy, record finding as learning
+list is built from, so the two can never disagree. **Rebuilding is free only while it is
+byte-identical**; when capabilities move mid-session, append the change rather than rewrite
+the prefix — `references/kv-cache.md` for what an edit before the boundary costs.
 
 ---
 
@@ -383,6 +354,7 @@ there; this table is only an index.
 | [`references/memory-lifecycle.md`](references/memory-lifecycle.md) | the memory **write path** — what enters, and what leaves |
 | [`references/memory-landscape.md`](references/memory-landscape.md) | **build or adopt** a memory layer, and what is settled practice |
 | [`references/context-engineering.md`](references/context-engineering.md) | the loop is **running out of window** |
+| [`references/kv-cache.md`](references/kv-cache.md) | you are deciding **what goes where in a request** — the static prefix against the trajectory, what a miss costs, the 2^N cache populations a runtime condition in front of the boundary creates, the named invalidators, and the four common optimisations that pay cache for nothing |
 | [`references/runtime.md`](references/runtime.md) | the agent must **survive a crash, a pause, a second message or a schedule** |
 | [`references/governance.md`](references/governance.md) | the question is **permission, not cost** — what it may do, and how you prove it |
 | [`references/llm-proxy-billing.md`](references/llm-proxy-billing.md) | the product **resells LLM access** |

package/plugins/agent-stack/skills/agent-orchestrator/references/context-engineering.md

@@ -33,13 +33,13 @@ Compaction is not one call. It is an ordered set of strategies, and the expensiv
 is last. A loop that summarizes at the first sign of pressure pays a model call and a
 round-trip for what a string operation would have solved.
 
-| Rung | What it does | Cost | Loses |
-|---|---|---|---|
-| 1. Microcompact | Replace old tool results with a tombstone: `[tool result cleared]`. Keep the N most recent. | free | old observations, kept recent ones |
-| 2. Head/tail collapse | For an oversized text block, keep a head and a tail, elide the middle with a marker | free | the middle of long outputs |
-| 3. Session condensation | Collapse each older message to a one-line summary, capped in total | free | phrasing, keeps the thread of events |
-| 4. LLM compaction | One model call summarizes the transcript into a structured brief | a call + latency | anything the summarizer does not think to keep |
-| 5. Prompt-round truncation | Drop the oldest whole prompt rounds, boundary-aligned | free | the earliest history entirely |
+| Rung | What it does | Cost | Cache | Loses |
+|---|---|---|---|---|
+| 1. Microcompact | Replace old tool results with a tombstone: `[tool result cleared]`. Keep the N most recent. | free | invalidates from the oldest replacement | old observations, kept recent ones |
+| 2. Head/tail collapse | For an oversized text block, keep a head and a tail, elide the middle with a marker | free | invalidates from that block | the middle of long outputs |
+| 3. Session condensation | Collapse each older message to a one-line summary, capped in total | free | invalidates from the first collapsed message | phrasing, keeps the thread of events |
+| 4. LLM compaction | One model call summarizes the transcript into a structured brief | a call + latency | invalidates the whole trajectory | anything the summarizer does not think to keep |
+| 5. Prompt-round truncation | Drop the oldest whole prompt rounds, boundary-aligned | free | invalidates from the first dropped round | the earliest history entirely |
 
 Rung 5 exists for one case: **the compaction request itself does not fit.** When rung 4
 fails because the transcript it must summarize is over the limit, summarizing harder is
@@ -49,6 +49,12 @@ not available — you drop oldest rounds and retry, bounded by a small retry cou
 as position: anything past a few thousand characters, and every result from an external
 tool server, whose outputs are the usual window hog and the least likely to be re-read.
 
+**"Free" is a compute column, and none of these rungs is free in cache.** Every one edits
+history, and an edit invalidates the prefix from the replacement point onward — so the
+frequency of compaction is itself a cost decision: **compact in batch at a threshold, never
+every round.** A per-round compactor pays a full re-prefill each round to save tokens it had
+already paid for once. `references/kv-cache.md` carries the economics and the arithmetic.
+
 ## Re-measure between rungs
 
 After every rung, measure again and stop if you are under the threshold. Two failure

package/plugins/agent-stack/skills/agent-orchestrator/references/kv-cache.md

@@ -0,0 +1,186 @@
+# The prompt cache — an architectural constraint, not an optimisation
+
+**Load this before deciding what goes where in a request**: the system prompt's shape,
+whether the tool list may change mid-run, how often to compact, whether to swap a role or
+load a skill, whether few-shot examples may be selected per request.
+
+It reads as a cost topic and is not. The cache decides **context layout before semantics
+does**, because every other decision in this skill is cheap or ruinous depending on where
+in the request it lands. A team that treats it as tuning discovers it as an incident.
+
+## Contents
+
+- [The split, and the one directional rule](#the-split-and-the-one-directional-rule)
+- [What a miss costs, measured](#what-a-miss-costs-measured)
+- [Every condition before the boundary doubles the keys](#every-condition-before-the-boundary-doubles-the-keys)
+- [The named invalidators](#the-named-invalidators)
+- [Three regions, never mixed](#three-regions-never-mixed)
+- [Compaction is a cache decision](#compaction-is-a-cache-decision)
+- [Four things that look like optimisations and are not](#four-things-that-look-like-optimisations-and-are-not)
+- [Where this constrains the rest of the skill](#where-this-constrains-the-rest-of-the-skill)
+
+---
+
+## The split, and the one directional rule
+
+Every request is two parts:
+
+```
+agent context = static prefix + trajectory
+                ^^^^^^^^^^^^^   ^^^^^^^^^^
+                system prompt   user messages, assistant messages,
+                tool definitions   tool results — append-only
+                few-shot examples
+```
+
+Caching operates on the **byte sequence of tokens**. A request hits the cache for as long
+as its bytes are an exact prefix of a previous one, and stops hitting at the first
+differing token.
+
+> **The earlier a change lands, the more cache it invalidates.**
+
+That single line is the whole discipline. It is why the append-only shape of a trajectory
+is not a stylistic preference: appending changes nothing before the append point, so the
+entire prior context stays a valid prefix. Editing an earlier message discards everything
+after it.
+
+**The structural fix follows from the rule and is worth stating as a rule of its own:** a
+configuration change is **appended as a new message**, never applied by editing an earlier
+one. Codex deliberately keeps the old prompt an exact prefix of the new one for this
+reason — the agent loop is quadratic in JSON and linear in sampling *only while cache hits
+hold*.
+
+## What a miss costs, measured
+
+A customer-service agent at **100,000 conversations/day** was healthy until an engineer
+added `Current time: {{now}}` to the system prompt. Nothing else changed:
+
+| | before | after |
+|---|---|---|
+| TTFT | **0.5 s** | **3–5 s** |
+| monthly inference bill | baseline | **nearly doubled** |
+
+The line sat near the front of the prefix, so every request differed from that token
+onward and the whole remainder was recomputed and re-billed, every time, for every user.
+
+A second measurement from the other direction: on one real user in one day, a harness that
+treats prefix stability as a loop invariant moved **435M input tokens**, at a hit price
+roughly **1/120** of a miss. At that ratio the cache is not a saving — it is the only
+reason the workload is affordable at all.
+
+**The general shape:** anything that varies per request and sits early in the prefix is a
+permanent, silent, whole-fleet cost. A timestamp is the classic; a user id, a session
+counter, a randomly ordered list and a freshly retrieved example are the same defect
+wearing different clothes.
+
+## Every condition before the boundary doubles the keys
+
+Providers let you mark where the cacheable region ends. Content before the boundary can be
+cached **across users and sessions**; content after it is user- or session-specific.
+
+The arithmetic is unforgiving: **N binary runtime conditions in front of the boundary
+produce 2^N distinct cache populations**, each of which must be warmed independently.
+
+| conditions before the boundary | cache populations |
+|---|---|
+| 1 (e.g. OS) | 2 |
+| 2 (+ debug mode) | 4 |
+| 3 (+ locale) | **8** |
+| 5 | 32 |
+
+Three innocuous conditions — macOS/Linux × normal/debug × zh/en — and one warm cache
+becomes eight cold ones. **Push every runtime condition after the boundary**, or accept
+that the prefix is no longer shared.
+
+## The named invalidators
+
+Each of these changes the prefix and costs everything after it:
+
+- **Changing the `tools` array mid-conversation** — adding, removing *or reordering* a
+  definition. Tool definitions are hundreds of tokens each and sit in the prefix.
+- **Changing the model.**
+- **Changing sandbox configuration, approval mode, or working directory**, where those are
+  rendered into the prompt.
+- **Changing the thinking / reasoning budget.**
+- **Hot-loading a plugin at runtime** — it changes the tools and prompt fragments the model
+  sees, so a plugin's documentation owes the reader its impact on the KV cache, not only on
+  behaviour.
+- **Replacing the system prompt to switch a role** (`transfer_to_agent`-style). This is a
+  real architectural trade, not a mistake: replacing the prompt makes an out-of-scope tool
+  *absent* — a hard boundary — where loading a **skill** keeps the static prefix intact and
+  gives the model an *instruction* it may ignore. Boundary versus instruction, paid for in
+  cache. Decide it deliberately.
+
+## Three regions, never mixed
+
+The cleanest shape observed in a production harness partitions every request and never
+lets the parts blend:
+
+| Region | Holds | Lifetime |
+|---|---|---|
+| **Immutable prefix** | system prompt, tool specs, few-shot examples | computed once per session, pinned |
+| **Append-only log** | `[assistant][tool][assistant]…` | every prior turn stays a prefix of the next |
+| **Volatile scratch** | reasoning traces, transient state | reset each turn, **never sent upstream** |
+
+The value is that the invariant becomes checkable: if anything ever writes into region one
+after the session starts, that is a bug with a name, not a mystery in the bill.
+
+## Compaction is a cache decision
+
+Compression happens **between** API calls, not inside one, and it never touches the static
+prefix — its target is tool results in the history. But every such edit invalidates the
+cache **from the replacement point onward**.
+
+So compression frequency is itself a cost decision: **compact in batch when the context
+approaches the threshold, never every round.** A per-round compactor pays a full re-prefill
+every round to save tokens it was already paying for once.
+
+`references/context-engineering.md`'s ladder carries this now: four of its five rungs are
+free in *compute* and none is free in *cache*, because each one edits history.
+
+**A marker makes the operation idempotent** — a `[COMPRESSED]` tombstone tells the next
+pass what it may skip, so a second compaction does not rewrite the same region and pay the
+invalidation twice.
+
+## Four things that look like optimisations and are not
+
+- **Sorting tool definitions by usage frequency.** Invalidates from the first moved
+  position onward — and the measurement is the useful half: **a fixed order has almost no
+  effect on tool-selection accuracy.** The trade is not accuracy against cost. It is cost
+  for nothing.
+- **Retrieving "the most relevant few-shot example" per request.** Examples land early in
+  the prefix, so once chosen they must be **byte-for-byte identical** across requests.
+  Per-request selection is a RAG-flavoured instinct that guarantees a permanent miss.
+- **Deferred tool loading, misread.** `defer_loading` controls *what enters the context
+  window, not what you send* — every definition still ships in the `tools` array on every
+  request. What it buys is real and specific: deferred tools are excluded from the
+  **system-prompt prefix** and discovered ones are appended inline as `tool_reference`
+  blocks, so the cached prefix is untouched. That makes it the platform's cache-safe path,
+  which the three hand-rolled mitigations in `agent-interop/references/mcp-scale.md` were
+  approximating. At least one tool must stay non-deferred — all-deferred is a 400.
+- **"Manual message concatenation breaks the cache."** It does not. Caching is over bytes,
+  so a hand-built `"USER: … ASSISTANT: …"` prefix that is byte-stable hits exactly like a
+  templated one; it breaks only if the concatenation is unstable. The real cost of
+  flattening is different and worse — an **out-of-distribution format**, since the model
+  was trained on role-delimited dialogue. Fix the reason, not the myth.
+
+**The pinning mechanism, because it is what makes discovery viable at all:** on the turn a
+tool is discovered its schema is appended at the end of the context, and **from then on it
+stays fixed at that position and becomes ordinary history**. It is never moved to the new
+end again — doing so would force a re-prefill every turn and make the whole scheme
+pointless.
+
+## Where this constrains the rest of the skill
+
+- **§3 (meta-tools) and §10 (dynamic system prompts)** tell you to assemble tools and
+  prompt per request from the same capability flags, so the two can never disagree. That is
+  right for correctness and silent about cost. The reconciliation: rebuilding is free while
+  it is **byte-identical** — which it is whenever the capability set has not moved — and the
+  moment capabilities genuinely change mid-session, append the change as a new message
+  rather than rewriting the prefix, and take the one miss knowingly.
+- **§2's loop** may not swap the model between iterations of one conversation without
+  counting the miss.
+- **`references/context-engineering.md`** owns the ladder; this file owns why its rungs are
+  not free.
+- **`agent-interop/references/mcp-scale.md`** owns the tools-array case in an MCP client.
+  This file owns the general rule it is an instance of.

package/plugins/agent-stack/skills/agent-orchestrator/references/patterns.md

@@ -200,6 +200,55 @@ for attempt in range(1, max_retries + 1):
 
 ---
 
+## The tool-calling loop, in full
+
+`SKILL.md` §2 states the six steps and the guard; this is the listing they describe. It
+moved here in v0.19.0 to buy the body headroom the §10 cache correction needed — the body
+carries what is read every time, a reference carries what is read once.
+
+```python
+max_iter = settings.max_orchestrator_iterations  # e.g. 10
+for iteration in range(max_iter):
+    # 1. Context pressure management
+    messages, did_trim = trim_loop_messages(messages, context_window)
+    if should_wrap_up(messages, context_window):
+        messages.append(Message(role="system",
+            content="IMPORTANT: Stop making tool calls. Compose final answer now."))
+
+    # 2. LLM call with retry
+    llm_resp = await llm_call_with_retry(messages, tools, provider, model)
+
+    # 3. No tool calls = final answer
+    if not llm_resp.tool_calls:
+        final_text = llm_resp.content
+        break
+
+    # 4. Dispatch tool calls
+    messages.append(Message(role="assistant", content=llm_resp.content,
+                            tool_calls=llm_resp.tool_calls))
+
+    # 5. Parallel execution (except sequential-only tools)
+    if len(llm_resp.tool_calls) > 1 and not has_sequential_tool:
+        results = await asyncio.gather(
+            *(handle_tool(tc, context) for tc in llm_resp.tool_calls),
+            return_exceptions=True)
+    else:
+        results = [await handle_tool(tc, context) for tc in llm_resp.tool_calls]
+
+    # 6. Append tool results
+    for tc, (text, sub_result) in zip(llm_resp.tool_calls, results):
+        messages.append(Message(role="tool", content=text,
+                                tool_call_id=tc.id, name=tc.name))
+else:
+    # Max iterations reached — compose partial answer from gathered data
+    final_text = "I reached maximum analysis steps. Here is what I found..."
+```
+
+Read it against §2's critical details: the wrap-up injection at ~70% of the window, in-loop
+trimming at ~80%, compression to 60% and one retry on a token-limit error, and the
+iteration refund that keeps a recoverable provider error from being charged to the guard.
+
+
 ## Context Window Sizes
 
 **Do not ship a table of model ids.** This file carried one until 2026-08-15 — nine