@bridge_gpt/mcp-server 0.2.62 → 0.2.66

package/README.md

@@ -252,9 +252,13 @@ workflows. Bridge-spawned Codex workers then select it automatically, including
 the fresh implementation session after review. Pass `--codex-profile=off` to
 decline; the installer leaves any existing profile content intact. On package
 upgrade, the next Bridge-spawned worker refreshes an older, unmodified managed
-profile before launch. If a profile
-already contains user-authored or conflicting content, the installer leaves it
-untouched and reports that workers cannot use it. Run `doctor --agent codex` to
+profile before launch. The profile preapproves review-decision capture, the
+fixed reviewed-document publisher, and the implementation phase-result record,
+so those required Bridge writes do not enter Codex Auto-review. The general
+`attachment` tool stays on automatic review because it also supports deletion
+and replacement. If a profile already contains user-authored or conflicting
+content, the installer leaves it untouched and reports that workers cannot use
+it. Run `doctor --agent codex` to
 inspect the current status. To use the profile in a Codex session you open
 yourself, run `codex --profile bridge`. Bridge `--auto` controls recipe gates;
 Codex MCP tool approvals are a separate setting. The profile does not change
@@ -369,7 +373,7 @@ later boot.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.62", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.66", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -391,7 +395,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.62", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.66", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -413,7 +417,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.62", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.66", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -436,7 +440,7 @@ Windsurf only supports global MCP configuration.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.62", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.66", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -455,7 +459,7 @@ Windsurf only supports global MCP configuration.
 ```toml
 [mcp_servers.bridge]
 command = "npx"
-args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.62", "serve"]
+args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.66", "serve"]
 
 [mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -893,7 +897,7 @@ Because tier 2 outranks tier 3, a stale `SFCC_HOSTNAME` left in the environment
 "env": { "BRIDGE_MCP_PROFILE": "sfcc" }
 ```
 
-`sfcc` gives the eight read tools plus `sfcc_log_query`. For the nine destructive write tools as well, use `"sfcc,sfcc-write"`; `full` expands to every group and is therefore write-capable. Without any of these, only the diagnostic tools are registered.
+`sfcc` gives the two diagnostics, the eight read tools, and `sfcc_log_query`. For the nine destructive write tools as well, use `"sfcc,sfcc-write"`; `full` expands to every group and is therefore write-capable. Without any of these, no SFCC tool is registered — not even the diagnostics.
 
 **4. Verify and grant OCAPI access.** With `sfcc` selected in step 3 (both diagnostics live in that profile), ask your agent to run `sfcc_setup_status` (expect all checks ✓), then `check_permissions`. If it reports HTTP 401/403, it prints the exact OCAPI Settings JSON to paste in Business Manager (**Administration → Site Development → Open Commerce API Settings → Data API** tab); save it there and re-run. Restart the MCP client after any credential or env change — a running session does not pick them up.
 
@@ -1049,7 +1053,7 @@ Each `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switch
 npx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248
 ```
 
