auditor-lambda 0.3.19 → 0.3.20

package/README.md

@@ -30,8 +30,9 @@ npm install -g auditor-lambda
 
 That makes `audit-code` available on `PATH`. During package install, the package
 also writes user-level command/skill assets for hosts we can seed safely, including
-the Claude command file, the global Codex skill bundle, and the global OpenCode
-slash command entry in `~/.config/opencode/opencode.json`.
+the Claude command file, the global Codex skill bundle with `audit-code` display
+metadata, and the global OpenCode slash command entry in
+`~/.config/opencode/opencode.json`.
 
 After that, invoke `/audit-code` in a supported host. The prompt self-bootstraps
 the current repository by running:

package/audit-code-wrapper-lib.mjs

@@ -533,8 +533,59 @@ function renderCodexAutomationRecipe() {
   ].join('\n');
 }
 
+const OPENCODE_AUDIT_EDIT_PERMISSION = {
+  '*': 'ask',
+  '.audit-code/**': 'allow',
+  '.audit-artifacts/**': 'allow',
+  'audit-report.md': 'allow',
+};
+
+const OPENCODE_AUDIT_BASH_PERMISSION = {
+  '*': 'ask',
+  'audit-code run-to-completion*': 'deny',
+  'audit-code synthesize*': 'deny',
+  'audit-code cleanup*': 'deny',
+  'audit-code requeue*': 'deny',
+  'audit-code ingest-results*': 'deny',
+  '*audit-code.mjs* run-to-completion*': 'deny',
+  '*audit-code.mjs* synthesize*': 'deny',
+  '*audit-code.mjs* cleanup*': 'deny',
+  '*audit-code.mjs* requeue*': 'deny',
+  '*audit-code.mjs* ingest-results*': 'deny',
+  'audit-code': 'allow',
+  'audit-code ensure*': 'allow',
+  'audit-code prepare-dispatch*': 'allow',
+  'audit-code submit-packet*': 'allow',
+  'audit-code merge-and-ingest*': 'allow',
+  'audit-code validate*': 'allow',
+  '*audit-code.mjs': 'allow',
+  '*audit-code.mjs* ensure*': 'allow',
+  '*audit-code.mjs* prepare-dispatch*': 'allow',
+  '*audit-code.mjs* submit-packet*': 'allow',
+  '*audit-code.mjs* merge-and-ingest*': 'allow',
+  '*audit-code.mjs* worker-run*': 'allow',
+  '*audit-code.mjs* validate*': 'allow',
+  'node* .audit-code/install/run-mcp-server.mjs*': 'allow',
+  'node* ./.audit-code/install/run-mcp-server.mjs*': 'allow',
+  'git status*': 'allow',
+  'git diff*': 'allow',
+  'grep *': 'allow',
+  'rm *': 'deny',
+};
+
+function renderOpenCodePermissionConfig() {
+  return {
+    read: 'allow',
+    glob: 'allow',
+    grep: 'allow',
+    edit: { ...OPENCODE_AUDIT_EDIT_PERMISSION },
+    bash: { ...OPENCODE_AUDIT_BASH_PERMISSION },
+  };
+}
+
 function renderOpenCodeProjectConfig(root, promptBody) {
   const launcher = replaceBackslashes(toRepoRelativePath(root, join(root, '.audit-code', 'install', MCP_LAUNCHER_FILENAME)));
+  const auditPermission = renderOpenCodePermissionConfig();
   return {
     $schema: 'https://opencode.ai/config.json',
     command: {
@@ -553,19 +604,7 @@ function renderOpenCodeProjectConfig(root, promptBody) {
         timeout: 10000,
       },
     },
-    permission: {
-      read: 'allow',
-      glob: 'allow',
-      grep: 'allow',
-      edit: 'ask',
-      bash: {
-        '*': 'ask',
-        'git status*': 'allow',
-        'git diff*': 'allow',
-        'grep *': 'allow',
-        'rm *': 'deny',
-      },
-    },
+    permission: auditPermission,
     agent: {
       auditor: {
         description:
@@ -574,14 +613,8 @@ function renderOpenCodeProjectConfig(root, promptBody) {
           'auditor*': true,
         },
         permission: {
-          edit: 'ask',
-          bash: {
-            '*': 'ask',
-            'git status*': 'allow',
-            'git diff*': 'allow',
-            'grep *': 'allow',
-            'rm *': 'deny',
-          },
+          edit: { ...OPENCODE_AUDIT_EDIT_PERMISSION },
+          bash: { ...OPENCODE_AUDIT_BASH_PERMISSION },
           question: 'allow',
         },
       },
@@ -607,6 +640,99 @@ function objectValue(value) {
     : {};
 }
 
+function mergeOpenCodePermissionRule(existingRule, generatedRule, managedRules = {}) {
+  if (generatedRule && typeof generatedRule === 'object' && !Array.isArray(generatedRule)) {
+    const generatedObject = generatedRule;
+    const merged = {};
+    const existingObject =
+      existingRule && typeof existingRule === 'object' && !Array.isArray(existingRule)
+        ? existingRule
+        : {};
+
+    if (typeof existingRule === 'string') {
+      merged['*'] = existingRule;
+    } else {
+      merged['*'] = existingObject['*'] ?? generatedObject['*'] ?? 'ask';
+    }
+
+    for (const [key, value] of Object.entries(generatedObject)) {
+      if (key !== '*') merged[key] = value;
+    }
+    for (const [key, value] of Object.entries(existingObject)) {
+      if (key !== '*') merged[key] = value;
+    }
+    for (const [key, value] of Object.entries(managedRules)) {
+      merged[key] = value;
+    }
+
+    return merged;
+  }
+
+  return existingRule ?? generatedRule;
+}
+
+function mergeOpenCodePermissionConfig(existingPermission, generatedPermission) {
+  if (!existingPermission || typeof existingPermission !== 'object' || Array.isArray(existingPermission)) {
+    return generatedPermission;
+  }
+
+  return {
+    ...generatedPermission,
+    ...existingPermission,
+    edit: mergeOpenCodePermissionRule(
+      existingPermission.edit,
+      generatedPermission.edit,
+      OPENCODE_AUDIT_EDIT_PERMISSION,
+    ),
+    bash: mergeOpenCodePermissionRule(
+      existingPermission.bash,
+      generatedPermission.bash,
+      OPENCODE_AUDIT_BASH_PERMISSION,
+    ),
+  };
+}
+
+function assertOpenCodeAuditPermissionConfig(permissionConfig, label) {
+  const edit = permissionConfig?.edit;
+  const bash = permissionConfig?.bash;
+  if (!edit || typeof edit !== 'object' || Array.isArray(edit)) {
+    throw new Error(`OpenCode ${label}.edit must allow audit-owned file paths. Run "audit-code install --host opencode".`);
+  }
+  for (const pattern of ['.audit-code/**', '.audit-artifacts/**', 'audit-report.md']) {
+    if (edit[pattern] !== 'allow') {
+      throw new Error(`OpenCode ${label}.edit must allow ${pattern}. Run "audit-code install --host opencode".`);
+    }
+  }
+  if (!bash || typeof bash !== 'object' || Array.isArray(bash)) {
+    throw new Error(`OpenCode ${label}.bash must allow audit-code commands. Run "audit-code install --host opencode".`);
+  }
+  for (const pattern of [
+    'audit-code',
+    'audit-code ensure*',
+    'audit-code prepare-dispatch*',
+    'audit-code submit-packet*',
+    'audit-code merge-and-ingest*',
+    '*audit-code.mjs',
+    '*audit-code.mjs* submit-packet*',
+    '*audit-code.mjs* merge-and-ingest*',
+    'node* .audit-code/install/run-mcp-server.mjs*',
+  ]) {
+    if (bash[pattern] !== 'allow') {
+      throw new Error(`OpenCode ${label}.bash must allow ${pattern}. Run "audit-code install --host opencode".`);
+    }
+  }
+  for (const pattern of [
+    'audit-code run-to-completion*',
+    'audit-code synthesize*',
+    '*audit-code.mjs* run-to-completion*',
+    '*audit-code.mjs* synthesize*',
+  ]) {
+    if (bash[pattern] !== 'deny') {
+      throw new Error(`OpenCode ${label}.bash must deny ${pattern}. Run "audit-code install --host opencode".`);
+    }
+  }
+}
+
 function buildMergedOpenCodeProjectConfig(existing, root, promptBody) {
   const generated = renderOpenCodeProjectConfig(root, promptBody);
   return {
@@ -620,13 +746,17 @@ function buildMergedOpenCodeProjectConfig(existing, root, promptBody) {
       ...objectValue(existing.mcp),
       auditor: generated.mcp.auditor,
     },
-    permission:
-      existing.permission && typeof existing.permission === 'object' && !Array.isArray(existing.permission)
-        ? existing.permission
-        : generated.permission,
+    permission: mergeOpenCodePermissionConfig(existing.permission, generated.permission),
     agent: {
       ...objectValue(existing.agent),
-      auditor: generated.agent.auditor,
+      auditor: {
+        ...objectValue(objectValue(existing.agent).auditor),
+        ...generated.agent.auditor,
+        permission: mergeOpenCodePermissionConfig(
+          objectValue(objectValue(existing.agent).auditor).permission,
+          generated.agent.auditor.permission,
+        ),
+      },
     },
   };
 }
@@ -1822,8 +1952,10 @@ async function verifyInstalledBootstrap(argv) {
           if (commandConfig.template !== sourceBody.trimStart()) {
             throw new Error('OpenCode config command["audit-code"].template is out of sync with the source prompt. Run "audit-code install".');
           }
+          assertOpenCodeAuditPermissionConfig(config?.permission, 'permission');
+          assertOpenCodeAuditPermissionConfig(config?.agent?.auditor?.permission, 'agent.auditor.permission');
           return {
-            summary: 'OpenCode project config has MCP server and /audit-code slash command.',
+            summary: 'OpenCode project config has MCP server, /audit-code slash command, and audit permissions.',
             path: assetPaths.opencodeConfigPath,
           };
         });
@@ -2001,6 +2133,12 @@ async function detectBootstrapRefreshReason(root, host) {
         if (opencodeConfig?.command?.['audit-code']?.template !== sourcePromptBody.trimStart()) {
           return 'stale_host_asset:opencode:config_command';
         }
+        try {
+          assertOpenCodeAuditPermissionConfig(opencodeConfig?.permission, 'permission');
+          assertOpenCodeAuditPermissionConfig(opencodeConfig?.agent?.auditor?.permission, 'agent.auditor.permission');
+        } catch {
+          return 'stale_host_asset:opencode:permissions';
+        }
         if (await fileExists(join(root, '.opencode', 'commands', 'audit-code.md'))) {
           return 'stale_host_asset:opencode:legacy_command_file';
         }

package/dist/cli.js

@@ -218,8 +218,8 @@ async function emitEnvelope(params) {
 }
 function buildManualReviewBlocker(providerName) {
     return providerName === LOCAL_SUBPROCESS_PROVIDER_NAME
-        ? "Ready for LLM review. Dispatched task files are in .audit-artifacts/dispatch/. " +
-            "Review the code, write audit results to the specified path, then run the worker_command to continue."
+        ? "Ready for LLM semantic review. If the host exposes a callable subagent tool, prepare dispatch and fan out packets. " +
+            "If not, use single-task fallback: review only the first pending task, write one AuditResult to the run audit-results path, execute worker_command, then stop."
         : "Audit blocked: waiting for manual audit results or interactive provider configuration.";
 }
 function shouldRunInlineExecutor(selectedExecutor) {

package/dist/io/runArtifacts.js

@@ -10,6 +10,8 @@ const findingSchemaPath = join(packageRoot, "schemas", "finding.schema.json");
 const CURRENT_TASK_FILENAME = "current-task.json";
 const CURRENT_PROMPT_FILENAME = "current-prompt.md";
 const CURRENT_TASKS_FILENAME = "current-tasks.json";
+const CURRENT_SINGLE_TASK_FILENAME = "current-single-task.json";
+const CURRENT_SINGLE_TASK_PROMPT_FILENAME = "current-single-task-prompt.md";
 const CURRENT_SCHEMA_FILENAME = "audit-result.schema.json";
 const CURRENT_RESULTS_SCHEMA_FILENAME = "audit-results.schema.json";
 const CURRENT_FINDING_SCHEMA_FILENAME = "finding.schema.json";
@@ -63,6 +65,49 @@ async function writeDispatchSchemaFiles(artifactsDir) {
     await writeFile(join(dispatchDir, CURRENT_RESULTS_SCHEMA_FILENAME), await readFile(auditResultsSchemaPath, "utf8"), "utf8");
     await writeFile(join(dispatchDir, CURRENT_FINDING_SCHEMA_FILENAME), await readFile(findingSchemaPath, "utf8"), "utf8");
 }
+function renderSingleTaskFallbackPrompt(task, auditTask) {
+    const commandArgv = JSON.stringify(task.worker_command);
+    const lineCounts = auditTask.file_paths
+        .map((path) => `- ${path}: ${auditTask.file_line_counts?.[path] ?? 0} lines`)
+        .join("\n");
+    return [
+        "# audit-code single-task fallback",
+        "",
+        "Use this file only when the conversation host cannot dispatch subagents.",
+        "This prompt is generated deterministically from the first pending task.",
+        "",
+        `run_id: ${task.run_id}`,
+        `task_id: ${auditTask.task_id}`,
+        `unit_id: ${auditTask.unit_id}`,
+        `pass_id: ${auditTask.pass_id}`,
+        `lens: ${auditTask.lens}`,
+        `rationale: ${auditTask.rationale}`,
+        "",
+        "Assigned files and line counts:",
+        lineCounts,
+        "",
+        "Instructions:",
+        "1. Read only the assigned files above.",
+        "2. Produce exactly one AuditResult object for task_id above, wrapped in a JSON array.",
+        "3. Write that JSON array to audit_results_path.",
+        "4. Run worker_command exactly, then stop without checking audit state or reading a report.",
+        "",
+        `audit_results_path: ${task.audit_results_path}`,
+        `worker_command: ${commandArgv}`,
+        "",
+    ].join("\n");
+}
+async function writeSingleTaskFallbackFiles(artifactsDir, task, currentTasks) {
+    if (task.preferred_executor !== "agent" ||
+        !task.audit_results_path ||
+        !currentTasks ||
+        currentTasks.length === 0) {
+        return;
+    }
+    const firstTask = currentTasks[0];
+    await writeJsonFile(join(artifactsDir, "dispatch", CURRENT_SINGLE_TASK_FILENAME), firstTask);
+    await writeFile(join(artifactsDir, "dispatch", CURRENT_SINGLE_TASK_PROMPT_FILENAME), renderSingleTaskFallbackPrompt(task, firstTask), "utf8");
+}
 export async function writeWorkerTaskFiles(task, prompt, paths, artifactsDir, currentTasks, options = {}) {
     await mkdir(paths.runDir, { recursive: true });
     await writeJsonFile(paths.taskPath, task);
@@ -78,6 +123,7 @@ export async function writeWorkerTaskFiles(task, prompt, paths, artifactsDir, cu
     await writeJsonFile(join(artifactsDir, "dispatch", CURRENT_TASK_FILENAME), task);
     await writeFile(join(artifactsDir, "dispatch", CURRENT_PROMPT_FILENAME), prompt, "utf8");
     await writeJsonFile(join(artifactsDir, "dispatch", CURRENT_TASKS_FILENAME), currentTasks ?? []);
+    await writeSingleTaskFallbackFiles(artifactsDir, task, currentTasks);
     await writeDispatchSchemaFiles(artifactsDir);
 }
 export async function writeDispatchBatchFiles(artifactsDir, runs, currentTasks) {
@@ -121,6 +167,8 @@ export async function clearDispatchFiles(artifactsDir) {
         CURRENT_TASK_FILENAME,
         CURRENT_PROMPT_FILENAME,
         CURRENT_TASKS_FILENAME,
+        CURRENT_SINGLE_TASK_FILENAME,
+        CURRENT_SINGLE_TASK_PROMPT_FILENAME,
         CURRENT_SCHEMA_FILENAME,
         CURRENT_RESULTS_SCHEMA_FILENAME,
         CURRENT_FINDING_SCHEMA_FILENAME,

package/dist/supervisor/operatorHandoff.js

@@ -11,6 +11,8 @@ const RUN_LEDGER_FILENAME = "run-ledger.json";
 const CURRENT_TASK_FILENAME = "current-task.json";
 const CURRENT_PROMPT_FILENAME = "current-prompt.md";
 const CURRENT_TASKS_FILENAME = "current-tasks.json";
+const CURRENT_SINGLE_TASK_FILENAME = "current-single-task.json";
+const CURRENT_SINGLE_TASK_PROMPT_FILENAME = "current-single-task-prompt.md";
 const AUDIT_TASKS_FILENAME = "audit_tasks.json";
 const RUNTIME_VALIDATION_TASKS_FILENAME = "runtime_validation_tasks.json";
 const BLOCKED_STATUS = "blocked";
@@ -121,7 +123,7 @@ function buildInteractiveProviderHint(status, providerName, sessionConfigPath, i
         return `Configuration error: Verify --root points to the intended repository root and that the tree contains auditable files.`;
     }
     const providerLabel = providerName ?? LOCAL_SUBPROCESS_PROVIDER_NAME;
-    return `Provider: ${providerLabel}. For automatic LLM review, configure an interactive provider in ${sessionConfigPath}.`;
+    return `Provider: ${providerLabel}. This is a deterministic semantic-review handoff, not a failed audit. Use host subagents when the active toolset provides them; otherwise use the single-task fallback and stop after the worker command. For automatic LLM review, configure an interactive provider in ${sessionConfigPath}; that is only needed for backend-launched review.`;
 }
 function renderMarkdown(handoff) {
     const lines = [
@@ -167,6 +169,9 @@ function renderMarkdown(handoff) {
         for (const command of handoff.suggested_commands) {
             lines.push(`- ${command}`);
         }
+        if (handoff.active_review_run) {
+            lines.push("- Use packet dispatch commands only when the conversation host exposes a callable subagent tool; otherwise follow the single-task fallback.");
+        }
     }
     if (handoff.active_review_run) {
         lines.push("", "Active review run:");
@@ -237,6 +242,8 @@ export function buildAuditCodeHandoff(params) {
         handoff.file_map = {
             current_task: artifactPaths.current_task,
             current_prompt: artifactPaths.current_prompt,
+            single_task: join(params.artifactsDir, "dispatch", CURRENT_SINGLE_TASK_FILENAME),
+            single_task_prompt: join(params.artifactsDir, "dispatch", CURRENT_SINGLE_TASK_PROMPT_FILENAME),
             dispatch_plan: join(params.artifactsDir, "runs", params.activeReviewRun.run_id, "dispatch-plan.json"),
             audit_results: params.activeReviewRun.audit_results_path,
             final_report: join(params.root, "audit-report.md"),

package/docs/operator-guide.md

@@ -57,7 +57,9 @@ ChatGPT-style project conversations are the intended product surface. Use
 default context.
 
 Codex should normally use the global skill seeded by the npm install plus
-repo-local `AGENTS.md` fallback guidance.
+repo-local `AGENTS.md` fallback guidance. The installed skill includes
+`agents/openai.yaml` metadata so Codex can keep the slash-list display aligned
+with the canonical `/audit-code` spelling.
 
 Claude Desktop is treated as an MCP-first host. Use the generated project
 template and local bundle artifacts when installing the integration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.3.19",
+  "version": "0.3.20",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",

package/scripts/postinstall.mjs

@@ -7,6 +7,7 @@ import { fileURLToPath } from 'url';
 const pkgRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const promptSourceFile = join(pkgRoot, 'skills', 'audit-code', 'audit-code.prompt.md');
 const skillSourceFile = join(pkgRoot, 'skills', 'audit-code', 'SKILL.md');
+const codexOpenAiAgentSourceFile = join(pkgRoot, 'skills', 'audit-code', 'agents', 'openai.yaml');
 
 function readRequiredSource(path, label) {
   if (!existsSync(path)) {
@@ -18,6 +19,15 @@ function readRequiredSource(path, label) {
   return readFileSync(path);
 }
 
+function readOptionalSource(path, label) {
+  if (!existsSync(path)) {
+    console.warn(`audit-code: ${label} source not found at ${path} - skipping optional install`);
+    return null;
+  }
+
+  return readFileSync(path);
+}
+
 function writeGeneratedFile(path, content) {
   const action = existsSync(path) ? 'updated' : 'installed';
   mkdirSync(dirname(path), { recursive: true });
@@ -32,8 +42,118 @@ function splitFrontmatter(text) {
   return { body: normalized.slice(match[0].length) };
 }
 
+const OPENCODE_AUDIT_EDIT_PERMISSION = {
+  '*': 'ask',
+  '.audit-code/**': 'allow',
+  '.audit-artifacts/**': 'allow',
+  'audit-report.md': 'allow',
+};
+
+const OPENCODE_AUDIT_BASH_PERMISSION = {
+  '*': 'ask',
+  'audit-code run-to-completion*': 'deny',
+  'audit-code synthesize*': 'deny',
+  'audit-code cleanup*': 'deny',
+  'audit-code requeue*': 'deny',
+  'audit-code ingest-results*': 'deny',
+  '*audit-code.mjs* run-to-completion*': 'deny',
+  '*audit-code.mjs* synthesize*': 'deny',
+  '*audit-code.mjs* cleanup*': 'deny',
+  '*audit-code.mjs* requeue*': 'deny',
+  '*audit-code.mjs* ingest-results*': 'deny',
+  'audit-code': 'allow',
+  'audit-code ensure*': 'allow',
+  'audit-code prepare-dispatch*': 'allow',
+  'audit-code submit-packet*': 'allow',
+  'audit-code merge-and-ingest*': 'allow',
+  'audit-code validate*': 'allow',
+  '*audit-code.mjs': 'allow',
+  '*audit-code.mjs* ensure*': 'allow',
+  '*audit-code.mjs* prepare-dispatch*': 'allow',
+  '*audit-code.mjs* submit-packet*': 'allow',
+  '*audit-code.mjs* merge-and-ingest*': 'allow',
+  '*audit-code.mjs* worker-run*': 'allow',
+  '*audit-code.mjs* validate*': 'allow',
+  'node* .audit-code/install/run-mcp-server.mjs*': 'allow',
+  'node* ./.audit-code/install/run-mcp-server.mjs*': 'allow',
+  'git status*': 'allow',
+  'git diff*': 'allow',
+  'grep *': 'allow',
+  'rm *': 'deny',
+};
+
+function objectValue(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+}
+
+function mergeOpenCodePermissionRule(existingRule, generatedRule, managedRules = {}) {
+  if (generatedRule && typeof generatedRule === 'object' && !Array.isArray(generatedRule)) {
+    const generatedObject = generatedRule;
+    const merged = {};
+    const existingObject =
+      existingRule && typeof existingRule === 'object' && !Array.isArray(existingRule)
+        ? existingRule
+        : {};
+
+    if (typeof existingRule === 'string') {
+      merged['*'] = existingRule;
+    } else {
+      merged['*'] = existingObject['*'] ?? generatedObject['*'] ?? 'ask';
+    }
+
+    for (const [key, value] of Object.entries(generatedObject)) {
+      if (key !== '*') merged[key] = value;
+    }
+    for (const [key, value] of Object.entries(existingObject)) {
+      if (key !== '*') merged[key] = value;
+    }
+    for (const [key, value] of Object.entries(managedRules)) {
+      merged[key] = value;
+    }
+
+    return merged;
+  }
+
+  return existingRule ?? generatedRule;
+}
+
+function mergeOpenCodePermissionConfig(existingPermission, generatedPermission) {
+  if (!existingPermission || typeof existingPermission !== 'object' || Array.isArray(existingPermission)) {
+    return generatedPermission;
+  }
+
+  return {
+    ...generatedPermission,
+    ...existingPermission,
+    edit: mergeOpenCodePermissionRule(
+      existingPermission.edit,
+      generatedPermission.edit,
+      OPENCODE_AUDIT_EDIT_PERMISSION,
+    ),
+    bash: mergeOpenCodePermissionRule(
+      existingPermission.bash,
+      generatedPermission.bash,
+      OPENCODE_AUDIT_BASH_PERMISSION,
+    ),
+  };
+}
+
+function renderOpenCodePermissionConfig() {
+  return {
+    read: 'allow',
+    glob: 'allow',
+    grep: 'allow',
+    edit: { ...OPENCODE_AUDIT_EDIT_PERMISSION },
+    bash: { ...OPENCODE_AUDIT_BASH_PERMISSION },
+  };
+}
+
 function mergeOpenCodeGlobalConfig(existing, promptBody) {
   const parsed = existing ? JSON.parse(existing) : {};
+  const auditPermission = renderOpenCodePermissionConfig();
+  const existingAuditor = objectValue(objectValue(parsed.agent).auditor);
   return {
     ...parsed,
     command: {
@@ -47,12 +167,18 @@ function mergeOpenCodeGlobalConfig(existing, promptBody) {
         subtask: false,
       },
     },
+    permission: mergeOpenCodePermissionConfig(parsed.permission, auditPermission),
     agent: {
       ...(parsed.agent && typeof parsed.agent === 'object' && !Array.isArray(parsed.agent)
         ? parsed.agent
         : {}),
       auditor: {
+        ...existingAuditor,
         description: 'Read-heavy audit orchestration agent for the /audit-code workflow.',
+        permission: mergeOpenCodePermissionConfig(
+          existingAuditor.permission,
+          auditPermission,
+        ),
       },
     },
   };
@@ -75,23 +201,37 @@ if (!promptSource || !skillSource) {
 }
 
 const promptBody = splitFrontmatter(promptSource.toString('utf8')).body;
+const codexOpenAiAgentSource = readOptionalSource(codexOpenAiAgentSourceFile, 'Codex skill UI metadata');
 
 const installs = [
   {
     label: 'Claude command',
     path: join(homedir(), '.claude', 'commands', 'audit-code.md'),
+    sourcePath: promptSourceFile,
     content: promptSource,
   },
   {
     label: 'Codex skill',
     path: join(homedir(), '.codex', 'skills', 'audit-code', 'SKILL.md'),
+    sourcePath: skillSourceFile,
     content: skillSource,
   },
   {
     label: 'Codex prompt',
     path: join(homedir(), '.codex', 'skills', 'audit-code', 'audit-code.prompt.md'),
+    sourcePath: promptSourceFile,
     content: promptSource,
   },
+  ...(codexOpenAiAgentSource
+    ? [
+        {
+          label: 'Codex skill UI metadata',
+          path: join(homedir(), '.codex', 'skills', 'audit-code', 'agents', 'openai.yaml'),
+          sourcePath: codexOpenAiAgentSourceFile,
+          content: codexOpenAiAgentSource,
+        },
+      ]
+    : []),
 ];
 
 for (const install of installs) {
@@ -101,7 +241,7 @@ for (const install of installs) {
   } catch (err) {
     console.warn(`audit-code: could not install global ${install.label} (${err.message})`);
     console.warn(`  To install manually, copy from:`);
-    console.warn(`    ${install.label === 'Codex skill' ? skillSourceFile : promptSourceFile}`);
+    console.warn(`    ${install.sourcePath}`);
     console.warn(`  to:`);
     console.warn(`    ${install.path}`);
   }

package/skills/audit-code/SKILL.md

@@ -27,6 +27,11 @@ dispatch.
 If the host cannot delegate to subagents, the conversation orchestrator may
 complete exactly one assigned review task, ingest it through the provided backend
 command, then stop so the user can rerun `/audit-code` from fresh context.
+In that fallback path it should not prepare packet dispatch, probe alternate
+backend subcommands, synthesize reports, or choose a smaller task; the first
+pending task and the exact worker command are the boundary.
+The backend writes a deterministic single-task fallback prompt for that case so
+the orchestrator does not need to infer the first task from a broad batch prompt.
 
 Subagent fan-out belongs to the host agent runtime rather than to repo-local
 backend provider settings.

package/skills/audit-code/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "audit-code"
+  short_description: "Run the autonomous /audit-code repository audit workflow."
+  default_prompt: "Start /audit-code for this repository and continue until the audit completes or blocks for operator input."

package/skills/audit-code/audit-code.prompt.md

@@ -25,12 +25,21 @@ and ingest results mechanically.
   a backend command fails and the error explicitly requires diagnosis.
 - Do not inspect individual subagent result files after dispatch. Validation
   and ingestion are backend responsibilities.
+- Do not inspect the backend command catalog or try alternate subcommands to
+  bypass a blocked semantic-review handoff. In particular, do not run
+  `run-to-completion`, `synthesize`, `cleanup`, `requeue`, or direct
+  `ingest-results` while following this directive.
+- A report under `.audit-artifacts/` is not a completion signal while
+  `audit_state.status` is `"blocked"`. Present a report only after Step 5.
 - CRITICAL: Do not use your `Read` tool to read `entry.prompt_path` or JSON schemas into your own context window. The subagent will read them. Pass the path literally.
 - Prefer subagent dispatch for semantic review whenever the host exposes an
   Agent/subagent tool.
 - Treat the user's `/audit-code` request as explicit authorization to launch
   review subagents in parallel. Do not ask for a separate delegation request
   before using available Agent/subagent tools.
+- Decide subagent support from the active toolset, not from shell commands or
+  backend provider names. A shell command named `agent`, an MCP prompt, or a
+  `local-subprocess` provider is not a host subagent facility.
 - Do not use `browser_subagent` for semantic review of source code unless the
   task explicitly requires browser-based validation.
 - If the host cannot dispatch subagents, complete exactly one assigned review
@@ -86,7 +95,11 @@ If status is `"blocked"` for semantic review, continue to Step 2.
 
 ## Step 2 - Dispatch Review Work
 
-When the host supports subagents, prepare a dispatch plan by default:
+Use this step only when the active toolset exposes a callable host subagent
+facility such as `Agent`, `Task`, or an equivalent built-in delegation tool.
+Do not try to discover subagent support by running shell commands.
+
+When that callable subagent facility exists, prepare a dispatch plan by default:
 
 ```bash
 audit-code prepare-dispatch --run-id <run_id> --artifacts-dir <artifacts_dir>
@@ -132,21 +145,43 @@ error. Do not improvise manual merging or state edits.
 
 Loop back to Step 1.
 
+If no callable host subagent facility exists, or a delegation attempt fails
+because the host does not provide such a tool, go directly to Step 3. Do not run
+`prepare-dispatch`, do not inspect generated packet prompts, and do not try
+alternate backend commands.
+
 ## Step 3 - Single-Task Fallback
 
 Use this path only when the host cannot dispatch subagents.
 
-Read the current review prompt named by `handoff.active_review_run.prompt_path`
-or `.audit-artifacts/dispatch/current-prompt.md`, plus the matching task file
+Allowed backend command in this step: the exact `worker_command` from the task
+file, after you have written the single-task result. Do not run `audit-code`,
+`run-to-completion`, `prepare-dispatch`, `merge-and-ingest`, `synthesize`,
+`validate`, or any other backend command as a substitute for the fallback.
+
+Read the generated single-task fallback prompt at
+`handoff.file_map.single_task_prompt` when present, otherwise
+`.audit-artifacts/dispatch/current-single-task-prompt.md`. That file is
+deterministically narrowed to the first pending task. If it is unavailable, read
+the current review prompt named by `handoff.active_review_run.prompt_path` or
+`.audit-artifacts/dispatch/current-prompt.md`, plus the matching task file
 needed to find `audit_results_path` and `worker_command`.
 
 Complete exactly one assigned review task. If a batch file lists multiple tasks,
-choose the first pending task only. Read only that task's assigned files. Write
-one valid `AuditResult` object, wrapped in a JSON array, to `audit_results_path`.
+choose the first pending task by array order only; do not substitute a smaller
+or easier task. If that first task covers a large file, use targeted reads and
+searches within its assigned files instead of abandoning it. Read only that
+task's assigned files. Write one valid `AuditResult` object, wrapped in a JSON
+array, to `audit_results_path`.
+
+If the current review prompt says to produce results for every listed task, the
+single-task fallback overrides that wording for the top-level orchestrator:
+produce exactly one result for the first pending task only.
 
 Run the exact `worker_command` from the task file. Then stop and summarize that
 one bounded step. Do not loop into another semantic review task in the same
-conversation turn.
+conversation turn. Do not re-check audit state or read an audit report after the
+worker command.
 
 ## Step 4 - Backend Failure Handling