kc-beta 0.7.3 → 0.8.1

package/src/agent/tools/release.js

@@ -85,13 +85,19 @@ export class ReleaseTool extends BaseTool {
       return new ToolResult(`release template missing at ${TEMPLATE_DIR}`, true);
     }
 
-    // 1. Snapshot first — locks in commit + tag, regardless of whether bundle build succeeds
-    const snapResult = await this._snapshot.execute({
-      label: `release-${slug}`,
-      notes: `Release ${label} bundle source`,
-    });
-    if (snapResult.isError) return new ToolResult(`snapshot failed: ${snapResult.content}`, true);
-    const { tag: snapshotTag, commit: snapshotCommit } = this._readSnapshotMeta(`release-${slug}`);
+    // v0.8.1 P9-C: defer the snapshot (git tag) until AFTER the bundle
+    // is written + verified. v0.8.0 ordered snapshot-first to "lock in
+    // commit + tag regardless of bundle outcome," but E2E #11 资管 v0.8
+    // audit found `release-v1` tags with no corresponding bundle dir —
+    // tag without bundle confuses downstream consumers. New order:
+    //   1. Build bundle (catalog read, copy template, write fixtures, manifest, README)
+    //   2. Verify bundle (manifest.json + README.md exist + non-empty)
+    //   3. ONLY THEN snapshot (creates the git tag) + back-fill manifest
+    //      with snapshot tag/commit
+    // If verification fails, a `.failed_release` marker is written into
+    // the bundle dir and NO tag is created.
+    let snapshotTag = null;
+    let snapshotCommit = null;
 
     // 2. Read catalog and filter
     const catalogPath = path.join(this._workspace.cwd, "rules", "catalog.json");
