@renzrollon/interlock 1.1.1 → 1.2.1

package/lib/host/claude-env.mjs

@@ -0,0 +1,179 @@
+// The Claude Code environment a Workflow run's routing reads (design D1, D2).
+//
+// Pure, and imports nothing: `lib/run.mjs` and `lib/doctor.mjs` both read it,
+// and neither may load an adapter — adapters spawn vendor binaries. This module
+// only parses. The spawn that learns the host's version lives beside the effort
+// probe in `./claude-cli.mjs`; what the run does with the reading is decided in
+// `decideHostEnvironment` in `lib/run.mjs`.
+//
+// Every name and number below is a fact about Claude Code, not an Interlock
+// threshold, so each is a named constant in the module that reads it — the
+// convention every `INTERLOCK_*` reader follows. The two version floors are the
+// load-bearing ones:
+//
+//   SUBAGENT_MODEL_DEFAULT_ONLY_MIN_VERSION  from 2.1.251 `CLAUDE_CODE_SUBAGENT_MODEL`
+//     sets only the DEFAULT subagent model; a model named at spawn time wins.
+//     Below it the variable replaces every agent's model. If the task-1 probe in
+//     the change's design.md shows a spawn-time model does NOT win on a current
+//     host, this constant becomes `null`, which disables the default-only reading
+//     on every version — a one-constant revert, which is why it is a constant.
+//   SUBAGENT_MODEL_FORCE_MIN_VERSION  from 2.1.257 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`
+//     forces one model onto every agent. Below it the variable is inert.
+//   MODS_MIN_HOST_VERSION  from 2.1.287 a plugin's hooks module (hooks/hooks.json
+//     `modules`) loads, so the ship meter draws. Below it the module is not
+//     loaded and the run is exactly today's; doctor's `mods` row is advice only.
+
+/** Override the binary, for a wrapper or a fixture. Read by the adapter, the doctor and the probes. */
+export const CLAUDE_COMMAND_ENV = 'INTERLOCK_CLAUDE_COMMAND'
+
+export const SUBAGENT_MODEL_ENV = 'CLAUDE_CODE_SUBAGENT_MODEL'
+export const SUBAGENT_MODEL_FORCE_ENV = 'CLAUDE_CODE_SUBAGENT_MODEL_FORCE'
+export const WORKFLOW_MAX_CONCURRENT_ENV = 'CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS'
+/** Advice only: Workflow `agent()` calls are unaffected by agent teams. */
+export const AGENT_TEAMS_ENV = 'CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS'
+/** Either one set routes the session through Bedrock, where haiku is often unreachable. */
+export const BEDROCK_ENVS = Object.freeze(['CLAUDE_CODE_USE_BEDROCK', 'AWS_BEDROCK'])
+
+export const SUBAGENT_MODEL_DEFAULT_ONLY_MIN_VERSION = '2.1.251'
+export const SUBAGENT_MODEL_FORCE_MIN_VERSION = '2.1.257'
+export const MODS_MIN_HOST_VERSION = '2.1.287'
+
+/** The vendor's accepted range for the concurrency override. Outside it, the value is not a count. */
+export const WORKFLOW_MAX_CONCURRENT_RANGE = Object.freeze({ min: 1, max: 256 })
+
+/**
+ * The installed CLI's command line: `$INTERLOCK_CLAUDE_COMMAND` or `claude`,
+ * split on whitespace — the same split the adapter applies to the same variable.
+ *
+ * @returns {string[]} `[bin, ...fixedArgs]`
+ */
+export function claudeCommandArgv(env) {
+  const raw = env && typeof env[CLAUDE_COMMAND_ENV] === 'string' ? env[CLAUDE_COMMAND_ENV].trim() : ''
+  return (raw || 'claude').split(/\s+/)
+}
+
+/**
+ * The first `major.minor.patch` in the output of `claude --version`
+ * (`2.1.274 (Claude Code)`), or null. Unknown stays unknown: nothing here
+ * guesses a version from anything else.
+ */
+export function parseClaudeVersion(text) {
+  if (typeof text !== 'string') return null
+  const m = /(\d+)\.(\d+)\.(\d+)/.exec(text)
+  return m ? `${Number(m[1])}.${Number(m[2])}.${Number(m[3])}` : null
+}
+
+/**
+ * Compare two versions numerically, part by part. Returns -1, 0 or 1, or null
+ * when either side does not parse — never a guess at an order.
+ */
+export function compareVersions(a, b) {
+  const left = parseClaudeVersion(a)
+  const right = parseClaudeVersion(b)
+  if (!left || !right) return null
+  const x = left.split('.').map(Number)
+  const y = right.split('.').map(Number)
+  for (let i = 0; i < 3; i++) {
+    if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1
+  }
+  return 0
+}
+
+/** A variable's trimmed value, or null when it is unset or blank. */
+function valueOf(env, name) {
+  const raw = env && typeof env[name] === 'string' ? env[name].trim() : ''
+  return raw || null
+}
+
+/**
+ * Whether a switch-like variable is on: non-empty and not `0` or `false` — the
+ * test the validate ping applied to the Bedrock variables, kept exactly.
+ */
+function enabled(value) {
+  return value !== null && !['0', 'false'].includes(value.toLowerCase())
+}
+
+/**
+ * What the environment, the host version and the machine say, before anything
+ * is decided from them. The raw observation is what a run stores on its
+ * manifest, so a later reader sees exactly what the decision saw.
+ *
+ * Throws only if `env` itself throws on read; every caller that hands it an
+ * environment it does not own wraps the call.
+ *
+ * @param {Record<string, string|undefined>} env
+ * @param {{version?: string|null, cpuCount?: number|null}} [host]
+ */
+export function observeClaudeEnv(env, { version = null, cpuCount = null } = {}) {
+  const force = valueOf(env, SUBAGENT_MODEL_FORCE_ENV)
+  const teams = valueOf(env, AGENT_TEAMS_ENV)
+  const rawSlots = valueOf(env, WORKFLOW_MAX_CONCURRENT_ENV)
+  let maxConcurrent = null
+  if (rawSlots !== null) {
+    const n = /^\d+$/.test(rawSlots) ? Number(rawSlots) : NaN
+    const valid =
+      Number.isInteger(n) && n >= WORKFLOW_MAX_CONCURRENT_RANGE.min && n <= WORKFLOW_MAX_CONCURRENT_RANGE.max
+    maxConcurrent = { raw: rawSlots, value: valid ? n : null, valid }
+  }
+  return {
+    version: parseClaudeVersion(version),
+    subagentModel: valueOf(env, SUBAGENT_MODEL_ENV),
+    subagentModelForce: force,
+    subagentModelForceEnabled: force !== null && enabled(force),
+    maxConcurrent,
+    agentTeams: teams,
+    bedrock: BEDROCK_ENVS.filter(name => {
+      const value = valueOf(env, name)
+      return value !== null && enabled(value)
+    }),
+    cpuCount: Number.isInteger(cpuCount) && cpuCount > 0 ? cpuCount : null
+  }
+}
+
+/**
+ * The version-aware reading of the two model variables (design D1's table),
+ * shared by the run program's decision and the doctor's advice so the two
+ * cannot read one environment two ways.
+ *
+ * An unreadable version takes the conservative reading on both: FORCE is
+ * effective and the plain variable overrides.
+ */
+export function readModelRouting(observation) {
+  const o = observation && typeof observation === 'object' ? observation : {}
+  const version = parseClaudeVersion(o.version)
+  const known = version !== null
+  const forceEffective =
+    o.subagentModelForceEnabled === true && !(known && compareVersions(version, SUBAGENT_MODEL_FORCE_MIN_VERSION) < 0)
+  const plain = typeof o.subagentModel === 'string' && o.subagentModel ? o.subagentModel : null
+  const defaultOnly =
+    !forceEffective &&
+    plain !== null &&
+    SUBAGENT_MODEL_DEFAULT_ONLY_MIN_VERSION !== null &&
+    known &&
+    compareVersions(version, SUBAGENT_MODEL_DEFAULT_ONLY_MIN_VERSION) >= 0
+  return {
+    version,
+    versionKnown: known,
+    forceEffective,
+    // Set, on a host that predates the variable: it does nothing there.
+    forceInert: o.subagentModelForceEnabled === true && !forceEffective,
+    plainDefaultOnly: defaultOnly,
+    plainOverrides: !forceEffective && plain !== null && !defaultOnly
+  }
+}
+
+/**
+ * The concurrency the runtime will honour, as far as this process can observe
+ * it (design D5): the override when it is a valid count, otherwise the vendor
+ * default — which the runtime may reduce on a small machine by an amount the
+ * vendor does not publish, so the CPU count is recorded and no number is
+ * invented. An invalid override is recorded with its raw text and otherwise
+ * read as unset.
+ */
+export function runtimeSlotsOf(observation) {
+  const o = observation && typeof observation === 'object' ? observation : {}
+  const mc = o.maxConcurrent && typeof o.maxConcurrent === 'object' ? o.maxConcurrent : null
+  const cpuCount = Number.isInteger(o.cpuCount) ? o.cpuCount : null
+  if (mc && mc.valid) return { observed: mc.value, source: 'env', cpuCount }
+  return { observed: null, source: 'vendor-default', cpuCount, ...(mc ? { invalid: mc.raw } : {}) }
+}

