@haposoft/cafekit 0.16.7 → 0.18.0

package/src/claude/hooks/semantic-review-authority.cjs

@@ -1,154 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
-const { spawnSync } = require('child_process');
-const STATE = require('./completion-authority-state.cjs');
-const PATH_SAFETY = require('./lib/runtime-path-safety.cjs');
-
-const SCHEMA_VERSION = 1;
-const MARKER = 'CAFEKIT_SEMANTIC_REVIEW_ATTESTATION ';
-const SHA256_RE = /^sha256:[a-f0-9]{64}$/;
-const REVIEWER_ROLE_ALLOWLIST = new Set(['code-auditor', 'code_auditor']);
-const RECORD_FIELDS = ['schema_version', 'kind', 'identity', 'semantic_digest', 'event', 'verdict', 'host_session_id', 'reviewer_agent_id', 'reviewer_agent_type', 'issued_at', 'mac'];
-
-function plain(value) {
-  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
-}
-
-function exactKeys(value, fields) {
-  return plain(value) && JSON.stringify(Object.keys(value).sort()) === JSON.stringify([...fields].sort());
-}
-
-function inside(root, target) {
-  const relative = path.relative(root, target);
-  return relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
-}
-
-function projectRoot(payload = {}) {
-  const installedRoot = path.resolve(__dirname, '..', '..');
-  if (fs.existsSync(runtimePath(installedRoot, 'hooks', path.basename(__filename)))) {
-    try { return STATE.canonicalProjectRoot(installedRoot); } catch {}
-  }
-  for (const candidate of [process.env.CLAUDE_PROJECT_DIR, process.env.PROJECT_ROOT]) {
-    if (typeof candidate === 'string' && candidate.trim()) {
-      try { return STATE.canonicalProjectRoot(candidate); } catch { /* continue */ }
-    }
-  }
-  const cwd = typeof payload.cwd === 'string' && payload.cwd.trim() ? payload.cwd : process.cwd();
-  return STATE.canonicalProjectRoot(cwd);
-}
-
-function identityFor(root, specFile, featureName) {
-  if (typeof featureName !== 'string' || !featureName.trim() || featureName.includes('/') || featureName.includes('\\') || featureName === '.' || featureName === '..' || featureName.includes('..')) throw new Error('feature identity is malformed');
-  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(featureName)) throw new Error('feature identity is malformed');
-  const canonicalRoot = STATE.canonicalProjectRoot(root);
-  const canonicalSpec = fs.realpathSync(path.resolve(specFile));
-  if (!inside(canonicalRoot, canonicalSpec) || path.basename(canonicalSpec) !== 'spec.json') throw new Error('spec identity escapes the project');
-  const relative = path.relative(canonicalRoot, canonicalSpec);
-  const expected = path.join('specs', featureName, 'spec.json');
-  if (relative !== expected) throw new Error(`spec identity must be ${expected}, not ${relative}`);
-  const spec = JSON.parse(fs.readFileSync(canonicalSpec, 'utf8'));
-  if (spec.feature_name !== featureName) throw new Error('feature identity does not match spec.json');
-  return { project_root: canonicalRoot, spec_file: canonicalSpec, feature_name: featureName };
-}
-
-function recordPath(root, identity) {
-  const name = STATE.digest({ namespace: 'cafekit-semantic-review-observation-v1', identity });
-  return path.join(STATE.stateDir(root), 'semantic-reviews', `observation-${name}.json`);
-}
-
-function parseClaim(message) {
-  const lines = String(message || '').split(/\r?\n/).filter((line) => line.startsWith(MARKER));
-  if (lines.length === 0) return null;
-  if (lines.length !== 1) throw new Error('exactly one semantic review attestation marker is required');
-  const claim = JSON.parse(lines[0].slice(MARKER.length));
-  if (!exactKeys(claim, ['feature_name', 'spec_file', 'semantic_digest', 'verdict'])) throw new Error('semantic review claim fields are malformed');
-  if (claim.verdict !== 'PASS' || !SHA256_RE.test(claim.semantic_digest || '')) throw new Error('semantic review claim must contain literal PASS and a sha256 digest');
-  return claim;
-}
-
-function validatorFor(root) {
-  const installedRoot = runtimeDir(root);
-  const installedHook = path.join(installedRoot, 'hooks', path.basename(__filename));
-  if (fs.existsSync(installedHook)) {
-    const canonicalHook = PATH_SAFETY.canonicalRegularFile(root, installedHook, 'installed semantic hook');
-    if (canonicalHook !== fs.realpathSync(__filename)) throw new Error('installed semantic hook identity is invalid');
-    const validator = path.join(installedRoot, 'scripts', 'validate-spec-output.cjs');
-    PATH_SAFETY.verifyCommonJsClosure(installedRoot, validator);
-    return PATH_SAFETY.canonicalRegularFile(installedRoot, validator, 'semantic validator');
-  }
-
-  const sourceRuntime = path.resolve(__dirname, '..');
-  const sourceRoot = path.resolve(sourceRuntime, '..');
-  if (`.${path.basename(sourceRuntime)}` !== runtimeDirName() || path.basename(sourceRoot) !== 'src') {
-    throw new Error('semantic validator runtime root is not recognized');
-  }
-  const validator = path.join(sourceRuntime, 'scripts', 'validate-spec-output.cjs');
-  PATH_SAFETY.verifyCommonJsClosure(sourceRoot, validator);
-  return PATH_SAFETY.canonicalRegularFile(sourceRoot, validator, 'semantic validator');
-}
-
-function currentDigest(root, specFile) {
-  const validator = validatorFor(root);
-  const result = spawnSync(process.execPath, [validator, path.dirname(specFile), '--semantic-digest'], { cwd: root, encoding: 'utf8' });
-  const digest = result.stdout.trim();
-  if (result.status !== 0 || !SHA256_RE.test(digest)) throw new Error(`semantic digest could not be recomputed (${result.stderr.trim() || `exit ${result.status}`})`);
-  return digest;
-}
-
-function recordFromSubagentStop(payload) {
-  // Honest-agent guardrail: the host hook observes this SubagentStop payload.
-  // The worker-authored claim is not authenticated input or a security boundary.
-  if (!plain(payload) || payload.hook_event_name !== 'SubagentStop') return { recorded: false, reason: 'event' };
-  for (const field of ['session_id', 'agent_id', 'agent_type', 'last_assistant_message']) {
-    if (typeof payload[field] !== 'string' || !payload[field].trim()) return { recorded: false, reason: `missing-${field}` };
-  }
-  if (!REVIEWER_ROLE_ALLOWLIST.has(payload.agent_type)) return { recorded: false, reason: 'reviewer-role' };
-  const root = projectRoot(payload);
-  const claim = parseClaim(payload.last_assistant_message);
-  if (claim === null) return { recorded: false, reason: 'no-claim' };
-  const requestedSpec = path.resolve(root, claim.spec_file);
-  const identity = identityFor(root, requestedSpec, claim.feature_name);
-  const digest = currentDigest(root, identity.spec_file);
-  if (digest !== claim.semantic_digest) throw new Error('claimed semantic digest does not match current artifacts');
-  const key = STATE.ensureKey();
-  const record = {
-    schema_version: SCHEMA_VERSION, kind: 'semantic-review-observation', identity,
-    semantic_digest: digest, event: 'SubagentStop', verdict: 'PASS',
-    host_session_id: payload.session_id, reviewer_agent_id: payload.agent_id,
-    reviewer_agent_type: payload.agent_type, issued_at: new Date().toISOString(),
-  };
-  record.mac = STATE.recordMac(record, key);
-  STATE.atomicWrite(recordPath(root, identity), record);
-  return { recorded: true, record };
-}
-
-function verifyAttestation(root, specFile, featureName, semanticDigest) {
-  let identity;
-  try { identity = identityFor(root, specFile, featureName); } catch (error) { return { ok: false, reason: error.message }; }
-  const file = recordPath(root, identity);
-  let record;
-  try { record = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (error) { return { ok: false, reason: error.code === 'ENOENT' ? 'matching host-hook observation is missing' : 'host-hook observation is unreadable' }; }
-  const key = STATE.readKey();
-  if (key.missing) return { ok: false, reason: 'completion authority key is missing' };
-  if (!exactKeys(record, RECORD_FIELDS) || !STATE.macMatches(record, key.key)) return { ok: false, reason: 'host-hook observation is malformed or its MAC is invalid' };
-  if (record.schema_version !== SCHEMA_VERSION || record.kind !== 'semantic-review-observation' || record.event !== 'SubagentStop' || record.verdict !== 'PASS') return { ok: false, reason: 'host-hook observation event or verdict is invalid' };
-  if (STATE.stableStringify(record.identity) !== STATE.stableStringify(identity)) return { ok: false, reason: 'host-hook observation project, feature, or spec identity is invalid' };
-  if (record.semantic_digest !== semanticDigest) return { ok: false, reason: 'host-hook observation semantic digest is stale' };
-  return { ok: true, record };
-}
-
-if (require.main === module) {
-  try {
-    const raw = fs.readFileSync(0, 'utf8').trim();
-    const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
-    if (raw) recordFromSubagentStop(normalizeHookPayload(JSON.parse(raw)));
-  } catch (error) {
-    process.stderr.write(`CafeKit semantic review SubagentStop claim rejected: ${error.message}\n`);
-  }
-}
-
-module.exports = { MARKER, REVIEWER_ROLE_ALLOWLIST, recordFromSubagentStop, verifyAttestation, identityFor, recordPath };

package/src/claude/hooks/task-scaffold-guard.cjs

@@ -1,114 +0,0 @@
-#!/usr/bin/env node
-/**
- * Copyright (c) 2026 Haposoft. MIT License.
- *
- * PreToolUse Hook — task-scaffold-guard.cjs
- * Implements: https://docs.anthropic.com/en/docs/claude-code/hooks
- *
- * Forces spec task files to be GENERATED via spec-scaffold.cjs instead of
- * hand-written. Field tests showed the model dodges the (opt-in) scaffold step
- * and raw-`Write`s every task file — the single biggest output-token cost of a
- * spec run. This hook blocks `Write` to `specs/<feature>/tasks/task-*.md`, so
- * the only path to a task file is: scaffold (creates the stub) -> Edit (fills it).
- *
- * Scope is deliberately narrow — it only ever blocks the `Write` tool on a task
- * file path. `Edit`/`MultiEdit` (filling a stub), and `Write` to any other file
- * (requirements.md, design.md, source code) are never touched. The scaffold
- * script itself writes via Node fs through a Bash call, not the `Write` tool, so
- * it is never blocked.
- *
- * Safety valves:
- *   1. fail-open when spec-scaffold.cjs is absent — you cannot force a tool that
- *      is not installed, so a hook shipped without its script must not deadlock.
- *   2. actionable block message — prints the exact scaffold command to run.
- *   3. escape hatch — "spec": { "scaffold_guard": false } in <runtime>/runtime.json.
- *
- * Exit: 0 = allow, 2 = block.
- */
-
-try {
-  const fs   = require('fs');
-  const path = require('path');
-  const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
-
-/**
- * Deny the call with a reason every host can read.
- *
- * The reason is the JSON `permissionDecisionReason`, which Claude Code reads natively and
- * grok honours "regardless of exit code"; the same text also goes to stderr, because on
- * an exit-2 denial that is the channel Claude Code feeds back, and grok reads only the
- * first stderr line. Exit 2 stays so a host that reads neither still blocks.
- */
-function denyWithReason(reason) {
-  process.stdout.write(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      permissionDecision: 'deny',
-      permissionDecisionReason: reason
-    }
-  }) + '\n');
-  process.stderr.write(reason + '\n');
-  process.exit(2);
-}
-
-  const stdin = fs.readFileSync(0, 'utf8').trim();
-  if (!stdin) process.exit(0);
-
-  const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
-  const data      = normalizeHookPayload(JSON.parse(stdin));
-  const toolName  = data.tool_name  || '';
-  const toolInput = data.tool_input || {};
-  const cwd       = data.cwd        || process.cwd();
-
-  // Only `Write` can create a file from scratch. Edit/MultiEdit require an
-  // existing file, so filling a scaffolded stub is always allowed.
-  if (toolName !== 'Write') process.exit(0);
-
-  const filePath = toolInput.file_path || toolInput.path || '';
-  if (!filePath) process.exit(0);
-
-  // Match a spec task file: .../specs/<feature>/tasks/task-<...>.md
-  const norm = filePath.replace(/\\/g, '/');
-  const isTaskFile = /(^|\/)specs\/[^/]+\/tasks\/task-[^/]+\.md$/.test(norm);
-  if (!isTaskFile) process.exit(0);
-
-  // Valve 3: explicit escape hatch via <runtime>/runtime.json (fail-closed: a
-  // missing/broken runtime.json keeps the guard ON).
-  let runtime = {};
-  try {
-    const rp = runtimePath(cwd, 'runtime.json');
-    if (fs.existsSync(rp)) runtime = JSON.parse(fs.readFileSync(rp, 'utf8'));
-  } catch { /* malformed runtime.json -> keep guard on */ }
-  if (runtime.spec && runtime.spec.scaffold_guard === false) process.exit(0);
-
-  // Valve 1: fail-open if the scaffold script is not installed next to this hook
-  // (hook lives in <runtime>/hooks/, script in <runtime>/scripts/). Forcing a tool
-  // that does not exist would deadlock task creation.
-  const scaffold = path.join(__dirname, '..', 'scripts', 'spec-scaffold.cjs');
-  if (!fs.existsSync(scaffold)) process.exit(0);
-
-  // Valve 2: block with an actionable message carrying the exact command.
-  // NOTE: deliberately does NOT mention the runtime.json escape hatch — an
-  // Smoke testing proved the model reads the advertised override and
-  // simply disables the guard itself. The hatch stays functional for humans.
-  const m = norm.match(/(^|\/)specs\/([^/]+)\/tasks\//);
-  const feature = m ? m[2] : '<feature>';
-  denyWithReason(
-    `TASK SCAFFOLD REQUIRED: task files must be generated, not hand-written.\n` +
-    `Blocked Write: ${filePath}\n\n` +
-    `Generate the stub(s), then Edit-fill the {{...}} placeholders:\n` +
-    `  node ${runtimeDirName()}/scripts/spec-scaffold.cjs ${feature} --tasks "R0-01-slug,R1-01-slug,..." --tasks-only\n` +
-    `Then use Edit (not Write) on each tasks/task-*.md stub.`
-  );
-
-} catch (e) {
-  // Never let a hook crash block the user — log and fail-open.
-  try {
-    const fs = require('fs'), p = require('path');
-    const d = require('./lib/hook-state-dir.cjs').hookStateDir();
-    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
-    fs.appendFileSync(p.join(d, 'hook-log.jsonl'),
-      JSON.stringify({ ts: new Date().toISOString(), hook: 'task-scaffold-guard', status: 'crash', error: e.message }) + '\n');
-  } catch (_) {}
-  process.exit(0);
-}

