regent-code 3.0.0

package/.opencode/plugins/regent.js

@@ -0,0 +1,1623 @@
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { Plugin } from '@opencode-ai/plugin';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, '../..');
+const skillsDir = path.resolve(rootDir, '.opencode', 'skills');
+
+let regentVersion = 'unknown';
+try {
+  const pkgPath = path.join(rootDir, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    regentVersion = pkg.version || 'unknown';
+  }
+} catch {
+  /* version non-critical */
+}
+
+// ── State ──
+const sessionFileChanges = new Map();
+let evidenceLog = [];
+const dispatchTimesByRoot = new Map();
+const circuitStateByRoot = new Map();
+const pluginWorkerSessionIds = new Set();
+const sessionRoots = new Map();
+
+// ── Dispatch safety limits ──
+const MAX_DISPATCH_ITEMS = 10;
+const MAX_STRING_LENGTH = 8000;
+const MAX_ID_LENGTH = 200;
+const MAX_DISPATCHES_PER_WINDOW = 20;
+const DISPATCH_WINDOW_MS = 60000;
+
+// ── Typed recovery actions ──
+const RecoveryAction = { RETRY: 'retry', ABORT: 'abort', SKIP: 'skip', ESCALATE: 'escalate' };
+
+function classifyError(err) {
+  const msg = (err?.message || String(err)).toLowerCase();
+  if (msg.includes('timeout') || msg.includes('rate limit') || msg.includes('too many'))
+    return RecoveryAction.RETRY;
+  if (
+    msg.includes('not found') ||
+    msg.includes('missing') ||
+    msg.includes('invalid') ||
+    msg.includes('enoent')
+  )
+    return RecoveryAction.ABORT;
+  if (msg.includes('permission') || msg.includes('denied') || msg.includes('unauthorized'))
+    return RecoveryAction.ESCALATE;
+  return RecoveryAction.RETRY;
+}
+
+// ── Shell guardrail ──────────────────────────────────────────
+// Deterministic, code-enforced safety net for destructive commands. The model
+// cannot reason its way past these; the hook rejects before any shell exists.
+// Patterns are deliberately precise: a hard block on root/home/wiping targets
+// and force-writes, while routine scoped commands pass untouched.
+
+const SHELL_ROOT_TARGET = /^(?:\/|~|\$HOME|\/[A-Za-z]|[a-zA-Z]:[\\/]|\.\.?(?:[\\/].*)?$)/;
+const SHELL_FORCE_PUSH = /\bgit\s+push\b[^|;&]*?(?:--force(?!-|\w)|\s-f(?![-\w]))/;
+const SHELL_WIN_ROOT_TARGET =
+  /^(?:\/|~(?=[\\/]|$)|\$HOME(?=[\\/]|$)|\$env:USERPROFILE(?=[\\/]|$)|\.\.?(?=[\\/]|$)|[a-zA-Z]:[\\/](?:\*|$))/i;
+const SHELL_CMD_RMDIR = /\b(?:rmdir|rd)\s+\/s\s*\/q\s+((?:'[^']*')|(?:"[^"]*")|\S+)/gi;
+const SHELL_WIN_DELETE_CMD = /^(?:remove-item|ri|rm|del|erase|rd|rmdir)$/i;
+const SHELL_WIN_RECURSE = /^-(?:recurse|r)$/i;
+const SHELL_WIN_FORCE = /^-(?:force|f)$/i;
+const SHELL_WIN_PATH = /^-(?:literalpath|path)(?::(.+))?$/i;
+
+function stripQuotes(value) {
+  return value.replace(/^['"]|['"]$/g, '');
+}
+
+function collectDeleteTargets(value) {
+  return String(value)
+    .split(',')
+    .map((part) => stripQuotes(part.trim()));
+}
+
+function guardWindowsDeleteReason(command) {
+  const cmd = String(command || '').trim();
+  for (const rmdirMatch of cmd.matchAll(SHELL_CMD_RMDIR)) {
+    const target = stripQuotes(rmdirMatch[1].trim());
+    if (SHELL_WIN_ROOT_TARGET.test(target)) return `cmd rmdir /s /q targets ${target}`;
+  }
+  if (/^\s*cmd(?:\.exe)?\s+\/c\b/i.test(cmd)) return null;
+
+  const tokens = cmd.split(/\s+/);
+  const start = tokens.findIndex((token) => SHELL_WIN_DELETE_CMD.test(token));
+  if (start < 0) return null;
+  let recurse = false;
+  let force = false;
+  const targets = [];
+  for (let i = start + 1; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (SHELL_WIN_RECURSE.test(token)) {
+      recurse = true;
+      continue;
+    }
+    if (SHELL_WIN_FORCE.test(token)) {
+      force = true;
+      continue;
+    }
+    const pathSwitch = token.match(SHELL_WIN_PATH);
+    if (pathSwitch) {
+      if (pathSwitch[1] !== undefined) targets.push(...collectDeleteTargets(pathSwitch[1]));
+      else if (i + 1 < tokens.length) targets.push(...collectDeleteTargets(tokens[++i]));
+      continue;
+    }
+    if (token.startsWith('-')) continue;
+    targets.push(...collectDeleteTargets(token));
+  }
+  if (!recurse || !force) return null;
+  for (const target of targets) {
+    if (SHELL_WIN_ROOT_TARGET.test(target)) return `Remove-Item -Recurse -Force targets ${target}`;
+  }
+  return null;
+}
+
+/** @param {string} command @returns {string | null} */
+function guardShellReason(command) {
+  const cmd = String(command || '').trim();
+  if (!cmd) return null;
+
+  const rmMatch = cmd.match(
+    /\brm\s+(?:-[a-z]*r[a-z]*f[a-z]*|-f[a-z]*r[a-z]*|-r[a-z]*\s+-?f[a-z]*|-f[a-z]*\s+-?r[a-z]*)\s+(.+)$/,
+  );
+  if (rmMatch && SHELL_ROOT_TARGET.test(rmMatch[1].trim())) {
+    return `rm -rf targets ${rmMatch[1].trim()}`;
+  }
+  const windowsReason = guardWindowsDeleteReason(cmd);
+  if (windowsReason) return windowsReason;
+  if (SHELL_FORCE_PUSH.test(cmd)) {
+    return 'git push --force overwrites remote history';
+  }
+  if (/\bgit\s+clean\b[^|;&]*?\s-f/.test(cmd)) {
+    return 'git clean -f deletes untracked files';
+  }
+  if (/\bgit\s+reset\b[^|;&]*?--hard/.test(cmd)) {
+    return 'git reset --hard discards working tree changes';
+  }
+  if (/\bgit\s+(?:checkout|restore)\b[^|;&]*?(?:--\s*\.|\.\s*$|-\.$)/.test(cmd)) {
+    return 'git checkout/restore of the whole tree discards uncommitted work';
+  }
+  if (
+    /\b(?:drop\s+(?:table|database|schema|index|view|extension|function)|dropdb|truncate\s+table)\b/i.test(
+      cmd,
+    )
+  ) {
+    return 'database drop/truncate is destructive';
+  }
+  return null;
+}
+
+/**
+ * @param {{ command?: string }} event
+ */
+function guardShellCreate(event) {
+  const reason = guardShellReason(event?.command || '');
+  if (reason) {
+    throw new Error(
+      `Regent guardrail: blocked shell command — ${reason}. Use a precise, reviewed alternative.`,
+    );
+  }
+}
+
+// ── Session lineage and dispatch limits ──
+function resolveRootSessionId(sessionId) {
+  if (!sessionId) return '';
+
+  let current = sessionId;
+  const visited = new Set();
+  while (sessionRoots.has(current) && !visited.has(current)) {
+    visited.add(current);
+    const parent = sessionRoots.get(current);
+    if (parent === '' || parent === current) return parent;
+    current = parent;
+  }
+  return current;
+}
+
+function trackSessionLineage(sessionId, rootSessionId) {
+  if (sessionId) sessionRoots.set(sessionId, rootSessionId ?? sessionId);
+}
+
+function dispatchRateLimit(rootSessionId) {
+  const key = rootSessionId || '';
+  const now = Date.now();
+  const times = dispatchTimesByRoot.get(key) || [];
+  while (times.length > 0 && times[0] < now - DISPATCH_WINDOW_MS) times.shift();
+  if (times.length >= MAX_DISPATCHES_PER_WINDOW) return false;
+  times.push(now);
+  dispatchTimesByRoot.set(key, times);
+  return true;
+}
+
+function circuitIsOpen(rootSessionId) {
+  const key = rootSessionId || '';
+  const state = circuitStateByRoot.get(key);
+  if ((state?.failures || 0) < 2) return false;
+
+  // Block once when open, then permit one half-open recovery attempt.
+  if (state.recoveryReady) {
+    circuitStateByRoot.set(key, { ...state, recoveryReady: false, halfOpen: true });
+    return false;
+  }
+
+  circuitStateByRoot.set(key, { ...state, recoveryReady: true });
+  return true;
+}
+
+function recordCircuitResult(rootSessionId, success) {
+  const key = rootSessionId || '';
+  if (success) {
+    circuitStateByRoot.delete(key);
+    return;
+  }
+
+  const current = circuitStateByRoot.get(key) || { failures: 0 };
+  circuitStateByRoot.set(key, { failures: current.failures + 1 });
+}
+
+// ── Evidence tracking ──
+/** @param {string} absolutePath @returns {{ exists: boolean, size?: number, mtimeMs?: number }} */
+function fileFingerprint(absolutePath) {
+  try {
+    const stat = fs.statSync(absolutePath);
+    return { exists: true, size: stat.size, mtimeMs: stat.mtimeMs };
+  } catch {
+    return { exists: false };
+  }
+}
+
+/**
+ * @param {string[]} files
+ * @param {string} directory
+ * @returns {Array<{ file: string, absolute: string, stat: { exists: boolean, size?: number, mtimeMs?: number } }>}
+ */
+function buildFingerprints(files, directory = '') {
+  return files.map((file) => {
+    const absolute = path.isAbsolute(file) ? file : path.resolve(directory || process.cwd(), file);
+    return { file, absolute, stat: fileFingerprint(absolute) };
+  });
+}
+
+/**
+ * Grade verification evidence by the current state of the files it points at.
+ * An entry is FRESH while every file it claimed still matches the fingerprint
+ * recorded when the evidence was captured; STALE when any of them changed.
+ *
+ * @param {any[]} entries
+ * @returns {{ total: number, fresh: number, stale: number, missing: number, stale_files: string[] }}
+ */
+function evidenceFreshness(entries) {
+  const grades = [];
+  const staleFiles = [];
+  for (const entry of entries) {
+    if (entry.verified !== true) continue;
+    if (!Array.isArray(entry.fingerprints) || entry.fingerprints.length === 0) {
+      grades.push('missing');
+      continue;
+    }
+    let checkable = 0;
+    let stale = false;
+    for (const fp of entry.fingerprints) {
+      if (fp?.stat?.exists !== true) continue;
+      checkable++;
+      const current = fileFingerprint(fp.absolute);
+      if (!current.exists || current.size !== fp.stat.size || current.mtimeMs !== fp.stat.mtimeMs) {
+        stale = true;
+        staleFiles.push(fp.file);
+      }
+    }
+    if (checkable === 0) {
+      grades.push('missing');
+      continue;
+    }
+    grades.push(stale ? 'stale' : 'fresh');
+  }
+  return {
+    total: grades.length,
+    fresh: grades.filter((grade) => grade === 'fresh').length,
+    stale: grades.filter((grade) => grade === 'stale').length,
+    missing: grades.filter((grade) => grade === 'missing').length,
+    stale_files: [...new Set(staleFiles)],
+  };
+}
+
+function recordEvidence(sessionId, files, rootSessionId = '', directory = '') {
+  if (files.length > 0) {
+    evidenceLog.push({
+      sessionId,
+      files,
+      rootSessionId,
+      timestamp: Date.now(),
+      verified: false,
+      fingerprints: buildFingerprints(files, directory),
+    });
+  }
+}
+function markEvidenceVerified(sessionId, rootSessionId = '') {
+  const root = resolveRootSessionId(rootSessionId);
+  for (const entry of evidenceLog) {
+    if (
+      entry.rootSessionId === root &&
+      (entry.sessionId === sessionId || entry.rootSessionId === sessionId)
+    ) {
+      entry.verified = true;
+    }
+  }
+  for (const [sid, data] of sessionFileChanges) {
+    if (data.root === root && (sid === sessionId || data.root === sessionId)) {
+      data.verified = true;
+    }
+  }
+}
+function evidenceForRoot(rootSessionId) {
+  const root = resolveRootSessionId(rootSessionId);
+  return evidenceLog.filter((entry) => entry.rootSessionId === root);
+}
+
+/** @param {string} text @returns {string} */
+function redactSecrets(text) {
+  return String(text)
+    .replace(/\bauthorization\s*:\s*(?:bearer\s+)?[^\s,;}\]]+/gi, 'authorization: <REDACTED>')
+    .replace(
+      /((?:api[_-]?key|api key|secret|token|passwd|password|authorization|bearer)(?:\s+provided)?(?:\s*[:=]\s*|\s+(?:is|was|are|were)\s+))["']?[^"'\s,;}\]]+/gi,
+      '$1<REDACTED>',
+    )
+    .replace(/\beyJ[A-Za-z0-9_-]{10,}(?:\.[A-Za-z0-9_-]{10,}){2}\b/g, '<REDACTED>')
+    .replace(
+      /\b(?:sk-(?:ant|proj|live)-[A-Za-z0-9]{8,}|sk-[A-Za-z0-9]{16,}|sk_live_[A-Za-z0-9]{16,}|ghp_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{6,}|AKIA[0-9A-Z]{16})\b/g,
+      '<REDACTED>',
+    );
+}
+
+const SENSITIVE_FOCUS_NAMES = new Set([
+  '.aws',
+  '.azure',
+  '.docker',
+  '.htpasswd',
+  '.kube',
+  '.netrc',
+  '.npmrc',
+  '.pypirc',
+  '.ssh',
+  '.yarnrc',
+  '.yarnrc.yml',
+  '.git-credentials',
+  'authorized_keys',
+  'cookies',
+  'cookies.json',
+  'known_hosts',
+  'login.json',
+  'auth.json',
+  'oauth.json',
+  'passwd',
+  'password',
+  'passwords',
+  'secrets.json',
+  'secret.json',
+  'session.json',
+  'shadow',
+  'token.json',
+  'cert',
+  'certs',
+  'certificates',
+  'key',
+  'keys',
+  'private',
+  'private-keys',
+]);
+
+const SENSITIVE_FOCUS_MATERIAL =
+  /(?:^|[._-])(?:certificate|cert|certificates|certs|key|keys|private(?:[._-]?key)?|service[-_]?account|firebase[-_]?adminsdk)(?:$|[._-])/i;
+const SENSITIVE_FOCUS_CREDENTIAL =
+  /(?:^|[._-])(?:auth|authorization|cookie|cookies|credential|credentials|oauth|pass(?:word|wd)s?|secret|secrets|session|sessions|token|tokens)(?:$|[._-])/i;
+const SENSITIVE_FOCUS_KEY = /^id_(?:rsa|dsa|ecdsa|ed25519)(?:$|[._-])/i;
+const SENSITIVE_FOCUS_EXTENSION =
+  /\.(?:asc|cer|crt|csr|der|gpg|jks|keystore|key|p12|p8|pem|pgp|pfx|ppk)$/i;
+
+function isSensitiveFocusPath(focusPath, worktreeRoot) {
+  const relative = path.relative(worktreeRoot, focusPath);
+  const segments = relative
+    .split(path.sep)
+    .filter(Boolean)
+    .map((segment) => segment.toLowerCase());
+  const name = segments.at(-1) || '';
+  const parentSegments = segments.slice(0, -1);
+
+  if (
+    parentSegments.some(
+      (segment) =>
+        segment === '.git' ||
+        SENSITIVE_FOCUS_NAMES.has(segment) ||
+        SENSITIVE_FOCUS_CREDENTIAL.test(segment) ||
+        SENSITIVE_FOCUS_MATERIAL.test(segment),
+    )
+  ) {
+    return true;
+  }
+  if (name === '.env' || name.startsWith('.env.')) return true;
+  if (name === '.git' || SENSITIVE_FOCUS_NAMES.has(name)) return true;
+  if (SENSITIVE_FOCUS_CREDENTIAL.test(name) && !/\.(?:log|md|txt)$/i.test(name)) return true;
+  return (
+    SENSITIVE_FOCUS_MATERIAL.test(name) ||
+    SENSITIVE_FOCUS_KEY.test(name) ||
+    SENSITIVE_FOCUS_EXTENSION.test(name)
+  );
+}
+
+/** @param {any} toolContext @returns {string} */
+function resolveDirectory(toolContext) {
+  return toolContext?.directory || toolContext?.worktree || process.cwd();
+}
+
+async function resolveDirectoryFromSession(sessionApi, toolContext) {
+  const directory = resolveDirectory(toolContext);
+  if (
+    toolContext?.directory ||
+    toolContext?.worktree ||
+    !toolContext?.sessionID ||
+    typeof sessionApi?.get !== 'function'
+  ) {
+    return directory;
+  }
+
+  try {
+    const session = unwrapData(await sessionApi.get({ sessionID: toolContext.sessionID }));
+    return session?.location?.directory || directory;
+  } catch {
+    return directory;
+  }
+}
+
+/** @param {string} content @returns {string} */
+const extractContent = (content) => {
+  const match = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?([\s\S]*)$/);
+  return match ? match[1] : content;
+};
+
+// ── Bootstrap cache ──────────────────────────────────────────
+/** @type {string | null | undefined} */
+let bootstrapCache;
+
+const getBootstrap = () => {
+  if (bootstrapCache !== undefined) return bootstrapCache;
+
+  const skillPath = path.join(skillsDir, 'using-regent', 'SKILL.md');
+  if (!fs.existsSync(skillPath)) {
+    bootstrapCache = null;
+    return null;
+  }
+
+  const content = extractContent(fs.readFileSync(skillPath, 'utf8'));
+
+  let constitutionText = '';
+  const constitutionPath = path.join(rootDir, 'CONSTITUTION.md');
+  if (fs.existsSync(constitutionPath)) {
+    constitutionText = fs.readFileSync(constitutionPath, 'utf8');
+  }
+
+  bootstrapCache = `<EXTREMELY_IMPORTANT>
+${content}
+
+${constitutionText}
+
+## Regent Version
+Regent v${regentVersion}
+</EXTREMELY_IMPORTANT>`;
+
+  return bootstrapCache;
+};
+
+// ── Retry with exponential backoff ──
+async function withRetry(fn, maxRetries = 2) {
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      const action = classifyError(err);
+      if (action === RecoveryAction.ABORT || action === RecoveryAction.SKIP) throw err;
+      if (attempt < maxRetries) {
+        const delay = Math.min(1000 * Math.pow(2, attempt), 4000);
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+  }
+  throw lastError;
+}
+
+/**
+ * @param {string} text
+ * @returns {{ status: string, concerns: string[], filesChanged: string[] }}
+ */
+function parseSubagentTextResponse(text) {
+  let status = 'done';
+  let concerns = [];
+
+  if (text.includes('BLOCKED')) {
+    status = 'blocked';
+  } else if (text.includes('NEEDS_CONTEXT')) {
+    status = 'needs_context';
+  } else if (text.includes('CONCERN:')) {
+    status = 'done_with_concerns';
+    concerns = text.match(/CONCERN:.*$/gm)?.map((c) => c.replace('CONCERN:', '').trim()) || [];
+  }
+
+  const pathPattern =
+    /(?:^|\n)(?:[\w./\\-]+\.[a-zA-Z0-9]+|[\w.-]+(?:[\\/][\w.-]+)+(?:\.[a-zA-Z0-9]+)?|^[A-Za-z][\w-]+\.[\w-]+|^[A-Za-z][\w-]+(?:\.[\w-]+)*$(?!\.))/gm;
+  const matches = text.match(pathPattern);
+  const filesChanged = (matches || [])
+    .map((f) => f.trim())
+    .filter(
+      (f) =>
+        !f.startsWith('CONCERN:') &&
+        !f.startsWith('NEEDS_CONTEXT') &&
+        !f.startsWith('BLOCKED') &&
+        !/^\d+\.\s/.test(f),
+    )
+    .slice(0, 20);
+
+  return { status, concerns, filesChanged };
+}
+
+function unwrapData(result) {
+  return result?.data ?? result;
+}
+
+function normalizeAgents(result) {
+  const data = unwrapData(result);
+  if (Array.isArray(data)) return data;
+  if (Array.isArray(data?.agents)) return data.agents;
+  return null;
+}
+
+function agentMode(agent) {
+  return agent?.mode;
+}
+
+function isVisibleAgent(agent) {
+  return Boolean(agent?.id) && agent.hidden !== true && agent.disabled !== true;
+}
+
+function isChildCapableAgent(agent) {
+  return isVisibleAgent(agent) && ['subagent', 'all'].includes(agentMode(agent));
+}
+
+function isPrimaryCapableAgent(agent) {
+  return isVisibleAgent(agent) && ['primary', 'all'].includes(agentMode(agent));
+}
+
+function isUnavailableAgentError(err) {
+  const message = (err?.message || String(err)).toLowerCase();
+  return (
+    message.includes('not found') ||
+    message.includes('unavailable') ||
+    message.includes('invalid agent') ||
+    message.includes('agent not')
+  );
+}
+
+async function createWorkerResolver(agentApi, options = {}) {
+  let catalog = null;
+  if (typeof agentApi?.list === 'function') {
+    try {
+      catalog = normalizeAgents(await agentApi.list());
+    } catch {
+      catalog = null;
+    }
+  }
+
+  const findAgent = async (id) => {
+    const fromCatalog = catalog?.find((agent) => agent.id === id);
+    if (fromCatalog) return fromCatalog;
+    if (catalog !== null || typeof agentApi?.get !== 'function') return undefined;
+    try {
+      return unwrapData(await agentApi.get({ agentID: id }));
+    } catch {
+      return undefined;
+    }
+  };
+
+  const validate = async (id, label = 'agent') => {
+    const agent = await findAgent(id);
+    if (!agent || !isVisibleAgent(agent)) {
+      return { error: `${label} "${id}" is unavailable` };
+    }
+    if (!isChildCapableAgent(agent)) {
+      return { error: `${label} "${id}" is primary-only and cannot be used for subagent dispatch` };
+    }
+    return { agents: [id], automatic: false };
+  };
+
+  const resolveWorker = async (requestedAgent = '') => {
+    const requested = typeof requestedAgent === 'string' ? requestedAgent.trim() : requestedAgent;
+    if (requested) return validate(requested);
+
+    const configuredWorker =
+      typeof options.workerAgent === 'string' ? options.workerAgent.trim() : '';
+    if (configuredWorker) return validate(configuredWorker, 'workerAgent');
+
+    if (catalog === null) {
+      // `general` is a documented built-in. It is the only safe fallback when
+      // a globally installed package cannot inspect project agent definitions.
+      return { agents: ['general'], automatic: false };
+    }
+
+    const candidates = [];
+    if (isChildCapableAgent(catalog.find((agent) => agent.id === 'regent-general'))) {
+      candidates.push('regent-general');
+    }
+    const configuredGeneral = catalog.find((agent) => agent.id === 'general');
+    if (!configuredGeneral || isChildCapableAgent(configuredGeneral)) {
+      candidates.push('general');
+    }
+    for (const agent of catalog) {
+      if (isChildCapableAgent(agent) && !candidates.includes(agent.id)) {
+        candidates.push(agent.id);
+      }
+    }
+
+    if (candidates.length === 0) {
+      return { error: 'No visible child-capable worker agent is available' };
+    }
+    return { agents: candidates, automatic: true };
+  };
+
+  resolveWorker.authorizeCaller = async (toolContext) => {
+    const hasAgent =
+      toolContext !== null && typeof toolContext === 'object' && 'agent' in toolContext;
+    if (!hasAgent) return null;
+
+    const caller = toolContext.agent;
+    const callerId =
+      typeof caller === 'string'
+        ? caller.trim()
+        : caller && typeof caller === 'object'
+          ? caller.id
+          : '';
+    const callerAgent = callerId ? await findAgent(callerId) : undefined;
+    if (!isPrimaryCapableAgent(callerAgent)) {
+      return 'caller is not a visible primary-capable agent; subagent dispatch is blocked';
+    }
+    return null;
+  };
+
+  return resolveWorker;
+}
+
+async function authorizeDispatchCaller(resolveWorker, toolContext) {
+  if (typeof resolveWorker?.authorizeCaller !== 'function') return null;
+  return resolveWorker.authorizeCaller(toolContext);
+}
+
+function structuredBlockedResult(message) {
+  return {
+    status: 'blocked',
+    output: `Subagent error: ${message}`,
+    concerns: [],
+    files_changed: [],
+  };
+}
+
+// ── Shared subagent dispatch ─────────────────────────────────
+/**
+ * @param {{ create: Function, generate: Function }} sessionApi
+ * @param {string} task
+ * @param {string} context
+ * @param {string} expectedOutput
+ * @param {string} [taskId]
+ * @param {any} [toolContext]
+ * @param {Function} [resolveWorker]
+ * @param {string} [agentOverride]
+ * @returns {Promise<{ status: string, output: string, concerns: string[], files_changed: string[], session_id?: string }>}
+ */
+async function dispatchSubagent(
+  sessionApi,
+  task,
+  context,
+  expectedOutput,
+  taskId = '',
+  toolContext = undefined,
+  resolveWorker = async () => ({ agents: ['general'], automatic: false }),
+  agentOverride = '',
+) {
+  const blockedResult = structuredBlockedResult;
+
+  /** @type {Array<[string, string, number]>} */
+  const inputChecks = [
+    [task, 'task', MAX_STRING_LENGTH],
+    [context, 'context', MAX_STRING_LENGTH],
+    [expectedOutput, 'expected_output', MAX_STRING_LENGTH],
+    [taskId, 'id', MAX_ID_LENGTH],
+  ];
+  for (const [value, label, limit] of inputChecks) {
+    if (typeof value !== 'string' || value.length > limit) {
+      return blockedResult(`${label} is too long (limit ${limit} characters)`);
+    }
+  }
+
+  if (agentOverride !== '' && typeof agentOverride !== 'string') {
+    return blockedResult('agent must be a string');
+  }
+  if (typeof agentOverride === 'string' && agentOverride.length > MAX_ID_LENGTH) {
+    return blockedResult(`agent is too long (limit ${MAX_ID_LENGTH} characters)`);
+  }
+
+  const callerError = await authorizeDispatchCaller(resolveWorker, toolContext);
+  if (callerError) return blockedResult(callerError);
+
+  const callerSessionId = typeof toolContext?.sessionID === 'string' ? toolContext.sessionID : '';
+  if (callerSessionId && !sessionRoots.has(callerSessionId)) {
+    trackSessionLineage(callerSessionId, callerSessionId);
+  }
+  const rootSessionId = resolveRootSessionId(callerSessionId);
+  let session;
+  try {
+    const title = task;
+    const directory = await resolveDirectoryFromSession(sessionApi, toolContext);
+    const workerSelection = await resolveWorker(agentOverride);
+    if (workerSelection.error) return blockedResult(workerSelection.error);
+    if (!dispatchRateLimit(rootSessionId)) {
+      return blockedResult(
+        `dispatch rate limit exceeded (${MAX_DISPATCHES_PER_WINDOW} dispatches per ${DISPATCH_WINDOW_MS / 1000}s)`,
+      );
+    }
+
+    for (let index = 0; index < workerSelection.agents.length; index++) {
+      const agent = workerSelection.agents[index];
+      try {
+        const createInput = { title, agent, location: { directory } };
+        const sessionResult = await withRetry(() => sessionApi.create(createInput));
+        session = unwrapData(sessionResult);
+        if (session?.id) break;
+      } catch (err) {
+        if (
+          !workerSelection.automatic ||
+          index === workerSelection.agents.length - 1 ||
+          !isUnavailableAgentError(err)
+        ) {
+          throw err;
+        }
+      }
+    }
+
+    if (!session?.id) throw new Error('session create returned no session');
+    pluginWorkerSessionIds.add(session.id);
+    trackSessionLineage(session.id, rootSessionId);
+
+    const prompt = [
+      `## Task`,
+      task,
+      ``,
+      `## Context`,
+      context,
+      ``,
+      `## Expected Output`,
+      expectedOutput,
+      ``,
+      `Complete the task. When you finish, provide:`,
+      `- summary: What you did`,
+      `- status: one of: done, blocked, needs_context, done_with_concerns`,
+      `- concerns: Any issues encountered (if status is done_with_concerns)`,
+      `- files_changed: List of files created or modified`,
+      ``,
+      `If you need more context, say NEEDS_CONTEXT and explain what you need.`,
+      `If you cannot complete the task, say BLOCKED and explain why.`,
+    ].join('\n');
+
+    const result = await withRetry(() => sessionApi.generate({ sessionID: session.id, prompt }));
+    const message = unwrapData(result);
+    const output = typeof message?.text === 'string' ? message.text : '';
+    const parsed = parseSubagentTextResponse(output);
+    const { status, concerns, filesChanged } = parsed;
+
+    // Track file changes + evidence
+    if (filesChanged.length > 0) {
+      sessionFileChanges.set(session.id, {
+        taskId,
+        files: filesChanged,
+        timestamp: Date.now(),
+        verified: false,
+        root: rootSessionId,
+      });
+      recordEvidence(session.id, filesChanged, rootSessionId, directory);
+    }
+
+    // Session is NOT deleted — remains as visible child session in TUI tree
+    return { status, output, concerns, files_changed: filesChanged, session_id: session.id };
+  } catch (err) {
+    const message = redactSecrets(err instanceof Error ? err.message : String(err)).slice(0, 500);
+    return {
+      status: 'blocked',
+      output: `Subagent error: ${message}`,
+      concerns: [],
+      files_changed: [],
+      session_id: session?.id,
+    };
+  }
+  // No finally block — sessions persist as visible TUI children
+}
+
+const TOOL_INPUTS = {
+  delegate: {
+    type: 'object',
+    properties: {
+      task: { type: 'string', description: 'The specific task for the subagent to complete' },
+      context: { type: 'string', description: 'Background context for the task' },
+      expected_output: { type: 'string', description: 'What done looks like for the task' },
+      agent: { type: 'string', description: 'Optional child-capable agent ID override' },
+    },
+    required: ['task', 'context', 'expected_output'],
+    additionalProperties: false,
+  },
+  delegate_many: {
+    type: 'object',
+    properties: {
+      tasks: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: 'Unique identifier for this task' },
+            task: { type: 'string', description: 'What this subagent should do' },
+            context: { type: 'string', description: 'Background context for this task' },
+            expected_output: { type: 'string', description: 'What done looks like for this task' },
+            agent: { type: 'string', description: 'Optional child-capable agent ID override' },
+          },
+          required: ['id', 'task', 'context', 'expected_output'],
+          additionalProperties: false,
+        },
+      },
+    },
+    required: ['tasks'],
+    additionalProperties: false,
+  },
+  research: {
+    type: 'object',
+    properties: {
+      questions: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: 'Unique identifier' },
+            question: { type: 'string', description: 'The question to research' },
+            scope: { type: 'string', description: 'Optional narrowing scope' },
+            agent: { type: 'string', description: 'Optional child-capable agent ID override' },
+          },
+          required: ['id', 'question'],
+          additionalProperties: false,
+        },
+      },
+    },
+    required: ['questions'],
+    additionalProperties: false,
+  },
+  explore: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'What to understand in the codebase' },
+      focus: { type: 'string', description: 'Optional directory path, file pattern, or topic' },
+    },
+    required: ['query'],
+    additionalProperties: false,
+  },
+  'changed-files': {
+    type: 'object',
+    properties: {
+      session_id: { type: 'string', description: 'Optional session ID filter' },
+      task_id: { type: 'string', description: 'Optional task ID filter' },
+    },
+    additionalProperties: false,
+  },
+  verify: {
+    type: 'object',
+    properties: {
+      requirements: { type: 'string', description: 'The requirements text' },
+      implementation_context: { type: 'string', description: 'What was built' },
+      session_id: { type: 'string', description: 'Optional session ID to verify' },
+    },
+    required: ['requirements', 'implementation_context'],
+    additionalProperties: false,
+  },
+};
+
+const toContent = (payload) => ({ content: JSON.stringify(payload) });
+
+const RUNTIME_COMMAND_NAMES = [
+  'orchestrate',
+  'delegate',
+  'research',
+  'tdd',
+  'diagnose',
+  'verify',
+  'review',
+  'spec',
+  'plan',
+  'ship',
+  'status',
+  'accept',
+];
+
+function frontmatterValue(content, key) {
+  return content.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))?.[1]?.trim() || '';
+}
+
+function readPackageSkills() {
+  if (!fs.existsSync(skillsDir)) return [];
+
+  try {
+    return fs
+      .readdirSync(skillsDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => {
+        const location = path.join(skillsDir, entry.name, 'SKILL.md');
+        if (!fs.existsSync(location)) return null;
+        const content = fs.readFileSync(location, 'utf8');
+        return {
+          id: entry.name,
+          name: frontmatterValue(content, 'name') || entry.name,
+          description: frontmatterValue(content, 'description'),
+          location,
+          content: extractContent(content),
+        };
+      })
+      .filter((skill) => skill !== null);
+  } catch {
+    return [];
+  }
+}
+
+function readPackageCommands() {
+  const commandsDir = path.join(rootDir, '.opencode', 'commands');
+  return RUNTIME_COMMAND_NAMES.map((name) => {
+    const location = path.join(commandsDir, `${name}.md`);
+    if (!fs.existsSync(location)) {
+      return { name, description: `Regent ${name}`, template: '' };
+    }
+
+    try {
+      const content = fs.readFileSync(location, 'utf8');
+      return {
+        name,
+        description: frontmatterValue(content, 'description') || `Regent ${name}`,
+        template: extractContent(content).trim(),
+      };
+    } catch {
+      return { name, description: `Regent ${name}`, template: '' };
+    }
+  });
+}
+
+const resetState = () => {
+  evidenceLog = [];
+  sessionFileChanges.clear();
+  dispatchTimesByRoot.clear();
+  circuitStateByRoot.clear();
+  pluginWorkerSessionIds.clear();
+  sessionRoots.clear();
+  bootstrapCache = undefined;
+};
+
+// ── Plugin export ────────────────────────────────────────────
+export default Plugin.define({
+  id: 'regent',
+  async setup(ctx) {
+    const registrations = [];
+    const options = ctx.options && typeof ctx.options === 'object' ? ctx.options : {};
+    const resolveWorker = await createWorkerResolver(ctx.agent, options);
+
+    if (typeof options.primaryAgent === 'string' && options.primaryAgent.trim()) {
+      if (typeof ctx.agent?.transform === 'function') {
+        try {
+          const primaryRegistration = await ctx.agent.transform((draft) => {
+            const target =
+              typeof draft.get === 'function'
+                ? draft.get(options.primaryAgent.trim())
+                : draft.list?.().find((agent) => agent.id === options.primaryAgent.trim());
+            if (isPrimaryCapableAgent(target)) draft.default(options.primaryAgent.trim());
+          });
+          if (primaryRegistration) registrations.push(primaryRegistration);
+        } catch {
+          /* invalid optional primaryAgent must not prevent plugin loading */
+        }
+      }
+    }
+
+    const toolRegistration = await ctx.tool.transform((draft) => {
+      draft.add({
+        name: 'delegate',
+        description:
+          'Dispatch a single focused task to a subagent. Returns structured result with status (done, blocked, needs_context). Use when a task is well-defined and self-contained.',
+        input: TOOL_INPUTS.delegate,
+        async execute(/** @type {any} */ args, toolContext) {
+          const callerError = await authorizeDispatchCaller(resolveWorker, toolContext);
+          if (callerError) return toContent(structuredBlockedResult(callerError));
+
+          const result = await dispatchSubagent(
+            ctx.session,
+            args.task,
+            args.context,
+            args.expected_output,
+            '',
+            toolContext,
+            resolveWorker,
+            args.agent,
+          );
+          return toContent(result);
+        },
+      });
+
+      draft.add({
+        name: 'delegate_many',
+        description:
+          'Dispatch multiple independent tasks to subagents in PARALLEL. All tasks run simultaneously via Promise.all with work-stealing. Use for tasks that have no dependencies on each other.',
+        input: TOOL_INPUTS.delegate_many,
+        async execute(/** @type {any} */ args, toolContext) {
+          const callerError = await authorizeDispatchCaller(resolveWorker, toolContext);
+          if (callerError) {
+            const blocked = structuredBlockedResult(callerError);
+            const blockedResults = (Array.isArray(args?.tasks) ? args.tasks : [])
+              .slice(0, MAX_DISPATCH_ITEMS)
+              .map((task) => ({ id: task?.id, ...blocked }));
+            return toContent({
+              ...blocked,
+              results: blockedResults,
+              summary: {
+                total: blockedResults.length,
+                completed: 0,
+                failed: blockedResults.length || 1,
+                needs_context: 0,
+              },
+              _blocked: true,
+            });
+          }
+
+          const rootSessionId = resolveRootSessionId(toolContext?.sessionID || '');
+
+          if (!Array.isArray(args.tasks) || args.tasks.length > MAX_DISPATCH_ITEMS) {
+            return toContent({
+              results: [],
+              summary: { total: 0, completed: 0, failed: 1, needs_context: 0 },
+              _error: `delegate_many supports at most ${MAX_DISPATCH_ITEMS} tasks`,
+            });
+          }
+
+          if (circuitIsOpen(rootSessionId)) {
+            return toContent({
+              results: [],
+              summary: { total: 0, completed: 0, failed: 1, needs_context: 0 },
+              _circuit_open: true,
+              _warning:
+                'Circuit breaker open after repeated delegate_many failures. One half-open recovery attempt is allowed; escalate to Inspector if it fails.',
+            });
+          }
+
+          // Work-stealing: convert to shared queue
+          const queue = [...args.tasks];
+          const results = [];
+
+          async function worker() {
+            while (queue.length > 0) {
+              const t = queue.shift();
+              if (!t) break;
+              const result = await dispatchSubagent(
+                ctx.session,
+                t.task,
+                t.context,
+                t.expected_output,
+                t.id,
+                toolContext,
+                resolveWorker,
+                t.agent,
+              );
+              results.push({ id: t.id, ...result });
+            }
+          }
+
+          const workerCount = Math.min(queue.length, 10);
+          const workers_arr = Array.from({ length: workerCount }, () => worker());
+          await Promise.all(workers_arr);
+
+          const failed = results.filter((r) => r.status === 'blocked').length;
+          recordCircuitResult(rootSessionId, results.length > 0 && failed === 0);
+
+          return toContent({
+            results,
+            summary: {
+              total: results.length,
+              completed: results.filter(
+                (r) => r.status === 'done' || r.status === 'done_with_concerns',
+              ).length,
+              failed,
+              needs_context: results.filter((r) => r.status === 'needs_context').length,
+            },
+          });
+        },
+      });
+
+      draft.add({
+        name: 'research',
+        description:
+          'Research multiple questions in parallel by dispatching independent research subagents. Each question gets a focused agent. Returns combined findings with synthesis.',
+        input: TOOL_INPUTS.research,
+        async execute(/** @type {any} */ args, toolContext) {
+          const callerError = await authorizeDispatchCaller(resolveWorker, toolContext);
+          if (callerError) {
+            const blocked = structuredBlockedResult(callerError);
+            const blockedFindings = (Array.isArray(args?.questions) ? args.questions : [])
+              .slice(0, MAX_DISPATCH_ITEMS)
+              .map((question) => ({
+                id: question?.id,
+                question: question?.question,
+                ...blocked,
+              }));
+            return toContent({
+              ...blocked,
+              findings: blockedFindings,
+              synthesis: `Blocked: ${callerError}`,
+              _blocked: true,
+            });
+          }
+
+          if (!Array.isArray(args.questions) || args.questions.length > MAX_DISPATCH_ITEMS) {
+            return toContent({
+              findings: [],
+              synthesis: `research supports at most ${MAX_DISPATCH_ITEMS} questions per call`,
+              _error: `research supports at most ${MAX_DISPATCH_ITEMS} questions per call`,
+            });
+          }
+
+          const results = await Promise.all(
+            args.questions.map(async (q) => {
+              const task = `Research this question thoroughly:\n${q.question}`;
+              const taskContext = q.scope
+                ? `Scope: ${q.scope}`
+                : 'Be thorough and concise. Return key findings, data points, and sources.';
+              const result = await dispatchSubagent(
+                ctx.session,
+                task,
+                taskContext,
+                'Key findings, data points, sources, and recommendations',
+                q.id,
+                toolContext,
+                resolveWorker,
+                q.agent,
+              );
+              return { id: q.id, question: q.question, ...result };
+            }),
+          );
+
+          const completed = results.filter(
+            (r) => r.status === 'done' || r.status === 'done_with_concerns',
+          );
+          const blocked = results.filter((r) => r.status === 'blocked');
+          const needsContext = results.filter((r) => r.status === 'needs_context');
+
+          // Cross-question synthesis: find common themes and contradictions
+          const allOutputs = completed.map((r) => r.output || '');
+          const commonThemes = [];
+          if (allOutputs.length >= 2) {
+            const words = {};
+            for (const output of allOutputs) {
+              const seen = new Set();
+              for (const w of output
+                .toLowerCase()
+                .split(/\s+/)
+                .filter((w) => w.length > 5)) {
+                if (!seen.has(w)) {
+                  seen.add(w);
+                  words[w] = (words[w] || 0) + 1;
+                }
+              }
+            }
+            for (const [word, count] of Object.entries(words)) {
+              if (count >= Math.ceil(allOutputs.length / 2)) {
+                commonThemes.push(word);
+              }
+            }
+          }
+
+          const summaryParts = [];
+          if (completed.length > 0) {
+            summaryParts.push(`Addressed: ${completed.map((r) => r.question).join(', ')}`);
+          }
+          if (blocked.length > 0) {
+            summaryParts.push(`Blocked: ${blocked.map((r) => r.question).join(', ')}`);
+          }
+          if (needsContext.length > 0) {
+            summaryParts.push(`Needs context: ${needsContext.map((r) => r.question).join(', ')}`);
+          }
+          if (commonThemes.length > 0) {
+            summaryParts.push(`Common themes: ${commonThemes.slice(0, 10).join(', ')}`);
+          }
+
+          return toContent({
+            findings: results,
+            synthesis:
+              summaryParts.length > 0
+                ? summaryParts.join('. ') + '.'
+                : 'No research results returned.',
+          });
+        },
+      });
+
+      draft.add({
+        name: 'explore',
+        description:
+          'Analyze the project codebase to answer structural questions. Uses SDK file operations to understand directory layout, key files, and patterns. Call this before planning to understand what exists.',
+        input: TOOL_INPUTS.explore,
+        async execute(/** @type {any} */ args, context) {
+          const toolContext = /** @type {any} */ (context);
+          const worktree = await resolveDirectoryFromSession(ctx.session, toolContext);
+          if (!worktree) {
+            return toContent({
+              structure:
+                'Error: Cannot determine project directory. OpenCode runtime did not provide context.directory or context.worktree.',
+              summary: 'Exploration requires context.directory or context.worktree',
+            });
+          }
+          let result = `Codebase exploration for: ${args.query}\n\n`;
+
+          // Top-level listing
+          try {
+            const items = fs.readdirSync(worktree, { withFileTypes: true });
+            result += '## Top-level contents\n';
+            for (const item of items) {
+              if (item.name.startsWith('.') && item.name !== '.gitignore') continue;
+              result += `${item.isDirectory() ? '/' : ''} ${item.name}\n`;
+            }
+            result += '\n';
+          } catch {
+            /* ignore read errors */
+          }
+
+          // Walk src/ if it exists (up to 3 levels)
+          try {
+            const srcDir = path.join(worktree, 'src');
+            if (fs.existsSync(srcDir)) {
+              result += '## src/ directory\n';
+              /** @param {string} dir @param {number} depth */
+              const walk = (dir, depth) => {
+                if (depth > 3) return;
+                const entries = fs.readdirSync(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                  if (entry.name.startsWith('.')) continue;
+                  const full = path.join(dir, entry.name);
+                  const indent = '  '.repeat(depth);
+                  if (entry.isDirectory()) {
+                    result += `${indent}${entry.name}/\n`;
+                    walk(full, depth + 1);
+                  } else {
+                    result += `${indent}${entry.name}\n`;
+                  }
+                }
+              };
+              walk(srcDir, 0);
+            }
+          } catch {
+            /* ignore read errors */
+          }
+
+          // Focus path
+          if (args.focus) {
+            const worktreeRoot = path.resolve(worktree);
+            const focusPath = path.resolve(worktree, args.focus);
+            const lexicalInside =
+              focusPath.startsWith(worktreeRoot + path.sep) || focusPath === worktreeRoot;
+            if (!lexicalInside) {
+              result += `\n## Focus: ${args.focus}\n(path outside project directory)\n`;
+            } else if (isSensitiveFocusPath(focusPath, worktreeRoot)) {
+              result += `\n## Focus: ${args.focus}\n(access denied: sensitive path)\n`;
+            } else {
+              let realRoot = worktreeRoot;
+              let realFocus = focusPath;
+              try {
+                realRoot = fs.realpathSync(worktreeRoot);
+                realFocus = fs.realpathSync(focusPath);
+              } catch {
+                /* fall back to lexical paths */
+              }
+              const inside =
+                (realFocus.startsWith(realRoot + path.sep) || realFocus === realRoot) &&
+                (focusPath.startsWith(worktreeRoot + path.sep) || focusPath === worktreeRoot);
+              if (!inside) {
+                result += `\n## Focus: ${args.focus}\n(path outside project directory)\n`;
+              } else if (isSensitiveFocusPath(realFocus, realRoot)) {
+                result += `\n## Focus: ${args.focus}\n(access denied: sensitive path)\n`;
+              } else if (fs.existsSync(focusPath)) {
+                const stat = fs.statSync(focusPath);
+                if (stat.isDirectory()) {
+                  const items = fs.readdirSync(focusPath);
+                  result += items.join('\n') + '\n';
+                } else {
+                  try {
+                    const content = redactSecrets(
+                      fs.readFileSync(focusPath, 'utf8').slice(0, 3000),
+                    );
+                    result += '```\n' + content + '\n```\n';
+                  } catch {
+                    result += '(path not found)\n';
+                  }
+                }
+              } else {
+                result += '(path not found)\n';
+              }
+            }
+          }
+
+          return toContent({ structure: result, summary: `Explored ${args.query}` });
+        },
+      });
+
+      draft.add({
+        name: 'changed-files',
+        description:
+          'View files changed by subagent dispatches in this session. Returns navigable tree of what each subagent touched.',
+        input: TOOL_INPUTS['changed-files'],
+        async execute(/** @type {any} */ args, toolContext) {
+          const filters = args || {};
+          const rootSessionId = resolveRootSessionId(toolContext?.sessionID || '');
+          const entries = [];
+          for (const [sid, data] of sessionFileChanges) {
+            if (data.root !== rootSessionId) continue;
+            if (filters.session_id && sid !== filters.session_id) continue;
+            if (filters.task_id && data.taskId !== filters.task_id) continue;
+            entries.push({ session_id: sid, ...data });
+          }
+          return toContent({
+            entries,
+            total: entries.length,
+            unverified: entries.filter((e) => !e.verified).length,
+          });
+        },
+      });
+
+      draft.add({
+        name: 'verify',
+        description:
+          'Compare implementation against requirements. Returns structured pass/fail per requirement, flags extras (YAGNI). Includes evidence gate: reports unverified file changes. Use after execution to check if work meets the plan.',
+        input: TOOL_INPUTS.verify,
+        async execute(/** @type {any} */ args, toolContext) {
+          const callerSession =
+            typeof toolContext?.sessionID === 'string' ? toolContext.sessionID : '';
+          const callerRoot = resolveRootSessionId(callerSession);
+          if (!args || args.requirements == null || args.implementation_context == null) {
+            const callerEvidence = evidenceForRoot(callerRoot);
+            return toContent({
+              compliant: false,
+              requirements_met: [],
+              requirements_unmet: [],
+              extras_built: [],
+              evidence_gate: {
+                unverified_changes: callerEvidence.filter((entry) => !entry.verified).length,
+                freshness: evidenceFreshness(callerEvidence),
+              },
+              summary:
+                'Missing required arguments: provide "requirements" and "implementation_context"',
+            });
+          }
+
+          /** @param {string} s */
+          const getKeyBigrams = (s) => {
+            const words = s
+              .toLowerCase()
+              .split(/\s+/)
+              .filter((w) => w.length > 3);
+            const bigrams = /** @type {string[]} */ ([]);
+            for (let i = 0; i < words.length - 1; i++) {
+              bigrams.push(words[i] + ' ' + words[i + 1]);
+            }
+            return bigrams;
+          };
+
+          /** @param {string} s */
+          const getKeyUnigrams = (s) =>
+            s
+              .toLowerCase()
+              .split(/\s+/)
+              .filter((w) => w.length > 3);
+
+          /** @param {string} s */
+          const stripCheckbox = (s) =>
+            s
+              .replace(/^[-*]\s*\[\s*[x ]?\s*\]\s*/i, '')
+              .replace(/^[-*\d+.]\s+/, '')
+              .trim();
+
+          // Support checklist format: category headers with - [x] items
+          const reqs = args.requirements
+            .split('\n')
+            .map((r) => stripCheckbox(r))
+            .filter(
+              (r) => r.length > 2 && !r.startsWith('#') && !r.startsWith('```') && !r.endsWith(':'),
+            );
+
+          const impl = args.implementation_context.toLowerCase();
+
+          const met = [];
+          const unmet = [];
+
+          for (const req of reqs) {
+            const reqBigrams = getKeyBigrams(req);
+            const reqUnigrams = getKeyUnigrams(req);
+            let found;
+            if (reqBigrams.length > 0) {
+              found = reqBigrams.some((b) => impl.includes(b));
+            } else {
+              found = reqUnigrams.some((w) => impl.includes(w));
+            }
+            if (found) {
+              met.push(req);
+            } else {
+              unmet.push(req);
+            }
+          }
+
+          const implLines = args.implementation_context
+            .split('\n')
+            .map((l) => stripCheckbox(l))
+            .filter((l) => l.length > 3 && !l.startsWith('#') && !l.startsWith('```'));
+
+          const extras = implLines.filter((line) => {
+            const lineLower = line.toLowerCase();
+            return !reqs.some((req) => {
+              const reqBigrams = getKeyBigrams(req);
+              const reqUnigrams = getKeyUnigrams(req);
+              if (reqBigrams.length > 0) {
+                return reqBigrams.some((b) => lineLower.includes(b));
+              }
+              return reqUnigrams.some((w) => lineLower.includes(w));
+            });
+          });
+
+          // Mark evidence as verified only for the caller's own lineage
+          let verificationNote = null;
+          if (args.session_id) {
+            if (callerSession && resolveRootSessionId(args.session_id) === callerRoot) {
+              markEvidenceVerified(args.session_id, callerRoot);
+            } else {
+              verificationNote =
+                'session_id does not match the calling session; evidence was not marked verified';
+            }
+          }
+
+          const callerEvidence = evidenceForRoot(callerRoot);
+          const unverifiedCount = callerEvidence.filter((entry) => !entry.verified).length;
+          const freshness = evidenceFreshness(callerEvidence);
+
+          // Assess confidence: low when many unmet with sparse context
+          const implWords = args.implementation_context.split(/\s+/).length;
+          const lowConfidence = unmet.length > 0 && implWords < 20;
+
+          const warningParts = [];
+          if (unverifiedCount > 0) {
+            warningParts.push(
+              `${unverifiedCount} file change(s) not followed by verification command`,
+            );
+          }
+          if (freshness.stale > 0) {
+            warningParts.push(
+              `${freshness.stale} verified change(s) went stale (evidence no longer matches files on disk)`,
+            );
+          }
+
+          return toContent({
+            compliant: unmet.length === 0 && unverifiedCount === 0 && freshness.stale === 0,
+            requirements_met: met,
+            requirements_unmet: unmet,
+            extras_built: extras,
+            verification_note: verificationNote,
+            evidence_gate: {
+              unverified_changes: unverifiedCount,
+              total_changes: callerEvidence.length,
+              freshness,
+              warning: warningParts.length > 0 ? warningParts.join('; ') : null,
+            },
+            confidence_assessment: lowConfidence
+              ? 'low — sparse implementation context may hide unverified requirements'
+              : 'adequate',
+            recommend_delegation:
+              unmet.length > 0
+                ? 'Consider delegating each unmet requirement to a subagent for detailed verification'
+                : null,
+            summary: `${met.length}/${reqs.length} requirements met, ${extras.length} extras flagged, ${unverifiedCount} unverified changes`,
+          });
+        },
+      });
+    });
+
+    if (toolRegistration) registrations.push(toolRegistration);
+
+    if (typeof ctx.shell?.hook === 'function') {
+      try {
+        const shellRegistration = await ctx.shell.hook('create.before', guardShellCreate);
+        if (shellRegistration) registrations.push(shellRegistration);
+      } catch {
+        /* guardrail must never prevent the plugin from loading */
+      }
+    }
+
+    if (typeof ctx.skill?.transform === 'function') {
+      const skillRegistration = await ctx.skill.transform((draft) => {
+        const existingIds = new Set(
+          typeof draft.list === 'function'
+            ? draft.list().map((skill) => String(skill.id || skill.name))
+            : [],
+        );
+        for (const skill of readPackageSkills()) {
+          if (!existingIds.has(skill.id)) draft.add(/** @type {any} */ (skill));
+        }
+      });
+      if (skillRegistration) registrations.push(skillRegistration);
+    }
+
+    if (typeof ctx.command?.transform === 'function') {
+      const commandRegistration = await ctx.command.transform((draft) => {
+        for (const command of readPackageCommands()) {
+          draft.add({
+            name: `regent/${command.name}`,
+            description: command.description,
+            execute: async ({ sessionID, prompt, delivery }) => {
+              const invocationPrompt = prompt && typeof prompt === 'object' ? prompt : { text: '' };
+              const argumentsText =
+                typeof invocationPrompt.text === 'string' ? invocationPrompt.text : '';
+              const text = command.template.includes('$ARGUMENTS')
+                ? command.template.replaceAll('$ARGUMENTS', () => argumentsText)
+                : argumentsText.trim()
+                  ? `${command.template}\n\n${argumentsText}`
+                  : command.template;
+              const sessionApi = /** @type {any} */ (ctx.session);
+              await sessionApi.prompt({
+                ...invocationPrompt,
+                sessionID,
+                text,
+                delivery,
+              });
+            },
+          });
+        }
+      });
+      if (commandRegistration) registrations.push(commandRegistration);
+    }
+
+    const contextRegistration = await ctx.session.hook('context', async (event) => {
+      const sessionId = typeof event?.sessionID === 'string' ? event.sessionID : '';
+      let isWorkerSession = pluginWorkerSessionIds.has(sessionId);
+      if (!isWorkerSession && sessionId && typeof ctx.session?.get === 'function') {
+        try {
+          const sessionInfo = unwrapData(await ctx.session.get({ sessionID: sessionId }));
+          const pluginManagedSession =
+            pluginWorkerSessionIds.has(sessionInfo?.id) ||
+            pluginWorkerSessionIds.has(sessionInfo?.parentID);
+          isWorkerSession = Boolean(sessionInfo?.parentID) || pluginManagedSession;
+          if (pluginManagedSession && sessionInfo?.id) {
+            pluginWorkerSessionIds.add(sessionInfo.id);
+            if (sessionInfo.parentID) {
+              trackSessionLineage(sessionInfo.id, resolveRootSessionId(sessionInfo.parentID));
+            }
+          }
+        } catch {
+          /* test doubles and unavailable session metadata are non-fatal */
+        }
+      }
+
+      if (isWorkerSession) {
+        if (event?.tools && typeof event.tools === 'object') {
+          for (const name of ['delegate', 'delegate_many', 'research']) {
+            delete event.tools[name];
+          }
+        }
+        return;
+      }
+
+      if (!Array.isArray(event.system)) event.system = [];
+      const bootstrap = getBootstrap();
+      const hasBootstrap = event.system.some(
+        (part) => part.type === 'text' && part.text.includes('EXTREMELY_IMPORTANT'),
+      );
+      const additions = [];
+      const rootSessionId = resolveRootSessionId(sessionId);
+
+      if (bootstrap && !hasBootstrap) additions.push(bootstrap);
+
+      const unverified = evidenceLog.filter(
+        (entry) => !entry.verified && entry.rootSessionId === rootSessionId,
+      );
+      if (unverified.length > 0) {
+        additions.push(`## Regent Evidence Log (unverified)\n${JSON.stringify(unverified)}\n`);
+      }
+
+      const activeChanges = [...sessionFileChanges.entries()]
+        .filter(([_, data]) => !data.verified && data.root === rootSessionId)
+        .map(([sessionId, data]) => `${sessionId}: ${data.files.join(', ')}`);
+      if (activeChanges.length > 0) {
+        additions.push(`## Regent Active File Changes\n${activeChanges.join('\n')}\n`);
+      }
+
+      if (additions.length > 0) {
+        event.system.push({ type: 'text', text: additions.join('\n') });
+      }
+    });
+
+    if (contextRegistration) registrations.push(contextRegistration);
+
+    return async () => {
+      try {
+        await Promise.all(
+          registrations
+            .filter((registration) => typeof registration?.dispose === 'function')
+            .map((registration) => registration.dispose()),
+        );
+      } finally {
+        resetState();
+      }
+    };
+  },
+});