@hasna/hooks 0.13.1 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +30 -15
  2. package/bin/hooks/stop-review.js +53 -17
  3. package/bin/hooks-mcp.js +4787 -1415
  4. package/bin/index.js +5250 -2337
  5. package/bin/native-safety-entry.js +15 -37
  6. package/bin/native-safety-worker.cjs +38 -36
  7. package/bin/serve.js +34 -11
  8. package/dist/index.js +4970 -1579
  9. package/dist/lib/claude-skills-coordination.d.ts +1 -1
  10. package/dist/lib/codex-safety-trust.d.ts +2 -2
  11. package/dist/lib/native-safety-registration.d.ts +2 -2
  12. package/dist/lib/native-safety.d.ts +1 -1
  13. package/dist/lib/registry.d.ts +3 -1
  14. package/dist/native-safety.d.ts +4 -2
  15. package/dist/native-safety.js +21 -2
  16. package/dist/sdk/index.js +9 -53
  17. package/hooks/hook-job-folder-guard/README.md +61 -0
  18. package/hooks/hook-job-folder-guard/package.json +12 -0
  19. package/hooks/hook-job-folder-guard/src/classify.ts +398 -0
  20. package/hooks/hook-job-folder-guard/src/hook.ts +96 -0
  21. package/hooks/hook-protected-delete-guard/README.md +114 -0
  22. package/hooks/hook-protected-delete-guard/package.json +12 -0
  23. package/hooks/hook-protected-delete-guard/src/hook.ts +539 -0
  24. package/hooks/hook-signed-link-guard/src/classify.ts +41 -2
  25. package/hooks/hook-stop-review/README.md +16 -0
  26. package/hooks/hook-stop-review/manifest.json +1 -1
  27. package/hooks/hook-stop-review/package.json +1 -1
  28. package/hooks/hook-stop-review/src/hook.ts +1 -1
  29. package/hooks/hook-stop-review/src/native.ts +44 -8
  30. package/hooks/hook-stop-review/src/policy.ts +20 -8
  31. package/hooks/hook-stop-review/src/runtime.ts +16 -13
  32. package/hooks/hook-stop-review/src/types.ts +12 -2
  33. package/hooks/hook-trash-guard/README.md +130 -13
  34. package/hooks/hook-trash-guard/src/hook.ts +518 -71
  35. package/hooks/local-executors.ts +130 -12
  36. package/hooks/native-safety-composite.ts +19 -8
  37. package/package.json +3 -3
  38. package/scripts/build-native-entry.ts +123 -0
  39. package/scripts/build-native-worker.ts +11 -4
  40. package/scripts/validate-package.ts +8 -2
  41. package/hooks/native-safety-entry.ts +0 -11
@@ -1,7 +1,7 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import { constants, closeSync, fstatSync, openSync, readlinkSync, readSync, statSync } from "node:fs";
3
3
  import { dirname, isAbsolute, join } from "node:path";
4
- import type { StopReviewEnvelope, StopReviewResult } from "./types";
4
+ import type { CodexStopReviewAdmission, StopReviewEnvelope, StopReviewResult } from "./types";
5
5
 
6
6
  export type NativeHarness = "codex" | "claude";
7
7
  type ObjectValue = Record<string, unknown>;
