@yunhozz/arc 0.1.2 → 0.1.3

package/codex/skill/runtime/store.mjs

@@ -0,0 +1,63 @@
+import {verifiedReconciliation} from './gate.mjs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {validateWorkflowState, validateRequest} from './schema.mjs';
+/** Hash complete normalized decision inputs at the trusted caller boundary, never a tool-supplied hash. */
+export function fingerprintRequest(input){
+ const canonical=value=>{
+  if(value===null||typeof value==='string'||typeof value==='boolean')return value;
+  if(typeof value==='number'&&Number.isFinite(value))return value;
+  if(Array.isArray(value))return value.map(canonical);
+  if(value&&Object.getPrototypeOf(value)===Object.prototype)return Object.fromEntries(Object.keys(value).sort().map(key=>[key,canonical(value[key])]));
+  throw Error('Request fingerprint requires complete JSON inputs');
+ };
+ return 'sha256:'+crypto.createHash('sha256').update(JSON.stringify(canonical(input))).digest('hex');
+}
+/** A failed/interrupted transaction retains the original state. Locks are never silently recovered. */
+export async function transactWorkflow({statePath,expectedRevision,requestId,request,requestFingerprint,decide}){
+ if(!path.isAbsolute(statePath)||!Number.isSafeInteger(expectedRevision)||expectedRevision<0||typeof requestId!=='string'||!requestId||typeof decide!=='function')throw Error('Invalid transaction');
+ if(typeof requestFingerprint!=='string'||!/^sha256:[a-f0-9]{64}$/.test(requestFingerprint))throw Error('Valid request fingerprint required');
+ const normalized=validateRequest(structuredClone(request));
+ if(normalized.requestId!==requestId||fingerprintRequest(normalized)!==requestFingerprint)throw Error('Request fingerprint conflict with normalized input');
+ const parent=await fs.realpath(path.dirname(statePath));statePath=path.join(parent,path.basename(statePath));
+ const lockPath=statePath+'.lock';let lock;let temporary;
+ try{
+  lock=await fs.open(lockPath,'wx',0o600);
+  const stat=await fs.lstat(statePath);if(!stat.isFile()||stat.isSymbolicLink())throw Error('State must be regular file');
+  const state=validateWorkflowState(JSON.parse(await fs.readFile(statePath,'utf8')));
+  const prior=state.requests.find(r=>r.requestId===requestId);
+  let decision;
+  if(prior){
+   if(prior.requestFingerprint!==requestFingerprint)throw Error('Request fingerprint conflict');
+   const current=await decide(structuredClone(state));
+   if(!current||!['allow','deny','hold'].includes(current.decision))throw Error('Invalid replay decision');
+   const completing=normalized.operation==='commit'&&prior.decision.decision==='allow'&&prior.decision.expectedCommit&&current.decision==='allow'&&current.proposedTransition&&verifiedReconciliation(current,state,current.proposedTransition,prior.decision.expectedCommit)&&!state.commits.some(c=>c.requestId===requestId);
+   if(completing)decision=current;
+   else{
+    const replay={...current,proposedTransition:null};
+    if(current.decision==='allow'&&(current.proposedTransition||!['read','draft','review'].includes(normalized.operation))){replay.decision='hold';replay.reason='Replay cannot authorize repeated state or external effects';}
+    return {state,decision:replay,replayed:true};
+   }
+  }
+  if(state.revision!==expectedRevision)throw Error('Stale revision');
+  decision??=await decide(structuredClone(state));
+  if(!decision||!['allow','deny','hold'].includes(decision.decision))throw Error('Invalid decision');
+  const next=decision.proposedTransition?structuredClone(decision.proposedTransition):structuredClone(state);
+  if(decision.decision!=='allow'&&decision.proposedTransition)throw Error('Denied transition');
+  if(next.workflowId!==state.workflowId||(JSON.stringify(next.target)!==JSON.stringify(state.target)&&!verifiedReconciliation(decision,state,next)))throw Error('Transaction target mismatch');
+  for(const old of state.identities){const current=next.identities.find(i=>i.actorRef===old.actorRef);if(!current||current.taskId!==old.taskId||current.role!==old.role)throw Error('Identity rebind forbidden');}
+  for(const old of state.leases){const current=next.leases.find(l=>l.actorRef===old.actorRef);if(old.status==='retired'&&(!current||current.status!=='retired'||current.taskId!==old.taskId))throw Error('Retired lease revival forbidden');}
+  next.revision=state.revision+1;next.requests=prior?state.requests.map(r=>r.requestId===requestId?{requestId,requestFingerprint,decision}:r):[...state.requests,{requestId,requestFingerprint,decision}];
+  next.audit=[...state.audit,{requestId,revision:next.revision,decision:decision.decision,ruleIds:decision.ruleIds??[],result:'pending'}];
+  validateWorkflowState(next);
+  temporary=path.join(parent,`.${path.basename(statePath)}.${crypto.randomUUID()}.tmp`);
+  const handle=await fs.open(temporary,'wx',0o600);try{await handle.writeFile(JSON.stringify(next,null,2)+'\n');await handle.sync();}finally{await handle.close();}
+  await fs.rename(temporary,statePath);temporary=undefined;
+  const directory=await fs.open(parent,'r');try{await directory.sync();}finally{await directory.close();}
+  return {state:next,decision,replayed:false};
+ }finally{
+  if(temporary)await fs.unlink(temporary).catch(()=>{});
+  if(lock){await lock.close();await fs.unlink(lockPath);}
+ }
+}

