@rubytech/create-maxy-code 0.1.280 → 0.1.282

package/payload/platform/lib/mcp-spawn-tee/src/index.ts

@@ -1,53 +1,41 @@
 #!/usr/bin/env node
 /**
- * MCP spawn-tee — parent-side stderr capture wrapper.
+ * MCP spawn-tee — parent-side stderr capture + lifecycle observability.
  *
- * Claude Code's `--mcp-config` accepts `{command, args, env}` descriptors and
- * spawns each MCP server itself; the platform never holds a ChildProcess
- * handle. The in-process `mcp-stderr-tee` patches `process.stderr.write` from
- * inside the MCP server, but its writes go through `createWriteStream` —
- * async, buffered. A synchronous module-load throw (e.g. schema-loader's
- * line-168 width check on memory) calls `process.exit(1)` before the buffer
- * flushes, so the per-server log file is empty and the platform's
- * `[mcp-init-error] tail="(no stderr file)"` probe is operationally useless.
- * That class shipped as the chronic memory-MCP silent-fail loop fixed by
- * (and hit graph — solved there with per-plugin
- * `appendFileSync` discipline that this wrapper now generalises).
+ * Claude Code spawns each MCP server itself; the platform never holds a
+ * ChildProcess handle. This wrapper sits between Claude Code and the real
+ * MCP server: Claude Code runs `node <this> <real-entry>`, and the wrapper
+ * spawns the real entry with `stdio:['inherit','inherit','pipe']` so stdin
+ * and stdout (the JSON-RPC channel) pass through byte-identical. Only stderr
+ * is intercepted, and only for logging.
  *
- * The wrapper sits between Claude Code and the real MCP server: it spawns
- * the real entry with `stdio: ['inherit', 'inherit', 'pipe']`, then
- * synchronously appends every child stderr chunk to
- * `${LOG_DIR}/mcp-${name}-stderr-<date>.log`. Synchronous writes survive
- * `process.exit` because the kernel queues the syscall before the call
- * returns. The chunk is also written to the wrapper's own stderr so
- * Claude Code's existing stderr consumer is unchanged — the mechanism is
- * additive, not interceptive.
+ * Because the wrapper IS the helper's parent, it observes the helper's true
+ * exit code, signal, and lifetime for every death mode — including a SIGKILL
+ * or a transport-layer crash that an in-process handler would miss.
  *
- *   Claude Code CLI
- *        │ spawns
- *        ▼
- *   wrapper (this file) — argv[2] = real entry, env.MCP_SPAWN_TEE_NAME = name
- *        │ spawns child with stdio:['inherit','inherit','pipe']
- *        ▼
- *   child = node <real-entry>
- *        │
- *        ├──▶ stdin/stdout: inherited from wrapper (Claude Code pipe)
- *        └──▶ stderr → wrapper.on('data', chunk =>)
- *               ├──▶ appendFileSync(${LOG_DIR}/mcp-${name}-stderr-<date>.log)
- *               └──▶ process.stderr.write(chunk)  → Claude Code consumer
+ *   Claude Code CLI → wrapper (this file) → child = node <real-entry>
+ *        child stdin/stdout : inherited (Claude Code pipe, untouched)
+ *        child stderr       : piped → per-date log + per-session log + passthrough
  *
- * The wrapper catches:
- *   - MODULE_NOT_FOUND on the entry script itself (success criterion #3:
- *     `mv plugins/memory/mcp/dist plugins/memory/mcp/dist-broken && reboot`
- *     leaves the cause on disk).
- *   - Synchronous throws during module load before the in-process tee runs.
- *   - Any stderr a normally-running plugin emits (steady-state telemetry
- *     remains visible too — the in-process tee handles per-line stream-log
- *     prefixing; this wrapper handles the raw per-server file).
+ * Destinations (Task 706):
+ *   - `${LOG_DIR}/mcp-<name>-stderr-<date>.log`  — per-date raw (back-compat;
+ *     the in-process mcp-stderr-tee and the [mcp-init-error] probe read it).
+ *   - `${LOG_DIR}/mcp-<name>-<SESSION_ID>.log`   — per-session raw + lifecycle
+ *     lines; wrapper-only, so it never mixes the enumeration copy with the
+ *     live copy. Authoritative sink. Absent when SESSION_ID is unset
+ *     (enumeration spawn) — then the per-date file is the fallback.
+ *   - `server.log` via the loopback log-ingest route — best-effort mirror of
+ *     the [mcp-helper] lifecycle lines. A dropped POST loses nothing because
+ *     the per-session file already holds the line (written synchronously).
  *
- * SIGTERM/SIGINT propagation: forwarded to the child so a Claude Code
- * shutdown does not orphan the MCP server. Child exit code is propagated
- * verbatim so upstream (Claude Code) sees the real outcome.
+ * Lifecycle lines, correlation key `session=<id8> server=<name>`:
+ *   [mcp-helper] op=spawn ... pid= entry=
+ *   [mcp-helper] op=boot  ... head=<first stderr bytes>
+ *   [mcp-helper] op=exit  ... code= signal= lifetimeMs= stderr-tail=   (always)
+ *
+ * The wrapper never writes to fd 1 (stdout) — that is the JSON-RPC channel.
+ * SIGTERM/SIGINT are forwarded to the child so a Claude Code shutdown does
+ * not orphan it; the child exit code/signal is propagated verbatim.
  */
 
 import { spawn } from "node:child_process";
