SessionStart hook output exceeds Claude Code's additionalContext limit, silently truncating task state

[suyuan2022]

Observation

On a fresh trellis init --claude install (verified against v0.4.0-beta.8), the session-start.py hook produces additionalContext that is consistently over 30 KB. Claude Code appears to truncate additionalContext at around 20 KB, emitting only a ~2 KB preview plus a fallback file path. In practice the AI does not read the fallback file unless explicitly prompted, so anything past the 2 KB preview is effectively invisible — including ## ACTIVE TASKS, ## CURRENT TASK, and ## MY TASKS.

End result: the session-start context injection silently breaks for any project whose combined size pushes it past ~20 KB, which is most non-trivial projects. The developer sees "task state not being surfaced" without any error.

Data

Measurements from the hook output on two projects (one clean vanilla install, one lightly used):

Segment	Project A (vanilla)	Project B (light use)
<session-context>	~150 B	~150 B
<current-state> (tasks, git, journal)	1.6 KB	1.7 KB
<workflow> (full workflow.md)	12.5 KB	16.6 KB
<guidelines> (spec index files)	6.3 KB	5.0 KB
<instructions> (full start.md)	11.0 KB	11.0 KB
total additionalContext	~31 KB	~36 KB

Both are over the observed ~20 KB truncation threshold. The two large blocks marked ★ in the table above account for 75%+ of the payload.

How I verified the truncation behavior

Using claude -p --session-id <uuid> to spawn a fresh Claude Code instance inside the project and asking it to report what it actually received:

• Fresh instance replies: "additionalContext was truncated; only a ~2 KB preview was available; saved to tool-results/hook-<id>-additionalContext.txt"
• The Active Tasks / Current Task sections are not visible in the visible preview
• The instance does not proactively read the fallback file

After reducing the hook output to well under 20 KB (see "Possible approaches" below), a fresh Claude instance reports:

• "No truncation. I can see 3 active tasks, the current task name, and the full workflow section index."

Possible approaches (not prescriptive)

I experimented with a couple of out-of-tree patches on my own projects and both worked well; sharing here as ideas for upstream discussion, not as a fait-accompli solution.

Approach A — Dynamic TOC for workflow.md

Instead of reading workflow.md verbatim into <workflow>, session-start.py scans the file at session-start time and emits a compact table of contents with line ranges for each ## section. Claude navigates by line range and reads specific sections on-demand via Read offset+limit. A compact form:

<workflow>
`.trellis/workflow.md` — read on-demand by section (use Read with offset+limit):
- L7-18 (12L): Table of Contents
- L19-88 (70L): Quick Start
- L89-150 (62L): Workflow Overview
- L151-202 (52L): Session Start Process
- L203-240 (38L): Development Process
- L241-270 (30L): Session End
- L271-337 (67L): File Descriptions
- L338-368 (31L): Best Practices
- L369-406 (38L): Quick Reference
- L407-420 (14L): Summary
</workflow>

Typical size: ~500–700 bytes instead of 12–16 KB. Claude still has full content access — it just reads it lazily.

Approach B — Remove start.md from session-start entirely

start.md is the /trellis:start slash command definition. Claude Code already expands it as a prompt when the user types the command. Injecting it at session-start as well is duplicate work: the user either types the command (in which case they get the full content on demand) or they don't (in which case the 11 KB is unused ballast). Other slash commands (brainstorm, finish-work, check, record-session) are not pre-injected — so this would restore symmetry.

Replace the current <instructions> block with a 1-line pointer like:

<instructions>
For task startup workflow, type the slash command `/trellis:start`. It expands the full guide on demand. Other slash commands (brainstorm / finish-work / check / record-session) follow the same pattern — not pre-injected here.
</instructions>

Typical savings: ~11 KB.

Combined result on my measurement projects

With both Approach A and B applied:

Project	Before	After
A (vanilla)	31 KB	9.3 KB
B (light use)	36 KB	8.4 KB

Both drop well under the truncation threshold. Fresh claude -p instances in both projects confirm they now see the full <current-state> and <workflow> TOC, with room to spare (~11 KB headroom before hitting the limit).

Reproduction

mkdir /tmp/trellis-repro && cd /tmp/trellis-repro && git init
npx @mindfoldhq/trellis@beta init --claude -u test-user -y

# Measure session-start output size:
echo '{"session_id":"t","source":"startup"}' \
  | python3 .claude/hooks/session-start.py \
  | python3 -c 'import sys,json; d=json.load(sys.stdin); ctx=d["hookSpecificOutput"]["additionalContext"]; print(f"{len(ctx.encode(\"utf-8\"))} bytes")'

Typical vanilla output: 30+ KB on a repo with a handful of tasks and spec files.

