@lazyingart/agintiflow 0.20.175 → 0.20.176

package/README.md

@@ -54,7 +54,7 @@ Most agent tools are either a chat box with hidden state or an expensive one-mod
 | Disciplined by default | `AGINTI.md` starts with a behavior contract: surface ambiguity, keep edits surgical, avoid speculative complexity, verify outcomes, and respect permission blockers. |
 | Role-based models | Route, main, spare, wrapper, and auxiliary image roles are separate. You can use cheap route models, stronger main models, optional OpenAI/Qwen/Venice routes, and GRS AI/Venice image tools. |
 | Writing without agent noise | `writing_specialist` drafts novels, books, scripts, essays, and paper prose in an isolated writing-only context, then the main agent handles files, formatting, citations, checks, and artifacts. |
-| Visual and web evidence | `read_image` reads screenshots/figures with typed perception artifacts, `web_research` saves sourced research artifacts, and `research_wrapper` can ask Codex `gpt-5.4-mini` medium for a strict-JSON second opinion. |
+| Visual and web evidence | `read_image` reads screenshots/figures with typed JSON and Markdown perception artifacts, uses OpenAI vision when configured, and falls back to `codex exec --image` when Codex is available. `web_research` saves sourced research artifacts, and `research_wrapper` can ask Codex `gpt-5.4-mini` medium for a strict-JSON second opinion. |
 | Scouts before big work | Parallel scouts can cheaply map architecture, tests, risks, symbols, and integration points before the main executor edits anything. |
 | SCS by default | Student-Committee-Supervisor mode adds a typed gate: committee drafts, student approves/monitors, supervisor executes. Use `/scs off` or `--no-scs` only when speed matters more than validation. |
 | AAPS for large workflows | AAPS describes top-down agentic pipeline scripts; AgInTiFlow can act as the interactive backend that validates, compiles, and executes those workflows. |
@@ -239,7 +239,7 @@ The website keeps the visual walkthrough in a carousel so this README can stay f
 | Writing specialist | A dedicated writing-only LLM call for prose, chapters, scripts, books, essays, research-paper sections, and revisions, with formatter handoff notes for Markdown/LaTeX/Final Draft. |
 | Patch workflow | Codex-style patch envelopes, unified diffs, exact replacements, hashes, compact diffs, and path guardrails. |
 | Parallel scouts | Optional scout calls for architecture, implementation, review, tests, git flow, research, symbol tracing, and dependency risk. |
-| Image reading and web research | `read_image` uses OpenAI vision for workspace images when `OPENAI_API_KEY` is configured. `web_research` preserves source lists, and optional OpenAI hosted web search or `research_wrapper` can be used for higher-confidence research. |
+| Image reading and web research | `read_image` uses OpenAI vision for workspace images when `OPENAI_API_KEY` is configured, otherwise it can fall back to Codex CLI image attachments when available. It saves JSON and Markdown reports and can surface the report in the canvas. `web_research` preserves source lists, and optional OpenAI hosted web search or `research_wrapper` can be used for higher-confidence research. |
 | SCS mode | Default Student-Committee-Supervisor quality gate with independent planning, execution, and validation roles. |
 | AAPS adapter | Optional `@lazyingart/aaps` integration for `.aaps` workflow init, validate, parse, compile, dry-run, and run commands. |
 | Image generation | Optional GRS AI and Venice image tools with saved manifests and canvas artifact previews. |

package/docs/perception-and-web-research.md

@@ -6,7 +6,7 @@ AgInTiFlow separates visual understanding, web search, and wrapper advice so eac
 
 | Tool | Purpose | Evidence |
 | --- | --- | --- |
-| `read_image` | Read workspace screenshots, plots, scanned text, diagrams, or allowed remote image URLs. | Saves `artifacts/perception/*-read-image.json` in the central session store with image hashes, MIME type, size, model, prompt, and typed result. |
+| `read_image` | Read workspace screenshots, plots, scanned text, diagrams, or allowed remote image URLs. | Saves JSON and Markdown reports under `artifacts/perception/`, records image hashes, and sends the Markdown report to the canvas when used by an agent run. |
 | `web_search` | Cheap raw search snippets. | Returns compact titles, URLs, snippets, and fallback search URL. |
 | `web_research` | Sourced research unit for current or external information. | Saves `artifacts/research/*-web-research.json` with query, mode, source list, and answer. |
 | `research_wrapper` | Read-only strict-JSON second opinion from the selected wrapper. | Saves `artifacts/wrappers/*-research-wrapper.json` with wrapper, model, reasoning, metadata, result, and raw fallback output. |
@@ -14,7 +14,9 @@ AgInTiFlow separates visual understanding, web search, and wrapper advice so eac
 ## Defaults
 
 - `read_image` uses OpenAI Responses vision when `OPENAI_API_KEY` is configured.
-- `read_image` defaults to `AGINTI_PERCEPTION_MODEL=gpt-5.4-mini` and `AGINTI_PERCEPTION_REASONING=medium`, then falls back through `AGINTI_PERCEPTION_FALLBACK_MODELS` or `gpt-4o-mini` if the account lacks access to the preferred model.
+- If OpenAI vision is unavailable, `read_image` falls back to `codex exec --image` when the Codex CLI is installed and wrapper tools are enabled.
+- Wrapper tools default on when Codex is available, and can still be disabled with `/wrapper off` or `--no-wrapper`-style runtime settings.
+- `read_image` defaults to `AGINTI_PERCEPTION_MODEL=gpt-5.4-mini` and `AGINTI_PERCEPTION_REASONING=medium`, then falls back through `AGINTI_PERCEPTION_FALLBACK_MODELS` or `gpt-4o-mini` if the account lacks access to the preferred OpenAI model.
 - `web_research` defaults to lightweight snippet mode; use `mode=openai` only when hosted OpenAI web search is needed and configured.
 - `web_research mode=openai` defaults to `AGINTI_WEB_RESEARCH_MODEL=gpt-5.4-mini` / `medium`, then falls back through `AGINTI_WEB_RESEARCH_FALLBACK_MODELS` or `gpt-4o-mini`.
 - `research_wrapper` defaults to `AGINTI_RESEARCH_WRAPPER_MODEL=gpt-5.4-mini` and `AGINTI_RESEARCH_WRAPPER_REASONING=medium`.