@@ -56,31 +44,71 @@ import { resolve } from "node:path";
 
 const SERVER_NAME = process.env.MCP_SPAWN_TEE_NAME ?? "unknown";
 const LOG_DIR = process.env.LOG_DIR;
+const SESSION_ID = process.env.SESSION_ID;
+const PLATFORM_PORT = process.env.PLATFORM_PORT;
 const ENTRY = process.argv[2];
 
-// Sync-emit: appendFileSync to per-server log + stderr passthrough. Used for
-// wrapper-internal diagnostics (attach line, errors) and for forwarding child
-// stderr chunks. Each destination wrapped independently — an unwritable log
-// must not mask the primary output.
-function syncEmitLine(line: string): void {
-  if (LOG_DIR) {
-    try {
-      mkdirSync(LOG_DIR, { recursive: true });
-      const date = new Date().toISOString().slice(0, 10);
-      appendFileSync(resolve(LOG_DIR, `mcp-${SERVER_NAME}-stderr-${date}.log`), line);
-    } catch {
-      /* unwritable destination — preserve primary failure */
-    }
+const SESSION_ID8 = SESSION_ID ? SESSION_ID.slice(0, 8) : "—";
+const spawnStamp = Date.now();
+
+// Per-session raw + lifecycle log (Task 706). Wrapper-only. Empty SESSION_ID
+// (enumeration spawn) → undefined, and the per-date file is the fallback.
+const perSessionPath = LOG_DIR && SESSION_ID
+  ? resolve(LOG_DIR, `mcp-${SERVER_NAME}-${SESSION_ID}.log`)
+  : undefined;
+const perDatePath = LOG_DIR
+  ? resolve(LOG_DIR, `mcp-${SERVER_NAME}-stderr-${new Date(spawnStamp).toISOString().slice(0, 10)}.log`)
+  : undefined;
+
+// Rolling tail of child stderr for op=exit. Capped so a chatty child cannot
+// grow the buffer without bound.
+const TAIL_CAP = 2048;
+let stderrTail = "";
+let bootEmitted = false;
+
+function appendSafe(path: string | undefined, data: string | Uint8Array): void {
+  if (!path || !LOG_DIR) return;
+  try {
+    mkdirSync(LOG_DIR, { recursive: true });
+    appendFileSync(path, data);
+  } catch {
+    /* unwritable destination — never mask primary output */
   }
+}
+
+// Best-effort mirror of a lifecycle line to server.log via the loopback
+// log-ingest route. Fire-and-forget: the per-session file is authoritative,
+// so a dropped POST (unreachable port, process exiting) loses nothing.
+function postToServerLog(suffix: string, level: "info" | "error"): void {
+  if (!PLATFORM_PORT) return;
   try {
-    process.stderr.write(line);
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), 500);
+    t.unref?.(); // never let the abort timer keep the wrapper's event loop alive
+    void fetch(`http://127.0.0.1:${PLATFORM_PORT}/api/admin/log-ingest`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ tag: "mcp-helper", level, line: suffix }),
+      signal: ctrl.signal,
+    }).then(() => clearTimeout(t)).catch(() => clearTimeout(t));
   } catch {
-    /* stderr closed — nothing else to do */
+    /* fetch threw synchronously — best-effort only */
   }
 }
 
