@cleocode/contracts 2026.10.1 → 2026.10.2

package/src/heavy-command-hook.ts

@@ -0,0 +1,136 @@
+/**
+ * Heavy-command provider hook — shared types.
+ *
+ * CLEO ships a pre-exec hook for agent harnesses (Claude Code, Codex, Kimi,
+ * opencode) that recognises heavy shell commands (test runners, compilers,
+ * builds, installs) and routes them through `cleo run`, so every agent on the
+ * machine shares the ResourceGovernor's one budget. The planner lives in
+ * `@cleocode/core` (`resources/heavy-command`, on top of `resources/run-class`),
+ * the provider wire formats and the entry point (`cleo hook heavy-command`) in
+ * `@cleocode/cleo` (`cli/hook-entry`), and the per-provider installers in
+ * `@cleocode/adapters` (`providers/shared/heavy-command-hook-install`).
+ *
+ * @task T12983
+ * @epic T12978
+ */
+
+/**
+ * How the hook treats a recognised heavy command.
+ *
+ * - `rewrite` — DEFAULT. Wrap it in place as
+ *   `cleo run --wait --passthrough --class <c> -- <cmd>`, when the harness
+ *   runs in `bypassPermissions` or `auto` mode and no deny or ask rule names
+ *   the command (otherwise the hook warns: a rewrite would change which
+ *   permission rules match).
+ * - `warn` — leave the command alone; add a context line naming the governed
+ *   form.
+ * - `off` — do nothing (the installer also removes the hook entry).
+ *
+ * Set by the `CLEO_HEAVY_COMMAND_HOOK` environment variable or the
+ * `resources.heavyCommandHook` config key (the variable wins).
+ */
+export type HeavyCommandHookMode = 'rewrite' | 'warn' | 'off';
+
+/** The harnesses `cleo hook heavy-command --provider <p>` answers for. */
+export type HeavyCommandHookProvider = 'claude-code' | 'codex' | 'kimi' | 'opencode';
+
+/** One heavy command found in a shell command line. */
+export interface HeavyCommandSegment {
+  /** The list element exactly as written (a simple command or a pipeline). */
+  readonly text: string;
+  /** The `cleo run --class` value: `test`, `build`, `full-build` or `db`. */
+  readonly runClass: string;
+  /** The element with `cleo run --wait --passthrough … --` inserted before the heavy command. */
+  readonly governed: string;
+  /** The heavy command's own words (quotes removed), command word first. */
+  readonly argv: readonly string[];
+}
+
+/**
+ * What the planner decided for one shell command line.
+ *
+ * - `none` — nothing heavy (or already governed): leave it alone.
+ * - `rewrite` — `command` is the whole line with every heavy command wrapped
+ *   in place; every other byte is unchanged.
+ * - `warn` — heavy, but rewriting could change what the line does (a heavy
+ *   command inside `$(…)`, a subshell, a compound command, a background job,
+ *   reading a heredoc, or sharing a pipeline with another heavy command), or
+ *   the hook may not rewrite here; `reason` says which.
+ */
+export type HeavyCommandPlan =
+  | { readonly action: 'none' }
+  | {
+      readonly action: 'rewrite';
+      readonly command: string;
+      readonly segments: readonly HeavyCommandSegment[];
+    }
+  | {
+      readonly action: 'warn';
+      readonly reason: string;
+      readonly segments: readonly HeavyCommandSegment[];
+    };
+
+/** A JSON value as a hook receives it on stdin. */
+export type HookJsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly HookJsonValue[]
+  | { readonly [key: string]: HookJsonValue };
+
+/**
+ * A shell tool's input: Claude Code and Codex `Bash`, Kimi `Shell`, opencode
+ * `bash`. Every harness carries the command line in `command`; the other
+ * fields (`timeout`, `description`, `run_in_background`, …) vary.
+ */
+export interface ShellToolInput {
+  /** The shell command line the agent wants to run. */
+  readonly command: string;
+  /** Harness-specific fields, passed back unchanged unless noted. */
+  readonly [field: string]: HookJsonValue;
+}
+
+/**
+ * The fields of a `PreToolUse` hook's stdin JSON the heavy-command hook reads.
+ * Claude Code, Codex and Kimi send this shape; CLEO's generated opencode
+ * plugin sends the same fields.
+ */
+export interface PreToolUseHookInput {
+  readonly hook_event_name?: string;
+  /** `Bash` (Claude Code, Codex), `Shell` (Kimi), `bash` (opencode). */
+  readonly tool_name?: string;
+  readonly tool_input?: ShellToolInput;
+  /** The session's working directory. */
+  readonly cwd?: string;
+  /** Claude Code and Codex: `default`, `plan`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`. */
+  readonly permission_mode?: string;
+}
+
+/** The answer `cleo hook heavy-command --provider opencode` prints for CLEO's opencode plugin. */
+export interface OpencodeHeavyCommandAnswer {
+  /** Replacement for `output.args.command`, when the command was rewritten. */
+  readonly command?: string;
+  /** Replacement for `output.args.timeout` (ms): the old one plus the queue wait. */
+  readonly timeout?: number;
+  /** What the hook tells the agent; the plugin appends it to the tool's output. */
+  readonly context?: string;
+}
+
+/**
+ * The Claude-style `PreToolUse` hook answer on stdout. Claude Code, Codex and
+ * Kimi share this shape (each honours a different subset of it).
+ */
+export interface PreToolUseHookOutput {
+  readonly hookSpecificOutput: {
+    readonly hookEventName: 'PreToolUse';
+    /** Omitted unless the provider requires it (Codex rewrites need `allow`). */
+    readonly permissionDecision?: 'allow' | 'deny';
+    /** Shown to the agent on `deny`. */
+    readonly permissionDecisionReason?: string;
+    /** Replaces the whole tool input. */
+    readonly updatedInput?: ShellToolInput;
+    /** Added to the agent's context alongside the tool result. */
+    readonly additionalContext?: string;
+  };
+}