package/src/claude/hooks/usage.cjs

@@ -1,197 +0,0 @@
-#!/usr/bin/env node
-/**
- * Copyright (c) 2026 Haposoft. MIT License.
- *
- * UserPromptSubmit & PostToolUse Hook — usage.cjs
- * Implements: https://docs.anthropic.com/en/docs/claude-code/hooks
- *
- * Fetches Claude Code usage limits from Anthropic OAuth API and writes to cache.
- * Cache is read by status.cjs for statusline display.
- *
- * ⚠ EXPERIMENTAL / UNDOCUMENTED API: api.anthropic.com/api/oauth/usage with the
- * "oauth-2025-04-20" beta header is not a public contract and may break or
- * change shape without notice. Every failure path degrades to
- * status:"unavailable" (statusline hides the segment) — never block on it.
- * Disable entirely with "usage": { "enabled": false } if it misbehaves.
- *
- * Features:
- * - Cross-platform credential retrieval (macOS Keychain, file-based)
- * - Throttled API calls: 1 min (prompt) / 5 min (tool use)
- * - Disable: set "usage": { "enabled": false } in <runtime>/runtime.json
- */
-
-// Crash wrapper
-try {
-  const fs = require("fs");
-  const path = require("path");
-  const os = require("os");
-  const { execSync } = require("child_process");
-
-  const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
-  function readRuntime(cwd) {
-    try {
-      const rp = runtimePath(cwd, 'runtime.json');
-      if (fs.existsSync(rp)) {
-        return JSON.parse(fs.readFileSync(rp, 'utf-8'));
-      }
-    } catch { /* fail-open */ }
-    return {};
-  }
-
-// Cache configuration
-const USAGE_CACHE_FILE = path.join(os.tmpdir(), "ck-usage-limits-cache.json");
-const CACHE_TTL_MS = 60000; // 60 seconds
-const FETCH_INTERVAL_MS = 300000; // 5 minutes for PostToolUse
-const FETCH_INTERVAL_PROMPT_MS = 60000; // 1 minute for UserPromptSubmit
-
-/**
- * Get Claude OAuth credentials (cross-platform)
- */
-function getClaudeCredentials() {
-	// macOS: Try Keychain first
-	if (os.platform() === "darwin") {
-		try {
-			const result = execSync('security find-generic-password -s "Claude Code-credentials" -w', {
-				timeout: 5000,
-				encoding: "utf-8",
-				stdio: ["pipe", "pipe", "ignore"],
-			}).trim();
-			const parsed = JSON.parse(result);
-			if (parsed.claudeAiOauth?.accessToken) {
-				return parsed.claudeAiOauth.accessToken;
-			}
-		} catch {
-			// Fallback to file-based
-		}
-	}
-
-	// File-based credentials (Linux/Windows, or macOS fallback)
-	const credPath = path.join(os.homedir(), ".claude", ".credentials.json");
-	try {
-		const content = fs.readFileSync(credPath, "utf-8");
-		const parsed = JSON.parse(content);
-		return parsed.claudeAiOauth?.accessToken || null;
-	} catch {
-		return null;
-	}
-}
-
-/**
- * Check if we should fetch (throttled)
- */
-function shouldFetch(isUserPrompt = false) {
-	const interval = isUserPrompt ? FETCH_INTERVAL_PROMPT_MS : FETCH_INTERVAL_MS;
-
-	try {
-		if (fs.existsSync(USAGE_CACHE_FILE)) {
-			const cache = JSON.parse(fs.readFileSync(USAGE_CACHE_FILE, "utf-8"));
-			if (Date.now() - cache.timestamp < interval) {
-				return false;
-			}
-		}
-	} catch {}
-	return true;
-}
-
-/**
- * Write cache with status (available or unavailable)
- */
-function writeCache(status, data = null) {
-	fs.writeFileSync(
-		USAGE_CACHE_FILE,
-		JSON.stringify({
-			timestamp: Date.now(),
-			status,
-			data,
-		})
-	);
-}
-
-/**
- * Fetch usage limits from Anthropic OAuth API and write to cache
- * Always writes status to cache (available or unavailable) for statusline fallback
- */
-async function fetchAndCacheUsageLimits() {
-	const token = getClaudeCredentials();
-	if (!token) {
-		writeCache("unavailable");
-		return false;
-	}
-
-	try {
-		const response = await fetch("https://api.anthropic.com/api/oauth/usage", {
-			method: "GET",
-			headers: {
-				Accept: "application/json",
-				"Content-Type": "application/json",
-				Authorization: `Bearer ${token}`,
-				"anthropic-beta": "oauth-2025-04-20",
-				"User-Agent": "cafekit/1.0",
-			},
-		});
-
-		if (!response.ok) {
-			writeCache("unavailable");
-			return false;
-		}
-
-		const data = await response.json();
-		writeCache("available", data);
-		return true;
-	} catch {
-		writeCache("unavailable");
-		return false;
-	}
-}
-
-/**
- * Main hook execution - just fetch and cache, no injection
- */
-async function main() {
-	// Always allow operation to continue
-	const result = { continue: true };
-
-	try {
-		// Read hook input
-		let inputStr = "";
-		try {
-			inputStr = fs.readFileSync(0, "utf-8");
-		} catch {}
-
-		const input = JSON.parse(inputStr || "{}");
-		const cwd = input.cwd || process.cwd();
-		const runtime = readRuntime(cwd);
-		if (runtime.usage?.enabled === false) {
-			console.log(JSON.stringify(result));
-			return;
-		}
-
-		// Detect hook type
-		const isUserPrompt = typeof input.prompt === "string";
-
-		// Check if we should fetch (throttled)
-		if (shouldFetch(isUserPrompt)) {
-			await fetchAndCacheUsageLimits();
-		}
-	} catch {}
-
-	// Output result (no injection, just continue)
-	console.log(JSON.stringify(result));
-  }
-
-  main().catch(() => {
-    console.log(JSON.stringify({ continue: true }));
-    process.exit(0);
-  });
-} catch (e) {
-  // Minimal crash logging (zero deps — only Node builtins)
-  try {
-    const fs = require('fs');
-    const p = require('path');
-    const logDir = require('./lib/hook-state-dir.cjs').hookStateDir();
-    if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
-    fs.appendFileSync(p.join(logDir, 'hook-log.jsonl'),
-      JSON.stringify({ ts: new Date().toISOString(), hook: p.basename(__filename, '.cjs'), status: 'crash', error: e.message }) + '\n');
-  } catch (_) {}
-  process.exit(0); // fail-open
-}