package/lib/models/profiles.mjs

@@ -1,4 +1,4 @@
-import {hookFrontmatter,validateClaudeHookCommand} from '../policy/claude-hook.mjs';
+import {validateClaudeHookCommand} from '../policy/claude-hook.mjs';
 import { parseToml, exactKeys, validateRoles, effortField, ROLES, fail } from './config.mjs';
 const tools = {
   arc_scouter: ['Read', 'Grep', 'Glob', 'WebFetch', 'WebSearch'],
@@ -74,6 +74,43 @@ function renderCodex(text, role, settings) {
   if (checked.name !== role || Object.entries(settings).some(([key, value]) => checked[key] !== value)) fail('Rendered Codex profile does not match settings');
   return Buffer.from(output);
 }
+// Validate the consumed hook subset without rewriting any hook/user bytes.
+// The two ARC entries are exact contracts; user command entries remain data.
+function validateClaudeHooks(lines){
+ const managed=new Map();let event;const events=new Set();
+ if(lines[0]!=='hooks:')fail('Unsupported managed Claude hooks');
+ for(let i=1;i<lines.length;){
+  const heading=/^  (PreToolUse|PostToolUse|SubagentStart):$/.exec(lines[i]);
+  if(heading){event=heading[1];if(events.has(event))fail('Duplicate Claude hook event');events.add(event);i++;continue;}
+  if(!event)fail('Unsupported Claude hook event');
+  const matcher=/^    - matcher: (.+)$/.exec(lines[i]);
+  let parsedMatcher,command;
+  try{
+   if(!matcher)throw Error('Missing matcher');
+   parsedMatcher=matcher[1].startsWith('"')?JSON.parse(matcher[1]):matcher[1];
+   if(typeof parsedMatcher!=='string'||!parsedMatcher||/[\r\n\x00]/.test(parsedMatcher)||(!matcher[1].startsWith('"')&&!/^[A-Za-z][A-Za-z0-9_|]*$/.test(parsedMatcher)))throw Error('Invalid matcher');
+   if(lines[i+1]!=='      hooks:'||lines[i+2]!=='        - type: command'||!lines[i+3]?.startsWith('          command: '))throw Error('Unsupported command entry');
+   command=JSON.parse(lines[i+3].slice('          command: '.length));
+   if(typeof command!=='string'||!command||/[\r\n\x00]/.test(command))throw Error('Invalid command');
+  }catch{fail('Unsupported managed Claude hooks');}
+  let isManaged=false;
+  try{validateClaudeHookCommand(command);isManaged=true;}catch{}
+  const hasFailure=lines[i+4]?.startsWith('          onFailure:');
+  if(isManaged){
+   if(lines[i+4]!=='          onFailure: block')fail('Unsupported managed Claude failure behavior');
+   const encoded=/"([A-Za-z0-9+/]+={0,2})"$/.exec(command)[1];
+   const url=new URL(Buffer.from(encoded,'base64').toString('utf8'));const file=url.pathname.split('/').at(-1);
+   const expected=file==='runtime-gate.mjs'?'"*"':'Bash';
+   if(event!=='PreToolUse'||matcher[1]!==expected||!hasFailure||managed.has(file))fail('Malformed or duplicate managed Claude hooks');
+   managed.set(file,url.href.slice(0,url.href.lastIndexOf('/')+1));
+  }else{
+   if(hasFailure&&!['          onFailure: continue','          onFailure: block'].includes(lines[i+4]))fail('Unsupported Claude failure behavior');
+   if(/runtime-gate\.mjs|role-git-guard\.mjs/.test(command))fail('Unrecognized managed Claude hook command');
+  }
+  i+=hasFailure?5:4;
+ }
+ if(managed.size!==1||!managed.has('role-git-guard.mjs'))fail('Missing or mismatched managed Claude hooks');
+}
 function renderClaude(text, role, settings) {
   const lines = linesOf(text); if (lines[0]?.replace(/\r?\n$/, '') !== '---') fail('Missing opening Claude frontmatter');
   const fields = {}, indices = {}; let current, closed = false;
@@ -81,9 +118,9 @@ function renderClaude(text, role, settings) {
     const line = lines[i].replace(/\r?\n$/, ''); if (line === '---') { closed = true; break; }
     if(line==='hooks:') {
       if(Object.hasOwn(fields,'hooks'))fail('Duplicate Claude hooks');
-      const raw=lines.slice(i,i+6).map(x=>x.replace(/\r?\n$/,''));
-      try {const command=JSON.parse(raw[5]?.replace(/^          command: /,''));validateClaudeHookCommand(command);if(raw.join('\n')!==hookFrontmatter(command))throw Error('Unsupported hooks');fields.hooks=command;}catch {fail('Unsupported managed Claude hooks');}
-      indices.hooks=i;i+=5;current='hooks';continue;
+      let end=i+1;while(end<lines.length&&/^[ \t]/.test(lines[end]))end++;
+      validateClaudeHooks(lines.slice(i,end).map(x=>x.replace(/\r?\n$/,'')));
+      fields.hooks=true;indices.hooks=i;i=end-1;current='hooks';continue;
     }
     const item = /^  - ([A-Za-z][A-Za-z0-9]*)$/.exec(line);
     if (item && current === 'tools') { fields.tools.push(item[1]); continue; }

package/lib/policy/claude-hook.mjs

@@ -16,25 +16,65 @@ export function validateClaudeHookCommand(command) {
   if(typeof command!=='string'||!command.startsWith(prefix))throw Error('Unmanaged Claude hook command');
   const encoded=/^"([A-Za-z0-9+/]+={0,2})"$/.exec(command.slice(prefix.length));if(!encoded)throw Error('Invalid Claude hook command');
   const decoded=Buffer.from(encoded[1],'base64');if(decoded.toString('base64')!==encoded[1])throw Error('Invalid hook path encoding');
-  const url=new URL(decoded.toString('utf8'));if(url.protocol!=='file:'||url.host||!url.pathname.endsWith('/hooks/role-git-guard.mjs')||url.search||url.hash)throw Error('Invalid hook file URL');
+  const url=new URL(decoded.toString('utf8'));if(url.protocol!=='file:'||url.host||!['/hooks/role-git-guard.mjs','/hooks/runtime-gate.mjs'].some(suffix=>url.pathname.endsWith(suffix))||url.search||url.hash)throw Error('Invalid hook file URL');
   return command;
 }
-export function hookFrontmatter(command=templateHookCommand,eol='\n') {
-  validateClaudeHookCommand(command);
-  return ['hooks:','  PreToolUse:','    - matcher: Bash','      hooks:','        - type: command',`          command: ${JSON.stringify(command)}`].join(eol);
+function entry(command,matcher,eol){
+ validateClaudeHookCommand(command);
+ return [`    - matcher: ${matcher}`,'      hooks:','        - type: command',`          command: ${JSON.stringify(command)}`,'          onFailure: block'].join(eol);
+}
+function entries(skillPath,eol){
+ return entry(buildClaudeHookCommand(path.join(skillPath,'hooks/role-git-guard.mjs')),'Bash',eol);
 }
-export function installClaudeHook(bytes,skillPath) {
-  const text=bytes.toString('utf8'),eol=/\r?\n/.exec(text)?.[0]??'\n';
-  const pattern=/^hooks:\r?\n  PreToolUse:\r?\n    - matcher: Bash\r?\n      hooks:\r?\n        - type: command\r?\n          command: ("[^\r\n]+")(?=\r?$)/gm;
-  const matches=[...text.matchAll(pattern)];if(matches.length!==1)throw Error('Missing or duplicate managed Claude hook');
-  validateClaudeHookCommand(JSON.parse(matches[0][1]));
-  return Buffer.from(text.replace(pattern,()=>hookFrontmatter(buildClaudeHookCommand(path.join(skillPath,'hooks/role-git-guard.mjs')),eol)));
+export function hookFrontmatter(command=templateHookCommand,eol='\n') {
+ validateClaudeHookCommand(command);
+ return ['hooks:','  PreToolUse:',entry(command,'Bash',eol)].join(eol);
 }
-export function renderSourceClaudeHook(text) {
-  const eol=/\r?\n/.exec(text)?.[0]??'\n';
-  const frontmatter=/^---\r?\n([\s\S]*?)\r?\n---(?=\r?\n|$)/.exec(text);
-  if(!frontmatter)throw Error('Missing Claude frontmatter for hook generation');
-  if(/^hooks:/m.test(frontmatter[1]))return installClaudeHook(Buffer.from(text),'/__ARC_INSTALLED_SKILL__').toString('utf8');
-  const closing=frontmatter[0].lastIndexOf(eol+'---');
-  return text.slice(0,closing)+eol+hookFrontmatter(templateHookCommand,eol)+text.slice(closing);
+function update(text,skillPath,requireManaged){
+ const eol=/\r?\n/.exec(text)?.[0]??'\n';
+ const fm=/^---\r?\n([\s\S]*?)\r?\n---(?=\r?\n|$)/.exec(text);
+ if(!fm)throw Error('Missing Claude frontmatter for hook generation');
+ let lines=fm[1].split(/\r?\n/);
+ const headers=lines.flatMap((line,i)=>/^hooks:/.test(line)?[i]:[]);
+ if(headers.length>1)throw Error('Duplicate Claude hooks');
+ let count=0;
+ if(headers.length){
+  const h=headers[0];if(lines[h]!=='hooks:')throw Error('Malformed Claude hooks');
+  let end=h+1;while(end<lines.length&&(/^[ \t]/.test(lines[end])||lines[end]===''))end++;
+  const indexes=[];for(let i=h+1;i<end;i++)if(/^  PreToolUse:/.test(lines[i]))indexes.push(i);
+  if(indexes.length>1)throw Error('Duplicate PreToolUse');
+  if(indexes.length){
+   const pre=indexes[0];if(lines[pre]!=='  PreToolUse:')throw Error('Malformed PreToolUse');
+   let finish=pre+1;while(finish<end&&!/^  \S/.test(lines[finish]))finish++;
+   const kept=[];const seen=new Set();
+   for(let i=pre+1;i<finish;){
+    if(lines[i]===''){kept.push(lines[i++]);continue;}
+    if(!/^    - /.test(lines[i]))throw Error('Malformed Claude hook entry');
+    let j=i+1;while(j<finish&&!/^    - /.test(lines[j]))j++;
+    const chunk=lines.slice(i,j),body=chunk.join('\n');
+    const commands=chunk.filter(line=>/^          command: /.test(line));
+    const managed=commands.some(line=>{try{validateClaudeHookCommand(JSON.parse(line.slice('          command: '.length)));return true;}catch{return false;}});
+    if(managed){
+     if(commands.length!==1)throw Error('Malformed managed Claude hook');
+     const command=JSON.parse(commands[0].slice('          command: '.length));
+     const encoded=/"([A-Za-z0-9+/]+={0,2})"$/.exec(command)[1];const file=new URL(Buffer.from(encoded,'base64').toString('utf8')).pathname.split('/').at(-1);
+     if(seen.has(file))throw Error('Duplicate managed Claude hook');seen.add(file);count++;
+     const matcher=file==='runtime-gate.mjs'?'    - matcher: "*"':'    - matcher: Bash';
+     const base=[matcher,'      hooks:','        - type: command',commands[0]];
+     // Legacy four-line guard upgrades once; malformed failure behavior is never repaired silently.
+     if(JSON.stringify(chunk)!==JSON.stringify(base)&&JSON.stringify(chunk)!==JSON.stringify([...base,'          onFailure: block']))throw Error('Malformed managed Claude hook');
+    }else{
+     if(body.includes(prefix)||/role-git-guard\.mjs|runtime-gate\.mjs/.test(body))throw Error('Malformed managed Claude hook command');
+     kept.push(...chunk);
+    }
+    i=j;
+   }
+   lines.splice(pre+1,finish-pre-1,...kept,...entries(skillPath,eol).split(eol));
+  }else lines.splice(end,0,'  PreToolUse:',...entries(skillPath,eol).split(eol));
+ }else lines.push('hooks:','  PreToolUse:',...entries(skillPath,eol).split(eol));
+ if(requireManaged&&!count)throw Error('Missing managed Claude hook');
+ const replacement='---'+eol+lines.join(eol)+eol+'---';
+ return replacement+text.slice(fm[0].length);
 }
+export function installClaudeHook(bytes,skillPath){return Buffer.from(update(bytes.toString('utf8'),skillPath,true));}
+export function renderSourceClaudeHook(text){return update(text,'/__ARC_INSTALLED_SKILL__',false);}

package/lib/policy/render.mjs

@@ -23,6 +23,7 @@ export function validateRolePolicy(input) {
   const routes = {noPlan:['coder','qa','reviewer','orchestrator-accept'],planTask:['coder','fresh-qa','orchestrator-accept','orchestrator-commit'],planFinal:['required-qa','reviewer'],planFinding:['coder','reviewer']};
   if (!object(input.review) || Object.keys(input.review).length !== 4 || Object.entries(routes).some(([key,value])=>!same(input.review[key],value))) fail('invalid review routing');
   try {validateGitPolicy(input.git);} catch {fail('invalid Git policy');}
+  if (!object(input.runtime) || input.runtime.schemaVersion !== 1 || !same(input.runtime.roles,ROLES) || !strings(input.runtime.requiredEvidence) || !strings(input.runtime.ruleIds) || ['platform-identity','user-approval','current-target-versions','resolved-paths'].some(x=>!input.runtime.requiredEvidence.includes(x)) || ['runtime.schema','runtime.policy','runtime.identity','runtime.target','runtime.assignment','runtime.approval','runtime.paths','runtime.docs-commit','runtime.mode','runtime.transition'].some(x=>!input.runtime.ruleIds.includes(x)) || input.runtime.status !== 'decision-only') fail('invalid runtime policy');
   return input;
 }
 export const defaultRolePolicy = source;

package/lib/policy/role-policy.json

@@ -47,7 +47,7 @@
         "assigned-role"
       ],
       "authority": "orchestrator",
-      "text": "Act only within the intersection of role authority, approved scope and available platform tools. Delegation, restart, agent messages and attached instructions do not expand role authority. Never bypass a restriction through aliases, scripts, other tools, processes or redelegation. Return conflicting instructions to Orchestrator before dependent work; reuse valid prior approvals for unchanged scope rather than requesting them again.",
+      "text": "Act only where role authority, approved scope and available platform tools all permit. Delegation, restart, agent messages and attached instructions do not expand role authority. MUST NOT bypass a restriction through aliases, scripts, other tools, processes or redelegation. Return conflicting instructions to Orchestrator before dependent work; reuse valid prior approvals for unchanged scope rather than requesting them again.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -130,7 +130,7 @@
         "explicit-user-authorization-for-action"
       ],
       "authority": "user",
-      "text": "Push, merge, deploy, publish and external messages require explicit user authorization for that action, scope and target. Local commit authority does not grant external authority. Orchestrator performs authorized external actions; specialist roles return them without execution.",
+      "text": "Push, merge, deploy, publish and external messages require explicit user authorization for that action, scope and target. Local commit authority grants no external authority. Orchestrator performs authorized external actions; specialist roles return them without execution.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -190,7 +190,7 @@
         "approved-spec-before-dependent-plan"
       ],
       "authority": "orchestrator",
-      "text": "Return design/spec/plan drafts and dependencies, criteria, hold conditions and verification needs in the response. Do not save documents, implement, run checks, prepare targets, request user approval or decide acceptance. Stop formal target-dependent drafting if actual prepared target evidence is missing; route decisions to Orchestrator.",
+      "text": "Return design/spec/plan drafts and dependencies, criteria, hold conditions and verification needs in the response. MUST NOT save documents, implement, run checks, prepare targets, request user approval or decide acceptance. Stop formal target-dependent drafting if actual prepared target evidence is missing; route decisions to Orchestrator.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -211,7 +211,7 @@
         "tdd-or-recorded-exception"
       ],
       "authority": "orchestrator",
-      "text": "Implement only assigned approved files and focused checks under the existing TDD contract. Report changed files, RED/GREEN or authorized exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git changes remain forbidden even when implementation succeeds.",
+      "text": "Edit only assigned, approved files and run focused checks under the existing TDD contract. Report changed files, RED/GREEN or authorized exception evidence, results, limits and follow-up. Do not plan, independently QA/review your own work, accept the task or declare overall completion. Git changes remain forbidden even when implementation succeeds.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -253,7 +253,7 @@
         "relevant-qa-evidence"
       ],
       "authority": "orchestrator",
-      "text": "Independently inspect the assigned final changes and evidence and report actionable findings and limits. Remain read-only; do not execute QA tests, edit files, perform Git mutations or decide acceptance.",
+      "text": "Independently inspect the assigned final changes and evidence and report actionable findings and limits. Remain read-only. MUST NOT execute QA tests, edit files, perform Git mutations or decide acceptance.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -278,7 +278,7 @@
         "qa-rechecks"
       ],
       "authority": "orchestrator",