package/lib/host/codex.mjs

@@ -35,6 +35,7 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { assertWorkflowHost, execCapture, mapPipeline, runCli } from '../host.mjs'
+import { EFFORT_REASONS, effortRoutingEvent, resolveEffort } from './effort.mjs'
 import { parseModelMap, resolveModel } from './model-map.mjs'
 
 /** Override the binary, for a wrapper or a fixture. */
@@ -161,6 +162,9 @@ export function createCodexHost({ command, cwd = process.cwd(), env = process.en
           reason: routed.reason
         })
       }
+      // No effort channel this adapter is verified to use: argv is untouched and
+      // the not-applied verdict is spoken (design D4, D29).
+      const effort = resolveEffort(request.effort, 'unsupported', EFFORT_REASONS.notRouted)
 
       const scratch = mkdtempSync(join(tmpdir(), 'interlock-codex-'))
       const outputPath = join(scratch, 'last-message.json')
@@ -168,7 +172,7 @@ export function createCodexHost({ command, cwd = process.cwd(), env = process.en
       try {
         // Written rather than passed inline: `--output-schema` takes a path.
         if (schemaPath) writeFileSync(schemaPath, JSON.stringify(request.schema))
-        const { code, stdout, stderr, timedOut } = await execCapture(
+        const { code, stdout, stderr, timedOut, started: ran } = await execCapture(
           bin,
           [
             ...fixedArgs,
@@ -186,6 +190,10 @@ export function createCodexHost({ command, cwd = process.cwd(), env = process.en
             timeoutMs: budget
           }
         )
+        // Once the process started — a spawn that never did is a failed spawn,
+        // not an unapplied effort.
+        const routedEffort = ran ? effortRoutingEvent(label, effort) : null
+        if (routedEffort && onEvent) onEvent(routedEffort)
 
         if (code !== 0) {
           if (onEvent) {

package/lib/host/effort.mjs

@@ -0,0 +1,163 @@
+// The effort resolver every adapter shares (design D18, D19, D21, D29, D32).
+//
+// A spawn's effort comes from the run program, which read it off the published
+// table in `lib/limits.mjs`. Whether a host can apply it, and the reason when it
+// cannot, are decided here, once: the runner prints these verdicts and may not
+// word one of its own, and each adapter passes its own capability literal and
+// reason in, because the registry imports the adapters and the reverse import is
+// not available. `lib/host/model-map.mjs` is the precedent for the shape.
+//
+// Pure: no I/O, and no import of an adapter.
+
+/**
+ * Every reason a named effort can go unapplied. Each is true of the host that
+ * gives it — a host with no per-spawn channel, a host whose channel the adapter
+ * does not route, and a CLI that lacks the flag each say a different thing.
+ * `docs/04-when-it-stops.md` carries each of these verbatim.
+ */
+export const EFFORT_REASONS = Object.freeze({
+  // `qwen`, and any capability this module does not know.
+  noControl: 'host has no effort control',
+  // `codex` (D29): a real knob exists; sending it a Claude-derived label would
+  // be a cross-vendor mapping this module does not make.
+  notRouted: 'effort is not routed on this host',
+  // `claude` (D30), when its own help does not list the flag.
+  noFlag: 'this claude CLI has no --effort flag',
+  // `claude` (D30), when the help probe fails or times out.
+  probeFailed: 'could not establish whether this claude CLI accepts --effort',
+  // `acp`: the agent offered no effort option for this session.
+  noOption: 'no effort option advertised',
+  // `acp`: the option exists, and the level is not one of its flat values.
+  notAdvertised: 'level not among advertised values',
+  // `acp`: `session/set_config_option` failed.
+  rejected: 'agent rejected the effort option'
+})
+
+/**
+ * The variable the Claude CLI reads, which outranks `--effort`, `/effort`,
+ * settings and a subagent's own `effort` (D16). It is the operator's: it is
+ * bannered, never stripped (D26).
+ */
+export const EFFORT_LEVEL_ENV = 'CLAUDE_CODE_EFFORT_LEVEL'
+
+/**
+ * The operator's exported effort override, trimmed, or `''` when it is unset or
+ * blank.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string}
+ */
+export function effortLevelOverride(env) {
+  const raw = env && typeof env === 'object' ? env[EFFORT_LEVEL_ENV] : undefined
+  return typeof raw === 'string' ? raw.trim() : ''
+}
+
+/** A level as requested, or `''` when none was named. */
+function levelOf(level) {
+  return typeof level === 'string' ? level.trim() : ''
+}
+
+/**
+ * The verdict for a flag host or a host with no effort channel.
+ *
+ * The level is passed through unvalidated (D11): the published table is the
+ * authority, and a vendor CLI falls back on a level its model lacks. On a flag
+ * host "applied" means the flag was passed (D24) — the adapter cannot see past
+ * its own argv and does not claim to.
+ *
+ * Only `flag` applies. `unsupported`, and any capability this module does not
+ * know, resolve to not applied with the reason given — fail open, and spoken. A
+ * `negotiated` host does not come through here: it negotiates per session with
+ * {@link findEffortOption} and {@link pickEffortValue}.
+ *
+ * @param {string} [level]       the spawn's effort, as the step named it
+ * @param {string} [capability]  the adapter's own `effort` capability literal
+ * @param {string} [reason]      what this host says when it cannot apply one
+ * @returns {{requested: string|null, applied: boolean, via: string|null, value: string|null, reason: string|null}}
+ */
+export function resolveEffort(level, capability, reason) {
+  const requested = levelOf(level)
+  if (!requested) return { requested: null, applied: false, via: null, value: null, reason: null }
+  if (capability === 'flag') return { requested, applied: true, via: 'flag', value: requested, reason: null }
+  return {
+    requested,
+    applied: false,
+    via: null,
+    value: null,
+    reason: typeof reason === 'string' && reason ? reason : EFFORT_REASONS.noControl
+  }
+}
+
+/**
+ * The effort-routing event for one spawn, or `null` when the spawn named no
+ * effort and so must raise none.
+ *
+ * A flag or no-channel adapter emits it once the spawn's process has started,
+ * never before: a spawn that fails to start is a failed spawn, counted neither
+ * as applied nor as unapplied.
+ *
+ * @param {string} label
+ * @param {ReturnType<typeof resolveEffort>} effort
+ * @returns {object|null}
+ */
+export function effortRoutingEvent(label, effort) {
+  if (!effort || !effort.requested) return null
+  return {
+    type: 'effort-routing',
+    label,
+    requested: effort.requested,
+    applied: effort.applied,
+    via: effort.via,
+    value: effort.value,
+    reason: effort.reason
+  }
+}
+
+/**
+ * The agent's effort option, found by its conventional id or by the reserved
+ * `thought_level` category (D19) — the same two-way rule the model option is
+ * found by. A model option is never returned.
+ *
+ * @param {unknown} configOptions the config options the agent returned most recently
+ * @returns {object|null}
+ */
+export function findEffortOption(configOptions) {
+  if (!Array.isArray(configOptions)) return null
+  return (
+    configOptions.find(
+      o =>
+        o &&
+        typeof o === 'object' &&
+        o.id !== 'model' &&
+        o.category !== 'model' &&
+        (o.id === 'effort' || o.category === 'thought_level')
+    ) || null
+  )
+}
+
+/**
+ * Which advertised value a level means — exactly, or not at all (D18, D32).
+ *
+ * Exact equality on a flat `options[].value` only. No substring rule, because
+ * `high` is inside `xhigh` and an agent rejects a wrong value outright; no
+ * display-name rule; no operator map, which would be the cross-vendor mapping
+ * D29 declines. A grouped or non-select option is not read, so a level offered
+ * only inside a group is not among the advertised values.
+ *
+ * @param {string} [level]
+ * @param {object|null} [option] {@link findEffortOption}'s result
+ * @returns {{value: string|null, reason: string|null}}
+ */
+export function pickEffortValue(level, option) {
+  const wanted = levelOf(level)
+  if (!wanted) return { value: null, reason: null }
+  if (!option || typeof option !== 'object') return { value: null, reason: EFFORT_REASONS.noOption }
+  if (option.type !== undefined && option.type !== 'select') {
+    return { value: null, reason: EFFORT_REASONS.notAdvertised }
+  }
+  const flat = Array.isArray(option.options)
+    ? option.options.filter(o => o && typeof o === 'object' && typeof o.value === 'string')
+    : []
+  const hit = flat.find(o => o.value === wanted)
+  return hit ? { value: hit.value, reason: null } : { value: null, reason: EFFORT_REASONS.notAdvertised }
+}

package/lib/host/model-map.mjs

@@ -127,3 +127,46 @@ export function resolveModel(hostId, slug, map = {}, capabilities = {}) {
 
   return { value: null, applied: false, reason: `no mapping for ${wanted}` }
 }
+
+/** The tier slugs a planner routes by, which match any id that carries the tier. */
+const TIER_SLUGS = Object.freeze(['haiku', 'sonnet', 'opus'])
+
+/** A model id as comparable tokens: lowercased, provider prefix and date stamp dropped. */
+function modelTokens(value) {
+  const tokens = String(value).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
+  const claude = tokens.indexOf('claude')
+  const rest = claude > 0 ? tokens.slice(claude) : tokens
+  return rest.length > 1 && /^\d{8}$/.test(rest[rest.length - 1]) ? rest.slice(0, -1) : rest
+}
+
+/**
+ * Whether a served model is the model a spawn was routed to (design D6).
+ *
+ * THE ONLY COMPARISON of a routed model against a served one, on either host:
+ * `modelSubstitution` in `lib/run.mjs` calls it, and nothing else may.
+ * Plain equality would banner every lane, because the run routes `sonnet` and
+ * the host serves `claude-sonnet-5-5`; a prefix test misses `bedrock.`; a fuzzy
+ * one is a guess, and a wrong model that ran would be invisible, which is the
+ * failure the banner exists to name. So:
+ *
+ *   - both are lowercased and split on runs of non-alphanumerics;
+ *   - every token before the first `claude` token is dropped (a provider prefix);
+ *   - a trailing token of exactly eight digits is dropped (a date stamp);
+ *   - a bare tier slug matches any served id that carries that tier token;
+ *   - anything else matches only the same token list.
+ *
+ * `sonnet` matches `bedrock.claude-sonnet-5-5`; `claude-sonnet-5-5` matches
+ * `claude-sonnet-5-5-20261001`; `claude-sonnet-5` does not match
+ * `claude-sonnet-5-5`; `sonnet` does not match `claude-opus-5-5`.
+ *
+ * @param {string} routed  the model the spawn was sent with
+ * @param {string} served  one model the host reports having served
+ * @returns {boolean|null} `null` when either side is empty: no comparison was made
+ */
+export function modelMatches(routed, served) {
+  const want = typeof routed === 'string' ? modelTokens(routed) : []
+  const got = typeof served === 'string' ? modelTokens(served) : []
+  if (!want.length || !got.length) return null
+  if (want.length === 1 && TIER_SLUGS.includes(want[0])) return got.includes(want[0])
+  return want.length === got.length && want.every((token, i) => token === got[i])
+}

package/lib/host/qwen.mjs

@@ -27,6 +27,7 @@
 // the tier the planner asked for.
 
 import { assertWorkflowHost, execCapture, mapPipeline, parseAgentJson, runCli } from '../host.mjs'
+import { effortRoutingEvent, resolveEffort } from './effort.mjs'
 import { parseModelMap, resolveModel } from './model-map.mjs'
 
 /** Override the binary, for a wrapper or a fixture. */
@@ -132,8 +133,11 @@ export function createQwenHost({ command, cwd = process.cwd(), env = process.env
           reason: routed.reason
         })
       }
+      // No effort channel this adapter is verified to use: argv is untouched and
+      // the not-applied verdict is spoken (design D4, D29).
+      const effort = resolveEffort(request.effort, 'unsupported')
 
-      const { code, stdout, stderr, timedOut } = await execCapture(
+      const { code, stdout, stderr, timedOut, started: ran } = await execCapture(
         bin,
         [...fixedArgs, ...qwenArgs(request, { model: routed.value })],
         {
@@ -143,6 +147,10 @@ export function createQwenHost({ command, cwd = process.cwd(), env = process.env
           timeoutMs: budget
         }
       )
+      // Once the process started — a spawn that never did is a failed spawn,
+      // not an unapplied effort.
+      const routedEffort = ran ? effortRoutingEvent(label, effort) : null
+      if (routedEffort && onEvent) onEvent(routedEffort)
 
       if (code !== 0) {
         if (onEvent) {

package/lib/host/registry.mjs

@@ -7,11 +7,13 @@
 // directory implementing the three-function port in `../host.mjs`, plus a
 // declaration of what it cannot do.
 //
-// The declaration is the load-bearing half. Every adapter states the same seven
+// The declaration is the load-bearing half. Every adapter states the same eight
 // facts, and the run program reads them rather than branching on an id:
 //
 //   schemaEnforced  does the CLI itself validate the result against the schema
 //   modelSelect     'flag' | 'negotiated' | 'map-only' — how a slug becomes a model
+//                   ('forced' is observed by run start, never declared)
+//   effort          'flag' | 'negotiated' | 'unsupported' — how a named effort is applied
 //   worktree        'driver' | 'runtime' — who creates a lane's worktree
 //   hooks           do this repository's PreToolUse guards fire on this host
 //   usage           does the CLI report token usage
@@ -32,7 +34,7 @@
 // `/interlock:ship`, it owns its own worktrees (`worktree: 'runtime'`), and the
 // runner refuses its id (design D10).
 
-import { createAcpHost, isClaudeCodeBinary, parseAcpCommand, ACP_COMMAND_ENV } from './acp.mjs'
+import { createAcpHost, isClaudeBackedCommand, parseAcpCommand, ACP_COMMAND_ENV } from './acp.mjs'
 import { createClaudeHost } from './claude-cli.mjs'
 import { createCodexHost } from './codex.mjs'
 import { createQwenHost } from './qwen.mjs'
@@ -41,6 +43,7 @@ import { createQwenHost } from './qwen.mjs'
 export const CAPABILITY_KEYS = Object.freeze([
   'schemaEnforced',
   'modelSelect',
+  'effort',
   'worktree',
   'hooks',
   'usage',
@@ -51,11 +54,22 @@ export const CAPABILITY_KEYS = Object.freeze([
 /** The allowed value of each declared capability. */
 export const CAPABILITY_VALUES = Object.freeze({
   schemaEnforced: Object.freeze([true, false]),
-  modelSelect: Object.freeze(['flag', 'negotiated', 'map-only']),
+  // `forced`: an environment variable forces one model onto every spawned
+  // agent, so the per-spawn channel is ignored. OBSERVED ONLY — no adapter may
+  // declare it; `interlock run start` on the Workflow host records it when
+  // `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` is in effect.
+  modelSelect: Object.freeze(['flag', 'negotiated', 'map-only', 'forced']),
+  // `unsupported`: no effort channel the adapter is verified to use on this
+  // host — no per-spawn channel at all, or one the adapter does not route.
+  effort: Object.freeze(['flag', 'negotiated', 'unsupported']),
   worktree: Object.freeze(['driver', 'runtime']),
   hooks: Object.freeze([true, false]),
   usage: Object.freeze([true, false]),
-  cacheAccounting: Object.freeze([true, false]),
+  // `hook`: the cache figures were recorded by the plugin's recorder hooks, not
+  // reported by the host. OBSERVED ONLY — no adapter may declare it; `run close`
+  // sets it when every briefed spawn of the run joined a recorded transcript
+  // (`ship/agent-results`).
+  cacheAccounting: Object.freeze([true, false, 'hook']),
   billing: Object.freeze(['claude-subscription-programmatic', 'chatgpt-plan-or-api', 'local'])
 })
 
@@ -74,6 +88,10 @@ export const HOSTS = Object.freeze({
     capabilities: Object.freeze({
       schemaEnforced: true,
       modelSelect: 'flag',
+      // `claude --help` on 2.1.285 lists `--effort <level>`, and it works with
+      // `-p`. Refined at creation: the adapter probes `--help` once and observes
+      // `unsupported` when the installed CLI does not list the flag (D30).
+      effort: 'flag',
       worktree: 'driver',
       hooks: true,
       usage: true,
@@ -88,12 +106,18 @@ export const HOSTS = Object.freeze({
     id: 'acp',
     create: opts => createAcpHost(opts),
     // Declared for the general case — an arbitrary agent behind
-    // `INTERLOCK_ACP_COMMAND`. The adapter refines `hooks` and `billing` at
-    // creation when that command turns out to be the Claude binary, because a
-    // run that IS spending a Claude subscription must say so (design D8).
+    // `INTERLOCK_ACP_COMMAND`. The adapter refines `hooks` when that command is
+    // the Claude binary, and `billing` when it is the binary or a known wrapper
+    // (`claude-agent-acp`, `claude-code-acp`), because a run that IS spending a
+    // Claude subscription must say so. A wrapper does not load this plugin's
+    // hooks, so those stay false and HOOKS NOT IN FORCE still prints.
     capabilities: Object.freeze({
       schemaEnforced: false,
       modelSelect: 'negotiated',
+      // The protocol has no effort field; claude-agent-acp 0.84.0 advertises a
+      // config option (id `effort`, category `thought_level`) that is set with
+      // `session/set_config_option`, so the adapter asks the agent per session.
+      effort: 'negotiated',
       worktree: 'driver',
       hooks: false,
       usage: false,
@@ -109,6 +133,10 @@ export const HOSTS = Object.freeze({
     capabilities: Object.freeze({
       schemaEnforced: true,
       modelSelect: 'map-only',
+      // `codex exec -c model_reasoning_effort=<lvl>` exists, but it is outside
+      // this adapter's verified contract, and a Claude-derived label sent to it
+      // would be a cross-vendor mapping (D29). A channel not routed.
+      effort: 'unsupported',
       worktree: 'driver',
       hooks: false,
       usage: true,
@@ -124,6 +152,9 @@ export const HOSTS = Object.freeze({
     capabilities: Object.freeze({
       schemaEnforced: true,
       modelSelect: 'map-only',
+      // Qwen Code reads `model.reasoningEffort` from settings files only; its
+      // CLI has no per-spawn effort channel at all (D4).
+      effort: 'unsupported',
       worktree: 'driver',
       hooks: false,
       usage: false,
@@ -189,8 +220,11 @@ function effectiveCapabilities(entry, host) {
 }
 
 /**
- * Whether a host id, as configured, drives the Claude binary — directly or
- * through ACP. The `SUBSCRIPTION PATH` banner's condition (design D8).
+ * Whether a host id, as configured, drives Claude — the CLI directly, or an
+ * ACP command that is the CLI or a known wrapper around it. The `SUBSCRIPTION
+ * PATH` and `EFFORT ROUTING OVERRIDDEN` banners' condition. A wrapper is
+ * recognised by its own command name (`claude-agent-acp`, `claude-code-acp`),
+ * not by an argument of `npx`.
  *
  * @param {string} id
  * @param {Record<string, string|undefined>} [env]
@@ -204,7 +238,7 @@ export function drivesClaudeBinary(id, env = {}, acpCommand) {
     ? acpCommand
     : (env && env[ACP_COMMAND_ENV]) || ''
   try {
-    return isClaudeCodeBinary(parseAcpCommand(raw).command)
+    return isClaudeBackedCommand(parseAcpCommand(raw).command)
   } catch {
     // An unusable command is not a Claude run; the adapter's own creation error
     // is what the operator will see.