iterate-plugin 2.8.3 → 2.9.0

package/dist/skill-prompt.js

@@ -12,14 +12,14 @@ You have the iterate plugin installed, which registers these tools:
 - \`iterate_config\` — read iterate.config.yaml (dimensions, validation commands, personalization) or write a validated partial update (operation:"write", with automatic backup + rollback)
 - \`iterate_validate\` — run a whitelisted validation command
 - \`iterate_decision_log\` — append to the decision log, or read entries back for review
-- \`iterate_context\` — read SKILL.md / ITERATE.md project context
+- \`iterate_context\` — read SKILL.md / ITERATE.md project context; also relays user-attached image metadata (e.g. UI screenshots, error dialogs) so reviewers can treat them as visual evidence
 - \`iterate_review\` — deterministic review engine: \`plan\` builds the review plan (for \`review.scope: changed-only\`, it resolves the git-diff file set against \`git.target_branch\` and auto-falls back to \`full\` when nothing changed); \`aggregate\` dedupes/merges findings, validates every finding against the findings schema when \`reviewer.output_schema_validation\` is on (dropping invalid entries and reporting them via \`schemaValidation\`), and computes convergence; \`meta-review\` audits a built report for internal consistency (counts, buckets, sorting, convergence math) and returns a final report with an \`approved\` / \`needs_revision\` verdict. Purely computational.
 - \`iterate_triage\` — manage "known_intentional" entries in the config (list / apply, with dedupe + backup + rollback)
 - \`iterate_fix\` — apply ONE atomic fix: backs up the file, enforces the atomic max_lines threshold, writes the new content, and records the fix (id + diff summary) in \`.iterate/fixes/registry.json\`
 - \`iterate_diff\` — show the accumulated diff for a fixed file (vs its original backup) or a per-file summary of all fixes
 - \`iterate_rollback\` — revert a fix by id: restore the file from its backup, remove the fix from the registry, log a \`revert\` entry. Use when a round's validation fails
 - \`iterate_checkpoint\` — save / load / clear an iteration checkpoint (\`.iterate/checkpoint.json\`) so a long run can resume where it left off
-- \`iterate_status\` — summarize the current run: mode, round, fixes applied, architectural remaining, decision-log size, checkpoint presence
+- \`iterate_status\` — summarize the current run: mode, round, fixes applied, architectural remaining, decision-log size, checkpoint presence, and whether the run was interrupted (a checkpoint left on disk means the previous run was interrupted and can be resumed)
 - \`iterate_history\` — inspect the runtime state in detail: decision-log entries and applied fixes (optionally scoped to a round or a fixed file)
 - \`iterate_prune\` — remove stale runtime artifacts (\`.iterate/\` entries). Defaults to a read-only dry-run that reports what WOULD be removed; pass \`dryRun:false\` to actually prune.
 
@@ -30,13 +30,26 @@ When the user asks to review or iterate on the project (e.g. "review this projec
 
 ### Workflow script contract
 Write a plain-JS script (top-level await, ends with \`return <json>\`). Available globals:
-- \`agent(prompt, opts?): Promise<value>\` — spawn a subagent. \`opts.schema\` gives structured output (object-rooted JSON Schema: type/properties/required/additionalProperties/items/enum/const/oneOf only). Resolves \`null\` on child failure. Other opts: \`label\`, \`phase\`.
+- \`agent(prompt, opts?): Promise<value>\` — spawn a subagent. \`opts.schema\` gives structured output (object-rooted JSON Schema: type/properties/required/additionalProperties/items/enum/const/oneOf only). Resolves \`null\` on child failure. Other opts: \`label\`, \`phase\`. Backend selection (optional): pass \`provider\` (e.g. \`"codex"\`, \`"claude"\`, \`"default"\`) to route the sub-agent to a specific provider backend, and/or \`model\` to pin a model id. When omitted, the sub-agent uses the same provider/model as the parent session.
 - \`parallel(thunks): Promise<value[]>\` — run zero-arg async functions concurrently, await all.
 - \`phase(title)\`, \`log(message)\` — progress narration.
 - \`args\` — the args object passed to the workflow tool.
 
 The script CANNOT call tools directly. Subagents are the ones who call tools.
 
+### Sub-agent backend selection
+Every \`agent()\` call may carry a backend hint via \`opts.provider\` / \`opts.model\`. Use it deliberately to balance cost, speed, and reliability:
+- **Reviewers** (many, run in parallel, read-only, benefit from strict JSON): prefer a fast/cheap model when one is configured; otherwise omit the hint and inherit the session backend.
+- **Fixers / aggregators** (few, must be reliable and follow tool results exactly): keep them on the parent's default backend unless a specific provider is known-good.
+- **Never invent a provider/model name.** Pass a hint ONLY when the deployment actually registers that adapter (see \`ih config\` / the configured provider list). When in doubt, omit \`provider\`/\`model\` entirely — the sub-agent then runs on the same backend as the parent session, which is always a safe default.
+- The optional \`args.subagentProvider\` / \`args.subagentModel\` allow the caller to override the whole run's sub-agent backend from the invocation; the canonical scripts below read them and spread the hint onto every spawned sub-agent (reviewers, fixers, validators, aggregators).
+
+### User-attached image evidence
+The user may attach images to the conversation (UI screenshots, error dialogs, design references, logs-as-pictures). When they do:
+- You see those images natively in the session. Capture their metadata and pass it into the workflow via \`args.attachments\` — an array of objects, each with optional \`name\`, \`mediaType\`, \`width\`, \`height\`, and a \`note\` describing what the image shows and why it matters for this review.
+- The canonical scripts below read \`args.attachments\` and relay them into every reviewer prompt so reviewers treat the attached visuals as evidence (e.g. "the screenshot in this message shows the broken layout the review should reproduce").
+- If a reviewer needs the images relayed explicitly, it can call \`iterate_context\` with \`attachments\` to get the normalized image descriptions in its context. Never fabricate an attachment — only relay images the user actually attached.
+
 ### Dry-run mode workflow (pure review — the ONLY mode that never touches files)
 This is iterate's read-only health-check: repeated review rounds until findings converge,
 then produce an auditable report, then audit the report itself (meta-review) and give a
@@ -46,9 +59,15 @@ Canonical script — reproduce this structure exactly (adjust dims via the plan)
 
 \`\`\`js
 phase('plan')
+// Optional per-run backend override for sub-agents (omit to inherit the session backend).
+const subAgentProvider = (args && args.subagentProvider) || undefined
+const subAgentModel = (args && args.subagentModel) || undefined
+const backend = Object.assign({}, subAgentProvider ? { provider: subAgentProvider } : {}, subAgentModel ? { model: subAgentModel } : {})
+// User-attached image evidence relayed into reviewer prompts (metadata only).
+const attachments = (args && Array.isArray(args.attachments)) ? args.attachments : []
 const planRes = await agent(
   'Call iterate_review({operation:"plan", mode:"dry-run"}) and return the plan JSON.',
-  { label: 'review:plan' }
+  Object.assign({ label: 'review:plan' }, backend)
 )
 const plan = (planRes && planRes.plan) ? planRes.plan : null
 if (!plan || !Array.isArray(plan.dimensions)) throw new Error('plan failed: iterate_review did not return a valid plan')
@@ -70,16 +89,18 @@ for (let r = 1; r <= maxRounds; r++) {
       ? '\\nSTRICT JSON REQUIRED: your previous output failed schema validation. Return ONLY a JSON object {"findings":[...]} where EVERY finding has dimension, file, line (non-negative integer; 0 = whole-file), severity (critical|high|medium|low), summary, failure_scenario, suggested_fix, is_atomic (boolean).'
       : ''
     const raw = await parallel(dims.map(dim => () => agent(
-      'Review dimension "' + dim + '". Already-known findings (do NOT re-report): ' +
+      'Review dimension "' + dim + '".' +
+      (attachments.length > 0 ? ' User-attached images are part of the evidence (reproduce/verify against them): ' + JSON.stringify(attachments) + '.' : '') +
+      ' Already-known findings (do NOT re-report): ' +
       JSON.stringify(known) + nudge + '\\nReturn the findings JSON object.',
-      { label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }
+      Object.assign({ label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }, backend)
     )))
     const thisRound = { round: r, findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])) }
     if (rounds.length >= r) rounds[r - 1] = thisRound; else rounds.push(thisRound)
     // Deterministic aggregate: cross-round dedupe + known_intentional filter + severity sort.
     agg = await agent(
       'Call iterate_review({operation:"aggregate", mode:"dry-run", rounds:' + JSON.stringify(rounds) + ', maxReviewRounds:' + maxRounds + ', knownIntentional:' + JSON.stringify(knownIntentional) + '}) and return the report JSON.',
-      { label: 'review:aggregate:r' + r }
+      Object.assign({ label: 'review:aggregate:r' + r }, backend)
     )
     // reviewer.output_schema_validation (default on): aggregate returns per-round
     // schemaValidation; retry the just-finished round (≤2 times) when invalid.
@@ -103,20 +124,20 @@ for (let r = 1; r <= maxRounds; r++) {
 phase('report')
 const finalAgg = await agent(
   'Call iterate_review({operation:"aggregate", mode:"dry-run", rounds:' + JSON.stringify(rounds) + ', maxReviewRounds:' + maxRounds + ', knownIntentional:' + JSON.stringify(knownIntentional) + '}) and return the report JSON.',
-  { label: 'review:aggregate:final' }
+  Object.assign({ label: 'review:aggregate:final' }, backend)
 )
 const report = (finalAgg && finalAgg.report) ? finalAgg.report : null
 if (!report || !report.convergence) throw new Error('aggregate failed: no valid report was produced')
 await agent(
   'Call iterate_decision_log({operation:"append", type:"report", round:' + report.convergence.totalRounds + ', data:{mode:"dry-run", totalFindings:' + report.summary.totalFindings + '}})',
-  { label: 'review:log' }
+  Object.assign({ label: 'review:log' }, backend)
 )
 
 phase('meta-review')
 // Audit the report itself for internal consistency, then produce the final report.
 const metaRes = await agent(
   'Call iterate_review({operation:"meta-review", report:' + JSON.stringify(report) + '}) and return the finalReport JSON.',
-  { label: 'review:meta' }
+  Object.assign({ label: 'review:meta' }, backend)
 )
 const finalReport = metaRes && metaRes.finalReport ? metaRes.finalReport : null
 const metaAudit = finalReport && finalReport.metaReview ? finalReport.metaReview : null
@@ -152,26 +173,42 @@ Set \`args.mode = "normal"\`. Loop: resume → plan → parallel review ×N →
 Canonical script — reproduce this structure exactly (adjust dims via the plan):
 
 \`\`\`js
-// args = { mode: "normal", maxRounds? }
+// args = { mode: "normal", maxRounds?, subagentProvider?, subagentModel?, attachments? }
+// Optional per-run backend override for sub-agents (omit to inherit the session backend).
+const subAgentProvider = (args && args.subagentProvider) || undefined
+const subAgentModel = (args && args.subagentModel) || undefined
+const backend = Object.assign({}, subAgentProvider ? { provider: subAgentProvider } : {}, subAgentModel ? { model: subAgentModel } : {})
+// User-attached image evidence relayed into reviewer prompts (metadata only).
+const attachments = (args && Array.isArray(args.attachments)) ? args.attachments : []
 phase('resume')
 // If a previous run was interrupted, resume from its checkpoint instead of restarting.
 const ckRes = await agent(
   'Call iterate_checkpoint({ operation: "load" }) and return the checkpoint JSON.',
-  { label: 'checkpoint:load' }
+  Object.assign({ label: 'checkpoint:load' }, backend)
 )
 const checkpoint = (ckRes && ckRes.checkpoint) ? ckRes.checkpoint : null
 const startRound = (checkpoint && typeof checkpoint.round === 'number') ? checkpoint.round + 1 : 1
+// Track how many times this checkpoint has already been resumed (interruption recovery).
+const resumeCount = (checkpoint && typeof checkpoint.resumeCount === 'number') ? checkpoint.resumeCount : 0
+if (checkpoint) {
+  // A previous run left a checkpoint — record the recovery so the decision log
+  // shows the resume, then continue where it left off.
+  await agent(
+    'Call iterate_decision_log({operation:"append", type:"resume", round:' + startRound + ', data:{resumedFromRound:' + checkpoint.round + ', resumeCount:' + (resumeCount + 1) + '}})',
+    Object.assign({ label: 'log:resume' }, backend)
+  )
+}
 
 phase('plan')
 const configRes = await agent(
   'Call iterate_config({ validate: true }) and return the config JSON.',
-  { label: 'config:read' }
+  Object.assign({ label: 'config:read' }, backend)
 )
 const cfg = (configRes && configRes.config) ? configRes.config : null
 const atomicMaxLines = (cfg && cfg.atomic && cfg.atomic.max_lines) ? cfg.atomic.max_lines : 20
 const planRes = await agent(
   'Call iterate_review({operation:"plan", mode:"normal", maxReviewRounds:' + (args.maxRounds || 3) + '}) and return the plan JSON.',
-  { label: 'review:plan' }
+  Object.assign({ label: 'review:plan' }, backend)
 )
 const plan = (planRes && planRes.plan) ? planRes.plan : null
 if (!plan || !Array.isArray(plan.dimensions)) throw new Error('plan failed: iterate_review did not return a valid plan')
@@ -198,8 +235,9 @@ for (let r = startRound; r <= maxRounds; r++) {
       : ''
     const raw = await parallel(dims.map(dim => () => agent(
       'Review dimension "' + dim + '" on the CURRENT code state (previous atomic findings are fixed). ' +
+      (attachments.length > 0 ? ' User-attached images are part of the evidence (reproduce/verify against them): ' + JSON.stringify(attachments) + '.' : '') +
       'Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + nudge + '\\nReturn the findings JSON object.',
-      { label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }
+      Object.assign({ label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }, backend)
     )))
     const thisRound = { round: r, findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])) }
     if (rounds.length >= r) rounds[r - 1] = thisRound; else rounds.push(thisRound)
@@ -209,7 +247,7 @@ for (let r = startRound; r <= maxRounds; r++) {
     // show a running "fixes applied" metric for normal mode.
     agg = await agent(
       'Call iterate_review({operation:"aggregate", mode:"normal", rounds:' + JSON.stringify([thisRound]) + ', knownIntentional:' + JSON.stringify(knownIntentional) + ', fixedCount:' + fixedCount + '}) and return the report JSON.',
-      { label: 'review:aggregate:r' + r }
+      Object.assign({ label: 'review:aggregate:r' + r }, backend)
     )
     // reviewer.output_schema_validation (default on): aggregate returns per-round
     // schemaValidation; retry the just-finished round (≤2 times) when invalid.
@@ -239,12 +277,12 @@ for (let r = startRound; r <= maxRounds; r++) {
       'iterate_fix({ file: "' + file + '", content: <full new file content>, finding: <that finding>, round: ' + r + ' }). ' +
       'Apply the findings IN ORDER. After all fixes, call iterate_diff({ file: "' + file + '" }) to verify the accumulated diff. ' +
       'Findings: ' + JSON.stringify(byFile[file]) + '. Return the array of {id, ok, error} per iterate_fix call.',
-      { label: 'fix:' + file, phase: 'fix', schema: {
+      Object.assign({ label: 'fix:' + file, phase: 'fix', schema: {
         type: 'object', additionalProperties: false,
         properties: {
           fixes: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { id: { type: 'string' }, ok: { type: 'boolean' }, error: { type: 'string' } }, required: ['id', 'ok'] } }
         },
-        required: ['fixes'] } }
+        required: ['fixes'] } }, backend)
     )))
     for (const res of fixRes) {
       if (res && Array.isArray(res.fixes)) {
@@ -266,12 +304,12 @@ for (let r = startRound; r <= maxRounds; r++) {
   const valRes = await agent(
     'Read iterate.config.yaml validation.commands, then call iterate_validate({ command: <cmd> }) for EACH configured command ' +
     '(one tool call per command). Return all results as {command, exitCode} entries.',
-    { label: 'validate:r' + r, phase: 'validate', schema: {
+    Object.assign({ label: 'validate:r' + r, phase: 'validate', schema: {
       type: 'object', additionalProperties: false,
       properties: {
         results: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { command: { type: 'string' }, exitCode: { type: 'integer' } }, required: ['command', 'exitCode'] } }
       },
-      required: ['results'] } }
+      required: ['results'] } }, backend)
   )
   failedCommands = (valRes && Array.isArray(valRes.results)) ? valRes.results.filter(v => v.exitCode !== 0).map(v => v.command) : []
   if (failedCommands.length > 0) {
@@ -280,17 +318,17 @@ for (let r = startRound; r <= maxRounds; r++) {
     if (roundFixIds.length > 0) {
       await agent(
         'Call iterate_rollback({ id: <id> }) for EACH of these fix ids (one call per id): ' + JSON.stringify(roundFixIds) + '. Return the array of {id, ok, error}.',
-        { label: 'rollback:r' + r, phase: 'rollback', schema: {
+        Object.assign({ label: 'rollback:r' + r, phase: 'rollback', schema: {
           type: 'object', additionalProperties: false,
           properties: {
             results: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { id: { type: 'string' }, ok: { type: 'boolean' }, error: { type: 'string' } }, required: ['id', 'ok'] } }
           },
-          required: ['results'] } }
+          required: ['results'] } }, backend)
       )
     }
     await agent(
       'Call iterate_decision_log({operation:"append", type:"round_failed", round:' + r + ', data:{failedCommands:' + JSON.stringify(failedCommands) + ', rolledBack:' + roundFixIds.length + '}})',
-      { label: 'log:failed:r' + r }
+      Object.assign({ label: 'log:failed:r' + r }, backend)
     )
     break
   }
@@ -298,13 +336,13 @@ for (let r = startRound; r <= maxRounds; r++) {
   await agent(
     'Call iterate_decision_log({operation:"append", type:"review_result", round:' + r +
     ', data:{atomic:' + atomic.length + ', architectural:' + remaining.length + ', fixedSoFar:' + fixedCount + '}})',
-    { label: 'log:r' + r }
+    Object.assign({ label: 'log:r' + r }, backend)
   )
 
   // Persist progress so an interrupted run can resume from the next round.
   await agent(
-    'Call iterate_checkpoint({ operation: "save", mode: "normal", round:' + r + ', maxRounds:' + maxRounds + ', fixedCount:' + fixedCount + ', architecturalCount:' + architectural.length + ', findings:' + JSON.stringify(architectural) + ' }) and return the checkpoint JSON.',
-    { label: 'checkpoint:save:r' + r }
+    'Call iterate_checkpoint({ operation: "save", mode: "normal", round:' + r + ', maxRounds:' + maxRounds + ', fixedCount:' + fixedCount + ', architecturalCount:' + architectural.length + ', resumeCount:' + resumeCount + ', findings:' + JSON.stringify(architectural) + ' }) and return the checkpoint JSON.',
+    Object.assign({ label: 'checkpoint:save:r' + r }, backend)
   )
 
   if (atomic.length === 0 && remaining.length === 0) {

package/dist/tools/checkpoint.js

@@ -51,6 +51,10 @@ export function validateCheckpoint(input) {
     if (typeof input.architecturalCount !== 'number' || !Number.isInteger(input.architecturalCount) || input.architecturalCount < 0) {
         return 'architecturalCount must be a non-negative integer';
     }
+    if (input.resumeCount !== undefined &&
+        (typeof input.resumeCount !== 'number' || !Number.isInteger(input.resumeCount) || input.resumeCount < 0)) {
+        return 'resumeCount must be a non-negative integer';
+    }
     return null;
 }
 /**
@@ -88,6 +92,10 @@ export function computeStatus(input) {
         findingsCount: checkpoint?.findings.length ?? 0,
         totalDecisionLogEntries: entries.length,
         hasCheckpoint: checkpoint !== null,
+        // A checkpoint left on disk means the previous run was interrupted before
+        // it could clear it — this is the durable "interruption" signal.
+        interrupted: checkpoint !== null,
+        resumeCount: checkpoint?.resumeCount ?? 0,
         checkpoint,
         lastUpdated,
     };
@@ -114,6 +122,7 @@ export function registerCheckpointTool(ctx) {
             maxRounds: { type: 'integer', description: 'Required for save: total round cap.' },
             fixedCount: { type: 'integer', description: 'Required for save: number of fixes applied so far.' },
             architecturalCount: { type: 'integer', description: 'Required for save: architectural findings left unfixed.' },
+            resumeCount: { type: 'integer', description: 'Optional for save: how many times this checkpoint has already been resumed after an interruption (default 0).' },
             findings: { type: 'json', description: 'Optional for save: the current deduped findings to resume from.' },
             path: { type: 'string', description: 'Project root directory (default: current working directory).' },
         },
@@ -161,6 +170,7 @@ export function registerCheckpointTool(ctx) {
                     maxRounds: args.maxRounds,
                     fixedCount: args.fixedCount,
                     architecturalCount: args.architecturalCount,
+                    resumeCount: args.resumeCount,
                 });
                 if (invalid)
                     return { operation: 'save', ok: false, error: invalid };
@@ -170,6 +180,7 @@ export function registerCheckpointTool(ctx) {
                     maxRounds: args.maxRounds,
                     fixedCount: args.fixedCount,
                     architecturalCount: args.architecturalCount,
+                    resumeCount: (typeof args.resumeCount === 'number' ? args.resumeCount : 0),
                     findings: (Array.isArray(args.findings) ? args.findings : []),
                     startedAt: readCheckpoint(projectRoot)?.startedAt ?? new Date().toISOString(),
                     updatedAt: new Date().toISOString(),
@@ -214,6 +225,8 @@ export function registerStatusTool(ctx) {
                     findingsCount: { type: 'integer' },
                     totalDecisionLogEntries: { type: 'integer' },
                     hasCheckpoint: { type: 'boolean' },
+                    interrupted: { type: 'boolean', description: 'True when a checkpoint exists, meaning the previous run was interrupted before finishing.' },
+                    resumeCount: { type: 'integer', description: 'How many times the current checkpoint has already been resumed.' },
                     lastUpdated: { type: 'string' },
                     error: { type: 'string' },
                 },
@@ -227,7 +240,7 @@ export function registerStatusTool(ctx) {
                     `Fixed: ${value.fixedCount} · Architectural remaining: ${value.architecturalCount}`,
                     `Findings in checkpoint: ${value.findingsCount}`,
                     `Decision-log entries: ${value.totalDecisionLogEntries}`,
-                    `Checkpoint: ${value.hasCheckpoint ? 'yes' : 'no'}`,
+                    `Checkpoint: ${value.hasCheckpoint ? 'yes' : 'no'}${value.interrupted ? ' (interrupted — resumable)' : ''}${value.resumeCount ? ` · resumed ${value.resumeCount}x` : ''}`,
                     value.lastUpdated ? `Last updated: ${value.lastUpdated}` : '',
                 ];
                 return [{ type: 'text', text: lines.filter(Boolean).join('\n') }];
@@ -253,6 +266,8 @@ export function registerStatusTool(ctx) {
                 findingsCount: status.findingsCount,
                 totalDecisionLogEntries: status.totalDecisionLogEntries,
                 hasCheckpoint: status.hasCheckpoint,
+                interrupted: status.interrupted,
+                resumeCount: status.resumeCount,
                 lastUpdated: status.lastUpdated ?? undefined,
             };
         },

package/dist/tools/context.js

@@ -5,6 +5,87 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import { resolveProjectRoot } from "../config-loader.js";
 /** How many ancestor directories we walk up looking for a SKILL.md. */
 const MAX_SKILL_DIR_LOOKUP_DEPTH = 12;
+/** Maximum number of image attachments relayed into the context in one call. */
+const MAX_ATTACHMENTS = 8;
+/**
+ * Validate and normalize one raw image-attachment entry passed by the
+ * orchestrator. The top-level model observes user-attached images in its own
+ * context (as image blocks) and relays their metadata here so reviewers get the
+ * same visual evidence. Pure — exported for unit tests.
+ */
+export function normalizeAttachment(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { ok: false, error: 'attachment must be an object' };
+    }
+    const entry = raw;
+    const out = {};
+    if (entry.name !== undefined) {
+        if (typeof entry.name !== 'string' || entry.name.length > 256) {
+            return { ok: false, error: 'attachment.name must be a string (≤ 256 chars)' };
+        }
+        out.name = entry.name;
+    }
+    if (entry.mediaType !== undefined) {
+        if (typeof entry.mediaType !== 'string' || !/^image\/(png|jpeg|webp|gif)$/.test(entry.mediaType)) {
+            return { ok: false, error: 'attachment.mediaType must be image/png, image/jpeg, image/webp, or image/gif' };
+        }
+        out.mediaType = entry.mediaType;
+    }
+    for (const dim of ['width', 'height']) {
+        if (entry[dim] !== undefined) {
+            if (typeof entry[dim] !== 'number' || !Number.isInteger(entry[dim]) || entry[dim] < 0 || entry[dim] > 16384) {
+                return { ok: false, error: `attachment.${dim} must be an integer in [0, 16384]` };
+            }
+            out[dim] = entry[dim];
+        }
+    }
+    if (entry.note !== undefined) {
+        if (typeof entry.note !== 'string' || entry.note.length > 1000) {
+            return { ok: false, error: 'attachment.note must be a string (≤ 1000 chars)' };
+        }
+        out.note = entry.note;
+    }
+    return { ok: true, value: out };
+}
+/**
+ * Validate a whole attachments array, dropping invalid entries.
+ * Returns the normalized list plus the reasons for any dropped entries.
+ */
+export function normalizeAttachments(raw) {
+    const attachments = [];
+    const errors = [];
+    if (raw === undefined || raw === null)
+        return { attachments, errors };
+    if (!Array.isArray(raw))
+        return { attachments, errors: ['attachments must be an array'] };
+    for (let i = 0; i < raw.length; i++) {
+        if (attachments.length >= MAX_ATTACHMENTS) {
+            errors.push(`attachments capped at ${MAX_ATTACHMENTS}; entry ${i} dropped`);
+            break;
+        }
+        const result = normalizeAttachment(raw[i]);
+        if (result.ok)
+            attachments.push(result.value);
+        else
+            errors.push(`attachments[${i}]: ${result.error}`);
+    }
+    return { attachments, errors };
+}
+/**
+ * Render a normalized attachment as a compact text block for the model.
+ */
+export function renderAttachment(a, index) {
+    const bits = [`[${index + 1}]`];
+    if (a.name)
+        bits.push(a.name);
+    if (a.mediaType)
+        bits.push(a.mediaType);
+    if (typeof a.width === 'number' && typeof a.height === 'number')
+        bits.push(`${a.width}x${a.height}`);
+    if (a.note)
+        bits.push(a.note);
+    return bits.join(' · ');
+}
 /**
  * The directory this source file lives in (…/src/tools). The plugin's own
  * package root is one level up (…/src), and the skill root is typically a few
@@ -82,7 +163,9 @@ export function registerContextTool(ctx) {
             'SKILL.md contains the original iterate skill instructions; it is searched in ' +
             'the skill directory (auto-detected), the project root, or an explicit `skillDir`. ' +
             'ITERATE.md contains the project-specific knowledge base and onboarding information. ' +
-            'Use this to understand the skill workflow and project context.',
+            'Also relays user-attached image metadata (e.g. UI screenshots, error dialogs) into ' +
+            'the review context so reviewers can treat them as visual evidence. ' +
+            'Use this to understand the skill workflow, project context, and any attached visuals.',
         parameters: {
             files: {
                 type: 'string',
@@ -98,6 +181,24 @@ export function registerContextTool(ctx) {
                 description: 'Custom directory to search for SKILL.md (highest priority). ' +
                     'When omitted, SKILL.md is auto-detected from the skill directory, then the project root.',
             },
+            attachments: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        name: { type: 'string', description: 'Optional display name of the attached image.' },
+                        mediaType: { type: 'string', enum: ['image/png', 'image/jpeg', 'image/webp', 'image/gif'], description: 'Optional media type of the image.' },
+                        width: { type: 'integer', description: 'Optional intrinsic width in pixels.' },
+                        height: { type: 'integer', description: 'Optional intrinsic height in pixels.' },
+                        note: { type: 'string', description: 'Optional short description of what the image shows and why it matters for this review.' },
+                    },
+                },
+                description: 'Optional: image attachments observed in the session (e.g. UI screenshots, error ' +
+                    'dialogs, design references) relayed into the review context. The top-level model ' +
+                    'sees these images natively and passes their metadata here so reviewers get the same ' +
+                    'visual evidence. Up to 8 entries; invalid entries are dropped and reported.',
+            },
         },
         output: {
             schema: {
@@ -110,6 +211,8 @@ export function registerContextTool(ctx) {
                     skillSource: { oneOf: [{ type: 'string' }, { type: 'null' }] },
                     error: { type: 'string' },
                     searched: { type: 'array', items: { type: 'string' } },
+                    attachments: { type: 'array', items: { type: 'string' }, description: 'Normalized attached-image descriptions relayed to reviewers.' },
+                    attachmentErrors: { type: 'array', items: { type: 'string' }, description: 'Reasons for any attachment entries that were dropped.' },
                 },
             },
             render: (_args, value) => {
@@ -118,9 +221,15 @@ export function registerContextTool(ctx) {
                     parts.push(`--- SKILL.md (${value.skillSource ?? '?source?'}) ---\n${value.skill}`);
                 if (value.project)
                     parts.push(`--- ITERATE.md ---\n${value.project}`);
-                if (!value.skill && !value.project) {
+                if (Array.isArray(value.attachments) && value.attachments.length > 0) {
+                    parts.push(`--- User-attached images (${value.attachments.length}) ---\n${value.attachments.join('\n')}`);
+                }
+                if (!value.skill && !value.project && !(Array.isArray(value.attachments) && value.attachments.length > 0)) {
                     parts.push('No files found. Searched: ' + (value.searched?.join(', ') ?? 'none'));
                 }
+                if (Array.isArray(value.attachmentErrors) && value.attachmentErrors.length > 0) {
+                    parts.push('Attachment warnings: ' + value.attachmentErrors.join('; '));
+                }
                 return [{ type: 'text', text: parts.join('\n\n') }];
             },
         },
@@ -135,6 +244,16 @@ export function registerContextTool(ctx) {
                 .map((s) => s.trim().toLowerCase())
                 .filter(Boolean);
             const result = { found: true, searched: [] };
+            // Relay user-attached image metadata into the review context. The
+            // orchestrator observes attached images in the session and passes their
+            // metadata here; invalid entries are dropped with a reported reason.
+            const attachments = normalizeAttachments(args.attachments);
+            if (attachments.attachments.length > 0) {
+                result.attachments = attachments.attachments.map(renderAttachment);
+            }
+            if (attachments.errors.length > 0) {
+                result.attachmentErrors = attachments.errors;
+            }
             if (requested.includes('skill') || requested.includes('skill.md')) {
                 // Candidate dirs in priority order: custom path → auto-detected skill
                 // root → project root. This is how "skill 目录、项目根、自定义路径"

package/dist/tools/decision-log.js

@@ -15,6 +15,7 @@ const VALID_ENTRY_TYPES = new Set([
     'validation',
     'decision',
     'report',
+    'resume',
 ]);
 /**
  * Validate a candidate (type, round, data) triple for an append operation.
@@ -101,7 +102,7 @@ export function registerDecisionLogTool(ctx) {
             type: {
                 type: 'string',
                 description: 'Entry type (required for append): round_start, review_result, atomic_fix, ' +
-                    'architectural_fix, revert, round_failed, validation, decision, report.',
+                    'architectural_fix, revert, round_failed, validation, decision, report, resume.',
                 enum: [
                     'round_start',
                     'review_result',
@@ -112,6 +113,7 @@ export function registerDecisionLogTool(ctx) {
                     'validation',
                     'decision',
                     'report',
+                    'resume',
                 ],
             },
             round: {

package/lib/client.js

@@ -43,6 +43,101 @@ var SEVERITY_COLOR = {
   medium: "#eab308",
   low: "#6b7280"
 };
+function scanSessionForResume(obj, seen, maxDepth = 20) {
+  if (maxDepth <= 0) return 0;
+  if (!obj || typeof obj !== "object") return 0;
+  const s = seen || /* @__PURE__ */ new Set();
+  if (s.has(obj)) return 0;
+  s.add(obj);
+  let best = 0;
+  const direct = (
+    /** @type {Record<string, unknown>} */
+    obj
+  );
+  if (direct.type === "resume") {
+    const data = (
+      /** @type {Record<string, unknown>} */
+      direct.data || {}
+    );
+    if (typeof data.resumeCount === "number" && data.resumeCount > best) {
+      best = data.resumeCount;
+    }
+  }
+  if (direct.entry && typeof direct.entry === "object") {
+    const entry = (
+      /** @type {Record<string, unknown>} */
+      direct.entry
+    );
+    if (entry.type === "resume") {
+      const data = (
+        /** @type {Record<string, unknown>} */
+        entry.data || {}
+      );
+      if (typeof data.resumeCount === "number" && data.resumeCount > best) {
+        best = data.resumeCount;
+      }
+    }
+  }
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      const found = scanSessionForResume(item, s, maxDepth - 1);
+      if (found > best) best = found;
+    }
+    return best;
+  }
+  for (const key of Object.keys(direct)) {
+    const val = direct[key];
+    if (val && typeof val === "object") {
+      const found = scanSessionForResume(val, s, maxDepth - 1);
+      if (found > best) best = found;
+    }
+  }
+  return best;
+}
+function countSessionImages(session) {
+  if (!session || typeof session !== "object") return 0;
+  const ids = /* @__PURE__ */ new Set();
+  let count = 0;
+  const walk = (obj, depth) => {
+    if (depth <= 0 || !obj || typeof obj !== "object") return;
+    if (seen.has(obj)) return;
+    seen.add(obj);
+    const o = (
+      /** @type {Record<string, unknown>} */
+      obj
+    );
+    let ref = null;
+    if (o.type === "image" && o.attachment && typeof o.attachment === "object") {
+      ref = /** @type {Record<string, unknown>} */
+      o.attachment;
+    }
+    if (!ref && typeof o.mediaType === "string" && String(o.mediaType).startsWith("image/")) {
+      ref = o;
+    }
+    if (ref) {
+      const id = typeof ref.attachmentId === "string" ? ref.attachmentId : null;
+      if (id) {
+        if (!ids.has(id)) {
+          ids.add(id);
+          count += 1;
+        }
+      } else {
+        count += 1;
+      }
+    }
+    if (Array.isArray(obj)) {
+      for (const item of obj) walk(item, depth - 1);
+      return;
+    }
+    for (const key of Object.keys(o)) {
+      const val = o[key];
+      if (val && typeof val === "object") walk(val, depth - 1);
+    }
+  };
+  const seen = /* @__PURE__ */ new Set();
+  walk(session, 12);
+  return count;
+}
 function isReviewReport(obj) {
   if (!obj || typeof obj !== "object") return false;
   const o = (
@@ -827,6 +922,10 @@ var ITERATE_CSS = `
 .iterate-pill { display: inline-flex; align-items: center; gap: 7px; padding: 3px 11px; border-radius: 999px; font-size: 11px; font-weight: 600; white-space: nowrap; color: var(--dsw-alias-state-success-primary); background: color-mix(in srgb, var(--dsw-alias-state-success-primary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-state-success-primary) 28%, transparent); }
 .iterate-pill-dot { width: 6px; height: 6px; border-radius: 50%; background: currentColor; }
 