Why I'm raising this as an issue, not a PR

This is a design-space question more than a clear bug:

1. Is the truncation behavior I'm seeing a Claude Code platform limit, a trellis design assumption, or both?
2. If workflow.md / start.md pre-injection is intentional, what's the rationale? (I'd like to understand before proposing a change — I might be missing a reason.)
3. If reducing the payload is welcome, which approach fits better — dynamic TOC, symmetry with other slash commands, a config toggle, all three?

I'm happy to turn either or both approaches into a PR if there's interest, but I'd rather discuss the direction first so the work doesn't go to waste.

Environment

• trellis: 0.4.0-beta.8 (also observed on beta.9)
• Claude Code: 4.6
• OS: macOS 14 (Darwin 23.6)
• Python: 3.11
• node: 20.x

Related

• Search turned up no existing issues for SubagentStop / truncat / size-related SessionStart discussion
• Related fixes I'm opening separately: fix(hooks): correct SubagentStop event field names in ralph-loop #152 (ralph-loop field names), fix(update): parse name from .developer when creating migration task #153 (migration task assignee parsing)

[taosu0216]

Thanks for the thorough writeup and data — I reproduced it end-to-end on my side and can confirm every number you cited. Direction: both A and B are welcome, happy to merge them as separate PRs.

Reproduction confirmed

I hit this live, by the way — my own active Claude Code session in the Trellis dev repo got truncated:

Output too large (34.4KB). Full output saved to:
.../tool-results/hook-<id>-additionalContext.txt

That's the exact failure mode you described. Here's the breakdown I measured:

Project A — npx @mindfoldhq/trellis@beta init --claude -u test -y in a fresh /tmp dir:

Section	Bytes	KB	%
<session-context>	147	0.1	0.5%
<current-state>	1,018	1.0	3.4%
<workflow>	11,908	11.6	39.9%
<guidelines>	5,186	5.1	17.4%
<instructions>	11,071	10.8	37.1%
<task-status>	221	0.2	0.7%
<ready>	284	0.3	1.0%
Total	29,847	29.1

Project B — the Trellis dev repo itself (light use):

Section	KB
<workflow>	11.7
<instructions>	10.1
<guidelines>	10.8
<current-state>	1.5
Total	34.6

Matches your 31 KB / 36 KB within 2 KB. Two blocks account for 77% of vanilla payload, exactly as you said.

On Approach B alone — not enough

I simulated dropping just <instructions> on both projects:

Project	Before	After B only
Vanilla	29.1 KB	18.6 KB ✓
Trellis dev repo	34.6 KB	24.7 KB ✗ still truncates

Approach B alone only saves vanilla. Any project with a real spec tree still busts the limit because <guidelines> keeps growing with spec/*/index.md count. So both A and B are needed.

A + B combined on the Trellis dev repo: 13.5 KB — about 6.5 KB safety margin under the threshold. Comfortable.

On your three open questions

1. Is the truncation a Claude Code platform limit or a Trellis assumption? Platform limit. We've verified independently that Claude Code truncates additionalContext around 20 KB and writes the fallback to disk. Agents don't read the fallback unless prompted. So this is real and will bite any payload that grows past the threshold.

2. Was pre-injecting start.md intentional? Historical. Your symmetry argument is correct — brainstorm, finish-work, check, record-session are all slash commands whose definition files Claude Code expands on demand. start.md being the only one pre-injected is an inconsistency we should remove. Approach B is the right call on its own merits, independent of the size issue.

3. Which approach fits better? Both. Different problems, different fixes:

   • B removes a ~10 KB redundancy that shouldn't exist (zero risk, pure cleanup).
   • A addresses the workflow.md size that will keep growing.
   • A config toggle isn't needed — the slash command mechanism already provides opt-in access to the full content.

Suggested landing order

If you're up for it:

• PR 1 — Approach B: drop the <instructions> block from session-start.py, replace with a one-line pointer to /trellis:start. Small, reviewable in 5 minutes. Needs to touch all platform mirrors (packages/cli/src/templates/claude/hooks/, codex/, iflow/, copilot/) — I noticed there are 4 copies of this hook, so let's not leave any behind.

• PR 2 — Approach A: dynamic TOC for workflow.md. Please include a test that asserts the output size stays under 15 KB on a vanilla install so we catch regressions.

One thing to consider for PR 2: the <guidelines> block (5.1 → 10.8 KB between vanilla and a lightly-used project) is a third time bomb that grows with spec count. Out of scope for this issue, but worth mentioning — if you spot a clean way to give it the same TOC treatment, feel free to roll it into PR 2 or flag it as a follow-up.

Go ahead whenever you're ready.

[taosu0216]

#160 and #161 merged. Thanks for the thorough writeup and the PRs.