package/src/index.ts

@@ -774,6 +774,18 @@ export {
   confidenceLabelFromNumeric,
   provenanceFromNumeric,
 } from './graph.js';
+// === Heavy-command provider hook (T12983 / Epic T12978) ===
+export type {
+  HeavyCommandHookMode,
+  HeavyCommandHookProvider,
+  HeavyCommandPlan,
+  HeavyCommandSegment,
+  HookJsonValue,
+  OpencodeHeavyCommandAnswer,
+  PreToolUseHookInput,
+  PreToolUseHookOutput,
+  ShellToolInput,
+} from './heavy-command-hook.js';
 export type { AdapterHookProvider } from './hooks.js';
 export type { AdapterInstallProvider, InstallOptions, InstallResult } from './install.js';
 // === Invariants Registry (Saga T10326 / Epic T10327 / Task T10335 — SG-SUBSTRATE-RECONCILIATION) ===
@@ -783,6 +795,9 @@ export type {
   InvariantRuntimeGate,
   InvariantSeverity,
   RegisteredInvariant,
+  SyncWriteInvariant,
+  SyncWriteInvariantClass,
+  SyncWriteInvariantPending,
 } from './invariants/index.js';
 export {
   ADR_056_INVARIANTS,
@@ -790,6 +805,7 @@ export {
   getInvariant,
   getInvariantsByAdr,
   INVARIANTS_REGISTRY,
+  SYNC_WRITE_INVARIANTS,
 } from './invariants/index.js';
 // === Background Job Status (T9955 — promoted from core/store/tasks-schema.ts) ===
 export type { BackgroundJobStatus } from './jobs.js';
@@ -2265,6 +2281,8 @@ export {
   RESOURCE_BACKPRESSURE_CODE,
   RESOURCE_CLASSES,
   RESOURCE_DEFERRED_CODE,
+  RUN_COMMAND_FAILED_CODE,
+  RUN_DEFERRED_EXIT_CODE,
 } from './resource-governor.js';
 // === Result Types (Dashboard, Stats, Log, Context, Sequence, Analysis, Deps) ===
 export type {
@@ -3018,6 +3036,7 @@ export type {
   CloudPaging,
   CloudProjectShowResult,
   CloudProjectsResult,
+  CloudStatusGlobalStore,
   CloudStatusLocal,
   CloudStatusOfflineDetails,
   CloudStatusResult,
@@ -3073,4 +3092,29 @@ export {
   nexusCloudUserSchema,
   nexusCloudWhoamiSchema,
 } from './nexus-cloud.js';
+export {
+  type CloudActivityItem,
+  type CloudActivityResult,
+  type CloudLeaseReleaseResult,
+  type CloudPushResult,
+  type CloudRestoreResult,
+  type CloudVaultLease,
+  type CloudVaultScope,
+  type CloudVaultSnapshot,
+  type CloudVaultStatusResult,
+  type CloudVaultTable,
+  type CloudVaultTableDiff,
+  type CloudVerifyResult,
+  NEXUS_VAULT_LEASE_ROLE,
+  type NexusActivityEvent,
+  nexusActivityEventSchema,
+  nexusActivityPageSchema,
+  nexusLeaseAcquireSchema,
+  nexusLeaseSchema,
+  nexusProjectKeysSchema,
+  nexusStreamHeadSchema,
+  nexusUserKeysSchema,
+} from './nexus-vault.js';
+// === Sync schema version, shared by the change journal and the cloud vault (T13034) ===
+export { SYNC_SCHEMA_VERSION } from './sync-schema.js';
 export { isStorableTaskId, isTaskId, TASK_ID_REGEX, type TaskId } from './task-id.js';

package/src/install.ts

@@ -5,6 +5,8 @@
  * @task T5240
  */
 
+import type { HeavyCommandHookMode } from './heavy-command-hook.js';
+
 export interface AdapterInstallProvider {
   install(options: InstallOptions): Promise<InstallResult>;
   uninstall(): Promise<void>;
@@ -16,6 +18,13 @@ export interface AdapterInstallProvider {
 export interface InstallOptions {
   projectDir: string;
   global?: boolean;
+  /**
+   * The heavy-command hook mode (`resources.heavyCommandHook`, T12983).
+   * `rewrite`/`warn` install or refresh the project-level hook entry, `off`
+   * removes it, and `undefined` leaves the hook alone (callers that are not a
+   * project init/upgrade, such as global bootstrap, pass nothing).
+   */
+  heavyCommandHook?: HeavyCommandHookMode;
 }
 
 export interface InstallResult {

package/src/invariants/index.ts

@@ -36,6 +36,12 @@ import { ADR_073_INVARIANTS } from './adr-073-saga.js';
 export { ADR_056_INVARIANTS } from './adr-056-release.js';
 export { ADR_070_INVARIANTS } from './adr-070-orchestration.js';
 export { ADR_073_INVARIANTS } from './adr-073-saga.js';
+export type {
+  SyncWriteInvariant,
+  SyncWriteInvariantClass,
+  SyncWriteInvariantPending,
+} from './sync-write-invariants.js';
+export { SYNC_WRITE_INVARIANTS } from './sync-write-invariants.js';
 
 /**
  * Severity tier for a registered invariant.