@@ -185,8 +191,23 @@ export class ReleaseTool extends BaseTool {
     // file through and emitted a stub on miss. We try to populate from
     // known QC artifact shapes here; if nothing matches, fall through
     // to the existing stub fallback.
+    // v0.7.5 G-H3: aggregator now runs if calibSrc is MISSING **or** has
+    // empty `historical_accuracy`. v0.7.4 audit (both 贷款 + 资管) shipped
+    // empty stubs despite QC data on disk — root cause was the v0.7.2
+    // gate only checked file existence; a stub written earlier (e.g., on
+    // finalization phase entry) kept the aggregator from firing later.
     const calibSrc = path.join(this._workspace.cwd, "confidence_calibration.json");
-    if (!fs.existsSync(calibSrc)) {
+    let shouldAggregate = !fs.existsSync(calibSrc);
+    if (!shouldAggregate) {
+      try {
+        const existing = JSON.parse(fs.readFileSync(calibSrc, "utf-8"));
+        const ha = existing?.historical_accuracy;
+        if (!ha || (typeof ha === "object" && Object.keys(ha).length === 0)) {
+          shouldAggregate = true;
+        }
+      } catch { shouldAggregate = true; } // corrupt → re-aggregate
+    }
+    if (shouldAggregate) {
       const aggregated = this._aggregateAccuracyFromOutput();
       if (aggregated && Object.keys(aggregated.historical_accuracy).length > 0) {
         fs.writeFileSync(calibSrc, JSON.stringify(aggregated, null, 2) + "\n", "utf-8");
@@ -247,6 +268,14 @@ export class ReleaseTool extends BaseTool {
       .replace(/\{RULES_LIST\}/g, rulesList);
     fs.writeFileSync(path.join(bundleAbs, "README.md"), readme, "utf-8");
 
+    // v0.7.5 G-H4: sweep any leftover `.tmpl` files from the bundle dir.
+    // template/release/v1/ contains manifest.json.tmpl, catalog.json.tmpl,
+    // README.md.tmpl. _copyDir's exclude list (line 119) only filters
+    // README.md.tmpl; the other two ride along and persist alongside their
+    // populated counterparts. Audit (v0.7.4 贷款) confirmed this regression
+    // of v0.7.2 G1d which only handled the v1/ scaffold case.
+    this._sweepTmplFiles(bundleAbs);
+
     // v0.7.2 1d: clean up the template scaffold dir if a customized
     // release was just written alongside it. Both v0.7.1 audit runs
     // shipped with `output/releases/v1/` (template-derived, .tmpl
@@ -271,6 +300,77 @@ export class ReleaseTool extends BaseTool {
       }
     }
 
+    // v0.8.1 P9-C: bundle verification + transactional snapshot.
+    // The manifest + README were written above. Verify they exist with
+    // substance (≥200 bytes README, valid JSON manifest with `slug` field).
+    // If verification fails, write `.failed_release` marker and skip
+    // the git-tag step — no tag-without-bundle.
+    const manifestPath = path.join(bundleAbs, "manifest.json");
+    const readmePath = path.join(bundleAbs, "README.md");
+    let verifyError = null;
+    try {
+      const mStat = fs.statSync(manifestPath);
+      const rStat = fs.statSync(readmePath);
+      if (!mStat.isFile() || mStat.size < 50) verifyError = "manifest.json missing or too small";
+      else if (!rStat.isFile() || rStat.size < 200) verifyError = "README.md missing or too small";
+      else {
+        const m = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+        if (m.slug !== slug) verifyError = `manifest.slug=${m.slug} doesn't match expected ${slug}`;
+      }
+    } catch (e) {
+      verifyError = `bundle verification threw: ${e.message}`;
+    }
+
+    if (verifyError) {
+      try {
+        fs.writeFileSync(
+          path.join(bundleAbs, ".failed_release"),
+          JSON.stringify({
+            failed_at: new Date().toISOString(),
+            reason: verifyError,
+            label,
+            slug,
+          }, null, 2),
+        );
+      } catch { /* best-effort */ }
+      return new ToolResult(
+        `Release bundle verification failed (${verifyError}). NO git tag created. ` +
+        `See .failed_release marker in ${bundleRel}/ for details. Fix the bundle issue and re-run.`,
+        true,
+      );
+    }
+
+    // Bundle verified. NOW snapshot — creates the durable git tag.
+    const snapResult = await this._snapshot.execute({
+      label: `release-${slug}`,
+      notes: `Release ${label} bundle source`,
+    });
+    if (snapResult.isError) {
+      // Bundle exists but tagging failed. Surface but don't roll back —
+      // the bundle is still usable; the user can manually tag later.
+      return new ToolResult(
+        `Release '${label}' bundled at ${bundleRel} but snapshot tag FAILED: ${snapResult.content}. ` +
+        `Bundle is valid; create the snapshot tag manually if needed.`,
+      );
+    }
+    const meta = this._readSnapshotMeta(`release-${slug}`);
+    snapshotTag = meta.tag;
+    snapshotCommit = meta.commit;
+
+    // Back-fill the manifest with the now-known snapshot tag/commit.
+    try {
+      const m = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+      m.snapshot_tag = snapshotTag;
+      m.snapshot_commit = snapshotCommit;
+      fs.writeFileSync(manifestPath, JSON.stringify(m, null, 2) + "\n");
+      // Also back-fill the README's snapshot placeholders if still placeholder.
+      const readme = fs.readFileSync(readmePath, "utf-8");
+      const updated = readme
+        .replace(/\(no tag — git unavailable\)/g, snapshotTag || "")
+        .replace(/\(unknown\)/g, snapshotCommit || "(unknown)");
+      if (updated !== readme) fs.writeFileSync(readmePath, updated);
+    } catch { /* best-effort back-fill */ }
+
     // Bundle dir is in output/ (gitignored). Snapshot manifest in snapshots/ IS tracked.
     const lines = [
       `Release '${label}' bundled at ${bundleRel}`,
@@ -303,6 +403,25 @@ export class ReleaseTool extends BaseTool {
     }
   }
 
+  /**
+   * v0.7.5 G-H4: recursively remove any `*.tmpl` files from a directory.
+   * Used after populating a release bundle to drop template stubs that
+   * weren't filtered by the initial copy's exclude list. Idempotent.
+   */
+  _sweepTmplFiles(dir) {
+    try {
+      if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return;
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const entryPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          this._sweepTmplFiles(entryPath);
+        } else if (entry.isFile() && entry.name.endsWith(".tmpl")) {
+          try { fs.unlinkSync(entryPath); } catch { /* best-effort */ }
+        }
+      }
+    } catch { /* best-effort */ }
+  }
+
   _findLatestWorkflow(ruleId) {
     // Canonical: workflows/<ruleId>/workflow_v#.py (subdirectory layout)
     const wfDir = path.join(this._workspace.cwd, "workflows", ruleId);
@@ -338,10 +457,95 @@ export class ReleaseTool extends BaseTool {
           }
         } catch { /* manifest unreadable; skip */ }
       }
+
+      // v0.7.5 G-H2: master / grouped workflow pattern. Agent shipped a
+      // single workflow folder (e.g., workflows/master/ or workflows/
+      // bank_wm_compliance/) declaring `source_rules: [R001, R002, ...]`
+      // in its SKILL.md / workflow.md / config.json. The manifest writer
+      // should credit this rule_id as covered by that workflow.
+      //
+      // Walk workflows/ subdirs looking for a source_rules declaration
+      // that includes this ruleId. Return the first matching workflow file.
+      // Audit (v0.7.4 贷款 session) confirmed manifest under-counted:
+      // catalog had 15 rules; manifest only listed R001 because R002-R015
+      // weren't found as standalone workflows.
+      for (const entry of fs.readdirSync(flatRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        if (entry.name === ruleId) continue; // already checked above
+        const subDir = path.join(flatRoot, entry.name);
+        const declaredRules = this._readWorkflowSourceRules(subDir);
+        if (declaredRules.includes(ruleId)) {
+          // Find the workflow entry file in this dir
+          const subFiles = fs.readdirSync(subDir);
+          const versioned = subFiles.filter((f) => /^workflow_v\d+\.py$/.test(f)).sort();
+          if (versioned.length > 0) return path.join(subDir, versioned[versioned.length - 1]);
+          const any = subFiles.find((f) => f.endsWith(".py"));
+          if (any) return path.join(subDir, any);
+        }
+      }
     }
     return null;
   }
 
