@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/autonomy/envelope.mjs

@@ -0,0 +1,301 @@
+// envelope.mjs — pure functions for autonomy-envelope frontmatter parsing +
+// rendering. Zero IO. All filesystem side effects live in cli.mjs.
+//
+// The envelope is a markdown file with a YAML frontmatter block carrying the
+// machine-readable state. We ship our own minimal YAML reader/writer here
+// (limited to the shape the schema defines) to avoid pulling in a YAML dep
+// for such a narrow surface. Any file whose frontmatter falls outside the
+// documented shape is rejected as invalid.
+
+export const VALID_STATES = ['fullyApproved', 'checkBeforeCommitting', 'needsFullSupervision'];
+
+const STATE_LABELS = {
+  fullyApproved: 'fully approved',
+  checkBeforeCommitting: 'check before committing',
+  needsFullSupervision: 'needs full supervision',
+};
+
+/**
+ * Parse an autonomy-envelope markdown file. Returns
+ *   { frontmatter, body }
+ * where `frontmatter` matches the schema shape and `body` is the markdown
+ * after the closing `---`. Throws on malformed input; the error carries an
+ * `exitCode` for the CLI to propagate.
+ */
+export function parseEnvelope(source) {
+  if (typeof source !== 'string' || source.length === 0) {
+    throwUsage('envelope file is empty');
+  }
+  const lines = source.split(/\r?\n/);
+  if (lines[0].trim() !== '---') {
+    throwParse('envelope must start with YAML frontmatter delimited by ---');
+  }
+  let closeIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') {
+      closeIdx = i;
+      break;
+    }
+  }
+  if (closeIdx < 0) {
+    throwParse('unterminated YAML frontmatter (missing closing ---)');
+  }
+  const fmLines = lines.slice(1, closeIdx);
+  const bodyLines = lines.slice(closeIdx + 1);
+  const frontmatter = parseFrontmatter(fmLines);
+  return { frontmatter, body: bodyLines.join('\n') };
+}
+
+/**
+ * Parse a limited-shape YAML block. Supports:
+ *   key: value                      (string)
+ *   key:                            (empty list start)
+ *     - key: value                  (list item — object)
+ *       key: value
+ * Numbers, booleans, and nested maps beyond one level are NOT supported —
+ * the schema doesn't need them. Values are always treated as strings.
+ */
+function parseFrontmatter(lines) {
+  const out = {};
+  let i = 0;
+  while (i < lines.length) {
+    const raw = lines[i];
+    if (raw.trim() === '' || raw.trim().startsWith('#')) { i++; continue; }
+    const match = raw.match(/^([a-zA-Z][a-zA-Z0-9]*):(?:\s*(.*))?$/);
+    if (!match) {
+      throwParse(`could not parse frontmatter line ${i + 1}: ${raw}`);
+    }
+    const key = match[1];
+    const value = (match[2] ?? '').trim();
+    if (value === '') {
+      // Expect either a list (starts with "- " at next non-empty indented
+      // line) or an empty value.
+      const listItems = [];
+      let j = i + 1;
+      while (j < lines.length) {
+        const peek = lines[j];
+        if (peek.trim() === '' || peek.trim().startsWith('#')) { j++; continue; }
+        if (!/^\s+-\s/.test(peek)) break;
+        const item = readListItem(lines, j);
+        listItems.push(item.value);
+        j = item.next;
+      }
+      out[key] = listItems;
+      i = j;
+    } else {
+      out[key] = stripQuotes(value);
+      i++;
+    }
+  }
+  return out;
+}
+
+function readListItem(lines, start) {
+  const first = lines[start];
+  const indentMatch = first.match(/^(\s+)-\s/);
+  if (!indentMatch) {
+    throwParse(`expected list item at line ${start + 1}: ${first}`);
+  }
+  const itemIndent = indentMatch[1] + '  '; // continuation is deeper than "- "
+  const item = {};
+  // The "- key: value" first line is the first key on the item.
+  const firstBody = first.slice(indentMatch[0].length);
+  const firstMatch = firstBody.match(/^([a-zA-Z][a-zA-Z0-9]*):\s*(.*)$/);
+  if (!firstMatch) {
+    throwParse(`could not parse list item at line ${start + 1}: ${first}`);
+  }
+  item[firstMatch[1]] = stripQuotes(firstMatch[2].trim());
+  let j = start + 1;
+  while (j < lines.length) {
+    const peek = lines[j];
+    if (peek.trim() === '' || peek.trim().startsWith('#')) { j++; continue; }
+    // Terminate when indent doesn't extend the item (either new list item
+    // at the same "- " indent, or dedent back to a top-level key).
+    if (peek.startsWith(itemIndent)) {
+      const bodyLine = peek.slice(itemIndent.length);
+      const m = bodyLine.match(/^([a-zA-Z][a-zA-Z0-9]*):\s*(.*)$/);
+      if (!m) {
+        throwParse(`could not parse list item continuation at line ${j + 1}: ${peek}`);
+      }
+      item[m[1]] = stripQuotes(m[2].trim());
+      j++;
+    } else {
+      break;
+    }
+  }
+  return { value: item, next: j };
+}
+
+function stripQuotes(value) {
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1);
+  }
+  if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+/**
+ * Render an envelope object (frontmatter shape) back to markdown. Body is
+ * regenerated: a current-state table + a history log preserved from prior
+ * body sections. This keeps the file readable + deterministic.
+ */
+export function renderEnvelope(frontmatter, history = []) {
+  const fm = renderFrontmatter(frontmatter);
+  const body = renderBody(frontmatter, history);
+  return `---\n${fm}---\n\n${body}\n`;
+}
+
+function renderFrontmatter(fm) {
+  const lines = [];
+  lines.push(`agent: ${quoteIfNeeded(fm.agent)}`);
+  lines.push(`owner: ${quoteIfNeeded(fm.owner)}`);
+  lines.push(`updated: ${quoteIfNeeded(fm.updated)}`);
+  lines.push('taskTypes:');
+  const items = fm.taskTypes ?? [];
+  for (const item of items) {
+    lines.push(`  - id: ${quoteIfNeeded(item.id)}`);
+    lines.push(`    label: ${quoteIfNeeded(item.label)}`);
+    lines.push(`    state: ${quoteIfNeeded(item.state)}`);
+    if (item.stateSince) lines.push(`    stateSince: ${quoteIfNeeded(item.stateSince)}`);
+    if (item.operatorNote) lines.push(`    operatorNote: ${quoteIfNeeded(item.operatorNote)}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+function quoteIfNeeded(value) {
+  if (value == null) return '""';
+  const str = String(value);
+  // Quote values that could be misparsed as YAML control sequences.
+  if (/^[\s"'#\-\[\{,&*!|>%@`]/.test(str)) return JSON.stringify(str);
+  if (/[:#]\s/.test(str)) return JSON.stringify(str);
+  if (str.trim() !== str) return JSON.stringify(str);
+  return str;
+}
+
+function renderBody(fm, history) {
+  const lines = [];
+  lines.push(`# Autonomy envelope — ${fm.agent}`);
+  lines.push('');
+  lines.push('## Current state');
+  lines.push('');
+  if (!fm.taskTypes || fm.taskTypes.length === 0) {
+    lines.push('_No task types configured. Use `pa autonomy set <agent> <task-type> <state>` to add one._');
+  } else {
+    lines.push('| Task type | State | Since | Note |');
+    lines.push('|---|---|---|---|');
+    for (const item of fm.taskTypes) {
+      const since = (item.stateSince ?? '').slice(0, 10);
+      const note = (item.operatorNote ?? '—').replace(/\|/g, '\\|');
+      lines.push(`| ${escapeCell(item.label)} | ${STATE_LABELS[item.state] ?? item.state} | ${since || '—'} | ${note} |`);
+    }
+  }
+  lines.push('');
+  lines.push('## History');
+  lines.push('');
+  const entries = [...history].sort((a, b) => (b.at ?? '').localeCompare(a.at ?? ''));
+  if (entries.length === 0) {
+    lines.push('_No history yet._');
+  } else {
+    for (const entry of entries) {
+      lines.push(`### ${entry.at} — ${entry.taskTypeId} → ${entry.state}`);
+      if (entry.note) {
+        lines.push('');
+        lines.push(`Operator note: ${entry.note}`);
+      }
+      lines.push('');
+    }
+  }
+  return lines.join('\n');
+}
+
+function escapeCell(str) {
+  return String(str).replace(/\|/g, '\\|');
+}
+
+/**
+ * Extract history entries from a rendered body. Returns an array of
+ *   { at, taskTypeId, state, note }
+ * entries. Best-effort — malformed sections are skipped, not raised.
+ */
+export function extractHistory(body) {
+  const entries = [];
+  if (typeof body !== 'string') return entries;
+  const lines = body.split(/\r?\n/);
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const match = line.match(/^###\s+(\S+)\s+—\s+([a-z0-9][a-z0-9-]*)\s+→\s+([A-Za-z]+)\s*$/);
+    if (!match) { i++; continue; }
+    const at = match[1];
+    const taskTypeId = match[2];
+    const state = match[3];
+    let note = null;
+    let j = i + 1;
+    while (j < lines.length && lines[j].trim() === '') j++;
+    if (j < lines.length && lines[j].startsWith('Operator note:')) {
+      note = lines[j].slice('Operator note:'.length).trim();
+    }
+    entries.push({ at, taskTypeId, state, note });
+    i = j + 1;
+  }
+  return entries;
+}
+
+/**
+ * Validate a frontmatter object against the schema. Throws on invalid;
+ * returns nothing on valid.
+ */
+export function validateFrontmatter(fm) {
+  if (!fm || typeof fm !== 'object') throwParse('frontmatter must be an object');
+  requireString(fm, 'agent');
+  requireString(fm, 'owner');
+  requireString(fm, 'updated');
+  if (!Array.isArray(fm.taskTypes)) throwParse('taskTypes must be an array');
+  for (const [i, item] of fm.taskTypes.entries()) {
+    if (!item || typeof item !== 'object') throwParse(`taskTypes[${i}] must be an object`);
+    requireString(item, `taskTypes[${i}].id`, item.id);
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(item.id)) throwParse(`taskTypes[${i}].id '${item.id}' must match ^[a-z0-9][a-z0-9-]*$`);
+    requireString(item, `taskTypes[${i}].label`, item.label);
+    requireString(item, `taskTypes[${i}].state`, item.state);
+    if (!VALID_STATES.includes(item.state)) {
+      throwParse(`taskTypes[${i}].state '${item.state}' must be one of ${VALID_STATES.join(', ')}`);
+    }
+  }
+}
+
+function requireString(obj, field, value) {
+  const v = value ?? obj?.[field];
+  if (typeof v !== 'string' || v.length === 0) {
+    throwParse(`${field} must be a non-empty string`);
+  }
+}
+
+function throwParse(msg) {
+  const err = new Error(msg);
+  err.exitCode = 2;
+  throw err;
+}
+
+function throwUsage(msg) {
+  const err = new Error(msg);
+  err.exitCode = 1;
+  throw err;
+}
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+export function emptyEnvelope(agent, owner) {
+  return {
+    frontmatter: {
+      agent,
+      owner,
+      updated: nowIso(),
+      taskTypes: [],
+    },
+    history: [],
+  };
+}

package/dist/engineering-pa-cli/src/coordinator-hook/cli.mjs

@@ -0,0 +1,140 @@
+// cli.mjs — pa-coordinator-hook entry point.
+//
+// This is a Claude Code PreToolUse hook, NOT a normal repo CLI — its exit
+// code contract is dictated by Claude Code's hook protocol
+// (https://code.claude.com/docs/en/hooks), not by this monorepo's usual
+// "0 ok / 1 usage / 2 logical failure / 3 transport failure" convention
+// (CONTRIBUTING.md). Deliberately:
+//
+//   exit 0  — allow. Either coordinator mode is off, the tool is
+//             unconditionally allowed, or the tier2 arguments matched an
+//             allow pattern. No stdout JSON is emitted — Claude Code falls
+//             through to its normal permission flow, which is exactly what
+//             we want (the hook only ever tightens, never auto-grants
+//             something the user's own settings wouldn't already allow).
+//   exit 2  — block. stderr carries the message Claude Code shows the
+//             model. tool_input is never mutated. Also used for a hook-
+//             internal failure (config missing/corrupted, or any other
+//             unexpected exception while deciding) — a security-relevant
+//             gate fails CLOSED on its own bugs, never open.
+//   exit 1  — malformed input (unparseable stdin JSON, missing tool_name).
+//             Per the hooks doc this is a NON-BLOCKING error — the tool
+//             call proceeds normally. We'd rather fail open on a malformed
+//             payload than break every tool call estate-wide because of a
+//             hook bug; the alternative (fail closed) turns one hook bug
+//             into a total PA outage. Logged to stderr either way, so it's
+//             visible in the transcript.
+//
+// Input: PreToolUse JSON on stdin — { tool_name, tool_input, cwd, ... }
+// (see packages/cli/docs/coordinator-hook.md for the full contract this
+// was verified against).
+//
+// `pa-coordinator-hook --help` prints usage and exits 0 without touching
+// stdin — matches the "every bin runs --help and exits 0" install-health
+// convention documented in packages/engineering-pa/README.md, and gives
+// operators a way to sanity-check the install without constructing a fake
+// hook payload.
+
+import { loadEffectiveConfig, overlayPaths } from './config.mjs';
+import { decide } from './policy.mjs';
+import { formatBlockMessage } from './message.mjs';
+import { resolveRepoRoot } from './repo-root.mjs';
+import { resolveSelfAgent } from './self.mjs';
+
+const USAGE = `pa-coordinator-hook — Claude Code PreToolUse hook enforcing the three-tier
+coordinator-mode tool policy for interactive PA main threads.
+
+Not meant to be invoked by hand — wired up via settings.json's PreToolUse
+hooks (see packages/cli/docs/coordinator-hook.md for the snippet). Reads a
+PreToolUse JSON payload from stdin, exits 0 (allow) or 2 (block, message on
+stderr).
+
+Toggle: set PA_COORDINATOR_MODE=1 to enforce. Unset (or any other value)
+is a transparent no-op — exits 0 for everything, including malformed input.
+
+Usage:
+  pa-coordinator-hook            Read a PreToolUse payload from stdin
+  pa-coordinator-hook --help     Show this help and exit 0
+`;
+
+export async function main(argv = [], { stdin = process.stdin, stderr = process.stderr, env = process.env } = {}) {
+  if (argv.includes('-h') || argv.includes('--help')) {
+    stderr.write(USAGE);
+    return 0;
+  }
+
+  const mode = env.PA_COORDINATOR_MODE;
+  if (mode !== '1') {
+    // Transparent no-op — don't even read stdin, nothing to decide.
+    return 0;
+  }
+
+  if (stdin.isTTY) {
+    // Invoked bare in an interactive terminal — there is no PreToolUse
+    // payload coming. Don't hang waiting for stdin to close; fail open
+    // and tell the human what happened.
+    stderr.write('pa-coordinator-hook: no stdin payload (interactive terminal) — nothing to decide, allowing. Use --help for usage.\n');
+    return 1;
+  }
+
+  let payload;
+  try {
+    const raw = await readAll(stdin);
+    payload = JSON.parse(raw);
+  } catch (err) {
+    stderr.write(`pa-coordinator-hook: malformed stdin payload (${err.message}) — failing open (allow)\n`);
+    return 1; // non-blocking per the hooks contract — tool call proceeds
+  }
+
+  const toolName = payload?.tool_name;
+  const toolInput = payload?.tool_input ?? {};
+  const cwd = payload?.cwd || process.cwd();
+
+  if (!toolName || typeof toolName !== 'string') {
+    stderr.write('pa-coordinator-hook: payload missing tool_name — failing open (allow)\n');
+    return 1;
+  }
+
+  // Everything from here on is "the gate itself" — config load, repo-root /
+  // self-agent resolution, and the actual policy decision. This is
+  // deliberately distinct from the malformed-stdin-JSON case above (which
+  // is a legitimate exit-1/fail-open case per the hooks contract): an
+  // exception in here means the gate itself is broken (missing/corrupted
+  // config, a bug in the decision logic, whatever) and a security-relevant
+  // gate must fail CLOSED on its own failures, not silently fall through to
+  // allow. Previously an uncaught exception here (e.g. loadEffectiveConfig
+  // throwing on a corrupted coordinator-allowlist.json) propagated out of
+  // main() entirely and crashed the process — which the hooks contract
+  // reads as a non-blocking/allow outcome, silently disabling the whole
+  // gate on a bad install.
+  try {
+    // PA_COORDINATOR_CORE_CONFIG_PATH is an internal test seam (also usable
+    // for a deliberate ops override) — unset in normal operation, so
+    // loadEffectiveConfig falls back to its own CORE_CONFIG_PATH default.
+    const configPath = env.PA_COORDINATOR_CORE_CONFIG_PATH || undefined;
+    const { config, warnings } = await loadEffectiveConfig({ cwd, env, configPath });
+    for (const w of warnings) stderr.write(`pa-coordinator-hook: ${w}\n`);
+
+    const repoRoot = await resolveRepoRoot(cwd, env);
+    const selfAgent = await resolveSelfAgent(repoRoot, env);
+
+    const result = decide(toolName, toolInput, config, { cwd, repoRoot, selfAgent });
+
+    if (result.decision === 'allow') return 0;
+
+    const { workspace } = overlayPaths({ repoRoot, cwd, env });
+    const message = formatBlockMessage(toolName, result, config, workspace);
+    stderr.write(message + '\n');
+    return 2;
+  } catch (err) {
+    stderr.write(`pa-coordinator-hook: internal error (${err && err.message}) — failing closed (block)\n`);
+    return 2;
+  }
+}
+
+async function readAll(stream) {
+  if (stream.readableEnded || stream.destroyed) return '';
+  const chunks = [];
+  for await (const chunk of stream) chunks.push(chunk);
+  return Buffer.concat(chunks.map((c) => (Buffer.isBuffer(c) ? c : Buffer.from(c)))).toString('utf8');
+}

package/dist/engineering-pa-cli/src/coordinator-hook/config.mjs

@@ -0,0 +1,134 @@
+// config.mjs — load + merge the coordinator-hook allowlist config.
+//
+// Three layers, in priority order (lowest to highest — later layers only
+// ADD allow-pattern entries, they never remove or reclassify anything):
+//   1. Core config — packages/cli/config/coordinator-allowlist.json,
+//      resolved relative to this module via import.meta.url so it works
+//      identically from source (packages/cli/src/coordinator-hook/…) and
+//      from the bundled dist tree (dist/engineering-pa-cli/src/coordinator-hook/…) —
+//      build.mjs preserves the package's internal relative layout.
+//   2. Home overlay — ~/.claude/coordinator-overlay.json
+//   3. Workspace overlay — <repoRoot or cwd>/.claude/coordinator-overlay.json
+//
+// Overlay contract (spec-locked, do not relax): an overlay may ONLY extend
+// `tier2.<Bash|Read|Write>.allowPatterns` / `allowPathPatterns`. It cannot
+// move a tool between tiers, cannot touch tier1/tier3, and cannot touch
+// hardDeny. Anything else in an overlay file is ignored with a stderr
+// warning — silently accepting unknown shape would be how a stray overlay
+// key quietly widens the policy.
+
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CORE_CONFIG_PATH = resolve(__dirname, '..', '..', 'config', 'coordinator-allowlist.json');
+
+const OVERLAYABLE_TOOLS = ['Bash', 'Read', 'Write'];
+const OVERLAYABLE_KEYS = ['allowPatterns', 'allowPathPatterns'];
+
+export async function loadCoreConfig(configPath = CORE_CONFIG_PATH) {
+  const raw = await readFile(configPath, 'utf8');
+  return JSON.parse(raw);
+}
+
+// Discriminated result so the caller never has to guess whether a `null`
+// came from "file absent" vs. "file contained the JSON literal null".
+async function tryReadJson(path) {
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { ok: false, missing: true };
+    return { ok: false, error: err };
+  }
+  try {
+    return { ok: true, data: JSON.parse(raw) };
+  } catch (err) {
+    return { ok: false, error: err };
+  }
+}
+
+/**
+ * Merge one overlay object's allowlisted keys onto `config` (returns a new
+ * object — never mutates the input). Unknown/disallowed keys are dropped
+ * and reported via `warnings`.
+ */
+export function mergeOverlay(config, overlay, warnings = []) {
+  if (!overlay || typeof overlay !== 'object') return config;
+
+  const next = {
+    ...config,
+    tier2: { ...config.tier2 },
+  };
+
+  for (const [key, value] of Object.entries(overlay)) {
+    if (key !== 'tier2') {
+      warnings.push(`coordinator-overlay: ignoring top-level key "${key}" (overlays may only extend tier2 allow patterns)`);
+      continue;
+    }
+    if (!value || typeof value !== 'object') continue;
+    for (const [tool, toolPatch] of Object.entries(value)) {
+      if (!OVERLAYABLE_TOOLS.includes(tool)) {
+        warnings.push(`coordinator-overlay: ignoring tier2.${tool} — overlays may only extend Bash/Read/Write`);
+        continue;
+      }
+      if (!toolPatch || typeof toolPatch !== 'object') continue;
+      const mergedTool = { ...(next.tier2[tool] ?? {}) };
+      for (const [patchKey, patternList] of Object.entries(toolPatch)) {
+        if (!OVERLAYABLE_KEYS.includes(patchKey)) {
+          warnings.push(`coordinator-overlay: ignoring tier2.${tool}.${patchKey} — only allowPatterns/allowPathPatterns may be extended`);
+          continue;
+        }
+        if (!Array.isArray(patternList)) continue;
+        const existing = Array.isArray(mergedTool[patchKey]) ? mergedTool[patchKey] : [];
+        mergedTool[patchKey] = [...new Set([...existing, ...patternList.filter((p) => typeof p === 'string')])];
+      }
+      next.tier2[tool] = mergedTool;
+    }
+  }
+
+  return next;
+}
+
+/**
+ * Resolve the two overlay file candidates (home, workspace). Workspace
+ * overlay is anchored at `repoRoot` when known, else `cwd` — either way it
+ * lives at `.claude/coordinator-overlay.json` under that directory.
+ */
+export function overlayPaths({ repoRoot, cwd, env = process.env }) {
+  const home = env.HOME || homedir();
+  const workspaceBase = repoRoot || cwd;
+  return {
+    home: home ? join(home, '.claude', 'coordinator-overlay.json') : null,
+    workspace: workspaceBase ? join(workspaceBase, '.claude', 'coordinator-overlay.json') : null,
+  };
+}
+
+/**
+ * Load the fully-merged effective config: core + home overlay + workspace
+ * overlay (workspace applied last, so it can extend past whatever the home
+ * overlay already added). Returns `{ config, warnings }` — warnings is a
+ * flat array of human-readable strings for anything ignored along the way.
+ */
+export async function loadEffectiveConfig({ repoRoot, cwd, env = process.env, configPath } = {}) {
+  const warnings = [];
+  let config = await loadCoreConfig(configPath);
+
+  const { home, workspace } = overlayPaths({ repoRoot, cwd, env });
+  for (const overlayPath of [home, workspace]) {
+    if (!overlayPath) continue;
+    const result = await tryReadJson(overlayPath);
+    if (!result.ok) {
+      if (result.missing) continue; // no overlay at this path — normal case
+      warnings.push(`coordinator-overlay: failed to parse ${overlayPath} (${result.error.message}) — ignoring`);
+      continue;
+    }
+    config = mergeOverlay(config, result.data, warnings);
+  }
+
+  return { config, warnings };
+}
+
+export { CORE_CONFIG_PATH };