+// Emit one [mcp-helper] lifecycle line: authoritative per-session file (sync,
+// survives process.exit), the wrapper's own stderr (journald / Claude Code
+// visibility), and a best-effort server.log mirror. `suffix` is the line body
+// after the tag and carries no newline (the log-ingest route rejects newlines).
+function emitLifecycle(suffix: string, level: "info" | "error"): void {
+  const line = `[mcp-helper] ${suffix}\n`;
+  appendSafe(perSessionPath, line);
+  try { process.stderr.write(line); } catch { /* stderr closed */ }
+  postToServerLog(suffix, level);
+}
+
 if (!ENTRY) {
-  syncEmitLine(`[mcp-spawn-tee-error] server=${SERVER_NAME} reason="no entry given (argv[2] missing)"\n`);
+  emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason="no entry given (argv[2] missing)"`, "error");
   process.exit(2);
 }
 
@@ -89,46 +117,47 @@ const child = spawn(process.execPath, [ENTRY], {
   env: process.env,
 });
 
-syncEmitLine(`[mcp-spawn-tee-attached] server=${SERVER_NAME} pid=${child.pid ?? -1} entry=${ENTRY}\n`);
+emitLifecycle(`op=spawn session=${SESSION_ID8} server=${SERVER_NAME} pid=${child.pid ?? -1} entry=${ENTRY}`, "info");
 
 child.on("error", (err) => {
   const msg = err instanceof Error ? err.message : String(err);
-  syncEmitLine(`[mcp-spawn-tee-error] server=${SERVER_NAME} reason=${JSON.stringify(`spawn error: ${msg}`)}\n`);
+  emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason=${JSON.stringify(`spawn error: ${msg}`)}`, "error");
   process.exit(127);
 });
 
 if (child.stderr) {
   child.stderr.on("data", (chunk: Buffer) => {
-    if (LOG_DIR) {
-      try {
-        const date = new Date().toISOString().slice(0, 10);
-        appendFileSync(resolve(LOG_DIR, `mcp-${SERVER_NAME}-stderr-${date}.log`), chunk);
-      } catch {
-        /* unwritable destination — preserve passthrough */
-      }
-    }
-    try {
-      process.stderr.write(chunk);
-    } catch {
-      /* stderr closed — nothing else to do */
+    appendSafe(perDatePath, chunk);     // per-date raw (back-compat)
+    appendSafe(perSessionPath, chunk);  // per-session raw (Task 706)
+    try { process.stderr.write(chunk); } catch { /* stderr closed */ } // passthrough
+    stderrTail = (stderrTail + chunk.toString("utf8")).slice(-TAIL_CAP);
+    if (!bootEmitted) {
+      bootEmitted = true;
+      const head = chunk.toString("utf8").split("\n")[0].slice(0, 200);
+      emitLifecycle(`op=boot session=${SESSION_ID8} server=${SERVER_NAME} head=${JSON.stringify(head)}`, "info");
     }
   });
 }
 
-// Forward SIGTERM/SIGINT so Claude Code shutdown doesn't orphan the child.
-const forward = (signal: NodeJS.Signals) => {
-  if (!child.killed) child.kill(signal);
-};
+const forward = (signal: NodeJS.Signals) => { if (!child.killed) child.kill(signal); };
 process.on("SIGTERM", () => forward("SIGTERM"));
 process.on("SIGINT", () => forward("SIGINT"));
 
+// Signal → number, so a signal-killed child propagates as 128+signum (the
+// shell convention). `code` is null on a signal exit, so `128 + (code ?? 0)`
+// would collapse every signal to 128 and lose the signal identity in the
+// wrapper's own exit status.
+const SIGNUM: Record<string, number> = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 };
+
 child.on("exit", (code, signal) => {
-  if (signal) {
-    syncEmitLine(`[mcp-spawn-tee-exit] server=${SERVER_NAME} pid=${child.pid ?? -1} signal=${signal}\n`);
-    process.exit(128 + (code ?? 0));
-  }
-  if (code !== 0) {
-    syncEmitLine(`[mcp-spawn-tee-exit] server=${SERVER_NAME} pid=${child.pid ?? -1} code=${code}\n`);
-  }
+  const lifetimeMs = Date.now() - spawnStamp;
+  const tail = stderrTail.slice(-200);
+  const level: "info" | "error" = signal || (code ?? 0) !== 0 ? "error" : "info";
+  emitLifecycle(
+    `op=exit session=${SESSION_ID8} server=${SERVER_NAME} pid=${child.pid ?? -1} ` +
+    `code=${code ?? "—"} signal=${signal ?? "—"} lifetimeMs=${lifetimeMs} stderr-tail=${JSON.stringify(tail)}`,
+    level,
+  );
+  if (signal) process.exit(128 + (SIGNUM[signal] ?? 0));
   process.exit(code ?? 0);
 });

