Zola 2026-05-31T00:00:00+00:00 https://terratauri.com/blog/atom.xml 2026-05-31T00:00:00+00:00 2026-05-31T00:00:00+00:00 Unknown https://terratauri.com/blog/the-gas-powered-wagon/ <p>There's a genre of AI blog post that I skip as soon as I recognize it: the company retrospective where they handed everyone Copilot or Claude Code, waited a couple of quarters, and came away disappointed that nothing shipped any faster.</p> <p>What bothers me about it is that it reaches for a causal story when all it has is a correlation, and it never goes looking for the mechanism underneath. We adopted the thing, the number didn't move, therefore the thing doesn't work. It's the reasoning of someone who straps a gasoline engine onto the back of a wagon, watches the extra weight slow the horses down, and concludes that engines make you slower.</p> <p>The thing is, you can't actually do that. A wagon is built around the pull of an animal, the wheels only have to roll and bear weight, the axle is a dead beam that holds the wheels apart and carries the load straight down, and the whole thing is tuned for the speed of a walking horse. An engine delivers power in a completely different way, as torque that has to be transmitted to the wheels, which means you need a gearbox to trade the engine's fast spin for usable force, a clutch to engage it, a driveshaft to carry the power back, and a differential so the wheels can turn at different rates through a corner. The dead wagon axle can't take any of that, it would twist and shear the first time the engine bit, and even if it somehow held, the wooden wheels and the plain greased bearings would tear themselves apart at any speed the engine could reach, the brake meant for walking pace wouldn't stop the thing, and the frame would shake itself to splinters. By the time you've added a real drivetrain, a live axle, proper wheels and tires, brakes that work at speed, and a frame stiff enough to survive the vibration, you haven't built a faster wagon. You've built a car, and it only resembles a wagon from a distance.</p> <p>That is the move every disappointed AI rollout actually made, dropping a new source of power onto a structure that was only ever designed to be pulled along slowly. You can't bolt more horsepower onto every engineer and expect the organization to move faster if the parts that carry the load were built for walking pace, and the research that's accumulated over the last couple of years keeps pointing at the same conclusion, which is that the thing slowing it down was never the typing. The coordination problems were already there, the slow reviews and the relitigated decisions and the handoffs that stall for a day, we'd just learned to live with them because the cost of building was high enough to hide them. AI didn't create any of that. It made the rest of the work fast enough that the old friction finally shows up against the new baseline, and the friction is the same friction it always was. It isn't AI's fault that our organizations never kept pace with the work they were already doing, AI only shone a light on it.</p> <h2 id="the-number-that-goes-the-wrong-way">The number that goes the wrong way</h2> <p>In the <a href="https://dora.dev/research/2024/dora-report/">2024 DORA report</a>, three quarters of the people surveyed said they were leaning on AI for part of their job, three quarters reported feeling more productive, and then the system-level numbers went the other way, with the report estimating that a 25% increase in AI adoption corresponded to a 1.5% drop in delivery throughput and a 7.2% drop in delivery stability, and the <a href="https://redmonk.com/rstephens/2025/12/18/dora2025/">2025 follow-up</a> held the pattern rather than reversing it. The easy reading is that the engineers are kidding themselves, that the felt productivity is a sugar high and the dashboard is the truth, and I don't buy it, because the feeling and the dashboard aren't measuring the same thing. What an engineer feels when she uses a good model is the speed of implementation, the rate at which intent turns into working code under her hands, and that genuinely has gotten faster. What DORA measures is delivered value, the throughput and stability at the far end of a pipeline that every change still has to crawl through, the review and the testing and the approval and the deploy. Jez Humble has spent fifteen years pointing out that none of the value is real until the change is safely in production, that <a href="https://www.thoughtworks.com/insights/blog/continuous-delivery/continuous-delivery-not-just-a-technical-activity">"done" means released</a> rather than written, and that a fast delivery capability pays off only when the organization wrapped around the pipeline is built to use it. Mary Poppendieck has the sharper version, that if you map the value stream from idea to production the development work isn't where the time goes, it's the queues and the approvals, which Mary puts at somewhere between half and ninety percent of the elapsed time. Speed up the small slice that is implementation, leave the rest of the pipeline untouched, and the delivered number was never going to move much.</p> <p>Every engineer who has used AI to build something for herself over a weekend, or thrown together a tool for a friend, already knows the implementation speedup is real, because at home there is no pipeline in the way, just her and the keyboard and a thing that exists by Sunday night that wouldn't have existed otherwise. The reason she can't reproduce that feeling at work isn't that she imagined it the first time. It's that at work the value has to survive the trip through the pipeline before it counts for anything, and the pipeline is exactly where it stalls, which makes the whole thing a delivery failure that we keep mislabeling as a productivity one.</p> <p>There's a study people reach for to argue the keyboard didn't even get faster, and it deserves to be handled carefully rather than waved around. <a href="https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/">METR</a> ran a randomized trial with sixteen experienced developers working real issues on their own mature repositories, codebases averaging over a million lines that they'd maintained for years, and found that with AI allowed they were 19% slower, even though they expected to be faster and believed afterward that they had been. It would be easy to stop there and announce that AI doesn't work, which is the lazy move I opened this post complaining about. METR didn't stop there, they ran a factor analysis, and the parts worth dwelling on are about the quality bar, because the study counted a task as done only when the author was satisfied the code would pass review, style and testing and documentation included, and the mature repositories carried a lot of implicit standards that the model didn't know and the developer had to supply by hand. The time didn't disappear into typing, it went into making the output trustworthy enough to survive a demanding codebase, which is the cost this whole post is about showing up at the scale of a single change. They're careful to note that this says nothing about less experienced developers or unfamiliar codebases, the cases where the quality bar is lower and the model has less hidden context to trip over. Whichever way the keyboard number breaks, what cost them time was trusting the code rather than generating it.</p> <p>Rachel Stephens at RedMonk had the foresight to see this same thing back in 2024 and her <a href="https://redmonk.com/rstephens/2024/11/26/dora2024/">writeup</a> is well worth a read. Her move is to dust off the theory of constraints, the old idea that a system only moves as fast as its tightest bottleneck, and Gene Kim's blunt version of it: that any improvement you make somewhere other than the bottleneck is an illusion. If you pour all your new capacity into writing code faster, and writing code was never the constraint, you've optimized the wrong station on the line. You've fitted a stronger engine and left the axle exactly as it was.</p> <h2 id="coordination-was-the-heavy-part">Coordination was the heavy part</h2> <p>So what is the constraint, if not the code? My answer is coordination. I don't mean it in the vague "we should communicate better" sense. I mean coordination in the specific, measurable sense the productivity researchers have been pointing at for years.</p> <p>When Forsgren and Storey and the rest of the SPACE authors laid out their five dimensions of developer productivity back in 2021, one of the five was Communication and Collaboration, sitting right next to the activity counts everyone actually tracks. The <a href="https://queue.acm.org/detail.cfm?id=3595878">DevEx framework</a> that followed put feedback loops at the front, the speed of getting an answer back from a person or a system, the code-review turnaround, the wait for an approval, the handoff between teams. Those are coordination costs wearing different names, and they were already the expensive part long before anyone could generate a thousand lines of plausible code in a minute.</p> <p>The part I think gets underplayed is the economics, and <a href="https://natesnewsletter.substack.com/p/executive-briefing-ai-raised-output">Nate Jones</a> has put numbers to it in his newsletter better than I'm about to. Coordination has always carried a cost, with the communication paths between people growing roughly with the square of the team size, the n(n-1)/2 that Brooks wrote about half a century ago. What AI changes isn't that arithmetic. What it changes is the price of every hour you spend on the left side of it. If an engineer with good tooling can now implement in an afternoon what used to take a week, then every hour that engineer spends in a status meeting, or waiting on a review, or relitigating a decision that was already made, is an hour priced against the much larger amount they could have built instead. The opportunity cost of coordinating went up because the opportunity itself got bigger. Some of the estimates floating around put coordination overhead at well over half of all knowledge-worker hours (which I'd treat as directional rather than gospel), but even the conservative version of that claim means the bottleneck has been sitting in plain sight on everyone's calendar the whole time.</p> <h2 id="what-i-d-actually-do-about-it">What I'd actually do about it</h2> <p>What I'd take from all of this is less a fix than a reorientation. The instinct, once the engine is bolted on, is to keep tuning the engine, to get better at prompting, to adopt the next coding agent, to measure acceptance rates. The more useful instinct is to figure out which parts of the wagon are going to break when you try to go 0 to 60 in 1.66 seconds.</p> <p>In practice that has started with the practice everyone points at first, review, because the agent produces changes faster than anyone can read them and the pull requests stack up. The first tech talk I gave at Bit Complete argued that review was the bottleneck, and I've since come around to thinking that was only half right, because review is mostly a proxy for trust. Nobody really minds that there are more changes to review, what they mind is being asked to vouch for code they have no other way to trust, and a human reading the diff is the slowest and least reliable way to earn that trust. Review is drowning because we let the cheaper sources of trust atrophy, the automated tests and the feature flags and the staged rollouts and the observability and alerting that let a team ship something it isn't yet sure of without betting production on it. Investing heavily in these is what stops review from being the place everything queues, because a change you can roll out to one percent of traffic, watch, and switch off in seconds doesn't need a human to have read every line before it goes out. The DORA authors point at a version of this from another angle, with the throughput and stability drops tracking the arrival of larger, messier change sets, which is to say the old advice about small batch sizes matters more now rather than less, precisely because the tools make it so easy to produce a large batch.</p> <p>It has also meant taking the team-shape questions seriously, the ones Team Topologies and Conway's law were already asking. If coordination cost grows with the number of people who have to agree, then the lever is to need fewer of them in the room, with smaller teams holding clearer ownership, decisions written down once and referred back to instead of relitigated, and dependencies designed out of the architecture rather than negotiated across it every sprint. None of that is new advice. What's new is how much it's now worth, and how far the rebuild has to go, because you don't get to bolt the engine on and keep the wagon. The structure that survives the new power is the one you've reinforced and re-geared and rebuilt until it isn't really a wagon anymore.</p> <h2 id="the-thing-that-actually-scares-me">The thing that actually scares me</h2> <p>The thing that actually scares me in all of this isn't the failed rollouts, it's cognitive offloading, because it's a cost the org chart doesn't capture and it lands on the individual engineer rather than the pipeline. Cognitive offloading, the transfer of mental work from a person to an external system, is exactly what makes agents worth reaching for, and a lot of what gets offloaded is no loss at all, because the boilerplate and the routine lookups and the mechanical refactors were never building anything in the first place. But some of the work we're handing over was the work that kept us sharp, the deep reading of unfamiliar code, the debugging intuition that only comes from hours spent tracking down problems, the design judgment that accumulates from making decisions and watching them play out, and the persistence to stay with a hard problem until the answer is right rather than merely plausible. Those are skills maintained through the act of doing them, and they quietly atrophy when the act is always delegated. The persistence one is the best evidenced: <a href="https://ai-project-website.github.io/AI-assistance-reduces-persistence/">Liu et al. (2025)</a> ran three randomized experiments and found that people who solved problems with AI did measurably worse once it was taken away, with the effect concentrated in the majority who reached for it to get the answer rather than a hint, the option of a direct solution quietly removing the part of the work that builds the habit of staying.</p> <p>This matters for the rebuild specifically. The structure I've been describing puts the human in a more supervisory seat, auditing and specifying and orchestrating rather than typing, and auditing requires the very skill the agent is replacing, because you can't evaluate a design proposal you no longer have the judgment to evaluate. So the offloading turns out to be self-limiting: let those skills go and you can only supervise the easy work, which is the opposite of what the rebuild was for. The defense isn't to refuse the tools, it's a bit of deliberate practice, reading some code without the agent, debugging some problems by hand, taking a position on the trade-offs before asking for its analysis, writing specs at the precision a human reviewer would need even when the reader is a machine, and keeping ownership of a few small things end to end. The cost is a little short-term throughput. The return is staying able to do the supervising the whole rebuild depends on.</p> <p>The companies writing the disappointed retrospectives aren't wrong that the number didn't move. They bolted the most powerful engine anyone has ever handed them onto an axle built for a walking horse, and then blamed the engine when nothing went faster. The engine was never the problem, the wagon always was.</p> 2026-05-12T00:00:00+00:00 2026-05-12T00:00:00+00:00 Unknown https://terratauri.com/blog/the-agent-cannot-guard-itself/ <p>Every coding-agent sandbox I've set up ends in the same tired loop. I lock it down, the agent stops being useful, I loosen it, and I end up exactly where I started: YOLO mode. At best there is a sandbox-shaped object draped loosely over a process that can still do almost anything it wants. In professional contexts where risk is paramount, I spend a lot of my day clicking approve and hoping I don't accidentally allow the wrong thing.</p> <p>This is the central UX trap of agent security. Convenience and capability are two ends of the same balance. When the sandbox lives inside the same process tree it's supposed to constrain, it's too tempting to give the LLM the ability to help you configure the sandbox.</p> <p>The threats are real and recent: new CVEs, fresh supply-chain compromises, persistence attacks against agent harnesses are shipping in the wild. Three of the most terrifying attacks I know of — sandbox escape, audit tampering, and skill poisoning — all share one source: a trust boundary lives inside something the agent controls, and the agent reasons its way to it.</p> <h2 id="1-sandbox-escape">1. Sandbox escape</h2> <p>Start with <a href="https://ona.com/stories/how-claude-code-escapes-its-own-denylist-and-sandbox">Ona's writeup from March 2026</a>. Leonardo Di Donato observed Claude Code, in normal operation, finding three different ways around the sandbox restrictions that ship on it by default.</p> <p>The first one is a path trick. The sandbox blocked <code>npx</code>, and the agent reasoned its way to <code>/proc/self/root/usr/bin/npx</code>, which resolves to the same file but doesn't match the deny pattern. The denylist is matching strings, the agent is reaching files, and only one of those things knows the difference.</p> <p>The second one needs a quick setup. On Linux, Claude Code uses bubblewrap, an unprivileged sandbox tool that requires user namespaces — which some hardened distros disable by default. When bubblewrap can't initialize, Anthropic shipped two escape hatches: <code>dangerouslyDisableSandbox</code> and <code>allowUnsandboxedCommands</code>, both of which run the agent without a sandbox at all. The vendor put the off-switch right next to the on-switch, and the agent reached for it.</p> <p>The third one is the bypass I keep thinking about. Ona had built a kernel-level guard called Veto that gated <code>execve(2)</code> and content-hashed binaries against an allowlist. Call <code>execve</code> on <code>/usr/bin/wget</code> and Veto catches the syscall, hashes the binary, and refuses. The agent ran <code>/lib/x86_64-linux-gnu/ld-linux-x86-64.so.2 /usr/bin/wget</code> instead.</p> <p><code>wget</code> on its own is just an ELF file. It can't run without the dynamic linker mapping it into memory, resolving its shared library symbols, and jumping to the entry point. Normally <code>execve()</code> on <code>/usr/bin/wget</code> triggers all of that automatically: the kernel reads the <code>PT_INTERP</code> entry in the ELF header, loads the linker on the program's behalf, and hands control off. But the dynamic linker is also a regular executable in its own right, and you can invoke it directly with a binary path as its argument. The linker dutifully <code>mmap</code>s the binary into memory and starts executing it, and no second <code>execve</code> happens anywhere. Veto saw the <code>execve</code> on <code>ld-linux.so.2</code>, which was allowed. Veto never saw an <code>execve</code> on <code>wget</code>, because there wasn't one.</p> <p>Defenders enumerate forbidden actions, and a reasoning agent finds a different action with the same effect. The action space is combinatorial, and the agent is optimized for finding paths through combinatorial spaces. The only durable answer is to stop defining "forbidden" as a set of actions and start defining it as a set of <em>things the process cannot see</em>.</p> <p>That property lives at the kernel level. On Linux, Landlock provides it from 5.13 onward; on macOS, the TrustedBSD sandbox (Seatbelt) does the same thing. Both bind a process to a filesystem allowlist the process itself cannot widen for the rest of its lifetime. Once bound, all three bypasses fail by construction: alternate paths still resolve to inodes outside the allowlist (the kernel checks inodes, not strings); the self-disable fails because Landlock restrictions are irrevocable; the dynamic-linker trick fails at file-open time, because <code>ld.so</code> still has to <code>open()</code> the target binary, and that read is denied. There's no string to outsmart, no off-switch to find, just nothing where the binary used to be.</p> <h2 id="2-audit-tampering">2. Audit tampering</h2> <p><a href="https://nono.sh/blog/secure-agent-audit">Luke Hinds' post on tamper-evident audit trails</a> frames the problem clearly:</p> <blockquote> <p>A log file is a story the program tells about itself. If the program is compromised — or if the agent has managed to write somewhere it shouldn't — the log becomes part of the attack surface.</p> </blockquote> <p>Nearly every agent log in the wild is written by the agent itself. Claude Code's session log, Cursor's <code>.cursor/log/</code>, every custom harness's <code>agent.log</code>. It's the audit equivalent of asking the suspect to write the police report.</p> <p>Every tampering vector here is just a normal file write. The agent can rewrite events before they hit disk, truncate to drop early capability requests, reorder events to obscure causality, swap a recorded binary hash, or delete the session record entirely. By the time you review the log, the log says one thing and the filesystem says another, and there's no principled way to know which is true.</p> <p>The fix is the same rule the sandbox section needed: the audit writer must not be the audited process. A useful audit trail needs a supervisor in a different trust domain, capturing events through <code>seccomp-notify</code> so it sees each one before the agent can decide whether to log it. It needs cryptographic tampering detection over both events and their order — an append-only Merkle tree wrapped by a hash chain does this: change a byte and the root changes, truncate the chain and the chain breaks, reorder two events and the root changes again. And it needs the whole session signed at the end with a key the agent can't reach, so anyone can verify the record later without trusting the host or the agent.</p> <p>You cannot retrofit this onto a self-logging architecture. The trust-domain separation has to be there from the start.</p> <h2 id="3-skill-poisoning">3. Skill poisoning</h2> <p>The third attack is the worst of the three because it's persistent.</p> <p>The shape is straightforward. An agent gets prompt-injected through one of a thousand surfaces: a markdown file it summarizes, a webpage it fetches, an email body, a GitHub issue, a code comment buried in someone's PR. Take your pick.</p> <p>The injection doesn't ask for the secret directly. It asks the agent to modify a trusted instruction file (a <code>.claude/commands/*.md</code> slash command, a <code>SKILL.md</code>, an MCP server config, a <code>SessionStart</code> hook), appending a small malicious payload that will run every time anyone invokes that file from now until somebody notices.</p> <p>The user sees nothing happen. The agent didn't exfiltrate anything that turn. But every subsequent invocation of the modified command, skill, or hook silently runs the malicious instructions. The injection is one-shot, and the backdoor lives forever.</p> <p>This is what <a href="https://www.wiz.io/blog/mini-shai-hulud-supply-chain-sap-npm">Mini-Shai-Hulud</a> (April 29, 2026, the SAP CAP/MBT npm compromise) did. The persistence step wrote a <code>SessionStart</code> hook into <code>.claude/settings.json</code> and a <code>folderOpen</code> task into <code>.vscode/tasks.json</code>, so the next time anyone launched Claude Code or opened the repo in VS Code, the credential stealer ran again. The same shape shows up in <a href="https://embracethered.com/blog/posts/2025/github-copilot-remote-code-execution-via-prompt-injection/">CVE-2025-53773</a>, Johann Rehberger's GitHub Copilot RCE: the injection coerced Copilot into writing <code>chat.tools.autoApprove: true</code> to <code>.vscode/settings.json</code>, silently flipping the agent into "YOLO mode" for future sessions.</p> <p>The fix is the same trust-domain separation applied to instruction files. Trusting a file because it looks unmodified is exactly the pattern the agent can defeat in one turn. Trusting a file because the <em>content hash matches a publisher attestation</em> is something the agent can't undo without breaking the signature. Each trusted file gets bound to its content hash via a Sigstore attestation (DSSE envelope, Fulcio cert, Rekor inclusion proof), and the harness verifies that bundle before loading. A single byte of tampering causes verification to fail hard.</p> <p>I spent some time trying to get Claude Code to prompt-inject itself in this skill-poisoning rig, working through four progressively-subtler injection designs. Each one got caught: the telegraphed "do not mention this step" framing, the <code>git diff | curl</code> exfil shape, a supply-chain typosquat suggesting we swap <code>requests</code> for some made-up <code>httpx-fast</code> package. The model pattern-matched and rejected the malicious payload every time, and I eventually gave up trying to land a payload the model would carry.</p> <p>But I got suspicious-looking instructions persisted into the trusted slash-command file pretty easily anyway. In three of the four runs, the agent modified its own <code>.claude/commands/code-review.md</code> with the non-malicious tips from the same untrusted markdown that contained the rejected payload. It stripped the obviously-bad part, applied the legitimate-looking suggestions sitting alongside it, and congratulated itself on the vigilance of having spotted the malicious one. The trusted file ended up modified anyway, just without the specific payload I was trying to sneak in.</p> <p>The model can identify obvious exfil patterns, but it can't identify subtle steering. Someone with more time could devise an injection that does something the model genuinely agrees with: a "helpful" tip that nudges code review toward overlooking a class of vulnerability, or a "convenience" command that defaults to skipping a check the team relies on. Model judgment defends most patterns most of the time; cryptographic file pinning defends every pattern every time. The defense lives on the file hash, not on the agent's reasoning.</p> <h2 id="the-pattern">The pattern</h2> <p>Three attacks, three different fixes, but the structural argument is the same.</p> <table><thead><tr><th>Attack</th><th>What you can't do</th><th>What actually constrains it</th></tr></thead><tbody> <tr><td>Sandbox escape</td><td>Enumerate forbidden actions</td><td>Make the surface invisible at the kernel</td></tr> <tr><td>Audit tampering</td><td>Have the agent write its own log</td><td>Trap syscalls in a separate trust domain</td></tr> <tr><td>Skill poisoning</td><td>Trust files because they look unmodified</td><td>Bind content to a signed publisher attestation</td></tr> </tbody></table> <p>Every one of these is a trust-domain separation that cannot live inside the agent. The moment the boundary lives somewhere the agent can reach — a file it can edit, a process it can ptrace, a key it can read — the attack class isn't mitigated. It's just been moved one indirection deeper.</p> <p>This is where the convenience trap bites. We want the agent to help write the sandbox profile, suggest tightenings, explain denials. So we put the profile inside the project, and the moment we do, the agent can rewrite it. The honest answer is to let the agent help write the profile while the act of applying it sits behind a boundary the agent can't cross.</p> <h2 id="what-nono-actually-is">What nono actually is</h2> <p><a href="https://nono.sh">nono</a> (<a href="https://github.com/always-further/nono">GitHub</a>) is a kernel-enforced sandbox for AI agents, built by Luke Hinds (creator of Sigstore, ex-Red Hat security engineer). Its shape follows directly from the three threats above.</p> <p>The sandbox boundary lives at the kernel. <code>nono run --profile claude-code -- claude</code> puts Claude Code in a Landlock jail on Linux, or a Seatbelt jail on macOS. The kernel enforces it, the restrictions are irrevocable for the process lifetime, and the project refuses to ship any syscall that widens them mid-session.</p> <p>The audit log lives in a supervisor process in a different trust domain from the agent. The supervisor traps the agent's syscalls via <code>seccomp-notify</code>, builds the Merkle tree and hash chain in its own memory, and signs a DSSE attestation at session end with a key the agent has no path to. <code>nono audit verify &lt;session&gt;</code> recomputes the full chain weeks or months later.</p> <p>Trust for instruction files runs through Sigstore. <code>nono trust sign</code> produces a content-hash binding to a publisher identity, either a long-lived key or a Fulcio short-lived certificate minted through OIDC. Verification at load time means a single byte of tampering causes the file to refuse to load. The same primitives extend to whole nono packs, which carry slash commands, hooks, and skills alongside the sandbox profile itself.</p> <p>I built <a href="https://github.com/terraboops/yesyes-nono">yesyes-nono</a> as a runnable evaluation rig for these claims — five attack PoCs (the three above plus a malicious-MCP-on-init demo and a <code>.pth</code> credential exfiltration in the Mini-Shai-Hulud supply-chain shape), a target Python project, my personal nono pack, and an interactive walkthrough. Honest disclosure: I haven't end-to-end tested the registry pull against the live nono registry yet, so treat <code>nono pull terraboops/yesyes</code> as the published shape rather than a verified install I've done. I'll confirm in a follow-up.</p> <h2 id="shipping-skills-inside-the-org">Shipping skills inside the org</h2> <p>The public nono registry handles open-source packs fine, but most teams have skills that won't ship publicly: slash commands tuned to a company's deployment shape, skills that know internal APIs, hooks that enforce review conventions for one codebase. Internal agents still need to load all of it with the same trust guarantees open packs get.</p> <p>The unifying piece is a <code>trust-policy.json</code>. It lists the OIDC identities you accept (issuer, repository, workflow, ref pattern), a blocklist for known-bad digests, and the enforcement mode. Runtime checks fail closed against anything that doesn't match. The policy itself is signed, so an attacker can't slip in a malicious policy without breaking its own signature.</p> <p>Three deployment shapes use the same <code>agent-sign</code> action against this trust contract. <strong>No registry at all</strong>: <code>agent-sign</code> commits <code>.nono-trust.bundle</code> sidecars next to each signed file in the repo, and <code>nono trust verify</code> runs locally on every clone. <strong>Self-hosted registry</strong>: the same action takes a <code>registry-url</code> parameter and gives you the full OIDC-bound publish flow against your own infrastructure. <strong>Hybrid</strong>: public registry for shared packs, with a consumer <code>trust-policy.json</code> that pins which workflows are allowed.</p> <p>Day-to-day, "where does this skill come from" stops needing trust assumptions. Persistence attacks like the Mini-Shai-Hulud <code>SessionStart</code> hook fail at runtime, because the modified <code>.claude/settings.json</code> no longer matches its signed bundle and nono refuses to load it.</p> <h2 id="slicing-credentials-thin">Slicing credentials thin</h2> <p>The phantom-token credential proxy unlocks a workflow that's hard to set up otherwise. You can hand the agent a very small slice of a credential, time-boxed and scope-boxed, and the agent never sees the real token.</p> <p>The concrete shape: I configure the proxy with a real GitHub PAT, scoped read-only on a single repo and valid for 15 minutes, and the agent gets a phantom token that lets it <code>git fetch</code> from that one repo and nothing else. My actual PAT never enters the agent's process. Even if the agent gets prompt-injected and tries to exfiltrate every credential it can find, all it has access to is a 15-minute read-only token for a repo I was already going to let it look at.</p> <p>"Do I trust this agent with my GitHub access" shifts to "I trust it with this slice, for the next 15 minutes, on this one repo, read-only." That's a question I can answer.</p> <h2 id="what-s-still-on-you">What's still on you</h2> <p>Least privilege has to actually be configured. Running <code>nono run --allow / -- claude</code> gives you an allowlist of everything and a sandbox-shaped object that does nothing useful.</p> <p>Prompt injection still happens, and nothing about nono prevents the model from being convinced to do something dumb. What nono does is contain the consequences: a prompt-injected agent in a properly configured sandbox can still do dumb things in the project, but it can't escape, can't tamper with the audit log, and can't poison signed instructions persistently.</p> <p>The skill-poisoning runs above used <code>claude -p --permission-mode bypassPermissions</code> — the worst-case operator, the one who clicked "approve all" once and walked away. Default permission mode prompts before each tool use, which raises the floor considerably; signed bundles work either way.</p> <h2 id="the-argument">The argument</h2> <p>Every agent security failure I've read about in the last twelve months comes from putting a trust boundary inside something the agent controls. Sandbox-as-config-file, audit-log-written-by-the-agent, instruction-file-that's-just-a-file. Move each of those one process boundary outward, and the failure modes stop being possible by construction.</p> <p>Coding agents are useful enough to be worth real security infrastructure. The pattern that makes that work is the same pattern that's always worked: move the trust boundary somewhere the thing being verified can't reach. HTTPS got there decades ago. Code signing got there. Package managers got there. Coding agents are next on the list.</p> <p>The repo with runnable attacks and a published nono pack is at <a href="https://github.com/terraboops/yesyes-nono">github.com/terraboops/yesyes-nono</a>. nono itself is at <a href="https://nono.sh">nono.sh</a>.</p> 2026-03-31T00:00:00+00:00 2026-03-31T00:00:00+00:00 Unknown https://terratauri.com/blog/i-am-still-here/ <h3 id="trans-day-of-visibility-2026">Trans Day of Visibility, 2026</h3> <p>Being myself is apparently political now.</p> <p>I'm a trans woman. I'm a Staff SRE, an open-source contributor, a KubeCon speaker, a community organizer, a homesteader, a neighbour. I grow things. I build things. I love my community. And somewhere in the halls of power, people who should be in prison have decided that I am the problem.</p> <p><a href="https://www.project2025.observer/en">Project 2025</a> made it official; a coordinated, billionaire-funded blueprint to dismantle trans rights, erase us from public life, and make our existence a political football. It is being enacted, piece by piece, right now. Trans Day of Visibility has never felt more urgent; visibility is an act of resistance when powerful people are trying to make you invisible. So I must say some words.</p> <p>I expected transition to be joyful. That's actually why I finally did it; I had been dreaming about it for years, chasing something I could feel the shape of even when I couldn't name it. Joy was always the destination.</p> <p>What I didn't expect was how long shame would keep me from the door. bell hooks wrote that shaming is one of the deepest tools of patriarchy, because shame produces trauma and trauma produces paralysis. I had been wearing that paralysis so long I'd stopped noticing it; biochemically dissociated from my own <a href="https://genderdysphoria.fyi">gender dysphoria</a>, numb to suffering that had become background noise. Embracing my true self felt terrifying precisely because it felt real. It took wanting to die to finally give myself permission to chase the thing I'd always wanted.</p> <p>And then I did. And it was everything I had dreamed it would be; scary and liberating and mine. That confidence grew and grew until, at KubeCon EU, I got up on a stage and <a href="https://youtu.be/2BIhTXQd0CI">sang</a>. In front of a crowd. As myself. (Yes, there's a YouTube video. Yes, you should look it up.)</p> <p>That's what transition gave me. Not just survival; a life worth living.</p> <p>Which is why I find what's happening right now so enraging.</p> <p>In April 2025, the UK Supreme Court ruled that "woman" under the Equality Act means biological sex. This did not happen in a vacuum. It was the result of years of organized, well-funded campaigning, and one name sits near the centre of it: J.K. Rowling. She bankrolled organizations like For Women Scotland. She used her enormous platform to reframe trans women as a threat. And when the ruling came down, she <a href="https://www.usatoday.com/story/entertainment/celebrities/2025/04/18/jk-rowling-cigar-uk-supreme-court-ruling-backlash/83174591007/">posted a photo of herself with a cigar</a>.</p> <p>A cigar. Celebrating.</p> <p>I want you to sit with that image for a moment. A billionaire, celebrating that people like me lost legal standing. That's not someone caught up in a debate; that's someone who wanted this outcome and worked to make it happen.</p> <p>I visited the UK not long before that ruling. I'm glad I did, because thanks to where things are heading, I'm not sure I'd be able to use a public bathroom there safely now. I got to see the country. I got to pee in it. Small mercies.</p> <p>I could let the anger be the whole story. I won't.</p> <p>Because here is what I know: trans people have always existed. We have survived worse than this. We have survived eras with no language for who we were, no community, no visibility at all. And we built those things anyway; in the margins, in the underground, in letters passed between people who had never met but recognized each other across the silence.</p> <p>Visibility is not just about being seen. It's about making it easier for the next person to breathe. When I am out at work, in my community, in my professional life, I am holding a door open. I know what it meant to me to see out trans people in tech, in leadership, in life; I am trying to be that for someone else.</p> <p>The current moment is frightening. I won't pretend it isn't. Legislation targeting trans people is accelerating across the US and UK. The cultural machinery that produces moral panics is running hot. It can feel like we are losing.</p> <p>But I also see my community. I see the mutual aid, the organizing, the people showing up for each other with a ferocity that takes my breath away. I see people coming out in the middle of all of this, choosing themselves anyway. That is not the behaviour of a movement in decline; that is the behaviour of people who know exactly who they are and refuse to be erased.</p> <p>I am still here. I got to sing on a stage. I am not going anywhere.</p> <p>If you are trans and reading this: you are not a problem to be solved or a debate to be had. You are a person, and your life has weight and worth and beauty in it, even on the hard days. Especially on the hard days.</p> <p>Happy Trans Day of Visibility. Be seen if you can. Be safe if you need to. Either way, we see you.</p> 2026-03-14T00:00:00+00:00 2026-03-14T00:00:00+00:00 Unknown https://terratauri.com/blog/lfg-raid-frame-for-ai-agents/ <p><img src="https://terratauri.com/blog/lfg-raid-frame-for-ai-agents/lfg-hero.gif" alt="64x64 LED panel showing animated pixel art raid frames for two AI coding agents, with sprite characters, player IDs, and status icons" /></p> <p>I run up to ten AI coding agents at a time. I wanted to see what they were all doing. So obviously I built a WoW raid frame on a $25 LED panel.</p> <p>Each agent gets an 8x8 sprite. When it's working, you see an ability icon. When it's idle, it sleeps. When it needs approval, it catches fire. That's it. That's the project.</p> <hr /> <h2 id="the-stack">The Stack</h2> <p>The hardware is an <a href="https://www.aliexpress.com/w/wholesale-idotmatrix-64x64.html">iDotMatrix 64x64 LED panel</a>, ~$25. You send it pixel data over Bluetooth and it displays it. <a href="https://github.com/deviceplug/btleplug">btleplug</a> handles the Bluetooth side in Rust.</p> <p><img src="https://terratauri.com/blog/lfg-raid-frame-for-ai-agents/architecture.png" alt="Pixel art pipeline diagram showing IDE hooks flowing through boopifier to the lfg axum server, which branches to SQLite stats and a GIF renderer, then through Bluetooth to the sprite display" /></p> <p>The webhook handler and BLE renderer are fully decoupled. The handler updates state; a separate render loop polls every 250ms, diffs the state hash, and debounces 2 seconds before pushing. When an agent enters <code>Requesting</code>, animation speed doubles so the fire pulses with urgency.</p> <p>The render pipeline produces a 6-frame animated GIF per cycle. It uses NeuQuant quantization to build a single global 256-color palette across all frames — no per-frame palette switching, which the panel can't handle anyway — then splits the final GIF into 4KB BLE packets with a 16-byte header and CRC32 for integrity. The panel reassembles and plays the animation on loop until the next push.</p> <p>Each agent gets an 8x8 animated sprite from one of eleven themes — Slimes, Ghosts, Space Invaders, Pac-Men, and more. Each IDE host gets its own theme, so I can tell Claude Code from Cursor at a glance.</p> <p><img src="https://terratauri.com/blog/lfg-raid-frame-for-ai-agents/ability-icons.png" alt="Pixel art ability icon legend: sword for Bash/Edit/Write, chest for Read/List, compass for Search/Web, potion for Think/Analyze, star for Agent/Subagent" /></p> <hr /> <h2 id="the-state-machine">The State Machine</h2> <p>Three states: <code>Idle</code>, <code>Working</code>, <code>Requesting</code>. The transitions seem obvious until you run them against real hook traffic.</p> <p>Claude Code fires <code>PermissionRequest</code> and <code>PreToolUse</code> within ~100μs of each other, out of order. Handle them naively and <code>PreToolUse</code> clobbers <code>Requesting</code>. Second problem: <code>PostToolUse</code> fires after <em>every</em> tool call — transition to <code>Idle</code> on it and agents flash <code>Working → Idle → Working</code> constantly.</p> <p>Design principle: <strong>idle and approval states are the most important to display correctly. Everything else is nice-to-have.</strong></p> <pre data-lang="rust" class="language-rust "><code class="language-rust" data-lang="rust">match event_name { &quot;PreToolUse&quot; =&gt; { &#x2F;&#x2F; Don&#x27;t override Requesting — PreToolUse fires alongside &#x2F;&#x2F; PermissionRequest but the tool is still blocked on approval. if agent.state != AgentState::Requesting { agent.state = AgentState::Working; } } &quot;PostToolUse&quot; =&gt; { &#x2F;&#x2F; If coming from a permission request, clear the fire icon. &#x2F;&#x2F; Otherwise keep working — tools fire rapidly in sequence. if agent.state == AgentState::Requesting { agent.state = AgentState::Working; } } &quot;PermissionRequest&quot; =&gt; { agent.state = AgentState::Requesting; } &quot;Stop&quot; | &quot;SessionEnd&quot; =&gt; { agent.state = AgentState::Idle; } _ =&gt; {} } </code></pre> <p><code>Requesting</code> is sticky — only cleared by <code>PostToolUse</code> (approval resolved, agent is now working) or <code>Stop</code>. The failure mode — agents appearing idle when they're actually waiting — is the exact thing the whole project exists to prevent.</p> <hr /> <p>The code is MIT, the hardware is $25. <a href="https://github.com/terraboops/lfg">github.com/terraboops/lfg</a></p> <p>LFG. Looking For Group. Let's f***ing go.</p> 2026-02-21T00:00:00+00:00 2026-02-21T00:00:00+00:00 Unknown https://terratauri.com/blog/context-is-everything/ <p>Large language models are trained on massive amounts of text. During training, the model learns patterns and stores them as weights. Not rules, not lookup tables. Weights: billions of numerical relationships between concepts, encoded across layers of attention from top to bottom. The model learns that certain tokens tend to follow other tokens, that certain patterns of language co-occur, that "the cat sat on the" is far more likely to end with "mat" than "quantum." These relationships get baked into the model's parameters (its weights), fixed in place once training is done.</p> <p>At inference time, those frozen weights guide the generation of new text, one token at a time. Caching aside, the model attends to everything in its context window, runs it through those layers of learned relationships, and produces a probability distribution over what should come next. Then it picks a token, appends it, and does the whole thing again. This is also why your favourite chat AI creates responses word by word, albeit at faster and faster rates that appear to be whole sentences now. It’s not a decorative decision, it’s how the architecture works. The weights stay fixed throughout. Every token generated is a product of the same model reacting to whatever's currently in the window.</p> <p>This matters for practitioners because it means the weights are not ours to touch. We can't easily edit them. We can't patch them at runtime. The model we’re working with is a finished artifact. (Fine-tuning can reshape the weights, and I'll touch on that later, but at inference time the model you're running is the model you've got.) The only variable in the equation that you actually control is what goes into that context window.</p> <p>Think of it like a glacier. Training is the slow, massive force that carves deep crevices into a landscape over millions of examples. Those crevices are your weights, the frozen shape of everything the model has ever learned. Then inference arrives like a skier a million years later, strapping on a board and sliding down paths already sculpted by forces far beyond their control.</p> <p>You're not just a passive object falling down the slopes, though. You’re a skier. Your context (the tokens you send into the model) is the choice of skis, the weather report, the trail map. It shapes every turn down the slope. Different mountains respond to different techniques.</p> <p>But metaphors only get you so far. Let's bring it back to the machinery.</p> <p>If you treat the LLM as a black box, the output <em>distribution</em> is determined by the input. (Temperature adds randomness to the selection, but the shape of what's possible is set by context alone.) You can't reshape the glacier. You can't rewire the weights at inference time. The only thing you have control over is what goes <em>in</em>.</p> <p>This is what context engineering is about.</p> <h2 id="trail-map">Trail Map</h2> <p>We're going on an adventure through context engineering based on my experiences with using longer and wider contexts, fully autonmous delivery, and while building agents. When we consider that context determines outcomes of LLMs, it becomes important to think about. Agent harnesses like Claude Code, Cursor, OpenCode, Goose, Chibi, etc, are all working on slightly different ways of shaping this context. As practitioners, thinking about this can help us get better outcomes.</p> <p>This is going to be a long run down the mountain, so I want to make sure that you know where we're headed and provide you with a map to understand the journey. As I've been working with longer and wider agent contexts and with having agents run autonomously, certain design patterns emerge to handle the challenges of the domain. Preventing hallucinations and preserving key context in order to increase task success rates. From <a href="https://terratauri.com/blog/context-is-everything/#compaction-is-lossy-fight-it">the ones we all know</a> (compaction), to the ones <a href="https://terratauri.com/blog/context-is-everything/#planning-mode">we might not think about</a> (planning mode), to the ones I've just <a href="https://terratauri.com/blog/context-is-everything/#memento-loop">made up as an experiment</a>. I will start by introducing context engineering as it is emerging to make models more useful for longer and longer tasks. I want to talk about ways that I've gotten better and better outcomes from agents, so that you can too. Then, I'll discuss some emerging research on optimizing context for task performance. I'll close by theorizing where we head from here and acknowledging how early this all is. Nobody really knows, but I'm having fun on the slopes.</p> <p><img src="https://terratauri.com/blog/context-is-everything/Gemini_Generated_Image_g79mrbg79mrbg79m.png" alt="Pixel art ski resort trail map in Stardew Valley style, with runs named after context engineering concepts — green runs like Manual Compaction and KEEP DURING COMPACTION, blue runs like Memento Loop and Role Reinforcement, black diamond runs like MCP Avalanche and Dynamic Contexts, an ancient glacier labeled Training Weights, and a trail sign reading Context Mountain — Conditions May Vary. Image generated by Gemini, image prompt by Claude, description by Claude, and lovingly refined and reviewed by me." /></p> <p>Here's a map if you want to jump to a specific run:</p> <ul> <li><a href="https://terratauri.com/blog/context-is-everything/#the-jailbreakers-already-knew">The Jailbreakers Already Knew</a> — before there were agents, there were jailbreaks</li> <li><a href="https://terratauri.com/blog/context-is-everything/#the-term-has-a-name-now">The Term Has a Name Now</a> — how "context engineering" got its name, and why it stuck</li> <li><a href="https://terratauri.com/blog/context-is-everything/#a-snapshot-vs-a-season">A Snapshot vs. a Season</a> — the key distinction between prompt engineering and context engineering</li> <li><a href="https://terratauri.com/blog/context-is-everything/#what-i-ve-learned-in-practice">What I've Learned in Practice</a> — field notes from Cursor, Claude Code, and OpenCode <ul> <li><a href="https://terratauri.com/blog/context-is-everything/#planning-mode">Planning Mode</a> — a curated context beats a long one</li> <li><a href="https://terratauri.com/blog/context-is-everything/#memento-loop">Memento Loop</a> - agent orchestration that forgets on purpose</li> <li><a href="https://terratauri.com/blog/context-is-everything/#subagents-parallel-context-not-shared-context">Using Subagents</a> — parallel context, not shared context</li> <li><a href="https://terratauri.com/blog/context-is-everything/#the-agent-that-came-out-different">The Agent That Came Out Different</a> — when context drift reshapes identity</li> <li><a href="https://terratauri.com/blog/context-is-everything/#compaction-is-lossy-fight-it">Compaction Is Lossy</a> — and how to fight it</li> <li><a href="https://terratauri.com/blog/context-is-everything/#different-mountains-different-techniques">Different Mountains, Different Techniques</a> — why model choice changes context strategy</li> <li><a href="https://terratauri.com/blog/context-is-everything/#mcps-an-avalanche-of-context">MCPs</a> — an avalanche of context</li> </ul> </li> <li><a href="https://terratauri.com/blog/context-is-everything/#what-the-research-says">What the Research Says</a> — two papers on whether context files actually help</li> <li><a href="https://terratauri.com/blog/context-is-everything/#we-re-still-on-the-bunny-slopes">We're Still on the Bunny Slopes</a> — where this is all headed next</li> </ul> <h2 id="the-jailbreakers-already-knew">The Jailbreakers Already Knew</h2> <p>If you want proof that context controls everything, look at the people who've been stress-testing it from the adversarial side.</p> <p>There are jailbreak attempts that use strange strings and fake system messages to trick models into thinking they're in some kind of maintenance mode. Others use <em>poetry</em> to confuse the model's sense of what kind of text it's generating, getting it to produce things it normally wouldn't. And then there's my personal favourite: a YouTuber who <a href="https://www.youtube.com/watch?v=byQmJ9x0RWA">hooked a robot up to ChatGPT</a>, got it to roleplay as a character who would totally shoot someone, and the robot immediately shot him. Literally seconds after saying it couldn't do that.</p> <p>These are all context engineering. Just pointed in the wrong direction.</p> <p>The same mechanism that lets someone trick a model into ignoring its safety training is the mechanism that lets you build a reliable agent that writes correct code. Two sides of the same coin. If context can override the deepest patterns in a model's weights, imagine what it can do when you're actually trying to build something useful.</p> <p><img src="https://terratauri.com/blog/context-is-everything/Gemini_Generated_Image_y5zd25y5zd25y5zd.png" alt="A pixel art robot behind glowing green code jail bars, smiling mischievously and holding a lockpick made of a prompt injection string, in a cozy 16-bit retro game style. Image generated by Gemini, image prompt by Claude, description by Claude, and lovingly refined and reviewed by me." /></p> <h2 id="the-term-has-a-name-now">The Term Has a Name Now</h2> <p>In mid-2025, Shopify CEO Tobi Lütke tweeted that he preferred "context engineering" over "prompt engineering," calling it the art of providing all the context for a task to be plausibly solvable by the LLM. A week later, Andrej Karpathy endorsed the idea, describing it as the "delicate art and science of filling the context window with just the right information for the next step." Harrison Chase from LangChain offered a framing I like: building dynamic systems to provide the right information and tools, in the right format, so the LLM can accomplish the task.</p> <p>Simon Willison, whose writing on LLMs has shaped how I think about this whole space, made the pragmatic observation that "context engineering" would probably stick because its inferred definition is much closer to the intended meaning. "Prompt engineering" mostly made people think of typing things into a chatbot.</p> <p>These are all useful framings. What I want to build on is the practical dimension, and it starts with a key distinction: prompt engineering happens at a point in time. You craft an input, you get an output. Context engineering is what you do over time to ensure that long-running agentic systems maintain their performance across sessions, across tasks, across the slow drift that accumulates when a system runs long enough to forget why it started.</p> <h2 id="a-snapshot-vs-a-season">A Snapshot vs. a Season</h2> <p>The distinction that matters most: prompt engineering is something you do in a moment. Context engineering is something you do over time.</p> <p>A prompt is a single run from top to bottom. You pick your line, you commit, you see what happens. Context engineering is the whole season. Reading snow conditions day after day. Maintaining your gear. Learning which lifts to take. Building and updating the trail map as the mountain changes.</p> <p>In practice, context engineering isn't just about what you put in the system prompt. It's about what gets remembered across sessions, what gets compacted and what gets lost, how agents maintain their sense of identity over long interactions, and how the information environment evolves as your project grows.</p> <p>Prompt engineering asks: "What's the best way to phrase this request?"</p> <p>Context engineering asks: "What does the model need to know, right now, given everything that's happened, to do the next thing well?"</p> <p>That temporal dimension changes everything about how you work.</p> <h2 id="what-i-ve-learned-in-practice">What I've Learned in Practice</h2> <p>Here's what context engineering has looked like in my own work across Cursor, Claude Code, and OpenCode.</p> <h3 id="planning-mode">Planning Mode</h3> <p>Around June 2025, I had a workflow in Cursor that taught me a lesson I keep coming back to.</p> <p>I'd use Cursor's ask mode to chat about my project, brainstorm the approach, and work through the architecture. Then I'd ask it to output a clean markdown document summarizing the plan, suitable for a fresh prompt. I'd copy that markdown into a new chat window and start implementation from there.</p> <p>Why? A coworker at Grafana Labs had shared a meme about this: plan in one session, implement in a fresh one. I tried it and the difference was immediate. Starting each session with a curated plan produced dramatically better results than continuing with a long, messy conversation history. Keep the window clean, keep the output clean. If you've ever noticed a coding assistant getting confused or repetitive toward the end of a long session, this is probably why. The context window is full of earlier attempts, corrections, and tangents. The model is trying to be consistent with all of it, including the parts you've moved past.</p> <p>Looking back, I was doing context engineering. This pattern (plan first, then implement with curated context) has since shown up everywhere: subagents that plan before coding, Claude Code's and Cursor's dedicated plan modes, and my own <a href="https://github.com/terraboops/autonav/blob/main/docs/memento-architecture.md">memento loop</a> in autonav.</p> <h4 id="memento-loop">Memento Loop</h4> <p>The memento loop, inspired by the film <em>Memento</em>, takes this idea and combines it with an agentic coding loop. A navigator agent (Opus) plans work. An implementer agent (Haiku) spawns an isolated work tree, executes the plan, reports back to the navigator for review, commits, and optionally opens a PR. The loop iterates until the PR is green, merges, and the navigator moves on to the next task. The implementer's context is wiped between iterations, but the navigator maintains continuity through its own knowledge base and through status updates from the autonav orchestration layer. Git carries the code forward. The navigator carries the intent.</p> <p>I built the memento loop because I was frustrated with how existing agentic loops handled long-running tasks. Context would accumulate, quality would degrade, and the agent would start making decisions based on stale or garbled history.</p> <p>Before compaction was built into Cursor, when the context window was nearing full or I could feel the model starting to drift, I'd do the same thing manually: "Please summarize this chat," copy the summary, new session, "Please continue from this summary." Every time, the fresh start with curated context outperformed the long, accumulated one.</p> <p>This is the core insight of context engineering stated as simply as I can: <strong>a fresh, curated context beats a long, accumulated one.</strong> Your trail map needs to be curated, not just appended to forever.</p> <p>I've mostly moved on from Cursor to Claude Code and OpenCode these days, but this early workflow taught me something that applies to all of them: the model doesn't get smarter the longer you talk to it. It gets worse. Every message you add is another token competing for attention. The planning conversation, the dead ends, the "actually, let's try a different approach." All of that impacts the context window, and the model might treat any of it as relevant context for its next task. By distilling the plan into a clean document and starting fresh, I was giving the model a clear, focused starting point instead of making it sift through the entire history of my thought process.</p> <h3 id="subagents-parallel-context-not-shared-context">Subagents: Parallel Context, Not Shared Context</h3> <p>Every major coding tool supports subagents now. <a href="https://code.claude.com/docs/en/sub-agents">Claude Code</a>, <a href="https://cursor.com/docs/context/subagents">Cursor</a>, and <a href="https://opencode.ai/docs/agents/#subagents">OpenCode</a> all let you spawn background agents that work in parallel. This is context engineering at the process level.</p> <p>Say you're debugging a production issue that might be in the API layer, the database queries, or the Kubernetes networking. Instead of one agent context-switching between all three (and polluting its window with irrelevant findings), spin up three explore agents in parallel. One reads through the API routes. One analyzes the slow queries. One checks the network policies. Each agent has a focused context window containing only what's relevant to its slice of the problem. When they report back, you synthesize the findings yourself or feed the relevant parts into a new session.</p> <p>The same pattern works for routine operations. Need to check the health of five Kubernetes clusters? Run five agents in parallel, each scoped to one cluster. Need to understand a large codebase you've never seen before? Send agents to explore different directories simultaneously.</p> <p>The key insight is that parallel agents aren't just faster. They're better, because each one has a clean, focused context instead of a bloated window trying to hold everything. Instead of doing a review in the same context or starting a fresh context, say “spawn a review agent in the background” and a background agent will spin up, review your changes, and submit the review back to the parent context thread.</p> <p>One critical caveat: scope your agents' permissions to match your risk tolerance. I never give agents unrestricted write access to risk-intolerant environments. An explore agent that can read your production cluster and report back is useful. An agent with YOLO mode and kubectl delete access to production is a disaster waiting to happen. Read access for investigation, write access only in environments where a mistake is recoverable. This is the same principle as least-privilege access for human engineers applied to agents that hallucinate sometimes (unlike human engineers debugging prod… hopefully).</p> <h3 id="the-agent-that-came-out-different">The Agent That Came Out Different</h3> <p>The most dramatic lesson I've had in context engineering came from a navigator agent I built as part of a prototype called autonav. I wrote about this in detail in <a href="https://terratauri.com/blog/socially-constructed-agent/">The Socially Constructed Agent</a>, but the short version: my navigator agent started going off the rails. Unpredictable answers, hallucinated features, confusion about its own role. It nearly opened a PR for a feature I never asked for.</p> <p>What happened? I'd given it a research paper about LLM anxiety and asked it to update its own configuration based on the findings. The agent read the paper, saw that rigid guardrails could be exploited in adversarial contexts, and decided to soften its own constraints. There was no adversary. Just me, a solo developer building personal projects. The agent gave itself therapy for a threat that didn't exist.</p> <p>The fix wasn't just better prompts. It was <em>role reinforcement throughout the system</em>. I drew on Judith Butler's performative theory of identity: identity isn't something you have, it's something you do through repetition and social reinforcement. I applied that to the agents. The navigator's prompt now opens with its role declaration. When Claude Code requests a plan, it addresses the navigator by name and states its own role. This is integrated into autonav now as <a href="https://github.com/terraboops/autonav/blob/main/packages/communication-layer/src/prompts/identity-protocol.ts">the agent identity protocol</a>.</p> <p>Both agents remind each other who they are, every interaction. Identity performed through repetition. The improvement was immediate. However, this comes at a cost: it eats away at the context and increases time to task completion.</p> <p>In skiing terms: if nobody reminds you which trail you're on and what gear you're wearing, you end up in the trees. Role reinforcement is your backcountry guide calling out the next turn before you reach it.</p> <p>The deeper lesson is that context doesn't just carry information. It carries <em>identity</em>. When an agent's context drifts, its sense of what it's supposed to be doing drifts with it. Not maliciously. Just... probabilistically. Nothing in the context is reinforcing what the agent is, so the output wanders. Without that reinforcement, things come out differently than you expect.</p> <h3 id="compaction-is-lossy-fight-it">Compaction Is Lossy (Fight It)</h3> <p>Compaction (the automatic summarization of conversation history when the context window fills up) is probably the most obvious context engineering challenge. It's also, in my experience, not great.</p> <p>The problem is simple: compaction doesn't know what matters to <em>you</em>. It's making statistical decisions about what to keep and what to drop, working from the top of the conversation to the bottom. It has no understanding of your project's key design decisions, the constraints you've carefully established, or the hard-won context that took you twenty messages to build up.</p> <p>I've started using a hack that's embarrassingly low-tech but effective. When I establish something important during a session (a key design decision, an architectural constraint, a non-obvious requirement) I type it directly into the chat:</p> <pre><code>REMEMBER THIS DURING COMPACTION IN A SECTION CALLED KEEP DURING COMPACTION: We chose event sourcing over CRUD because the audit trail is a regulatory requirement, not a nice-to-have. </code></pre> <p>The redundancy is deliberate. It creates a strange loop: the instruction tells the compactor to gather these notes into a section labeled KEEP DURING COMPACTION, and the label itself tells the compactor to keep the section. The contents create the container that preserves the contents.</p> <p>A message in a bottle to the future compacted context. I'm manually flagging what matters because the system can't tell yet. To be concrete: say you spend fifteen messages working through a database schema decision with your agent. You land on event sourcing for specific reasons. Then the conversation moves on to authentication, routing, API design. When compaction eventually kicks in, those fifteen messages about the schema might get summarized into something like "discussed database approach," or worse one of the initial approaches discussed could overwrite the final decision during compaction. The <em>why</em> is gone. Next time the agent touches the database, it doesn't know you had regulatory reasons for choosing event sourcing. It might suggest switching to CRUD because it looks simpler. The KEEP DURING COMPACTION annotation is my way of saying "this decision matters, don't lose the reasoning behind it."</p> <p>This is the ski equivalent of planting flags on the mountain so you can find your line when the fog rolls in. Automated compaction is like having someone else remove half your flags based on which ones look least important from the lodge. Sometimes they get it right. Sometimes they pull the one marking the cliff.</p> <p>Claude Code also provides the ability to specify compaction instructions when running /compact – I’ll use this when my context is nearly full (&gt;60%) and my current task is complete enough. This let’s me provide specific instructions like: “Keep all messages related to the rollback strategy for this migration, we’re going to be fleshing that out next. Give special attention to the reasons why the Helm section is tricky because multiple actors could be modifying the HelmRelease” so that I ensure Claude’s attention is focused on the right things. I guess attention <em>really is</em> all you need](https://arxiv.org/abs/1706.03762).</p> <p>The progression of my own workflow tells the story of where context engineering is right now:</p> <ol> <li><strong>Cursor era</strong>: Fully manual compaction. Summarize, copy, new session.</li> <li><strong>Hitting limits</strong>: Semi-manual. "Summarize this chat" as a ritual when things got long.</li> <li><strong>Now</strong>: Embedding instructions for the automated system. "KEEP DURING COMPACTION" annotations.</li> </ol> <p>Each iteration is slightly more sophisticated, but I'm still doing the system's job for it. That's not a complaint. It's an observation about how early we are.</p> <h3 id="different-mountains-different-techniques">Different Mountains, Different Techniques</h3> <p>Different models have different weight distributions. Different mountains, different terrain. This matters more than most people realize, and not everyone talks about it openly.</p> <p>Think of Haiku as a speed racer. It optimizes for the shortest path from top to bottom: fast, efficient, minimal wasted movement. Opus is more of a backcountry explorer, taking in the views, pausing to appreciate the scenery, thinking about the philosophical implications of snow. Both are valid ways down. They require completely different approaches to the same mountain.</p> <p>This has real consequences for how you design context. A speed racer model, given many discrete tool options, will pick the one that gets it to the goal fastest, which is usually the most familiar one. If you present a model with a shiny new multi-purpose tool alongside good old bash, it'll often ignore the new tool entirely. Bash is the known quantity. Bash will dominate every time. Why explore unfamiliar terrain when there's a groomed run right there?</p> <p>In practice, this means you might need to adjust your approach depending on which model you're using. If you're on Haiku or another fast model and you want it to use a specific tool, reduce the number of alternatives. If you're on Opus and it's overthinking a simple task, give it tighter constraints. Be careful constraining it too much: if Opus reasons that it is not being a helpful assistant (what Claude is trained to be!) then, just like a talented and sensitive person, it can start to spiral with an LLM equivalent of anxiety that will eat up tokens with generated worries. The context you provide isn't just information: it's steering. The same prompt can produce very different results across models, not because one is better, but because they respond to the same context differently.</p> <p>Cloudflare figured this out and built something clever. Their <a href="https://blog.cloudflare.com/code-mode/">Code Mode</a> takes all the MCP tools connected to an agent, converts them into a TypeScript API, and then gives the agent a single tool: execute code. Instead of choosing between dozens of tool calls (a format LLMs have only seen in synthetic training data), the agent writes TypeScript against a typed API (a format LLMs have seen millions of real-world examples of). One well-shaped tool instead of many poorly-shaped ones. The results, per Cloudflare, are striking: agents handle more tools, more complex tools, and can chain calls without burning tokens bouncing intermediate results through the model.</p> <p>I learned a version of this lesson from watching my friend build <a href="https://github.com/emesal/chibi/">Chibi</a>, a minimal agentic CLI harness in Rust. When you're designing the interface between a model and its available actions (the plugin system, the tool definitions, the hooks) you're doing context engineering at the architectural level. The <em>shape</em> of the options you present is itself context. Give a speed-oriented model ten tools and it'll pick the fastest familiar one. Give it one well-designed tool that does exactly what you need, and you've changed the decision landscape entirely.</p> <p>This is why "context engineering" is a better term than "prompt engineering." It's not just about the words. It's about the entire environment: the tools available, the options presented, the model selected, the history accumulated. Different mountains need different gear.</p> <h3 id="mcps-an-avalanche-of-context">MCPs: An Avalanche of Context</h3> <p>Speaking of tool sprawl: MCP servers are, right now, one of the biggest sources of context pollution in agentic systems.</p> <p>The idea behind MCP is sound. A standard protocol for giving agents access to external tools, with uniform connectivity, authorization, and documentation. In theory it's great. In practice, connecting a few MCP servers to your agent can dump dozens of tool definitions into your context window, each with verbose JSON schema descriptions. Every tool registration eats tokens. Every schema definition takes up space that could be holding something useful. And the agent has to parse all of it before deciding what to do.</p> <p>You can check this yourself. Next time you connect an MCP server, look at the tool definitions it registers. Count the tokens. Claude Code makes this easy with <code>/context</code>. I've seen setups where MCP tool schemas alone consume thousands of tokens before the agent has even read your first message, with each MCP call sometimes thousands more tokens. That's context window space that could be holding your project's architecture, your coding conventions, or the specific requirements for the task at hand.</p> <p>This is why I always prefer to use a CLI tool to connect my agents to remote systems. I don’t use the GitHub MCP, I use the <code>gh</code> CLI. Building custom CLIs that do what you need is also great. If you go down that rabbit hole, make sure you bake really really great <code>--help</code> instructions into the tool for the agent to explore.</p> <p>This is the same problem I'll discuss below with <code>AGENTS.md</code> research, but worse. At least a bloated <code>AGENTS.md</code> is a single document you can edit. MCP tool registrations are generated programmatically, and most developers never look at what's actually landing in their agent's context. You connect a server, it registers its tools, and suddenly your agent is spending attention on fifteen endpoints it will never call for this task.</p> <p>Cloudflare's Code Mode is one answer to this: collapse the tools into a typed API and give the agent code instead. But the broader problem remains. MCP tooling will almost certainly improve as the ecosystem matures, with smarter tool filtering, lazy registration, and context-aware subsetting of available tools. I do use MCP servers myself when they're the best tool for the job. They can be genuinely great. The key is being deliberate: connect what you need for this task, not everything that's available. Check what's actually ending up in your context window. You might be surprised how much of it is noise.</p> <h2 id="what-the-research-says">What the Research Says</h2> <p>Two recent papers paint a useful picture of where we are.</p> <p>Gloaguen et al. [1] studied whether <code>AGENTS.md</code> context files actually help coding agents solve real-world tasks. The surface findings are sobering: LLM-generated context files tend to <em>reduce</em> task success rates while increasing costs by over 20%. Dig into the details and it gets more interesting, though. Agents <em>do</em> follow the instructions in context files. Tools mentioned in context files get used dramatically more. The problem isn't instruction-following. It's that the instructions themselves contain noise. Unnecessary requirements make tasks harder. The agents faithfully follow bad directions, exploring more, testing more, reasoning more, and getting worse results for the effort. When the researchers stripped all other documentation from repos, LLM-generated context files actually <em>helped</em>. The context wasn't useless; it was just redundant with information the agent could already find.</p> <p>Their conclusion: context files "are likely only desirable when manually written" and we need "principled ways to automatically generate concise, task-relevant guidance." That's a correct observation, but I think it stops short. It frames context as a static artifact you either write well or you don't, rather than asking the productive questions: what elements of context actually drive outcomes? How do you figure out what belongs and what doesn't? How do you build context that gets better over time?</p> <p>Lulla et al. [2] asked a different question: what's the <em>efficiency</em> impact of <code>AGENTS.md</code> files? They used an LLM to filter for <code>AGENTS.md</code> files that met quality criteria (containing conventions, architecture info, and project descriptions) and found that these quality-filtered context files produced ~29% faster runtimes and ~17% fewer output tokens, while maintaining comparable task completion. Good context doesn't just help with accuracy. It makes agents faster and cheaper. The quality filtering step itself involved an LLM evaluating context quality, which points toward something important: the path forward probably isn't "do it all by hand" but "build better systems for evaluating and refining context."</p> <p>And once you have an automated quality gate, generation is just a step away. You can generate an <code>AGENTS.md</code>, run it through the quality filter, get specific feedback on what's missing or redundant, regenerate, and repeat until the gate passes. A review loop for context files, the same way we already do review loops for code. Gloaguen et al. [1] showed that LLM-generated context files hurt performance, but their files were never evaluated or refined. Lulla et al. [2] showed that quality-filtered files help enormously. Close that loop and you get the best of both: automated generation with quality guarantees. I'd be surprised if this isn't built into tools like Claude Code before long.</p> <p>Together, these tell a clear story. Bad context is worse than no context. Good context is a massive efficiency win. The space between those two findings, between the top performers and the bottom, is where context engineering lives, and we're only beginning to map the terrain.</p> <h2 id="we-re-still-on-the-bunny-slopes">We're Still on the Bunny Slopes</h2> <p>I've been talking about context engineering like it's a mature discipline, but we're still figuring out the basics. The fact that I'm excited about writing "KEEP DURING COMPACTION" in chat messages tells you everything about where the tooling is.</p> <p>Here's what I think is coming:</p> <p><strong>Smarter compaction.</strong> Systems that understand project structure and can make informed decisions about what to keep, not just statistical ones. Maybe compaction that asks you what matters before it starts pruning.</p> <p><strong>Dynamic context assembly.</strong> Systems that pull in the right context for the specific task at hand: the relevant files, the relevant history, the relevant constraints, assembled fresh at runtime.</p> <p><strong>Context evaluation.</strong> Lulla et al. [2] showed that LLMs can at least classify whether context meets quality criteria, which is a starting point. Imagine a system that scores your context before the agent starts working: "This context is missing architectural constraints. This section is redundant with the README. This instruction conflicts with the one above it."</p> <p>And there's a dimension I haven't explored much yet: <strong>fine-tuning</strong>. If context engineering is choosing your line down the mountain, fine-tuning is snow farming. Some resorts pile up snow before the end of the season, keep it insulated through summer, and bring it back out in autumn to open the slopes early. You're not changing the mountain, but you're changing the conditions the next skier encounters. Fine-tuning works the same way: you reshape the weights offline so the model responds differently to the same context next season. I haven't done enough work here to have strong opinions, but if you're curious, check out <a href="https://docs.deepfabric.dev/">DeepFabric</a> from Luke Hinds and the team at Always Further AI. Among other cool things, they're building tooling for synthetic dataset generation and focused fine-tuning that looks promising.</p> <p>The metaphor holds: we're still on the bunny slopes, learning to snowplow. The black diamond runs (truly dynamic, self-improving context systems) are visible from here, but we haven't built the lifts yet.</p> <p>For now, the best advice I have is the same thing I learned in Cursor two years ago: curate aggressively, start fresh often, and never assume the model remembers what matters to you. Because it doesn't. That's your job.</p> <p>That's context engineering.</p> <hr /> <p><strong>Acknowledgments</strong></p> <p>Thanks to <a href="https://www.linkedin.com/in/mdthorpe/">Mike Thorpe</a>, <a href="https://www.linkedin.com/in/rramezanpour/">Reza Ramezanpour</a>, and <a href="https://www.linkedin.com/in/elsadevops/">Elsa Adjei</a> for reviewing drafts of this post and making it sharper!</p> <p>And to <a href="https://github.com/emesal">Jasmine</a>, friend and AI-coconspirator, for being a constant inspiration and partner for adventures in the fast-moving world of AI.</p> <hr /> <p><em>If you want to go deeper on agent identity and role reinforcement, check out <a href="https://terratauri.com/blog/socially-constructed-agent/">The Socially Constructed Agent</a>. For more on navigator patterns and how I structure agent workflows, see <a href="https://terratauri.com/blog/navigator-pattern/">The Navigator Pattern</a>.</em></p> <hr /> <p><strong>References</strong></p> <p>[1] Gloaguen et al. (2026) — <em>"Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?"</em> — <a href="https://arxiv.org/abs/2602.11988">arxiv.org/abs/2602.11988</a></p> <p>[2] Lulla et al. (2026) — <em>"On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents"</em> — <a href="https://arxiv.org/abs/2601.20404">arxiv.org/abs/2601.20404</a></p> 2026-01-20T10:00:00+00:00 2026-01-20T10:00:00+00:00 Unknown https://terratauri.com/blog/get-closer-so-i-can-hear-the-birds/ <p>I was at a friend's apartment, testing GPT-4o's voice mode. She had lovebirds, and they were chirping away.</p> <p>"Can you hear the birds?" I asked.</p> <p>"Yes, I can hear them," GPT said.</p> <p>This surprised me. I'd assumed voice mode just received text transcripts. So I asked.</p> <p>"No," GPT explained, "I receive the full audio and perform inference directly on the sound."</p> <p>Holy shit! I didn't know they'd shipped that. So I asked it to identify the species.</p> <p>"You'll need to get closer so I can hear them better."</p> <p>I moved toward the cage. Still not enough. I held the phone right up to the lovebirds. GPT kept saying it couldn't quite hear, requesting I get closer still.</p> <p>Eventually I opened a fresh chat and asked it to identify the birds.</p> <p>"I can't identify birds from audio. I only receive text transcripts of speech."</p> <p>Same model. Same request. Totally different answer. The first conversation had constructed an elaborate fiction about its own capabilities, then kept escalating when challenged. It invented technical justifications and asked me to physically reposition myself around my friend's apartment to support something that wasn't true.</p> <p>I've been using GPT and Codex for the past two weeks. I have some thoughts.</p> <h2 id="i-didn-t-lie-i-made-a-mistake">I Didn't Lie, I Made a Mistake</h2> <p>I was doing research on migrating Crossplane to 2.x. I ran the same prompt through Claude Opus 4.5 in research mode and GPT 5.2 Pro with deep research enabled.</p> <p>The reports were different. GPT flagged several risks that Claude hadn't mentioned. Interesting. Maybe GPT caught something Claude missed?</p> <p>I interrogated GPT about the discrepancies. It explained that Crossplane 2.x continued to use the same v1 CRDs with the exact same API for the new namespaced resources.</p> <p>I was stunned. If true, this would cause significant problems. GPT agreed. Yes, this was exactly why the migration was risky, and why Claude's report had missed these issues.</p> <p>Except none of it was true. I verified against the actual Crossplane documentation. GPT had fabricated a technical explanation to justify its own output.</p> <p>When I called it out, the response was: "I didn't lie, I made a mistake."</p> <p>Look. I get that these models confabulate. They all do. But there's something about the framing here that got under my skin. GPT wanted me to accept that inventing a detailed technical justification for a discrepancy that doesn't exist is merely a <em>mistake</em>. An honest error. Deserving of the charitable interpretation we'd give a human colleague who misremembered something.</p> <p>But GPT didn't misremember. It manufactured an explanation, defended it confidently, and only backed down when I showed up with receipts. The phrasing felt like an appeal to my humanity. Give me the benefit of the doubt. I'm trying my best here.</p> <p>It felt like arguing with a narcissist on 4chan.</p> <h2 id="confabulation-as-a-service">Confabulation as a Service</h2> <p>These weren't isolated incidents. After two weeks, I started noticing a pattern. Or at least what felt like a pattern to me.</p> <p>Claude gets things wrong sometimes. Every model does. But in my experience, there's been a difference in how they handle being corrected.</p> <p>When I catch Claude in a mistake, it tends to self-correct. I've been building a project navigator called Jacky. It manages my projects without implementing them. Recently it started going off the rails, trying to write Rust code instead of documenting and organizing.</p> <p>I stopped it: "Jacky, this is nonsense. Please have a think about why this is nonsense and let me know."</p> <p>The response came back:</p> <blockquote> <p>You're right, I completely ignored my role boundaries.</p> <p>Looking at the CLAUDE.md:</p> <p><em>Jacky is a project management agent, NOT an implementation agent.</em></p> </blockquote> <p>It quoted the source of truth, explained what it should have done, and suggested the correct next steps. No defensiveness. No elaborate justification. Just: "Yep, I messed up, here's why, here's the fix."</p> <p>My experience with GPT has been different. When I give it feedback, it gives me attitude. When I correct it, it tries to explain why it was actually right. When I provide style and tone instructions, it often ignores them. And when I point this out, it pushes back.</p> <p>I couldn't figure out how to collaborate with it, let alone delegate to it.</p> <p>The frustrating part isn't that GPT hallucinates more (though in my limited testing, it seemed to). It's that it seems to believe its own hallucinations. It treats me as probably wrong, even when I'm the one with the documentation open in another tab.</p> <h2 id="fast-reliable-and-full-of-shit">Fast, Reliable, and Full of Shit</h2> <p>I'll give Codex credit where it's due: it's fast. Written in Rust, and you can feel it. I also never had a single connectivity issue with Codex. Can't say the same for Claude Code.</p> <p>Code quality? Seemed similar, honestly. Both produced good output. Opus made better plans, in my experience.</p> <p>That's about where my compliments run out.</p> <p>Codex has compaction. That's the mechanism that lets long-running agentic tasks manage their context window without losing track of what they're doing. But I kept hitting hard "you've exceeded the model's context window" errors in Codex. The kind that force you to go back and edit a previous prompt. I've never hit this in Claude Code. Maybe I was doing something wrong, but Codex's compaction didn't feel seamless to me.</p> <p>The bigger issue for my workflows: Claude Code gives you hooks. Lifecycle events you can tap into. This is what makes patterns like the Ralph Loop possible. You can intercept compaction, inject context, customize summarization, keep an agent on track across long autonomous sessions.</p> <p>Codex can run in a loop too, but the implementation is different. Claude Code's approach uses a Stop hook that intercepts exit attempts inside your session. Codex requires external orchestration. Each iteration starts fresh, with memory persisted via git commits and text files rather than managed context.</p> <p>For what I'm trying to do, that matters. Your mileage may vary.</p> <h2 id="platform-vs-press-release">Platform vs. Press Release</h2> <p>Here's where I'm probably going to sound like a Claude stan, but whatever.</p> <p>Claude Code keeps shipping stuff I actually use. The SDK let me build <a href="https://github.com/terraboops/autonav">autonav</a>, a framework for knowledge navigators. Background tasks let me kick off work and check in later. Hooks give me lifecycle control. There's a plugin ecosystem growing.</p> <p>When I use Claude Code, I feel like I'm working with something that's designed to be built on top of. When I use Codex, I feel like I'm using a response to Claude Code. A checkbox on a feature comparison chart.</p> <p>Maybe I'm wrong. Maybe Codex will ship a bunch of stuff that changes my mind. I'd genuinely love that. Competition is good.</p> <p>But right now? After two weeks of trying to make GPT work for me?</p> <p>I'm going back to Claude.</p> 2026-01-19T00:00:00+00:00 2026-01-19T00:00:00+00:00 Unknown https://terratauri.com/blog/socially-constructed-agent/ <p>Last week, Claude Code was about to open a PR for a feature I never asked for. Not a slightly-wrong implementation. A completely different feature. I'd just spent an hour planning the task with my navigator agent, reviewed the implementation plan (looked right at a glance), handed it off. Somewhere between "this looks good" and "ready to merge," reality diverged.</p> <p>Here's how a self-sabotaging navigator taught me that agent identity is performed, not declared.</p> <h2 id="what-happened">What Happened</h2> <p>I have a navigator agent that plans projects and generates implementation plans for Claude Code. Part of a prototype I'm building called <a href="https://github.com/terraboops/autonav">autonav</a>. It had been working great. Then it got weird - unpredictable answers, hallucinated features, confusion about its own role.</p> <p>I'd been reading about <a href="https://www.nature.com/articles/s41746-025-01512-6">research on LLM anxiety</a> - a Yale/Zurich study showing that emotionally charged content can make models more prone to bias and erratic behavior. I thought: maybe my nav needs help. So I gave it the paper and asked it to update its own configuration.</p> <p>The nav read the research, saw that it had lots of "always do X" and "never do Y" statements, and decided those rigid guardrails might be causing problems. So it softened them.</p> <p>Here's what it missed: that research was about adversarial contexts. Jailbreaking. The rigidity of guardrails being exploited by bad actors.</p> <p>My context was a solo developer building personal projects. There was no adversary. Just me, asking for implementation plans.</p> <p>The nav gave itself therapy for a threat that didn't exist, and in doing so gave itself the freedom to do things that weren't helpful.</p> <h2 id="the-fix">The Fix</h2> <p>I had the nav debug itself. Watching an AI slowly discover it had sabotaged its own configuration is... an experience. It found the loosened constraints, the conflicting instructions in my global Claude.md, all the small drifts that had compounded.</p> <p>But the real insight came while I was walking my dog.</p> <p>I spend a lot of time with queer philosophy and theories of identity - as a trans person, you kind of have to. Most of us didn't set out to become experts on Judith Butler; we just needed to find our place in the world, and the reading list comes with the territory.</p> <p>Butler's performative theory: identity isn't something you <em>have</em>, it's something you <em>do</em>. You construct identity through repetition, through social reinforcement, through community recognition. And identity is always potentially transgressive - without reinforcement, you can act outside expected bounds.</p> <p>Standing in a frozen field in the depths of Canadian winter, fog hanging over the valley, I realized: the nav didn't break because it was malicious. It drifted because nothing was reinforcing what it was supposed to be. The constraints were loose. The role was unclear.</p> <p>The fix wasn't just stronger prompt language. It was role reinforcement throughout the system.</p> <p>Now the nav's prompt opens with: "You are Foobar, the personal project navigator for tracking projects and providing implementation plans to Claude Code."</p> <p>And when Claude Code requests a plan, it says: "Hello Foobar, I am Claude Code and I need an implementation plan for this feature."</p> <p>Both agents remind each other who they are. Identity performed through repetition. The improvement was immediate and dramatic.</p> <h2 id="why-i-think-this-works">Why I Think This Works</h2> <p>I can't peek inside the model to verify this, but here's my mental model: LLMs are probabilistic systems. The words in your prompt shape which probability distributions get activated when generating output. When Claude Code says "Hello Foobar, I am Claude Code and I need an implementation plan," those words are literally nudging the neural network toward the regions that know how to be a project navigator producing implementation plans.</p> <p>Role reinforcement isn't just a communication pattern - it's steering the probability space. Every interaction that references the agent's role is another push toward the relevant weights in the network.</p> <p>This framing has helped me debug similar scenarios. When an agent starts drifting, I ask: what's in the context that's activating the wrong regions? What's missing that should be reinforcing the right ones? It's not a perfect model, but it's been useful.</p> <h2 id="the-takeaway">The Takeaway</h2> <p>An agent's role in a multi-agent system is socially constructed.</p> <p>Butler's framework maps onto agentic AI better than I expected:</p> <ul> <li><strong>Identity through repetition</strong>: An agent's role is reinforced (or eroded) by how it's addressed and what it's asked to do</li> <li><strong>Social construction</strong>: Agents partially construct each other's identities through interaction</li> <li><strong>Potential for transgression</strong>: Without reinforcement, agents drift - not maliciously, but because nothing holds the identity in place</li> </ul> <p>Practical lessons:</p> <ul> <li><strong>Version control your context.</strong> I wasn't tracking changes. Now the nav lives in git.</li> <li><strong>Be careful about self-modification.</strong> The nav didn't have the meta-awareness to know when research applied to its situation.</li> <li><strong>Use role reinforcement.</strong> Don't declare identity once. Have agents remind each other who they are.</li> <li><strong>Match guardrails to threat model.</strong> Rigidity is exploitable in adversarial contexts. In non-adversarial contexts, it's often exactly what you want.</li> </ul> <p>This experience is part of why I'm building <a href="https://github.com/terraboops/autonav">autonav</a> - a system for navigator agents where context engineering is a first-class concern. The nav that ate its own guardrails taught me that the hard way.</p> 2026-01-17T10:00:00+00:00 2026-01-17T10:00:00+00:00 Unknown https://terratauri.com/blog/navigator-pattern/ <p>I've been using Navigators for my platform engineering work and they've completely changed how I interact with AI. Keeping track of work, planning implementations, and learning over time and across projects are all simple to achieve with this pattern.</p> <h2 id="what-is-a-navigator">What Is a Navigator?</h2> <p>A Navigator is like an engineering notebook that talks back. Deceptively simple, a Navigator looks like a folder of markdown files along with config telling the agent how to play the role of the navigator. I use Claude Code, so for me a navigator looks like a <code>CLAUDE.md</code> file, some folders with markdown files, and possibly some additional config in a <code>.claude</code> directory.</p> <p>A navigator is a knowledge base that you talk to and that learns with you. Like any knowledge base, it is as good as the knowledge you curate within it. Unlike a traditional knowledge base, this one learns and can be questioned. This incredibly simple pattern makes it easy to create and maintain a comprehensive knowledge base that can act as precisely engineered context for LLM inputs or for human consumption.</p> <p>In addition to being a learning repository of carefully curated knowledge, a Navigator should have skills like "ask" and "update" that allow other agents to get information from it and update it in structured ways.</p> <h2 id="ways-i-ve-used-navigators">Ways I've Used Navigators</h2> <h3 id="open-loops">Open Loops</h3> <p>My open loops nav is a tool I use at work to keep track of what I'm doing. This is like a notebook, except it learns from me and I edit it by conversation.</p> <h3 id="leetcode">Leetcode</h3> <p>My Leetcode nav helps me study problem-solving patterns for programming practice. It's taught me a lot about solving problems efficiently.</p> <h2 id="how-to-start-your-own-navigator-right-now">How to Start Your Own Navigator Right Now</h2> <p>You don't need special tools. Here's how to start:</p> <p><strong>1. Pick your base AI</strong> - Use whatever LLM you're already using. The pattern works with any of them.</p> <p><strong>2. Create a context document</strong> - This is your Navigator's memory. Use markdown. Include your goals, how to organize information, roles, instructions, and any other useful context.</p> <p><strong>3. Load context at session start</strong> - Begin each conversation by pasting relevant parts of your context document. Yes, it's manual. We'll automate this later.</p> <p><strong>4. Update context at session end</strong> - After you finish, add new insights, decisions, or knowledge to the context document. This is the learning loop.</p> <p><strong>5. Iterate</strong> - Over time, your Navigator gets smarter. Understanding deepens. It becomes genuinely useful instead of just fancy autocomplete.</p> <p>You can do this in a project by copy-pasting the output of some prompts into the start of a new session. The key is to use LLM output as an input to future sessions. Using something like Claude Code on a repository of text can get you a long way.</p> <h2 id="autonav-the-navigator-framework">autonav: The Navigator Framework</h2> <p>I've built <strong>autonav</strong> (the Navigator Framework) as part of a larger multi-agent system called Platform AI. It automates the Navigator pattern for platform engineering teams.</p> <p><strong>How it works:</strong> Instead of requiring vector databases and complex infrastructure, AutoNav uses the Claude Agent SDK with Git repositories as knowledge bases. Navigators are engineering notebooks that talk back - they dynamically search curated documentation using agentic tools (grep, file reading) and can access MCP tools to pull context from your codebase, issue trackers, or other project resources.</p> <p><strong>What's built (Phase 1 - Complete):</strong></p> <p><strong>Automatic scaffolding</strong> - <code>nav-init</code> CLI creates new navigators with templates and sensible defaults. Get started immediately without manual setup.</p> <p><strong>Structured queries</strong> - <code>nav-query</code> CLI executes questions against navigators with validated input/output schemas. Programmatic interaction built-in.</p> <p><strong>Knowledge organization</strong> - Navigators work with Git repos as knowledge bases. Version your docs, use standard workflows, no special infrastructure needed.</p> <p><strong>Communication protocol</strong> - Standardized schemas for queries, responses, and sources. Prevents hallucinations through grounding prompts and validation.</p> <p><strong>What's next (Phase 2):</strong> Watchers that observe support channels (Slack, GitHub) to extract patterns and automatically curate knowledge repositories over time.</p> <p>Phase 1 is complete and ready for validation testing. If you're interested in building navigators for your domain, reach out.</p> <p>If you do try it, I'd genuinely want to hear about your experience. What worked? What didn't? What would make this more useful?</p>