/** * CLI Commands: auto-handoff, statusline, usage-guard * * specweave auto-handoff [on|off|status] [--mode suggest|enforce|checkpoint] [--at 95] [--wait-under 30] * specweave statusline [--wrap ""] (Claude Code status line) * specweave usage-guard (Stop hook, Claude Code and Codex) * specweave usage-guard --limit-hit (StopFailure hook, Claude Code and Grok Build) * * `auto-handoff on` wires the tools once, in the user's own settings. Every * hook saves a local checkpoint. When any window reaches the threshold, the * Stop hook acts once per usage window: in the default `suggest` mode the * session tells the user a handoff is available and keeps working; in * `enforce` mode it runs `specweave handoff` and stops. Neither happens when * every full window resets within `--wait-under` minutes. A turn that fails on * the rate limit hands off from the StopFailure hook itself in both modes: an * increment handoff, or, for a session in a worktree or nested repository or * with several increments active, a marked checkpoint of its own checkout that * `specweave handoff list` shows and `specweave pickup ` takes. * `checkpoint` mode keeps only the checkpoints, for plans where credits or a * proxy keep working past the limit. Inside SpecWeave Studio the hooks only * save the checkpoint: Studio switches provider between turns. The Stop hook * also stays quiet outside a SpecWeave project and for a Codex plan whose * credits will last. * * @module cli/commands/auto-handoff */ import { type AutoHandoffSettings } from '../../core/session/usage-guard.js'; /** Claude Code status line: record usage, then print a line (or the wrapped command's). */ export declare function statuslineCommand(opts?: { wrap?: string; home?: string; }): Promise; /** * Stop hook (Claude Code, Codex): queue a local checkpoint, then print `{}` or, * once per usage window at the threshold, the output that asks for a handoff. * With `limitHit` (StopFailure, Claude Code and Grok Build) the model has * already run out, so the hook writes the handoff itself, or only the * checkpoint when the mode or Studio says so. */ export declare function usageGuardCommand(opts?: { home?: string; limitHit?: boolean; input?: string; env?: NodeJS.ProcessEnv; }): Promise; /** * A session that hit the limit hands off through its own checkpoint when an * increment handoff would describe someone else's work: it ran in a worktree * or nested repository inside the project, or several increments are active * and nothing says which one is its. */ export declare function needsSessionHandoff(root: string, input: { session_id?: string; sessionId?: string; cwd?: string; workspaceRoot?: string; }): boolean; interface HookEntry { type?: string; command?: string; timeout?: number; env?: Record; } interface HookGroup { matcher?: string; hooks?: HookEntry[]; } type Settings = Record & { hooks?: Record; statusLine?: { type?: string; command?: string; }; }; /** Grok Build hook file: hand off when a turn fails on the rate limit. */ export declare function grokHook(): Settings; export interface AutoHandoffOptions { at?: number; /** `suggest`, `enforce` or `checkpoint`. */ mode?: string; /** Minutes; when every full window resets sooner, nothing is suggested or enforced. 0 turns it off. */ waitUnder?: number; /** Same as `--mode checkpoint`. */ checkpointOnly?: boolean; /** Same as `--mode enforce` (the only mode before 3.0.11). */ handoff?: boolean; home?: string; } /** What `on` says about the mode it set. */ export declare function modeSummary(settings: AutoHandoffSettings): string; export declare function autoHandoffCommand(action?: string, opts?: AutoHandoffOptions): Promise; /** * Codex runs a user hook only after the user trusts it, and records that in * ~/.codex/config.toml as a `[hooks.state."/.codex/hooks.json:stop::"]` * table with a `trusted_hash`. Plugin hooks use keys like * `"sw@specweave:hooks/hooks.json:stop:0:0"`, which say nothing about ours. * The hash covers the hook's content, so a changed hook needs approving again. * There is no command to approve one; Codex asks when it next starts in a terminal. */ export declare function codexHookTrusted(home?: string): boolean; /** * What `auto-handoff status` prints: checkpoint policy, whether each tool's hooks * are actually in place, and the last usage each tool reported. */ export declare function autoHandoffStatus(home?: string, now?: number): string[]; export {}; //# sourceMappingURL=auto-handoff.d.ts.map