package/payload/platform/lib/mcp-spawn-tee/tsconfig.json

@@ -4,5 +4,6 @@
     "outDir": "dist",
     "rootDir": "src"
   },
-  "include": ["src"]
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
 }

package/payload/platform/plugins/admin/PLUGIN.md

@@ -147,7 +147,8 @@ Tools are available via the `admin` MCP server.
 - `hooks/mcp-tool-missing.sh` — **PostToolUse hook on `mcp__.*` (Task 502, directive 3).** Defence-in-depth for the `No such tool available: mcp__…` failure class that the Task 502 name-binding is built to eliminate. Fires on any MCP tool call; no-op unless the `tool_response` carries `No such tool available` AND the qualified name resolves to a maxy plugin (read from the generated `hooks/lib/maxy-mcp-plugins.txt`). On a maxy match it logs one deterministic `[mcp-tool-missing] server=<server> tool=<tool>` line and exits 2 with a fixed envelope on stderr, so the agent relays a named server-unavailable failure instead of narrating "warming up" or blind-retrying. A missing non-maxy bridge tool (Playwright etc., upstream-owned) passes through (exit 0). The maxy-plugin list is regenerated and gate-diffed by `platform/scripts/check-canonical-tool-names.mjs`.
 - `hooks/post-tool-use-agent.sh` — **PostToolUse hook on `Agent` (Task 560).** Drains any subagent hook-decision buffers under `~/.maxy-code/logs/hook-decisions/` modified since this parent's previous PostToolUse-Agent fire (cursor file keyed by parent session id), prints one `[hook-propagate]` line per record to stdout — Claude Code attaches the stdout as a `hook_success` attachment on the parent JSONL, making the records grep-queryable from the parent session alone (Task 559 motivating case). Rotates consumed buffers to `consumed/`. Emits one `[hook-propagate-census] parentSession=<…> subagentHooksObserved=<N> attachmentsEmitted=<M>` line per fire to stdout and server.log; `N != M` is the propagation regression signal. The companion emitter library `hooks/lib/hook-emit.sh` is sourced by `post-tool-use-agent.sh` and any other hook that records a block decision (4 KB stderr truncation, `truncated=true` set on the record).
 - `hooks/admin-authoring-observer.sh` — **PostToolUse hook on Write and Edit (Task 486).** Observation only — never blocks; exits 0 on every path. Fires when the admin agent (not a specialist subagent — gated by `MAXY_SPECIALIST` env) writes or edits a file under `<accountDir>/output/`. Walks the session transcript from the latest real-user turn forward to detect any prior `Task` `tool_use` whose `subagent_type` starts with `specialists:`. Emits one stderr line `[admin-authoring] inline-write path=<rel> priorSpecialistSpawnInTurn=<true|false|unknown>`. A `false` value on a long-form prose file is the regression signal Task 486 was designed to make visible — the BioSymm proposal session (admin authored a customer-facing proposal inline despite content-producer being installed) is the failure mode this surfaces mechanically. Mechanical enforcement (refuse the write, force a re-spawn) is deferred per the task spec.