-**Difficulty-based model routing.** Before launching each agent, the CLI selects an implementation **model tier** from the ticket's `difficulty` (1-2 → cheap, 3-6 → basic, 7-10 → premium) and may inject `--model` at the spawn boundary. The Python backend returns only the coarse tier (`GET /jira/tickets/{KEY}/model-tier`, computing + caching difficulty on demand). Claude and Cursor map that tier through their agent registry aliases; Cursor validates against `cursor-agent --list-models`. Routing is gated per repo by `difficulty_model_routing_enabled` (default **ON**). Claude/Cursor may use `difficulty_model_tier_overrides` (tier → alias) and retain their premium fallback behavior on an unknown tier or transient failure. When an alias cannot be validated, the CLI omits `--model` and launches the agent default. `--dry-run` resolves routing read-only to preview the command without creating worktrees or opening tabs.
+**Difficulty-based model routing.** Before launching each agent, the CLI selects an implementation **model tier** from the ticket's `difficulty` (1-2 → cheap, 3-6 → basic, 7-10 → premium) and may inject `--model` at the spawn boundary. Under the repo's `quality` optimization posture (also the fail-safe default), premium starts one step earlier, at difficulty 6. The Python backend returns only the coarse tier (`GET /jira/tickets/{KEY}/model-tier`, computing + caching difficulty on demand). Claude and Cursor map that tier through their agent registry aliases; Cursor validates against `cursor-agent --list-models`. Routing is gated per repo by `difficulty_model_routing_enabled` (default **ON**). Claude/Cursor may use `difficulty_model_tier_overrides` (tier → alias) and retain their premium fallback behavior on an unknown tier or transient failure. When an alias cannot be validated, the CLI omits `--model` and launches the agent default. `--dry-run` resolves routing read-only to preview the command without creating worktrees or opening tabs.
 
 For Codex, `GET /jira/codex-model-catalog?repo_name=...` is the sole tier-to-model authority. Bridge derives its three bare CLI IDs and SHA-256 mapping revision at request time from `MODEL_REGISTRY`; the launcher fetches and validates that catalog once per invocation. Repository `difficulty_model_tier_overrides` do not apply to Codex. A failed access, config, tier, catalog, revision, or alias check omits `--model` and launches the configured Codex default. The catalog expresses **Bridge provider policy only**: it cannot confirm that the local Codex login or subscription can use a model. The CLI has no supported non-interactive entitlement probe, so routing emits that limitation as a diagnostic and never uses Bridge's OpenAI API key as proof of local access.
 
@@ -1128,6 +1132,51 @@ including every error path, ever offers you two paths.
 the strategy and the posture (see below). With none of them, a multi-ticket epic
 runs on `epic/<KEY>`, unattended.
 
