Claude Code Tools Files

v1.23.1 makes a failing >trim say what actually went wrong, instead of the one sentence it used to give you for every possible failure.

>trim failures used to be unreadable

When the >trim trigger could not run the trim, it said this — and only this:

Trim preview failed:
Trim command failed to run (timeout or error).

That message covers a hung process, a killed one, a missing CLI and a slow transcript equally well, which is to say not at all. It had been appearing regularly on large sessions since late July.

The interesting part is what the measurements showed. The trim work itself finishes in 0.7 to 2.4 seconds even on a 20 MB transcript, against a fixed 25-second budget — 10 to 35 times under the limit. So the timeout was real, but the trim was never the slow part: something was stalling the CLI before it got going. That is also why running the same trim through aichat resume kept working fine on the very same session.

What a timeout tells you now

The trim CLI did not finish within 45s, so it was stopped.
This was only a preview, so nothing was changed.
  transcript: /Users/you/.claude/projects/…/session.jsonl (19.4 MB)
  binary:     /Users/you/.local/bin/aichat

Run the same command yourself to see the real failure:
  aichat trim-in-place '/Users/you/.claude/projects/…/session.jsonl' --json --len 500

If that returns quickly, the trim was starved rather than slow - just retry >trim.
To allow more time, set AICHAT_TRIM_TIMEOUT (seconds, up to 75) before starting Claude.

It had printed on stderr: …

The budget that ran out, the transcript and its size, which aichat your PATH actually resolved to, a shell-quoted command you can paste to reproduce it, and whatever the CLI managed to print before it wedged. Failures that are not timeouts now name their exception type rather than hiding behind the same sentence.

An apply-time timeout no longer lies to you

The old message said "nothing was changed" whichever step had failed. That is true for a preview, but >trim yes is a real write, and the subprocess is killed outright — so the trimmed file may already have been swapped in. An apply-time timeout now reports the outcome as UNKNOWN and points you at the timestamped .pre-trim-*.jsonl.bak backup beside the transcript before you retry.

The budget fits the transcript

One fixed number for every session made no sense when sessions range from a handful of kilobytes to tens of megabytes. The budget now starts at 25 seconds and grows by a second per megabyte, capped at 60. AICHAT_TRIM_TIMEOUT sets it explicitly, hard-capped at 75 seconds so the child can never outlive the hook itself and die with nothing to show. The hook's own timeout moved from 30 to 90 seconds to leave room for that.

Also

A transcript path carrying an embedded NUL byte used to let a ValueError escape, which silently passed your prompt through to the model as if you had typed it. It now blocks with a message like every other bad input.

What this does not fix

The stall itself is still unidentified — it does not reproduce outside a live hook process. This release does not stop >trim from timing out; it makes the next timeout carry enough evidence to find the cause.