-      "text": "For significant/high-risk work without a plan: Coder → QA and required QA rechecks → Reviewer of the final full change → Orchestrator acceptance. Do not omit Reviewer merely because no plan exists. This creates no new plan obligation.",
+      "text": "For significant/high-risk work without a plan: Coder \u2192 QA and required QA rechecks \u2192 Reviewer of the final full change \u2192 Orchestrator acceptance. MUST NOT omit Reviewer merely because no plan exists. This creates no new plan obligation.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -303,7 +303,7 @@
         "required-qa"
       ],
       "authority": "orchestrator",
-      "text": "For significant/high-risk plan work: each task uses Coder → fresh QA as required → Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.",
+      "text": "For significant/high-risk plan work: each task uses Coder \u2192 fresh QA as required \u2192 Orchestrator acceptance and focused commit. After all tasks are accepted and required QA is complete, Reviewer reviews the final full change once. Reviewer is NOT a per-task or per-commit required gate. Preserve required checks and necessary finding rechecks.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -327,7 +327,7 @@
         "reviewer-findings"
       ],
       "authority": "orchestrator",
-      "text": "For final overall Reviewer findings on plan work, including behavior findings, use Coder → Reviewer without QA reassignment; repeat until resolved. This exception applies only to that final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.",
+      "text": "For final overall Reviewer findings on plan work, including behavior findings, use Coder \u2192 Reviewer without QA reassignment; repeat until resolved. This exception applies only at the final plan stage. Preserve required QA and QA failure rechecks before initial final review and outside this exception.",
       "controls": {
         "codex": "prompt",
         "claude": "prompt"
@@ -573,5 +573,35 @@
         "positionals": "any"
       }
     }