+**Finding the plan from the epic key (BAPI-1285).** `--plan-file` is optional.
+Without it, `drive-epic` searches `{docs_dir}/epic-plans/*/epic-plan.meta.json` for a
+file whose `epic_key` is exactly this epic (`docs_dir` is `BAPI_DOCS_DIR`, else
+`docs/tmp`, resolved against the Git top level; an absolute `BAPI_DOCS_DIR` is used
+as given). Exactly one match with a sibling `epic-plan.dag.json` is used as if you
+had passed `--plan-file`, and its path is printed before anything is created. Zero
+matches, two or more, or an unusable meta file **stop** with the paths found and
+create nothing, and a folder name, a child ticket key, or
+`sibling-ticket-manifest.json` is never used to guess. A supplied `--plan-file`
+always wins and discovery does not run.
+
+The meta file is `{"epic_key": "<KEY>"}`, written by `emit-epic-implementer-bundle
+finalize` beside the DAG (its own atomic write, reported as `meta_path` in
+`--json`). It is separate from `epic-plan.dag.json` on purpose: the DAG is sent to
+the server, which rejects unknown fields. A plan finalized before this change has no
+meta file, so it is reported as not found — pass its DAG with `--plan-file`.
+
+**A live run with no plan.** If the epic already has a live run and no plan was
+supplied or found, `drive-epic` creates nothing. It makes sure that run has an
+executor: it reuses a verified live one (never starting a second), starts one when
+the old one is gone, starts none for a durable launch profile with a confirmed
+repo-wide executor, and starts none when this checkout's plane is bound to that
+run. An epic with several active runs (`live-run-ambiguous`), or a run that cannot
+be read (`live-run-unknown`), is refused by name.
+
+**Preview with `--dry-run`.** `drive-epic <EPIC> --dry-run` is read-only. It reads
+the target, readiness, the live run, and the plan, runs the bootstrap's own dry-run
+validation when a plan is available, and reports the decision a real invocation
+would make — `create`, `attach`, `refuse`, or `stop` (exit `0` for the first two,
+`1` for the others). It never creates a run, cuts a branch, starts a plane,
+requests a lane, or starts or signals an executor. With `--json` (valid only with
+`--dry-run`) stdout carries exactly one JSON document with `epic_key`, `target`,
+`readiness`, `live_run`, `plan`, `summary`, `decision`, and `refusal`. The
+readiness `reason_id` and `remedy` are the strings the real refusal prints. The
+webhook URL, credentials, and policy contents are never included. The preview does
+probes only a selected loopback plane after a network readiness failure and an
+available plan. A refused port plus passing local preflight yields a conditional
+`create` with optional `cold_start` (`plane_endpoint`, `will_start_plane: true`,
+`live_run_checked: false`), `live_run: null`, and partial offline setup validation.
+The real launch attempts guarded startup, then rechecks run existence and server
+validation; the preview does not guarantee creation. Remote targets, non-refused
+port probes, and ordinary production previews keep their existing refusal or
+create behavior. `target.source` is optional and appears only for selected
+profiles (`profile` or `profile-env`).
+
 **The composed bring-up is two-phase (BAPI-1102).** With `--plan-file` on a
 repository whose readiness is missing only the runtime facts, one invocation runs,
 in order: the **control plane** (Bridge API server + reconciler, each gated on its
@@ -1209,8 +1258,10 @@ default, or, when it declares none, as an explicit recorded `no_ci_gate` mode.
 > combining `--attended` with a file that declares `posture: "unattended"` is a named
 > refusal rather than a silent winner.
 
-An unattended run has two one-time **repository** prerequisites — consent
-(`unattended_epic_implementer_allowed`) and a verified notify webhook default — plus
+An unattended run has two **repository** prerequisites — consent
+(`unattended_epic_implementer_allowed`, ON by default; the repository owner can switch
+"Allow unattended Epic Implementer runs" off and on in the Bridge admin panel's Setup
+page) and a verified notify webhook default — plus
 confirmed default-branch review/CI workflows. Each is refused by name **before any
 run row is created** (`target_not_allowed`, `webhook_unverified`,
 `repository_readiness_unconfirmed`), and `drive-epic` readiness and `doctor` both
@@ -1417,7 +1468,7 @@ If a custom pipeline has the same key as a built-in pipeline, the custom version
 | `BAPI_BASE_URL` (`executor` subcommand) | **Yes** | _(none)_ | The `executor` deliberately has **no** production fallback — it refuses to start rather than guess a target |
 | `BAPI_REPO_NAME` | Yes | _(none)_ | Jira project/repository identifier configured in Bridge API |
 | `BAPI_API_KEY` | No | _(none)_ | A Bridge credential **is** required; this environment variable is only the first place the server looks for it. When it is unset the server resolves the credential from the user-scoped store (`~/.config/bridge/credentials.json`, target `bapi:<repo>`), which is why generated MCP registrations are secret-free |
-| `BAPI_PROJECT_ROOT` | No | _(see fallback order)_ | Absolute path to project root. Anchors `BAPI_DOCS_DIR` and `BAPI_PIPELINES_DIR` resolution. Resolved once, in order: `BAPI_PROJECT_ROOT` → the connected client's MCP `roots/list` → `CLAUDE_PROJECT_DIR` → `process.cwd()`. Several paths *write* it into a generated registration (`--init`, host-config provisioning, the worktree `mcp-invoke` shim) — that is provenance, not a runtime default |
+| `BAPI_PROJECT_ROOT` | No | _(see fallback order)_ | Absolute path to project root. Anchors `BAPI_DOCS_DIR` and `BAPI_PIPELINES_DIR` resolution. Resolved once, in order: `BAPI_PROJECT_ROOT` → the connected client's MCP `roots/list` → `CLAUDE_PROJECT_DIR` → `process.cwd()`. The explicit value is validated: it is used only when it exists, is a folder, and contains `.git` (a folder, or a worktree's `.git` file) or `.bridge/config`. Otherwise it is ignored and the next source is used, so a path committed from another machine is harmless. The later sources are not validated. The server logs the chosen root and its source to stderr once (for example `Bridge MCP: project root /home/b/app (from roots/list); BAPI_PROJECT_ROOT /Users/a/app ignored: does not exist`), and `doctor` reports whether each configured value is valid. The check proves the path looks like a project, not that it is *this* project. Several paths *write* it into a generated registration (`--init`, `install`, `upgrade`, host-config provisioning, the worktree `mcp-invoke` shim) — that is provenance, not a runtime default; a git-tracked config keeps its existing value. What each host passes at start: see the per-host table in `docs/claude/cli-install-architecture.md` (§5a) |
 | `SFCC_HOSTNAME` | No | _(none)_ | SFCC sandbox hostname. Part of the environment credential tier — `SFCC_HOSTNAME`, `SFCC_CLIENT_ID`, and `SFCC_CLIENT_SECRET` must **all three** be set for that tier to apply, and a complete tier takes precedence over `dw.json` |
 | `SFCC_CLIENT_ID` | No | _(none)_ | Account Manager API client id. See `SFCC_HOSTNAME` — all three are needed together. Also required on its own when a tool is called with an explicit dotted `instance` |
 | `SFCC_CLIENT_SECRET` | No | _(none)_ | Account Manager API client secret. See `SFCC_HOSTNAME` — all three are needed together. Never sent to Bridge; it goes only to the Account Manager token endpoint |
