Summary

Auto-compaction can recover from an overflow, but the automatic retry can still overflow if the session’s system prompt (or embedded consumers’ injected context) remains too large. This can create an overflow → compaction → retry → overflow cascade.

This PR adds a small, embedded-consumer-focused hook that runs after auto-compaction has been applied but before Pi schedules the overflow retry, so consumers can:

• keep the retry as-is
• downgrade the system prompt for the retry (e.g. drop injected workspace context)
• cancel the retry with a clear error message

Refs #1317.

What changed

• AgentSession API
  • Added setAutoCompactionRetryHook(hook).
  • New types: AutoCompactionRetryHookContext, AutoCompactionRetryHookResult, AutoCompactionRetryHook.
  • The context includes post-compaction messages, systemPrompt, model + context window sizing, and token estimates (message/system/total/budget/overBy + overhead estimate).
  • Added a configurable timeout: compaction.autoCompactionRetryHookTimeoutMs (default: 1000ms).
• Events
  • auto_compaction_end now includes retryCanceledMessage when compaction succeeds but the overflow retry is cancelled by the hook.
• Tests
  • Added coverage for proceed / system-prompt override / cancel behavior.

Why this is useful

Embedded consumers may inject extra context (e.g. workspace files) into the system prompt. After compaction, the conversation may fit but the system prompt may still exceed the retry budget. The new hook provides a safe escape hatch to prevent runaway overflow cascades.

OpenClaw will use this hook to apply a slimmer retry prompt when needed.

Backward compatibility

• No behavior change unless an embedded consumer registers the hook.
• Hook failures/timeouts are treated defensively (they do not block retry by default).