@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/hooks/category_a.ts

@@ -23,6 +23,7 @@
  * grant — the host's own strings record `permissionDecision=allow ignored: a
  * confined session takes grants only from its command line`.
  */
+import * as fs from "node:fs";
 import * as path from "node:path";
 
 /** A JSON-ish tool input as it arrives in the dispatcher envelope. */
@@ -145,7 +146,46 @@ export function isInsideWorkingTree(candidate: string, root: string): boolean {
     const abs = path.resolve(root, candidate);
     const rel = path.relative(path.resolve(root), abs);
     if (rel === "") return true;
-    return !rel.startsWith("..") && !path.isAbsolute(rel);
+    // `..` as a whole first segment escapes; `...` or `..cache` is a name.
+    const escapes = rel === ".." || rel.startsWith(`..${path.sep}`);
+    return !escapes && !path.isAbsolute(rel);
+}
+
+/** `p` with every symlink in its longest existing prefix resolved. */
+function _real(p: string): string {
+    try {
+        return fs.realpathSync(p);
+    } catch (e) {
+        const code = (e as NodeJS.ErrnoException).code;
+        if (code !== "ENOENT" && code !== "ENOTDIR") return "";
+        // A dangling link is not a missing suffix: its target is unknowable.
+        try {
+            if (code === "ENOENT" && fs.lstatSync(p, { throwIfNoEntry: false })?.isSymbolicLink()) return "";
+        } catch {
+            return "";
+        }
+        const parent = path.dirname(p);
+        if (parent === p) return p;
+        const up = _real(parent);
+        return up && path.join(up, path.basename(p));
+    }
+}
+
+/**
+ * {@link isInsideWorkingTree}, and still inside once symlinks are followed.
+ *
+ * The one place the classifier reads the filesystem, and it can only withhold:
+ * an in-tree symlink to `~/.ssh` is lexically inside and really outside. A
+ * missing suffix keeps its lexical answer; a dangling link and any other
+ * resolution failure (`EACCES`, `ELOOP`) resolve to `""`, which is never inside. The check runs
+ * before the command does, so a link swapped in between is not seen — the
+ * OS sandbox is the boundary, this is a guardrail.
+ */
+function _reallyInside(candidate: string, root: string): boolean {
+    if (!isInsideWorkingTree(candidate, root)) return false;
+    const real = _real(path.resolve(root, candidate));
+    const realRoot = _real(path.resolve(root));
+    return real !== "" && realRoot !== "" && isInsideWorkingTree(real, realRoot);
 }
 
 /** Split a command on whitespace; the caller has already refused metacharacters. */
@@ -182,7 +222,7 @@ const GIT_VALUE_FLAGS: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * The `git` subcommand, with global options skipped.
+ * The `git` subcommand and its argv index, with global options skipped.
  *
  * Returns `""` when a global option's VALUE escapes the working tree — an
  * absolute path or a `..` traversal. The check is textual rather than resolved
@@ -190,21 +230,127 @@ const GIT_VALUE_FLAGS: ReadonlySet<string> = new Set([
  * can decide is exactly the property that matters, and a relative path with no
  * `..` cannot escape.
  */
-function _gitSubcommand(argv: readonly string[]): string {
+function _gitSubcommandAt(argv: readonly string[]): { sub: string; index: number } {
     for (let i = 1; i < argv.length; i++) {
         const token = argv[i] as string;
-        if (!_isFlag(token)) return token;
+        if (!_isFlag(token)) return { sub: token, index: i };
         const [flag, inlineValue] = token.includes("=")
             ? [token.slice(0, token.indexOf("=")), token.slice(token.indexOf("=") + 1)]
             : [token, null];
         const value = inlineValue ?? (GIT_VALUE_FLAGS.has(flag) ? argv[++i] : undefined);
         if (value !== undefined && (path.isAbsolute(value) || value.split("/").includes(".."))) {
-            return "";
+            return { sub: "", index: -1 };
         }
     }
-    return "";
+    return { sub: "", index: -1 };
+}
+
+/**
+ * `git branch` is category A only in its observational forms — an allowlist,
+ * like the rest of this file. Every other form writes a ref: `-d`/`-D` and
+ * `-f`/`-m`/`-M`/`-C` can lose one, and a bare `git branch <name>`, `-c`,
+ * `-u` or `--edit-description` create or rewrite one. A positional operand is
+ * admitted only under `-l`/`--list`, where it is a pattern, or as the value of
+ * a filter flag.
+ */
+const GIT_BRANCH_OBSERVES =
+    /^(-[arlvi]+|--(all|remotes|list|verbose|show-current|(no-)?color)(=.*)?)$/;
+const GIT_BRANCH_FILTER = /^--((no-)?(contains|merged)|points-at|sort|format|abbrev)(=|$)/;
+
+function _gitBranchOnlyObserves(argv: readonly string[], index: number): boolean {
+    const rest = argv.slice(index + 1);
+    const listing = rest.some((t) => /^(-[arvi]*l[arlvi]*|--list)$/.test(t));
+    for (let i = 0; i < rest.length; i++) {
+        const token = rest[i] as string;
+        if (!_isFlag(token)) {
+            if (!listing) return false;
+        } else if (GIT_BRANCH_FILTER.test(token)) {
+            if (!token.includes("=") && !_isFlag(rest[i + 1] ?? "-")) i++;
+        } else if (!GIT_BRANCH_OBSERVES.test(token)) {
+            return false;
+        }
+    }
+    return true;
 }
 
+/**
+ * Heads that never open their arguments, so a path-shaped argument is a string
+ * and confining it would only put a prompt on `echo /tmp`. Not `date`: its
+ * `-f`/`--file` and `-r`/`--reference` open a path.
+ */
+const NON_OPENING_HEADS = /^(pwd|echo|basename|dirname|which)$/;
+
+/**
+ * Output-writing flags (0.3). Their target is a path like any other, and the
+ * walk below confines every spelling: a separate value token (`--output x`,
+ * `-fprint x`, `--outDir x`) is a positional, `--output=x` is an inline value,
+ * a glued short value (`sort -o/path`) is the tail of a single-dash token, and
+ * the value-less writers (`--write`/`-w`, `--fix`) write their positionals. So
+ * no per-head table is needed; one was measured inert and removed.
+ *
+ * For `grep`/`rg` the first positional, or an `-e`/`--regexp` value, is a
+ * pattern and therefore data; an `-f`/`--file` value is a path.
+ */
+const PATTERN_GIVEN = /^(-e|--regexp|-f|--file)(=|$)/;
+
+/**
+ * Every argument of a Bash command that may name a filesystem location.
+ *
+ * Positionals, flag inline values and the tail of a single-dash token
+ * (`-o/path`, `-f/path`) are all candidates: one that stays inside is harmless
+ * to check, and missing one is not. After `--` every token is a positional.
+ * Shell quote removal is applied; every other expansion is refused upstream by
+ * the metacharacter rule.
+ */
+function _pathArguments(argv: readonly string[], head: string): string[] {
+    const out: string[] = [];
+    const grep = head === "grep" || head === "rg";
+    let patternPending = grep && !argv.some((t) => PATTERN_GIVEN.test(t));
+    let endOfOptions = false;
+    for (let i = 1; i < argv.length; i++) {
+        const raw = argv[i] as string;
+        // An unquoted glob is expanded after this check, so what it selects
+        // (`.*` to `..`, `le*` to an outward symlink) is never seen. "*" is a
+        // candidate nothing confines.
+        if (/[*?[]/.test(raw.replace(/'[^']*'|"[^"]*"/g, ""))) out.push("*");
+        const token = raw.replace(/["']/g, "");
+        if (!endOfOptions && token === "--") {
+            endOfOptions = true;
+        } else if (endOfOptions || !_isFlag(token)) {
+            if (patternPending) patternPending = false;
+            else out.push(token);
+        } else if (grep && /^(-e|--regexp)$/.test(token)) {
+            i++;
+        } else if (grep && /^(-f|--file)$/.test(token)) {
+            out.push((argv[++i] ?? "").replace(/["']/g, ""));
+        } else {
+            // A dash-led token may itself be the value of the option before it
+            // (`sort -o --/../x`), so one that contains `/` is a path too.
+            if (token.includes("/")) out.push(token);
+            const eq = token.indexOf("=");
+            if (eq >= 0) out.push(token.slice(eq + 1));
+            else if (!token.startsWith("--") && token.length > 2) out.push(token.slice(2));
+        }
+    }
+    return out;
+}
+
+/** Stands in for the tree when the caller has none: absolute and `..` still escape it. */
+const UNROOTED = path.resolve("/agent-config-unrooted");
+
+function _confined(candidate: string, workingTree: string): boolean {
+    if (candidate.startsWith("~") || candidate === "*") return false;
+    return _reallyInside(candidate, workingTree.trim() ? workingTree : UNROOTED);
+}
+
+/** What the classifier decided, and whether a path confinement actually ran. */
+export interface CategoryAVerdict {
+    categoryA: boolean;
+    confined: boolean;
+}
+
+const NOT_A: CategoryAVerdict = { categoryA: false, confined: false };
+
 /** Non-flag token after the subcommand, or `""`. */
 function _secondSubcommand(argv: readonly string[]): string {
     const nonFlags = argv.slice(1).filter((t) => !_isFlag(t));
@@ -231,20 +377,14 @@ export function namesConsequenceOperation(command: string): boolean {
     return false;
 }
 
-/** Is this Bash command string category A? */
-export function isCategoryABashCommand(command: string): boolean {
-    if (typeof command !== "string" || !command.trim()) return false;
-    if (SHELL_METACHARACTERS.test(command)) return false;
-    if (namesConsequenceOperation(command)) return false;
-
-    const argv = _argv(command);
-    const head = (argv[0] ?? "").toLowerCase();
-    if (!head) return false;
-
+/** Does the head and its subcommand name a read, build, test or lint? */
+function _namesASafeOperation(argv: readonly string[], head: string): boolean {
     if (SAFE_HEADS.has(head)) return true;
 
     if (head === "git") {
-        return GIT_READ_SUBCOMMANDS.has(_gitSubcommand(argv));
+        const { sub, index } = _gitSubcommandAt(argv);
+        if (!GIT_READ_SUBCOMMANDS.has(sub)) return false;
+        return sub !== "branch" || _gitBranchOnlyObserves(argv, index);
     }
 
     const allowed = RUNNER_SUBCOMMANDS[head];
@@ -258,6 +398,36 @@ export function isCategoryABashCommand(command: string): boolean {
     return true;
 }
 
+/**
+ * Classify a Bash command string.
+ *
+ * `workingTree` is the root every path argument must resolve inside. Without
+ * one, the command is judged against a stand-in root, so an absolute, `~` or
+ * `..`-escaping argument still disqualifies it.
+ */
+export function bashCategoryAVerdict(command: string, workingTree = ""): CategoryAVerdict {
+    if (typeof command !== "string" || !command.trim()) return NOT_A;
+    if (SHELL_METACHARACTERS.test(command)) return NOT_A;
+    if (namesConsequenceOperation(command)) return NOT_A;
+
+    const argv = _argv(command);
+    const head = (argv[0] ?? "").toLowerCase();
+    if (!head) return NOT_A;
+    if (!_namesASafeOperation(argv, head)) return NOT_A;
+
+    if (NON_OPENING_HEADS.test(head)) return { categoryA: true, confined: false };
+    const candidates = _pathArguments(argv, head);
+    for (const candidate of candidates) {
+        if (!_confined(candidate, workingTree)) return NOT_A;
+    }
+    return { categoryA: true, confined: candidates.length > 0 };
+}
+
+/** Is this Bash command string category A? */
+export function isCategoryABashCommand(command: string, workingTree = ""): boolean {
+    return bashCategoryAVerdict(command, workingTree).categoryA;
+}
+
 /**
  * Is this tool call category A?
  *
@@ -265,27 +435,34 @@ export function isCategoryABashCommand(command: string): boolean {
  * root means the dispatcher could not establish one, and an unestablished
  * boundary is not a boundary — the call is not category A.
  */
-export function isCategoryA(
+export function categoryAVerdict(
     toolName: string,
     toolInput: ToolInput,
     workingTree: string,
-): boolean {
-    if (!workingTree.trim()) return false;
-    if (typeof toolName !== "string" || !toolName) return false;
+): CategoryAVerdict {
+    if (!workingTree.trim()) return NOT_A;
+    if (typeof toolName !== "string" || !toolName) return NOT_A;
 
     if (READ_ONLY_TOOLS.has(toolName)) {
+        let checked = false;
         for (const key of PATH_KEYS) {
             const value = toolInput?.[key];
             if (typeof value !== "string") continue;
-            if (!isInsideWorkingTree(value, workingTree)) return false;
+            if (!_reallyInside(value, workingTree)) return NOT_A;
+            checked = true;
         }
-        return true;
+        return { categoryA: true, confined: checked };
     }
 
     if (toolName === "Bash") {
         const command = toolInput?.["command"];
-        return typeof command === "string" && isCategoryABashCommand(command);
+        return typeof command === "string" ? bashCategoryAVerdict(command, workingTree) : NOT_A;
     }
 
-    return false;
+    return NOT_A;
+}
+
+/** Is this tool call category A? */
+export function isCategoryA(toolName: string, toolInput: ToolInput, workingTree: string): boolean {
+    return categoryAVerdict(toolName, toolInput, workingTree).categoryA;
 }

package/src/scripts/hooks/concern_failure_policy.ts

@@ -95,12 +95,12 @@ export function _is_blocking(concern: JsonObject): boolean {
  * it is honoured, however slow it was.
  *
  * THE ONE-RETRY ESCAPE, AND WHY THE STOP SLOT NEEDS IT.
- * `turn-end-gate` and `run-continuation` are `severity: blocking` on `stop`,
- * and `tests/hooks/concern_severity.test.ts` records the hazard in as many
- * words: a turn-end gate that fails closed "does not degrade, it wedges the
- * session". Neither carries `skip_on_refusal_retry`, so without this clause a
- * DETERMINISTIC crash in either would refuse every Stop, indefinitely, with no
- * escape the user can reach.
+ * `turn-end-gate` is `severity: blocking` on `stop` (`run-continuation` was too,
+ * until it was withdrawn), and `tests/hooks/concern_severity.test.ts` records
+ * the hazard in as many words: a turn-end gate that fails closed "does not
+ * degrade, it wedges the session". It carries no `skip_on_refusal_retry`, so
+ * without this clause a DETERMINISTIC crash in it would refuse every Stop,
+ * indefinitely, with no escape the user can reach.
  *
  * So the promotion is spent ONCE. On the retry the host itself marks
  * (`stop_hook_active`, read by `_is_refusal_retry`) a crash falls back to

package/src/scripts/hooks/concern_registry.ts

@@ -24,7 +24,6 @@
  *              fail-closed reduction unchanged)
  */
 
-import { main as chatHistoryMain } from '../chat_history.js';
 import { main as hotContextMain } from '../hot_context_hook.js';
 import { main as handoffContextMain } from '../handoff_context_hook.js';
 import { main as roadmapProgressMain } from '../roadmap_progress_hook.js';
@@ -55,6 +54,7 @@ import { main as blockKernelRuleWritesMain } from './block_kernel_rule_writes.js
 import { main as blockPlumbingWritesMain } from './block_plumbing_writes.js';
 import { main as blockConfigWeakeningMain } from './block_config_weakening.js';
 import { main as blockSpeakingInboxDirMain } from './block_speaking_inbox_dir.js';
+import { main as blockCredentialReadsMain } from './block_credential_reads.js';
 import { main as oneQuestionPerAskMain } from './one_question_per_ask_hook.js';
 import { main as rtkWrapMain } from './rtk_wrap_hook.js';
 import { _main as designPassMain } from './design_pass_hook.js';
@@ -81,18 +81,19 @@ import { main as sessionEolMain } from './session_eol_hook.js';
 import { main as subagentLedgerMain } from './subagent_ledger_hook.js';
 import { main as toolResultBytesMain } from './tool_result_bytes_hook.js';
 import { main as spawnGuardShadowMain } from './spawn_guard_shadow_hook.js';
+import { main as hostRateMarkerMain } from './host_rate_marker_hook.js';
 import { main as sourceFirstGateMain } from './source_first_gate_hook.js';
 import { main as interruptionLedgerMain } from './interruption_ledger_hook.js';
-import { main as runContinuationMain } from './run_continuation_hook.js';
 import { main as journalRecordMain } from './journal_record_hook.js';
 import { main as obligationSettleMain } from './obligation_settle_hook.js';
 
-/** A concern `main` — argv-taking or not; both shapes exist. */
-export type ConcernMain = (argv?: string[]) => number | undefined | void;
+import { LAZY_CONCERNS, loadLazyConcern } from './lazy_concern.js';
+import type { ConcernMain } from './concern_registry_types.js';
+
+export type { ConcernMain };
 
 /** Keyed by the manifest's `script:` value (repo-relative path). */
 export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
-    'src/scripts/chat_history.ts': chatHistoryMain as ConcernMain,
     'src/scripts/hot_context_hook.ts': hotContextMain as ConcernMain,
     'src/scripts/handoff_context_hook.ts': handoffContextMain as ConcernMain,
     'src/scripts/roadmap_progress_hook.ts': roadmapProgressMain as ConcernMain,
@@ -123,6 +124,7 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/hooks/block_plumbing_writes.ts': blockPlumbingWritesMain as ConcernMain,
     'src/scripts/hooks/block_config_weakening.ts': blockConfigWeakeningMain as ConcernMain,
     'src/scripts/hooks/block_speaking_inbox_dir.ts': blockSpeakingInboxDirMain as ConcernMain,
+    'src/scripts/hooks/block_credential_reads.ts': blockCredentialReadsMain as ConcernMain,
     'src/scripts/hooks/one_question_per_ask_hook.ts': oneQuestionPerAskMain as ConcernMain,
     'src/scripts/hooks/rtk_wrap_hook.ts': rtkWrapMain as ConcernMain,
     'src/scripts/hooks/design_pass_hook.ts': designPassMain as ConcernMain,
@@ -150,8 +152,31 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/hooks/subagent_ledger_hook.ts': subagentLedgerMain as ConcernMain,
     'src/scripts/hooks/tool_result_bytes_hook.ts': toolResultBytesMain as ConcernMain,
     'src/scripts/hooks/spawn_guard_shadow_hook.ts': spawnGuardShadowMain as ConcernMain,
+    'src/scripts/hooks/host_rate_marker_hook.ts': hostRateMarkerMain as ConcernMain,
     'src/scripts/hooks/source_first_gate_hook.ts': sourceFirstGateMain as ConcernMain,
     'src/scripts/hooks/interruption_ledger_hook.ts': interruptionLedgerMain as ConcernMain,
-    'src/scripts/hooks/run_continuation_hook.ts': runContinuationMain as ConcernMain,
     'src/scripts/hooks/journal_record_hook.ts': journalRecordMain as ConcernMain,
 };
+
+/**
+ * Every concern the dispatcher can run in-process: inlined in the table above,
+ * or loadable from a conditional chunk. The parity test asserts against THIS,
+ * not against `CONCERN_REGISTRY` alone — a lazy concern is still in-process on
+ * the fast path, and a parity check that could not see one would push the next
+ * extraction back into the bundle.
+ */
+export function isInProcessConcern(script: string): boolean {
+    return CONCERN_REGISTRY[script] !== undefined || LAZY_CONCERNS[script] !== undefined;
+}
+
+/**
+ * The concern's `main`, inlined or loaded from its chunk, or `null` when the
+ * dispatcher must fall back to the spawn path.
+ *
+ * The one resolver. The dispatcher and every test that drives a concern
+ * in-process go through it, so a concern moved into a chunk does not have to be
+ * found again at each call site.
+ */
+export function resolveConcernMain(script: string): ConcernMain | null {
+    return CONCERN_REGISTRY[script] ?? loadLazyConcern(script);
+}

package/src/scripts/hooks/concern_registry_types.ts

@@ -0,0 +1,11 @@
+/**
+ * The concern-invocation type, in a module that imports nothing.
+ *
+ * `hooks/lazy_concern.ts` needs the type and `concern_registry.ts` needs the
+ * loader, so the type cannot live in either without a cycle. It is five lines,
+ * so it gets its own file rather than a `import type` indirection nobody can
+ * follow.
+ */
+
+/** A concern `main` — argv-taking or not; both shapes exist. */
+export type ConcernMain = (argv?: string[]) => number | undefined | void;

package/src/scripts/hooks/delegation_nudge_hook.ts

@@ -97,12 +97,15 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { readHookStdin } from "./hook_stdin.js";
 import { load_agent_settings } from "../_lib/agent_settings.js";
 import { probeHostCapabilities } from "../_lib/host_capability.js";
-import type { ActivationInputs, Classification, TaskSignals } from "../_lib/auto_dispatch.js";
+import { inferSliceTier, type ActivationInputs, type Classification, type SliceType, type TaskSignals } from "../_lib/auto_dispatch.js";
+import { TIER_TO_CLAUDE_MODEL } from "../_lib/model_tier.js";
 import { classifyLadder, type LadderRung } from "../_lib/judgment_ladder.js";
 import { resolveSessionRole } from "../_lib/session_role.js";
 import { resolveSubagentRouting, type Tier } from "../_lib/subagent_routing.js";
 import { isSyntheticPrompt } from "../_lib/prompt_shape.js";
+import { handKindFromPrompt, type HandKind } from "../_lib/hand_kinds.js";
 import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
+import { councilConfigPath, freeRungFor } from "../ai_council/free_rung.js";
 
 // Severity is taken from the EXIT CODE, not from the `decision` field in the
 // stdout payload — mirrors `language_mirror_hook.ts`'s own note (found the
@@ -330,16 +333,18 @@ export function resolveActivation(
 }
 
 /**
- * Tier recommendation for the (not-yet-inspected) slices: `resolveSubagentRouting`'s
- * first production caller. Conservative "lite, downshifted" default — the
- * concern has no per-slice type classification available at prompt-submit
- * time, so it recommends the cheapest starting point and lets the downshift
- * setting (shipped default: on) decide whether that survives.
+ * Tier recommendation for the slices, from the cheapest-sufficient table
+ * (`inferSliceTier`) and never from a default: an unknown slice kind is
+ * `inherit`, so the nudge cannot name a tier the table did not produce.
  */
-export function recommendSliceTier(downshift: boolean, separate_quota_pool: boolean): Tier {
+export function recommendSliceTier(
+  downshift: boolean,
+  separate_quota_pool: boolean,
+  sliceKind: SliceType = "unknown",
+): Tier {
   const decision = resolveSubagentRouting({
-    task_tier: "lite",
-    session_tier: "high",
+    task_tier: inferSliceTier({ slice_type: sliceKind }).tier,
+    session_tier: "inherit",
     downshift,
     quota_arbitrage: false,
     model_map: {},
@@ -348,6 +353,28 @@ export function recommendSliceTier(downshift: boolean, separate_quota_pool: bool
   return decision.tier;
 }
 
+const READ_ONLY_FANOUT_RE =
+  /\b(find|locate|search|grep|list|inventor(?:y|ise|ize)|enumerate|count|which files|where (?:is|are)|finde|suche|liste|z(?:ä|ae)hle|wo (?:ist|sind))\b/i;
+const MUTATING_RE =
+  /\b(fix|implement|edit|write|refactor|change|add|create|remove|delete|update|rename|migrate|build|move|replace|mach|bau|implementier\w*|(?:ä|ae)nder\w*|erstell\w*|l(?:ö|oe)sch\w*|f(?:ü|ue)g\w*|schreib\w*)\b/i;
+
+/**
+ * The slice kind a prompt names, deterministically: a read verb with no
+ * mutating verb is a read-only fan-out; everything else is `unknown`, which
+ * the table maps to `inherit`.
+ */
+export function sliceKindFromPrompt(prompt: string): SliceType {
+  return READ_ONLY_FANOUT_RE.test(prompt) && !MUTATING_RE.test(prompt) ? "read-only-fanout" : "unknown";
+}
+
+/**
+ * Median first-call written-or-uncached tokens of a subagent leg — a
+ * measurement, not a tuning knob. Re-take it in {@link LEG_COLD_START_SOURCE}
+ * and change it here; a test fails while the two disagree.
+ */
+export const LEG_COLD_START_UNCACHED_TOKENS = 182_257;
+export const LEG_COLD_START_SOURCE = "agents/evidence/analysis/subagent-cold-start-2026-10-14.md";
+
 /**
  * `rung` names the resolved judgment-ladder rung (2.4): `null` renders as
  * `rung-?` — this concern only ever calls it for a `subagent` verdict
@@ -359,9 +386,21 @@ export function buildNudgeLine(
   classification: Classification,
   sliceCount: number,
   tier: Tier,
+  sliceKind?: SliceType,
+  handKind?: HandKind,
 ): string {
   const unit = sliceCount === 1 ? "slice" : "slices";
   const rungLabel = rung === null ? "rung-?" : `rung-${rung}`;
+  // A pointer only: nothing is sent, and the return is a proposal the head verifies.
+  if (rung === 0.5 && handKind !== undefined) {
+    return (
+      `<delegation-nudge>rung-0.5: free rung. This slice is a typed \`${handKind}\` task and an unpaid ` +
+      "route is admissible — you may send it as ONE call via " +
+      `\`./scripts-run src/scripts/ask_transport --kind ${handKind} --content-class public-artifact "<slice>"\` ` +
+      `(public-artifact text only; project content stays on a paid route). The return is a proposal: ` +
+      `verify it before acting on it. Nothing was sent for you — ${classification.reason}.</delegation-nudge>`
+    );
+  }
   // Rung 0.5 (token-economy-dispatch 4.3): cite the sub-spawn ask path —
   // never a spawn recommendation for a question-shaped slice.
   if (rung === 0.5) {
@@ -403,11 +442,20 @@ export function buildNudgeLine(
   // Rung 1 (single bounded slice) carries no do-in-steps/do-in-parallel
   // mode of its own — `classification.mode` is `null` for that shape.
   const modeLabel = classification.mode ?? "single-slice";
+  // Advisory only, never a block.
+  const coldStart =
+    rung === 1
+      ? ` A leg starts cold (~${Math.round(LEG_COLD_START_UNCACHED_TOKENS / 1000)}k uncached tokens): ` +
+        "a slice of one to three direct reads does not amortise it."
+      : "";
+  // The per-call model value, only for a tier the table produced for a known kind.
+  const model = tier === "lite" && sliceKind !== undefined && sliceKind !== "unknown" ? TIER_TO_CLAUDE_MODEL[tier] : undefined;
+  const carrier = model ? ` Pass \`model: "${model}"\` on each Agent call (${sliceKind} slices earn lite).` : "";
   return (
     `<delegation-nudge>${rungLabel}: dispatch ${modeLabel} ` +
     `(${sliceCount} ${unit}, ${tier} tier recommended). Consider dispatching via ` +
     `subagent-orchestration instead of doing every slice in-session — ` +
-    `${classification.reason}.</delegation-nudge>`
+    `${classification.reason}.${carrier}${coldStart}</delegation-nudge>`
   );
 }
 
@@ -415,9 +463,14 @@ export interface NudgeResult {
   classification: Classification;
   sliceCount: number;
   tier: Tier;
+  /** The slice kind the tier was read from (`unknown` → `inherit`). */
+  sliceKind: SliceType;
+  /** Set only for a rung-0.5 slice of a typed hand kind with an admissible unpaid route. */
+  handKind?: HandKind;
   /** The judgment-ladder rung this verdict resolved to (2.4) — 1 or 2 in
    *  production today: classifyPrompt returns null for every non-subagent
-   *  verdict including rung 0.5 (the carrier stays silent on questions);
+   *  verdict including rung 0.5 (the carrier stays silent on questions),
+   *  except a typed hand slice whose unpaid route an injected check admits;
    *  buildNudgeLine's 0.5 branch is vocabulary for orchestrator-facing
    *  surfaces and direct callers. */
   rung: LadderRung;
@@ -429,10 +482,20 @@ export interface NudgeResult {
  * verdict out of this concern's scope, activation gate closed, or an
  * internal error — all degrade to the same silent outcome).
  */
+export interface ClassifyOptions {
+  /**
+   * Whether an unpaid route would admit this kind. Injected so the verdict does
+   * not depend on what is configured; absent means no route, so the free rung
+   * stays silent.
+   */
+  freeRouteAdmissible?: (kind: HandKind) => boolean;
+}
+
 export function classifyPrompt(
   prompt: string,
   workspace_root: string,
   hostId: string | null | undefined,
+  opts: ClassifyOptions = {},
 ): NudgeResult | null {
   try {
     const { signals, sliceCountForLine } = extractTaskSignals(prompt);
@@ -476,13 +539,30 @@ export function classifyPrompt(
         classification: { delegable: false, action: "ask", mode: null, reason: ladder.reason },
         sliceCount: 0,
         tier: recommendSliceTier(downshift, separate_quota_pool),
+        sliceKind: "unknown",
         rung: ladder.rung,
       };
     }
+    // The one rung-0.5 exception to silence: a typed hand kind with an admissible
+    // unpaid route, which moves paid work off the head rather than adding a line.
+    if (ladder.rung === 0.5 && opts.freeRouteAdmissible !== undefined) {
+      const handKind = handKindFromPrompt(prompt);
+      if (handKind !== null && opts.freeRouteAdmissible(handKind)) {
+        return {
+          classification: { delegable: false, action: "ask", mode: null, reason: ladder.reason },
+          sliceCount: 0,
+          tier: recommendSliceTier(downshift, separate_quota_pool),
+          sliceKind: "unknown",
+          rung: ladder.rung,
+          handKind,
+        };
+      }
+    }
     if (ladder.verdict !== "subagent") {
       return null; // rung-0 script, rung-0.5 ask-transport, or ∅ user-ask/in-session
     }
-    const tier = recommendSliceTier(downshift, separate_quota_pool);
+    const sliceKind = sliceKindFromPrompt(prompt);
+    const tier = recommendSliceTier(downshift, separate_quota_pool, sliceKind);
     // Rung 1 (single bounded slice) has no explicit slice count of its own —
     // extractTaskSignals never produces one for that shape — so the line
     // always names it as exactly one slice.
@@ -493,7 +573,7 @@ export function classifyPrompt(
       mode: ladder.mode ?? null,
       reason: ladder.reason,
     };
-    return { classification, sliceCount, tier, rung: ladder.rung };
+    return { classification, sliceCount, tier, sliceKind, rung: ladder.rung };
   } catch {
     return null; // classifier/settings error → silence, never a crash-to-block
   }
@@ -545,7 +625,10 @@ export function main(): number {
   const root = _workspaceRoot(env);
   const platform = env["platform"];
   const hostId = typeof platform === "string" && platform ? platform : null;
-  const result = classifyPrompt(prompt, root, hostId);
+  // Read lazily: the council config is opened only on a rung-0.5 hand-kind slice.
+  const result = classifyPrompt(prompt, root, hostId, {
+    freeRouteAdmissible: (kind) => freeRungFor(root, kind, councilConfigPath()),
+  });
   if (!result) {
     return EXIT_ALLOW; // anti-canary default: no verdict → no output
   }
@@ -554,7 +637,14 @@ export function main(): number {
     `${JSON.stringify({
       decision: "warn",
       reason: `delegation-nudge: rung-${result.rung} verdict (${result.sliceCount} slices, ${result.tier} tier)`,
-      additional_context: buildNudgeLine(result.rung, result.classification, result.sliceCount, result.tier),
+      additional_context: buildNudgeLine(
+        result.rung,
+        result.classification,
+        result.sliceCount,
+        result.tier,
+        result.sliceKind,
+        result.handKind,
+      ),
     })}\n`,
   );
   return EXIT_WARN;