@@ -24,6 +26,7 @@ AgInTiFlow separates visual understanding, web search, and wrapper advice so eac
 
 ```text
 /image-read artifacts/screenshots/app.png what looks wrong?
+/image-read --codex artifacts/screenshots/app.png what looks wrong?
 /web-research latest Android Gradle plugin official docs
 /research-wrapper gpt-5.4-mini medium
 /research-wrapper off

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.175",
+  "version": "0.20.176",
   "type": "module",
   "description": "AgInTiFlow is a project-aware agent workspace for hybrid wet-dry R&D, hardware-aware intelligence, software automation, and industrial workflows.",
   "license": "Apache-2.0",

package/scripts/smoke-perception-research.js

@@ -58,7 +58,28 @@ async function main() {
   assert(image.ok, `read_image dry-run failed: ${image.error || "unknown"}`);
   assert(image.images?.[0]?.sha256, "read_image did not record image hash");
   assert(image.artifactPath, "read_image did not persist a perception artifact");
+  assert(image.markdownArtifactPath, "read_image did not persist a Markdown perception artifact");
+  assert(image.markdownPath, "read_image did not persist a workspace Markdown report");
   await fs.access(image.artifactPath);
+  await fs.access(image.markdownArtifactPath);
+  await fs.access(path.join(workspace, image.markdownPath));
+
+  const codexFallback = await readImage(
+    {
+      path: "artifacts/screenshots/tiny.png",
+      prompt: "Describe this tiny image with the Codex image fallback.",
+      provider: "codex",
+      codexDryRun: true,
+    },
+    {
+      ...config,
+      allowWrapperTools: true,
+    },
+    store
+  );
+  assert(codexFallback.ok, `read_image Codex fallback dry-run failed: ${codexFallback.error || "unknown"}`);
+  assert(codexFallback.provider === "codex-wrapper-dry-run", "read_image did not select the Codex wrapper fallback path");
+  assert(codexFallback.markdownPath, "read_image Codex fallback did not write a Markdown report");
 
   const secretBlock = checkToolUse({
     toolName: "read_image",
@@ -116,6 +137,7 @@ async function main() {
   const runStore = new SessionStore(agentConfig.sessionsDir, run.sessionId);
   const events = await runStore.loadEvents();
   assert(events.some((event) => event.type === "tool.completed" && event.data?.toolName === "read_image"), "mock agent did not call read_image");
+  assert(events.some((event) => event.type === "canvas.item" && event.data?.toolName === "read_image"), "read_image did not send the Markdown report to canvas");
 
   await fs.rm(tempRoot, { recursive: true, force: true });
   console.log("smoke-perception-research ok");

package/src/agent-runner.js

@@ -1775,6 +1775,40 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
         const eventResult = sanitizeToolResult(result);
         await store.appendEvent(result.ok ? "tool.completed" : "tool.failed", eventResult);
         observers.event(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        if (result.ok && result.markdownPath) {
+          const normalized = normalizeCanvasPayload(
+            {
+              title: "Image reading report",
+              kind: "markdown",
+              path: result.markdownPath,
+              note: result.result?.summary || result.result?.answer || "Image reading report.",
+              selected: true,
+            },
+            config
+          );
+          if (normalized.ok) {
+            const persisted = await persistCanvasPayloadFile(normalized.payload, { config, store });
+            if (persisted.ok) {
+              const canvasItem = {
+                ...persisted.payload,
+                toolName: "read_image",
+                commandCwd: config.commandCwd,
+              };
+              await store.appendEvent("canvas.item", canvasItem);
+              observers.event("canvas.item", canvasItem);
+              await store.appendEvent("canvas.selected", {
+                artifactId: canvasItem.artifactId,
+                title: canvasItem.title,
+                source: "read_image",
+              });
+              observers.event("canvas.selected", {
+                artifactId: canvasItem.artifactId,
+                title: canvasItem.title,
+                source: "read_image",
+              });
+            }
+          }
+        }
         return result;
       }
       case "json_specialist": {

package/src/config.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import crypto from "node:crypto";
 import { getModelRoleDefaults, getProviderDefaults, normalizeRoutingMode, selectModelRoute } from "./model-routing.js";
 import { normalizePackageInstallPolicy, normalizeSandboxMode } from "./command-policy.js";
-import { normalizeWrapperName } from "./tool-wrappers.js";
+import { isWrapperAvailable, normalizeWrapperName } from "./tool-wrappers.js";
 import { loadProjectEnv, projectPaths, resolveProjectRoot } from "./project.js";
 import { normalizeTaskProfile } from "./task-profiles.js";
 import { recommendedMaxStepsForTask } from "./engineering-guidance.js";
@@ -113,6 +113,10 @@ export function resolveRuntimeConfig(args, overrides = {}) {
     overrides.allowParallelScouts ?? args.allowParallelScouts ?? process.env.AGINTI_PARALLEL_SCOUTS,
     true
   );
+  const preferredWrapper = normalizeWrapperName(
+    overrides.preferredWrapper ?? args.preferredWrapper ?? process.env.PREFERRED_WRAPPER ?? process.env.AGENT_WRAPPER
+  );
+  const wrapperDefaultEnabled = isWrapperAvailable(preferredWrapper) || isWrapperAvailable("codex");
 
   return {
     ...defaults,
@@ -192,7 +196,7 @@ export function resolveRuntimeConfig(args, overrides = {}) {
     ),
     allowWrapperTools: parseBoolean(
       overrides.allowWrapperTools ?? args.allowWrapperTools ?? process.env.ALLOW_WRAPPER_TOOLS,
-      false
+      wrapperDefaultEnabled
     ),
     allowAuxiliaryTools: parseBoolean(
       overrides.allowAuxiliaryTools ?? args.allowAuxiliaryTools ?? process.env.ALLOW_AUXILIARY_TOOLS,
@@ -206,9 +210,7 @@ export function resolveRuntimeConfig(args, overrides = {}) {
       1,
       10
     ),
-    preferredWrapper: normalizeWrapperName(
-      overrides.preferredWrapper ?? args.preferredWrapper ?? process.env.PREFERRED_WRAPPER ?? process.env.AGENT_WRAPPER
-    ),
+    preferredWrapper,
     wrapperTimeoutMs: parseNumber(overrides.wrapperTimeoutMs ?? process.env.WRAPPER_TIMEOUT_MS, 120000),
     permissionMode,
     sandboxMode,

package/src/interactive-cli.js

@@ -47,6 +47,7 @@ import {
 } from "./permission-modes.js";
 import { ensureAgintiWebApp, readWebAppPreference, stopAgintiWebApp, writeWebAppPreference } from "./web-autostart.js";
 import { mcpCliCommand, formatMcpCliResult } from "./mcp/tool-bridge.js";
+import { isWrapperAvailable } from "./tool-wrappers.js";
 
 const useColor = Boolean(input.isTTY && output.isTTY && process.env.AGINTIFLOW_NO_COLOR !== "1");
 const ansi = {
@@ -1112,7 +1113,7 @@ function printHelp() {
       `  ${command("/webapp [port|start|stop|restart|reuse|enable|disable|status]", "Start, reuse, stop, restart, or configure the local webapp.", "helpWebapp")}`,
       `  ${command("/web-search on|off", "Enable or disable the web_search tool.", "helpWebSearch")}`,
       `  ${command("/web-research <query>", "Run a sourced web_research turn with persisted evidence.", "helpWebSearch")}`,
-      `  ${command("/image-read <path> [question]", "Run read_image on a workspace screenshot/image.", "helpWebSearch")}`,
+      `  ${command("/image-read [--codex|--openai] <path> [question]", "Run read_image on a workspace screenshot/image.", "helpWebSearch")}`,
       `  ${command("/research-wrapper [on|off|model reasoning]", "Configure strict JSON wrapper research, default gpt-5.4-mini medium.", "helpWrapper")}`,
       `  ${command("/scs [on|auto|off|status]", "Toggle Student-Committee-Supervisor gated execution.", "helpEnableScs")}`,
       `  ${command("/scouts on|off|<1-10>", "Enable parallel DeepSeek scouts and set scout count.", "helpScouts")}`,
@@ -2659,7 +2660,7 @@ function createState(args = {}) {
     allowParallelScouts: args.allowParallelScouts ?? true,
     enableScs: normalizeScsMode(args.enableScs || process.env.AGINTI_SCS_MODE || "on"),
     parallelScoutCount: args.parallelScoutCount || 3,
-    allowWrapperTools: args.allowWrapperTools ?? false,
+    allowWrapperTools: args.allowWrapperTools ?? isWrapperAvailable(args.preferredWrapper || "codex"),
     allowDestructive: args.allowDestructive ?? permissionDefaults.allowDestructive ?? false,
     allowPasswords: args.allowPasswords ?? permissionDefaults.allowPasswords ?? false,
     allowOutsideWorkspaceFileTools:
@@ -3844,21 +3845,27 @@ async function handleCommand(line, state, packageDir) {
     return true;
   }
   if (command === "image-read") {
-    const [target, ...questionParts] = value.split(/\s+/).filter(Boolean);
+    const rawParts = value.split(/\s+/).filter(Boolean);
+    const providerFlag = ["--codex", "--openai"].includes(rawParts[0]) ? rawParts.shift() : "";
+    const provider = providerFlag ? providerFlag.replace(/^--/, "") : "";
+    const [target, ...questionParts] = rawParts;
     if (!target) {
-      printAgentMessage("Usage: /image-read <workspace-image-path-or-url> [question]");
+      printAgentMessage("Usage: /image-read [--codex|--openai] <workspace-image-path-or-url> [question]");
       return true;
     }
     const previousProfile = state.taskProfile;
     const previousMaxSteps = state.maxSteps;
+    const previousWrapperTools = state.allowWrapperTools;
     try {
       state.taskProfile = "image";
       state.maxSteps = Math.max(state.maxSteps, 12);
+      if (provider === "codex") state.allowWrapperTools = true;
       await runPrompt(
         [
           `Use the read_image tool on ${target}.`,
+          provider ? `Use read_image provider=${provider}.` : "Use read_image provider=auto so it can use OpenAI vision or Codex fallback.",
           questionParts.length ? `Question: ${questionParts.join(" ")}` : "Question: describe the image accurately and report visible text, issues, and uncertainty.",
-          "Do not infer from the filename. Report the read_image artifact path.",
+          "Do not infer from the filename. Report the read_image JSON and Markdown artifact paths.",
         ].join("\n"),
         state,
         packageDir
@@ -3866,6 +3873,7 @@ async function handleCommand(line, state, packageDir) {
     } finally {
       state.taskProfile = previousProfile;
       state.maxSteps = previousMaxSteps;
+      state.allowWrapperTools = previousWrapperTools;
     }
     return true;
   }

package/src/model-client.js

@@ -723,7 +723,7 @@ export async function createPlan(client, config, state) {
           "For substantial writing work such as novels, chapters, books, scripts, essays, LaTeX manuscripts, or research-paper prose, plan to call writing_specialist with only the writing brief/canon/style/draft context. The main agent should handle files, citations, checks, and Markdown/LaTeX/Final Draft formatting after the isolated writing draft returns.",
           "For repetitive schema-bound extraction, annotation, conversion, or validation tasks, use json_specialist with only the task, input, schema, and focused instructions. It calls the model directly for strict JSON, tries provider-native structured output when supported, and keeps agent/runtime/tool context out of the specialist prompt.",
           config.allowFileTools
-            ? "read_image is available for workspace-local or allowed remote screenshots/images using OpenAI vision when OPENAI_API_KEY is configured. It returns typed visual observations and persists a perception artifact; if credentials are missing, report the blocker instead of guessing from the filename."
+            ? "read_image is available for workspace-local or allowed remote screenshots/images. It tries OpenAI vision first when OPENAI_API_KEY is configured, then Codex CLI image wrapper when available and wrappers are enabled. It returns typed visual observations and persists JSON plus Markdown artifacts; never guess from filenames."
             : "",
           config.allowParallelScouts
             ? `Parallel scout notes may be injected before execution for complex tasks. Scout count: ${config.parallelScoutCount}.`
@@ -1179,7 +1179,7 @@ export async function requestNextStep(client, config, messages) {
         function: {
           name: "read_image",
           description:
-            "Read and describe workspace-local screenshots/images or allowed remote image URLs using OpenAI vision. Use for UI screenshots, plots, microscopy images, scanned text, diagrams, and visual debugging. It records hashes and persists a typed perception artifact. Defaults to gpt-5.4-mini with gpt-4o-mini fallback when needed. Requires OPENAI_API_KEY; if unavailable, report that blocker.",
+            "Read and describe workspace-local screenshots/images or allowed remote image URLs. Use for UI screenshots, plots, microscopy images, scanned text, diagrams, and visual debugging. It records hashes and persists JSON plus Markdown perception artifacts. Defaults to OpenAI vision, then falls back to the Codex image wrapper when Codex CLI is available and wrappers are enabled.",
           parameters: {
             type: "object",
             properties: {
@@ -1191,8 +1191,9 @@ export async function requestNextStep(client, config, messages) {
                 description: "Optional multiple workspace-relative image paths or HTTPS image URLs, maximum 4.",
               },
               prompt: { type: "string", description: "Question or reading instruction for the image(s)." },
+              provider: { type: "string", enum: ["auto", "openai", "codex"], description: "Perception backend. auto tries OpenAI then Codex wrapper." },
               detail: { type: "string", enum: ["low", "high", "auto"], description: "Vision detail level. Defaults to auto." },
-              model: { type: "string", description: "Optional OpenAI vision model. Defaults to AGINTI_PERCEPTION_MODEL or gpt-5.4-mini." },
+              model: { type: "string", description: "Optional perception model. OpenAI defaults to AGINTI_PERCEPTION_MODEL; Codex defaults to the research wrapper model." },
               reasoning: { type: "string", enum: ["low", "medium", "high", "xhigh"], description: "Optional reasoning effort. Defaults to medium." },
             },
             additionalProperties: false,
@@ -1577,6 +1578,8 @@ export async function requestNextStep(client, config, messages) {
         toolPayload.error,
         toolPayload.reason,
         toolPayload.summary ? `Summary: ${toolPayload.summary}` : "",
+        toolPayload.result?.summary ? `Summary: ${toolPayload.result.summary}` : "",
+        toolPayload.result?.answer ? `Answer: ${toolPayload.result.answer}` : "",
         toolPayload.counts ? `Counts: ${JSON.stringify(toolPayload.counts)}` : "",
         Array.isArray(toolPayload.recommendedReads) && toolPayload.recommendedReads.length
           ? `Recommended reads: ${toolPayload.recommendedReads.join(", ")}`
@@ -1585,6 +1588,8 @@ export async function requestNextStep(client, config, messages) {
           ? `Results:\n${toolPayload.results.map((item, index) => `${index + 1}. ${item.title} ${item.url}`).join("\n")}`
           : "",
         toolPayload.path ? `Path: ${toolPayload.path}` : "",
+        toolPayload.markdownPath ? `Markdown: ${toolPayload.markdownPath}` : "",
+        toolPayload.artifactPath ? `Artifact: ${toolPayload.artifactPath}` : "",
         Array.isArray(toolPayload.changes)
           ? toolPayload.changes
               .map((change) => [change.path ? `Path: ${change.path}` : "", change.diff ? `Diff:\n${change.diff}` : ""].filter(Boolean).join("\n"))

package/src/perception-tools.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import OpenAI from "openai";
 import { isDomainAllowed } from "./guardrails.js";
 import { redactSensitiveText } from "./redaction.js";
-import { normalizeWrapperName, runAgentWrapper } from "./tool-wrappers.js";
+import { isWrapperAvailable, normalizeWrapperName, runAgentWrapper, runCodexImageWrapper } from "./tool-wrappers.js";
 import { searchWeb } from "./web-search.js";
 import { resolveWorkspacePath } from "./workspace-tools.js";
 
@@ -154,6 +154,92 @@ async function persistToolArtifact(store, subdir, stem, payload) {
   return filePath;
 }
 
+function markdownList(items = []) {
+  const values = Array.isArray(items) ? items.map((item) => String(item || "").trim()).filter(Boolean) : [];
+  return values.length ? values.map((item) => `- ${item}`).join("\n") : "- None recorded.";
+}
+
+function imageReadMarkdown(payload = {}) {
+  const result = payload.result || {};
+  const images = Array.isArray(payload.images) ? payload.images : [];
+  return [
+    "# Image Reading Report",
+    "",
+    `- Status: ${payload.ok ? "ok" : "failed"}`,
+    `- Provider: ${payload.provider || ""}`,
+    payload.wrapper ? `- Wrapper: ${payload.wrapper}` : "",
+    payload.model ? `- Model: ${payload.model}` : "",
+    payload.reasoning ? `- Reasoning: ${payload.reasoning}` : "",
+    payload.detail ? `- Detail: ${payload.detail}` : "",
+    payload.prompt ? `- Prompt: ${payload.prompt}` : "",
+    payload.error ? `- Error: ${payload.error}` : "",
+    "",
+    "## Images",
+    "",
+    images.length
+      ? images
+          .map(
+            (image, index) =>
+              `${index + 1}. ${image.path || image.url || "image"} (${image.mime || "unknown"}, ${image.sizeBytes || 0} bytes, sha256=${image.sha256 || ""})`
+          )
+          .join("\n")
+      : "No loaded images were recorded.",
+    "",
+    "## Summary",
+    "",
+    result.summary || payload.rawText || payload.error || "No summary was returned.",
+    "",
+    "## Answer",
+    "",
+    result.answer || result.summary || payload.rawText || payload.error || "No answer was returned.",
+    "",
+    "## Visible Text",
+    "",
+    markdownList(result.visibleText),
+    "",
+    "## Observations",
+    "",
+    markdownList(result.observations),
+    "",
+    "## Issues",
+    "",
+    markdownList(result.issues),
+    "",
+    "## Uncertainty",
+    "",
+    markdownList(result.uncertainty || result.uncertainties),
+    "",
+  ]
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trimEnd() + "\n";
+}
+
+async function persistMarkdownArtifact(store, config, subdir, stem, payload) {
+  const content = imageReadMarkdown(payload);
+  const filename = `${isoStamp()}-${stem}.md`;
+  let markdownArtifactPath = "";
+  let markdownPath = "";
+
+  if (store?.artifactsDir) {
+    await store.ensure();
+    const outputDir = path.join(store.artifactsDir, subdir);
+    await fs.mkdir(outputDir, { recursive: true });
+    markdownArtifactPath = path.join(outputDir, filename);
+    await fs.writeFile(markdownArtifactPath, content, "utf8");
+  }
+
+  if (config?.commandCwd) {
+    const workspaceDir = path.join(config.commandCwd, "artifacts", subdir);
+    await fs.mkdir(workspaceDir, { recursive: true });
+    const workspacePath = path.join(workspaceDir, filename);
+    await fs.writeFile(workspacePath, content, "utf8");
+    markdownPath = path.relative(config.commandCwd, workspacePath).replace(/\\/g, "/");
+  }
+
+  return { markdownArtifactPath, markdownPath };
+}
+
 function imageMimeForPath(inputPath, contentType = "") {
   const type = String(contentType || "").split(";")[0].trim().toLowerCase();
   if (type.startsWith("image/")) return type;
@@ -310,17 +396,132 @@ async function callOpenAiImageRead(args, images, config) {
   };
 }
 
+function codexImageReadPrompt(args, images) {
+  return [
+    "Inspect the attached image(s) directly and return strict JSON only. Do not wrap in Markdown.",
+    "Use this schema:",
+    JSON.stringify({
+      summary: "short factual summary",
+      visibleText: ["OCR text or labels, empty if none"],
+      observations: ["concrete visible details"],
+      issues: ["possible UI/data/quality issues, empty if none"],
+      answer: "direct answer to the user's question",
+      uncertainty: ["limits, ambiguity, or details not visible"],
+    }),
+    "Rules: describe only visible evidence. Do not infer from filenames. If uncertain, say so.",
+    `User question: ${String(args.prompt || args.question || "Describe the image accurately.").trim()}`,
+    `Image metadata: ${images
+      .map((image, index) => `${index + 1}. ${image.path || image.url} ${image.mime} ${image.sizeBytes} bytes sha256=${image.sha256}`)
+      .join("; ")}`,
+  ].join("\n");
+}
+
+async function codexReadableImagePaths(images, store) {
+  const imagePaths = [];
+  for (const image of images) {
+    if (image.absolutePath) {
+      imagePaths.push(image.absolutePath);
+      continue;
+    }
+    if (!store?.artifactsDir) {
+      throw new Error("Codex image fallback needs a local image file; remote image copy store is unavailable.");
+    }
+    await store.ensure();
+    const ext = image.mime === "image/jpeg" ? ".jpg" : image.mime === "image/webp" ? ".webp" : image.mime === "image/gif" ? ".gif" : ".png";
+    const outputDir = path.join(store.artifactsDir, "perception", "codex-inputs");
+    await fs.mkdir(outputDir, { recursive: true });
+    const outputPath = path.join(outputDir, `${isoStamp()}-${image.sha256.slice(0, 12)}${ext}`);
+    const raw = Buffer.from(String(image.dataUrl || "").replace(/^data:image\/[a-z0-9.+-]+;base64,/i, ""), "base64");
+    if (!raw.length) throw new Error("Remote image copy for Codex fallback was empty.");
+    await fs.writeFile(outputPath, raw);
+    imagePaths.push(outputPath);
+  }
+  return imagePaths;
+}
+
+async function callCodexImageRead(args, images, config, store, priorError = null) {
+  if (args.codexDryRun) {
+    return {
+      provider: "codex-wrapper-dry-run",
+      wrapper: "codex",
+      model: args.model || config.researchWrapperModel || "gpt-5.4-mini",
+      reasoning: args.reasoning || config.researchWrapperReasoning || "medium",
+      rawText: "",
+      parsed: {
+        summary: "Codex image fallback dry run",
+        visibleText: [],
+        observations: ["Codex image wrapper fallback path was selected."],
+        issues: [],
+        answer: "dry run",
+        uncertainty: [],
+      },
+    };
+  }
+  if (config.allowWrapperTools === false && args.provider !== "codex") {
+    throw new Error("Codex image fallback is disabled because wrapper tools are off.");
+  }
+  if (!isWrapperAvailable("codex")) {
+    throw new Error("Codex image fallback is unavailable because the Codex CLI was not found on PATH.");
+  }
+  const imagePaths = await codexReadableImagePaths(images, store);
+  const wrapperConfig = {
+    ...config,
+    wrapperModel: args.model || config.researchWrapperModel || process.env.AGINTI_RESEARCH_WRAPPER_MODEL || "gpt-5.4-mini",
+    wrapperReasoning: args.reasoning || config.researchWrapperReasoning || process.env.AGINTI_RESEARCH_WRAPPER_REASONING || "medium",
+  };
+  const wrapperResult = await runCodexImageWrapper(
+    {
+      prompt: [
+        codexImageReadPrompt(args, images),
+        priorError ? `OpenAI vision fallback reason: ${redactSensitiveText(priorError instanceof Error ? priorError.message : String(priorError))}` : "",
+      ]
+        .filter(Boolean)
+        .join("\n\n"),
+      imagePaths,
+    },
+    wrapperConfig
+  );
+  if (!wrapperResult.ok) throw new Error(wrapperResult.error || "Codex image fallback failed.");
+  const parsed = firstJsonObject(wrapperResult.stdout || "");
+  return {
+    provider: "codex-wrapper",
+    wrapper: "codex",
+    model: wrapperResult.model || wrapperConfig.wrapperModel,
+    reasoning: wrapperResult.reasoning || wrapperConfig.wrapperReasoning,
+    rawText: compactText(wrapperResult.stdout || ""),
+    parsed,
+    stderr: compactText(wrapperResult.stderr || "", 4000),
+    fallback: Boolean(priorError || wrapperResult.fallback),
+    fallbackReason: priorError ? redactSensitiveText(priorError instanceof Error ? priorError.message : String(priorError)) : "",
+  };
+}
+
+async function callImageRead(args, images, config, store) {
+  const provider = String(args.provider || args.engine || "auto").trim().toLowerCase();
+  if (args.dryRun) {
+    return { provider: "dry-run", rawText: "", parsed: { summary: "read_image dry run", answer: "dry run" } };
+  }
+  if (provider === "codex") return callCodexImageRead(args, images, config, store);
+  if (provider === "openai") return callOpenAiImageRead(args, images, config);
+  try {
+    return await callOpenAiImageRead(args, images, config);
+  } catch (error) {
+    return callCodexImageRead(args, images, config, store, error);
+  }
+}
+
 export async function readImage(args = {}, config = {}, store = null) {
   const loadedImages = [];
   let payload = null;
   try {
     const images = await loadImageInputs(args, config);
     loadedImages.push(...images);
-    const analysis = args.dryRun ? { provider: "dry-run", rawText: "", parsed: { summary: "read_image dry run", answer: "dry run" } } : await callOpenAiImageRead(args, images, config);
+    const analysis = await callImageRead(args, images, config, store);
     payload = {
       ok: true,
       toolName: "read_image",
       provider: analysis.provider,
+      wrapper: analysis.wrapper || "",
       model: analysis.model || "",
       reasoning: analysis.reasoning || "",
       detail: analysis.detail || "",
@@ -328,8 +529,12 @@ export async function readImage(args = {}, config = {}, store = null) {
       images: images.map(({ dataUrl, absolutePath, ...image }) => image),
       result: analysis.parsed || { summary: analysis.rawText, answer: analysis.rawText, uncertainty: ["Model output was not valid JSON."] },
       rawText: analysis.parsed ? "" : analysis.rawText,
+      stderr: analysis.stderr || "",
+      fallback: Boolean(analysis.fallback),
+      fallbackReason: analysis.fallbackReason || "",
     };
     payload.artifactPath = await persistToolArtifact(store, "perception", "read-image", payload);
+    Object.assign(payload, await persistMarkdownArtifact(store, config, "perception", "read-image", payload));
     return payload;
   } catch (error) {
     payload = {
@@ -339,6 +544,7 @@ export async function readImage(args = {}, config = {}, store = null) {
       images: loadedImages.map(({ dataUrl, absolutePath, ...image }) => image),
     };
     payload.artifactPath = await persistToolArtifact(store, "perception", "read-image-failed", payload);
+    Object.assign(payload, await persistMarkdownArtifact(store, config, "perception", "read-image-failed", payload));
     return payload;
   }
 }

package/src/scs-controller.js

@@ -5,6 +5,7 @@ import {
   buildScsEvidenceLedger,
   deriveScsTaskContract,
   deterministicFinishBlocker,
+  evaluateScsSemanticContract,
   evaluateScsEvidence,
   finishResultClaimsBlocker,
   hasScsBlockerEvidence,
@@ -140,6 +141,25 @@ function fallbackBlockedPlan(goal = "", studentReason = "") {
     .join("\n");
 }
 
+function fallbackHardContractPlan(goal = "", contract = {}, studentReason = "") {
+  const exactOutputPaths = normalizeStringList(contract.exactOutputPaths, []);
+  const requiredTextTerms = normalizeStringList(contract.requiredTextTerms, []);
+  const forbiddenTextTerms = normalizeStringList(contract.forbiddenTextTerms, []);
+  return [
+    "1. Execute the user's target work under the deterministic hard-contract fallback plan.",
+    exactOutputPaths.length
+      ? `2. Write the requested output exactly at: ${exactOutputPaths.join(", ")}. If an output file already exists and the user allowed overwrite/update, overwrite it intentionally.`
+      : "2. Create or update the requested output artifact at the user-specified location.",
+    requiredTextTerms.length ? `3. Ensure the output contains these required term(s): ${requiredTextTerms.join(", ")}.` : "",
+    forbiddenTextTerms.length ? `4. Ensure the output does not contain these forbidden term(s): ${forbiddenTextTerms.join(", ")}.` : "",
+    "5. Run concrete validation commands or inspections for file existence and content before finish.",
+    studentReason ? `6. Preserve the validator concern while executing: ${compact(studentReason, 180)}` : "",
+    goal ? `7. Original goal remains authoritative: ${compact(goal, 220)}` : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
 function parseJsonObject(content = "") {
   const text = String(content || "").trim();
   if (!text) return null;
@@ -222,6 +242,47 @@ function normalizePlanText(plan) {
   return redacted.length <= 1800 ? redacted : `${redacted.slice(0, 1776)} ... [truncated]`;
 }
 
+function formatHardContractForPrompt(contract = {}) {
+  const lines = [];
+  const exactOutputPaths = normalizeStringList(contract.exactOutputPaths, []);
+  const requiredTextTerms = normalizeStringList(contract.requiredTextTerms, []);
+  const forbiddenTextTerms = normalizeStringList(contract.forbiddenTextTerms, []);
+  const forbiddenActions = normalizeStringList(contract.forbiddenActions, []);
+  if (exactOutputPaths.length) lines.push(`Exact output path(s): ${exactOutputPaths.join(", ")}`);
+  if (requiredTextTerms.length) lines.push(`Required text term(s) in the output: ${requiredTextTerms.join(", ")}`);
+  if (forbiddenTextTerms.length) lines.push(`Forbidden text term(s) in the output: ${forbiddenTextTerms.join(", ")}`);
+  if (forbiddenActions.length) lines.push(`Forbidden action(s): ${forbiddenActions.join("; ")}`);
+  return lines.length
+    ? [
+        "Inferred hard task contract. Preserve these literally; do not replace them with weaker or contradictory criteria:",
+        ...lines.map((line) => `- ${line}`),
+      ].join("\n")
+    : "";
+}
+
+function deterministicPlanContractIssue(committee = {}, contract = {}) {
+  const planText = `${committee.phaseGoal || ""}\n${committee.plan || ""}\n${(committee.acceptanceCriteria || []).join("\n")}`;
+  const missingPath = normalizeStringList(contract.exactOutputPaths, []).filter((item) => !planText.includes(item));
+  const missingRequiredTerms = normalizeStringList(contract.requiredTextTerms, []).filter((item) => !planText.includes(item));
+  const forbiddenTermsInPlan = normalizeStringList(contract.forbiddenTextTerms, []).filter((item) => planText.includes(item));
+  if (missingPath.length || missingRequiredTerms.length || forbiddenTermsInPlan.length) {
+    return {
+      decision: "veto_plan",
+      confidence: 0.94,
+      evidence: [
+        missingPath.length ? `Plan omitted exact output path(s): ${missingPath.join(", ")}` : "",
+        missingRequiredTerms.length ? `Plan omitted required text term(s): ${missingRequiredTerms.join(", ")}` : "",
+        forbiddenTermsInPlan.length ? `Plan includes forbidden text term(s): ${forbiddenTermsInPlan.join(", ")}` : "",
+      ].filter(Boolean),
+      reason:
+        "The phase plan does not preserve the user's inferred hard task contract. It must carry exact paths and required/forbidden output terms into acceptance criteria.",
+      next_required_action:
+        "Committee must draft a new plan whose acceptance criteria explicitly include every exact output path, required text term, and forbidden text term from the hard contract.",
+    };
+  }
+  return null;
+}
+
 function isBrowserSubmitGoal(goal = "") {
   const text = String(goal || "");
   const browserSignal =
@@ -345,6 +406,7 @@ export function buildScsEvidencePack(state = {}, context = {}) {
 export function buildSupervisorInstruction(scs = {}) {
   const criteria = normalizeStringList(scs.acceptanceCriteria);
   const stopConditions = normalizeStringList(scs.stopConditions);
+  const hardContract = formatHardContractForPrompt(scs.taskContract || {});
   return [
     "SCS mode is enabled. SCS means Student-Committee-Supervisor; do not redefine the acronym.",
     "You are the supervisor executor in that Student-Committee-Supervisor pipeline.",
@@ -355,6 +417,7 @@ export function buildSupervisorInstruction(scs = {}) {
     "If tool evidence invalidates the plan, stop repeating the failed path and explain the blocker through finish or wait for student review.",
     "Approved phase plan:",
     scs.plan || fallbackPlan(),
+    hardContract,
     criteria.length ? `Acceptance criteria:\n${criteria.map((item) => `- ${item}`).join("\n")}` : "",
     stopConditions.length ? `Stop conditions:\n${stopConditions.map((item) => `- ${item}`).join("\n")}` : "",
     "Before calling finish, include concrete evidence: files changed, commands/checks run, artifacts created, or a clear limitation.",
@@ -376,6 +439,7 @@ function committeeSystemPrompt({ phaseKind = "initial" } = {}) {
       : "",
     browserStateReconciliationGuidance(),
     formatBehaviorContractForPrompt({ mode: "plan" }),
+    "Preserve exact user hard constraints literally: output paths, required words/phrases, forbidden words/phrases, model/duration/tier, and explicit no-action instructions. Do not invent contradictory acceptance criteria such as a different length target or output location.",
     "Return strict JSON with keys: role, phase_goal, plan, acceptance_criteria, allowed_tools, stop_conditions.",
   ]
     .filter(Boolean)
@@ -389,6 +453,7 @@ function studentPlanGatePrompt() {
     "Judge whether the committee phase plan is safe, scoped, minimal, permission-aware, and evidence-oriented.",
     "You cannot execute tools or approve your own work. If the plan is weak, veto it so the committee must draft a better plan.",
     "For browser tasks, reject plans that stop merely because a state field is unknown when the user requested a target state and a bounded set-then-verify path is available.",
+    "Reject any plan whose phase goal, steps, or acceptance criteria omit exact output paths, required output phrases, or forbidden output phrases from the hard task contract. Also reject plans that add contradictory constraints not requested by the user.",
     formatBehaviorContractForPrompt({ mode: "plan" }),
     "Return strict JSON with keys: role, decision, confidence, evidence, reason, next_required_action.",
   ].join(" ");
@@ -468,6 +533,11 @@ async function createScsPhase(client, config, state, context = {}, options = {})
     "approve_plan"
   );
   let lastValidatorConcern = validatorFeedback?.reason || validatorFeedback?.nextRequiredAction || "";
+  const taskContract = deriveScsTaskContract({
+    goal: state.goal,
+    taskProfile: context.taskProfile || "",
+    acceptanceCriteria: [],
+  });
 
   for (let attempt = 1; attempt <= 2; attempt += 1) {
     const rawCommittee = await callJson(
@@ -482,6 +552,7 @@ async function createScsPhase(client, config, state, context = {}, options = {})
           role: "user",
           content: [
             `Goal and evidence:\n${evidence}`,
+            formatHardContractForPrompt(taskContract),
             validatorFeedback
               ? `Student validator feedback that caused this ${phaseKind}:\n${compactJson(validatorFeedback, 1800)}`
               : "",
@@ -496,6 +567,13 @@ async function createScsPhase(client, config, state, context = {}, options = {})
       "SCS committee"
     );
     committee = normalizeCommitteePlan(rawCommittee, state.goal);
+    const deterministicIssue = deterministicPlanContractIssue(committee, taskContract);
+    if (deterministicIssue) {
+      student = normalizeDecision(deterministicIssue, "veto_plan");
+      lastValidatorConcern = student.reason || student.nextRequiredAction || lastValidatorConcern;
+      if (attempt < 2) continue;
+      break;
+    }
 
     const rawStudent = await callJson(
       client,
@@ -507,7 +585,11 @@ async function createScsPhase(client, config, state, context = {}, options = {})
         },
         {
           role: "user",
-          content: `Goal/evidence:\n${evidence}\n\nCommittee plan:\n${compactJson(committee, 4000)}`,
+          content: [
+            `Goal/evidence:\n${evidence}`,
+            formatHardContractForPrompt(taskContract),
+            `Committee plan:\n${compactJson(committee, 4000)}`,
+          ].join("\n\n"),
         },
       ],
       student,
@@ -519,15 +601,19 @@ async function createScsPhase(client, config, state, context = {}, options = {})
   }
 
   if (student.decision === "veto_plan") {
+    const hardContractPlan = fallbackHardContractPlan(state.goal, taskContract, student.reason || lastValidatorConcern);
+    const hardContractCriteria = [
+      ...normalizeStringList(taskContract.exactOutputPaths, []).map((item) => `Exact output path is used: ${item}`),
+      ...normalizeStringList(taskContract.requiredTextTerms, []).map((item) => `Output contains required text: ${item}`),
+      ...normalizeStringList(taskContract.forbiddenTextTerms, []).map((item) => `Output omits forbidden text: ${item}`),
+      "Concrete file/content validation evidence is collected before finish.",
+    ];
     committee = normalizeCommitteePlan(
       {
-        phase_goal: "Report SCS validator blocker instead of executing rejected target work.",
-        plan: fallbackBlockedPlan(state.goal, student.reason || lastValidatorConcern),
-        acceptance_criteria: [
-          "The run does not execute target work under a rejected plan.",
-          "The final report names the student validator concern and requested clarification or override.",
-        ],
-        stop_conditions: ["Any attempt to proceed with target work without an approved phase plan."],
+        phase_goal: "Execute the user's target work using the deterministic hard-contract fallback plan.",
+        plan: hardContractPlan,
+        acceptance_criteria: hardContractCriteria,
+        stop_conditions: ["A required file path is inaccessible.", "A required/forbidden text constraint cannot be satisfied."],
       },
       state.goal
     );
@@ -536,9 +622,9 @@ async function createScsPhase(client, config, state, context = {}, options = {})
         decision: "approve_plan",
         confidence: 0.9,
         reason:
-          "Student veto remained after committee retries; approving only a blocker-reporting phase, not target execution.",
+          "Student veto remained after committee retries; runtime synthesized a deterministic hard-contract fallback plan that preserves exact user constraints.",
         evidence: student.evidence || [],
-        next_required_action: "supervisor_report_validator_blocker",
+        next_required_action: "supervisor_execute_hard_contract_plan",
       },
       "approve_plan"
     );
@@ -756,8 +842,28 @@ export async function reviewScsFinish(client, config, state, result = "", contex
   });
   const evidenceLedger = buildScsEvidenceLedger({ state, context });
   const evidenceEvaluation = evaluateScsEvidence(taskContract, evidenceLedger);
+  const semanticEvaluation = evaluateScsSemanticContract(taskContract, {
+    commandCwd: config.commandCwd || process.cwd(),
+  });
   const deterministicBlocker = deterministicFinishBlocker(taskContract, evidenceLedger, evidenceEvaluation);
   const hasRealBlocker = hasScsBlockerEvidence(evidenceLedger) && finishResultClaimsBlocker(result);
+  if (!semanticEvaluation.ok && !hasRealBlocker) {
+    return normalizeDecision(
+      {
+        decision: "finish_rejected",
+        confidence: 0.97,
+        reason: `SCS semantic hard-contract gate rejected finish: ${semanticEvaluation.reason}`,
+        evidence: [
+          ...(semanticEvaluation.missingFiles || []).map((item) => `missing file: ${item}`),
+          ...(semanticEvaluation.missingRequiredText || []).map((item) => `missing required text: ${item}`),
+          ...(semanticEvaluation.presentForbiddenText || []).map((item) => `forbidden text present: ${item}`),
+        ],
+        next_required_action:
+          "Revise the exact output file(s) to satisfy the required and forbidden text terms, then run concrete validation commands before finishing.",
+      },
+      "finish_rejected"
+    );
+  }
   const requiresEvidence =
     taskContract.requiresExternalEvidence ||
     finishRequiresExternalEvidence(context.goal || state.goal || "", context.taskProfile || config.taskProfile || "");

package/src/scs-evidence.js

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import path from "node:path";
 import { redactSensitiveText, redactValue } from "./redaction.js";
 
 const CATEGORY_LABELS = {
@@ -62,6 +64,89 @@ function unique(items = []) {
   return [...new Set(items.filter(Boolean))];
 }
 
+function uniqueLimited(items = [], limit = 16) {
+  return unique(items.map((item) => compact(item, 120)).filter(Boolean)).slice(0, limit);
+}
+
+function quotedTerms(text = "") {
+  const terms = [];
+  const patterns = [
+    /“([^”]{1,80})”/g,
+    /"([^"\n]{1,80})"/g,
+    /'([^'\n]{1,80})'/g,
+    /`([^`\n]{1,80})`/g,
+  ];
+  for (const pattern of patterns) {
+    for (const match of String(text || "").matchAll(pattern)) {
+      const term = String(match[1] || "").trim();
+      if (!term || /[\\/]/.test(term)) continue;
+      terms.push(term);
+    }
+  }
+  return terms;
+}
+
+function splitInlineTerms(text = "") {
+  return String(text || "")
+    .split(/[、,，;；]/)
+    .map((item) => item.replace(/[。.!！?？:：]/g, "").trim())
+    .filter((item) => item.length >= 2 && item.length <= 40 && !/[\\/]/.test(item));
+}
+
+function inferExactOutputPaths(goal = "") {
+  const paths = [];
+  const lines = String(goal || "").split(/\n+/);
+  const pathPattern = /(?:^|[\s"'`：:])((?:~|\.{1,2}|[A-Za-z0-9_\-\u4e00-\u9fff])[\w./~\-\u4e00-\u9fff ]{0,220}\.(?:md|txt|json|ya?ml|html|css|js|ts|tsx|jsx|py|sh|csv|tex|svg|png|jpe?g|webp|mp4|mov|pdf|docx))(?:$|[\s"'`,，。；;])/gi;
+  for (const line of lines) {
+    if (!/\b(save|saved|write|written|output|create|store)\b|保存|写入|寫入|输出|輸出|创建|建立/.test(line)) continue;
+    for (const match of line.matchAll(pathPattern)) {
+      const raw = String(match[1] || "").trim();
+      if (!raw) continue;
+      paths.push(raw);
+    }
+  }
+  return uniqueLimited(paths, 8);
+}
+
+function inferRequiredTextTerms(goal = "") {
+  const terms = [];
+  const lines = String(goal || "").split(/\n+/);
+  for (const line of lines) {
+    const positiveSegment = String(line || "").split(
+      /(?:并)?确认没有|(?:并)?確認沒有|没有|沒有|\b(?:does not contain|do not contain|not contain|not include|without)\b/i
+    )[0];
+    if (
+      /\b(must|require|required|include|contain|contains|check|verify|grep|keyword|keywords)\b/i.test(line) ||
+      /必须|必須|要求|包含|检查|檢查|验证|驗證|关键词|關鍵詞|自检|自檢/.test(line)
+    ) {
+      terms.push(...quotedTerms(positiveSegment));
+    }
+  }
+  return uniqueLimited(terms, 24);
+}
+
+function inferForbiddenTextTerms(goal = "") {
+  const terms = [];
+  const lines = String(goal || "").split(/\n+/);
+  for (const line of lines) {
+    const text = String(line || "");
+    if (
+      /\b(?:do not|don't|dont|must not|never)\s+(?:write|include|mention|contain)\b/i.test(text) ||
+      /不要(?:写|寫|包含|提到)|不得(?:写|寫|包含|提到)|禁止(?:写|寫|包含|提到)|(?:确认|確認)(?:没有|沒有)/.test(text)
+    ) {
+      const tail =
+        text.match(/(?:不要(?:写|寫|包含|提到)|不得(?:写|寫|包含|提到)|禁止(?:写|寫|包含|提到))(.+)/)?.[1] ||
+        text.match(/(?:确认|確認)(?:没有|沒有)(.+)/)?.[1] ||
+        text.match(/\b(?:do not|don't|dont|must not|never)\s+(?:write|include|mention|contain)\s+(.+)/i)?.[1] ||
+        "";
+      terms.push(...quotedTerms(tail));
+      const unquotedTail = tail.replace(/“[^”]+”|"[^"\n]+"|'[^'\n]+'|`[^`\n]+`/g, "");
+      terms.push(...splitInlineTerms(unquotedTail).filter((item) => !/^(and|or|the|a|an|other|其他|上一集道具)$/.test(item)));
+    }
+  }
+  return uniqueLimited(terms, 16);
+}
+
 function blockerFromPayload(payload = {}, source = "tool") {
   if (!payload || typeof payload !== "object") return null;
   if (!payload.blocked && payload.ok !== false && !payload.permissionAdvice) return null;
@@ -182,7 +267,7 @@ function inferRequirementCategories(goal = "", taskProfile = "", acceptanceCrite
   if (textHas(text, /\b(artifact|canvas|pdf|image|video|screenshot|cover|plot|chart|figure|docx|archive|copy to|export|generated|generate|draft)\b/) || /输出|产物|图片|视频|截图|封面|生成/.test(text)) {
     categories.add("artifact");
   }
-  if (textHas(text, /\b(browser|chrome|chromium|cdp|devtools|playwright|selenium|web[- ]?ui|website|page|tab|composer|click|type|upload|attach|submit|form)\b/) || /浏览器|网页|页面|上传|提交|附件|资产库|按钮/.test(text)) {
+  if (textHas(text, /\b(browser|chrome|chromium|cdp|devtools|playwright|selenium|web[- ]?ui|website|page|tab|composer|click|type|upload|attach|submit|form)\b/) || /浏览器|网页|页面|上传|提交|附件|资产库/.test(text)) {
     categories.add("browser");
   }
   if (textHas(text, /\b(screenshot|visible|visual|see|inspect image|open image|read_image|thumbnail)\b/) || /截图|可见|缩略图/.test(text)) {
@@ -205,6 +290,10 @@ function inferRequirementCategories(goal = "", taskProfile = "", acceptanceCrite
 function inferForbiddenActions(goal = "") {
   const text = String(goal || "");
   const forbidden = [];
+  const isAction = (value = "") =>
+    /\b(use|open|click|browse|browser|upload|attach|submit|publish|deploy|run|execute|install|delete|remove|commit|push|call|api)\b/i.test(
+      value
+    ) || /浏览器|网页|打开|点击|上传|提交|发布|部署|运行|执行|安装|删除|复制|移动|提交代码|推送|调用|API/.test(value);
   const patterns = [
     { re: /\b(do not|don't|dont|never|no need to|without)\s+([^.\n;]+)/gi, prefix: "User forbids" },
     { re: /不要([^。\n；]+)/g, prefix: "User forbids" },
@@ -212,7 +301,8 @@ function inferForbiddenActions(goal = "") {
   ];
   for (const { re, prefix } of patterns) {
     for (const match of text.matchAll(re)) {
-      forbidden.push(`${prefix}: ${compact(match[2] || match[1], 160)}`);
+      const value = compact(match[2] || match[1], 160);
+      if (isAction(value)) forbidden.push(`${prefix}: ${value}`);
     }
   }
   return unique(forbidden).slice(0, 8);
@@ -240,10 +330,78 @@ export function deriveScsTaskContract({ goal = "", taskProfile = "", acceptanceC
     requiresExternalEvidence,
     requiredEvidence,
     forbiddenActions: inferForbiddenActions(goal),
+    exactOutputPaths: inferExactOutputPaths(goal),
+    requiredTextTerms: inferRequiredTextTerms(goal),
+    forbiddenTextTerms: inferForbiddenTextTerms(goal),
     successCriteria: unique(acceptanceCriteria).slice(0, 10),
   };
 }
 
+function resolveContractPath(commandCwd = process.cwd(), rawPath = "") {
+  const text = String(rawPath || "").trim();
+  if (!text) return "";
+  if (text.startsWith("~/")) return path.join(process.env.HOME || commandCwd, text.slice(2));
+  if (path.isAbsolute(text)) return text;
+  return path.resolve(commandCwd || process.cwd(), text);
+}
+
+export function evaluateScsSemanticContract(contract = {}, { commandCwd = process.cwd() } = {}) {
+  const exactOutputPaths = Array.isArray(contract.exactOutputPaths) ? contract.exactOutputPaths : [];
+  const requiredTextTerms = Array.isArray(contract.requiredTextTerms) ? contract.requiredTextTerms : [];
+  const forbiddenTextTerms = Array.isArray(contract.forbiddenTextTerms) ? contract.forbiddenTextTerms : [];
+  if (!exactOutputPaths.length && !requiredTextTerms.length && !forbiddenTextTerms.length) {
+    return { ok: true, checked: false, reason: "No semantic file contract was inferred." };
+  }
+  if (!exactOutputPaths.length) {
+    return {
+      ok: true,
+      checked: false,
+      reason: "Semantic text terms were inferred, but no exact output path was inferred for deterministic file inspection.",
+      requiredTextTerms,
+      forbiddenTextTerms,
+    };
+  }
+
+  const files = exactOutputPaths.map((rawPath) => {
+    const absolutePath = resolveContractPath(commandCwd, rawPath);
+    try {
+      const content = fs.readFileSync(absolutePath, "utf8");
+      return { rawPath, absolutePath, exists: true, content };
+    } catch {
+      return { rawPath, absolutePath, exists: false, content: "" };
+    }
+  });
+  const missingFiles = files.filter((file) => !file.exists).map((file) => file.rawPath);
+  const combinedContent = files.map((file) => file.content).join("\n");
+  const missingRequiredText = requiredTextTerms.filter((term) => !combinedContent.includes(term));
+  const presentForbiddenText = forbiddenTextTerms.filter((term) => combinedContent.includes(term));
+  const ok = missingFiles.length === 0 && missingRequiredText.length === 0 && presentForbiddenText.length === 0;
+  return {
+    ok,
+    checked: true,
+    exactOutputPaths,
+    requiredTextTerms,
+    forbiddenTextTerms,
+    missingFiles,
+    missingRequiredText,
+    presentForbiddenText,
+    inspectedFiles: files.map((file) => ({
+      path: file.rawPath,
+      exists: file.exists,
+      chars: file.content.length,
+    })),
+    reason: ok
+      ? "Exact output files satisfy inferred semantic hard constraints."
+      : [
+          missingFiles.length ? `Missing exact output files: ${missingFiles.join(", ")}` : "",
+          missingRequiredText.length ? `Missing required text terms: ${missingRequiredText.join(", ")}` : "",
+          presentForbiddenText.length ? `Forbidden text terms present: ${presentForbiddenText.join(", ")}` : "",
+        ]
+          .filter(Boolean)
+          .join("; "),
+  };
+}
+
 function eventToEvidence(event = {}) {
   const type = String(event.type || "");
   const data = event.data && typeof event.data === "object" ? event.data : {};
@@ -415,6 +573,9 @@ export function summarizeScsContractEvidence({ contract = {}, ledger = {}, evalu
         description: item.description,
       })),
       forbiddenActions: contract.forbiddenActions || [],
+      exactOutputPaths: contract.exactOutputPaths || [],
+      requiredTextTerms: contract.requiredTextTerms || [],
+      forbiddenTextTerms: contract.forbiddenTextTerms || [],
       successCriteria: contract.successCriteria || [],
     },
     evidenceLedger: {

package/src/tool-wrappers.js

@@ -1,4 +1,7 @@
 import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import { getModelPresets } from "./model-routing.js";
 import { redactSensitiveText } from "./redaction.js";
 
@@ -11,7 +14,7 @@ const BASE_ADVISORY_PROMPT = [
   "Return concise findings, commands to consider, or an implementation plan.",
 ].join(" ");
 
-function commandExists(command) {
+export function commandExists(command) {
   try {
     if (process.platform === "win32") {
       execFileSync("where", [command], { stdio: "ignore" });
@@ -225,6 +228,11 @@ export function listAgentWrappers() {
   ];
 }
 
+export function isWrapperAvailable(wrapper) {
+  const candidate = normalizeWrapperName(wrapper);
+  return Boolean(wrapperCommand(candidate, "", {}, {}) && commandExists(wrapperCommand(candidate, "", {}, {}).command));
+}
+
 export function wrapperStatusText() {
   return listAgentWrappers()
     .map((wrapper) => `${wrapper.name}:${wrapper.available ? "available" : "missing"}`)
@@ -284,3 +292,95 @@ export async function runAgentWrapper({ wrapper, prompt }, config) {
     };
   }
 }
+
+function codexImageArgs(prompt, imagePaths, config, preset, outputFile) {
+  const imageArgs = [];
+  for (const imagePath of imagePaths || []) {
+    imageArgs.push("--image", imagePath);
+  }
+  return [
+    "exec",
+    "--model",
+    preset.model,
+    "-c",
+    `model_reasoning_effort="${preset.reasoning}"`,
+    "--sandbox",
+    "read-only",
+    "--cd",
+    config.commandCwd,
+    "--skip-git-repo-check",
+    "--output-last-message",
+    outputFile,
+    ...imageArgs,
+    "--",
+    buildPrompt(prompt),
+  ];
+}
+
+export async function runCodexImageWrapper({ prompt, imagePaths = [] }, config) {
+  if (!commandExists("codex")) {
+    return { ok: false, wrapper: "codex", error: "Codex CLI is not available on PATH." };
+  }
+  if (!Array.isArray(imagePaths) || imagePaths.length === 0) {
+    return { ok: false, wrapper: "codex", error: "At least one image file is required for Codex image reading." };
+  }
+
+  const presets = getModelPresets({
+    wrapperModel: config.wrapperModel,
+    wrapperReasoning: config.wrapperReasoning,
+  });
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "aginti-codex-image-"));
+  const runOnce = async (preset, label) => {
+    const outputFile = path.join(tempDir, `${label}.txt`);
+    const result = await runWrapperProcess(
+      {
+        command: "codex",
+        args: codexImageArgs(prompt, imagePaths, config, preset, outputFile),
+      },
+      config
+    );
+    const lastMessage = await fs.readFile(outputFile, "utf8").catch(() => "");
+    return {
+      stdout: cleanOutput(lastMessage || result.stdout, 24000),
+      stderr: cleanOutput(result.stderr, 4000),
+    };
+  };
+
+  try {
+    const result = await runOnce(presets.codexPrimary, "primary");
+    return {
+      ok: true,
+      wrapper: "codex",
+      model: presets.codexPrimary.model,
+      reasoning: presets.codexPrimary.reasoning,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    };
+  } catch (error) {
+    if (error?.name === "AbortError" || error?.code === "ABORT_ERR") throw error;
+    try {
+      const fallback = await runOnce(presets.codexSpare, "fallback");
+      return {
+        ok: true,
+        wrapper: "codex",
+        fallback: true,
+        model: presets.codexSpare.model,
+        reasoning: presets.codexSpare.reasoning,
+        stdout: fallback.stdout,
+        stderr: fallback.stderr,
+      };
+    } catch (fallbackError) {
+      if (fallbackError?.name === "AbortError" || fallbackError?.code === "ABORT_ERR") throw fallbackError;
+      return {
+        ok: false,
+        wrapper: "codex",
+        error: redactSensitiveText(fallbackError instanceof Error ? fallbackError.message : String(fallbackError)),
+        primaryError: redactSensitiveText(error instanceof Error ? error.message : String(error)),
+        stdout: cleanOutput(fallbackError.stdout, 8000),
+        stderr: cleanOutput(fallbackError.stderr, 4000),
+      };
+    }
+  } finally {
+    await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/web.js

@@ -17,7 +17,7 @@ import {
   getProviderDefaults,
   normalizeRoutingMode,
 } from "./src/model-routing.js";
-import { listAgentWrappers, normalizeWrapperName } from "./src/tool-wrappers.js";
+import { isWrapperAvailable, listAgentWrappers, normalizeWrapperName } from "./src/tool-wrappers.js";
 import { getDockerSandboxStatus, getSandboxLogs, runDockerPreflight } from "./src/docker-sandbox.js";
 import { normalizePackageInstallPolicy, normalizeSandboxMode } from "./src/command-policy.js";
 import { summarizeWorkspaceTools, WORKSPACE_TOOL_NAMES } from "./src/workspace-tools.js";
@@ -574,7 +574,11 @@ function normalizePreferencePayload(body = {}, current = db.getPreferences()) {
         ? Math.min(Math.max(parsedParallelScoutCount, 1), 10)
         : Number(current.parallelScoutCount) || 3,
     allowWrapperTools:
-      typeof body.allowWrapperTools === "boolean" ? body.allowWrapperTools : Boolean(current.allowWrapperTools),
+      typeof body.allowWrapperTools === "boolean"
+        ? body.allowWrapperTools
+        : current.allowWrapperTools !== undefined
+          ? Boolean(current.allowWrapperTools)
+          : isWrapperAvailable(normalizeWrapperName(body.preferredWrapper || current.preferredWrapper || "codex")),
     preferredWrapper: normalizeWrapperName(body.preferredWrapper || current.preferredWrapper || "codex"),
     wrapperTimeoutMs:
       Number.isFinite(parsedWrapperTimeoutMs) && parsedWrapperTimeoutMs >= 10000