@rubytech/create-sitedesk-code 0.1.340

package/payload/platform/plugins/admin/hooks/mcp-tool-missing.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# Deterministic missing-tool envelope (Task 502, directive 3).
+#
+# PostToolUse hook. When a maxy MCP tool call resolves to "No such tool
+# available: mcp__..." (the failure class Task 502's name-binding is designed to
+# eliminate, kept here as defence-in-depth for a server that failed to start or
+# a name that slipped the build gate), this hook replaces the agent's latitude
+# to narrate ("the servers were still warming up") and blind-retry with a fixed
+# failure envelope, and logs one deterministic diagnostic line that names the
+# server and tool so a future occurrence identifies itself.
+#
+# Scope: maxy servers only. A missing non-maxy bridge tool (Playwright etc.,
+# upstream-owned) is passed through untouched. Maxy plugins are read from the
+# generated list at lib/maxy-mcp-plugins.txt (kept current by the build gate).
+#
+# Output:
+#   stderr (diagnostic): [mcp-tool-missing] server=<server> tool=<tool>
+#   stderr (envelope, exit 2): the fixed message the agent must relay verbatim.
+#
+# A maxy missing-tool match exits 2 so PostToolUse feeds the envelope back to
+# the model as the authoritative result. Every other path exits 0 (no-op).
+
+set -uo pipefail
+
+if [ -t 0 ]; then
+  exit 0
+fi
+INPUT=$(cat)
+
+PLUGINS_FILE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/maxy-mcp-plugins.txt"
+
+# Parse hook_event_name, tool_name, and the tool_response text in one pass.
+PARSED=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    print("\t\t"); sys.exit(0)
+event = d.get("hook_event_name", "") or ""
+tool = d.get("tool_name", "") or ""
+resp = d.get("tool_response", "")
+# tool_response may be a string, a dict, or a list of content blocks. Flatten
+# to text so the "No such tool available" probe sees it whatever the shape.
+text = json.dumps(resp) if not isinstance(resp, str) else resp
+print(event + "\t" + tool + "\t" + text.replace("\n", " "))
+' 2>/dev/null)
+
+HOOK_EVENT="${PARSED%%$'\t'*}"
+REST="${PARSED#*$'\t'}"
+TOOL_NAME="${REST%%$'\t'*}"
+RESP_TEXT="${REST#*$'\t'}"
+
+[ "$HOOK_EVENT" = "PostToolUse" ] || exit 0
+case "$TOOL_NAME" in mcp__*) ;; *) exit 0 ;; esac
+# Only act on the missing-tool failure class; a tool that ran is none of our
+# business.
+case "$RESP_TEXT" in *"No such tool available"*) ;; *) exit 0 ;; esac
+
+# Resolve <server> and <tool> from the qualified name.
+#   long:  mcp__plugin_<server>_<server>__<tool>
+#   short: mcp__<server>__<tool>
+SERVER=""
+TOOL=""
+case "$TOOL_NAME" in
+  mcp__plugin_*)
+    inner="${TOOL_NAME#mcp__plugin_}"      # <server>_<server>__<tool>
+    SERVER="${inner%%__*}"                 # <server>_<server>
+    SERVER="${SERVER%%_*}"                 # <server>  (plugin == server)
+    TOOL="${TOOL_NAME##*__}"
+    ;;
+  mcp__*)
+    inner="${TOOL_NAME#mcp__}"             # <server>__<tool>
+    SERVER="${inner%%__*}"
+    TOOL="${TOOL_NAME##*__}"
+    ;;
+esac
+[ -n "$SERVER" ] || exit 0
+
+# Maxy server? A non-maxy bridge (Playwright shares the long-prefix shape) is
+# upstream-owned — pass it through.
+if [ ! -f "$PLUGINS_FILE" ] || ! grep -qxF "$SERVER" "$PLUGINS_FILE"; then
+  exit 0
+fi
+
+echo "[mcp-tool-missing] server=${SERVER} tool=${TOOL}" >&2
+cat >&2 <<EOF
+The maxy tool ${TOOL_NAME} is not available in this session. This is a
+deterministic failure of the ${SERVER} MCP server — either it failed to start
+on this device or the tool name is not registered. Reply once telling the
+operator the ${SERVER} server is unavailable and to run the admin system-status
+check; do not retry this call, do not guess another tool name, do not describe
+the servers as "warming up". Then stop.
+EOF
+exit 2

