Playbooks · Coding tasks
Kiro 3.1: hooks that can veto compaction
Written November 8, 2026
Kiro CLI 3.1.0 adds PreCompact and PostCompact hooks — one can refuse compaction, the other rescues what the summary dropped. Plus session credits.
What 3.1.0 adds
Kiro CLI 3.1.0, released November 5, 2026, adds PreCompact and PostCompact hooks that run around conversation compaction, and shows the credits a session has used so far in /usage, the status line, and workflow step rows. The same release lets you ship default settings for an environment, adds an opt-in session recap, lets sub-agents read their parent's memories, and groups notifications into one row.
Compaction is the point where a long session summarizes its older history to make room. Until 3.1.0, that summary ran on its own schedule and you had no say in what survived it. The two hooks give you a say at both ends of the process: one before the summary is written, one after it replaces the older history.
How the two hooks work
Kiro's hook reference describes both triggers. PreCompact fires before a CLI V3 session compacts its conversation — when you run /compact, when automatic summarization starts, when Kiro recovers from a context overflow, and when Kiro hands the session to another model. It takes no matcher.
- Exit 0: compaction continues. In CLI V3, the hook's standard output is added to the agent's context, up to 3,000 characters. Use that to hand the summarizer guidance, or to save a copy of the conversation before older history is summarized.
- Exit 2: compaction is cancelled. In CLI V3, the conversation stays as it is. In the IDE, Kiro reports the hook's standard error as the reason, and the turn continues without compacting unless the context is nearly full.
PostCompact fires after the summary has replaced the older history. The event JSON on standard input includes summary, up to 3,000 characters of the summary text, and summary_path, the file holding the full summary. The hook's output is added to the conversation, so the agent keeps details the summary dropped. The hook cannot undo the compaction or change the summary, and it takes no matcher either.
Both triggers are V3-only and need 3.1.0 or later. They have no CLI 2.x equivalent. Workspace hooks live in .kiro/hooks/; hooks in ~/.kiro/hooks/ run in every workspace.
Setting up a guard for one fact
- Pick the fact worth guarding. A guard works best for one named thing: a deployment target, a constraint the agent keeps forgetting, a decision made earlier in the session. A hook that tries to save everything saves nothing useful.
- Write a
PreCompacthook that checks for it. The hook runs a command before compaction. If the fact is still present and the session can go on, exit 0. If compaction would run while a tracked task is still open, exit 2 and print the reason to standard error. - Write a
PostCompacthook that re-injects it. After compaction, the hook reads the summary from standard input and prints the guarded fact back out. Its output joins the conversation, so the agent keeps working with the fact even though the summary dropped it. - Test both hooks with a manual
/compact. Run/compactyourself first, in a session you can afford to lose, and read what the agent remembers afterwards. A hook that fires at the wrong time is worse than no hook: it either blocks compaction until the context overflows, or it re-injects stale guidance.
What the hooks cannot do
- A refusal is not a guarantee. Exit 2 cancels the compaction in front of you, but a session that keeps growing will hit the context limit anyway. In the IDE, the turn continues without compacting unless the context is nearly full. Refusing compaction buys time; it does not buy room.
PostCompactcannot repair a bad summary. It can add back facts the summary dropped, but it cannot change the summary itself or restore the history the summary replaced. If the summary misstates a decision, re-injecting the fact corrects the record going forward — the wrong summary stays in the record.- Neither hook sees the full conversation.
PreCompactgets the hook event, not the transcript.PostCompactgets the summary, up to 3,000 characters inline, plus the full summary file. A hook that needs the whole transcript has to read it from where the session stores it. - Session credits are a total, not a budget.
/usageshows the credits your session has used so far, and the optional Session credits segment under/settings displaykeeps that total in the status line. The changelog says nothing about a cap or an alert, so treat the number as a record of spend, not a limit.
Limits
- This page reads Kiro's changelog and hook reference. It reports no long Kiro session run here, so it says nothing firsthand about what a summary drops in practice or whether a guard hook saves a given fact.
- The hook behaviour described here is for CLI V3 sessions on 3.1.0 or later. The compaction hooks in the IDE arrived in the same week under different trigger names, and the IDE exit-code behaviour differs in the details given above.
- Compaction survival depends on the model, the session length, and what the summary keeps. A hook that re-injects one fact does not make a compacted session equal to the session before compaction.
Related playbooks
- Two hooks that enforce your coding conventions
- Kiro CLI 3.0: V3 is the default, Classic is gone
- Claude Agent ACP 0.101.0: idle compaction lands
- Check whether your Claude Code hooks are adding tokens to every prompt or cutting them
Sources
Back to: Coding playbooks hub · Also: Kiro CLI 3.0: V3 is the default, Classic is gone · What version should I be on · Run parallel subagents in Claude Code