# v2 Roadmap

This document records the proposed direction for the next major release. It is a roadmap, not a description of behavior currently implemented in `0.2.0`.

## Motivation

The current extension has a fixed, context-window-aware threshold policy. Some sessions and models should be able to opt out of the extension's automatic threshold trigger without disabling Pi's native compaction or manual `/compact` command.

## Proposed v2 scope

### Session-level control

Add commands such as:

```text
/auto-compact on
/auto-compact off
/auto-compact status
```

The setting should be stored as a Pi custom session entry rather than only in extension memory. On `session_start`, the extension should reconstruct the setting from the session history so it survives resume, reload, and process restart.

The session setting should control only the extension's automatic threshold trigger.

### Model-level exclusions

Add support for excluding selected models from the extension's automatic trigger. Matching should use the active provider and model ID exposed by Pi's extension context, for example:

```text
anthropic/example-model
openai/example-model
```

A model switch should re-evaluate the model-specific policy. A model exclusion should be explicit and visible in the command/status output so users can understand why a session is not being compacted.

Possible v2 commands include:

```text
/auto-compact models
/auto-compact exclude <provider/model-id>
/auto-compact include <provider/model-id>
```

The exact persistence and configuration model remains to be decided: session-only model exclusions, global user exclusions, or both.

## Compaction semantics

The v2 exclusion behavior should be implemented before calling `ctx.compact()` from the `agent_settled` handler.

It should not cancel or intercept the shared `session_before_compact` event for all compaction paths. Doing so could interfere with:

- Pi's native threshold compaction
- Context-overflow recovery
- Manual `/compact`
- Future Pi compaction behavior

The extension should therefore skip only its own automatic threshold decision when a session or model is excluded.

Disabling all automatic compaction should remain a Pi compaction setting rather than an extension-level override.

## Cache behavior to preserve

Pi's compaction implementation uses `cacheRetention: "none"` for one-off summarization requests. After compaction, the normal conversation prefix changes because older messages are replaced by a summary. The first post-compaction request may therefore have a lower prompt-cache hit rate, while later turns can build a new cache for the compacted prefix.

Any v2 metrics or status output should distinguish:

- Extension-triggered compactions
- Session/model exclusions
- Manual compactions
- Pi native threshold or overflow compactions

## Open questions before implementation

1. Should model exclusions be session-local, user-global, or configurable in both scopes?
2. Should `/auto-compact off` persist until explicitly enabled, or expire when the session ends?
3. Should the status command display the active threshold, exclusion reason, and last compaction outcome?
4. Should v2 support a configurable threshold override in addition to exclusions?
5. Should model matching support provider/model IDs only, or also model families and wildcard patterns?

No v2 exclusion behavior is implemented yet. The current release remains `0.2.0` with the tiered threshold policy documented in the root [README](../README.md).