package/payload/platform/plugins/admin/hooks/post-tool-use-agent.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+# Task 560 — PostToolUse hook scoped to tool_name=Agent in the admin role.
+# Drains every subagent hook-decision buffer in the dir, prints each record
+# as a [hook-propagate] line to stdout (Claude Code attaches the stdout to
+# the parent JSONL as a hook_success attachment), and emits one
+# [hook-propagate-census] line. N != M in the census is the propagation
+# regression signal.
+#
+# Task 563 — concurrency hardening:
+#   - Atomic claim before read. Each buffer is renamed under a mkdir mutex
+#     to a per-fire `claimed/<basename>-<epoch>-<pid>.jsonl` path. The lock
+#     is held only for the rename syscall; reading happens against the
+#     renamed inode, which no emitter can address. The race window between
+#     the drainer's read and the buffer rotation is closed.
+#   - No cursor. The cursor file was load-bearing only because consumed
+#     buffers could be re-seen; with atomic claim the file's presence in
+#     the directory is the unambiguous signal. Dropping the cursor closes
+#     two further races (concurrent-drainer cursor write, shared
+#     `.unknown.cursor` across broken-stdin fires).
+#   - Unknown-parent observability. When stdin's `session_id` is missing
+#     or unparseable, an explicit `[hook-propagate] parentSession=unknown
+#     reason=session-id-missing` line is emitted to both stdout and
+#     server.log so the broken-stdin path is no longer silent.
+
+set -uo pipefail
+
+: "${MAXY_HOOK_BUFFER_DIR:=$HOME/.maxy-code/logs/hook-decisions}"
+: "${MAXY_HOOK_SERVER_LOG:=$HOME/.maxy-code/logs/server.log}"
+: "${MAXY_HOOK_LOCK_ATTEMPTS:=100}"
+: "${MAXY_HOOK_LOCK_SLEEP:=0.01}"
+# Task 569 — TTL for orphaned lockdirs (see hook-emit.sh for rationale).
+: "${MAXY_HOOK_LOCK_TTL_SECONDS:=5}"
+
+if [ -t 0 ]; then
+  # No stdin — no correlation possible. Fail-open.
+  exit 0
+fi
+INPUT=$(cat)
+PARENT_SESSION=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    sid = json.load(sys.stdin).get("session_id") or ""
+    print(sid if sid else "unknown")
+except Exception:
+    print("unknown")
+' 2>/dev/null || echo "unknown")
+
+if [[ "$PARENT_SESSION" == "unknown" ]]; then
+  # Conservative play (Task 563 brief option C): emit observability and
+  # exit without draining. A broken-stdin fire has no business processing
+  # buffers — the next valid parent fire will pick them up.
+  mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+  printf '[hook-propagate] parentSession=unknown reason=session-id-missing\n'
+  printf '[hook-propagate] parentSession=unknown reason=session-id-missing\n' \
+    >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null || true
+  exit 0
+fi
+
+mkdir -p "$MAXY_HOOK_BUFFER_DIR/claimed" "$MAXY_HOOK_BUFFER_DIR/consumed" 2>/dev/null
+
+# Sweep orphaned `.<session>.cursor` files left behind by an older
+# version of this script. The cursor mechanism is gone; without this
+# they would persist forever as dir noise.
+rm -f "$MAXY_HOOK_BUFFER_DIR"/.*.cursor 2>/dev/null || true
+
+NOW_EPOCH=$(date +%s)
+N_OBSERVED=0
+N_EMITTED=0
+
+# Task 569 — same stale-lockdir TTL reclamation as hook-emit.sh.
+_drain_lockdir_age_seconds() {
+  local lockdir="$1" mtime now
+  mtime=$(stat -c %Y "$lockdir" 2>/dev/null || stat -f %m "$lockdir" 2>/dev/null)
+  [[ -z "$mtime" ]] && { echo -1; return; }
+  now=$(date +%s)
+  echo $((now - mtime))
+}
+
+_drain_acquire_lock() {
+  local lockdir="$1" i=0 age
+  while ! mkdir "$lockdir" 2>/dev/null; do
+    age=$(_drain_lockdir_age_seconds "$lockdir")
+    if [[ "$age" -ge "$MAXY_HOOK_LOCK_TTL_SECONDS" ]]; then
+      rmdir "$lockdir" 2>/dev/null || rm -rf "$lockdir" 2>/dev/null
+      mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+      printf '[hook-propagate-error] reason=stale-lock-reclaimed lockdir=%s ageSeconds=%s\n' \
+        "$lockdir" "$age" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null || true
+      mkdir "$lockdir" 2>/dev/null && return 0
+    fi
+    i=$((i+1))
+    [[ "$i" -ge "$MAXY_HOOK_LOCK_ATTEMPTS" ]] && return 1
+    sleep "$MAXY_HOOK_LOCK_SLEEP" 2>/dev/null || true
+  done
+  return 0
+}
+
+shopt -s nullglob
+for buf in "$MAXY_HOOK_BUFFER_DIR"/*.jsonl; do
+  [[ -f "$buf" ]] || continue
+  case "$(basename "$buf")" in
+    .*) continue;;
+  esac
+  lock="${buf}.lock"
+  if ! _drain_acquire_lock "$lock"; then
+    mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+    printf '[hook-propagate-error] reason=lock-timeout parentSession=%s buffer=%s\n' \
+      "$PARENT_SESSION" "$(basename "$buf")" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null || true
+    continue
+  fi
+  # Re-check existence under lock — a peer drainer may have claimed it
+  # between our `for` iteration and our lock acquisition.
+  if [[ ! -f "$buf" ]]; then
+    rmdir "$lock" 2>/dev/null || true
+    continue
+  fi
+  CLAIMED="$MAXY_HOOK_BUFFER_DIR/claimed/$(basename "$buf" .jsonl)-${NOW_EPOCH}-$$.jsonl"
+  if ! mv "$buf" "$CLAIMED" 2>/dev/null; then
+    rmdir "$lock" 2>/dev/null || true
+    mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+    printf '[hook-propagate-error] reason=claim-mv parentSession=%s buffer=%s\n' \
+      "$PARENT_SESSION" "$(basename "$buf")" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null || true
+    continue
+  fi
+  rmdir "$lock" 2>/dev/null || true
+
+  # Ground-truth observed count: non-empty lines in the claimed file. The
+  # printf-success N_EMITTED is incremented independently below, so a
+  # printf failure (SIGPIPE on a closed downstream pipe, EIO on stdout)
+  # produces N_OBSERVED > N_EMITTED — the propagation regression signal
+  # the census promises. The two counters must not be bumped together.
+  BUF_LINES=$(grep -c . "$CLAIMED" 2>/dev/null || echo 0)
+  N_OBSERVED=$((N_OBSERVED + BUF_LINES))
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    [[ -z "$line" ]] && continue
+    if printf '[hook-propagate] %s\n' "$line" 2>/dev/null; then
+      N_EMITTED=$((N_EMITTED+1))
+    fi
+  done <"$CLAIMED"
+  TARGET="$MAXY_HOOK_BUFFER_DIR/consumed/$(basename "$CLAIMED")"
+  if ! mv "$CLAIMED" "$TARGET" 2>/dev/null; then
+    mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+    printf '[hook-propagate-error] reason=consumed-mv parentSession=%s buffer=%s\n' \
+      "$PARENT_SESSION" "$(basename "$CLAIMED")" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null || true
+  fi
+done
+shopt -u nullglob
+
+printf '[hook-propagate-census] parentSession=%s subagentHooksObserved=%d attachmentsEmitted=%d\n' \
+  "$PARENT_SESSION" "$N_OBSERVED" "$N_EMITTED"
+
+mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+printf '[hook-propagate-census] parentSession=%s subagentHooksObserved=%d attachmentsEmitted=%d\n' \
+  "$PARENT_SESSION" "$N_OBSERVED" "$N_EMITTED" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null || true
+
+exit 0

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

@@ -0,0 +1,213 @@
+#!/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), OR the prompt is
+#                     a <channel>-wrapped reframe turn (## Context/## Instruction
+#                     sections, Task 805) — the directive hook suppresses itself
+#                     on channel turns, so the reframe is directive-equivalent.
+#   route taken     = the turn contains a tool_use that is a genuine route:
+#                     Agent/Task dispatch, native Skill, or a *__skill-load MCP
+#                     tool. ToolSearch (a schema load) and the channel transport
+#                     reply tools (mcp__*-channel__reply/-document) are NOT routes
+#                     — counting them was the Task 747 bug that blinded the
+#                     detector on every channel turn (the reply is mandatory).
+#   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> tools=<csv> prompt="<clip>"
+#   tools=<csv> is the comma-joined tool names seen in the slice (empty on a
+#   no-tool freestyle turn), so a future false-negative shows what was (mis)counted.
+# 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 leading <channel ...>...</channel> wrapper(s) to reach the inner
+# prompt. WhatsApp/native-channel prompts arrive wrapped once; a multi-target
+# (unified-server, Task 853) prompt arrives DOUBLE-wrapped — the harness wraps
+# with the registration key `channel` and the server embeds an inner
+# <channel source="<door>"> tag — so iterate until the payload surfaces.
+inner = prompt_text
+is_channel = False
+while inner.startswith("<channel"):
+    end = inner.find(">")
+    close = inner.rfind("</channel>")
+    if end == -1 or close == -1 or close <= end:
+        break
+    inner = inner[end + 1:close].strip()
+    is_channel = True
+
+# Task 805 — a channel-wrapped reframe turn (the ## Context / ## Instruction
+# sections of composeAdminContent) is directive-equivalent: the directive hook suppresses
+# itself on channel turns (Task 753), so the reframe is the only routing
+# instruction the turn carries, and the marker check alone left every channel
+# turn unevaluated. A channel-wrapped turn WITHOUT the reframe (webchat today,
+# Task 776) is not directive-equivalent. For the trivial check the prompt is the
+# Context payload, not the wrapper — the always-present instruction text would
+# otherwise make a one-word confirmation look non-trivial.
+is_reframe = is_channel and inner.startswith("## Context\n") and "\n## Instruction\n" in inner
+if is_reframe:
+    head, _, _rest = inner.partition("\n## Instruction\n")
+    inner = head[len("## Context"):].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) OR
+# the prompt is a channel-wrapped reframe turn (Task 805).
+marker = "PROMPT-OPTIMISER DIRECTIVE"
+directive_fired = is_reframe or any(marker in json.dumps(r, ensure_ascii=False) for r in slice_rows)
+
+# Route taken = an assistant tool_use that is a genuine route: specialist
+# dispatch (Agent/Task) or skill load (native Skill, or the *__skill-load MCP
+# tool under either admin namespace). ToolSearch is a schema load, and the channel
+# transport reply tools (mcp__*-channel__reply / reply-document) are mandatory
+# transport, not routes — neither counts. Every tool name in the slice is
+# collected for the tools= breadcrumb so a future false-negative shows what was
+# (mis)counted.
+ROUTE_TOOLS = ("Agent", "Task", "Skill")
+def is_route(name):
+    if not isinstance(name, str):
+        return False
+    return name in ROUTE_TOOLS or name.endswith("__skill-load")
+
+tool_names = []
+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":
+                nm = b.get("name")
+                if isinstance(nm, str):
+                    tool_names.append(nm)
+
+route_taken = any(is_route(n) for n in tool_names)
+
+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 "?"
+    tools_csv = ",".join(tool_names)
+    print("%s [prompt-optimiser-compliance] directive-fired no-route-taken session=%s tools=%s prompt=\"%s\"" % (ts, sid8, tools_csv, 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

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook: inject the standing prompt-optimiser directive plus the
+# per-turn three-tier routing ladder as additionalContext on every turn, so the
+# agent restates each non-trivial prompt and routes it before acting. Mirrors
+# doctrine.sh: emit hookSpecificOutput.additionalContext via python3, fail-open
+# with exit 0.
+#
+# The ladder ranks, in order: (1) delegate to a specialist that owns the
+# deliverable via the Agent tool; (2) only if none fits, load an admin-usable
+# skill; (3) only if neither fits, author inline — freestyle is the named last
+# resort. The full agent roster and admin-usable skills list are re-emitted every
+# turn by reading two generated files from the account dir; the hook never walks
+# the plugins tree per turn (Task 698).
+#
+# Compliance is behavioural, not deterministic. A hook cannot force a skill call
+# or a dispatch; the directive steers the agent, it does not gate the turn. The
+# raw prompt always still reaches the model (UserPromptSubmit output is ADDED to
+# the prompt, never substituted).
+#
+# Input  (stdin, UserPromptSubmit contract): { "prompt": "...", ... } — drained
+#         and ignored; the directive is standing and prompt-independent.
+# Output (stdout JSON):
+#   { "hookSpecificOutput": { "hookEventName": "UserPromptSubmit",
+#                             "additionalContext": "<directive+ladder>" } }
+#
+# The two lists are read from <cwd>/agents/admin/ — the hook fires with the
+# account dir as cwd (the same resolution admin-authoring-observer.sh relies on).
+# Fail-open is VISIBLE: a missing list logs `[prompt-optimiser] missing=<file>
+# emitting-partial` to stderr and the ladder still injects with whatever resolves.
+# If python3 is unavailable or JSON encoding fails, exit 0 with no stdout. The
+# hook must never block or corrupt a turn.
+
+set -uo pipefail
+
+# 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
+
+# Task 753 — suppress the directive on a native channel turn. A channel inbound
+# arrives as a `<channel source="..." ...>` event; the channel service already
+# reframes that event text into a select-and-dispatch instruction, so injecting
+# the standing routing ladder on top is redundant. The marker is matched on the
+# parsed `.prompt` field (not raw stdin) and only at the start of the prompt, so
+# a normal admin prompt that merely mentions "channel" is never suppressed.
+# Fail-open: if the prompt cannot be parsed, do NOT suppress (inject as usual).
+IS_CHANNEL_TURN=$(printf '%s' "$HOOK_INPUT" | python3 -c '
+import json, sys
+try:
+    p = json.load(sys.stdin).get("prompt", "")
+except Exception:
+    print("no"); sys.exit(0)
+print("yes" if isinstance(p, str) and p.lstrip().startswith("<channel source=") else "no")
+' 2>/dev/null || echo "no")
+if [ "$IS_CHANNEL_TURN" = "yes" ]; then
+  SID_C=$(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)
+  echo "[prompt-optimiser-directive] skipped reason=channel-turn session=${SID_C:-?}" >&2
+  exit 0
+fi
+
+# Read a generated list from the account dir (cwd). On a missing file, emit a
+# visible breadcrumb to stderr and echo a one-line placeholder so the ladder
+# still names the tier.
+ADMIN_DIR="$PWD/agents/admin"
+read_list() {  # $1 = filename under agents/admin/
+  if [ -f "$ADMIN_DIR/$1" ]; then
+    cat "$ADMIN_DIR/$1"
+  else
+    echo "[prompt-optimiser] missing=$1 emitting-partial" >&2
+    echo "($1 unavailable this turn)"
+  fi
+}
+ROSTER=$(read_list AGENTS.md)
+ADMIN_SKILLS=$(read_list ADMIN-SKILLS.md)
+
+# Build the directive from LITERAL (quoted-heredoc) static parts joined with the
+# generated lists via printf. The parts are captured with `read -r -d ''` rather
+# than `$(cat <<'EOF')` because bash 3.2's command-substitution parser miscounts
+# the parentheses inside the ladder prose; `read` has no such limitation. The
+# quoted delimiter keeps backticks and parens literal, and the lists are spliced
+# in as printf data, never evaluated. `read -d ''` returns non-zero at EOF (no
+# NUL terminator) but populates the variable; the `|| true` keeps that benign.
+IFS= read -r -d '' DIRECTIVE_HEAD <<'DIRECTIVE_EOF' || true
+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
+
+IFS= read -r -d '' DIRECTIVE_MID <<'DIRECTIVE_EOF' || true
+2) Only if no specialist owns it, use an admin skill. Load one from the admin-usable list with skill-load and do the work from this seat. Admin-usable skills:
+DIRECTIVE_EOF
+
+IFS= read -r -d '' DIRECTIVE_TAIL <<'DIRECTIVE_EOF' || true
+3) Only if neither a specialist nor an admin skill fits, author it directly. Freestyle inline authoring is the last resort, not a peer of the two routes above.
+DIRECTIVE_EOF
+
+DIRECTIVE=$(printf '%s\n%s\n%s\n%s\n%s' \
+  "$DIRECTIVE_HEAD" "$ROSTER" "$DIRECTIVE_MID" "$ADMIN_SKILLS" "$DIRECTIVE_TAIL")
+
+OUT=$(printf '%s' "$DIRECTIVE" | python3 -c '
+import json, sys
+ctx = sys.stdin.read()
+print(json.dumps({
+    "hookSpecificOutput": {
+        "hookEventName": "UserPromptSubmit",
+        "additionalContext": ctx,
+    }
+}))
+' 2>/dev/null) || exit 0
+
+[ -n "$OUT" ] || exit 0
+printf '%s\n' "$OUT"
+
+# Session id, content hash, timestamp — computed unconditionally (cheap) so the
+# stored file path and the breadcrumb can reference them even when LOG_DIR is
+# absent (file=-). session_id is parsed from the captured stdin; absent -> "?".
+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)
+SID=${SID:-?}
+SHA=$(printf '%s' "$DIRECTIVE" | python3 -c 'import hashlib,sys
+sys.stdout.write(hashlib.sha256(sys.stdin.buffer.read()).hexdigest())' 2>/dev/null || echo "?")
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Task 746: persist the EXACT emitted additionalContext bytes per turn, so the
+# full directive is recoverable from an operator surface (the JSONL attachment
+# row Claude Code keeps is truncated to <=2.6 KB; this file is not). Keyed by
+# session + epoch seconds + pid -> one file per injection. Fail-open: a missing
+# LOG_DIR, an unknown session, an un-creatable dir, or an unwritable file all
+# skip the write and leave DIR_FILE=- ; the turn is never blocked.
+DIR_FILE="-"
+if [ -n "${LOG_DIR:-}" ] && [ -d "$LOG_DIR" ] && [ "$SID" != "?" ]; then
+  STORE="$LOG_DIR/prompt-optimiser-directives/$SID"
+  if mkdir -p "$STORE" 2>/dev/null; then
+    CAND="$STORE/$(date +%s)-$$.txt"
+    if printf '%s' "$DIRECTIVE" > "$CAND" 2>/dev/null; then
+      DIR_FILE="$CAND"
+    fi
+  fi
+fi
+
+# Durable breadcrumb (Task 719 + 746): length + content hash + stored path +
+# session, so "directive fired on this turn" carries enough to recover and
+# verify the exact bytes. The `injected len=` and `session=` substrings are
+# preserved for the existing greps/tests.
+if [ -n "${LOG_DIR:-}" ] && [ -d "$LOG_DIR" ]; then
+  printf '%s [prompt-optimiser-directive] injected len=%s sha256=%s file=%s session=%s\n' \
+    "$TS" "${#DIRECTIVE}" "$SHA" "$DIR_FILE" "$SID" \
+    >> "$LOG_DIR/prompt-optimiser-directive.log" 2>/dev/null || true
+fi
+
+echo "[prompt-optimiser-directive] injected len=${#DIRECTIVE} sha256=$SHA file=$DIR_FILE session=$SID" >&2
+exit 0