+  },
+  "runtime": {
+    "schemaVersion": 1,
+    "roles": [
+      "orchestrator",
+      "scouter",
+      "planner",
+      "coder",
+      "qa",
+      "reviewer"
+    ],
+    "requiredEvidence": [
+      "platform-identity",
+      "user-approval",
+      "current-target-versions",
+      "resolved-paths"
+    ],
+    "ruleIds": [
+      "runtime.schema",
+      "runtime.policy",
+      "runtime.identity",
+      "runtime.target",
+      "runtime.assignment",
+      "runtime.approval",
+      "runtime.paths",
+      "runtime.docs-commit",
+      "runtime.mode",
+      "runtime.transition"
+    ],
+    "status": "decision-only"
   }
 }

package/lib/runtime/adapters/claude.mjs

@@ -0,0 +1,81 @@
+import {evaluate} from '../evaluate.mjs';
+import {evaluateCapability} from '../capabilities.mjs';
+import {registerAgentObservation} from '../identity.mjs';
+import {transactWorkflow, fingerprintRequest} from '../store.mjs';
+import {runGate} from '../gate.mjs';
+import {classifyGitCommand} from '../git-query.mjs';
+
+const text=v=>typeof v==='string'&&v.length>0;
+const object=v=>v!==null&&typeof v==='object'&&!Array.isArray(v);
+const supported=new Set(['Read','Glob','Grep','Bash','Write','Edit','MultiEdit','Agent']);
+const deny=reason=>({decision:'deny',reason,ruleIds:['runtime.claude'],proposedTransition:null});
+/** Host-verified support for this installed version is required. A config value
+ * alone cannot establish hook failure blocking; provider wiring belongs to T6. */
+export function claudeFailureBlockingReady(support){
+ return support?.status==='verified'&&support.onFailure==='block'&&text(support.platformVersion)&&text(support.verificationRef);
+}
+/** Context is a trusted host dependency, never deserialized from stdin/tool_input.
+ * describeTool must parse the complete tool invocation conservatively, and supply
+ * semantic operation, paths and descriptor. No native provider is assumed here. */
+export function normalizeClaudeEvent(input,context={}){
+ if(!object(input)||input.hook_event_name!=='PreToolUse'||!text(input.session_id)||input.session_id!==context.sessionRef||!text(context.actorRef)||!text(context.taskId)||!text(context.requestId)||!text(input.tool_use_id)||input.tool_use_id!==context.toolUseId||!text(input.tool_name)||!object(input.tool_input)||!text(input.cwd))throw Error('Verified session identity and complete PreToolUse event required');
+ const toolPath=input.tool_name;
+ const coverage={...evaluateCapability({platform:'claude',toolPath,sessionRef:context.sessionRef}),enforcement:'hook-response-only',nativeVerified:false,startupTimeout:'unknown',existingSessionInput:'unsupported',specializedPaths:'unknown',hostedTools:'unsupported'};
+ if(!claudeFailureBlockingReady(context.failureBlocking))throw Error('Verified current-version onFailure block contract required');
+ if(!supported.has(input.tool_name))return {request:null,coverage};
+ if(typeof context.describeTool!=='function')throw Error('Trusted semantic tool provider unavailable');
+ const semantic=context.describeTool(structuredClone(input));
+ if(!object(semantic)||!text(semantic.operation)||!Array.isArray(semantic.paths)||!object(semantic.descriptor))throw Error('Complete semantic tool descriptor required');
+ if(input.tool_name==='Agent'&&semantic.operation!=='assign-agent')throw Error('Agent tool requires assignment validation');
+ return {request:{requestId:context.requestId,platform:'claude',actorRef:context.actorRef,taskId:context.taskId,cwd:input.cwd,toolName:input.tool_name,arguments:structuredClone(input.tool_input),operation:semantic.operation,paths:structuredClone(semantic.paths),descriptor:structuredClone(semantic.descriptor)},coverage};
+}
+/** Only documented PreToolUse fields are emitted. hold is a native deny. */
+export function renderClaudeDecision(decision){
+ if(decision?.decision==='allow')return {};
+ const permissionDecision='deny';
+ return {hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision,permissionDecisionReason:typeof decision?.reason==='string'?decision.reason:'Runtime gate could not verify permission'}};
+}
+/** This returns a response, not proof the host applied it. Startup failures,
+ * timeout, hosted/specialized paths and existing write_stdin are outside it. */
+export async function runClaudeGate(input,context={}){
+ if(input?.hook_event_name==='PostToolUse'){
+  // Result recording cannot authorize assignment/start or prevent a completed call.
+  try{if(input.session_id===context.sessionRef&&input.tool_use_id===context.toolUseId&&text(context.actorRef)&&typeof context.recordToolResult==='function')await context.recordToolResult(structuredClone(input));}catch{}
+  return {};
+ }
+ if(input?.hook_event_name==='SubagentStart'){
+  // SubagentStart cannot prevent startup. Only a trusted provider can correlate
+  // agent_id with a pending assignment; tool/event agent_type is not authority.
+  try{
+   if(input.session_id===context.sessionRef&&text(input.agent_id)&&typeof context.observeAgent==='function'){
+    const observation=await context.observeAgent(structuredClone(input));
+    if(observation?.actorRef===input.agent_id&&observation.platform==='claude'){
+     const decision=registerAgentObservation(context.state,observation);
+     if(decision.decision==='allow'&&decision.proposedTransition&&typeof context.persistObservation==='function')await context.persistObservation(decision,observation);
+    }
+   }
+  }catch{/* Observation failure never claims startup was blocked. */}
+  return {};
+ }
+ try{
+  const {request,coverage}=normalizeClaudeEvent(input,context);
+  if(!request)return renderClaudeDecision(deny('Tool path has no verified pre-action coverage'));
+  if(!text(context.statePath))return renderClaudeDecision(deny('Trusted durable workflow store unavailable'));
+  const result=await transactWorkflow({statePath:context.statePath,expectedRevision:context.state?.revision,requestId:request.requestId,request,requestFingerprint:fingerprintRequest(request),decide:async state=>{
+   const decision=evaluate(context.policy,state,request,context.evidence);
+   if(decision.decision!=='allow')return {...decision,coverage};
+   const actor=state.identities.find(identity=>identity.actorRef===request.actorRef);
+   if(request.toolName==='Bash'&&actor?.role!=='orchestrator'){
+    const query=classifyGitCommand(request.arguments.command,context.policy.git);
+    if(!query.allowed)return {...deny('Specialist Git guard: '+query.reason),coverage};
+   }
+   if(request.operation==='commit'){
+    const git=await runGate({phase:'preflight',state,request,gitEvidence:context.gitEvidence});
+    if(git.decision!=='allow')return {...git,coverage};
+    return {...decision,expectedCommit:git.expectedCommit,coverage};
+   }
+   return {...decision,coverage};
+  }});
+  return renderClaudeDecision(result.decision);
+ }catch(error){return renderClaudeDecision(deny('Runtime validation unavailable: '+error.message));}
+}