-- `hooks/prompt-optimiser-directive.sh` — **UserPromptSubmit hook (Task 698).** Injects the standing prompt-optimiser restatement directive plus the per-turn three-tier routing ladder as `additionalContext`: **(1)** delegate to the specialist that owns the deliverable via the Agent tool — the brief states the outcome plus binding constraints, never lines/anchors/literal text; **(2)** only if none fits, load an admin-usable skill with `skill-load`; **(3)** only if neither fits, author inline — freestyle is the named last resort. Re-emits the full agent roster (`agents/admin/AGENTS.md`) and the full admin-usable skills list (`agents/admin/ADMIN-SKILLS.md`) every turn by reading the two generated files from the account dir (the hook fires with the account dir as cwd); it never walks the plugins tree per turn. Fail-open is **visible**: a missing list logs `[prompt-optimiser] missing=<AGENTS.md\|ADMIN-SKILLS.md> emitting-partial` to stderr and the ladder still injects. The trivial-turn skip (one-word confirmation, slash-command, direct continuation) is unchanged. **Staleness:** `ADMIN-SKILLS.md` is regenerated only by `setup-account.sh`; a plugin add/remove since the last setup leaves the list stale — compare `ADMIN-SKILLS.md` mtime against the newest `SKILL.md` mtime and re-run setup to refresh. The list generator is `platform/scripts/lib/admin-skills-bootstrap.sh`; it logs `[admin-skills] scanned=<N> admin-usable=<M> no-declaration=<K>` (failure signature: `admin-usable=0` while `scanned>0`, or any `missing-declaration` line).
+- `hooks/prompt-optimiser-directive.sh` — **UserPromptSubmit hook (Task 698).** Injects the standing prompt-optimiser restatement directive plus the per-turn three-tier routing ladder as `additionalContext`: **(1)** delegate to the specialist that owns the deliverable via the Agent tool — the brief states the outcome plus binding constraints, never lines/anchors/literal text; **(2)** only if none fits, load an admin-usable skill with `skill-load`; **(3)** only if neither fits, author inline — freestyle is the named last resort. Re-emits the full agent roster (`agents/admin/AGENTS.md`) and the full admin-usable skills list (`agents/admin/ADMIN-SKILLS.md`) every turn by reading the two generated files from the account dir (the hook fires with the account dir as cwd); it never walks the plugins tree per turn. Fail-open is **visible**: a missing list logs `[prompt-optimiser] missing=<AGENTS.md\|ADMIN-SKILLS.md> emitting-partial` to stderr and the ladder still injects. The trivial-turn skip (one-word confirmation, slash-command, direct continuation) is unchanged. **Staleness:** `ADMIN-SKILLS.md` is regenerated only by `setup-account.sh`; a plugin add/remove since the last setup leaves the list stale — compare `ADMIN-SKILLS.md` mtime against the newest `SKILL.md` mtime and re-run setup to refresh. The list generator is `platform/scripts/lib/admin-skills-bootstrap.sh`; it logs `[admin-skills] scanned=<N> admin-usable=<M> no-declaration=<K>` (failure signature: `admin-usable=0` while `scanned>0`, or any `missing-declaration` line). **Task 719:** the directive now carries a standing CAPABILITY-QUESTIONS-ARE-OWNED-WORK clause (how-to / "do you have instructions for X" / config questions about platform features are answered from the owning specialist or plugin tool/reference, never from training memory), and the hook appends a durable `<ts> [prompt-optimiser-directive] injected len=<n> session=<id>` breadcrumb to `$LOG_DIR/prompt-optimiser-directive.log` so per-turn injection is greppable, not stderr-only.
+- `hooks/prompt-optimiser-compliance.sh` — **Stop hook (Task 719).** After each admin turn, reads the just-finished turn from `transcript_path` and appends `<ts> [prompt-optimiser-compliance] directive-fired no-route-taken session=<id8> prompt="<clip>"` to `$LOG_DIR/prompt-optimiser-directive.log` (and stderr) when the routing directive fired, the prompt was non-trivial (not a slash-command, not a one-word confirmation), and the turn took **no route** — no `Agent` dispatch, no `Skill` load, no `ToolSearch`, no `mcp__*` tool call. This is the standing compliance signal that surfaces the session-`da0b12d4` failure class (agent answers a capability question from memory) as a visible event instead of a silent stale answer. Directive-fired is detected by the marker `PROMPT-OPTIMISER DIRECTIVE` in the turn slice, so it is robust to the CC-version difference in how `UserPromptSubmit` `additionalContext` is recorded (`attachment`/`hook_success` vs `hook_additional_context`). **Known limitation:** "direct continuation of the prior turn" is not detectable from the transcript, so a continuation turn that legitimately needs no route can be flagged; treat the log as a review signal, not a gate. **Fail-open:** no python3, no `transcript_path`, or an unreadable transcript → exit 0, no output. Lives in the same log as the directive breadcrumb, so a single `grep` interleaves "fired" and "no-route" into one per-session timeline; cross-check via `platform/scripts/logs-read.sh <sessionKey>`. This is a lightweight transcript read, not a per-turn spawn (contrast the Task-626 turn recorder below).
 - **Turn recorder — removed entirely (Task 626).** The `turn-completed-graph-write.sh` Stop hook, the `/api/admin/claude-sessions` loopback bypass it relied on, the `[turn-recorder]` emitters, the envelope walker, and the recorder-auto-archive subscriber are deleted. It had been dormant since Task 214 (never re-registered in settings.json); the admin now writes to the graph by delegating to `database-operator` via the Task tool inside the live session, and the on-demand `/insight` pass (`skills/insight/SKILL.md`, a registered admin skill — Task 641) is the per-session review. There is no per-turn spawn.
 
 ## Session identifiers (Task 135)