@@ -1691,7 +1742,7 @@ The full surface, for when you need the complete enumeration. Day-to-day, use [U
 
 ### MCP tools
 
-The authoritative tool catalog covers **77 tools** (enumerated below). What's actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
+The authoritative tool catalog covers **78 tools** (enumerated below). What's actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
 
 - **Connectivity & identity** — `ping` (its JSON also carries `docs_dir`, `role`, and `customer_type`)
 - **Team & access** — `invite_member` (admin-only; mints a scoped access key for a teammate on an already-configured project — the plaintext key is shown exactly once)
@@ -1704,7 +1755,7 @@ The authoritative tool catalog covers **77 tools** (enumerated below). What's ac
 - **Jira status** — `update_jira_status` (pass `status: "auto"` to resolve the configured post-PR status server-side)
 - **Repository & CI** — `parse_repository` (`action`: `start`, `status`), `regenerate_directory_map`, `create_pull_request`, `merge_pull_request`, `resolve_ci_checks`, `poll_ci_checks`, `wait_for_ci_checks` (the last two are hidden until `ci_check_config` resolves, and share one visibility gate)
 - **Pipelines & automation** — `get_pipeline_recipe` (returns a fully resolved recipe the agent executes step-by-step)
-- **Config** — `get_project_standards`, `config_field` (operations: `get`, `update`, `list`)
+- **Config** — `get_project_standards`, `config_field` (operations: `get`, `update`, `list`), `model_thresholds` (actions: `get`, `set`, `clear`; the only way to set personal thresholds)
 
 ### Bundled pipelines
 

package/build/agent-launchers/claude-executor-adapter.js

@@ -1,4 +1,3 @@
-import { isModelTier, isValidModelAlias, resolveModelAlias } from "../agent-registry.js";
 import { evaluateClaudeMcpShadowingPolicy, inspectClaudeUserConfigForMcpShadowing, resolveClaudeUserConfigPath, } from "../claude-user-config-doctor.js";
 import { runDenyEnforcementPreflight } from "../conductor/deny-enforcement-preflight.js";
 import { buildExecutorBaseWorkerEnv } from "../executor/env.js";
@@ -7,7 +6,8 @@ import { provisionExecutorDenyLayer } from "../executor/permissions.js";
 import { WORKER_GUARD_ROOT_FLAG } from "../executor/worker-guard-hook.js";
 import { SUPPORTED_EXECUTOR_PLATFORMS, evaluateExecutorPlatform } from "../executor/platform.js";
 import { normalizeMcpServerNames } from "../executor/observation.js";
-import { supported } from "./executor-adapter.js";
+import { COMPLETION_EVIDENCE_TRANSPORT, resolveExecutorModelAlias, supported, } from "./executor-adapter.js";
+import { SUPPORTED_COMPLETION_RUNTIME, boundedIdentifier, } from "../executor/completion-contract.js";
 import { MCP_SERVER_NAME } from "../mcp-identity.js";
 /** Stable identity of this reference implementation. */
 export const CLAUDE_ADAPTER_ID = "claude-reference";
@@ -158,21 +158,12 @@ export function classifyClaudeAuthFailure(stdoutExcerpt) {
  * when it passes both registry alias validation AND the spec's static allowlist;
  * anything else falls through to tier resolution, and an unusable result is null
  * (meaning "omit `--model`") rather than an unvalidated passthrough.
+ *
+ * BAPI-1343: the rule now lives in the agent-neutral
+ * {@link resolveExecutorModelAlias}; this export delegates with no behavior change.
  */
 export function resolveClaudeModelAlias(spec, payload) {
-    const p = payload && typeof payload === "object" ? payload : {};
-    const directRaw = p.model_alias;
-    if (typeof directRaw === "string" && directRaw.trim().length > 0) {
-        const direct = directRaw.trim();
-        const allowed = !spec.staticModelAliasAllowlist || spec.staticModelAliasAllowlist.includes(direct);
-        if (isValidModelAlias(direct) && allowed) {
-            return direct;
-        }
-        // An invalid/disallowed direct alias falls through to the tier path — never
-        // returned as-is.
-    }
-    const tier = isModelTier(p.model_tier) ? p.model_tier : null;
-    return resolveModelAlias(spec, tier, null);
+    return resolveExecutorModelAlias(spec, payload);
 }
 // ---------------------------------------------------------------------------
 // Spawn shape
@@ -210,8 +201,17 @@ export function resolveClaudeModelAlias(spec, payload) {
  * Every entry is pushed SEPARATELY and never joined into a command string, so a
  * prompt or path containing a space or a shell metacharacter is just a value.
  */
-export function buildClaudeArgv(prompt, alias, mcpConfigPath, posture) {
-    const argv = ["-p", prompt, "--output-format", "stream-json", "--verbose"];
+export function buildClaudeArgv(prompt, alias, mcpConfigPath, posture, options = {}) {
+    // BAPI-1301 (D4a): the held-stdin form keeps `-p` (headless print mode) but
+    // puts NO prompt on argv — it arrives as the first stream-json user message on
+    // a held-open stdin, which is what lets the executor keep the worker alive
+    // until its required background work resolves. Everything after the input
+    // flags — output format, model, exactly one permission posture, strict MCP
+    // loading — is identical to the argv form. The default is byte-identical to the
+    // pre-BAPI-1301 golden shape.
+    const argv = options.promptTransport === "stdin-stream-json"
+        ? ["-p", "--input-format", "stream-json", "--output-format", "stream-json", "--verbose"]
+        : ["-p", prompt, "--output-format", "stream-json", "--verbose"];
     if (alias) {
         argv.push("--model", alias);
     }
@@ -219,6 +219,101 @@ export function buildClaudeArgv(prompt, alias, mcpConfigPath, posture) {
     argv.push("--strict-mcp-config", "--mcp-config", mcpConfigPath);
     return argv;
 }
+// ---------------------------------------------------------------------------
+// Held-stdin stream-json messages (BAPI-1301, D4a)
+// ---------------------------------------------------------------------------
+/**
+ * One stream-json user message as the exact NDJSON line written to the held
+ * stdin: `{"type":"user","message":{"role":"user","content":<text>}}\n`.
+ * `JSON.stringify` escapes every newline inside `text`, so one message is always
+ * exactly one line.
+ */
+function claudeStdinUserLine(text) {
+    return `${JSON.stringify({ type: "user", message: { role: "user", content: text } })}\n`;
+}
+/** The prompt as the first held-stdin user message. */
+export function buildClaudeStdinUserMessage(prompt) {
+    return claudeStdinUserLine(prompt);
+}
+/** At most this many task ids are named in a nudge. */
+const NUDGE_MAX_TASK_IDS = 16;
+/**
+ * The ONE optional-watcher nudge (BAPI-1301, D4a), sent when the worker produced
+ * its result while background tasks are still live.
+ *
+ * The wording is the safety property. It asks the worker to WAIT for tasks it
+ * needs and to stop ONLY an optional watcher it no longer needs — it never asks
+ * the worker to cancel, kill, or abandon required work to finish sooner, because
+ * a nudge that could talk a worker out of required work would turn the
+ * supervision meant to guarantee completion into a way to skip it. Task ids are
+ * passed through {@link boundedIdentifier}; anything that is not a safe opaque
+ * identifier is dropped rather than echoed.
+ */
+export function buildClaudeWatcherNudgeMessage(liveTaskIds) {
+    const ids = liveTaskIds
+        .map((id) => boundedIdentifier(id))
+        .filter((id) => id !== null)
+        .slice(0, NUDGE_MAX_TASK_IDS);
+    const named = ids.length > 0 ? ` (task ids: ${ids.join(", ")})` : "";
+    return claudeStdinUserLine(`Your result was received, but background work you started is still running${named}. ` +
+        "If that work is part of this task, wait for it to finish and then report its outcome. " +
+        "If a task is only an optional watcher you no longer need (for example a monitor or a " +
+        "background log tail), you may stop that watcher. Do not cancel, kill, or abandon any " +
+        "required work in order to finish sooner.");
+}
+// ---------------------------------------------------------------------------
+// Runtime identity probe (BAPI-1301, D4a)
+// ---------------------------------------------------------------------------
+/** Bound on the `--version` identity probe. */
+export const CLAUDE_RUNTIME_PROBE_TIMEOUT_MS = 15_000;
+/** Placeholder for a version the probe could not recognize — never matches. */
+export const UNRECOGNIZED_CLI_VERSION = "unrecognized";
+/**
+ * Parse `claude --version` output of the exact measured form
+ * `2.1.282 (Claude Code)` into `2.1.282`. Anything else is null — the raw text
+ * is never carried, because it would travel into logs and evidence.
+ */
+export function parseClaudeCliVersion(stdout) {
+    const firstLine = (typeof stdout === "string" ? stdout : "").trim().split("\n")[0]?.trim() ?? "";
+    const match = /^(\d{1,4}\.\d{1,4}\.\d{1,6}) \(Claude Code\)$/.exec(firstLine);
+    return match ? match[1] : null;
+}
+/**
+ * The completion platform id for a host: `darwin` + `arm64` is `darwin-arm64`.
+ * Every other pair is rendered as `<os>-<arch>` over a closed character set, so
+ * it is bounded and can never equal the approved id by accident.
+ */
+export function completionPlatformId(platform, arch) {
+    const clean = (value) => (typeof value === "string" ? value : "").toLowerCase().replace(/[^a-z0-9_]/g, "").slice(0, 16) ||
+        "unknown";
+    return `${clean(platform)}-${clean(arch)}`;
+}
+/**
+ * Probe the installed Claude runtime's completion identity through the INJECTED
+ * command runner (the adapter never spawns on its own authority). Resolves null
+ * when the probe could not run or exited non-zero; otherwise an identity whose
+ * `cli_version` is the parsed version or {@link UNRECOGNIZED_CLI_VERSION}. The
+ * event schema is the one this adapter's lifecycle parser speaks. Never throws.
+ */
+export async function probeClaudeCompletionRuntime(command, deps) {
+    let output;
+    try {
+        output = await deps.runCommand(command, ["--version"], {
+            timeoutMs: deps.timeoutMs ?? CLAUDE_RUNTIME_PROBE_TIMEOUT_MS,
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!output || output.exitCode !== 0)
+        return null;
+    return {
+        adapter: SUPPORTED_COMPLETION_RUNTIME.adapter,
+        cli_version: parseClaudeCliVersion(output.stdout) ?? UNRECOGNIZED_CLI_VERSION,
+        platform: completionPlatformId(deps.platform ?? process.platform, deps.arch ?? process.arch),
+        event_schema: SUPPORTED_COMPLETION_RUNTIME.event_schema,
+    };
+}
 /**
  * The single permission form for one posture — the whole policy→argv mapping,
  * in one exhaustive place.
@@ -306,9 +401,10 @@ function shellQuoteHookPath(value) {
  * where the executor's env deny-list can guarantee an ambient value never
  * substitutes for the job's own.
  */
-export function buildWorkerGuardHookCommand(binPath, execPath, worktreePath) {
+export function buildWorkerGuardHookCommand(binPath, execPath, worktreePath, correctionIntentVersion) {
     return (`${shellQuoteHookPath(execPath)} ${shellQuoteHookPath(binPath)} ` +
-        `${WORKER_GUARD_ROOT_FLAG} ${shellQuoteHookPath(worktreePath)}`);
+        `${WORKER_GUARD_ROOT_FLAG} ${shellQuoteHookPath(worktreePath)}` +
+        (correctionIntentVersion === 1 ? " --correction-intent-version 1" : ""));
 }
 // ---------------------------------------------------------------------------
 // The adapter factory
@@ -345,9 +441,24 @@ export function createClaudeExecutorAdapter(spec, deps = {}) {
             if (input.workerBranch !== undefined) {
                 envOptions.workerBranch = input.workerBranch;
             }
+            if (input.correctionIntentVersion !== undefined) {
+                envOptions.correctionIntentVersion = input.correctionIntentVersion;
+            }
             if (input.declaredTouchedFiles !== undefined) {
                 envOptions.declaredTouchedFiles = input.declaredTouchedFiles;
             }
+            // BAPI-1301 (D4a): the held-stdin transport is opted into per spawn. The
+            // argv form returns exactly the pre-BAPI-1301 three-key shape.
+            if (input.promptTransport === "stdin-stream-json") {
+                return {
+                    executable: spec.command,
+                    argv: buildClaudeArgv(input.prompt, input.modelAlias, input.mcpConfigPath, input.posture, {
+                        promptTransport: "stdin-stream-json",
+                    }),
+                    env: buildClaudeWorkerEnv(input.parentEnv, envOptions),
+                    stdinMessages: { initial: buildClaudeStdinUserMessage(input.prompt) },
+                };
+            }
             return {
                 executable: spec.command,
                 argv: buildClaudeArgv(input.prompt, input.modelAlias, input.mcpConfigPath, input.posture),
@@ -405,7 +516,7 @@ export function createClaudeExecutorAdapter(spec, deps = {}) {
             }
             const options = {
                 baseBranch: input.baseBranch,
-                workerGuardHookCommand: buildWorkerGuardHookCommand(input.workerGuardHookBinPath, deps.execPath ?? process.execPath, input.worktreePath),
+                workerGuardHookCommand: buildWorkerGuardHookCommand(input.workerGuardHookBinPath, deps.execPath ?? process.execPath, input.worktreePath, input.correctionIntentVersion),
             };
             if (input.workerBranch !== undefined) {
                 options.workerBranch = input.workerBranch;
@@ -470,6 +581,19 @@ export function createClaudeExecutorAdapter(spec, deps = {}) {
             }
         },
     };
+    /**
+     * BAPI-1301 (D4a) — declared for exactly the measured identity (Claude Code
+     * 2.1.282, macOS arm64, the lifecycle event schema this adapter parses).
+     * Declaring it is not qualifying: preflight probes the installed runtime and
+     * advertises `completion_evidence.v1` only on an exact match, so a future CLI
+     * version or another platform stays unsupported until it is measured.
+     */
+    const completionEvidence = {
+        runtime: { ...SUPPORTED_COMPLETION_RUNTIME },
+        transport: COMPLETION_EVIDENCE_TRANSPORT,
+        probeRuntime: (probeDeps) => probeClaudeCompletionRuntime(spec.command, probeDeps),
+        buildWatcherNudge: buildClaudeWatcherNudgeMessage,
+    };
     return {
         identity: {
             agentId: spec.name,
@@ -488,5 +612,6 @@ export function createClaudeExecutorAdapter(spec, deps = {}) {
         redaction: supported(redaction),
         lifecycle: supported(lifecycle),
         advisoryMcpInspection: supported(advisoryMcpInspection),
+        completionEvidence: supported(completionEvidence),
     };
 }

package/build/agent-launchers/executor-adapter.js

@@ -1,3 +1,4 @@
+import { isModelTier, isValidModelAlias, resolveModelAlias } from "../agent-registry.js";
 /** Construct a supported capability. */
 export function supported(value) {
     return { supported: true, value };
@@ -8,6 +9,68 @@ export function unsupported(reason, strategyId) {
         ? { supported: false, reason }
         : { supported: false, reason, strategyId };
 }
+/**
+ * Agent-neutral payload -> model alias rule shared by every executor adapter
+ * (BAPI-1343).
+ *
+ * A direct `model_alias` is accepted only when it passes registry alias
+ * validation AND the spec's static allowlist. Otherwise a stamped `model_tier`
+ * maps through {@link resolveModelAlias} with no repository override. Anything
+ * unusable returns null, meaning "omit the model flag". There is deliberately no
+ * job-type branch: the server decides whether to stamp a tier, and every stamped
+ * payload takes the same path.
+ */
+export function resolveExecutorModelAlias(spec, payload) {
+    const p = payload && typeof payload === "object" ? payload : {};
+    const directRaw = p.model_alias;
+    if (typeof directRaw === "string" && directRaw.trim().length > 0) {
+        const direct = directRaw.trim();
+        const allowed = !spec.staticModelAliasAllowlist || spec.staticModelAliasAllowlist.includes(direct);
+        if (isValidModelAlias(direct) && allowed) {
+            return direct;
+        }
+        // An invalid/disallowed direct alias falls through to the tier path — never
+        // returned as-is.
+    }
+    const tier = isModelTier(p.model_tier) ? p.model_tier : null;
+    return resolveModelAlias(spec, tier, null);
+}
+// ---------------------------------------------------------------------------
+// Completion evidence (job-specific, non-required) — BAPI-1301 (D4a)
+// ---------------------------------------------------------------------------
+/** The one held-stdin transport a completion-evidence adapter can declare. */
+export const COMPLETION_EVIDENCE_TRANSPORT = "held-stdin-stream-json";
+/**
+ * Validate an OPTIONAL completion-evidence declaration (BAPI-1301).
+ *
+ * Returns the usable capability or a bounded reason it cannot be used. Never a
+ * refusal of the adapter: an absent, unsupported, or malformed declaration only
+ * means the executor does not advertise `completion_evidence.v1`.
+ */
+export function resolveCompletionEvidenceCapability(adapter) {
+    const declared = adapter.completionEvidence;
+    if (declared === undefined || declared === null) {
+        return { supported: false, reason: "adapter declares no completion-evidence capability" };
+    }
+    if (declared.supported !== true) {
+        const reason = typeof declared.reason === "string" && declared.reason.length > 0
+            ? declared.reason.slice(0, 200)
+            : "completion-evidence capability is declared unsupported";
+        return { supported: false, reason };
+    }
+    const value = declared.value;
+    const runtime = value?.runtime;
+    const wellFormedRuntime = !!runtime &&
+        ["adapter", "cli_version", "platform", "event_schema"].every((key) => typeof runtime[key] === "string" && runtime[key].length > 0);
+    if (!value ||
+        !wellFormedRuntime ||
+        value.transport !== COMPLETION_EVIDENCE_TRANSPORT ||
+        typeof value.probeRuntime !== "function" ||
+        typeof value.buildWatcherNudge !== "function") {
+        return { supported: false, reason: "completion-evidence capability declaration is malformed" };
+    }
+    return { supported: true, value: value };
+}
 /**
  * The capability keys an adapter MUST supply as supported.
  *
@@ -93,10 +156,26 @@ export function validateExecutorAdapterCapabilities(adapter) {
             reason: null,
         });
     }
+    // BAPI-1301 (D4a): the job-specific completion-evidence capability is
+    // validated ONLY when declared, and its outcome never joins `refusals` — an
+    // adapter that cannot supervise required work is still a complete adapter for
+    // every other job. The key is added only when declared, so an adapter without
+    // it validates to exactly the pre-BAPI-1301 shape.
+    const optional = {};
+    if (adapter.completionEvidence !== undefined && adapter.completionEvidence !== null) {
+        const resolved = resolveCompletionEvidenceCapability(adapter);
+        optional.optionalCapabilities = [
+            {
+                capability: "completionEvidence",
+                supported: resolved.supported,
+                reason: resolved.supported ? null : resolved.reason,
+            },
+        ];
+    }
     if (refusals.length > 0) {
-        return { ok: false, identity, refusals, capabilities };
+        return { ok: false, identity, refusals, capabilities, ...optional };
     }
-    return { ok: true, identity, capabilities };
+    return { ok: true, identity, capabilities, ...optional };
 }
 /** Render a bounded, secret-free summary of why an adapter was refused. */
 export function formatAdapterRefusal(identity, refusals) {