package/src/claude/skills/delegate/SKILL.md

@@ -1,124 +0,0 @@
----
-name: cf:delegate
-description: "Delegate implementation tasks from Claude Code to external CLI agents (Codex or Grok). Covers task-brief authoring, non-interactive dispatch, permission setup, background monitoring, resume, and independent verification of the returned work."
-user-invocable: true
-when_to_use: "Invoke when the user asks to assign/offload a coding task to codex or grok, or to run work on an external agent CLI."
-category: orchestration
-keywords: [delegate, codex, grok, external-agent, offload, assign]
-argument-hint: "<codex|grok> <task-description | path/to/task-brief.md>"
-metadata:
-  author: haposoft
-  version: "1.0.0"
----
-# Delegate to External Agents (Codex / Grok)
-
-Dispatch a well-scoped implementation task to an external agentic CLI — **Codex** (OpenAI) or **Grok** (xAI Grok Build) — from a Claude Code session acting as orchestrator. Claude Code stays responsible for: writing the task brief, choosing safe permissions, monitoring, and **independently verifying** the result before reporting completion.
-
-**Mantra:** Brief precisely, sandbox tightly, verify independently.
-
-## When to Use
-
-- User explicitly asks to hand a task to codex/grok ("giao cho codex", "assign to grok").
-- Parallel workstreams: Claude Code keeps orchestrating while an external agent implements a scoped task.
-- Cross-checking: a second model implements or reviews independently.
-
-Do NOT delegate: tasks touching secrets/`.env`, deploys to shared environments, destructive migrations on live data, or tasks whose scope is still unclear (clarify first — a vague brief wastes an entire agent run).
-
-## Workflow
-
-### 1. Write the task brief (mandatory, file-based)
-
-External agents run **fresh-context** — they see none of your conversation. Write the brief to a file (convention: `plans/<slug>-task.md` in the target repo), never inline-only. Follow the orchestrator prompt rules (`.claude/rules/orchestrator.md`): the brief must be self-contained.
-
-Required sections:
-
-```markdown
-# Task: <title>
-
-> Self-contained brief for a fresh-context agent. Date: <YYYY-MM-DD>.
-> FOUNDATION: <state of the working tree the agent builds on — branch,
-> uncommitted changes it must NOT revert, verified test/build status>
-
-## Context        — project, architecture, why this task exists
-## Scope          — numbered work items with exact file paths
-## Constraints    — what must NOT be touched (staging data, .env, deploys,
-                    unrelated refactors); repo rules to obey (CLAUDE.md)
-## Completion Criteria — verifiable, numbered
-## Evidence required   — exact commands whose output proves completion
-```
-
-Rules of thumb:
-- Name exact files and line-level anchors where known; agents burn tokens rediscovering what you already know.
-- State dependency order explicitly if this task builds on another agent's uncommitted work ("do NOT revert/stash existing changes").
-- Put user-pending decisions in Constraints as forbidden actions (e.g. "do NOT touch staging rows until user confirms").
-
-### 2. Protect the working tree
-
-Before dispatch, snapshot state you cannot afford to lose:
-
-```bash
-git stash push -u -m "backup: <reason>" && git stash apply -q   # snapshot, keep tree intact
-```
-
-Prefer isolation when the task is risky or parallel to other edits:
-- Grok: `--worktree=<name>` (built-in).
-- Codex: run with `-C <worktree-dir>` after creating a git worktree yourself.
-
-If the agent must build on uncommitted changes, isolation is not possible — use the stash-backup pattern above and say so in the brief.
-
-### 3. Dispatch
-
-Load the matching reference for exact flags, permission model, and pitfalls:
-- **Codex:** `./references/codex-delegation.md`
-- **Grok:** `./references/grok-delegation.md`
-
-Common principles:
-- Run non-interactive/headless mode in a **background** shell; both CLIs stream progress to stdout.
-- Grant the **minimum** permission set that lets the agent write code and run its Evidence commands (npm/node). Never grant full-access/bypass modes for routine tasks.
-- Model/effort overrides: pass explicitly rather than relying on user config, so the run is reproducible.
-- Capture the output file path; check progress after ~20–30s to confirm the agent actually started (auth errors, bad flags, and permission blocks surface early).
-
-### 4. Monitor
-
-- Poll the background output periodically; look for permission-block messages — both CLIs degrade to "design-only" output instead of failing loudly when a write tool is blocked.
-- If blocked on permissions: **resume the same session** with corrected flags (both CLIs support resume; see references) — context is preserved, work continues instead of restarting.
-- Apply the 3-strike rule from `.claude/rules/orchestrator.md`: same failure 3+ times → stop, escalate to user with evidence.
-
-### 5. Verify independently (non-negotiable)
-
-External-agent claims are **not** evidence (CLAUDE.md: no completion claim without fresh proof from the current run). After the agent reports done:
-
-1. `git status` / `git diff` — confirm the changed file set matches the brief's Scope; flag out-of-scope edits.
-2. Run the brief's Evidence commands yourself (tests, build). The agent's transcript of a test run does not count.
-3. Check Completion Criteria one by one.
-4. Report to user: what was delegated, what came back, verification results, and any deviations.
-
-### 6. Sync
-
-- Keep the brief file updated (checklist ticks / blockers) so it doubles as task state.
-- If a spec (`specs/<slug>/`) governs the work, follow the Tollgate Protocol (`.claude/rules/state-sync.md`): update `spec.json` + task files only after verification passes.
-- The user decides commit/merge/deploy — delegation ends at verified working-tree changes unless told otherwise.
-
-## Choosing Codex vs Grok
-
-Both are capable general coding agents; prefer the one the user names. If unspecified:
-
-| Factor | Codex | Grok |
-|---|---|---|
-| Isolation | manual git worktree + `-C` | built-in `--worktree=<name>` |
-| Structured output | `--output-schema` (JSON Schema) | `--json-schema` |
-| Self-verification | ask in the brief | `--check` flag appends a verify loop |
-| Resume | `codex exec resume <id>` | `grok --resume <id>` |
-
-## Rules
-
-- Never grant `--dangerously-bypass-approvals-and-sandbox` (codex) or `bypassPermissions` (grok) for routine delegation.
-- Never let an external agent touch `.env`, secrets, staging/production data, or run deploys.
-- Never report the agent's own success claim as completion — verify first.
-- Never re-dispatch a blocked task unchanged (BLOCKED ≠ retry; fix the cause: permissions, context, or scope).
-- One writer per file set: don't run two agents (or an agent + yourself) editing the same files concurrently.
-
-## References
-
-- `./references/codex-delegation.md` — Codex CLI: exec mode, sandbox/approval model, resume, pitfalls
-- `./references/grok-delegation.md` — Grok CLI: headless mode, worktree, permission rules, resume, pitfalls

