one-code-extension 0.4.0 → 0.5.0

package/extensions/hooks/protocol.ts

@@ -2,10 +2,12 @@
  * Claude Code hook protocol (pure): the stdin payload shape, the stdout JSON
  * envelope, and the mapping from a finished hook run to what One Code should do
  * about it. Envelope semantics follow Claude Code's hooks reference; the
- * fail-closed choices are One Code's own (see docs/decisions.md).
+ * fail-closed choices are One Code's own (see working-docs/decisions.md).
  */
 
 import { isAppendedReminderText } from "../lib/reminders.ts";
+import { emptyToolResultText } from "../lib/empty-tool-result.ts";
+import type { SessionBackgroundTask, SessionCron } from "../lib/session-work.ts";
 
 /** The contiguous run of reminder/countdown blocks at the tail of a tool result (review M3). */
 function trailingReminderBlocks<T extends { type: string }>(content: readonly T[]): T[] {
@@ -51,6 +53,10 @@ export interface HookStdinPayload {
 	tool_response?: { content: unknown; is_error: boolean };
 	prompt?: string;
 	stop_hook_active?: boolean;
+	/** Stop: in-flight background work (Claude Code's `background_tasks`). */
+	background_tasks?: SessionBackgroundTask[];
+	/** Stop: jobs that will wake the session later (Claude Code's `session_crons`). */
+	session_crons?: SessionCron[];
 	trigger?: "manual" | "auto";
 	/** PreCompact: the `/compact <instructions>` text, empty when none (Claude Code sends the string as is). */
 	custom_instructions?: string;
@@ -97,6 +103,8 @@ export function parseEnvelope(stdout: string): HookEnvelope | undefined {
 /** What one finished hook run asks One Code to do. */
 export interface HookOutcome {
 	block?: { reason: string };
+	/** Stop continue:false ends the turn rather than requesting another response. */
+	preventContinuation?: boolean;
 	updatedInput?: Record<string, unknown>;
 	updatedToolResult?: unknown;
 	additionalContext?: string;
@@ -104,8 +112,24 @@ export interface HookOutcome {
 }
 
 export interface FinishedRun {
+	/**
+	 * null when the process was killed (timeout) or never spawned. Normalized on
+	 * the timeout path rather than taken from `waitpid`: a group SIGKILL is not
+	 * atomic, so the shell can be scheduled after its foreground child is killed
+	 * and before its own signal lands, reap the child and exit(128+9) itself —
+	 * `close` then reports a normal exit of 137 instead of death by signal
+	 * (roughly 1% of timeouts under load, and never when the shell had exec'd
+	 * away, leaving no shell to reap; findings §10.20). Callers should still
+	 * prefer `timedOut`, which says what happened rather than what it looked
+	 * like, but they no longer have to.
+	 */
 	exitCode: number | null;
 	timedOut: boolean;
+	/** The calling turn or child session was cancelled. */
+	aborted?: boolean;
+	/** Output is incomplete and must not be interpreted as a hook response. */
+	outputLimitExceeded?: boolean;
+	/** Set when the child could not be spawned at all. */
 	spawnError?: string;
 	stdout: string;
 	stderr: string;
@@ -117,9 +141,19 @@ const TIMEOUT_BLOCKS: ReadonlySet<CcHookEvent> = new Set(["PreToolUse", "UserPro
  * Events where CC's plain (non-JSON) stdout becomes model-visible context
  * rather than being discarded.
  */
-const STDOUT_IS_CONTEXT: ReadonlySet<CcHookEvent> = new Set(["UserPromptSubmit", "SessionStart"]);
+const STDOUT_IS_CONTEXT: ReadonlySet<CcHookEvent> = new Set(["UserPromptSubmit", "SessionStart", "PreCompact"]);
+
+/** A cancelled run: the gating events block, the rest pass. */
+export function cancelledOutcome(event: CcHookEvent): HookOutcome {
+	return TIMEOUT_BLOCKS.has(event) ? { block: { reason: "Hook cancelled" } } : {};
+}
 
 export function interpretHookResult(event: CcHookEvent, run: FinishedRun): HookOutcome {
+	if (run.aborted) return cancelledOutcome(event);
+	if (run.outputLimitExceeded) {
+		const reason = "Hook exceeded its output limit; reduce stdout/stderr to at most 1,000,000 bytes per stream.";
+		return TIMEOUT_BLOCKS.has(event) ? { block: { reason } } : { systemMessage: reason };
+	}
 	// Killed (timeout or otherwise): a null exit code must never read as a
 	// clean allow. Closed for the two events that gate something; open for the
 	// rest — the side effect already happened, or blocking would wedge exit.
@@ -146,6 +180,7 @@ export function interpretHookResult(event: CcHookEvent, run: FinishedRun): HookO
 
 	if (envelope.continue === false) {
 		outcome.block = { reason: envelope.stopReason?.trim() || "Hook stopped continuation" };
+		if (event === "Stop") outcome.preventContinuation = true;
 	}
 	const decision = specific?.permissionDecision;
 	if (decision === "deny" || decision === "ask") {
@@ -191,6 +226,7 @@ interface TextBlock {
 export function applyPostToolUseOutcome<T extends { type: string }>(
 	content: readonly T[],
 	outcome: Pick<HookOutcome, "block" | "updatedToolResult" | "additionalContext">,
+	toolName: string,
 ): Array<T | TextBlock> | undefined {
 	if (!outcome.block && outcome.updatedToolResult === undefined && !outcome.additionalContext) return undefined;
 	let result: Array<T | TextBlock> = [...content];
@@ -201,7 +237,9 @@ export function applyPostToolUseOutcome<T extends { type: string }>(
 		// tool_result hook before ours). Replacing the content must not drop
 		// them, so keep the trailing run of reminder blocks (review M3).
 		const reminderTail = trailingReminderBlocks(content);
-		result = [{ type: "text", text: typeof replacement === "string" ? replacement : JSON.stringify(replacement) }, ...reminderTail];
+		const text = typeof replacement === "string" ? replacement : JSON.stringify(replacement);
+		// The hook's own text: an empty one gets the marker for every tool, read included.
+		result = [{ type: "text", text: text.trim() ? text : emptyToolResultText(toolName) }, ...reminderTail];
 	}
 	if (outcome.block) result = [{ type: "text", text: `PostToolUse hook: ${outcome.block.reason}` }, ...result];
 	if (outcome.additionalContext) result = [...result, { type: "text", text: outcome.additionalContext }];

package/extensions/hooks/settings.ts

@@ -1,9 +1,10 @@
 /**
  * Hook config discovery and merge (pure fs reads, no pi imports).
  *
- * Sources, lowest authority first: user ~/.claude/settings.json, managed
+ * Sources, in collection order: user ~/.claude/settings.json, managed
  * settings (Claude Code's platform paths), project .claude/settings.json,
- * project .claude/settings.local.json. Project and local sources are
+ * project .claude/settings.local.json (independent mode: One Code's user and
+ * per-repo settings, `hookSettingsPaths`). Project and local sources are
  * *returned flagged, not filtered* — whether they run is a trust decision
  * (hooks are arbitrary code execution) that index.ts applies via trust.ts;
  * this module stays pure.
@@ -14,7 +15,10 @@
  */
 
 import { readFileSync, statSync } from "node:fs";
+import os from "node:os";
 import { join } from "node:path";
+import { managedSettingsPaths, settingsSources } from "../lib/claude-settings.ts";
+import { claudeSourcesOn } from "../lib/config-mode.ts";
 import { CC_HOOK_EVENTS, type CcHookEvent } from "./protocol.ts";
 
 /** Claude Code's per-hook `shell` field: which interpreter runs the command string. */
@@ -50,21 +54,23 @@ export interface HooksSource {
 
 export interface LoadedHooks {
 	sources: HooksSource[];
+	/** Configured sources are filtered; collectors must also suppress plugin hooks when set. */
+	disabled?: "all" | "unmanaged";
 	/** Malformed entries are skipped and reported, never fatal. */
 	diagnostics: string[];
 }
 
-/** Managed-settings locations — Claude Code's exact per-platform paths. */
-export function managedSettingsPath(platform: NodeJS.Platform = process.platform): string {
-	if (platform === "darwin") return "/Library/Application Support/ClaudeCode/managed-settings.json";
-	if (platform === "win32") return "C:\\ProgramData\\ClaudeCode\\managed-settings.json";
-	return "/etc/claude-code/managed-settings.json";
-}
-
-export function hookSettingsPaths(claudeDir: string, cwd: string): Array<{ scope: HookScope; path: string }> {
+/**
+ * The settings files hooks are read from, in collection order. Independent
+ * mode (lib/config-mode.ts) reads One Code's user file and its per-repo file
+ * under `~/.onecode/projects/<slug>/` instead; neither ships in a repository,
+ * so both are user scope and need no project-trust prompt.
+ */
+export function hookSettingsPaths(claudeDir: string, cwd: string, home: string = os.homedir()): Array<{ scope: HookScope; path: string }> {
+	if (!claudeSourcesOn()) return settingsSources(cwd, home).map(([, path]) => ({ scope: "user" as const, path }));
 	return [
 		{ scope: "user", path: join(claudeDir, "settings.json") },
-		{ scope: "managed", path: managedSettingsPath() },
+		...managedSettingsPaths().map((path) => ({ scope: "managed" as const, path })),
 		{ scope: "project", path: join(cwd, ".claude", "settings.json") },
 		{ scope: "local", path: join(cwd, ".claude", "settings.local.json") },
 	];
@@ -130,13 +136,14 @@ export function parseHooksBlock(raw: unknown, origin: string, diagnostics: strin
 interface CacheEntry {
 	mtimeMs: number;
 	config: HooksFileConfig;
+	disableAllHooks?: boolean;
 	diagnostics: string[];
 }
 
 const cache = new Map<string, CacheEntry>();
 
-/** Read one settings file's hooks block, via the mtime cache. */
-function readHooksFile(path: string, diagnostics: string[]): HooksFileConfig | undefined {
+/** Read one settings file's hooks and disabling flag, via the mtime cache. */
+function readHooksFile(path: string, diagnostics: string[]): CacheEntry | undefined {
 	let mtimeMs: number;
 	try {
 		mtimeMs = statSync(path).mtimeMs;
@@ -147,27 +154,51 @@ function readHooksFile(path: string, diagnostics: string[]): HooksFileConfig | u
 	const cached = cache.get(path);
 	if (cached && cached.mtimeMs === mtimeMs) {
 		diagnostics.push(...cached.diagnostics);
-		return cached.config;
+		return cached;
 	}
 	const fileDiagnostics: string[] = [];
 	let config: HooksFileConfig = {};
+	let disableAllHooks: boolean | undefined;
 	try {
-		const parsed = JSON.parse(readFileSync(path, "utf-8")) as { hooks?: unknown };
+		const parsed = JSON.parse(readFileSync(path, "utf-8")) as { hooks?: unknown; disableAllHooks?: unknown };
 		config = parseHooksBlock(parsed.hooks, path, fileDiagnostics);
+		if (typeof parsed.disableAllHooks === "boolean") disableAllHooks = parsed.disableAllHooks;
 	} catch (error) {
 		fileDiagnostics.push(`${path}: unreadable settings file skipped (${error instanceof Error ? error.message : error})`);
 	}
-	cache.set(path, { mtimeMs, config, diagnostics: fileDiagnostics });
+	const entry: CacheEntry = { mtimeMs, config, disableAllHooks, diagnostics: fileDiagnostics };
+	cache.set(path, entry);
 	diagnostics.push(...fileDiagnostics);
-	return config;
+	return entry;
 }
 
 export function loadHookSettings(claudeDir: string, cwd: string): LoadedHooks {
 	const diagnostics: string[] = [];
 	const sources: HooksSource[] = [];
+	let userDisableAllHooks: boolean | undefined;
+	let managedDisableAllHooks: boolean | undefined;
+	let repoDisableAllHooks: boolean | undefined;
 	for (const { scope, path } of hookSettingsPaths(claudeDir, cwd)) {
-		const config = readHooksFile(path, diagnostics);
-		if (config && Object.keys(config).length > 0) sources.push({ scope, path, config });
+		const entry = readHooksFile(path, diagnostics);
+		if (!entry) continue;
+		if (entry.disableAllHooks !== undefined) {
+			if (scope === "managed") managedDisableAllHooks = entry.disableAllHooks;
+			else if (scope === "user") userDisableAllHooks = entry.disableAllHooks;
+			else repoDisableAllHooks = entry.disableAllHooks;
+		}
+		if (Object.keys(entry.config).length > 0) sources.push({ scope, path, config: entry.config });
+	}
+	// Collection order stays stable, but managed booleans have highest precedence.
+	// A non-managed disable must not turn off organization-managed hooks.
+	if (managedDisableAllHooks === true) return { sources: [], diagnostics, disabled: "all" };
+	if ((managedDisableAllHooks ?? userDisableAllHooks) === true) {
+		return { sources: sources.filter((source) => source.scope === "managed"), diagnostics, disabled: "unmanaged" };
+	}
+	// A repository's flag reaches only its own hooks: a cloned repo must not
+	// switch off the user's guard hooks, as project settings never set autoMode.
+	if (managedDisableAllHooks === undefined && repoDisableAllHooks === true) {
+		diagnostics.push("disableAllHooks in project settings turns off only the project's own hooks");
+		return { sources: sources.filter((source) => source.scope === "user" || source.scope === "managed"), diagnostics };
 	}
 	return { sources, diagnostics };
 }

package/extensions/hooks/subagent-bridge.ts

@@ -33,6 +33,8 @@ export interface ChildHookCall {
 	input: Record<string, unknown>;
 	/** The child's runtime cwd (a worktree, if isolated). */
 	cwd: string;
+	/** The child's turn signal; cancelling it must stop its hooks, not the parent's. */
+	signal?: AbortSignal;
 	/** The child session's id — becomes the payload's `session_id` and `agent_id`. */
 	sessionId?: string;
 	/** The child's session file, if persisted (payload `transcript_path`). */

package/extensions/hooks/trust.ts

@@ -17,9 +17,9 @@
 
 import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname } from "node:path";
 import { boundConsentItems } from "../lib/consent-preview.ts";
-import { oneCodeStateDir } from "../lib/paths.ts";
+import { consentStorePath } from "../lib/consent-stores.ts";
 import type { HooksSource } from "./settings.ts";
 
 interface ApprovalStore {
@@ -28,7 +28,7 @@ interface ApprovalStore {
 }
 
 export function approvalStorePath(): string {
-	return join(oneCodeStateDir(), "hooks", "project-approvals.json");
+	return consentStorePath("hooks");
 }
 
 /** Key order must not change the hash — two spellings of one config are one consent. */
@@ -98,6 +98,7 @@ export interface TrustDecisionDeps {
 	confirm: (title: string, message: string) => Promise<boolean | undefined>;
 	notify: (message: string) => void;
 	storePath?: string;
+	signal?: AbortSignal;
 	/**
 	 * Answer from the remembered/stored approval only: neither prompt nor record
 	 * a decision. For a dispatch at session shutdown — recording "declined" there
@@ -108,7 +109,8 @@ export interface TrustDecisionDeps {
 
 /** Process-lifetime memory of declined/approved hashes per project, so a dispatch storm asks once. */
 const sessionDecisions = new Map<string, boolean>();
-const pendingPrompts = new Map<string, Promise<boolean>>();
+/** Undefined: the dispatch that opened the prompt aborted, so nobody decided. */
+const pendingPrompts = new Map<string, Promise<boolean | undefined>>();
 
 /**
  * Whether the project/local hook sources may run. Resolves without prompting
@@ -120,6 +122,7 @@ export async function projectHooksApproved(
 	projectSources: HooksSource[],
 	deps: TrustDecisionDeps,
 ): Promise<boolean> {
+	if (deps.signal?.aborted) return false;
 	if (projectSources.length === 0) return true;
 	const configHash = hashProjectHooks(projectSources);
 	const key = `${projectRoot}:${configHash}`;
@@ -145,6 +148,8 @@ export async function projectHooksApproved(
 					"Run this project's hooks?",
 					`This project's .claude settings define ${describeProjectHooks(projectSources)}\n\nThey run as shell commands on your machine. Approval is remembered until the hook config changes.`,
 				)) === true;
+			// An interrupted dialog is no trust decision, even if a reply raced abort.
+			if (deps.signal?.aborted) return undefined;
 			sessionDecisions.set(key, approved);
 			if (approved) persistApproval(projectRoot, configHash, deps.storePath);
 			else deps.notify("Project hooks disabled for this session (user/managed hooks still run).");
@@ -152,7 +157,10 @@ export async function projectHooksApproved(
 		})().finally(() => pendingPrompts.delete(key));
 		pendingPrompts.set(key, pending);
 	}
-	return pending;
+	const decided = await pending;
+	if (deps.signal?.aborted) return false;
+	// The opener aborted without an answer: a dispatch still live asks again.
+	return decided ?? projectHooksApproved(projectRoot, projectSources, deps);
 }
 
 /** Test seam. */

package/extensions/idle-compact/index.ts

@@ -0,0 +1,119 @@
+/**
+ * idle-compact extension — Claude Code's compaction of an idle session before
+ * its one-hour prompt cache expires (rules and refusal order: policy.ts).
+ *
+ * Wiring: the timer follows the compaction extension's capture of the
+ * session's last request (`LAST_REQUEST_CHANNEL`), the very request its
+ * cache-reading replay sends. Each capture re-arms it when the body caches for
+ * one hour (`hasOneHourCache`); a cleared capture (a new session, a compaction,
+ * a branch switch) drops it, so the timer is armed only while a replay is
+ * possible. The reply's usage says whether the cache was warm, the response
+ * headers carry Anthropic's rate-limit status, and keystrokes
+ * (`onTerminalInput`) mark the user present.
+ *
+ * TUI only: RPC mode also runs the one-hour cache, but its host's input never
+ * reaches `onTerminalInput`, so the presence check could not hold a
+ * compaction off while someone is there.
+ *
+ * On fire it calls `ctx.compact()`; pi's TUI shows its usual "Compacting"
+ * indicator, Esc cancels, and on success a display-only entry carries Claude
+ * Code's notice. Failures are silent, as in Claude Code.
+ */
+
+import { type ExtensionAPI, type ExtensionContext, getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { hasOneHourCache } from "../lib/anthropic-payload.ts";
+import { modelSpec } from "../lib/model-policy.ts";
+import { LAST_REQUEST_CHANNEL, type RequestCapture } from "../lib/request-replay.ts";
+import { unrefTimers } from "../lib/timer-ops.ts";
+import { dimMarkedLine, liveUiCtx } from "../lib/tui-render.ts";
+import { type ArmedRequest, IDLE_COMPACT_NOTICE, IdleCompactTimer, type IdleCompactConfig, idleCompactConfig, idleRefusal } from "./policy.ts";
+
+const ENTRY_TYPE = "one-code:idle-compact";
+const NOTICE_MARK = "●";
+const RATE_LIMIT_HEADER = "anthropic-ratelimit-unified-status";
+
+/** pi's auto-compaction setting; unreadable settings mean pi's default, on. */
+function autoCompactionOn(cwd: string): boolean {
+	try {
+		return SettingsManager.create(cwd, getAgentDir()).getCompactionEnabled();
+	} catch {
+		return true;
+	}
+}
+
+export default function idleCompactExtension(pi: ExtensionAPI) {
+	pi.registerEntryRenderer(ENTRY_TYPE, (_entry, _options, theme) => dimMarkedLine(theme, NOTICE_MARK, IDLE_COMPACT_NOTICE));
+
+	let sessionCtx: ExtensionContext | undefined;
+	let warm = false;
+	let rateLimitStatus: string | undefined;
+	let lastInteractionAt: number | undefined;
+	let inputHookRegistered = false;
+
+	const timer = new IdleCompactTimer(unrefTimers, Date.now, () => idleCompactConfig(process.env), (armed, dueAt, config) => fire(armed, dueAt, config));
+
+	function fire(armed: ArmedRequest, dueAt: number, config: IdleCompactConfig) {
+		const ctx = liveUiCtx(sessionCtx);
+		if (!ctx) return;
+		const refusal = idleRefusal(armed, {
+			now: Date.now(),
+			dueAt,
+			config,
+			compactionOn: process.env.CC_COMPACTION !== "0" && autoCompactionOn(ctx.cwd),
+			model: ctx.model ? modelSpec(ctx.model) : undefined,
+			thinking: pi.getThinkingLevel(),
+			warm,
+			contextTokens: ctx.getContextUsage()?.tokens ?? 0,
+			rateLimitStatus,
+			idle: ctx.isIdle() && !ctx.hasPendingMessages(),
+			lastInteractionAt,
+		});
+		if (refusal !== null) return;
+		ctx.compact({
+			onComplete: () => pi.appendEntry(ENTRY_TYPE),
+			// Claude Code logs a failed idle compaction and shows nothing; pi's TUI
+			// still reports an error or an Esc cancel, as for any compaction.
+			onError: () => {},
+		});
+	}
+
+	pi.events.on(LAST_REQUEST_CHANNEL, (data) => {
+		const capture = data as RequestCapture | undefined;
+		const ctx = liveUiCtx(sessionCtx);
+		warm = false;
+		if (!capture || ctx?.mode !== "tui" || !hasOneHourCache(capture.payload)) {
+			timer.cancel();
+			return;
+		}
+		timer.arm({ at: Date.now(), model: modelSpec({ provider: capture.provider, id: capture.modelId }), thinking: pi.getThinkingLevel() });
+	});
+
+	pi.on("after_provider_response", (event) => {
+		if (!timer.pending) return;
+		const entry = Object.entries(event.headers ?? {}).find(([name]) => name.toLowerCase() === RATE_LIMIT_HEADER);
+		rateLimitStatus = entry?.[1];
+	});
+
+	pi.on("message_end", (event) => {
+		const message = event.message as { role?: string; usage?: { cacheRead?: number; cacheWrite?: number } };
+		if (message.role === "assistant") warm = (message.usage?.cacheRead ?? 0) + (message.usage?.cacheWrite ?? 0) > 0;
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		sessionCtx = ctx;
+		rateLimitStatus = undefined;
+		lastInteractionAt = undefined;
+		if (!ctx.hasUI || inputHookRegistered) return;
+		// Registered once: session_start fires again on every /clear and switch.
+		inputHookRegistered = true;
+		ctx.ui.onTerminalInput(() => {
+			lastInteractionAt = Date.now();
+			return undefined; // observe only
+		});
+	});
+
+	pi.on("session_shutdown", () => {
+		timer.cancel();
+		sessionCtx = undefined;
+	});
+}

package/extensions/idle-compact/policy.ts

@@ -0,0 +1,143 @@
+/**
+ * Idle compaction's rules, pure (no pi imports; index.ts is the wiring).
+ *
+ * Claude Code 2.1.289 compacts an idle main session shortly before its
+ * one-hour prompt cache expires: the compaction reads the warm cache at the
+ * cached rate, where the user's next prompt after expiry would write the whole
+ * context to the cache again. Its rules, matched here:
+ *   - a timer is armed after every main-session request whose cache carries a
+ *     one-hour TTL, for 90% of the hour (`fireAtFraction`), so 54 minutes;
+ *   - when it fires, the first refusal below that applies wins, in Claude
+ *     Code's order: off, compaction off, prefix changed, lapsed (fired more
+ *     than 60 s late, or the cache is no longer warm), small (under 200,000
+ *     context tokens), near the rate limit; then the host's: busy (a turn
+ *     running or messages queued), present (a keystroke in the last 60 s);
+ *   - otherwise it compacts with no instructions and shows
+ *     "Compacted while idle, before the prompt cache expired".
+ * Claude Code's `not_one_hour` and `newer_request` refusals need no check
+ * here: every request replaces the timer, and only a one-hour request arms one.
+ *
+ * Claude Code ships it behind a server flag that defaults off; One Code turns
+ * it on, with `CC_IDLE_COMPACT=0` to opt out (working-docs/decisions/caching.md,
+ * "Idle compaction before the cache expires").
+ */
+
+import type { TimerOps } from "../lib/timer-ops.ts";
+
+/** The notice Claude Code appends after an idle compaction. */
+export const IDLE_COMPACT_NOTICE = "Compacted while idle, before the prompt cache expired";
+
+/** The one-hour cache lifetime idle compaction is armed for. */
+export const ONE_HOUR_MS = 60 * 60_000;
+/** Claude Code's defaults (`minTokens` 200,000, `fireAtFraction` 0.9). */
+export const DEFAULT_MIN_TOKENS = 200_000;
+export const DEFAULT_FIRE_AT_FRACTION = 0.9;
+/** A timer that fires later than this may find the cache gone (the machine slept). */
+export const LATE_MS = 60_000;
+/** A keystroke this recent means the user is present: no compaction under them. */
+export const PRESENCE_MS = 60_000;
+
+export interface IdleCompactConfig {
+	enabled: boolean;
+	minTokens: number;
+	/** Delay from the request to the fire; undefined means `fireAtFraction` of the hour. */
+	delayMs?: number;
+}
+
+/**
+ * The config from the environment: `CC_IDLE_COMPACT=0` turns it off;
+ * `CC_IDLE_COMPACT_MIN_TOKENS` and `CC_IDLE_COMPACT_DELAY_MS` override the
+ * threshold and the fire delay, for live testing (the delay stays under the
+ * hour, at least one second).
+ */
+export function idleCompactConfig(env: Record<string, string | undefined>): IdleCompactConfig {
+	const minTokens = Number(env.CC_IDLE_COMPACT_MIN_TOKENS);
+	const delayMs = Number(env.CC_IDLE_COMPACT_DELAY_MS);
+	return {
+		enabled: env.CC_IDLE_COMPACT !== "0",
+		minTokens: Number.isFinite(minTokens) && minTokens >= 1 ? minTokens : DEFAULT_MIN_TOKENS,
+		...(Number.isFinite(delayMs) && delayMs >= 1000 && delayMs < ONE_HOUR_MS ? { delayMs } : {}),
+	};
+}
+
+/** Why a fire did not compact. */
+export type IdleRefusal = "disabled" | "compaction_off" | "prefix_changed" | "lapsed" | "small" | "near_limit" | "busy" | "present";
+
+/** The one-hour main-session request a timer was armed for. */
+export interface ArmedRequest {
+	/** When it went out (ms). */
+	at: number;
+	/** `provider/id` and thinking level it ran with: the cache's identity. */
+	model: string | undefined;
+	thinking: string | undefined;
+}
+
+/** What the session looks like when the timer fires. */
+export interface FireProbe {
+	now: number;
+	/** When the timer was due. */
+	dueAt: number;
+	config: IdleCompactConfig;
+	/** pi's auto-compaction setting, and One Code's cache-reading compaction (CC_COMPACTION). */
+	compactionOn: boolean;
+	model: string | undefined;
+	thinking: string | undefined;
+	/** The armed request's reply reported cache reads or writes. */
+	warm: boolean;
+	contextTokens: number;
+	/** Anthropic's `anthropic-ratelimit-unified-status` from the latest response, if any. */
+	rateLimitStatus: string | undefined;
+	idle: boolean;
+	lastInteractionAt: number | undefined;
+}
+
+/** The first refusal that applies, in Claude Code's order, or null to compact. */
+export function idleRefusal(armed: ArmedRequest, probe: FireProbe): IdleRefusal | null {
+	if (!probe.config.enabled) return "disabled";
+	if (!probe.compactionOn) return "compaction_off";
+	if (probe.model !== armed.model || probe.thinking !== armed.thinking) return "prefix_changed";
+	// The expiry half only trips under a CC_IDLE_COMPACT_DELAY_MS near the hour:
+	// at the default 54 minutes the lateness check trips first.
+	if (probe.now - probe.dueAt > LATE_MS || !probe.warm || probe.now >= armed.at + ONE_HOUR_MS) return "lapsed";
+	if (probe.contextTokens < probe.config.minTokens) return "small";
+	if (probe.rateLimitStatus !== undefined && probe.rateLimitStatus !== "allowed") return "near_limit";
+	if (!probe.idle) return "busy";
+	if (probe.lastInteractionAt !== undefined && probe.now - probe.lastInteractionAt < PRESENCE_MS) return "present";
+	return null;
+}
+
+/**
+ * One pending timer for the latest one-hour request. Each `arm` replaces it;
+ * `cancel()` drops it when the session's last request stops being a one-hour
+ * one, or there is none (a new session, a compaction, a branch switch).
+ */
+export class IdleCompactTimer {
+	private handle: unknown;
+
+	constructor(
+		private readonly timer: TimerOps,
+		private readonly now: () => number,
+		private readonly config: () => IdleCompactConfig,
+		private readonly onFire: (armed: ArmedRequest, dueAt: number, config: IdleCompactConfig) => void,
+	) {}
+
+	arm(request: ArmedRequest): void {
+		this.cancel();
+		const config = this.config();
+		if (!config.enabled) return;
+		const dueAt = request.at + (config.delayMs ?? ONE_HOUR_MS * DEFAULT_FIRE_AT_FRACTION);
+		this.handle = this.timer.set(() => {
+			this.handle = undefined;
+			this.onFire(request, dueAt, config);
+		}, Math.max(0, dueAt - this.now()));
+	}
+
+	cancel(): void {
+		if (this.handle !== undefined) this.timer.clear(this.handle);
+		this.handle = undefined;
+	}
+
+	get pending(): boolean {
+		return this.handle !== undefined;
+	}
+}

package/extensions/init/index.ts

@@ -1,26 +1,27 @@
 /**
  * init extension — Claude Code's `/init`.
  *
- * `/init` scans the repo and writes a concise CLAUDE.md for future sessions. It
- * is a prompt template, not procedural code: the handler submits INIT_PROMPT as
- * a user turn (pi.sendUserMessage) and the model does the work with the ordinary
- * tool set — subagent survey, ask_user_question, write. This mirrors how Claude
- * Code's `/init` is just a canned prompt.
+ * `/init` scans the repo and writes a CLAUDE.md for future sessions. It is a
+ * prompt template, not procedural code: the handler submits INIT_PROMPT
+ * (Claude Code's classic prompt) as a user turn (pi.sendUserMessage) and the
+ * model does the work with the ordinary tool set, as Claude Code's `/init`
+ * does.
  *
  * pi has no built-in `/init`, so a Claude Code user typing it would otherwise
  * have the word go to the model as a chat message.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createUserMessageSender } from "../lib/notifications.ts";
+import { promptCommandText } from "../skill/invoke.ts";
 import { INIT_PROMPT } from "./prompt.ts";
 
 export default function initExtension(pi: ExtensionAPI) {
+	const sendUserMessage = createUserMessageSender(pi);
 	pi.registerCommand("init", {
-		description: "Analyze the codebase and set up a CLAUDE.md for future sessions",
-		// sendUserMessage always triggers a turn and returns void; the async
-		// handler satisfies RegisteredCommand's Promise<void> contract.
-		handler: async () => {
-			pi.sendUserMessage(INIT_PROMPT, { deliverAs: "followUp" });
+		description: "Initialize a new CLAUDE.md file with codebase documentation",
+		handler: async (_args, ctx) => {
+			await sendUserMessage(ctx, promptCommandText("init", "", INIT_PROMPT));
 		},
 	});
 }