@haposoft/cafekit 0.16.0-rc.3 → 0.16.0-rc.5

package/src/codex/hooks/completion-authority-check.cjs

@@ -1,260 +1,63 @@
 'use strict';
 
-const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const STATE = require('./completion-authority-state.cjs');
-const { checkReceipt, evidenceBody } = require('./lib/spec-receipt.cjs');
-const { findAllSpecCandidates, resolveActiveSpec } = require('./lib/spec-utils.cjs');
+const { checkFeatureReceipt, checkReceiptDetails } = require('./lib/spec-receipt.cjs');
+const RESOLVER = require('./lib/spec-utils.cjs');
 
-function plain(value) {
-  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
-}
-
-function inside(root, target) {
-  const relative = path.relative(path.resolve(root), path.resolve(target));
-  return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
-}
+const installedScripts = path.join(__dirname, '..', 'scripts');
+const scripts = fs.existsSync(path.join(installedScripts, 'spec-final-state.cjs'))
+  ? installedScripts
+  : path.resolve(__dirname, '..', '..', 'claude', 'scripts');
 
-function readBoundFile(root, target) {
-  const requested = path.isAbsolute(target) ? target : path.resolve(root, target);
-  if (!inside(root, requested)) return null;
-  try {
-    const canonicalRoot = fs.realpathSync(root);
-    const canonical = fs.realpathSync(requested);
-    if (!inside(canonicalRoot, canonical) || !fs.statSync(canonical).isFile()) return null;
-    return fs.readFileSync(canonical);
-  } catch { return null; }
+function runtimeModule(root, name) {
+  const target = path.join(root, name);
+  const stat = fs.lstatSync(target);
+  if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`runtime dependency must be a regular non-symlink file: ${name}`);
+  const canonicalRoot = fs.realpathSync(root);
+  const canonical = fs.realpathSync(target);
+  const relative = path.relative(canonicalRoot, canonical);
+  if (relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error(`runtime dependency escaped scripts root: ${name}`);
+  return require(canonical);
 }
 
-function readTask(featureDir, taskPath) {
-  const target = path.resolve(featureDir, taskPath);
-  if (!inside(featureDir, target)) return null;
-  const bytes = readBoundFile(featureDir, target);
-  if (!bytes) return null;
-  return { bytes, text: bytes.toString('utf8'), path: fs.realpathSync(target) };
-}
+const FINAL_STATE = runtimeModule(scripts, 'spec-final-state.cjs');
 
-function artifactReferences(body) {
-  if (typeof body !== 'string') return [];
-  const references = [];
-  for (const line of body.split('\n')) {
-    if (!/^\s*Artifacts?\s*:/i.test(line) && !/^\s*Artifact\s+produced\b/i.test(line)) continue;
-    const hashes = [...line.matchAll(/\b(?:artifact[_-])?sha-?256\s*:\s*([^\s),;`]+)/gi)].map((match) => match[1]);
-    const raw = line.replace(/^\s*Artifacts?\s*:\s*/i, '').replace(/^\s*Artifact\s+produced\s*:?[ \t]*/i, '').replace(/\b(?:artifact[_-])?sha-?256\s*:\s*[^\s),;`]+/gi, '').replace(/[()[\]{}]/g, ' ').trim();
-    const paths = raw.split(/\s*(?:\+|,|;|\band\b)\s*/i).map((value) => value.trim()).filter(Boolean);
-    paths.forEach((artifactPath, index) => references.push({ path: artifactPath, hash: hashes[index] || null }));
+function explicitTarget(payload) {
+  for (const key of ['featureName', 'feature', 'explicitFeature']) {
+    if (Object.prototype.hasOwnProperty.call(payload, key)) return { explicitFeature: payload[key] };
   }
-  return references;
+  for (const key of ['specPath', 'spec_path', 'featurePath']) {
+    if (Object.prototype.hasOwnProperty.call(payload, key)) return { explicitPath: payload[key] };
+  }
+  return null;
 }
 
 function resolveCandidate({ projectRoot, runtime, payload }) {
-  const explicitFeature = payload.featureName || payload.feature || payload.explicitFeature || null;
-  const explicitPath = payload.specPath || payload.spec_path || payload.featurePath || null;
-  const candidates = findAllSpecCandidates(projectRoot, runtime);
+  const target = explicitTarget(payload);
+  if (target) return RESOLVER.resolveActiveSpec({ projectRoot, runtime, ...target });
+  const candidates = RESOLVER.findAllSpecCandidates(projectRoot, runtime);
   if (candidates.length > 1) return { error: 'multiple_persisted', candidates: candidates.map((candidate) => candidate.featureName) };
-  if (candidates.length === 0) {
-    if (explicitFeature || explicitPath) return { error: 'explicit_not_found', explicitFeature, explicitPath, reason: 'no globally persisted spec matches the explicit target' };
-    return null;
-  }
-  if (!explicitFeature && !explicitPath) return candidates[0];
-  const targeted = resolveActiveSpec({ projectRoot, runtime, explicitFeature, explicitPath });
-  if (!targeted || targeted.error) {
-    return {
-      error: 'explicit_mismatch',
-      explicitFeature,
-      explicitPath,
-      reason: targeted?.reason || 'explicit target does not resolve to the persisted candidate',
-    };
-  }
-  if (targeted.featureName !== candidates[0].featureName || path.resolve(targeted.specFile) !== path.resolve(candidates[0].specFile)) {
-    return {
-      error: 'explicit_mismatch',
-      explicitFeature,
-      explicitPath,
-      reason: 'explicit target does not match the sole globally persisted candidate',
-    };
-  }
-  return candidates[0];
-}
-
-function policyRank(policy, lane) {
-  const lanes = Array.isArray(policy.LANES) ? policy.LANES : ['Direct', 'Standard', 'Critical'];
-  return lanes.indexOf(lane);
-}
-
-function policyMonotonicFailures(policy, baseline, current) {
-  const failures = [];
-  if (baseline.version !== current.version) failures.push('workflow_policy.version changed');
-  if (policyRank(policy, current.lane) < policyRank(policy, baseline.lane)) failures.push(`workflow_policy.lane downgraded from ${baseline.lane} to ${current.lane}`);
-  if (policyRank(policy, current.automatic_lane) < policyRank(policy, baseline.automatic_lane)) failures.push(`workflow_policy.automatic_lane downgraded from ${baseline.automatic_lane} to ${current.automatic_lane}`);
-  const currentRisks = new Set(current.risks);
-  for (const risk of baseline.risks) if (!currentRisks.has(risk)) failures.push(`workflow_policy risk ${risk} was removed`);
-  const currentObligations = new Set(current.proof_obligations);
-  for (const obligation of baseline.proof_obligations) if (!currentObligations.has(obligation)) failures.push(`workflow_policy obligation ${obligation} was removed`);
-  return failures;
-}
-
-function mergePolicyFloor(policy, floor, current) {
-  const merged = { ...current };
-  if (policyRank(policy, floor.lane) > policyRank(policy, current.lane)) merged.lane = floor.lane;
-  if (policyRank(policy, floor.automatic_lane) > policyRank(policy, current.automatic_lane)) merged.automatic_lane = floor.automatic_lane;
-  merged.risks = [...new Set([...current.risks, ...floor.risks])];
-  const proofObligations = [];
-  const actorNeeds = [];
-  for (const source of [current, floor]) {
-    for (let index = 0; index < source.proof_obligations.length; index += 1) {
-      const obligation = source.proof_obligations[index];
-      if (proofObligations.includes(obligation)) continue;
-      proofObligations.push(obligation);
-      actorNeeds.push(source.actor_needs[index]);
-    }
-  }
-  merged.proof_obligations = proofObligations;
-  merged.actor_needs = actorNeeds;
-  return merged;
+  return candidates[0] || null;
 }
 
-function observePolicyBaseline({ STATE: state, policy, projectRoot, candidate }) {
-  if (!Object.prototype.hasOwnProperty.call(candidate.spec, 'workflow_policy')) {
-    return { ok: false, reason: 'workflow_policy is missing for persisted spec' };
-  }
-  const current = candidate.spec.workflow_policy;
-  const validation = policy.validateWorkflowPolicySnapshot(current);
-  if (!validation.valid) return { ok: false, reason: `workflow_policy is malformed: ${validation.errors.join('; ')}` };
-  let identity;
-  try {
-    identity = {
-      project_root: fs.realpathSync(projectRoot),
-      spec_file: fs.realpathSync(candidate.specFile),
-      feature_name: candidate.featureName,
-    };
-    state.ensureKey();
-    let authorityState = state.readState(projectRoot);
-    if (authorityState.malformed || authorityState.keyError || authorityState.keyMissing) {
-      return { ok: false, reason: authorityState.reason || 'completion authority state is unavailable' };
-    }
-    if (!authorityState.floor) {
-      if (authorityState.baselines.length > 0 || authorityState.pending || authorityState.grant) {
-        return { ok: false, reason: 'project policy floor is missing for persisted authority state' };
-      }
-      state.writePolicyFloor(projectRoot, current);
-      authorityState = state.readState(projectRoot);
-      if (authorityState.malformed || authorityState.keyError || authorityState.keyMissing || !authorityState.floor) {
-        return { ok: false, reason: authorityState.reason || 'project policy floor could not be persisted' };
-      }
-    } else {
-      const floorValidation = policy.validateWorkflowPolicySnapshot(authorityState.floor.policy);
-      if (!floorValidation.valid) return { ok: false, reason: `persisted project policy floor is malformed: ${floorValidation.errors.join('; ')}` };
-      const floorFailures = policyMonotonicFailures(policy, authorityState.floor.policy, current);
-      if (floorFailures.length) return { ok: false, reason: `project policy floor is monotonic and cannot be downgraded (${floorFailures.join('; ')})` };
-      const mergedFloor = mergePolicyFloor(policy, authorityState.floor.policy, current);
-      if (state.digest(authorityState.floor.policy) !== state.digest(mergedFloor)) state.writePolicyFloor(projectRoot, mergedFloor);
-    }
-    const baseline = state.readBaseline(projectRoot, identity);
-    if (!baseline) {
-      state.writeBaseline(projectRoot, identity, current);
-      return { ok: true };
-    }
-    const baselineValidation = policy.validateWorkflowPolicySnapshot(baseline.policy);
-    if (!baselineValidation.valid) return { ok: false, reason: `persisted workflow policy baseline is malformed: ${baselineValidation.errors.join('; ')}` };
-    const failures = policyMonotonicFailures(policy, baseline.policy, current);
-    if (failures.length) return { ok: false, reason: `workflow_policy baseline is monotonic and cannot be downgraded (${failures.join('; ')})` };
-    if (state.digest(baseline.policy) !== state.digest(current)) state.writeBaseline(projectRoot, identity, current);
-    return { ok: true };
-  } catch (error) {
-    return { ok: false, reason: `workflow_policy baseline unavailable: ${error.message}` };
-  }
-}
-
-function evaluateCloseout({ policy, projectRoot, runtime, payload }) {
-  const candidate = resolveCandidate({ projectRoot, runtime, payload });
-  if (!candidate) return { ok: true, candidate: null };
-  if (candidate.error) {
-    const detail = Array.isArray(candidate.candidates) ? candidate.candidates.join(', ') : (candidate.reason || candidate.error);
-    return { ok: false, candidate, reason: `${candidate.error}: ${detail}` };
-  }
-  const sessionId = payload.session_id;
-  if (typeof sessionId !== 'string' || !sessionId.trim()) return { ok: false, candidate, reason: 'trusted host session ID is unavailable' };
-  const baseline = observePolicyBaseline({ STATE, policy, projectRoot, candidate });
-  if (!baseline.ok) return { ok: false, candidate, reason: baseline.reason };
-  if (runtime.spec?.completion_gate !== undefined && runtime.spec.completion_gate !== true) return { ok: false, candidate, reason: 'runtime.spec.completion_gate is worker-writable and cannot authorize completion' };
-  const status = candidate.spec.status;
-  if (!['in_progress', 'in-progress', 'completed', 'complete'].includes(status)) return { ok: false, candidate, reason: `spec status is invalid: ${String(status)}` };
-  const registry = candidate.spec.task_registry;
-  if (!plain(registry) || Object.keys(registry).length === 0) return { ok: false, candidate, reason: 'task_registry is missing or empty' };
-
-  let runtimeContext;
-  try {
-    runtimeContext = policy.deriveRuntimeContext({
-      projectRoot,
-      specsRoot: candidate.specsDir,
-      specFile: candidate.specFile,
-      featureName: candidate.featureName,
-      runtimeSession: sessionId,
-    });
-  } catch (error) {
-    return { ok: false, candidate, reason: `runtime provenance unavailable: ${error.message}` };
-  }
-  if (!policy.isTrustedRuntimeContext(runtimeContext)) return { ok: false, candidate, reason: 'fresh trusted runtime Base/Head/context is unavailable' };
-
-  const featureDir = path.join(candidate.specsDir, candidate.featureName);
-  const receiptBodies = new Map();
-  const taskFiles = [];
-  const failures = [];
-  for (const [taskPath, task] of Object.entries(registry)) {
-    if (!plain(task) || task.status !== 'done') {
-      failures.push(`${taskPath}: status is not done`);
-      continue;
-    }
-    if (policy.isStaleFlashDone(task)) failures.push(`${taskPath}: FLASH_UNVERIFIED`);
-    const file = readTask(featureDir, taskPath);
-    const body = file ? evidenceBody(file.text) : null;
-    if (body !== null) receiptBodies.set(taskPath, body);
-    const receiptFailures = checkReceipt(featureDir, taskPath, task, runtimeContext);
-    if (receiptFailures.length) failures.push(`${taskPath}: checks ${receiptFailures.join(',')}`);
-    if (file) taskFiles.push({ path: taskPath, digest: crypto.createHash('sha256').update(file.bytes).digest('hex') });
-  }
-  if (failures.length) return { ok: false, candidate, reason: `technical completion proof is incomplete (${failures.slice(0, 4).join('; ')})` };
-
-  const firstTask = Object.keys(registry).find((taskPath) => receiptBodies.has(taskPath));
-  let completion;
-  try {
-    completion = policy.completionDecisionForSpec(candidate.spec, {
-      runtimeContext,
-      executionReceipt: firstTask ? receiptBodies.get(firstTask) : null,
-      taskContext: firstTask ? registry[firstTask] : null,
-    });
-  } catch (error) {
-    return { ok: false, candidate, reason: `workflow completion proof could not be evaluated: ${error.message}` };
-  }
-  if (completion.completion !== 'complete' && completion.completion !== 'not_applicable') {
-    return { ok: false, candidate, reason: completion.blocker || 'workflow completion proof is incomplete' };
-  }
-
-  const artifactRefs = [...receiptBodies.values()].flatMap(artifactReferences).sort((left, right) => `${left.path}:${left.hash}`.localeCompare(`${right.path}:${right.hash}`));
-  const artifactFiles = artifactRefs.map((reference) => ({
-    ...reference,
-    digest: crypto.createHash('sha256').update(readBoundFile(projectRoot, reference.path) || Buffer.from('<missing>')).digest('hex'),
-  }));
-  const specBytes = readBoundFile(projectRoot, candidate.specFile);
-  const binding = {
-    project_root: runtimeContext.project_root,
-    platform: process.platform,
-    session_id: sessionId,
-    feature_name: candidate.featureName,
-    spec_file: candidate.specFile,
-    runtime: { base: runtimeContext.base, head: runtimeContext.head, context_id: runtimeContext.context_id },
-    spec_digest: STATE.digest(candidate.spec),
-    spec_bytes_digest: crypto.createHash('sha256').update(specBytes || Buffer.from('<missing>')).digest('hex'),
-    policy_digest: STATE.digest(candidate.spec.workflow_policy ?? null),
-    task_registry_digest: STATE.digest(registry),
-    task_digest: STATE.digest(taskFiles),
-    artifact_digest: STATE.digest(artifactFiles),
-    provenance_digest: STATE.digest({ runtime: runtimeContext, receipts: [...receiptBodies.values()].map((body) => body.match(/^\s*(?:Base|Head|base_sha|head_sha)\s*:.*$/gim) || []) }),
+function dependencies(overrides = {}) {
+  if (!overrides.grounder) runtimeModule(scripts, 'spec-semantic-model.cjs');
+  const grounder = overrides.grounder || runtimeModule(scripts, 'spec-ground.cjs');
+  return {
+    validator: overrides.validator || runtimeModule(scripts, 'validate-spec-output.cjs'),
+    grounder,
+    semanticAuthority: overrides.semanticAuthority || require('./semantic-review-authority.cjs'),
   };
-  binding.binding_digest = STATE.digest(binding);
-  return { ok: true, candidate, runtimeContext, binding };
 }
 
-module.exports = { evaluateCloseout, resolveCandidate, observePolicyBaseline };
+module.exports = FINAL_STATE.createAuthority({
+  state: STATE,
+  resolveCandidate,
+  dependencies,
+  receipts: {
+    task: (featureDir, taskPath, task, context) => checkReceiptDetails(featureDir, taskPath, task, context),
+    feature: (featureDir, context) => checkFeatureReceipt(featureDir, context),
+  },
+});

package/src/codex/hooks/completion-authority-state.cjs

@@ -10,7 +10,8 @@ const NONCE_RE = /^[a-f0-9]{24}$/;
 const HASH_RE = /^[a-f0-9]{64}$/;
 const TTL_MS = 5 * 60 * 1000;
 const KEY_BYTES = 32;
-const SCHEMA_VERSION = 2;
+const SCHEMA_VERSION = 3;
+const LEGACY_SCHEMA_VERSION = 2;
 const EPHEMERAL_FILE_RE = /^(pending|grant)-([a-f0-9]{24})\.json$/;
 const BASELINE_FILE_RE = /^baseline-([a-f0-9]{64})\.json$/;
 const FLOOR_FILE = 'policy-floor.json';
@@ -222,7 +223,7 @@ function validateEphemeral(record, kind, nonce, now, key) {
     : ['schema_version', 'kind', 'nonce', 'binding', 'issued_at', 'expires_at', 'approved_at', 'mac'];
   if (!plain(record) || !exactKeys(record, expected)) return { ok: false, reason: 'malformed authority record' };
   if (!macMatches(record, key)) return { ok: false, reason: 'authority record MAC is invalid' };
-  if (record.schema_version !== SCHEMA_VERSION || record.kind !== kind || record.nonce !== nonce || !NONCE_RE.test(nonce)) return { ok: false, reason: 'authority record identity is invalid' };
+  if (![LEGACY_SCHEMA_VERSION, SCHEMA_VERSION].includes(record.schema_version) || record.kind !== kind || record.nonce !== nonce || !NONCE_RE.test(nonce)) return { ok: false, reason: 'authority record identity is invalid' };
   if (!plain(record.binding) || typeof record.binding.session_id !== 'string' || !record.binding.session_id.trim()) return { ok: false, reason: 'authority record binding is invalid' };
   if (!validTimestamp(record.issued_at) || !Number.isFinite(record.expires_at) || record.expires_at <= Date.parse(record.issued_at)) return { ok: false, reason: 'authority record timestamps are invalid' };
   if (kind === 'grant' && !validTimestamp(record.approved_at)) return { ok: false, reason: 'authority grant approval timestamp is invalid' };
@@ -234,7 +235,7 @@ function validateBaseline(record, filename, projectRoot, key) {
   const expected = ['schema_version', 'kind', 'identity', 'policy', 'issued_at', 'updated_at', 'mac'];
   if (!plain(record) || !exactKeys(record, expected)) return { ok: false, reason: 'malformed policy baseline' };
   if (!macMatches(record, key)) return { ok: false, reason: 'policy baseline MAC is invalid' };
-  if (record.schema_version !== SCHEMA_VERSION || record.kind !== 'baseline' || !validTimestamp(record.issued_at) || !validTimestamp(record.updated_at)) return { ok: false, reason: 'policy baseline identity or timestamps are invalid' };
+  if (![LEGACY_SCHEMA_VERSION, SCHEMA_VERSION].includes(record.schema_version) || record.kind !== 'baseline' || !validTimestamp(record.issued_at) || !validTimestamp(record.updated_at)) return { ok: false, reason: 'policy baseline identity or timestamps are invalid' };
   let identity;
   try { identity = normalizeIdentity(record.identity, { allowMissingSpec: true }); } catch (error) { return { ok: false, reason: error.message }; }
   if (filename !== `baseline-${identityDigest(identity)}.json` || identity.project_root !== canonicalProjectRoot(projectRoot)) return { ok: false, reason: 'policy baseline namespace is invalid' };
@@ -246,7 +247,7 @@ function validatePolicyFloor(record, filename, key) {
   const expected = ['schema_version', 'kind', 'policy', 'issued_at', 'updated_at', 'mac'];
   if (!plain(record) || !exactKeys(record, expected)) return { ok: false, reason: 'malformed project policy floor' };
   if (!macMatches(record, key)) return { ok: false, reason: 'project policy floor MAC is invalid' };
-  if (filename !== FLOOR_FILE || record.schema_version !== SCHEMA_VERSION || record.kind !== 'policy-floor' || !validTimestamp(record.issued_at) || !validTimestamp(record.updated_at)) {
+  if (filename !== FLOOR_FILE || ![LEGACY_SCHEMA_VERSION, SCHEMA_VERSION].includes(record.schema_version) || record.kind !== 'policy-floor' || !validTimestamp(record.issued_at) || !validTimestamp(record.updated_at)) {
     return { ok: false, reason: 'project policy floor identity or timestamps are invalid' };
   }
   if (!plain(record.policy)) return { ok: false, reason: 'project policy floor policy is malformed' };
@@ -344,10 +345,6 @@ function readState(projectRoot, now = Date.now()) {
   }
   if (!state.floor) {
     state.floorMissing = true;
-    if (state.pending || state.grant || state.baselines.length > 0) {
-      state.malformed = true;
-      state.reason ||= 'project policy floor is missing';
-    }
   }
   return state;
 }
@@ -509,6 +506,11 @@ module.exports = {
   FLOOR_FILE,
   stableStringify,
   digest,
+  canonicalProjectRoot,
+  atomicWrite,
+  readKey,
+  recordMac,
+  macMatches,
   userStateRoot,
   stateDir,
   clearState,

package/src/codex/hooks/completion-authority.cjs

@@ -45,6 +45,7 @@ function approve(payload) {
 }
 
 function stop(payload) {
+  if (payload.stop_hook_active === true) return;
   const loaded = loadSharedPolicy();
   if (!loaded.policy) {
     emitBlock(`Completion authority unavailable: shared workflow policy could not be loaded (${loaded.error.message}). Repair ${loaded.path} before completing tasks`);
@@ -69,6 +70,7 @@ function stop(payload) {
     }
     return;
   }
+  if (result.active === false) return;
   if (!result.ok) {
     STATE.clearState(projectRoot);
     emitBlock(`Completion authority: ${result.reason}`);
@@ -84,13 +86,17 @@ let mode = process.argv[2] || null;
 try {
   const payload = readPayload();
   mode = mode || (payload.hook_event_name === 'UserPromptSubmit' ? '--approve' : '--stop');
-  const dependencyError = loadAuthority();
-  if (dependencyError) {
-    if (mode === '--approve') context(`CafeKit completion approval failed safely; authority dependency unavailable (${dependencyError.message}).`);
-    else emitBlock(`Completion authority unavailable: ${dependencyError.message}. Repair the installed authority before completing tasks`);
-  } else if (mode === '--approve') approve(payload);
-  else if (mode === '--stop') stop(payload);
-  else throw new Error('completion authority mode is required');
+  if (mode === '--stop' && payload.stop_hook_active === true) {
+    // Host loop prevention is always silent, including when dependencies are unavailable.
+  } else {
+    const dependencyError = loadAuthority();
+    if (dependencyError) {
+      if (mode === '--approve') context(`CafeKit completion approval failed safely; authority dependency unavailable (${dependencyError.message}).`);
+      else emitBlock(`Completion authority unavailable: ${dependencyError.message}. Repair the installed authority before completing tasks`);
+    } else if (mode === '--approve') approve(payload);
+    else if (mode === '--stop') stop(payload);
+    else throw new Error('completion authority mode is required');
+  }
 } catch (error) {
   if (mode === '--approve') context(`CafeKit completion approval failed safely; no grant was issued (${error.message}).`);
   else {

package/src/codex/hooks/lib/hook-context.cjs

@@ -5,7 +5,18 @@ const fs = require('fs');
 const path = require('path');
 
 // Installed layout: <project>/.codex/hooks/lib/hook-context.cjs
-const PROJECT_ROOT = path.resolve(__dirname, '..', '..', '..');
+// Canonicalize installed project root via realpath where available; lexical fallback keeps source-tree tests working.
+// This ensures a symlink project root (e.g., /tmp/link -> /real/project) is resolved to its real location,
+// keeping assertConfiguredSpecsPath and state paths consistent with resolveSessionCwd's realpath.
+// Installed-root authority stays PROJECT_ROOT (now canonical); do not change without updating state/approval paths.
+const PROJECT_ROOT = (() => {
+  const lexical = path.resolve(__dirname, '..', '..', '..');
+  try {
+    return fs.realpathSync(lexical);
+  } catch {
+    return lexical;
+  }
+})();
 
 function readPayload() {
   const raw = fs.readFileSync(0, 'utf8').trim();
@@ -104,7 +115,10 @@ function atomicWrite(file, content, mode = 0o600) {
 
 function logCrash(hook, error) {
   try {
-    const dir = path.join(PROJECT_ROOT, '.codex', 'hooks', '.logs');
+    const isSourceTree = PROJECT_ROOT.includes(`${path.sep}packages${path.sep}spec${path.sep}src`);
+    const dir = isSourceTree
+      ? path.join(require('os').tmpdir(), 'cafekit-hook-logs', 'codex', hook)
+      : path.join(PROJECT_ROOT, '.codex', 'hooks', '.logs');
     fs.mkdirSync(dir, { recursive: true });
     fs.appendFileSync(
       path.join(dir, 'hook-log.jsonl'),

package/src/codex/hooks/lib/privacy-command-analysis.cjs

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('../../../claude/hooks/lib/privacy-command-analysis.cjs');

package/src/codex/hooks/lib/privacy-state.cjs

@@ -3,12 +3,36 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
-
-const TTL_MS = 5 * 60 * 1000;
+const PATH_SAFETY = require('./runtime-path-safety.cjs');
+
+// Codex cannot raise an interactive prompt from a hook -- PreToolUse honours no
+// "ask" decision -- so approval costs a full round trip: the agent has to relay
+// a request id and the user has to type it back. A five-minute window expired
+// mid-conversation, leaving the agent repeating a request id that could no
+// longer be approved. An hour outlives a working session's train of thought.
+const TTL_MS = 60 * 60 * 1000;
 const APPROVAL_PREFIX = 'APPROVE CAFEKIT PRIVACY ';
 function stateDir(projectRoot) {
   return path.join(projectRoot, '.codex', 'hooks', '.privacy');
 }
+function secureStateDir(projectRoot, create = false) {
+  const root = PATH_SAFETY.canonicalDirectory(projectRoot, 'privacy project root');
+  const hooks = path.join(root, '.codex', 'hooks');
+  try { PATH_SAFETY.assertComponentPath(root, hooks); }
+  catch (error) {
+    if (!create && error.code === 'ENOENT') return null;
+    throw error;
+  }
+  const dir = path.join(hooks, '.privacy');
+  if (create && !fs.existsSync(dir)) fs.mkdirSync(dir, { mode: 0o700 });
+  try { PATH_SAFETY.assertComponentPath(root, dir); }
+  catch (error) {
+    if (!create && error.code === 'ENOENT') return null;
+    throw error;
+  }
+  if (!fs.lstatSync(dir).isDirectory()) throw new Error('privacy state must be a regular directory');
+  return dir;
+}
 function hash(value) {
   return crypto.createHash('sha256').update(String(value)).digest('hex');
 }
@@ -44,16 +68,16 @@ function displayNames(filePaths) {
     : `${names.slice(0, 3).join(', ')} (+${names.length - 3} more)`;
 }
 
-function atomicWrite(file, payload) {
-  const dir = path.dirname(file);
-  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+function atomicWrite(dir, file, payload) {
+  PATH_SAFETY.assertComponentPath(dir, path.dirname(file));
   const temp = `${file}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
   fs.writeFileSync(temp, `${JSON.stringify(payload)}\n`, { encoding: 'utf8', mode: 0o600 });
   fs.renameSync(temp, file);
 }
 
-function readJson(file) {
+function readJson(dir, file) {
   try {
+    PATH_SAFETY.assertComponentPath(dir, file);
     return JSON.parse(fs.readFileSync(file, 'utf8'));
   } catch {
     return null;
@@ -61,12 +85,12 @@ function readJson(file) {
 }
 
 function cleanup(projectRoot, now = Date.now()) {
-  const dir = stateDir(projectRoot);
-  if (!fs.existsSync(dir)) return;
+  const dir = secureStateDir(projectRoot);
+  if (!dir) return;
   for (const name of fs.readdirSync(dir)) {
     if (!/^(pending|token)-[a-f0-9]+\.json$/.test(name)) continue;
     const file = path.join(dir, name);
-    const record = readJson(file);
+    const record = readJson(dir, file);
     if (!record || Number(record.expiresAt) <= now) {
       try {
         fs.unlinkSync(file);
@@ -78,9 +102,9 @@ function cleanup(projectRoot, now = Date.now()) {
 }
 
 function clearState(projectRoot) {
-  const dir = stateDir(projectRoot);
   try {
-    if (!fs.existsSync(dir)) return;
+    const dir = secureStateDir(projectRoot);
+    if (!dir) return;
     for (const name of fs.readdirSync(dir)) {
       if (/^(pending|token)-[a-f0-9]+\.json$/.test(name)) {
         try { fs.unlinkSync(path.join(dir, name)); } catch { /* concurrently consumed */ }
@@ -96,8 +120,7 @@ function createPending({
   sessionCwd,
   sessionId,
   filePaths,
-  filePath,
-  toolName
+  filePath
 }) {
   cleanup(projectRoot);
   if (!sessionId) throw new Error('A Codex session ID is required');
@@ -110,10 +133,10 @@ function createPending({
     sessionId: String(sessionId || ''),
     pathKeys: requestPathKeys(paths, sessionCwd),
     displayName: displayNames(paths),
-    toolName: String(toolName || ''),
     expiresAt: Date.now() + TTL_MS
   };
-  atomicWrite(path.join(stateDir(projectRoot), `pending-${requestId}.json`), record);
+  const dir = secureStateDir(projectRoot, true);
+  atomicWrite(dir, path.join(dir, `pending-${requestId}.json`), record);
   return record;
 }
 
@@ -122,8 +145,10 @@ function approvePending({ projectRoot, sessionId, requestId }) {
   if (!sessionId) return { ok: false, reason: 'session' };
   if (!/^[a-f0-9]{24}$/.test(requestId)) return { ok: false, reason: 'invalid' };
 
-  const pendingFile = path.join(stateDir(projectRoot), `pending-${requestId}.json`);
-  const record = readJson(pendingFile);
+  const dir = secureStateDir(projectRoot);
+  if (!dir) return { ok: false, reason: 'missing' };
+  const pendingFile = path.join(dir, `pending-${requestId}.json`);
+  const record = readJson(dir, pendingFile);
   if (!record) return { ok: false, reason: 'missing' };
   if (record.sessionId !== String(sessionId || '')) return { ok: false, reason: 'session' };
   if (Number(record.expiresAt) <= Date.now()) return { ok: false, reason: 'expired' };
@@ -134,55 +159,53 @@ function approvePending({ projectRoot, sessionId, requestId }) {
     return { ok: false, reason: 'consumed' };
   }
 
-  atomicWrite(path.join(stateDir(projectRoot), `token-${requestId}.json`), {
+  // The grant window starts when the user approves, not when the request was
+  // raised. Carrying the pending record's deadline over meant a late approval
+  // bought only the minutes left on it.
+  atomicWrite(dir, path.join(dir, `token-${requestId}.json`), {
     version: 2,
     requestId,
     sessionId: record.sessionId,
     pathKeys: record.pathKeys,
-    toolName: record.toolName,
-    expiresAt: Math.min(record.expiresAt, Date.now() + TTL_MS)
+    expiresAt: Date.now() + TTL_MS
   });
   return { ok: true, displayName: record.displayName };
 }
 
-function consumeToken({
+/**
+ * A grant is session-bound, path-bound and time-limited, but not single-use:
+ * one approval covers repeated access to the same paths until it expires.
+ * Consuming it on first use made every re-read a fresh round trip, and the tool
+ * name is not part of the identity either -- reading a file with `cat` and with
+ * a native read is the same access to the same secret.
+ */
+function hasGrant({
   projectRoot,
   sessionCwd,
   sessionId,
   filePaths,
-  filePath,
-  toolName
+  filePath
 }) {
   cleanup(projectRoot);
   if (!sessionId) return false;
-  const dir = stateDir(projectRoot);
-  if (!fs.existsSync(dir)) return false;
+  const dir = secureStateDir(projectRoot);
+  if (!dir) return false;
   const paths = requestPaths(filePaths, filePath);
   if (paths.length === 0) return false;
   const expectedPaths = requestPathKeys(paths, sessionCwd);
 
   for (const name of fs.readdirSync(dir)) {
     if (!/^token-[a-f0-9]{24}\.json$/.test(name)) continue;
-    const tokenFile = path.join(dir, name);
-    const token = readJson(tokenFile);
+    const token = readJson(dir, path.join(dir, name));
     if (
       !token ||
       token.sessionId !== String(sessionId || '') ||
       !samePathKeys(token.pathKeys, expectedPaths) ||
-      token.toolName !== String(toolName || '') ||
       Number(token.expiresAt) <= Date.now()
     ) {
       continue;
     }
-
-    const claimed = `${tokenFile}.claimed-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
-    try {
-      fs.renameSync(tokenFile, claimed);
-      fs.unlinkSync(claimed);
-      return true;
-    } catch {
-      // Only one concurrent tool invocation can rename and consume this token.
-    }
+    return true;
   }
   return false;
 }
@@ -193,7 +216,7 @@ module.exports = {
   pathKey,
   createPending,
   approvePending,
-  consumeToken,
+  hasGrant,
   cleanup,
   clearState
 };

package/src/codex/hooks/lib/runtime-path-safety.cjs

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('../../../claude/hooks/lib/runtime-path-safety.cjs');