@prohost/cli 0.13.2 → 0.14.0

package/dist/codehost/hooks.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Claude Code hooks and Codex `notify` for Mac-hosted Code threads.
+ *
+ * **Nothing global is installed.** The operator's `~/.claude/settings.json`
+ * and `~/.codex/config.toml` are never edited. Each thread's agent is launched
+ * with the hooks on its own command line — `claude --settings <file>`, `codex -c
+ * notify=[...]` — so they exist only in the sessions this host starts, and the
+ * one command they run is a shim that exits at once unless
+ * `$PROHOST_TERMINAL_ID` is set. A `claude` the operator starts in their own
+ * terminal sees none of it.
+ *
+ * The shim (`$PROHOST_HOME/code-host/bin/prohost-hook`) is rewritten on every
+ * daemon start to name the CLI that is installed now, so a session started
+ * under an older CLI (npx caches move) keeps working after an upgrade.
+ *
+ * What each hook reports (contract "Hook / host ingest"):
+ *
+ * | Hook | Event |
+ * | --- | --- |
+ * | `UserPromptSubmit` | `prompt {text}` |
+ * | `Stop` | `stop {finalText, question}` then `stats {...}` |
+ * | `PermissionRequest --wait <s>` | `permission_request {approvalId, command, options, capabilities: ['hook_decision'], waitMs, deadlineMs, sentAtMs}`, then waits for the decision and prints it (`decision.ts`); `prompt_local` if its wait runs out |
+ * | `PermissionRequest` (a window launched before `--wait`) | `permission_request`, then at once `prompt_local {reason: 'launched_before_update'}`: its Claude Code would kill a waiting hook at 10 s |
+ * | `Notification` (`permission_prompt`) | for a Claude Code without `PermissionRequest`: `permission_request`, then `prompt_local {reason: 'no_hook'}` |
+ * | `SessionStart` | nothing posted; like every hook, it marks the window past the trust dialog (`ready.ts`) |
+ * | Codex `agent-turn-complete` | `prompt` (when it carries one) then `stop` |
+ *
+ * `question` is always true for an interactive turn: when an interactive agent
+ * stops, its turn is over and nothing more happens until a person types — that
+ * is a hand-off by construction, not a reading of what it said.
+ *
+ * Ordinary hooks print nothing (a `UserPromptSubmit` hook's stdout becomes part of the
+ * prompt), except a waiting `PermissionRequest` hook's decision from ProhostAI,
+ * which never blocks the menu (Claude Code draws it while the hook runs, and
+ * applies whichever answers first). The verified modern profile also records
+ * PreToolUse IDs; recording failures block the tool rather than returning success. Claude Code and
+ * Codex credentials are never read; the only Claude file read is the session's
+ * own transcript, for the turn's final text and token counts, and for whether a
+ * held prompt's call is over (`decision.ts`).
+ */
+import type { CodeThreadEvent } from './events.js';
+import type { HostDecision } from './decision.js';
+export declare const TERMINAL_ID_ENV = "PROHOST_TERMINAL_ID";
+export declare const CODE_THREAD_ID_ENV = "PROHOST_CODE_THREAD_ID";
+/** Claude Code hook events this host registers. */
+export declare const CLAUDE_HOOK_EVENTS: readonly ["SessionStart", "UserPromptSubmit", "Stop", "PermissionRequest", "Notification"];
+export type ClaudeHookEvent = (typeof CLAUDE_HOOK_EVENTS)[number];
+export declare const APPROVAL_OPTIONS: readonly ["allow", "allow_session", "deny"];
+/**
+ * Declared on a `permission_request` whose decision the hook itself returns
+ * (`decision.ts`): the server may relay a decision the moment it has the
+ * prompt, since it can only ever answer that prompt.
+ */
+export declare const HOOK_DECISION_CAPABILITY = "hook_decision";
+/** Waits between `permission_request` attempts whose outcome is unknown, within the hook's wait. */
+export declare const POST_RETRY_DELAYS_MS: number[];
+/** Waits between `approval_overridden_locally` attempts, all within {@link OVERRIDE_BUDGET_MS}. */
+export declare const OVERRIDE_RETRY_DELAYS_MS: number[];
+/** Every correction attempt ends this soon after the PostToolUse hook started, under its 10 s timeout. */
+export declare const OVERRIDE_BUDGET_MS = 8000;
+/**
+ * How long the `PermissionRequest` hook waits for a decision from ProhostAI.
+ * The menu is up in the terminal all along (Claude Code draws it while the hook
+ * runs), so the person at the Mac is never kept waiting by it: this bounds only
+ * how long a decision from ProhostAI may still answer the prompt.
+ */
+export declare const HOOK_DECISION_WAIT_S = 120;
+/** The hook's own timeout, past which Claude Code kills it: above its wait. */
+export declare const PERMISSION_HOOK_TIMEOUT_S = 150;
+export declare const MAX_PREVIEW_CHARS = 280;
+export declare function hookBinDir(env?: NodeJS.ProcessEnv): string;
+export declare function hookShimPath(env?: NodeJS.ProcessEnv): string;
+export declare function claudeSettingsPath(env?: NodeJS.ProcessEnv): string;
+/** The shim script: env-guarded, then the current CLI's `hook` command. */
+export declare function hookShimScript(nodePath: string, cliEntrypoint: string): string;
+/** The `--settings` document Claude Code is launched with: hooks only. */
+export declare function claudeHookSettings(shimPath: string, invocationProtocol?: boolean): Record<string, unknown>;
+/** Codex `-c notify=[...]` value (TOML array), naming the shim. */
+export declare function codexNotifyOverride(shimPath: string): string;
+/** Write the shim and Claude settings. Called on every daemon start. */
+export declare function installHookFiles(nodePath: string, cliEntrypoint: string, env?: NodeJS.ProcessEnv): {
+    shim: string;
+    claudeSettings: string;
+    claudeInvocationSettings: string;
+};
+/** Last non-empty line, clipped — the inbox row's preview. */
+export declare function previewOf(text: string): string | undefined;
+export interface TranscriptTurn {
+    finalText?: string;
+    tokensTotal?: number;
+    tokensCachedPct?: number;
+}
+/**
+ * The last assistant turn of a Claude Code transcript (JSONL): its text and
+ * token usage. Unknown shapes yield nothing rather than zeros.
+ */
+export declare function parseTranscriptTail(content: string): TranscriptTurn;
+/** `git diff --shortstat` numbers for a worktree, against where its branch left the default branch. */
+export declare function parseShortstat(text: string): {
+    filesChanged: number;
+    additions: number;
+    deletions: number;
+};
+export type GitRunner = (args: string[], cwd: string) => Promise<string | undefined>;
+/**
+ * What the thread changed in its worktree, against where its branch left the
+ * default branch: commits, uncommitted edits, and new files not yet added
+ * (`git diff` alone never counts an untracked file, so a thread that made one
+ * would read "No changes yet").
+ */
+export declare function diffStats(cwd: string, git?: GitRunner, countLines?: (file: string) => number): Promise<{
+    filesChanged: number;
+    additions: number;
+    deletions: number;
+} | undefined>;
+/** Stable approval id for one permission prompt, so a retried hook doesn't make two. */
+export declare function approvalIdFor(parts: (string | undefined)[]): string;
+/** A one-line description of what a tool wants to do. */
+export declare function permissionCommand(toolName: string | undefined, toolInput: unknown): string;
+export interface HookContext {
+    env: NodeJS.ProcessEnv;
+    now: () => number;
+    git: GitRunner;
+    readTranscript: (file: string) => string | undefined;
+}
+/** Events for one Claude Code hook invocation. Pure apart from the context's readers. */
+export declare function claudeHookEvents(hook: string, input: Record<string, unknown>, ctx: HookContext): Promise<CodeThreadEvent[]>;
+/** Events for one Codex `notify` call; `payload` is the JSON Codex passes as the last argument. */
+export declare function codexNotifyEvents(payload: string, now: number): CodeThreadEvent[];
+/**
+ * One hook can report several events at the moment it fired (`stop` then
+ * `stats`). Ingest drops an event older than the newest it applied for the
+ * thread, so each later event gets a later `at` — a millisecond apart.
+ */
+export declare function strictlyIncreasing(events: CodeThreadEvent[]): CodeThreadEvent[];
+export interface RunHookOptions {
+    env?: NodeJS.ProcessEnv;
+    stdin?: NodeJS.ReadableStream;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    git?: GitRunner;
+    sleep?: (ms: number) => Promise<void>;
+    /** A waiting `PermissionRequest` hook's decision output (default: stdout). */
+    stdout?: (text: string) => void;
+    /** Registers what runs when Claude Code stops a waiting hook (default: the signal handlers). */
+    onStop?: (handler: () => void) => void;
+    claudeVersion?: () => Promise<string | undefined>;
+}
+/** `--wait <seconds>` on the hook's command line, capped below its timeout; 0 without one. */
+export declare function waitArg(args: string[]): number;
+/**
+ * "Allow for this session", as Claude Code offers it for this prompt: its first
+ * suggestion that adds an allow rule, kept to the session. Only that kind: a
+ * suggestion to add a directory or switch mode grants more than the one call
+ * the person decided on. None: the option isn't offered.
+ */
+export declare function sessionRule(suggestions: unknown): Record<string, unknown> | undefined;
+/** The hook's stdout for a decision: what Claude Code applies to the prompt. */
+export declare function decisionOutput(decision: HostDecision, rule: Record<string, unknown> | undefined): string;
+export interface PermissionWait {
+    /** How long to wait for a decision from ProhostAI. */
+    waitMs: number;
+    /**
+     * Why the prompt is the terminal's when the hook doesn't wait (`waitMs` 0), as `prompt_local`
+     * says it: remote control is off, or the window was launched before hooks waited.
+     */
+    localReason: PromptLocalReason;
+    stdout: (text: string) => void;
+    /** Called with a handler for SIGTERM/SIGINT/SIGHUP: Claude Code stopping the hook (Escape, "No"). */
+    onStop: (handler: () => void) => void;
+}
+/** Why a prompt is answered in the terminal, as `prompt_local {reason}` tells the server. */
+export type PromptLocalReason = 'timeout' | 'remote_off' | 'launched_before_update' | 'no_hook';
+/**
+ * `prohost hook claude <Event>` / `prohost hook codex <payload>`. Critical invocation
+ * recording failures are nonzero; ordinary reporting failures stay nonblocking.
+ */
+export declare function runHook(args: string[], options?: RunHookOptions): Promise<number>;