Spill: When Tool Output Is Too Large

A grep hits tens of thousands of lines, or web_fetch pulls back a whole document — 2MB. Where does that result go next? Only three options.

Option one: stuff it all into context. The next model request is packed full — wallet and context window both take the hit. Option two: chop the overflow. You save space, but if the model later needs exactly the chopped error line, the task is stuck. Option three is DSH: archive the full text to disk, leave only head/tail previews in context plus a hint naming the path and saying read or grep can recover it. What left context can still be found — that's Spill (overflow-to-disk).

The plugin doing this is dsh-spill-policy. It hangs on the tool pipeline's tools/post-execute event and only acts after a tool result is finalized. The whole decision is five steps — Agent Note 2026-07-08 spells them out: delegate, plain-text check, byte threshold, saveText, replace. The checklist in the demo is those five steps copied as-is.

The policy entry is a chain of pass-through checks — four reasons not to touch, checked in order: a downstream listener did not accept the result; another plugin already replaced the value; this is a nested sub-call or the read tool; content mixed in a non-text block. Any hit → pass through as-is. If none hit, measure bytes; under maxInlineBytes also passes. Only when all clear does spill run.

An easy-to-miss ordering detail: step one is await next() — delegate first. Let downstream listeners (a content-replacing hook, say) fully settle the result; only then does spill touch the final draft. So even if another plugin swapped the content, the swapped content is still under spill's watch.

Source: packages/spill/spill-policy/src/index.ts lines 194–209, verified on 2026-08-13. Why skip read is in the source comments: avoid a loop where read output is spilled to a file, the model reads again, spills again.

That edge case from the outline: if spill storage write fails, does this tool call count as success or failure? The answer is in the catch branch — success, and not one character is hidden.

    let ref: SpillRef
    try {
      ref = await spillStore.saveText(save)
    } catch (error: unknown) {
      // Best-effort: a storage failure (permissions, ENOSPC, backend down) must
      // never fail the call or hide the content — keep the original inline.
      ctx.logger.warn(`spill-policy: saveText failed for ${toolName}: ${String(error)}; keeping the inline content`)
      return undefined
    }

Disk full, bad permissions, backend not mounted — all you get is a warn log, then the original result stays inline in context. The design note's exact line: “a spill failure must never turn a successful tool call into an isError result, nor hide the inline content” (Agent Note 2026-07-08 line 91). The logic is plain: spill is a cost-saving optimization; if it fails, context gets a bit fatter at worst — never turn a successful call into failure, and never lose information.

The opposite pitfall is plugged too: config validation runs at plugin load, not per call. A negative or fractional maxInlineBytes fails deploy startup outright (lines 114–119) — bad config should crash the deploy, not make some tool call take the blame.

After replacement, model-visible text is three parts: kept head preview, omission note plus credential, kept tail preview. The credential line is built by spillNotice (lines 104–108); Agent Note's example is “(Omitted N bytes. Full formatted result stored at: /.../session-.../....txt. Use read with offset/limit, or grep this path to search within it.)”. Wording stays deliberately generic — the policy only knows final text, not tool-internal resources.

One detail shows how strict this code is: the credential's own byte count is subtracted from the maxInlineBytes budget before sizing the preview (lines 171–172). Otherwise the preview could fill the budget, the credential sticks on, and the replacement ends up larger than the cap. If the credential line alone exceeds the whole cap, the policy simply abandons spill and keeps inline — never violate its own stated limit (lines 183–185).

The archive file itself is careful. The local backend writes to <root>/session-<hash>/<random>-<safeName>, private root (0700), write via open(path, 'wx', 0o600) exclusive and owner-readable — a pre-planted symlink cannot redirect the write (docs/subsystems/spill.zh.md line 85). A sibling design is the attachment system: reference in the log, bytes in an external store — same idea, body keeps only a light reference (docs/subsystems/attachment.zh.md).

The comparison focus is generality. All three admit large output cannot all feed the model; the difference is whether the dropped part can be recovered, and across how many tools. Grok spills only for bash; Claude Code and DSH made it a general mechanism. DSH's cut is the finest: preview lives in the output-retention library, storage in the spillStore seam (a one-method abstract service), and the policy plugin only decides when to spill and how to build the credential. Three packages each own a slice — swap a remote storage backend without touching a line of policy. Agent Note's alternatives section even names the reference: make it the general default, aiming at “Claude Code–like general tool-result persistence” (line 187).