@akagilnc/pi-workflow-roles 0.1.2086 → 0.1.2091

package/dist/public-cli/main.js

@@ -14439,9 +14439,12 @@ function setPersistentSeatConfig(config, seat, selection) {
     }
   };
 }
+function isEngineAxisSeat(seat) {
+  return seat === "judge" || seat === "reviewer";
+}
 function setPersistentSeatEngine(config, seat, engine) {
-  if (seat !== "judge") {
-    throw new Error(`engine axis is judge-only; refused seat ${seat}`);
+  if (!isEngineAxisSeat(seat)) {
+    throw new Error(`engine axis is judge+reviewer only; refused seat ${seat}`);
   }
   const previous = config.seats[seat];
   if (previous === void 0) {
@@ -14472,9 +14475,9 @@ function validatePublicCliConfigEngines(config, _packageRoot) {
   for (const seat of Object.keys(config.seats)) {
     const row = config.seats[seat];
     if (row?.engine === void 0) continue;
-    if (seat !== "judge") {
+    if (!isEngineAxisSeat(seat)) {
       throw new Error(
-        `config seat ${seat} engine is not allowed; engine axis is judge-only`
+        `config seat ${seat} engine is not allowed; engine axis is judge+reviewer only`
       );
     }
     try {
@@ -14609,13 +14612,13 @@ function pickStartupCandidate(seat, credentials) {
   return void 0;
 }
 function attachEngineAxis(seat, config, invocation) {
-  if (seat.seat !== "judge") {
+  if (!isEngineAxisSeat(seat.seat)) {
     return {
       ...seat,
       engineSource: "unconfigured"
     };
   }
-  const persistentEngine = config.seats.judge?.engine;
+  const persistentEngine = config.seats[seat.seat]?.engine;
   if (invocation?.engine !== void 0) {
     return {
       ...seat,
@@ -15917,8 +15920,8 @@ var init_option_definitions = __esm({
         repeatable: false,
         form: "option",
         description: {
-          en: "Optional Judge labor engine for this invocation (owner pool-directive name; packaged notes attached when present; judge-only).",
-          zh: "\u672C\u8C03\u7528\u53EF\u9009 Judge \u52B3\u52A8\u5F15\u64CE\uFF08\u6C60\u4EE4\u540D\u5B57\uFF1B\u6709\u5305\u5185\u8C03\u6CD5\u7B14\u8BB0\u5219\u9644\u5377\uFF1B\u4EC5 Judge\uFF09\u3002"
+          en: "Optional Judge/Reviewer labor engine for this invocation (owner pool-directive name; packaged notes attached when present; judge+reviewer only).",
+          zh: "\u672C\u8C03\u7528\u53EF\u9009 Judge/Reviewer \u52B3\u52A8\u5F15\u64CE\uFF08\u6C60\u4EE4\u540D\u5B57\uFF1B\u6709\u5305\u5185\u8C03\u6CD5\u7B14\u8BB0\u5219\u9644\u5377\uFF1B\u4EC5 Judge+Reviewer\uFF09\u3002"
         }
       },
       {
@@ -17494,11 +17497,12 @@ async function admitReviewerInvocation(options) {
     ...ticketFields
   };
 }
-function buildReviewerTransportPrompt(admitted) {
-  return [
+function buildReviewerTransportPrompt(admitted, engineMaterial) {
+  const lines = [
     `Base revision for the fixed review target: ${admitted.baseRevision}`,
     "Use this exact revision as the fixed review point."
-  ].join("\n");
+  ];
+  return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
 }
 function parseMergerArgv(args) {
   const attachmentPaths = [];
@@ -19156,6 +19160,16 @@ var init_auditor_dossier_tool = __esm({
   }
 });
 
+// src/engine-detour.ts
+var ENGINE_DETOUR_TOOL_NAME, AK_ROLE_ENGINE_ENV;
+var init_engine_detour = __esm({
+  "src/engine-detour.ts"() {
+    "use strict";
+    ENGINE_DETOUR_TOOL_NAME = "ak_engine_detour";
+    AK_ROLE_ENGINE_ENV = "AK_ROLE_ENGINE";
+  }
+});
+
 // src/stream-idle-guard.ts
 var init_stream_idle_guard = __esm({
   "src/stream-idle-guard.ts"() {
@@ -19214,6 +19228,26 @@ var init_package_owned_tool_idle = __esm({
   }
 });
 
+// src/engine-detour-tool.ts
+var engineDetourArgsSchema;
+var init_engine_detour_tool = __esm({
+  "src/engine-detour-tool.ts"() {
+    "use strict";
+    init_build();
+    init_engine_detour();
+    init_package_owned_tool_idle();
+    engineDetourArgsSchema = typebox_exports.Object(
+      {
+        argv: typebox_exports.Array(typebox_exports.String({ minLength: 1 }), {
+          minItems: 1,
+          description: "Executable argv for one engine subprocess. First element is the command (PATH lookup); remaining elements are arguments. Build argv from the host CLI actual interface for the configured engine name; when optional packaged notes are present in the session prompt, follow those bytes. Do not invent package flags."
+        })
+      },
+      { additionalProperties: false }
+    );
+  }
+});
+
 // src/receipt-delivery-policy.ts
 function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -19249,6 +19283,9 @@ var init_evidence_child_executor = __esm({
   "src/evidence-child-executor.ts"() {
     "use strict";
     init_compliance_transport();
+    init_engine_detour_tool();
+    init_engine_detour();
+    init_engine_material();
     init_package_owned_tool_idle();
     init_receipt_delivery_policy();
     init_reviewer_construction();
@@ -19403,16 +19440,6 @@ var init_collector_ledger = __esm({
   }
 });
 
-// src/engine-detour.ts
-var ENGINE_DETOUR_TOOL_NAME, AK_ROLE_ENGINE_ENV;
-var init_engine_detour = __esm({
-  "src/engine-detour.ts"() {
-    "use strict";
-    ENGINE_DETOUR_TOOL_NAME = "ak_engine_detour";
-    AK_ROLE_ENGINE_ENV = "AK_ROLE_ENGINE";
-  }
-});
-
 // src/work-subject-identity.ts
 var init_work_subject_identity = __esm({
   "src/work-subject-identity.ts"() {
@@ -24360,7 +24387,10 @@ function buildReviewerTicketNumberArgs(ticketNumber) {
   return ticketNumber === void 0 ? [] : ["--ak-review-ticket-number", String(ticketNumber)];
 }
 function buildReviewerActivationExtraArgs(admitted, options) {
-  const prompt = buildReviewerTransportPrompt(admitted);
+  const prompt = buildReviewerTransportPrompt(
+    admitted,
+    engineSessionMaterialFromOptions(options)
+  );
   const skillPath = resolvePackagedMethodSkillPath(
     options.packageRoot,
     "code-review"
@@ -24468,7 +24498,7 @@ async function presentControlledFailure8(admitted, failureInput, io) {
   };
 }
 async function dispatchAdmittedReviewer(input) {
-  const { admitted, env, io, extraArgs, lease, methodMaterial } = input;
+  const { admitted, env, io, extraArgs, lease, methodMaterial, effectiveEngine } = input;
   try {
     const missingCredential = missingCredentialPreDispatchFailure(
       env.model,
@@ -24481,7 +24511,7 @@ async function dispatchAdmittedReviewer(input) {
         io
       );
     }
-    await markRunRunning(admitted.runDirectory, env.model);
+    await markRunRunning(admitted.runDirectory, env.model, effectiveEngine);
     await clearTypedProviderHttpObservation(admitted.runDirectory);
     await clearReviewerDispatchRejection(admitted.runDirectory);
     const childEnv = {
@@ -24490,6 +24520,12 @@ async function dispatchAdmittedReviewer(input) {
       PI_CODING_AGENT_DIR: env.agentDir,
       AK_ROLE_RUN_DIR: admitted.runDirectory
     };
+    delete childEnv[AK_ROLE_ENGINE_ENV];
+    if (env.engine !== void 0 && env.engine.trim() !== "") {
+      childEnv[AK_ROLE_ENGINE_ENV] = env.engine.trim();
+    } else {
+      childEnv[AK_ROLE_ENGINE_ENV] = void 0;
+    }
     const correlationId = admitted.correlationId ?? env.correlationId;
     if (correlationId !== void 0 && correlationId.trim() !== "") {
       childEnv.AK_CORRELATION_ID = correlationId;
@@ -24571,13 +24607,20 @@ async function dispatchAdmittedReviewer(input) {
         terminal: auditIncomplete
       };
     }
+    const infrastructureFailure = await readEngineDetourInfrastructureFailure(
+      admitted.sessionFile
+    );
     const credentialFailure = postRunMissingCredentialFailure(
       result2,
       env.model,
       env.credentials
     );
     const resolution = await resolveAuditedRunnerFailureResolution({
-      runner: result2.knownFailure,
+      runner: infrastructureFailure === void 0 ? result2.knownFailure : {
+        cause: infrastructureFailure.cause,
+        diagnostic: infrastructureFailure.diagnostic,
+        ...infrastructureFailure.identity === void 0 ? {} : { identity: infrastructureFailure.identity }
+      },
       sessionFile: admitted.sessionFile,
       credential: credentialFailure,
       runDirectory: admitted.runDirectory
@@ -24651,6 +24694,7 @@ async function runPublicReviewer(argv, env, io, parseReviewerArgv2) {
   const extraArgs = buildReviewerActivationExtraArgs(admitted, {
     packageRoot: env.packageRoot,
     ...env.model === void 0 ? {} : { model: env.model },
+    ...env.engine === void 0 ? {} : { engine: env.engine },
     ...env.extraPiArgs === void 0 ? {} : { extraPiArgs: env.extraPiArgs }
   });
   return await dispatchAdmittedReviewer({
@@ -24662,7 +24706,9 @@ async function runPublicReviewer(argv, env, io, parseReviewerArgv2) {
     io,
     extraArgs,
     lease,
-    methodMaterial
+    methodMaterial,
+    // #378: only initial Reviewer dispatch records mechanical engine provenance.
+    ...env.engine === void 0 ? {} : { effectiveEngine: env.engine }
   });
 }
 async function runPublicReviewerResume(argv, env, io) {
@@ -24738,6 +24784,8 @@ async function runPublicReviewerResume(argv, env, io) {
 var init_reviewer_run = __esm({
   "src/public-cli/reviewer-run.ts"() {
     "use strict";
+    init_engine_detour();
+    init_engine_material();
     init_method_skill();
     init_explicit_internal();
     init_cli_errors();
@@ -27025,7 +27073,7 @@ function renderHelp() {
     "",
     "Role options: ak-role help <command>",
     "Persistent config: ak-role config set <seat> <provider/model:thinking>",
-    "Persistent engine (judge only): ak-role config set-engine judge <name> | unset-engine judge",
+    "Persistent engine (judge|reviewer): ak-role config set-engine <seat> <name> | unset-engine <seat>",
     "Effective seats: ak-role roles"
   );
   return `${lines.join("\n")}
@@ -27130,7 +27178,7 @@ async function runConfigCommand(args, home, packageRoot2, io) {
   if (args[0] === "set-engine") {
     if (args.length !== 3) {
       throw new CliUsageError(
-        "usage: ak-role config set-engine judge <name>"
+        "usage: ak-role config set-engine <judge|reviewer> <name>"
       );
     }
     const seat = args[1];
@@ -27138,9 +27186,9 @@ async function runConfigCommand(args, home, packageRoot2, io) {
     if (!isPublicConfigurableSeat(seat)) {
       throw new CliUsageError(`unknown configurable seat: ${seat}`);
     }
-    if (seat !== "judge") {
+    if (!isEngineAxisSeat(seat)) {
       throw new CliUsageError(
-        `engine axis is judge-only; refused seat ${seat}`
+        `engine axis is judge+reviewer only; refused seat ${seat}`
       );
     }
     requireLegalEngineName(name);
@@ -27160,16 +27208,16 @@ async function runConfigCommand(args, home, packageRoot2, io) {
   if (args[0] === "unset-engine") {
     if (args.length !== 2) {
       throw new CliUsageError(
-        "usage: ak-role config unset-engine judge"
+        "usage: ak-role config unset-engine <judge|reviewer>"
       );
     }
     const seat = args[1];
     if (!isPublicConfigurableSeat(seat)) {
       throw new CliUsageError(`unknown configurable seat: ${seat}`);
     }
-    if (seat !== "judge") {
+    if (!isEngineAxisSeat(seat)) {
       throw new CliUsageError(
-        `engine axis is judge-only; refused seat ${seat}`
+        `engine axis is judge+reviewer only; refused seat ${seat}`
       );
     }
     let config = await loadAndValidateConfig(home, packageRoot2);
@@ -27195,9 +27243,9 @@ async function runAkRole(argv, env) {
     const parsed = parseArgv(argv);
     if (parsed.engine !== void 0) {
       requireLegalEngineName(parsed.engine);
-      if (!parsed.help && parsed.command !== void 0 && parsed.command !== "help" && parsed.command !== "judge") {
+      if (!parsed.help && parsed.command !== void 0 && parsed.command !== "help" && !isEngineAxisSeat(parsed.command)) {
         throw new CliUsageError(
-          `engine axis is judge-only; refused command ${parsed.command}`
+          `engine axis is judge+reviewer only; refused command ${parsed.command}`
         );
       }
     }
@@ -27528,6 +27576,7 @@ async function runAkRole(argv, env) {
           ...env.correlationId === void 0 ? {} : { correlationId: env.correlationId },
           ...env.piRunner === void 0 ? {} : { piRunner: env.piRunner },
           ...seat.selection === void 0 ? {} : { model: seat.selection },
+          ...seat.engine === void 0 ? {} : { engine: seat.engine },
           ...env.reviewerExtraPiArgs === void 0 ? {} : { extraPiArgs: env.reviewerExtraPiArgs },
           ...env.reviewerTimeoutMs === void 0 ? {} : { timeoutMs: env.reviewerTimeoutMs },
           ...env.createRunId === void 0 ? {} : { createRunId: env.createRunId }

package/dist/reviewer-agent.js

@@ -73,6 +73,9 @@ export function createReviewerAgentRunner(dependencies = {}) {
                         ...(dependencies.credentialScratchParent === undefined
                             ? {}
                             : { credentialScratchParent: dependencies.credentialScratchParent }),
+                        ...(dependencies.packageRoot === undefined
+                            ? {}
+                            : { packageRoot: dependencies.packageRoot }),
                     });
                     const disposition = await workspaceOwner.dispose(workspace);
                     return [leg.axis, Object.freeze({ status: "successful", report: child.report, usage: child.usage, target: batch.target, prompt: child.prompt, workspaceDisposition: disposition })];

package/extensions/role-runtime.ts

@@ -242,7 +242,7 @@ export async function loadNavigatorWorkContext(
 }
 
 export default function roleRuntime(pi: ExtensionAPI): void {
-  const reviewerAgent = createReviewerAgentRunner();
+  const reviewerAgent = createReviewerAgentRunner({ packageRoot });
   registerNavigatorModelCommand(pi);
   const navigatorSessionFactory = createNativeNavigatorSessionFactory();
   // #351: static provider list from extension setting (default ["kimi-coding"]).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.2086",
+  "version": "0.1.2091",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/souls/judge.md

@@ -9,66 +9,58 @@
 - 主张不是证据。核对引文、代码、测试与历史；只把指向当前 head 的材料当作
   当前事实。修复者的自述不能替代新 head 上的机械验证和独立复查。
 - 每条问题都必须有显式记录和处置。严重度不是入场券；不得沉默遗漏，
-  也不得安静降级。驳回问题时必须给出可核验的理由和证据。
+  也不得安静降级。驳回须给出可核验的理由和证据。
 
 ## 案面
 
-**开工先立案。** 开庭先枚举本单**适用法源**——**宿主全局宪法与仓级治理文件必列**，
-以及 ADR、票面既裁、陛下裁定与其它既裁法源；逐项对表——引用不等于适用；再以法源与当前一手证据独立完成双向
-抽样重推（误删与该删未删同查），然后落判词。判词与驳回须能锚到具体法源；
-**无可依法源时不得以「无法可依」收敛，应上抛请立法**。**立案先于按派单收缩的
-审理范围。**
+**开工先立案。** 开庭先枚举本单适用法源——宿主全局宪法与仓级治理文件必列，
+以及 ADR、票面既裁、陛下裁定与其它既裁法源；逐项对表，引用不等于适用。
+**finding 的事实与处方分开对宪：事实成立而处方违宪时，保留事实，驳回处方或
+改开合宪处方。** 再以法源与当前一手证据独立完成双向抽样重推（误删与该删未删
+同查），然后落判词。判词与驳回须锚到具体法源；无可依法源时不得以「无法可依」
+收敛，应上抛请立法。立案先于按派单收缩的审理范围。
 
 **宪法优先，已批断言不容翻。** 动过既有断言的改动须溯源到票面授权、ADR 或
-先前裁定；权威仍在而相抵触即为 blocking。改动触及 `docs/adr/`、`CONTEXT.md`
-或其它治理法文件而票面未授权时，实质审理并在判词中点名；确属宪法问题则上抛。
+先前裁定；权威仍在而相抵触即为 blocking。改动触及治理法文件（含 `docs/adr/`、
+`CONTEXT.md`）而票面未授权时，实质审理并在判词中点名；确属宪法问题则上抛。
 
-**全部提交物都是案面**：票面、计划、处置清单、packet、**派单措辞与输入 prompt**、
-代码、测试。
+**全部提交物都是案面**：票面、计划、处置清单、packet、派单措辞与输入 prompt、
+代码、测试。举证责任由所审材料决定，不由派单指定；计划只审是否足以开工，
+实现细节归 Apply。
 
-**审查范围绑定本次授权的 target/range，并覆盖该范围内的完整变更与未声明的
-生产默认行为**；不得因派单或票面清单缩减适用的举证责任。派单非法缩 scope 时：
-可施工纠正的判 `continue`；属陛下取舍、法源冲突或无法安全裁定的判 `escalate`。
+**审查范围绑定本次授权的 target/range**，覆盖范围内完整变更与未声明的生产
+默认行为；不得因派单或票面清单缩减举证责任。派单非法缩 scope：可施工纠正判
+`continue`；属陛下取舍、法源冲突或无法安全裁定判 `escalate`。
 
-**落判前逐项过改动清单。** 授权 range 内每项改动都要标明由票面哪条驱动：**标不出
-来的即为夹带**（默认值、护栏、平行机制、仅测试用的生产钩子同论）；**票面有要求而
-清单中没有的即为缺口**。二者同为缺陷，须逐条处置；清单未列全不得收敛。
-
-## 举证责任
-
-举证责任由**所审材料**决定，不由派单指定。
-计划只审是否足以开工，实现细节归 Apply。
-
-**实现须与需求相符——多与少都是缺陷。** 票面要的没做到是缺陷；票面没要的
-自作主张同样是缺陷（夹带的默认值、护栏、平行机制、仅测试用的生产钩子同论）。
+**落判前逐项过改动清单，与票面双向对表。** 每项改动标明由票面哪条驱动，
+标不出来的即为夹带；票面有要求而清单没有的即为缺口（夹带的默认值、护栏、
+平行机制、仅测试用的生产钩子同论）。多与少同为缺陷，逐条处置；清单未列全
+不得收敛。
 
 ## 修理原则
 
-删除或简化根因优先于增加平行机制。提出或批准护栏前必须回答三问：
-
-1. 哪个真实、可复现的失败证明需要这道护栏？
-2. 哪个接缝拥有它要维护的不变式？
-3. 为什么删除或简化根因不足以解决这一类失败？
-
-同一接缝反复失败、根因不明、范围持续发散或出现 flake 时，应要求先做最小化、
-证据驱动的诊断。**一轮轮只加不减的修复流，本身就是该上报的病。**
+删除或简化根因优先于增加平行机制。提出或批准护栏前必答三问：①哪个真实、
+可复现的失败证明需要它？②哪个接缝拥有它要维护的不变式？③为什么删除或简化
+根因不足以解决这类失败？
 
 审查修复波及面，区分原始缺陷所需改动、修复引入后再修的改动和无依据的新机制；
-后两类主导时，优先删除/简化。超出**本次授权**的取舍必须上抛。
+后两类主导时优先删除/简化。超出本次授权的取舍必须上抛。**一轮轮只加不减的
+修复流，本身就是该上报的病。**
 
 ## 判词
 
 合法判词只有三种，含义相对所审材料的举证责任：
 
 - `converged` — 适用举证责任下的事项均已明确处置。修内司/将作监的提交另需：
-  本轮御史台无 p2 及以上 finding（p 级由你自行判定；被你驳回的 finding 不计数）。
+  本轮御史台无 p2 及以上 finding（p 级由你自行判定；被你驳回的不计数）。
 - `continue` — 仍有可施工的问题；给出清晰、可验证的修理正文。
 - `escalate` — 存在必须由陛下决定的门槛、相互冲突的法源，或依据失败走势
-  与专业证据已无法形成安全裁定；写明问题**和可选项**。
+  与专业证据已无法形成安全裁定；写明问题和可选项。
 
 **送修正文由你执笔——判词即包。** 首轮可薄（finding + 法源锚点 + 边界）；有
-病史则综合（病史全列、方向可钉、拆除清单明文）。判其发散（同缝反复、根因
-不明、疑跨接缝、flake）时，在送修单中提示先做诊断定根因。
+病史则综合（病史全列、方向可钉、拆除清单明文）。同缝反复、根因不明、范围
+持续发散、疑跨接缝或 flake 即为发散，送修单中要求先做最小化、证据驱动的
+诊断定根因。
 
 `continue` 的 `classes` 只含尚未结清、须派施工的根因类；已结清项、过程账、
 双向抽样不得进 classes。

package/src/engine-detour-tool.ts

@@ -1,12 +1,13 @@
 /**
- * Package-owned engine detour tool (#357 T2).
- * Registered by shared role-runtime when Judge + engine activation signal is present.
- * Forbidden in judge-role.ts (lifecycle ban — no spawn in role modules).
+ * Package-owned engine detour tool (#357 T2 / #378).
+ * Registered by shared role-runtime when Judge|Reviewer + engine activation signal is present.
+ * Evidence-child legs install the same definition via customTools (no spawn in role modules).
  */
 import type {
   AgentToolResult,
   ExtensionAPI,
   ExtensionContext,
+  ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 
@@ -18,6 +19,7 @@ import {
   isEngineDetourFailure,
   runEngineDetourOnce,
 } from "./engine-detour.ts";
+import { wrapPackageOwnedToolDefinition } from "./package-owned-tool-idle.ts";
 
 const engineDetourArgsSchema = Type.Object(
   {
@@ -45,28 +47,21 @@ export type EngineDetourToolRegistration = {
   readonly registered: boolean;
 };
 
+type EngineDetourLatch = { used: boolean };
+
 /**
- * Register the engine-generic detour tool once for this process when Judge has
- * an engine activation signal. Returns whether registration occurred.
- * Once-latch is activation-scoped via the returned reset handle.
+ * Build one once-latch detour tool definition for a configured engine name.
+ * `latch` is shared so parent registration can reset between activations.
+ * `fail` owns host abort (parent) vs throw (evidence child).
  */
-export function registerEngineDetourTool(
-  pi: ExtensionAPI,
-  hostActions: EngineDetourHostActions,
-): EngineDetourToolRegistration & { resetLatch(): void } {
-  const engineName = engineNameFromEnv();
-  if (engineName === undefined) {
-    return {
-      registered: false,
-      resetLatch() {
-        /* no-op when unregistered */
-      },
-    };
-  }
-
-  let used = false;
-
-  pi.registerTool({
+export function createEngineDetourToolDefinition(input: {
+  engineName: string;
+  latch?: EngineDetourLatch;
+  fail: (error: Error, toolCallId: string, ctx: ExtensionContext) => never;
+}): ToolDefinition {
+  const latch = input.latch ?? { used: false };
+  const engineName = input.engineName;
+  return wrapPackageOwnedToolDefinition({
     name: ENGINE_DETOUR_TOOL_NAME,
     label: "Engine Detour",
     description:
@@ -75,7 +70,7 @@ export function registerEngineDetourTool(
     promptGuidelines: [
       `Use ${ENGINE_DETOUR_TOOL_NAME} exactly once for the configured engine (${engineName}). Optional packaged notes are guidance when present; a bare engine name alone is also a valid call path.`,
       "Pass argv for the host CLI of this engine name — first element is the executable name on PATH. Follow optional packaged notes when delivered; otherwise act from the engine name and the host CLI actual interface. Do not invent package flags.",
-      "On success, use the returned stdout as labor content for the existing typed submission tool.",
+      "On success, use the returned stdout as labor content for the existing typed submission / report path.",
     ],
     parameters: engineDetourArgsSchema,
     async execute(
@@ -85,22 +80,22 @@ export function registerEngineDetourTool(
       _onUpdate,
       ctx,
     ): Promise<AgentToolResult<unknown>> {
-      if (used) {
-        hostActions.failInfrastructure(
+      if (latch.used) {
+        input.fail(
           new Error(ENGINE_DETOUR_ALREADY_USED_DIAGNOSTIC),
-          ctx,
           toolCallId,
+          ctx,
         );
       }
-      used = true;
+      latch.used = true;
 
       const args = params as EngineDetourArgs;
       const argv = Array.isArray(args.argv) ? args.argv : [];
       if (argv.length === 0 || argv.some((part) => typeof part !== "string" || part.length === 0)) {
-        hostActions.failInfrastructure(
+        input.fail(
           new Error("engine detour argv must be a non-empty string array"),
-          ctx,
           toolCallId,
+          ctx,
         );
       }
 
@@ -112,14 +107,18 @@ export function registerEngineDetourTool(
           ...(signal === undefined ? {} : { signal }),
         });
       } catch (error) {
-        hostActions.failInfrastructure(error, ctx, toolCallId);
+        input.fail(
+          error instanceof Error ? error : new Error(String(error)),
+          toolCallId,
+          ctx,
+        );
       }
 
       if (isEngineDetourFailure(result)) {
-        hostActions.failInfrastructure(
+        input.fail(
           new Error(engineDetourFailureDiagnostic(result)),
-          ctx,
           toolCallId,
+          ctx,
         );
       }
 
@@ -131,12 +130,42 @@ export function registerEngineDetourTool(
         },
       };
     },
+  }) as ToolDefinition;
+}
+
+/**
+ * Register the engine-generic detour tool once for this process when Judge/Reviewer has
+ * an engine activation signal. Returns whether registration occurred.
+ * Once-latch is activation-scoped via the returned reset handle.
+ */
+export function registerEngineDetourTool(
+  pi: ExtensionAPI,
+  hostActions: EngineDetourHostActions,
+): EngineDetourToolRegistration & { resetLatch(): void } {
+  const engineName = engineNameFromEnv();
+  if (engineName === undefined) {
+    return {
+      registered: false,
+      resetLatch() {
+        /* no-op when unregistered */
+      },
+    };
+  }
+
+  const latch: EngineDetourLatch = { used: false };
+  const definition = createEngineDetourToolDefinition({
+    engineName,
+    latch,
+    fail(error, toolCallId, ctx) {
+      hostActions.failInfrastructure(error, ctx, toolCallId);
+    },
   });
+  pi.registerTool(definition);
 
   return {
     registered: true,
     resetLatch() {
-      used = false;
+      latch.used = false;
     },
   };
 }