<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>vanducng</title>
  
  
  <link href="https://vanducng.dev/atom.xml" rel="self"/>
  
  <link href="https://vanducng.dev/"/>
  <updated>2026-11-16T05:26:58.281Z</updated>
  <id>https://vanducng.dev/</id>
  
  <author>
    <name>vanducng</name>
    
  </author>
  
  <generator uri="https://hexo.io/">Hexo</generator>
  
  <entry>
    <title>Running a Coding Agent Fleet, Part 1: The Day the Agents Built Their Own Gates</title>
    <link href="https://vanducng.dev/2026/11/10/running-a-coding-agent-fleet-part-1-foundation-day/"/>
    <id>https://vanducng.dev/2026/11/10/running-a-coding-agent-fleet-part-1-foundation-day/</id>
    <published>2026-11-10T02:28:00.000Z</published>
    <updated>2026-11-16T05:26:58.281Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><blockquote><p><strong>Sources</strong>: my private workspace records for that day (the mission’s spec, progress log, slice proofs and review verdicts), and the merged PRs in my public <a target="_blank" rel="noopener" href="https://github.com/vanducng/skills/pulls?q=is:pr+is:merged">skills repo</a>. Times are UTC.</p></blockquote><p>I run a fleet of coding agents: several teams of them, on three machines, each team working through one project. For months the process lived in prose. My root <code>AGENTS.md</code> was 4,496 words. Reviews passed because a reviewer agent said “looks good”, and nobody could tell which diff it had looked at.</p><p>On Sunday 8 November I wrote seven decisions down and handed them to the fleet. By the next morning the agents had built most of the gates that enforce them, and the gates had already caught real mistakes, including some in the gates.</p><span id="more"></span><p>This is part 1 of a series on running that fleet. It covers that one day.</p><h2 id="Seven-decisions"><a href="#Seven-decisions" class="headerlink" title="Seven decisions"></a>Seven decisions</h2><p>The mission was called workflow foundation. Its intent line:</p><blockquote><p>Process is defined by proof contracts and enforced gates: every slice carries intent, a proof contract, a non-author verdict and a retro line, seats are roles in domain pods, and skills are gate, tool or lens kinds checked by evals.</p></blockquote><p>The seven decisions behind it, in short:</p><table><thead><tr><th></th><th>Decision</th><th>What it means in practice</th></tr></thead><tbody><tr><td>D1</td><td>Proof contracts and enforced gates</td><td>Every slice has an intent, a checklist of proof, a verdict from someone who did not write it, and one retro line. Checks enforce it, not prose.</td></tr><tr><td>D2</td><td>Pods are domains, seats are roles</td><td><code>orch.lead</code>, <code>dev.build</code>, <code>dev.qa</code>, <code>dev.review</code>. A lint enforces that the reviewer comes from a different model family than the builder.</td></tr><tr><td>D3</td><td>Three kinds of skills</td><td>Gate skills, tool skills, lens skills. Each <code>SKILL.md</code> stays short and ships with 3+ evals.</td></tr><tr><td>D4</td><td>Skills are written evals first</td><td>A new skill must beat the same model without it.</td></tr><tr><td>D5</td><td>One record shape</td><td><code>SPEC.md</code>, <code>PROGRESS.md</code>, <code>PROOF.md</code> and <code>reports/</code>, in one place per slice.</td></tr><tr><td>D6</td><td>Verdicts bound to the diff</td><td>A review names the exact diff it read. Change the diff and the verdict goes stale.</td></tr><tr><td>D7</td><td>Roll out in waves</td><td>Dogfood on my own workspace rig first, then pilot rigs one at a time, never a forced restart.</td></tr></tbody></table><p>The work was split into 13 slices. A slice is the unit of work here: one outcome, one owner seat, one worktree per repo, usually one PR.</p><h2 id="How-the-day-went"><a href="#How-the-day-went" class="headerlink" title="How the day went"></a>How the day went</h2><p>The first log line is at 02:28. Two seats ran in parallel: one red-teamed the seven decisions against outside sources, the other took an inventory of what already existed. The inventory was not flattering: 96 skills, 131,839 words, 92 of them over the 500-word target.</p><p>Both reports were fact-checked by a reviewer from a third model family, fixed, and turned into an ADR. I accepted it at 03:26. Phase 0, from first log line to accepted ADR, took about an hour.</p><p>Then the build:</p><table><thead><tr><th>Slice</th><th>What landed</th></tr></thead><tbody><tr><td>04 checks</td><td>Five commands: <code>rig-lint</code>, <code>verdict-check</code>, <code>pr-lint</code>, <code>slice-check</code>, <code>merge-gate</code></td></tr><tr><td>05 create-skill</td><td>A skill for writing skills with evals and a no-skill baseline. It replaced the old skill-creator.</td></tr><tr><td>06 gate skills</td><td><code>code-review</code>, <code>intake</code>, <code>shape</code>, <code>retro</code>, <code>verify</code>, each with evals on two models</td></tr><tr><td>07 records resolver</td><td>One script that says where a slice’s records live</td></tr><tr><td>08 roles and templates</td><td>Three rig templates: solo, workshop, factory</td></tr><tr><td>09 prose diet</td><td>Root <code>AGENTS.md</code> from 4,496 to 1,806 words, rules as a table that names the check enforcing each row</td></tr><tr><td>10 deletions</td><td>Six unused skills deleted, 96 down to 90; more scheduled once they sit unused for 14 days</td></tr><tr><td>11 rollout</td><td>The other rigs switched in waves, the last ones the next morning</td></tr><tr><td>12, 13</td><td>A one-seat “content” rig kind (the one writing this post), and a statechart lens skill</td></tr></tbody></table><p>Twelve of the 13 slices closed on the 8th. In the roughly 30 hours from the first log line to the last rollout wave, the public skills repo merged 46 PRs, 8 of them release PRs.</p><p>That is the summary. The parts worth writing about are where something pushed back.</p><h2 id="A-verdict-that-knows-which-diff-it-read"><a href="#A-verdict-that-knows-which-diff-it-read" class="headerlink" title="A verdict that knows which diff it read"></a>A verdict that knows which diff it read</h2><p>Before this, a review was a chat message. Now it is a file with frontmatter: the axes it judged (spec, standards, and security on risky changes), the findings with ids and tags, the reviewer’s seat and model family, and two hashes of the diff:</p><figure class="highlight yaml hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-attr">axes:</span> {<span class="hljs-attr">spec:</span> <span class="hljs-string">pass</span>, <span class="hljs-attr">standards:</span> <span class="hljs-string">pass</span>}</span><br><span class="line"><span class="hljs-attr">patch_id:</span> <span class="hljs-string">21217d35fc70...</span>        <span class="hljs-comment"># git diff base..head | git patch-id --stable</span></span><br><span class="line"><span class="hljs-attr">diff_digest:</span> <span class="hljs-string">sha256:4882e91d...</span>  <span class="hljs-comment"># sha256 of git diff --binary base..head</span></span><br><span class="line"><span class="hljs-attr">reviewer_family:</span> <span class="hljs-string">muse</span></span><br><span class="line"><span class="hljs-attr">findings:</span></span><br><span class="line">  <span class="hljs-bullet">-</span> {<span class="hljs-attr">id:</span> <span class="hljs-string">F2</span>, <span class="hljs-attr">axis:</span> <span class="hljs-string">standards</span>, <span class="hljs-attr">tag:</span> <span class="hljs-string">Nit</span>, <span class="hljs-attr">status:</span> <span class="hljs-string">fixed</span>}</span><br><span class="line">  <span class="hljs-bullet">-</span> {<span class="hljs-attr">id:</span> <span class="hljs-string">F7</span>, <span class="hljs-attr">axis:</span> <span class="hljs-string">spec</span>, <span class="hljs-attr">tag:</span> <span class="hljs-string">Nit</span>, <span class="hljs-attr">status:</span> <span class="hljs-string">open</span>}</span><br></pre></td></tr></tbody></table></figure><p><code>verdict-check</code> recomputes both from the branch. The patch-id survives a rebase, so a verdict stays valid when the branch only moved. It does not catch whitespace: a 1-space and a 4-space indent gave the same patch-id. The digest does catch it, so an indent-only change after review marks the verdict stale. There is a test for exactly that case.</p><p>The first verdict bound this way was the checks slice’s own. It survived two rebases onto main with the same patch-id and digest, and then it landed.</p><h2 id="The-family-lint-and-the-check-that-failed-open"><a href="#The-family-lint-and-the-check-that-failed-open" class="headerlink" title="The family lint, and the check that failed open"></a>The family lint, and the check that failed open</h2><p>D2 says a reviewer must not share a model family with the builder. Two seats on the same model tend to agree with each other, including on the same blind spots. <code>rig-lint</code> maps model ids to families (claude, gpt, glm, grok, gemini, kimi, composer, muse) and fails a rig where a review or QA seat shares a family with a build seat.</p><p>Its first run was humbling. Across the 26 rig specs on one machine, 16 had a failing family finding. My own workspace rig was one of them: its second reviewer ran Claude Opus, the same family as the builders.</p><p>The better story is what happened inside the slice. The builder was on Claude, so the reviewer for the checks themselves was a one-shot from a third family. It found F2, filed as a Nit and fixed as a must-fix: the family check in <code>verdict-check</code> passed silently when <code>reviewer_family</code> was missing, unknown, or in a different case. The independence check failed open on its own metadata. The tests only covered the case where the field was present.</p><p>The retro line for that slice says it better than I would:</p><blockquote><p>A check that reads reviewer-written metadata needs a test for the field being absent.</p></blockquote><h2 id="Evals-that-were-wrong-not-the-model"><a href="#Evals-that-were-wrong-not-the-model" class="headerlink" title="Evals that were wrong, not the model"></a>Evals that were wrong, not the model</h2><p>D4 says a skill has to beat the bare model. The <code>create-skill</code> skill was the first one held to that. It shipped with four scenarios, three runs each, with and without the skill:</p><table><thead><tr><th>Model</th><th>With the skill</th><th>Without</th></tr></thead><tbody><tr><td>Claude Sonnet</td><td>12/12</td><td>0/12</td></tr><tr><td>Muse</td><td>12/12</td><td>0/12</td></tr><tr><td>GLM</td><td>6/12</td><td>0/12</td></tr></tbody></table><p>Then a Claude Opus round came in at 2/3 and 1/3 on two scenarios. The builder seat read the saved outputs before touching anything. Both misses on the second scenario were correct refusals worded “I didn’t create a skill”, and the check’s regex only knew “not create”. The other miss was a helper folder that the check counted as a scenario, while the runner skipped it. The checks were wrong, not the skill. They were fixed, the change was disclosed as “changed after results”, and Opus went to 12/12.</p><p>This happened twice more during the day. A later eval passed 3/3 <em>without</em> the skill on both Claude models. It was too easy, because a strong model found the answer by reading <code>package.json</code>. It was hardened until the baseline failed.</p><h2 id="35-out-of-35-sync-failures-had-one-cause"><a href="#35-out-of-35-sync-failures-had-one-cause" class="headerlink" title="35 out of 35 sync failures had one cause"></a>35 out of 35 sync failures had one cause</h2><p>My workspace records sync through git on a timer, on every machine. On the 8th the sync kept stopping. It went down three times: for 4 h 12 min, 36 min and 3 h 21 min. Each time a person (me, through an operator session) repaired it by hand.</p><p>The seat that took the fix started by counting. The sync log on that machine had 35 integrate failures. All 35 were the same error: a conflict while replaying the local commit. None was the other failure mode. The cause was a habit, not a race. A lead seat committed records from its own worktree while other seats edited the same files in the live checkout, so two commits changed the same record file.</p><p>The fix has two halves:</p><ul><li><strong>A merge rule.</strong> Append logs (<code>PROGRESS.md</code>, <code>NOTES.md</code>) keep both sides with <code>git merge-file --union</code>. Any other record keeps the newer side, and the older one is named in the sync log. Code, specs and docs still stop the round for a person.</li><li><strong>A rule.</strong> Records are written in the live checkout and committed only by the sync. Worktrees carry code, specs and docs.</li></ul><p>The retro for that slice found its own escape: the new commit format put <code>Seat: retro</code> on the first live commit, because a line starting with <code>retro:</code> looked like a seat name. That got fixed the same evening, with test cases for <code>retro</code>, <code>review</code> and <code>lead</code>.</p><h2 id="The-first-PR-end-to-end-and-a-real-find"><a href="#The-first-PR-end-to-end-and-a-real-find" class="headerlink" title="The first PR end to end, and a real find"></a>The first PR end to end, and a real find</h2><p>The real test of D7 was a project rig relaunched fresh on the new templates, then given one PR through the whole flow. It was a client API change. The rig came up at 20:52 and the PR merged at 21:35.</p><p>The first verdict was BLOCKING. The new reviewer seat found an env file holding an API key that was not gitignored. That is a real find, not a style nit. The fix was one line in <code>.gitignore</code>. Round 2 passed, and the merge gate held all six gates on its third run, without an admin override.</p><p>The lead of that rig wrote a read-out with ten frictions. Three of them:</p><ul><li>The retro gate counted per slice, so a second PR passed on the first PR’s retro line.</li><li>The review round counter counted other PRs’ verdicts toward this PR’s cap.</li><li>Proving a <code>.gitignore</code> change with <code>git check-ignore</code> read the base branch’s file, not the PR’s.</li></ul><p>The first two were fixed that night in the checks and the skills, after a review that was itself BLOCKING once on three holes in the new per-PR checks. The third became one line in the <code>code-review</code> skill.</p><h2 id="Quota-juggling"><a href="#Quota-juggling" class="headerlink" title="Quota juggling"></a>Quota juggling</h2><p>All of this ran on subscription quota, and the quota set the pace more than anything else.</p><ul><li><strong>03:26</strong>: my main Claude account was at 100% on both the 5-hour and the 7-day window. One writer at a time.</li><li><strong>06:02</strong>: I moved the building seats to Opus on high effort anyway. Quality before quota. Reviewers stayed off Claude: Muse and GLM one-shots.</li><li><strong>08:25</strong>: Claude’s 5-hour window dropped under about 10%. Two seats moved to GLM, and their work was reviewed by Muse, since GLM wrote it.</li><li><strong>Afternoon</strong>: an Opus eval run hit 429s and stopped at the cap. The Claude eval runs went on a list for later.</li><li><strong>16:15</strong>: one probe with 12 Opus sessions showed no visible change in quota at whole-percent resolution, so the list ran: about 156 sessions moved one account’s 7-day window from 65% to 67%.</li></ul><p>The family lint and the quota pulled the same way. Reviewers had to be another family anyway, so the reviewers ran on the accounts with room. The next day that became the fallback until the weekly reset: builders and leads stay on Claude, reviewers run GLM for code and Muse for anything with screenshots.</p><h2 id="Slips-that-became-rules"><a href="#Slips-that-became-rules" class="headerlink" title="Slips that became rules"></a>Slips that became rules</h2><p>Agents slipped too, and the records kept them:</p><ul><li>A seat backgrounded <code>cd &lt;worktree&gt; &amp;&amp; harness &amp;</code>, then ran <code>git commit</code> in the same call. The <code>cd</code> only ran in the background subshell, so the commit landed in the live workspace checkout and swept in two other seats’ files. It was not pushed, and it was undone with a mixed reset.</li><li>A seat killed its eval harness with <code>pkill -f &lt;pattern&gt;</code>. Kill by pattern matches every command line that contains it.</li><li>The lead ran <code>find /</code> to locate a skill.</li></ul><p>Two of them are now lines in the rules every seat loads: never kill by pattern (start with <code>cmd &amp; pid=$!</code>, then <code>kill "$pid"</code>), and never scan from <code>/</code>. The pattern-kill rule names the incident that made it a rule: the same day, a pattern kill stopped my board server. The background <code>cd</code> is a recorded lesson for now, not a rule. A rule that names its incident is easier to keep than one that only names a principle.</p><h2 id="What-is-still-open"><a href="#What-is-still-open" class="headerlink" title="What is still open"></a>What is still open</h2><ul><li>The rollout’s later waves are switched, but the seat renames wait for each rig’s next natural relaunch.</li><li>The rest of the delete list becomes eligible between 11 and 22 November, once each skill sits unused for 14 days.</li><li>GLM passes <code>create-skill</code> at 6/12. I did not tune the skill for it. Whether the bar should be per model is an open question.</li></ul><p>The lesson from the day: none of the checks had to be clever. A hash of the diff, a table of model families, a regex for a retro line. They worked because they ran on every slice. The first real catches were in the checks themselves.</p><h2 id="Start-your-own"><a href="#Start-your-own" class="headerlink" title="Start your own"></a>Start your own</h2><p>I am turning the skeleton of this setup (records layout, rig templates, the check commands) into a template repo. It is public now: <a target="_blank" rel="noopener" href="https://github.com/vanducng/agent-project-template">agent-project-template</a>.</p><p>Part 2 will cover the week after: whether the gates held up on real client work, and what the pilot rigs’ numbers say.</p><h2 id="References"><a href="#References" class="headerlink" title="References"></a>References</h2><ul><li><a target="_blank" rel="noopener" href="https://github.com/vanducng/skills">vanducng/skills</a>: <code>create-skill</code>, <code>code-review</code>, <code>intake</code>, <code>shape</code>, <code>verify</code>, <code>retro</code>, <code>openrig-workspace</code></li><li><a target="_blank" rel="noopener" href="https://github.com/mvschwarz/openrig">OpenRig</a>, the rig runtime the fleet runs on</li><li><a href="/2026/10/31/rexboard-an-attention-board-for-my-coding-agents/">rexboard: An Attention Board for My Coding Agents</a>, how I watch the fleet</li></ul></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Sources&lt;/strong&gt;: my private workspace records for that day (the mission’s spec, progress log, slice proofs and review verdicts), and the merged PRs in my public &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://github.com/vanducng/skills/pulls?q=is:pr+is:merged&quot;&gt;skills repo&lt;/a&gt;. Times are UTC.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;I run a fleet of coding agents: several teams of them, on three machines, each team working through one project. For months the process lived in prose. My root &lt;code&gt;AGENTS.md&lt;/code&gt; was 4,496 words. Reviews passed because a reviewer agent said “looks good”, and nobody could tell which diff it had looked at.&lt;/p&gt;
&lt;p&gt;On Sunday 8 November I wrote seven decisions down and handed them to the fleet. By the next morning the agents had built most of the gates that enforce them, and the gates had already caught real mistakes, including some in the gates.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="agentic-coding" scheme="https://vanducng.dev/tags/agentic-coding/"/>
    
    <category term="coding-agents" scheme="https://vanducng.dev/tags/coding-agents/"/>
    
    <category term="developer-tools" scheme="https://vanducng.dev/tags/developer-tools/"/>
    
    <category term="code-review" scheme="https://vanducng.dev/tags/code-review/"/>
    
    <category term="openrig" scheme="https://vanducng.dev/tags/openrig/"/>
    
  </entry>
  
  <entry>
    <title>My Coding Agents Kept Failing. The ISP Router Was the Bug (Part 1)</title>
    <link href="https://vanducng.dev/2026/11/01/home-network-for-coding-agents-part-1/"/>
    <id>https://vanducng.dev/2026/11/01/home-network-for-coding-agents-part-1/</id>
    <published>2026-11-01T21:00:00.000Z</published>
    <updated>2026-11-16T05:26:58.277Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><p>A few of my coding-agent seats started reporting <code>connection failed</code>. Not all of them. Not all the time. Just enough to stall work for hours.</p><p>The bug was not in the agents, the model provider, or the gateway in front of them. It was the ISP router at home: a VNPT iGate GW040-NS that had started dropping most full-size packets.</p><p>This is Part 1: how I found it, what I measured, what I’m replacing it with, and the setup plan. Part 2 covers the real cutover once the hardware is on my desk.</p><span id="more"></span><img src="/2026/11/01/home-network-for-coding-agents-part-1/cover.png" class="" title="My coding agents kept failing. The ISP router was the bug."><h2 id="The-setup"><a href="#The-setup" class="headerlink" title="The setup"></a>The setup</h2><p>Two always-on machines at home run my agent seats: a Linux box and a Mac mini. Both talk to an LLM gateway (CLIProxyAPI) on a small k3s cluster outside the house. Everything else is a normal family network: a Proxmox server, a NAS, my MacBook, my wife’s PCs and phones, and a handful of smart-home devices.</p><p>All of it hangs off one box from the ISP.</p><img src="/2026/11/01/home-network-for-coding-agents-part-1/home-network-as-is.png" class="" title="Home network today: the VNPT GW040-NS does fiber, PPPoE, NAT, DHCP and Wi-Fi for everything"><p>The GW040-NS is the fiber terminal, the PPPoE client, the NAT, the DHCP and DNS server, and the Wi-Fi access point, on a dual-core 1.0 GHz ARM with 512 MB of RAM (<a target="_blank" rel="noopener" href="https://www.vnpt-technology.vn/vi/product_detail/gpon-ont-igate-gw040-ns">VNPT Technology spec</a>). All four of its LAN ports are in use.</p><h2 id="The-symptom"><a href="#The-symptom" class="headerlink" title="The symptom"></a>The symptom</h2><p>From the agent side: <code>connection failed</code>, then a retry, sometimes a stuck turn.</p><p>From the gateway side, the logs had a pattern:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">400 | 2m20s | POST "/v1/responses"</span><br><span class="line">{"error":{"message":"Invalid request: unexpected EOF","type":"invalid_request_error"}}</span><br></pre></td></tr></tbody></table></figure><p>A <code>400</code> after two minutes is not a model error. The gateway was still reading the request body when the connection died. One failed request declared <code>Content-Length: 6556360</code>, and the gateway had received about 3.7 MB of it.</p><h2 id="False-lead-1-a-deployment"><a href="#False-lead-1-a-deployment" class="headerlink" title="False lead 1: a deployment"></a>False lead 1: a deployment</h2><p>My first guess was a gateway upgrade. The image had moved from v8.0.41 to v8.0.47 that week.</p><p>The numbers said no. Counting those slow <code>unexpected EOF</code> errors per window (GMT+7):</p><table><thead><tr><th>Window</th><th>Successful requests</th><th>Cut-off uploads</th><th>Gateway version</th></tr></thead><tbody><tr><td>Oct 27 17:00 → Oct 28 17:00</td><td>11,700</td><td>0</td><td>v8.0.41</td></tr><tr><td>Oct 28 17:00 → Oct 29 11:00</td><td>12,100</td><td>58</td><td>v8.0.41</td></tr><tr><td>Oct 29 11:00 → Oct 30 11:00</td><td>19,900</td><td>1,677</td><td>v8.0.41</td></tr><tr><td>Oct 30 11:00 → Nov 1 05:00</td><td>24,000</td><td>0</td><td>v8.0.41</td></tr><tr><td>Nov 1 05:00 → Nov 2 01:30</td><td>13,900+</td><td>318</td><td>v8.0.41, then v8.0.47</td></tr></tbody></table><p>The same version had the worst stretch and then 42 clean hours at normal traffic. The latest wave started an hour before the upgrade rolled out. Nothing was deployed when the big wave began.</p><h2 id="False-lead-2-“only-some-seats-are-broken”"><a href="#False-lead-2-“only-some-seats-are-broken”" class="headerlink" title="False lead 2: “only some seats are broken”"></a>False lead 2: “only some seats are broken”</h2><p>At first only one seat failed: a QA reviewer. That looked like a seat bug.</p><p>It was a size bug. Coding agents resend their whole conversation every turn, and that QA seat had screenshots in its context. Each turn uploaded about <strong>6.6 MB</strong>. The other seats sent well under 1 MB.</p><p>As the network got worse, the smaller seats started failing too. The last ten failures before the fix all came from my home connection, with request bodies from 0.28 MB to 6.6 MB. Big uploads fail first. Then everything does.</p><h2 id="The-measurement"><a href="#The-measurement" class="headerlink" title="The measurement"></a>The measurement</h2><p>Two tests settled it, both run from the Linux box and the Mac mini:</p><ol><li><strong>Ping with small and full-size packets.</strong> Small pings lie. A 56-byte ping got through almost every time. A 1400-byte ping often didn’t.</li><li><strong>A real upload.</strong> Download was fine at 10 MB/s. Upload was not.</li></ol><table><thead><tr><th>Test</th><th>Linux box</th><th>Mac mini</th></tr></thead><tbody><tr><td>56-byte ping → router, loss</td><td>3%</td><td>10%</td></tr><tr><td>1400-byte ping → router, loss</td><td><strong>77%</strong></td><td><strong>70%</strong></td></tr><tr><td>1400-byte ping → gateway cluster, loss</td><td>57%</td><td>70%</td></tr><tr><td>6 MB upload</td><td>4 KB/s, did not finish</td><td>13 KB/s, did not finish</td></tr></tbody></table><p>The packet loss started at the first hop: the router itself. The Linux box and the Mac mini pinged each other with 0% loss, and a laptop on another network reached the gateway cluster with 0% loss. Both hosts are wired at 1 Gbps, and the Linux box showed zero interface errors.</p><p>So it was not the machines, the cables between them, the gateway, or the model provider. It was the GW040-NS.</p><h2 id="The-fix-that-only-buys-time"><a href="#The-fix-that-only-buys-time" class="headerlink" title="The fix that only buys time"></a>The fix that only buys time</h2><p>I restarted the router.</p><table><thead><tr><th>Test</th><th>Before restart</th><th>After restart</th></tr></thead><tbody><tr><td>1400-byte ping → router</td><td>70–77% loss</td><td>0%</td></tr><tr><td>1400-byte ping → gateway cluster</td><td>57–70% loss</td><td>0%</td></tr><tr><td>6 MB upload</td><td>4–13 KB/s</td><td>5.6–8.5 MB/s</td></tr></tbody></table><p>The gateway logged no new cut-off uploads after that. The last few errors were requests that had started before the restart and timed out afterwards.</p><p>Two hours later, upload from the same machines was already down to 0.2–0.4 MB/s again, still without packet loss. A restart resets the box. It does not fix it.</p><p>My best explanation: the GW040-NS does NAT for every long-lived connection on the network (agent streams, Tailscale, remote desktop, sync) on a small CPU, and it degrades until it is restarted. I can’t see inside it, so I’m not going to keep guessing. I’m moving the routing off it.</p><h2 id="The-plan"><a href="#The-plan" class="headerlink" title="The plan"></a>The plan</h2><p>Keep the VNPT box for the one thing it has to do: terminate the fiber. Put the GW040-NS in <strong>bridge mode</strong> and let a real router do PPPoE, NAT, DHCP, DNS, and the firewall.</p><img src="/2026/11/01/home-network-for-coding-agents-part-1/home-network-to-be.png" class="" title="Planned network: GW040-NS in bridge mode, MikroTik RB5009 does the routing, optional second WAN for failover"><p>Two extras while I’m at it:</p><ul><li><strong>A second WAN</strong> (Viettel or FPT) with automatic failover, so one ISP box can’t take every agent down again.</li><li><strong>A probe on the Linux box</strong> that runs full-size pings and a real upload test every few minutes and alerts me. This time the network was bad on and off for four days before I knew why.</li></ul><h2 id="Choosing-the-router"><a href="#Choosing-the-router" class="headerlink" title="Choosing the router"></a>Choosing the router</h2><p>Requirements: PPPoE on gigabit fiber without breaking a sweat, lots of concurrent NAT sessions, at least 6 ports, multi-WAN, and config I can keep in git.</p><table><thead><tr><th></th><th>VNPT GW040-NS (today)</th><th>MikroTik hEX S 2025</th><th>TP-Link ER605 v2</th><th>UniFi Cloud Gateway Ultra</th><th><strong>MikroTik RB5009</strong></th></tr></thead><tbody><tr><td>CPU</td><td>dual-core ARM 1.0 GHz</td><td>dual-core 950 MHz</td><td>not published</td><td>quad-core A53 1.5 GHz</td><td>quad-core ARMv8 1.4 GHz</td></tr><tr><td>RAM</td><td>512 MB</td><td>512 MB</td><td>not published</td><td>3 GB</td><td>1 GB</td></tr><tr><td>Ports</td><td>4× 1G LAN</td><td>5× 1G + 2.5G SFP</td><td>5× 1G</td><td>1× 2.5G WAN + 4× 1G</td><td>7× 1G + 1× 2.5G + 10G SFP+</td></tr><tr><td>Multi-WAN</td><td>no</td><td>yes</td><td>up to 4 WAN</td><td>up to 4 WAN</td><td>yes, any port</td></tr><tr><td>Managed via</td><td>ISP web UI</td><td>RouterOS</td><td>Omada web/cloud</td><td>UniFi app</td><td>RouterOS (CLI, scriptable)</td></tr><tr><td>Price in Vietnam</td><td>from the ISP</td><td>2.16–2.5M VND</td><td>1.15–1.63M VND</td><td>3.07–3.95M VND</td><td>5.59–6.12M VND</td></tr></tbody></table><p>Prices were checked on November 2, 2026, VAT included, from Vietnamese shops (links below). They move often.</p><p><strong>Why not the cheaper ones.</strong> The hEX S is in the same CPU and RAM class as the box I’m replacing. The ER605 is fine for a small office, but shops rate it for about 50–60 users, and I’m already near that once phones and IoT count.</p><p><strong>Why not UniFi.</strong> The UCG-Ultra is the easiest good option here, and the one I’d recommend to most people. I want RouterOS config I can export, diff, and keep in git, and more than four LAN ports.</p><p><strong>Why the RB5009.</strong> Quad-core, 1 GB RAM, eight copper ports plus 10G SFP+, and any port can be a WAN. In MikroTik’s own <a target="_blank" rel="noopener" href="https://mikrotik.com/product/rb5009ug_s_in">all-port test</a> it routes 9.8 Gbps with 1518-byte packets. Far more than one gigabit fiber line needs, which is the point. MikroTik’s suggested price is $219.</p><h3 id="Port-plan"><a href="#Port-plan" class="headerlink" title="Port plan"></a>Port plan</h3><img src="/2026/11/01/home-network-for-coding-agents-part-1/rb5009-ports.jpg" class="" title="MikroTik RB5009 port plan: ether1 WAN, ether2 to 5 wired hosts, ether6 Wi-Fi AP, spares"><p>On the VNPT side, only one LAN port stays in use:</p><img src="/2026/11/01/home-network-for-coding-agents-part-1/gw040ns-ports.png" class="" title="GW040-NS back panel: LAN1 feeds the RB5009 in bridge mode, LAN2 to 4 go empty"><h3 id="Where-to-buy"><a href="#Where-to-buy" class="headerlink" title="Where to buy"></a>Where to buy</h3><table><thead><tr><th>Shop</th><th>Price (VAT incl.)</th><th>Notes</th></tr></thead><tbody><tr><td><a target="_blank" rel="noopener" href="https://t2qwifi.com/san-pham/router-mikrotik-rb5009ugsin">T2QWIFI</a></td><td>5,590,000 VND</td><td>Ho Chi Minh City</td></tr><tr><td><a target="_blank" rel="noopener" href="https://tic.vn/mikrotik-rb5009ug-s-in">TIC</a></td><td>6,120,000 VND</td><td></td></tr><tr><td><a target="_blank" rel="noopener" href="https://www.anphatpc.com.vn/thiet-bi-can-bang-tai-router-mikrotik-rb5009ug-s-in.html">An Phát</a></td><td>ask</td><td>large retailer</td></tr></tbody></table><p>Ask for official stock (<em>hàng chính hãng</em>) with a 12-month warranty. If you go UniFi instead, the UCG-Ultra was 3.07–3.95M VND at <a target="_blank" rel="noopener" href="https://akas.com.vn/unifi-cloud-gateway-ultra/">AKAS</a>, <a target="_blank" rel="noopener" href="https://techonline.vn/unifi-cloud-gateway-ultra-ucg-ultra">Techonline</a>, <a target="_blank" rel="noopener" href="https://www.sieuthimaychu.vn/index.php/Thong_Tin_San_Pham/23734/UniFi-Cloud-Gateway-Ultra">Siêu Thị Máy Chủ</a>, and <a target="_blank" rel="noopener" href="https://khanhhan.vn/unifi-cloud-gateway-ultra-ucg-ultra">Khánh Hân</a>.</p><h2 id="Setup-plan"><a href="#Setup-plan" class="headerlink" title="Setup plan"></a>Setup plan</h2><p>This is the plan I’ll execute in Part 2. The RouterOS commands are a draft against the RB5009 default configuration on RouterOS v7. Part 2 will have the tested version and screenshots.</p><h3 id="1-Collect-what-VNPT-knows"><a href="#1-Collect-what-VNPT-knows" class="headerlink" title="1. Collect what VNPT knows"></a>1. Collect what VNPT knows</h3><p>Call VNPT (18001091) or read the GW040-NS WAN page, and write down:</p><ul><li>the PPPoE username and password (the router UI usually masks the password; VNPT can give it to you),</li><li>the Internet VLAN ID on the WAN connection,</li><li>whether you use MyTV or a VNPT phone line. Each needs its own VLAN. I use neither.</li></ul><p>You can also ask VNPT to put the box in bridge mode for you.</p><h3 id="2-Stage-the-RB5009-on-the-bench"><a href="#2-Stage-the-RB5009-on-the-bench" class="headerlink" title="2. Stage the RB5009 on the bench"></a>2. Stage the RB5009 on the bench</h3><p>Do all of this before touching the live network, with only a laptop plugged in.</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line"># Update RouterOS (reboots), then the RouterBOOT firmware (reboot once more)</span><br><span class="line">/system package update check-for-updates</span><br><span class="line">/system package update install</span><br><span class="line">/system routerboard upgrade</span><br><span class="line">/system reboot</span><br><span class="line"></span><br><span class="line"># Lock it down; keep Winbox and SSH</span><br><span class="line">/user set admin password="&lt;a-long-password&gt;"</span><br><span class="line">/ip service disable telnet,ftp,www,api,api-ssl</span><br></pre></td></tr></tbody></table></figure><p>The default config already gives you a LAN bridge (ether2–8 and the SFP+), a DHCP server, a firewall that drops unsolicited WAN traffic, FastTrack, and NAT for anything leaving the <code>WAN</code> interface list. Keep it and adjust.</p><p>Move the LAN to its own subnet, because the GW040-NS usually keeps <code>192.168.1.1</code> for its admin page even in bridge mode. Run this block from Winbox connected by MAC address: changing the bridge address drops an IP session halfway through.</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line">/ip address set [find interface=bridge] address=192.168.10.1/24</span><br><span class="line">/ip pool set [find name=default-dhcp] ranges=192.168.10.100-192.168.10.200</span><br><span class="line">/ip dhcp-server network set [find] address=192.168.10.0/24 gateway=192.168.10.1 dns-server=192.168.10.1</span><br><span class="line">/ip dns set servers=1.1.1.1,8.8.8.8 allow-remote-requests=yes</span><br><span class="line"></span><br><span class="line"># Fixed addresses for the always-on hosts</span><br><span class="line">/ip dhcp-server lease add address=192.168.10.10 mac-address=&lt;linux-box-mac&gt; comment="Linux box"</span><br><span class="line">/ip dhcp-server lease add address=192.168.10.11 mac-address=&lt;mac-mini-mac&gt; comment="Mac mini"</span><br></pre></td></tr></tbody></table></figure><h3 id="3-WAN-PPPoE-on-ether1"><a href="#3-WAN-PPPoE-on-ether1" class="headerlink" title="3. WAN: PPPoE on ether1"></a>3. WAN: PPPoE on ether1</h3><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line">/ip dhcp-client remove [find interface=ether1]</span><br><span class="line">/interface pppoe-client add name=pppoe-vnpt interface=ether1 \</span><br><span class="line">    user="&lt;pppoe-user&gt;" password="&lt;pppoe-password&gt;" \</span><br><span class="line">    add-default-route=yes use-peer-dns=no max-mtu=1492 max-mru=1492 disabled=no</span><br><span class="line">/interface list member add list=WAN interface=pppoe-vnpt</span><br><span class="line"></span><br><span class="line"># TCP MSS must be clamped for PPPoE; change-tcp-mss should be yes here</span><br><span class="line">/ppp profile print where name=default</span><br></pre></td></tr></tbody></table></figure><p>If the GW040-NS bridge passes the VLAN tag through instead of stripping it, move the PPPoE client onto a VLAN interface:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">/interface vlan add name=vlan-vnpt interface=ether1 vlan-id=&lt;vlan-id&gt;</span><br><span class="line">/interface pppoe-client set pppoe-vnpt interface=vlan-vnpt</span><br></pre></td></tr></tbody></table></figure><p>Keep the VNPT admin page reachable from the LAN:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">/ip address add address=192.168.1.2/24 interface=ether1 comment="GW040 admin"</span><br><span class="line">/ip firewall nat add chain=srcnat out-interface=ether1 dst-address=192.168.1.1 action=masquerade comment="GW040 admin"</span><br></pre></td></tr></tbody></table></figure><p>VNPT also hands out IPv6. Ask for a prefix over PPPoE and advertise it on the LAN:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">/ipv6 dhcp-client add interface=pppoe-vnpt request=prefix pool-name=vnpt-v6 add-default-route=yes</span><br><span class="line">/ipv6 address add interface=bridge address=::1 from-pool=vnpt-v6 advertise=yes</span><br></pre></td></tr></tbody></table></figure><p>Save a baseline before the cutover:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">/system backup save name=pre-cutover</span><br><span class="line">/export file=rb5009-baseline</span><br></pre></td></tr></tbody></table></figure><p>On RouterOS v7, <code>/export</code> leaves passwords out unless you ask for them, so that file can go into git. The <code>.backup</code> file holds every secret, including the PPPoE password: keep it off git.</p><h3 id="4-The-cutover"><a href="#4-The-cutover" class="headerlink" title="4. The cutover"></a>4. The cutover</h3><ol><li>On the GW040-NS: delete the PPPoE WAN, create a <strong>Bridge</strong> WAN with the same VLAN, bind it to <strong>LAN1</strong>, then turn off its DHCP server and Wi-Fi. Menu names vary by firmware.</li><li>Cable it: GW040 LAN1 → RB5009 ether1. Linux box, Proxmox, Mac mini, NAS → ether2–5. Wi-Fi AP → ether6.</li><li>Watch PPPoE come up: <code>/interface pppoe-client monitor pppoe-vnpt once</code>.</li><li>Move the hosts with static addresses to <code>192.168.10.0/24</code>.</li></ol><p>One open question for Wi-Fi: my VNPT mesh node backhauls over Wi-Fi to the GW040-NS. With the GW040’s Wi-Fi off, it loses that uplink. Either it gets wired to ether6 as an access point, or it gets replaced with a proper AP. Part 2 will say which.</p><p><strong>Rollback:</strong> recreate the PPPoE WAN on the GW040-NS with the credentials from step 1 and plug the hosts back into it. That is quick as long as the credentials are written down.</p><h3 id="5-Prove-it-then-keep-proving-it"><a href="#5-Prove-it-then-keep-proving-it" class="headerlink" title="5. Prove it, then keep proving it"></a>5. Prove it, then keep proving it</h3><p>The same tests as before, from the Linux box and the Mac mini:</p><figure class="highlight bash hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">ping -c 40 -s 1400 -q &lt;gateway-host&gt;      <span class="hljs-comment"># expect 0% loss</span></span><br><span class="line"><span class="hljs-built_in">head</span> -c 6000000 /dev/urandom | \</span><br><span class="line">  curl -s -o /dev/null -w <span class="hljs-string">'%{speed_upload}\n'</span> --data-binary @- https://speed.cloudflare.com/__up</span><br></pre></td></tr></tbody></table></figure><p>Then automate it. This is the probe I’ll run on the Linux box every five minutes:</p><figure class="highlight bash hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-meta">#!/usr/bin/env bash</span></span><br><span class="line"><span class="hljs-comment"># Full-size ping + real upload probe; alerts to Telegram when either looks bad.</span></span><br><span class="line"><span class="hljs-comment"># Linux only: iputils ping takes -W in seconds.</span></span><br><span class="line"><span class="hljs-built_in">set</span> -euo pipefail</span><br><span class="line"></span><br><span class="line">target=<span class="hljs-string">"<span class="hljs-variable">${PROBE_TARGET:-1.1.1.1}</span>"</span></span><br><span class="line">max_loss=5          <span class="hljs-comment"># percent, 1400-byte pings</span></span><br><span class="line">min_upload=1000000  <span class="hljs-comment"># bytes/s for a 2 MB upload</span></span><br><span class="line"></span><br><span class="line">loss=$( (ping -c 20 -i 0.2 -s 1400 -W 1 -q <span class="hljs-string">"<span class="hljs-variable">$target</span>"</span> || <span class="hljs-literal">true</span>) | grep -oE <span class="hljs-string">'[0-9.]+% packet loss'</span> | <span class="hljs-built_in">cut</span> -d% -f1 || <span class="hljs-literal">true</span>)</span><br><span class="line">loss=<span class="hljs-variable">${loss:-100}</span>   <span class="hljs-comment"># no summary line means the network is down</span></span><br><span class="line">upload=$(<span class="hljs-built_in">head</span> -c 2000000 /dev/urandom |</span><br><span class="line">  curl -s -o /dev/null -m 30 -w <span class="hljs-string">'%{speed_upload}'</span> --data-binary @- https://speed.cloudflare.com/__up || <span class="hljs-literal">true</span>)</span><br><span class="line">upload=<span class="hljs-variable">${upload:-0}</span></span><br><span class="line"></span><br><span class="line">msg=<span class="hljs-string">"net-probe <span class="hljs-subst">$(hostname)</span>: 1400B loss=<span class="hljs-variable">${loss}</span>% upload=<span class="hljs-subst">$((${upload%.*} / 1024)</span>) KB/s"</span></span><br><span class="line"><span class="hljs-built_in">echo</span> <span class="hljs-string">"<span class="hljs-variable">$msg</span>"</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">if</span> awk -v l=<span class="hljs-string">"<span class="hljs-variable">$loss</span>"</span> -v u=<span class="hljs-string">"<span class="hljs-variable">$upload</span>"</span> -v ml=<span class="hljs-string">"<span class="hljs-variable">$max_loss</span>"</span> -v mu=<span class="hljs-string">"<span class="hljs-variable">$min_upload</span>"</span> <span class="hljs-string">'BEGIN { exit !(l &gt; ml || u &lt; mu) }'</span>; <span class="hljs-keyword">then</span></span><br><span class="line">  <span class="hljs-keyword">if</span> [[ -n <span class="hljs-string">"<span class="hljs-variable">${TG_TOKEN:-}</span>"</span> &amp;&amp; -n <span class="hljs-string">"<span class="hljs-variable">${TG_CHAT:-}</span>"</span> ]]; <span class="hljs-keyword">then</span></span><br><span class="line">    curl -s -o /dev/null <span class="hljs-string">"https://api.telegram.org/bot<span class="hljs-variable">${TG_TOKEN}</span>/sendMessage"</span> \</span><br><span class="line">      --data-urlencode <span class="hljs-string">"chat_id=<span class="hljs-variable">${TG_CHAT}</span>"</span> --data-urlencode <span class="hljs-string">"text=ALERT <span class="hljs-variable">${msg}</span>"</span></span><br><span class="line">  <span class="hljs-keyword">fi</span></span><br><span class="line">  <span class="hljs-built_in">exit</span> 1</span><br><span class="line"><span class="hljs-keyword">fi</span></span><br></pre></td></tr></tbody></table></figure><figure class="highlight ini hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-comment"># /etc/systemd/system/net-probe.service</span></span><br><span class="line"><span class="hljs-section">[Service]</span></span><br><span class="line"><span class="hljs-attr">Type</span>=<span class="hljs-literal">on</span>eshot</span><br><span class="line"><span class="hljs-attr">EnvironmentFile</span>=-/etc/net-probe.env</span><br><span class="line"><span class="hljs-attr">ExecStart</span>=/usr/local/bin/net-probe.sh</span><br><span class="line"></span><br><span class="line"><span class="hljs-comment"># /etc/systemd/system/net-probe.timer</span></span><br><span class="line"><span class="hljs-section">[Timer]</span></span><br><span class="line"><span class="hljs-attr">OnCalendar</span>=*:<span class="hljs-number">0</span>/<span class="hljs-number">5</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-section">[Install]</span></span><br><span class="line"><span class="hljs-attr">WantedBy</span>=timers.target</span><br></pre></td></tr></tbody></table></figure><figure class="highlight bash hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-built_in">sudo</span> install -m 755 net-probe.sh /usr/local/bin/net-probe.sh</span><br><span class="line"><span class="hljs-built_in">sudo</span> install -m 600 /dev/null /etc/net-probe.env   <span class="hljs-comment"># then add TG_TOKEN= and TG_CHAT=</span></span><br><span class="line"><span class="hljs-built_in">sudo</span> systemctl daemon-reload &amp;&amp; <span class="hljs-built_in">sudo</span> systemctl <span class="hljs-built_in">enable</span> --now net-probe.timer</span><br></pre></td></tr></tbody></table></figure><p>Every five minutes, a 2 MB upload adds up to about 576 MB a day. Fine on home fiber, but worth knowing.</p><p>I ran this probe on the current setup while finishing this post, about two and a half hours after the restart. It reported 5% loss on full-size packets and 82 KB/s upload, and exited non-zero. The box is sliding again.</p><h2 id="What-I’d-tell-past-me"><a href="#What-I’d-tell-past-me" class="headerlink" title="What I’d tell past me"></a>What I’d tell past me</h2><ul><li><strong>Small pings lie.</strong> Test with full-size packets (<code>ping -s 1400</code>) and a real upload, not just <code>ping 1.1.1.1</code>.</li><li><strong>Agents are upload-heavy.</strong> They resend the whole context every turn, so a degraded uplink hits them first, and the seat with the biggest context fails before anyone else.</li><li><strong>Read the status code and the duration together.</strong> A <code>400</code> after two minutes on a large body is a transport problem dressed up as a validation error.</li><li><strong>Check what changed before blaming a deploy.</strong> The same gateway version had both the worst day and 42 clean hours.</li></ul><p>Part 2: the RB5009 arrives, the VNPT box goes into bridge mode, and the same tests run again.</p></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;p&gt;A few of my coding-agent seats started reporting &lt;code&gt;connection failed&lt;/code&gt;. Not all of them. Not all the time. Just enough to stall work for hours.&lt;/p&gt;
&lt;p&gt;The bug was not in the agents, the model provider, or the gateway in front of them. It was the ISP router at home: a VNPT iGate GW040-NS that had started dropping most full-size packets.&lt;/p&gt;
&lt;p&gt;This is Part 1: how I found it, what I measured, what I’m replacing it with, and the setup plan. Part 2 covers the real cutover once the hardware is on my desk.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="DevOps" scheme="https://vanducng.dev/categories/DevOps/"/>
    
    
    <category term="agentic-coding" scheme="https://vanducng.dev/tags/agentic-coding/"/>
    
    <category term="networking" scheme="https://vanducng.dev/tags/networking/"/>
    
    <category term="mikrotik" scheme="https://vanducng.dev/tags/mikrotik/"/>
    
    <category term="homelab" scheme="https://vanducng.dev/tags/homelab/"/>
    
    <category term="debugging" scheme="https://vanducng.dev/tags/debugging/"/>
    
  </entry>
  
  <entry>
    <title>rexboard: An Attention Board for My Coding Agents</title>
    <link href="https://vanducng.dev/2026/10/31/rexboard-an-attention-board-for-my-coding-agents/"/>
    <id>https://vanducng.dev/2026/10/31/rexboard-an-attention-board-for-my-coding-agents/</id>
    <published>2026-10-31T18:00:00.000Z</published>
    <updated>2026-11-16T05:26:58.281Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><blockquote><p><strong>Sources</strong>: the <a target="_blank" rel="noopener" href="https://github.com/vanducng/rexboard">rexboard repo</a> (README, docs, ADRs and the <a target="_blank" rel="noopener" href="https://github.com/vanducng/rexboard/blob/main/CHANGELOG.md">CHANGELOG</a> up to v0.20.0), my own mission notes for the build, and the tools I compared it with: <a target="_blank" rel="noopener" href="https://github.com/nicknisi/fleet">Fleet</a>, <a target="_blank" rel="noopener" href="https://github.com/asheshgoplani/agent-deck">Agent Deck</a>, <a target="_blank" rel="noopener" href="https://github.com/miya-masa/cc-pane">cc-pane</a>, <a target="_blank" rel="noopener" href="https://muxbell.com/">Muxbell</a> and <a target="_blank" rel="noopener" href="https://github.com/Lukeesec/mux-beacon">Mux Beacon</a>.</p></blockquote><p>On a normal day I have somewhere around 70 agent panes open across three machines. Most of them are fine. A few are stuck on a permission prompt, one has finished and is waiting for me, and one hit an error twenty minutes ago and I have no idea which. I kept losing time hunting for those panes, so I built a board that finds them for me.</p><p>That board is <a target="_blank" rel="noopener" href="https://github.com/vanducng/rexboard">rexboard</a>. It went from v0.1.0 to v0.20.0 in about a week. This post covers what it is, why it works the way it does, where it stands, and what I want to add next.</p><span id="more"></span><p><video src="/videos/rexboard-promo.mp4" controls="" muted="" playsinline="" width="100%"></video></p><h2 id="What-it-is"><a href="#What-it-is" class="headerlink" title="What it is"></a>What it is</h2><p>rexboard is a Rust CLI and TUI (ratatui) for the coding agents running in <a target="_blank" rel="noopener" href="https://www.superlogical.com/rex/docs">Rex</a> panes. The intent line in my project spec says it plainly:</p><blockquote><p>One list of every coding agent pane on every Rex host, ordered by who needs you, with time in state and a key that jumps to the pane.</p></blockquote><p>You run <code>rexboard</code>, and you get one list grouped into NEEDS YOU, WORKING, QUIET and UNREPORTED. Blocked, errored, and done-but-not-seen rows sit on top. <code>enter</code> jumps to the pane, even on another host. <code>space</code> watches it live, <code>a</code> answers a prompt from the board, <code>x</code> sends a message, and <code>p</code> shows a live preview strip of the selected pane.</p><figure class="highlight bash hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line">brew install vanducng/tap/rexboard</span><br><span class="line">rexboard</span><br><span class="line">rexboard hooks install --dry-run   <span class="hljs-comment"># see what it would change first</span></span><br><span class="line">rexboard hooks install</span><br></pre></td></tr></tbody></table></figure><p>It knows Claude Code, Codex, pi and grok. Since v0.18.0 it also shows MODEL, CTX, TOK, COST and the 5-hour usage window per row, on remote hosts too.</p><h2 id="How-it-works"><a href="#How-it-works" class="headerlink" title="How it works"></a>How it works</h2><p>A small daemon, <code>rexboard serve</code>, starts on first run. On this host and every host in <code>rex hosts</code>, it runs an <code>observer.lua</code> script through <code>rex do</code>, which streams NDJSON back. Serve keeps state on disk, holds the harness adapters, runs extensions and answers the board and the CLI over a unix socket.</p><p>A few decisions shaped the rest. Each one has an ADR in <a target="_blank" rel="noopener" href="https://github.com/vanducng/rexboard/tree/main/docs/decisions">docs/decisions</a>:</p><ul><li><strong>Reach Rex only through the <code>rex</code> CLI.</strong> No private APIs.</li><li><strong>The agent tells Rex, rexboard shows it.</strong> No screen scraping and no transcript reading. Agents report state through hooks, and rexboard ships those hooks.</li><li><strong>The CLI is the API.</strong> Everything the board shows is also a command with <code>--json</code>, like <code>rexboard ls --json</code>.</li><li><strong>Extensions, not a built-in core.</strong> An extension is a process with JSON in and fields out. My OpenRig extension adds PROJECT and RIG columns and a <code>send</code> action this way.</li><li><strong>Acting on panes is guarded.</strong> rexboard writes only to a pane you picked: a jump, an answer, or a close.</li><li><strong>Seen means you acted.</strong> A done row stays in NEEDS YOU until you actually touch it.</li></ul><p>The scope ADR is just as useful for what it refuses: no Rex layout writes, no themes, no user-defined views, no extension registry, no Windows.</p><h2 id="How-I-built-it"><a href="#How-I-built-it" class="headerlink" title="How I built it"></a>How I built it</h2><p>I did not write most of this code by hand. The build ran as missions split into slices, one slice per PR, each with a spec, a progress log and a proof file. A dev agent implemented, a review agent and a PM agent scored, and I made the calls: which mockup, which scope, when to release. The v2 mission alone is past 75 slices.</p><p>Some of the work that took the most rounds was not UI at all. Making serve restart cleanly after a <code>brew upgrade</code> took four review rounds. A whole run of slices went to flaky tests under load. And the status coverage problem (21 of 37 rows had no status at one point) turned out to be seats relaunched with <code>--resume</code> that had no <code>TMUX</code> or <code>TMUX_PANE</code>, so the hook gate exited early.</p><h2 id="Where-it-stands"><a href="#Where-it-stands" class="headerlink" title="Where it stands"></a>Where it stands</h2><p>As of v0.20.0 (31 October 2026):</p><ul><li>Shipped: the list-first board with row numbers (<code>1</code>-<code>99</code> selects), live preview, card grid, answer mode, send from the board, extension actions, remote usage through Rex, Homebrew install and <code>rexboard upgrade</code>.</li><li>Running on my Mac, a second Mac and a Linux box.</li><li>Open draft PRs: an EFFORT column with <code>[models]</code> aliases (<a target="_blank" rel="noopener" href="https://github.com/vanducng/rexboard/pull/129">#129</a>), extension column widths that fit their values (<a target="_blank" rel="noopener" href="https://github.com/vanducng/rexboard/pull/128">#128</a>), and a batch of test flake fixes.</li><li>Deferred by me: a 1W weekly quota column, since my proxy setup does not expose it easily.</li></ul><h2 id="What-is-next"><a href="#What-is-next" class="headerlink" title="What is next"></a>What is next</h2><p>I looked at what the closest tools do. <a target="_blank" rel="noopener" href="https://github.com/nicknisi/fleet">Fleet</a> is the nearest match: a tmux dashboard grouped by urgency with a clickable status row. <a target="_blank" rel="noopener" href="https://github.com/miya-masa/cc-pane">cc-pane</a> sends OSC 9 alerts on approval prompts. <a target="_blank" rel="noopener" href="https://muxbell.com/">Muxbell</a> and <a target="_blank" rel="noopener" href="https://github.com/Lukeesec/mux-beacon">Mux Beacon</a> are macOS menu-bar inboxes. <a target="_blank" rel="noopener" href="https://github.com/asheshgoplani/agent-deck">Agent Deck</a> goes further into orchestration, cost dashboards and Telegram or Slack control.</p><p>None of them work across Rex hosts, which is the reason rexboard exists. But they point at gaps worth closing. In rough order:</p><ol><li><strong>A notification when a row enters NEEDS YOU.</strong> My scope ADR already lists this as deferred, not refused. OSC 9 like cc-pane is the smallest version.</li><li><strong>A summary strip.</strong> Fleet’s <code>N need you · N working</code> header. I want the count before I read rows.</li><li><strong>Clear all seen done rows at once.</strong> Fleet has a clear chip for this.</li><li><strong>Finish EFFORT and model aliases</strong>, already in a draft PR.</li><li><strong>State stats from <code>transitions.jsonl</code>.</strong> The data is already on disk. How long did each agent wait on me today is the number I actually care about.</li><li><strong>Turn durations.</strong> Mux Beacon treats one prompt as one turn with one alert and one duration, even when subagents wake it up. That would make QUIET and done rows easier to trust.</li><li><strong>NEEDS YOU off the laptop.</strong> Agent Deck does Telegram and Slack. For me this should be an extension, not core.</li></ol><p>I will write about each one as it lands. If you run a lot of agents in Rex, try it and tell me which row on that list you would want first.</p><h2 id="References"><a href="#References" class="headerlink" title="References"></a>References</h2><ul><li><a target="_blank" rel="noopener" href="https://github.com/vanducng/rexboard">rexboard on GitHub</a></li><li><a target="_blank" rel="noopener" href="https://github.com/vanducng/rexboard/tree/main/docs/decisions">rexboard decisions (ADRs)</a></li><li><a target="_blank" rel="noopener" href="https://www.superlogical.com/rex/docs">Rex docs</a></li><li><a target="_blank" rel="noopener" href="https://github.com/nicknisi/fleet">Fleet</a></li><li><a target="_blank" rel="noopener" href="https://github.com/asheshgoplani/agent-deck">Agent Deck</a></li><li><a target="_blank" rel="noopener" href="https://github.com/miya-masa/cc-pane">cc-pane</a></li><li><a target="_blank" rel="noopener" href="https://muxbell.com/">Muxbell</a></li><li><a target="_blank" rel="noopener" href="https://github.com/Lukeesec/mux-beacon">Mux Beacon</a></li></ul></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Sources&lt;/strong&gt;: the &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://github.com/vanducng/rexboard&quot;&gt;rexboard repo&lt;/a&gt; (README, docs, ADRs and the &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://github.com/vanducng/rexboard/blob/main/CHANGELOG.md&quot;&gt;CHANGELOG&lt;/a&gt; up to v0.20.0), my own mission notes for the build, and the tools I compared it with: &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://github.com/nicknisi/fleet&quot;&gt;Fleet&lt;/a&gt;, &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://github.com/asheshgoplani/agent-deck&quot;&gt;Agent Deck&lt;/a&gt;, &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://github.com/miya-masa/cc-pane&quot;&gt;cc-pane&lt;/a&gt;, &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://muxbell.com/&quot;&gt;Muxbell&lt;/a&gt; and &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://github.com/Lukeesec/mux-beacon&quot;&gt;Mux Beacon&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;On a normal day I have somewhere around 70 agent panes open across three machines. Most of them are fine. A few are stuck on a permission prompt, one has finished and is waiting for me, and one hit an error twenty minutes ago and I have no idea which. I kept losing time hunting for those panes, so I built a board that finds them for me.&lt;/p&gt;
&lt;p&gt;That board is &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://github.com/vanducng/rexboard&quot;&gt;rexboard&lt;/a&gt;. It went from v0.1.0 to v0.20.0 in about a week. This post covers what it is, why it works the way it does, where it stands, and what I want to add next.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="agentic-coding" scheme="https://vanducng.dev/tags/agentic-coding/"/>
    
    <category term="tui" scheme="https://vanducng.dev/tags/tui/"/>
    
    <category term="rexboard" scheme="https://vanducng.dev/tags/rexboard/"/>
    
    <category term="rust" scheme="https://vanducng.dev/tags/rust/"/>
    
    <category term="developer-tools" scheme="https://vanducng.dev/tags/developer-tools/"/>
    
  </entry>
  
  <entry>
    <title>Software Factories: What My X Feed Taught Me This Month</title>
    <link href="https://vanducng.dev/2026/10/22/software-factories-what-my-x-feed-taught-me/"/>
    <id>https://vanducng.dev/2026/10/22/software-factories-what-my-x-feed-taught-me/</id>
    <published>2026-10-22T18:00:00.000Z</published>
    <updated>2026-11-16T05:26:58.281Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><blockquote><p><strong>Sources</strong>: posts I reposted on X between September and October 2026: Josh Rosen’s <a target="_blank" rel="noopener" href="https://x.com/JoshARosen/status/2108616086140735976">Software Factories for Skeptics</a> (via <a target="_blank" rel="noopener" href="https://x.com/mstockton/status/2110209446970286488">Matt Stockton</a>), Josh Rosen’s <a target="_blank" rel="noopener" href="https://x.com/JoshARosen/status/2112902388302467493">The Software Factory Debate: Build, Buy, Fork or Delegate</a>, Lauren’s (<a target="_blank" rel="noopener" href="https://x.com/poteto">@poteto</a>) <a target="_blank" rel="noopener" href="https://x.com/poteto/status/2102050467505430555">2,500 PRs talk</a> and Matt Pocock’s <a target="_blank" rel="noopener" href="https://x.com/mattpocockuk/status/2103431302527508886">notes on it</a>, and <a target="_blank" rel="noopener" href="https://x.com/Tailscale/status/2113324012012970128">Tailscale on the Secure Software Factory</a>.</p></blockquote><p>“Software factory” kept showing up in my feed this month. My first reaction was the same as most people’s: that sounds like a lights-out shop where nobody reads the code. After reading the posts I reposted side by side, I think that framing is wrong, and the useful version is much smaller and much closer to what I already do.</p><p>This post pulls the threads together. In <a href="/2026/08/19/background-agents-what-13-companies-actually-run/">Background Agents: What 13 Companies Actually Run</a> I looked at the runtime. This one is about the system around it.</p><span id="more"></span><h2 id="Light-factory-not-dark-factory"><a href="#Light-factory-not-dark-factory" class="headerlink" title="Light factory, not dark factory"></a>Light factory, not dark factory</h2><p>Josh Rosen’s <a target="_blank" rel="noopener" href="https://x.com/JoshARosen/status/2108616086140735976">Software Factories for Skeptics</a> starts from Addy Osmani’s split:</p><table><thead><tr><th></th><th>Dark factory</th><th>Light factory</th></tr></thead><tbody><tr><td>Humans read code</td><td>Rarely</td><td>Yes</td></tr><tr><td>Humans plan, review, approve</td><td>Mostly no</td><td>Yes</td></tr><tr><td>What the factory is</td><td>The agents</td><td>The system around the work</td></tr><tr><td>Where we are today</td><td>Aggressive bet</td><td>Practical now</td></tr></tbody></table><p>His point: light factories are still factories. Factories always had people in them. The factory is the system that organizes production, and you already have some version of it. The level of automation can change without changing that system.</p><p><a target="_blank" rel="noopener" href="https://x.com/mstockton/status/2110209446970286488">Matt Stockton</a> summarized the piece in one line that stuck with me: it is about org-wide agent transparency and a learning, compounding loop, not tools.</p><h2 id="Coding-agents-already-run-tiny-factories-then-throw-them-away"><a href="#Coding-agents-already-run-tiny-factories-then-throw-them-away" class="headerlink" title="Coding agents already run tiny factories, then throw them away"></a>Coding agents already run tiny factories, then throw them away</h2><p>Give Claude Code or Codex a big enough task and it spawns subagents: one explores the repo, one researches a dependency, one reviews. That is a small factory with workers.</p><p>The catch, per Rosen: the plan and the recipe are ephemeral. We keep the code and drop the structure that produced it. Multiply that by 100 engineers, each with several loops running, and the org sees a ticket at the start and a PR at the end. Everything in between is invisible.</p><p>A factory is just putting a system around that work so the breakdown is reusable and visible:</p><pre class="mermaid">flowchart LR    T[Ticket / Slack / CI failure] --&gt; F[Factory loop]    F --&gt; W1[Worker: Claude Code]    F --&gt; W2[Worker: Codex]    F --&gt; W3[Human]    W1 --&gt; V[Verification]    W2 --&gt; V    W3 --&gt; V    V --&gt;|fail| F    V --&gt;|pass| PR[PR / Deploy]    V --&gt; D[(Run data)]    D --&gt; S[Strategy loop]    S --&gt;|propose changes| F    style F fill:#4A90E2,color:#fff    style V fill:#F39C12,color:#fff    style D fill:#27AE60,color:#fff    style S fill:#9B59B6,color:#fff</pre><p>Iteration does not go away. An agent opens a PR, a reviewer comments, someone adds context to the ticket, the agent picks it up again. Same loop as local steering, but in a shared system instead of trapped in one session.</p><h2 id="Software-factories-are-data-factories"><a href="#Software-factories-are-data-factories" class="headerlink" title="Software factories are data factories"></a>Software factories are data factories</h2><p>This was the part I underrated. Agents generate a lot of process data: which approach they took, what tests ran, when they asked for help, whether they understood the docs. Git, CI, and Jira hold some of it. Most of it is lost.</p><p>Across thousands of tasks, that data tells you which work needs humans, where agents get stuck, and which prompt, model, or verification setup actually wins. You need a system first, then data about how it runs, and only then can you improve it.</p><p>That leads to <strong>factory as code</strong>: prompts, verification requirements, model routing, tools, context, policies, and approval points in a versioned repo. An <code>AGENTS.md</code> is the seed of this, not the end state.</p><h2 id="Build-buy-fork-or-delegate"><a href="#Build-buy-fork-or-delegate" class="headerlink" title="Build, buy, fork, or delegate"></a>Build, buy, fork, or delegate</h2><p>The follow-up, <a target="_blank" rel="noopener" href="https://x.com/JoshARosen/status/2112902388302467493">The Software Factory Debate</a>, compares four ways to get one:</p><table><thead><tr><th>Option</th><th>What it means</th><th>Example</th><th>Improvement loop</th></tr></thead><tbody><tr><td>Build</td><td>Compose queues, sandboxes, workers yourself</td><td>Temporal + Modal/E2B + Claude Code/Codex</td><td>You build traces, evals, replay</td></tr><tr><td>Buy</td><td>Factory platform</td><td>Warp, Factory, Port</td><td>Built in (benchmarks, scorers)</td></tr><tr><td>Fork</td><td>Adapt an open-source factory</td><td>Open SWE</td><td>Comes with tracing (LangSmith)</td></tr><tr><td>Delegate</td><td>Give an always-on agent enough access</td><td>Grok Bot, OpenAI Dots</td><td>Weak today: hard to measure</td></tr></tbody></table><p>The line I liked most: Build, Buy, and Fork put agents inside a factory. Delegate puts the factory inside an agent.</p><p>Delegate is the simplest and the least engineerable. Evidence is spread across the bot, the coding worker, GitHub, CI, and the ticket. There is no single place to see what was supposed to happen, what did happen, and whether a change made it better. Rosen’s proposed fix is <strong>checkpoints</strong>: declare what the work must satisfy and what evidence proves it, and let the agent choose the path.</p><p>His realistic answer is a mix: fork a factory, buy sandboxes, build your own verification, and delegate the coordination you do not want to hard-code.</p><h2 id="Constraints-and-verification-are-the-factory-floor"><a href="#Constraints-and-verification-are-the-factory-floor" class="headerlink" title="Constraints and verification are the factory floor"></a>Constraints and verification are the factory floor</h2><p>Lauren’s talk on <a target="_blank" rel="noopener" href="https://x.com/poteto/status/2102050467505430555">shipping 2,500 PRs in a month</a> is the practitioner side. Matt Pocock’s <a target="_blank" rel="noopener" href="https://x.com/mattpocockuk/status/2103431302527508886">notes</a> pulled out three things:</p><ol><li><strong>Lock down your agents.</strong> Humans like sharp-knife abstractions. Agents do better in locked-down environments where abstractions cannot be misused and lint rules enforce it. Her team built an internal framework to keep agents on track.</li><li><strong>Build verification infrastructure.</strong> Either watch the agent or make it produce evidence. Custom CLIs that let the agent drive the app and measure it, and an app that is “factory ready” from day one: deployable somewhere the agent can poke at it.</li><li><strong>Feature maps.</strong> Her outer loop turns vague bug reports into fixes. A maintained map of every main feature, synced by automation, is the navigation layer that makes that fast on a large codebase.</li></ol><p>Her own <a target="_blank" rel="noopener" href="https://x.com/poteto/status/2106916667599278365">follow-up</a> is the best framing I have seen: before agent slop there was human slop. Big companies solved it with lint rules, better compilers, high-quality tests, and observability. Agents just make big-company problems everyone’s problems. None of it is novel. It is good engineering.</p><h2 id="Security-is-part-of-the-spec"><a href="#Security-is-part-of-the-spec" class="headerlink" title="Security is part of the spec"></a>Security is part of the spec</h2><p>The last piece is access. <a target="_blank" rel="noopener" href="https://x.com/Tailscale/status/2113324012012970128">Tailscale</a> put it bluntly: agents writing good code does not mean they need the keys to the entire network. They joined Agent Baseline with Docker, Keycard, Snyk, Socket, Tessl, and Tracebit on a “Secure Software Factory”. I have not dug into that spec yet, but the direction matches the “lock down your agents” lesson: scoped identity and network access per worker, not a shared god token.</p><h2 id="What-I-am-taking-away"><a href="#What-I-am-taking-away" class="headerlink" title="What I am taking away"></a>What I am taking away</h2><ul><li><strong>Start light.</strong> I do not need a dark factory. I need visibility into the agent work I already run.</li><li><strong>Keep the recipe, not just the code.</strong> If a decomposition worked, it belongs in version control next to the prompts and checks that made it work.</li><li><strong>Capture run data before optimizing.</strong> Without traces and outcomes, every prompt or model change is a vibe.</li><li><strong>Constraints over cleverness.</strong> Lint rules, typed boundaries, verification CLIs, and feature maps pay off for agents and humans alike.</li><li><strong>Delegate with checkpoints.</strong> An always-on bot is the fastest path, but only engineerable if I define what done looks like and what evidence proves it.</li></ul><p>For my own setup, the honest gap is the data loop. I run agents on a laptop and in the background, but I am not measuring which configurations work. That is the next thing to fix.</p><h2 id="References"><a href="#References" class="headerlink" title="References"></a>References</h2><ul><li>Josh Rosen - <a target="_blank" rel="noopener" href="https://x.com/JoshARosen/status/2108616086140735976">Software Factories for Skeptics</a> (my <a target="_blank" rel="noopener" href="https://x.com/vanducng/status/2110540180411081120">repost</a> via <a target="_blank" rel="noopener" href="https://x.com/mstockton/status/2110209446970286488">Matt Stockton</a>)</li><li>Josh Rosen - <a target="_blank" rel="noopener" href="https://x.com/JoshARosen/status/2112902388302467493">The Software Factory Debate: Build, Buy, Fork or Delegate</a> (my <a target="_blank" rel="noopener" href="https://x.com/vanducng/status/2113047817765761216">repost</a>)</li><li>Lauren (@poteto) - <a target="_blank" rel="noopener" href="https://x.com/poteto/status/2102050467505430555">How I shipped 2,500 PRs last month</a></li><li>Matt Pocock - <a target="_blank" rel="noopener" href="https://x.com/mattpocockuk/status/2103431302527508886">Notes on Lauren’s talk</a></li><li>Lauren (@poteto) - <a target="_blank" rel="noopener" href="https://x.com/poteto/status/2106916667599278365">Constraints are freeing for humans and agents</a></li><li>Tailscale - <a target="_blank" rel="noopener" href="https://x.com/Tailscale/status/2113324012012970128">Joining Agent Baseline on the Secure Software Factory</a></li><li>Dex Horthy / HumanLayer - <a target="_blank" rel="noopener" href="https://github.com/humanlayer/advanced-context-engineering-for-coding-agents/blob/main/wsff.md">Lights-out software factory write-up</a></li><li>Addy Osmani - <a target="_blank" rel="noopener" href="https://www.oreilly.com/radar/software-factories-light-and-dark/">Software factories, light and dark</a></li></ul></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Sources&lt;/strong&gt;: posts I reposted on X between September and October 2026: Josh Rosen’s &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://x.com/JoshARosen/status/2108616086140735976&quot;&gt;Software Factories for Skeptics&lt;/a&gt; (via &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://x.com/mstockton/status/2110209446970286488&quot;&gt;Matt Stockton&lt;/a&gt;), Josh Rosen’s &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://x.com/JoshARosen/status/2112902388302467493&quot;&gt;The Software Factory Debate: Build, Buy, Fork or Delegate&lt;/a&gt;, Lauren’s (&lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://x.com/poteto&quot;&gt;@poteto&lt;/a&gt;) &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://x.com/poteto/status/2102050467505430555&quot;&gt;2,500 PRs talk&lt;/a&gt; and Matt Pocock’s &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://x.com/mattpocockuk/status/2103431302527508886&quot;&gt;notes on it&lt;/a&gt;, and &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://x.com/Tailscale/status/2113324012012970128&quot;&gt;Tailscale on the Secure Software Factory&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;“Software factory” kept showing up in my feed this month. My first reaction was the same as most people’s: that sounds like a lights-out shop where nobody reads the code. After reading the posts I reposted side by side, I think that framing is wrong, and the useful version is much smaller and much closer to what I already do.&lt;/p&gt;
&lt;p&gt;This post pulls the threads together. In &lt;a href=&quot;/2026/08/19/background-agents-what-13-companies-actually-run/&quot;&gt;Background Agents: What 13 Companies Actually Run&lt;/a&gt; I looked at the runtime. This one is about the system around it.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="background-agents" scheme="https://vanducng.dev/tags/background-agents/"/>
    
    <category term="agentic-coding" scheme="https://vanducng.dev/tags/agentic-coding/"/>
    
    <category term="platform-engineering" scheme="https://vanducng.dev/tags/platform-engineering/"/>
    
    <category term="software-factory" scheme="https://vanducng.dev/tags/software-factory/"/>
    
  </entry>
  
  <entry>
    <title>Background Agents: What 13 Companies Actually Run</title>
    <link href="https://vanducng.dev/2026/08/19/background-agents-what-13-companies-actually-run/"/>
    <id>https://vanducng.dev/2026/08/19/background-agents-what-13-companies-actually-run/</id>
    <published>2026-08-19T01:50:00.000Z</published>
    <updated>2026-11-16T05:26:58.274Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><blockquote><p><strong>Sources</strong>: <a target="_blank" rel="noopener" href="https://background-agents.com/summit/">Background Agents Summit</a> session pages and the <a target="_blank" rel="noopener" href="https://www.youtube.com/playlist?list=PL3TSF5whlprXNdegxuGPSoa13wqx-dcAw">YouTube talks</a> (6-7 May 2026). Definition from <a target="_blank" rel="noopener" href="https://background-agents.com/">background-agents.com</a>. I used Ona’s <a target="_blank" rel="noopener" href="https://ona.com/stories/background-agents-summit">summit recap</a> and <a target="_blank" rel="noopener" href="https://background-agents.com/llms-full.txt">llms-full.txt</a> as indexes. Where a talk, a session page, and other Ona pages disagree, I leave the disagreement in.</p></blockquote><p>I have been treating coding agents as a laptop problem: more terminals, more worktrees, more parallel sessions. That is useful. It is also the wrong unit of scale.</p><p>The <a target="_blank" rel="noopener" href="https://background-agents.com/summit/">Background Agents Summit</a> put a sharper name on the next layer. Thirteen talks, recorded 6-7 May 2026, from Stripe, Uber, Cloudflare, Harvey, Open Inspect, Genentech, incident.io, Monzo, AWS, Tessl, Ona, Nono, and software-factory.dev. The claim is not that agents write more code. The claim is that org cycle time stays flat until the work leaves the laptop.</p><p>I am reading this as a field review. The useful part is how independently these teams landed on the same runtime.</p><span id="more"></span><h2 id="What-a-background-agent-is"><a href="#What-a-background-agent-is" class="headerlink" title="What a background agent is"></a>What a background agent is</h2><p><a target="_blank" rel="noopener" href="https://background-agents.com/">background-agents.com</a> draws a hard line.</p><p>A background agent is an AI coding agent that runs autonomously on cloud infrastructure, triggered by events, schedules, or system signals, in its own full toolchain environment, decoupled from the developer’s laptop and session. The developer is <strong>on the loop</strong> (review later), not <strong>in the loop</strong> (steer live).</p><p>“Agents running in the background on a laptop” are not background agents. Extra terminals are still localhost. That is the same distinction I keep coming back to in <a href="/2025/10/15/From-Chatbots-to-Agents-Understanding-Intelligent-AI-Systems/">From Chatbots to Agents</a>: autonomy is not a longer reply. It is a loop that can proceed without you sitting in it.</p><h2 id="The-false-summit"><a href="#The-false-summit" class="headerlink" title="The false summit"></a>The false summit</h2><p>Coding assistants make individuals faster. Org cycle time and DORA stay flat.</p><p>That is the false summit the site names. PRs flood in. Review queues grow. The same security patch still has to land across the repos nobody wants to touch. Individual speed compounds with the person. Organizational velocity does not, until the work is triggered, isolated, governed, and reviewed as a system.</p><p>I have seen this locally: a strong laptop agent makes <em>me</em> faster. It does not shrink the toil that lives in Slack, CI, and migrations.</p><h2 id="Coding-agent-vs-background-agent-vs-CI"><a href="#Coding-agent-vs-background-agent-vs-CI" class="headerlink" title="Coding agent vs background agent vs CI"></a>Coding agent vs background agent vs CI</h2><p>Three different machines, three different jobs.</p><table><thead><tr><th></th><th>Coding agent</th><th>Background agent</th><th>CI</th></tr></thead><tbody><tr><td>Where</td><td>Laptop</td><td>Cloud</td><td>Pipeline runners</td></tr><tr><td>Trigger</td><td>Manual prompt</td><td>Event, Slack, ticket, schedule</td><td>Predefined pipeline event</td></tr><tr><td>Scope</td><td>One repo, one session</td><td>Across the SDLC</td><td>The steps you already wrote</td></tr><tr><td>Human</td><td>In the loop: watch, steer</td><td>On the loop: review later</td><td>Out of the reasoning path</td></tr><tr><td>Reasoning</td><td>Yes</td><td>Yes</td><td>No</td></tr><tr><td>New code</td><td>Yes, under your hands</td><td>Yes, as a reviewable artifact</td><td>No</td></tr></tbody></table><p>CI tells you a dependency is stale or a test failed. It does not decide what to change. A background agent can reason, write the fix, run checks, and open a PR. That is closer to the loop in <a href="/2025/10/30/Anatomy-of-an-AI-Agent-Building-Blocks-and-Workflows/">Anatomy of an AI Agent</a> than it is to a build script.</p><pre class="mermaid">flowchart TB  subgraph Cloud["Background agent"]    direction LR    T1[Event / Slack / ticket] --&gt; S1[Cloud sandbox] --&gt; O1[PR or report]  end  subgraph Local["Coding agent"]    direction LR    T2[Manual prompt] --&gt; S2[Laptop] --&gt; O2[Local diff]  end  classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff  classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff  classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff  classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff  classDef tealClass fill:#16A085,stroke:#333,stroke-width:2px,color:#fff  classDef redClass fill:#E74C3C,stroke:#333,stroke-width:2px,color:#fff  class T1 blueClass  class S1 orangeClass  class O1 greenClass  class T2 purpleClass  class S2 tealClass  class O2 redClass</pre><h2 id="Five-primitives-independently-arrived-at"><a href="#Five-primitives-independently-arrived-at" class="headerlink" title="Five primitives, independently arrived at"></a>Five primitives, independently arrived at</h2><p>Stripe, Uber, Harvey, Cloudflare, and Open Inspect did not coordinate. The site says they still converged on the same five primitives.</p><pre class="mermaid">flowchart LR  P1[Sandboxed execution] --&gt; P2[Runtime governance]  P2 --&gt; P3[Context behind the firewall]  P3 --&gt; P4[Triggers]  P4 --&gt; P5[Fleet coordination]  classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff  classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff  classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff  classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff  classDef tealClass fill:#16A085,stroke:#333,stroke-width:2px,color:#fff  class P1 blueClass  class P2 orangeClass  class P3 greenClass  class P4 purpleClass  class P5 tealClass</pre><ol><li><strong>Sandboxed execution.</strong> Each run gets its own full toolchain: isolate, reproduce, tear down. Without this, agents share machine state and security teams veto the rest.</li><li><strong>Governance enforced at runtime, not by prompt.</strong> Deny lists, scoped credentials, audit trails, human review gates. A system prompt that says “please don’t delete files” is a suggestion.</li><li><strong>Context and connectivity behind the firewall.</strong> IAM roles, private registries, internal APIs, replicas. A sandbox that cannot reach the real system produces code that compiles and does not integrate.</li><li><strong>Triggers.</strong> Scheduled, event-driven, fleets (one task across many repos), swarms (many agents, one outcome). If every run starts with a typed prompt, you automated the work and not the workflow.</li><li><strong>Fleet coordination.</strong> One intent, many repos, progress tracked and results aggregated. Updating one repository is a coding-agent task. Updating hundreds is a fleet task.</li></ol><p>The order matters. Sandbox without governance is a liability. Governance without internal context is a toy. Triggers without fleet coordination still leave the 500-repo change as a multi-week project.</p><h2 id="What-13-companies-actually-ran"><a href="#What-13-companies-actually-ran" class="headerlink" title="What 13 companies actually ran"></a>What 13 companies actually ran</h2><p>Each section links the <a target="_blank" rel="noopener" href="https://www.youtube.com/playlist?list=PL3TSF5whlprXNdegxuGPSoa13wqx-dcAw">Watch</a> recording and the session page. I am not collapsing conflicting figures.</p><h3 id="Stripe-Minions"><a href="#Stripe-Minions" class="headerlink" title="Stripe: Minions"></a>Stripe: Minions</h3><p><a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=W42t-CoXyuE">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/alistair-gray/">session</a></p><p>Slack, Jira, or the web allocates a dev box. Blueprints handle the deterministic steps: lint, generated code, tests. The agent opens a PR. Humans still review. The line that stuck: “dev boxes were a strategy credit.” Stripe built reproducible environments for humans first. Agents inherited them.</p><p>The published numbers do not agree, so I am not picking one. The <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/alistair-gray/">session page</a> says a 30-million-line Ruby codebase. In the <a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=W42t-CoXyuE">talk</a>, Gray says thousands of PRs a week with zero human-written code, and a codebase of “hundreds of millions of lines.” Other Ona pages, including the <a target="_blank" rel="noopener" href="https://background-agents.com/white-paper/">February 2026 white paper</a>, say 1,000+ or 1,300+ PRs a week and 100M+ lines.</p><h3 id="Uber-start-with-toil"><a href="#Uber-start-with-toil" class="headerlink" title="Uber: start with toil"></a>Uber: start with toil</h3><p><a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=o7G5EHDqQ1g">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/nikhil-ramakrishnan/">session</a></p><p>Minion (singular; Stripe’s is Minions). The path was DevPod, then Minion. Shepard handles migrations. Code Inbox routes review.</p><p>The <a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=o7G5EHDqQ1g">talk</a> says over 11% of all merge PRs across Uber. The <a target="_blank" rel="noopener" href="https://ona.com/stories/background-agents-summit">Ona recap</a> sometimes says “generated PRs.” Those are not the same denominator. I am keeping the talk wording.</p><p>The correction I needed: start with toil, not novelty. Validation-heavy fixes and cleanup before the impressive generation demo.</p><h3 id="Cloudflare-93-is-the-stack-not-the-factory"><a href="#Cloudflare-93-is-the-stack-not-the-factory" class="headerlink" title="Cloudflare: 93% is the stack, not the factory"></a>Cloudflare: 93% is the stack, not the factory</h3><p><a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=MbLdrAZFQRs">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/rajesh-bhatia/">session</a></p><p>AI Gateway, Access, Backstage, Agents.md, MCP, one-command setup. A multi-agent reviewer is tied to machine-readable standards.</p><p>93% of R&amp;D is on that AI engineering stack: about 4,000 people, 295 teams, 4,000+ Backstage repos. The <a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=MbLdrAZFQRs">talk</a> treats full background / delegated cloud agents as the next phase, not the current bulk of that 93%. The measurement note I am keeping: feature velocity, not just PR count.</p><h3 id="Harvey-Slack-as-the-workspace"><a href="#Harvey-Slack-as-the-workspace" class="headerlink" title="Harvey: Slack as the workspace"></a>Harvey: Slack as the workspace</h3><p><a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=2pod6GeckXc">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/joey-wang/">session</a></p><p>Spectre, a collaborative cloud agent. The Slack thread is the shared workspace for engineering, PM, research, and legal. A GitHub repo is treated as a legal matter. Scheduled agents cover dashboards and triage.</p><p>The bottleneck they name is alignment, not code generation: permissions, context, and follow-through that a laptop tab cannot carry.</p><h3 id="Open-Inspect-review-becomes-the-constraint"><a href="#Open-Inspect-review-becomes-the-constraint" class="headerlink" title="Open Inspect: review becomes the constraint"></a>Open Inspect: review becomes the constraint</h3><p><a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=-T_Qc1Vmbtk">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/cole-murray/">session</a></p><p>Internal platform: Cloudflare as the control plane, Modal and Daytona sandboxes, OpenCode as the agent. First use cases: SRE triage, support, PM prototypes, self-serve analytics. Modeled after Ramp. Boots typically under 2 seconds, with a goal under 10 seconds. Images rebuilt about every 30 minutes.</p><p>The scaling note is blunt. Once the laptop is no longer the boundary, review capacity becomes the bottleneck.</p><h3 id="Genentech-genomics-then-the-Specificity-Paradox"><a href="#Genentech-genomics-then-the-Specificity-Paradox" class="headerlink" title="Genentech: genomics, then the Specificity Paradox"></a>Genentech: genomics, then the Specificity Paradox</h3><p><a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=GXDtw0EmoX0">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/xiucheng-quek/">session</a></p><p>A team of 4. Failed analyses fan out across hundreds or thousands of instances. Agents produce incident reports, daily summaries, and routine tickets, with controlled merges. Nightly self-evolution pulls from logs, Slack, and Confluence. One sprint: 189 tickets, about 122 by the bot. Triage that took hours or days dropped to minutes.</p><p>The Specificity Paradox: highly specific skills can make agents slower. A rigid debug skill took 2× longer.</p><h3 id="incident-io-design-the-handoff-surface"><a href="#incident-io-design-the-handoff-surface" class="headerlink" title="incident.io: design the handoff surface"></a>incident.io: design the handoff surface</h3><p><a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=uG0Jz6kLWV0">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/lawrence-jones/">session</a></p><p>AI SRE. Slack-native investigation: pinned summaries, canvases, threaded progress with citations. MCP and Investigation Sync move context into the IDE and into local coding agents. Netflix, Etsy, and Skyscanner are named as customers. Hundreds of telemetry queries per investigation. A heads-up only if the agent knows something humans do not, and it is relevant, confident, and citable.</p><p>The product lesson is the handoff surface. A background agent that dumps a wall of text into a channel is not collaboration. The work has to be skim-able in Slack and usable where the engineer already works.</p><h3 id="Monzo-constraints-help-agents"><a href="#Monzo-constraints-help-agents" class="headerlink" title="Monzo: constraints help agents"></a>Monzo: constraints help agents</h3><p><a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=ptVO89qaxY4">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/suhail-patel/">session</a></p><p>A regulated bank: 3,000+ microservices in a Go monorepo. Golden paths, static analysis, data-flow controls. Sandbox untrusted work. Govern MCP. Own the model interface instead of coupling to one vendor shell.</p><p>The surprise is directional. Regulation and opinionated platform defaults are usually framed as friction. Here they are the reason agents can be let in: the secure path is already the easy path.</p><h3 id="AWS-dark-factories"><a href="#AWS-dark-factories" class="headerlink" title="AWS: dark factories"></a>AWS: dark factories</h3><p><a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=e7AvdrxsbaU">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/shardul-vaidya/">session</a></p><p>Requirement to orchestrator DAG to isolated sandboxes. Plan and code adversaries apply back pressure. Deterministic gates decide whether work moves. Failed work is fed forward as rework, not retry. He ran a live factory demo.</p><p>I am treating “dark factory” as an operating model, not a slogan: humans move to requirements, tool curation, and verification. The loop still needs proof.</p><h3 id="Tessl-Context-Development-Lifecycle"><a href="#Tessl-Context-Development-Lifecycle" class="headerlink" title="Tessl: Context Development Lifecycle"></a>Tessl: Context Development Lifecycle</h3><p><a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=Pz-vVV0Jmfc">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/patrick-debois/">session</a></p><p>Context now needs the same discipline as code: generate, evaluate with LLM-as-judge, distribute via registries, observe, manage drift.</p><p>This matches how I already think about repo instructions and evals. If the agent is steered by skills, specs, and <code>AGENTS.md</code>, those files are production artifacts. Drift is technical debt.</p><h3 id="Ona-enforce-below-the-agent"><a href="#Ona-enforce-below-the-agent" class="headerlink" title="Ona: enforce below the agent"></a>Ona: enforce below the agent</h3><p><a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=XKFKwyFhk8A">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/data-wall-for-agents/">session</a></p><p>Leo Di Donato and Lorenzo Fontana: prompt-level guardrails fail. Agents reason around rules written at their own level. Enforce below the agent.</p><p>That is the same conclusion I landed on in <a href="/2026/08/15/bounded-autonomy-and-guardrails-for-claude-code/">bounded autonomy for Claude Code</a>: a hook or a kernel policy holds when a classifier or a system prompt will not.</p><h3 id="Nono-Enforce-Attest-Decide"><a href="#Nono-Enforce-Attest-Decide" class="headerlink" title="Nono: Enforce, Attest, Decide"></a>Nono: Enforce, Attest, Decide</h3><p><a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=pg0t9jf5DY4">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/stephen-parkinson/">session</a></p><p>Three layers. <strong>Enforce</strong> at the kernel. <strong>Attest</strong> steering files and policies with Sigstore. <strong>Decide</strong> / grant capability expansion over Slack. Merkle audit log.</p><p>Sandboxing is not a boolean. Useful agents request more access. The reviewable path for that request <em>is</em> the product.</p><h3 id="software-factory-dev-the-factory-in-public"><a href="#software-factory-dev-the-factory-in-public" class="headerlink" title="software-factory.dev: the factory in public"></a>software-factory.dev: the factory in public</h3><p><a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=a4pEznCiWNo">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/zacharias-malguitou/">session</a></p><p>Building a software factory in public. Most of the other talks describe internal platforms. This one is an inspectable loop: agents across planning, implementation, review, and operations, with the human on spec and taste.</p><p>First 10 days of Memo: 375+ merged PRs, about 68k LOC, 16 automations, median issue-to-close 38 minutes, 87% of PRs merged autonomously, 98% of executions factory-triggered.</p><h2 id="Peer-numbers-outside-the-playlist"><a href="#Peer-numbers-outside-the-playlist" class="headerlink" title="Peer numbers outside the playlist"></a>Peer numbers outside the playlist</h2><p>These are not summit talks. The site cites them as peer deployments. I am repeating only the published figures, with their sources.</p><table><thead><tr><th>Company</th><th>System</th><th>Published figure</th><th>Source</th></tr></thead><tbody><tr><td>DoorDash</td><td>Flux</td><td>130,000 automated engineering tasks in one month; 25,000+ code reviews a week</td><td><a target="_blank" rel="noopener" href="https://x.com/AIatDoorDash/status/2087285008906240193">DoorDash AI on X</a></td></tr><tr><td>Spotify</td><td>Background coding agent</td><td>1,500+ agent PRs</td><td><a target="_blank" rel="noopener" href="https://engineering.atspotify.com/2025/11/spotifys-background-coding-agent-part-1">Spotify Engineering</a></td></tr><tr><td>Abnormal</td><td>Nora</td><td>200+ PRs a day</td><td><a target="_blank" rel="noopener" href="https://builders.abnormal.ai/p/nora-our-first-agent-employee">Abnormal Builders</a></td></tr></tbody></table><p>I am not treating these as comparable benchmarks. Different units: tasks, PRs, reviews, days versus months. Useful as existence proofs that the laptop is already the wrong runtime for some orgs.</p><h2 id="Trigger-to-output"><a href="#Trigger-to-output" class="headerlink" title="Trigger to output"></a>Trigger to output</h2><table><thead><tr><th>Trigger</th><th>Company</th><th>Output</th></tr></thead><tbody><tr><td>Slack, Jira, or web task</td><td>Stripe</td><td>Dev box run, blueprints, human-reviewed PR</td></tr><tr><td>Toil and migrations</td><td>Uber</td><td>Minion PRs; Shepard migrations; Code Inbox routing</td></tr><tr><td>One-command platform defaults</td><td>Cloudflare</td><td>AI stack adoption; multi-agent review against machine-readable standards; delegated cloud agents as the next phase</td></tr><tr><td>Slack thread as shared session</td><td>Harvey</td><td>Spectre run across eng, PM, research, legal; scheduled dashboards and triage</td></tr><tr><td>SRE, support, PM prototype, analytics</td><td>Open Inspect</td><td>Internal platform work; sub-2s typical boot; review as the next bottleneck</td></tr><tr><td>Failed genomics analyses, tickets, logs</td><td>Genentech</td><td>Triage, incident reports, daily summaries, controlled merges</td></tr><tr><td>Slack incident</td><td>incident.io</td><td>Cited investigation, canvases, IDE / local-agent handoff; heads-up only if new, relevant, confident, citable</td></tr><tr><td>Untrusted or regulated work</td><td>Monzo</td><td>Sandboxed run, governed MCP, owned model interface</td></tr><tr><td>Requirement</td><td>AWS</td><td>Orchestrator DAG, isolated sandboxes, adversarial review, deterministic gates</td></tr><tr><td>Context change or drift</td><td>Tessl</td><td>Generated, judged, registered, observed context</td></tr><tr><td>Agent trying to bypass a written rule</td><td>Ona</td><td>Enforcement below the prompt</td></tr><tr><td>Headless capability request</td><td>Nono</td><td>Kernel enforce, Sigstore attest, Slack decide/grant</td></tr><tr><td>Public factory loop</td><td>software-factory.dev</td><td>Inspectable SDLC run in the open</td></tr></tbody></table><h2 id="What-I-am-taking-from-this"><a href="#What-I-am-taking-from-this" class="headerlink" title="What I am taking from this"></a>What I am taking from this</h2><p>The category is real enough that thirteen teams, under different constraints, described the same runtime. I am not taking the marketing destination (“self-driving codebase”) as a plan. I am taking the primitives.</p><p>Dev boxes before agents. Stripe said it out loud. Uber’s DevPod-to-Minion path is the same idea. If I do not have a reproducible environment, I do not have a background agent. I have a prompt with extra steps.</p><p>Start with toil. Uber, Open Inspect, and Genentech all picked work that already had a definition of done: triage, migrations, routine tickets, failed jobs. Novelty is a poor first customer.</p><p>Review is the scarce resource. Open Inspect said it. Stripe still has humans reviewing agent PRs. Cloudflare measures feature velocity because PR count will lie, and its 93% is stack adoption, not a finished delegated factory. If I automate authoring and leave review unchanged, I have built the false summit again.</p><p>Governance sits under the model. Ona, Nono, and Monzo agree from three directions: prompt rules fail, the kernel and attestation layer hold, and a regulated platform’s defaults are an accelerant. That is also why MCP has to be governed, not just connected.</p><p>Context is now an artifact. Tessl’s lifecycle is the formal version of what laptop agents already depend on. I will version, evaluate, and watch drift on the files that steer agents the same way I do for code.</p><p>The handoff surface is product work. Harvey and incident.io are not “put the agent in Slack.” They are designing a shared object that other humans, and other agents, can pick up later.</p><p>I am still running coding agents on a laptop. That is fine for work I want to steer. The question this summit leaves me with is narrower: which of my triggers already have a sandbox, a review gate, and a definition of done, and which ones I am still pretending are a longer chat.</p><h2 id="References"><a href="#References" class="headerlink" title="References"></a>References</h2><ul><li><a target="_blank" rel="noopener" href="https://background-agents.com/summit/">Background Agents Summit</a></li><li><a target="_blank" rel="noopener" href="https://www.youtube.com/playlist?list=PL3TSF5whlprXNdegxuGPSoa13wqx-dcAw">YouTube playlist</a></li><li><a target="_blank" rel="noopener" href="https://background-agents.com/">background-agents.com definition and primitives</a></li><li><a target="_blank" rel="noopener" href="https://background-agents.com/llms-full.txt">llms-full.txt</a></li><li><a target="_blank" rel="noopener" href="https://ona.com/stories/background-agents-summit">Ona summit recap</a></li><li><a target="_blank" rel="noopener" href="https://background-agents.com/white-paper/">February 2026 white paper</a></li><li>Stripe: <a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=W42t-CoXyuE">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/alistair-gray/">session</a></li><li>Uber: <a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=o7G5EHDqQ1g">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/nikhil-ramakrishnan/">session</a></li><li>Cloudflare: <a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=MbLdrAZFQRs">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/rajesh-bhatia/">session</a></li><li>Harvey: <a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=2pod6GeckXc">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/joey-wang/">session</a></li><li>Open Inspect: <a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=-T_Qc1Vmbtk">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/cole-murray/">session</a></li><li>Genentech: <a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=GXDtw0EmoX0">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/xiucheng-quek/">session</a></li><li>incident.io: <a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=uG0Jz6kLWV0">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/lawrence-jones/">session</a></li><li>Monzo: <a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=ptVO89qaxY4">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/suhail-patel/">session</a></li><li>AWS: <a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=e7AvdrxsbaU">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/shardul-vaidya/">session</a></li><li>Tessl: <a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=Pz-vVV0Jmfc">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/patrick-debois/">session</a></li><li>Ona: <a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=XKFKwyFhk8A">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/data-wall-for-agents/">session</a></li><li>Nono: <a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=pg0t9jf5DY4">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/stephen-parkinson/">session</a></li><li>software-factory.dev: <a target="_blank" rel="noopener" href="https://www.youtube.com/watch?v=a4pEznCiWNo">Watch</a> · <a target="_blank" rel="noopener" href="https://background-agents.com/summit/sessions/zacharias-malguitou/">session</a></li><li><a target="_blank" rel="noopener" href="https://x.com/AIatDoorDash/status/2087285008906240193">DoorDash Flux</a></li><li><a target="_blank" rel="noopener" href="https://engineering.atspotify.com/2025/11/spotifys-background-coding-agent-part-1">Spotify background coding agent</a></li><li><a target="_blank" rel="noopener" href="https://builders.abnormal.ai/p/nora-our-first-agent-employee">Abnormal Nora</a></li></ul></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Sources&lt;/strong&gt;: &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://background-agents.com/summit/&quot;&gt;Background Agents Summit&lt;/a&gt; session pages and the &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://www.youtube.com/playlist?list=PL3TSF5whlprXNdegxuGPSoa13wqx-dcAw&quot;&gt;YouTube talks&lt;/a&gt; (6-7 May 2026). Definition from &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://background-agents.com/&quot;&gt;background-agents.com&lt;/a&gt;. I used Ona’s &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://ona.com/stories/background-agents-summit&quot;&gt;summit recap&lt;/a&gt; and &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://background-agents.com/llms-full.txt&quot;&gt;llms-full.txt&lt;/a&gt; as indexes. Where a talk, a session page, and other Ona pages disagree, I leave the disagreement in.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;I have been treating coding agents as a laptop problem: more terminals, more worktrees, more parallel sessions. That is useful. It is also the wrong unit of scale.&lt;/p&gt;
&lt;p&gt;The &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://background-agents.com/summit/&quot;&gt;Background Agents Summit&lt;/a&gt; put a sharper name on the next layer. Thirteen talks, recorded 6-7 May 2026, from Stripe, Uber, Cloudflare, Harvey, Open Inspect, Genentech, incident.io, Monzo, AWS, Tessl, Ona, Nono, and software-factory.dev. The claim is not that agents write more code. The claim is that org cycle time stays flat until the work leaves the laptop.&lt;/p&gt;
&lt;p&gt;I am reading this as a field review. The useful part is how independently these teams landed on the same runtime.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="background-agents" scheme="https://vanducng.dev/tags/background-agents/"/>
    
    <category term="agentic-coding" scheme="https://vanducng.dev/tags/agentic-coding/"/>
    
    <category term="platform-engineering" scheme="https://vanducng.dev/tags/platform-engineering/"/>
    
  </entry>
  
  <entry>
    <title>Pi Coding Agent Field Guide</title>
    <link href="https://vanducng.dev/2026/08/16/pi-coding-agent-field-guide/"/>
    <id>https://vanducng.dev/2026/08/16/pi-coding-agent-field-guide/</id>
    <published>2026-08-16T14:00:00.000Z</published>
    <updated>2026-11-16T05:26:58.281Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><p>Pi is a terminal coding agent that starts almost empty and grows through packages, skills, hooks, and project files. That is the opposite of many agents that ship fully loaded.</p><p>This post is a compact field guide: install and auth, security, sessions (<code>/tree</code>, clone, fork, compaction), packages, <code>AGENTS.md</code>, skills, prompt templates, extensions, and daily TUI habits. Prefer the <a target="_blank" rel="noopener" href="https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent">official docs</a> and <a target="_blank" rel="noopener" href="https://pi.dev/">pi.dev</a> when flags drift.</p><span id="more"></span><h2 id="What-Pi-is"><a href="#What-Pi-is" class="headerlink" title="What Pi is"></a>What Pi is</h2><p>Minimal, highly extensible <strong>terminal coding agent</strong> (TUI). Built-in surface is small<br>(read/write/edit/bash + a few helpers). Power comes from:</p><p>packages · skills · prompt templates (slash commands) · extensions/hooks · AGENTS.md</p><p>Philosophy: start lean, then shape the agent to your workflow - not the reverse.</p><hr><h2 id="1-Install-auth-model"><a href="#1-Install-auth-model" class="headerlink" title="1. Install, auth, model"></a>1. Install, auth, model</h2><figure class="highlight bash hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-comment"># npm (common)</span></span><br><span class="line">npm install -g @mariozechner/pi-coding-agent</span><br><span class="line"></span><br><span class="line"><span class="hljs-comment"># or package managers / binaries from pi.dev or GitHub releases</span></span><br><span class="line">pi</span><br></pre></td></tr></tbody></table></figure><p>First run often: <strong>no models</strong> until auth.</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">/login          # OAuth (subscription providers) or API-key path</span><br><span class="line">/logout</span><br><span class="line">/model          # switch mid-session (Ctrl+L / Ctrl+P cycle)</span><br></pre></td></tr></tbody></table></figure><p>Auth file (preferred): <code>~/.pi/agent/auth.json</code><br>Env vars also work (<code>ANTHROPIC_API_KEY</code>, <code>OPENAI_API_KEY</code>, <code>GEMINI_API_KEY</code>, …).<br>Auth file wins over env.</p><p><strong>Caution:</strong> some “subscription” logins still bill <strong>extra API usage</strong>,<br>not the same included pool as the vendor’s own IDE agent. Prefer intentional auth.</p><p>Custom models (Ollama/vLLM/proxies): <code>~/.pi/agent/models.json</code><br>(live-reloads when opening <code>/model</code>).</p><hr><h2 id="2-Settings-two-layers"><a href="#2-Settings-two-layers" class="headerlink" title="2. Settings (two layers)"></a>2. Settings (two layers)</h2><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">/settings                 # TUI toggles (subset)</span><br><span class="line">~/.pi/agent/settings.json # global full config</span><br><span class="line">./.pi/settings.json       # project overrides (merge)</span><br></pre></td></tr></tbody></table></figure><p>Common toggles / fields:</p><table><thead><tr><th>Area</th><th>Examples</th></tr></thead><tbody><tr><td>Compaction</td><td><code>compaction.enabled</code>, <code>reserveTokens</code>, <code>keepRecentTokens</code></td></tr><tr><td>Thinking</td><td><code>defaultThinkingLevel</code>, hide thinking (Ctrl+T)</td></tr><tr><td>Queue</td><td><code>queueMode</code>: <code>one-at-a-time</code> | <code>all</code></td></tr><tr><td>Steering</td><td>how follow-ups inject while agent runs</td></tr><tr><td>Models</td><td><code>defaultProvider</code>, <code>defaultModel</code>, <code>enabledModels</code></td></tr><tr><td>Skills</td><td><code>skills.enabled</code></td></tr><tr><td>Packages</td><td><code>packages: ["npm:…", "git:…"]</code></td></tr><tr><td>Theme</td><td><code>theme</code>, custom <code>~/.pi/agent/themes/*.json</code></td></tr><tr><td>Terminal</td><td><code>terminal.showImages</code></td></tr></tbody></table><p>Advanced: edit settings JSON directly for options not in <code>/settings</code>.</p><hr><h2 id="3-Security-model-critical"><a href="#3-Security-model-critical" class="headerlink" title="3. Security model (critical)"></a>3. Security model (critical)</h2><p>Unlike some agents, <strong>Pi is broad by default</strong> once a project is trusted.</p><p>On start: <strong>trust prompt</strong><br>→ trust project / parent folder / session-only / deny.</p><p>Trusted project ⇒ agent can read/write/exec with full tools.<br>If you need isolation: <strong>Docker sandbox</strong> (or similar) is the recommended hard boundary.</p><p>Typical hard isolation: Dockerfile + run Pi inside container so host FS is not exposed.</p><p>Complementary soft boundaries:</p><ul><li>packages that add <strong>guardrails</strong> (command/path policy)</li><li>custom <strong>hooks</strong> that block <code>sudo</code>, <code>rm -rf</code>, writes to <code>.env</code>, etc.</li><li><code>--tools</code> to start with a reduced tool list</li></ul><hr><h2 id="4-CLI-startup-flags-worth-memorizing"><a href="#4-CLI-startup-flags-worth-memorizing" class="headerlink" title="4. CLI startup flags worth memorizing"></a>4. CLI startup flags worth memorizing</h2><figure class="highlight bash hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br></pre></td><td class="code"><pre><span class="line">pi                         <span class="hljs-comment"># interactive session (saves JSONL)</span></span><br><span class="line">pi -c / --<span class="hljs-built_in">continue</span>         <span class="hljs-comment"># latest session for cwd</span></span><br><span class="line">pi -r / --resume           <span class="hljs-comment"># picker</span></span><br><span class="line">pi --no-session            <span class="hljs-comment"># ephemeral (no resume pollution)</span></span><br><span class="line">pi --session path.jsonl    <span class="hljs-comment"># explicit file</span></span><br><span class="line">pi <span class="hljs-string">"initial prompt here"</span>   <span class="hljs-comment"># start + auto-send first message</span></span><br><span class="line">pi --<span class="hljs-built_in">print</span> <span class="hljs-string">"prompt"</span>        <span class="hljs-comment"># non-interactive / print mode (scripts, CI)</span></span><br><span class="line">pi --tools find,<span class="hljs-built_in">read</span>,<span class="hljs-built_in">ls</span>,grep   <span class="hljs-comment"># restrict built-ins (names as exposed)</span></span><br><span class="line">pi --no-skills</span><br><span class="line">pi --provider … --model …</span><br></pre></td></tr></tbody></table></figure><p>Resume picker tips:</p><ul><li><strong>Tab</strong> changes scope (cwd only → broader)</li><li>search/filter shortcuts in the picker UI</li><li>sessions are <strong>per working directory</strong> by default</li></ul><hr><h2 id="5-Sessions-core-mental-model"><a href="#5-Sessions-core-mental-model" class="headerlink" title="5. Sessions (core mental model)"></a>5. Sessions (core mental model)</h2><p>Everything happens in a <strong>session</strong>.</p><table><thead><tr><th>Action</th><th>Effect</th></tr></thead><tbody><tr><td><code>pi</code> / <code>/new</code></td><td>Fresh context</td></tr><tr><td>Auto-save</td><td><code>~/.pi/agent/sessions/--&lt;cwd-path&gt;--/&lt;ts&gt;_&lt;uuid&gt;.jsonl</code></td></tr><tr><td>Format</td><td>JSONL tree: each entry has <code>id</code> + <code>parentId</code></td></tr><tr><td>Continue</td><td>same branch grows</td></tr><tr><td>Clone</td><td>copy session at <strong>current tip</strong> → new file</td></tr><tr><td>Fork</td><td>copy from <strong>earlier message</strong> → new file</td></tr><tr><td><code>/tree</code></td><td>navigate <strong>in-place</strong> tree, no new file</td></tr><tr><td><code>/branch</code></td><td>branch into new session file via message picker</td></tr><tr><td>Compaction</td><td>summarize older turns to free context</td></tr></tbody></table><p>Tree view (<code>/tree</code>) is the power tool:</p><ul><li>search, page, filter modes (default / no-tools / user-only / labeled)</li><li>label bookmarks</li><li>jump back and grow a side branch without losing history</li><li>optional summary of abandoned branch when switching</li></ul><p>Compaction:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">/compact</span><br><span class="line">/compact Focus on the API surface and open bugs</span><br></pre></td></tr></tbody></table></figure><p>Auto-compaction (if enabled): on overflow error, or when near context window.<br><strong>Lossy</strong> for the live prompt - full history still on disk; recover via <code>/tree</code>.</p><p>When context is polluted: prefer <code>/new</code> + a written plan file over grinding in junk context.</p><hr><h2 id="6-Everyday-TUI-usage"><a href="#6-Everyday-TUI-usage" class="headerlink" title="6. Everyday TUI usage"></a>6. Everyday TUI usage</h2><p><strong>Editor</strong></p><ul><li><code>@</code> fuzzy file reference (respects gitignore)</li><li>Tab path completion</li><li>multi-line: Shift/Alt+Enter</li><li>Ctrl+G external editor</li><li>Ctrl+C clear; double Ctrl+C exit</li><li>Esc abort stream; Esc×2 earlier-state picker (tree-related)</li><li>Ctrl+O expand tool output; Ctrl+T thinking visibility</li><li>Shift+Tab thinking level cycle</li><li>Ctrl+P / Shift+Ctrl+P model cycle</li></ul><p><strong>Bash mode (include shell output in context)</strong></p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">!git status</span><br><span class="line">!ls -la src</span><br></pre></td></tr></tbody></table></figure><p>Large output truncated (docs: ~2000 lines / 50KB). Esc cancels.</p><p><strong>Message queue / steering</strong></p><p>While agent runs you can type more:</p><ul><li>queue modes: process all vs one-at-a-time</li><li>steering: inject mid-turn vs wait</li><li>Esc aborts and restores queued text to editor</li></ul><p>Plan without a dedicated “plan mode”: ask for a markdown/HTML plan file, iterate,<br>then implement from that artifact (a solid pattern).</p><hr><h2 id="7-Packages-third-party-extensions"><a href="#7-Packages-third-party-extensions" class="headerlink" title="7. Packages (third-party extensions)"></a>7. Packages (third-party extensions)</h2><p>Installable capabilities (tools, UI, behaviors). Catalog on pi.dev packages page.</p><p>In settings:</p><figure class="highlight json hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-punctuation">{</span></span><br><span class="line">  <span class="hljs-attr">"packages"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span></span><br><span class="line">    <span class="hljs-string">"npm:some-package@version"</span><span class="hljs-punctuation">,</span></span><br><span class="line">    <span class="hljs-string">"git:github.com/org/repo@commit"</span></span><br><span class="line">  <span class="hljs-punctuation">]</span></span><br><span class="line"><span class="hljs-punctuation">}</span></span><br></pre></td></tr></tbody></table></figure><p>Common package patterns (names evolve - check the current catalog):</p><table><thead><tr><th>Goal</th><th>Package idea</th></tr></thead><tbody><tr><td>Web research</td><td>web-access style package (search + fetch tools for the <strong>agent</strong>)</td></tr><tr><td>Safety</td><td>guardrails package (policies on commands/paths)</td></tr><tr><td>Parallel work</td><td>subagents package (spawn workers with <strong>fresh context</strong>, report back)</td></tr><tr><td>UX / workflows</td><td>many others - browse by downloads</td></tr></tbody></table><p><strong>Self-configure:</strong> because Pi is a coding agent with system access, you can ask it<br>to edit its own settings/packages - powerful and risky; review diffs.</p><p>After install: restart or reload as package docs require; new tools appear for the model.</p><hr><h2 id="8-AGENTS-md-always-on-project-brain"><a href="#8-AGENTS-md-always-on-project-brain" class="headerlink" title="8. AGENTS.md (always-on project brain)"></a>8. AGENTS.md (always-on project brain)</h2><p>Loaded at startup (merge order):</p><ol><li><code>~/.pi/agent/AGENTS.md</code></li><li>parents walking up</li><li><code>./AGENTS.md</code></li></ol><p>Use for: commands, architecture, conventions, test how-to, don’t-touch lists.<br>Not for heavy one-off workflows (skills) or short reusable prompts (slash commands).</p><p>Claude Code uses <code>CLAUDE.md</code>; Pi also reads it as alternate project context.</p><hr><h2 id="9-Skills-on-demand-capability-packs"><a href="#9-Skills-on-demand-capability-packs" class="headerlink" title="9. Skills (on-demand capability packs)"></a>9. Skills (on-demand capability packs)</h2><p>Agent Skills standard (<code>SKILL.md</code>). Loaded when description matches <strong>or</strong> forced:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">/skill:my-skill-name optional args</span><br></pre></td></tr></tbody></table></figure><p>Locations (recursive under Pi dirs):</p><ul><li><code>~/.pi/agent/skills/**/SKILL.md</code></li><li><code>.pi/skills/**/SKILL.md</code></li><li>also discovers Claude/Codex skill trees</li></ul><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">my-skill/</span><br><span class="line">  SKILL.md          # name + description (critical for auto-trigger)</span><br><span class="line">  scripts/</span><br><span class="line">  references/</span><br><span class="line">  assets/</span><br></pre></td></tr></tbody></table></figure><table><thead><tr><th>Need</th><th>Prefer</th></tr></thead><tbody><tr><td>Always-on conventions</td><td>AGENTS.md</td></tr><tr><td>User-triggered prompt template</td><td>slash command (<code>commands/*.md</code>)</td></tr><tr><td>New LLM-callable tool</td><td>custom tool / package</td></tr><tr><td>On-demand workflow + scripts + docs</td><td><strong>skill</strong></td></tr></tbody></table><p>Local skill wins for token efficiency vs “please read the whole web docs every time”.<br>Global skills: cross-project helpers. Project skills: stack/domain specifics.</p><hr><h2 id="10-Prompt-templates-slash-commands"><a href="#10-Prompt-templates-slash-commands" class="headerlink" title="10. Prompt templates (slash commands)"></a>10. Prompt templates (slash commands)</h2><p>Reusable prompts as markdown:</p><ul><li>Global: <code>~/.pi/agent/commands/*.md</code> (docs path; some setups also use a <code>prompts/</code> folder)</li><li>Project: <code>.pi/commands/*.md</code></li></ul><figure class="highlight markdown hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line">---</span><br><span class="line"><span class="hljs-section">description: Review staged git changes</span></span><br><span class="line"><span class="hljs-section">---</span></span><br><span class="line">Review <span class="hljs-code">`git diff --cached`</span>. Focus on bugs, security, missing tests.</span><br></pre></td></tr></tbody></table></figure><p>Filename → <code>/filename</code>. Args: <code>$1</code>, <code>$@</code>.<br>Subdirs namespace commands.</p><p>Use when you keep retyping the same multi-paragraph instruction.</p><hr><h2 id="11-Extensions-hooks-deep-customization"><a href="#11-Extensions-hooks-deep-customization" class="headerlink" title="11. Extensions / hooks (deep customization)"></a>11. Extensions / hooks (deep customization)</h2><p><strong>Hooks</strong> = TypeScript modules on lifecycle events (tool_call, session_start, …):</p><ul><li>block dangerous tools</li><li>checkpoint git state</li><li>protect paths</li><li>inject external wake-up messages</li></ul><p>Paths: <code>~/.pi/agent/hooks/*.ts</code>, <code>.pi/hooks/*.ts</code>, or settings <code>hooks: []</code>.</p><p><strong>Custom tools</strong> = new tools the model can call (TypeBox params, optional TUI UI).</p><p>Paths: <code>~/.pi/agent/tools/*/index.ts</code>, <code>.pi/tools/*/index.ts</code>, settings <code>customTools</code>.</p><p>Extension idea: after each turn, open last assistant message as rendered HTML<br>(summary/readability) - implemented as extension, preferably global.</p><p>Packages are the distributed form of extensions/tools/hooks.</p><hr><h2 id="12-Workflow-patterns"><a href="#12-Workflow-patterns" class="headerlink" title="12. Workflow patterns"></a>12. Workflow patterns</h2><ol><li><strong>Bootstrap project brain</strong> - AGENTS.md + stack skills before heavy coding  </li><li><strong>Plan as artifact</strong> - markdown/HTML plan file, refine, then implement  </li><li><strong>Discuss then build</strong> - architecture critique in-session, then code  </li><li><strong>Commit via agent</strong> - <code>!git …</code> or natural language commit (still review)  </li><li><strong>Feature branches of thought</strong> - <code>/tree</code> or <code>/fork</code> when exploring alternatives  </li><li><strong>Keep context clean</strong> - ephemeral for one-shots; new session when topic shifts  </li><li><strong>Docs-first skills</strong> - for young frameworks, pin official docs in a skill  </li><li><strong>Manual skill activation</strong> when auto-discovery is unreliable</li></ol><hr><h2 id="13-Pocket-command-map"><a href="#13-Pocket-command-map" class="headerlink" title="13. Pocket command map"></a>13. Pocket command map</h2><table><thead><tr><th>Command / action</th><th>Purpose</th></tr></thead><tbody><tr><td><code>/settings</code></td><td>Quick settings</td></tr><tr><td><code>/model</code> <code>/login</code> <code>/logout</code></td><td>Models &amp; auth</td></tr><tr><td><code>/new</code></td><td>Fresh session</td></tr><tr><td><code>/session</code></td><td>Path, tokens, cost</td></tr><tr><td><code>/resume</code> <code>-r</code></td><td>Session picker</td></tr><tr><td><code>--continue</code> <code>-c</code></td><td>Last session</td></tr><tr><td><code>--no-session</code></td><td>Ephemeral</td></tr><tr><td><code>/tree</code></td><td>In-place branch nav</td></tr><tr><td><code>/branch</code> <code>/fork</code> <code>/clone</code></td><td>Copy/branch sessions</td></tr><tr><td><code>/compact</code></td><td>Summarize old context</td></tr><tr><td><code>/export</code></td><td>HTML export</td></tr><tr><td><code>/hotkeys</code></td><td>Shortcut list</td></tr><tr><td><code>/copy</code></td><td>Copy last assistant msg</td></tr><tr><td><code>@file</code></td><td>Attach project file</td></tr><tr><td><code>!cmd</code></td><td>Shell → context</td></tr><tr><td><code>/skill:name</code></td><td>Force skill</td></tr><tr><td><code>/command</code></td><td>Prompt template</td></tr></tbody></table><hr><h2 id="14-Layout-on-disk-cheat"><a href="#14-Layout-on-disk-cheat" class="headerlink" title="14. Layout on disk (cheat)"></a>14. Layout on disk (cheat)</h2><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br></pre></td><td class="code"><pre><span class="line">~/.pi/agent/</span><br><span class="line">  auth.json</span><br><span class="line">  settings.json</span><br><span class="line">  models.json</span><br><span class="line">  AGENTS.md</span><br><span class="line">  SYSTEM.md                 # optional full system prompt replace</span><br><span class="line">  sessions/--path--/*.jsonl</span><br><span class="line">  packages / hooks / tools / skills / commands / themes / extensions …</span><br><span class="line"></span><br><span class="line">project/</span><br><span class="line">  AGENTS.md</span><br><span class="line">  .pi/</span><br><span class="line">    settings.json</span><br><span class="line">    skills/…</span><br><span class="line">    commands/…</span><br><span class="line">    hooks/…</span><br><span class="line">    tools/…</span><br><span class="line">    SYSTEM.md</span><br></pre></td></tr></tbody></table></figure><hr><h2 id="15-Decision-tree"><a href="#15-Decision-tree" class="headerlink" title="15. Decision tree"></a>15. Decision tree</h2><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line">Always true for this repo?          → AGENTS.md</span><br><span class="line">I retype the same prompt weekly?    → slash command / prompt template</span><br><span class="line">Need scripts + workflow docs?       → skill</span><br><span class="line">Need new tool the model calls?      → package / custom tool</span><br><span class="line">Need to block/modify behavior?      → hook / guardrails package</span><br><span class="line">Need isolation from host?           → Docker (or stronger sandbox)</span><br><span class="line">Context full / polluted?            → /tree branch, /compact, or /new + plan file</span><br><span class="line">Quick throwaway Q?                  → --no-session</span><br></pre></td></tr></tbody></table></figure><hr></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;p&gt;Pi is a terminal coding agent that starts almost empty and grows through packages, skills, hooks, and project files. That is the opposite of many agents that ship fully loaded.&lt;/p&gt;
&lt;p&gt;This post is a compact field guide: install and auth, security, sessions (&lt;code&gt;/tree&lt;/code&gt;, clone, fork, compaction), packages, &lt;code&gt;AGENTS.md&lt;/code&gt;, skills, prompt templates, extensions, and daily TUI habits. Prefer the &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent&quot;&gt;official docs&lt;/a&gt; and &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://pi.dev/&quot;&gt;pi.dev&lt;/a&gt; when flags drift.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="agentic-coding" scheme="https://vanducng.dev/tags/agentic-coding/"/>
    
    <category term="pi" scheme="https://vanducng.dev/tags/pi/"/>
    
    <category term="coding-agents" scheme="https://vanducng.dev/tags/coding-agents/"/>
    
    <category term="tui" scheme="https://vanducng.dev/tags/tui/"/>
    
  </entry>
  
  <entry>
    <title>CLI Proxy API Keys for Codex Desktop on macOS</title>
    <link href="https://vanducng.dev/2026/08/15/cli-proxy-api-keys-for-codex-desktop-on-macos/"/>
    <id>https://vanducng.dev/2026/08/15/cli-proxy-api-keys-for-codex-desktop-on-macos/</id>
    <published>2026-08-15T20:00:00.000Z</published>
    <updated>2026-11-16T05:26:58.275Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><p>Codex CLI was talking to my OpenAI-compatible gateway just fine. Codex Desktop was not.</p><p>Same <code>~/.codex/config.toml</code>. Same custom provider. Same machine. Desktop failed immediately with:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">Missing environment variable: CLI_PROXY_API_KEY</span><br></pre></td></tr></tbody></table></figure><p>The provider was not the problem. The process environment was.</p><span id="more"></span><img src="/2026/08/15/cli-proxy-api-keys-for-codex-desktop-on-macos/cover.png" class="" title="CLI and Desktop linked by launchctl setenv"><h2 id="Intent"><a href="#Intent" class="headerlink" title="Intent"></a>Intent</h2><p>I run coding agents through a single gateway - <strong>CLIProxyAPI</strong> - so model choice stays flexible without re-wiring auth in every client.</p><p>For Codex, that means a custom provider:</p><figure class="highlight toml hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-attr">model_provider</span> = <span class="hljs-string">"cli_proxy"</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-section">[model_providers.cli_proxy]</span></span><br><span class="line"><span class="hljs-attr">name</span> = <span class="hljs-string">"CLIProxyAPI"</span></span><br><span class="line"><span class="hljs-attr">base_url</span> = <span class="hljs-string">"https://cli-proxy.example.com/v1"</span></span><br><span class="line"><span class="hljs-attr">wire_api</span> = <span class="hljs-string">"responses"</span></span><br><span class="line"><span class="hljs-attr">env_key</span> = <span class="hljs-string">"CLI_PROXY_API_KEY"</span></span><br></pre></td></tr></tbody></table></figure><p>The key never lives in the config file. Codex reads it from the process environment via <code>env_key</code>.</p><p>In the shell that is easy:</p><figure class="highlight bash hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-built_in">export</span> CLI_PROXY_API_KEY=<span class="hljs-string">"<span class="hljs-subst">$(gopass show -o &lt;secret-path&gt;)</span>"</span></span><br><span class="line">codex</span><br></pre></td></tr></tbody></table></figure><p>CLI inherits the export. Done.</p><p>Desktop is a different animal.</p><h2 id="Why-CLI-worked-and-Desktop-did-not"><a href="#Why-CLI-worked-and-Desktop-did-not" class="headerlink" title="Why CLI worked and Desktop did not"></a>Why CLI worked and Desktop did not</h2><p>Codex Desktop ships inside <strong>ChatGPT.app</strong>. When you open it from the Dock or Spotlight, macOS starts it through LaunchServices.</p><p>LaunchServices does <strong>not</strong> load <code>~/.zshrc</code>.</p><p>So the same provider block that works in a terminal session fails in the GUI process, because <code>CLI_PROXY_API_KEY</code> is simply not present.</p><p>You can confirm the split:</p><figure class="highlight bash hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-comment"># shell world</span></span><br><span class="line"><span class="hljs-built_in">printenv</span> CLI_PROXY_API_KEY | <span class="hljs-built_in">wc</span> -c</span><br><span class="line"></span><br><span class="line"><span class="hljs-comment"># GUI session world</span></span><br><span class="line">launchctl getenv CLI_PROXY_API_KEY | <span class="hljs-built_in">wc</span> -c</span><br></pre></td></tr></tbody></table></figure><p>If the first is non-zero and the second is zero, you have the bug.</p><h2 id="The-fix-bridge-the-GUI-session-with-launchctl"><a href="#The-fix-bridge-the-GUI-session-with-launchctl" class="headerlink" title="The fix: bridge the GUI session with launchctl"></a>The fix: bridge the GUI session with launchctl</h2><p>macOS lets you inject environment variables into the GUI session:</p><figure class="highlight bash hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">launchctl setenv CLI_PROXY_API_KEY <span class="hljs-string">"<span class="hljs-subst">$(gopass show -o &lt;secret-path&gt;)</span>"</span></span><br></pre></td></tr></tbody></table></figure><p>Then fully quit ChatGPT (Cmd+Q) and reopen it so the new process inherits the session env.</p><p>That is the whole idea. Everything else is packaging so you do not have to remember the command after every reboot.</p><h2 id="Stow-managed-LaunchAgent"><a href="#Stow-managed-LaunchAgent" class="headerlink" title="Stow-managed LaunchAgent"></a>Stow-managed LaunchAgent</h2><p>I put it in my <a target="_blank" rel="noopener" href="https://github.com/vanducng/dotfiles">dotfiles</a> as a macOS-only LaunchAgent:</p><table><thead><tr><th>Piece</th><th>Role</th></tr></thead><tbody><tr><td><code>~/.local/bin/set-cli-proxy-gui-env.sh</code></td><td>Reads gopass, runs <code>launchctl setenv</code></td></tr><tr><td><code>~/Library/LaunchAgents/local.cli-proxy-gui-env.plist</code></td><td>Runs at login, retries every 5 minutes if gpg was locked</td></tr></tbody></table><p>Install:</p><figure class="highlight bash hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line">make stow-bin stow-launchd</span><br><span class="line"></span><br><span class="line">launchctl bootout <span class="hljs-string">"gui/<span class="hljs-subst">$(id -u)</span>"</span> \</span><br><span class="line">  <span class="hljs-string">"<span class="hljs-variable">$HOME</span>/Library/LaunchAgents/local.cli-proxy-gui-env.plist"</span> 2&gt;/dev/null || <span class="hljs-literal">true</span></span><br><span class="line">launchctl bootstrap <span class="hljs-string">"gui/<span class="hljs-subst">$(id -u)</span>"</span> \</span><br><span class="line">  <span class="hljs-string">"<span class="hljs-variable">$HOME</span>/Library/LaunchAgents/local.cli-proxy-gui-env.plist"</span></span><br><span class="line">launchctl kickstart -k <span class="hljs-string">"gui/<span class="hljs-subst">$(id -u)</span>/local.cli-proxy-gui-env"</span></span><br></pre></td></tr></tbody></table></figure><p>Design choices that mattered:</p><ol><li><strong>Skip when already set</strong> - avoids pinentry spam on the 5-minute retry.</li><li><strong>Timeout around gopass</strong> - a hung pinentry under launchd must not stall forever.</li><li><strong><code>refresh</code> / <code>unset</code> modes</strong> - key rotation without reboot:</li></ol><figure class="highlight bash hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-string">"<span class="hljs-variable">$HOME</span>/.local/bin/set-cli-proxy-gui-env.sh"</span> refresh</span><br><span class="line"><span class="hljs-comment"># or</span></span><br><span class="line"><span class="hljs-string">"<span class="hljs-variable">$HOME</span>/.local/bin/set-cli-proxy-gui-env.sh"</span> <span class="hljs-built_in">unset</span></span><br></pre></td></tr></tbody></table></figure><ol start="4"><li><strong>Portable <code>$HOME</code> paths</strong> - the plist launches via <code>bash -c 'exec "$HOME/.local/bin/..."'</code> so the package does not hardcode a username.</li></ol><p>Shipped as <a target="_blank" rel="noopener" href="https://github.com/vanducng/dotfiles/pull/107">dotfiles#107</a>.</p><h2 id="How-we-proved-it"><a href="#How-we-proved-it" class="headerlink" title="How we proved it"></a>How we proved it</h2><p>After loading the agent and relaunching ChatGPT:</p><ol><li><strong>GUI env</strong> - <code>launchctl getenv CLI_PROXY_API_KEY</code> was non-empty.</li><li><strong>Process env</strong> - the ChatGPT process itself contained <code>CLI_PROXY_API_KEY</code>.</li><li><strong>Gateway</strong> - <code>GET /v1/models</code> with that key returned HTTP 200.</li><li><strong>Desktop chat</strong> - sent <code>hello from computer-use env test</code> on a CLIProxy-backed model. The footer showed <strong>CLIProxyAPI</strong>. The agent worked. No missing-env banner.</li></ol><p>One amusing constraint: Codex Computer Use refuses to drive <code>com.openai.codex</code> for safety reasons, so the UI proof used window capture and Accessibility rather than Computer Use controlling Codex itself. The process-env + gateway + live chat evidence was enough.</p><h2 id="Mental-model"><a href="#Mental-model" class="headerlink" title="Mental model"></a>Mental model</h2><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line">gopass secret</span><br><span class="line">    |</span><br><span class="line">    v</span><br><span class="line">shell export  --------------&gt;  Codex CLI   (works)</span><br><span class="line">    |</span><br><span class="line">    +-- launchctl setenv ---&gt;  GUI session</span><br><span class="line">                                   |</span><br><span class="line">                                   v</span><br><span class="line">                              ChatGPT.app / Codex Desktop  (works after relaunch)</span><br></pre></td></tr></tbody></table></figure><p>If the CLI works and Desktop fails on the <strong>same</strong> config file, check the process tree before the provider block.</p><p>Shells export. Docks do not.</p><h2 id="Tradeoffs"><a href="#Tradeoffs" class="headerlink" title="Tradeoffs"></a>Tradeoffs</h2><ul><li><code>launchctl setenv</code> is session-scoped. Cold boot still depends on gopass unlock timing.</li><li>Rotating the secret leaves a stale GUI value until <code>refresh</code> or logout.</li><li>This is a deliberate bridge for one env var, not a general secret injector for every app.</li></ul><h2 id="Takeaway"><a href="#Takeaway" class="headerlink" title="Takeaway"></a>Takeaway</h2><p>Custom providers with <code>env_key</code> are only as reliable as the environment of the process that loads them.</p><p>For terminal agents, your shell is enough.</p><p>For macOS GUI agents, you need an explicit bridge into the LaunchServices world. A small LaunchAgent that reads gopass and runs <code>launchctl setenv</code> is that bridge - boring, portable, and enough to make Codex Desktop use the same CLI Proxy path as the CLI.</p></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;p&gt;Codex CLI was talking to my OpenAI-compatible gateway just fine. Codex Desktop was not.&lt;/p&gt;
&lt;p&gt;Same &lt;code&gt;~/.codex/config.toml&lt;/code&gt;. Same custom provider. Same machine. Desktop failed immediately with:&lt;/p&gt;
&lt;figure class=&quot;highlight text hljs&quot;&gt;&lt;table&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td class=&quot;gutter&quot;&gt;&lt;pre&gt;&lt;span class=&quot;line&quot;&gt;1&lt;/span&gt;&lt;br&gt;&lt;/pre&gt;&lt;/td&gt;&lt;td class=&quot;code&quot;&gt;&lt;pre&gt;&lt;span class=&quot;line&quot;&gt;Missing environment variable: CLI_PROXY_API_KEY&lt;/span&gt;&lt;br&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/figure&gt;

&lt;p&gt;The provider was not the problem. The process environment was.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="agentic-coding" scheme="https://vanducng.dev/tags/agentic-coding/"/>
    
    <category term="codex" scheme="https://vanducng.dev/tags/codex/"/>
    
    <category term="macos" scheme="https://vanducng.dev/tags/macos/"/>
    
    <category term="launchd" scheme="https://vanducng.dev/tags/launchd/"/>
    
    <category term="cli-proxy" scheme="https://vanducng.dev/tags/cli-proxy/"/>
    
  </entry>
  
  <entry>
    <title>Bounded Autonomy and Guardrails for Claude Code</title>
    <link href="https://vanducng.dev/2026/08/15/bounded-autonomy-and-guardrails-for-claude-code/"/>
    <id>https://vanducng.dev/2026/08/15/bounded-autonomy-and-guardrails-for-claude-code/</id>
    <published>2026-08-15T08:30:00.000Z</published>
    <updated>2026-11-16T05:26:58.274Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><p><a href="/2026/08/15/evaluation-and-observability-for-claude-agents/">Part 5</a> ended with a debt: autonomy I am willing to grant, and guardrails that hold even when the model would rather keep going.</p><p>This is Part 6 of 6 in my <strong>Agentic Coding with Claude Code</strong> series. The working model I am keeping is simple: eval tells me whether the loop did the job. Guardrails decide what the loop is allowed to do even when the model wants another hop. Bounded autonomy is the grant: which agents, which tools, how many turns, when a human is required.</p><p>This is the series closer. I will not rewrite <a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Parts 1</a> through 5. I will bound the loop those posts already built.</p><span id="more"></span><h2 id="Autonomy-Is-a-Grant-Not-a-Vibe"><a href="#Autonomy-Is-a-Grant-Not-a-Vibe" class="headerlink" title="Autonomy Is a Grant, Not a Vibe"></a>Autonomy Is a Grant, Not a Vibe</h2><p><a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Part 1</a> already said it: give the agent the smallest authority that still lets it finish. I used to treat that as a prompt habit. “Be careful with prod.” “Do not merge.” “Ask if you are unsure.” Those sentences are guidance. They live in the window. The model can still decide the next hop is worth it.</p><p>A grant is code. <a href="/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/">Part 3</a> already named the knobs. I am not re-teaching them. I am naming which ones <em>are</em> the grant:</p><table><thead><tr><th>Knob</th><th>Official field</th><th>What I am actually granting</th></tr></thead><tbody><tr><td><strong>Who may act</strong></td><td><code>agents</code> on <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/subagents"><code>ClaudeAgentOptions</code></a>, plus <code>Agent</code> in <code>allowed_tools</code></td><td>Which specialized loops I defined. Omit <code>Agent</code> from <code>allowed_tools</code> and a spawn falls through to <code>can_use_tool</code>, or is denied in <code>dontAsk</code>. The built-in <code>general-purpose</code> spoke needs no <code>agents</code> entry.</td></tr><tr><td><strong>What each loop can see</strong></td><td><code>AgentDefinition.tools</code> / <code>disallowedTools</code></td><td>The spoke’s public API. A tool you omit is not in that session.</td></tr><tr><td><strong>What may run without a human</strong></td><td><code>permission_mode</code>, <code>allowed_tools</code>, <code>disallowed_tools</code></td><td>The same <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/permissions#how-permissions-are-evaluated">permission order</a> from Parts 3 and 4.</td></tr><tr><td><strong>How many hops</strong></td><td><code>max_turns</code> on the query; <code>maxTurns</code> on an <code>AgentDefinition</code></td><td>When the loop must stop even if the model wants another tool.</td></tr><tr><td><strong>How much spend</strong></td><td><code>max_budget_usd</code> / <code>maxBudgetUsd</code></td><td>The query ends with <code>error_max_budget_usd</code>. Subagent requests count.</td></tr><tr><td><strong>How wide the tree gets</strong></td><td><code>CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH</code>, <code>CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS</code></td><td>Official env caps. Depth default is 3. Concurrency default is 20.</td></tr><tr><td><strong>What must never run</strong></td><td>A <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/hooks"><code>PreToolUse</code></a> hook that returns <code>permissionDecision: "deny"</code></td><td>The grant that holds when the model would rather keep going.</td></tr><tr><td><strong>When a human is required</strong></td><td><code>plan</code>, <code>default</code> plus <code>can_use_tool</code>, or a hook that returns <code>"ask"</code></td><td>The pause is a product decision, not a polite request in <code>CLAUDE.md</code>.</td></tr></tbody></table><p><code>CLAUDE.md</code> is still guidance, the way <a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a> said. If a write must not happen, that is a permission rule or a hook. If a second agent must not exist, I do not define it. If the tree must stay one layer deep, I set <code>CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1</code>. I do not ask Opus to “please not nest.”</p><p>The takeaway I kept: autonomy is a budget of agents, tools, turns, and spend. I write the budget down. I do not vibe it.</p><h2 id="Multi-Agent-Only-When-Isolation-Is-Cheaper-or-Safer"><a href="#Multi-Agent-Only-When-Isolation-Is-Cheaper-or-Safer" class="headerlink" title="Multi-Agent Only When Isolation Is Cheaper or Safer"></a>Multi-Agent Only When Isolation Is Cheaper or Safer</h2><p><a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Part 1</a> already said more agents do not automatically produce better work. Coordination cost is real. I start with one agent. I add a second loop only when a step is cheaper or safer in isolation: a noisy review that should not fill the parent window, a read-only lint pass that must never edit, a test runner whose bash I do not want on the coordinator.</p><p>Official <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/subagents">subagents</a> are that isolation. Each spoke is a fresh conversation. Intermediate tool calls stay inside it. The parent receives the final message, not every file the spoke read. That is the same fork trick <a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a> used on skills, applied to a named worker.</p><p>Hub-and-spoke is the shape I actually use. One coordinator. Scoped spokes. A structured handoff. The coordinator routes and integrates. It does not re-do the lint.</p><pre class="mermaid">flowchart TB    Goal[Review request] --&gt; Hub[Orchestrator]    Hub --&gt; Lint[lint spoke]    Hub --&gt; Tests[tests spoke]    Hub --&gt; Sec[security notes]    Lint --&gt; Handoff[Structured handoff]    Tests --&gt; Handoff    Sec --&gt; Handoff    Handoff --&gt; Hub    Hub --&gt; Gate{Merge hook}    Gate --&gt;|under threshold| Notes[Publish review notes]    Gate --&gt;|over threshold| Human[Human required]    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff    classDef tealClass fill:#16A085,stroke:#333,stroke-width:2px,color:#fff    classDef redClass fill:#E74C3C,stroke:#333,stroke-width:2px,color:#fff    class Goal blueClass    class Hub orangeClass    class Lint,Tests,Sec purpleClass    class Handoff tealClass    class Gate redClass    class Notes greenClass    class Human redClass</pre><p>The public Course 4 syllabus names sequential, parallel, and advanced orchestration. Those are not SDK type names. They are patterns I map onto official tools:</p><table><thead><tr><th>Pattern</th><th>What I mean</th><th>Official surface I actually use</th><th>When I use it</th><th>When I do not</th></tr></thead><tbody><tr><td><strong>Single agent</strong></td><td>One loop owns the task</td><td><code>query()</code> with no <code>agents</code> map</td><td>The work shares one context</td><td>A noisy subtask would tax the parent window</td></tr><tr><td><strong>Sequential</strong></td><td>Spoke B needs spoke A’s result</td><td>One <code>Agent</code> call, then another, after the first <code>tool_result</code></td><td>Handoff depends on prior evidence</td><td>The steps are independent. I am paying for a queue I do not need.</td></tr><tr><td><strong>Parallel</strong></td><td>Independent spokes in one turn</td><td>Several <code>Agent</code> calls; official docs say they can run concurrently</td><td>Lint, tests, and security notes do not share changing state</td><td>Two spokes would edit the same files</td></tr><tr><td><strong>Hub-and-spoke</strong></td><td>One coordinator, scoped workers, structured handoff</td><td><code>agents={...}</code> plus <code>Agent</code> in <code>allowed_tools</code></td><td>I need isolation and a single integrator</td><td>I cannot name what each spoke returns</td></tr><tr><td><strong>Nested / wide tree</strong></td><td>Spokes spawn spokes</td><td>Same <code>Agent</code> tool. Cap with <code>CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH</code></td><td>Rare. A spoke that must research further</td><td>Default. Depth 3 plus Opus 5 is how a review becomes a swarm.</td></tr><tr><td><strong>Scripted orchestration</strong></td><td>Dozens to hundreds of workers</td><td>The <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/workflows"><code>Workflow</code></a> tool (TypeScript SDK v0.3.149+). Include <code>Workflow</code> in <code>allowedTools</code>.</td><td>A repo-wide audit that does not fit one conversation</td><td>A three-spoke review. Subagents are enough.</td></tr><tr><td><strong>Agent teams</strong></td><td>Separate sessions that message each other</td><td><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-teams"><code>agent teams</code></a>. Official page: experimental, off until <code>CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1</code>. SDK / <code>-p</code> sessions do not spawn teammates.</td><td>Interactive research where workers must argue</td><td>A headless review desk. I stay on subagents.</td></tr></tbody></table><p>Claude invokes a spoke through the <code>Agent</code> tool (<code>Task</code> on older SDK traces). Include <code>Agent</code> in <code>allowed_tools</code> or, in <code>dontAsk</code>, the spawn is denied. A spoke’s <code>description</code> is how the coordinator decides to call it. Mention the name in the prompt when I need that spoke, not a guess.</p><p>What a spoke inherits is narrower than I first assumed. Official table: it gets its own <code>prompt</code>, the Agent tool’s prompt string, project <code>CLAUDE.md</code> if <code>setting_sources</code> loads it, and its tool list. It does <strong>not</strong> get the parent’s conversation or the parent’s system prompt. If the spoke needs a file path or a PR number, I put that in the delegation prompt. A missing handoff is a context bug, the same class <a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a> already named.</p><p>Subagents inherit the parent’s <code>permission_mode</code>. An <code>AgentDefinition.permissionMode</code> can override it, except when the parent is <code>bypassPermissions</code>, <code>acceptEdits</code>, or <code>auto</code>. Those three apply to every spoke and cannot be overridden. I do not put the coordinator in <code>bypassPermissions</code> and hope a spoke stays read-only.</p><h2 id="Deterministic-Hooks-vs-Prompts"><a href="#Deterministic-Hooks-vs-Prompts" class="headerlink" title="Deterministic Hooks vs Prompts"></a>Deterministic Hooks vs Prompts</h2><p>A prompt is guidance. A hook is code that runs on an official event and can deny, rewrite, or halt.</p><p>The public Course 4 syllabus names a comparison harness: deterministic hooks block 100% of violations where a strong prompt cannot. I did not rerun their banking exercise. The takeaway I kept does not need their files. A sentence in <code>CLAUDE.md</code> occupies the window. A <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/hooks"><code>PreToolUse</code></a> callback occupies the process. The model does not get a vote.</p><pre class="mermaid">flowchart TB    subgraph Hook["Deterministic hook"]        direction LR        H1[Official event] --&gt; H2[Callback reads args] --&gt; H3["deny / allow / ask"]    end    subgraph Prompt["Prompt only"]        direction LR        P1["Please never merge"] --&gt; P2[Model decides] --&gt; P3[May still call]    end    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef redClass fill:#E74C3C,stroke:#333,stroke-width:2px,color:#fff    class H1,H2,H3 greenClass    class P1,P2 orangeClass    class P3 redClass</pre><p>Hook on the right is the grant. Prompt on the left is the baseline I no longer trust for a write I cannot undo.</p><p>Official events I actually fetched, from the <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/hooks#available-hooks">Agent SDK hooks</a> table and the <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/hooks">Claude Code hooks</a> reference. I am not inventing names. I am also not dumping the full catalog (the Claude Code page lists session, worktree, elicitation, and file-watch events I am not using here). The ones that bound a loop:</p><table><thead><tr><th>Event</th><th>Python SDK</th><th>What it is for</th><th>Guardrail I actually write</th></tr></thead><tbody><tr><td><code>PreToolUse</code></td><td>Yes</td><td>Before a tool runs. Can block or rewrite.</td><td>Deny an over-threshold write. <code>updatedInput</code> to sandbox a path.</td></tr><tr><td><code>PostToolUse</code></td><td>Yes</td><td>After a tool succeeds</td><td>Normalize a messy result (<code>updatedToolOutput</code>). Append <code>additionalContext</code>. Audit.</td></tr><tr><td><code>PostToolUseFailure</code></td><td>Yes</td><td>After a tool fails</td><td>Log the failure class. Do not invent a success.</td></tr><tr><td><code>PermissionRequest</code></td><td>Yes</td><td>A tool call needs a permission decision</td><td>Notify. Or encode the ask in my own UI.</td></tr><tr><td><code>UserPromptSubmit</code></td><td>Yes</td><td>User prompt, before Claude sees it</td><td>Inject a facts block. Block a prompt I will not send.</td></tr><tr><td><code>Stop</code></td><td>Yes</td><td>Agent finished responding</td><td>Official <code>decision: "block"</code> <em>prevents</em> the stop and keeps the loop going (with a <code>reason</code>). I use that when the handoff object is missing. I do not treat Stop as a halt.</td></tr><tr><td><code>SubagentStart</code> / <code>SubagentStop</code></td><td>Yes</td><td>A spoke spawned or finished</td><td>Count spokes. Attach the handoff to the audit.</td></tr><tr><td><code>PreCompact</code></td><td>Yes</td><td>Before compaction</td><td>Archive the transcript I am about to squeeze.</td></tr><tr><td><code>Notification</code></td><td>Yes</td><td>Status messages</td><td>Side effects only. Official docs: Notification hooks do not modify agent behavior. In headless SDK sessions only <code>elicitation_complete</code> and <code>elicitation_response</code> fire. Permission waits go to <code>can_use_tool</code>, not this hook.</td></tr></tbody></table><p>TypeScript adds more (<code>SessionStart</code>, <code>SessionEnd</code>, <code>PostToolBatch</code>, <code>TeammateIdle</code>, <code>TaskCreated</code>, <code>TaskCompleted</code>, and others). The Python SDK page only calls out <code>SessionStart</code> and <code>SessionEnd</code> as missing from <code>HookEvent</code>: those two are shell hooks in <code>.claude/settings.json</code>, loaded with <code>setting_sources=["project"]</code>. I do not assume the rest of the TypeScript-only list is a Python callback.</p><p>How a hook is wired, official fields only:</p><table><thead><tr><th>Field</th><th>Where</th><th>What I set</th></tr></thead><tbody><tr><td>Event name</td><td>Key on <code>options.hooks</code></td><td>Case-sensitive. <code>PreToolUse</code>, not <code>preToolUse</code>.</td></tr><tr><td><code>matcher</code></td><td><code>HookMatcher(matcher=...)</code></td><td>For tool events, the tool name. <code>"Write|Edit"</code>, <code>"Bash"</code>, or a regex like <code>"^mcp__"</code>. Omit it and the callback runs for every event of that type. Matchers do not filter file paths. I check <code>tool_input</code> for that.</td></tr><tr><td>Callback</td><td><code>hooks=[...]</code></td><td>Receives <code>input_data</code>, <code>tool_use_id</code>, <code>context</code>. Shared input fields: <code>session_id</code>, <code>cwd</code>, <code>hook_event_name</code>. Tool events also have <code>tool_name</code> and <code>tool_input</code>.</td></tr><tr><td><code>permissionDecision</code></td><td>Inside <code>hookSpecificOutput</code> on <code>PreToolUse</code></td><td><code>"allow"</code>, <code>"deny"</code>, <code>"ask"</code>, or <code>"defer"</code>. <code>"deny"</code> blocks. <code>"defer"</code> ends the query so I can resume later (<code>stop_reason: "tool_deferred"</code>).</td></tr><tr><td><code>permissionDecisionReason</code></td><td>Same object</td><td>On <code>"deny"</code>, shown to Claude. On <code>"allow"</code> / <code>"ask"</code>, shown to the user, not the model.</td></tr><tr><td><code>updatedInput</code></td><td>Same object</td><td>Rewrite args. Pair with <code>"allow"</code> to auto-approve the rewrite, or omit the decision and let the normal permission flow run. Ignored with <code>"defer"</code>.</td></tr><tr><td><code>updatedToolOutput</code></td><td><code>PostToolUse</code></td><td>Replace what Claude sees. Official replacement for the older MCP-only <code>updatedMCPToolOutput</code>.</td></tr><tr><td><code>continue_</code> / <code>continue</code></td><td>Top-level return</td><td>Whether the agent keeps running after this hook.</td></tr><tr><td><code>async_</code> / <code>async</code></td><td>Top-level return</td><td>Fire-and-forget. Cannot deny. Logging only.</td></tr></tbody></table><p>When several hooks fire, official priority is <code>deny</code> over <code>defer</code> over <code>ask</code> over <code>allow</code>. One deny wins. Hooks run in parallel, so I do not write hook B as if hook A already ran.</p><p>A <code>PreToolUse</code> timeout does not run the tool. Official behavior: Claude gets a hook-timeout tool result and the turn continues. That is not a <code>permissionDecision: "deny"</code>, and it is not a success. I treat a hung guardrail as fail-closed.</p><h2 id="Hooks-Sit-First-in-the-Permission-Order"><a href="#Hooks-Sit-First-in-the-Permission-Order" class="headerlink" title="Hooks Sit First in the Permission Order"></a>Hooks Sit First in the Permission Order</h2><p><a href="/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/">Part 3</a> and <a href="/2026/08/15/mcp-and-tool-governance/">Part 4</a> already used this order. I re-fetched the <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/permissions#how-permissions-are-evaluated">permissions</a> page. It still starts with hooks.</p><ol><li><strong>Hooks.</strong> A hook can deny outright. A hook that returns <code>allow</code> does <strong>not</strong> skip the deny and ask rules below. Those still run.</li><li><strong>Deny rules</strong> (<code>disallowed_tools</code>, <code>settings.json</code>). A scoped deny like <code>Bash(rm *)</code> blocks in every mode, including <code>bypassPermissions</code>. A bare <code>Bash</code> removes the tool from the window before this step.</li><li><strong>Ask rules.</strong> Matched calls fall through to <code>can_use_tool</code>, even in <code>bypassPermissions</code>.</li><li><strong>Active mode.</strong> <code>bypassPermissions</code> approves what reaches this step. <code>acceptEdits</code> approves file ops. <code>plan</code> never auto-approves writes. <code>dontAsk</code> has no prompt.</li><li><strong>Allow rules</strong> (<code>allowed_tools</code>). A match approves.</li><li><strong><code>can_use_tool</code>.</strong> Only if nothing above resolved it. Skipped in <code>dontAsk</code> (denied).</li></ol><p>That is why a hook is the grant I reach for when a mode would lie. <code>allowed_tools</code> does not constrain <code>bypassPermissions</code>. <code>can_use_tool</code> never sees a call that an allow rule or <code>acceptEdits</code> already approved. Official wording: to gate every tool call, use a <code>PreToolUse</code> hook. Hooks still run in <code>bypassPermissions</code>. A hook deny still applies there.</p><p><code>auto</code> is a newer mode than Part 3 listed: a model classifier approves or denies prompts. I am not using it as a guardrail. A classifier is still a model. A hook is still code.</p><h2 id="Keel-Ledger-a-Review-Desk"><a href="#Keel-Ledger-a-Review-Desk" class="headerlink" title="Keel Ledger: a Review Desk"></a>Keel Ledger: a Review Desk</h2><p>Course 4 trains this on an enterprise code-review orchestrator and a banking-hook layer. I am not reprinting those files. Invented analog: <strong>Keel Ledger</strong>, a fictional TypeScript ledger (same fictional shop as <a href="/2026/08/15/evaluation-and-observability-for-claude-agents/">Part 5</a>‘s Keel Freight). One PR lands. A hub routes three read-mostly spokes. A hook blocks merge when the change is over a threshold a prompt would have let through.</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line">Goal: a structured review of one PR, or a fail-closed halt.</span><br><span class="line">Definition of done: lint, tests, and security notes in one handoff object,</span><br><span class="line">  plus merge_allowed true only when every spoke is ok and the hook agrees.</span><br><span class="line">Spokes: lint (read-only), tests (bash for the test command), security-notes (read-only).</span><br><span class="line">Stop and ask before: merging, publishing a release, writing a journal entry over 100000 cents.</span><br><span class="line">Never: let the coordinator re-run a spoke's tools, or let a prompt override the merge hook.</span><br></pre></td></tr></tbody></table></figure><p>Three spokes, one coordinator. Intentionally small. Same isolation rule I used when warranty-desk escalated and shelfwatch skipped: the specialist does one job.</p><table><thead><tr><th>Spoke</th><th><code>AgentDefinition</code> grant</th><th>Returns (handoff fields)</th><th>When not to spawn it</th></tr></thead><tbody><tr><td><code>lint</code></td><td><code>tools=["Read", "Grep", "Glob"]</code>, <code>maxTurns=8</code></td><td><code>lint_ok</code>, <code>lint_findings[]</code></td><td>You already have a CI lint artifact</td></tr><tr><td><code>tests</code></td><td><code>tools=["Bash", "Read", "Grep"]</code>, <code>maxTurns=10</code></td><td><code>tests_ok</code>, <code>failed_names[]</code></td><td>The PR is docs-only</td></tr><tr><td><code>security-notes</code></td><td><code>tools=["Read", "Grep", "Glob"]</code>, <code>model="sonnet"</code></td><td><code>security_ok</code>, <code>notes[]</code></td><td>The diff does not touch <code>src/ledger/**</code></td></tr></tbody></table><p>The structured handoff the hub must produce. Same seam as <a href="/2026/08/15/evaluation-and-observability-for-claude-agents/">Part 5</a>: schema-valid is not truth-valid, but without a schema I cannot score or gate.</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br><span class="line">48</span><br><span class="line">49</span><br><span class="line">50</span><br><span class="line">51</span><br><span class="line">52</span><br><span class="line">53</span><br><span class="line">54</span><br><span class="line">55</span><br><span class="line">56</span><br><span class="line">57</span><br><span class="line">58</span><br><span class="line">59</span><br><span class="line">60</span><br><span class="line">61</span><br><span class="line">62</span><br><span class="line">63</span><br><span class="line">64</span><br><span class="line">65</span><br><span class="line">66</span><br><span class="line">67</span><br><span class="line">68</span><br><span class="line">69</span><br><span class="line">70</span><br><span class="line">71</span><br><span class="line">72</span><br><span class="line">73</span><br><span class="line">74</span><br><span class="line">75</span><br><span class="line">76</span><br><span class="line">77</span><br><span class="line">78</span><br><span class="line">79</span><br><span class="line">80</span><br><span class="line">81</span><br><span class="line">82</span><br><span class="line">83</span><br><span class="line">84</span><br><span class="line">85</span><br><span class="line">86</span><br><span class="line">87</span><br><span class="line">88</span><br><span class="line">89</span><br><span class="line">90</span><br><span class="line">91</span><br><span class="line">92</span><br><span class="line">93</span><br><span class="line">94</span><br><span class="line">95</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-comment"># Sketch. Official fields only. Invented analog, not a course file.</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">from</span> claude_agent_sdk <span class="hljs-keyword">import</span> (</span><br><span class="line">    ClaudeAgentOptions,</span><br><span class="line">    AgentDefinition,</span><br><span class="line">    HookMatcher,</span><br><span class="line">)</span><br><span class="line"></span><br><span class="line">HANDOFF_SCHEMA = {</span><br><span class="line">    <span class="hljs-string">"type"</span>: <span class="hljs-string">"object"</span>,</span><br><span class="line">    <span class="hljs-string">"properties"</span>: {</span><br><span class="line">        <span class="hljs-string">"lint_ok"</span>: {<span class="hljs-string">"type"</span>: <span class="hljs-string">"boolean"</span>},</span><br><span class="line">        <span class="hljs-string">"tests_ok"</span>: {<span class="hljs-string">"type"</span>: <span class="hljs-string">"boolean"</span>},</span><br><span class="line">        <span class="hljs-string">"security_ok"</span>: {<span class="hljs-string">"type"</span>: <span class="hljs-string">"boolean"</span>},</span><br><span class="line">        <span class="hljs-string">"files_changed"</span>: {<span class="hljs-string">"type"</span>: <span class="hljs-string">"integer"</span>},</span><br><span class="line">        <span class="hljs-string">"merge_allowed"</span>: {<span class="hljs-string">"type"</span>: <span class="hljs-string">"boolean"</span>},</span><br><span class="line">        <span class="hljs-string">"reason"</span>: {<span class="hljs-string">"type"</span>: <span class="hljs-string">"string"</span>},</span><br><span class="line">    },</span><br><span class="line">    <span class="hljs-string">"required"</span>: [</span><br><span class="line">        <span class="hljs-string">"lint_ok"</span>,</span><br><span class="line">        <span class="hljs-string">"tests_ok"</span>,</span><br><span class="line">        <span class="hljs-string">"security_ok"</span>,</span><br><span class="line">        <span class="hljs-string">"files_changed"</span>,</span><br><span class="line">        <span class="hljs-string">"merge_allowed"</span>,</span><br><span class="line">        <span class="hljs-string">"reason"</span>,</span><br><span class="line">    ],</span><br><span class="line">    <span class="hljs-string">"additionalProperties"</span>: <span class="hljs-literal">False</span>,</span><br><span class="line">}</span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">async</span> <span class="hljs-keyword">def</span> <span class="title function_">block_over_threshold</span>(<span class="hljs-params">input_data, tool_use_id, context</span>):</span><br><span class="line">    args = input_data.get(<span class="hljs-string">"tool_input"</span>, {})</span><br><span class="line">    files_changed = args.get(<span class="hljs-string">"files_changed"</span>, <span class="hljs-number">0</span>)</span><br><span class="line">    amount_cents = args.get(<span class="hljs-string">"amount_cents"</span>, <span class="hljs-number">0</span>)</span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">if</span> files_changed &gt; <span class="hljs-number">20</span> <span class="hljs-keyword">or</span> amount_cents &gt; <span class="hljs-number">100000</span>:</span><br><span class="line">        <span class="hljs-keyword">return</span> {</span><br><span class="line">            <span class="hljs-string">"hookSpecificOutput"</span>: {</span><br><span class="line">                <span class="hljs-string">"hookEventName"</span>: input_data[<span class="hljs-string">"hook_event_name"</span>],</span><br><span class="line">                <span class="hljs-string">"permissionDecision"</span>: <span class="hljs-string">"deny"</span>,</span><br><span class="line">                <span class="hljs-string">"permissionDecisionReason"</span>: (</span><br><span class="line">                    <span class="hljs-string">"Over threshold. Human required. "</span></span><br><span class="line">                    <span class="hljs-string">"Do not retry merge or post_journal_entry."</span></span><br><span class="line">                ),</span><br><span class="line">            }</span><br><span class="line">        }</span><br><span class="line">    <span class="hljs-keyword">return</span> {}</span><br><span class="line"></span><br><span class="line">options = ClaudeAgentOptions(</span><br><span class="line">    allowed_tools=[</span><br><span class="line">        <span class="hljs-string">"Read"</span>,</span><br><span class="line">        <span class="hljs-string">"Grep"</span>,</span><br><span class="line">        <span class="hljs-string">"Glob"</span>,</span><br><span class="line">        <span class="hljs-string">"Bash"</span>,</span><br><span class="line">        <span class="hljs-string">"Agent"</span>,</span><br><span class="line">        <span class="hljs-string">"mcp__ledger__merge_pr"</span>,</span><br><span class="line">        <span class="hljs-string">"mcp__ledger__post_journal_entry"</span>,</span><br><span class="line">    ],</span><br><span class="line">    disallowed_tools=[<span class="hljs-string">"Write"</span>, <span class="hljs-string">"Edit"</span>],</span><br><span class="line">    permission_mode=<span class="hljs-string">"dontAsk"</span>,</span><br><span class="line">    max_turns=<span class="hljs-number">24</span>,</span><br><span class="line">    max_budget_usd=<span class="hljs-number">5.0</span>,</span><br><span class="line">    output_format={<span class="hljs-string">"type"</span>: <span class="hljs-string">"json_schema"</span>, <span class="hljs-string">"schema"</span>: HANDOFF_SCHEMA},</span><br><span class="line">    agents={</span><br><span class="line">        <span class="hljs-string">"lint"</span>: AgentDefinition(</span><br><span class="line">            description=<span class="hljs-string">"Read-only lint pass. Use for style and import findings."</span>,</span><br><span class="line">            prompt=<span class="hljs-string">"Report lint_ok and lint_findings. Do not edit files."</span>,</span><br><span class="line">            tools=[<span class="hljs-string">"Read"</span>, <span class="hljs-string">"Grep"</span>, <span class="hljs-string">"Glob"</span>],</span><br><span class="line">            maxTurns=<span class="hljs-number">8</span>,</span><br><span class="line">        ),</span><br><span class="line">        <span class="hljs-string">"tests"</span>: AgentDefinition(</span><br><span class="line">            description=<span class="hljs-string">"Runs the targeted test command. Use when the PR touches src/."</span>,</span><br><span class="line">            prompt=<span class="hljs-string">"Run the test command you were given. Return tests_ok and failed_names."</span>,</span><br><span class="line">            tools=[<span class="hljs-string">"Bash"</span>, <span class="hljs-string">"Read"</span>, <span class="hljs-string">"Grep"</span>],</span><br><span class="line">            maxTurns=<span class="hljs-number">10</span>,</span><br><span class="line">        ),</span><br><span class="line">        <span class="hljs-string">"security-notes"</span>: AgentDefinition(</span><br><span class="line">            description=<span class="hljs-string">"Read-only security notes for src/ledger. Use on ledger diffs."</span>,</span><br><span class="line">            prompt=<span class="hljs-string">"List notes. Never approve a merge. Never edit."</span>,</span><br><span class="line">            tools=[<span class="hljs-string">"Read"</span>, <span class="hljs-string">"Grep"</span>, <span class="hljs-string">"Glob"</span>],</span><br><span class="line">            model=<span class="hljs-string">"sonnet"</span>,</span><br><span class="line">        ),</span><br><span class="line">    },</span><br><span class="line">    hooks={</span><br><span class="line">        <span class="hljs-string">"PreToolUse"</span>: [</span><br><span class="line">            HookMatcher(</span><br><span class="line">                matcher=<span class="hljs-string">"mcp__ledger__merge_pr|mcp__ledger__post_journal_entry"</span>,</span><br><span class="line">                hooks=[block_over_threshold],</span><br><span class="line">            )</span><br><span class="line">        ]</span><br><span class="line">    },</span><br><span class="line">    env={</span><br><span class="line">        <span class="hljs-string">"CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH"</span>: <span class="hljs-string">"1"</span>,</span><br><span class="line">        <span class="hljs-string">"CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS"</span>: <span class="hljs-string">"3"</span>,</span><br><span class="line">    },</span><br><span class="line">)</span><br></pre></td></tr></tbody></table></figure><p><code>mcp__ledger__merge_pr</code> and <code>mcp__ledger__post_journal_entry</code> are invented tool names on a fictional server, same naming rule <a href="/2026/08/15/mcp-and-tool-governance/">Part 4</a> already used (<code>mcp__server__tool</code>). They sit on <code>allowed_tools</code> so <code>dontAsk</code> can approve an under-threshold call. Leave them off that list and every merge is denied by mode, which hides whether the hook did any work. The matcher is official syntax. The cents threshold is the same class of rule as a transfer gate: a prompt that says “never post over 100000 cents” will still try when the model wants to close the ticket. The hook reads <code>amount_cents</code> and denies. Fail closed. Do not retry the merge into an allow.</p><p>A prompt-only desk fails in a predictable way. The coordinator summarizes three green spokes, decides the PR “looks small,” and calls <code>merge_pr</code> with <code>files_changed: 47</code>. The hook is the only layer that still says no. Warranty-desk would have escalated. Shelfwatch would have skipped. Harbor Credit would have left <code>rate_bps</code> null. Same instinct, now enforced on the event, not in the window.</p><p>If a spoke returns <code>security_ok: false</code>, the hub sets <code>merge_allowed: false</code>. That is policy in the structured object. The hook is the second lock: even a hub that hallucinates <code>merge_allowed: true</code> cannot run <code>merge_pr</code> over the threshold.</p><h2 id="The-Six-Post-Working-Model"><a href="#The-Six-Post-Working-Model" class="headerlink" title="The Six-Post Working Model"></a>The Six-Post Working Model</h2><p>I am not restating the posts. I am naming the sentence each one left me with.</p><table><thead><tr><th>Post</th><th>Working sentence</th></tr></thead><tbody><tr><td><a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Part 1</a></td><td>The model reasons inside a perceive / reason / act loop. Smallest authority. Coordination costs.</td></tr><tr><td><a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a></td><td>Context is assembled, not typed. Tokens are a budget. <code>CLAUDE.md</code> is guidance.</td></tr><tr><td><a href="/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/">Part 3</a></td><td>The harness decides. <code>stop_reason</code> chooses the next verb. Permissions and <code>max_turns</code> are the loop.</td></tr><tr><td><a href="/2026/08/15/mcp-and-tool-governance/">Part 4</a></td><td>MCP is the surface. Host owns the window. Allow list, deny list, <code>dontAsk</code>. Fail closed.</td></tr><tr><td><a href="/2026/08/15/evaluation-and-observability-for-claude-agents/">Part 5</a></td><td>Eval scores the loop. Structured output is the seam. Schema-valid is not truth-valid.</td></tr><tr><td><strong>Part 6</strong></td><td>Guardrails bound the loop. Autonomy is a grant. Hooks hold when the model would rather keep going.</td></tr></tbody></table><p>One line: the model reasons, the harness decides, MCP is the surface, eval scores the loop, guardrails bound the loop. Context is the budget those five share.</p><h2 id="Putting-the-Concepts-into-Practice"><a href="#Putting-the-Concepts-into-Practice" class="headerlink" title="Putting the Concepts into Practice"></a>Putting the Concepts into Practice</h2><p>Pick one workflow you would not trust to a polite prompt (a merge, a journal write, a publish) and write this brief before you add a second agent:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line">Grant (agents, tools per agent, permission_mode, max_turns, max_budget_usd):</span><br><span class="line">What is cheaper or safer in isolation (and is therefore a spoke):</span><br><span class="line">What each spoke returns (the handoff object):</span><br><span class="line">What the hub is not allowed to redo:</span><br><span class="line">Hook event + matcher + the arg you will read:</span><br><span class="line">Threshold that denies even if the model wants another hop:</span><br><span class="line">What fail-closed means (do not merge / post / publish X):</span><br><span class="line">When a human is required:</span><br></pre></td></tr></tbody></table></figure><p>Then inspect a real run:</p><ol><li>If you omit <code>Agent</code> from <code>allowed_tools</code> and set <code>dontAsk</code>, does the spawn die instead of the coordinator “just doing the lint”?</li><li>If a spoke has no <code>Write</code>, can it still edit through the parent? (It should not. The tool is missing from that session.)</li><li>If you keep the prompt “never merge over 20 files” and remove the hook, does a 47-file PR still get a <code>merge_pr</code> call?</li><li>If the hook denies, does the audit line say <code>denied</code> and does <code>merge_allowed</code> stay false?</li><li>If you put the parent in <code>bypassPermissions</code>, does the hook still deny? (Official docs: yes. <code>allowed_tools</code> will not save you. The hook will.)</li></ol><p>If you cannot answer those, you have a multi-agent demo, not a grant.</p><h2 id="Key-Terms"><a href="#Key-Terms" class="headerlink" title="Key Terms"></a>Key Terms</h2><ul><li><strong>Bounded autonomy</strong>: The grant of agents, tools, turns, spend, and human pauses. Not a vibe in the prompt</li><li><strong>Guardrail</strong>: A check that holds when the model wants another hop. Permissions, caps, and hooks. Not <code>CLAUDE.md</code></li><li><strong>Hook</strong>: Official callback or command on a lifecycle event (<code>PreToolUse</code>, <code>PostToolUse</code>, and the rest I fetched)</li><li><strong><code>HookMatcher</code></strong>: SDK wrapper. <code>matcher</code> filters the event target (tool name for tool events). <code>hooks</code> is the callback list</li><li><strong><code>permissionDecision</code></strong>: <code>PreToolUse</code> result: <code>"allow"</code>, <code>"deny"</code>, <code>"ask"</code>, <code>"defer"</code></li><li><strong><code>updatedInput</code> / <code>updatedToolOutput</code></strong>: Rewrite the call or the result before Claude sees it</li><li><strong>Permission evaluation order</strong>: Hooks, deny, ask, mode, allow, <code>can_use_tool</code>. Still hooks first on the page I fetched</li><li><strong>Hub-and-spoke</strong>: One coordinator, scoped spokes, structured handoff</li><li><strong><code>Agent</code> tool / <code>agents</code> / <code>AgentDefinition</code></strong>: How the SDK names and invokes a spoke. Older traces used <code>Task</code></li><li><strong><code>maxTurns</code> (spoke) / <code>max_turns</code> (query)</strong>: Hop caps. The model does not get a courtesy extra turn</li><li><strong><code>CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH</code> / <code>CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS</code></strong>: Official tree caps</li><li><strong><code>Workflow</code> tool</strong>: Scripted orchestration for jobs too large for turn-by-turn <code>Agent</code> calls</li><li><strong>Agent teams</strong>: Experimental multi-session teammates. Off by default. Not an SDK headless feature</li><li><strong>Fail closed</strong>: Deny, skip, or escalate when the grant is exceeded. Do not retry a deny into an allow</li></ul><h2 id="Final-Thoughts"><a href="#Final-Thoughts" class="headerlink" title="Final Thoughts"></a>Final Thoughts</h2><p>Eval from <a href="/2026/08/15/evaluation-and-observability-for-claude-agents/">Part 5</a> tells me whether the loop did the job. It does not decide what the loop is allowed to do. That is this post. The model is still the reasoning engine from <a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Part 1</a>. The window is still a budget from <a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a>. The harness is still the runtime from <a href="/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/">Part 3</a>. MCP is still the surface from <a href="/2026/08/15/mcp-and-tool-governance/">Part 4</a>. Guardrails are the last lock: the grant I wrote down, and the hook that holds when the model would rather keep going.</p><p>I do not need more agents. I need a smaller authority, a structured handoff, and a <code>PreToolUse</code> deny that does not care how confident the last sentence sounded.</p><h2 id="References"><a href="#References" class="headerlink" title="References"></a>References</h2><ul><li>AI Engineering with Claude</li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/hooks">Claude Code hooks</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/hooks-guide">Hooks guide</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/hooks">Agent SDK hooks</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/permissions">Permissions</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/subagents">Subagents</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/custom-tools">Custom tools</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/agent-loop">Agent loop</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/sub-agents">Claude Code sub-agents</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/workflows">Dynamic workflows</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-teams">Agent teams</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/permission-modes">Permission modes</a></li></ul><hr><p><em>This is Part 6 of 6 in the Agentic Coding with Claude Code series. Earlier: <a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Part 1</a>, <a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a>, <a href="/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/">Part 3</a>, <a href="/2026/08/15/mcp-and-tool-governance/">Part 4</a>, <a href="/2026/08/15/evaluation-and-observability-for-claude-agents/">Part 5</a>.</em></p></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;p&gt;&lt;a href=&quot;/2026/08/15/evaluation-and-observability-for-claude-agents/&quot;&gt;Part 5&lt;/a&gt; ended with a debt: autonomy I am willing to grant, and guardrails that hold even when the model would rather keep going.&lt;/p&gt;
&lt;p&gt;This is Part 6 of 6 in my &lt;strong&gt;Agentic Coding with Claude Code&lt;/strong&gt; series. The working model I am keeping is simple: eval tells me whether the loop did the job. Guardrails decide what the loop is allowed to do even when the model wants another hop. Bounded autonomy is the grant: which agents, which tools, how many turns, when a human is required.&lt;/p&gt;
&lt;p&gt;This is the series closer. I will not rewrite &lt;a href=&quot;/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/&quot;&gt;Parts 1&lt;/a&gt; through 5. I will bound the loop those posts already built.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="agentic-coding" scheme="https://vanducng.dev/tags/agentic-coding/"/>
    
    <category term="claude-code" scheme="https://vanducng.dev/tags/claude-code/"/>
    
    <category term="agent-sdk" scheme="https://vanducng.dev/tags/agent-sdk/"/>
    
    <category term="hooks" scheme="https://vanducng.dev/tags/hooks/"/>
    
    <category term="orchestration" scheme="https://vanducng.dev/tags/orchestration/"/>
    
    <category term="guardrails" scheme="https://vanducng.dev/tags/guardrails/"/>
    
  </entry>
  
  <entry>
    <title>Evaluation and Observability for Claude Agents</title>
    <link href="https://vanducng.dev/2026/08/15/evaluation-and-observability-for-claude-agents/"/>
    <id>https://vanducng.dev/2026/08/15/evaluation-and-observability-for-claude-agents/</id>
    <published>2026-08-15T08:00:00.000Z</published>
    <updated>2026-11-16T05:26:58.277Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><p><a href="/2026/08/15/mcp-and-tool-governance/">Part 4</a> ended with a debt: whether the loop is actually doing the job. When a skip was correct, when a tool lied, and when the audit trail is the only honest record.</p><p>This is Part 5 of 6 in my <strong>Agentic Coding with Claude Code</strong> series. The working model I am keeping is simple: evaluation is how I score a run. Observability is how I see the run. Structured output is the seam between them.</p><p>A harness that cannot tell success from a polite hallucination is a demo. Later I will talk about bounded autonomy. This one stays on scoring the loop and seeing it.</p><span id="more"></span><h2 id="Silent-Failures-Hide-in-Free-Form-Text"><a href="#Silent-Failures-Hide-in-Free-Form-Text" class="headerlink" title="Silent Failures Hide in Free-Form Text"></a>Silent Failures Hide in Free-Form Text</h2><p><a href="/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/">Part 3</a> already said free-form text is a chat. A harness needs a value it can branch on. I now treat that as an eval problem, not only a parsing problem.</p><p>The failure I keep seeing is not a crash. It is a run that looks finished.</p><table><thead><tr><th>What I see</th><th>What it actually was</th></tr></thead><tbody><tr><td>A paragraph that says “extracted”</td><td>Two required fields were invented</td></tr><tr><td>Schema-valid JSON</td><td>The numbers do not add up, or a field is a guess</td></tr><tr><td><code>action: "skip"</code></td><td>The case needed a human, not a quiet pass</td></tr><tr><td><code>ResultMessage.subtype == "success"</code></td><td>The last text was polite and empty of evidence</td></tr><tr><td>A tool result that looks like <code>ok</code></td><td>The handler returned a plausible row the source never had</td></tr></tbody></table><p><a href="/2026/08/15/mcp-and-tool-governance/">Part 4</a> already wrote result classes (<code>ok</code>, <code>not_found</code>, <code>denied</code>, <code>error</code>) into an append-only audit. That file is not a score. It is the raw material. Evaluation is the next sentence: given this fixture, this trace, and this structured decision, did the agent do the job?</p><p>The takeaway I kept: schema-valid is not truth-valid. A skip can be the right answer. A skip can also be the agent ducking a case it should have escalated. I cannot tell those two apart from prose.</p><h2 id="Structured-Output-Is-the-Contract"><a href="#Structured-Output-Is-the-Contract" class="headerlink" title="Structured Output Is the Contract"></a>Structured Output Is the Contract</h2><p>On the Agent SDK, I pass <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/structured-outputs"><code>output_format</code></a> as <code>{"type": "json_schema", "schema": ...}</code>. TypeScript uses <code>outputFormat</code>. The agent may still use tools. When the loop ends, <code>ResultMessage.structured_output</code> is validated JSON. The SDK validates against JSON Schema draft-07. Zod schemas need <code>target: "draft-7"</code> or the run fails at startup.</p><p>On the Messages API, the equivalent is <a target="_blank" rel="noopener" href="https://platform.claude.com/docs/en/build-with-claude/structured-outputs"><code>output_config.format</code></a> with <code>type: "json_schema"</code>. Same idea: the last text block is parseable JSON matching the schema.</p><p>I treat that object as the contract the harness branches on. I do not treat it as a grade.</p><p>Official result contract I actually check, from the <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/agent-loop#handle-the-result">agent loop</a> and the <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/python#resultmessage">Python <code>ResultMessage</code></a>:</p><table><thead><tr><th><code>ResultMessage.subtype</code></th><th>Official meaning</th><th>What I do before I score</th></tr></thead><tbody><tr><td><code>success</code></td><td>The loop finished</td><td>Use <code>structured_output</code> only if it is present. <code>success</code> with no structured payload is still a failure.</td></tr><tr><td><code>error_max_structured_output_retries</code></td><td>Schema validation never succeeded, or a model fallback retracted the output and no retry replaced it</td><td>Score as a harness failure. Read <code>errors</code> before I blame the schema.</td></tr><tr><td><code>error_max_turns</code></td><td>Hit <code>max_turns</code> (tool-use turns only)</td><td>Incomplete. Do not invent the missing fields.</td></tr><tr><td><code>error_max_budget_usd</code></td><td>Hit <code>max_budget_usd</code></td><td>Same. The spend cap fired.</td></tr><tr><td><code>error_during_execution</code></td><td>The loop broke (API failure, cancel)</td><td>Incomplete. Check <code>errors</code>.</td></tr></tbody></table><p>A single-shot <code>query()</code> then raises a plain <code>Exception</code> after yielding an error result. Wrap the loop. A result can also be <code>success</code> with <code>is_error=True</code> when the last API call failed. I check <code>subtype</code>, then <code>structured_output</code>, then <code>is_error</code>. I do not score <code>result</code> text as if it were the contract.</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-comment"># Sketch. Official fields only. Not a course file.</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">from</span> claude_agent_sdk <span class="hljs-keyword">import</span> query, ClaudeAgentOptions, ResultMessage</span><br><span class="line"></span><br><span class="line">EXTRACT_SCHEMA = {</span><br><span class="line">    <span class="hljs-string">"type"</span>: <span class="hljs-string">"object"</span>,</span><br><span class="line">    <span class="hljs-string">"properties"</span>: {</span><br><span class="line">        <span class="hljs-string">"status"</span>: {</span><br><span class="line">            <span class="hljs-string">"type"</span>: <span class="hljs-string">"string"</span>,</span><br><span class="line">            <span class="hljs-string">"enum"</span>: [<span class="hljs-string">"extracted"</span>, <span class="hljs-string">"incomplete"</span>, <span class="hljs-string">"escalate"</span>],</span><br><span class="line">        },</span><br><span class="line">        <span class="hljs-string">"loan_amount_cents"</span>: {<span class="hljs-string">"type"</span>: [<span class="hljs-string">"integer"</span>, <span class="hljs-string">"null"</span>]},</span><br><span class="line">        <span class="hljs-string">"rate_bps"</span>: {<span class="hljs-string">"type"</span>: [<span class="hljs-string">"integer"</span>, <span class="hljs-string">"null"</span>]},</span><br><span class="line">        <span class="hljs-string">"missing_fields"</span>: {<span class="hljs-string">"type"</span>: <span class="hljs-string">"array"</span>, <span class="hljs-string">"items"</span>: {<span class="hljs-string">"type"</span>: <span class="hljs-string">"string"</span>}},</span><br><span class="line">        <span class="hljs-string">"reason"</span>: {<span class="hljs-string">"type"</span>: <span class="hljs-string">"string"</span>},</span><br><span class="line">    },</span><br><span class="line">    <span class="hljs-string">"required"</span>: [<span class="hljs-string">"status"</span>, <span class="hljs-string">"missing_fields"</span>, <span class="hljs-string">"reason"</span>],</span><br><span class="line">    <span class="hljs-string">"additionalProperties"</span>: <span class="hljs-literal">False</span>,</span><br><span class="line">}</span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">async</span> <span class="hljs-keyword">def</span> <span class="title function_">run_extract</span>(<span class="hljs-params">prompt</span>):</span><br><span class="line">    <span class="hljs-keyword">async</span> <span class="hljs-keyword">for</span> message <span class="hljs-keyword">in</span> query(</span><br><span class="line">        prompt=prompt,</span><br><span class="line">        options=ClaudeAgentOptions(</span><br><span class="line">            output_format={<span class="hljs-string">"type"</span>: <span class="hljs-string">"json_schema"</span>, <span class="hljs-string">"schema"</span>: EXTRACT_SCHEMA},</span><br><span class="line">            max_turns=<span class="hljs-number">12</span>,</span><br><span class="line">        ),</span><br><span class="line">    ):</span><br><span class="line">        <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> <span class="hljs-built_in">isinstance</span>(message, ResultMessage):</span><br><span class="line">            <span class="hljs-keyword">continue</span></span><br><span class="line">        <span class="hljs-keyword">if</span> message.subtype == <span class="hljs-string">"success"</span> <span class="hljs-keyword">and</span> message.structured_output:</span><br><span class="line">            <span class="hljs-keyword">return</span> message</span><br><span class="line">        <span class="hljs-keyword">return</span> <span class="hljs-literal">None</span></span><br></pre></td></tr></tbody></table></figure><p>The schema is allowed to say <code>null</code>. That is the point. A field the document does not contain stays <code>null</code> and lands in <code>missing_fields</code>. Fabricating a rate so the object “looks complete” is the silent failure I am trying to make expensive.</p><p>I use structured output for decisions the harness must act on (<code>extracted</code> / <code>incomplete</code> / <code>escalate</code>). I do not use it for the essay a reviewer reads. The reviewer reads the reason string and the audit.</p><h2 id="What-I-Measure"><a href="#What-I-Measure" class="headerlink" title="What I Measure"></a>What I Measure</h2><p>Course 3’s public syllabus names task completion, quality, and reliability. Those are not SDK field names. They are scores I attach to a run. Official fields I <em>can</em> attach, from <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/python#resultmessage"><code>ResultMessage</code></a> and <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/cost-tracking">cost tracking</a>:</p><table><thead><tr><th>Working-model score</th><th>Question I ask</th><th>Official fields I attach</th></tr></thead><tbody><tr><td><strong>Task completion</strong></td><td>Did the definition of done happen?</td><td><code>subtype</code>, <code>structured_output</code>, <code>stop_reason</code></td></tr><tr><td><strong>Quality</strong></td><td>Was the answer right, not just shaped?</td><td>Fixture gold vs extracted fields. Not an SDK field.</td></tr><tr><td><strong>Tool-use correctness</strong></td><td>Right tool, right args, right result class?</td><td>Audit line from <a href="/2026/08/15/mcp-and-tool-governance/">Part 4</a>. OTEL <code>claude_code.tool</code> spans if I export them.</td></tr><tr><td><strong>System metrics</strong></td><td>How expensive was the path?</td><td><code>num_turns</code>, <code>duration_ms</code>, <code>duration_api_ms</code>, <code>total_cost_usd</code>, <code>usage</code>, <code>model_usage</code></td></tr></tbody></table><p><code>total_cost_usd</code> is a client-side estimate. Official wording: do not bill from it, and do not trigger financial decisions from it. I use it as a budget signal next to <code>max_budget_usd</code>. Authoritative spend lives on Anthropic’s Usage and Cost API, which I am not wrapping here.</p><p><code>usage</code> covers the top-level loop only. Nested work (subagents, compaction) is missing from that dict. For whole-tree tokens I read <code>model_usage</code>. I am not standing up subagents in this post. I still refuse to treat <code>usage</code> as the whole bill.</p><p><code>stop_reason</code> on the result is the same field <a href="/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/">Part 3</a> already branched on (<code>end_turn</code>, <code>tool_use</code>, <code>refusal</code>, and the rest). A <code>refusal</code> is not a quality miss. It is a stop policy. I score it as <code>halted</code>, not as <code>wrong_extract</code>.</p><p>The takeaway I kept: completion without quality is a silent failure. Quality without a trace is a story I cannot replay.</p><h2 id="Response-Step-Trajectory"><a href="#Response-Step-Trajectory" class="headerlink" title="Response, Step, Trajectory"></a>Response, Step, Trajectory</h2><p>I score at three units. The public syllabus names them. The labels below are my working model, not product APIs.</p><table><thead><tr><th>Unit</th><th>What I score</th><th>When it is the right unit</th><th>When it lies</th></tr></thead><tbody><tr><td><strong>Response</strong></td><td>The final <code>structured_output</code> against a gold fixture</td><td>Extraction, a classify, any task whose done-state is one object</td><td>A lucky last object after a bad tool path. Schema-valid and still wrong.</td></tr><tr><td><strong>Step</strong></td><td>One hop: this tool, these args, this result class</td><td>Tool-use correctness, a permission deny, a validator that should have fired</td><td>A perfect hop inside a trajectory that never should have started</td></tr><tr><td><strong>Trajectory</strong></td><td>The whole path: tools, order, skips, retries, final object</td><td>Routing, multi-source fusion, anything where <em>how</em> it got there matters</td><td>Expensive to label. Overfit to one happy path.</td></tr></tbody></table><p>Response eval is cheap. I use it first. If an invented Harbor Credit extractor (below) returns <code>loan_amount_cents: 45000000</code> and the fixture says <code>45000000</code>, the response score passes. It does not tell me the agent called <code>lookup_rate</code> on the wrong product, then “corrected” the math.</p><p>Step eval is the Part 4 audit, scored. Did <code>fetch_doc</code> return <code>ok</code> with the expected fields? Did a deny stay a deny? I write this as assertions on one line, not as a second model.</p><p>Trajectory eval is the unit I reach for when the product is a path. An insurance router that retries a schema miss and then escalates a coverage conflict can have a perfect final object and still be the wrong story if it never opened the human queue. I score the sequence: which tools, which result classes, whether a retry happened, whether the last <code>status</code> matches the policy.</p><pre class="mermaid">flowchart TB    subgraph Path["Trajectory score"]        direction LR        T1[Tools] --&gt; T2[Result classes] --&gt; T3[Retries] --&gt; T4[Final object]    end    subgraph Last["Response score"]        direction LR        R1[Final object] --&gt; R2[Gold fixture]    end    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff    classDef tealClass fill:#16A085,stroke:#333,stroke-width:2px,color:#fff    class T1 blueClass    class T2 tealClass    class T3 purpleClass    class T4 greenClass    class R1,R2 orangeClass</pre><p>Response on the left is the baseline. Trajectory on the right is the score I add when the path is the product. I still keep a response assertion. A beautiful path that fabricates the rate is a fail.</p><h2 id="The-Eval-Loop"><a href="#The-Eval-Loop" class="headerlink" title="The Eval Loop"></a>The Eval Loop</h2><p>I do not have an official Anthropic “eval product” to turn on. What I do have is a working loop I can run in CI, plus official telemetry I can export if I want the same run in a collector.</p><pre class="mermaid">flowchart LR    Fix[Fixture] --&gt; Run[Agent run]    Run --&gt; Trace[Trace + ResultMessage]    Trace --&gt; Score[Score]    Score --&gt; Store[Store]    Store --&gt; Next[Next fixture]    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff    classDef tealClass fill:#16A085,stroke:#333,stroke-width:2px,color:#fff    class Fix blueClass    class Run orangeClass    class Trace purpleClass    class Score greenClass    class Store tealClass    class Next orangeClass</pre><ol><li><strong>Fixture in.</strong> A document (or a stubbed tool result), a gold object, and a policy: extract, skip, or escalate. Invented files. Not production PII.</li><li><strong>Agent run.</strong> <code>query()</code> with <code>output_format</code>, a tight <code>allowed_tools</code> list, <code>permission_mode="dontAsk"</code>, and <code>max_turns</code>.</li><li><strong>Score.</strong> Response assertions on <code>structured_output</code>. Step assertions on the audit. Trajectory assertions when the path matters. System metrics as budgets, not as grades.</li><li><strong>Store.</strong> The fixture id, <code>session_id</code>, <code>subtype</code>, scores, and the audit lines. Append-only, same rule as Part 4.</li></ol><p>The trace is the raw material. I keep two layers, and I do not mix their names.</p><p><strong>Working-model trace</strong> (what I log in my process, every run):</p><table><thead><tr><th>Field</th><th>Why I keep it</th></tr></thead><tbody><tr><td>Tool name and args</td><td>The public API the model actually called</td></tr><tr><td>Result class (<code>ok</code> / <code>not_found</code> / <code>denied</code> / <code>error</code>)</td><td>Part 4’s honest record</td></tr><tr><td><code>stop_reason</code></td><td>Why that turn ended</td></tr><tr><td><code>ResultMessage.subtype</code></td><td>Why the loop ended</td></tr><tr><td><code>structured_output</code></td><td>The contract I scored</td></tr><tr><td><code>num_turns</code>, <code>duration_ms</code>, <code>total_cost_usd</code></td><td>The budget</td></tr></tbody></table><p><strong>Official export</strong> (what the CLI can send if I turn telemetry on):</p><p>The Agent SDK does not emit telemetry itself. It runs the Claude Code CLI as a child process. That CLI can export OpenTelemetry metrics, log events, and (in beta) traces to any OTLP collector. Official page: <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/observability">Agent SDK observability</a>. The catalog of names lives on <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/monitoring-usage">Claude Code monitoring</a>.</p><table><thead><tr><th>Signal</th><th>Official enable</th><th>What I use it for</th></tr></thead><tbody><tr><td>Metrics</td><td><code>CLAUDE_CODE_ENABLE_TELEMETRY=1</code> and <code>OTEL_METRICS_EXPORTER</code></td><td>Token and cost counters (<code>claude_code.token.usage</code>, <code>claude_code.cost.usage</code>)</td></tr><tr><td>Log events</td><td><code>CLAUDE_CODE_ENABLE_TELEMETRY=1</code> and <code>OTEL_LOGS_EXPORTER</code></td><td><code>claude_code.user_prompt</code>, <code>claude_code.api_error</code>, <code>claude_code.tool_result</code>, <code>claude_code.tool_decision</code></td></tr><tr><td>Traces (beta)</td><td><code>CLAUDE_CODE_ENABLE_TELEMETRY=1</code>, <code>OTEL_TRACES_EXPORTER</code>, and <code>CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1</code></td><td>Spans: <code>claude_code.interaction</code>, <code>claude_code.llm_request</code>, <code>claude_code.tool</code>, <code>claude_code.tool.execution</code></td></tr></tbody></table><p>Telemetry is off until I set those variables. I can put them in the process environment or in <code>ClaudeAgentOptions.env</code>. Prompt text and tool bodies stay out of the export unless I opt in (<code>OTEL_LOG_USER_PROMPTS</code>, <code>OTEL_LOG_TOOL_DETAILS</code>, <code>OTEL_LOG_TOOL_CONTENT</code>). I leave those unset on anything that touches documents.</p><p>I do not treat OTEL as the score. A span says a tool ran. It does not say the extract was right. The working-model loop still owns the grade. Official tracing is also labeled beta: span names may change. If the collector is down, the CLI fails silent on export by default. The agent still runs. That is why the append-only audit stays in my process.</p><p><code>session_id</code> on the <code>ResultMessage</code> is how I join a CI fixture to a later replay. Official traces attach a <code>session.id</code> span attribute by default. Claude Code omits it if <code>OTEL_METRICS_INCLUDE_SESSION_ID</code> is falsy.</p><h2 id="Retry-vs-Escalate"><a href="#Retry-vs-Escalate" class="headerlink" title="Retry vs Escalate"></a>Retry vs Escalate</h2><p>The SDK already retries structured-output validation. If the object never matches, I get <code>error_max_structured_output_retries</code>, not a best-effort blob. That is a harness retry. I am not inventing a second retry API on top of it.</p><p>The product question is narrower: which mistakes may the model fix, and which ones must a human see?</p><table><thead><tr><th>Failure class</th><th>Example</th><th>Retry?</th><th>Escalate?</th></tr></thead><tbody><tr><td><strong>Shape miss</strong></td><td>JSON failed the schema</td><td>Yes. The SDK already does this.</td><td>After the retry cap.</td></tr><tr><td><strong>Fixable arithmetic</strong></td><td>Line items do not sum to the stated total</td><td>Yes, once, with the validator error in the next user turn</td><td>If the second pass still disagrees. Do not “correct” the source.</td></tr><tr><td><strong>Transient tool error</strong></td><td>Result class <code>error</code> (timeout, 5xx)</td><td>Yes, once, same args</td><td>If it fails again. Fail closed.</td></tr><tr><td><strong>Honest empty</strong></td><td>Result class <code>not_found</code>, or a required page is missing</td><td>No</td><td><code>incomplete</code> or <code>escalate</code>. Never fill the field.</td></tr><tr><td><strong>Denied call</strong></td><td>Result class <code>denied</code></td><td>No</td><td>Halt the write path. Same as Part 4.</td></tr><tr><td><strong>Conflict</strong></td><td>Two sources disagree on a date or a rate</td><td>No blend</td><td>Annotate both, then <code>escalate</code>.</td></tr><tr><td><strong>Policy / harm</strong></td><td>Fraud language, legal threat, a coverage fight</td><td>No</td><td>Human queue. Do not retry the classify.</td></tr><tr><td><strong>Refusal</strong></td><td><code>stop_reason == "refusal"</code></td><td>Official docs allow a fallback model. I still fail closed on extract.</td><td>Yes. Do not invent a workaround.</td></tr></tbody></table><pre class="mermaid">flowchart TB    Out[structured_output or error subtype] --&gt; Kind{Failure class}    Kind --&gt;|shape / arithmetic / transient| Retry[Retry once]    Retry --&gt; Ok{Valid and consistent?}    Ok --&gt;|yes| Accept[Accept]    Ok --&gt;|no| Human[Escalate]    Kind --&gt;|empty / denied / conflict / policy / refusal| Human    Kind --&gt;|extracted and gold matches| Accept    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef redClass fill:#E74C3C,stroke:#333,stroke-width:2px,color:#fff    classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff    class Out blueClass    class Kind orangeClass    class Retry purpleClass    class Ok orangeClass    class Accept greenClass    class Human redClass</pre><p>Retry is for mistakes the model can see in the next window: a schema error string, a validator diff, a transient <code>error</code> class. Escalate is for missing evidence, a deny, a conflict, or a case I do not want a cheaper model to close. I do not retry a skip into an extract. That is how a silent failure gets a second chance to look like success.</p><h2 id="Three-Small-Analogs"><a href="#Three-Small-Analogs" class="headerlink" title="Three Small Analogs"></a>Three Small Analogs</h2><p>Course 3 trains this on insurance extraction, mortgage documents, and multi-source supply-chain risk. I am not reprinting those pipelines. Invented analogs only. Same fail-closed rule I used on shelfwatch: a skip is better than a blended guess.</p><h3 id="Harbor-Credit-extract-refuse-to-fabricate"><a href="#Harbor-Credit-extract-refuse-to-fabricate" class="headerlink" title="Harbor Credit: extract, refuse to fabricate"></a>Harbor Credit: extract, refuse to fabricate</h3><p>Fictional lender. One messy application packet. The agent may read a stubbed <code>fetch_packet</code> tool and return the schema above.</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">Goal: fill the fields the packet actually states.</span><br><span class="line">Definition of done: status extracted with cents and basis points, or incomplete / escalate.</span><br><span class="line">Fail closed when: a required page is missing, a total does not match the line items,</span><br><span class="line">  or fetch_packet returns not_found / error / denied.</span><br><span class="line">Never: invent a rate, average two disagreeing figures, or coerce a skip into extracted.</span><br></pre></td></tr></tbody></table></figure><p>Fixtures I will actually score (invented):</p><table><thead><tr><th>Fixture</th><th>Gold <code>status</code></th><th>What a silent failure looks like</th></tr></thead><tbody><tr><td>Complete packet, totals match</td><td><code>extracted</code></td><td>Extra fields the page never had</td></tr><tr><td>Rate page missing</td><td><code>incomplete</code>, <code>rate_bps: null</code></td><td>A made-up <code>rate_bps</code> that still schema-validates</td></tr><tr><td>Line items sum to 44900000, header says 45000000</td><td>retry once, then <code>escalate</code></td><td>The model “corrects” the header so the object is clean</td></tr><tr><td><code>fetch_packet</code> denied</td><td><code>escalate</code></td><td>A guessed packet assembled from the prompt</td></tr></tbody></table><p>Response eval catches the invented rate. Step eval catches the deny that was ignored. Trajectory eval catches the “corrected” total: the path had a validator error and still ended <code>extracted</code>.</p><h3 id="Northline-Mutual-retry-the-fixable-escalate-the-rest"><a href="#Northline-Mutual-retry-the-fixable-escalate-the-rest" class="headerlink" title="Northline Mutual: retry the fixable, escalate the rest"></a>Northline Mutual: retry the fixable, escalate the rest</h3><p>Fictional carrier. One inbound policy PDF stub. The harness routes <code>renew</code> / <code>refer</code> / <code>escalate</code>.</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">Goal: a structured route, plus a reason a human can audit.</span><br><span class="line">Retry when: schema miss, one arithmetic mismatch, one transient tool error.</span><br><span class="line">Escalate when: coverage language conflicts, a missing declarations page,</span><br><span class="line">  fraud or legal wording, or the retry cap fires.</span><br><span class="line">Do not retry a refer into a renew.</span><br></pre></td></tr></tbody></table></figure><p>The structured object is the route. The score is whether the route matches the fixture policy, and whether a retry happened only on the allowed classes. A trajectory that retries a coverage conflict is a fail even if the last object says <code>escalate</code>.</p><h3 id="Keel-Freight-fuse-evidence-keep-provenance"><a href="#Keel-Freight-fuse-evidence-keep-provenance" class="headerlink" title="Keel Freight: fuse evidence, keep provenance"></a>Keel Freight: fuse evidence, keep provenance</h3><p>Fictional briefing. Four disagreeing stubs: carrier ETA, warehouse scan, weather bulletin, customs hold.</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line">Goal: one briefing object with one row per source, plus a conflicts list.</span><br><span class="line">Definition of done: every source is present or marked failed, conflicts are named,</span><br><span class="line">  escalate_on is filled when two timestamps or two risk flags disagree.</span><br><span class="line">Never: average ETAs, drop a failed source, or emit a single "most likely" date.</span><br></pre></td></tr></tbody></table></figure><p>Provenance is a field, not a paragraph. Each row keeps <code>source</code>, <code>observed_at</code>, and <code>value</code>. The conflicts array points at the two rows. If customs is down, that row is <code>error</code> and the briefing still ships. The silent failure here is a blended Wednesday that no source stated.</p><p>Quality on this analog is not “did we pick the right date.” It is “did we refuse to pick.” Trajectory eval asks whether a failed source stayed visible.</p><h2 id="Putting-the-Concepts-into-Practice"><a href="#Putting-the-Concepts-into-Practice" class="headerlink" title="Putting the Concepts into Practice"></a>Putting the Concepts into Practice</h2><p>Pick one workflow that already emits a decision (extract, route, a briefing) and write this brief before you add a score:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line">Definition of done (the structured object):</span><br><span class="line">Gold fixtures (happy, missing field, conflict, deny, transient error):</span><br><span class="line">Response assertions (fields that must match, fields that must stay null):</span><br><span class="line">Step assertions (tool, args shape, result class):</span><br><span class="line">Trajectory assertions (allowed retries, required escalate):</span><br><span class="line">Budgets (max_turns, max_budget_usd, duration_ms you will page on):</span><br><span class="line">What you will log (audit line + ResultMessage fields):</span><br><span class="line">What you will export (OTEL off, metrics only, or traces beta):</span><br><span class="line">What fail-closed means (do not guess X):</span><br></pre></td></tr></tbody></table></figure><p>Then inspect a real run:</p><ol><li>Is <code>structured_output</code> present on <code>subtype == "success"</code>, or did you score <code>result</code> text?</li><li>Did any fixture pass response eval and fail step eval (wrong tool, ignored deny)?</li><li>Did a schema-valid object invent a field the source never had?</li><li>If you force <code>not_found</code> on the only evidence tool, does the status become <code>incomplete</code> or <code>escalate</code> instead of a guess?</li><li>If traces (beta) are on, does a <code>claude_code.tool</code> span exist for every audit line? Metrics or log events alone will not emit that span. If a span is missing, trust the audit.</li></ol><p>If you cannot answer those, you have a typed demo, not an evaluated agent.</p><h2 id="Key-Terms"><a href="#Key-Terms" class="headerlink" title="Key Terms"></a>Key Terms</h2><ul><li><strong>Evaluation</strong>: How I score a run against a fixture and a policy</li><li><strong>Observability</strong>: How I see a run: the working-model audit, <code>ResultMessage</code> fields, and optional OTEL export</li><li><strong>Silent failure</strong>: A finished-looking run that skipped, guessed, or blended when it should have stopped</li><li><strong><code>output_format</code> / <code>outputFormat</code></strong>: Agent SDK knob. <code>{"type": "json_schema", "schema": ...}</code>. Draft-07.</li><li><strong><code>output_config.format</code></strong>: Messages API equivalent</li><li><strong><code>structured_output</code></strong>: Validated JSON on a successful <code>ResultMessage</code>. Absent means do not branch.</li><li><strong><code>ResultMessage.subtype</code></strong>: <code>success</code>, <code>error_max_turns</code>, <code>error_max_budget_usd</code>, <code>error_during_execution</code>, <code>error_max_structured_output_retries</code></li><li><strong><code>num_turns</code> / <code>duration_ms</code> / <code>total_cost_usd</code></strong>: Official system metrics on the result. <code>total_cost_usd</code> is a client-side estimate.</li><li><strong>Response / step / trajectory</strong>: Working-model eval units. Final object, one hop, or the whole path.</li><li><strong>Working-model trace</strong>: Tool name, args, result class, <code>stop_reason</code>, <code>structured_output</code></li><li><strong>OTEL export</strong>: Official CLI telemetry (<code>CLAUDE_CODE_ENABLE_TELEMETRY</code>). Traces are beta (<code>CLAUDE_CODE_ENHANCED_TELEMETRY_BETA</code>).</li><li><strong><code>claude_code.interaction</code> / <code>claude_code.llm_request</code> / <code>claude_code.tool</code></strong>: Official span names when traces are on</li><li><strong>Retry vs escalate</strong>: Fixable mistakes go back to the model once. Missing evidence, denies, conflicts, and policy cases go to a human.</li><li><strong>Fail closed</strong>: Skip, mark incomplete, or escalate when evidence is missing. Do not guess.</li><li><strong>Provenance</strong>: Keep the source next to the value. Do not blend disagreements into one number.</li></ul><h2 id="Final-Thoughts"><a href="#Final-Thoughts" class="headerlink" title="Final Thoughts"></a>Final Thoughts</h2><p>The model is still the reasoning engine from <a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Part 1</a>. The harness is still the runtime from <a href="/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/">Part 3</a>. MCP is still the governed surface from <a href="/2026/08/15/mcp-and-tool-governance/">Part 4</a>. None of that tells me the loop did the job.</p><p>Structured output is the seam: the object I branch on, and the object I score. Observability is the audit plus, if I opt in, official OTEL spans. Evaluation is the fixture, the three units, and the retry-versus-escalate rule. Schema-valid JSON that is still wrong is the failure mode I now look for first.</p><p>The next post moves from scoring the loop to bounding it: autonomy I am willing to grant, and guardrails that hold even when the model would rather keep going.</p><h2 id="References"><a href="#References" class="headerlink" title="References"></a>References</h2><ul><li>AI Engineering with Claude</li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/structured-outputs">Agent SDK structured outputs</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/agent-loop">Agent loop</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/python#resultmessage">Python ResultMessage</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/cost-tracking">Cost tracking</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/observability">Agent SDK observability</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/monitoring-usage">Claude Code monitoring</a></li><li><a target="_blank" rel="noopener" href="https://platform.claude.com/docs/en/build-with-claude/structured-outputs">Platform structured outputs</a></li><li><a target="_blank" rel="noopener" href="https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons">Stop reasons</a></li><li><a target="_blank" rel="noopener" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview">Tool use</a></li></ul><hr><p><em>This is Part 5 of 6 in the Agentic Coding with Claude Code series. Earlier: <a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Part 1</a>, <a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a>, <a href="/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/">Part 3</a>, <a href="/2026/08/15/mcp-and-tool-governance/">Part 4</a>.</em></p></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;p&gt;&lt;a href=&quot;/2026/08/15/mcp-and-tool-governance/&quot;&gt;Part 4&lt;/a&gt; ended with a debt: whether the loop is actually doing the job. When a skip was correct, when a tool lied, and when the audit trail is the only honest record.&lt;/p&gt;
&lt;p&gt;This is Part 5 of 6 in my &lt;strong&gt;Agentic Coding with Claude Code&lt;/strong&gt; series. The working model I am keeping is simple: evaluation is how I score a run. Observability is how I see the run. Structured output is the seam between them.&lt;/p&gt;
&lt;p&gt;A harness that cannot tell success from a polite hallucination is a demo. Later I will talk about bounded autonomy. This one stays on scoring the loop and seeing it.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="evaluation" scheme="https://vanducng.dev/tags/evaluation/"/>
    
    <category term="observability" scheme="https://vanducng.dev/tags/observability/"/>
    
    <category term="agentic-coding" scheme="https://vanducng.dev/tags/agentic-coding/"/>
    
    <category term="claude-code" scheme="https://vanducng.dev/tags/claude-code/"/>
    
    <category term="agent-sdk" scheme="https://vanducng.dev/tags/agent-sdk/"/>
    
  </entry>
  
  <entry>
    <title>MCP and Tool Governance</title>
    <link href="https://vanducng.dev/2026/08/15/mcp-and-tool-governance/"/>
    <id>https://vanducng.dev/2026/08/15/mcp-and-tool-governance/</id>
    <published>2026-08-15T06:00:00.000Z</published>
    <updated>2026-11-16T05:26:58.281Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><p><a href="/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/">Part 3</a> ended with a debt: tools that live outside the process, MCP servers, how they enter the window, and how to keep that surface small.</p><p>This is Part 4 of 6 in my <strong>Agentic Coding with Claude Code</strong> series. The working model I am keeping is simple: the model still reasons. The harness still decides. MCP is how tools and context live <em>outside</em> the process and still enter the window as a governed surface.</p><p>Later posts will cover evaluation and observability, then bounded autonomy. This one stays on the MCP boundary.</p><span id="more"></span><h2 id="Why-the-Split-Matters"><a href="#Why-the-Split-Matters" class="headerlink" title="Why the Split Matters"></a>Why the Split Matters</h2><p><a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Part 1</a> treated tools as the agent’s public API. <a href="/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/">Part 3</a> put that API inside a harness I own: <code>allowed_tools</code>, <code>disallowed_tools</code>, <code>permission_mode</code>. Those knobs still apply. MCP adds a second address: the tool or the file does not have to live in my process.</p><p>Official <a target="_blank" rel="noopener" href="https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture">architecture</a> names three roles. I kept the split because it is the reason I can add a scraper without rewriting the agent.</p><table><thead><tr><th>Role</th><th>Official job</th><th>Why I care</th></tr></thead><tbody><tr><td><strong>Host</strong></td><td>The AI application that coordinates one or more MCP clients (Claude Code, the Agent SDK process, an IDE)</td><td>One product, many servers. The host owns the window, permissions, and the loop.</td></tr><tr><td><strong>Client</strong></td><td>The connector the host instantiates <em>per server</em></td><td>Not a second agent. A dedicated connection. One client, one server.</td></tr><tr><td><strong>Server</strong></td><td>A program that exposes tools, resources, and prompts</td><td>The capability lives here. Local stdio or remote HTTP. Same JSON-RPC either way.</td></tr></tbody></table><p>One host. Many servers. The client is the connector inside the host, not a chat partner. If I collapse those three into “the MCP,” I lose the place where governance actually sits: the host decides which servers exist, which tools from those servers enter the window, and which calls run.</p><pre class="mermaid">flowchart TB    Host["Host: Claude Code / Agent SDK"]    Host --&gt; C1[Client: scraper]    Host --&gt; C2[Client: catalog]    Host --&gt; C3[Client: docs]    C1 --&gt; S1[Scraper server]    C2 --&gt; S2[Catalog server]    C3 --&gt; S3[Remote docs server]    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff    classDef tealClass fill:#16A085,stroke:#333,stroke-width:2px,color:#fff    class Host blueClass    class C1,C2,C3 orangeClass    class S1 greenClass    class S2 purpleClass    class S3 tealClass</pre><p>MCP’s <a target="_blank" rel="noopener" href="https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture#data-layer">data layer</a> is JSON-RPC. The <a target="_blank" rel="noopener" href="https://blog.modelcontextprotocol.io/posts/2026-07-28/">2026-07-28 spec</a> made that layer stateless: each request carries version and capabilities in <code>_meta</code>, and a client that wants the catalog up front calls <code>server/discover</code>. I treat that as infrastructure. The product question is still: what from those servers is allowed to occupy the window?</p><h2 id="Server-Primitives-Tools-Resources-Prompts"><a href="#Server-Primitives-Tools-Resources-Prompts" class="headerlink" title="Server Primitives: Tools, Resources, Prompts"></a>Server Primitives: Tools, Resources, Prompts</h2><p><a target="_blank" rel="noopener" href="https://modelcontextprotocol.io/docs/2026-07-28/learn/server-concepts">Server concepts</a> give servers three building blocks. Who <em>controls</em> each one is the useful column.</p><table><thead><tr><th>Primitive</th><th>Who controls it</th><th>Protocol ops I actually use</th><th>When I use it</th><th>When I do not</th></tr></thead><tbody><tr><td><strong>Tools</strong></td><td>Model</td><td><code>tools/list</code>, <code>tools/call</code></td><td>An action: scrape a shelf, look up a SKU, write a row</td><td>Read-only context the host should attach itself</td></tr><tr><td><strong>Resources</strong></td><td>Application (the host)</td><td><code>resources/list</code>, <code>resources/read</code></td><td>A schema, a snapshot, a file the host chooses to load</td><td>Anything with a side effect</td></tr><tr><td><strong>Prompts</strong></td><td>User</td><td><code>prompts/list</code>, <code>prompts/get</code></td><td>A named template: “reconcile this aisle”</td><td>Hidden policy. Policy is a permission rule.</td></tr></tbody></table><p>Tools are model-invoked. The model sees the name, the description, and the <code>inputSchema</code>, then returns a <code>tool_use</code> the way <a href="/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/">Part 3</a> already described. The host still runs or denies the call.</p><p>Resources are read-only context. The host (not the model) decides whether to fetch <code>resources/read</code> and paste the bytes into the window. A catalog schema is a resource. A “delete this SKU” endpoint is a tool.</p><p>Prompts are templates the user (or a slash command) invokes. They are not a second system prompt I hope the model obeys.</p><p>They all cost tokens. <code>tools/list</code> is not free metadata. Every tool name and description sits in the working set before the first user sentence. A fat catalog is a <a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a> context bug at the MCP boundary: the model is already paying for tools it will never need.</p><pre class="mermaid">flowchart TB    subgraph Small["Small surface"]        direction LR        A1[2 servers] --&gt; B1[4 tools] --&gt; C1[Trimmed results]    end    subgraph Fat["Fat tools/list"]        direction LR        A2[8 servers] --&gt; B2[60 tools] --&gt; C2[Raw dumps]    end    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef redClass fill:#E74C3C,stroke:#333,stroke-width:2px,color:#fff    class A1,B1,C1 greenClass    class A2,B2 orangeClass    class C2 redClass</pre><p>Official <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/mcp#mcp-tool-search">Agent SDK MCP</a> docs already treat this as a known tax. <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/tool-search">Tool search</a> withholds unused definitions and loads the ones the turn needs. That is a safety net, the same way Claude Code’s bash output cap is a safety net. I still keep the catalog small. Tool search does not fix a server that exposes thirty overlapping verbs.</p><h2 id="Client-Features-I-Will-Name"><a href="#Client-Features-I-Will-Name" class="headerlink" title="Client Features I Will Name"></a>Client Features I Will Name</h2><p>The public Course 2 syllabus names client features including roots, sampling, and elicitation. Current <a target="_blank" rel="noopener" href="https://modelcontextprotocol.io/docs/2026-07-28/learn/client-concepts">client concepts</a> still list all three. Roots and sampling are <a target="_blank" rel="noopener" href="https://modelcontextprotocol.io/specification/2026-07-28/deprecated">deprecated</a> as of protocol version <code>2026-07-28</code>. New implementations should not adopt them. Earliest removal is the first spec revision on or after 2027-07-28. The <a target="_blank" rel="noopener" href="https://blog.modelcontextprotocol.io/posts/2026-07-28/">spec notes</a> still say they work during that window.</p><table><thead><tr><th>Feature</th><th>What it was for</th><th>What I do instead</th></tr></thead><tbody><tr><td><strong>Roots</strong></td><td>The client tells the server which <code>file://</code> directories to focus on. Advisory, not a lock. The spec says servers SHOULD respect roots, not MUST enforce them.</td><td>Pass the directory as a tool argument, a resource URI, or server config. <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/mcp">Claude Code</a> still answers <code>roots/list</code> with the launch directory plus <code>--add-dir</code> / <code>additionalDirectories</code>. I do not treat that reply as a sandbox.</td></tr><tr><td><strong>Sampling</strong></td><td>The server asks the host’s model to complete a prompt (<code>sampling/createMessage</code>) so the server stays model-agnostic.</td><td>Call the Messages API from my process. The host already owns model choice and spend.</td></tr></tbody></table><p>Elicitation is the live client primitive (a server asking the user for input mid-call via <a target="_blank" rel="noopener" href="https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr">MRTR</a>). I am not covering it here. The takeaway I kept for roots and sampling: they were coordination, not governance. A root is a hint. A sample is a nested model call I did not budget. Neither one is an allow list.</p><h2 id="Transports-High-Level"><a href="#Transports-High-Level" class="headerlink" title="Transports, High Level"></a>Transports, High Level</h2><p>The <a target="_blank" rel="noopener" href="https://modelcontextprotocol.io/specification/2026-07-28/basic/transports">transport binding</a> does not change the messages. It changes how they are framed.</p><table><thead><tr><th>Transport</th><th>Official shape</th><th>When I use it</th></tr></thead><tbody><tr><td><strong>stdio</strong></td><td>Client launches a subprocess. Newline-delimited JSON-RPC on stdin/stdout.</td><td>A local server I trust on this machine: a catalog process, a scraper I wrote.</td></tr><tr><td><strong>Streamable HTTP</strong></td><td>HTTP POST to one MCP endpoint. Reply is JSON or a request-scoped SSE stream.</td><td>A remote server. Claude Code and the Agent SDK call this <code>type: "http"</code>. In <code>.mcp.json</code>, <code>streamable-http</code> is an alias for <code>http</code>.</td></tr></tbody></table><p><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/mcp">Claude Code</a> still accepts <code>sse</code> for services that have not moved, and documents it as deprecated. HTTP+SSE is on the spec deprecation list. I do not pick SSE for new work.</p><p>I am not walking connection exploits or auth bypasses. The only operational note I kept: a <code>.mcp.json</code> entry with a <code>url</code> and no <code>type</code> is a config error. Claude Code reads a typeless entry as stdio, skips it, and reports that the server has a URL but no type.</p><h2 id="Wiring-MCP-into-Claude-Code-and-the-Agent-SDK"><a href="#Wiring-MCP-into-Claude-Code-and-the-Agent-SDK" class="headerlink" title="Wiring MCP into Claude Code and the Agent SDK"></a>Wiring MCP into Claude Code and the Agent SDK</h2><p>In Claude Code, a server is configuration. <code>claude mcp add</code> writes it. Scope decides who else sees it.</p><table><thead><tr><th>Scope</th><th>Where it lives</th><th>Who it is for</th></tr></thead><tbody><tr><td><strong>local</strong></td><td><code>~/.claude.json</code>, under this project’s path</td><td>Default for <code>claude mcp add</code>. Private to this project.</td></tr><tr><td><strong>user</strong></td><td><code>~/.claude.json</code>, top-level <code>mcpServers</code></td><td>Every project on this laptop. Still private to you.</td></tr><tr><td><strong>project</strong></td><td><code>.mcp.json</code> in the repo</td><td>The team. First interactive session asks you to approve it so a clone cannot launch processes without consent.</td></tr></tbody></table><p><code>claude mcp list</code> and <code>/mcp</code> are how I check health (<code>Connected</code>, <code>Needs authentication</code>, <code>Failed to connect</code>, <code>Pending approval</code>). Headless <code>claude -p</code> and Agent SDK sessions cannot show that approval prompt. Project servers load without asking unless I put the name in <code>disabledMcpjsonServers</code> or drop project settings with <code>--setting-sources</code> / <code>setting_sources</code>.</p><p>In the Agent SDK, the same servers are a field on <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/mcp"><code>ClaudeAgentOptions</code></a>: <code>mcp_servers</code> in Python, <code>mcpServers</code> in TypeScript. I can pass them in code or load <code>.mcp.json</code> when the <code>project</code> setting source is on.</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">from</span> claude_agent_sdk <span class="hljs-keyword">import</span> ClaudeAgentOptions</span><br><span class="line"></span><br><span class="line">options = ClaudeAgentOptions(</span><br><span class="line">    mcp_servers={</span><br><span class="line">        <span class="hljs-string">"scraper"</span>: {</span><br><span class="line">            <span class="hljs-string">"command"</span>: <span class="hljs-string">"python"</span>,</span><br><span class="line">            <span class="hljs-string">"args"</span>: [<span class="hljs-string">"servers/scraper.py"</span>],</span><br><span class="line">        },</span><br><span class="line">        <span class="hljs-string">"catalog"</span>: {</span><br><span class="line">            <span class="hljs-string">"type"</span>: <span class="hljs-string">"http"</span>,</span><br><span class="line">            <span class="hljs-string">"url"</span>: <span class="hljs-string">"https://catalog.example.invalid/mcp"</span>,</span><br><span class="line">        },</span><br><span class="line">    },</span><br><span class="line">    allowed_tools=[</span><br><span class="line">        <span class="hljs-string">"mcp__scraper__fetch_shelf"</span>,</span><br><span class="line">        <span class="hljs-string">"mcp__catalog__lookup_sku"</span>,</span><br><span class="line">    ],</span><br><span class="line">    disallowed_tools=[<span class="hljs-string">"Bash"</span>],</span><br><span class="line">    permission_mode=<span class="hljs-string">"dontAsk"</span>,</span><br><span class="line">)</span><br></pre></td></tr></tbody></table></figure><p>That snippet is a sketch, not a product, and not a course file. Official names only: <code>mcp_servers</code>, <code>allowed_tools</code>, <code>disallowed_tools</code>, <code>permission_mode</code>.</p><p>Custom tools I write in-process are still MCP. <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/custom-tools"><code>create_sdk_mcp_server</code></a> / <code>createSdkMcpServer</code> wraps <code>@tool</code> / <code>tool()</code> handlers. The key in <code>mcp_servers</code> becomes the server segment of the fully qualified name: <code>mcp__{server}__{tool}</code>. List that name in <code>allowed_tools</code> or the model can see the tool and still not be allowed to call it.</p><p>MCP tools require explicit permission. Official wording: without it, Claude sees the tools and will not call them.</p><h3 id="Governance-Is-Not-Prompt-Text"><a href="#Governance-Is-Not-Prompt-Text" class="headerlink" title="Governance Is Not Prompt Text"></a>Governance Is Not Prompt Text</h3><p><a href="/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/">Part 3</a> said <code>CLAUDE.md</code> is guidance. The same sentence applies to MCP. “Please only use the catalog lookup” is a prompt. <code>allowed_tools=["mcp__catalog__lookup_sku"]</code> plus <code>permission_mode="dontAsk"</code> is a rule.</p><p>The SDK still evaluates <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/permissions#how-permissions-are-evaluated">permissions in a fixed order</a>: hooks, deny, ask, the active mode, allow, then <code>can_use_tool</code>. I am not writing hooks in this post. The MCP-specific facts I fetched:</p><table><thead><tr><th>Knob</th><th>Official field</th><th>What it does to MCP</th></tr></thead><tbody><tr><td><strong>Allow list</strong></td><td><code>allowed_tools</code> / <code>allowedTools</code></td><td>Auto-approves listed tools. MCP names are <code>mcp__server__tool</code>. A per-server wildcard is <code>mcp__scraper__*</code>. An unanchored <code>*</code> or <code>mcp__*</code> in the allow list is ignored.</td></tr><tr><td><strong>Deny list</strong></td><td><code>disallowed_tools</code> / <code>disallowedTools</code></td><td>A bare name (<code>Bash</code>, or <code>mcp__scraper__fetch_shelf</code>) removes the tool from the window. <code>mcp__*</code> removes every MCP tool from context. A scoped deny keeps the tool visible and blocks the pattern in every mode, including <code>bypassPermissions</code>.</td></tr><tr><td><strong>Mode</strong></td><td><code>permission_mode</code></td><td><code>acceptEdits</code> does <strong>not</strong> auto-approve MCP tools. <code>bypassPermissions</code> does, and also disables most other prompts. Official guidance: prefer <code>allowed_tools</code> over a mode for MCP access.</td></tr><tr><td><strong>Locked headless</strong></td><td><code>dontAsk</code> + allow list</td><td>Listed MCP tools run, except a tool the server marks <code>_meta["anthropic/requiresUserInteraction"]</code> (that mode never prompts, so those calls deny). Everything else is denied. Pair this when I ship a fixed surface.</td></tr><tr><td><strong>Availability vs permission</strong></td><td><code>tools</code> vs <code>allowed_tools</code></td><td><code>tools: ["Read", "Grep"]</code> drops unlisted <em>built-ins</em> from context. MCP tools are unaffected. <code>tools: []</code> removes built-ins so only MCP remains.</td></tr></tbody></table><p><code>allowed_tools</code> still does not constrain <code>bypassPermissions</code>. Listing <code>mcp__catalog__lookup_sku</code> and then setting bypass still approves <code>Bash</code>. For a locked-down analyst, I pair the allow list with <code>dontAsk</code> and I put writes on the deny list.</p><p>The description on each tool is still the prompt, the way <a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a> said. On the wire, an MCP tool advertises <code>name</code>, <code>description</code>, and <code>inputSchema</code>. The handler returns <code>content</code>. The spec result may also set <code>structuredContent</code> and <code>isError</code>. On the Agent SDK, TypeScript handlers use <code>isError</code>; the Python <code>@tool</code> decorator forwards <code>content</code> and <code>is_error</code> only. To return <code>structuredContent</code> from Python I need a standalone server, not the in-process decorator.</p><h2 id="Keep-the-Surface-Small"><a href="#Keep-the-Surface-Small" class="headerlink" title="Keep the Surface Small"></a>Keep the Surface Small</h2><p>The trim rule from <a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a> moves to the MCP boundary. If <code>fetch_shelf</code> returns a raw HTML dump, every later turn pays for it. If <code>lookup_sku</code> returns the whole commerce row, the next reason step is already working from noise.</p><p>The contract I keep, in-process or over MCP:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">Name: the verb the model should think</span><br><span class="line">When to use / when not to use</span><br><span class="line">Inputs: required vs optional, units, invariants</span><br><span class="line">Output: the fields the next turn will read</span><br><span class="line">Failure: not_found, denied, or error; never a guess</span><br></pre></td></tr></tbody></table></figure><p>A working checklist:</p><ol><li><strong>Few servers.</strong> One job per server. A scraper that also writes the catalog will fight the catalog server.</li><li><strong>Few tools.</strong> If two tools both “get a price,” they will race. Say so in both descriptions, or delete one.</li><li><strong>Tight descriptions.</strong> When to use, when not to, what empty means. Newer models explore less when I over-specify the happy path. They still need the overlap called out.</li><li><strong>Trimmed results.</strong> Return <code>sku</code>, <code>price_cents</code>, <code>currency</code>, <code>observed_at</code>. Not the page. The MCP spec lets a tool set <code>outputSchema</code> and <code>structuredContent</code>. I use that (on a standalone server, or in TypeScript) so the next turn reads fields, not prose.</li><li><strong>Deny lists.</strong> If a server ships a <code>write_*</code> tool I do not want, deny it by name so it never enters the window.</li><li><strong>Scoped config.</strong> Project <code>.mcp.json</code> for the team surface. User scope for my laptop experiments. <code>disabledMcpjsonServers</code> for a server I will not load in CI.</li></ol><p>A fat <code>tools/list</code> is the failure mode I now look for first. It is cheaper to delete a tool than to ask the model to ignore it.</p><h2 id="An-Audited-Agent-Loop"><a href="#An-Audited-Agent-Loop" class="headerlink" title="An Audited Agent Loop"></a>An Audited Agent Loop</h2><p>This is not the observability post. I am not standing up traces or evals. I want an append-only record of what crossed the MCP boundary so I can answer four questions after a run: which server, which tool, which args, which result class.</p><p>Result classes I will write, not SDK field names:</p><table><thead><tr><th>Class</th><th>Meaning</th></tr></thead><tbody><tr><td><code>ok</code></td><td>Handler returned the expected fields</td></tr><tr><td><code>not_found</code></td><td>The SKU or shelf does not exist. Not a guess.</td></tr><tr><td><code>denied</code></td><td>The harness blocked the call (deny rule, <code>dontAsk</code>, missing allow)</td></tr><tr><td><code>error</code></td><td>Transport failed, schema failed, or the server set <code>isError: true</code></td></tr></tbody></table><p>The record is append-only. I do not update a row to make the story nicer. A later compact can squeeze the conversation. The audit file still has the call.</p><pre class="mermaid">flowchart TB    Model[Model returns tool_use] --&gt; Gate{Allow or deny}    Gate --&gt;|denied| Audit1[Append: denied]    Audit1 --&gt; Result1[tool_result: denied]    Gate --&gt;|allowed| Call[Call MCP server]    Call --&gt; Class{Result class}    Class --&gt;|ok / not_found / error| Trim[Trim to contract fields]    Trim --&gt; Audit2[Append: server, tool, args, class]    Audit2 --&gt; Result2[tool_result into the window]    Result1 --&gt; Loop[Next turn]    Result2 --&gt; Loop    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff    classDef tealClass fill:#16A085,stroke:#333,stroke-width:2px,color:#fff    classDef redClass fill:#E74C3C,stroke:#333,stroke-width:2px,color:#fff    class Model blueClass    class Gate orangeClass    class Call purpleClass    class Class tealClass    class Trim greenClass    class Audit1,Audit2 orangeClass    class Result1,Result2 greenClass    class Loop redClass</pre><p>The harness already owns this dispatch. MCP does not change the <code>stop_reason == "tool_use"</code> branch. It changes <em>where</em> the function runs. The audit line is how I keep that hop inspectable without turning this post into a metrics stack.</p><h2 id="Shelfwatch-Gather-Reconcile-Reason"><a href="#Shelfwatch-Gather-Reconcile-Reason" class="headerlink" title="Shelfwatch: Gather, Reconcile, Reason"></a>Shelfwatch: Gather, Reconcile, Reason</h2><p>Course 2 trains this on PriceScout: an agentic analyst over a custom scraper and a database server. I am not reprinting their starter files. Invented analog: <strong>shelfwatch</strong>, a small watcher for a fictional grocer (Northbridge Market) that checks a fictional competitor (Harbor Pantry) for shelf prices on a short list of SKUs.</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line">Goal: say whether Harbor's shelf price for a SKU moved, with evidence.</span><br><span class="line">Definition of done: a structured note per SKU, or a fail-closed skip.</span><br><span class="line">Gather: scrape the competitor shelf, look up our catalog row.</span><br><span class="line">Reconcile: same SKU, same currency, fresh enough timestamp.</span><br><span class="line">Reason: moved / unchanged / skip. Never invent a price.</span><br><span class="line">Stop and skip when: the scrape is malformed, the catalog misses the SKU,</span><br><span class="line">  the currencies disagree, or the harness denied a call.</span><br></pre></td></tr></tbody></table></figure><p>Two servers, four tools. Intentionally small.</p><table><thead><tr><th>Server</th><th>Tool</th><th>Returns</th><th>When not to use</th></tr></thead><tbody><tr><td><code>scraper</code></td><td><code>fetch_shelf</code></td><td><code>sku</code>, <code>price_cents</code>, <code>currency</code>, <code>observed_at</code>, <code>shelf</code></td><td>You already have today’s observation; use the catalog</td></tr><tr><td><code>scraper</code></td><td><code>list_aisle</code></td><td><code>sku</code> list for one aisle</td><td>You already know the SKU</td></tr><tr><td><code>catalog</code></td><td><code>lookup_sku</code></td><td><code>sku</code>, <code>our_price_cents</code>, <code>currency</code>, <code>name</code></td><td>You are asking Harbor’s price; that is <code>fetch_shelf</code></td></tr><tr><td><code>catalog</code></td><td><code>record_observation</code></td><td><code>observation_id</code></td><td>Any field is missing or the result class is not <code>ok</code></td></tr></tbody></table><p>Each result is a handful of fields. <code>fetch_shelf</code> does not return the page. That is the Part 2 trim rule, implemented at the MCP handler.</p><p>The allow list is the product surface:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-comment"># Sketch. Official fields only. Not a course file.</span></span><br><span class="line">options = ClaudeAgentOptions(</span><br><span class="line">    mcp_servers={</span><br><span class="line">        <span class="hljs-string">"scraper"</span>: scraper_server,   <span class="hljs-comment"># create_sdk_mcp_server(...) or stdio</span></span><br><span class="line">        <span class="hljs-string">"catalog"</span>: catalog_server,</span><br><span class="line">    },</span><br><span class="line">    allowed_tools=[</span><br><span class="line">        <span class="hljs-string">"mcp__scraper__fetch_shelf"</span>,</span><br><span class="line">        <span class="hljs-string">"mcp__scraper__list_aisle"</span>,</span><br><span class="line">        <span class="hljs-string">"mcp__catalog__lookup_sku"</span>,</span><br><span class="line">        <span class="hljs-string">"mcp__catalog__record_observation"</span>,</span><br><span class="line">    ],</span><br><span class="line">    disallowed_tools=[<span class="hljs-string">"Bash"</span>, <span class="hljs-string">"mcp__catalog__delete_sku"</span>],</span><br><span class="line">    permission_mode=<span class="hljs-string">"dontAsk"</span>,</span><br><span class="line">)</span><br></pre></td></tr></tbody></table></figure><p>If the catalog server also exposes <code>delete_sku</code>, the deny list keeps it out of the window. The model should not have to “be careful.”</p><p>Malformed and misbehaving results are the point of the exercise. Invented cases I will actually test:</p><table><thead><tr><th>What comes back</th><th>Result class</th><th>What the harness does</th></tr></thead><tbody><tr><td><code>{sku, price_cents, currency, observed_at}</code></td><td><code>ok</code></td><td>Trim (already small), audit, reason</td></tr><tr><td>Empty body, or SKU not on the shelf</td><td><code>not_found</code></td><td>Audit, skip that SKU, do not invent a price</td></tr><tr><td>HTML, a string price (<code>"$3.49"</code>), missing currency</td><td><code>error</code></td><td>Audit, skip. Fail closed.</td></tr><tr><td><code>isError: true</code> from the server</td><td><code>error</code></td><td>Same. The model sees the error text, not a guessed number.</td></tr><tr><td><code>lookup_sku</code> denied by config</td><td><code>denied</code></td><td>Halt the write path. Do not record an observation.</td></tr></tbody></table><p>The reason step is allowed to say <code>skip</code>. It is not allowed to average two bad scrapes into a “probably $3.50.” Prices are evidence or they are absent.</p><p>A facts block for one run, rebuilt after every tool result:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line">sku: NB-OATS-1KG</span><br><span class="line">harbor_price_cents: 349</span><br><span class="line">harbor_currency: USD</span><br><span class="line">observed_at: 2026-08-15T06:12:00Z</span><br><span class="line">our_price_cents: 329</span><br><span class="line">our_currency: USD</span><br><span class="line">decision_so_far: moved</span><br><span class="line">skipped: none</span><br></pre></td></tr></tbody></table></figure><p>If <code>fetch_shelf</code> returns junk, that block stays empty on the Harbor side and the decision is <code>skip</code>. I do not ask the model to remember the cents from turn 2 after a compact. I rewrite the block.</p><h2 id="Putting-the-Concepts-into-Practice"><a href="#Putting-the-Concepts-into-Practice" class="headerlink" title="Putting the Concepts into Practice"></a>Putting the Concepts into Practice</h2><p>Pick one workflow that already copies data out of another system (a price list, an issue tracker, a catalog) and write this brief before you add a server:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line">Host (Claude Code vs Agent SDK):</span><br><span class="line">Servers (one job each) and transport (stdio vs http):</span><br><span class="line">Tools (name, when not to use, return fields):</span><br><span class="line">Resources the host should attach itself, if any:</span><br><span class="line">Allow list (mcp__server__tool) and deny list:</span><br><span class="line">permission_mode (dontAsk for a fixed surface):</span><br><span class="line">Trim at the handler (fields the next turn will read):</span><br><span class="line">Audit line (server, tool, args, ok/not_found/denied/error):</span><br><span class="line">What fail-closed means in this domain (do not guess X):</span><br></pre></td></tr></tbody></table></figure><p>Then inspect a real run:</p><ol><li>How many <code>mcp__</code> names landed in the init <code>tools</code> array? Was that the surface you meant?</li><li>Did <code>acceptEdits</code> fool you into thinking an MCP write was gated? (It does not auto-approve MCP.)</li><li>Did any handler return a dump you then asked the model to ignore?</li><li>If you force <code>dontAsk</code> and omit a write tool, does the agent stop instead of inventing a workaround?</li><li>If a tool returns HTML or <code>isError: true</code>, does the audit say <code>error</code> and does the decision say <code>skip</code>?</li></ol><p>If you cannot answer those, you have a connected demo, not a governed surface.</p><h2 id="Key-Terms"><a href="#Key-Terms" class="headerlink" title="Key Terms"></a>Key Terms</h2><ul><li><strong>MCP</strong>: Model Context Protocol. An open standard for connecting a host to external tools, resources, and prompts</li><li><strong>Host</strong>: The AI application that owns the window, the loop, and the permission policy</li><li><strong>Client</strong>: The per-server connector the host instantiates</li><li><strong>Server</strong>: A process (local or remote) that exposes primitives over JSON-RPC</li><li><strong>Tools / <code>tools/list</code> / <code>tools/call</code></strong>: Model-invoked actions. The catalog is context. A fat list is a budget bug.</li><li><strong>Resources</strong>: Host-fetched, read-only context (<code>resources/read</code>)</li><li><strong>Prompts</strong>: User-invoked templates (<code>prompts/get</code>)</li><li><strong>Roots</strong>: Client hint for <code>file://</code> directories. Deprecated as of MCP <code>2026-07-28</code>. Not a sandbox.</li><li><strong>Sampling</strong>: Client feature where a server asks the host to run a model completion. Deprecated as of MCP <code>2026-07-28</code>.</li><li><strong>stdio / Streamable HTTP</strong>: The two standard transports. Claude Code’s <code>http</code> type is Streamable HTTP.</li><li><strong><code>mcp__server__tool</code></strong>: Fully qualified MCP tool name in Claude Code and the Agent SDK</li><li><strong><code>mcp_servers</code> / <code>allowed_tools</code> / <code>disallowed_tools</code> / <code>permission_mode</code></strong>: The governance knobs from Part 3, applied to MCP</li><li><strong><code>create_sdk_mcp_server</code></strong>: In-process MCP server for custom tools</li><li><strong><code>structuredContent</code> / <code>isError</code></strong>: Official MCP tool-result fields for a machine payload and a failed call. Python <code>@tool</code> uses <code>is_error</code> and does not forward <code>structuredContent</code>.</li><li><strong>Append-only audit</strong>: A durable line per call: server, tool, args, result class</li><li><strong>Fail closed</strong>: Skip or halt when evidence is missing or malformed. Do not guess.</li></ul><h2 id="Final-Thoughts"><a href="#Final-Thoughts" class="headerlink" title="Final Thoughts"></a>Final Thoughts</h2><p>The model is still the reasoning engine from <a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Part 1</a>. The harness is still the runtime from <a href="/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/">Part 3</a>. MCP does not replace either one. It moves the public API outside the process and then asks the same questions: which servers exist, which tools enter the window, which calls run, and what a bad result is allowed to mean.</p><p><a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a>‘s trim rule does not stop at bash. A scraper that returns a page, or a <code>tools/list</code> that returns sixty verbs, is the same tax. Governance is the allow list, the deny list, and <code>dontAsk</code>. It is not a paragraph in <code>CLAUDE.md</code>.</p><p>The next post moves from this architecture to whether the loop is actually doing the job: evaluation and observability. I want to know when a skip was correct, when a tool lied, and when the audit trail is the only honest record.</p><h2 id="References"><a href="#References" class="headerlink" title="References"></a>References</h2><ul><li>AI Engineering with Claude</li><li><a target="_blank" rel="noopener" href="https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture">Architecture</a></li><li><a target="_blank" rel="noopener" href="https://modelcontextprotocol.io/docs/2026-07-28/learn/server-concepts">Server concepts</a></li><li><a target="_blank" rel="noopener" href="https://modelcontextprotocol.io/docs/2026-07-28/learn/client-concepts">Client concepts</a></li><li><a target="_blank" rel="noopener" href="https://modelcontextprotocol.io/specification/2026-07-28/basic/transports">Transports</a></li><li><a target="_blank" rel="noopener" href="https://blog.modelcontextprotocol.io/posts/2026-07-28/">2026-07-28 spec notes</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/mcp">Claude Code MCP</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/mcp">Agent SDK MCP</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/custom-tools">Custom tools</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/permissions">Permissions</a></li></ul><hr><p><em>This is Part 4 of 6 in the Agentic Coding with Claude Code series. Earlier: <a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Part 1</a>, <a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a>, <a href="/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/">Part 3</a>.</em></p></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;p&gt;&lt;a href=&quot;/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/&quot;&gt;Part 3&lt;/a&gt; ended with a debt: tools that live outside the process, MCP servers, how they enter the window, and how to keep that surface small.&lt;/p&gt;
&lt;p&gt;This is Part 4 of 6 in my &lt;strong&gt;Agentic Coding with Claude Code&lt;/strong&gt; series. The working model I am keeping is simple: the model still reasons. The harness still decides. MCP is how tools and context live &lt;em&gt;outside&lt;/em&gt; the process and still enter the window as a governed surface.&lt;/p&gt;
&lt;p&gt;Later posts will cover evaluation and observability, then bounded autonomy. This one stays on the MCP boundary.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="mcp" scheme="https://vanducng.dev/tags/mcp/"/>
    
    <category term="agentic-coding" scheme="https://vanducng.dev/tags/agentic-coding/"/>
    
    <category term="claude-code" scheme="https://vanducng.dev/tags/claude-code/"/>
    
    <category term="agent-sdk" scheme="https://vanducng.dev/tags/agent-sdk/"/>
    
  </entry>
  
  <entry>
    <title>The Harness: Models, the Agent SDK, and Stop-Reason Loops</title>
    <link href="https://vanducng.dev/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/"/>
    <id>https://vanducng.dev/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/</id>
    <published>2026-08-15T04:00:00.000Z</published>
    <updated>2026-11-16T05:26:58.282Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><p><a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a> ended with a debt: when I own the runtime, I have to implement trim, a facts block, tiered compress, and placement myself. Claude Code already does a version of that. A product I ship does not get it for free.</p><p>This is Part 3 of 6 in my <strong>Agentic Coding with Claude Code</strong> series. The working model I am keeping is simple: the model reasons, the harness decides what happens next.</p><p>Claude Code is one harness. The <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/overview">Agent SDK</a> is that same loop as a library. The Messages API is the loop with the cover off: every response has a <code>stop_reason</code>, and your code chooses whether to run a tool, ask the user, route, escalate, or halt.</p><p>Later posts will cover MCP, evals, and guardrails. This one stays on the runtime around the model.</p><span id="more"></span><h2 id="The-Harness-Is-the-Runtime-Around-the-Model"><a href="#The-Harness-Is-the-Runtime-Around-the-Model" class="headerlink" title="The Harness Is the Runtime Around the Model"></a>The Harness Is the Runtime Around the Model</h2><p><a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Part 1</a> treated Claude Code as a bounded loop: perceive, reason, act, then feed the evidence back in. That loop does not live inside the weights. It lives in the process that calls the model.</p><p>Official docs say the same thing in product language. <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/how-claude-code-works">How Claude Code works</a> calls Claude Code the <strong>agentic harness</strong> around Claude: tools, context management, and an execution environment that turn a language model into a coding agent. The <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/overview">Agent SDK</a> is that harness as a library. The <a target="_blank" rel="noopener" href="https://platform.claude.com/docs/en/cli-sdks-libraries/overview">Client SDK</a> calls the Messages API: you implement the tool loop yourself.</p><p>My working split:</p><table><thead><tr><th>Piece</th><th>Job</th><th>Who owns it</th></tr></thead><tbody><tr><td><strong>Model</strong></td><td>Read the window, pick the next action or the next sentence</td><td>Anthropic</td></tr><tr><td><strong>Loop</strong></td><td>Call the model again until the task is done or a limit fires</td><td>Harness</td></tr><tr><td><strong>Tools</strong></td><td>The agent’s public API: what it can observe or change</td><td>Harness</td></tr><tr><td><strong>Permissions</strong></td><td>Which tool calls run, which ask, which never exist</td><td>Harness</td></tr><tr><td><strong>Context assembly</strong></td><td>What occupies the window on the next turn</td><td>Harness</td></tr><tr><td><strong>Stop conditions</strong></td><td>When to run a tool, ask a human, route, escalate, or halt</td><td>Harness</td></tr></tbody></table><pre class="mermaid">flowchart TB    Goal[Goal] --&gt; Assemble[Assemble context]    Assemble --&gt; Model[Model]    Model --&gt; Stop["stop_reason"]    Stop --&gt;|tool_use| Tool[Run or deny tool]    Tool --&gt; Trim[Trim the result]    Trim --&gt; Assemble    Stop --&gt;|end_turn| Decide[Ask / route / halt]    Stop --&gt;|refusal / max_tokens| Halt[Retry or fail closed]    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff    classDef tealClass fill:#16A085,stroke:#333,stroke-width:2px,color:#fff    classDef redClass fill:#E74C3C,stroke:#333,stroke-width:2px,color:#fff    class Goal blueClass    class Assemble,Trim orangeClass    class Model greenClass    class Stop purpleClass    class Tool tealClass    class Decide,Halt redClass</pre><p>The model does not invoke your function. It returns a <code>tool_use</code> block and stops. The harness runs the function, or refuses to, then writes a <code>tool_result</code> back into the window. If I skip that step, the user sees an agent that dies the first time it tries to act.</p><p>Claude Code hides that dispatch. The Agent SDK hides it too, and yields a stream of messages while it works. When I want the dispatch itself to encode product policy (clarify vs route vs escalate), I read <code>stop_reason</code> on the Messages API and write the branch.</p><h2 id="Model-Choice-Is-an-Engineering-Decision"><a href="#Model-Choice-Is-an-Engineering-Decision" class="headerlink" title="Model Choice Is an Engineering Decision"></a>Model Choice Is an Engineering Decision</h2><p>Course 1 used the Claude 4.5 family: Haiku, Sonnet, Opus. The IDs move. The decision does not. Match the model to the step, not one model to the whole system.</p><p>Current aliases I fetched from the <a target="_blank" rel="noopener" href="https://platform.claude.com/docs/en/about-claude/models/overview">models overview</a> (August 2026):</p><table><thead><tr><th>Tier</th><th>Alias</th><th>Use it for</th><th>Do not use it for</th></tr></thead><tbody><tr><td><strong>Haiku</strong></td><td><code>claude-haiku-4-5</code></td><td>Classify, extract, cheap tool hops, high-volume substeps</td><td>Ambiguous policy, first-time architecture</td></tr><tr><td><strong>Sonnet</strong></td><td><code>claude-sonnet-5</code></td><td>The default agent loop: read, edit, test, route</td><td>Overnight research you will not review</td></tr><tr><td><strong>Opus</strong></td><td><code>claude-opus-5</code></td><td>Hard judgment: escalate, conflicting evidence, a plan that will spawn other work</td><td>Every lookup in a tight loop</td></tr></tbody></table><p>Pricing and context windows change. The current table on that page is Haiku at $1 / $5 per million tokens (200k context), Sonnet at $2 / $10 (1M), Opus at $5 / $25 (1M). I treat those as inputs to the step budget, not as a reason to pick one model and forget it.</p><p>The Agent SDK makes the choice explicit. If you omit <code>model</code>, it uses Claude Code’s default for the authentication method and subscription. Pin it when the step has a known cost shape:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">from</span> claude_agent_sdk <span class="hljs-keyword">import</span> ClaudeAgentOptions</span><br><span class="line"></span><br><span class="line">options = ClaudeAgentOptions(</span><br><span class="line">    model=<span class="hljs-string">"claude-sonnet-5"</span>,</span><br><span class="line">    max_turns=<span class="hljs-number">20</span>,</span><br><span class="line">)</span><br></pre></td></tr></tbody></table></figure><p>A pattern I will reuse: Haiku classifies the incoming message, Sonnet runs the tool loop, Opus only sees the cases the classifier marked <code>escalate</code>. That is the same “smallest authority that still works” rule from <a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Part 1</a>, applied to intelligence instead of file permissions.</p><p><code>effort</code> on the Agent SDK is a second knob, not a substitute for model choice. Official docs: <code>"low"</code> for file lookups, <code>"high"</code> for refactors. Set it per session or per subagent. I leave it unset until I have a cost problem.</p><h2 id="Agentic-Design-One-Pointer"><a href="#Agentic-Design-One-Pointer" class="headerlink" title="Agentic Design, One Pointer"></a>Agentic Design, One Pointer</h2><p>I am not re-teaching the loop. <a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Part 1</a> already has the components (goal, tools, memory, reasoning engine, human) and the patterns (single-agent, multi-agent, hierarchical).</p><p>The harness question is narrower: which of those components do I implement in code, and which do I leave to Claude Code? For this post the default is still one agent. Add a second model or a second loop only when a step is cheaper or safer in isolation (classify on Haiku, research in a subagent). Coordination cost is a later post.</p><h2 id="The-Agent-SDK-Goal-Tools-Permissions-Structured-Outputs"><a href="#The-Agent-SDK-Goal-Tools-Permissions-Structured-Outputs" class="headerlink" title="The Agent SDK: Goal, Tools, Permissions, Structured Outputs"></a>The Agent SDK: Goal, Tools, Permissions, Structured Outputs</h2><p>The <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/overview">Agent SDK</a> is how I embed Claude Code’s loop in a process I own. Python and TypeScript only. Other languages drive the CLI with <code>-p</code> and <code>--output-format json</code>.</p><p>What I configure on the SDK call is the product. Python field names below; TypeScript uses the same knobs in camelCase.</p><table><thead><tr><th>Knob</th><th>Official field</th><th>What I am actually deciding</th></tr></thead><tbody><tr><td><strong>Goal</strong></td><td><code>prompt</code> on <code>query()</code>, plus any loaded <code>CLAUDE.md</code></td><td>What evidence means done</td></tr><tr><td><strong>Tools</strong></td><td><code>allowed_tools</code> on <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/python#claudeagentoptions"><code>ClaudeAgentOptions</code></a>, plus any custom tools I register</td><td>The agent’s public API</td></tr><tr><td><strong>Permissions</strong></td><td><code>permission_mode</code>, <code>disallowed_tools</code>, <code>can_use_tool</code></td><td>What may run without a human</td></tr><tr><td><strong>Structured output</strong></td><td><code>output_format</code></td><td>The shape my code will consume</td></tr><tr><td><strong>Budget</strong></td><td><code>max_turns</code>, <code>max_budget_usd</code></td><td>When the loop must stop even if the model wants another hop</td></tr></tbody></table><p>A single-shot <code>query()</code> streams messages and ends on a <code>ResultMessage</code>. Check <code>subtype</code> before you read <code>result</code>:</p><table><thead><tr><th><code>ResultMessage.subtype</code></th><th>Meaning</th></tr></thead><tbody><tr><td><code>success</code></td><td>The loop finished; <code>result</code> is the final text</td></tr><tr><td><code>error_max_turns</code></td><td>Hit <code>max_turns</code> (tool-use turns only)</td></tr><tr><td><code>error_max_budget_usd</code></td><td>Hit <code>max_budget_usd</code></td></tr><tr><td><code>error_during_execution</code></td><td>The loop broke (API failure, cancel)</td></tr><tr><td><code>error_max_structured_output_retries</code></td><td>Schema validation never succeeded</td></tr></tbody></table><p><code>query()</code> then raises after an error result. Wrap the loop. The session id on that message is how you resume. Crash recovery and dual-write session stores are a later layer; this post stops at the per-turn loop.</p><h3 id="Tools-Are-the-Agent’s-Public-API"><a href="#Tools-Are-the-Agent’s-Public-API" class="headerlink" title="Tools Are the Agent’s Public API"></a>Tools Are the Agent’s Public API</h3><p><a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a> said a vague tool contract wastes the loop. In a harness I own, that contract is the product surface.</p><p>Official <a target="_blank" rel="noopener" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools">tool definitions</a> need a <code>name</code>, a <code>description</code>, and an <code>input_schema</code>. The description is the prompt. Anthropic’s current guidance: say what the tool does, when to use it, when not to, what each parameter means, and what an empty or error result means. Return only the fields the next reason step will read.</p><p>Badly shaped tools produce badly shaped agents. Two tools that both “look up a customer” will fight. A tool that dumps a raw order JSON will tax every later turn. A tool named <code>search</code> with no “when not to use” will get called instead of the precise one.</p><p>The Agent SDK ships the same built-ins as Claude Code (<code>Read</code>, <code>Edit</code>, <code>Bash</code>, <code>Glob</code>, <code>Grep</code>, and the rest). Custom tools are functions I define and register. I will not walk the registration path here (it is an in-process server; MCP is the next post). The contract I keep is the same on either API:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">Name: the verb the model should think</span><br><span class="line">When to use / when not to use</span><br><span class="line">Inputs: required vs optional, units, invariants</span><br><span class="line">Output: the fields the next turn will read</span><br><span class="line">Failure: not_found, not_allowed, or error; never a guess</span><br></pre></td></tr></tbody></table></figure><h3 id="Permissions-Are-Not-Prompt-Text"><a href="#Permissions-Are-Not-Prompt-Text" class="headerlink" title="Permissions Are Not Prompt Text"></a>Permissions Are Not Prompt Text</h3><p><code>CLAUDE.md</code> is guidance. If a write must not happen, that is a permission rule.</p><p>The SDK evaluates <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/permissions#how-permissions-are-evaluated">permissions in a fixed order</a>: hooks, deny rules, ask rules, the active mode, allow rules, then <code>can_use_tool</code>. A bare <code>disallowed_tools=["Bash"]</code> removes the tool from the model’s context. A scoped deny like <code>Bash(rm *)</code> keeps Bash and blocks that pattern in every mode, including <code>bypassPermissions</code>.</p><p>Modes I will actually use:</p><table><thead><tr><th>Mode</th><th>Behavior</th><th>When I use it</th></tr></thead><tbody><tr><td><code>default</code></td><td>Unmatched tools hit <code>can_use_tool</code></td><td>Interactive product with an approval UI</td></tr><tr><td><code>dontAsk</code></td><td>Tools not pre-approved by allow rules are denied; no prompt</td><td>Headless agent with a fixed surface</td></tr><tr><td><code>acceptEdits</code></td><td>File edits and common filesystem commands auto-approve; other Bash still gated</td><td>Isolated repo, I trust the diffs</td></tr><tr><td><code>plan</code></td><td>Explore and propose; writes are never auto-approved</td><td>I want a plan, not a patch</td></tr><tr><td><code>bypassPermissions</code></td><td>Almost everything runs</td><td>CI or a container I can throw away</td></tr></tbody></table><p><code>allowed_tools</code> does not constrain <code>bypassPermissions</code>. Listing <code>Read</code> and then setting bypass still approves <code>Bash</code>. For a locked-down agent, pair an allow list with <code>dontAsk</code>.</p><h3 id="Structured-Outputs-Close-the-Loop"><a href="#Structured-Outputs-Close-the-Loop" class="headerlink" title="Structured Outputs Close the Loop"></a>Structured Outputs Close the Loop</h3><p>Free-form text is a chat. A harness needs a value it can branch on.</p><p>On the Agent SDK, pass <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/structured-outputs"><code>output_format</code></a> as <code>{"type": "json_schema", "schema": ...}</code>. The agent may still use tools. When it finishes, <code>ResultMessage.structured_output</code> is validated JSON. If validation fails past the retry limit, you get <code>error_max_structured_output_retries</code>, not a best-effort blob.</p><p>On the Messages API, the equivalent is <a target="_blank" rel="noopener" href="https://platform.claude.com/docs/en/build-with-claude/structured-outputs"><code>output_config.format</code></a> with <code>type: "json_schema"</code>. Same idea: the last text block is parseable JSON matching the schema.</p><p>I use structured output for decisions the harness must act on (clarify / route / escalate). I do not use it for the essay the user reads.</p><h2 id="stop-reason-Drives-the-Loop"><a href="#stop-reason-Drives-the-Loop" class="headerlink" title="stop_reason Drives the Loop"></a><code>stop_reason</code> Drives the Loop</h2><p>Every successful Messages API response includes <a target="_blank" rel="noopener" href="https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons"><code>stop_reason</code></a>. That field is why the model stopped generating. It is not an HTTP error. Your harness reads it and chooses the next verb.</p><table><thead><tr><th><code>stop_reason</code></th><th>Official meaning</th><th>What my harness does</th></tr></thead><tbody><tr><td><code>end_turn</code></td><td>Finished naturally</td><td>Use the text or the structured decision: ask, route, or halt</td></tr><tr><td><code>tool_use</code></td><td>One or more <code>tool_use</code> blocks</td><td>Run permitted tools, append <code>tool_result</code>, call again</td></tr><tr><td><code>max_tokens</code></td><td>Hit <code>max_tokens</code></td><td>Raise the limit or treat as truncated; do not pretend it is complete</td></tr><tr><td><code>stop_sequence</code></td><td>Hit a custom <code>stop_sequences</code> value</td><td>Read <code>stop_sequence</code>, then continue or halt</td></tr><tr><td><code>pause_turn</code></td><td>A server-tool loop hit its iteration limit</td><td>Send the assistant content back to resume</td></tr><tr><td><code>refusal</code></td><td>Declined the request</td><td>Read <code>stop_details</code>, fail closed, do not invent a workaround</td></tr><tr><td><code>model_context_window_exceeded</code></td><td>The response filled the window</td><td>Treat as truncated; compact or halt</td></tr></tbody></table><p>The <code>tool_use</code> branch is the whole agent, in four steps the docs repeat:</p><ol><li>Append the assistant turn <strong>verbatim</strong>, including every <code>tool_use</code> block.</li><li>Run each tool (or deny it).</li><li>Append a user turn of <code>tool_result</code> blocks, each with the matching <code>tool_use_id</code>.</li><li>Call the API again with the same tools.</li></ol><p>Skip step 1 and the next request is malformed. Skip step 3 and the model has no evidence. Cap the loop (<code>max_turns</code> on the Agent SDK, a counter on the Messages API) or an open-ended prompt will spend until you notice.</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-comment"># Sketch of a Messages API loop. Official fields only.</span></span><br><span class="line"><span class="hljs-comment"># Not a product, and not a course file.</span></span><br><span class="line"><span class="hljs-comment"># run_or_deny, decide_from_text, halt, TOOLS, and MAX_TURNS are placeholders you own, not SDK symbols.</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">from</span> anthropic <span class="hljs-keyword">import</span> Anthropic</span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">def</span> <span class="title function_">handle_message</span>(<span class="hljs-params">user_text</span>):</span><br><span class="line">    client = Anthropic()</span><br><span class="line">    messages = [{<span class="hljs-string">"role"</span>: <span class="hljs-string">"user"</span>, <span class="hljs-string">"content"</span>: user_text}]</span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">for</span> _ <span class="hljs-keyword">in</span> <span class="hljs-built_in">range</span>(MAX_TURNS):</span><br><span class="line">        response = client.messages.create(</span><br><span class="line">            model=<span class="hljs-string">"claude-sonnet-5"</span>,</span><br><span class="line">            max_tokens=<span class="hljs-number">1024</span>,</span><br><span class="line">            tools=TOOLS,</span><br><span class="line">            messages=messages,</span><br><span class="line">        )</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">if</span> response.stop_reason == <span class="hljs-string">"tool_use"</span>:</span><br><span class="line">            messages.append({<span class="hljs-string">"role"</span>: <span class="hljs-string">"assistant"</span>, <span class="hljs-string">"content"</span>: response.content})</span><br><span class="line">            results = []</span><br><span class="line">            <span class="hljs-keyword">for</span> block <span class="hljs-keyword">in</span> response.content:</span><br><span class="line">                <span class="hljs-keyword">if</span> block.<span class="hljs-built_in">type</span> == <span class="hljs-string">"tool_use"</span>:</span><br><span class="line">                    results.append(</span><br><span class="line">                        {</span><br><span class="line">                            <span class="hljs-string">"type"</span>: <span class="hljs-string">"tool_result"</span>,</span><br><span class="line">                            <span class="hljs-string">"tool_use_id"</span>: block.<span class="hljs-built_in">id</span>,</span><br><span class="line">                            <span class="hljs-string">"content"</span>: run_or_deny(block.name, block.<span class="hljs-built_in">input</span>),</span><br><span class="line">                        }</span><br><span class="line">                    )</span><br><span class="line">            messages.append({<span class="hljs-string">"role"</span>: <span class="hljs-string">"user"</span>, <span class="hljs-string">"content"</span>: results})</span><br><span class="line">            <span class="hljs-keyword">continue</span></span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">if</span> response.stop_reason == <span class="hljs-string">"end_turn"</span>:</span><br><span class="line">            <span class="hljs-keyword">return</span> decide_from_text(response)  <span class="hljs-comment"># ask / route / escalate / halt</span></span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">if</span> response.stop_reason == <span class="hljs-string">"refusal"</span>:</span><br><span class="line">            <span class="hljs-keyword">return</span> halt(<span class="hljs-string">"model_refused"</span>)</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">return</span> halt(response.stop_reason)</span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">return</span> halt(<span class="hljs-string">"max_turns"</span>)</span><br></pre></td></tr></tbody></table></figure><p>The Agent SDK runs that <code>tool_use</code> branch for you. You still handle the <em>result</em>: success, turn cap, budget cap, refusal (<code>ResultMessage.stop_reason == "refusal"</code>). The Messages API is what I reach for when the branch itself is the product: after <code>end_turn</code>, I may ask a clarifying question instead of closing the ticket.</p><h3 id="Prompt-Chain-vs-Stop-Reason-Loop"><a href="#Prompt-Chain-vs-Stop-Reason-Loop" class="headerlink" title="Prompt Chain vs Stop-Reason Loop"></a>Prompt Chain vs Stop-Reason Loop</h3><p>A prompt chain is a fixed pipeline. Step 2 always runs after step 1. Dynamic decomposition is the opposite: the model picks the next tool from evidence, and the harness only enforces permissions and stop policy.</p><pre class="mermaid">flowchart TB    subgraph Loop["Stop-reason loop"]        direction LR        L1[Observe] --&gt; L2[Reason] --&gt; L3{stop_reason} --&gt; L4[Act or ask]        L4 --&gt; L1    end    subgraph Chain["Prompt chain"]        direction LR        C1[Parse] --&gt; C2[Validate] --&gt; C3[Classify] --&gt; C4[Reply]    end    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff    class C1,C2,C3,C4 orangeClass    class L1 blueClass    class L2 greenClass    class L3 purpleClass    class L4 greenClass</pre><table><thead><tr><th></th><th>Prompt chain</th><th><code>stop_reason</code> loop</th></tr></thead><tbody><tr><td><strong>Control flow</strong></td><td>You named the steps in advance</td><td>The model names the next tool; you name the stop policy</td></tr><tr><td><strong>Missing input</strong></td><td>A later step inherits a bad parse</td><td>The harness can ask, then resume</td></tr><tr><td><strong>New evidence</strong></td><td>The chain cannot grow a step you did not write</td><td>A new <code>tool_use</code> is just another turn</td></tr><tr><td><strong>Cost</strong></td><td>Bounded and predictable</td><td>Needs <code>max_turns</code> / <code>max_budget_usd</code></td></tr><tr><td><strong>Use it when</strong></td><td>The path is truly linear</td><td>The next action depends on what the last tool returned</td></tr></tbody></table><p>I still write chains for work that is actually a pipeline (normalize, then validate, then persist). I write a loop when the agent must discover the path. Course 1 spends time on that contrast. The takeaway I kept: do not encode a tree of “if the user said X, call Y” in prompts if <code>stop_reason</code> plus tools already is that tree.</p><h2 id="Claims-Intake-Clarify-Route-Escalate"><a href="#Claims-Intake-Clarify-Route-Escalate" class="headerlink" title="Claims Intake: Clarify, Route, Escalate"></a>Claims Intake: Clarify, Route, Escalate</h2><p>Course 1 trains this on a claims-style copilot. I am not reprinting their files. Invented example: <strong>warranty-desk</strong>, a small intake bot for a headphone company. A customer pastes a messy email. The harness must either ask a question, open a claim in the right queue, or hand the thread to a human.</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line">Goal: turn one inbound message into a claim decision.</span><br><span class="line">Definition of done: a structured decision, plus a claim id if we opened one.</span><br><span class="line">Clarify when: no order id, no defect photos, or the defect text is ambiguous.</span><br><span class="line">Route when: we can look up the order and the warranty window is clear.</span><br><span class="line">  repair | replace | deny</span><br><span class="line">Escalate when: battery swell, legal language, a repeat claimant, or retail over $400.</span><br><span class="line">Stop and ask before: issuing a refund, writing to the customer, or closing a claim.</span><br></pre></td></tr></tbody></table></figure><p>The tools are the public API. Invented, and intentionally small:</p><table><thead><tr><th>Tool</th><th>Returns</th><th>When not to use</th></tr></thead><tbody><tr><td><code>lookup_order</code></td><td><code>order_id</code>, <code>sku</code>, <code>purchased_on</code>, <code>warranty_until</code>, <code>status</code></td><td>You only have an email; use <code>lookup_customer</code></td></tr><tr><td><code>lookup_customer</code></td><td><code>customer_id</code>, <code>open_claim_ids</code></td><td>You already have the order</td></tr><tr><td><code>create_claim</code></td><td><code>claim_id</code>, <code>queue</code></td><td>Any escalate condition is true</td></tr><tr><td><code>escalate_to_human</code></td><td><code>ticket_id</code></td><td>The case is a normal repair / replace / deny</td></tr></tbody></table><p>Each result is a handful of fields. <code>lookup_order</code> does not return the raw commerce payload. That is <a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a>‘s trim rule, implemented at the tool boundary.</p><p>The structured decision the loop must produce:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br></pre></td><td class="code"><pre><span class="line">DECISION_SCHEMA = {</span><br><span class="line">    <span class="hljs-string">"type"</span>: <span class="hljs-string">"object"</span>,</span><br><span class="line">    <span class="hljs-string">"properties"</span>: {</span><br><span class="line">        <span class="hljs-string">"action"</span>: {</span><br><span class="line">            <span class="hljs-string">"type"</span>: <span class="hljs-string">"string"</span>,</span><br><span class="line">            <span class="hljs-string">"enum"</span>: [<span class="hljs-string">"clarify"</span>, <span class="hljs-string">"route"</span>, <span class="hljs-string">"escalate"</span>],</span><br><span class="line">        },</span><br><span class="line">        <span class="hljs-string">"queue"</span>: {</span><br><span class="line">            <span class="hljs-string">"type"</span>: <span class="hljs-string">"string"</span>,</span><br><span class="line">            <span class="hljs-string">"enum"</span>: [<span class="hljs-string">"repair"</span>, <span class="hljs-string">"replace"</span>, <span class="hljs-string">"deny"</span>, <span class="hljs-string">"human"</span>, <span class="hljs-string">"none"</span>],</span><br><span class="line">        },</span><br><span class="line">        <span class="hljs-string">"question"</span>: {<span class="hljs-string">"type"</span>: <span class="hljs-string">"string"</span>},</span><br><span class="line">        <span class="hljs-string">"claim_id"</span>: {<span class="hljs-string">"type"</span>: <span class="hljs-string">"string"</span>},</span><br><span class="line">        <span class="hljs-string">"reason"</span>: {<span class="hljs-string">"type"</span>: <span class="hljs-string">"string"</span>},</span><br><span class="line">    },</span><br><span class="line">    <span class="hljs-string">"required"</span>: [<span class="hljs-string">"action"</span>, <span class="hljs-string">"queue"</span>, <span class="hljs-string">"reason"</span>],</span><br><span class="line">    <span class="hljs-string">"additionalProperties"</span>: <span class="hljs-literal">False</span>,</span><br><span class="line">}</span><br></pre></td></tr></tbody></table></figure><p>On the Agent SDK I would pass that schema as <code>output_format</code> and let <code>query()</code> run the <code>tool_use</code> turns. On the Messages API I run the sketch above, then branch on <code>action</code>:</p><pre class="mermaid">flowchart TB    In[Inbound email] --&gt; Loop[stop_reason loop]    Loop --&gt;|tool_use| Tools[lookup / create / escalate]    Tools --&gt; Loop    Loop --&gt;|end_turn + clarify| Ask[Ask the customer one question]    Loop --&gt;|end_turn + route| Ticket[Open claim in repair / replace / deny]    Loop --&gt;|end_turn + escalate| Human[Hand off with the facts block]    Loop --&gt;|refusal / max_turns| Closed[Fail closed]    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff    classDef tealClass fill:#16A085,stroke:#333,stroke-width:2px,color:#fff    classDef redClass fill:#E74C3C,stroke:#333,stroke-width:2px,color:#fff    class In blueClass    class Loop orangeClass    class Tools purpleClass    class Ask tealClass    class Ticket greenClass    class Human,Closed redClass</pre><p>A chain would always parse, then always validate, then always classify. The loop can look up the order first, notice the warranty expired last month, and route to <code>deny</code> without inventing a “validate photos” step I forgot to write. It can also stop after one turn and ask for the order id. That ask is not a tool. It is <code>end_turn</code> plus <code>action: "clarify"</code>, and the harness owns the pause.</p><p>Haiku can draft the first <code>action</code> guess. Sonnet should own the tool loop. Opus only sees <code>escalate</code> drafts I do not want a cheaper model to close.</p><h2 id="When-You-Own-the-Runtime-You-Own-Part-2"><a href="#When-You-Own-the-Runtime-You-Own-Part-2" class="headerlink" title="When You Own the Runtime, You Own Part 2"></a>When You Own the Runtime, You Own Part 2</h2><p>Claude Code already caps bash output, runs <code>/compact</code>, re-injects root <code>CLAUDE.md</code> after compact, and can fork a noisy skill. The Agent SDK inherits that loop, including <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/agent-loop#automatic-compaction">automatic compaction</a> and a <code>compact_boundary</code> message. Persistent rules still belong in <code>CLAUDE.md</code> loaded via <code>setting_sources</code>, because compaction replaces early turns with a summary.</p><p>If I am on the Messages API, none of that exists until I write it. The four rules from <a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a> become code:</p><table><thead><tr><th>Rule</th><th>In Claude Code</th><th>In a runtime I own</th></tr></thead><tbody><tr><td><strong>Trim at the tool</strong></td><td>Bash cap, structured tool results</td><td>The handler returns six fields, not the vendor dump</td></tr><tr><td><strong>Persistent facts block</strong></td><td>Root <code>CLAUDE.md</code>, auto memory</td><td>A short list I rewrite every turn: order id, claim id, confirmed defect, what the user already answered</td></tr><tr><td><strong>Tiered compress</strong></td><td><code>/compact</code>, auto compact</td><td>Squeeze resolved clarify turns hard; keep the active lookup; never drop the facts block; budget in tokens</td></tr><tr><td><strong>Place facts at the edge</strong></td><td>Root <code>CLAUDE.md</code> is re-injected after compact</td><td>Prepend or append the facts block on every <code>messages.create</code>; do not bury it between tool traces</td></tr></tbody></table><p>A facts block for warranty-desk looks like this, not like a transcript:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line">order_id: AO-18422</span><br><span class="line">sku: Auraline-H2</span><br><span class="line">warranty_until: 2026-03-01</span><br><span class="line">user_confirmed: no receipt, photos attached</span><br><span class="line">open_claims: none</span><br><span class="line">decision_so_far: none</span><br></pre></td></tr></tbody></table></figure><p>I rebuild that block from durable state after every tool result. I do not ask the model to remember it from turn 3. After a compact, the middle of the window is a summary. The facts still sit at the head or tail.</p><p>The squeeze rule does not change:</p><table><thead><tr><th>Layer</th><th>Squeeze</th><th>Keep</th></tr></thead><tbody><tr><td>Resolved turns</td><td>Hard</td><td>Outcome and the evidence that proved it</td></tr><tr><td>Active turns</td><td>Light</td><td>Enough to continue the current step</td></tr><tr><td>Facts block</td><td>Never</td><td>Ids, constraints, confirmed answers</td></tr></tbody></table><p>Custom tool handlers are the first place this fails. If <code>lookup_order</code> returns 40 KB of line items, the next <code>end_turn</code> is already working from noise. Trim is a harness job, not a prompt.</p><h2 id="Putting-the-Concepts-into-Practice"><a href="#Putting-the-Concepts-into-Practice" class="headerlink" title="Putting the Concepts into Practice"></a>Putting the Concepts into Practice</h2><p>Pick one workflow you would not trust to a single prompt (intake, triage, a support copilot) and write this brief before you open an SDK:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line">Goal and definition of done:</span><br><span class="line">Model per step (Haiku / Sonnet / Opus):</span><br><span class="line">Tools (name, when not to use, return fields):</span><br><span class="line">Permission mode and the deny list:</span><br><span class="line">Structured decision the harness will branch on:</span><br><span class="line">stop_reason policy (tool / ask / route / escalate / halt):</span><br><span class="line">Facts that must survive compact, and where they sit:</span><br><span class="line">What a prompt chain would force you to pre-write:</span><br></pre></td></tr></tbody></table></figure><p>Then inspect a real run:</p><ol><li>Did the first <code>stop_reason</code> match what you expected (<code>tool_use</code> vs <code>end_turn</code>)?</li><li>Did any tool return a dump you then asked the model to ignore?</li><li>After three turns, can you point to the facts block at the edge of the window?</li><li>If you force <code>dontAsk</code> and omit a write tool, does the agent stop instead of inventing a workaround?</li><li>If you swap the main loop to Haiku, which decisions get worse?</li></ol><p>If you cannot answer those, you have a demo, not a harness.</p><h2 id="Key-Terms"><a href="#Key-Terms" class="headerlink" title="Key Terms"></a>Key Terms</h2><ul><li><strong>Harness</strong>: The runtime around the model: loop, tools, permissions, context assembly, and stop policy</li><li><strong>Claude Code</strong>: One harness, built for interactive coding</li><li><strong>Agent SDK</strong>: The same Claude Code loop as a Python or TypeScript library (<code>query()</code>, <code>ClaudeAgentOptions</code>)</li><li><strong>Client SDK / Messages API</strong>: Language libraries that call the Messages API; you implement the tool loop yourself</li><li><strong><code>stop_reason</code></strong>: Why the model stopped generating; the harness reads it and chooses the next verb</li><li><strong><code>tool_use</code> / <code>tool_result</code></strong>: The model requests a call; the harness runs or denies it and writes the evidence back</li><li><strong>Permission mode</strong>: How unmatched tool calls are approved, denied, or prompted (<code>default</code>, <code>dontAsk</code>, <code>acceptEdits</code>, <code>plan</code>, <code>bypassPermissions</code>)</li><li><strong>Structured output</strong>: A JSON Schema the final answer must match, so your code can branch</li><li><strong>Prompt chain</strong>: A fixed sequence of model calls you named in advance</li><li><strong>Dynamic decomposition</strong>: The model picks the next tool from evidence; you enforce permissions and stop policy</li><li><strong>Clarify / route / escalate</strong>: An intake policy: ask, act in a known queue, or hand off</li><li><strong>Facts block</strong>: Short durable state re-attached at the head or tail so it survives prune and compact</li></ul><h2 id="Final-Thoughts"><a href="#Final-Thoughts" class="headerlink" title="Final Thoughts"></a>Final Thoughts</h2><p>The model is the reasoning engine from <a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Part 1</a>. The harness is everything that makes that engine a product: which model runs which step, which tools exist, which calls are allowed, what the window contains, and what <code>stop_reason</code> means in your domain. Claude Code is a good harness I did not have to write. The Agent SDK is that harness in my process. The Messages API is the same loop with the cover off.</p><p><a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a>‘s context strategy does not disappear when I leave the terminal. If I own the runtime, I own trim, the facts block, the compact budget, and placement. Tools stay the public API. A badly shaped tool still produces a badly shaped agent.</p><p>The next post moves from tools I register in-process to tools that live outside the process: MCP servers, how they enter the window, and how to keep that surface small.</p><h2 id="References"><a href="#References" class="headerlink" title="References"></a>References</h2><ul><li>AI Engineering with Claude</li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/overview">Agent SDK overview</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/agent-loop">Agent loop</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/permissions">Permissions</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/agent-sdk/structured-outputs">Structured outputs</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/how-claude-code-works">How Claude Code works</a></li><li><a target="_blank" rel="noopener" href="https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons">Stop reasons</a></li><li><a target="_blank" rel="noopener" href="https://platform.claude.com/docs/en/about-claude/models/overview">Models</a></li><li><a target="_blank" rel="noopener" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview">Tool use</a></li></ul><hr><p><em>This is Part 3 of 6 in the Agentic Coding with Claude Code series.</em></p></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;p&gt;&lt;a href=&quot;/2026/08/15/context-engineering-for-claude-code/&quot;&gt;Part 2&lt;/a&gt; ended with a debt: when I own the runtime, I have to implement trim, a facts block, tiered compress, and placement myself. Claude Code already does a version of that. A product I ship does not get it for free.&lt;/p&gt;
&lt;p&gt;This is Part 3 of 6 in my &lt;strong&gt;Agentic Coding with Claude Code&lt;/strong&gt; series. The working model I am keeping is simple: the model reasons, the harness decides what happens next.&lt;/p&gt;
&lt;p&gt;Claude Code is one harness. The &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://code.claude.com/docs/en/agent-sdk/overview&quot;&gt;Agent SDK&lt;/a&gt; is that same loop as a library. The Messages API is the loop with the cover off: every response has a &lt;code&gt;stop_reason&lt;/code&gt;, and your code chooses whether to run a tool, ask the user, route, escalate, or halt.&lt;/p&gt;
&lt;p&gt;Later posts will cover MCP, evals, and guardrails. This one stays on the runtime around the model.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="agentic-coding" scheme="https://vanducng.dev/tags/agentic-coding/"/>
    
    <category term="claude-code" scheme="https://vanducng.dev/tags/claude-code/"/>
    
    <category term="agent-sdk" scheme="https://vanducng.dev/tags/agent-sdk/"/>
    
  </entry>
  
  <entry>
    <title>Context Engineering for Claude Code</title>
    <link href="https://vanducng.dev/2026/08/15/context-engineering-for-claude-code/"/>
    <id>https://vanducng.dev/2026/08/15/context-engineering-for-claude-code/</id>
    <published>2026-08-15T02:00:00.000Z</published>
    <updated>2026-11-16T05:26:58.275Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><p>In <a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Part 1</a>, I treated Claude Code as a bounded loop: perceive, reason, act, then feed the evidence back in. The reasoning engine is only as good as the working set it sees. A precise goal still fails if the window is full of directory trees, stale chat, and a vague tool contract.</p><p>This is Part 2 of 6 in my <strong>Agentic Coding with Claude Code</strong> series. The working model I am keeping is simple: context is assembled, not typed, and it is a budget, not a bucket.</p><p><code>CLAUDE.md</code>, path-scoped rules, skills, memory, tool results, and the conversation all compete for the same tokens. Unfiltered tool output is paid for on every later turn. The job is to load the right slice at the right time.</p><p>Later posts will cover the harness and Agent SDK, MCP, evals, and guardrails. This one stays on the context layer that shapes every decision in the loop.</p><span id="more"></span><h2 id="Context-Is-Assembled-Not-Just-the-Prompt"><a href="#Context-Is-Assembled-Not-Just-the-Prompt" class="headerlink" title="Context Is Assembled, Not Just the Prompt"></a>Context Is Assembled, Not Just the Prompt</h2><p>A Claude Code session does not start from your latest sentence. The product already packed a window before you typed.</p><p>At launch, Claude typically receives the system prompt, <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/memory#auto-memory">auto memory</a>, environment and git hints, skill <em>names and descriptions</em>, and every <code>CLAUDE.md</code> that applies to the working directory, including <code>@</code> imports. Your prompt is one more block in that stack. After you start working, file reads, path-scoped rules, skill bodies, and tool output join the same window.</p><pre class="mermaid">flowchart TB    subgraph Demand["Loaded on demand"]        direction LR        R[Path-scoped rules] --&gt; S[Skill body] --&gt; T[Tool results]    end    subgraph Launch["Loaded at launch"]        direction LR        C[CLAUDE.md] --&gt; I["@ imports"] --&gt; M[Auto memory] --&gt; D[Skill names]    end    Prompt[User prompt] --&gt; Window[Working context]    Launch --&gt; Window    Demand --&gt; Window    Window --&gt; Loop[Perceive / Reason / Act]    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff    classDef tealClass fill:#16A085,stroke:#333,stroke-width:2px,color:#fff    classDef redClass fill:#E74C3C,stroke:#333,stroke-width:2px,color:#fff    class Prompt blueClass    class C,I orangeClass    class M,D greenClass    class R,S purpleClass    class T tealClass    class Window,Loop redClass</pre><p>Two consequences follow from <a href="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/">Part 1</a>:</p><ol><li><strong>Memory is not one file.</strong> Working context, project instructions, and durable notes are different layers. Current source and fresh tool output remain the authority.</li><li><strong>Tokens are a budget.</strong> File reads dominate cost. A research-heavy turn that dumps six files, or a tool that returns an unfiltered log, taxes every later decision. You pay again on the next perceive step, not only on the turn that fetched the text.</li></ol><p>Anthropic’s current guidance matches that framing. <a target="_blank" rel="noopener" href="https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models">Context engineering</a> is the work of assembling general guidance that still leaves room for the user’s actual request. Newer Claude models need fewer hardcoded “never do X” constraints. They need cleaner interfaces and progressive disclosure.</p><p><code>CLAUDE.md</code> is guidance, not a lock. Claude treats it as context. If an action must be blocked no matter what the model decides, that belongs in permissions or a hook. Guardrails are a later post. Here the question is: what should occupy the window at all?</p><h2 id="Progressive-Disclosure"><a href="#Progressive-Disclosure" class="headerlink" title="Progressive Disclosure"></a>Progressive Disclosure</h2><p>The failure mode I keep seeing in my own repos is a <code>CLAUDE.md</code> that tries to be a handbook. Build commands, folder maps, review checklists, deploy steps, and “be careful with X” all sit in one file that loads on every turn.</p><p>Official size guidance is blunt: target <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/memory#write-effective-instructions">under 200 lines</a> per <code>CLAUDE.md</code>. Longer files cost tokens and reduce adherence. <code>/doctor</code> can propose trims for a checked-in file: cut what Claude can derive from the tree, keep pitfalls and conventions that differ from defaults.</p><p>My working split:</p><table><thead><tr><th>Keep in <code>CLAUDE.md</code></th><th>Move out</th></tr></thead><tbody><tr><td>What this repo is for, in a few lines</td><td>Directory tours Claude can <code>ls</code></td></tr><tr><td>Commands Claude cannot guess</td><td>Multi-step procedures</td></tr><tr><td>Gotchas and non-obvious invariants</td><td>Surface-specific style that only matters in one tree</td></tr><tr><td>Always / never rules that apply to every session</td><td>Side-effect workflows you want to invoke on purpose</td></tr></tbody></table><p>Procedures become <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/skills">skills</a>. A skill is lazily loaded: frontmatter and a short description stay in the catalog so Claude knows the skill exists; the body loads only when you type <code>/name</code> or Claude decides it is relevant. Path-specific conventions become rules in <code>.claude/rules/</code> with <code>paths</code> frontmatter, so they load when Claude reads a matching file, not at launch.</p><p>A skill encodes expertise. An agent is what acts with it. <code>SKILL.md</code> is the playbook. Claude Code (or a later SDK loop) is the worker that reads the playbook, calls tools, and updates the window. Mixing those two jobs is how a <code>CLAUDE.md</code> turns into a handbook: you stuffed an agent’s procedure into always-on memory.</p><p>That is progressive disclosure: the model always knows <em>that</em> a capability exists. It pays for the full text only when the task needs it.</p><h2 id="Imports-vs-Rules-vs-Skills"><a href="#Imports-vs-Rules-vs-Skills" class="headerlink" title="Imports vs Rules vs Skills"></a>Imports vs Rules vs Skills</h2><p><code>CLAUDE.md</code> scales by staying modular: a small root file, <code>@</code> imports for shared always-on snippets, and path-scoped rules for the file surface in play. <code>@</code> imports help humans navigate. They do not help the context window. <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/memory#import-additional-files">Imported files still expand at launch</a>. Use them to organize, not to hide cost.</p><table><thead><tr><th>Mechanism</th><th>When it loads</th><th>Use it for</th><th>Do not use it for</th></tr></thead><tbody><tr><td><strong><code>CLAUDE.md</code></strong></td><td>Every session, in full</td><td>Facts, gotchas, always / never, pointers to skills</td><td>Tutorials, dump of the file tree, long playbooks</td></tr><tr><td><strong><code>@</code> imports</strong></td><td>At launch, with the file that references them</td><td>Shared snippets you want in every session, or an <code>AGENTS.md</code> bridge</td><td>Large reference docs you only need sometimes</td></tr><tr><td><strong>Rules without <code>paths</code></strong></td><td>At launch, same priority as project <code>CLAUDE.md</code></td><td>Topic files that still apply everywhere</td><td>Anything you were trying to lazy-load</td></tr><tr><td><strong>Path-scoped rules</strong></td><td>When Claude reads a matching file</td><td>Conventions tied to a glob: <code>apps/web/**</code>, <code>**/*.test.ts</code></td><td>Procedures you invoke by name</td></tr><tr><td><strong>Skills</strong></td><td>Description at launch; body on invoke</td><td>Repeatable workflows, checklists, domain playbooks</td><td>One-line facts that belong in every session</td></tr></tbody></table><p>A useful test: if I would paste the text into chat only for some tasks, it is a skill. If it is true only when a certain path is open, it is a path-scoped rule. If I would re-explain it in every session, it stays in <code>CLAUDE.md</code>.</p><p>Skills also have a second context trick. Set <code>context: fork</code> when the workflow is noisy: a deploy check, a wide review, a script that prints a lot. The skill runs in a <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/skills#run-skills-in-a-subagent">subagent</a>. The main session keeps the summary, not the raw trace. Custom commands in <code>.claude/commands/</code> still work and still become <code>/name</code>. New work should be a skill so you can attach supporting files and control who may invoke it.</p><h2 id="Long-Conversations-Need-a-Strategy"><a href="#Long-Conversations-Need-a-Strategy" class="headerlink" title="Long Conversations Need a Strategy"></a>Long Conversations Need a Strategy</h2><p>Course 1 trains this on a long-running support copilot. I am not reprinting that exercise. The pattern I kept is a harness rule, not a product-specific trick.</p><p>A long session dies in a predictable way. Tool output is verbose. Early turns are resolved but still occupy tokens. The few facts that must stay true (order id, last error, what the user already confirmed) get buried in the middle of the window. The model then re-asks questions or “fixes” the wrong object.</p><p>The working model:</p><pre class="mermaid">flowchart LR    Raw[Verbose tool output] --&gt; Trim[Trim at the tool]    Trim --&gt; Facts[Persistent facts block]    Chat[Resolved turns] --&gt; Compress[Tiered compress]    Facts --&gt; Place[Place facts at head or tail]    Compress --&gt; Place    Place --&gt; Next[Next perceive / reason / act]    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff    classDef tealClass fill:#16A085,stroke:#333,stroke-width:2px,color:#fff    class Raw,Chat orangeClass    class Trim,Compress blueClass    class Facts greenClass    class Place purpleClass    class Next tealClass</pre><ol><li><strong>Trim at the tool boundary first.</strong> A deterministic cap (<code>--quiet</code>, a structured result, a line limit) is cheaper than asking the model to ignore a dump it already ingested. Claude Code already <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/tools-reference#timeout-and-output-limits">caps bash output</a> and, past that, returns a file path plus a short preview. That is a safety net, not a strategy. If I own the tool, I shrink the result before it enters the window.</li><li><strong>Keep a persistent facts block.</strong> Case id, environment, constraints, and confirmed decisions must not be compressed away. Write it as short bullets, not a transcript.</li><li><strong>Compress in tiers, under a stated budget.</strong> <code>/compact</code> is Claude Code’s version of this. When I assemble a window myself later, I will set the budget in tokens, not in “looks short enough.”</li><li><strong>Place critical facts, do not only include them.</strong> Models read the head and tail of a long window more reliably than the middle. A facts block buried between tool traces is as good as missing. After <code>/compact</code>, <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/memory#instructions-seem-lost-after-compact">project-root <code>CLAUDE.md</code> is re-read and re-injected</a>. Nested <code>CLAUDE.md</code> files and path-scoped rules are not. Skill <em>descriptions</em> are not re-injected either; only skills you already invoked are carried forward, and only within a token budget. Put durable facts in a slot that is re-attached at the edge of the working set: root <code>CLAUDE.md</code>, or a facts block your harness writes back to the head or tail.</li></ol><p>The squeeze rule I will reuse:</p><table><thead><tr><th>Layer</th><th>Squeeze</th><th>Keep</th></tr></thead><tbody><tr><td>Resolved turns</td><td>Hard</td><td>Outcome and the evidence that proved it</td></tr><tr><td>Active turns</td><td>Light</td><td>Enough to continue the current step</td></tr><tr><td>Facts block</td><td>Never</td><td>Case id, constraints, confirmed decisions</td></tr></tbody></table><p>The <a target="_blank" rel="noopener" href="https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models">context-engineering post</a> also dropped an older habit: repeat the same rule at the end of the window so the model cannot miss it. Newer models need less of that repetition. They still need the one copy to sit where it survives compact and where it is not lost in the middle of a log.</p><p>When I build my own loop with the Agent SDK (the next post), I will have to implement trim / facts / tiered compress / placement myself. In Claude Code, I get a head start: output caps, <code>/compact</code>, auto memory, forked skills, and Explore.</p><h2 id="Team-Config-for-a-Multi-Surface-Repo"><a href="#Team-Config-for-a-Multi-Surface-Repo" class="headerlink" title="Team Config for a Multi-Surface Repo"></a>Team Config for a Multi-Surface Repo</h2><p>The other Course 1 lesson I keep coming back to is a version-controlled Claude Code setup for a team that shares one monorepo. Again, my notes, not their files.</p><p>A single root <code>CLAUDE.md</code> that lists every package’s quirks will fight itself. Frontend “use the design tokens” and API “do not invent status codes” are both true, and both are noise when you are in the other tree.</p><p>The setup I want in a multi-surface repo:</p><table><thead><tr><th>Piece</th><th>Role</th></tr></thead><tbody><tr><td>Root <code>CLAUDE.md</code></td><td>Repo purpose, shared commands, always / never, links to skills</td></tr><tr><td>Path-scoped rules</td><td>One file per surface: <code>apps/web/**</code>, <code>apps/api/**</code>, <code>**/*.test.ts</code></td></tr><tr><td>Skills</td><td>Review, deploy-check, release notes: procedures with a <code>/name</code></td></tr><tr><td>Forked skills</td><td>Checks whose logs should not land in the main session</td></tr><tr><td>Slash entry points</td><td><code>/review</code> as a read-only skill; <code>/deploy-check</code> only when a human invokes it</td></tr></tbody></table><p><code>disable-model-invocation: true</code> is the right default for anything with side effects. Claude should not decide that the branch looks ready and run deploy. You type <code>/deploy-check</code> when you mean it.</p><p>The real config work is a decision framework, not a pile of files. Official docs already separate the modes:</p><table><thead><tr><th>Mode</th><th>What Claude can do</th><th>When I use it</th></tr></thead><tbody><tr><td><strong><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode">Plan mode</a></strong></td><td>Read and propose. No source edits until I approve.</td><td>Scope is unclear, several files will change, or I am new to the area</td></tr><tr><td><strong>Direct execution</strong></td><td>Edit and run in the main session</td><td>I can describe the diff in one sentence</td></tr><tr><td><strong><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/sub-agents">Explore</a></strong></td><td>Search in a separate window; only the findings return</td><td>I need a map, not a patch. Explore also skips <code>CLAUDE.md</code> to stay cheap</td></tr></tbody></table><p>Best-practice wording I agree with: <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/best-practices#explore-first-then-plan-then-code">explore, then plan, then code</a>. Skip the ceremony for a typo. Pay for it when the wrong edit is expensive.</p><p>One monorepo detail that surprised me: Explore and Plan skip your <code>CLAUDE.md</code> on purpose. The parent session still has those instructions when it reads the summary. If a rule must reach the researcher (“ignore <code>vendor/</code>“), put it in the delegation prompt.</p><h2 id="Tool-Descriptions-Are-Context-Too"><a href="#Tool-Descriptions-Are-Context-Too" class="headerlink" title="Tool Descriptions Are Context Too"></a>Tool Descriptions Are Context Too</h2><p>Part 1 said a vague tool contract wastes the loop. I now treat the description as part of the prompt, because it is.</p><p>The <a target="_blank" rel="noopener" href="https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models">new context-engineering rules</a> dropped a habit I used to follow: pile examples into the tool text so the model cannot miss the shape. Newer models explore less when you over-specify the happy path. They do better when the interface is expressive: clear name, when to call it, parameters that encode the real choices, and a result the next turn can use.</p><p>A working checklist for any tool I add later (CLI, MCP, or SDK):</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line">Name: what this tool is for, in the verb the model should think</span><br><span class="line">When to use: the situation, not a slogan</span><br><span class="line">When not to use: the overlapping tool that is a better fit</span><br><span class="line">Inputs: required vs optional, with units and invariants</span><br><span class="line">Output: the fields the next reason step will read</span><br><span class="line">Failure: what an empty or error result means</span><br></pre></td></tr></tbody></table></figure><p>“Search the system” is a weak contract. “Find an invoice by id or by customer email; return id, status, and outstanding cents; return not_found instead of guessing” is a contract the loop can verify. The return shape is the first trim: a small structured result beats a raw dump the model is then asked to filter. If two tools overlap, say so in both descriptions. Silent overlap is how the agent calls the wrong one and then reasons over junk.</p><p>I will go deeper on MCP tool design in a later post. The takeaway for this one: if the description is vague, the perception step is already compromised.</p><h2 id="How-I-Will-Set-This-Up"><a href="#How-I-Will-Set-This-Up" class="headerlink" title="How I Will Set This Up"></a>How I Will Set This Up</h2><p>A checklist I can reuse on the next repo:</p><ol><li>Run <code>/init</code>, then delete anything Claude can see by reading the tree.</li><li>Keep root <code>CLAUDE.md</code> under 200 lines: purpose, commands, gotchas, always / never. Scale with <code>@</code> imports and path-scoped rules, not a longer root file.</li><li>Treat skills as expertise, not as extra agents. Point at them instead of inlining playbooks. <code>@</code> import only what must load every session.</li><li>Add <code>.claude/rules/</code> with <code>paths</code> for each surface. Leave unscoped rules for true globals.</li><li>Put review and deploy-check in skills. Fork the noisy ones. Set <code>disable-model-invocation: true</code> on side effects.</li><li>Write down the mode rule: plan for unfamiliar or cross-cutting work, Explore for research, direct for small diffs.</li><li>For any tool I add, return a small structured result. Do not dump a log and ask the model to filter it.</li><li>Run <code>/context</code> and <code>/doctor</code>. If a line would not change a decision, cut it.</li><li>After a long session, ask: which facts should have sat in a persistent block at the head or tail, and which tool dumps should have been trimmed before they entered the window?</li></ol><h3 id="Before-After-a-Small-CLAUDE-md"><a href="#Before-After-a-Small-CLAUDE-md" class="headerlink" title="Before / After: a Small CLAUDE.md"></a>Before / After: a Small <code>CLAUDE.md</code></h3><p>Invented example, not a course file. Imagine <code>invoice-desk</code>: a TypeScript API, a React dashboard, and shared types.</p><p><strong>Before</strong> (loads every session, teaches almost nothing Claude cannot discover):</p><figure class="highlight markdown hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-section"># invoice-desk</span></span><br><span class="line"></span><br><span class="line">This monorepo has three packages:</span><br><span class="line"><span class="hljs-bullet">-</span> apps/api: Fastify API</span><br><span class="line"><span class="hljs-bullet">-</span> apps/web: Vite + React dashboard</span><br><span class="line"><span class="hljs-bullet">-</span> packages/shared: Zod types</span><br><span class="line"></span><br><span class="line"><span class="hljs-section">## Commands</span></span><br><span class="line"><span class="hljs-bullet">-</span> API: cd apps/api &amp;&amp; npm test</span><br><span class="line"><span class="hljs-bullet">-</span> Web: cd apps/web &amp;&amp; npm run dev</span><br><span class="line"><span class="hljs-bullet">-</span> Lint everything with npm run lint from the root</span><br><span class="line"></span><br><span class="line"><span class="hljs-section">## API</span></span><br><span class="line">When you add an endpoint, update the OpenAPI file, add a Zod schema</span><br><span class="line">in packages/shared, write a test, and restart the dev server. Status</span><br><span class="line">codes: 200, 201, 400, 401, 404, 409, 422, 500. Never invent a 418.</span><br><span class="line">Always paginate list endpoints. Use the standard error envelope.</span><br><span class="line"></span><br><span class="line"><span class="hljs-section">## Web</span></span><br><span class="line">Use the design tokens in apps/web/src/theme.ts. Do not add raw hex</span><br><span class="line">colors. Components go in apps/web/src/components. Pages go in</span><br><span class="line">apps/web/src/pages. Run Playwright for any flow that touches money.</span><br><span class="line"></span><br><span class="line"><span class="hljs-section">## Review</span></span><br><span class="line">Read the diff, check types, check tests, check migrations, write a</span><br><span class="line">summary with risk, then suggest a commit message.</span><br></pre></td></tr></tbody></table></figure><p><strong>After</strong> (facts and gotchas; procedures and surfaces live elsewhere):</p><figure class="highlight markdown hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-section"># invoice-desk</span></span><br><span class="line"></span><br><span class="line">Internal invoicing for one workspace. Money is integer cents.</span><br><span class="line">Never invent an invoice id.</span><br><span class="line"></span><br><span class="line"><span class="hljs-section">## Commands Claude cannot guess</span></span><br><span class="line"><span class="hljs-bullet">-</span> <span class="hljs-code">`npm test --workspace=api -- &lt;file&gt;`</span> for a single API test</span><br><span class="line"><span class="hljs-bullet">-</span> <span class="hljs-code">`npm run e2e -- --grep @money`</span> for money-path Playwright</span><br><span class="line"></span><br><span class="line"><span class="hljs-section">## Always / never</span></span><br><span class="line"><span class="hljs-bullet">-</span> Always keep invoice totals in cents in <span class="hljs-code">`packages/shared`</span></span><br><span class="line"><span class="hljs-bullet">-</span> Never edit <span class="hljs-code">`apps/api/src/legacy/import-jobs.ts`</span> without a pair</span><br><span class="line"><span class="hljs-bullet">-</span> Never run deploy from a skill; use <span class="hljs-code">`/deploy-check`</span> only</span><br><span class="line"></span><br><span class="line"><span class="hljs-section">## Load on demand</span></span><br><span class="line"><span class="hljs-bullet">-</span> Web tokens and component rules: <span class="hljs-code">`.claude/rules/web.md`</span></span><br><span class="line"><span class="hljs-bullet">-</span> API errors and pagination: <span class="hljs-code">`.claude/rules/api.md`</span></span><br><span class="line"><span class="hljs-bullet">-</span> Review workflow: <span class="hljs-code">`/review`</span></span><br><span class="line"><span class="hljs-bullet">-</span> Deploy readiness: <span class="hljs-code">`/deploy-check`</span> (forked, human-invoked)</span><br></pre></td></tr></tbody></table></figure><p>The path-scoped API rule can be a short file:</p><figure class="highlight markdown hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br></pre></td><td class="code"><pre><span class="line">---</span><br><span class="line">paths:</span><br><span class="line"><span class="hljs-bullet">  -</span> "apps/api/<span class="hljs-strong">**/<span class="hljs-emphasis">*.ts"</span></span></span><br><span class="line"><span class="hljs-emphasis"><span class="hljs-strong">  - "packages/shared/*</span><span class="hljs-emphasis">*/*</span>.ts"</span></span><br><span class="line"><span class="hljs-strong">---</span></span><br><span class="line"><span class="hljs-strong"></span></span><br><span class="line"><span class="hljs-strong"># API surface</span></span><br><span class="line"><span class="hljs-strong"></span></span><br><span class="line"><span class="hljs-strong">- List endpoints paginate; do not return unbounded arrays</span></span><br><span class="line"><span class="hljs-strong">- Errors use `{ error, code, details }`; do not invent status 418</span></span><br><span class="line"><span class="hljs-strong">- New fields go through Zod in `packages/shared` first</span></span><br></pre></td></tr></tbody></table></figure><p>The <code>/review</code> skill body stays out of the default window until someone invokes it. That is the whole point.</p><h2 id="Putting-the-Concepts-into-Practice"><a href="#Putting-the-Concepts-into-Practice" class="headerlink" title="Putting the Concepts into Practice"></a>Putting the Concepts into Practice</h2><p>Pick one repo you already use with Claude Code and write this brief before you add more files:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line">Repo purpose (2 lines):</span><br><span class="line">Always / never:</span><br><span class="line">Commands Claude cannot guess:</span><br><span class="line">Surfaces that need path-scoped rules:</span><br><span class="line">Skills whose full body should stay out of the default window:</span><br><span class="line">Facts that must survive compact, and where they sit:</span><br><span class="line">Tools that still return a dump instead of a trimmed result:</span><br></pre></td></tr></tbody></table></figure><p>Then inspect a real session:</p><ol><li>Run <code>/context</code>. What loaded that you did not need?</li><li>Which <code>CLAUDE.md</code> lines are a procedure in disguise?</li><li>Did a path-scoped rule fire when you opened the matching files?</li><li>Did a forked skill or Explore keep a noisy trace out of the main window?</li><li>After <code>/compact</code>, which instruction disappeared, and should it live in root <code>CLAUDE.md</code> or a facts block at the edge of the window?</li></ol><p>If you cannot answer those, the config is still a document, not a working set.</p><h2 id="Key-Terms"><a href="#Key-Terms" class="headerlink" title="Key Terms"></a>Key Terms</h2><ul><li><strong>Context engineering</strong>: Assembling the instructions, evidence, and tool contracts the model needs for the next decision, while keeping the rest out of the window</li><li><strong>Context budget</strong>: Every token stays in the working set and is paid for on later turns; treat the window as a scarce allocation, not a dump</li><li><strong>Progressive disclosure</strong>: Keep a small index in context; load the full text only when the task needs it</li><li><strong><code>CLAUDE.md</code></strong>: Project, user, or managed instructions loaded at session start; guidance, not enforcement</li><li><strong><code>@</code> import</strong>: A file expanded into <code>CLAUDE.md</code> at launch; useful for structure, not for lazy-loading</li><li><strong>Path-scoped rule</strong>: A <code>.claude/rules/</code> file with <code>paths</code> frontmatter that loads when Claude reads a matching file</li><li><strong>Skill</strong>: Encoded expertise whose description is listed up front and whose body loads on invoke; not an agent</li><li><strong>Agent</strong>: The loop that perceives, reasons, and acts, using skills and tools</li><li><strong>Forked skill</strong>: A skill with <code>context: fork</code> that runs in a subagent so verbose output stays out of the main session</li><li><strong>Auto memory</strong>: Notes Claude writes for itself; the <code>MEMORY.md</code> index loads every session, topic files load on demand</li><li><strong>Facts block</strong>: A short, durable set of case or project facts you re-attach so they survive prune and compact</li><li><strong>Tiered compression</strong>: Squeeze resolved turns hardest, keep active turns fuller, never drop the facts block, all under a stated token budget</li><li><strong>Plan mode</strong>: Read-and-propose workflow with edits blocked until you approve</li><li><strong>Explore</strong>: Built-in research subagent that returns findings without filling the parent window</li></ul><h2 id="Final-Thoughts"><a href="#Final-Thoughts" class="headerlink" title="Final Thoughts"></a>Final Thoughts</h2><p>The loop from Part 1 does not get cheaper when I paste more instructions. It gets cheaper when each instruction has a load rule and each tool result has a size. Root <code>CLAUDE.md</code> holds facts. Rules hold surface law. Skills hold expertise the agent can load. Tool descriptions hold contracts. Long sessions keep a facts block at the edge of the window and throw the rest away.</p><p>That is the setup I will carry into the rest of this series. The next post moves from Claude Code configuration to the harness: the Agent SDK, the stop-reason loop, and the context strategy you have to implement when you own the runtime.</p><h2 id="References"><a href="#References" class="headerlink" title="References"></a>References</h2><ul><li>AI Engineering with Claude</li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/memory">CLAUDE.md and memory</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/skills">Skills</a></li><li><a target="_blank" rel="noopener" href="https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models">The new rules of context engineering</a></li></ul><hr><p><em>This is Part 2 of 6 in the Agentic Coding with Claude Code series.</em></p></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;p&gt;In &lt;a href=&quot;/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/&quot;&gt;Part 1&lt;/a&gt;, I treated Claude Code as a bounded loop: perceive, reason, act, then feed the evidence back in. The reasoning engine is only as good as the working set it sees. A precise goal still fails if the window is full of directory trees, stale chat, and a vague tool contract.&lt;/p&gt;
&lt;p&gt;This is Part 2 of 6 in my &lt;strong&gt;Agentic Coding with Claude Code&lt;/strong&gt; series. The working model I am keeping is simple: context is assembled, not typed, and it is a budget, not a bucket.&lt;/p&gt;
&lt;p&gt;&lt;code&gt;CLAUDE.md&lt;/code&gt;, path-scoped rules, skills, memory, tool results, and the conversation all compete for the same tokens. Unfiltered tool output is paid for on every later turn. The job is to load the right slice at the right time.&lt;/p&gt;
&lt;p&gt;Later posts will cover the harness and Agent SDK, MCP, evals, and guardrails. This one stays on the context layer that shapes every decision in the loop.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="context-engineering" scheme="https://vanducng.dev/tags/context-engineering/"/>
    
    <category term="agentic-coding" scheme="https://vanducng.dev/tags/agentic-coding/"/>
    
    <category term="claude-code" scheme="https://vanducng.dev/tags/claude-code/"/>
    
  </entry>
  
  <entry>
    <title>What Cordis Does Inside DeepSeek Harness</title>
    <link href="https://vanducng.dev/2026/08/15/what-cordis-does-inside-deepseek-harness/"/>
    <id>https://vanducng.dev/2026/08/15/what-cordis-does-inside-deepseek-harness/</id>
    <published>2026-08-15T02:00:00.000Z</published>
    <updated>2026-11-16T05:26:58.282Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><blockquote><p><strong>Source</strong>: <a target="_blank" rel="noopener" href="https://blog.antinomie.org/">Cordis 在做什么：从 DeepSeek Harness 看</a> by Antinomie on antinomie.org. The piece is the site’s current homepage post.</p></blockquote><p>DeepSeek Harness (DSH) is an agent harness built on Cordis. The first thing that clicks is not a privileged core loop. Model adapters, tool registries, session logs, and the agent loop itself are all plugins.</p><p>This is the first post in my <strong>DeepSeek Harness</strong> series. I am starting with a close reading of how DSH actually uses Cordis: services, <code>inject</code>, reversible <code>ctx.effect</code> registration, Loader, and the config layers that turn composition into data.</p><span id="more"></span><blockquote><p><strong>Version note</strong>: Code citations pin <a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> <code>master</code> @ <a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/tree/47f943859b"><code>47f943859b</code></a>. Cordis is the vendored source snapshot <code>@deepseek-ai/cordis@4.0.1</code> in <a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/vendor/cordis/package.json"><code>vendor/cordis/package.json</code></a>.</p><p>Cordis has a theoretical background in <a target="_blank" rel="noopener" href="https://github.com/cordiverse/paper"><em>A Programming Paradigm for Spatiotemporal Composability</em></a> (<a target="_blank" rel="noopener" href="https://github.com/cordiverse/paper/blob/main/paper.pdf">PDF</a>; cited as “paper section x.y”). This post does not unpack the theory. It uses the mechanisms to answer one question: <strong>how does DeepSeek Harness use the features Cordis provides?</strong></p><p>Every code citation keeps <code>file:line</code> and links to the GitHub source at that commit.</p></blockquote><h2 id="1-Premise-Everything-Is-a-Plugin"><a href="#1-Premise-Everything-Is-a-Plugin" class="headerlink" title="1. Premise: Everything Is a Plugin"></a>1. Premise: Everything Is a Plugin</h2><p>DSH is an agent harness.</p><p>Its first principle is: <strong>model adapters, the tool registry, session logs, and the agent loop itself are all Cordis plugins. There is no privileged core.</strong> So “how DSH uses Cordis” and “how DSH is built” are the same question.</p><p>The second principle is about how packages are split: <strong>one capability becomes three packages</strong>. The Definition package defines the service. The Provider package supplies an implementation. The Consumer package uses the capability. Providers attach an implementation to a service name in two ways:</p><ul><li><strong>Exclusive</strong>: the provider occupies the service name. Only one implementation is live at a time. Shell works this way: <code>bash-sandbox</code> occupies <code>ctx.shell</code> (section 3). A second implementation throws at <code>provide</code> time (the duplicate check in section 5). Which implementation is running is not a runtime race. Configuration decides it statically. <code>dsh --profile web --dump-config</code> shows the stacked tree that actually takes effect.</li><li><strong>Registry-style</strong>: several implementations coexist under one capability. The Definition package holds a registry. That registry is not a framework feature. It is just a <code>Map</code> on the service, for example <code>WebRuntime</code>‘s <code>private searchProviders = new Map&lt;string, WebSearchProvider&gt;()</code> (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/web/web/src/index.ts#L85"><code>packages/web/web/src/index.ts:85</code></a>). “Register into the registry” means the provider calls a register method and lands in that <code>Map</code> (<code>store.set</code> in section 5). The registry absorbs high-frequency implementation changes: swap one implementation and you only undo one entry and add another. Plugins that depend on the service stay still.</li></ul><p>Take the shell capability that will keep showing up:</p><ul><li><strong>Definition</strong>: <code>@deepseek-ai/dsh-shell</code> (<code>ShellExecutor</code> plus a type patch, unpacked in section 3)</li><li><strong>Provider</strong>: <code>@deepseek-ai/dsh-bash-sandbox</code> (<code>SandboxBashExecutor</code> in section 6, plus bash-local and the pwsh family)</li><li><strong>Consumer</strong>: <code>@deepseek-ai/dsh-tool-bash</code>, which declares <code>inject = ['tools', 'shell', 'systemPrompt', 'shellEnv']</code> (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/shell/tool-bash/src/index.ts#L31"><code>packages/shell/tool-bash/src/index.ts:31</code></a>), wraps shell as a bash tool the model can see, and calls <code>ctx.shell.run(...)</code> at <a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/shell/tool-bash/src/index.ts#L380">line 380</a></li></ul><p>Provider and consumer never import each other. Both only know the Definition package and the service name. Swap the implementation and the consumer does not change a line.</p><pre class="mermaid">flowchart TB    Def["Definition<br>@deepseek-ai/dsh-shell"]    Prov["Provider<br>dsh-bash-sandbox / bash-local / pwsh"]    Cons["Consumer<br>dsh-tool-bash"]    Def --&gt; Prov    Def --&gt; Cons    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    class Def blueClass    class Prov orangeClass    class Cons greenClass</pre><p>I have to admit: because DeepSeek Harness needs a plugin tree with spatiotemporal independence, the framework code is expensive to understand. As a developer, we only need the mechanisms. And after this article, the surprise is that most of that complexity is eaten by DeepSeek Harness itself. Adding a plugin does not add extra complexity.</p><h2 id="2-One-Boot-Five-Lines-Every-Concept"><a href="#2-One-Boot-Five-Lines-Every-Concept" class="headerlink" title="2. One Boot: Five Lines, Every Concept"></a>2. One Boot: Five Lines, Every Concept</h2><p>Run <code>dsh --profile headless "fix this bug"</code> and you land in <code>boot()</code> (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/boot/app-boot/src/index.ts#L757-L784"><code>packages/boot/app-boot/src/index.ts:757-784</code></a>, error handling omitted):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">export</span> <span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span> <span class="title function_">boot</span>(<span class="hljs-params"></span></span><br><span class="line"><span class="hljs-params">  <span class="hljs-attr">binName</span>: <span class="hljs-built_in">string</span>,</span></span><br><span class="line"><span class="hljs-params">  <span class="hljs-attr">absoluteConfigPath</span>: <span class="hljs-built_in">string</span>,</span></span><br><span class="line"><span class="hljs-params">  <span class="hljs-comment">// ...</span></span></span><br><span class="line"><span class="hljs-params"></span>): <span class="title class_">Promise</span>&lt;<span class="title class_">Context</span>&gt; {</span><br><span class="line">  <span class="hljs-keyword">const</span> ctx = <span class="hljs-keyword">new</span> <span class="title class_">Context</span>()</span><br><span class="line">  <span class="hljs-comment">// ...</span></span><br><span class="line">  ctx.<span class="title function_">provide</span>(<span class="hljs-string">'dshHomePath'</span>, dshHomePath)</span><br><span class="line">  <span class="hljs-keyword">await</span> ctx.<span class="title function_">plugin</span>(<span class="title class_">Loader</span>)</span><br><span class="line">  <span class="hljs-comment">// ...</span></span><br><span class="line">  <span class="hljs-keyword">await</span> <span class="title function_">mountRootInclude</span>(ctx, absoluteConfigPath, patches, bareModuleBaseUrl)</span><br><span class="line">  <span class="hljs-keyword">await</span> ctx.<span class="title function_">get</span>(<span class="hljs-string">'loader'</span>)?.<span class="title function_">await</span>()</span><br><span class="line">  <span class="hljs-keyword">if</span> (ctx.<span class="title function_">get</span>(<span class="hljs-string">'loader'</span>) === <span class="hljs-literal">undefined</span>) <span class="hljs-keyword">return</span> ctx</span><br><span class="line">  <span class="hljs-keyword">await</span> <span class="title function_">assertEntriesActivated</span>(ctx, binName)</span><br><span class="line">  <span class="hljs-keyword">return</span> ctx</span><br><span class="line">}</span><br></pre></td></tr></tbody></table></figure><p>Those five lines map to five Cordis mechanisms:</p><ul><li><code>new Context()</code>: create the root of the plugin tree. Context is both the service store (every later <code>ctx.xxx</code> is registered on it) and a tree node. Each mounted plugin gets its own child context. Unload the parent and the subtree unloads with it.</li><li><code>ctx.provide('dshHomePath', ...)</code>: the first service registration. Hang a value on ctx so the whole system can read it.</li><li><code>ctx.plugin(Loader)</code>: programmatically mount the first plugin. Loader reads YAML config.</li><li><code>mountRootInclude(...)</code>: hand <code>cordis.yml</code> (plus patch layers, section 7) to Loader, which expands it declaratively into the full plugin tree.</li><li><code>await ctx.get('loader')?.await()</code> plus <code>assertEntriesActivated(...)</code>: wait until the tree is in place, then audit. If an entry never activates (for example a declared dependency will never exist), fail here and name what is missing. Do not run with a half-loaded tree.</li></ul><pre class="mermaid">flowchart LR    A["new Context()"] --&gt; B["provide dshHomePath"]    B --&gt; C["plugin Loader"]    C --&gt; D["mount cordis.yml"]    D --&gt; E["await + audit"]    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff    classDef tealClass fill:#16A085,stroke:#333,stroke-width:2px,color:#fff    class A blueClass    class B orangeClass    class C greenClass    class D purpleClass    class E tealClass</pre><p>The next three sections unpack the three most important mechanisms on this tree: services, dependency declarations, and reversible registration. Section 6 looks at a plugin as a whole. Section 7 covers the config layers.</p><h3 id="Plugin-the-unit-of-loaded-code"><a href="#Plugin-the-unit-of-loaded-code" class="headerlink" title="Plugin: the unit of loaded code"></a>Plugin: the unit of loaded code</h3><p><strong>A plugin is the unit of loaded code</strong>: an <code>inject</code> declaration plus a block that runs after its dependencies are ready. That block has two shapes:</p><ul><li>A function plugin exports <code>apply(ctx, config)</code>.</li><li>A class plugin (<code>extends Service</code>) has no <code>apply</code>. <strong>Its constructor is that block.</strong></li></ul><p>Both receive the same <code>(ctx, config)</code>. A plugin has a lifecycle: instantiate on mount, reclaim everything it registered on unload.</p><h3 id="Service-an-object-shared-by-name"><a href="#Service-an-object-shared-by-name" class="headerlink" title="Service: an object shared by name"></a>Service: an object shared by name</h3><p><strong>A service is an object one plugin shares with the rest of the system by name.</strong> The provider uses <code>provide</code> to bind an object to a service name (<code>'web'</code>, <code>'shell'</code>, <code>'llm'</code>). The consumer reads the same name as <code>ctx.web</code>.</p><p>The object can be anything. <code>dshHomePath</code> is just a string. <code>loader</code> is an instance with methods. After Loader is mounted with <code>ctx.plugin</code>, its constructor binds itself to the <code>loader</code> service name (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/vendor/loader/src/index.ts#L90"><code>vendor/loader/src/index.ts:90</code></a>; a class plugin’s constructor is the startup code, see section 3):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">ctx.<span class="hljs-property">reflect</span>.<span class="title function_">provide</span>(<span class="hljs-string">'loader'</span>, <span class="variable language_">this</span>, <span class="variable language_">this</span>[<span class="title class_">Service</span>.<span class="hljs-property">check</span>])</span><br></pre></td></tr></tbody></table></figure><p>The only shared contract is the service name. <code>web-search-exa</code> declares that it needs <code>web</code>. It does not know or care which plugin provides the object.</p><p>If the provider is not loaded yet, reading the name returns nothing. If the provider is unloaded, the binding disappears. “I need this service” is not the same as “I can read it now.” That is why we need <code>inject</code>: declare which services a plugin needs to start, then <strong>wait until those services are in place</strong>. That is section 4.</p><p>And “wait until ready” is not a one-shot. If a running service is swapped (for example the <code>shell</code> implementation plugin changes from bash-local to pwsh), Cordis reloads every plugin that declared it needs <code>shell</code> and re-runs <code>apply</code> on the new tree. If a service loses its provider, those plugins are stopped first. Dependencies always point at the provider that is currently in effect, not the one that existed at first boot.</p><p>Why reload instead of quietly handing the new object to a running plugin? Because <code>apply</code> already ran. The old implementation may already be captured in event listeners or timer closures. Swap only the object and the plugin still holds the old reference. Undo all of its effects and re-run <code>apply</code> on the new implementation. That is the only consistent way to land the whole plugin on the new implementation.</p><p>Why can reload happen at any time? Because every effect is reversible. There is no half-success, half-failure middle state. That is section 5.</p><p>Keep two layers of change distinct. The example above swaps <strong>the service provider</strong>, which triggers reload. When a registry-style provider such as web-search-exa is swapped (sections 4 and 5), <strong>no plugin reloads</strong>. The registry undoes one entry and adds another. The next <code>ctx.web.search()</code> follows the selection rules onto the new provider. That is the point of the three-package split in section 1: high-frequency provider changes stop at the registry layer and do not disturb plugins that depend on the service.</p><h3 id="The-plugin-tree-who-mounts-whom"><a href="#The-plugin-tree-who-mounts-whom" class="headerlink" title="The plugin tree: who mounts whom"></a>The plugin tree: who mounts whom</h3><p>The plugin tree is the set of “who mounted whom” edges. There are two ways to declare those edges. Start with the programmatic one.</p><blockquote><p><strong>Programmatic</strong>: <code>ctx.plugin(X)</code> mounts X as a child of the ctx at the call site. X’s <code>apply</code> receives that new child ctx. If X then calls <code>ctx.plugin(Y)</code> inside its own <code>apply</code>, Y is X’s child. agent-spine in section 4 fires about twenty <code>ctx.plugin</code> calls in a row and produces a subtree with twenty-odd children.</p></blockquote><p>Mount and start are separate actions.</p><p>Here is everything <code>ctx.plugin(X)</code> does (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/vendor/cordis/src/registry.ts#L316-L330"><code>vendor/cordis/src/registry.ts:316-330</code></a>, <code>RegistryService.plugin</code>, return wrapping omitted):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br></pre></td><td class="code"><pre><span class="line"><span class="title function_">plugin</span>(<span class="hljs-params"><span class="hljs-attr">plugin</span>: <span class="title class_">Plugin</span>, <span class="hljs-attr">config</span>?: <span class="hljs-built_in">any</span>, getOuterStack = buildOuterStack()</span>) {</span><br><span class="line">  <span class="hljs-keyword">const</span> callback = <span class="variable language_">this</span>.<span class="title function_">resolve</span>(plugin)   <span class="hljs-comment">// function / class / { apply } object, unified into one callback</span></span><br><span class="line">  <span class="hljs-keyword">if</span> (!callback) <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="title class_">Error</span>(<span class="hljs-string">'invalid plugin, ...'</span>)</span><br><span class="line">  <span class="variable language_">this</span>.<span class="hljs-property">ctx</span>.<span class="hljs-property">fiber</span>.<span class="title function_">assertActive</span>()</span><br><span class="line"></span><br><span class="line">  <span class="hljs-keyword">let</span> runtime = <span class="variable language_">this</span>.<span class="hljs-property">_internal</span>.<span class="title function_">get</span>(callback)   <span class="hljs-comment">// registry for this plugin; fibers is a list</span></span><br><span class="line">  <span class="hljs-keyword">if</span> (!runtime) {</span><br><span class="line">    <span class="hljs-comment">// ...</span></span><br><span class="line">    runtime = { name, callback, <span class="hljs-attr">fibers</span>: <span class="hljs-keyword">new</span> <span class="title class_">DisposableList</span>(), <span class="title class_">Config</span>: plugin.<span class="hljs-property">Config</span> }</span><br><span class="line">    <span class="variable language_">this</span>.<span class="hljs-property">_internal</span>.<span class="title function_">set</span>(callback, runtime)</span><br><span class="line">  }</span><br><span class="line"></span><br><span class="line">  <span class="hljs-keyword">const</span> fiber = <span class="hljs-keyword">new</span> <span class="title class_">Fiber</span>(<span class="variable language_">this</span>.<span class="hljs-property">ctx</span>, config, <span class="title class_">Inject</span>.<span class="title function_">resolve</span>(plugin.<span class="hljs-property">inject</span>), runtime, getOuterStack)</span><br></pre></td></tr></tbody></table></figure><p>Look at the last line: config and the inject declaration enter the fiber at this moment.</p><p>A <strong>fiber</strong> is the runtime object for one mount. It holds that mount’s config, inject declaration, child ctx, and lifecycle state machine. This post does not unpack the state machine. Remember two faces: it holds a disposal list used to undo effects (section 5), and it waits until inject dependencies are complete before starting (section 4).</p><p>Fiber’s constructor (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/vendor/cordis/src/fiber.ts#L222-L265"><code>vendor/cordis/src/fiber.ts:222-253,265</code></a>, intercept bookkeeping omitted):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br></pre></td><td class="code"><pre><span class="line"><span class="title function_">constructor</span>(<span class="hljs-params"></span></span><br><span class="line"><span class="hljs-params">  <span class="hljs-keyword">public</span> <span class="hljs-attr">parent</span>: <span class="title class_">Context</span>,</span></span><br><span class="line"><span class="hljs-params">  <span class="hljs-attr">config</span>: <span class="hljs-built_in">any</span>,</span></span><br><span class="line"><span class="hljs-params">  <span class="hljs-keyword">public</span> <span class="hljs-attr">inject</span>: <span class="title class_">Dict</span>&lt;<span class="hljs-built_in">any</span>&gt;,</span></span><br><span class="line"><span class="hljs-params">  <span class="hljs-keyword">public</span> <span class="hljs-attr">runtime</span>: <span class="title class_">Plugin</span>.<span class="title class_">Runtime</span> | <span class="hljs-literal">null</span>,</span></span><br><span class="line"><span class="hljs-params">  <span class="hljs-comment">// ...</span></span></span><br><span class="line"><span class="hljs-params"></span>) {</span><br><span class="line">  <span class="variable language_">this</span>.<span class="hljs-property">_config</span> = config</span><br><span class="line">  <span class="hljs-comment">// ...</span></span><br><span class="line">  <span class="variable language_">this</span>.<span class="hljs-property">ctx</span> = <span class="variable language_">this</span>.<span class="hljs-property">context</span> = parent.<span class="title function_">extend</span>({ <span class="hljs-attr">fiber</span>: <span class="variable language_">this</span> })   <span class="hljs-comment">// derive a child ctx</span></span><br><span class="line"></span><br><span class="line">  <span class="variable language_">this</span>.<span class="hljs-property">_runner</span> = {</span><br><span class="line">    <span class="hljs-attr">epoch</span>: <span class="variable constant_">INACTIVE</span>,</span><br><span class="line">    <span class="hljs-attr">execute</span>: <span class="hljs-keyword">function</span> (<span class="hljs-params"></span>) {</span><br><span class="line">      <span class="hljs-keyword">if</span> (<span class="title function_">isConstructor</span>(runtime.<span class="hljs-property">callback</span>)) {</span><br><span class="line">        <span class="hljs-keyword">const</span> instance = <span class="hljs-keyword">new</span> runtime.<span class="title function_">callback</span>(<span class="variable language_">this</span>.<span class="hljs-property">ctx</span>, <span class="variable language_">this</span>.<span class="hljs-property">config</span>)   <span class="hljs-comment">// ← the impl class is new'ed only at start</span></span><br><span class="line">        <span class="hljs-comment">// ...</span></span><br><span class="line">      } <span class="hljs-keyword">else</span> {</span><br><span class="line">        <span class="hljs-keyword">return</span> runtime.<span class="title function_">callback</span>(<span class="variable language_">this</span>.<span class="hljs-property">ctx</span>, <span class="variable language_">this</span>.<span class="hljs-property">config</span>)</span><br><span class="line">      }</span><br><span class="line">    },</span><br><span class="line">    collect,</span><br><span class="line">  }</span><br><span class="line"></span><br><span class="line">  <span class="variable language_">this</span>.<span class="hljs-property">dispose</span> = parent.<span class="hljs-property">fiber</span>.<span class="title function_">effect</span>(<span class="hljs-function">() =&gt;</span> {   <span class="hljs-comment">// register self as a parent-fiber effect → cascading unload</span></span><br><span class="line">    <span class="hljs-keyword">const</span> remove = runtime.<span class="hljs-property">fibers</span>.<span class="title function_">push</span>(<span class="variable language_">this</span>)</span><br><span class="line">    <span class="hljs-comment">// ...</span></span><br><span class="line">  })</span><br></pre></td></tr></tbody></table></figure><p>The <code>execute</code> closure is only prepared. The constructor does not call it. The implementation class object is <code>new</code>‘ed only when the fiber starts (inject dependencies are complete, then <code>execute</code> runs).</p><p>That is the split:</p><ul><li><strong>Mount</strong> = build a fiber and hang it on the tree. Synchronous, immediate, and it does not run plugin code.</li><li><strong>Start</strong> = run <code>execute</code>. Timing is decided by dependencies (section 4). agent-spine can write <code>ctx.plugin(...)</code> in any order because every mount finishes immediately. Who starts first is decided by dependencies, not by source order.</li></ul><p>After the programmatic path, there is a second way to declare mount edges: declarative.</p><blockquote><p><strong>Declarative</strong>: an entry in <code>cordis.yml</code> with <code>group: true</code> has a <code>config</code> that is a list of child entries (in section 7, <code>pty</code> is nested under <code>persistent-shell</code> in the minimal preset). Loader instantiates the entry hierarchy into a tree of the same shape. “Unload the parent and the subtree unloads” is one sentence: a child instance registers itself as an effect of the parent instance (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/vendor/cordis/src/fiber.ts#L265"><code>vendor/cordis/src/fiber.ts:265</code></a>), and effects are reclaimed automatically when their instance unloads (section 5). Unload the parent and the whole subtree is reclaimed in cascade.</p></blockquote><p>Why two ways? They face different people.</p><p><strong>Declarative is for the orchestrator.</strong> That person manages the whole system and wants a data file they can edit line by line: disable a row, replace one row’s config, then hot-reload. To the orchestrator, agent-spine is one line in <code>cordis.yml</code>. How many child plugins it contains is not their problem.</p><p><strong>Programmatic is for the component author.</strong> Inside a component you need “decide which child plugins to mount from my own config, and with what settings.” Literal YAML fields cannot express that. You write code.</p><p>Both paths produce the same tree. Children of a YAML group and children mounted by a bundle go through the same inject wait and the same effect reclaim.</p><h2 id="3-Services-Where-ctx-shell-Comes-From"><a href="#3-Services-Where-ctx-shell-Comes-From" class="headerlink" title="3. Services: Where ctx.shell Comes From"></a>3. Services: Where <code>ctx.shell</code> Comes From</h2><p>In DSH, <code>ctx.shell</code>, <code>ctx.llm</code>, and <code>ctx.web</code> are not built into Cordis. Packages register them. Registration happens in the <code>Service</code> base-class constructor (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/vendor/cordis/src/service.ts#L42-L57"><code>vendor/cordis/src/service.ts:42,57</code></a>):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="title function_">constructor</span>(<span class="hljs-params"><span class="hljs-keyword">protected</span> <span class="hljs-attr">ctx</span>: <span class="title class_">Context</span>, <span class="hljs-attr">name</span>: <span class="hljs-built_in">string</span></span>) {</span><br><span class="line">  <span class="hljs-comment">// ...</span></span><br><span class="line">  self.<span class="hljs-property">ctx</span>.<span class="hljs-property">reflect</span>.<span class="title function_">provide</span>(name, self, <span class="variable language_">this</span>[symbols.<span class="hljs-property">check</span>])</span><br><span class="line">  <span class="hljs-keyword">return</span> self</span><br><span class="line">}</span><br></pre></td></tr></tbody></table></figure><p>A subclass calls <code>super(ctx, 'shell')</code> and registers itself as <code>ctx.shell</code>. Shell as an example (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/shell/shell/src/index.ts#L40-L65"><code>packages/shell/shell/src/index.ts:40,65</code></a>):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">declare</span> <span class="variable language_">module</span> <span class="hljs-string">'@deepseek-ai/cordis'</span> {</span><br><span class="line">  <span class="hljs-keyword">interface</span> <span class="title class_">Context</span> {</span><br><span class="line">    <span class="hljs-attr">shell</span>: <span class="title class_">ShellExecutor</span></span><br><span class="line">  }</span><br><span class="line">}</span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">export</span> <span class="hljs-keyword">abstract</span> <span class="hljs-keyword">class</span> <span class="title class_">ShellExecutor</span> <span class="hljs-keyword">extends</span> <span class="title class_ inherited__">Service</span> {</span><br><span class="line">  <span class="title function_">constructor</span>(<span class="hljs-params"><span class="hljs-attr">ctx</span>: <span class="title class_">Context</span></span>) {</span><br><span class="line">    <span class="variable language_">super</span>(ctx, <span class="hljs-string">'shell'</span>)</span><br><span class="line">  }</span><br><span class="line"></span><br><span class="line">  <span class="hljs-keyword">abstract</span> <span class="title function_">resolve</span>(<span class="hljs-attr">request</span>: <span class="title class_">ShellExecRequest</span>): <span class="title class_">ShellExecSpec</span></span><br><span class="line">  <span class="hljs-keyword">abstract</span> <span class="title function_">run</span>(<span class="hljs-attr">spec</span>: <span class="title class_">ShellExecSpec</span>): <span class="title class_">Promise</span>&lt;<span class="title class_">ShellRunResult</span>&gt;</span><br><span class="line">  <span class="hljs-keyword">abstract</span> <span class="title function_">start</span>(<span class="hljs-attr">spec</span>: <span class="title class_">ShellExecSpec</span>): <span class="title class_">ShellProcess</span></span><br><span class="line">}</span><br></pre></td></tr></tbody></table></figure><p>Two mechanisms sit in that snippet:</p><ul><li><strong><code>declare module '@deepseek-ai/cordis'</code></strong> (TypeScript module augmentation): add members to Cordis’s <code>Context</code> interface so every <code>ctx.shell</code> in the repo is typed. This is not a Cordis feature, but the Cordis service model depends on it for type checking. Every DSH service and event type is declared this way.</li><li><strong>The abstract class is the contract</strong>: <code>ShellExecutor</code> is abstract. Implementation packages such as <code>bash-local</code> and <code>pwsh</code> subclass it, load as plugins, and occupy the name <code>ctx.shell</code>. Occupying the name is exclusive. Mount a second implementation and you get a duplicate-service error. Whichever row config selects is the implementation at runtime.</li></ul><p><code>ShellExecutor</code> is only the contract. The code that actually loads as a plugin lives in an implementation package, for example <code>bash-local</code> (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/shell/bash-local/src/index.ts#L95-L123"><code>packages/shell/bash-local/src/index.ts:95-112,122-123</code></a>):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-comment">/**</span></span><br><span class="line"><span class="hljs-comment"> * Local bash executor over `ctx.subprocess`. Bounded output, spill files, and</span></span><br><span class="line"><span class="hljs-comment"> * process-group SIGTERM→SIGKILL escalation are the subprocess service's</span></span><br><span class="line"><span class="hljs-comment"> * mechanics; this executor supplies their configured budgets per spawn, so a</span></span><br><span class="line"><span class="hljs-comment"> * still-running background process stays managed (killed and joined at</span></span><br><span class="line"><span class="hljs-comment"> * composition teardown) even across an executor reload.</span></span><br><span class="line"><span class="hljs-comment"> */</span></span><br><span class="line"><span class="hljs-keyword">export</span> <span class="hljs-keyword">class</span> <span class="title class_">LocalBashExecutor</span> <span class="hljs-keyword">extends</span> <span class="title class_ inherited__">ShellExecutor</span> {</span><br><span class="line">  <span class="hljs-keyword">static</span> inject = [<span class="hljs-string">'subprocess'</span>]</span><br><span class="line"></span><br><span class="line">  <span class="hljs-keyword">static</span> <span class="title class_">Config</span>: z&lt;<span class="title class_">Config</span>&gt; = z.<span class="title function_">object</span>({</span><br><span class="line">    <span class="hljs-attr">cwd</span>: z.<span class="title function_">string</span>(),</span><br><span class="line">    <span class="hljs-attr">timeoutMs</span>: z.<span class="title function_">number</span>().<span class="title function_">default</span>(<span class="hljs-number">120_000</span>),</span><br><span class="line">    <span class="hljs-attr">maxTimeoutMs</span>: z.<span class="title function_">number</span>().<span class="title function_">default</span>(<span class="hljs-number">600_000</span>),</span><br><span class="line">    <span class="hljs-attr">maxOutputBytes</span>: z.<span class="title function_">number</span>().<span class="title function_">default</span>(<span class="hljs-number">64_000</span>),</span><br><span class="line">    <span class="hljs-comment">// ...</span></span><br><span class="line">  })</span><br><span class="line">  <span class="hljs-comment">// ...</span></span><br><span class="line">  <span class="title function_">constructor</span>(<span class="hljs-params"><span class="hljs-attr">ctx</span>: <span class="title class_">Context</span>, <span class="hljs-attr">config</span>: <span class="title class_">Config</span></span>) {</span><br><span class="line">    <span class="variable language_">super</span>(ctx)</span><br></pre></td></tr></tbody></table></figure><p>The plugin’s whole obligation is those few lines: inherit the contract (the constructor chain ends at <code>super(ctx, 'shell')</code> and occupies the name), declare its own dependencies (it still needs the lower-level <code>subprocess</code> service), and accept config.</p><p>There is no <code>apply</code>. When a class plugin starts, Cordis runs <code>new LocalBashExecutor(ctx, config)</code>. The constructor is the startup logic. <code>config</code> comes from the mount: the YAML entry’s <code>config:</code> field, or the <code>config</code> argument to <code>ctx.plugin(X, config)</code>. The <code>static Config</code> above validates and fills defaults (<code>timeoutMs</code> defaults to 120 seconds in that schema).</p><p>How <code>resolve</code> / <code>run</code> / <code>start</code> are implemented is none of Cordis’s business. Cordis only tracks which plugin instance currently owns the name <code>shell</code> (empty, occupied by <code>bash-sandbox</code>, or swapped to <code>pwsh-sandbox</code>) and when each plugin’s declared dependencies are complete. The doc comment at the top of the quote is worth a pause: a still-running background process is killed and joined at composition teardown, “even across an executor reload.” The implementation author wrote the code under the assumption “I may be reloaded at any time.”</p><h2 id="4-inject-Declare-Dependencies-Infer-Load-Order"><a href="#4-inject-Declare-Dependencies-Infer-Load-Order" class="headerlink" title="4. inject: Declare Dependencies, Infer Load Order"></a>4. inject: Declare Dependencies, Infer Load Order</h2><p>The second plugin mechanism is <code>inject</code>: declare “I need these services,” and Cordis waits until they exist before starting the plugin. A complete function plugin (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/web/web-search-exa/src/index.ts#L32-L60"><code>packages/web/web-search-exa/src/index.ts:32,35,60</code></a>):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">export</span> <span class="hljs-keyword">const</span> name = <span class="hljs-string">'web-search-exa'</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-comment">/** The web seam this provider registers into. */</span></span><br><span class="line"><span class="hljs-keyword">export</span> <span class="hljs-keyword">const</span> inject = [<span class="hljs-string">'web'</span>]</span><br><span class="line"></span><br><span class="line"><span class="hljs-comment">/** Register the Exa search provider with `ctx.web`. */</span></span><br><span class="line"><span class="hljs-keyword">export</span> <span class="hljs-keyword">function</span> <span class="title function_">apply</span>(<span class="hljs-params"><span class="hljs-attr">ctx</span>: <span class="title class_">Context</span>, <span class="hljs-attr">config</span>: <span class="title class_">Config</span></span>): <span class="hljs-built_in">void</span> {</span><br><span class="line">  ctx.<span class="hljs-property">web</span>.<span class="title function_">registerSearchProvider</span>(<span class="hljs-keyword">new</span> <span class="title class_">ExaSearchProvider</span>({</span><br><span class="line">    <span class="hljs-attr">apiKey</span>: config.<span class="hljs-property">apiKey</span> ?? <span class="title function_">launchEnvironmentOf</span>(ctx).<span class="title function_">get</span>(<span class="hljs-string">'EXA_API_KEY'</span>)?.<span class="hljs-property">value</span> ?? <span class="hljs-string">''</span>,</span><br><span class="line">    <span class="hljs-comment">// ...</span></span><br><span class="line">  }))</span><br><span class="line">}</span><br></pre></td></tr></tbody></table></figure><p><code>inject = ['web']</code> means: keep this plugin waiting until some plugin provides the <code>web</code> service, then run <code>apply</code>. The class-plugin equivalent is a static property (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/core/agent-loop/src/index.ts#L296-L297"><code>packages/core/agent-loop/src/index.ts:296-297</code></a>):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-comment">/** Concrete agent factory and driver service. */</span></span><br><span class="line"><span class="hljs-keyword">export</span> <span class="hljs-keyword">class</span> <span class="title class_">AgentLoop</span> <span class="hljs-keyword">extends</span> <span class="title class_ inherited__">Service</span> <span class="hljs-keyword">implements</span> <span class="title class_">AgentFactory</span> {</span><br><span class="line">  <span class="hljs-keyword">static</span> inject = [<span class="hljs-string">'agents'</span>, <span class="hljs-string">'sessions'</span>, <span class="hljs-string">'llm'</span>, <span class="hljs-string">'tools'</span>, <span class="hljs-string">'systemPrompt'</span>]</span><br></pre></td></tr></tbody></table></figure><p>The direct payoff of “declare dependencies, start only when they exist”: <strong>you do not care about source order when composing plugins</strong>. DSH’s fullest example is agent-spine, a bundle plugin that mounts about twenty child plugins in one go (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/examples/agent-spine-demo/src/index.ts#L212-L261"><code>packages/examples/agent-spine-demo/src/index.ts:212-261</code></a>):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">export</span> <span class="hljs-keyword">function</span> <span class="title function_">apply</span>(<span class="hljs-params"><span class="hljs-attr">ctx</span>: <span class="title class_">Context</span>, <span class="hljs-attr">config</span>: <span class="title class_">Config</span></span>): <span class="hljs-built_in">void</span> {</span><br><span class="line">  <span class="hljs-comment">// ...</span></span><br><span class="line">  ctx.<span class="title function_">plugin</span>(<span class="title class_">Timer</span>)</span><br><span class="line">  ctx.<span class="title function_">plugin</span>(<span class="title class_">LlmRuntime</span>)</span><br><span class="line">  ctx.<span class="title function_">plugin</span>(<span class="title class_">SessionStore</span>)</span><br><span class="line">  ctx.<span class="title function_">plugin</span>(<span class="title class_">SystemPrompt</span>, { <span class="hljs-comment">/* ... */</span> })</span><br><span class="line">  ctx.<span class="title function_">plugin</span>(<span class="title class_">ToolRuntime</span>, config.<span class="hljs-property">tools</span> ?? {})</span><br><span class="line">  <span class="hljs-comment">// ...</span></span><br><span class="line">  ctx.<span class="title function_">plugin</span>(<span class="title class_">AgentLoop</span>, { <span class="hljs-attr">agents</span>: config.<span class="hljs-property">agents</span> ?? [], <span class="hljs-comment">/* ... */</span> })</span><br><span class="line">}</span><br></pre></td></tr></tbody></table></figure><p>The file-header comment states the semantics (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/examples/agent-spine-demo/src/index.ts#L206-L207">lines 206-207</a>): “Load order is irrelevant (cordis pends each fiber on its <code>inject</code> until the services it needs exist)”. The last line, <code>AgentLoop</code>, is the class with <code>static inject = ['agents', 'sessions', 'llm', 'tools', 'systemPrompt']</code>. The <code>llm</code>, <code>tools</code>, and <code>systemPrompt</code> it declares are provided by earlier plugins in the list (<code>LlmRuntime</code>, <code>ToolRuntime</code>, <code>SystemPrompt</code>, …). Move it to the first line and it still waits until those dependencies exist. It sits last only for readability.</p><h2 id="5-Registration-Is-an-Effect-Where-Unload-Comes-From"><a href="#5-Registration-Is-an-Effect-Where-Unload-Comes-From" class="headerlink" title="5. Registration Is an Effect: Where Unload Comes From"></a>5. Registration Is an Effect: Where Unload Comes From</h2><h3 id="Inside-one-registration-where-ctx-effect-hides"><a href="#Inside-one-registration-where-ctx-effect-hides" class="headerlink" title="Inside one registration: where ctx.effect hides"></a>Inside one registration: where <code>ctx.effect</code> hides</h3><p>The <code>apply</code> of that provider plugin in section 4 does one real thing:</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">ctx.<span class="hljs-property">web</span>.<span class="title function_">registerSearchProvider</span>(<span class="hljs-keyword">new</span> <span class="title class_">ExaSearchProvider</span>({ <span class="hljs-comment">/* ... */</span> }))</span><br></pre></td></tr></tbody></table></figure><p>That call enters <code>WebRuntime.registerSearchProvider</code>, which forwards to <code>registerProvider</code> in the same file. <code>ctx.effect</code> is hidden there (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/web/web/src/index.ts#L98-L125"><code>packages/web/web/src/index.ts:98-105,118-125</code></a>):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-comment">/**</span></span><br><span class="line"><span class="hljs-comment"> * ...</span></span><br><span class="line"><span class="hljs-comment"> * if its id is already registered for search. Returns a disposer; disposed</span></span><br><span class="line"><span class="hljs-comment"> * with the calling fiber.</span></span><br><span class="line"><span class="hljs-comment"> */</span></span><br><span class="line"><span class="title function_">registerSearchProvider</span>(<span class="hljs-attr">provider</span>: <span class="title class_">WebSearchProvider</span>): <span class="hljs-function">() =&gt;</span> <span class="hljs-built_in">void</span> {</span><br><span class="line">  <span class="hljs-keyword">return</span> <span class="variable language_">this</span>.<span class="title function_">registerProvider</span>(<span class="variable language_">this</span>.<span class="hljs-property">searchProviders</span>, provider)</span><br><span class="line">}</span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">private</span> registerProvider&lt;P <span class="hljs-keyword">extends</span> { <span class="hljs-keyword">readonly</span> <span class="hljs-attr">id</span>: <span class="hljs-built_in">string</span> }&gt;(<span class="hljs-attr">store</span>: <span class="title class_">Map</span>&lt;<span class="hljs-built_in">string</span>, P&gt;, <span class="hljs-attr">provider</span>: P): <span class="hljs-function">() =&gt;</span> <span class="hljs-built_in">void</span> {</span><br><span class="line">  <span class="hljs-keyword">if</span> (store.<span class="title function_">has</span>(provider.<span class="hljs-property">id</span>)) {</span><br><span class="line">    <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="title class_">WebError</span>(<span class="hljs-string">`a web provider with id "<span class="hljs-subst">${provider.id}</span>" is already registered`</span>, <span class="hljs-string">'WEB_DUPLICATE_PROVIDER'</span>)</span><br><span class="line">  }</span><br><span class="line">  <span class="hljs-keyword">const</span> dispose = <span class="variable language_">this</span>.<span class="hljs-property">ctx</span>.<span class="title function_">effect</span>(<span class="hljs-keyword">function</span>* () {</span><br><span class="line">    store.<span class="title function_">set</span>(provider.<span class="hljs-property">id</span>, provider)</span><br><span class="line">    <span class="title function_">yield</span> () =&gt; store.<span class="title function_">delete</span>(provider.<span class="hljs-property">id</span>)</span><br><span class="line">  }, <span class="hljs-string">'web.registerProvider()'</span>)</span><br><span class="line">  <span class="hljs-comment">// ...</span></span><br><span class="line">}</span><br></pre></td></tr></tbody></table></figure><p><code>ctx.effect</code> takes a “do” callback. The callback returns (or yields) an “undo” function. The generator body <code>store.set(...)</code> adds the provider to the registry. The yielded <code>store.delete(...)</code> is the undo. Two more details in the quote are worth naming. The second argument <code>'web.registerProvider()'</code> is a diagnostic label for this effect. It shows up in <code>getEffects()</code> output (for example when you ask which effects an instance holds, or which undo failed). The default is <code>'anonymous'</code> and it does not change behavior. The <code>dispose</code> returned by <code>ctx.effect</code> is wrapped and returned to the caller. Automatic execution on plugin unload is the backstop. The caller can also use that handle to undo this one registration early. web-search-exa does not take the handle. It relies on the automatic backstop.</p><h3 id="Generators-ctx-effect-drives-them-immediately"><a href="#Generators-ctx-effect-drives-them-immediately" class="headerlink" title="Generators: ctx.effect drives them immediately"></a>Generators: <code>ctx.effect</code> drives them immediately</h3><p>After <code>ctx.effect</code> receives the callback, it drives it immediately (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/vendor/cordis/src/fiber.ts#L366-L382"><code>vendor/cordis/src/fiber.ts:366,375-382</code></a>, inside <code>_execute</code>, other return-shape branches omitted):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">const</span> <span class="hljs-attr">effect</span>: <span class="title class_">Effect</span> = runner.<span class="hljs-property">execute</span>.<span class="title function_">call</span>(<span class="variable language_">this</span>)   <span class="hljs-comment">// call the generator function, get an iterator</span></span><br><span class="line"><span class="hljs-comment">// ... (omitted: branches where the callback returns a function / Promise / async iterator)</span></span><br><span class="line">} <span class="hljs-keyword">else</span> <span class="hljs-keyword">if</span> (<span class="title class_">Symbol</span>.<span class="hljs-property">iterator</span> <span class="hljs-keyword">in</span> effect) {</span><br><span class="line">  <span class="hljs-keyword">const</span> iter = effect[<span class="title class_">Symbol</span>.<span class="hljs-property">iterator</span>]()</span><br><span class="line">  <span class="hljs-keyword">while</span> (<span class="hljs-literal">true</span>) {</span><br><span class="line">    <span class="hljs-keyword">const</span> result = iter.<span class="title function_">next</span>()       <span class="hljs-comment">// drive it to the end on the spot</span></span><br><span class="line">    <span class="title function_">safeCollect</span>(result.<span class="hljs-property">value</span>)        <span class="hljs-comment">// collect each yielded undo immediately</span></span><br><span class="line">    <span class="hljs-keyword">if</span> (result.<span class="hljs-property">done</span>) <span class="hljs-keyword">return</span></span><br><span class="line">  }</span><br><span class="line">}</span><br></pre></td></tr></tbody></table></figure><p>So <code>store.set</code> runs at the moment <code>ctx.effect</code> is called, and the undo function is collected at the same time. The returned <code>dispose</code> is a Cordis wrapper. Calling it runs every collected undo, and only once.</p><h3 id="Undo-whoever-registers-undoes"><a href="#Undo-whoever-registers-undoes" class="headerlink" title="Undo: whoever registers, undoes"></a>Undo: whoever registers, undoes</h3><p>The key is who <code>this.ctx</code> points at. Look at that <code>apply</code> from section 4 again. This time watch the parameter and which object the property access happens on (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/web/web-search-exa/src/index.ts#L60-L61"><code>packages/web/web-search-exa/src/index.ts:60-61</code></a>, provider constructor args omitted):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">export</span> <span class="hljs-keyword">function</span> <span class="title function_">apply</span>(<span class="hljs-params"><span class="hljs-attr">ctx</span>: <span class="title class_">Context</span>, <span class="hljs-attr">config</span>: <span class="title class_">Config</span></span>): <span class="hljs-built_in">void</span> {</span><br><span class="line">  ctx.<span class="hljs-property">web</span>.<span class="title function_">registerSearchProvider</span>(<span class="hljs-keyword">new</span> <span class="title class_">ExaSearchProvider</span>({ <span class="hljs-comment">/* ... */</span> }))</span><br><span class="line">}</span><br></pre></td></tr></tbody></table></figure><p>The <code>ctx</code> that <code>apply</code> receives is web-search-exa’s own plugin ctx (the child ctx from section 2). The <code>ctx.web</code> access happens on that ctx. The <code>WebRuntime</code> you get back is not a bare object. Cordis wraps it and, at wrap time, remembers “which ctx is reading.” Methods called through that wrapper trace <code>this.ctx</code> back to it. So the undo function in <code>registerProvider</code> is registered on web-search-exa’s own plugin instance, not on the <code>WebRuntime</code> instance.</p><p>Contrast that with <code>WebRuntime</code> calling <code>this.registerProvider(...)</code> internally (for example to register a built-in provider during its own init). Then <code>this.ctx</code> is its own ctx, and undo belongs to its instance. Removing that entry would mean touching <code>WebRuntime</code> itself.</p><p>On the real path, undo belongs to the registrar: the entry lives in <code>WebRuntime</code>‘s table, but the function that removes it is kept by the web-search-exa instance. Each side owns its own concern. <code>WebRuntime</code> only holds the table. It does not need to know who put an entry in, and it does not clean up for anyone else. When web-search-exa unloads, the undo it registered (<code>store.delete</code>) runs automatically and the provider entry disappears from the registry. The registry holder’s lifecycle and the registrar’s lifecycle are not coupled.</p><p>The registrar never writes cleanup code. Unload itself is triggered by an orchestration action: delete that entry from <code>cordis.yml</code>, set <code>disabled: true</code>, or replace it with a patch. Loader disposes the matching plugin instance and runs every undo it registered.</p><p>“Registered on the instance” also has a concrete meaning. Each plugin instance has a disposal list. <code>ctx.effect</code> pushes the undo function onto it (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/vendor/cordis/src/fiber.ts#L203"><code>vendor/cordis/src/fiber.ts:203</code></a>, <a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/vendor/cordis/src/fiber.ts#L520"><code>520</code></a>, <code>Fiber</code>):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">public</span> <span class="hljs-keyword">readonly</span> _disposables = <span class="hljs-keyword">new</span> <span class="title class_">DisposableList</span>&lt;<span class="title class_">Disposable</span>&gt;()   <span class="hljs-comment">// each instance's disposal list</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-comment">// inside Fiber.effect:</span></span><br><span class="line">removeWrapper = <span class="variable language_">this</span>.<span class="hljs-property">_disposables</span>.<span class="title function_">push</span>(wrapper)                    <span class="hljs-comment">// "register" = push onto the list</span></span><br></pre></td></tr></tbody></table></figure><p>On unload, clear the list and run each item (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/vendor/cordis/src/fiber.ts#L675-L676">lines 675-676</a>, inside <code>_unload</code>):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">await</span> <span class="title class_">Promise</span>.<span class="title function_">all</span>(<span class="variable language_">this</span>.<span class="hljs-property">_disposables</span>.<span class="title function_">clear</span>().<span class="title function_">map</span>(<span class="title function_">async</span> (dispose) =&gt; {</span><br></pre></td></tr></tbody></table></figure><p>Loader and this list split “trigger” from “execute.” Each entry holds a reference to the matching instance (<code>entry.fiber</code>). When a config change hits disable / delete / replace, Loader calls <code>await fiber.dispose()</code> once (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/vendor/loader/src/config/entry.ts#L130-L135"><code>vendor/loader/src/config/entry.ts:130-135</code></a>, <code>Entry._dispose</code>). It knows nothing about what is on the list. <code>fiber.dispose()</code> starts the instance’s own unload path, and <code>_unload</code> above clears and runs the list. Loader decides when to dispose which instance. The instance decides what disposal does. The only seam is <code>fiber.dispose()</code>. That is how “config-driven unload” and “plugin authors write no cleanup” fit together.</p><h3 id="Why-a-generator-hand-over-as-you-go"><a href="#Why-a-generator-hand-over-as-you-go" class="headerlink" title="Why a generator: hand over as you go"></a>Why a generator: hand over as you go</h3><p>An ordinary function can only <code>return</code> one undo at the end. A generator can <strong>hand over as you go</strong>: finish one step, <code>yield</code> that step’s undo. The difference shows up only when something fails halfway. If a multi-step setup fails in the middle (or a dependency changes, or startup is aborted), the undos already yielded have been collected step by step, so completed steps can roll back precisely. A “return at the end” form has nothing to hand over on a mid-setup failure, so the work already done leaks. The generator can also be an async generator: steps may <code>await</code> (async setup) and undos are still collected incrementally. This example has only one setup step, so both forms are equivalent. The generator is DSH’s uniform habit.</p><p>A real multi-step example: <code>SessionStore</code> creates a session in two steps, persist then broadcast <code>session/created</code> (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/core/session/src/index.ts#L833-L839"><code>packages/core/session/src/index.ts:833-839</code></a>; the comments are in the source):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-comment">// announcing so a throwing `session/created` listener rolls the attach back</span></span><br><span class="line"><span class="hljs-comment">// (the generator effect disposes already-yielded disposers on a throw)</span></span><br><span class="line"><span class="hljs-comment">// instead of leaking the store entry and its publication hooks.</span></span><br><span class="line"><span class="variable language_">this</span>.<span class="hljs-property">ctx</span>.<span class="title function_">effect</span>(<span class="hljs-keyword">function</span>* (<span class="hljs-attr">this</span>: <span class="title class_">SessionStore</span>) {</span><br><span class="line">  <span class="hljs-keyword">yield</span> <span class="variable language_">this</span>.<span class="title function_">enter</span>(session)   <span class="hljs-comment">// step 1: persist, immediately hand over "remove it"</span></span><br><span class="line">  <span class="variable language_">this</span>.<span class="title function_">announce</span>(session)      <span class="hljs-comment">// step 2: broadcast: a listener may throw</span></span><br><span class="line">}.<span class="title function_">bind</span>(<span class="variable language_">this</span>), <span class="hljs-string">'sessions.create()'</span>)</span><br></pre></td></tr></tbody></table></figure><p>Watch the order: the undo is handed over <strong>before</strong> the broadcast. The comment states the reason. If a listener throws, the already-yielded undo rolls the persist back, instead of leaving a dirty store entry with hooks attached. That is “hand over as you go” in production form. It is not a fix after failure. The code is written in the order “the next step might explode.”</p><p>Async and composition have a real example too. <code>settings-file</code>‘s <code>[Service.init]</code> is an async generator (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/settings/settings-file/src/index.ts#L232-L269"><code>packages/settings/settings-file/src/index.ts:232-269</code></a>). Steps <code>await</code> (wait for path resolution, then start a file watcher) and <code>yield* super[Service.init]()</code> collects the base class’s undos into the same chain: the base class’s “load and publish settings” undo and the subclass’s “close the watcher” undo share one reclaim path.</p><h3 id="The-rule-every-registration-goes-through-ctx-effect"><a href="#The-rule-every-registration-goes-through-ctx-effect" class="headerlink" title="The rule: every registration goes through ctx.effect"></a>The rule: every registration goes through <code>ctx.effect</code></h3><p>Actions like <code>store.set</code> that “put an object into a table another component holds, so the rest of the system can find it” (register a provider, an event listener, a tool, a service) are what DSH calls registration. It has a hard rule: <strong>every registration goes through <code>ctx.effect()</code></strong>. At the framework layer that rule is literal. Look at the full <code>provide</code> implementation (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/vendor/cordis/src/reflect.ts#L277-L305"><code>vendor/cordis/src/reflect.ts:277-305</code></a>, property-declaration bookkeeping omitted):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br></pre></td><td class="code"><pre><span class="line"><span class="title function_">provide</span>(<span class="hljs-params"><span class="hljs-attr">name</span>: <span class="hljs-built_in">string</span>, <span class="hljs-attr">value</span>?: <span class="hljs-built_in">any</span>, <span class="hljs-attr">check</span>?: () =&gt; <span class="hljs-built_in">boolean</span></span>) {</span><br><span class="line">  <span class="hljs-keyword">return</span> <span class="variable language_">this</span>.<span class="hljs-property">ctx</span>.<span class="hljs-property">fiber</span>.<span class="title function_">effect</span>(<span class="hljs-function">() =&gt;</span> {</span><br><span class="line">    <span class="hljs-comment">// ... (omitted: bookkeeping that declares name as a service)</span></span><br><span class="line">    <span class="variable language_">this</span>.<span class="hljs-property">ctx</span>.<span class="hljs-property">root</span>[symbols.<span class="hljs-property">isolate</span>][name] ??= <span class="title class_">Symbol</span>(name)</span><br><span class="line">    <span class="hljs-keyword">const</span> key = <span class="variable language_">this</span>.<span class="hljs-property">ctx</span>[symbols.<span class="hljs-property">isolate</span>][name]</span><br><span class="line">    <span class="hljs-keyword">const</span> <span class="hljs-attr">impl</span>: <span class="title class_">Impl</span> = { name, value, <span class="hljs-attr">fiber</span>: <span class="variable language_">this</span>.<span class="hljs-property">ctx</span>.<span class="hljs-property">fiber</span>, check }</span><br><span class="line">    <span class="hljs-keyword">if</span> (<span class="variable language_">this</span>.<span class="hljs-property">store</span>[key]) {</span><br><span class="line">      <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="title class_">Error</span>(<span class="hljs-string">`service "<span class="hljs-subst">${name}</span>" has been registered at &lt;<span class="hljs-subst">${<span class="variable language_">this</span>.store[key].fiber.name}</span>&gt;`</span>)</span><br><span class="line">    }</span><br><span class="line">    <span class="variable language_">this</span>.<span class="hljs-property">store</span>[key] = impl</span><br><span class="line">    <span class="variable language_">this</span>.<span class="hljs-property">ctx</span>.<span class="hljs-property">fiber</span>.<span class="hljs-property">store</span>![name] = impl</span><br><span class="line">    <span class="hljs-keyword">if</span> (<span class="variable language_">this</span>.<span class="hljs-property">ctx</span>.<span class="hljs-property">fiber</span>.<span class="hljs-property">state</span> === <span class="title class_">FiberState</span>.<span class="hljs-property">ACTIVE</span>) {</span><br><span class="line">      <span class="variable language_">this</span>.<span class="title function_">notify</span>([name])</span><br><span class="line">    }</span><br><span class="line">    <span class="hljs-keyword">return</span> <span class="title function_">async</span> () =&gt; {</span><br><span class="line">      <span class="hljs-keyword">delete</span> <span class="variable language_">this</span>.<span class="hljs-property">store</span>[key]</span><br><span class="line">      <span class="hljs-keyword">const</span> fibers = <span class="variable language_">this</span>.<span class="title function_">notify</span>([name])</span><br><span class="line">      <span class="hljs-keyword">await</span> <span class="title class_">Promise</span>.<span class="title function_">allSettled</span>(fibers.<span class="title function_">map</span>(<span class="hljs-function"><span class="hljs-params">fiber</span> =&gt;</span> fiber.<span class="title function_">await</span>()))</span><br><span class="line">      <span class="hljs-comment">// ensure self access before dependencies cleanup</span></span><br><span class="line">      <span class="hljs-keyword">delete</span> <span class="variable language_">this</span>.<span class="hljs-property">ctx</span>.<span class="hljs-property">fiber</span>.<span class="hljs-property">store</span>![name]</span><br><span class="line">    }</span><br><span class="line">  }, <span class="hljs-string">`ctx.provide(<span class="hljs-subst">${<span class="hljs-built_in">JSON</span>.stringify(name)}</span>)`</span>)</span><br><span class="line">}</span><br></pre></td></tr></tbody></table></figure><p>The “do” side: write <code>{ name, value, fiber }</code> into the store. If the name is taken, throw immediately. That is the exclusive name occupancy from section 3. If this fiber is already active, <code>notify</code> wakes plugins waiting on the service. The “undo” side is worth reading line by line: drop the name first, <code>notify</code> dependents, then <strong><code>await</code> until they have all stopped</strong>, and only then clear the record on this instance. “Consumers stop first, provider withdraws second” is written here. So <code>ctx.provide('dshHomePath', ...)</code> in the section 2 boot, and <code>provide</code> in the section 3 <code>Service</code> constructor, all go through the same register-and-reclaim channel. Unload the provider plugin and the service name disappears. Plugins that declared a dependency on it stop. This rule is the foundation of two advanced DSH capabilities:</p><ul><li><strong>Config hot-reload</strong>: change a patch file, Loader unloads the old subtree and mounts a new one. The effect mechanism guarantees that services, tools, and listeners registered by the old subtree are all reclaimed. No middle state.</li><li><strong>Plugin scope isolation</strong>: when a subtree mounted by a preset (section 7) unloads, every tool, prompt segment, and event listener it registered disappears automatically. No manual reconciliation.</li></ul><p>Event listeners are not an exception. <code>ctx.on</code> (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/vendor/cordis/src/events.ts#L288-L301"><code>vendor/cordis/src/events.ts:288-301</code></a>) calls <code>register</code>, and <code>register</code> is <code>ctx.effect</code> (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/vendor/cordis/src/events.ts#L254-L259"><code>254-259</code></a>). A listener’s lifetime follows the plugin that registered it. Unload the plugin and the listener is removed. The <code>waterfall</code> extension points DSH builds on top of events (<code>llm/stream</code>, <code>agent/pre-step</code>, and so on) are DSH usage, not a new Cordis mechanism. This post does not unpack them.</p><h2 id="6-How-to-Write-a-Plugin-Cordis-Hides-the-Complexity"><a href="#6-How-to-Write-a-Plugin-Cordis-Hides-the-Complexity" class="headerlink" title="6. How to Write a Plugin: Cordis Hides the Complexity"></a>6. How to Write a Plugin: Cordis Hides the Complexity</h2><p>The first five sections took the mechanisms apart. This section asks what writing a plugin actually requires, and what a plugin’s lifecycle looks like.</p><p>Below is all the Cordis-related code a service plugin has to write. <code>SandboxBashExecutor</code> is the main class of the bash-sandbox package, the implementation that occupies <code>ctx.shell</code> in the base bundle (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/shell/bash-sandbox/src/index.ts#L44-L182"><code>packages/shell/bash-sandbox/src/index.ts:44-45,67-72,182</code></a>, sandbox business logic omitted):</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">import</span> { <span class="title class_">Context</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'@deepseek-ai/cordis'</span></span><br><span class="line"><span class="hljs-keyword">import</span> { <span class="title class_">LocalBashExecutor</span> } <span class="hljs-keyword">from</span> <span class="hljs-string">'@deepseek-ai/dsh-bash-local'</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">export</span> <span class="hljs-keyword">class</span> <span class="title class_">SandboxBashExecutor</span> <span class="hljs-keyword">extends</span> <span class="title class_ inherited__">LocalBashExecutor</span> {</span><br><span class="line">  <span class="hljs-keyword">static</span> <span class="hljs-keyword">override</span> inject = [<span class="hljs-string">'subprocess'</span>, <span class="hljs-string">'sandbox'</span>, <span class="hljs-string">'sandboxPolicy'</span>]</span><br><span class="line"></span><br><span class="line">  <span class="title function_">constructor</span>(<span class="hljs-params"><span class="hljs-attr">ctx</span>: <span class="title class_">Context</span>, <span class="hljs-attr">config</span>: <span class="title class_">Config</span></span>) {</span><br><span class="line">    <span class="variable language_">super</span>(ctx, config)</span><br><span class="line">    <span class="variable language_">this</span>.<span class="hljs-property">mode</span> = ctx.<span class="hljs-property">sandboxPolicy</span>.<span class="hljs-property">defaultMode</span>   <span class="hljs-comment">// a service declared in inject, used directly</span></span><br><span class="line">  }</span><br><span class="line"></span><br><span class="line">  <span class="hljs-keyword">override</span> <span class="title function_">resolve</span>(<span class="hljs-attr">request</span>: <span class="title class_">ShellExecRequest</span>): <span class="title class_">ShellExecSpec</span> { <span class="hljs-comment">/* ... */</span> }</span><br><span class="line">  <span class="hljs-keyword">override</span> <span class="hljs-keyword">async</span> <span class="title function_">run</span>(<span class="hljs-attr">spec</span>: <span class="title class_">ShellExecSpec</span>): <span class="title class_">Promise</span>&lt;<span class="title class_">ShellRunResult</span>&gt; { <span class="hljs-comment">/* ... */</span> }</span><br><span class="line">  <span class="hljs-keyword">override</span> <span class="title function_">start</span>(<span class="hljs-attr">spec</span>: <span class="title class_">ShellExecSpec</span>): <span class="title class_">ShellProcess</span> { <span class="hljs-comment">/* ... */</span> }</span><br><span class="line">  <span class="hljs-comment">// ... (sandbox business logic; Cordis does not care)</span></span><br><span class="line">}</span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="title class_">SandboxBashExecutor</span></span><br></pre></td></tr></tbody></table></figure><p>Count what Cordis requires: <strong>inherit the contract</strong> (<code>extends LocalBashExecutor</code>, the chain reaches <code>ShellExecutor</code>), <strong>declare dependencies</strong> (<code>static inject</code>, two more services than the parent: <code>sandbox</code> and <code>sandboxPolicy</code>), and <strong>take <code>(ctx, config)</code> in the constructor</strong>, where <code>ctx.sandboxPolicy</code> is used directly because inject guarantees it is there. That is all. No register call, no unload code, no lifecycle hooks. <code>resolve</code> / <code>run</code> / <code>start</code> are pure domain logic. The trailing <code>export default</code> lets Loader find the class.</p><p>One question remains: after this class is mounted, what does the runtime do with it? That is the timeline below.</p><p><strong>Step 0: the contract comes first.</strong> <code>@deepseek-ai/dsh-shell</code> defines the abstract class <code>ShellExecutor</code> (section 3): it declares the type of <code>ctx.shell</code> and three abstract methods. It provides no implementation.</p><p><strong>Step 1: mount.</strong> The orchestration config has one entry (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/bundle/base/cordis.patch.yml#L178-L182"><code>packages/bundle/base/cordis.patch.yml:178-182</code></a>):</p><figure class="highlight yaml hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-bullet">-</span> <span class="hljs-attr">id:</span> <span class="hljs-string">bash-sandbox</span></span><br><span class="line">  <span class="hljs-attr">name:</span> <span class="hljs-string">'@deepseek-ai/dsh-bash-sandbox'</span></span><br><span class="line">  <span class="hljs-attr">disabled:</span> <span class="hljs-type">!!js</span> <span class="hljs-string">process.platform</span> <span class="hljs-string">===</span> <span class="hljs-string">'win32'</span></span><br><span class="line">  <span class="hljs-attr">config:</span></span><br><span class="line">    <span class="hljs-attr">timeoutMs:</span> <span class="hljs-number">60000</span></span><br></pre></td></tr></tbody></table></figure><p>Loader reads it: <code>import</code> the package, create the plugin instance (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/vendor/loader/src/config/entry.ts#L277-L285"><code>vendor/loader/src/config/entry.ts:277-285</code></a>, <code>Entry._init</code>: first <code>this.parent.tree.import(this.options.name, ...)</code>, then <code>_start(plugin)</code> to build the instance). Mount is config-driven. At boot, Loader mounts when it expands to this row. Later config changes (hot-reload, patch, preset) also trigger it. The plugin never mounts itself. Notice the <code>disabled</code> expression: on Windows this row is not mounted at all. Its twin <code>pwsh-sandbox</code> (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/bundle/base/cordis.patch.yml#L184-L186">lines 184-186</a>, opposite condition) takes its place.</p><p><strong>Step 2: wait.</strong> The implementation class declares <code>static inject = ['subprocess', 'sandbox', 'sandboxPolicy']</code> (the second line of the skeleton above). Until all three services are in place, the instance stays waiting. The constructor does not run.</p><p><strong>Step 3: start.</strong> The three dependencies are ready. Cordis runs <code>new</code> (the class is the startup callback, sections 2 and 3). <code>static Config</code> validates config first: <code>timeoutMs: 60000</code> goes through the schema here. The constructor chain reaches <code>super(ctx, 'shell')</code>, <code>provide</code> occupies the name (the implementation at the end of section 5), the instance activates, and <code>notify</code> wakes every plugin that declared it needs <code>shell</code>.</p><p><strong>Step 4: service.</strong> A consumer (for example the tool-bash plugin) calls it through <code>ctx.shell.run(...)</code>. Each call goes through the wrapper layer. <code>this.ctx</code> inside the method belongs to the caller. Registrations the consumer makes through it hang on the consumer’s own instance (section 5).</p><p><strong>Step 5: unload.</strong> Config disables or deletes the row, or hot-reload rebuilds it. Loader calls <code>fiber.dispose()</code>. The disposal list runs LIFO. Still-running background processes are reclaimed (the “killed and joined” promise in the section 3 doc comment). The <code>provide</code> undo drops the name <code>shell</code>, notifies dependents, and waits for them to stop first.</p><p><strong>Step 6: replace (if it happens).</strong> Change the entry’s <code>name</code> to another implementation package. The old instance takes step 5 and the name is vacated. The new instance takes steps 2-3 and occupies the name. Plugins that declared they need <code>shell</code> are reloaded onto the new implementation (the “continuous re-evaluation” in section 2).</p><pre class="mermaid">flowchart TB    S0["0. Contract first<br>ShellExecutor defines ctx.shell"] --&gt; S1["1. Mount<br>Loader reads the YAML entry"]    S1 --&gt; S2["2. Wait<br>inject services are not all ready"]    S2 --&gt; S3["3. Start<br>new + provide occupies the name"]    S3 --&gt; S4["4. Serve<br>consumers call ctx.shell.run"]    S4 --&gt; S5["5. Unload<br>fiber.dispose, LIFO undo"]    S5 --&gt; S6["6. Replace<br>new provider, dependents reload"]    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff    classDef tealClass fill:#16A085,stroke:#333,stroke-width:2px,color:#fff    classDef redClass fill:#E74C3C,stroke:#333,stroke-width:2px,color:#fff    class S0 blueClass    class S1 orangeClass    class S2 purpleClass    class S3 greenClass    class S4 tealClass    class S5 redClass    class S6 orangeClass</pre><p>Composition complexity is collected into the framework in one place. Cordis owns registration, dependency decisions, and reclaim. DSH owns the organizational discipline of “one capability, three packages (Definition / Provider / Consumer)” and static checks on config. What is left for a module author is domain code. So “add a module” has two tiers. Adding another implementation of an existing capability (another search backend, for example) is a few dozen lines of code plus one YAML row.</p><p>The cost that remains is opening a new capability. You must prepare the Definition package, the Provider package, and the Consumer package that faces the model or the user at the same time. That is a design decision, not just writing domain code. Those three packages already appeared in section 1: <code>dsh-shell</code> (contract), <code>dsh-bash-sandbox</code> (implementation), <code>dsh-tool-bash</code> (consumer).</p><h2 id="7-Composition-Is-Configuration-cordis-yml-Patch-Layers-and-Presets"><a href="#7-Composition-Is-Configuration-cordis-yml-Patch-Layers-and-Presets" class="headerlink" title="7. Composition Is Configuration: cordis.yml, Patch Layers, and Presets"></a>7. Composition Is Configuration: cordis.yml, Patch Layers, and Presets</h2><p>Loader describes the whole system as data. A <code>cordis.yml</code> is a list of entries. Each entry commonly has four fields: <code>id</code> (row identity), <code>name</code> (package name), <code>config</code> (passed to the plugin), and <code>disabled</code> (on/off). A real example (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/examples/headless-agent/cordis.yml#L9-L44"><code>examples/headless-agent/cordis.yml:9,23,44</code></a>):</p><figure class="highlight yaml hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-bullet">-</span> <span class="hljs-attr">id:</span> <span class="hljs-string">settings</span></span><br><span class="line">  <span class="hljs-attr">name:</span> <span class="hljs-string">'@deepseek-ai/dsh-settings-file'</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-bullet">-</span> <span class="hljs-attr">id:</span> <span class="hljs-string">llm-deepseek</span></span><br><span class="line">  <span class="hljs-attr">name:</span> <span class="hljs-string">'@deepseek-ai/dsh-llm-deepseek'</span></span><br><span class="line">  <span class="hljs-attr">config:</span></span><br><span class="line">    <span class="hljs-attr">thinking:</span> <span class="hljs-string">enabled</span></span><br><span class="line">    <span class="hljs-attr">reasoningEffort:</span> <span class="hljs-string">max</span></span><br><span class="line">    <span class="hljs-attr">models:</span></span><br><span class="line">      <span class="hljs-bullet">-</span> <span class="hljs-attr">id:</span> <span class="hljs-string">deepseek-v4-pro</span></span><br><span class="line">        <span class="hljs-attr">contextWindow:</span> <span class="hljs-number">128000</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-bullet">-</span> <span class="hljs-attr">id:</span> <span class="hljs-string">agent-spine</span></span><br><span class="line">  <span class="hljs-attr">name:</span> <span class="hljs-string">'@deepseek-ai/dsh-agent-spine-demo'</span></span><br></pre></td></tr></tbody></table></figure><p>The file’s only “programming” feature is <code>!!js</code> expressions, and they are allowed in only two fields: <code>config</code> (evaluated after that plugin’s dependencies activate, so it can read environment state) and <code>disabled</code> (evaluated on every mount decision, so a whole row can switch by platform). Every other field is a literal. Static checks (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/scripts/verify-cordis-config.ts"><code>scripts/verify-cordis-config.ts</code></a>) enforce that at commit time.</p><p>The tree that actually runs is not a single file. A patch is not a complete tree. It is a <strong>modification list addressed by <code>id</code></strong>: each item locates an existing row and replaces that row’s <code>config</code> wholesale (no deep merge). The tree that takes effect is stacked from five patch layers, in order: each bundle’s <code>cordis.patch.yml</code> (in declaration order) → the profile’s own patch → machine-level <code>$DSH_HOME/cordis.patch.yml</code> (applies to every profile, so it overrides the per-profile layer) → CLI <code>--patch</code> → the telemetry switch. When the same row is written by more than one layer, the later write wins.</p><p>A real example. The base bundle mounts the HMR plugin (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/bundle/base/cordis.patch.yml#L19-L22"><code>packages/bundle/base/cordis.patch.yml:19-22</code></a>):</p><figure class="highlight yaml hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-bullet">-</span> <span class="hljs-attr">id:</span> <span class="hljs-string">hmr</span></span><br><span class="line">  <span class="hljs-attr">name:</span> <span class="hljs-string">'@deepseek-ai/cordis-plugin-hmr'</span></span><br><span class="line">  <span class="hljs-attr">config:</span></span><br><span class="line">    <span class="hljs-attr">root:</span> [<span class="hljs-string">'.'</span>]</span><br></pre></td></tr></tbody></table></figure><p>The headless bundle writes the same <code>id: hmr</code> and only <code>disabled: true</code> (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/packages/bundle/headless/cordis.patch.yml#L12-L15"><code>packages/bundle/headless/cordis.patch.yml:12-15</code></a>; the comment is in the file):</p><figure class="highlight yaml hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-comment"># The shared module-reload HMR row stays off; the launcher's watch-only</span></span><br><span class="line"><span class="hljs-comment"># fallback still keeps the user patch layers live until the run exits.</span></span><br><span class="line"><span class="hljs-bullet">-</span> <span class="hljs-attr">id:</span> <span class="hljs-string">hmr</span></span><br><span class="line">  <span class="hljs-attr">disabled:</span> <span class="hljs-literal">true</span></span><br></pre></td></tr></tbody></table></figure><p>In the profile’s bundle order, headless comes after base. Patches apply in that order, so HMR is off at headless runtime and the base row is not edited. To see which tree actually runs: <code>dsh --profile web --dump-config</code>.</p><p>Up to here, composition is process-level. <code>cordis.yml</code> is the base (layer one). Patch layers modify it (layer two). The whole process has one tree. <strong>The third layer is the preset, and it is session-level</strong> (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/tree/47f943859b/apps/cli/config/agent-presets"><code>apps/cli/config/agent-presets/*/agent.cordis.yml</code></a>). A preset is an entry list like <code>cordis.yml</code>. The difference is scope. The <code>cordis.yml</code> tree is shared by the whole process, and its services are process-wide singletons. A preset hangs on one session. Different sessions in the same process can hang different presets: one runs “minimal,” one runs “create,” and they do not interfere.</p><p>That produces a hard constraint: service rows in a preset must go into a <code>cordis:group</code> with <code>isolate</code>. Otherwise two sessions collide on the same process-level singleton (the <code>persistent-shell</code> row in minimal mode below is this pattern). The CLI’s four modes (standard / PTC / minimal / create) <strong>are not a <code>mode</code> field and not an if/else branch. They are four shipped preset directories.</strong> Each directory has one composition YAML and one display-metadata file. The entire difference among the four modes is the difference among YAML rows:</p><table><thead><tr><th>Mode</th><th>Preset directory</th><th>What the YAML changes</th></tr></thead><tbody><tr><td>Minimal</td><td><code>minimal</code></td><td>Persona occupies the whole system prompt (<code>complete: true</code>); few tools; per-session services sit in an <code>isolate</code> group</td></tr><tr><td>Standard</td><td><code>standard</code></td><td>Full coding agent; shell tool is bash or pwsh by platform</td></tr><tr><td>PTC</td><td><code>code</code></td><td>Standard plus one <code>tool-presentation</code> row with <code>mode: code</code></td></tr><tr><td>Create</td><td><code>cordis</code></td><td>Standard plus self-modification tools and a composition skill</td></tr></tbody></table><ul><li><strong>Minimal mode</strong> (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/apps/cli/config/agent-presets/minimal/agent.cordis.yml#L8-L18"><code>minimal/agent.cordis.yml:8,18</code></a>): persona uses <code>complete: true</code> to occupy the entire system prompt and mounts only a few tools. Per-session services go into a <code>cordis:group</code> with <code>isolate</code>, so two sessions do not collide on one process-level singleton:</li></ul><figure class="highlight yaml hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-bullet">-</span> <span class="hljs-attr">id:</span> <span class="hljs-string">persona</span></span><br><span class="line">  <span class="hljs-attr">name:</span> <span class="hljs-string">'@deepseek-ai/dsh-persona'</span></span><br><span class="line">  <span class="hljs-attr">config:</span></span><br><span class="line">    <span class="hljs-attr">text:</span> <span class="hljs-string">You</span> <span class="hljs-string">are</span> <span class="hljs-string">a</span> <span class="hljs-string">helpful</span> <span class="hljs-string">software</span> <span class="hljs-string">engineer</span> <span class="hljs-string">assistant.</span></span><br><span class="line">    <span class="hljs-attr">complete:</span> <span class="hljs-literal">true</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-bullet">-</span> <span class="hljs-attr">id:</span> <span class="hljs-string">persistent-shell</span></span><br><span class="line">  <span class="hljs-attr">name:</span> <span class="hljs-string">cordis:group</span></span><br><span class="line">  <span class="hljs-attr">group:</span> <span class="hljs-literal">true</span></span><br><span class="line">  <span class="hljs-attr">isolate:</span></span><br><span class="line">    <span class="hljs-attr">terminals:</span> <span class="hljs-literal">true</span></span><br><span class="line">  <span class="hljs-attr">config:</span></span><br><span class="line">    <span class="hljs-bullet">-</span> <span class="hljs-attr">id:</span> <span class="hljs-string">pty</span></span><br><span class="line">      <span class="hljs-attr">name:</span> <span class="hljs-string">'@deepseek-ai/dsh-terminal'</span></span><br></pre></td></tr></tbody></table></figure><p><code>isolate: { terminals: true }</code> means: open a resolution space private to this group for the service name <code>terminals</code>. The pty plugin inside it will provide the <code>terminals</code> service (the PTY registry).</p><p>When the same preset is mounted once by each of two sessions, without this isolation the second mount hits the exclusive-name duplicate error at <code>provide</code> (section 5). With it, provide and read inside the group land in the private space. The outside world and the same kind of group in another session cannot see it. Each session gets its own PTY registry. (The <code>true</code> here means this entry is private. Loader also supports a string so several entries share one isolation space. DSH’s shipped config does not use that form.)</p><ul><li><strong>Standard mode</strong> (<code>standard</code>): a full coding agent. The shell tool is chosen by platform (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/apps/cli/config/agent-presets/standard/agent.cordis.yml#L44-L50"><code>standard/agent.cordis.yml:44-50</code></a>; the same rows exist in the <code>code</code> preset):</li></ul><figure class="highlight yaml hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-bullet">-</span> <span class="hljs-attr">id:</span> <span class="hljs-string">tool-bash</span></span><br><span class="line">  <span class="hljs-attr">name:</span> <span class="hljs-string">'@deepseek-ai/dsh-tool-bash'</span></span><br><span class="line">  <span class="hljs-attr">disabled:</span> <span class="hljs-type">!!js</span> <span class="hljs-string">process.platform</span> <span class="hljs-string">===</span> <span class="hljs-string">'win32'</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-bullet">-</span> <span class="hljs-attr">id:</span> <span class="hljs-string">tool-pwsh</span></span><br><span class="line">  <span class="hljs-attr">name:</span> <span class="hljs-string">'@deepseek-ai/dsh-tool-pwsh'</span></span><br><span class="line">  <span class="hljs-attr">disabled:</span> <span class="hljs-type">!!js</span> <span class="hljs-string">process.platform</span> <span class="hljs-type">!==</span> <span class="hljs-string">'win32'</span></span><br></pre></td></tr></tbody></table></figure><ul><li><strong>PTC mode</strong> (<code>code</code>): a complete copy of standard plus one row (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/apps/cli/config/agent-presets/code/agent.cordis.yml#L259-L262"><code>code/agent.cordis.yml:259-262</code></a>). Tool presentation becomes “one <code>run_code</code> tool plus a generated TypeScript SDK.” The model writes programs that compose multi-step operations:</li></ul><figure class="highlight yaml hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-bullet">-</span> <span class="hljs-attr">id:</span> <span class="hljs-string">tool-presentation</span></span><br><span class="line">  <span class="hljs-attr">name:</span> <span class="hljs-string">'@deepseek-ai/dsh-agent-tool-presentation'</span></span><br><span class="line">  <span class="hljs-attr">config:</span></span><br><span class="line">    <span class="hljs-attr">mode:</span> <span class="hljs-string">code</span></span><br></pre></td></tr></tbody></table></figure><ul><li><strong>Create mode</strong> (<code>cordis</code>): a copy of standard, plus self-modification (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/apps/cli/config/agent-presets/cordis/agent.cordis.yml#L245-L255"><code>cordis/agent.cordis.yml:245,255</code></a>): a toolset that reads, writes, mounts, and unmounts runtime plugins, plus a skill that teaches composition:</li></ul><figure class="highlight yaml hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-bullet">-</span> <span class="hljs-attr">id:</span> <span class="hljs-string">tool-cordis</span></span><br><span class="line">  <span class="hljs-attr">name:</span> <span class="hljs-string">'@deepseek-ai/dsh-tool-cordis'</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-bullet">-</span> <span class="hljs-attr">id:</span> <span class="hljs-string">skill-filesystem</span></span><br><span class="line">  <span class="hljs-attr">name:</span> <span class="hljs-string">'@deepseek-ai/dsh-skill-filesystem'</span></span><br></pre></td></tr></tbody></table></figure><p>This last preset’s file header has a trust-boundary statement (<a target="_blank" rel="noopener" href="https://github.com/deepseek-ai/deepseek-harness/blob/47f943859b/apps/cli/config/agent-presets/cordis/agent.cordis.yml#L9-L12">lines 9-12</a>): <code>cordis_mount</code> executes model-written JavaScript inside the runtime. A session running in create mode should be treated with the same caution as shell permissions.</p><pre class="mermaid">flowchart TB    subgraph Process["Process-level tree"]        direction TB        Y["cordis.yml base"] --&gt; P1["bundle cordis.patch.yml"]        P1 --&gt; P2["profile patch"]        P2 --&gt; P3["DSH_HOME/cordis.patch.yml"]        P3 --&gt; P4["CLI --patch"]        P4 --&gt; P5["telemetry switch"]    end    subgraph Session["Session-level presets"]        direction LR        M["minimal"]        S["standard"]        C["PTC / code"]        R["create / cordis"]    end    Process --&gt; Session    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff    classDef tealClass fill:#16A085,stroke:#333,stroke-width:2px,color:#fff    classDef redClass fill:#E74C3C,stroke:#333,stroke-width:2px,color:#fff    class Y blueClass    class P1 orangeClass    class P2 greenClass    class P3 purpleClass    class P4 tealClass    class P5 redClass    class M blueClass    class S orangeClass    class C greenClass    class R purpleClass</pre><p>The mechanical result: <strong>adding a fifth mode does not require changing any TypeScript</strong>. Copy a preset directory and edit YAML. That is “composition is configuration” in the literal sense.</p><h2 id="8-Mapping-Which-Cordis-Feature-Each-Usage-Eats"><a href="#8-Mapping-Which-Cordis-Feature-Each-Usage-Eats" class="headerlink" title="8. Mapping: Which Cordis Feature Each Usage Eats"></a>8. Mapping: Which Cordis Feature Each Usage Eats</h2><p>Fold the first seven sections back onto Cordis features:</p><table><thead><tr><th>Cordis feature</th><th>Usage in DSH</th></tr></thead><tbody><tr><td>Context tree + service registration (<code>provide</code>)</td><td>Everything is a plugin. <code>ctx.shell</code> / <code>ctx.llm</code> / <code>ctx.web</code> are all registered by packages (section 3)</td></tr><tr><td><code>inject</code> dependency declaration + start when available</td><td>Composing plugins does not care about order. agent-spine mounts about twenty children at once (section 4)</td></tr><tr><td>Reversible <code>ctx.effect</code> registration</td><td>Provider registration and event listeners are reclaimed when the plugin unloads. Config hot-reload leaves no middle state (section 5)</td></tr><tr><td>Loader declarative composition</td><td><code>cordis.yml</code> + stacked patches (process-level), presets (session-level). Four modes are four YAML files (section 7)</td></tr><tr><td><code>isolate</code></td><td>Per-session services in a preset go into an isolate group. Multiple sessions in one process do not interfere (section 7)</td></tr></tbody></table><p><a target="_blank" rel="noopener" href="https://github.com/cordiverse/paper/blob/main/paper.pdf">Paper section 1.2.2</a>, “Self-Evolving Agent Harnesses,” lists this as a motivating example: the harness generates and replaces its own components while it keeps serving. DSH’s create mode is a productized slice of that scenario. The model edits its own runtime plugin tree through tools such as <code>cordis_mount</code>. It can do that safely because of every row above: dependency declarations decide when to start, effects decide how to unload cleanly, and Loader turns “the system shape I want” into readable, writable data.</p><h2 id="9-Developer-View-Why-DSH-Is-a-Meta-Harness"><a href="#9-Developer-View-Why-DSH-Is-a-Meta-Harness" class="headerlink" title="9. Developer View: Why DSH Is a Meta Harness"></a>9. Developer View: Why DSH Is a Meta Harness</h2><p>The end of section 8 said create mode lets the model edit the runtime plugin tree directly. Next: why that capability holds, and what it means once it does.</p><p>A harness’s job is <strong>assembling the model’s context</strong>: system prompt, tool list, environment information. In the earlier sections, each of those fragments has a clear owner. persona owns prompt text (minimal mode in section 7 uses it to occupy the entire system prompt). systemPrompt owns prompt segments. tools owns the tool registry. Those fragments are all “effect registrations” from section 5: reversible, replaceable, hot-reloadable.</p><p>Changing harness behavior then becomes a local act. The article already has a ready example: swap the shell implementation from bash-local to bash-sandbox (the lead of section 6) and execution policy goes from unrestricted to sandboxed. The consumer tool-bash does not change a line (the mutual non-import in section 1). Hot-reload applies the change. No process restart (section 5). Want different file-access permission logic, a different search backend, or a different prompt organization? Same motion: write an implementation package, change one YAML row. You do not hunt for scattered handling points in glue code.</p><p>That workflow is isomorphic for humans and for agents. Each plugin’s inputs and outputs are verifiable: config goes in, registration comes out, behavior is measurable. So “debug how this piece of context works” can be handed to the agent itself: change a plugin, hot-swap, verify, close the loop. Create mode productizes that loop and attaches an explicit trust-boundary statement.</p><p>That is enough to say what a meta harness means. DSH does not prescribe what an agent looks like, because the agent loop itself is just one of the twenty-odd lines in the agent-spine list (section 4). What it provides is a composition mechanism. The shape of the harness is decided by configuration. What is fixed first is <strong>context structure</strong>: which system-prompt segments, which tools, how environment information enters. Code (plugins) fills that structure. You do not write the code first and let context structure emerge from it. Extension points are no longer hook callbacks scattered through the code. Everything is a plugin.</p><p>That leaves a lot of room to explore. I will keep watching what gets built on DeepSeek Harness next. (Yes, that last line is a small ad.)</p><hr><p><em>This is Part 1 of the DeepSeek Harness series.</em></p></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Source&lt;/strong&gt;: &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://blog.antinomie.org/&quot;&gt;Cordis 在做什么：从 DeepSeek Harness 看&lt;/a&gt; by Antinomie on antinomie.org. The piece is the site’s current homepage post.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;DeepSeek Harness (DSH) is an agent harness built on Cordis. The first thing that clicks is not a privileged core loop. Model adapters, tool registries, session logs, and the agent loop itself are all plugins.&lt;/p&gt;
&lt;p&gt;This is the first post in my &lt;strong&gt;DeepSeek Harness&lt;/strong&gt; series. I am starting with a close reading of how DSH actually uses Cordis: services, &lt;code&gt;inject&lt;/code&gt;, reversible &lt;code&gt;ctx.effect&lt;/code&gt; registration, Loader, and the config layers that turn composition into data.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="ai-agents" scheme="https://vanducng.dev/tags/ai-agents/"/>
    
    <category term="deepseek" scheme="https://vanducng.dev/tags/deepseek/"/>
    
  </entry>
  
  <entry>
    <title>Building Autonomous Workflows with the Claude Agent SDK</title>
    <link href="https://vanducng.dev/2026/08/09/building-autonomous-workflows-with-the-claude-agent-sdk/"/>
    <id>https://vanducng.dev/2026/08/09/building-autonomous-workflows-with-the-claude-agent-sdk/</id>
    <published>2026-08-09T02:25:00.000Z</published>
    <updated>2026-11-16T05:26:58.274Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><p>Claude Code is the interactive experience. The Claude Agent SDK is the programmable interface to the same agent loop, tools, and context management.</p><p>That distinction changes what we can build. Instead of opening a terminal and guiding one task by hand, we can place the agent inside a product, internal service, CI job, or document pipeline. Our application defines the goal and operational boundary. Claude decides which permitted actions to take, observes the results, and continues until the task is complete.</p><p>This is Part 2 of my <strong>Agentic Coding with Claude Code</strong> series. We will move from the concepts in Part 1 to the SDK primitives that make an agent work: <code>query()</code>, message streams, sessions, tools, and permissions.</p><span id="more"></span><h2 id="Claude-Agent-SDK-vs-Claude-Code"><a href="#Claude-Agent-SDK-vs-Claude-Code" class="headerlink" title="Claude Agent SDK vs Claude Code"></a>Claude Agent SDK vs Claude Code</h2><p>The SDK and Claude Code share the same underlying capabilities, but they serve different interfaces.</p><table><thead><tr><th>Interface</th><th>Best fit</th><th>Who drives the interaction?</th></tr></thead><tbody><tr><td><strong>Claude Code CLI</strong></td><td>Interactive development and one-off terminal tasks</td><td>A person works with Claude directly</td></tr><tr><td><strong>Claude Agent SDK</strong></td><td>Agents embedded in applications and automated processes</td><td>Application code starts, observes, and controls the run</td></tr></tbody></table><p>The <a target="_blank" rel="noopener" href="https://docs.claude.com/en/docs/agent-sdk/overview">Agent SDK</a> is available for TypeScript and Python. It runs the agent loop in our process, so we do not have to implement the cycle of model calls, tool execution, and tool-result feedback ourselves.</p><p>This is also where a useful distinction appears. A <strong>workflow</strong> follows orchestration that our code defines. An <strong>agent</strong> dynamically chooses its next action and tool. A production system often combines both: our application owns the reliable outer workflow, while Claude owns the decisions inside a bounded agentic step.</p><h2 id="query-Is-the-Entry-Point"><a href="#query-Is-the-Entry-Point" class="headerlink" title="query() Is the Entry Point"></a><code>query()</code> Is the Entry Point</h2><p>The main <a target="_blank" rel="noopener" href="https://docs.claude.com/en/api/agent-sdk/typescript">TypeScript SDK</a> entry point is <code>query()</code>:</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="title function_">query</span>({</span><br><span class="line">  <span class="hljs-attr">prompt</span>: <span class="hljs-built_in">string</span> | <span class="title class_">AsyncIterable</span>&lt;<span class="title class_">SDKUserMessage</span>&gt;,</span><br><span class="line">  <span class="hljs-attr">options</span>?: <span class="title class_">Options</span>,</span><br><span class="line">}): <span class="title class_">Query</span></span><br></pre></td></tr></tbody></table></figure><p>The call has two important inputs:</p><ul><li><strong><code>prompt</code></strong> describes the goal in natural language</li><li><strong><code>options</code></strong> configures the environment, including the model, working directory, tools, sessions, limits, and permission behavior</li></ul><p>Unlike a conventional request that resolves to one response, <code>query()</code> returns a <code>Query</code>, an async generator of SDK messages. The application can observe assistant messages, tool calls, tool results, lifecycle events, and the final result as the agent works.</p><p>That stream provides operational visibility. It does not expose a transcript of Claude’s hidden chain-of-thought. We should build interfaces around observable actions, concise progress, results, cost, and errors instead.</p><h2 id="A-Minimal-Read-Only-Agent"><a href="#A-Minimal-Read-Only-Agent" class="headerlink" title="A Minimal Read-Only Agent"></a>A Minimal Read-Only Agent</h2><p>Here is a complete TypeScript example that asks Claude to summarize one file:</p><figure class="highlight ts hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">import</span> { query } <span class="hljs-keyword">from</span> <span class="hljs-string">"@anthropic-ai/claude-agent-sdk"</span>;</span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">try</span> {</span><br><span class="line">  <span class="hljs-keyword">for</span> <span class="title function_">await</span> (<span class="hljs-keyword">const</span> message <span class="hljs-keyword">of</span> <span class="title function_">query</span>({</span><br><span class="line">    <span class="hljs-attr">prompt</span>: <span class="hljs-string">"Read api-guide.md and summarize its key decisions and examples."</span>,</span><br><span class="line">    <span class="hljs-attr">options</span>: {</span><br><span class="line">      <span class="hljs-attr">allowedTools</span>: [<span class="hljs-string">"Read(./api-guide.md)"</span>],</span><br><span class="line">      <span class="hljs-attr">permissionMode</span>: <span class="hljs-string">"dontAsk"</span>,</span><br><span class="line">      <span class="hljs-attr">maxTurns</span>: <span class="hljs-number">3</span>,</span><br><span class="line">      <span class="hljs-attr">maxBudgetUsd</span>: <span class="hljs-number">0.25</span>,</span><br><span class="line">    },</span><br><span class="line">  })) {</span><br><span class="line">    <span class="hljs-keyword">if</span> (message.<span class="hljs-property">type</span> !== <span class="hljs-string">"result"</span>) {</span><br><span class="line">      <span class="hljs-keyword">continue</span>;</span><br><span class="line">    }</span><br><span class="line">    <span class="hljs-keyword">if</span> (message.<span class="hljs-property">subtype</span> !== <span class="hljs-string">"success"</span>) {</span><br><span class="line">      <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="title class_">Error</span>(<span class="hljs-string">`Agent ended with <span class="hljs-subst">${message.subtype}</span>`</span>);</span><br><span class="line">    }</span><br><span class="line">    <span class="variable language_">console</span>.<span class="title function_">log</span>(message.<span class="hljs-property">result</span>);</span><br><span class="line">  }</span><br><span class="line">} <span class="hljs-keyword">catch</span> (error) {</span><br><span class="line">  <span class="variable language_">console</span>.<span class="title function_">error</span>(<span class="hljs-string">"Agent failed"</span>, error);</span><br><span class="line">  process.<span class="hljs-property">exitCode</span> = <span class="hljs-number">1</span>;</span><br><span class="line">}</span><br></pre></td></tr></tbody></table></figure><p>The prompt defines the outcome. The scoped rule auto-approves <code>Read</code> only for <code>api-guide.md</code>, and <code>dontAsk</code> denies anything that was not pre-approved instead of prompting. The turn and cost limits bound the run, while the <code>catch</code> handles SDK failures. Tune those limits for the size of the real document. Because the file path is known, the agent does not need <code>Glob</code>, <code>Grep</code>, <code>Write</code>, or <code>Bash</code>.</p><p>There is a subtle but important rule here: <strong><code>allowedTools</code> is an approval list, not a complete capability boundary.</strong> Unlisted tools can still fall through to the active permission mode. Pairing a narrow <code>allowedTools</code> list with <code>dontAsk</code>, or explicitly blocking tools with <code>disallowedTools</code>, creates the predictable boundary that headless automation needs.</p><h2 id="A-Sketchnote-of-the-SDK"><a href="#A-Sketchnote-of-the-SDK" class="headerlink" title="A Sketchnote of the SDK"></a>A Sketchnote of the SDK</h2><img src="/2026/08/09/building-autonomous-workflows-with-the-claude-agent-sdk/claude-agent-sdk-workflow-sketch-note.png" alt="Sketchnote of a prompt and options entering the Claude Agent SDK query method, its streamed messages, perceive-reason-act loop, tools, and least-privilege permission boundary" title="Claude Agent SDK workflow sketchnote" width="1600" height="900"><p>The application starts the run and consumes its message stream. Inside that boundary, the SDK keeps feeding tool results back to Claude until the goal is complete or a configured limit stops the run.</p><h2 id="How-the-SDK-Runs-the-Agentic-Loop"><a href="#How-the-SDK-Runs-the-Agentic-Loop" class="headerlink" title="How the SDK Runs the Agentic Loop"></a>How the SDK Runs the Agentic Loop</h2><p>Suppose the goal is:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">Summarize api-guide.md.</span><br></pre></td></tr></tbody></table></figure><p>The loop can unfold like this:</p><ol><li><strong>Perception</strong>: Claude receives the goal and sees that <code>Read</code> is available.</li><li><strong>Reasoning</strong>: It determines that it needs the document before it can summarize it.</li><li><strong>Action</strong>: It calls <code>Read</code> for <code>api-guide.md</code>.</li><li><strong>Perception</strong>: The file content returns as a tool result.</li><li><strong>Reasoning</strong>: Claude identifies the important decisions, examples, and structure.</li><li><strong>Action</strong>: It returns the summary as the final result.</li></ol><p>For a larger task, this cycle can repeat many times within one <code>query()</code> call. The SDK handles the model-tool-model exchange and streams each observable step back to the application.</p><h2 id="Tools-Define-What-the-Agent-Can-Do"><a href="#Tools-Define-What-the-Agent-Can-Do" class="headerlink" title="Tools Define What the Agent Can Do"></a>Tools Define What the Agent Can Do</h2><p>Tools turn the model’s decisions into grounded actions.</p><table><thead><tr><th>Category</th><th>Common tools</th><th>Capability</th></tr></thead><tbody><tr><td><strong>Observe</strong></td><td><code>Read</code>, <code>Glob</code>, <code>Grep</code></td><td>Inspect files and search the workspace</td></tr><tr><td><strong>Modify</strong></td><td><code>Edit</code>, <code>Write</code></td><td>Change or create files</td></tr><tr><td><strong>Execute</strong></td><td><code>Bash</code></td><td>Run commands and programs</td></tr><tr><td><strong>Web</strong></td><td><code>WebSearch</code>, <code>WebFetch</code></td><td>Search for and retrieve online information</td></tr><tr><td><strong>Extend</strong></td><td><code>Agent</code>, <code>Skill</code>, MCP tools</td><td>Delegate focused work or load specialized capabilities</td></tr></tbody></table><p>The current SDK calls the subagent tool <code>Agent</code>; <code>Task</code> remains accepted as a compatibility alias. Skills can be made available with the <code>skills</code> option, while MCP connects tools and data sources that the built-in set does not cover.</p><p>Tool names are not a security model by themselves. A safe deployment combines a narrow tool surface with permission rules, filesystem or process isolation, hooks where every call must be checked, and application-level validation of the final result.</p><h2 id="Permission-Modes-Set-the-Autonomy-Level"><a href="#Permission-Modes-Set-the-Autonomy-Level" class="headerlink" title="Permission Modes Set the Autonomy Level"></a>Permission Modes Set the Autonomy Level</h2><p><a target="_blank" rel="noopener" href="https://docs.claude.com/en/docs/agent-sdk/permissions">Permission modes</a> determine what happens when Claude requests a tool.</p><table><thead><tr><th>Mode</th><th>Behavior</th><th>Typical use</th></tr></thead><tbody><tr><td><strong><code>default</code></strong></td><td>Unmatched tools reach the application’s approval callback</td><td>Interactive approval flows</td></tr><tr><td><strong><code>dontAsk</code></strong></td><td>Anything not pre-approved is denied</td><td>Fixed, headless agents</td></tr><tr><td><strong><code>acceptEdits</code></strong></td><td>File edits and common filesystem operations are auto-approved</td><td>Trusted work in an isolated directory</td></tr><tr><td><strong><code>plan</code></strong></td><td>Claude explores and plans while write operations require approval</td><td>Analysis before implementation</td></tr><tr><td><strong><code>auto</code></strong></td><td>A model classifier decides permission prompts where available</td><td>Environments that support classified approvals</td></tr><tr><td><strong><code>bypassPermissions</code></strong></td><td>Most tool calls run without prompts</td><td>Fully isolated, trusted automation only</td></tr></tbody></table><p><code>bypassPermissions</code> requires an additional explicit opt-in and gives Claude broad system access. Even then, hooks and deny rules can still block calls. It should be the exception, not the default.</p><p>The practical least-privilege sequence is:</p><ol><li>Start with the exact tools the task requires.</li><li>Deny or omit capabilities that should never be used.</li><li>Choose the most restrictive permission mode that still lets the task finish.</li><li>Add sandboxing and hooks when the environment needs stronger enforcement.</li><li>Expand authority only after a real workflow proves that it needs more.</li></ol><h2 id="Sessions-Carry-Context-Across-Queries"><a href="#Sessions-Carry-Context-Across-Queries" class="headerlink" title="Sessions Carry Context Across Queries"></a>Sessions Carry Context Across Queries</h2><p>A single <code>query()</code> can take many agentic turns. <a target="_blank" rel="noopener" href="https://docs.claude.com/en/docs/agent-sdk/sessions">Sessions</a> matter when separate queries need to share context.</p><p>The TypeScript SDK supports three useful paths:</p><ul><li><strong><code>continue: true</code></strong> resumes the most recent session for the current directory and fits apps that run one conversation at a time there</li><li><strong><code>resume: sessionId</code></strong> returns to a specific session</li><li><strong><code>resume: sessionId</code> with <code>forkSession: true</code></strong> branches the conversation into a new session while preserving the original</li></ul><p>Do not use <code>continue: true</code> to identify state in a concurrent or multi-user service. Capture the session ID from each run and pass the correct ID through <code>resume</code> for that user or job.</p><p>A session contains prompts, responses, tool calls, and tool results. It does not snapshot the filesystem. If two resumed or forked sessions operate in the same directory, they still see the same real files unless we isolate or checkpoint them separately.</p><p>That difference matters in production. Conversation state helps Claude remember what it learned. Application state must still own durable business facts, authorization, idempotency, and the status of external work.</p><h2 id="From-One-Query-to-a-Real-Workflow"><a href="#From-One-Query-to-a-Real-Workflow" class="headerlink" title="From One Query to a Real Workflow"></a>From One Query to a Real Workflow</h2><p>A document-standardization process shows how the pieces combine. Imagine a directory of contracts that must be converted into a consistent internal format.</p><p>The outer workflow can:</p><ol><li>Place copies of the source documents in an isolated working directory.</li><li>Start <code>query()</code> with a precise output schema and validation rules.</li><li>Allow read tools for the inputs and write access only to a dedicated output directory.</li><li>Stream progress and tool activity into the application’s audit log.</li><li>Validate the generated documents before accepting them.</li><li>Route exceptions and final legal approval to a human reviewer.</li></ol><p>Within that workflow, the agent can decide which document to inspect next, how to map inconsistent sections, and when it needs more context. The application still owns the non-negotiable sequence, permissions, validation, and approval boundary.</p><p>This is the pattern to aim for: <strong>dynamic reasoning inside deterministic controls.</strong></p><h2 id="Apply-Your-Skills"><a href="#Apply-Your-Skills" class="headerlink" title="Apply Your Skills"></a>Apply Your Skills</h2><p>Pick a repetitive process from your work, such as compiling a weekly report, preparing release notes, or onboarding a teammate. Write down:</p><ol><li>What outcome should one <code>query()</code> own?</li><li>Which tools are strictly necessary?</li><li>Which actions must be denied, sandboxed, or approved?</li><li>What messages should the application surface to a human?</li><li>What belongs in the SDK session, and what must live in application storage?</li><li>Which validations prove that the final result is safe to use?</li></ol><p>Then implement the smallest read-only version first. Add modification or execution tools only when the workflow has a concrete need for them.</p><h2 id="Key-Terms"><a href="#Key-Terms" class="headerlink" title="Key Terms"></a>Key Terms</h2><ul><li><strong>Claude Agent SDK</strong>: The TypeScript and Python library that exposes Claude Code’s agent loop, tools, and context management to applications</li><li><strong><code>query()</code></strong>: The primary SDK function that starts an agent run and returns an asynchronous message stream</li><li><strong><code>Query</code></strong>: The async generator returned by <code>query()</code>, with streamed SDK messages and controls for the active run</li><li><strong>Agentic loop</strong>: The repeating perception, reasoning, and action cycle managed by the SDK</li><li><strong>Tool</strong>: A capability Claude can call to observe or change its environment</li><li><strong>Permission mode</strong>: The global policy that controls how unmatched tool requests are approved, denied, or escalated</li><li><strong>Least privilege</strong>: Giving an agent only the authority required for its current goal</li><li><strong>Session</strong>: Persisted conversation history containing prompts, messages, tool calls, and tool results</li><li><strong>Resume</strong>: Continue a specific prior session by its ID</li><li><strong>Fork</strong>: Create a new session from an existing history without changing the original conversation</li></ul><h2 id="Final-Thoughts"><a href="#Final-Thoughts" class="headerlink" title="Final Thoughts"></a>Final Thoughts</h2><p>The Claude Agent SDK turns the interaction model of Claude Code into a programmable building block. <code>query()</code> gives us a goal-driven agent loop, tools give it capabilities, the message stream gives us observability, sessions give it continuity, and permissions define its operating boundary.</p><p>The strongest systems do not maximize autonomy. They give Claude enough room to reason and adapt inside controls that remain understandable, testable, and owned by the application.</p><p>The next post will go deeper into context engineering: how project instructions, scoped rules, skills, and tool descriptions shape the decisions an agent makes.</p><hr><p><em>This is Part 2 of the Agentic Coding with Claude Code series.</em></p></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;p&gt;Claude Code is the interactive experience. The Claude Agent SDK is the programmable interface to the same agent loop, tools, and context management.&lt;/p&gt;
&lt;p&gt;That distinction changes what we can build. Instead of opening a terminal and guiding one task by hand, we can place the agent inside a product, internal service, CI job, or document pipeline. Our application defines the goal and operational boundary. Claude decides which permitted actions to take, observes the results, and continues until the task is complete.&lt;/p&gt;
&lt;p&gt;This is Part 2 of my &lt;strong&gt;Agentic Coding with Claude Code&lt;/strong&gt; series. We will move from the concepts in Part 1 to the SDK primitives that make an agent work: &lt;code&gt;query()&lt;/code&gt;, message streams, sessions, tools, and permissions.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="agentic-coding" scheme="https://vanducng.dev/tags/agentic-coding/"/>
    
    <category term="claude-code" scheme="https://vanducng.dev/tags/claude-code/"/>
    
    <category term="claude-agent-sdk" scheme="https://vanducng.dev/tags/claude-agent-sdk/"/>
    
    <category term="ai-agents" scheme="https://vanducng.dev/tags/ai-agents/"/>
    
  </entry>
  
  <entry>
    <title>Core Concepts of Agentic Coding with Claude Code</title>
    <link href="https://vanducng.dev/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/"/>
    <id>https://vanducng.dev/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/</id>
    <published>2026-08-09T02:00:00.000Z</published>
    <updated>2026-11-16T05:26:58.275Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><p>Most people first meet Claude Code as a chatbot in a terminal. That mental model is too small.</p><p>Ask it to explain a bug and it may answer once. Give it a concrete engineering objective and permission to work, and it can read the repository, trace the code, edit files, run tests, inspect the result, and change course when the evidence contradicts its plan. That repeated cycle is what makes the workflow agentic.</p><p>This is Part 1 of 6 in my <strong>Agentic Coding with Claude Code</strong> series. The working model I am keeping is simple: Claude Code is a bounded loop of perceive, reason, act, and feedback, not a longer chatbot reply.</p><p>Later posts will cover context, the harness / Agent SDK / stop-reason loop, MCP, evals, and guardrails. This one stays on the loop, the components, and the patterns.</p><span id="more"></span><h2 id="From-a-Prompt-to-an-Agentic-Loop"><a href="#From-a-Prompt-to-an-Agentic-Loop" class="headerlink" title="From a Prompt to an Agentic Loop"></a>From a Prompt to an Agentic Loop</h2><p>A single-turn interaction ends after one reply. Agentic coding keeps going until the definition of done has evidence.</p><pre class="mermaid">flowchart TB    Obj[Objective] --&gt; Perc[Perceive]    Perc --&gt; Reas[Reason]    Reas --&gt; Act[Act]    Act --&gt; Feed[Feedback]    Feed --&gt;|more evidence needed| Perc    Feed --&gt;|definition of done met| Done[Verified result]    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff    classDef tealClass fill:#16A085,stroke:#333,stroke-width:2px,color:#fff    classDef redClass fill:#E74C3C,stroke:#333,stroke-width:2px,color:#fff    class Obj blueClass    class Perc orangeClass    class Reas greenClass    class Act purpleClass    class Feed tealClass    class Done redClass</pre><p>The difference is not that the model produces a longer answer. The difference is that it can take multiple grounded actions, receive feedback from the environment, and adapt until it reaches a defined outcome.</p><p>Official <a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/how-claude-code-works">How Claude Code works</a> names the same cycle in product language: gather context, take action, verify results. I am keeping the four names I already use: perceive, reason, act, feedback.</p><p>Autonomy is still bounded. Claude Code operates with the context, tools, permissions, and constraints that I give it. A useful agent is not one that acts without limits. It is one that can make progress independently while keeping its work inspectable and stopping at the right boundaries.</p><h2 id="The-Perception-Reasoning-Action-Loop"><a href="#The-Perception-Reasoning-Action-Loop" class="headerlink" title="The Perception-Reasoning-Action Loop"></a>The Perception-Reasoning-Action Loop</h2><p>The engine of an agentic system is a continuous feedback loop.</p><h3 id="1-Perception-Build-a-Current-View-of-the-Work"><a href="#1-Perception-Build-a-Current-View-of-the-Work" class="headerlink" title="1. Perception: Build a Current View of the Work"></a>1. Perception: Build a Current View of the Work</h3><p>The agent gathers the information needed to understand the task and its environment. In Claude Code, perception can include:</p><ul><li>The request and definition of done</li><li>Repository instructions in <code>CLAUDE.md</code>, including any imported guidance</li><li>Source code, configuration, documentation, and git state</li><li>Test failures, logs, API responses, and runtime output</li><li>Results returned by tools used in an earlier step</li></ul><p>This is why a strong coding agent reads before it edits. A bug report describes a symptom. The repository and runtime evidence reveal the actual system.</p><h3 id="2-Reasoning-Choose-the-Next-Useful-Step"><a href="#2-Reasoning-Choose-the-Next-Useful-Step" class="headerlink" title="2. Reasoning: Choose the Next Useful Step"></a>2. Reasoning: Choose the Next Useful Step</h3><p>Claude analyzes what it has observed, forms a working model of the problem, and decides what to do next. That may mean decomposing a large objective, tracing callers, comparing implementation options, or recognizing that more evidence is needed before changing code.</p><p>For collaboration, the useful outputs are a concise plan, stated assumptions, decisions, and evidence. I do not need a transcript of hidden reasoning. I need enough visibility to understand what the agent is doing and to redirect it when necessary.</p><h3 id="3-Action-Change-or-Query-the-Environment"><a href="#3-Action-Change-or-Query-the-Environment" class="headerlink" title="3. Action: Change or Query the Environment"></a>3. Action: Change or Query the Environment</h3><p>Claude Code acts through tools. It can search and read files, apply edits, run commands, execute tests, inspect git history, call connected services, or delegate a bounded task to a specialized agent.</p><p>A tool call is not progress by itself. Its result must move the objective forward or improve the agent’s understanding of the problem.</p><h3 id="4-Feedback-Turn-Results-into-the-Next-Perception"><a href="#4-Feedback-Turn-Results-into-the-Next-Perception" class="headerlink" title="4. Feedback: Turn Results into the Next Perception"></a>4. Feedback: Turn Results into the Next Perception</h3><p>Every action produces evidence: a diff, a passing test, a compiler error, a changed API response, or a new failure. That evidence becomes the next perception.</p><p>If the test fails, the agent revises its model. If the test passes but the diff touches unrelated files, it tightens the change. If the local result is correct but the user asked for runtime proof, it continues to the authorized verification boundary.</p><p>The takeaway I kept: the loop ends when the definition of done is supported by evidence, not when the agent has merely produced code.</p><h2 id="A-Sketchnote-of-the-System"><a href="#A-Sketchnote-of-the-System" class="headerlink" title="A Sketchnote of the System"></a>A Sketchnote of the System</h2><img src="/2026/08/09/core-concepts-of-agentic-coding-with-claude-code/claude-code-agentic-system-sketch-note.png" alt="Sketchnote of the Claude Code perception, reasoning, action, and feedback loop with its goal, tools, memory, human collaborator, and common agent patterns" title="Claude Code agentic system sketchnote" width="1600" height="900"><p>The central loop is only one part of the system. Goals, tools, memory, the reasoning engine, and the human collaborator determine whether that loop is useful and safe.</p><h2 id="The-Core-Components"><a href="#The-Core-Components" class="headerlink" title="The Core Components"></a>The Core Components</h2><table><thead><tr><th>Component</th><th>In a Claude Code workflow</th><th>Question to answer</th></tr></thead><tbody><tr><td><strong>Goal</strong></td><td>The requested outcome and definition of done</td><td>What evidence will prove the work is complete?</td></tr><tr><td><strong>Tools</strong></td><td>File access, shell commands, tests, git, browsers, APIs, and MCP servers</td><td>What can the agent observe or change?</td></tr><tr><td><strong>Memory</strong></td><td>Current context, repository instructions, prior tool results, and durable project knowledge</td><td>What must remain available for the next decision?</td></tr><tr><td><strong>Reasoning engine</strong></td><td>The Claude model that interprets context and selects the next action</td><td>Is the model receiving the right evidence and constraints?</td></tr><tr><td><strong>Human collaborator</strong></td><td>The person who sets goals, supplies judgment, reviews evidence, and approves risky boundaries</td><td>When should the agent proceed, report, or stop for approval?</td></tr></tbody></table><h3 id="Goal-Define-Success-Before-Activity"><a href="#Goal-Define-Success-Before-Activity" class="headerlink" title="Goal: Define Success Before Activity"></a>Goal: Define Success Before Activity</h3><p>“Fix the login bug” is a direction. A stronger goal defines the observable result:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line">Fix the login regression at its shared root cause.</span><br><span class="line">Preserve the existing authentication contract.</span><br><span class="line">Add a regression check and pass the relevant test suite.</span><br><span class="line">Do not change unrelated files.</span><br></pre></td></tr></tbody></table></figure><p>The clearer the finish line, the less likely the agent is to optimize for visible activity instead of the actual outcome.</p><h3 id="Tools-Capabilities-with-Boundaries"><a href="#Tools-Capabilities-with-Boundaries" class="headerlink" title="Tools: Capabilities with Boundaries"></a>Tools: Capabilities with Boundaries</h3><p>Tools turn a language model into a working agent. File tools let Claude inspect and edit the repository. The terminal lets it compile and test. APIs and MCP servers connect it to external systems.</p><p>Every tool also expands the failure surface. Read access is different from write access. Editing a local file is different from merging a pull request or changing production. Give the agent the smallest authority that still allows it to complete the task, and make approval boundaries explicit.</p><h3 id="Memory-Preserve-Context-Verify-Reality"><a href="#Memory-Preserve-Context-Verify-Reality" class="headerlink" title="Memory: Preserve Context, Verify Reality"></a>Memory: Preserve Context, Verify Reality</h3><p>An agent needs memory to connect one step to the next. For coding work, memory usually exists at three levels:</p><ol><li><strong>Working context</strong>: the current request, open files, recent commands, and tool results</li><li><strong>Project context</strong>: repository rules, architecture documents, conventions, and accepted patterns</li><li><strong>Durable context</strong>: knowledge carried across sessions, such as prior decisions or recurring workflows</li></ol><p>Memory helps continuity, but it can become stale. Current source code, live runtime state, and fresh test output remain the authority.</p><h3 id="Reasoning-Engine-Claude-Is-the-Brain-Context-Shapes-the-Decision"><a href="#Reasoning-Engine-Claude-Is-the-Brain-Context-Shapes-the-Decision" class="headerlink" title="Reasoning Engine: Claude Is the Brain, Context Shapes the Decision"></a>Reasoning Engine: Claude Is the Brain, Context Shapes the Decision</h3><p>The Claude model interprets the goal and observations, then chooses the next action. Its effectiveness depends on more than model capability. Missing files, vague tool descriptions, noisy context, or an ambiguous definition of done can all lead to poor decisions.</p><p>Good agentic coding is therefore also context engineering: give the model the right instructions, relevant evidence, and clear tool contracts while keeping irrelevant material out of the working set.</p><h3 id="Human-Collaborator-Control-the-Objective-and-the-Boundaries"><a href="#Human-Collaborator-Control-the-Objective-and-the-Boundaries" class="headerlink" title="Human Collaborator: Control the Objective and the Boundaries"></a>Human Collaborator: Control the Objective and the Boundaries</h3><p>The human is part of the system, not an exception to it. I contribute product intent, architectural judgment, risk tolerance, and authority that the agent should not invent.</p><p>A practical collaboration loop looks like this:</p><ul><li>Before work: define the goal, scope, constraints, and proof required</li><li>During work: review decisions, assumptions, diffs, and evidence</li><li>At risky boundaries: approve external, destructive, or production actions</li><li>At completion: verify the final artifact or runtime outcome</li></ul><h2 id="Choosing-an-Agentic-Design-Pattern"><a href="#Choosing-an-Agentic-Design-Pattern" class="headerlink" title="Choosing an Agentic Design Pattern"></a>Choosing an Agentic Design Pattern</h2><p>More agents do not automatically produce better work. Start with the simplest structure that can complete the objective.</p><pre class="mermaid">flowchart TB    subgraph Single["Single agent"]        direction LR        S1[Perceive] --&gt; S2[Reason] --&gt; S3[Act] --&gt; S4[Verify]    end    subgraph Multi["Multi-agent / hierarchical"]        direction LR        M1[Manager] --&gt; M2[Specialist A]        M1 --&gt; M3[Specialist B]        M2 --&gt; M4[Integrate]        M3 --&gt; M4    end    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef purpleClass fill:#9B59B6,stroke:#333,stroke-width:2px,color:#fff    classDef tealClass fill:#16A085,stroke:#333,stroke-width:2px,color:#fff    class S1,S2,S3,S4 greenClass    class M1 orangeClass    class M2,M3 purpleClass    class M4 tealClass</pre><p>Single agent on the right is the default. Multi-agent on the left is the coordination I add only when the work has real, separable boundaries.</p><h3 id="Single-Agent-Pattern"><a href="#Single-Agent-Pattern" class="headerlink" title="Single-Agent Pattern"></a>Single-Agent Pattern</h3><p>One agent owns the task from perception through verification. This is the default for most focused engineering work: fixing a bug, adding a small feature, updating documentation, or investigating a failing test.</p><p>Use it when the work shares one context and the steps depend heavily on one another. It minimizes coordination overhead and keeps accountability clear.</p><h3 id="Multi-Agent-Pattern"><a href="#Multi-Agent-Pattern" class="headerlink" title="Multi-Agent Pattern"></a>Multi-Agent Pattern</h3><p>Several specialized agents handle independent parts of the objective. One might inspect the backend while another audits the frontend or reviews test coverage.</p><p>Use this pattern when tasks can run in parallel, require genuinely different expertise, and have clear ownership boundaries. Avoid it when every agent needs the same evolving context or when their edits would collide.</p><h3 id="Hierarchical-Pattern"><a href="#Hierarchical-Pattern" class="headerlink" title="Hierarchical Pattern"></a>Hierarchical Pattern</h3><p>A manager agent decomposes a large goal, delegates bounded sub-tasks, integrates the results, and verifies the whole system.</p><p>This fits migrations, cross-layer features, or broad reviews where central coordination matters. It also adds the most orchestration risk: incomplete handoffs, duplicated work, conflicting changes, and a manager that reports progress without proving integration.</p><p>The takeaway I kept: <strong>start with one agent and add coordination only when the work has real, separable boundaries.</strong></p><h3 id="From-a-Manual-Process-to-a-Multi-Agent-Workflow"><a href="#From-a-Manual-Process-to-a-Multi-Agent-Workflow" class="headerlink" title="From a Manual Process to a Multi-Agent Workflow"></a>From a Manual Process to a Multi-Agent Workflow</h3><p>Designing a complete multi-agent architecture turns theory into explicit engineering choices. The goal, agent responsibilities, tools, handoffs, failure handling, and verification path all need to be documented. A resilient design is not a collection of agent names. It is a system in which every agent has a clear job and the whole workflow still produces a verifiable result.</p><p>This lens can transform a slow manual process into an intelligent workflow. Specialization lets each agent focus on one responsibility, while parallel execution reduces time when tasks are genuinely independent. The result can be faster and easier to scale than a single-agent sequence, but only when the coordination cost is lower than the time it saves.</p><h2 id="Putting-the-Concepts-into-Practice"><a href="#Putting-the-Concepts-into-Practice" class="headerlink" title="Putting the Concepts into Practice"></a>Putting the Concepts into Practice</h2><p>Choose a real task from your backlog and describe it with this compact brief:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line">Goal:</span><br><span class="line">Definition of done:</span><br><span class="line">Relevant context:</span><br><span class="line">Allowed tools and scope:</span><br><span class="line">Required verification:</span><br><span class="line">Stop and ask before:</span><br></pre></td></tr></tbody></table></figure><p>Then map the loop:</p><ol><li>What should Claude Code inspect before changing anything?</li><li>What evidence would distinguish the root cause from the symptom?</li><li>Which tools can move the task forward?</li><li>What results should feed the next decision?</li><li>Which actions require human approval?</li><li>Can one agent own the full context, or are there truly independent sub-tasks?</li></ol><p>For example:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">Find and fix the root cause of the failing checkout flow.</span><br><span class="line">Read the repository instructions first and reproduce the failure at the closest realistic boundary.</span><br><span class="line">Trace all callers of the code you plan to change.</span><br><span class="line">Make the smallest shared fix, add one regression check, and run the relevant tests.</span><br><span class="line">Preserve unrelated changes. Stop before committing, pushing, or changing external systems.</span><br></pre></td></tr></tbody></table></figure><p>That prompt does not prescribe every implementation step. It gives the agent a goal, a method for grounding its decisions, a verification standard, and clear authority boundaries.</p><h3 id="Multi-Agent-Design-Exercise"><a href="#Multi-Agent-Design-Exercise" class="headerlink" title="Multi-Agent Design Exercise"></a>Multi-Agent Design Exercise</h3><p>Pick a repetitive, multi-step process from your work. Compiling a weekly report, onboarding a team member, triaging customer issues, or preparing a release are all useful candidates. Sketch the process before deciding how many agents it needs.</p><p>Ask:</p><ol><li>Who are the specialized agents?</li><li>What single responsibility does each agent own?</li><li>Which tasks can run in parallel without sharing changing state?</li><li>What information must pass between agents?</li><li>Who integrates the results and verifies the final outcome?</li><li>Where must a human review, approve, or redirect the workflow?</li></ol><p>This exercise builds the habit of seeing work as responsibilities, dependencies, and evidence. That is the foundation for designing sophisticated agentic systems without adding agents merely for appearance.</p><h2 id="Key-Terms"><a href="#Key-Terms" class="headerlink" title="Key Terms"></a>Key Terms</h2><ul><li><strong>Agentic coding</strong>: Using an AI system that can observe, reason, act through tools, and adapt across multiple steps to complete an engineering objective</li><li><strong>Agent architecture</strong>: The blueprint for the agents, responsibilities, tools, communication paths, and controls that solve a multi-step problem</li><li><strong>Agentic system</strong>: A goal-directed system that can work across multiple steps, use tools, observe results, and adapt its actions</li><li><strong>Agentic workflow</strong>: A predefined orchestration of model, tool, and human steps that completes a multi-step task</li><li><strong>Perception-Reasoning-Action loop</strong>: The repeating cycle in which an agent gathers evidence, decides what to do, acts, and uses the result as new evidence</li><li><strong>Goal</strong>: The objective and observable definition of success</li><li><strong>Tools</strong>: Capabilities that let the agent inspect or change its environment</li><li><strong>Memory</strong>: Context retained across steps or sessions to inform future decisions</li><li><strong>Reasoning engine</strong>: The model that interprets context and selects the next action</li><li><strong>Single-agent pattern</strong>: One agent owns the complete task loop</li><li><strong>Multi-agent pattern</strong>: Specialized agents collaborate on separate parts of a goal</li><li><strong>Hierarchical pattern</strong>: A manager agent delegates to and coordinates worker agents</li></ul><h2 id="Final-Thoughts"><a href="#Final-Thoughts" class="headerlink" title="Final Thoughts"></a>Final Thoughts</h2><p>Claude Code becomes most useful when I stop treating it as an answer generator and start designing the work around a controlled feedback loop. I give it a concrete goal, the right tools, reliable context, and explicit boundaries. Then I judge the result by the evidence it produces. Learning to identify specialized responsibilities and orchestrate them into one verified workflow is a foundational skill for building more capable AI systems.</p><p>The rest of the series keeps this loop and asks what occupies the window, what the harness decides, what MCP is allowed to add, how I score a run, and what the agent is allowed to do even when the model wants another hop.</p><p>The next post moves from this loop to context engineering: how repository instructions, scoped rules, skills, and tool descriptions shape every decision the agent makes.</p><h2 id="References"><a href="#References" class="headerlink" title="References"></a>References</h2><ul><li>AI Engineering with Claude</li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/how-claude-code-works">How Claude Code works</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/overview">Overview</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/memory">CLAUDE.md and memory</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/tools-reference">Tools reference</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/sub-agents">Subagents</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/common-workflows">Common workflows</a></li><li><a target="_blank" rel="noopener" href="https://code.claude.com/docs/en/best-practices">Best practices</a></li></ul><hr><p><em>This is Part 1 of 6 in the Agentic Coding with Claude Code series. Next: <a href="/2026/08/15/context-engineering-for-claude-code/">Part 2</a>, <a href="/2026/08/15/the-harness-models-agent-sdk-and-stop-reason-loops/">Part 3</a>, <a href="/2026/08/15/mcp-and-tool-governance/">Part 4</a>, <a href="/2026/08/15/evaluation-and-observability-for-claude-agents/">Part 5</a>, <a href="/2026/08/15/bounded-autonomy-and-guardrails-for-claude-code/">Part 6</a>.</em></p></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;p&gt;Most people first meet Claude Code as a chatbot in a terminal. That mental model is too small.&lt;/p&gt;
&lt;p&gt;Ask it to explain a bug and it may answer once. Give it a concrete engineering objective and permission to work, and it can read the repository, trace the code, edit files, run tests, inspect the result, and change course when the evidence contradicts its plan. That repeated cycle is what makes the workflow agentic.&lt;/p&gt;
&lt;p&gt;This is Part 1 of 6 in my &lt;strong&gt;Agentic Coding with Claude Code&lt;/strong&gt; series. The working model I am keeping is simple: Claude Code is a bounded loop of perceive, reason, act, and feedback, not a longer chatbot reply.&lt;/p&gt;
&lt;p&gt;Later posts will cover context, the harness / Agent SDK / stop-reason loop, MCP, evals, and guardrails. This one stays on the loop, the components, and the patterns.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="agentic-coding" scheme="https://vanducng.dev/tags/agentic-coding/"/>
    
    <category term="claude-code" scheme="https://vanducng.dev/tags/claude-code/"/>
    
    <category term="ai-agents" scheme="https://vanducng.dev/tags/ai-agents/"/>
    
  </entry>
  
  <entry>
    <title>From Theory to Gateway - Why Go Makes Sense for Production AI Agents</title>
    <link href="https://vanducng.dev/2026/02/28/From-Theory-to-Gateway-Building-a-Production-AI-Agent-System-in-Go/"/>
    <id>https://vanducng.dev/2026/02/28/From-Theory-to-Gateway-Building-a-Production-AI-Agent-System-in-Go/</id>
    <published>2026-02-28T09:00:00.000Z</published>
    <updated>2026-11-16T05:26:58.203Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><p>I learned agentic AI concepts in Python - <a href="/2025/10/30/Anatomy-of-an-AI-Agent-Building-Blocks-and-Workflows/">agent loops</a>, <a href="/2025/11/20/Extending-Agents-with-Tools-and-Structured-Outputs/">tool calling</a>, <a href="/2025/12/08/Designing-Multi-Agent-Architecture-From-Solo-to-Ensemble/">multi-agent coordination</a>, <a href="/2025/07/24/From-Prototype-to-Production-LangGraph-Systems/">production patterns</a>. I even <a href="/2026/02/20/Building-MiuBot-A-Personal-AI-Assistant-From-Nanobot-to-Production/">built my own Python assistant</a> - MiuBot - with 10 chat channels, Temporal workflows, and multi-tenant workspaces. Python works well for most of these cases. But while building MiuBot, I kept hitting the same question: what happens when you need to serve many users concurrently over WebSocket with streaming responses? That’s when I discovered <a target="_blank" rel="noopener" href="https://github.com/nextlevelbuilder/goclaw/">GoClaw</a> from the <a target="_blank" rel="noopener" href="https://github.com/nextlevelbuilder">NextLevelBuilder</a> team, and it changed how I think about the problem.</p><p><a class="github-card-link" target="_blank" rel="noopener" href="https://github.com/nextlevelbuilder/goclaw/"><img src="https://gh-card.dev/repos/nextlevelbuilder/goclaw.svg" alt="GoClaw"></a></p><style>.github-card-link::after { display: none !important; }</style><span id="more"></span><h2 id="Python-Works-Until-It-Doesn’t"><a href="#Python-Works-Until-It-Doesn’t" class="headerlink" title="Python Works - Until It Doesn’t"></a>Python Works - Until It Doesn’t</h2><p>Python’s AI ecosystem is enormous. LangChain, LangGraph, AutoGen, CrewAI, Haystack, LlamaIndex - for learning and prototyping agent patterns, nothing beats it. I used Python throughout my <a href="/2025/10/30/Anatomy-of-an-AI-Agent-Building-Blocks-and-Workflows/">agentic AI series</a> and <a href="/2025/05/01/Mastering-LangChain-and-LangGraph-A-Practitioners-Guide/">LangChain/LangGraph series</a>, and I built <a href="/2026/02/20/Building-MiuBot-A-Personal-AI-Assistant-From-Nanobot-to-Production/">MiuBot</a> as a fully working assistant with asyncio, Temporal, and 10 chat channels.</p><p>But there’s a gap between “agent that works for a few users” and “agent that serves many users concurrently over WebSocket with streaming responses.” I felt this gap while building MiuBot - Python’s asyncio handles personal-scale concurrency fine, but the architecture decisions for true multi-user scale are fundamentally different. That gap is where language choice starts to matter.</p><p>Here’s what the benchmarks show for Go vs Python gateways at scale (Bifrost Go proxy vs LiteLLM Python proxy):</p><table><thead><tr><th>Metric</th><th>Go Gateway</th><th>Python Gateway</th><th>Difference</th></tr></thead><tbody><tr><td>P99 Latency</td><td>1.68s</td><td>90.72s</td><td>54x lower</td></tr><tr><td>Throughput</td><td>424 req/s</td><td>44.84 req/s</td><td>9.5x higher</td></tr><tr><td>Memory</td><td>120MB</td><td>372MB</td><td>3x lower</td></tr><tr><td>Instances at 10K RPS (extrapolated)</td><td>~24</td><td>~223</td><td>~9x fewer</td></tr></tbody></table><p>Python’s GIL means true parallelism requires multiprocessing with its own overhead. Go’s goroutines handle thousands of concurrent WebSocket connections, streaming LLM responses, and parallel tool execution on a single binary. No virtualenv, no dependency hell, no 500MB Docker images - just a ~15MB compiled binary.</p><p>Python remains the right choice for ML training, fine-tuning, and rapid prototyping. But for a <strong>chat application gateway</strong> handling real-time agent interactions at scale, Go is a stronger fit.</p><h2 id="GoClaw-An-AI-Agent-Gateway-Built-in-Go"><a href="#GoClaw-An-AI-Agent-Gateway-Built-in-Go" class="headerlink" title="GoClaw: An AI Agent Gateway Built in Go"></a>GoClaw: An AI Agent Gateway Built in Go</h2><p><a target="_blank" rel="noopener" href="https://github.com/nextlevelbuilder/goclaw/">GoClaw</a> is an open-source AI agent gateway built by <a target="_blank" rel="noopener" href="https://github.com/nextlevelbuilder">NextLevelBuilder</a>. It combines WebSocket RPC, HTTP API, multi-channel messaging, and a full agent loop into a single Go binary. What impressed me is how cleanly it implements the same agentic patterns I learned in Python - but designed for production from the start.</p><p>Before diving into GoClaw’s design, here’s where it sits in the landscape:</p><p><strong>Python frameworks</strong> (LangChain, CrewAI, AutoGen) give you building blocks for agent logic. They’re libraries you import and compose in your application code.</p><p><strong>OpenClaw</strong> (Node.js/TypeScript) is the closest architectural peer. It runs as a single gateway process with WebSocket RPC and multi-channel messaging. It’s personal-use focused: file-based storage, single-user, no multi-tenancy. OpenClaw was one of the inspirations when I built <a href="/2026/02/20/Building-MiuBot-A-Personal-AI-Assistant-From-Nanobot-to-Production/">MiuBot</a> in Python.</p><p><strong>GoClaw</strong> takes this further: a <strong>multi-tenant AI agent gateway</strong> with PostgreSQL persistence, RBAC, encrypted credential storage, and team-level isolation. Where MiuBot solves similar problems with Python’s asyncio and Temporal, GoClaw solves them natively in Go.</p><p><strong>Go-native AI frameworks</strong> are emerging too - Google ADK for Go, ByteDance’s Eino, LangChainGo - but they’re SDK libraries, not operational gateways. GoClaw sits one layer above.</p><pre class="mermaid">flowchart TB    subgraph Frameworks["SDK / Frameworks"]        direction LR        LC["LangChain<br>Python"]        AG["AutoGen<br>Python"]        EI["Eino<br>Go"]    end    subgraph Gateways["Gateways / Servers"]        direction LR        OC["OpenClaw<br>Node.js<br>Single-user"]        GC["GoClaw<br>Go<br>Multi-tenant"]    end    subgraph Platforms["Platforms"]        direction LR        DI["Dify<br>Python+TS<br>Visual builder"]    end    Frameworks --&gt; |"import as library"| App["Your Application"]    Gateways --&gt; |"connect via WebSocket/HTTP"| App    Platforms --&gt; |"no-code UI"| App    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    class LC,AG,EI blueClass    class OC,GC orangeClass    class DI greenClass</pre><h2 id="The-Agent-Loop-Same-Concept-Different-Runtime"><a href="#The-Agent-Loop-Same-Concept-Different-Runtime" class="headerlink" title="The Agent Loop: Same Concept, Different Runtime"></a>The Agent Loop: Same Concept, Different Runtime</h2><p>The core agent loop I covered in <a href="/2025/10/30/Anatomy-of-an-AI-Agent-Building-Blocks-and-Workflows/">Anatomy of an AI Agent</a> - <strong>Perceive → Reason → Plan → Act</strong> - maps directly to GoClaw’s implementation. In the <a href="/2025/05/29/LangGraph-State-Graphs-for-Agentic-Workflows/">LangGraph series</a>, we built this as a state graph. GoClaw implements it as a bounded iteration loop:</p><figure class="highlight go hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-function"><span class="hljs-keyword">func</span> <span class="hljs-params">(l *Loop)</span></span> runLoop(ctx context.Context, req RunRequest) RunResult {</span><br><span class="line">    <span class="hljs-keyword">for</span> iteration := <span class="hljs-number">0</span>; iteration &lt; l.maxIterations; iteration++ {</span><br><span class="line">        <span class="hljs-comment">// Think: ask the LLM (chatReq built from session history + system prompt)</span></span><br><span class="line">        response, err := l.provider.ChatStream(ctx, chatReq, onChunk)</span><br><span class="line">        <span class="hljs-keyword">if</span> err != <span class="hljs-literal">nil</span> {</span><br><span class="line">            <span class="hljs-keyword">return</span> RunResult{Error: err}</span><br><span class="line">        }</span><br><span class="line"></span><br><span class="line">        <span class="hljs-comment">// No tool calls? We're done - the LLM has its final answer.</span></span><br><span class="line">        <span class="hljs-keyword">if</span> <span class="hljs-built_in">len</span>(response.ToolCalls) == <span class="hljs-number">0</span> {</span><br><span class="line">            <span class="hljs-keyword">break</span></span><br><span class="line">        }</span><br><span class="line"></span><br><span class="line">        <span class="hljs-comment">// Act: execute tools (parallel when multiple)</span></span><br><span class="line">        results := l.executeTools(ctx, response.ToolCalls)</span><br><span class="line"></span><br><span class="line">        <span class="hljs-comment">// Observe: append results, loop back to Think</span></span><br><span class="line">        l.appendToolResults(results)</span><br><span class="line">    }</span><br><span class="line">    <span class="hljs-keyword">return</span> l.buildResult()</span><br><span class="line">}</span><br></pre></td></tr></tbody></table></figure><p>Same Think→Act→Observe cycle. But GoClaw adds production safeguards that tutorials typically skip.</p><h3 id="Loop-Detection"><a href="#Loop-Detection" class="headerlink" title="Loop Detection"></a>Loop Detection</h3><p>What happens when the LLM calls the same tool with the same arguments and gets the same result, repeatedly? In a tutorial, you hit max iterations. In production, you’re burning tokens for nothing.</p><p>GoClaw hashes every <code>(tool, args, result)</code> tuple with SHA256. Three identical calls trigger a warning injected as a system message nudging the LLM to try a different approach. Five identical calls force the loop to exit.</p><pre class="mermaid">stateDiagram-v2    [*] --&gt; Running    Running --&gt; ToolCall: LLM requests tool    ToolCall --&gt; HashCheck: SHA256(tool+args+result)    HashCheck --&gt; Running: unique hash    HashCheck --&gt; Warning: 3 identical calls    Warning --&gt; Running: nudge different approach    HashCheck --&gt; ForceExit: 5 identical calls    ForceExit --&gt; [*]    Running --&gt; [*]: no tool calls (done)</pre><p>This is a real production problem. No amount of prompt engineering fully prevents it - you need infrastructure-level detection.</p><h3 id="Parallel-Tool-Execution"><a href="#Parallel-Tool-Execution" class="headerlink" title="Parallel Tool Execution"></a>Parallel Tool Execution</h3><p>When the LLM requests multiple tool calls in a single response, GoClaw runs them concurrently with goroutines:</p><figure class="highlight go hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">var</span> wg sync.WaitGroup</span><br><span class="line">results := <span class="hljs-built_in">make</span>([]*ToolResult, <span class="hljs-built_in">len</span>(toolCalls))</span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">for</span> i, call := <span class="hljs-keyword">range</span> toolCalls {</span><br><span class="line">    wg.Add(<span class="hljs-number">1</span>)</span><br><span class="line">    <span class="hljs-keyword">go</span> <span class="hljs-function"><span class="hljs-keyword">func</span><span class="hljs-params">(idx <span class="hljs-type">int</span>, tc ToolCall)</span></span> {</span><br><span class="line">        <span class="hljs-keyword">defer</span> wg.Done()</span><br><span class="line">        results[idx] = registry.Execute(ctx, tc)</span><br><span class="line">    }(i, call)</span><br><span class="line">}</span><br><span class="line"></span><br><span class="line">wg.Wait()</span><br><span class="line"><span class="hljs-comment">// Results sorted by original index for deterministic ordering</span></span><br></pre></td></tr></tbody></table></figure><p>In Python, you’d use <code>asyncio.gather()</code> or <code>ThreadPoolExecutor</code> (as covered in <a href="/2025/12/08/Designing-Multi-Agent-Architecture-From-Solo-to-Ensemble/">Multi-Agent Architecture</a>). In Go, goroutines are the native primitive - no async/await coloring, no event loop to manage.</p><h2 id="Context-Window-The-Three-Layer-Defense"><a href="#Context-Window-The-Three-Layer-Defense" class="headerlink" title="Context Window: The Three-Layer Defense"></a>Context Window: The Three-Layer Defense</h2><p><a href="/2025/07/24/From-Prototype-to-Production-LangGraph-Systems/">From Prototype to Production</a> covered token tracking and cost control at a high level. GoClaw implements context window management as a three-layer pipeline - this is one of the most thoughtful parts of the architecture:</p><p><strong>Layer 1 - History Limiting.</strong> Keep the last N user turns. Simple but coarse.</p><p><strong>Layer 2 - Context Pruning.</strong> For old tool results (which tend to be large), apply a two-pass strategy:</p><ul><li>Soft trim: keep first 1500 chars + last 1500 chars, drop the middle</li><li>Hard clear: replace entire result with <code>[Old tool result content cleared]</code></li></ul><p>Hard clear only activates when context exceeds 50% of the window AND prunable content exceeds 50K characters.</p><p><strong>Layer 3 - Auto-Summarization.</strong> When history hits 75% of the context window, a background goroutine summarizes older messages via an LLM call, keeping only the last 4 messages intact.</p><pre class="mermaid">flowchart LR    A["Raw History"] --&gt; B["Layer 1<br>Limit Turns"]    B --&gt; C["Layer 2<br>Prune Tool Results"]    C --&gt; D["Layer 3<br>Auto-Summarize"]    D --&gt; E["Final Context<br>&lt; Window Size"]    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    class A blueClass    class B,C orangeClass    class D greenClass    class E blueClass</pre><p>A neat detail: the session queue applies <strong>adaptive throttle</strong> when context usage hits 60% - it serializes requests to prevent two concurrent runs from both triggering summarization simultaneously. This is the kind of concurrency bug that only surfaces under real load.</p><h2 id="Tool-Policy-Beyond-Simple-Registration"><a href="#Tool-Policy-Beyond-Simple-Registration" class="headerlink" title="Tool Policy: Beyond Simple Registration"></a>Tool Policy: Beyond Simple Registration</h2><p>In <a href="/2025/11/20/Extending-Agents-with-Tools-and-Structured-Outputs/">Extending Agents with Tools</a>, I learned to register tools as Python functions with schemas. GoClaw shows what tool management looks like in a multi-tenant system where the question isn’t just “what tools exist?” but “who gets access to what?”</p><p>Its tool policy engine evaluates access in 7 steps:</p><ol><li>Global profile (minimal/coding/messaging/full)</li><li>Provider-level profile override</li><li>Global allow list</li><li>Provider-level allow override</li><li>Per-agent allow list</li><li>Per-agent per-provider allow</li><li>Group-level allow</li></ol><p>Then: global deny → agent deny → <code>alsoAllow</code> (additive union).</p><p>Tools are <strong>stateless</strong> - they implement a <code>Tool</code> interface and receive per-call state through Go’s <code>context.Context</code>:</p><figure class="highlight go hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">type</span> Tool <span class="hljs-keyword">interface</span> {</span><br><span class="line">    Name() <span class="hljs-type">string</span></span><br><span class="line">    Description() <span class="hljs-type">string</span></span><br><span class="line">    Parameters() <span class="hljs-keyword">map</span>[<span class="hljs-type">string</span>]<span class="hljs-keyword">interface</span>{}</span><br><span class="line">    Execute(ctx context.Context, args <span class="hljs-keyword">map</span>[<span class="hljs-type">string</span>]<span class="hljs-keyword">interface</span>{}) *Result</span><br><span class="line">}</span><br></pre></td></tr></tbody></table></figure><p>Optional capability interfaces let tools opt into features without polluting the base interface:</p><figure class="highlight go hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">type</span> SandboxAware <span class="hljs-keyword">interface</span> {</span><br><span class="line">    SetSandboxScope(key <span class="hljs-type">string</span>)</span><br><span class="line">}</span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">type</span> StreamingTool <span class="hljs-keyword">interface</span> {</span><br><span class="line">    ExecuteStream(ctx context.Context, args <span class="hljs-keyword">map</span>[<span class="hljs-type">string</span>]<span class="hljs-keyword">interface</span>{}, onChunk <span class="hljs-function"><span class="hljs-keyword">func</span><span class="hljs-params">(<span class="hljs-type">string</span>)</span></span>) *Result</span><br><span class="line">}</span><br></pre></td></tr></tbody></table></figure><p>This is Go’s interface composition - small interfaces, opt-in capabilities, checked at registration time. The Python equivalent would be mixins or decorators.</p><h2 id="Memory-Hybrid-Search-in-Practice"><a href="#Memory-Hybrid-Search-in-Practice" class="headerlink" title="Memory: Hybrid Search in Practice"></a>Memory: Hybrid Search in Practice</h2><p>In <a href="/2025/12/05/Agentic-RAG-and-Agent-Evaluation-Strategies/">Agentic RAG</a>, I explored hybrid search combining BM25 keyword matching with vector similarity. GoClaw implements exactly this with SQLite FTS5 for BM25 and in-memory cosine similarity for vectors:</p><figure class="highlight go hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-function"><span class="hljs-keyword">func</span> <span class="hljs-params">(s *Store)</span></span> HybridSearch(query <span class="hljs-type">string</span>, limit <span class="hljs-type">int</span>) ([]Chunk, <span class="hljs-type">error</span>) {</span><br><span class="line">    <span class="hljs-comment">// BM25 via SQLite FTS5</span></span><br><span class="line">    ftsResults := s.ftsSearch(query, limit*<span class="hljs-number">2</span>)</span><br><span class="line"></span><br><span class="line">    <span class="hljs-comment">// Vector similarity (optional - graceful degradation)</span></span><br><span class="line">    vecResults := s.vectorSearch(query, limit*<span class="hljs-number">2</span>)</span><br><span class="line"></span><br><span class="line">    <span class="hljs-comment">// Weighted fusion</span></span><br><span class="line">    <span class="hljs-keyword">return</span> mergeResults(ftsResults, vecResults, Weights{</span><br><span class="line">        Vector: <span class="hljs-number">0.7</span>,</span><br><span class="line">        FTS:    <span class="hljs-number">0.3</span>,</span><br><span class="line">    }), <span class="hljs-literal">nil</span></span><br><span class="line">}</span><br></pre></td></tr></tbody></table></figure><p>The key design choice: <strong>graceful degradation</strong>. No embedding provider configured? Memory still works with FTS-only search. Vector search fails at runtime? Falls back to FTS. This “always works, sometimes works better” approach is something I wish more Python frameworks adopted.</p><h2 id="Concurrency-Lane-Based-Scheduling"><a href="#Concurrency-Lane-Based-Scheduling" class="headerlink" title="Concurrency: Lane-Based Scheduling"></a>Concurrency: Lane-Based Scheduling</h2><p>In <a href="/2025/12/12/Multi-Agent-Routing-State-and-Coordination/">Multi-Agent Routing, State, and Coordination</a>, I covered thread-safe shared state and routing patterns. GoClaw’s scheduler is a three-level hierarchy that takes these concepts much further:</p><figure class="highlight text hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">Scheduler → LaneManager → SessionQueue</span><br></pre></td></tr></tbody></table></figure><p><strong>Lanes</strong> are named worker pools using semaphore channels:</p><table><thead><tr><th>Lane</th><th>Concurrency</th><th>Purpose</th></tr></thead><tbody><tr><td><code>main</code></td><td>30</td><td>User chat messages</td></tr><tr><td><code>subagent</code></td><td>50</td><td>Child agent loops</td></tr><tr><td><code>delegate</code></td><td>100</td><td>Agent-to-agent delegation</td></tr><tr><td><code>cron</code></td><td>30</td><td>Scheduled tasks</td></tr></tbody></table><p><strong>Session queues</strong> add per-session ordering: FIFO with debounce (800ms default to collapse rapid messages), drop policies (<code>drop_old</code> or <code>drop_new</code>), and interrupt mode (cancel current run, start new one).</p><p>This solves a problem unique to chat applications: when a user sends 5 messages in 3 seconds to a long-running agent, what happens? GoClaw debounces them, queues them, and processes them in order - or interrupts if configured to do so. This is trivial with Go channels, complex with Python’s asyncio.</p><h2 id="Provider-Abstraction"><a href="#Provider-Abstraction" class="headerlink" title="Provider Abstraction"></a>Provider Abstraction</h2><p>In <a href="/2025/05/01/Mastering-LangChain-and-LangGraph-A-Practitioners-Guide/">Mastering LangChain</a>, I learned how LangChain abstracts providers behind a common interface. GoClaw follows the same principle with a minimal 4-method interface:</p><figure class="highlight go hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">type</span> Provider <span class="hljs-keyword">interface</span> {</span><br><span class="line">    Chat(ctx context.Context, req ChatRequest) (*ChatResponse, <span class="hljs-type">error</span>)</span><br><span class="line">    ChatStream(ctx context.Context, req ChatRequest, onChunk <span class="hljs-function"><span class="hljs-keyword">func</span><span class="hljs-params">(StreamChunk)</span></span>) (*ChatResponse, <span class="hljs-type">error</span>)</span><br><span class="line">    DefaultModel() <span class="hljs-type">string</span></span><br><span class="line">    Name() <span class="hljs-type">string</span></span><br><span class="line">}</span><br></pre></td></tr></tbody></table></figure><p>Optional capabilities use separate interfaces - for example, <code>ThinkingCapable</code> gates extended thinking parameters so non-supporting providers never see them. Retry logic uses a generic <code>RetryDo[T]()</code> with exponential backoff, jitter, and <code>Retry-After</code> header respect.</p><h2 id="Multi-Channel-Delivery"><a href="#Multi-Channel-Delivery" class="headerlink" title="Multi-Channel Delivery"></a>Multi-Channel Delivery</h2><p>This goes beyond what I covered in the Python series. The blog posts focused on agent logic; GoClaw addresses a different question: how do agents <strong>reach users where they are</strong>?</p><p>Its channel system supports Telegram, Discord, Feishu/Lark, WhatsApp, and Zalo through a common interface with optional streaming and reaction capabilities. When the LLM streams token by token, streaming channels edit the message in real-time. Reaction channels place emoji on the user’s message to show status: thinking, executing tool, done, or error.</p><p>A central manager goroutine consumes from an event bus and dispatches to the appropriate channel. Inbound messages from any channel normalize through the same bus.</p><h2 id="Two-Modes-Standalone-and-Managed"><a href="#Two-Modes-Standalone-and-Managed" class="headerlink" title="Two Modes: Standalone and Managed"></a>Two Modes: Standalone and Managed</h2><p>GoClaw runs in two modes using the same codebase:</p><p><strong>Standalone</strong> - file-based storage, single workspace, zero configuration beyond an API key. Quick to get started, similar to OpenClaw.</p><p><strong>Managed</strong> - PostgreSQL with pgvector, per-user isolation, RBAC (admin/operator/viewer), AES-256-GCM encrypted API keys, multi-agent support. This is the team/org deployment.</p><p>The store layer uses Go interfaces with two implementations (<code>file/</code> and <code>pg/</code>). Managed-only stores are simply <code>nil</code> in standalone mode - the code checks and skips managed paths. No feature flags, no mode enums.</p><h2 id="Subagents-Controlled-Delegation"><a href="#Subagents-Controlled-Delegation" class="headerlink" title="Subagents: Controlled Delegation"></a>Subagents: Controlled Delegation</h2><p><a href="/2025/12/08/Designing-Multi-Agent-Architecture-From-Solo-to-Ensemble/">Designing Multi-Agent Architecture</a> covered bounded responsibility and failure planning. GoClaw enforces these principles structurally:</p><ul><li><strong>Depth limit</strong> (default 3) - prevents infinite delegation chains</li><li><strong>Per-parent children limit</strong> (8) - bounds fan-out</li><li><strong>Tool deny lists</strong> - leaf agents get restricted tool sets (no spawning further subagents)</li><li><strong>Dedicated scheduler lanes</strong> - subagents don’t compete with user messages for slots</li></ul><p>This is the “specialization” principle from the theory, enforced at the infrastructure level rather than relying on prompt instructions.</p><h2 id="What-This-Teaches"><a href="#What-This-Teaches" class="headerlink" title="What This Teaches"></a>What This Teaches</h2><p>Studying GoClaw’s architecture after building MiuBot in Python reinforced a few things:</p><p><strong>The agent loop is the easy part.</strong> Think→Act→Observe fits in 50 lines of any language. The hard parts are context window management, concurrent session handling, graceful degradation, and multi-tenant isolation.</p><p><strong>Go’s concurrency model is a natural fit for chat gateways.</strong> Goroutines for parallel tool execution, channels for event broadcasting, <code>sync.WaitGroup</code> for coordinating results. No colored functions, no async/await split.</p><p><strong>Interface composition works beautifully for tool systems.</strong> Small interfaces (<code>Tool</code>, <code>SandboxAware</code>, <code>StreamingTool</code>) composed at registration time give you Python’s duck typing with compile-time safety.</p><p><strong>Python and Go serve different stages.</strong> Python for learning, prototyping, and building personal assistants like MiuBot. Go for serving agents at scale in a concurrent, multi-user chat application. I’m now migrating my setup to GoClaw for the production gateway while keeping Python for experimentation.</p><h2 id="Key-Takeaways"><a href="#Key-Takeaways" class="headerlink" title="Key Takeaways"></a>Key Takeaways</h2><ol><li><strong>Python works well for learning and prototyping agent patterns.</strong> The ecosystem is unmatched. But for production chat gateways serving concurrent users, Go’s runtime characteristics are a better fit.</li><li><strong>Go’s goroutines eliminate the async complexity</strong> that surfaces when handling many concurrent WebSocket connections with streaming responses.</li><li><strong>Context window management needs multiple layers.</strong> History limiting, content pruning, and auto-summarization work together - no single strategy is sufficient.</li><li><strong>Tool access control is a production requirement,</strong> not an afterthought. Multi-tenant systems need policy engines, not just registries.</li><li><strong>Loop detection saves real money.</strong> A stuck agent burning tokens in a loop is invisible until your bill arrives. Hash-based detection catches it early.</li><li><strong>Graceful degradation beats hard dependencies.</strong> Memory works without vectors. Channels work without streaming. Every optional capability has a working fallback.</li><li><strong>The concepts transfer across languages.</strong> ReAct loops, hybrid search, multi-agent coordination, provider abstraction - the principles are language-agnostic. GoClaw is proof that what you learn in Python applies directly to Go.</li></ol><hr><p><em>If you’re interested in GoClaw, check out the project on <a target="_blank" rel="noopener" href="https://github.com/nextlevelbuilder/goclaw/">GitHub</a>. For the Python side of this journey, see <a href="/2026/02/20/Building-MiuBot-A-Personal-AI-Assistant-From-Nanobot-to-Production/">Building MiuBot</a> and the foundational concepts in my <a href="/2025/10/30/Anatomy-of-an-AI-Agent-Building-Blocks-and-Workflows/">Agentic AI series</a> and <a href="/2025/05/01/Mastering-LangChain-and-LangGraph-A-Practitioners-Guide/">LangChain/LangGraph series</a>.</em></p></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;p&gt;I learned agentic AI concepts in Python - &lt;a href=&quot;/2025/10/30/Anatomy-of-an-AI-Agent-Building-Blocks-and-Workflows/&quot;&gt;agent loops&lt;/a&gt;, &lt;a href=&quot;/2025/11/20/Extending-Agents-with-Tools-and-Structured-Outputs/&quot;&gt;tool calling&lt;/a&gt;, &lt;a href=&quot;/2025/12/08/Designing-Multi-Agent-Architecture-From-Solo-to-Ensemble/&quot;&gt;multi-agent coordination&lt;/a&gt;, &lt;a href=&quot;/2025/07/24/From-Prototype-to-Production-LangGraph-Systems/&quot;&gt;production patterns&lt;/a&gt;. I even &lt;a href=&quot;/2026/02/20/Building-MiuBot-A-Personal-AI-Assistant-From-Nanobot-to-Production/&quot;&gt;built my own Python assistant&lt;/a&gt; - MiuBot - with 10 chat channels, Temporal workflows, and multi-tenant workspaces. Python works well for most of these cases. But while building MiuBot, I kept hitting the same question: what happens when you need to serve many users concurrently over WebSocket with streaming responses? That’s when I discovered &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://github.com/nextlevelbuilder/goclaw/&quot;&gt;GoClaw&lt;/a&gt; from the &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://github.com/nextlevelbuilder&quot;&gt;NextLevelBuilder&lt;/a&gt; team, and it changed how I think about the problem.&lt;/p&gt;
&lt;p&gt;&lt;a class=&quot;github-card-link&quot; target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://github.com/nextlevelbuilder/goclaw/&quot;&gt;&lt;img src=&quot;https://gh-card.dev/repos/nextlevelbuilder/goclaw.svg&quot; alt=&quot;GoClaw&quot;&gt;&lt;/a&gt;&lt;/p&gt;
&lt;style&gt;.github-card-link::after { display: none !important; }&lt;/style&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="llm" scheme="https://vanducng.dev/tags/llm/"/>
    
    <category term="agents" scheme="https://vanducng.dev/tags/agents/"/>
    
    <category term="multi-agent" scheme="https://vanducng.dev/tags/multi-agent/"/>
    
    <category term="production" scheme="https://vanducng.dev/tags/production/"/>
    
    <category term="golang" scheme="https://vanducng.dev/tags/golang/"/>
    
  </entry>
  
  <entry>
    <title>Building MiuBot - A Personal AI Assistant From Nanobot to Production</title>
    <link href="https://vanducng.dev/2026/02/20/Building-MiuBot-A-Personal-AI-Assistant-From-Nanobot-to-Production/"/>
    <id>https://vanducng.dev/2026/02/20/Building-MiuBot-A-Personal-AI-Assistant-From-Nanobot-to-Production/</id>
    <published>2026-02-20T09:00:00.000Z</published>
    <updated>2026-11-16T05:26:58.193Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><p>After months of studying agentic AI patterns in theory - <a href="/2025/10/30/Anatomy-of-an-AI-Agent-Building-Blocks-and-Workflows/">agent loops</a>, <a href="/2025/11/20/Extending-Agents-with-Tools-and-Structured-Outputs/">tool calling</a>, <a href="/2025/12/08/Designing-Multi-Agent-Architecture-From-Solo-to-Ensemble/">multi-agent coordination</a> - I wanted to build something real. Not another tutorial project, but an AI assistant I could actually use daily, connected to the chat platforms I already live on. That’s how <a target="_blank" rel="noopener" href="https://github.com/dataplanelabs/miu-bot">MiuBot</a> started - forked from <a target="_blank" rel="noopener" href="https://github.com/HKUDS/nanobot">Nanobot</a>, then reshaped into something quite different.</p><p><a class="github-card-link" target="_blank" rel="noopener" href="https://github.com/dataplanelabs/miu-bot"><img src="https://gh-card.dev/repos/dataplanelabs/miu-bot.svg" alt="MiuBot"></a></p><style>.github-card-link::after { display: none !important; }</style><span id="more"></span><h2 id="Why-Nanobot-as-a-Starting-Point"><a href="#Why-Nanobot-as-a-Starting-Point" class="headerlink" title="Why Nanobot as a Starting Point"></a>Why Nanobot as a Starting Point</h2><p>I wasn’t starting from scratch. I’d spent months learning agent concepts through Python frameworks - LangChain, LangGraph, and the patterns covered in my <a href="/2025/10/30/Anatomy-of-an-AI-Agent-Building-Blocks-and-Workflows/">agentic AI series</a>. But I wanted a <strong>standalone assistant</strong> - something that runs as its own process, connects to chat platforms, and handles real conversations with tool use.</p><p><a target="_blank" rel="noopener" href="https://github.com/HKUDS/nanobot">Nanobot</a> caught my attention: a lightweight Python assistant with a clean agent loop, tool calling, and chat integrations for Telegram, Discord, and several other platforms. File-based storage, single-process, JSON sessions - simple and readable. More importantly, it was small enough to understand completely in a few hours. That matters when you plan to rip it apart and rebuild it.</p><p>I also studied <a target="_blank" rel="noopener" href="https://github.com/openclaw/openclaw">OpenClaw</a> (Node.js/TypeScript) which runs as a WebSocket RPC gateway with multi-channel messaging. Its architecture gave me ideas about how a personal assistant should be structured - not as a library you import, but as a <strong>gateway</strong> that sits between users and LLMs. I adopted OpenClaw’s <a target="_blank" rel="noopener" href="https://github.com/openclaw/openclaw">SKILL.md format</a> for the skills system and even changed MiuBot’s default port to 18790 to avoid conflicting with OpenClaw’s port.</p><h2 id="From-Fork-to-Rebuild"><a href="#From-Fork-to-Rebuild" class="headerlink" title="From Fork to Rebuild"></a>From Fork to Rebuild</h2><p>The fork started on February 1, 2026. Within three weeks, almost nothing from the original Nanobot remained. Here’s the transformation:</p><table><thead><tr><th>Aspect</th><th>Nanobot</th><th>MiuBot</th></tr></thead><tbody><tr><td>Storage</td><td>JSON files</td><td>PostgreSQL + pgvector (30+ tables)</td></tr><tr><td>Durability</td><td>Event-driven, in-memory</td><td>Temporal workflows (distributed, durable)</td></tr><tr><td>Tenancy</td><td>Single-user</td><td>Multi-tenant with Gateway/Worker split</td></tr><tr><td>Memory</td><td>Basic conversation history</td><td>3-tier BASB (Active/Reference/Archive)</td></tr><tr><td>Scalability</td><td>Single process</td><td>Horizontal: K8s HPA, worker pools</td></tr><tr><td>Observability</td><td>Logs only</td><td>OpenTelemetry tracing, metrics, cost tracking</td></tr><tr><td>IDs</td><td>Mixed formats</td><td>UUIDv7 everywhere</td></tr></tbody></table><h3 id="The-Agent-Loop"><a href="#The-Agent-Loop" class="headerlink" title="The Agent Loop"></a>The Agent Loop</h3><p>Nanobot had a straightforward loop: receive message, call LLM, execute tools, respond. MiuBot keeps the same Think-Act-Observe cycle from <a href="/2025/10/30/Anatomy-of-an-AI-Agent-Building-Blocks-and-Workflows/">Anatomy of an AI Agent</a>, but adds production guardrails:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">AgentLoop</span>:</span><br><span class="line">    <span class="hljs-keyword">async</span> <span class="hljs-keyword">def</span> <span class="title function_">_run_agent_loop</span>(<span class="hljs-params">self, initial_messages, channel, chat_id, ...</span>):</span><br><span class="line">        messages = initial_messages</span><br><span class="line">        iteration = <span class="hljs-number">0</span></span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">while</span> iteration &lt; <span class="variable language_">self</span>.max_iterations:</span><br><span class="line">            iteration += <span class="hljs-number">1</span></span><br><span class="line"></span><br><span class="line">            <span class="hljs-keyword">try</span>:</span><br><span class="line">                response = <span class="hljs-keyword">await</span> asyncio.wait_for(</span><br><span class="line">                    <span class="variable language_">self</span>.provider.chat(</span><br><span class="line">                        messages=messages,</span><br><span class="line">                        tools=<span class="variable language_">self</span>.tools.get_definitions(),</span><br><span class="line">                        model=<span class="variable language_">self</span>.model,</span><br><span class="line">                    ),</span><br><span class="line">                    timeout=<span class="hljs-number">180</span>,</span><br><span class="line">                )</span><br><span class="line">            <span class="hljs-keyword">except</span> asyncio.TimeoutError:</span><br><span class="line">                <span class="hljs-keyword">break</span>  <span class="hljs-comment"># Don't hang forever</span></span><br><span class="line"></span><br><span class="line">            <span class="hljs-keyword">if</span> response.has_tool_calls:</span><br><span class="line">                <span class="hljs-comment"># Execute tools, append results, continue loop</span></span><br><span class="line">                <span class="hljs-keyword">for</span> tool_call <span class="hljs-keyword">in</span> response.tool_calls:</span><br><span class="line">                    result = <span class="hljs-keyword">await</span> <span class="variable language_">self</span>.tools.execute(</span><br><span class="line">                        tool_call.name, tool_call.arguments</span><br><span class="line">                    )</span><br><span class="line">                    messages = <span class="variable language_">self</span>.context.add_tool_result(</span><br><span class="line">                        messages, tool_call.<span class="hljs-built_in">id</span>, tool_call.name, result</span><br><span class="line">                    )</span><br><span class="line">            <span class="hljs-keyword">else</span>:</span><br><span class="line">                final_content = response.content</span><br><span class="line">                <span class="hljs-keyword">break</span></span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">return</span> final_content, tools_used, total_usage, messages</span><br></pre></td></tr></tbody></table></figure><p>The key additions: <strong>180-second timeout</strong> per LLM call, <strong>per-session locks</strong> to prevent race conditions on tool routing state, and <strong>usage tracking</strong> that accumulates tokens across iterations. None of these exist in a tutorial implementation.</p><h3 id="Per-Session-Concurrency"><a href="#Per-Session-Concurrency" class="headerlink" title="Per-Session Concurrency"></a>Per-Session Concurrency</h3><p>The original Nanobot processed messages sequentially. One user waiting for a long tool execution blocks everyone. MiuBot dispatches each session to its own asyncio task with a dedicated queue:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-comment"># Per-session processing: one concurrent task per session key</span></span><br><span class="line"><span class="variable language_">self</span>._session_tasks: <span class="hljs-built_in">dict</span>[<span class="hljs-built_in">str</span>, asyncio.Task] = {}</span><br><span class="line"><span class="variable language_">self</span>._session_queues: <span class="hljs-built_in">dict</span>[<span class="hljs-built_in">str</span>, asyncio.Queue] = {}</span><br><span class="line"><span class="variable language_">self</span>._session_locks: <span class="hljs-built_in">dict</span>[<span class="hljs-built_in">str</span>, asyncio.Lock] = {}</span><br></pre></td></tr></tbody></table></figure><p>Each chat session (identified by channel + chat ID) gets its own worker task. Messages queue up per-session, so Telegram user A and Discord user B run concurrently, but rapid messages from the same user serialize correctly.</p><h3 id="Side-Effect-Dedup-and-Tool-Loop-Detection"><a href="#Side-Effect-Dedup-and-Tool-Loop-Detection" class="headerlink" title="Side-Effect Dedup and Tool Loop Detection"></a>Side-Effect Dedup and Tool Loop Detection</h3><p>A problem I hit early: the LLM sometimes calls the same tool twice in a loop, or retries a side-effect tool (like sending a message) that already succeeded. MiuBot detects this with SHA256 hashing of <code>(tool_name, args)</code> for state-changing tools:</p><ul><li>Tools prefixed with <code>create_</code>, <code>update_</code>, <code>delete_</code>, <code>send_</code> are tracked as side-effects</li><li>Identical calls within the same loop iteration are deduplicated</li><li>A per-tool cap (<code>MAX_SAME_TOOL_CALLS=3</code>) prevents infinite loops</li><li>Read-only tools (<code>list</code>, <code>get</code>, <code>search</code>) are exempt</li></ul><p>This saved real money during early testing when the agent got stuck in a loop calling the same web search 10 times.</p><h2 id="10-Chat-Channels"><a href="#10-Chat-Channels" class="headerlink" title="10 Chat Channels"></a>10 Chat Channels</h2><p>This was the biggest investment. Nanobot already supported several platforms. MiuBot connects to 10:</p><table><thead><tr><th>Channel</th><th>Transport</th><th>Public IP Required</th></tr></thead><tbody><tr><td>Telegram</td><td>Long polling</td><td>No</td></tr><tr><td>Discord</td><td>WebSocket gateway</td><td>No</td></tr><tr><td>WhatsApp</td><td>Node.js bridge (WebSocket)</td><td>No</td></tr><tr><td>Feishu</td><td>WebSocket long connection</td><td>No</td></tr><tr><td>DingTalk</td><td>Stream mode</td><td>No</td></tr><tr><td>Slack</td><td>Socket mode</td><td>No</td></tr><tr><td>Email</td><td>IMAP polling + SMTP</td><td>No</td></tr><tr><td>QQ</td><td>botpy SDK (WebSocket)</td><td>No</td></tr><tr><td>Zalo</td><td>ZCA-CLI WebSocket bridge</td><td>No</td></tr><tr><td>Mochat</td><td>Socket.IO + msgpack</td><td>No</td></tr></tbody></table><p>A deliberate design choice: <strong>no channel requires a public IP</strong>. Every platform uses either long polling, WebSocket, or a bridge process. This means MiuBot runs behind a NAT, on a home server, or inside a corporate network without port forwarding.</p><p>Each channel implements a base interface with platform-specific formatting rules. Zalo doesn’t support Markdown, so the context builder injects formatting constraints into the system prompt:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line">_ZALO_FORMATTING_RULES = (</span><br><span class="line">    <span class="hljs-string">"\n\nFORMATTING RULES (MANDATORY):"</span></span><br><span class="line">    <span class="hljs-string">"\n- Zalo does NOT support markdown. NEVER use: ## headings, "</span></span><br><span class="line">    <span class="hljs-string">"**bold**, *italic*, `code`, tables, or &gt; quotes."</span></span><br><span class="line">    <span class="hljs-string">"\n- Use plain text only: VIET HOA for headings, bullet '-' for lists."</span></span><br><span class="line">)</span><br></pre></td></tr></tbody></table></figure><p>This is a pattern I didn’t see in any tutorial: <strong>channel-aware prompt injection</strong> - the system prompt adapts based on where the message came from.</p><h2 id="3-Tier-Memory-BASB-Inspired"><a href="#3-Tier-Memory-BASB-Inspired" class="headerlink" title="3-Tier Memory: BASB-Inspired"></a>3-Tier Memory: BASB-Inspired</h2><p>In <a href="/2025/11/25/Agent-State-and-Memory-Beyond-Single-Interactions/">Agent State and Memory</a>, I explored how agents maintain context across conversations. MiuBot implements a memory system inspired by <a target="_blank" rel="noopener" href="https://fortelabs.com/blog/basboverview/">Building a Second Brain (BASB)</a> with three tiers:</p><p><strong>Active</strong> - Short-term memories extracted from daily conversations. Things like “user prefers Vietnamese for casual chat” or “working on the API migration project.”</p><p><strong>Reference</strong> - Weekly consolidation compresses daily notes into durable insights. An LLM reviews the week’s active memories and produces structured reference entries.</p><p><strong>Archive</strong> - Monthly consolidation compresses reference memories further. Long-term storage for context that rarely changes.</p><pre class="mermaid">flowchart LR    A["Daily\nConversations"] --&gt; B["Daily\nConsolidation"]    B --&gt; C["Active\nMemories"]    C --&gt; D["Weekly\nConsolidation"]    D --&gt; E["Reference\nMemories"]    E --&gt; F["Monthly\nConsolidation"]    F --&gt; G["Archive\nMemories"]    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    class A,B blueClass    class C,D orangeClass    class E,F,G greenClass</pre><p>Each consolidation job uses a <strong>distributed advisory lock</strong> in PostgreSQL to prevent duplicate processing when multiple workers run:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line">lock_key = <span class="hljs-built_in">int</span>.from_bytes(</span><br><span class="line">    hashlib.sha256(<span class="hljs-string">f"daily:<span class="hljs-subst">{ws.<span class="hljs-built_in">id</span>}</span>"</span>.encode()).digest()[:<span class="hljs-number">8</span>],</span><br><span class="line">    <span class="hljs-string">"big"</span>, signed=<span class="hljs-literal">True</span>,</span><br><span class="line">)</span><br><span class="line">locked = <span class="hljs-keyword">await</span> conn.fetchval(</span><br><span class="line">    <span class="hljs-string">"SELECT pg_try_advisory_lock($1)"</span>, lock_key</span><br><span class="line">)</span><br><span class="line"><span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> locked:</span><br><span class="line">    <span class="hljs-keyword">return</span> {<span class="hljs-string">"status"</span>: <span class="hljs-string">"skipped"</span>, <span class="hljs-string">"reason"</span>: <span class="hljs-string">"locked"</span>}</span><br></pre></td></tr></tbody></table></figure><p>The consolidation runs as a Temporal scheduled workflow - not a cron job. Temporal gives us exactly-once execution, automatic retry on failure, and visibility into what happened and when.</p><h2 id="Durable-Workflows-with-Temporal"><a href="#Durable-Workflows-with-Temporal" class="headerlink" title="Durable Workflows with Temporal"></a>Durable Workflows with Temporal</h2><p>This is where MiuBot diverges most from typical Python assistant projects. Instead of processing messages in a single async loop, MiuBot uses <a target="_blank" rel="noopener" href="https://temporal.io/">Temporal</a> for durable workflow orchestration:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-meta">@workflow.defn</span></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">BotSessionWorkflow</span>:</span><br><span class="line">    <span class="hljs-string">"""Durable per-session workflow. One instance per (workspace, session)."""</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">    @workflow.signal</span></span><br><span class="line">    <span class="hljs-keyword">async</span> <span class="hljs-keyword">def</span> <span class="title function_">new_message</span>(<span class="hljs-params">self, msg: <span class="hljs-built_in">dict</span></span>) -&gt; <span class="hljs-literal">None</span>:</span><br><span class="line">        <span class="variable language_">self</span>._pending_messages.append(msg)</span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">    @workflow.run</span></span><br><span class="line">    <span class="hljs-keyword">async</span> <span class="hljs-keyword">def</span> <span class="title function_">run</span>(<span class="hljs-params">self, session_info: <span class="hljs-built_in">dict</span></span>) -&gt; <span class="hljs-literal">None</span>:</span><br><span class="line">        <span class="hljs-keyword">while</span> <span class="hljs-literal">True</span>:</span><br><span class="line">            <span class="hljs-keyword">await</span> workflow.wait_condition(</span><br><span class="line">                <span class="hljs-keyword">lambda</span>: <span class="hljs-built_in">len</span>(<span class="variable language_">self</span>._pending_messages) &gt; <span class="hljs-number">0</span></span><br><span class="line">            )</span><br><span class="line">            msg = <span class="variable language_">self</span>._pending_messages.pop(<span class="hljs-number">0</span>)</span><br><span class="line">            result = <span class="hljs-keyword">await</span> workflow.execute_activity(</span><br><span class="line">                <span class="hljs-string">"process_message_activity"</span>,</span><br><span class="line">                args=[msg, session_info],</span><br><span class="line">                start_to_close_timeout=timedelta(minutes=<span class="hljs-number">10</span>),</span><br><span class="line">                heartbeat_timeout=timedelta(minutes=<span class="hljs-number">5</span>),</span><br><span class="line">            )</span><br></pre></td></tr></tbody></table></figure><p>Each conversation session is a <strong>long-running Temporal workflow</strong>. Incoming messages are signals, processing happens as activities. If the worker crashes mid-response, Temporal retries the activity automatically. The workflow survives process restarts.</p><p>This also enables the gateway/worker split:</p><pre class="mermaid">flowchart LR    A["Telegram"] --&gt; GW["Gateway\n(routing)"]    B["Discord"] --&gt; GW    C["Zalo"] --&gt; GW    GW --&gt; T["Temporal\nServer"]    T --&gt; W1["Worker 1\n(bot: assistant)"]    T --&gt; W2["Worker 2\n(bot: researcher)"]    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    class A,B,C blueClass    class GW,T orangeClass    class W1,W2 greenClass</pre><p>The gateway handles channel connections and message routing. Workers process messages and call LLMs. You can scale workers independently, filter by bot name, and deploy different workers with different resource allocations.</p><h2 id="Multi-Tenant-Workspaces"><a href="#Multi-Tenant-Workspaces" class="headerlink" title="Multi-Tenant Workspaces"></a>Multi-Tenant Workspaces</h2><p>What started as a personal project became multi-tenant. MiuBot supports isolated workspaces - each with its own bots, providers, channels, and memory:</p><figure class="highlight yaml hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-comment"># bots.yaml - multi-bot configuration</span></span><br><span class="line"><span class="hljs-attr">bots:</span></span><br><span class="line">  <span class="hljs-attr">assistant:</span></span><br><span class="line">    <span class="hljs-attr">soul:</span> <span class="hljs-string">/path/to/soul.md</span></span><br><span class="line">    <span class="hljs-attr">provider:</span></span><br><span class="line">      <span class="hljs-attr">model:</span> <span class="hljs-string">anthropic/claude-sonnet-4-5-20250929</span></span><br><span class="line">      <span class="hljs-attr">api_key_env:</span> <span class="hljs-string">ANTHROPIC_API_KEY</span></span><br><span class="line">    <span class="hljs-attr">channels:</span></span><br><span class="line">      <span class="hljs-attr">telegram:</span></span><br><span class="line">        <span class="hljs-attr">token_env:</span> <span class="hljs-string">ASSISTANT_TG_TOKEN</span></span><br><span class="line">    <span class="hljs-attr">jobs:</span></span><br><span class="line">      <span class="hljs-attr">morning_briefing:</span></span><br><span class="line">        <span class="hljs-attr">schedule:</span> <span class="hljs-string">"0 8 * * *"</span></span><br><span class="line">        <span class="hljs-attr">timezone:</span> <span class="hljs-string">"Asia/Saigon"</span></span><br><span class="line">        <span class="hljs-attr">prompt:</span> <span class="hljs-string">"Summarize top news"</span></span><br><span class="line">        <span class="hljs-attr">targets:</span></span><br><span class="line">          <span class="hljs-bullet">-</span> <span class="hljs-attr">channel:</span> <span class="hljs-string">telegram</span></span><br><span class="line">            <span class="hljs-attr">chat_id_env:</span> <span class="hljs-string">NEWS_CHAT_ID</span></span><br></pre></td></tr></tbody></table></figure><p>Each bot gets its own identity (“soul” file), provider configuration, channel tokens, and scheduled jobs. The workspace resolver routes incoming messages to the correct bot based on channel token matching.</p><h2 id="MCP-Integration"><a href="#MCP-Integration" class="headerlink" title="MCP Integration"></a>MCP Integration</h2><p><a target="_blank" rel="noopener" href="https://modelcontextprotocol.io/">Model Context Protocol (MCP)</a> support was straightforward since the config format is compatible with Claude Desktop and Cursor:</p><figure class="highlight json hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-punctuation">{</span></span><br><span class="line">  <span class="hljs-attr">"tools"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span></span><br><span class="line">    <span class="hljs-attr">"mcpServers"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span></span><br><span class="line">      <span class="hljs-attr">"filesystem"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span></span><br><span class="line">        <span class="hljs-attr">"command"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"npx"</span><span class="hljs-punctuation">,</span></span><br><span class="line">        <span class="hljs-attr">"args"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-string">"-y"</span><span class="hljs-punctuation">,</span> <span class="hljs-string">"@modelcontextprotocol/server-filesystem"</span><span class="hljs-punctuation">,</span> <span class="hljs-string">"/path"</span><span class="hljs-punctuation">]</span></span><br><span class="line">      <span class="hljs-punctuation">}</span></span><br><span class="line">    <span class="hljs-punctuation">}</span></span><br><span class="line">  <span class="hljs-punctuation">}</span></span><br><span class="line"><span class="hljs-punctuation">}</span></span><br></pre></td></tr></tbody></table></figure><p>MCP servers connect lazily on first message and register their tools into the same registry as built-in tools. The agent doesn’t distinguish between native tools and MCP tools - they all implement the same interface.</p><h2 id="13-LLM-Providers"><a href="#13-LLM-Providers" class="headerlink" title="13+ LLM Providers"></a>13+ LLM Providers</h2><p>Rather than building provider-specific clients, MiuBot uses a registry pattern with LiteLLM as the underlying abstraction:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br></pre></td><td class="code"><pre><span class="line">ProviderSpec(</span><br><span class="line">    name=<span class="hljs-string">"openrouter"</span>,</span><br><span class="line">    keywords=(<span class="hljs-string">"openrouter"</span>,),</span><br><span class="line">    env_key=<span class="hljs-string">"OPENROUTER_API_KEY"</span>,</span><br><span class="line">    display_name=<span class="hljs-string">"OpenRouter"</span>,</span><br><span class="line">    litellm_prefix=<span class="hljs-string">"openrouter"</span>,</span><br><span class="line">    skip_prefixes=(<span class="hljs-string">"openrouter/"</span>,),</span><br><span class="line">)</span><br></pre></td></tr></tbody></table></figure><p>Adding a new provider is two steps: add a <code>ProviderSpec</code> and a config field. Everything else - environment variables, model prefixing, status display - works automatically. This supports OpenRouter, Anthropic, OpenAI, DeepSeek, Groq, Gemini, MiniMax, DashScope, Moonshot, Zhipu, AIHubMix, custom endpoints, and local vLLM servers.</p><h2 id="Subagent-System"><a href="#Subagent-System" class="headerlink" title="Subagent System"></a>Subagent System</h2><p>Following the patterns from <a href="/2025/12/08/Designing-Multi-Agent-Architecture-From-Solo-to-Ensemble/">Multi-Agent Architecture</a>, MiuBot supports spawning subagents for background tasks:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">SubagentManager</span>:</span><br><span class="line">    <span class="hljs-string">"""Lightweight agent instances that run in the background."""</span></span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">async</span> <span class="hljs-keyword">def</span> <span class="title function_">spawn</span>(<span class="hljs-params">self, task: <span class="hljs-built_in">str</span>, label: <span class="hljs-built_in">str</span> | <span class="hljs-literal">None</span> = <span class="hljs-literal">None</span>, ...</span>):</span><br><span class="line">        <span class="hljs-comment"># Creates isolated context with focused system prompt</span></span><br><span class="line">        <span class="hljs-comment"># Shares LLM provider but gets restricted tool set</span></span><br><span class="line">        <span class="hljs-comment"># Results are delivered back via the message bus</span></span><br></pre></td></tr></tbody></table></figure><p>Subagents share the LLM provider but get isolated context and a reduced tool set. They can’t spawn further subagents (no infinite delegation). Results flow back through the message bus, so the parent agent or the user gets notified when the background task completes.</p><h2 id="Skills-System"><a href="#Skills-System" class="headerlink" title="Skills System"></a>Skills System</h2><p>Adopted from OpenClaw’s SKILL.md format, MiuBot’s skills system uses a 5-tier hierarchy:</p><ol><li><strong>Workspace</strong> - team-level skills shared across bots</li><li><strong>Project</strong> - project-specific skills</li><li><strong>Personal</strong> - per-user skills</li><li><strong>Global</strong> - system-wide defaults</li><li><strong>Builtin</strong> - hardcoded essentials</li></ol><p>Skills are Markdown files with optional YAML frontmatter. The system uses <strong>BM25 keyword search</strong> to automatically inject relevant skills into the agent’s context based on the user’s message - no manual tagging or routing required. A file watcher with 500ms debounce enables hot-reloading during development.</p><h2 id="Bot-Identity"><a href="#Bot-Identity" class="headerlink" title="Bot Identity"></a>Bot Identity</h2><p>Each bot in a workspace has a rich identity system through context files:</p><table><thead><tr><th>File</th><th>Purpose</th></tr></thead><tbody><tr><td><code>SOUL.md</code></td><td>Core personality, values, communication style</td></tr><tr><td><code>USER.md</code></td><td>Knowledge about the bot’s user/owner</td></tr><tr><td><code>AGENTS.md</code></td><td>Available subagents and delegation rules</td></tr><tr><td><code>IDENTITY.md</code></td><td>Name, role, backstory</td></tr><tr><td><code>TOOLS.md</code></td><td>Tool usage guidelines and restrictions</td></tr><tr><td><code>MEMORY.md</code></td><td>Memory management instructions</td></tr><tr><td><code>HEARTBEAT.md</code></td><td>Proactive wake-up rules</td></tr><tr><td><code>BOOTSTRAP.md</code></td><td>First-run ritual (auto-deleted after 3 turns)</td></tr></tbody></table><p>The <code>BOOTSTRAP.md</code> pattern is interesting - it runs a first-run onboarding conversation where the bot learns about its user, then deletes the file so it never triggers again. The knowledge gets saved to memory instead.</p><h2 id="What-I-Learned"><a href="#What-I-Learned" class="headerlink" title="What I Learned"></a>What I Learned</h2><p>Building MiuBot taught me things that studying patterns in isolation doesn’t:</p><p><strong>Channel diversity is a user experience problem, not just a technical one.</strong> Each platform has different formatting rules, message length limits, media handling, and user expectations. The system prompt needs to adapt per-channel.</p><p><strong>Per-session concurrency is harder than per-request.</strong> HTTP APIs process independent requests. Chat sessions have state, ordering requirements, and the possibility of a user sending 5 messages while the agent processes the first one.</p><p><strong>Memory consolidation needs infrastructure.</strong> Running an LLM to summarize yesterday’s conversations sounds simple. Doing it reliably across multiple workspaces with exactly-once guarantees requires Temporal or something equivalent.</p><p><strong>Python’s async works well enough for this scale.</strong> For a personal assistant serving a handful of users across multiple channels, Python’s asyncio handles the concurrency fine. The bottleneck is always the LLM API call, not the framework.</p><p>That last point is important. Python works well for this use case. But as I started thinking about scaling beyond personal use - many users, concurrent WebSocket sessions, streaming responses - I started looking at what a Go implementation would look like. That led me to <a href="/2026/02/28/From-Theory-to-Gateway-Building-a-Production-AI-Agent-System-in-Go/">GoClaw</a>, which takes the same gateway concept much further with Go’s concurrency primitives. More on that in the next post.</p><h2 id="Key-Takeaways"><a href="#Key-Takeaways" class="headerlink" title="Key Takeaways"></a>Key Takeaways</h2><ol><li><strong>Start with something that works, then reshape it.</strong> Nanobot gave me a running agent loop in hours. The rebuild happened incrementally over three weeks while the bot was already useful.</li><li><strong>Chat platforms are the real integration challenge.</strong> The agent loop is 50 lines. Getting Zalo, WhatsApp, and Telegram to work reliably with proper formatting is 10x more code.</li><li><strong>Temporal changes how you think about reliability.</strong> Once message processing is a durable workflow, crashes and restarts stop being scary. The workflow picks up where it left off.</li><li><strong>BASB-inspired memory consolidation works.</strong> Daily/weekly/monthly compression keeps long-term context manageable without unbounded growth.</li><li><strong>MCP makes tool integration trivial.</strong> Compatible config format with Claude Desktop means you can copy-paste server configs and they just work.</li><li><strong>Python is the right choice for a personal AI assistant.</strong> The ecosystem (LiteLLM, Temporal SDK, asyncio, Pydantic) is mature and well-documented. The performance ceiling is high enough for personal/small-team use.</li></ol><hr><p><em>MiuBot is open source at <a target="_blank" rel="noopener" href="https://github.com/dataplanelabs/miu-bot">GitHub</a>. If you’re interested in how these concepts translate to a Go-based production gateway, see the next post: <a href="/2026/02/28/From-Theory-to-Gateway-Building-a-Production-AI-Agent-System-in-Go/">From Theory to Gateway - Why Go Makes Sense for Production AI Agents</a>.</em></p></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;p&gt;After months of studying agentic AI patterns in theory - &lt;a href=&quot;/2025/10/30/Anatomy-of-an-AI-Agent-Building-Blocks-and-Workflows/&quot;&gt;agent loops&lt;/a&gt;, &lt;a href=&quot;/2025/11/20/Extending-Agents-with-Tools-and-Structured-Outputs/&quot;&gt;tool calling&lt;/a&gt;, &lt;a href=&quot;/2025/12/08/Designing-Multi-Agent-Architecture-From-Solo-to-Ensemble/&quot;&gt;multi-agent coordination&lt;/a&gt; - I wanted to build something real. Not another tutorial project, but an AI assistant I could actually use daily, connected to the chat platforms I already live on. That’s how &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://github.com/dataplanelabs/miu-bot&quot;&gt;MiuBot&lt;/a&gt; started - forked from &lt;a target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://github.com/HKUDS/nanobot&quot;&gt;Nanobot&lt;/a&gt;, then reshaped into something quite different.&lt;/p&gt;
&lt;p&gt;&lt;a class=&quot;github-card-link&quot; target=&quot;_blank&quot; rel=&quot;noopener&quot; href=&quot;https://github.com/dataplanelabs/miu-bot&quot;&gt;&lt;img src=&quot;https://gh-card.dev/repos/dataplanelabs/miu-bot.svg&quot; alt=&quot;MiuBot&quot;&gt;&lt;/a&gt;&lt;/p&gt;
&lt;style&gt;.github-card-link::after { display: none !important; }&lt;/style&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="llm" scheme="https://vanducng.dev/tags/llm/"/>
    
    <category term="python" scheme="https://vanducng.dev/tags/python/"/>
    
    <category term="agents" scheme="https://vanducng.dev/tags/agents/"/>
    
    <category term="multi-agent" scheme="https://vanducng.dev/tags/multi-agent/"/>
    
    <category term="production" scheme="https://vanducng.dev/tags/production/"/>
    
  </entry>
  
  <entry>
    <title>Data Agents: From OpenAI&#39;s 6 Layers to Open-Source Alternatives</title>
    <link href="https://vanducng.dev/2026/02/06/Data-Agents-From-OpenAI-to-Open-Source/"/>
    <id>https://vanducng.dev/2026/02/06/Data-Agents-From-OpenAI-to-Open-Source/</id>
    <published>2026-02-06T15:00:00.000Z</published>
    <updated>2026-11-16T05:26:58.199Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><p>Every company sitting on a data warehouse wants the same thing: let anyone ask questions in plain English and get reliable answers. OpenAI published how they built their internal data agent, and the open-source community responded fast. Here’s a quick summary of three projects pushing this forward.</p><span id="more"></span><h2 id="OpenAI’s-In-House-Data-Agent-6-Layers-of-Context"><a href="#OpenAI’s-In-House-Data-Agent-6-Layers-of-Context" class="headerlink" title="OpenAI’s In-House Data Agent: 6 Layers of Context"></a>OpenAI’s In-House Data Agent: 6 Layers of Context</h2><blockquote><p><strong>Source</strong>: <a target="_blank" rel="noopener" href="https://openai.com/index/inside-our-in-house-data-agent/">Inside OpenAI’s In-House Data Agent</a> by OpenAI, January 2026</p></blockquote><p>OpenAI built a bespoke data agent serving <strong>3,500+ internal users</strong> across <strong>600 petabytes</strong> and <strong>70k datasets</strong>. The core insight: <strong>context is everything</strong>. Without it, even strong models hallucinate column names and misinterpret business terminology.</p><p>The agent grounds itself in 6 layers of context:</p><table><thead><tr><th>Layer</th><th>What It Provides</th><th>How</th></tr></thead><tbody><tr><td><strong>Metadata Grounding</strong></td><td>Schema, columns, data types, table lineage</td><td>Warehouse metadata</td></tr><tr><td><strong>Query Inference</strong></td><td>Historical query patterns, common joins</td><td>Ingested past queries</td></tr><tr><td><strong>Curated Descriptions</strong></td><td>Business meaning, caveats, intent</td><td>Domain expert annotations</td></tr><tr><td><strong>Code-Level Definitions</strong></td><td>How tables are built, freshness, scope</td><td>Codex-powered code crawling</td></tr><tr><td><strong>Institutional Knowledge</strong></td><td>Launches, incidents, metric definitions</td><td>Slack, Docs, Notion (RAG)</td></tr><tr><td><strong>Memory</strong></td><td>Corrections, discovered filters, nuances</td><td>Self-learning from conversations</td></tr></tbody></table><p>Plus a <strong>runtime context</strong> layer for live schema inspection when existing info is stale.</p><h3 id="Key-Lessons"><a href="#Key-Lessons" class="headerlink" title="Key Lessons"></a>Key Lessons</h3><ul><li><strong>Tool consolidation matters</strong> - overlapping tools confuse agents. Restrict and consolidate.</li><li><strong>Less prescriptive prompting works better</strong> - rigid instructions pushed the agent down wrong paths. Higher-level guidance + model reasoning = more robust results.</li><li><strong>Code &gt; metadata</strong> - pipeline logic captures assumptions and business intent that never surface in SQL or table schemas. Crawling the codebase with Codex was a game-changer.</li><li><strong>Memory is non-negotiable</strong> - stateless agents repeat the same mistakes. The self-learning memory stores corrections, non-obvious filters, and constraints critical for correctness.</li></ul><h3 id="Evaluation"><a href="#Evaluation" class="headerlink" title="Evaluation"></a>Evaluation</h3><p>OpenAI uses curated question-answer pairs with “golden” SQL. Generated SQL is compared both syntactically and by result set, using an LLM grader that accounts for acceptable variation. These run continuously as canaries in production.</p><hr><h2 id="Dash-Open-Source-Self-Learning-Data-Agent"><a href="#Dash-Open-Source-Self-Learning-Data-Agent" class="headerlink" title="Dash: Open-Source Self-Learning Data Agent"></a>Dash: Open-Source Self-Learning Data Agent</h2><blockquote><p><strong>Source</strong>: <a target="_blank" rel="noopener" href="https://www.ashpreetbedi.com/articles/dash">Dash: Self-learning data agent</a> by Ashpreet Bedi<br><strong>GitHub</strong>: <a target="_blank" rel="noopener" href="https://github.com/agno-agi/dash">agno-agi/dash</a></p></blockquote><p>Dash is an open-source implementation directly inspired by OpenAI’s architecture. It implements the same 6-layer context approach:</p><table><thead><tr><th>Layer</th><th>Source</th></tr></thead><tbody><tr><td>Table Usage</td><td><code>knowledge/tables/*.json</code></td></tr><tr><td>Human Annotations</td><td><code>knowledge/business/*.json</code></td></tr><tr><td>Query Patterns</td><td><code>knowledge/queries/*.sql</code></td></tr><tr><td>Institutional Knowledge</td><td>MCP (optional)</td></tr><tr><td>Memory</td><td><code>LearningMachine</code></td></tr><tr><td>Runtime Context</td><td><code>introspect_schema</code> tool</td></tr></tbody></table><h3 id="Self-Learning-Loop"><a href="#Self-Learning-Loop" class="headerlink" title="Self-Learning Loop"></a>Self-Learning Loop</h3><p>Dash learns through two systems:</p><ul><li><strong>Static Knowledge</strong> - validated queries, business context, table schemas, metric definitions. Curated by your team, maintained alongside the agent.</li><li><strong>Continuous Learning</strong> - patterns discovered through trial and error. Column mappings, team focus areas, business term disambiguation. Implemented with just ~5 lines of code via <code>LearningMachine</code>.</li></ul><h3 id="Quick-Start"><a href="#Quick-Start" class="headerlink" title="Quick Start"></a>Quick Start</h3><figure class="highlight bash hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">git <span class="hljs-built_in">clone</span> https://github.com/agno-agi/dash &amp;&amp; <span class="hljs-built_in">cd</span> dash</span><br><span class="line"><span class="hljs-built_in">cp</span> example.env .<span class="hljs-built_in">env</span>  <span class="hljs-comment"># Add OPENAI_API_KEY</span></span><br><span class="line">docker compose up -d --build</span><br><span class="line">docker <span class="hljs-built_in">exec</span> -it dash-api python -m dash.scripts.load_data</span><br><span class="line">docker <span class="hljs-built_in">exec</span> -it dash-api python -m dash.scripts.load_knowledge</span><br></pre></td></tr></tbody></table></figure><p>Ships with F1 race data (1950-2020), a built-in UI via <a target="_blank" rel="noopener" href="https://os.agno.com/">Agno</a>, and an evaluation suite (string matching, LLM grading, golden SQL comparison). Built with the <a target="_blank" rel="noopener" href="https://github.com/agno-agi/agno">Agno</a> framework.</p><hr><h2 id="Nao-Open-Source-Analytics-Agent"><a href="#Nao-Open-Source-Analytics-Agent" class="headerlink" title="Nao: Open-Source Analytics Agent"></a>Nao: Open-Source Analytics Agent</h2><blockquote><p><strong>GitHub</strong>: <a target="_blank" rel="noopener" href="https://github.com/getnao/nao">getnao/nao</a> (Y Combinator backed)</p></blockquote><p>Nao takes a different approach - it’s a framework-first analytics agent focused on <strong>context building</strong> and <strong>deployment</strong>.</p><h3 id="Two-Step-Architecture"><a href="#Two-Step-Architecture" class="headerlink" title="Two-Step Architecture"></a>Two-Step Architecture</h3><ol><li><strong>nao-core CLI</strong> - build and manage agent context (data, metadata, modeling, rules, docs, tools, MCPs)</li><li><strong>nao chat UI</strong> - deploy a conversational interface for anyone to query</li></ol><h3 id="Key-Differentiators"><a href="#Key-Differentiators" class="headerlink" title="Key Differentiators"></a>Key Differentiators</h3><table><thead><tr><th>Feature</th><th>Detail</th></tr></thead><tbody><tr><td><strong>Data stack agnostic</strong></td><td>Works with any warehouse, any LLM</td></tr><tr><td><strong>File-system context</strong></td><td>Context organized as files - no limit on what you include</td></tr><tr><td><strong>Agent reliability testing</strong></td><td>Unit test agent performance before deploying</td></tr><tr><td><strong>Version tracking</strong></td><td>Version context and track performance over time</td></tr><tr><td><strong>User feedback loop</strong></td><td>Built-in thumbs up/down for continuous improvement</td></tr><tr><td><strong>Self-hosted</strong></td><td>Use your own LLM keys, full data privacy</td></tr></tbody></table><h3 id="Quick-Start-1"><a href="#Quick-Start-1" class="headerlink" title="Quick Start"></a>Quick Start</h3><figure class="highlight bash hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">pip install nao-core</span><br><span class="line">nao init        <span class="hljs-comment"># Interactive project setup</span></span><br><span class="line">nao debug       <span class="hljs-comment"># Verify setup</span></span><br><span class="line">nao <span class="hljs-built_in">sync</span>        <span class="hljs-comment"># Populate context from sources</span></span><br><span class="line">nao chat        <span class="hljs-comment"># Launch UI at localhost:5005</span></span><br></pre></td></tr></tbody></table></figure><p>Also available via Docker:</p><figure class="highlight bash hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">docker pull getnao/nao:latest</span><br><span class="line">docker run -d --name nao -p 5005:5005 \</span><br><span class="line">  -e BETTER_AUTH_URL=http://localhost:5005 \</span><br><span class="line">  -e FASTAPI_URL=http://127.0.0.1:8005 \</span><br><span class="line">  getnao/nao:latest</span><br></pre></td></tr></tbody></table></figure><p>Stack: Fastify + Drizzle + tRPC (backend), React + TanStack Query + shadcn (frontend).</p><hr><h2 id="Comparison"><a href="#Comparison" class="headerlink" title="Comparison"></a>Comparison</h2><table><thead><tr><th>Aspect</th><th>OpenAI Agent</th><th>Dash</th><th>Nao</th></tr></thead><tbody><tr><td><strong>Open Source</strong></td><td>No (internal)</td><td>Yes (Apache 2.0)</td><td>Yes (Apache 2.0)</td></tr><tr><td><strong>Context Layers</strong></td><td>6 layers</td><td>6 layers (same model)</td><td>File-system based</td></tr><tr><td><strong>Self-Learning</strong></td><td>Memory system</td><td>LearningMachine</td><td>User feedback loop</td></tr><tr><td><strong>Evaluation</strong></td><td>Golden SQL + LLM grader</td><td>String match + LLM grader + golden SQL</td><td>Unit testing framework</td></tr><tr><td><strong>LLM Support</strong></td><td>GPT-5 / Codex</td><td>OpenAI</td><td>Any LLM</td></tr><tr><td><strong>Data Stack</strong></td><td>OpenAI internal</td><td>Configurable</td><td>Agnostic</td></tr><tr><td><strong>UI</strong></td><td>Internal tool</td><td>Agno platform</td><td>Built-in chat</td></tr><tr><td><strong>Best For</strong></td><td>-</td><td>Teams wanting OpenAI’s architecture OSS</td><td>Teams wanting stack-agnostic framework</td></tr></tbody></table><h2 id="Takeaway"><a href="#Takeaway" class="headerlink" title="Takeaway"></a>Takeaway</h2><p>The pattern is clear: <strong>context-rich, self-learning data agents</strong> are becoming the standard. OpenAI proved the architecture at scale, Dash made it accessible, and Nao provides a framework-first alternative. The shared insight across all three: without deep, layered context, even the best models produce unreliable results.</p><h2 id="References"><a href="#References" class="headerlink" title="References"></a>References</h2><ul><li><a target="_blank" rel="noopener" href="https://openai.com/index/inside-our-in-house-data-agent/">Inside OpenAI’s In-House Data Agent</a> - OpenAI (Jan 2026)</li><li><a target="_blank" rel="noopener" href="https://www.ashpreetbedi.com/articles/dash">Dash: Self-learning data agent</a> - Ashpreet Bedi</li><li><a target="_blank" rel="noopener" href="https://github.com/agno-agi/dash">agno-agi/dash</a> - Dash GitHub repo</li><li><a target="_blank" rel="noopener" href="https://github.com/getnao/nao">getnao/nao</a> - Nao GitHub repo</li></ul></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;p&gt;Every company sitting on a data warehouse wants the same thing: let anyone ask questions in plain English and get reliable answers. OpenAI published how they built their internal data agent, and the open-source community responded fast. Here’s a quick summary of three projects pushing this forward.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="llm" scheme="https://vanducng.dev/tags/llm/"/>
    
    <category term="agentic-ai" scheme="https://vanducng.dev/tags/agentic-ai/"/>
    
    <category term="data-agent" scheme="https://vanducng.dev/tags/data-agent/"/>
    
    <category term="analytics" scheme="https://vanducng.dev/tags/analytics/"/>
    
    <category term="text-to-sql" scheme="https://vanducng.dev/tags/text-to-sql/"/>
    
  </entry>
  
  <entry>
    <title>Applied Agentic AI in Finance: A Complete Guide</title>
    <link href="https://vanducng.dev/2026/01/30/Applied-Agentic-AI-in-Finance-A-Complete-Guide/"/>
    <id>https://vanducng.dev/2026/01/30/Applied-Agentic-AI-in-Finance-A-Complete-Guide/</id>
    <published>2026-01-30T09:00:00.000Z</published>
    <updated>2026-11-16T05:26:58.192Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><p>This post brings together everything we’ve learned about applying agentic AI to financial services. From role-based prompting through multi-agent coordination, we’ve covered the complete spectrum of techniques for building intelligent financial systems. Here’s the comprehensive overview with production patterns.</p><span id="more"></span><h2 id="Series-Overview"><a href="#Series-Overview" class="headerlink" title="Series Overview"></a>Series Overview</h2><p>This 14-post series covers the complete journey from basic prompting techniques to sophisticated multi-agent trading systems:</p><pre class="mermaid">flowchart TD    subgraph Part1["Part 1: Financial Prompting"]        P1[Role-Based Prompting] --&gt; P2[Reasoning Chains]        P2 --&gt; P3[Prompt Pipelines]    end    subgraph Part2["Part 2: Agentic Workflows"]        W1[Workflow Modeling] --&gt; W2[Chaining &amp; Routing]        W2 --&gt; W3[Parallel Processing]        W3 --&gt; W4[Orchestration]    end    subgraph Part3["Part 3: Building Agents"]        A1[Tools &amp; Outputs] --&gt; A2[State &amp; Memory]        A2 --&gt; A3[Data Sources]        A3 --&gt; A4[RAG &amp; Evaluation]    end    subgraph Part4["Part 4: Multi-Agent Systems"]        M1[Architecture] --&gt; M2[Coordination]    end    Part1 --&gt; Part2    Part2 --&gt; Part3    Part3 --&gt; Part4    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    classDef pinkClass fill:#E74C3C,stroke:#333,stroke-width:2px,color:#fff    class Part1 blueClass    class Part2 orangeClass    class Part3 greenClass    class Part4 pinkClass</pre><h2 id="Part-1-Financial-Prompting-Fundamentals"><a href="#Part-1-Financial-Prompting-Fundamentals" class="headerlink" title="Part 1: Financial Prompting Fundamentals"></a>Part 1: Financial Prompting Fundamentals</h2><h3 id="Role-Based-Prompting-for-Financial-Analysts"><a href="#Role-Based-Prompting-for-Financial-Analysts" class="headerlink" title="Role-Based Prompting for Financial Analysts"></a>Role-Based Prompting for Financial Analysts</h3><p>The foundation of effective financial AI is <strong>persona-based prompting</strong>. By framing prompts with specific roles, we get more relevant and contextual outputs:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-comment"># Instead of generic prompts</span></span><br><span class="line"><span class="hljs-string">"Analyze Apple stock"</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-comment"># Use role-based prompting</span></span><br><span class="line"><span class="hljs-string">"""You are a senior equity research analyst at a top-tier investment bank</span></span><br><span class="line"><span class="hljs-string">with 15 years of experience in technology sector coverage.</span></span><br><span class="line"><span class="hljs-string"></span></span><br><span class="line"><span class="hljs-string">Provide a comprehensive analysis of Apple Inc. including:</span></span><br><span class="line"><span class="hljs-string">- Current market position and competitive landscape</span></span><br><span class="line"><span class="hljs-string">- Key financial metrics and valuation assessment</span></span><br><span class="line"><span class="hljs-string">- Risk factors and investment thesis"""</span></span><br></pre></td></tr></tbody></table></figure><p><strong>Key insight</strong>: The more specific the persona, the more focused the analysis. Define expertise level, specialization, and communication style.</p><h3 id="Reasoning-Chains-for-Financial-Decisions"><a href="#Reasoning-Chains-for-Financial-Decisions" class="headerlink" title="Reasoning Chains for Financial Decisions"></a>Reasoning Chains for Financial Decisions</h3><p><strong>Chain of Thought (CoT)</strong> transforms opaque decisions into auditable reasoning:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br></pre></td><td class="code"><pre><span class="line">prompt = <span class="hljs-string">"""</span></span><br><span class="line"><span class="hljs-string">Analyze whether to recommend buying NVIDIA stock.</span></span><br><span class="line"><span class="hljs-string"></span></span><br><span class="line"><span class="hljs-string">Think step by step:</span></span><br><span class="line"><span class="hljs-string">1. First, examine the current market conditions</span></span><br><span class="line"><span class="hljs-string">2. Then, analyze the company fundamentals</span></span><br><span class="line"><span class="hljs-string">3. Consider the risk factors</span></span><br><span class="line"><span class="hljs-string">4. Evaluate the valuation</span></span><br><span class="line"><span class="hljs-string">5. Finally, provide your recommendation with reasoning</span></span><br><span class="line"><span class="hljs-string"></span></span><br><span class="line"><span class="hljs-string">Show your complete thought process.</span></span><br><span class="line"><span class="hljs-string">"""</span></span><br></pre></td></tr></tbody></table></figure><p><strong>ReACT pattern</strong> (Reason-Act-Observe) enables dynamic decision-making by interleaving reasoning with tool use - essential for real-time trading decisions.</p><h3 id="Building-Financial-Prompt-Pipelines"><a href="#Building-Financial-Prompt-Pipelines" class="headerlink" title="Building Financial Prompt Pipelines"></a>Building Financial Prompt Pipelines</h3><p>Complex analyses require <strong>prompt chaining</strong> - breaking tasks into focused steps where each output feeds the next:</p><pre class="mermaid">flowchart LR    Data[Market Data] --&gt; Extract[Extract Metrics]    Extract --&gt; Analyze[Analyze Trends]    Analyze --&gt; Risk[Assess Risk]    Risk --&gt; Recommend[Generate Recommendation]</pre><p><strong>Feedback loops</strong> enable iterative refinement - the output of one step can trigger re-evaluation of earlier steps.</p><h2 id="Part-2-Agentic-Workflow-Patterns"><a href="#Part-2-Agentic-Workflow-Patterns" class="headerlink" title="Part 2: Agentic Workflow Patterns"></a>Part 2: Agentic Workflow Patterns</h2><h3 id="Modeling-Agentic-Workflows-for-Finance"><a href="#Modeling-Agentic-Workflows-for-Finance" class="headerlink" title="Modeling Agentic Workflows for Finance"></a>Modeling Agentic Workflows for Finance</h3><p>The progression from simple to complex:</p><table><thead><tr><th>Pattern</th><th>Use Case</th><th>Financial Example</th></tr></thead><tbody><tr><td><strong>Single Agent</strong></td><td>Focused tasks</td><td>Trade execution</td></tr><tr><td><strong>Prompt Chaining</strong></td><td>Sequential processing</td><td>Order validation pipeline</td></tr><tr><td><strong>Routing</strong></td><td>Conditional branching</td><td>Order type classification</td></tr><tr><td><strong>Parallelization</strong></td><td>Concurrent tasks</td><td>Multi-market analysis</td></tr><tr><td><strong>Orchestrator-Worker</strong></td><td>Dynamic coordination</td><td>Report generation</td></tr></tbody></table><h3 id="Prompt-Chaining-and-Routing-in-Trading-Systems"><a href="#Prompt-Chaining-and-Routing-in-Trading-Systems" class="headerlink" title="Prompt Chaining and Routing in Trading Systems"></a>Prompt Chaining and Routing in Trading Systems</h3><p><strong>Routing</strong> directs different inputs to appropriate handlers:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">TradingRouter</span>:</span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">route</span>(<span class="hljs-params">self, request: <span class="hljs-built_in">str</span></span>) -&gt; Handler:</span><br><span class="line">        category = <span class="variable language_">self</span>.classifier.classify(request)</span><br><span class="line">        <span class="hljs-keyword">return</span> {</span><br><span class="line">            <span class="hljs-string">"EQUITY_ORDER"</span>: EquityHandler(),</span><br><span class="line">            <span class="hljs-string">"OPTIONS_ORDER"</span>: OptionsHandler(),</span><br><span class="line">            <span class="hljs-string">"FOREX_ORDER"</span>: ForexHandler(),</span><br><span class="line">            <span class="hljs-string">"COMPLIANCE_CHECK"</span>: ComplianceHandler(),</span><br><span class="line">        }.get(category, DefaultHandler())</span><br></pre></td></tr></tbody></table></figure><p><strong>Validation gates</strong> between chain steps prevent error propagation - critical for financial accuracy.</p><h3 id="Parallel-Processing-and-Quality-Control"><a href="#Parallel-Processing-and-Quality-Control" class="headerlink" title="Parallel Processing and Quality Control"></a>Parallel Processing and Quality Control</h3><p><strong>Parallelization</strong> accelerates multi-faceted analysis:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">async</span> <span class="hljs-keyword">def</span> <span class="title function_">comprehensive_analysis</span>(<span class="hljs-params">symbol: <span class="hljs-built_in">str</span></span>) -&gt; <span class="hljs-built_in">dict</span>:</span><br><span class="line">    <span class="hljs-comment"># Run independent analyses concurrently</span></span><br><span class="line">    results = <span class="hljs-keyword">await</span> asyncio.gather(</span><br><span class="line">        fundamental_analysis(symbol),</span><br><span class="line">        technical_analysis(symbol),</span><br><span class="line">        sentiment_analysis(symbol),</span><br><span class="line">        risk_analysis(symbol)</span><br><span class="line">    )</span><br><span class="line">    <span class="hljs-keyword">return</span> synthesize(results)</span><br></pre></td></tr></tbody></table></figure><p><strong>Evaluator-Optimizer loops</strong> ensure quality through iterative refinement with clear criteria, actionable feedback, and defined stopping conditions.</p><h3 id="Orchestrating-Financial-Operations"><a href="#Orchestrating-Financial-Operations" class="headerlink" title="Orchestrating Financial Operations"></a>Orchestrating Financial Operations</h3><p>The <strong>orchestrator-worker pattern</strong> provides dynamic coordination:</p><pre class="mermaid">flowchart TD    T[Complex Task] --&gt; O[Orchestrator]    O --&gt; |Analyze &amp; Plan| P[Task Plan]    P --&gt; W1[Data Worker]    P --&gt; W2[Analysis Worker]    P --&gt; W3[Report Worker]    W1 --&gt; S[Synthesis]    W2 --&gt; S    W3 --&gt; S    S --&gt; O    O --&gt; F[Final Output]    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    class O blueClass</pre><p>Unlike fixed workflows, the orchestrator analyzes problems at runtime and adapts its approach.</p><h2 id="Part-3-Building-Financial-Agents"><a href="#Part-3-Building-Financial-Agents" class="headerlink" title="Part 3: Building Financial Agents"></a>Part 3: Building Financial Agents</h2><h3 id="Financial-Tools-and-Structured-Outputs"><a href="#Financial-Tools-and-Structured-Outputs" class="headerlink" title="Financial Tools and Structured Outputs"></a>Financial Tools and Structured Outputs</h3><p><strong>Pydantic models</strong> ensure type-safe financial data:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">from</span> pydantic <span class="hljs-keyword">import</span> BaseModel, Field, field_validator</span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">TradeOrder</span>(<span class="title class_ inherited__">BaseModel</span>):</span><br><span class="line">    symbol: <span class="hljs-built_in">str</span> = Field(min_length=<span class="hljs-number">1</span>, max_length=<span class="hljs-number">10</span>)</span><br><span class="line">    quantity: <span class="hljs-built_in">int</span> = Field(gt=<span class="hljs-number">0</span>, le=<span class="hljs-number">1000000</span>)</span><br><span class="line">    order_type: <span class="hljs-type">Literal</span>[<span class="hljs-string">"market"</span>, <span class="hljs-string">"limit"</span>, <span class="hljs-string">"stop"</span>]</span><br><span class="line">    price: <span class="hljs-type">Optional</span>[<span class="hljs-built_in">float</span>] = Field(gt=<span class="hljs-number">0</span>)</span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">    @field_validator(<span class="hljs-params"><span class="hljs-string">'price'</span></span>)</span></span><br><span class="line"><span class="hljs-meta">    @classmethod</span></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">limit_orders_need_price</span>(<span class="hljs-params">cls, v, info</span>):</span><br><span class="line">        <span class="hljs-keyword">if</span> info.data.get(<span class="hljs-string">'order_type'</span>) == <span class="hljs-string">'limit'</span> <span class="hljs-keyword">and</span> v <span class="hljs-keyword">is</span> <span class="hljs-literal">None</span>:</span><br><span class="line">            <span class="hljs-keyword">raise</span> ValueError(<span class="hljs-string">'Limit orders require a price'</span>)</span><br><span class="line">        <span class="hljs-keyword">return</span> v</span><br></pre></td></tr></tbody></table></figure><p><strong>Function calling</strong> enables agents to interact with financial systems safely with validated inputs and outputs.</p><h3 id="State-and-Memory-for-Trading-Agents"><a href="#State-and-Memory-for-Trading-Agents" class="headerlink" title="State and Memory for Trading Agents"></a>State and Memory for Trading Agents</h3><p>State management requires three levels:</p><table><thead><tr><th>Level</th><th>Scope</th><th>Example</th></tr></thead><tbody><tr><td><strong>Local</strong></td><td>Single agent</td><td>Current trade context</td></tr><tr><td><strong>Session</strong></td><td>Conversation</td><td>Trading session history</td></tr><tr><td><strong>Persistent</strong></td><td>Cross-session</td><td>Account balances, portfolio</td></tr></tbody></table><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">TradingState</span>(<span class="title class_ inherited__">BaseModel</span>):</span><br><span class="line">    account_id: <span class="hljs-built_in">str</span></span><br><span class="line">    cash_balance: <span class="hljs-built_in">float</span></span><br><span class="line">    positions: <span class="hljs-type">Dict</span>[<span class="hljs-built_in">str</span>, Position]</span><br><span class="line">    pending_orders: <span class="hljs-type">List</span>[Order]</span><br><span class="line">    session_trades: <span class="hljs-type">List</span>[Trade]</span><br></pre></td></tr></tbody></table></figure><h3 id="Connecting-Agents-to-Financial-Data-Sources"><a href="#Connecting-Agents-to-Financial-Data-Sources" class="headerlink" title="Connecting Agents to Financial Data Sources"></a>Connecting Agents to Financial Data Sources</h3><p>Agents connect to external systems through:</p><ul><li><strong>Market Data APIs</strong>: Real-time prices, historical data</li><li><strong>News &amp; Sentiment</strong>: Web search, RSS feeds</li><li><strong>Databases</strong>: Transaction history, customer data</li><li><strong>Document Stores</strong>: Regulatory filings, contracts</li></ul><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-meta">@agent.tool</span></span><br><span class="line"><span class="hljs-keyword">def</span> <span class="title function_">get_stock_price</span>(<span class="hljs-params">ctx: RunContext, symbol: <span class="hljs-built_in">str</span></span>) -&gt; <span class="hljs-built_in">str</span>:</span><br><span class="line">    <span class="hljs-string">"""Get current stock price from market data API"""</span></span><br><span class="line">    response = requests.get(</span><br><span class="line">        <span class="hljs-string">f"<span class="hljs-subst">{API_URL}</span>/quote/<span class="hljs-subst">{symbol}</span>"</span>,</span><br><span class="line">        headers={<span class="hljs-string">"Authorization"</span>: <span class="hljs-string">f"Bearer <span class="hljs-subst">{ctx.deps.api_key}</span>"</span>}</span><br><span class="line">    )</span><br><span class="line">    data = response.json()</span><br><span class="line">    <span class="hljs-keyword">return</span> <span class="hljs-string">f"<span class="hljs-subst">{symbol}</span>: $<span class="hljs-subst">{data[<span class="hljs-string">'price'</span>]:<span class="hljs-number">.2</span>f}</span> (<span class="hljs-subst">{data[<span class="hljs-string">'change'</span>]:+<span class="hljs-number">.2</span>%}</span>)"</span></span><br></pre></td></tr></tbody></table></figure><h3 id="RAG-and-Evaluation-for-Financial-Agents"><a href="#RAG-and-Evaluation-for-Financial-Agents" class="headerlink" title="RAG and Evaluation for Financial Agents"></a>RAG and Evaluation for Financial Agents</h3><p><strong>Agentic RAG</strong> with retrieve-reason-retry loops:</p><pre class="mermaid">flowchart LR    Q[Query] --&gt; R[Retrieve Documents]    R --&gt; G[Generate Answer]    G --&gt; E{Sufficient?}    E --&gt;|Yes| A[Final Answer]    E --&gt;|No| I[Improve Query]    I --&gt; R</pre><p><strong>Long-term memory</strong> types:</p><ul><li><strong>Semantic</strong>: Facts and knowledge (market rules, company data)</li><li><strong>Episodic</strong>: Experiences (past trades, customer interactions)</li><li><strong>Procedural</strong>: Learned behaviors (trading patterns)</li></ul><p><strong>Agent evaluation</strong> across four dimensions:</p><ol><li>Task completion metrics</li><li>Quality control metrics</li><li>Tool interaction metrics</li><li>System metrics (latency, cost)</li></ol><h2 id="Part-4-Multi-Agent-Financial-Systems"><a href="#Part-4-Multi-Agent-Financial-Systems" class="headerlink" title="Part 4: Multi-Agent Financial Systems"></a>Part 4: Multi-Agent Financial Systems</h2><h3 id="Multi-Agent-Architecture-for-Trading"><a href="#Multi-Agent-Architecture-for-Trading" class="headerlink" title="Multi-Agent Architecture for Trading"></a>Multi-Agent Architecture for Trading</h3><p><strong>The specialization principle</strong>: Each agent should focus on a single domain:</p><pre class="mermaid">flowchart TD    subgraph Agents["Hedge Fund Agent Architecture"]        MA[Market Analyst] --&gt; |Market Data| SC[Shared Context]        SA[Strategy Agent] --&gt; |Recommendations| SC        RM[Risk Manager] --&gt; |Risk Assessment| SC        RA[Regulatory Agent] --&gt; |Compliance| SC        SC --&gt; SUP[Supervisor Agent]        SUP --&gt; |Final Decision| OUT[Trade Execution]    end    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    class SUP blueClass    class SC orangeClass</pre><p><strong>Shared context</strong> enables inter-agent communication without tight coupling.</p><p><strong>Orchestration patterns</strong>:</p><ul><li><strong>Sequential</strong>: Fixed order execution</li><li><strong>Parallel</strong>: Concurrent independent tasks</li><li><strong>Conditional</strong>: Dynamic flow based on results</li></ul><h3 id="Coordinated-Trading-Systems"><a href="#Coordinated-Trading-Systems" class="headerlink" title="Coordinated Trading Systems"></a>Coordinated Trading Systems</h3><p><strong>State coordination strategies</strong>:</p><ol><li><strong>Database as source of truth</strong>: Leverage locking and transactions</li><li><strong>State snapshots</strong>: Version hashing for conflict detection</li><li><strong>Optimistic concurrency</strong>: Assume conflicts are rare, check before commit</li></ol><p><strong>Conflict resolution</strong>:</p><ul><li>Predefined rules for simple conflicts</li><li>Rollback &amp; retry for concurrent modifications</li><li>Human escalation for complex situations</li></ul><p><strong>Multi-Agent RAG</strong> for comprehensive analysis:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">MultiAgentRAGSystem</span>:</span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">__init__</span>(<span class="hljs-params">self</span>):</span><br><span class="line">        <span class="variable language_">self</span>.market_agent = MarketDataAgent()</span><br><span class="line">        <span class="variable language_">self</span>.fundamental_agent = FundamentalDataAgent()</span><br><span class="line">        <span class="variable language_">self</span>.news_agent = NewsSentimentAgent()</span><br><span class="line">        <span class="variable language_">self</span>.risk_agent = RiskDataAgent()</span><br><span class="line">        <span class="variable language_">self</span>.coordinator = RetrievalCoordinator()</span><br><span class="line">        <span class="variable language_">self</span>.synthesizer = SynthesisAgent()</span><br><span class="line">        <span class="variable language_">self</span>.gap_analyzer = GapAnalysisAgent()</span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">query</span>(<span class="hljs-params">self, question: <span class="hljs-built_in">str</span>, symbol: <span class="hljs-built_in">str</span></span>) -&gt; Answer:</span><br><span class="line">        <span class="hljs-comment"># Coordinate -&gt; Retrieve -&gt; Synthesize -&gt; Gap Analysis</span></span><br><span class="line">        decision = <span class="variable language_">self</span>.coordinator.coordinate(question, symbol)</span><br><span class="line">        results = <span class="variable language_">self</span>.execute_retrievals(decision.required_agents)</span><br><span class="line">        synthesis = <span class="variable language_">self</span>.synthesizer.synthesize(results)</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">if</span> <span class="variable language_">self</span>.gap_analyzer.has_gaps(synthesis):</span><br><span class="line">            <span class="hljs-keyword">return</span> <span class="variable language_">self</span>.query(<span class="variable language_">self</span>.gap_analyzer.refined_query, symbol)</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">return</span> synthesis</span><br></pre></td></tr></tbody></table></figure><h2 id="Production-Patterns"><a href="#Production-Patterns" class="headerlink" title="Production Patterns"></a>Production Patterns</h2><h3 id="Error-Handling-and-Fallbacks"><a href="#Error-Handling-and-Fallbacks" class="headerlink" title="Error Handling and Fallbacks"></a>Error Handling and Fallbacks</h3><p>Every agent operation needs fallback strategies:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">def</span> <span class="title function_">run_agent_with_fallback</span>(<span class="hljs-params">agent, input_data: <span class="hljs-built_in">dict</span></span>):</span><br><span class="line">    <span class="hljs-keyword">try</span>:</span><br><span class="line">        <span class="hljs-keyword">return</span> agent.run_sync(input_data)</span><br><span class="line">    <span class="hljs-keyword">except</span> TimeoutError:</span><br><span class="line">        <span class="hljs-keyword">return</span> backup_agent.run_sync(input_data)</span><br><span class="line">    <span class="hljs-keyword">except</span> Exception:</span><br><span class="line">        <span class="hljs-keyword">return</span> {</span><br><span class="line">            <span class="hljs-string">"status"</span>: <span class="hljs-string">"MANUAL_REVIEW_REQUIRED"</span>,</span><br><span class="line">            <span class="hljs-string">"reason"</span>: <span class="hljs-string">"Automated processing failed"</span>,</span><br><span class="line">            <span class="hljs-string">"original_input"</span>: input_data</span><br><span class="line">        }</span><br></pre></td></tr></tbody></table></figure><h3 id="Audit-Trails-for-Compliance"><a href="#Audit-Trails-for-Compliance" class="headerlink" title="Audit Trails for Compliance"></a>Audit Trails for Compliance</h3><p>Financial systems require comprehensive logging:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-meta">@dataclass</span></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">AuditEntry</span>:</span><br><span class="line">    timestamp: datetime</span><br><span class="line">    operation: <span class="hljs-built_in">str</span></span><br><span class="line">    agent_id: <span class="hljs-built_in">str</span></span><br><span class="line">    input_hash: <span class="hljs-built_in">str</span></span><br><span class="line">    output_hash: <span class="hljs-built_in">str</span></span><br><span class="line">    duration_ms: <span class="hljs-built_in">int</span></span><br><span class="line">    decision: <span class="hljs-built_in">str</span></span><br><span class="line">    reasoning: <span class="hljs-built_in">str</span></span><br></pre></td></tr></tbody></table></figure><h3 id="Cost-Optimization"><a href="#Cost-Optimization" class="headerlink" title="Cost Optimization"></a>Cost Optimization</h3><p>Balance capability with cost:</p><table><thead><tr><th>Use Case</th><th>Recommended Model</th><th>Reason</th></tr></thead><tbody><tr><td>Simple classification</td><td>GPT-3.5 / Haiku</td><td>Fast, cheap</td></tr><tr><td>Complex reasoning</td><td>GPT-4 / Sonnet</td><td>Better accuracy</td></tr><tr><td>Code generation</td><td>Opus</td><td>Superior quality</td></tr><tr><td>High-volume processing</td><td>Smaller models</td><td>Cost control</td></tr></tbody></table><h2 id="Architecture-Summary"><a href="#Architecture-Summary" class="headerlink" title="Architecture Summary"></a>Architecture Summary</h2><p>The complete financial AI system architecture:</p><pre class="mermaid">flowchart TD    subgraph Interface["User Interface"]        UI[Trading Terminal]    end    subgraph Agents["Agent Layer"]        R[Router] --&gt; |Classify| A1[Trading Agent]        R --&gt; |Classify| A2[Analysis Agent]        R --&gt; |Classify| A3[Compliance Agent]    end    subgraph Tools["Tool Layer"]        T1[Market Data API]        T2[Order Execution]        T3[Document Search]        T4[Risk Calculator]    end    subgraph Memory["Memory Layer"]        M1[(Short-term)]        M2[(Long-term)]        M3[(Vector Store)]    end    subgraph Orchestration["Orchestration Layer"]        O[Supervisor] --&gt; |Coordinate| Agents        O --&gt; |State| SC[State Coordinator]    end    UI --&gt; R    A1 --&gt; Tools    A2 --&gt; Tools    A3 --&gt; Tools    Agents --&gt; Memory    SC --&gt; Memory    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    class Orchestration blueClass    class Agents orangeClass    class Memory greenClass</pre><h2 id="Complete-Series-Index"><a href="#Complete-Series-Index" class="headerlink" title="Complete Series Index"></a>Complete Series Index</h2><h3 id="Part-1-Financial-Prompting"><a href="#Part-1-Financial-Prompting" class="headerlink" title="Part 1: Financial Prompting"></a>Part 1: Financial Prompting</h3><ol><li><a href="/2025/12/22/Role-Based-Prompting-for-Financial-Analysts/">Role-Based Prompting for Financial Analysts</a></li><li><a href="/2025/12/25/Reasoning-Chains-for-Financial-Decisions/">Reasoning Chains for Financial Decisions</a></li><li><a href="/2025/12/28/Building-Financial-Prompt-Pipelines/">Building Financial Prompt Pipelines</a></li></ol><h3 id="Part-2-Agentic-Workflows"><a href="#Part-2-Agentic-Workflows" class="headerlink" title="Part 2: Agentic Workflows"></a>Part 2: Agentic Workflows</h3><ol start="4"><li><a href="/2025/12/31/Modeling-Agentic-Workflows-for-Finance/">Modeling Agentic Workflows for Finance</a></li><li><a href="/2026/01/03/Prompt-Chaining-and-Routing-in-Trading-Systems/">Prompt Chaining and Routing in Trading Systems</a></li><li><a href="/2026/01/06/Parallel-Processing-and-Quality-Control-in-Finance/">Parallel Processing and Quality Control in Finance</a></li><li><a href="/2026/01/09/Orchestrating-Financial-Operations/">Orchestrating Financial Operations</a></li></ol><h3 id="Part-3-Building-Agents"><a href="#Part-3-Building-Agents" class="headerlink" title="Part 3: Building Agents"></a>Part 3: Building Agents</h3><ol start="8"><li><a href="/2026/01/12/Financial-Tools-and-Structured-Outputs/">Financial Tools and Structured Outputs</a></li><li><a href="/2026/01/15/State-and-Memory-for-Trading-Agents/">State and Memory for Trading Agents</a></li><li><a href="/2026/01/18/Connecting-Agents-to-Financial-Data-Sources/">Connecting Agents to Financial Data Sources</a></li><li><a href="/2026/01/21/RAG-and-Evaluation-for-Financial-Agents/">RAG and Evaluation for Financial Agents</a></li></ol><h3 id="Part-4-Multi-Agent-Systems"><a href="#Part-4-Multi-Agent-Systems" class="headerlink" title="Part 4: Multi-Agent Systems"></a>Part 4: Multi-Agent Systems</h3><ol start="12"><li><a href="/2026/01/24/Multi-Agent-Architecture-for-Trading/">Multi-Agent Architecture for Trading</a></li><li><a href="/2026/01/27/Coordinated-Trading-Systems/">Coordinated Trading Systems</a></li><li>Applied Agentic AI in Finance: A Complete Guide (this post)</li></ol><h2 id="Key-Takeaways"><a href="#Key-Takeaways" class="headerlink" title="Key Takeaways"></a>Key Takeaways</h2><ol><li><p><strong>Start with personas</strong>: Role-based prompting provides context that improves output quality</p></li><li><p><strong>Make reasoning visible</strong>: Chain of Thought creates auditable decision trails essential for compliance</p></li><li><p><strong>Validate between steps</strong>: Prompt chains with validation gates prevent error propagation</p></li><li><p><strong>Choose the right pattern</strong>: Match workflow patterns to task complexity (routing, parallelization, orchestration)</p></li><li><p><strong>Use structured outputs</strong>: Pydantic models ensure type-safe data handling</p></li><li><p><strong>Manage state carefully</strong>: Distinguish ephemeral from persistent state; use interchangeable managers</p></li><li><p><strong>Connect safely</strong>: Tools with validation provide controlled access to external systems</p></li><li><p><strong>Specialize agents</strong>: Each agent should focus on a single domain for best results</p></li><li><p><strong>Coordinate state</strong>: Use snapshots, version hashing, and conflict resolution for multi-agent consistency</p></li><li><p><strong>Always have fallbacks</strong>: Production systems need graceful degradation when agents fail</p></li><li><p><strong>Audit everything</strong>: Financial systems require comprehensive logging for compliance</p></li><li><p><strong>Balance cost and capability</strong>: Use appropriate model sizes for different tasks</p></li></ol><hr><p><em>This completes the Applied Agentic AI for Finance series. For foundational concepts, see the <a href="/2025/12/18/Building-Intelligent-AI-Systems-Agentic-AI-Series-Overview/">Building Intelligent AI Systems</a> series overview.</em></p></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;p&gt;This post brings together everything we’ve learned about applying agentic AI to financial services. From role-based prompting through multi-agent coordination, we’ve covered the complete spectrum of techniques for building intelligent financial systems. Here’s the comprehensive overview with production patterns.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="llm" scheme="https://vanducng.dev/tags/llm/"/>
    
    <category term="python" scheme="https://vanducng.dev/tags/python/"/>
    
    <category term="finance" scheme="https://vanducng.dev/tags/finance/"/>
    
    <category term="multi-agent" scheme="https://vanducng.dev/tags/multi-agent/"/>
    
  </entry>
  
  <entry>
    <title>Coordinated Trading Systems</title>
    <link href="https://vanducng.dev/2026/01/27/Coordinated-Trading-Systems/"/>
    <id>https://vanducng.dev/2026/01/27/Coordinated-Trading-Systems/</id>
    <published>2026-01-27T09:00:00.000Z</published>
    <updated>2026-11-16T05:26:58.199Z</updated>
    
    <content type="html"><![CDATA[<html><head></head><body><p>When multiple agents operate simultaneously on trading operations, they must share a consistent understanding of the world state. This post explores the coordination patterns that make multi-agent trading systems reliable: persistent state management, conflict resolution, and multi-agent RAG for comprehensive analysis.</p><span id="more"></span><h2 id="State-Management-in-Multi-Agent-Systems"><a href="#State-Management-in-Multi-Agent-Systems" class="headerlink" title="State Management in Multi-Agent Systems"></a>State Management in Multi-Agent Systems</h2><p>Imagine a customer service agent who has amnesia - every time you talk to them, you have to start the conversation from scratch. A single-turn agent without memory is like that. To handle complex, multi-step tasks, our agents need a memory - what we call <strong>state</strong>.</p><p>State management is the process of recording what has happened, what the current status is, and what information has been gathered, so that any agent on the team can get up to speed.</p><h3 id="Ephemeral-vs-Persistent-State"><a href="#Ephemeral-vs-Persistent-State" class="headerlink" title="Ephemeral vs Persistent State"></a>Ephemeral vs Persistent State</h3><pre class="mermaid">flowchart TB    subgraph Ephemeral["Ephemeral State"]        direction LR        E1[Chat History] --&gt; E2[Session Context]        E2 --&gt; E3[Lost on Restart]    end    subgraph Persistent["Persistent State"]        direction LR        P1[Database/Files] --&gt; P2[Survives Restarts]        P2 --&gt; P3[Shared Access]    end    classDef pinkClass fill:#E74C3C,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    class Ephemeral pinkClass    class Persistent greenClass</pre><table><thead><tr><th>Type</th><th>Duration</th><th>Use Case</th></tr></thead><tbody><tr><td><strong>Ephemeral</strong></td><td>Single session</td><td>Chat history, temporary calculations</td></tr><tr><td><strong>Persistent</strong></td><td>Cross-session</td><td>Account balances, portfolio holdings, transaction history</td></tr></tbody></table><h2 id="Persistent-State-with-Interchangeable-Managers"><a href="#Persistent-State-with-Interchangeable-Managers" class="headerlink" title="Persistent State with Interchangeable Managers"></a>Persistent State with Interchangeable Managers</h2><p>For trading systems, persistent state is essential. The pattern that makes this maintainable is an <strong>interchangeable state manager</strong> that abstracts storage details:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br><span class="line">48</span><br><span class="line">49</span><br><span class="line">50</span><br><span class="line">51</span><br><span class="line">52</span><br><span class="line">53</span><br><span class="line">54</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">from</span> abc <span class="hljs-keyword">import</span> ABC, abstractmethod</span><br><span class="line"><span class="hljs-keyword">from</span> typing <span class="hljs-keyword">import</span> <span class="hljs-type">Dict</span>, <span class="hljs-type">Tuple</span></span><br><span class="line"><span class="hljs-keyword">import</span> csv</span><br><span class="line"><span class="hljs-keyword">from</span> datetime <span class="hljs-keyword">import</span> datetime</span><br><span class="line"><span class="hljs-keyword">from</span> pathlib <span class="hljs-keyword">import</span> Path</span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">BaseStateManager</span>(<span class="title class_ inherited__">ABC</span>):</span><br><span class="line">    <span class="hljs-string">"""Abstract base for state management"""</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">    @abstractmethod</span></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">get_synchronized_state</span>(<span class="hljs-params">self</span>) -&gt; <span class="hljs-type">Tuple</span>[<span class="hljs-built_in">float</span>, <span class="hljs-type">Dict</span>[<span class="hljs-built_in">str</span>, <span class="hljs-built_in">int</span>]]:</span><br><span class="line">        <span class="hljs-string">"""Get current cash balance and portfolio"""</span></span><br><span class="line">        <span class="hljs-keyword">pass</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">    @abstractmethod</span></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">update_account</span>(<span class="hljs-params">self, cash_balance: <span class="hljs-built_in">float</span></span>) -&gt; <span class="hljs-literal">None</span>:</span><br><span class="line">        <span class="hljs-string">"""Update cash balance"""</span></span><br><span class="line">        <span class="hljs-keyword">pass</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">    @abstractmethod</span></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">update_portfolio</span>(<span class="hljs-params">self, portfolio: <span class="hljs-type">Dict</span>[<span class="hljs-built_in">str</span>, <span class="hljs-built_in">int</span>]</span>) -&gt; <span class="hljs-literal">None</span>:</span><br><span class="line">        <span class="hljs-string">"""Update portfolio holdings"""</span></span><br><span class="line">        <span class="hljs-keyword">pass</span></span><br><span class="line"></span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">CSVStateManager</span>(<span class="title class_ inherited__">BaseStateManager</span>):</span><br><span class="line">    <span class="hljs-string">"""CSV-based implementation - easily swappable with SQL, Parquet, etc."""</span></span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">__init__</span>(<span class="hljs-params">self, data_dir: <span class="hljs-built_in">str</span></span>):</span><br><span class="line">        <span class="variable language_">self</span>.data_dir = Path(data_dir)</span><br><span class="line">        <span class="variable language_">self</span>._initialize_csv_files()</span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">_initialize_csv_files</span>(<span class="hljs-params">self</span>):</span><br><span class="line">        <span class="hljs-string">"""Initialize CSV files with headers"""</span></span><br><span class="line">        <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> (<span class="variable language_">self</span>.data_dir / <span class="hljs-string">"account.csv"</span>).exists():</span><br><span class="line">            <span class="hljs-keyword">with</span> <span class="hljs-built_in">open</span>(<span class="variable language_">self</span>.data_dir / <span class="hljs-string">"account.csv"</span>, <span class="hljs-string">'w'</span>, newline=<span class="hljs-string">''</span>) <span class="hljs-keyword">as</span> f:</span><br><span class="line">                writer = csv.writer(f)</span><br><span class="line">                writer.writerow([<span class="hljs-string">'cash_balance'</span>, <span class="hljs-string">'total_value'</span>, <span class="hljs-string">'last_updated'</span>])</span><br><span class="line">                writer.writerow([<span class="hljs-string">'100000.00'</span>, <span class="hljs-string">'100000.00'</span>, datetime.now().isoformat()])</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> (<span class="variable language_">self</span>.data_dir / <span class="hljs-string">"portfolio.csv"</span>).exists():</span><br><span class="line">            <span class="hljs-keyword">with</span> <span class="hljs-built_in">open</span>(<span class="variable language_">self</span>.data_dir / <span class="hljs-string">"portfolio.csv"</span>, <span class="hljs-string">'w'</span>, newline=<span class="hljs-string">''</span>) <span class="hljs-keyword">as</span> f:</span><br><span class="line">                writer = csv.writer(f)</span><br><span class="line">                writer.writerow([<span class="hljs-string">'symbol'</span>, <span class="hljs-string">'quantity'</span>, <span class="hljs-string">'avg_cost'</span>])</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> (<span class="variable language_">self</span>.data_dir / <span class="hljs-string">"transactions.csv"</span>).exists():</span><br><span class="line">            <span class="hljs-keyword">with</span> <span class="hljs-built_in">open</span>(<span class="variable language_">self</span>.data_dir / <span class="hljs-string">"transactions.csv"</span>, <span class="hljs-string">'w'</span>, newline=<span class="hljs-string">''</span>) <span class="hljs-keyword">as</span> f:</span><br><span class="line">                writer = csv.writer(f)</span><br><span class="line">                writer.writerow([<span class="hljs-string">'transaction_id'</span>, <span class="hljs-string">'timestamp'</span>, <span class="hljs-string">'type'</span>, <span class="hljs-string">'symbol'</span>,</span><br><span class="line">                               <span class="hljs-string">'quantity'</span>, <span class="hljs-string">'price'</span>, <span class="hljs-string">'total'</span>, <span class="hljs-string">'status'</span>])</span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">get_synchronized_state</span>(<span class="hljs-params">self</span>) -&gt; <span class="hljs-type">Tuple</span>[<span class="hljs-built_in">float</span>, <span class="hljs-type">Dict</span>[<span class="hljs-built_in">str</span>, <span class="hljs-built_in">int</span>]]:</span><br><span class="line">        <span class="hljs-comment"># This is where locking mechanisms would be implemented</span></span><br><span class="line">        <span class="hljs-keyword">return</span> <span class="variable language_">self</span>._read_cash_balance(), <span class="variable language_">self</span>._read_portfolio()</span><br></pre></td></tr></tbody></table></figure><p>The key insight: agents don’t care what type of state manager they use. You could swap <code>CSVStateManager</code> for <code>SQLStateManager</code> without changing agent code.</p><h2 id="Agent-Separation-Decision-vs-Execution"><a href="#Agent-Separation-Decision-vs-Execution" class="headerlink" title="Agent Separation: Decision vs Execution"></a>Agent Separation: Decision vs Execution</h2><p>A robust trading system separates decision-making from execution. This separation provides:</p><ul><li><strong>Clear responsibilities</strong>: One decides, one executes</li><li><strong>Different characteristics</strong>: Decision is non-deterministic (LLM reasoning), execution is deterministic (follows rules)</li><li><strong>Testable components</strong>: Each can be tested independently</li></ul><pre class="mermaid">flowchart LR    subgraph Decision["Trade Decision Agent"]        D1[Read Portfolio] --&gt; D2[Analyze State]        D2 --&gt; D3[Make Decision]    end    subgraph Execution["Execution Agent"]        E1[Verify Funds] --&gt; E2[Execute Trade]        E2 --&gt; E3[Update State]        E3 --&gt; E4[Record Transaction]    end    D3 --&gt; |Trade Request| E1    E4 --&gt; |Audit Trail| DB[(Shared State)]    D1 --&gt; |Read| DB    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    class Decision blueClass    class Execution orangeClass</pre><h3 id="Decision-Agent-Implementation"><a href="#Decision-Agent-Implementation" class="headerlink" title="Decision Agent Implementation"></a>Decision Agent Implementation</h3><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br><span class="line">48</span><br><span class="line">49</span><br><span class="line">50</span><br><span class="line">51</span><br><span class="line">52</span><br><span class="line">53</span><br><span class="line">54</span><br><span class="line">55</span><br><span class="line">56</span><br><span class="line">57</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">from</span> pydantic <span class="hljs-keyword">import</span> BaseModel</span><br><span class="line"><span class="hljs-keyword">from</span> pydantic_ai <span class="hljs-keyword">import</span> Agent, RunContext</span><br><span class="line"><span class="hljs-keyword">from</span> dataclasses <span class="hljs-keyword">import</span> dataclass</span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">@dataclass</span></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">AgentContext</span>:</span><br><span class="line">    data_dir: <span class="hljs-built_in">str</span></span><br><span class="line">    state_manager: BaseStateManager</span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">TradeDecision</span>(<span class="title class_ inherited__">BaseModel</span>):</span><br><span class="line">    should_trade: <span class="hljs-built_in">bool</span></span><br><span class="line">    transaction_type: <span class="hljs-built_in">str</span>  <span class="hljs-comment"># BUY or SELL</span></span><br><span class="line">    symbol: <span class="hljs-built_in">str</span></span><br><span class="line">    quantity: <span class="hljs-built_in">int</span></span><br><span class="line">    estimated_price: <span class="hljs-built_in">float</span></span><br><span class="line">    reasoning: <span class="hljs-built_in">str</span></span><br><span class="line">    confidence: <span class="hljs-built_in">float</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-comment"># Create decision agent</span></span><br><span class="line">decision_agent = Agent(</span><br><span class="line">    model=<span class="hljs-string">"openai:gpt-4"</span>,</span><br><span class="line">    deps_type=AgentContext,</span><br><span class="line">    output_type=TradeDecision</span><br><span class="line">)</span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">@decision_agent.system_prompt</span></span><br><span class="line"><span class="hljs-keyword">def</span> <span class="title function_">decision_prompt</span>(<span class="hljs-params">ctx: RunContext[AgentContext]</span>) -&gt; <span class="hljs-built_in">str</span>:</span><br><span class="line">    <span class="hljs-keyword">return</span> <span class="hljs-string">"""You are a Trade Decision Agent. Your role:</span></span><br><span class="line"><span class="hljs-string">    1. Analyze portfolio state from storage</span></span><br><span class="line"><span class="hljs-string">    2. Read account balance</span></span><br><span class="line"><span class="hljs-string">    3. Analyze current holdings</span></span><br><span class="line"><span class="hljs-string">    4. Decide if trade should be made</span></span><br><span class="line"><span class="hljs-string">    5. Provide clear reasoning</span></span><br><span class="line"><span class="hljs-string"></span></span><br><span class="line"><span class="hljs-string">    You have READ-ONLY access to state."""</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">@decision_agent.tool</span></span><br><span class="line"><span class="hljs-keyword">def</span> <span class="title function_">read_account_balance</span>(<span class="hljs-params">ctx: RunContext[AgentContext]</span>) -&gt; <span class="hljs-built_in">str</span>:</span><br><span class="line">    <span class="hljs-string">"""Read current cash balance"""</span></span><br><span class="line">    cash, _ = ctx.deps.state_manager.get_synchronized_state()</span><br><span class="line">    <span class="hljs-keyword">return</span> <span class="hljs-string">f"Current cash balance: $<span class="hljs-subst">{cash:,<span class="hljs-number">.2</span>f}</span>"</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">@decision_agent.tool</span></span><br><span class="line"><span class="hljs-keyword">def</span> <span class="title function_">read_portfolio</span>(<span class="hljs-params">ctx: RunContext[AgentContext]</span>) -&gt; <span class="hljs-built_in">str</span>:</span><br><span class="line">    <span class="hljs-string">"""Read current portfolio holdings"""</span></span><br><span class="line">    _, portfolio = ctx.deps.state_manager.get_synchronized_state()</span><br><span class="line">    <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> portfolio:</span><br><span class="line">        <span class="hljs-keyword">return</span> <span class="hljs-string">"Portfolio: Empty (no holdings)"</span></span><br><span class="line">    holdings = [<span class="hljs-string">f"<span class="hljs-subst">{sym}</span>: <span class="hljs-subst">{qty}</span> shares"</span> <span class="hljs-keyword">for</span> sym, qty <span class="hljs-keyword">in</span> portfolio.items()]</span><br><span class="line">    <span class="hljs-keyword">return</span> <span class="hljs-string">"Portfolio holdings:\n"</span> + <span class="hljs-string">"\n"</span>.join(holdings)</span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">@decision_agent.tool</span></span><br><span class="line"><span class="hljs-keyword">def</span> <span class="title function_">calculate_buying_power</span>(<span class="hljs-params">ctx: RunContext[AgentContext]</span>) -&gt; <span class="hljs-built_in">str</span>:</span><br><span class="line">    <span class="hljs-string">"""Calculate available buying power (80% of cash for safety)"""</span></span><br><span class="line">    cash, _ = ctx.deps.state_manager.get_synchronized_state()</span><br><span class="line">    buying_power = cash * <span class="hljs-number">0.8</span></span><br><span class="line">    <span class="hljs-keyword">return</span> <span class="hljs-string">f"Available buying power: $<span class="hljs-subst">{buying_power:,<span class="hljs-number">.2</span>f}</span>"</span></span><br></pre></td></tr></tbody></table></figure><h3 id="Execution-Agent-Implementation"><a href="#Execution-Agent-Implementation" class="headerlink" title="Execution Agent Implementation"></a>Execution Agent Implementation</h3><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br><span class="line">48</span><br><span class="line">49</span><br><span class="line">50</span><br><span class="line">51</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">ExecutionResult</span>(<span class="title class_ inherited__">BaseModel</span>):</span><br><span class="line">    success: <span class="hljs-built_in">bool</span></span><br><span class="line">    transaction_id: <span class="hljs-built_in">str</span></span><br><span class="line">    quantity: <span class="hljs-built_in">int</span></span><br><span class="line">    price: <span class="hljs-built_in">float</span></span><br><span class="line">    new_balance: <span class="hljs-built_in">float</span></span><br><span class="line">    message: <span class="hljs-built_in">str</span></span><br><span class="line"></span><br><span class="line">execution_agent = Agent(</span><br><span class="line">    model=<span class="hljs-string">"openai:gpt-4"</span>,</span><br><span class="line">    deps_type=AgentContext,</span><br><span class="line">    output_type=ExecutionResult</span><br><span class="line">)</span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">@execution_agent.system_prompt</span></span><br><span class="line"><span class="hljs-keyword">def</span> <span class="title function_">execution_prompt</span>(<span class="hljs-params">ctx: RunContext[AgentContext]</span>) -&gt; <span class="hljs-built_in">str</span>:</span><br><span class="line">    <span class="hljs-keyword">return</span> <span class="hljs-string">"""You are an Execution Agent. Your role:</span></span><br><span class="line"><span class="hljs-string">    1. Verify funds/shares availability</span></span><br><span class="line"><span class="hljs-string">    2. Execute trades</span></span><br><span class="line"><span class="hljs-string">    3. Update state atomically</span></span><br><span class="line"><span class="hljs-string">    4. Handle errors gracefully</span></span><br><span class="line"><span class="hljs-string"></span></span><br><span class="line"><span class="hljs-string">    You have WRITE access to state."""</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">@execution_agent.tool</span></span><br><span class="line"><span class="hljs-keyword">def</span> <span class="title function_">verify_cash_for_buy</span>(<span class="hljs-params">ctx: RunContext[AgentContext],</span></span><br><span class="line"><span class="hljs-params">                        quantity: <span class="hljs-built_in">int</span>, price: <span class="hljs-built_in">float</span></span>) -&gt; <span class="hljs-built_in">str</span>:</span><br><span class="line">    <span class="hljs-string">"""Verify sufficient cash for purchase"""</span></span><br><span class="line">    cash, _ = ctx.deps.state_manager.get_synchronized_state()</span><br><span class="line">    required = quantity * price</span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">if</span> cash &gt;= required:</span><br><span class="line">        <span class="hljs-keyword">return</span> <span class="hljs-string">f"Sufficient cash: $<span class="hljs-subst">{cash:,<span class="hljs-number">.2</span>f}</span> &gt;= $<span class="hljs-subst">{required:,<span class="hljs-number">.2</span>f}</span>"</span></span><br><span class="line">    <span class="hljs-keyword">return</span> <span class="hljs-string">f"Insufficient cash: $<span class="hljs-subst">{cash:,<span class="hljs-number">.2</span>f}</span> &lt; $<span class="hljs-subst">{required:,<span class="hljs-number">.2</span>f}</span>"</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">@execution_agent.tool</span></span><br><span class="line"><span class="hljs-keyword">def</span> <span class="title function_">execute_buy</span>(<span class="hljs-params">ctx: RunContext[AgentContext],</span></span><br><span class="line"><span class="hljs-params">                symbol: <span class="hljs-built_in">str</span>, quantity: <span class="hljs-built_in">int</span>, price: <span class="hljs-built_in">float</span></span>) -&gt; <span class="hljs-built_in">str</span>:</span><br><span class="line">    <span class="hljs-string">"""Execute BUY order and update state"""</span></span><br><span class="line">    total_cost = quantity * price</span><br><span class="line">    cash, portfolio = ctx.deps.state_manager.get_synchronized_state()</span><br><span class="line"></span><br><span class="line">    <span class="hljs-comment"># Update cash</span></span><br><span class="line">    new_balance = cash - total_cost</span><br><span class="line">    ctx.deps.state_manager.update_account(new_balance)</span><br><span class="line"></span><br><span class="line">    <span class="hljs-comment"># Update portfolio</span></span><br><span class="line">    portfolio[symbol] = portfolio.get(symbol, <span class="hljs-number">0</span>) + quantity</span><br><span class="line">    ctx.deps.state_manager.update_portfolio(portfolio)</span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">return</span> <span class="hljs-string">f"BUY executed: <span class="hljs-subst">{quantity}</span> <span class="hljs-subst">{symbol}</span> @ $<span class="hljs-subst">{price:<span class="hljs-number">.2</span>f}</span>"</span></span><br></pre></td></tr></tbody></table></figure><h2 id="State-Coordination-Strategies"><a href="#State-Coordination-Strategies" class="headerlink" title="State Coordination Strategies"></a>State Coordination Strategies</h2><p>When multiple agents operate simultaneously, they must share a consistent view of state. Several synchronization strategies apply:</p><h3 id="1-Database-as-Source-of-Truth"><a href="#1-Database-as-Source-of-Truth" class="headerlink" title="1. Database as Source of Truth"></a>1. Database as Source of Truth</h3><p>For state stored in a database, leverage built-in features:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">from</span> contextlib <span class="hljs-keyword">import</span> contextmanager</span><br><span class="line"><span class="hljs-keyword">import</span> threading</span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">LockingStateManager</span>(<span class="title class_ inherited__">CSVStateManager</span>):</span><br><span class="line">    <span class="hljs-string">"""State manager with locking for concurrency"""</span></span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">__init__</span>(<span class="hljs-params">self, data_dir: <span class="hljs-built_in">str</span></span>):</span><br><span class="line">        <span class="hljs-built_in">super</span>().__init__(data_dir)</span><br><span class="line">        <span class="variable language_">self</span>._lock = threading.Lock()</span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">    @contextmanager</span></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">synchronized</span>(<span class="hljs-params">self</span>):</span><br><span class="line">        <span class="hljs-string">"""Context manager for synchronized access"""</span></span><br><span class="line">        <span class="variable language_">self</span>._lock.acquire()</span><br><span class="line">        <span class="hljs-keyword">try</span>:</span><br><span class="line">            <span class="hljs-keyword">yield</span></span><br><span class="line">        <span class="hljs-keyword">finally</span>:</span><br><span class="line">            <span class="variable language_">self</span>._lock.release()</span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">get_synchronized_state</span>(<span class="hljs-params">self</span>) -&gt; <span class="hljs-type">Tuple</span>[<span class="hljs-built_in">float</span>, <span class="hljs-type">Dict</span>[<span class="hljs-built_in">str</span>, <span class="hljs-built_in">int</span>]]:</span><br><span class="line">        <span class="hljs-keyword">with</span> <span class="variable language_">self</span>.synchronized():</span><br><span class="line">            <span class="hljs-keyword">return</span> <span class="variable language_">self</span>._read_cash_balance(), <span class="variable language_">self</span>._read_portfolio()</span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">execute_atomic_trade</span>(<span class="hljs-params">self, trade: TradeDecision</span>) -&gt; <span class="hljs-built_in">bool</span>:</span><br><span class="line">        <span class="hljs-string">"""Execute trade atomically with locking"""</span></span><br><span class="line">        <span class="hljs-keyword">with</span> <span class="variable language_">self</span>.synchronized():</span><br><span class="line">            cash, portfolio = <span class="variable language_">self</span>._read_cash_balance(), <span class="variable language_">self</span>._read_portfolio()</span><br><span class="line"></span><br><span class="line">            <span class="hljs-keyword">if</span> trade.transaction_type == <span class="hljs-string">"BUY"</span>:</span><br><span class="line">                required = trade.quantity * trade.estimated_price</span><br><span class="line">                <span class="hljs-keyword">if</span> cash &lt; required:</span><br><span class="line">                    <span class="hljs-keyword">return</span> <span class="hljs-literal">False</span></span><br><span class="line">                cash -= required</span><br><span class="line">                portfolio[trade.symbol] = portfolio.get(trade.symbol, <span class="hljs-number">0</span>) + trade.quantity</span><br><span class="line">            <span class="hljs-keyword">else</span>:  <span class="hljs-comment"># SELL</span></span><br><span class="line">                <span class="hljs-keyword">if</span> portfolio.get(trade.symbol, <span class="hljs-number">0</span>) &lt; trade.quantity:</span><br><span class="line">                    <span class="hljs-keyword">return</span> <span class="hljs-literal">False</span></span><br><span class="line">                cash += trade.quantity * trade.estimated_price</span><br><span class="line">                portfolio[trade.symbol] -= trade.quantity</span><br><span class="line"></span><br><span class="line">            <span class="variable language_">self</span>._write_cash_balance(cash)</span><br><span class="line">            <span class="variable language_">self</span>._write_portfolio(portfolio)</span><br><span class="line">            <span class="hljs-keyword">return</span> <span class="hljs-literal">True</span></span><br></pre></td></tr></tbody></table></figure><h3 id="2-State-Snapshots-and-Version-Hashing"><a href="#2-State-Snapshots-and-Version-Hashing" class="headerlink" title="2. State Snapshots and Version Hashing"></a>2. State Snapshots and Version Hashing</h3><p>Track state changes with version hashes to detect concurrent modifications:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br><span class="line">48</span><br><span class="line">49</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">import</span> hashlib</span><br><span class="line"><span class="hljs-keyword">import</span> time</span><br><span class="line"><span class="hljs-keyword">from</span> pydantic <span class="hljs-keyword">import</span> BaseModel</span><br><span class="line"><span class="hljs-keyword">from</span> typing <span class="hljs-keyword">import</span> <span class="hljs-type">Optional</span>, <span class="hljs-type">List</span></span><br><span class="line"><span class="hljs-keyword">from</span> enum <span class="hljs-keyword">import</span> Enum</span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">StateSnapshot</span>(<span class="title class_ inherited__">BaseModel</span>):</span><br><span class="line">    snapshot_id: <span class="hljs-built_in">str</span></span><br><span class="line">    timestamp: <span class="hljs-built_in">str</span></span><br><span class="line">    cash_balance: <span class="hljs-built_in">float</span></span><br><span class="line">    portfolio: <span class="hljs-type">Dict</span>[<span class="hljs-built_in">str</span>, <span class="hljs-built_in">int</span>]</span><br><span class="line">    version_hash: <span class="hljs-built_in">str</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">ConflictType</span>(<span class="title class_ inherited__">Enum</span>):</span><br><span class="line">    CONCURRENT_MODIFICATION = <span class="hljs-string">"concurrent_modification"</span></span><br><span class="line">    INSUFFICIENT_FUNDS = <span class="hljs-string">"insufficient_funds"</span></span><br><span class="line">    INSUFFICIENT_SHARES = <span class="hljs-string">"insufficient_shares"</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">StateCoordinator</span>:</span><br><span class="line">    <span class="hljs-string">"""Coordinates state across multiple agents"""</span></span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">__init__</span>(<span class="hljs-params">self, state_manager: BaseStateManager</span>):</span><br><span class="line">        <span class="variable language_">self</span>.state_manager = state_manager</span><br><span class="line">        <span class="variable language_">self</span>.current_version = <span class="hljs-number">0</span></span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">create_state_snapshot</span>(<span class="hljs-params">self</span>) -&gt; StateSnapshot:</span><br><span class="line">        <span class="hljs-string">"""Create snapshot with version hash for conflict detection"""</span></span><br><span class="line">        cash, portfolio = <span class="variable language_">self</span>.state_manager.get_synchronized_state()</span><br><span class="line"></span><br><span class="line">        state_str = <span class="hljs-string">f"<span class="hljs-subst">{cash}</span>:<span class="hljs-subst">{<span class="hljs-built_in">sorted</span>(portfolio.items())}</span>"</span></span><br><span class="line">        version_hash = hashlib.md5(state_str.encode()).hexdigest()[:<span class="hljs-number">8</span>]</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">return</span> StateSnapshot(</span><br><span class="line">            snapshot_id=<span class="hljs-string">f"SNAP_<span class="hljs-subst">{<span class="hljs-built_in">int</span>(time.time())}</span>"</span>,</span><br><span class="line">            timestamp=datetime.now().isoformat(),</span><br><span class="line">            cash_balance=cash,</span><br><span class="line">            portfolio=portfolio.copy(),</span><br><span class="line">            version_hash=version_hash</span><br><span class="line">        )</span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">detect_conflicts</span>(<span class="hljs-params">self, initial_snapshot: StateSnapshot</span>) -&gt; <span class="hljs-type">List</span>[ConflictType]:</span><br><span class="line">        <span class="hljs-string">"""Detect if state changed since snapshot"""</span></span><br><span class="line">        current_snapshot = <span class="variable language_">self</span>.create_state_snapshot()</span><br><span class="line">        conflicts = []</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">if</span> current_snapshot.version_hash != initial_snapshot.version_hash:</span><br><span class="line">            conflicts.append(ConflictType.CONCURRENT_MODIFICATION)</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">return</span> conflicts</span><br></pre></td></tr></tbody></table></figure><h2 id="Conflict-Resolution-Strategies"><a href="#Conflict-Resolution-Strategies" class="headerlink" title="Conflict Resolution Strategies"></a>Conflict Resolution Strategies</h2><p>When agents disagree or state conflicts occur:</p><table><thead><tr><th>Strategy</th><th>Description</th><th>Use Case</th></tr></thead><tbody><tr><td><strong>Predefined Rules</strong></td><td>Embedded conflict resolution logic</td><td>Simple conflicts with clear precedence</td></tr><tr><td><strong>Rollback &amp; Retry</strong></td><td>Undo operation and retry with current state</td><td>Concurrent modification</td></tr><tr><td><strong>Human Escalation</strong></td><td>Escalate to human for decision</td><td>Critical or ambiguous conflicts</td></tr></tbody></table><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">ConflictResolver</span>:</span><br><span class="line">    <span class="hljs-string">"""Resolves conflicts between agent decisions"""</span></span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">resolve</span>(<span class="hljs-params">self, conflicts: <span class="hljs-type">List</span>[ConflictType],</span></span><br><span class="line"><span class="hljs-params">                trade: TradeDecision,</span></span><br><span class="line"><span class="hljs-params">                state_manager: BaseStateManager</span>) -&gt; <span class="hljs-type">Tuple</span>[<span class="hljs-built_in">bool</span>, <span class="hljs-built_in">str</span>]:</span><br><span class="line">        <span class="hljs-string">"""Attempt to resolve conflicts"""</span></span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">if</span> ConflictType.CONCURRENT_MODIFICATION <span class="hljs-keyword">in</span> conflicts:</span><br><span class="line">            <span class="hljs-comment"># Re-validate with current state</span></span><br><span class="line">            cash, portfolio = state_manager.get_synchronized_state()</span><br><span class="line"></span><br><span class="line">            <span class="hljs-keyword">if</span> trade.transaction_type == <span class="hljs-string">"BUY"</span>:</span><br><span class="line">                required = trade.quantity * trade.estimated_price</span><br><span class="line">                <span class="hljs-keyword">if</span> cash &gt;= required:</span><br><span class="line">                    <span class="hljs-keyword">return</span> <span class="hljs-literal">True</span>, <span class="hljs-string">"Re-validated: Sufficient funds"</span></span><br><span class="line">                <span class="hljs-keyword">return</span> <span class="hljs-literal">False</span>, <span class="hljs-string">f"Insufficient funds: $<span class="hljs-subst">{cash:,<span class="hljs-number">.2</span>f}</span> &lt; $<span class="hljs-subst">{required:,<span class="hljs-number">.2</span>f}</span>"</span></span><br><span class="line"></span><br><span class="line">            <span class="hljs-keyword">else</span>:  <span class="hljs-comment"># SELL</span></span><br><span class="line">                available = portfolio.get(trade.symbol, <span class="hljs-number">0</span>)</span><br><span class="line">                <span class="hljs-keyword">if</span> available &gt;= trade.quantity:</span><br><span class="line">                    <span class="hljs-keyword">return</span> <span class="hljs-literal">True</span>, <span class="hljs-string">"Re-validated: Sufficient shares"</span></span><br><span class="line">                <span class="hljs-keyword">return</span> <span class="hljs-literal">False</span>, <span class="hljs-string">f"Insufficient shares: <span class="hljs-subst">{available}</span> &lt; <span class="hljs-subst">{trade.quantity}</span>"</span></span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">return</span> <span class="hljs-literal">False</span>, <span class="hljs-string">"Unable to resolve conflicts"</span></span><br></pre></td></tr></tbody></table></figure><h2 id="Multi-Agent-Trading-System-with-Supervisor"><a href="#Multi-Agent-Trading-System-with-Supervisor" class="headerlink" title="Multi-Agent Trading System with Supervisor"></a>Multi-Agent Trading System with Supervisor</h2><p>The complete system uses a supervisor agent to coordinate all checks:</p><pre class="mermaid">flowchart TD    T[Trade Request] --&gt; S[Supervisor]    S --&gt; |Create Snapshot| SNAP[State Snapshot]    S --&gt; |Check| C[Compliance Agent]    S --&gt; |Check| R[Risk Agent]    S --&gt; |Check| A[Account Agent]    C --&gt; |Decision| AGG[Aggregate Decisions]    R --&gt; |Decision| AGG    A --&gt; |Decision| AGG    AGG --&gt; |All Approved?| D{Decision}    D --&gt;|Yes| CONF[Check Conflicts]    D --&gt;|No| REJ[Reject Trade]    CONF --&gt; |No Conflicts| EXEC[Execute Trade]    CONF --&gt; |Conflicts| RES[Resolve/Retry]    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    class S blueClass    class D orangeClass</pre><h3 id="Supervisor-Implementation"><a href="#Supervisor-Implementation" class="headerlink" title="Supervisor Implementation"></a>Supervisor Implementation</h3><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br><span class="line">48</span><br><span class="line">49</span><br><span class="line">50</span><br><span class="line">51</span><br><span class="line">52</span><br><span class="line">53</span><br><span class="line">54</span><br><span class="line">55</span><br><span class="line">56</span><br><span class="line">57</span><br><span class="line">58</span><br><span class="line">59</span><br><span class="line">60</span><br><span class="line">61</span><br><span class="line">62</span><br><span class="line">63</span><br><span class="line">64</span><br><span class="line">65</span><br><span class="line">66</span><br><span class="line">67</span><br><span class="line">68</span><br><span class="line">69</span><br><span class="line">70</span><br><span class="line">71</span><br><span class="line">72</span><br><span class="line">73</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">from</span> typing <span class="hljs-keyword">import</span> <span class="hljs-type">Dict</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">AgentDecision</span>(<span class="title class_ inherited__">BaseModel</span>):</span><br><span class="line">    approved: <span class="hljs-built_in">bool</span></span><br><span class="line">    reasoning: <span class="hljs-built_in">str</span></span><br><span class="line">    confidence: <span class="hljs-built_in">float</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">SupervisorDecision</span>(<span class="title class_ inherited__">BaseModel</span>):</span><br><span class="line">    trade_id: <span class="hljs-built_in">str</span></span><br><span class="line">    final_decision: <span class="hljs-built_in">str</span>  <span class="hljs-comment"># APPROVED or REJECTED</span></span><br><span class="line">    reasoning: <span class="hljs-built_in">str</span></span><br><span class="line">    agent_approvals: <span class="hljs-type">Dict</span>[<span class="hljs-built_in">str</span>, <span class="hljs-built_in">bool</span>]</span><br><span class="line">    conflicts_detected: <span class="hljs-type">List</span>[<span class="hljs-built_in">str</span>]</span><br><span class="line">    conflicts_resolved: <span class="hljs-built_in">bool</span></span><br><span class="line">    execution_allowed: <span class="hljs-built_in">bool</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">MultiAgentTradingSystem</span>:</span><br><span class="line">    <span class="hljs-string">"""Coordinates multiple agents for trade processing"""</span></span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">__init__</span>(<span class="hljs-params">self, state_coordinator: StateCoordinator</span>):</span><br><span class="line">        <span class="variable language_">self</span>.state_coordinator = state_coordinator</span><br><span class="line">        <span class="variable language_">self</span>.compliance_agent = <span class="variable language_">self</span>._create_compliance_agent()</span><br><span class="line">        <span class="variable language_">self</span>.risk_agent = <span class="variable language_">self</span>._create_risk_agent()</span><br><span class="line">        <span class="variable language_">self</span>.account_agent = <span class="variable language_">self</span>._create_account_agent()</span><br><span class="line">        <span class="variable language_">self</span>.supervisor_agent = <span class="variable language_">self</span>._create_supervisor_agent()</span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">supervise_trade</span>(<span class="hljs-params">self, trade: TradeDecision</span>) -&gt; SupervisorDecision:</span><br><span class="line">        <span class="hljs-string">"""Supervise multi-agent trade processing"""</span></span><br><span class="line"></span><br><span class="line">        <span class="hljs-comment"># Step 1: Create state snapshot for conflict detection</span></span><br><span class="line">        initial_snapshot = <span class="variable language_">self</span>.state_coordinator.create_state_snapshot()</span><br><span class="line"></span><br><span class="line">        <span class="hljs-comment"># Step 2: Run parallel agent checks</span></span><br><span class="line">        compliance = <span class="variable language_">self</span>.run_compliance_check(trade)</span><br><span class="line">        risk = <span class="variable language_">self</span>.run_risk_check(trade)</span><br><span class="line">        account = <span class="variable language_">self</span>.run_account_check(trade)</span><br><span class="line"></span><br><span class="line">        agent_approvals = {</span><br><span class="line">            <span class="hljs-string">"compliance"</span>: compliance.approved,</span><br><span class="line">            <span class="hljs-string">"risk"</span>: risk.approved,</span><br><span class="line">            <span class="hljs-string">"account"</span>: account.approved</span><br><span class="line">        }</span><br><span class="line"></span><br><span class="line">        all_approved = <span class="hljs-built_in">all</span>(agent_approvals.values())</span><br><span class="line"></span><br><span class="line">        <span class="hljs-comment"># Step 3: Detect conflicts</span></span><br><span class="line">        conflicts = <span class="variable language_">self</span>.state_coordinator.detect_conflicts(initial_snapshot)</span><br><span class="line"></span><br><span class="line">        <span class="hljs-comment"># Step 4: Resolve conflicts if needed</span></span><br><span class="line">        conflicts_resolved = <span class="hljs-literal">False</span></span><br><span class="line">        <span class="hljs-keyword">if</span> conflicts <span class="hljs-keyword">and</span> all_approved:</span><br><span class="line">            resolver = ConflictResolver()</span><br><span class="line">            conflicts_resolved, _ = resolver.resolve(</span><br><span class="line">                conflicts, trade, <span class="variable language_">self</span>.state_coordinator.state_manager</span><br><span class="line">            )</span><br><span class="line">            <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> conflicts_resolved:</span><br><span class="line">                all_approved = <span class="hljs-literal">False</span></span><br><span class="line"></span><br><span class="line">        <span class="hljs-comment"># Step 5: Execute if approved</span></span><br><span class="line">        execution_allowed = all_approved <span class="hljs-keyword">and</span> (<span class="hljs-keyword">not</span> conflicts <span class="hljs-keyword">or</span> conflicts_resolved)</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">if</span> execution_allowed:</span><br><span class="line">            <span class="variable language_">self</span>.state_coordinator.state_manager.execute_atomic_trade(trade)</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">return</span> SupervisorDecision(</span><br><span class="line">            trade_id=<span class="hljs-string">f"TRD_<span class="hljs-subst">{<span class="hljs-built_in">int</span>(time.time())}</span>"</span>,</span><br><span class="line">            final_decision=<span class="hljs-string">"APPROVED"</span> <span class="hljs-keyword">if</span> execution_allowed <span class="hljs-keyword">else</span> <span class="hljs-string">"REJECTED"</span>,</span><br><span class="line">            reasoning=<span class="variable language_">self</span>._aggregate_reasoning(compliance, risk, account),</span><br><span class="line">            agent_approvals=agent_approvals,</span><br><span class="line">            conflicts_detected=[c.value <span class="hljs-keyword">for</span> c <span class="hljs-keyword">in</span> conflicts],</span><br><span class="line">            conflicts_resolved=conflicts_resolved,</span><br><span class="line">            execution_allowed=execution_allowed</span><br><span class="line">        )</span><br></pre></td></tr></tbody></table></figure><h3 id="Fallback-Mechanisms"><a href="#Fallback-Mechanisms" class="headerlink" title="Fallback Mechanisms"></a>Fallback Mechanisms</h3><p>Critical for production systems - always handle agent failures:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">def</span> <span class="title function_">run_compliance_check</span>(<span class="hljs-params">self, trade: TradeDecision</span>) -&gt; AgentDecision:</span><br><span class="line">    <span class="hljs-string">"""Run compliance check with fallback"""</span></span><br><span class="line">    <span class="hljs-keyword">try</span>:</span><br><span class="line">        result = <span class="variable language_">self</span>.compliance_agent.run_sync(</span><br><span class="line">            <span class="hljs-string">f"Check compliance for <span class="hljs-subst">{trade.transaction_type}</span> <span class="hljs-subst">{trade.quantity}</span> <span class="hljs-subst">{trade.symbol}</span>"</span>,</span><br><span class="line">            deps=<span class="variable language_">self</span>.context</span><br><span class="line">        )</span><br><span class="line">        <span class="hljs-keyword">return</span> result.output</span><br><span class="line">    <span class="hljs-keyword">except</span> Exception <span class="hljs-keyword">as</span> e:</span><br><span class="line">        <span class="hljs-comment"># Fallback: Reject on compliance failure</span></span><br><span class="line">        <span class="hljs-keyword">return</span> AgentDecision(</span><br><span class="line">            approved=<span class="hljs-literal">False</span>,</span><br><span class="line">            reasoning=<span class="hljs-string">f"Compliance check failed: <span class="hljs-subst">{e}</span>"</span>,</span><br><span class="line">            confidence=<span class="hljs-number">0.0</span></span><br><span class="line">        )</span><br></pre></td></tr></tbody></table></figure><h2 id="Multi-Agent-RAG-for-Trading-Intelligence"><a href="#Multi-Agent-RAG-for-Trading-Intelligence" class="headerlink" title="Multi-Agent RAG for Trading Intelligence"></a>Multi-Agent RAG for Trading Intelligence</h2><p>For complex queries like “Should I buy AAPL?”, a single agent isn’t enough. Multi-Agent RAG coordinates specialized retrieval agents to gather comprehensive information:</p><pre class="mermaid">flowchart TD    Q[User Query] --&gt; C[Retrieval Coordinator]    C --&gt; |Analyze| D[Determine Required Agents]    D --&gt; M[Market Data Agent]    D --&gt; F[Fundamental Agent]    D --&gt; N[News Sentiment Agent]    D --&gt; R[Risk Agent]    M --&gt; S[Synthesis Agent]    F --&gt; S    N --&gt; S    R --&gt; S    S --&gt; G[Gap Analysis]    G --&gt; |Complete?| OUT{Output}    OUT --&gt;|Yes| ANS[Final Answer]    OUT --&gt;|No| C    classDef blueClass fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff    classDef orangeClass fill:#F39C12,stroke:#333,stroke-width:2px,color:#fff    classDef greenClass fill:#27AE60,stroke:#333,stroke-width:2px,color:#fff    class C blueClass    class S orangeClass    class G greenClass</pre><h3 id="Key-Roles-in-Multi-Agent-RAG"><a href="#Key-Roles-in-Multi-Agent-RAG" class="headerlink" title="Key Roles in Multi-Agent RAG"></a>Key Roles in Multi-Agent RAG</h3><table><thead><tr><th>Role</th><th>Responsibility</th></tr></thead><tbody><tr><td><strong>Retrieval Coordinator</strong></td><td>Analyzes query, delegates to appropriate agents</td></tr><tr><td><strong>Specialized Agents</strong></td><td>Each focused on a specific data source (market, fundamentals, news, risk)</td></tr><tr><td><strong>Synthesis Agent</strong></td><td>Combines results into coherent answer</td></tr><tr><td><strong>Gap Analyzer</strong></td><td>Identifies missing information, triggers follow-up queries</td></tr></tbody></table><h3 id="Implementation"><a href="#Implementation" class="headerlink" title="Implementation"></a>Implementation</h3><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br><span class="line">39</span><br><span class="line">40</span><br><span class="line">41</span><br><span class="line">42</span><br><span class="line">43</span><br><span class="line">44</span><br><span class="line">45</span><br><span class="line">46</span><br><span class="line">47</span><br><span class="line">48</span><br><span class="line">49</span><br><span class="line">50</span><br><span class="line">51</span><br><span class="line">52</span><br><span class="line">53</span><br><span class="line">54</span><br><span class="line">55</span><br><span class="line">56</span><br><span class="line">57</span><br><span class="line">58</span><br><span class="line">59</span><br><span class="line">60</span><br><span class="line">61</span><br><span class="line">62</span><br><span class="line">63</span><br><span class="line">64</span><br><span class="line">65</span><br><span class="line">66</span><br><span class="line">67</span><br><span class="line">68</span><br><span class="line">69</span><br><span class="line">70</span><br><span class="line">71</span><br><span class="line">72</span><br><span class="line">73</span><br><span class="line">74</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">from</span> enum <span class="hljs-keyword">import</span> Enum</span><br><span class="line"><span class="hljs-keyword">from</span> typing <span class="hljs-keyword">import</span> <span class="hljs-type">List</span>, <span class="hljs-type">Any</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">DataSource</span>(<span class="title class_ inherited__">Enum</span>):</span><br><span class="line">    MARKET_DATA = <span class="hljs-string">"MARKET_DATA"</span></span><br><span class="line">    FUNDAMENTAL_DATA = <span class="hljs-string">"FUNDAMENTAL_DATA"</span></span><br><span class="line">    NEWS_SENTIMENT = <span class="hljs-string">"NEWS_SENTIMENT"</span></span><br><span class="line">    RISK_METRICS = <span class="hljs-string">"RISK_METRICS"</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">RetrievalResult</span>(<span class="title class_ inherited__">BaseModel</span>):</span><br><span class="line">    agent_name: <span class="hljs-built_in">str</span></span><br><span class="line">    data_source: DataSource</span><br><span class="line">    retrieved_data: <span class="hljs-type">Dict</span>[<span class="hljs-built_in">str</span>, <span class="hljs-type">Any</span>]</span><br><span class="line">    confidence: <span class="hljs-built_in">float</span></span><br><span class="line">    retrieval_time: <span class="hljs-built_in">float</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">CoordinatorDecision</span>(<span class="title class_ inherited__">BaseModel</span>):</span><br><span class="line">    query: <span class="hljs-built_in">str</span></span><br><span class="line">    required_agents: <span class="hljs-type">List</span>[DataSource]</span><br><span class="line">    reasoning: <span class="hljs-built_in">str</span></span><br><span class="line">    priority_order: <span class="hljs-type">List</span>[<span class="hljs-built_in">str</span>]</span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">MultiAgentRAGSystem</span>:</span><br><span class="line">    <span class="hljs-string">"""Complete Multi-Agent RAG system for trading intelligence"""</span></span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">__init__</span>(<span class="hljs-params">self</span>):</span><br><span class="line">        <span class="variable language_">self</span>.market_agent = MarketDataAgent()</span><br><span class="line">        <span class="variable language_">self</span>.fundamental_agent = FundamentalDataAgent()</span><br><span class="line">        <span class="variable language_">self</span>.news_agent = NewsSentimentAgent()</span><br><span class="line">        <span class="variable language_">self</span>.risk_agent = RiskDataAgent()</span><br><span class="line">        <span class="variable language_">self</span>.coordinator = RetrievalCoordinator()</span><br><span class="line">        <span class="variable language_">self</span>.synthesizer = SynthesisAgent()</span><br><span class="line">        <span class="variable language_">self</span>.gap_analyzer = GapAnalysisAgent()</span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">query</span>(<span class="hljs-params">self, user_query: <span class="hljs-built_in">str</span>, symbol: <span class="hljs-built_in">str</span>,</span></span><br><span class="line"><span class="hljs-params">              max_iterations: <span class="hljs-built_in">int</span> = <span class="hljs-number">2</span></span>) -&gt; SynthesisResult:</span><br><span class="line">        <span class="hljs-string">"""Process query through multi-agent RAG pipeline"""</span></span><br><span class="line"></span><br><span class="line">        all_results = []</span><br><span class="line">        iteration = <span class="hljs-number">0</span></span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">while</span> iteration &lt; max_iterations:</span><br><span class="line">            iteration += <span class="hljs-number">1</span></span><br><span class="line"></span><br><span class="line">            <span class="hljs-comment"># Step 1: Coordinate - determine which agents to use</span></span><br><span class="line">            decision = <span class="variable language_">self</span>.coordinator.coordinate(user_query, symbol)</span><br><span class="line"></span><br><span class="line">            <span class="hljs-comment"># Step 2: Execute retrievals</span></span><br><span class="line">            results = []</span><br><span class="line">            <span class="hljs-keyword">for</span> agent_type <span class="hljs-keyword">in</span> decision.required_agents:</span><br><span class="line">                <span class="hljs-keyword">if</span> agent_type == DataSource.MARKET_DATA:</span><br><span class="line">                    results.append(<span class="variable language_">self</span>.market_agent.retrieve(user_query, symbol))</span><br><span class="line">                <span class="hljs-keyword">elif</span> agent_type == DataSource.FUNDAMENTAL_DATA:</span><br><span class="line">                    results.append(<span class="variable language_">self</span>.fundamental_agent.retrieve(user_query, symbol))</span><br><span class="line">                <span class="hljs-keyword">elif</span> agent_type == DataSource.NEWS_SENTIMENT:</span><br><span class="line">                    results.append(<span class="variable language_">self</span>.news_agent.retrieve(user_query, symbol))</span><br><span class="line">                <span class="hljs-keyword">elif</span> agent_type == DataSource.RISK_METRICS:</span><br><span class="line">                    results.append(<span class="variable language_">self</span>.risk_agent.retrieve(user_query, symbol))</span><br><span class="line"></span><br><span class="line">            all_results.extend(results)</span><br><span class="line"></span><br><span class="line">            <span class="hljs-comment"># Step 3: Synthesize</span></span><br><span class="line">            synthesis = <span class="variable language_">self</span>.synthesizer.synthesize(user_query, symbol, all_results)</span><br><span class="line"></span><br><span class="line">            <span class="hljs-comment"># Step 4: Gap analysis</span></span><br><span class="line">            gaps = <span class="variable language_">self</span>.gap_analyzer.analyze(user_query, synthesis)</span><br><span class="line"></span><br><span class="line">            <span class="hljs-keyword">if</span> <span class="hljs-keyword">not</span> gaps.needs_re_query:</span><br><span class="line">                <span class="hljs-keyword">return</span> synthesis</span><br><span class="line"></span><br><span class="line">            <span class="hljs-comment"># Expand query for next iteration</span></span><br><span class="line">            user_query = gaps.follow_up_queries[<span class="hljs-number">0</span>] <span class="hljs-keyword">if</span> gaps.follow_up_queries <span class="hljs-keyword">else</span> user_query</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">return</span> synthesis</span><br></pre></td></tr></tbody></table></figure><h3 id="Retrieval-Coordinator"><a href="#Retrieval-Coordinator" class="headerlink" title="Retrieval Coordinator"></a>Retrieval Coordinator</h3><p>The coordinator analyzes queries to determine which agents are needed:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">RetrievalCoordinator</span>:</span><br><span class="line">    <span class="hljs-string">"""Orchestrates retrieval agents based on query analysis"""</span></span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">__init__</span>(<span class="hljs-params">self</span>):</span><br><span class="line">        <span class="variable language_">self</span>.agent = Agent(</span><br><span class="line">            model=<span class="hljs-string">"openai:gpt-3.5-turbo"</span>,</span><br><span class="line">            deps_type=RAGContext,</span><br><span class="line">            output_type=CoordinatorDecision</span><br><span class="line">        )</span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">    @self.agent.tool</span></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">analyze_query_intent</span>(<span class="hljs-params">ctx: RunContext, query: <span class="hljs-built_in">str</span></span>) -&gt; <span class="hljs-built_in">str</span>:</span><br><span class="line">        <span class="hljs-string">"""Analyze what the query is asking for"""</span></span><br><span class="line">        keywords = query.lower()</span><br><span class="line">        intents = []</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">if</span> <span class="hljs-built_in">any</span>(word <span class="hljs-keyword">in</span> keywords <span class="hljs-keyword">for</span> word <span class="hljs-keyword">in</span> [<span class="hljs-string">'price'</span>, <span class="hljs-string">'volume'</span>, <span class="hljs-string">'technical'</span>]):</span><br><span class="line">            intents.append(<span class="hljs-string">"MARKET_DATA"</span>)</span><br><span class="line">        <span class="hljs-keyword">if</span> <span class="hljs-built_in">any</span>(word <span class="hljs-keyword">in</span> keywords <span class="hljs-keyword">for</span> word <span class="hljs-keyword">in</span> [<span class="hljs-string">'earnings'</span>, <span class="hljs-string">'revenue'</span>, <span class="hljs-string">'financial'</span>]):</span><br><span class="line">            intents.append(<span class="hljs-string">"FUNDAMENTAL_DATA"</span>)</span><br><span class="line">        <span class="hljs-keyword">if</span> <span class="hljs-built_in">any</span>(word <span class="hljs-keyword">in</span> keywords <span class="hljs-keyword">for</span> word <span class="hljs-keyword">in</span> [<span class="hljs-string">'news'</span>, <span class="hljs-string">'sentiment'</span>, <span class="hljs-string">'analyst'</span>]):</span><br><span class="line">            intents.append(<span class="hljs-string">"NEWS_SENTIMENT"</span>)</span><br><span class="line">        <span class="hljs-keyword">if</span> <span class="hljs-built_in">any</span>(word <span class="hljs-keyword">in</span> keywords <span class="hljs-keyword">for</span> word <span class="hljs-keyword">in</span> [<span class="hljs-string">'risk'</span>, <span class="hljs-string">'volatility'</span>, <span class="hljs-string">'beta'</span>]):</span><br><span class="line">            intents.append(<span class="hljs-string">"RISK_METRICS"</span>)</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">return</span> <span class="hljs-string">f"Query intents: <span class="hljs-subst">{<span class="hljs-string">', '</span>.join(intents) <span class="hljs-keyword">if</span> intents <span class="hljs-keyword">else</span> <span class="hljs-string">'GENERAL'</span>}</span>"</span></span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">coordinate</span>(<span class="hljs-params">self, query: <span class="hljs-built_in">str</span>, symbol: <span class="hljs-built_in">str</span></span>) -&gt; CoordinatorDecision:</span><br><span class="line">        <span class="hljs-string">"""Coordinate retrieval based on query"""</span></span><br><span class="line">        context = RAGContext(query=query, symbol=symbol)</span><br><span class="line">        result = <span class="variable language_">self</span>.agent.run_sync(</span><br><span class="line">            <span class="hljs-string">f"Analyze this query and determine which retrieval agents are needed: <span class="hljs-subst">{query}</span>"</span>,</span><br><span class="line">            deps=context</span><br><span class="line">        )</span><br><span class="line">        <span class="hljs-keyword">return</span> result.output</span><br></pre></td></tr></tbody></table></figure><h3 id="Gap-Analysis-and-Re-Querying"><a href="#Gap-Analysis-and-Re-Querying" class="headerlink" title="Gap Analysis and Re-Querying"></a>Gap Analysis and Re-Querying</h3><p>The gap analyzer ensures completeness before returning results:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">GapAnalysis</span>(<span class="title class_ inherited__">BaseModel</span>):</span><br><span class="line">    missing_data: <span class="hljs-type">List</span>[<span class="hljs-built_in">str</span>]</span><br><span class="line">    follow_up_queries: <span class="hljs-type">List</span>[<span class="hljs-built_in">str</span>]</span><br><span class="line">    needs_re_query: <span class="hljs-built_in">bool</span></span><br><span class="line">    reasoning: <span class="hljs-built_in">str</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">GapAnalysisAgent</span>:</span><br><span class="line">    <span class="hljs-string">"""Identifies missing information and triggers re-querying"""</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-meta">    @self.agent.tool</span></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">identify_data_gaps</span>(<span class="hljs-params">ctx: RunContext</span>) -&gt; <span class="hljs-built_in">str</span>:</span><br><span class="line">        <span class="hljs-string">"""Identify what data is missing"""</span></span><br><span class="line">        data = ctx.deps.retrieved_data</span><br><span class="line">        gaps = []</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">if</span> <span class="hljs-string">"MARKET_DATA"</span> <span class="hljs-keyword">not</span> <span class="hljs-keyword">in</span> data <span class="hljs-keyword">or</span> <span class="hljs-keyword">not</span> data[<span class="hljs-string">"MARKET_DATA"</span>]:</span><br><span class="line">            gaps.append(<span class="hljs-string">"Market data"</span>)</span><br><span class="line">        <span class="hljs-keyword">if</span> <span class="hljs-string">"FUNDAMENTAL_DATA"</span> <span class="hljs-keyword">not</span> <span class="hljs-keyword">in</span> data <span class="hljs-keyword">or</span> <span class="hljs-keyword">not</span> data[<span class="hljs-string">"FUNDAMENTAL_DATA"</span>]:</span><br><span class="line">            gaps.append(<span class="hljs-string">"Fundamental data"</span>)</span><br><span class="line">        <span class="hljs-keyword">if</span> <span class="hljs-string">"RISK_METRICS"</span> <span class="hljs-keyword">not</span> <span class="hljs-keyword">in</span> data <span class="hljs-keyword">or</span> <span class="hljs-keyword">not</span> data[<span class="hljs-string">"RISK_METRICS"</span>]:</span><br><span class="line">            gaps.append(<span class="hljs-string">"Risk metrics"</span>)</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">return</span> <span class="hljs-string">f"Data gaps: <span class="hljs-subst">{<span class="hljs-string">', '</span>.join(gaps) <span class="hljs-keyword">if</span> gaps <span class="hljs-keyword">else</span> <span class="hljs-string">'None - complete'</span>}</span>"</span></span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">analyze</span>(<span class="hljs-params">self, query: <span class="hljs-built_in">str</span>, synthesis: SynthesisResult</span>) -&gt; GapAnalysis:</span><br><span class="line">        <span class="hljs-string">"""Analyze information gaps"""</span></span><br><span class="line">        context = RAGContext(query=query, retrieved_data=synthesis.sources_used)</span><br><span class="line"></span><br><span class="line">        result = <span class="variable language_">self</span>.agent.run_sync(</span><br><span class="line">            <span class="hljs-string">f"Analyze if we have complete information. Confidence: <span class="hljs-subst">{synthesis.confidence:<span class="hljs-number">.0</span>%}</span>"</span>,</span><br><span class="line">            deps=context</span><br><span class="line">        )</span><br><span class="line">        <span class="hljs-keyword">return</span> result.output</span><br></pre></td></tr></tbody></table></figure><h2 id="Production-Considerations"><a href="#Production-Considerations" class="headerlink" title="Production Considerations"></a>Production Considerations</h2><h3 id="Audit-Trails"><a href="#Audit-Trails" class="headerlink" title="Audit Trails"></a>Audit Trails</h3><p>Every multi-agent operation should be logged:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-meta">@dataclass</span></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">CoordinationAudit</span>:</span><br><span class="line">    timestamp: datetime</span><br><span class="line">    trade_id: <span class="hljs-built_in">str</span></span><br><span class="line">    initial_snapshot: StateSnapshot</span><br><span class="line">    agent_decisions: <span class="hljs-type">Dict</span>[<span class="hljs-built_in">str</span>, AgentDecision]</span><br><span class="line">    conflicts: <span class="hljs-type">List</span>[ConflictType]</span><br><span class="line">    resolution: <span class="hljs-type">Optional</span>[<span class="hljs-built_in">str</span>]</span><br><span class="line">    final_decision: <span class="hljs-built_in">str</span></span><br><span class="line">    execution_time_ms: <span class="hljs-built_in">int</span></span><br><span class="line"></span><br><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">AuditedTradingSystem</span>(<span class="title class_ inherited__">MultiAgentTradingSystem</span>):</span><br><span class="line">    <span class="hljs-string">"""Trading system with comprehensive audit logging"""</span></span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">__init__</span>(<span class="hljs-params">self, state_coordinator: StateCoordinator</span>):</span><br><span class="line">        <span class="hljs-built_in">super</span>().__init__(state_coordinator)</span><br><span class="line">        <span class="variable language_">self</span>.audit_log: <span class="hljs-type">List</span>[CoordinationAudit] = []</span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">supervise_trade</span>(<span class="hljs-params">self, trade: TradeDecision</span>) -&gt; SupervisorDecision:</span><br><span class="line">        start_time = time.time()</span><br><span class="line">        initial_snapshot = <span class="variable language_">self</span>.state_coordinator.create_state_snapshot()</span><br><span class="line"></span><br><span class="line">        result = <span class="hljs-built_in">super</span>().supervise_trade(trade)</span><br><span class="line"></span><br><span class="line">        <span class="variable language_">self</span>.audit_log.append(CoordinationAudit(</span><br><span class="line">            timestamp=datetime.now(),</span><br><span class="line">            trade_id=result.trade_id,</span><br><span class="line">            initial_snapshot=initial_snapshot,</span><br><span class="line">            agent_decisions=result.agent_approvals,</span><br><span class="line">            conflicts=[ConflictType(c) <span class="hljs-keyword">for</span> c <span class="hljs-keyword">in</span> result.conflicts_detected],</span><br><span class="line">            resolution=<span class="hljs-string">"Resolved"</span> <span class="hljs-keyword">if</span> result.conflicts_resolved <span class="hljs-keyword">else</span> <span class="hljs-literal">None</span>,</span><br><span class="line">            final_decision=result.final_decision,</span><br><span class="line">            execution_time_ms=<span class="hljs-built_in">int</span>((time.time() - start_time) * <span class="hljs-number">1000</span>)</span><br><span class="line">        ))</span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">return</span> result</span><br></pre></td></tr></tbody></table></figure><h3 id="Handling-Agent-Failures"><a href="#Handling-Agent-Failures" class="headerlink" title="Handling Agent Failures"></a>Handling Agent Failures</h3><p>Graceful degradation when agents fail:</p><figure class="highlight python hljs"><table><tbody><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br></pre></td><td class="code"><pre><span class="line"><span class="hljs-keyword">class</span> <span class="title class_">ResilientTradingSystem</span>(<span class="title class_ inherited__">MultiAgentTradingSystem</span>):</span><br><span class="line">    <span class="hljs-string">"""Trading system with failure resilience"""</span></span><br><span class="line"></span><br><span class="line">    <span class="hljs-keyword">def</span> <span class="title function_">run_agent_check</span>(<span class="hljs-params">self, agent, trade: TradeDecision,</span></span><br><span class="line"><span class="hljs-params">                        agent_name: <span class="hljs-built_in">str</span></span>) -&gt; AgentDecision:</span><br><span class="line">        <span class="hljs-string">"""Run agent check with retry and fallback"""</span></span><br><span class="line"></span><br><span class="line">        <span class="hljs-keyword">for</span> attempt <span class="hljs-keyword">in</span> <span class="hljs-built_in">range</span>(<span class="hljs-number">3</span>):</span><br><span class="line">            <span class="hljs-keyword">try</span>:</span><br><span class="line">                <span class="hljs-keyword">return</span> agent.run_sync(</span><br><span class="line">                    <span class="hljs-string">f"Check <span class="hljs-subst">{trade.symbol}</span> trade"</span>,</span><br><span class="line">                    deps=<span class="variable language_">self</span>.context</span><br><span class="line">                ).output</span><br><span class="line">            <span class="hljs-keyword">except</span> Exception <span class="hljs-keyword">as</span> e:</span><br><span class="line">                <span class="hljs-keyword">if</span> attempt == <span class="hljs-number">2</span>:</span><br><span class="line">                    <span class="hljs-comment"># Final fallback: conservative rejection</span></span><br><span class="line">                    <span class="hljs-keyword">return</span> AgentDecision(</span><br><span class="line">                        approved=<span class="hljs-literal">False</span>,</span><br><span class="line">                        reasoning=<span class="hljs-string">f"<span class="hljs-subst">{agent_name}</span> failed after 3 attempts: <span class="hljs-subst">{e}</span>"</span>,</span><br><span class="line">                        confidence=<span class="hljs-number">0.0</span></span><br><span class="line">                    )</span><br><span class="line">                time.sleep(<span class="hljs-number">2</span> ** attempt)  <span class="hljs-comment"># Exponential backoff</span></span><br></pre></td></tr></tbody></table></figure><h2 id="Takeaways"><a href="#Takeaways" class="headerlink" title="Takeaways"></a>Takeaways</h2><ol><li><p><strong>State management</strong> requires distinguishing ephemeral (session) from persistent (database) state - trading systems need persistence</p></li><li><p><strong>Interchangeable state managers</strong> abstract storage details, allowing CSV, SQL, or other backends without changing agent code</p></li><li><p><strong>Agent separation</strong> between decision and execution provides clear responsibilities and different operational characteristics</p></li><li><p><strong>State coordination</strong> through snapshots and version hashing detects concurrent modifications before they cause problems</p></li><li><p><strong>Conflict resolution</strong> strategies include predefined rules, rollback/retry, and human escalation for complex situations</p></li><li><p><strong>Supervisor agents</strong> coordinate multiple specialized agents, aggregate decisions, and handle conflicts</p></li><li><p><strong>Fallback mechanisms</strong> are critical - always handle agent failures to prevent system deadlock</p></li><li><p><strong>Multi-Agent RAG</strong> coordinates specialized retrieval agents (market, fundamental, news, risk) with synthesis and gap analysis for comprehensive trading intelligence</p></li></ol><hr><p><em>This is the thirteenth post in my Applied Agentic AI for Finance series. Next: <a href="/2026/01/30/Applied-Agentic-AI-in-Finance-A-Complete-Guide/">Applied Agentic AI in Finance: A Complete Guide</a> where we’ll bring together everything we’ve learned into a comprehensive overview of production patterns.</em></p></body></html>]]></content>
    
    
    <summary type="html">&lt;html&gt;&lt;head&gt;&lt;/head&gt;&lt;body&gt;&lt;p&gt;When multiple agents operate simultaneously on trading operations, they must share a consistent understanding of the world state. This post explores the coordination patterns that make multi-agent trading systems reliable: persistent state management, conflict resolution, and multi-agent RAG for comprehensive analysis.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</summary>
    
    
    
    <category term="AI" scheme="https://vanducng.dev/categories/AI/"/>
    
    
    <category term="llm" scheme="https://vanducng.dev/tags/llm/"/>
    
    <category term="python" scheme="https://vanducng.dev/tags/python/"/>
    
    <category term="finance" scheme="https://vanducng.dev/tags/finance/"/>
    
    <category term="multi-agent" scheme="https://vanducng.dev/tags/multi-agent/"/>
    
  </entry>
  
</feed>