package/payload/platform/plugins/admin/hooks/__tests__/prompt-optimiser-compliance.test.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# Regression test for prompt-optimiser-compliance.sh (Task 719 Stop hook).
+#
+# A turn is flagged "directive-fired no-route-taken" only when the directive
+# marker is in the turn slice AND the prompt is non-trivial AND no Agent/Skill/
+# ToolSearch/mcp__* tool_use occurred. Covers both transcript record shapes,
+# every route surface, the trivial filters, and fail-open.
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/prompt-optimiser-compliance.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+
+# Build a transcript file from JSONL lines passed as args; echo its path.
+mk_transcript() {
+  local f; f=$(mktemp)
+  local line
+  for line in "$@"; do printf '%s\n' "$line" >> "$f"; done
+  printf '%s' "$f"
+}
+
+# Run the hook against a transcript; capture combined stderr (where the flag is
+# echoed). $1=transcript path.
+run_hook() {
+  printf '{"transcript_path":"%s","session_id":"sess12345678"}' "$1" | bash "$HOOK" 2>&1
+}
+
+USER_PROMPT='{"type":"user","message":{"role":"user","content":"how do I set up a Google Workspace email"}}'
+# UserPromptSubmit additionalContext, CC 2.1.x attachment/hook_success shape.
+DIRECTIVE_ATTACH='{"type":"attachment","attachment":{"type":"hook_success","hookEvent":"UserPromptSubmit","stdout":"{\"hookSpecificOutput\":{\"additionalContext\":\"PROMPT-OPTIMISER DIRECTIVE (standing) ...\"}}"}}'
+# Pi shape.
+DIRECTIVE_PI='{"type":"hook_additional_context","additionalContext":"PROMPT-OPTIMISER DIRECTIVE (standing) ..."}'
+ASSISTANT_TEXT='{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"To set up Gmail, enable IMAP in settings."}]}}'
+ASSISTANT_AGENT='{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"Agent","input":{}}]}}'
+ASSISTANT_SKILL='{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"Skill","input":{}}]}}'
+ASSISTANT_MCP='{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"mcp__plugin_email__email-provider-info","input":{}}]}}'
+ASSISTANT_TOOLSEARCH='{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","name":"ToolSearch","input":{}}]}}'
+
+assert_flagged() {
+  local name="$1" t="$2" out
+  out=$(run_hook "$t")
+  if printf '%s' "$out" | grep -q "no-route-taken"; then
+    echo "PASS: $name"; PASS=$((PASS+1))
+  else
+    echo "FAIL: $name (expected flag, got: $out)" >&2; FAIL=$((FAIL+1))
+  fi
+  rm -f "$t"
+}
+
+assert_not_flagged() {
+  local name="$1" t="$2" out
+  out=$(run_hook "$t")
+  if printf '%s' "$out" | grep -q "no-route-taken"; then
+    echo "FAIL: $name (expected NO flag, got: $out)" >&2; FAIL=$((FAIL+1))
+  else
+    echo "PASS: $name"; PASS=$((PASS+1))
+  fi
+  rm -f "$t"
+}
+
+# 1. Directive fired (attachment shape) + prose only -> flagged.
+assert_flagged "attachment-shape directive + no route -> flagged" \
+  "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_TEXT")"
+
+# 2. Directive fired (Pi shape) + prose only -> flagged.
+assert_flagged "pi-shape directive + no route -> flagged" \
+  "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_PI" "$ASSISTANT_TEXT")"
+
+# 3–6. Each route surface suppresses the flag.
+assert_not_flagged "Agent dispatch -> not flagged" \
+  "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_AGENT")"
+assert_not_flagged "Skill load -> not flagged" \
+  "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_SKILL")"
+assert_not_flagged "mcp__ tool -> not flagged" \
+  "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_MCP")"
+assert_not_flagged "ToolSearch -> not flagged" \
+  "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_TOOLSEARCH")"
+
+# 7. No directive in the slice -> not flagged.
+assert_not_flagged "no directive -> not flagged" \
+  "$(mk_transcript "$USER_PROMPT" "$ASSISTANT_TEXT")"
+
+# 8. Slash-command prompt -> not flagged.
+assert_not_flagged "slash-command -> not flagged" \
+  "$(mk_transcript '{"type":"user","message":{"role":"user","content":"/insight"}}' "$DIRECTIVE_ATTACH" "$ASSISTANT_TEXT")"
+
+# 9. One-word confirmation -> not flagged.
+assert_not_flagged "one-word confirmation -> not flagged" \
+  "$(mk_transcript '{"type":"user","message":{"role":"user","content":"yes"}}' "$DIRECTIVE_ATTACH" "$ASSISTANT_TEXT")"
+
+# Synthetic (isMeta) user rows that Claude Code injects AFTER the real prompt:
+# a skill body and a system-reminder. The boundary must NOT land on these.
+META_SKILL='{"type":"user","isMeta":true,"message":{"role":"user","content":[{"type":"text","text":"Base directory for this skill: /x/y. Follow the instructions."}]}}'
+META_REMINDER='{"type":"user","isMeta":true,"message":{"role":"user","content":[{"type":"text","text":"<system-reminder>The task tools were not used recently.</system-reminder>"}]}}'
+# WhatsApp/native channel inbound: isMeta:true AND channel-wrapped — this IS the prompt.
+CHANNEL_PROMPT='{"type":"user","isMeta":true,"message":{"role":"user","content":"<channel source=\"whatsapp-channel\"> how do I connect a domain </channel>"}}'
+
+# 10. Channel-wrapped non-trivial prompt (isMeta, as on the Pi) -> flagged.
+assert_flagged "isMeta channel-wrapped prompt + no route -> flagged" \
+  "$(mk_transcript "$CHANNEL_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_TEXT")"
+
+# 10b. Real prompt followed by isMeta skill/reminder injections -> still flagged
+# (boundary stays on the real prompt; the slice is not truncated). Regression for
+# the boundary bug where the last text-bearing user row was a meta injection.
+assert_flagged "prompt then isMeta injections + no route -> flagged (boundary holds)" \
+  "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_TEXT" "$META_SKILL" "$META_REMINDER")"
+
+# 10c. A route taken before the trailing isMeta injections -> NOT flagged. Proves
+# the slice still reaches the tool_use rather than stopping at the meta boundary.
+assert_not_flagged "route then isMeta injections -> not flagged (slice not truncated)" \
+  "$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_AGENT" "$META_SKILL")"
+
+# 10d. Slash-command prompt followed by an isMeta skill body -> not flagged. The
+# boundary must read the slash prompt, not the non-slash injected body.
+assert_not_flagged "slash prompt then isMeta skill body -> not flagged" \
+  "$(mk_transcript '{"type":"user","message":{"role":"user","content":"/insight"}}' "$DIRECTIVE_ATTACH" "$ASSISTANT_TEXT" "$META_SKILL")"
+
+# 11. Fail-open: missing transcript_path -> exit 0, no output.
+fo_out=$(printf '{"session_id":"x"}' | bash "$HOOK" 2>&1); fo_exit=$?
+if [[ "$fo_exit" -eq 0 && -z "$fo_out" ]]; then
+  echo "PASS: missing transcript_path -> exit 0, no output (fail-open)"; PASS=$((PASS+1))
+else
+  echo "FAIL: fail-open wrong (exit=$fo_exit out=$fo_out)" >&2; FAIL=$((FAIL+1))
+fi
+
+# 12. Fail-open: nonexistent transcript path -> exit 0, no output.
+ne_out=$(printf '{"transcript_path":"/nonexistent/x.jsonl","session_id":"x"}' | bash "$HOOK" 2>&1); ne_exit=$?
+if [[ "$ne_exit" -eq 0 && -z "$ne_out" ]]; then
+  echo "PASS: nonexistent transcript -> exit 0, no output (fail-open)"; PASS=$((PASS+1))
+else
+  echo "FAIL: nonexistent-transcript fail-open wrong (exit=$ne_exit out=$ne_out)" >&2; FAIL=$((FAIL+1))
+fi
+
+# 13. Durable log: flag lands in $LOG_DIR/prompt-optimiser-directive.log.
+LD=$(mktemp -d)
+t13=$(mk_transcript "$USER_PROMPT" "$DIRECTIVE_ATTACH" "$ASSISTANT_TEXT")
+printf '{"transcript_path":"%s","session_id":"sess12345678"}' "$t13" | LOG_DIR="$LD" bash "$HOOK" >/dev/null 2>&1
+if grep -q "no-route-taken" "$LD/prompt-optimiser-directive.log" 2>/dev/null \
+   && grep -q "session=sess1234" "$LD/prompt-optimiser-directive.log" 2>/dev/null; then
+  echo "PASS: flag appended to durable log with session id"; PASS=$((PASS+1))
+else
+  echo "FAIL: durable flag missing (log=$(cat "$LD/prompt-optimiser-directive.log" 2>/dev/null))" >&2; FAIL=$((FAIL+1))
+fi
+rm -rf "$LD" "$t13"
+
+echo "----"
+echo "PASS=$PASS FAIL=$FAIL"
+[[ "$FAIL" -eq 0 ]]

