cachetoast 0.1.0 → 0.1.2

package/README.md

@@ -1,8 +1,8 @@
 # Cachetoast
 
-When you come back to a **large, idle** coding-agent session whose prompt cache has likely expired, Cachetoast holds your first prompt before the agent re-reads the whole context at full price, and gives you a handoff to continue in a fresh session instead. Works with Claude Code, Codex, and Pi.
+Cachetoast tries to compact **large, idle** Claude Code and Pi sessions before their prompt cache expires. If compaction cannot run, it holds your next prompt once and offers a handoff to a fresh session. Codex uses that handoff fallback.
 
-Zero dependencies. No LLM calls, API keys, telemetry, or network access. Node.js 22+, macOS/Linux.
+Zero dependencies. No separate API keys or telemetry. Timers and handoffs run locally; native compaction uses your agent's model and normal billing. Node.js 22+, macOS/Linux.
 
 Built by [R. Hunter Harris](https://huntersoftwareconsulting.com) at [Hunter Software Consulting](https://huntersoftwareconsulting.com), fractional product and technology leadership for B2B SaaS.
 
@@ -20,12 +20,25 @@ It installs for the agents you have (`--provider codex` to choose, `--dry-run` t
 
 Then restart your agent.
 
+- **Claude Code:** start from the repo root and trust the project. The repo-local `cachetoast-idle` plugin provides the timer; mods require terminal v2.1.287+ or desktop v2.1.286+. Check `/plugin` for loading errors. Older clients retain the handoff fallback.
 - **Codex:** trust the project, run `codex` in the repo, and approve the hooks in `/hooks`. The Codex app skips unapproved hooks and can't approve them ([openai/codex#47283](https://github.com/openai/codex/issues/47283)).
 - **Pi:** trust the project.
 
 ## How it works
 
-If a session is at least 100k tokens (`--min-context-tokens`) and has been idle past its cache deadline, your next prompt is held once:
+For sessions of at least 100k tokens (`--min-context-tokens`), Claude Code and Pi schedule one native compaction attempt per idle period:
+
+| Cache TTL | Compact after idle | Time before expiry |
+| --- | --- | --- |
+| 5 minutes | 4 minutes | 1 minute |
+| 30 minutes | 25 minutes | 5 minutes |
+| 1 hour | 55 minutes | 5 minutes |
+
+New activity cancels the timer. Successful compaction avoids the handoff for that idle period and does not start another timer. If the agent closes or the computer sleeps past expiry, Cachetoast skips the cold compaction. Resuming while still warm can restore the remaining timer.
+
+Claude Code 2.1.299+ has its own [idle compaction](https://code.claude.com/docs/en/settings-reference#idlecompaction): terminal sessions on the 1h TTL, about 54 minutes idle, 200k tokens by default. Cachetoast lowers that minimum to match its own (`CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS`, 100k at least), so Claude usually compacts first and Cachetoast's timer covers what it skips: the 5m TTL, the desktop app and other clients, older versions, and `idleCompaction: false`. Either compaction prevents the hold.
+
+If compaction failed, was skipped, or is unavailable, your next prompt after the deadline is held once:
 
 ```text
 Cachetoast held this prompt!
@@ -49,11 +62,11 @@ Small sessions are left alone, since a fresh session wouldn't be cheaper. Cachet
 The hold starts at the TTL minus up to 5 minutes (1h → 55 min, 30m → 25 min, 5m → 4 min).
 
 - **Claude Code:** read from the session (1h on Pro/Max; 5m on API keys, cloud providers, or usage credits).
-- **Codex:** 30m (GPT-5.6 and later).
+- **Codex:** 30m (GPT-5.6 and later). OpenAI's API now also offers `12h`, but Codex CLI 0.163 doesn't request it. A Codex lead has said signed-in Codex users keep their cache indefinitely; OpenAI hasn't documented this, so Cachetoast still assumes 30m. If you trust it, raise the TTL with `--codex-cache-ttl 12h` or `24h`.
 - **Pi:** 5m for Claude models (1h with `PI_CACHE_RETENTION=long`), otherwise 30m.
 - **Anything else:** 30m.
 
-To override, run `init --pi-cache-ttl 1h` (or `--codex-cache-ttl`, `--claude-cache-ttl`; `5m`, `30m`, `1h`, `24h`). That saves to `~/.config/cachetoast/config.json`; `.cachetoast/local.json` takes the same format per repo. A TTL reported by a Claude session always wins.
+To override, run `init --pi-cache-ttl 1h` (or `--codex-cache-ttl`, `--claude-cache-ttl`; `5m`, `30m`, `1h`, `12h`, `24h`). That saves to `~/.config/cachetoast/config.json`; `.cachetoast/local.json` takes the same format per repo. A TTL reported by a Claude session always wins.
 
 ## Commands
 
@@ -65,7 +78,7 @@ node .cachetoast/runtime/bin/cachetoast.mjs uninstall           # restore origin
 
 ## What to commit
 
-Commit `.cachetoast/runtime`, `.cachetoast/config.json`, and the agent settings, hooks, and handoff command or skill. `local.json`, `state/`, `handoffs/`, and `manifest.json` are gitignored; handoffs contain conversation excerpts.
+Commit `.cachetoast/runtime`, `.cachetoast/config.json`, and the agent settings, hooks, handoff command or skill, and `.claude/skills/cachetoast-idle` plugin. These use repo-relative paths and need no launchd, cron, or global service. `local.json`, `state/`, `handoffs/`, and `manifest.json` are gitignored; handoffs contain conversation excerpts.
 
 `init` and `update` are idempotent and leave unrelated settings alone. `uninstall` restores the original files and removes local state. Each stops if you've edited the managed files by hand.
 
@@ -74,8 +87,10 @@ Commit `.cachetoast/runtime`, `.cachetoast/config.json`, and the agent settings,
 - Savings come mostly from Claude Code quota: its large contexts are rewritten to cache at 2× the input price after a miss. Codex and Pi misses cost less.
 - Mobile and remote clients may not show the notice clearly, and can't start a fresh local session to run the handoff. Send the prompt again to continue, or run the handoff later from the CLI or desktop app.
 - Expiry is estimated from a local clock; Cachetoast can't see the provider's cache.
+- Timers require the agent to remain running and awake. Starting a compaction before expiry does not guarantee completion or a cache hit. A failed attempt keeps the handoff available.
+- Codex exposes compaction to an owning app-server connection, but its repo hooks cannot portably reach an arbitrary open session. Codex gets the native context ceiling and handoff guard, without a proactive timer.
 - No hold if hooks are disabled, untrusted, or time out.
-- Verified with Claude Code 2.1.285, Codex CLI 0.159.2, and Pi 0.85.1; provider formats can change. Research: [docs/research.md](docs/research.md).
+- Claude plugin statically validated with Claude Code 2.1.292; adapter behavior tested with synthetic sessions. Claude's native idle compaction is read from its transcript summary; no live run confirmed it. No paid live-compaction experiment was run. Other integration baselines: Codex CLI 0.163.0 and Pi 0.85.1. Research: [docs/research.md](docs/research.md).
 
 ## Develop
 

package/bin/cachetoast.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
 import path from 'node:path';
-import { handleHook, configAt, ttlChoice, statePath, userConfigPath, KEY_RE, PROVIDERS } from '../lib/runtime.mjs';
+import { handleHook, idleState, recordIdle, configAt, ttlChoice, statePath, userConfigPath, KEY_RE, PROVIDERS } from '../lib/runtime.mjs';
 import { readJson, readText, safePath } from '../lib/storage.mjs';
 
-const HELP = `Cachetoast 0.1.0 — local handoffs, inspired in part by Antiburn
+const HELP = `Cachetoast 0.1.2 — local handoffs, inspired in part by Antiburn
 Usage: cachetoast <command> [--repo PATH] [options]
   init       Install in the current repo (or --repo) for the agents you have installed.
              [--provider claude,codex,pi] [--dry-run]
@@ -17,10 +17,12 @@ Usage: cachetoast <command> [--repo PATH] [options]
   uninstall  Restore installation files if they have no external edits
   hook       --provider claude|codex: JSON lifecycle event on stdin (internal; Pi runs in-process)
 Cache TTLs are read from Claude Code sessions, 30m for Codex (GPT-5.6+), and guessed from Pi's model.
-To override (5m, 30m, 1h, 24h), pass --<agent>-cache-ttl: saved per user in ~/.config/cachetoast/config.json,
+To override (5m, 30m, 1h, 12h, 24h), pass --<agent>-cache-ttl: saved per user in ~/.config/cachetoast/config.json,
 or per repo in the gitignored .cachetoast/local.json. A TTL a Claude session reports always wins.
-Only sessions of 100k+ tokens are held: the first prompt after the cache goes cold, once per idle period.
-Hooks and all commands run without LLMs, credentials, or network access.
+Claude Code and Pi attempt idle native compaction at 4m / 25m / 55m for 5m / 30m / 1h TTLs.
+Codex uses the handoff fallback; its hooks cannot portably compact an already-open session.
+Only sessions of 100k+ tokens are held, once per idle period, when compaction did not succeed.
+Hooks and handoffs run locally. Native compaction uses the agent's model and normal billing.
 `;
 function options(args) {
   const result = {};
@@ -65,6 +67,13 @@ async function main() {
   if (argv[0] === '--help' || argv[0] === '-h') { process.stdout.write(HELP); return; }
   const [command = 'help', ...args] = argv, o = options(args);
   if (command === 'help' || o.help) { process.stdout.write(HELP); return; }
+  if (command === 'idle') {
+    const input = JSON.parse(await stdin()), root = findRoot(o.repo ?? process.cwd());
+    const out = input.status ? recordIdle(root, o.provider, input.session_id, input)
+      : idleState(root, o.provider, input.session_id);
+    process.stdout.write(JSON.stringify(out) + '\n');
+    return;
+  }
   if (command === 'hook') {
     // A cost advisory must never stop work because of its own failure: fail open with a visible warning.
     let result;
@@ -104,8 +113,9 @@ async function main() {
     if (result.userConfig) console.log(`${result.dryRun ? 'Would save' : 'Saved'} cache TTLs to ${result.userConfig}.`);
     if (result.dryRun || !result.changed.length) return;
     const next = ['Restart your agent.'];
+    if (result.providers.includes('claude')) next.push('Claude: launch from the repo root, trust the project, and check /plugin for cachetoast-idle (requires mods support).');
     if (result.providers.includes('codex') || result.providers.includes('pi')) next.push('Trust the repo.');
-    if (result.providers.includes('codex')) next.push('Codex: review /hooks.');
+    if (result.providers.includes('codex')) next.push('Codex: review /hooks. Proactive idle compaction is unavailable, so the handoff is the fallback.');
     console.log(next.join(' '));
     return;
   }
@@ -127,7 +137,7 @@ async function main() {
     const sessions = keys.map(key => {
       try {
         const s = readJson(safePath(root, statePath(key)));
-        return { key, provider: s.provider, ...ttlChoice(config, s.provider, s), heldAt: s.heldAt ?? null, contextTokens: s.contextTokens ?? null, lastActivity: s.lastActivity, warnings: s.warnings ?? [] };
+        return { key, provider: s.provider, ...ttlChoice(config, s.provider, s), heldAt: s.heldAt ?? null, contextTokens: s.contextTokens ?? null, lastActivity: s.lastActivity, compaction: s.compaction ?? null, warnings: s.warnings ?? [] };
       } catch (error) { return { key, error: `Unreadable state (${error.message}); delete it to reset` }; }
     });
     console.log(JSON.stringify({ config, userConfig: userConfigPath(), sessions, note: 'Cache availability is inferred, never guaranteed. Sessions with unknown context size are never held.' }, null, 2));

package/docs/research.md

@@ -2,6 +2,10 @@
 
 Checked October 1, 2026 against primary provider documentation. Installed clients: Codex CLI 0.159.2 and Claude Code 2.1.285. No paid inference or quota experiment was performed. The private discussion was used to identify questions; its claims were not treated as documentation.
 
+Updated October 17, 2026: Claude's current mods API supports host timers and in-process compaction. The generated plugin passed strict static validation with Claude Code 2.1.292. Timing, cancellation, native API calls, and fallback state are tested with synthetic sessions; no paid live-compaction experiment was performed.
+
+Updated October 21, 2026: Claude Code added native idle compaction (2.1.299), and OpenAI added a 12-hour cache lifetime for GPT-5.6+ (October 20). Checked against Codex CLI 0.163.0; Pi was not rechecked.
+
 ## What survives cache expiry
 
 Cache expiry removes reusable inference state, not the transcript or its context window. Continuing sends the current context again. Earlier compacted-away history is not magically restored. Native compaction changes the prompt prefix and can require a new cache write. A handoff prepared locally avoids submitting long history solely to summarize it.
@@ -12,13 +16,15 @@ Claude’s current docs say a cold `/compact` summarization request reprocesses
 
 Included subscription main turns normally request one hour. API keys, cloud providers, and usage-credit billing normally use five minutes. Most helpers, including compaction, use five minutes unless overridden. Explicit controls exist: `promptCacheTtl` and `subagentPromptCacheTtl` settings, `CLAUDE_CODE_PROMPT_CACHE_TTL` (`5m`/`1h`), `ENABLE_PROMPT_CACHING_1H`, and `FORCE_PROMPT_CACHING_5M`. Switching from included usage to credits can shorten the effective lifetime. These are per-request controls, not a universal one-hour guarantee. Each assistant transcript record's `usage.cache_creation` splits cache writes into `ephemeral_1h_input_tokens` and `ephemeral_5m_input_tokens`, so Cachetoast reads the TTL a session actually gets from its latest write rather than from settings or billing. See [Claude Code prompt caching](https://code.claude.com/docs/en/prompt-caching).
 
+Claude Code 2.1.299 added [idle compaction](https://code.claude.com/docs/en/settings-reference#idlecompaction) (settings exist from 2.1.290): in an interactive terminal session on the one-hour TTL, with feature flags reachable, a conversation of at least 200K tokens is compacted after about 54 idle minutes, and the conversation shows `Compacted while idle, before the prompt cache expired`. `CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS` changes the minimum (values below 100K are raised to 100K); `idleCompaction: false` or `DISABLE_AUTO_COMPACT` turns it off. It does not cover the five-minute TTL, the desktop app, or 100K–200K sessions at its default. Cachetoast sets the minimum to its own (at least 100K) and keeps its mod for the rest. The docs do not say whether this compaction reaches a mod's `session.compact` hook, so Cachetoast instead treats a compaction summary after the latest usage record as an unmeasured context: no hold until the next response reports a size.
+
 Anthropic’s API supports five-minute and one-hour cache writes, priced at 1.25× and 2× ordinary input respectively. Reads are usually 0.1× with model-specific exceptions. Hits refresh the TTL. This is API pricing, not a formula for subscription quota. See [Anthropic prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching).
 
 Claude plan usage is shared across Claude and Claude Code. API-key authentication can use separate API billing. Exact subscription allowance savings should not be inferred from API-dollar estimates. See [Claude Pro/Max usage and billing](https://support.claude.com/en/articles/11145838-use-claude-code-with-your-pro-or-max-plan).
 
 ## OpenAI API versus Codex quota/credits
 
-Current API docs distinguish model generations. GPT-5.6 and later support a default/minimum 30-minute cache lifetime and charge 1.25× uncached input for cache writes. GPT-5.6+ set this with `prompt_cache_options.ttl` (only `30m`). Older models use `prompt_cache_retention`: `in_memory` entries commonly last 5–10 idle minutes, up to an hour; `24h` extended retention can last a day and is the default for organizations without Zero Data Retention where both are supported. GPT-5.5 supports only `24h`. Prefix changes and routing also affect hits. A single “30-minute Codex cache” rule cannot be applied to every model and billing mode. Codex transcripts record no TTL, so Cachetoast supports GPT-5.6 and later only and assumes their 30-minute minimum. See [OpenAI prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching).
+Current API docs distinguish model generations. GPT-5.6 and later set the lifetime with `prompt_cache_options.ttl`: `30m` (default and minimum, writes at 1.25× uncached input) or, since October 20, 2026, `12h` (Responses API only, writes at 2.5×); `prompt_cache_breakpoint.ttl` overrides one breakpoint. Reads are 0.1× on most models and 0.05× on GPT-6.1 Sol. Codex CLI 0.163.0 sends neither `prompt_cache_options` nor `prompt_cache_retention` (the strings appear only in its bundled migration notes), so API-key Codex gets the 30-minute default. Older models use `prompt_cache_retention`: `in_memory` entries commonly last 5–10 idle minutes, up to an hour; `24h` extended retention can last a day and is the default for organizations without Zero Data Retention where both are supported. GPT-5.5 supports only `24h`. Prefix changes and routing also affect hits. A single “30-minute Codex cache” rule cannot be applied to every model and billing mode. Codex transcripts record no TTL (0.163 adds `cache_write_input_tokens` but no lifetime), so Cachetoast supports GPT-5.6 and later only and assumes their 30-minute minimum. On October 20, 2026, Codex lead Tibo Sottiaux posted on X that signed-in Codex and Work users keep their cache indefinitely. Neither the Codex nor the API docs say so, and the API docs state cache entries are not stored indefinitely, so Cachetoast still assumes 30m for Codex. Users who rely on the claim can set `--codex-cache-ttl 12h` or `24h`. See [OpenAI prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching).
 
 Codex credit billing explicitly has no separate cache-write charge; API-key usage follows API pricing. Cached and uncached input have distinct credit rates. Included subscription usage is not determined solely by credit prices. Consequently “rehydration is free/irrelevant on subscriptions” does not follow. No public source reviewed establishes a universal exact quota weighting or Codex-client retention contract. See [Codex pricing and limits](https://learn.chatgpt.com/docs/pricing).
 
@@ -34,11 +40,17 @@ A universal “shorter sessions always perform better” or “250K is optimal
 
 ## Available hooks
 
-Both current clients expose command hooks, including `UserPromptSubmit`, `Stop`, and compaction events. `UserPromptSubmit` supports blocking before the model processes the prompt. A `systemMessage` only appears after the prompt is sent, when the cost is already paid, so Cachetoast holds the first cold prompt once per idle period (`decision: "block"`) and lets it through when sent again. Codex's CLI adds a submitted prompt to message history before hooks run, so Up-arrow recalls a held prompt. Neither client offers a repo-installable surface visible before typing, so the hold is the only point where the cost can still be avoided. Neither documented lifecycle provides a portable command that requests in-process `/compact` while an arbitrary CLI session is idle. Cachetoast therefore performs deterministic local extraction at the next prompt, leaving live transcripts intact. Because extraction needs no model call, preparing it earlier with a timer would cost the same and only add moving parts.
+Both clients expose command hooks including `UserPromptSubmit`, `Stop`, and compaction events. `UserPromptSubmit` supports blocking before the model processes the prompt. Cachetoast holds the first continuation after the idle deadline once (`decision: "block"`) when native compaction has not succeeded; sending it again proceeds. Codex's CLI adds a submitted prompt to message history before hooks run, so Up-arrow recalls a held prompt. Handoff extraction is deterministic and does not modify provider transcripts.
+
+Claude's newer [mods API](https://code.claude.com/docs/en/plugins/mods/reference) exposes `$.clock.after()` and `$.session.compact()`. The latter uses native semantic compaction between turns, rejects while a turn runs, and returns a skip reason when vetoed. Cachetoast installs a bundled module under `.claude/skills/cachetoast-idle`; [project plugins](https://code.claude.com/docs/en/plugins/loading#plugins-shared-through-a-repository) load after trust, from the primary working directory (desktop worktrees may load the main checkout's plugin). Launch from the repo root. Mods require terminal v2.1.287+ or desktop v2.1.286+ per the [mod creation docs](https://code.claude.com/docs/en/plugins/mods/create). The module uses the host process API to read/write Cachetoast state through its copied Node runtime, without invoking another agent or editing the transcript itself.
+
+Claude (alongside Claude Code's own idle compaction, which fires about a minute earlier on one-hour terminal sessions) and Pi attempt compaction at TTL minus up to five minutes: 5m → 4m, 30m → 25m, 1h → 55m. New activity cancels the timer. Each idle cycle has at most one attempt; success suppresses the fallback for that cycle. Suspended timers waking at or beyond expiry skip compaction. Native compaction has model cost and cache hits remain uncertain.
+
+Codex's [app-server compaction API](https://learn.chatgpt.com/docs/app-server) exposes `thread/compact/start` to an owning connection. This does not establish a portable repo-hook connection to an arbitrary running CLI or desktop session. Cachetoast keeps Codex's threshold and handoff fallback, and installs no private-socket, UI, or second-process transcript workaround.
 
 Codex loads trusted repo hooks from `.codex/hooks.json`; new or changed hook definitions require review in `/hooks`. Hooks run with the session cwd, which may be a subdirectory. See [Codex hooks](https://learn.chatgpt.com/docs/hooks).
 
-Claude’s `UserPromptSubmit` hooks fail open on timeout or non-zero exit (other than exit 2), and `Stop` does not fire on user interrupt. Cachetoast therefore fails open on its own errors too, and reads response timestamps from the transcript to cover interrupted turns. It uses only `UserPromptSubmit` and `Stop`; native compaction summaries are read from the transcript. See [Claude hooks](https://code.claude.com/docs/en/hooks).
+Claude’s `UserPromptSubmit` hooks fail open on timeout or non-zero exit (other than exit 2), and `Stop` does not fire on user interrupt. Cachetoast fails open on its own errors too, and reads response timestamps from the transcript to cover interrupted turns. Command hooks use `UserPromptSubmit` and `Stop`; the native mod also handles startup, turn start, compaction, and shutdown. See [Claude hooks](https://code.claude.com/docs/en/hooks).
 
 ## Pi
 

package/lib/claude-mod.mjs

@@ -0,0 +1,65 @@
+import { createIdleCompactor } from './idle.mjs';
+
+// The installer bundles this module into a repo-local Claude Code plugin.
+// No Node globals: all host access goes through Claude's portable mod API.
+let controller, root, sessionId;
+function warn($, error) { void Promise.resolve($.ui.log(`Cachetoast idle compaction skipped: ${error.message}. The handoff remains available.`)).catch(() => {}); }
+async function command($, input, target = { root, sessionId }) {
+  const result = await $.process.run(['node', `${target.root}/.cachetoast/runtime/bin/cachetoast.mjs`, 'idle', '--provider', 'claude', '--repo', target.root], {
+    cwd: target.root, stdin: JSON.stringify({ session_id: target.sessionId, ...input }), timeoutMs: 10_000
+  });
+  if (result.exitCode !== 0) throw new Error(result.stderr || 'Cannot read compaction state');
+  return JSON.parse(result.stdout);
+}
+async function connect($) {
+  const id = await $.session.id();
+  let dir = await $.session.cwd();
+  while (!await $.fs.exists(`${dir}/.cachetoast/config.json`)) {
+    const parent = dir.slice(0, dir.lastIndexOf('/')) || '/';
+    if (parent === dir) return false;
+    dir = parent;
+  }
+  if (controller && (sessionId !== id || root !== dir)) { controller.cancel(); controller = undefined; }
+  root = dir; sessionId = id;
+  const target = { root, sessionId };
+  controller ??= createIdleCompactor({
+    read: () => command($, {}, target),
+    record: (s, status, result) => command($, { activityId: s.activityId, lastActivity: s.lastActivity, status, skip: result?.skip, tokensAfter: result?.tokensAfter }, target),
+    compact: () => $.session.compact(),
+    now: () => $.clock.now(), after: (ms, fn) => $.clock.after(ms, fn), onError: error => warn($, error)
+  });
+  return true;
+}
+export function register(on) {
+  on('classic.Stop', async ($, e, next) => {
+    const result = await next(e);
+    if (!e.agent_id && !controller?.isRunning()) {
+      try { if (await connect($)) await controller.arm(); } catch (error) { warn($, error); }
+    }
+    return result;
+  });
+  on('classic.SessionStart', async ($, e, next) => {
+    controller?.cancel();
+    const result = await next(e);
+    try { if (await connect($)) await controller.arm(); } catch (error) { warn($, error); }
+    return result;
+  });
+  on('classic.UserPromptSubmit', ($, e, next) => { controller?.cancel(); return next(e); });
+  on('turn.start', ($, e, next) => { controller?.cancel(); return next(e); });
+  on('session.end', ($, e, next) => { controller?.cancel(); return next(e); });
+  // Manual/threshold compaction also satisfies this idle cycle; precompute does not install a summary.
+  on('session.compact', async ($, e, next) => {
+    if (e.agentId || e.trigger === 'precompute') return next(e);
+    if (controller?.isRunning()) return next(e);
+    controller?.cancel();
+    let state;
+    try { if (await connect($)) state = await command($, {}); } catch (error) { warn($, error); }
+    const target = { root, sessionId };
+    const result = await next(e);
+    if (state && !result.skip) {
+      try { await command($, { activityId: state.activityId, lastActivity: state.lastActivity, status: 'succeeded', tokensAfter: result.tokensAfter }, target); }
+      catch (error) { warn($, error); }
+    }
+    return result;
+  });
+}

package/lib/idle.mjs

@@ -0,0 +1,35 @@
+// Host-neutral, single-shot timer. Hosts supply their own clock and native compaction API.
+// Bundled into Claude's sandboxed module as well as imported by Pi.
+export function createIdleCompactor({ read, record, compact, now, after, onError }) {
+  let timer, revision = 0, running = false;
+  const cancel = () => { revision++; timer?.cancel(); timer = undefined; };
+  const eligible = s => s && s.lastActivity != null && Number.isFinite(s.contextTokens)
+    && s.contextTokens >= s.p.minContextTokens && s.compaction?.activityId !== s.activityId;
+  const arm = async () => {
+    cancel();
+    const ticket = revision;
+    try {
+      const s = await read(), time = await now();
+      if (ticket !== revision || running || !eligible(s) || time >= s.lastActivity + s.p.ttlMs) return;
+      timer = after(Math.max(0, s.lastActivity + s.p.idleMs - time), async () => {
+        timer = undefined;
+        try {
+          const current = await read(), firedAt = await now();
+          if (ticket !== revision || running || !eligible(current) || current.activityId !== s.activityId
+            || current.lastActivity !== s.lastActivity || firedAt < current.lastActivity + current.p.idleMs
+            || firedAt >= current.lastActivity + current.p.ttlMs) return;
+          if (!await record(s, 'attempting') || ticket !== revision) return;
+          running = true;
+          try {
+            const result = await compact();
+            await record(s, result?.skip ? 'skipped' : 'succeeded', result);
+          } catch (error) {
+            await record(s, 'failed', { skip: error.message });
+            throw error;
+          } finally { running = false; }
+        } catch (error) { onError(error); }
+      });
+    } catch (error) { onError(error); }
+  };
+  return { arm, cancel, isRunning: () => running };
+}

package/lib/install.mjs

@@ -97,10 +97,22 @@ export function install(root, options = {}) {
     const prior = settings.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW;
     if (prior != null && !/^\d+$/.test(String(prior))) throw new Error('Existing Claude compact window must be a plain integer');
     settings.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = String(Math.min(prior == null ? target : Number(prior), target));
+    // Claude Code's own idle compaction (1h TTL, terminal) starts at 200K; lower it to this policy's minimum
+    // (Claude's floor is 100K) so it covers the same sessions. The mod still covers 5m TTLs and other clients.
+    const priorIdle = settings.env.CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS, idleMin = Math.max(100_000, config.minContextTokens);
+    if (priorIdle != null && !/^\d+$/.test(String(priorIdle))) throw new Error('Existing Claude idle compaction minimum must be a plain integer');
+    settings.env.CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS = String(Math.min(priorIdle == null ? idleMin : Number(priorIdle), idleMin));
     // The bootstrap explicitly enables this compaction policy in the repo.
     settings.autoCompactEnabled = true;
     for (const flag of ['DISABLE_AUTO_COMPACT', 'DISABLE_COMPACT']) if (settings.env[flag] === '1') settings.env[flag] = '0';
     set('.claude/settings.json', JSON.stringify(mergeHooks(settings, 'claude'), null, 2) + '\n');
+    // Claude discovers trusted project plugins here. Relative paths survive moves and clones.
+    const plugin = '.claude/skills/cachetoast-idle';
+    set(`${plugin}/.claude-plugin/plugin.json`, JSON.stringify({ name: 'cachetoast-idle', version: '0.1.2', author: { name: 'R. Hunter Harris' }, description: 'Compact large idle sessions before estimated cache expiry' }, null, 2) + '\n');
+    set(`${plugin}/hooks/hooks.json`, JSON.stringify({ modules: ['./register.mjs'] }, null, 2) + '\n');
+    const idle = readText(path.join(PACKAGE_ROOT, 'lib/idle.mjs')).replace(/^export /gm, '');
+    const adapter = readText(path.join(PACKAGE_ROOT, 'lib/claude-mod.mjs')).replace(/^import .*\n/, '');
+    set(`${plugin}/hooks/register.mjs`, `// Managed by Cachetoast; bundled for Claude's mod sandbox.\n${idle}\n${adapter}`);
     // Arguments are prompt data, never interpolated into an injected shell command.
     set('.claude/commands/cachetoast-handoff.md', `---\ndescription: Continue a Cachetoast-held session by its key (latest if omitted)\nargument-hint: "[session-key]"\nallowed-tools: Bash(node ${SCRIPT} handoff:*)\n---\n<!-- Managed by Cachetoast; edits are overwritten by init. -->\n${handoffInstructions('claude', 'Requested session key: $ARGUMENTS')}`);
   }
@@ -115,7 +127,7 @@ export function install(root, options = {}) {
     set('.pi/extensions/cachetoast.ts', '// Managed by Cachetoast; edits are overwritten by init.\nexport { default } from "../../.cachetoast/runtime/lib/pi-extension.mjs";\n');
   }
   set('.cachetoast/config.json', JSON.stringify(config, null, 2) + '\n');
-  set('.cachetoast/README.md', '# Cachetoast\n\nThe runtime, config.json, and provider hook settings can be committed. local.json (optional per-repo cache TTL overrides), state, handoffs, and the manifest stay local: handoffs contain conversation excerpts.\n\nWhen a large session (default 100k+ tokens) has been idle past your cache deadline, the first prompt is held once with a fresh-session handoff (in a new session, copy `/cachetoast-handoff KEY` in Claude Code or `$cachetoast-handoff KEY` in Codex from the notice; in Pi, `/handoff` opens one); sending it again continues. The key selects the held session even when others have been held since. Omitting it loads the latest handoff for that provider. Handoffs are local extracts, not model summaries. Cache TTLs are read from Claude Code sessions, 30m for Codex, and guessed from the Pi model; override one with `node .cachetoast/runtime/bin/cachetoast.mjs init --pi-cache-ttl 1h` (saved in ~/.config/cachetoast/config.json). Inspect with `status` and `handoff --key KEY`.\n\nInspired in part by [Antiburn](https://antiburn.com/) and its [open source work](https://github.com/antiburn/antiburn).\n');
+  set('.cachetoast/README.md', '# Cachetoast\n\nThe runtime, config.json, and provider hook settings can be committed. local.json (optional per-repo cache TTL overrides), state, handoffs, and the manifest stay local: handoffs contain conversation excerpts.\n\nLarge idle Claude Code and Pi sessions get one native compaction attempt before estimated expiry: 4m for a 5m TTL, 25m for 30m, 55m for 1h. Claude uses the trusted repo plugin in .claude/skills/cachetoast-idle (launch from the repo root; requires mods support); Pi uses its extension. Keep the agent running and awake. Native compaction uses the agent’s model and normal billing. Claude Code 2.1.299+ also compacts idle 1h terminal sessions itself (about 54 minutes); its minimum is set to match. Codex has no portable repo-hook compaction trigger. If compaction cannot run or fails, the first prompt after the idle deadline is held once with a fresh-session handoff (in a new session, copy `/cachetoast-handoff KEY` in Claude Code or `$cachetoast-handoff KEY` in Codex from the notice; in Pi, `/handoff` opens one); sending it again continues. The key selects the held session even when others have been held since. Omitting it loads the latest handoff for that provider. Handoffs are local extracts, not model summaries. Cache TTLs are read from Claude Code sessions, 30m for Codex, and guessed from the Pi model; override one with `node .cachetoast/runtime/bin/cachetoast.mjs init --pi-cache-ttl 1h` (saved in ~/.config/cachetoast/config.json). Inspect with `status` and `handoff --key KEY`.\n\nInspired in part by [Antiburn](https://antiburn.com/) and its [open source work](https://github.com/antiburn/antiburn).\n');
   const ignore = readText(safePath(root, '.gitignore'));
   const ignores = ['state/', 'handoffs/', 'manifest.json', 'local.json'].map(p => `.cachetoast/${p}`);
   const missing = ignores.filter(p => !ignore.split('\n').includes(p));

package/lib/pi-extension.mjs

@@ -2,7 +2,8 @@
 // Runs in-process: same policy, state, and handoffs as the Claude/Codex hooks.
 import fs from 'node:fs';
 import path from 'node:path';
-import { handleHook, handoffFor, handoffName, configAt, policyFor, statePath } from './runtime.mjs';
+import { handleHook, handoffFor, handoffName, configAt, policyFor, statePath, idleState, recordIdle } from './runtime.mjs';
+import { createIdleCompactor } from './idle.mjs';
 import { statusText } from './policy.mjs';
 import { readJson, safePath, keyFor } from './storage.mjs';
 
@@ -24,7 +25,7 @@ const ttlGuess = ({ model } = {}) => model?.provider !== 'anthropic' && !/claude
   : model.provider === 'anthropic' && process.env.PI_CACHE_RETENTION === 'long' ? '1h' : '5m';
 
 export default function cachetoast(pi) {
-  let lastAssistant = '', compacting = false, timer = null;
+  let lastAssistant = '', compacting = false, compacted = false, timer = null, idle = null;
   // Fail open: any error becomes a warning and Pi continues.
   const guarded = (ctx, action) => {
     try {
@@ -37,6 +38,40 @@ export default function cachetoast(pi) {
     session_name: ctx.sessionManager.getSessionName?.(),
     context_tokens: ctx.getContextUsage()?.tokens ?? undefined, cache_ttl_guess: ttlGuess(ctx), ...extra
   });
+  const compact = ctx => new Promise((resolve, reject) => {
+    if (!ctx.isIdle() || ctx.hasPendingMessages?.() || compacting) return resolve({ skip: 'Session is busy' });
+    compacting = true;
+    try {
+      ctx.compact({
+        onComplete: () => {
+          compacting = false; compacted = true;
+          // Usage can be unavailable immediately after native compaction; success still stands.
+          let tokensAfter;
+          try { tokensAfter = ctx.getContextUsage()?.tokens; } catch {}
+          resolve({ tokensAfter });
+        },
+        onError: error => { compacting = false; reject(error); }
+      });
+    } catch (error) { compacting = false; reject(error); }
+  });
+  const arm = ctx => {
+    idle?.cancel();
+    guarded(ctx, root => {
+      const sessionId = ctx.sessionManager.getSessionId();
+      idle = createIdleCompactor({
+        read: () => {
+          const state = idleState(root, 'pi', sessionId);
+          if (!state || !ctx.isIdle() || ctx.hasPendingMessages?.()) return null;
+          return { ...state, contextTokens: ctx.getContextUsage()?.tokens, p: policyFor(configAt(root), 'pi', { ...state, guessedTtl: ttlGuess(ctx) }) };
+        },
+        record: (s, status, result) => recordIdle(root, 'pi', sessionId, { activityId: s.activityId, lastActivity: s.lastActivity, status, ...result }),
+        compact: () => compact(ctx), now: Date.now,
+        after: (ms, fn) => { const timeout = setTimeout(fn, ms); timeout.unref?.(); return { cancel: () => clearTimeout(timeout) }; },
+        onError: error => ctx.ui.notify(`Cachetoast idle compaction skipped: ${error.message}. The handoff remains available.`, 'warning')
+      });
+      void idle.arm();
+    });
+  };
 
   // Footer status, visible before the next prompt; a timer flips it to cold while idle. Errors just clear it.
   const status = ctx => {
@@ -48,13 +83,17 @@ export default function cachetoast(pi) {
     } catch { try { ctx.ui.setStatus('cachetoast', undefined); } catch {} }
   };
   pi.on('session_start', (_event, ctx) => {
+    compacted = false;
     clearInterval(timer);
     timer = setInterval(() => status(ctx), 30_000);
     timer.unref?.();
     status(ctx);
+    arm(ctx);
   });
-  pi.on('session_shutdown', () => { clearInterval(timer); timer = null; });
+  pi.on('session_shutdown', () => { clearInterval(timer); timer = null; idle?.cancel(); });
+  pi.on('agent_start', () => { idle?.cancel(); compacted = false; });
   pi.on('input', (event, ctx) => {
+    idle?.cancel();
     // Only prompts that start a new run after idle; steering and queued follow-ups do not.
     if (event.source === 'extension' || event.streamingBehavior) return { action: 'continue' };
     const out = guarded(ctx, root => hook(root, ctx, 'UserPromptSubmit', { prompt: event.text }));
@@ -65,6 +104,7 @@ export default function cachetoast(pi) {
       return { action: 'handled' };
     }
     ctx.ui.setStatus('cachetoast', undefined);
+    compacted = false;
     return { action: 'continue' };
   });
   pi.on('agent_end', event => {
@@ -72,14 +112,16 @@ export default function cachetoast(pi) {
     if (last) lastAssistant = messageText(last);
   });
   pi.on('agent_settled', (_event, ctx) => guarded(ctx, root => {
+    if (compacting || compacted || idle?.isRunning()) return;
     hook(root, ctx, 'Stop', { last_assistant_message: lastAssistant });
     // Same context ceiling as Claude/Codex. Pi's compact() aborts a running turn, so only compact once idle.
     const tokens = ctx.getContextUsage()?.tokens;
     if (!compacting && ctx.isIdle() && Number.isFinite(tokens) && tokens >= configAt(root).targetTokens) {
-      compacting = true;
-      const done = () => { compacting = false; };
-      ctx.compact({ onComplete: done, onError: done });
-    }
+      idle?.cancel();
+      const state = idleState(root, 'pi', ctx.sessionManager.getSessionId());
+      void compact(ctx).then(result => recordIdle(root, 'pi', state.sessionId, { ...state, status: result.skip ? 'skipped' : 'succeeded', ...result }))
+        .catch(error => ctx.ui.notify(`Cachetoast compaction failed: ${error.message}`, 'warning'));
+    } else arm(ctx);
     status(ctx);
   }));
   pi.registerCommand('handoff', {

package/lib/policy.mjs

@@ -1,6 +1,6 @@
 export const DEFAULT_TARGET = 250_000;
 export const DEFAULT_MIN_CONTEXT = 100_000;
-export const CACHE_TTLS = Object.freeze({ '5m': 300_000, '30m': 1_800_000, '1h': 3_600_000, '24h': 86_400_000 });
+export const CACHE_TTLS = Object.freeze({ '5m': 300_000, '30m': 1_800_000, '1h': 3_600_000, '12h': 43_200_000, '24h': 86_400_000 });
 
 export function positive(value, name) {
   if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`${name} must be a positive integer`);
@@ -29,7 +29,8 @@ export function policy(options = {}) {
 export function evaluate(session, p = policy(), now = Date.now()) {
   const idleForMs = session.lastActivity == null ? null : Math.max(0, now - session.lastActivity);
   const large = Number.isFinite(session.contextTokens) && session.contextTokens >= p.minContextTokens;
-  const due = large && idleForMs !== null && idleForMs >= p.idleMs;
+  const compacted = session.compaction?.status === 'succeeded' && session.compaction.activityId === session.activityId;
+  const due = !compacted && large && idleForMs !== null && idleForMs >= p.idleMs;
   return {
     action: due ? 'handoff' : 'wait',
     idleForMs,
@@ -40,6 +41,7 @@ export function evaluate(session, p = policy(), now = Date.now()) {
 
 // Short status for the Pi footer, shown before the next prompt. Null when the session is small or unmeasured.
 export function statusText(session, p = policy(), now = Date.now()) {
+  if (session.compaction?.status === 'succeeded' && session.compaction.activityId === session.activityId) return 'idle context compacted';
   if (!Number.isFinite(session.contextTokens) || session.contextTokens < p.minContextTokens || session.lastActivity == null) return null;
   const size = `${Math.round(session.contextTokens / 1000)}k`, left = p.idleMs - (now - session.lastActivity);
   return left > 0 ? `cache warm ${Math.ceil(left / 60_000)}m · ${size}` : `cache cold · ${size}`;

package/lib/runtime.mjs

@@ -75,9 +75,14 @@ function refreshEvidence(state, input, provider) {
   state.warnings = evidence.warnings;
   // Only a fresh measurement counts: an unreadable or truncated tail must not warn on stale numbers.
   // In-process adapters (Pi) report context size directly.
-  state.contextTokens = Number.isFinite(input.context_tokens) ? input.context_tokens : evidence.contextTokens;
+  const compacted = state.compaction?.status === 'succeeded' && state.compaction.activityId === state.activityId
+    && (evidence.lastActivity == null || evidence.lastActivity <= state.compaction.at);
+  state.contextTokens = Number.isFinite(input.context_tokens) ? input.context_tokens : compacted ? state.contextTokens : evidence.contextTokens;
   // Transcript response times cover interrupted turns, where Stop does not fire.
-  if (evidence.lastActivity !== null) state.lastActivity = Math.max(state.lastActivity ?? 0, evidence.lastActivity);
+  if (!compacted && evidence.lastActivity !== null && (state.lastActivity == null || evidence.lastActivity > state.lastActivity)) {
+    state.lastActivity = evidence.lastActivity;
+    state.activityId = (state.activityId ?? 0) + 1;
+  }
   if (input.last_assistant_message) state.evidence.assistant = terse(input.last_assistant_message, 2400);
   if (evidence.cacheTtl) state.observedTtl = evidence.cacheTtl;
   // Pi sends a guess with every event (none means the default), so a model switch replaces it.
@@ -98,10 +103,10 @@ export function handleHook(root, provider, input, { now = Date.now() } = {}) {
   if (event === 'Stop') {
     // Stop fires right after a model response, which refreshes the provider cache.
     state.lastActivity = Math.max(state.lastActivity ?? 0, now);
+    state.activityId = (state.activityId ?? 0) + 1;
   } else {
     const result = evaluate(state, policyFor(c, provider, state), now);
-    // No agent shows anything before you type, so the first prompt after the cache goes cold is held once:
-    // that is the last moment the cost can be avoided. Sending it again goes through.
+    // If native compaction did not succeed, hold the first continuation after the idle deadline once.
     const held = state.heldAt != null && state.heldAt > (state.lastActivity ?? 0);
     if (result.action === 'handoff' && !held) {
       atomicWrite(root, `.cachetoast/handoffs/${key}.md`, handoffPrompt(root, state, input.prompt) + '\n');
@@ -120,7 +125,27 @@ export function handleHook(root, provider, input, { now = Date.now() } = {}) {
     state.objective ||= state.latestUser;
     // The prompt is sent to the model now, so the cache clock restarts.
     state.lastActivity = now;
+    state.activityId = (state.activityId ?? 0) + 1;
   }
   atomicWrite(root, statePath(key), state);
   return {};
 }
+
+// Shared with native in-process adapters; this never calls a model or edits its transcript.
+export function idleState(root, provider, sessionId) {
+  if (!PROVIDERS.includes(provider) || !sessionId || typeof sessionId !== 'string') throw new Error('Invalid idle session');
+  const state = readJson(safePath(root, statePath(keyFor(provider, sessionId))));
+  return state ? { ...state, activityId: state.activityId ?? 0, p: policyFor(configAt(root), provider, state) } : null;
+}
+export function recordIdle(root, provider, sessionId, input, { now = Date.now() } = {}) {
+  const state = idleState(root, provider, sessionId);
+  if (!state || input.activityId !== state.activityId || input.lastActivity !== state.lastActivity) return false;
+  if (!['attempting', 'succeeded', 'skipped', 'failed'].includes(input.status)) throw new Error('Invalid compaction status');
+  if (input.status === 'attempting' && state.compaction?.activityId === state.activityId) return false;
+  delete state.p;
+  state.compaction = { activityId: state.activityId, status: input.status, at: now };
+  if (input.skip) state.compaction.reason = terse(input.skip, 300);
+  if (input.status === 'succeeded') state.contextTokens = Number.isFinite(input.tokensAfter) ? input.tokensAfter : null;
+  atomicWrite(root, statePath(state.key), state);
+  return true;
+}

package/lib/transcript.mjs

@@ -59,6 +59,9 @@ export function readTranscript(file, provider) {
       if (assistant) result.assistant = terse(assistant, 2400);
       if (summary) result.summary = terse(summary, 3000);
       if (Number.isFinite(tokens) && tokens >= 0) result.contextTokens = tokens;
+      // A summary after the latest usage means the context was replaced, e.g. by Claude Code's own idle
+      // compaction, which no hook reports. The old size no longer applies until the next response measures it.
+      else if (summary) result.contextTokens = null;
       const ts = Date.parse(r.timestamp);
       if (activity && Number.isFinite(ts)) result.lastActivity = Math.max(result.lastActivity ?? 0, ts);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cachetoast",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local, provider-neutral handoffs and cache-aware session rotation for coding agents",
   "type": "module",
   "license": "MIT",