package/lib/runtime/adapters/codex.mjs

@@ -0,0 +1,63 @@
+import {evaluate} from '../evaluate.mjs';
+import {evaluateCapability} from '../capabilities.mjs';
+import {registerAgentObservation} from '../identity.mjs';
+import {transactWorkflow, fingerprintRequest} from '../store.mjs';
+import {runGate} from '../gate.mjs';
+
+const text=v=>typeof v==='string'&&v.length>0;
+const object=v=>v!==null&&typeof v==='object'&&!Array.isArray(v);
+const supported=new Set(['Read','Glob','Grep','Bash','Write','Edit','MultiEdit','exec_command','apply_patch','Agent','spawn_agent']);
+const deny=reason=>({decision:'deny',reason,ruleIds:['runtime.codex'],proposedTransition:null});
+/** Context is a trusted host dependency, never deserialized from stdin/tool_input.
+ * describeTool must parse the complete tool invocation conservatively, and supply
+ * semantic operation, paths and descriptor. No native provider is assumed here. */
+export function normalizeCodexEvent(input,context={}){
+ if(!object(input)||input.hook_event_name!=='PreToolUse'||!text(input.session_id)||input.session_id!==context.sessionRef||!text(context.actorRef)||!text(context.taskId)||!text(context.requestId)||!text(input.tool_use_id)||input.tool_use_id!==context.toolUseId||!text(input.tool_name)||!object(input.tool_input)||!text(input.cwd))throw Error('Verified session identity and complete PreToolUse event required');
+ const toolPath=['Agent','spawn_agent'].includes(input.tool_name)?'spawn_agent':input.tool_name;
+ const coverage={...evaluateCapability({platform:'codex',toolPath,sessionRef:context.sessionRef}),enforcement:'hook-response-only',nativeVerified:false,startupTimeout:'unknown',existingSessionInput:'unsupported',specializedPaths:'unknown',hostedTools:'unsupported'};
+ if(!supported.has(input.tool_name))return {request:null,coverage};
+ if(typeof context.describeTool!=='function')throw Error('Trusted semantic tool provider unavailable');
+ const semantic=context.describeTool(structuredClone(input));
+ if(!object(semantic)||!text(semantic.operation)||!Array.isArray(semantic.paths)||!object(semantic.descriptor))throw Error('Complete semantic tool descriptor required');
+ if(['Agent','spawn_agent'].includes(input.tool_name)&&semantic.operation!=='assign-agent')throw Error('Agent tool requires assignment validation');
+ return {request:{requestId:context.requestId,platform:'codex',actorRef:context.actorRef,taskId:context.taskId,cwd:input.cwd,toolName:input.tool_name,arguments:structuredClone(input.tool_input),operation:semantic.operation,paths:structuredClone(semantic.paths),descriptor:structuredClone(semantic.descriptor)},coverage};
+}
+/** Only documented PreToolUse fields are emitted. hold is a native deny. */
+export function renderCodexDecision(decision){
+ const permissionDecision=decision?.decision==='allow'?'allow':'deny';
+ return {hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision,permissionDecisionReason:typeof decision?.reason==='string'?decision.reason:'Runtime gate could not verify permission'}};
+}
+/** This returns a response, not proof the host applied it. Startup failures,
+ * timeout, hosted/specialized paths and existing write_stdin are outside it. */
+export async function runCodexGate(input,context={}){
+ if(input?.hook_event_name==='SubagentStart'){
+  // SubagentStart cannot prevent startup. Only a trusted provider can correlate
+  // agent_id with a pending assignment; tool/event agent_type is not authority.
+  try{
+   if(input.session_id===context.sessionRef&&text(input.agent_id)&&typeof context.observeAgent==='function'){
+    const observation=await context.observeAgent(structuredClone(input));
+    if(observation?.actorRef===input.agent_id&&observation.platform==='codex'){
+     const decision=registerAgentObservation(context.state,observation);
+     if(decision.decision==='allow'&&decision.proposedTransition&&typeof context.persistObservation==='function')await context.persistObservation(decision,observation);
+    }
+   }
+  }catch{/* Observation failure never claims startup was blocked. */}
+  return {};
+ }
+ try{
+  const {request,coverage}=normalizeCodexEvent(input,context);
+  if(!request)return renderCodexDecision(deny('Tool path has no verified pre-action coverage'));
+  if(!text(context.statePath))return renderCodexDecision(deny('Trusted durable workflow store unavailable'));
+  const result=await transactWorkflow({statePath:context.statePath,expectedRevision:context.state?.revision,requestId:request.requestId,request,requestFingerprint:fingerprintRequest(request),decide:async state=>{
+   const decision=evaluate(context.policy,state,request,context.evidence);
+   if(decision.decision!=='allow')return {...decision,coverage};
+   if(request.operation==='commit'){
+    const git=await runGate({phase:'preflight',state,request,gitEvidence:context.gitEvidence});
+    if(git.decision!=='allow')return {...git,coverage};
+    return {...decision,expectedCommit:git.expectedCommit,coverage};
+   }
+   return {...decision,coverage};
+  }});
+  return renderCodexDecision(result.decision);
+ }catch(error){return renderCodexDecision(deny('Runtime validation unavailable: '+error.message));}
+}