+  /**
+   * v0.7.5 G-H2: read a workflow directory's source_rules declaration.
+   * Checks SKILL.md / workflow.md frontmatter (`source_rules: [...]`)
+   * and config.json (`source_rules`, `rules`, or `rule_ids` field).
+   * Returns array of canonical rule IDs.
+   */
+  _readWorkflowSourceRules(workflowDir) {
+    const ids = new Set();
+    try {
+      const files = fs.readdirSync(workflowDir);
+
+      // Frontmatter sources
+      for (const fname of files) {
+        if (!/^(skill|workflow)\.md$/i.test(fname)) continue;
+        let content;
+        try { content = fs.readFileSync(path.join(workflowDir, fname), "utf-8"); } catch { continue; }
+        const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!fmMatch) continue;
+        const fm = fmMatch[1];
+        // Inline form
+        const inlineMatch = fm.match(/^source_rules\s*:\s*\[([^\]]*)\]\s*$/m);
+        if (inlineMatch) {
+          inlineMatch[1].split(",").map(s => s.trim().replace(/^["']|["']$/g, ""))
+            .filter(Boolean).forEach(s => {
+              const m = s.match(/^R0*(\d+)$/i);
+              if (m) ids.add(`R${String(parseInt(m[1], 10)).padStart(3, "0")}`);
+            });
+        }
+        // Block form
+        const blockMatch = fm.match(/^source_rules\s*:\s*\n((?:[ \t]+-\s+\S+\s*\n?)+)/m);
+        if (blockMatch) {
+          blockMatch[1].split("\n").forEach(line => {
+            const m = line.match(/^[ \t]+-\s+["']?(R0*\d+)["']?\s*$/i);
+            if (m) {
+              const n = m[1].match(/R0*(\d+)/i);
+              if (n) ids.add(`R${String(parseInt(n[1], 10)).padStart(3, "0")}`);
+            }
+          });
+        }
+      }
+
+      // Config.json sources
+      const configPath = path.join(workflowDir, "config.json");
+      if (fs.existsSync(configPath)) {
+        try {
+          const data = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+          const rules = Array.isArray(data?.source_rules) ? data.source_rules :
+                        Array.isArray(data?.rules) ? data.rules :
+                        Array.isArray(data?.rule_ids) ? data.rule_ids : [];
+          for (const r of rules) {
+            const m = String(r).match(/^R0*(\d+)$/i);
+            if (m) ids.add(`R${String(parseInt(m[1], 10)).padStart(3, "0")}`);
+          }
+        } catch { /* ignore */ }
+      }
+    } catch { /* dir unreadable */ }
+    return [...ids];
+  }
+
   _resolveFixture(rel) {
     // Try samples/ first (workspace, then project), then plain workspace path
     const candidates = [];
@@ -449,10 +653,175 @@ export class ReleaseTool extends BaseTool {
       }
     }
 
+    // 3) v0.8 P0-C: production_qc_results.json + qc_results_v*.json shapes
+    // (资管 + 贷款 v0.7.5 audits both shipped empty historical_accuracy
+    // because the v0.7.2 aggregator only recognized rule_stats / full_test_results).
+    if (tally.size === 0) {
+      const qcFiles = files
+        .filter((f) =>
+          /^production_qc(?:_results)?(?:_v\d+)?\.json$/i.test(f.name) ||
+          /^qc_results(?:_v\d+)?\.json$/i.test(f.name)
+        )
+        .sort((a, b) => a.name.localeCompare(b.name));
+      for (const f of qcFiles.slice(0, 5)) {
+        try {
+          const d = JSON.parse(fs.readFileSync(f.path, "utf-8"));
+          const results = d.results;
+          if (!results) continue;
+
+          // Shape 3a (资管): nested rule-keyed map
+          //   {results: {<rid>: {<doc_id>: {verdict, ...}}}}
+          if (typeof results === "object" && !Array.isArray(results)) {
+            for (const [rid, docs] of Object.entries(results)) {
+              if (!isRuleId(rid) || !docs || typeof docs !== "object") continue;
+              for (const r of Object.values(docs)) {
+                if (!r || typeof r !== "object") continue;
+                const verdict = (r.verdict || "").toString().toUpperCase();
+                if (verdict === "PASS") bump(rid, "pass");
+                else if (verdict === "FAIL") bump(rid, "fail");
+                else if (verdict === "NOT_APPLICABLE" || verdict === "NA" || verdict === "WARNING") bump(rid, "na");
+              }
+            }
+            if (tally.size > 0) sourceFiles.push(path.relative(this._workspace.cwd, f.path));
+          }
+          // Shape 3b (贷款): per-doc rollup list with failed_rules
+          //   {results: [{filename, actual, correct, failed_rules: [...]}], total_tested: N}
+          // For each rule: failures counted from failed_rules union; passes
+          // inferred as (total_tested - failures) for rules that appear in the catalog.
+          else if (Array.isArray(results)) {
+            const catalogPath = path.join(this._workspace.cwd, "rules", "catalog.json");
+            let catalogRules = [];
+            try {
+              const cat = JSON.parse(fs.readFileSync(catalogPath, "utf-8"));
+              const list = Array.isArray(cat) ? cat : Array.isArray(cat?.rules) ? cat.rules : [];
+              catalogRules = list.map((r) => r?.id || r?.rule_id).filter((x) => isRuleId(x));
+            } catch { /* catalog optional */ }
+
+            const failCountByRule = new Map();
+            let docCount = 0;
+            for (const row of results) {
+              if (!row || typeof row !== "object") continue;
+              docCount += 1;
+              const failed = Array.isArray(row.failed_rules) ? row.failed_rules : [];
+              for (const rid of failed) {
+                if (!isRuleId(rid)) continue;
+                failCountByRule.set(rid, (failCountByRule.get(rid) || 0) + 1);
+              }
+            }
+            if (docCount > 0) {
+              const ruleSet = new Set([...catalogRules, ...failCountByRule.keys()]);
+              for (const rid of ruleSet) {
+                const fails = failCountByRule.get(rid) || 0;
+                const passes = Math.max(0, docCount - fails);
+                const t = tally.get(rid) || { pass: 0, fail: 0, na: 0, n: 0 };
+                t.pass += passes; t.fail += fails; t.n += docCount;
+                tally.set(rid, t);
+              }
+              if (tally.size > 0) sourceFiles.push(path.relative(this._workspace.cwd, f.path));
+            }
+          }
+        } catch { /* try next file */ }
+        if (tally.size > 0) break;
+      }
+    }
+
+    // 4) v0.8.1 P9-A: top-level fail_by_rule + pass_by_rule maps (贷款
+    // v0.8 production_qc_report.json shape). Direct per-rule counts —
+    // no per-doc rollup, no verdict literals to scan.
+    //   {accuracy, total_checks, fail_by_rule: {<rid>: N}, pass_by_rule: {<rid>: N}}
+    if (tally.size === 0) {
+      for (const f of files) {
+        if (!/qc|prod|report|result/i.test(f.name)) continue;
+        try {
+          const d = JSON.parse(fs.readFileSync(f.path, "utf-8"));
+          const failMap = d?.fail_by_rule;
+          const passMap = d?.pass_by_rule;
+          if (
+            failMap && typeof failMap === "object" && !Array.isArray(failMap) &&
+            passMap && typeof passMap === "object" && !Array.isArray(passMap)
+          ) {
+            const allRules = new Set([...Object.keys(failMap), ...Object.keys(passMap)]);
+            let matched = false;
+            for (const rid of allRules) {
+              if (!isRuleId(rid)) continue;
+              const fails = Number(failMap[rid]) || 0;
+              const passes = Number(passMap[rid]) || 0;
+              if (fails + passes === 0) continue;
+              const t = tally.get(rid) || { pass: 0, fail: 0, na: 0, n: 0 };
+              t.pass += passes;
+              t.fail += fails;
+              t.n += passes + fails;
+              tally.set(rid, t);
+              matched = true;
+            }
+            if (matched) {
+              sourceFiles.push(path.relative(this._workspace.cwd, f.path));
+              break;
+            }
+          }
+        } catch { /* skip non-JSON */ }
+      }
+    }
+
+    // 5) Fallback (belt-and-suspenders per v0.8 plan Risk #7):
+    // walk any output/*.json with a top-level rule_id-keyed shape that has
+    // verdict-like leaf objects. Catches future schema drift before the
+    // next audit cycle.
+    if (tally.size === 0) {
+      for (const f of files) {
+        if (!/qc|verdict|result/i.test(f.name)) continue;
+        try {
+          const d = JSON.parse(fs.readFileSync(f.path, "utf-8"));
+          const root = d?.results || d;
+          if (!root || typeof root !== "object" || Array.isArray(root)) continue;
+          let matched = false;
+          for (const [rid, val] of Object.entries(root)) {
+            if (!isRuleId(rid) || !val || typeof val !== "object") continue;
+            // val might be {verdict, ...} OR {<doc>: {verdict, ...}}
+            const probe = val.verdict ? [val] : Object.values(val);
+            for (const r of probe) {
+              if (!r || typeof r !== "object") continue;
+              const verdict = (r.verdict || "").toString().toUpperCase();
+              if (verdict === "PASS") { bump(rid, "pass"); matched = true; }
+              else if (verdict === "FAIL") { bump(rid, "fail"); matched = true; }
+              else if (verdict === "NOT_APPLICABLE" || verdict === "NA") { bump(rid, "na"); matched = true; }
+            }
+          }
+          if (matched) {
+            sourceFiles.push(path.relative(this._workspace.cwd, f.path) + " (fallback shape)");
+            break;
+          }
+        } catch { /* skip non-JSON */ }
+      }
+    }
+
     if (tally.size === 0) return null;
 
+    // v0.8.1 P9-D: filter tally to rule_ids in the current catalog.
+    // E2E #11 资管 v0.8 audit: confidence_calibration aggregated from
+    // an abandoned 39-rule pipeline included only 2 of 4 final samples.
+    // Filtering to catalog.json keeps the calibration scoped to the
+    // rules that actually ship in the release.
+    let catalogRuleIds = null;
+    try {
+      const catalogPath = path.join(this._workspace.cwd, "rules", "catalog.json");
+      if (fs.existsSync(catalogPath)) {
+        const cat = JSON.parse(fs.readFileSync(catalogPath, "utf-8"));
+        const list = Array.isArray(cat) ? cat : Array.isArray(cat?.rules) ? cat.rules : [];
+        catalogRuleIds = new Set(
+          list.map((r) => r?.id || r?.rule_id).filter((x) => isRuleId(x))
+        );
+        if (catalogRuleIds.size === 0) catalogRuleIds = null;
+      }
+    } catch { /* skip filter if catalog missing/malformed */ }
+
     const historical_accuracy = {};
+    const droppedRules = [];
     for (const [rid, t] of tally.entries()) {
+      if (catalogRuleIds && !catalogRuleIds.has(rid)) {
+        droppedRules.push(rid);
+        continue;
+      }
       const fired = t.pass + t.fail;
       historical_accuracy[rid] = {
         pass_rate: fired > 0 ? +(t.pass / fired).toFixed(4) : null,
@@ -466,6 +835,7 @@ export class ReleaseTool extends BaseTool {
       historical_accuracy,
       computed_at: new Date().toISOString(),
       source_files: sourceFiles,
+      ...(droppedRules.length > 0 ? { dropped_off_catalog: droppedRules } : {}),
     };
   }
 

package/src/agent/tools/sandbox-exec.js

@@ -25,16 +25,38 @@ function detectSharedFileWrites(command) {
  * Execute shell commands in the workspace directory.
  * Uses child_process.spawn so pipes, redirects, && all work.
  * Output (stdout + stderr combined) is capped at 10K chars.
+ *
+ * v0.8 P1-F timeout model:
+ *   - Default: KC_EXEC_DEFAULT_TIMEOUT_MS (env) or 120000ms (2 min)
+ *   - Hard cap: KC_EXEC_MAX_TIMEOUT_MS (env) or 600000ms (10 min)
+ *   - Per-call `timeout_ms` overrides default, clamped to [1000, max]
+ *   - Legacy `KC_EXEC_TIMEOUT` (seconds) still accepted as a deprecation
+ *     alias for the default; emits a warning to stderr on first read.
  */
 export class SandboxExecTool extends BaseTool {
   /**
    * @param {import('../workspace.js').Workspace} workspace
-   * @param {number} [timeout=30]
+   * @param {object|number} [opts] — either a config object (new) OR
+   *   a number meaning the legacy timeout-in-seconds (old). The number
+   *   form is preserved for callers that haven't been updated yet.
+   * @param {number} [opts.defaultTimeoutMs] — default 120000
+   * @param {number} [opts.maxTimeoutMs] — default 600000
    */
-  constructor(workspace, timeout = 30) {
+  constructor(workspace, opts = {}) {
     super();
     this._workspace = workspace;
-    this._timeout = timeout;
+
+    // Legacy: opts is a bare number = seconds. Convert to ms.
+    if (typeof opts === "number") {
+      this._defaultTimeoutMs = opts * 1000;
+      this._maxTimeoutMs = Math.max(this._defaultTimeoutMs, 600_000);
+    } else {
+      this._defaultTimeoutMs = opts.defaultTimeoutMs ?? 120_000;
+      this._maxTimeoutMs = opts.maxTimeoutMs ?? 600_000;
+    }
+    // Floor: keep at least 1s. Cap: max can't be below default.
+    this._defaultTimeoutMs = Math.max(1000, this._defaultTimeoutMs);
+    this._maxTimeoutMs = Math.max(this._defaultTimeoutMs, this._maxTimeoutMs);
   }
 
   get name() { return "sandbox_exec"; }
@@ -47,7 +69,10 @@ export class SandboxExecTool extends BaseTool {
       "Pipes, redirects, and chained commands (&&) are supported. " +
       "stdout + stderr combined are capped at 10,000 chars; longer output is truncated. " +
       "For reading individual files larger than ~10 KB (e.g. regulation documents), " +
-      "prefer workspace_file (operation=read) which has a larger 50 KB cap."
+      "prefer workspace_file (operation=read) which has a larger 50 KB cap. " +
+      `Default timeout ${Math.round(this._defaultTimeoutMs / 1000)}s; pass timeout_ms ` +
+      `to extend up to ${Math.round(this._maxTimeoutMs / 1000)}s for known-slow commands ` +
+      `(LLM batch processing, document parsing, large regression runs).`
     );
   }
 
@@ -64,6 +89,10 @@ export class SandboxExecTool extends BaseTool {
           enum: ["workspace", "project"],
           description: "Working directory. 'workspace' (default) = KC's workspace. 'project' = user's project directory.",
         },
+        timeout_ms: {
+          type: "integer",
+          description: `Optional per-call timeout in milliseconds. Default ${this._defaultTimeoutMs}ms; clamped to [1000, ${this._maxTimeoutMs}]. Pass for commands you expect to take longer than the default (LLM batches, parsing, regressions).`,
+        },
       },
       required: ["command"],
     };
@@ -76,6 +105,22 @@ export class SandboxExecTool extends BaseTool {
       return new ToolResult("No command provided", true);
     }
 
+    // v0.8 P1-F: per-call timeout clamping
+    let effectiveTimeoutMs = this._defaultTimeoutMs;
+    let clampedMessage = null;
+    if (Number.isFinite(input.timeout_ms) && input.timeout_ms > 0) {
+      const requested = Math.floor(input.timeout_ms);
+      if (requested < 1000) {
+        effectiveTimeoutMs = 1000;
+        clampedMessage = `timeout_ms=${requested} below 1000ms floor; using 1000ms.`;
+      } else if (requested > this._maxTimeoutMs) {
+        effectiveTimeoutMs = this._maxTimeoutMs;
+        clampedMessage = `timeout_ms=${requested} above ${this._maxTimeoutMs}ms ceiling; clamped to ${this._maxTimeoutMs}ms.`;
+      } else {
+        effectiveTimeoutMs = requested;
+      }
+    }
+
     const effectiveCwd = (cwdScope === "project" && this._workspace.projectDir)
       ? this._workspace.projectDir
       : this._workspace.cwd;
@@ -86,7 +131,7 @@ export class SandboxExecTool extends BaseTool {
     const sharedHits = detectSharedFileWrites(command);
 
     try {
-      const { output, code } = await this._run(command, effectiveCwd);
+      const { output, code } = await this._run(command, effectiveCwd, effectiveTimeoutMs);
       let result = output;
       if (result.length > MAX_OUTPUT) {
         result = result.slice(0, MAX_OUTPUT) + "\n[truncated]";
@@ -101,10 +146,20 @@ export class SandboxExecTool extends BaseTool {
           `   Under concurrent subagents this races — use workspace_file or rule_catalog instead.\n\n`;
         result = prefix + result;
       }
+      if (clampedMessage) {
+        result = `[note] ${clampedMessage}\n\n` + result;
+      }
       return new ToolResult(result, code !== 0);
     } catch (err) {
       if (err.message === "timeout") {
-        return new ToolResult(`Command timed out after ${this._timeout}s`, true);
+        const seconds = Math.round(effectiveTimeoutMs / 1000);
+        const hint = effectiveTimeoutMs < this._maxTimeoutMs
+          ? ` Pass timeout_ms (up to ${this._maxTimeoutMs}) for known-slow commands.`
+          : ` Already at max timeout (${this._maxTimeoutMs}ms); consider splitting the command into smaller batches or running it via a subagent.`;
+        return new ToolResult(
+          `Command timed out after ${seconds}s (${effectiveTimeoutMs}ms).${hint}`,
+          true,
+        );
       }
       return new ToolResult(`Execution error: ${err.message}`, true);
     }
@@ -112,9 +167,11 @@ export class SandboxExecTool extends BaseTool {
 
   /**
    * @param {string} command
+   * @param {string} cwd
+   * @param {number} timeoutMs
    * @returns {Promise<{output: string, code: number}>}
    */
-  _run(command, cwd) {
+  _run(command, cwd, timeoutMs) {
     return new Promise((resolve, reject) => {
       const controller = new AbortController();
       const proc = spawn("sh", ["-c", command], {
@@ -130,7 +187,7 @@ export class SandboxExecTool extends BaseTool {
       const timer = setTimeout(() => {
         controller.abort();
         reject(new Error("timeout"));
-      }, this._timeout * 1000);
+      }, timeoutMs);
 
       proc.on("close", (code) => {
         clearTimeout(timer);