AIClaw 3.7.14: Understanding the Recoverable Truncated Tool Output Mechanism

Why Agents "See the Data but Answer Wrong"

A command can return correct data and the agent can still give the wrong answer. One easily overlooked reason: the model only sees the beginning of the output, while the truly relevant field appears much further down.

AIClaw v3.7.14 was released on October 14, introducing a mechanism to read beyond truncated content without re-executing commands. This article is based on the published tag rather than changes on unreleased branches.

Previews Need a Continuation Path

In previous versions, the command writer kept only a bounded prefix, and subsequent bytes were simply discarded. The truncation marker made the limit visible but could not recover the discarded content.

Consider an export result spanning thousands of lines with a summary field at the end. Not seeing the summary field in the first few lines is not sufficient proof that it doesn't exist in the export. Re-running the export can be costly, produce different data, or even repeat a write operation.

The new output helper module separates "the text shown immediately" from "a larger retained copy." Command mode and Code Mode previews use a 24 KiB content budget. Ordinary tool results entering the conversation history still use the ~32 KiB head-and-tail preservation approach through history integration.

When a result exceeds the preview budget, the runtime attempts to save a bounded copy and provides an output_id. The model can then inspect the relevant pagination rather than treating the preview as the complete result.

UTF-8 byte offsets: In this version, the pagination interface for reading retained copies uses UTF-8 encoded byte positions as its unit of location, not line numbers or character counts. This means an offset may land in the middle of a multi-byte character, breaking decoding. To handle this, the reader actively validates and rejects such offsets, requiring callers to align to valid character boundaries before continuing to read.

4096-byte page limit: Each call returns at most 4096 bytes. By calling repeatedly and advancing along nextOffset, the entire retained copy can be read. This limit exists to avoid a single large return triggering preview truncation again.

Reading Saved Results Without Re-running Tools

The read_tool_output session reader accepts a result ID, a UTF-8 byte offset, and a page limit of at most 4096 bytes. It returns:

• text: the current page;
• nextOffset: the continuation position;
• totalBytes: the retained length;
• hasMore: whether another retained page exists;
• complete: whether the retained capture is complete.

The reader rejects offsets that fall inside a UTF-8 character. It looks up the ID under the current session rather than accepting filesystem paths or invoking the original command. Different sessions cannot use the same ID to retrieve that copy.

Copies are stored in local SQLite session state, can persist across session restoration, and follow the session's deletion lifecycle. They are not shared with forked sessions, and the feature cannot reconstruct output that older versions already discarded.

This also means more tool return text is stored locally. The retention mechanism is bounded storage, not a redaction or encryption feature.

Bounded storage: Retained copies are stored in local SQLite session state with a per-copy limit of 8 MiB, meaning it is not a lossless complete log. When command output, capture, or retention crosses a limit at any stage, the copy is explicitly marked incomplete rather than silently discarded. "Bounded" constrains both space usage and recoverable scope: bytes beyond the boundary cannot be retrieved through any subsequent read.

Session isolation: The reader looks up copies by ID only under the current session. It does not accept filesystem paths and does not re-execute the original command. Therefore, different sessions and forked sessions cannot use the same ID to obtain a copy from elsewhere. This design both prevents cross-session data leakage and keeps the copy lifecycle consistent with archival behavior.

Reading to the Last Retained Page Does Not Mean the Source Data Is Complete

Each retained copy is capped at 8 MiB. Command capture limits stdout and stderr separately; the saved merged copy also has an 8 MiB cap. Exceeding the capture or retention limit sets completeness to false. Save failures explicitly report that recovery is unavailable.

Thus the two flags answer different questions. hasMore=false means the reader has reached the end of the saved text; complete=false means that text may still be missing part of the captured result. On the last retained page, both can be false simultaneously.

Even if the capture is complete, that doesn't mean the upstream API never returned the line. Pagination, server-side filtering, and shell pipelines like head can all remove data before AIClaw sees it. System instructions require the model to check relevant fields and source pagination before claiming "it doesn't exist," and to state uncertainty when evidence cannot be obtained. These instructions guide the model but cannot guarantee its interpretation is always correct.

Code Mode Retains Large Results Before Script Slicing

Code Mode introduces another place where information can disappear: a script may receive a large tool result but return only a short selection.

The runtime bridge now retains oversized nested tool return values before passing them into scripts. It emits recovery metadata separately while keeping the script-returned tool value unchanged. Thus a subsequent slice() won't remove the recovery reference for that oversized return value.

This applies to nested results above the preview threshold that were successfully saved, not to every small value the script chose to omit. If a nested return value is itself a command preview, reading it can reveal a second ID for a larger command output; the model must follow the correct references onward.

Nested tool return values: In Code Mode, a script can call tools, get return values, and then slice or filter them. If a nested return value is too large, the runtime bridge retains it before it enters the script and emits recovery metadata separately, while the value the script sees remains unchanged. So even if the script returns only a short selection, the metadata reference can later lead back to the full content. This mechanism only acts on nested results above the preview threshold that were successfully saved, and does not create copies for every small value the script actively omits.

File Offsets Now Apply Before Pagination Budgets

The same version fixes a related file reading issue: the previous implementation truncated the file to 256 KiB before applying the requested line offset. As a result, lines beyond that prefix were unreachable via line parameters.

The new file pager locates the requested line in the full file and then reads a bounded page. Long lines can be continued via byte_offset. Returned pages respect UTF-8 boundaries, and the file tool retains its sensitive path checks.

What the Validation Establishes

The tagged session tests cover retained copies, session isolation, explicit incomplete captures, and recovery after Code Mode slicing. Tool tests cover later file lines, Unicode pagination, capture limits, and command exit states.

The release notes report passing local make check, a 15-scenario live model run, and four focused scenarios after the final changes. The public scenario definition includes finding a synthetic trailing field without re-running the command. These are bounded checks and do not prove that every model will always inspect every necessary page.

The actual improvement delivers a recoverable chain of evidence: a short preview, a session-scoped copy, and clear limits on what that copy can establish.

One-line Summary

AIClaw v3.7.14 separates previews from retained copies, letting agents continue reading truncated output instead of re-running commands.

Paragraph Summary

AIClaw v3.7.14 addresses the "saw the data but answered wrong" problem by splitting command output into two parts: an immediately shown preview and a larger retained copy. Command and Code Mode preview budgets are 24 KiB; when exceeded, the runtime saves a bounded copy and provides an output_id. Models can use read_tool_output to paginate through it by UTF-8 byte offsets without re-running the tool. Copies live in local SQLite and are session-isolated. The article emphasizes that hasMore=false and complete=false mean different things: the former means the end of retained text was reached, the latter means the capture may be incomplete—and even completeness doesn't rule out lines dropped beforehand by upstream APIs or shell pipelines. Code Mode retains large return values before they enter scripts, so slice() won't remove the recovery reference; file reading now locates line offsets in the full file before reading a bounded page.