Compaction Strategies

Compaction strategies (hooks)

Implement and wire compaction hooks via after_turn_complete.

Quick start

• Copy scripts/compaction_hooks.py into your project hooks module.
• Pick a strategy and wire it via tool_hooks.after_turn_complete.
• Tune defaults in the hook or wrap it in a custom function (hook specs do not accept params).

Agent card wiring

tool_hooks:
  after_turn_complete: hooks.py:rolling_window

Strategy menu

• Rolling window → rolling_window
• Truncate over threshold → truncate_over_threshold
• Clear results (soft) → clear_results_soft
• Clear results (hard) → clear_results_hard
• Compaction prompt → compaction_prompt

See references/compaction.md for the design summary.

Hook requirements

• Guard with if not ctx.is_turn_complete: return.
• Use ctx.usage when available to read context usage.
• Use ctx.load_message_history(...) to replace history.
• Use show_hook_message(...) to display a compaction notice.

Testing

Run a hook against saved history:

python scripts/hook_smoke_test.py \
  --hook path/to/hooks.py:rolling_window \
  --history ./history.json \
  --hook-type after_turn_complete \
  --output ./history-modified.json