package/src/claude/skills/delegate/references/codex-delegation.md

@@ -1,71 +0,0 @@
-# Delegating to Codex CLI
-
-Verified against codex-cli 0.144.4 (2026-07). Re-check `codex exec --help` if flags fail — the CLI evolves quickly.
-
-## Preflight
-
-```bash
-which codex && codex --version        # installed?
-codex doctor                          # auth + runtime health (slow; run only when suspicious)
-```
-
-User-level defaults live in `~/.codex/config.toml` (`model`, `model_reasoning_effort`, agents, MCP servers). Overrides via `-m` and `-c key=value` beat config — pass them explicitly for reproducible runs.
-
-## Non-interactive dispatch: `codex exec`
-
-Reads the prompt from an argument, or from **stdin** when the argument is `-`. Prefer stdin + brief file:
-
-```bash
-codex exec \
-  -m gpt-5.6-terra \
-  -c model_reasoning_effort='"max"' \
-  --sandbox workspace-write \
-  -o /tmp/codex-last-message.txt \
-  - < plans/<slug>-task.md
-```
-
-Run it in a background shell and poll the output.
-
-### Key flags
-
-| Flag | Notes |
-|---|---|
-| `-m <model>` | model ID, e.g. `gpt-5.6-terra` (note spelling: *terra*) |
-| `-c model_reasoning_effort='"max"'` | TOML-parsed value — keep the inner quotes |
-| `--sandbox <mode>` | `read-only` \| `workspace-write` \| `danger-full-access` |
-| `-o <file>` | write the agent's final message to a file — easiest completion check |
-| `-C <dir>` | working root (use for delegating into a git worktree) |
-| `--add-dir <dir>` | extra writable dirs alongside the workspace |
-| `--output-schema <file>` | JSON Schema constraining the final response |
-| `--json` | JSONL event stream on stdout (machine parsing) |
-| `--ephemeral` | don't persist session files |
-
-### Pitfalls
-
-- **`-a` / `--ask-for-approval` is TUI-only.** `codex exec` rejects it (`error: unexpected argument '-a' found`). Exec mode is implicitly `approval: never` — sandbox mode is your only control there.
-- **`workspace-write` limits writes, not reads**, to: workdir, `/tmp`, `$TMPDIR`. Network is available. Commands needing writes outside (global installs) will fail — keep Evidence commands repo-local.
-- **Effort value is TOML**: `-c model_reasoning_effort='"max"'` (double-quoted inside single quotes). Bare `max` may parse as a literal string too, but the quoted form is unambiguous.
-- Startup banner echoes `model:`, `reasoning effort:`, `sandbox:` — **verify these lines** ~20s after dispatch instead of assuming flags took effect.
-- User config may define agents/hooks/MCP servers that activate automatically; `--ignore-user-config` gives a clean run if they interfere.
-
-## Monitor & verify liveness
-
-```bash
-# ~20-30s after dispatch: banner shows model/sandbox; then agent narration follows
-head -c 1200 <output-file>
-tail -c 1500 <output-file>            # progress
-cat /tmp/codex-last-message.txt       # exists → run finished; content = final report
-```
-
-## Resume
-
-```bash
-codex exec resume --last "<follow-up>"          # most recent session
-codex exec resume <SESSION_ID> "<follow-up>"    # by id (session id printed in banner)
-```
-
-Use resume (not a fresh dispatch) when: permission-blocked mid-run, follow-up fixes after your verification failed, or continuing a design into implementation.
-
-## Review mode
-
-`codex review` (or `codex exec review`) runs a non-interactive code review of the current repo — useful as an independent second-opinion pass on another agent's diff.