package/dist/engineering-pa-cli/src/coordinator-hook/message.mjs

@@ -0,0 +1,47 @@
+// message.mjs — formats the exit-2 stderr message a blocked tool call sees.
+//
+// Format is spec-locked (agentic-harness product-vision.md §1 item 6):
+//
+//   coordinator-mode: <ToolName> blocked (<tier> - <reason>).
+//   Try: <specific alternative>
+//   - Dispatch a worker: `Agent(...)` with the appropriate role.
+//   - Retrieve knowledge: `Bash(pa knowledge search "...")`.
+//   - Named exception needed? Add to allowlist: <config path>.
+//
+// The "Try:" line is tool-specific (config.messages[toolName], falling back
+// to a generic line) — concrete alternatives matter more than a generic
+// "dispatch instead" for the model reading the block.
+
+export function formatBlockMessage(toolName, decisionResult, config, overlayPath) {
+  const { tier, reason, matched } = decisionResult;
+
+  const tryLine = pickTryLine(toolName, decisionResult, config);
+  const configPath = overlayPath || '~/.claude/coordinator-overlay.json (or <workspace>/.claude/coordinator-overlay.json)';
+
+  const lines = [
+    `coordinator-mode: ${toolName} blocked (${tier} - ${reason}).`,
+    `Try: ${tryLine}`,
+    '- Dispatch a worker: `Agent(...)` with the appropriate role.',
+    '- Retrieve knowledge: `Bash(pa knowledge search "...")`.',
+    `- Named exception needed? Add to allowlist: ${configPath} (tier2 allowPatterns/allowPathPatterns only — cannot move a tool between tiers).`,
+  ];
+  return lines.join('\n');
+}
+
+function pickTryLine(toolName, decisionResult, config) {
+  const messages = config.messages ?? {};
+
+  // Read blocked specifically by the operator/knowledge blockPathPatterns
+  // entry gets its own, more specific message than a generic Read-denied one.
+  if (toolName === 'Read' && decisionResult.tier === 'tier2-explicit-block' && messages['operator/knowledge/**']) {
+    return messages['operator/knowledge/**'];
+  }
+
+  if (decisionResult.tier === 'tier2-hard-deny' && messages.hardDeny) {
+    return messages.hardDeny;
+  }
+
+  if (messages[toolName]) return messages[toolName];
+
+  return `dispatch a worker instead of calling ${toolName} inline — main thread is coordinator-mode.`;
+}