package/payload/platform/plugins/admin/hooks/__tests__/prompt-optimiser-directive.test.sh

@@ -92,6 +92,16 @@ if printf '%s' "$ctx" | grep -qi "outcome" \
 else
   echo "FAIL: outcome-only-brief contract missing from ladder" >&2; FAIL=$((FAIL+1))
 fi
+# Capability-question clause (Task 719): capability/how-to/config questions are
+# owned work, answered from the owning specialist or plugin tool/reference,
+# never from training memory.
+if printf '%s' "$ctx" | grep -qi "owned work" \
+   && printf '%s' "$ctx" | grep -qi "training memory" \
+   && printf '%s' "$ctx" | grep -qi "do you have instructions"; then
+  echo "PASS: capability-question clause present in directive"; PASS=$((PASS+1))
+else
+  echo "FAIL: capability-question clause missing from directive" >&2; FAIL=$((FAIL+1))
+fi
 
 # Case 5 — ADMIN-SKILLS.md absent: fail-open. exit 0, ladder still injected,
 # and the missing= breadcrumb on stderr (fail-open must be visible).
@@ -107,6 +117,20 @@ else
 fi
 rm -rf "$WD"
 
+# Case 6 — durable breadcrumb (Task 719). With LOG_DIR set and a session_id on
+# stdin, the hook appends one `injected len=` line carrying the session id to
+# $LOG_DIR/prompt-optimiser-directive.log, in addition to the stderr line.
+LD=$(mktemp -d)
+printf '%s' '{"prompt":"x","session_id":"sess-719-test"}' | LOG_DIR="$LD" bash "$HOOK" >/dev/null 2>&1
+if [[ -f "$LD/prompt-optimiser-directive.log" ]] \
+   && grep -q "prompt-optimiser-directive] injected len=" "$LD/prompt-optimiser-directive.log" \
+   && grep -q "session=sess-719-test" "$LD/prompt-optimiser-directive.log"; then
+  echo "PASS: durable breadcrumb appended with session id"; PASS=$((PASS+1))
+else
+  echo "FAIL: durable breadcrumb missing (log=$(cat "$LD/prompt-optimiser-directive.log" 2>/dev/null))" >&2; FAIL=$((FAIL+1))
+fi
+rm -rf "$LD"
+
 echo "----"
 echo "PASS=$PASS FAIL=$FAIL"
 [[ "$FAIL" -eq 0 ]]