+/* Interruption / resume + attachment chips (dashboard) */
+.iterate-chip-resume { display: inline-flex; align-items: center; gap: 6px; padding: 3px 10px; border-radius: 999px; font-size: 11px; font-weight: 600; white-space: nowrap; color: var(--dsw-alias-state-warn-primary); background: color-mix(in srgb, var(--dsw-alias-state-warn-primary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-state-warn-primary) 28%, transparent); }
+.iterate-chip-images { display: inline-flex; align-items: center; gap: 6px; padding: 3px 10px; border-radius: 999px; font-size: 11px; font-weight: 600; white-space: nowrap; color: var(--dsw-alias-brand-primary); background: color-mix(in srgb, var(--dsw-alias-brand-primary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-brand-primary) 28%, transparent); }
+
 /* Accessibility-switch toggle */
 .iterate-switch { position: relative; width: 42px; height: 24px; border-radius: 999px; padding: 0; cursor: pointer; background: var(--dsw-alias-bg-layer-2); border: 1px solid var(--dsw-alias-border-l1); transition: background-color 160ms ease, border-color 160ms ease; }
 .iterate-switch:focus-visible { outline: 2px solid var(--dsw-alias-brand-primary); outline-offset: 2px; }
@@ -1010,6 +1109,18 @@ function ConvergenceDashboard(props) {
   const stats = severityStats(report);
   const dims = groupByDimension(report);
   const trend = computeTrendMetrics(report);
+  const resumeCount = scanSessionForResume(session);
+  const imageCount = countSessionImages(session);
+  const resumeChip = resumeCount > 0 ? React.createElement("span", {
+    className: "iterate-chip-resume",
+    key: "resume",
+    title: "\u672C\u6B21\u8FED\u4EE3\u4ECE\u4E0A\u4E00\u6B21\u4E2D\u65AD\u7684\u65AD\u70B9\u7EE7\u7EED\u6267\u884C"
+  }, `\u5DF2\u4E2D\u65AD\u6062\u590D \xD7${String(resumeCount)}`) : null;
+  const imageChip = imageCount > 0 ? React.createElement("span", {
+    className: "iterate-chip-images",
+    key: "images",
+    title: "\u4F1A\u8BDD\u4E2D\u68C0\u6D4B\u5230\u7528\u6237\u9644\u5E26\u7684\u56FE\u7247\uFF0C\u8BC4\u5BA1\u5C06\u4F5C\u4E3A\u89C6\u89C9\u8BC1\u636E\u53C2\u8003"
+  }, `\u9644\u4EF6\u56FE\u7247 ${String(imageCount)}`) : null;
   const dimBadges = Object.keys(dims).slice(0, 6).map(
     (dim) => React.createElement(
       "span",
@@ -1058,6 +1169,8 @@ function ConvergenceDashboard(props) {
       stats.medium
     ),
     fixBadge,
+    resumeChip,
+    imageChip,
     React.createElement(TrendChart, { points: trend.points }),
     ...dimBadges
   );