You have the helm

Why it exists

In one recorded run, a model called view on the same file 65 times. Speculative exploration is the most expensive thing a small context window does, because the model has no cheap way to see the shape of a repository. It greps, guesses, reads a whole file to learn it was the wrong file, then carries that file in the window for every remaining turn of the session.

How it works

Shoal keeps a YAML adjacency graph at .shoal/chart.yaml, YAML because you are meant to read and edit it. Nodes are files, each carrying a line count, a language, its defined names, and one purpose line lifted verbatim from the file's own leading comment. No model writes that line, and it is re-derived rather than remembered, so deleting the comment removes it from the chart. Edges are Go imports resolved through go/parser, decomposition lineage verified by Bosun, and annotations you draw by hand. Discovery walks breadth-first from the nodes your task seeds and spends its budget nearest-first, so pressure costs detail before it costs coverage. The chart is served by a tool call and never injected. No standing copy lives in any prompt, results append at the tail of history, and a session that never asks a discovery question never pays for one.

Why it exists

When a context window fills, Shoal compacts, dropping the oldest tool results whole to get back under the line. That is a cliff, and a cliff cannot tell a file your task depends on from a file you opened once and closed. The codebase already gets better treatment than that, since the chart hands a model a graded view of a file rather than all of it or none. The question this arc asked is whether history deserves the same gradient.

How it works

It does not, on the evidence, so it ships switched off. The gradient is built and tested. It is a fourth kind of janitorial edit that steps an old tool result down through outline, head, and finally a label that always names the tool and the file, so a condensed result stays identifiable and can be run again. It is off because a pre-registered measurement refused it, and refusing a feature you have already built is the only kind of refusal that costs anything. One number killed it. The gradient could not be driven to the compactor's token count on any of ten histories, because a result the live turn still refers to is exempt at every setting, so at the pressure where compaction actually happens the policy has no behaviour left. It keeps far more of what a task needs when cost is not matched, 0.83 against 0.34, and that is exactly the comparison that does not decide anything.

Why it exists

A coding agent that can read and write any path on the machine is trusting the model to stay inside your project. That is an honor system, not a boundary. One read-only git tool already held that line, written so a reviewer could not reach out of the workspace, and the arc was to make the same line hold everywhere a tool takes a path.

How it works

One check decides whether a path is inside your workspace, and view, glob, grep, write, edit and patch all call it. The path is resolved first, symlinks and all, and then compared, because a link inside your project pointing outside it walks straight through a check that only reads the spelling. An absolute path or one that climbs out with .. is refused by name, telling the model what happened and what would work, and it is never turned into a question for you to approve. Write and patch check before they create a directory, so a refusal cannot arrive after the directories already exist. The boundary is threaded from your project onto the tool registry and stamped at the moment a call is dispatched, both kinds of delegated agent inherit it, and nothing inside a session can widen it.

Why it exists

A wrong edit that costs nothing to revert is a retry. One that costs a manual cleanup is a reason to stop using Shoal. Local models carry higher per-turn variance than frontier ones, and in the measured corpus run three of four failures were the model working for twenty loops without converging. Undo built on your own commit history is the wrong shape. It can only reverse what Shoal itself committed, and it refuses when the last commit was somebody else's.

How it works

Shoal keeps a shadow worktree, a second git directory under the app data directory, seeded from your repository but never writing to it. A capture records a content-addressed tree and a restore puts named paths back, so your own history is never touched and your own commits are never made or unmade on your behalf. One constraint decides the shape. Bash operates deliberately outside the file writer, so a checkpoint built on write hooks would silently miss every file bash creates. The tree is captured at the turn boundary instead, not per write. Undo composes the two halves and says which ones it did. Rewinding the conversation alone tells you your files were not touched, and undoing to a point restores the files first and then cuts the history, so a restore that fails leaves nothing to explain away.

Why it exists

Every piece of work Shoal handed to a sub-agent went to the same agent. A fresh context, every tool the main loop has, and the same instructions. Handing a review to something that can rewrite the file it is reviewing is a boundary you are asked to trust the model to respect, and asking for a quick look at how something works costs you an agent equipped to change it.

How it works

A delegation can name a specialist and get that specialist's toolset and its own instructions instead of the default. Two ship. The reviewer reads code and reports what is wrong with it, worst first. The scout finds something out and reports the facts, including what it did not find, so you can tell an exhaustive search from a lucky one. Both are read only, and read only here means the tools to change a file are not in the set the child was handed, so a call to one of them is refused by Shoal at the moment it is dispatched rather than by instructions asking the model to behave. A specialist names a toolset; it cannot list one, so there is no way for a named role to end up with more reach than the role was given. Naming none is unchanged, so a delegation gets the full toolset and the main loop's own instructions. A name that does not exist is refused with the names that do, because falling back to the ordinary agent would make a typo look like a working delegation. The roster reports which specialist each child ran as, in the terminal and in both windowed clients, and the record survives the session.

Why it exists

Everything Shoal does assumes somebody is watching, ready to approve a write, read a diff, and steer a turn that wanders. Automation has none of that. A scheduled job, a check on every pull request, or a trigger from another system needs a Shoal that runs once, decides for itself, and exits with an answer a script can branch on.

How it works

shoal exec takes one prompt from an argument, a file, or standard input, runs it without asking anybody anything, and exits. Output is the final text, one result document carrying the stop reason and what it spent and which files it touched, or every engine event as JSON lines for something else to read as it happens. The exit code is distinct per outcome, so a scheduler can tell a completed run from a refused one without parsing anything. Approvals cannot ask a person, so they are answered by an autonomy ladder. One table maps what the engine already decided a call is onto the lowest rung that permits it. The floor is the default and it refuses anything that writes, and reports the refusal rather than dropping it quietly. Climbing takes a flag, and the top rung is not reachable by naming a level, only by asking for it outright.

Why it exists

A coding agent quietly takes the shape of whichever model its author had loaded. The tool-call format, the chat template, and the parser that reads a completion back all follow that one model's habits, and a different model then fails against them for reasons that look like the model's fault and are not. A twenty-task corpus run across four models on one machine found four distinct failures of exactly that kind, and every one of them was Shoal's to fix.

How it works

Shoal reads a model's tool-call support from its GGUF header before any weight loads, so shoal models and shoal doctor tell you when a model cannot call a tool and stop recommending one. When a dock refuses to parse a completion, Shoal retries once with the tools dropped instead of ending your turn, and counts the fallback in the tally as a degrade so the number is never hidden. A mooring can name the chat template llama.cpp renders with, which is the only way the two Mistral models are reachable at all. And a tool call a model writes into its message body is read back out of it, under a guard that is the point of the feature rather than a caveat on it. Every recognised call writes its own tally row, so a pass rate can always be re-derived with the recogniser subtracted. Measured live on three models, pinned and reproducible. gpt-oss-20b went 19/20 to 20/20 with zero recognised calls, which is the control saying the recogniser stays out of the way, and Qwen2.5-Coder 14B went 0/20 to 15/20 with all 138 of its tool calls read out of prose and none off the wire.