@rubytech/create-maxy-code 0.1.281 → 0.1.283

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.281",
+  "version": "0.1.283",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/config/brand.json

@@ -55,7 +55,6 @@
   },
 
   "externalPlugins": [
-    { "name": "telegram", "marketplace": "claude-plugins-official", "channelPlugin": true },
     { "name": "discord",  "marketplace": "claude-plugins-official", "channelPlugin": true },
     { "name": "imessage", "marketplace": "claude-plugins-official", "channelPlugin": true },
     { "name": "superpowers", "marketplace": "claude-plugins-official" },

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 ]]

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

@@ -0,0 +1,174 @@
+#!/usr/bin/env bash
+# Stop hook (Task 719): after the admin agent finishes a turn, flag the turn when
+# the per-turn routing directive fired, the turn was non-trivial, and NO route was
+# taken — i.e. the agent answered from memory instead of dispatching a specialist,
+# loading a skill, or calling the owning plugin's tool. This is the standing
+# compliance signal the directive hook (prompt-optimiser-directive.sh) cannot
+# self-emit, because "was a route taken" is only knowable after the turn ends.
+#
+# Classification (all derived from the just-finished turn in the transcript):
+#   directive fired = the marker "PROMPT-OPTIMISER DIRECTIVE" appears in the turn
+#                     slice (robust to CC-version differences in how the
+#                     UserPromptSubmit additionalContext is recorded: a
+#                     type:"attachment"/hook_success on 2.1.x, a
+#                     type:"hook_additional_context" on the Pi).
+#   route taken     = the turn contains a tool_use named Agent, Skill, ToolSearch,
+#                     or matching mcp__*.
+#   trivial         = the prompt is a slash-command or a one-word confirmation.
+# "Direct continuation" is NOT detectable from the transcript and is a stated
+# known limitation, not guessed.
+#
+# Emits, only on (directive fired AND not trivial AND no route):
+#   <ts> [prompt-optimiser-compliance] directive-fired no-route-taken session=<id8> prompt="<clip>"
+# to $LOG_DIR/prompt-optimiser-directive.log (same log as the fired breadcrumb,
+# so the two interleave into one greppable timeline) and to stderr.
+#
+# Input (stdin, Stop contract): { "transcript_path": "...", "session_id": "...", ... }
+# Fail-open everywhere: no python3, no transcript_path, unreadable transcript, or
+# any parse error -> exit 0 with no output. A Stop hook must never block a turn.
+
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || true)
+command -v python3 >/dev/null 2>&1 || exit 0
+
+RESULT=$(printf '%s' "$INPUT" | python3 -c '
+import json, sys, os, datetime
+
+def fail_open():
+    sys.exit(0)
+
+try:
+    inp = json.load(sys.stdin)
+except Exception:
+    fail_open()
+
+tp = inp.get("transcript_path")
+session = inp.get("session_id") or "?"
+if not isinstance(tp, str) or not tp or not os.path.exists(tp):
+    fail_open()
+
+rows = []
+try:
+    with open(tp, "r", errors="replace") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rows.append(json.loads(line))
+            except Exception:
+                continue
+except OSError:
+    fail_open()
+
+# Flatten a message.content into plain text; mark whether it is purely tool_result
+# (a tool output row, not a user prompt).
+def flatten(content):
+    if isinstance(content, str):
+        return content, False
+    if isinstance(content, list):
+        only_tool_result = bool(content)
+        parts = []
+        for b in content:
+            if not isinstance(b, dict):
+                only_tool_result = False
+                if isinstance(b, str):
+                    parts.append(b)
+                continue
+            t = b.get("type")
+            if t != "tool_result":
+                only_tool_result = False
+            if t == "text" and isinstance(b.get("text"), str):
+                parts.append(b["text"])
+        return " ".join(parts), only_tool_result
+    return "", False
+
+# A row is synthetic (not a genuine prompt) when Claude Code stamps it isMeta /
+# isSidechain / etc. Claude Code injects such user rows AFTER the real prompt
+# within the same turn — skill bodies, system-reminders, additionalContext
+# echoes — so a naive "last text-bearing user row" would land on the injection,
+# truncate the slice, and read the injected body as the prompt.
+def is_synthetic(r):
+    return any(r.get(k) for k in ("isMeta", "isSidechain", "isCompactSummary", "isVisibleInTranscriptOnly"))
+
+# Boundary: the last user row that carries a genuine prompt. A genuine prompt is
+# either a non-synthetic user turn (typed claude.ai) OR a synthetic turn whose
+# text is channel-wrapped — WhatsApp/native channels stamp the inbound prompt
+# isMeta:true and wrap it in <channel ...>, and that inbound IS the prompt. Every
+# other synthetic row (skill body, system-reminder) is skipped. The turn slice is
+# everything from the boundary to EOF.
+boundary = None
+prompt_text = ""
+for i, r in enumerate(rows):
+    if not isinstance(r, dict) or r.get("type") != "user":
+        continue
+    msg = r.get("message") if isinstance(r.get("message"), dict) else {}
+    text, only_tool_result = flatten(msg.get("content"))
+    if only_tool_result:
+        continue
+    stripped = text.strip()
+    if not stripped:
+        continue
+    if is_synthetic(r) and not stripped.startswith("<channel"):
+        continue
+    boundary = i
+    prompt_text = stripped
+
+if boundary is None:
+    fail_open()
+
+slice_rows = rows[boundary:]
+
+# Strip a leading <channel ...>...</channel> wrapper to reach the inner prompt for
+# the trivial check (WhatsApp/native-channel prompts arrive wrapped).
+inner = prompt_text
+if inner.startswith("<channel"):
+    end = inner.find(">")
+    close = inner.rfind("</channel>")
+    if end != -1 and close != -1 and close > end:
+        inner = inner[end + 1:close].strip()
+
+# Trivial-turn filter.
+is_slash = inner.startswith("/")
+tokens = inner.split()
+is_one_word = len(tokens) <= 1
+
+# Directive fired = marker present anywhere in the slice (any record shape).
+marker = "PROMPT-OPTIMISER DIRECTIVE"
+directive_fired = any(marker in json.dumps(r, ensure_ascii=False) for r in slice_rows)
+
+# Route taken = an assistant tool_use with a routing tool name.
+ROUTE_TOOLS = ("Agent", "Skill", "ToolSearch")
+def is_route(name):
+    return name in ROUTE_TOOLS or (isinstance(name, str) and name.startswith("mcp__"))
+
+route_taken = False
+for r in slice_rows:
+    if not isinstance(r, dict) or r.get("type") != "assistant":
+        continue
+    msg = r.get("message") if isinstance(r.get("message"), dict) else {}
+    content = msg.get("content")
+    if isinstance(content, list):
+        for b in content:
+            if isinstance(b, dict) and b.get("type") == "tool_use" and is_route(b.get("name")):
+                route_taken = True
+                break
+    if route_taken:
+        break
+
+if directive_fired and not is_slash and not is_one_word and not route_taken:
+    clip = prompt_text.replace("\n", " ")[:80]
+    ts = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    sid8 = session[:8] if isinstance(session, str) else "?"
+    print("%s [prompt-optimiser-compliance] directive-fired no-route-taken session=%s prompt=\"%s\"" % (ts, sid8, clip))
+' 2>/dev/null) || exit 0
+
+[ -n "$RESULT" ] || exit 0
+
+# Durable + stderr. Fail-open on an unwritable/absent LOG_DIR.
+if [ -n "${LOG_DIR:-}" ] && [ -d "$LOG_DIR" ]; then
+  printf '%s\n' "$RESULT" >> "$LOG_DIR/prompt-optimiser-directive.log" 2>/dev/null || true
+fi
+printf '%s\n' "$RESULT" >&2
+exit 0

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

@@ -32,8 +32,9 @@
 
 set -uo pipefail
 
-# Drain stdin; the directive does not depend on the prompt text.
-cat >/dev/null 2>&1 || true
+# Capture stdin: the directive does not depend on the prompt text, but the
+# UserPromptSubmit payload carries session_id, used for the durable breadcrumb.
+HOOK_INPUT=$(cat 2>/dev/null || true)
 
 # Fail-open if the JSON encoder is unavailable.
 command -v python3 >/dev/null 2>&1 || exit 0
@@ -65,6 +66,8 @@ PROMPT-OPTIMISER DIRECTIVE (standing)
 Before acting on this turn's request, run the prompt-optimiser skill on the user's raw prompt in its in-session restatement mode, then treat the restated task as the authoritative statement of what was asked and proceed from it. Set aside your own first reading of the raw wording; the restatement governs. The raw prompt stays in context for reference only.
 Skip the restatement when the prompt is a one-word confirmation, a slash-command invocation, or a direct continuation of the immediately preceding turn; restatement adds nothing in those cases.
 
+CAPABILITY QUESTIONS ARE OWNED WORK. A question about what this platform can do or how to do it — "how do I set up X", "do you have instructions for X", any configuration or how-to about a platform feature — is answered from the owning specialist or the owning plugin's tool or reference, never from your training memory. Your prior on the platform's own features is stale relative to what shipped, so memory is the wrong source here even when it feels confident. Route the question (dispatch the owning specialist, or skill-load / call the owning plugin's tool or reference) and source the answer from what that route returns. Freestyle tier 3 is not a route for these: "there is no instruction surface for this" is itself something you establish by routing and finding nothing, not by recalling.
+
 ROUTING LADDER (apply to the restated task, in this order):
 1) Delegate to a specialist. If an installed specialist owns this deliverable's type, dispatch it with the Agent tool and the matching subagent_type. Ownership covers origination, not just the final render: you may not author the substance here and hand the specialist only the formatting, the voice pass, or the PDF step. The brief states the outcome (what is true when the specialist returns) plus the binding constraints (account, file scope, deadline, acceptance check). It never names lines, anchors, or literal text to insert; deriving those is the specialist's job. Wrong shape: naming the file, the line range, and the exact text to drop in. Right shape: "on the realagent-code site, the footer respects iOS safe-area-inset-bottom on mobile; the site's CSS is the only file in scope." Installed specialists:
 DIRECTIVE_EOF
@@ -93,5 +96,22 @@ print(json.dumps({
 
 [ -n "$OUT" ] || exit 0
 printf '%s\n' "$OUT"
+
+# Durable breadcrumb: capture the per-turn injection in $LOG_DIR so "directive
+# fired on this turn" is greppable for compliance review, not only on stderr
+# (Task 719). Fail-open: no LOG_DIR, missing dir, or unwritable -> skip the file;
+# the stderr line below still emits. session_id is parsed from the captured
+# stdin; absent -> "?".
+if [ -n "${LOG_DIR:-}" ] && [ -d "$LOG_DIR" ]; then
+  SID=$(printf '%s' "$HOOK_INPUT" | python3 -c 'import json,sys
+try:
+    print(json.load(sys.stdin).get("session_id","") or "")
+except Exception:
+    print("")' 2>/dev/null)
+  TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  printf '%s [prompt-optimiser-directive] injected len=%s session=%s\n' \
+    "$TS" "${#DIRECTIVE}" "${SID:-?}" >> "$LOG_DIR/prompt-optimiser-directive.log" 2>/dev/null || true
+fi
+
 echo "[prompt-optimiser-directive] injected len=${#DIRECTIVE}" >&2
 exit 0

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Maxy ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:137ecdb03fdbb733f6150e0d931f4e5f30bf7daafcf738398d8c2768b868936e
+content-hash: sha256:5dae80dcc0e3d36e755dcf26570c4d7c8893b6198b8cd769b3e5c6c1c79169f5
 brand: maxy-code
 product-name: Maxy
 ---
@@ -1035,7 +1035,7 @@ Each installation has its own Cloudflare account. The **tunnel** sign-in is OAut
 | **Domain scope** (which zones the operator can route) | The operator picks the zone in the dashboard during OAuth or names it in chat; the agent can also enumerate zones via the API with a minted read-scoped token. |
 | **Local tunnel state** | `~/{configDir}/cloudflared/` — `cert.pem`, `<UUID>.json`, `config.yml`, `alias-domains.json`. |
 
-Tunnel auth on the operator-owned path (Mode A) is the OAuth cert (`cert.pem`); API operations use a narrow token the agent mints from your master token. To switch Cloudflare accounts, the agent runs the reset flow from `plugins/cloudflare/references/reset-guide.md` (deletes the cert and every tunnel on the current account), then the manual-setup flow again — `cloudflared tunnel login` picks a fresh account when you sign in.
+Tunnel auth on the operator-owned path (Mode A) is the OAuth cert (`cert.pem`); API operations use a narrow token the agent mints from your master token. That master may be account-scoped (`cfat_…`) or user-scoped (`cfut_…`); the agent detects the type and routes API endpoints accordingly (the account vs user token endpoints) — see `plugins/cloudflare/references/api.md`. To switch Cloudflare accounts, the agent runs the reset flow from `plugins/cloudflare/references/reset-guide.md` (deletes the cert and every tunnel on the current account), then the manual-setup flow again — `cloudflared tunnel login` picks a fresh account when you sign in.
 
 ## Setup flow
 
@@ -1728,13 +1728,13 @@ The Telegram plugin connects Maxy to a Telegram bot. Once set up, you can:
 
 ### Step 2: Connect the plugin
 
-Tell Maxy: "Set up Telegram" or "Configure the Telegram bot."
+Tell Maxy: "Set up Telegram" or "Configure the Telegram bot." Setup runs entirely in the admin chat — there is no settings page.
 
-Maxy will ask for your bot token, then save it and activate the plugin. The bot is now connected.
+Maxy asks for your bot token, then asks whether this is an **admin bot** (only your numeric Telegram IDs may message it) or a **public bot** (customer-facing, with a DM policy). It verifies the token, registers the bot's webhook on your brand's edge, stores the token under your brand's config (never in a shared system directory), and — for a public bot — sets the agent that will answer. The bot is now connected.
 
 ### Step 3: Start the bot
 
-In Telegram, open your bot and send `/start`. The bot is now active and listening.
+In Telegram, open your bot and send `/start`, then a message. Maxy receives it and replies in the same chat. Admin-bot messages from your registered IDs reach the admin agent; public-bot messages reach the public agent you selected.
 
 ## Sending Messages via Maxy