@@ -107,7 +107,34 @@ export function requestsStop(prompt: string): boolean {
107
107
  export type NativeGoal = StopReviewEnvelope["goal"];
108
108
  // Native generation evidence stays off enumerable envelopes/provider requests.
109
109
  const nativeGoalRevision = Symbol("nativeGoalRevision");
110
+ const nativeGoalAccounting = Symbol("nativeGoalAccounting");
111
+ interface NativeGoalAccounting { tokenBudget: number | null; tokensUsed: number; timeUsedSeconds?: number }
110
112
  type VerifiedNativeGoal = NonNullable<NativeGoal> & { [nativeGoalRevision]: string };
113
+ /** Native command-stdin context, never caller request_metadata or transcript content. */
114
+ export interface CodexNativeGoalStopReview {
115
+ goal_id: string;
116
+ turn_id: string;
117
+ revision: number;
118
+ status_source: "active" | "agent_blocked";
119
+ objective: string;
120
+ token_budget: number | null;
121
+ tokens_used: number;
122
+ time_used_seconds: number;
123
+ }
124
+ export function parseCodexNativeGoalStopReview(value: unknown): CodexNativeGoalStopReview | undefined {
125
+ const count = (x: unknown): x is number => Number.isSafeInteger(x) && (x as number) >= 0;
126
+ if (!object(value) || Object.keys(value).sort().join(",") !== "goal_id,objective,revision,status_source,time_used_seconds,token_budget,tokens_used,turn_id" ||
127
+ !id(value.goal_id) || !id(value.turn_id) || !count(value.revision) || !text(value.objective) ||
128
+ !["active", "agent_blocked"].includes(String(value.status_source)) ||
129
+ !(value.token_budget === null || count(value.token_budget)) || !count(value.tokens_used) || !count(value.time_used_seconds)) return undefined;
130
+ return { ...value } as unknown as CodexNativeGoalStopReview;
131
+ }
132
+ function nativeSnapshotMatches(snapshot: CodexNativeGoalStopReview, goal: NativeGoal): boolean {
133
+ if (!goal || goal.objective !== snapshot.objective || goal.status !== (snapshot.status_source === "active" ? "active" : "blocked")) return false;
134
+ const accounting = (goal as NonNullable<NativeGoal> & { [nativeGoalAccounting]?: NativeGoalAccounting })[nativeGoalAccounting];
135
+ return !!accounting && accounting.tokenBudget === snapshot.token_budget && accounting.tokensUsed === snapshot.tokens_used &&
136
+ accounting.timeUsedSeconds === snapshot.time_used_seconds;
137
+ }
111
138
  function goalFreshness(goal: NativeGoal): unknown {
112
139
  if (goal === undefined) return { state: "unreadable" };
113
140
  if (goal === null) return { state: "absent" };
@@ -126,6 +153,7 @@ export interface PreparedNativeStop {
126
153
  ok: true;
127
154
  envelope: StopReviewEnvelope;
128
155
  isCurrent: (envelope: StopReviewEnvelope) => Promise<boolean>;
156
+ nativeAdmission?: CodexStopReviewAdmission;
129
157
  }
130
158
  export async function prepareNativeStop(raw: unknown, options: NativeAdapterOptions): Promise<PreparedNativeStop | { ok: false; reason: string }> {
131
159
  if (!object(raw) || raw.hook_event_name !== "Stop" || !id(raw.session_id) || typeof raw.stop_hook_active !== "boolean" || !text(raw.last_assistant_message) || typeof raw.transcript_path !== "string") return unavailable("invalid_native_input");
@@ -134,6 +162,9 @@ export async function prepareNativeStop(raw: unknown, options: NativeAdapterOpti
134
162
  if (raw[key] !== undefined && (!Array.isArray(raw[key]) || raw[key].length > 0)) return unavailable("native_background_work");
135
163
  }
136
164
  if (options.harness === "codex" && !id(raw.turn_id)) return unavailable("missing_native_turn");
165
+ const hasNativeSnapshot = Object.hasOwn(raw, "native_goal_stop_review");
166
+ const nativeSnapshot = hasNativeSnapshot ? parseCodexNativeGoalStopReview(raw.native_goal_stop_review) : undefined;
167
+ if (hasNativeSnapshot && (options.harness !== "codex" || !nativeSnapshot || nativeSnapshot.turn_id !== raw.turn_id)) return unavailable("invalid_native_goal_snapshot");
137
168
  // Stop is the normal completion callback. Interrupt/StopFailure/SubagentStop are never admitted.
138
169
  const sessionId = raw.session_id, path = raw.transcript_path, assistant = raw.last_assistant_message;
139
170
  const readPrompt = async () => {
@@ -155,12 +186,14 @@ export async function prepareNativeStop(raw: unknown, options: NativeAdapterOpti
155
186
  const snapshot = async () => {
156
187
  const prompt = await readPrompt();
157
188
  const goal = options.harness === "codex" ? await options.readGoal?.(sessionId) : undefined;
158
- return { prompt, goal, revision: digest([prompt.revision, options.harness === "codex" ? goalFreshness(goal) : "optional-goal-unavailable", assistant]) };
189
+ if (nativeSnapshot && !nativeSnapshotMatches(nativeSnapshot, goal)) throw new Error("native_goal_snapshot_changed");
190
+ return { prompt, goal, revision: digest([prompt.revision, options.harness === "codex" ? goalFreshness(goal) : "optional-goal-unavailable", assistant, ...(nativeSnapshot ? [nativeSnapshot] : [])]) };
159
191
  };
160
192
  try {
161
193
  const current = await snapshot();
162
194
  if (current.prompt.interrupted || requestsStop(current.prompt.prompt)) return unavailable("user_stop");
163
- const goal = current.goal;
195
+ const goal = nativeSnapshot?.status_source === "agent_blocked" && current.goal
196
+ ? { ...current.goal, statusSource: "agent_blocked" as const, activationEpoch: nativeSnapshot.revision } : current.goal;
164
197
  const envelope: StopReviewEnvelope = {
165
198
  schema: "hooks.stop-review.v1", sessionId, turnId: current.prompt.turnId,
166
199
  inputRevision: current.revision, capturedAt: new Date((options.now ?? Date.now)()).toISOString(),
@@ -169,9 +202,10 @@ export async function prepareNativeStop(raw: unknown, options: NativeAdapterOpti
169
202
  ...(options.harness === "claude" ? { goalAvailability: "unavailable" as const } : {}),
170
203
  runtime: { stopReason: "end_turn", userRequestedStop: false, terminal: goal?.status === "complete" || goal?.status === "cancelled",
171
204
  paused: goal?.status === "paused", budgetExhausted: goal?.status === "budget_limited", usageLimited: goal?.status === "usage_limited",
172
- awaitingApproval: false, nativeContinuationAllowed: true, stopHookActive: false, continuationCount: 0 },
205
+ awaitingApproval: false, nativeContinuationAllowed: true, stopHookActive: false, continuationCount: 0,
206
+ ...(nativeSnapshot?.status_source === "agent_blocked" ? { agentBlockedAdmission: "parent_final_cas" as const } : {}) },
173
207
  };
174
- return { ok: true, envelope, isCurrent: async (candidate) => {
208
+ return { ok: true, envelope, ...(nativeSnapshot ? { nativeAdmission: { mode: "parent_final_cas" as const, harness: "codex" as const } } : {}), isCurrent: async (candidate) => {
175
209
  if (candidate.sessionId !== sessionId || candidate.turnId !== envelope.turnId || candidate.inputRevision !== envelope.inputRevision) return false;
176
210
  try { const latest = await snapshot(); return (options.harness !== "codex" || latest.goal !== undefined) && latest.revision === envelope.inputRevision && !latest.prompt.interrupted && !requestsStop(latest.prompt.prompt); } catch { return false; }
177
211
  } };
@@ -194,8 +228,10 @@ export function codexGoalFromResponse(value: unknown, sessionId: string): Native
194
228
  const status = statuses[String(goal.status)];
195
229
  if (!status || typeof goal.tokensUsed !== "number" || !Number.isFinite(goal.tokensUsed) || goal.tokensUsed < 0 || !(goal.tokenBudget === null || (Number.isSafeInteger(goal.tokenBudget) && (goal.tokenBudget as number) >= 0))) return undefined;
196
230
  if (!Number.isSafeInteger(goal.createdAt) || (goal.createdAt as number) < 0 || !Number.isSafeInteger(goal.updatedAt) || (goal.updatedAt as number) < (goal.createdAt as number)) return undefined;
231
+ if (goal.timeUsedSeconds !== undefined && (!Number.isSafeInteger(goal.timeUsedSeconds) || (goal.timeUsedSeconds as number) < 0)) return undefined;
197
232
  const projected: NonNullable<NativeGoal> = { id: sessionId, objective: goal.objective, status: goal.tokenBudget !== null && goal.tokensUsed >= (goal.tokenBudget as number) ? "budget_limited" : status };
198
- Object.defineProperty(projected, nativeGoalRevision, { value: digest([goal.createdAt, goal.updatedAt, goal.tokenBudget, goal.tokensUsed]), enumerable: false });
233
+ Object.defineProperty(projected, nativeGoalRevision, { value: digest([goal.createdAt, goal.updatedAt, goal.tokenBudget, goal.tokensUsed, goal.timeUsedSeconds]), enumerable: false });
234
+ Object.defineProperty(projected, nativeGoalAccounting, { value: { tokenBudget: goal.tokenBudget, tokensUsed: goal.tokensUsed, timeUsedSeconds: goal.timeUsedSeconds }, enumerable: false });
199
235
  return projected;
200
236
  }
201
237
 
@@ -260,12 +296,12 @@ export async function readCodexGoal(sessionId: string, options: { codexHome: str
260
296
  export async function runNativeStop(
261
297
  raw: unknown,
262
298
  options: NativeAdapterOptions,
263
- review: (envelope: StopReviewEnvelope, isCurrent: PreparedNativeStop["isCurrent"]) => Promise<StopReviewResult>,
299
+ review: (envelope: StopReviewEnvelope, isCurrent: PreparedNativeStop["isCurrent"], nativeAdmission?: CodexStopReviewAdmission) => Promise<StopReviewResult>,
264
300
  ): Promise<{ output: Record<string, string>; reason: string }> {
265
301
  const prepared = await prepareNativeStop(raw, options);
266
302
  if (!prepared.ok) return { output: {}, reason: prepared.reason };
267
303
  try {
268
- const result = await review(prepared.envelope, prepared.isCurrent);
304
+ const result = await review(prepared.envelope, prepared.isCurrent, prepared.nativeAdmission);
269
305
  const output = await nativeStopOutput(result, prepared);
270
306
  return { output, reason: result.action === "continue" && !output.decision ? "stale_input" : result.reason };
271
307
  } catch { return { output: {}, reason: "native_review_unavailable" }; }
@@ -1,6 +1,6 @@
1
1
  import { evaluateJev, parseJevAssessment } from "./jev";
2
2
  import { STOP_CLASSES } from "./types";
3
- import type { ParentStopReviewAdmission, StopRecommendationOptions, StopReviewEnvelope, StopReviewInstruction, StopReviewOptions, StopReviewReason, StopReviewResult } from "./types";
3
+ import type { StopReviewAdmission, StopRecommendationOptions, StopReviewEnvelope, StopReviewInstruction, StopReviewOptions, StopReviewReason, StopReviewResult } from "./types";
4
4
 
5
5
  const record = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
6
6
  const identifier = (value: unknown): value is string => typeof value === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,255}$/.test(value);
@@ -11,7 +11,7 @@ const stopReasons = ["end_turn", "user_stop", "cancelled", "error", "approval_wa
11
11
  const MIN_CERTAINTY = 0.9;
12
12
  const MAX_NEGATIVE = 0.1;
13
13
 
14
- function hasTruthfulSumiAgentPause(envelope: StopReviewEnvelope, admission?: ParentStopReviewAdmission): boolean {
14
+ function hasTruthfulSumiAgentPause(envelope: StopReviewEnvelope, admission?: StopReviewAdmission): boolean {
15
15
  const goal = envelope.goal;
16
16
  return admission?.mode === "parent_final_cas" && admission.harness === "sumi" && goal?.status === "paused" &&
17
17
  goal.statusSource === "agent" && goal.pauseReason === "agent" && Number.isSafeInteger(goal.activationEpoch) &&
@@ -19,6 +19,13 @@ function hasTruthfulSumiAgentPause(envelope: StopReviewEnvelope, admission?: Par
19
19
  envelope.runtime.agentPauseAdmission === "parent_final_cas";
20
20
  }
21
21
 
22
+ function hasNativeCodexAgentBlock(envelope: StopReviewEnvelope, admission?: StopReviewAdmission): boolean {
23
+ return admission?.mode === "parent_final_cas" && admission.harness === "codex" &&
24
+ envelope.goal?.status === "blocked" && envelope.goal.statusSource === "agent_blocked" &&
25
+ Number.isSafeInteger(envelope.goal.activationEpoch) && (envelope.goal.activationEpoch as number) >= 0 &&
26
+ envelope.runtime.agentBlockedAdmission === "parent_final_cas";
27
+ }
28
+
22
29
  export function isStopReviewEnvelope(value: unknown): value is StopReviewEnvelope {
23
30
  if (!record(value) || value.schema !== "hooks.stop-review.v1" || !identifier(value.sessionId) ||
24
31
  !identifier(value.turnId) || !identifier(value.inputRevision) || typeof value.capturedAt !== "string" ||
@@ -29,6 +36,8 @@ export function isStopReviewEnvelope(value: unknown): value is StopReviewEnvelop
29
36
  !stopReasons.includes(runtime.stopReason as string) || !Number.isSafeInteger(runtime.continuationCount) ||
30
37
  (runtime.continuationCount as number) < 0) return false;
31
38
  if (runtime.agentPauseAdmission !== undefined && runtime.agentPauseAdmission !== "parent_final_cas") return false;
39
+ if (runtime.agentBlockedAdmission !== undefined && runtime.agentBlockedAdmission !== "parent_final_cas") return false;
40
+ if (runtime.agentPauseAdmission !== undefined && runtime.agentBlockedAdmission !== undefined) return false;
32
41
  if (value.goal !== undefined && value.goal !== null && (!record(value.goal) || !identifier(value.goal.id) ||
33
42
  !text(value.goal.objective) || !goalStatuses.includes(value.goal.status as string))) return false;
34
43
  if (record(value.goal)) {
@@ -36,8 +45,11 @@ export function isStopReviewEnvelope(value: unknown): value is StopReviewEnvelop
36
45
  const hasPauseFact = pauseFacts.some((fact) => fact !== undefined);
37
46
  const exactPauseFacts = value.goal.status === "paused" && value.goal.statusSource === "agent" && value.goal.pauseReason === "agent" &&
38
47
  Number.isSafeInteger(value.goal.activationEpoch) && (value.goal.activationEpoch as number) >= 0;
39
- if (hasPauseFact !== (runtime.agentPauseAdmission !== undefined) || (hasPauseFact && !exactPauseFacts)) return false;
40
- } else if (runtime.agentPauseAdmission !== undefined) return false;
48
+ const exactBlockedFacts = value.goal.status === "blocked" && value.goal.statusSource === "agent_blocked" && value.goal.pauseReason === undefined &&
49
+ Number.isSafeInteger(value.goal.activationEpoch) && (value.goal.activationEpoch as number) >= 0;
50
+ if (runtime.agentBlockedAdmission !== undefined) { if (!exactBlockedFacts) return false; }
51
+ else if (hasPauseFact !== (runtime.agentPauseAdmission !== undefined) || (hasPauseFact && !exactPauseFacts)) return false;
52
+ } else if (runtime.agentPauseAdmission !== undefined || runtime.agentBlockedAdmission !== undefined) return false;
41
53
  if (value.goalAvailability !== undefined && !["known", "unavailable"].includes(value.goalAvailability as string)) return false;
42
54
  return true;
43
55
  }
@@ -58,7 +70,7 @@ export function isStopReviewInstruction(value: unknown): value is StopReviewInst
58
70
  }
59
71
 
60
72
  export function stopPolicyGate(envelope: StopReviewEnvelope, now: number, maxContinuations = 1,
61
- options: { assessmentOnlyAtCap?: boolean; admission?: ParentStopReviewAdmission } = {}): StopReviewReason | null {
73
+ options: { assessmentOnlyAtCap?: boolean; admission?: StopReviewAdmission } = {}): StopReviewReason | null {
62
74
  const runtime = envelope.runtime;
63
75
  const agentPause = hasTruthfulSumiAgentPause(envelope, options.admission);
64
76
  if (runtime.userRequestedStop || ["user_stop", "cancelled"].includes(runtime.stopReason)) return "user_stop";
@@ -70,7 +82,7 @@ export function stopPolicyGate(envelope: StopReviewEnvelope, now: number, maxCon
70
82
  if (!runtime.nativeContinuationAllowed) return "native_continuation_unavailable";
71
83
  if (runtime.stopReason === "error") return "runtime_failure";
72
84
  if (runtime.stopReason !== "end_turn" || (envelope.goal === undefined && envelope.goalAvailability !== "unavailable") || envelope.goal?.status === "unknown") return "unknown_runtime";
73
- if (envelope.goal && envelope.goal.status !== "active" && !agentPause) return "goal_not_active";
85
+ if (envelope.goal && envelope.goal.status !== "active" && !agentPause && !hasNativeCodexAgentBlock(envelope, options.admission)) return "goal_not_active";
74
86
  if (runtime.stopHookActive || runtime.continuationCount > maxContinuations ||
75
87
  (runtime.continuationCount === maxContinuations && !options.assessmentOnlyAtCap)) return "recursion_guard";
76
88
  const age = now - Date.parse(envelope.capturedAt);
@@ -80,7 +92,7 @@ export function stopPolicyGate(envelope: StopReviewEnvelope, now: number, maxCon
80
92
 
81
93
  /** The only authority is the native runtime; this function never delivers a prompt or resumes a goal. */
82
94
  export async function reviewStop(input: unknown, options: StopReviewOptions): Promise<StopReviewResult> {
83
- return assessStop(input, options, options.isCurrent);
95
+ return assessStop(input, options, options.isCurrent, options.nativeAdmission);
84
96
  }
85
97
 
86
98
  /** The parent owns all live-state reads and final atomic admission; the child only recommends. */
@@ -105,7 +117,7 @@ export function settlementFor(result: StopReviewResult): "complete" | "blocked"
105
117
  }
106
118
 
107
119
  async function assessStop(input: unknown, options: StopReviewOptions | StopRecommendationOptions,
108
- isCurrent?: StopReviewOptions["isCurrent"], admission?: ParentStopReviewAdmission): Promise<StopReviewResult> {
120
+ isCurrent?: StopReviewOptions["isCurrent"], admission?: StopReviewAdmission): Promise<StopReviewResult> {
109
121
  const empty = (reason: StopReviewReason): StopReviewResult => ({ schema: "hooks.stop-review-result.v1", action: "allow_stop", reason });
110
122
  if (!isStopReviewEnvelope(input)) return empty("invalid_input");
111
123
  const envelope = structuredClone(input);
@@ -7,7 +7,7 @@ import { restoreStopReviewClientContext, stopReviewClientContextRefused } from "
7
7
  import { nativeChildEnv } from "../../../src/lib/native-child-env";
8
8
  import { buildJevRequest, evaluateJev, parseJevAssessment } from "./jev";
9
9
  import { isStopReviewEnvelope, isStopReviewInstruction, recommendStop, reviewStop, stopPolicyGate } from "./policy";
10
- import type { JevResult, ParentStopReviewAdmission, StopReviewEnvelope, StopReviewInstruction, StopReviewNativeTarget, StopReviewResult } from "./types";
10
+ import type { CodexStopReviewAdmission, JevResult, ParentStopReviewAdmission, StopReviewAdmission, StopReviewEnvelope, StopReviewInstruction, StopReviewNativeTarget, StopReviewResult } from "./types";
11
11
 
12
12
  export interface StopReviewRuntimeConfiguration {
13
13
  schema: "hooks.stop-review-runtime.v1";
@@ -176,7 +176,7 @@ export async function scanStopReviewContent(envelope: StopReviewEnvelope, instru
176
176
 
177
177
  /** Append-only metadata. No prompt, goal objective, transcript or credential is persisted here. */
178
178
  export function claimStopReviewTurn(envelope: StopReviewEnvelope, env: NodeJS.ProcessEnv = process.env,
179
- requestHash?: string, instructionDigest?: string, admission?: ParentStopReviewAdmission,
179
+ requestHash?: string, instructionDigest?: string, admission?: StopReviewAdmission,
180
180
  nativeTarget?: StopReviewNativeTarget): "claimed" | "already_claimed" | "unavailable" {
181
181
  let fd: number | undefined;
182
182
  try {
@@ -201,7 +201,7 @@ export function claimStopReviewTurn(envelope: StopReviewEnvelope, env: NodeJS.Pr
201
201
  }
202
202
 
203
203
  function providerClaimMatches(envelope: StopReviewEnvelope, requestHash: string, instructionDigest: string, env: NodeJS.ProcessEnv,
204
- admission: ParentStopReviewAdmission | undefined, nativeTarget: StopReviewNativeTarget): boolean {
204
+ admission: StopReviewAdmission | undefined, nativeTarget: StopReviewNativeTarget): boolean {
205
205
  const path = join(getEffectiveDataRoot(env), "state", "stop-review", "turn-claims", `${sha256(`${envelope.sessionId}\0${envelope.turnId}`)}.json`);
206
206
  const claim = readPrivateConfiguration(path);
207
207
  return record(claim) && claim.schema === "hooks.stop-review-claim.v1" && claim.sessionHash === sha256(envelope.sessionId) &&
@@ -221,9 +221,9 @@ export async function runJevProviderChild(raw: unknown, env: NodeJS.ProcessEnv =
221
221
  (config.harness !== undefined && config.harness !== raw.nativeTarget)) return { ok: false, reason: "invalid_configuration" };
222
222
  const nativeTarget = raw.nativeTarget as StopReviewNativeTarget;
223
223
  if (raw.admission !== undefined && (!record(raw.admission) || raw.admission.mode !== "parent_final_cas" ||
224
- !["sumi", "opencode"].includes(raw.admission.harness as string) || Object.keys(raw.admission).sort().join(",") !== "harness,mode" ||
224
+ !["sumi", "opencode", "codex"].includes(raw.admission.harness as string) || Object.keys(raw.admission).sort().join(",") !== "harness,mode" ||
225
225
  nativeTarget !== raw.admission.harness)) return { ok: false, reason: "invalid_configuration" };
226
- const admission = raw.admission as ParentStopReviewAdmission | undefined;
226
+ const admission = raw.admission as StopReviewAdmission | undefined;
227
227
  const gate = stopPolicyGate(raw.envelope, Date.now(), 1, { assessmentOnlyAtCap: !!admission, admission });
228
228
  if (gate) return { ok: false, reason: gate };
229
229
  const instruction = instructionFromContent(raw.instructionContent, config);
@@ -235,7 +235,7 @@ export async function runJevProviderChild(raw: unknown, env: NodeJS.ProcessEnv =
235
235
 
236
236
  export async function evaluateThroughSecrets(envelope: StopReviewEnvelope, instruction: PinnedStopReviewInstruction,
237
237
  config: StopReviewRuntimeConfiguration, env: NodeJS.ProcessEnv, entrypoint: string,
238
- run: RuntimeCommandRunner = runRuntimeCommand, admission?: ParentStopReviewAdmission,
238
+ run: RuntimeCommandRunner = runRuntimeCommand, admission?: StopReviewAdmission,
239
239
  nativeTarget?: StopReviewNativeTarget): Promise<JevResult> {
240
240
  if (stopReviewClientContextRefused(env)) return { ok: false, reason: "invalid_configuration" };
241
241
  if (!safePath(entrypoint)) return { ok: false, reason: "invalid_configuration" };
@@ -271,8 +271,9 @@ export async function evaluateThroughSecrets(envelope: StopReviewEnvelope, instr
271
271
 
272
272
  export async function reviewNativeEnvelope(envelope: StopReviewEnvelope,
273
273
  isCurrent: (expected: StopReviewEnvelope) => boolean | Promise<boolean>,
274
- env: NodeJS.ProcessEnv = process.env, entrypoint = process.argv[1], nativeTarget?: "codex" | "claude"): Promise<StopReviewResult> {
275
- return reviewRuntimeEnvelope(envelope, env, entrypoint, nativeTarget, isCurrent);
274
+ env: NodeJS.ProcessEnv = process.env, entrypoint = process.argv[1], nativeTarget?: "codex" | "claude",
275
+ nativeAdmission?: CodexStopReviewAdmission): Promise<StopReviewResult> {
276
+ return reviewRuntimeEnvelope(envelope, env, entrypoint, nativeTarget, isCurrent, nativeAdmission);
276
277
  }
277
278
 
278
279
  /** The native parent checks freshness inside its durable continuation-admission transaction. */
@@ -283,13 +284,15 @@ export async function reviewParentGuardedEnvelope(raw: unknown, env: NodeJS.Proc
283
284
  }
284
285
 
285
286
  async function reviewRuntimeEnvelope(raw: unknown, env: NodeJS.ProcessEnv, entrypoint: string | undefined,
286
- nativeTarget: StopReviewNativeTarget | undefined, isCurrent?: (expected: StopReviewEnvelope) => boolean | Promise<boolean>): Promise<StopReviewResult> {
287
+ nativeTarget: StopReviewNativeTarget | undefined, isCurrent?: (expected: StopReviewEnvelope) => boolean | Promise<boolean>,
288
+ nativeAdmission?: CodexStopReviewAdmission): Promise<StopReviewResult> {
287
289
  if (!isStopReviewEnvelope(raw)) return { schema: "hooks.stop-review-result.v1", action: "unavailable", reason: "invalid_input" };
288
290
  const envelope = structuredClone(raw);
289
291
  const base = { schema: "hooks.stop-review-result.v1" as const, sessionId: envelope.sessionId, turnId: envelope.turnId, inputRevision: envelope.inputRevision };
290
292
  const unavailable = (reason: StopReviewResult["reason"]): StopReviewResult => ({ ...base, action: "unavailable", reason });
291
- const admission: ParentStopReviewAdmission | undefined = isCurrent || !nativeTarget || !["sumi", "opencode"].includes(nativeTarget)
292
- ? undefined : { mode: "parent_final_cas", harness: nativeTarget as ParentStopReviewAdmission["harness"] };
293
+ if (nativeAdmission && (!isCurrent || nativeTarget !== "codex" || nativeAdmission.mode !== "parent_final_cas" || nativeAdmission.harness !== "codex")) return unavailable("invalid_configuration");
294
+ const admission: StopReviewAdmission | undefined = nativeAdmission ?? (isCurrent || !nativeTarget || !["sumi", "opencode"].includes(nativeTarget)
295
+ ? undefined : { mode: "parent_final_cas", harness: nativeTarget as ParentStopReviewAdmission["harness"] });
293
296
  const gate = stopPolicyGate(envelope, Date.now(), 1, { assessmentOnlyAtCap: !isCurrent, admission });
294
297
  if (gate) return { ...base, action: "allow_stop", reason: gate };
295
298
  const config = loadNativeRuntimeConfiguration(env);
@@ -305,6 +308,6 @@ async function reviewRuntimeEnvelope(raw: unknown, env: NodeJS.ProcessEnv, entry
305
308
  if (claimed !== "claimed") return unavailable(claimed === "already_claimed" ? "turn_already_reviewed" : "claim_unavailable");
306
309
  const options = { model: config.model, instruction, externalContentApproved: true, timeoutMs: 8000,
307
310
  evaluate: () => evaluateThroughSecrets(envelope, instruction, config, env, entrypoint, runRuntimeCommand, admission, nativeTarget) };
308
- return isCurrent ? reviewStop(envelope, { ...options, isCurrent })
309
- : recommendStop(envelope, { ...options, admission: admission! });
311
+ return isCurrent ? reviewStop(envelope, { ...options, isCurrent, nativeAdmission })
312
+ : recommendStop(envelope, { ...options, admission: admission as ParentStopReviewAdmission });
310
313
  }
@@ -12,8 +12,8 @@ export interface StopReviewEnvelope {
12
12
  id: string;
13
13
  objective: string;
14
14
  status: "active" | "complete" | "paused" | "cancelled" | "blocked" | "budget_limited" | "usage_limited" | "unknown";
15
- /** Native Sumi facts for its narrowly admitted own-agent pause. */
16
- statusSource?: "agent";
15
+ /** Native Sumi pause or Codex agent-block provenance, never model text. */
16
+ statusSource?: "agent" | "agent_blocked";
17
17
  pauseReason?: "agent";
18
18
  activationEpoch?: number;
19
19
  } | null;
@@ -32,6 +32,8 @@ export interface StopReviewEnvelope {
32
32
  continuationCount: number;
33
33
  /** Advertised only for Sumi's native same-goal final-CAS pause admission. */
34
34
  agentPauseAdmission?: "parent_final_cas";
35
+ /** Codex's typed native snapshot, independently matched to the live goal. */
36
+ agentBlockedAdmission?: "parent_final_cas";
35
37
  };
36
38
  }
37
39
 
@@ -105,6 +107,8 @@ export interface JevOptions {
105
107
  }
106
108
 
107
109
  export interface StopReviewOptions extends JevOptions {
110
+ /** Adapter-verified context only. Codex retains the final goal/input CAS. */
111
+ nativeAdmission?: CodexStopReviewAdmission;
108
112
  /** Set only after the owning consumer's disclosure/credential-content checks. */
109
113
  externalContentApproved: boolean;
110
114
  /** Required before and after evaluation; final native delivery must also compare this revision. */
@@ -120,6 +124,12 @@ export interface ParentStopReviewAdmission {
120
124
  harness: "sumi" | "opencode";
121
125
  }
122
126
 
127
+ export interface CodexStopReviewAdmission {
128
+ mode: "parent_final_cas";
129
+ harness: "codex";
130
+ }
131
+ export type StopReviewAdmission = ParentStopReviewAdmission | CodexStopReviewAdmission;
132
+
123
133
  export type StopReviewNativeTarget = "codex" | "claude" | "sumi" | "opencode";
124
134
 
125
135
  export type StopRecommendationOptions = Omit<StopReviewOptions, "isCurrent"> & {
@@ -52,9 +52,23 @@ counts, and the rewrite replaces only the verb, behind its wrappers.
52
52
  ## What it refuses
53
53
 
54
54
  - `rmdir`, `unlink`, `shred` — their flags and semantics are not `rm`'s.
55
- - `git rm` (without `--cached`), `git clean` — they delete outside `rm`.
55
+ - `git rm` (without `--cached`), `git clean` — they delete outside `rm`. The
56
+ subcommand is also read with `$'…'` and `$"…"` decoded, after a redirection
57
+ (`git >/dev/null clean`), and, for an expansion, as every name it may stand
58
+ for (`${C:-clean}`, `$(echo clean)`, `C=clean; git $C`) (HO-00225).
56
59
  - `find -delete`, `find -exec|-execdir|-ok|-okdir rm …`, `xargs rm` (also
57
- `/bin/rm`) — the delete does not run through a verb this hook can swap.
60
+ `/bin/rm`) — the delete does not run through a verb this hook can swap. A
61
+ command `find -exec` or `xargs` runs is read as a command, so `xargs git
62
+ clean`, `find . -exec git clean -fdx \;` and `xargs sh -c '… rm …'` are
63
+ refused too (HO-00225).
64
+ - A command name in capitals (`RM`, `GIT`, `COMMAND rm`), which a
65
+ case-insensitive filesystem (the macOS default) runs as the lower-case
66
+ command: the command is read again with such names in lower case, and a
67
+ delete or refusal found only that way is refused. Options keep their case
68
+ (`awk -F`, `git -C`) (HO-00225).
69
+ - A command or git subcommand from a variable the same command assigns
70
+ (`C=rm; $C -rf build`). A variable the command does not assign is not known
71
+ here, so `$RM -rf build` alone is not refused.
58
72
  - A delete inside a command substitution, wherever bash runs one: `$( )` and
59
73
  backticks, unquoted or inside double quotes, nested (`"$(echo "$(rm …)")"`,
60
74
  escaped backticks inside backticks), and in a here-document body whose
@@ -74,13 +88,47 @@ counts, and the rewrite replaces only the verb, behind its wrappers.
74
88
  - A brace operand (`rm -rf ~/{.ssh,x}`) is expanded and each path checked: one
75
89
  in the protected class, or one under a protected repo-checkout root that the
76
90
  written word does not show, is refused.
77
- - An unparseable command (unterminated quote or substitution, or an extended
78
- glob such as `@(a|b)`) that mentions a delete verb. A here-document is read
79
- as bash reads it: the rest of its operator's line is still the command
91
+ - A command this hook cannot follow to its end, when it names a delete verb,
92
+ `find -delete` or `git clean` (read with `$'…'` and `$"…"` decoded and in any
93
+ case, HO-00226), or its scan finds a delete (HO-00208). The causes: an unterminated quote or
94
+ substitution, an extended glob such as `@(a|b)`, a `case` word inside a
95
+ substitution, or a `$'…'` spelling that shows a delete the plain reading
96
+ missed. A here-document is read as bash reads it: the rest of its operator's line is still the command
80
97
  (`cat <<EOF && rm x`), `<<-` strips tabs, and a body with no terminator runs
81
98
  to the end of the command.
82
99
  - The protected class, below.
83
100
 
101
+ A `#` comment is read as bash reads it too (HO-00210). A `#` that starts a
102
+ word, outside quotes, `${ … }` and `(( … ))`, comments out the rest of its line,
103
+ and a quote, `<<` or backtick in the comment opens nothing. Every command with
104
+ a comment is read twice: as it always was, and with its comments blanked to
105
+ spaces, so each character keeps its place for the rewrite. Every delete,
106
+ handoff and refusal either reading finds counts, and the command is rewritten
107
+ only when both readings can follow it to its end. Before, an apostrophe in a
108
+ comment (`# let's clean`, newline, `rm -rf build`, newline, `# that's it`) hid
109
+ the delete on the next line, and it ran raw. One unmatched quote in a comment
110
+ still makes the command unreadable to the first reading, so such a delete is
111
+ refused, not rewritten. The blanked reading follows `cd DIR # note` to `DIR`,
112
+ and what it finds there counts beside the old reading's. Because the second
113
+ reading can make a command untrusted that the first trusted, an untrusted
114
+ command whose scan found a delete is refused (HO-00208). Not read yet, and
115
+ unchanged from before (HO-00218): a `#` right after a process substitution's
116
+ `)`, which bash keeps as part of the word, and a line continuation before `#`.
117
+
118
+ An ANSI-C word with an escaped quote (`$'it\'s'`) is read a third way too
119
+ (HO-00213): with each `\'` in it spelled `\x27`, which bash decodes to the same
120
+ quote. The lexer ends such a word at the escaped quote, so the lines after it
121
+ could read as one quoted string and a delete on them was missed. If the third
122
+ reading finds a delete, handoff or refusal, the command is refused, never
123
+ rewritten, because that spelling moves the offsets a rewrite needs. Such words
124
+ are found in one pass from the left and, beside that, from every `$'`
125
+ (HO-00222). A `$'` that bash does not read as ANSI-C (inside quotes, in a
126
+ comment or a here-document body) started a word in the first pass that ran to
127
+ the real word's opening quote and hid it. Either pass can respell a `\'` that
128
+ bash keeps outside such a word, which only ever adds a refusal. One known case
129
+ since HO-00213: a delete after `x="$'it\'s'"`, where `$'` inside double quotes
130
+ is not ANSI-C, is refused rather than rewritten into Trash.
131
+
84
132
  Each refusal carries a reason and a way forward: re-run the delete as
85
133
  `rm -- <path>`, which this hook intercepts and redirects.
86
134
 
@@ -112,14 +160,83 @@ answer. Everything else this hook owns is rewritten, not refused.
112
160
 
113
161
  Deletes under the protected repo-checkout roots `$HOME/.hasna/repos/clones` and
114
162
  `$HOME/workspace/repos` belong to **`workspace-repos-guard`**, which blocks
115
- every delete under them at any depth. This hook does not restate that policy:
116
- it recognizes the boundary and abstains, so the other hook's decision stands.
117
- A command that mixes a delete inside those roots with one outside is refused,
118
- because a partial rewrite would leave one of them unredirected. A delete run
119
- from inside a checkout that names only literal paths outside the roots is
120
- refused too: `workspace-repos-guard` does not own those paths, so abstaining
121
- would let the raw delete run where the two hooks are registered on their own.
122
- The native safety entry already refused it.
163
+ every delete under them at any depth. This hook refuses such a delete too,
164
+ with the same text the native safety entry gives (HO-00185 review 4): where the
165
+ two hooks are registered on their own, abstaining let a delete run raw whenever
166
+ `workspace-repos-guard` placed the shell differently (a `)` inside an array
167
+ assignment, an escaped paren, a case pattern or a function body). A delete run
168
+ from inside a checkout is refused the same way, whatever paths it names. A
169
+ command that mixes a delete inside those roots with one outside is refused,
170
+ because a partial rewrite would leave one of them unredirected.
171
+
172
+ Whether a delete runs inside a checkout follows the `cd`s before it, read
173
+ with bash's grammar (HO-00185) when it is written plainly, the way
174
+ `workspace-repos-guard` reads it: the verb `cd` as is, options bash accepts on
175
+ Linux (`-L`, `-P`, `-e`) and `--` written bare before the directory, no
176
+ redirection before the directory, and a bare `cd` goes home. Any other
177
+ spelling of the operands (a quoted or escaped option, `cd > /dev/null DIR`)
178
+ keeps the old reading, the word after `cd`. A quoted or escaped verb (`"cd"`,
179
+ `\cd`) is the `cd` builtin to bash and is followed with the same grammar;
180
+ `workspace-repos-guard` does not read it, so a delete it leads into a checkout is
181
+ refused here instead of being handed over, and one it leads out of a checkout is
182
+ rewritten into Trash where `workspace-repos-guard` still refuses it. A destination the
183
+ hook cannot follow (`cd "$X"`, `cd -`, a relative name while the command sets CDPATH, an
184
+ option bash rejects such as `-@`) keeps the session's directory: such a `cd`
185
+ may fail, and a delete after `;` then runs where the session is. `pushd` and
186
+ `popd` are not read, because `workspace-repos-guard` does not read them: a
187
+ delete after `pushd <checkout>` is rewritten, and one after `pushd /tmp` from
188
+ inside a checkout is refused. An inherited
189
+ CDPATH in the environment is not read.
190
+
191
+ A `cd` moves the directory for the commands after it only where bash runs it
192
+ in the current shell and `workspace-repos-guard` reads it as plain: the first
193
+ word of its command, or the first after `{`. A `cd` in a pipeline stage or
194
+ the background runs in a child shell and moves nothing; one after a keyword
195
+ (`if`, `do`, `then`, `!`) or an assignment (`HOME=/tmp cd`) keeps the old
196
+ reading; one inside `( … )` moves the directory for the rest of the command,
197
+ as before, because this hook's `)` is not always bash's (a case pattern,
198
+ `${x:-)}`): a delete after a subshell that entered a checkout is refused.
199
+ The two readings can disagree. Bash may not run a `cd` this reading follows
200
+ (one after `||`, a case pattern `cd)`, one inside `${ … }`, a failing
201
+ `cd -P /missing`), and this reading does not follow a `cd` that has more than
202
+ one operand to it, though bash runs it: a trailing comment or an empty
203
+ expansion (`cd DIR # note`, `cd DIR $EMPTY`, `cd DIR "$@"`) keeps the session's
204
+ directory. So the old reading (the word after every `cd`) is kept beside it,
205
+ and every check that depends on the directory also runs at the old reading's
206
+ directory: the command word, an unreadable command word or wrapper, a second
207
+ reading of the command word, a protected-class delete and the command
208
+ substitutions. A refusal found there is kept, so a local executor in a checkout
209
+ and a protected-class delete are refused there as on main. After a `cd` this
210
+ reading does not follow (one it cannot read, or one it reads as a pipeline stage
211
+ or in the background, which is also how it reads `cd DIR ${x:+|}`) while the old
212
+ reading follows it somewhere else, the old reading's checkout handoff is kept as
213
+ well, so the native-safety composite, which takes its handoff from this hook,
214
+ refuses such a delete as main's did. It is not kept after a `cd` this reading
215
+ follows (`cd -- /tmp` from a checkout); the old reading never adds a delete or a
216
+ rewrite. A delete after `cd DIR # note`, `cd DIR $EMPTY` or `cd DIR "$@"` is
217
+ therefore refused where bash leaves the directory and this hook keeps it: from
218
+ inside a checkout, the org folder or the clones root any such delete (main
219
+ redirected it to Trash; the pairs stop it on both), from a directory under
220
+ `~/.hasna`, `~/.ssh` or `~/.aws` (worktrees and project folders included,
221
+ Scratchpad content excepted) a relative one, read as a protected-class delete,
222
+ and from home or `/` a relative delete of a protected name such as `.ssh` (main
223
+ and its pairs redirected these to Trash; this hook, its pairs and the composite
224
+ refuse them). A delete after a `cd` into a checkout in a pipeline stage or the
225
+ background, which bash runs in a child shell, is refused too, as main's
226
+ composite refused it; and once the handoff is kept, a later `cd` main misreads
227
+ keeps main's place (from /tmp, `cd <checkout> # c`, then
228
+ `cd -- /tmp/out && rm -rf foo` is refused, as main's composite refused it). With
229
+ Trash installed, the composite redirects into Trash a delete after a `cd` this
230
+ reading follows that bash does not run or that fails, where the delete runs from
231
+ where the shell already was, as main's does for the plain spellings: an optioned
232
+ `cd` that fails (`cd -P /missing; rm -rf ../apps/foo` from the clones root), one
233
+ after `||` or a false `&&`, a bare `cd` that does not run
234
+ (`true || cd; rm -rf clones` from `~/.hasna/repos`) and an optioned `cd` inside
235
+ `( … )`. The word `case` or `esac` anywhere inside `$( … )` or backticks (a
236
+ case statement, but also `$(grep -c esac f)` or a commit-message here-document
237
+ that mentions a case) makes the command one that is never rewritten, refused
238
+ when it names a delete verb or the scan finds a delete in it. `|&`
239
+ is a pipe, so a `cd` after it moves nothing.
123
240
 
124
241
  ## Conflict discipline
125
242