@cleocode/contracts 2026.10.18 → 2026.10.19

package/src/project-hooks.ts

@@ -6,6 +6,15 @@ import type { HookJsonValue } from './heavy-command-hook.js';
 export const HookSourceSchema = z.enum(['agent', 'git', 'worktree', 'direct', 'ci']);
 /** Shared invocation origin. */
 export type HookSource = z.infer<typeof HookSourceSchema>;
+/** Native provenance supplied by the harness payload, never guessed from the working directory. */
+export const HookNativeSessionSchema = z
+  .object({
+    sessionId: z.string().min(1).max(256),
+    harness: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/),
+  })
+  .strict();
+/** Session and provider carried from a native agent event into its redacted receipt. */
+export type HookNativeSession = z.infer<typeof HookNativeSessionSchema>;
 /** A checkout-relative path; runtime validation also resolves symlinks. */
 export const ProjectHookPathSchema = z
   .string()
@@ -41,6 +50,8 @@ export const ProjectHookDefinitionSchema = z
   .strict();
 /** Validated project checker configuration. Handler is executable's first argument. */
 export type ProjectHookDefinition = z.infer<typeof ProjectHookDefinitionSchema>;
+/** One source/event binding, shared by retained-receipt selectors. */
+export type ProjectHookBinding = ProjectHookDefinition['bindings'][number];
 /** Tracked single source of truth; array order defines execution order. */
 export const ProjectHooksManifestSchema = z
   .object({
@@ -88,6 +99,8 @@ export interface HookInvocation {
   source: HookSource;
   /** Canonical event name. */
   event: string;
+  /** Optional native harness identity; absent inputs stay unverified. */
+  nativeSession?: HookNativeSession;
   /** Optional remote name and URL/path as Git supplies them. */
   remote?: { name: string; location: string };
   /** All pushed ref updates in original order. */
@@ -168,7 +181,7 @@ export const ProjectHooksLocalStateSchema = z
 /** Local activation settings stored independently of tracked project configuration. */
 export type ProjectHooksLocalState = z.infer<typeof ProjectHooksLocalStateSchema>;
 /** Bounded last execution metadata; contains no input or arbitrary output. */
-export interface HookExecutionReceipt {
+export interface HookExecutionReceipt extends Partial<HookNativeSession> {
   /** Receipt format version. */
   schemaVersion: 1;
   /** Activated source digest. */
@@ -186,6 +199,7 @@ export interface HookExecutionReceipt {
 export const HookExecutionReceiptSchema = z
   .object({
     schemaVersion: z.literal(1),
+    ...HookNativeSessionSchema.partial().shape,
     manifestHash: z.string().regex(/^[a-f0-9]{64}$/),
     source: HookSourceSchema,
     event: z.string().max(128),

package/src/release/hook-pilot.ts

@@ -1,5 +1,6 @@
 /** Bound, retained evidence required before promoting project hooks to stable (T13350). */
 import { z } from 'zod';
+import { HookExecutionReceiptSchema, HookNativeSessionSchema } from '../project-hooks.js';
 
 /** Required pilot checks; every named check must pass on the same implementation. */
 export const HOOK_PILOT_CHECKS = [
@@ -42,6 +43,8 @@ export const HookPilotProofReferenceSchema = z
     sha256: HookPilotDigestSchema,
   })
   .strict();
+/** Hash-bound artifact reference reused by native receipts and phase proofs. */
+export type HookPilotProofReference = z.infer<typeof HookPilotProofReferenceSchema>;
 /** Common identity attached to every retained proof, never inferred from similar releases. */
 export const HookPilotIdentitySchema = z
   .object({
@@ -53,7 +56,7 @@ export const HookPilotIdentitySchema = z
   .strict();
 /** A bounded collection of actual pilot receipts. Missing or partial checks hold promotion. */
 export const HookPilotEvidenceSchema = HookPilotIdentitySchema.extend({
-  schemaVersion: z.literal(1),
+  schemaVersion: z.union([z.literal(1), z.literal(2)]),
   vidaRepository: z
     .string()
     .regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/)
@@ -73,9 +76,64 @@ export const HookPilotEvidenceSchema = HookPilotIdentitySchema.extend({
 }).strict();
 /** Validated evidence bundle index. */
 export type HookPilotEvidence = z.infer<typeof HookPilotEvidenceSchema>;
+/** Strict runner receipt binding native agent delivery to its session and provider. */
+export const HookPilotNativeReceiptSchema = HookExecutionReceiptSchema.extend({
+  ...HookNativeSessionSchema.shape,
+  source: z.literal('agent'),
+  event: z.string().min(1).max(128),
+  recordedAt: z.string().datetime(),
+}).strict();
+/** Retained native session evidence; receipt content is read and hash-checked by the release gate. */
+export const HookPilotNativeEvidenceSchema = z
+  .object({
+    sessionId: z.string().min(1).max(256),
+    checkout: z.enum(['standalone', 'linked-worktree']),
+    startedAt: z.string().datetime(),
+    endedAt: z.string().datetime(),
+    receipt: HookPilotProofReferenceSchema.extend(
+      HookPilotNativeReceiptSchema.pick({
+        source: true,
+        event: true,
+        recordedAt: true,
+        sessionId: true,
+        harness: true,
+      }).shape,
+    ).strict(),
+    trust: z.discriminatedUnion('mode', [
+      z
+        .object({
+          mode: z.literal('persisted'),
+          home: z.enum(['isolated', 'user-global']),
+          grantedBy: z.enum(['native-interactive', 'native-command']),
+        })
+        .strict(),
+      z
+        .object({
+          mode: z.literal('bypassed'),
+          home: z.enum(['isolated', 'user-global']),
+          flag: z.literal('--dangerously-bypass-hook-trust'),
+        })
+        .strict(),
+    ]),
+    contextInjection: z.enum(['observed', 'unverified', 'not-observed']),
+    contextEvidence: HookPilotProofReferenceSchema.optional(),
+    infrastructureFaults: z
+      .array(
+        z
+          .object({
+            source: z.enum(['agent', 'git', 'sandbox']),
+            code: z.string().regex(/^[A-Z][A-Z0-9_]{0,127}$/),
+          })
+          .strict(),
+      )
+      .max(100),
+  })
+  .strict();
+/** Typed, redacted native delivery and its known limitations. */
+export type HookPilotNativeEvidence = z.infer<typeof HookPilotNativeEvidenceSchema>;
 /** Structured, redacted proof produced by a real check and retained with its hash. */
 export const HookPilotProofSchema = HookPilotIdentitySchema.extend({
-  schemaVersion: z.literal(1),
+  schemaVersion: z.union([z.literal(1), z.literal(2)]),
   check: z.enum(HOOK_PILOT_CHECKS),
   status: z.literal('pass'),
   observedAt: z.string().datetime(),
@@ -85,15 +143,39 @@ export const HookPilotProofSchema = HookPilotIdentitySchema.extend({
   packageVersions: z.record(z.string().max(256), z.string().max(128)).optional(),
   ordinaryCommands: z.number().int().min(1).max(100000).optional(),
   disposablePushes: z.number().int().min(1).max(100000).optional(),
+  native: HookPilotNativeEvidenceSchema.optional(),
   hostedRunId: z.number().int().positive().safe().optional(),
   url: z.string().url().max(2048).optional(),
-}).strict();
+})
+  .strict()
+  .superRefine((proof, ctx) => {
+    if (
+      proof.schemaVersion === 2 &&
+      (proof.check === 'liveClaude' || proof.check === 'liveCodex') &&
+      !proof.native
+    ) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['native'],
+        message: 'Required native agent receipt missing',
+      });
+    }
+    if (proof.native?.contextInjection === 'observed' && !proof.native.contextEvidence) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['native', 'contextEvidence'],
+        message: 'Observed context requires retained evidence',
+      });
+    }
+  });
 /** A validated retained proof. */
 export type HookPilotProof = z.infer<typeof HookPilotProofSchema>;
 /** Minimal authoritative GitHub response required for an actual successful workflow run. */
 export const HookPilotHostedRunSchema = z.object({
   id: z.number().int().positive(),
   head_sha: z.string().regex(/^[a-f0-9]{40}$/),
+  /** Historical responses may omit the trigger; future proofs require an exact-commit dispatch. */
+  event: z.string().min(1).max(64).optional(),
   status: z.literal('completed'),
   conclusion: z.literal('success'),
   path: z.string().max(4096),

package/src/task.ts

@@ -320,6 +320,14 @@ export type EvidenceAtom =
        * `tool:test-affected`'s `untestedPackages` (T12965 review).
        */
       untestedPackages?: string[];
+      /** Changed CLEO config this result leaves to `tool:config-schema` in the same gate write (T13778). */
+      configPaths?: string[];
+      /**
+       * Dependents of a declared generated package this report left to a
+       * typecheck (T13783): a `tool:typecheck` or a qa-run typecheck receipt
+       * covering them must be in the same gate write.
+       */
+      typecheckDirs?: string[];
       /**
        * Tracked files matching `evidence.runtimePaths` whose working-tree
        * edits the tree hash left out (T13554).
@@ -355,6 +363,8 @@ export type EvidenceAtom =
       uncovered?: string[];
       /** Dependent packages this receipt's roots leave uncovered (T13580). */
       uncoveredPackages?: string[];
+      /** Changed CLEO config this result leaves to `tool:config-schema` in the same gate write (T13778). */
+      configPaths?: string[];
       /** The change it checked is non-code only, so no typecheck is owed (T13745). */
       nonCodeChange?: boolean;
     }
@@ -386,6 +396,17 @@ export type EvidenceAtom =
        * qa-run receipt: a moved tree voids it.
        */
       configSchema?: string[];
+      /**
+       * `tool:config-schema` on a change that also touches other paths (T13778):
+       * those paths, which another result in the same gate write must cover.
+       */
+      otherPaths?: string[];
+      /**
+       * `tool:config-schema` judged an already-merged change (T13781): the
+       * `commit:`/`pr:` merge commit whose config files it validated, in place
+       * of a tree pin.
+       */
+      configSchemaCommit?: string;
       /**
        * `affected`: the run covered only the packages the branch diff touches
        * plus their dependents (D11150, T12635). It satisfies testsPassed before
@@ -411,6 +432,8 @@ export type EvidenceAtom =
       affectedTestFiles?: string[];
       /** Affected DEPENDENT packages with no test project (a changed one refuses the scope). */
       untestedPackages?: string[];
+      /** Changed CLEO config this result leaves to `tool:config-schema` in the same gate write (T13778). */
+      configPaths?: string[];
       /**
        * Test files that failed and then passed on their single retry
        * (T12961). The run counts as a pass; this marks it as a FLAKY pass so