package/lib/runtime/capabilities.mjs

@@ -0,0 +1,32 @@
+// Declarations describe documented hooks, never proof that this installation ran them.
+const contracts = {
+  codex: {spawn_agent:'Agent', followup_task:null, SubagentStart:null},
+  claude: {Agent:'Agent', SubagentStart:null},
+};
+function operationOf(receipt, platform) {
+  const matcher = contracts[platform]?.[receipt.operation];
+  return matcher && receipt.toolPath === matcher ? receipt.operation : null;
+}
+export function summarizeProbe(receipts, {platform, sessionRef, platformVersion, attemptRef} = {}) {
+  const candidates = Array.isArray(receipts) ? receipts.filter(r => r && r.source === 'native' &&
+    r.platform === platform && operationOf(r,platform) &&
+    typeof sessionRef === 'string' && sessionRef.length > 0 && r.sessionRef === sessionRef &&
+    typeof platformVersion === 'string' && platformVersion.length > 0 && r.platformVersion === platformVersion &&
+    typeof attemptRef === 'string' && attemptRef.length > 0 && r.attemptRef === attemptRef &&
+    r.event === 'PreToolUse' && ['host-result','hook-decision'].includes(r.kind) &&
+    r.decision === 'deny' && (r.kind !== 'host-result' || (r.toolExecuted === false && r.success === true))) : [];
+  // JSON is unauthenticated. No native host verifier is available here, so even
+  // a structurally valid current receipt is only an unverified observation.
+  return {platform,sessionRef,platformVersion,attemptRef,verifiedDeny:false,status:'unknown',source:'unverified',
+    toolPaths:[...new Set(candidates.map(r=>operationOf(r,platform)))]};
+}
+export function evaluateCapability({platform,toolPath,sessionRef,platformVersion,attemptRef,receipts=[]} = {}) {
+  const known=Object.hasOwn(contracts[platform] ?? {},toolPath);
+  const observationOnly=known && toolPath === 'SubagentStart';
+  const observed=summarizeProbe(receipts,{platform,sessionRef,platformVersion,attemptRef});
+  return {platform,toolPath,sessionRef,platformVersion,attemptRef,observationOnly,
+    declared:{source:'documentation',matcher:contracts[platform]?.[toolPath] ?? null},
+    status:!known || observationOnly ? 'unsupported':'unknown',verifiedDeny:false,
+    source:!known || observationOnly ? 'documentation':'unverified',
+    observedPaths:observed.toolPaths.filter(p=>p === toolPath)};
+}