@rubytech/create-siteoffice-code 0.1.256

package/payload/platform/plugins/admin/hooks/askuserquestion-investigate-gate.sh

@@ -0,0 +1,257 @@
+#!/usr/bin/env bash
+# AskUserQuestion investigation gate.
+#
+# Blocks `AskUserQuestion` when no read-only investigation tool has fired
+# since the latest real user turn in the session JSONL. The structural fix
+# for the failure class where the agent jumps to a fabricated menu before
+# evidence-gathering — see session c085ec2c-46fb-4b73-8865-68cf85866ea8
+# (2026-05-22) where the agent menu'd "Admin PIN / Cloudflare tunnel / WiFi"
+# in response to "change remote access password", then on correction
+# immediately fired remote-auth-status → ToolSearch → set-password — proving
+# the agent knew the moves; it just skipped them.
+#
+# Prose IDENTITY/SKILL rules are narration, not enforcement
+# (feedback_doctrine_paragraph_is_not_a_gate.md). This hook removes the LLM
+# from the per-decision path.
+#
+# Contract:
+#   Input:  PreToolUse stdin JSON envelope from Claude Code
+#   Output: exit 0 (allow) or exit 2 (block) per hook protocol
+#   Logs:   one stderr line per call, format
+#           [ask-gate] decision=<allow|block> sessionId=<id8> seen=<csv|->
+#                      reason=<allowlist-hit|no-investigation|fail-open-no-transcript|fail-open-parse-error>
+#
+# Fail-open philosophy: any infrastructure error (missing transcript, parse
+# failure, non-AskUserQuestion tool) nudges the agent through, never bricks
+# the UI. Block is reserved for the deterministic case "AskUserQuestion fired
+# this turn with zero investigation evidence in the JSONL".
+
+set -uo pipefail
+
+# ----- Read stdin, identify event ------------------------------------------
+if [ -t 0 ]; then
+  # No envelope — cannot enforce. Fail open per nudge-not-brick rule.
+  echo "[ask-gate] decision=allow sessionId=- seen=- reason=fail-open-no-transcript" >&2
+  exit 0
+fi
+INPUT=$(cat)
+
+HOOK_EVENT=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    print(d.get("hook_event_name", "") or "")
+except Exception:
+    print("")
+' 2>/dev/null)
+
+TOOL_NAME=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    print(d.get("tool_name", "") or "")
+except Exception:
+    print("")
+' 2>/dev/null)
+
+# Only applies to PreToolUse on AskUserQuestion. Anything else: silent exit.
+if [ "$HOOK_EVENT" != "PreToolUse" ] || [ "$TOOL_NAME" != "AskUserQuestion" ]; then
+  exit 0
+fi
+
+SESSION_ID=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    print(d.get("session_id", "") or "")
+except Exception:
+    print("")
+' 2>/dev/null)
+SESSION_ID8="${SESSION_ID:0:8}"
+if [ -z "$SESSION_ID8" ]; then SESSION_ID8="-"; fi
+
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    print(d.get("transcript_path", "") or "")
+except Exception:
+    print("")
+' 2>/dev/null)
+
+# Allow `ASK_GATE_TRANSCRIPT_PATH` env override for tests — never used in
+# production; the SDK always passes transcript_path in the envelope.
+if [ -n "${ASK_GATE_TRANSCRIPT_PATH:-}" ]; then
+  TRANSCRIPT_PATH="$ASK_GATE_TRANSCRIPT_PATH"
+fi
+
+if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  echo "[ask-gate] decision=allow sessionId=${SESSION_ID8} seen=- reason=fail-open-no-transcript" >&2
+  exit 0
+fi
+
+# ----- Walk JSONL --------------------------------------------------------
+# Returns one of three lines on stdout:
+#   ALLOW\t<seen-csv>
+#   BLOCK\t<seen-csv-or-dash>
+#   PARSE_ERROR\t-
+#
+# "Real user turn" = type=user, message.role=user, content is either a
+# string OR a list with at least one non-tool_result block. Tool-result-only
+# user lines are tool replies, not turn starts.
+RESULT=$(TRANSCRIPT_PATH="$TRANSCRIPT_PATH" python3 - <<'PY'
+import os, json, sys
+
+ALLOWLIST = {
+    "ToolSearch", "Grep", "Glob", "Read", "LS", "NotebookRead",
+    "Bash", "WebFetch", "WebSearch",
+    "mcp__admin__skill-find",
+    "mcp__admin__agent-list",
+    "mcp__admin__agent-config-read",
+    "mcp__admin__plugin-read",
+    "mcp__admin__skill-load",
+    "mcp__admin__system-status",
+    "mcp__admin__logs-read",
+    "mcp__admin__remote-auth-status",
+    "mcp__admin__premium-list",
+    "mcp__memory__memory-find-candidates",
+    "mcp__memory__profile-read",
+    "mcp__memory__conversation-list",
+    "mcp__memory__memory-list-attachments",
+    "mcp__memory__memory-read-attachment",
+}
+
+# Pre-compute suffix matchers for namespaced aliases.
+# mcp__admin__skill-find -> suffix "__skill-find"
+SUFFIX_MATCHERS = []
+for entry in ALLOWLIST:
+    if "__" in entry:
+        tool = entry.rsplit("__", 1)[1]
+        if tool:
+            SUFFIX_MATCHERS.append("__" + tool)
+# Deduplicate
+SUFFIX_MATCHERS = sorted(set(SUFFIX_MATCHERS))
+
+def is_allowed(name: str) -> bool:
+    if name in ALLOWLIST:
+        return True
+    for suf in SUFFIX_MATCHERS:
+        if name.endswith(suf):
+            return True
+    return False
+
+def is_real_user(d: dict) -> bool:
+    if d.get("type") != "user":
+        return False
+    msg = d.get("message", {}) or {}
+    if msg.get("role") != "user":
+        return False
+    content = msg.get("content")
+    if isinstance(content, str):
+        return True
+    if isinstance(content, list):
+        for b in content:
+            if isinstance(b, dict) and b.get("type") != "tool_result":
+                return True
+        return False
+    # Missing / null content — treat as real-user start (defensive).
+    return True
+
+def assistant_tool_uses(d: dict):
+    if d.get("type") != "assistant":
+        return []
+    msg = d.get("message", {}) or {}
+    if msg.get("role") != "assistant":
+        return []
+    content = msg.get("content")
+    if not isinstance(content, list):
+        return []
+    names = []
+    for b in content:
+        if isinstance(b, dict) and b.get("type") == "tool_use":
+            n = b.get("name")
+            if isinstance(n, str) and n:
+                names.append(n)
+    return names
+
+path = os.environ["TRANSCRIPT_PATH"]
+records = []
+try:
+    with open(path, "r", encoding="utf-8") as f:
+        for raw in f:
+            raw = raw.strip()
+            if not raw:
+                continue
+            records.append(json.loads(raw))
+except json.JSONDecodeError:
+    print("PARSE_ERROR\t-")
+    sys.exit(0)
+except Exception:
+    # Any non-JSON I/O failure: fail open as no-transcript shape — but the
+    # outer bash already gates file existence, so this is a defence in depth.
+    print("PARSE_ERROR\t-")
+    sys.exit(0)
+
+last_user = -1
+for i in range(len(records) - 1, -1, -1):
+    if is_real_user(records[i]):
+        last_user = i
+        break
+
+seen = []
+if last_user >= 0:
+    for r in records[last_user + 1:]:
+        seen.extend(assistant_tool_uses(r))
+
+# Allow if any seen name matches the allowlist.
+allow = any(is_allowed(n) for n in seen)
+
+# Filter `AskUserQuestion` itself out of the seen-csv when nothing else fired —
+# its presence in JSONL before the gate fires can happen if the SDK records
+# the assistant message before dispatching. It does not count as investigation,
+# but listing only "AskUserQuestion" in the log is misleading. Drop self-name
+# from the displayed CSV (it does not affect the allow/block decision because
+# AskUserQuestion is not in the allowlist).
+display = [n for n in seen if n != "AskUserQuestion"]
+csv = ",".join(display) if display else "-"
+
+print(("ALLOW" if allow else "BLOCK") + "\t" + csv)
+PY
+)
+
+# ----- Parse python result + emit decision ---------------------------------
+REASON=""
+DECISION=""
+SEEN_CSV="-"
+
+case "$RESULT" in
+  ALLOW*)
+    DECISION="allow"
+    REASON="allowlist-hit"
+    SEEN_CSV="${RESULT#ALLOW	}"
+    ;;
+  BLOCK*)
+    DECISION="block"
+    REASON="no-investigation"
+    SEEN_CSV="${RESULT#BLOCK	}"
+    ;;
+  PARSE_ERROR*)
+    DECISION="allow"
+    REASON="fail-open-parse-error"
+    SEEN_CSV="-"
+    ;;
+  *)
+    DECISION="allow"
+    REASON="fail-open-parse-error"
+    SEEN_CSV="-"
+    ;;
+esac
+
+echo "[ask-gate] decision=${DECISION} sessionId=${SESSION_ID8} seen=${SEEN_CSV} reason=${REASON}" >&2
+
+if [ "$DECISION" = "block" ]; then
+  echo "Blocked: AskUserQuestion requires at least one investigation tool (ToolSearch, Grep, Read, *-list, *-status, *-read, skill-find, ...) earlier in this turn. Search the operator's literal phrase first." >&2
+  exit 2
+fi
+
+exit 0

package/payload/platform/plugins/admin/hooks/lib/hook-emit.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# Task 560 — emit subagent hook decisions to a sidecar buffer that the
+# parent-side post-tool-use-agent.sh propagator reads on its next fire.
+#
+# This library is fail-open: every error path is logged to server.log
+# under [hook-propagate-error] and returns success so the hook's primary
+# allow/block contract is never coupled to propagation succeeding.
+
+: "${MAXY_HOOK_BUFFER_DIR:=$HOME/.maxy-code/logs/hook-decisions}"
+: "${MAXY_HOOK_SERVER_LOG:=$HOME/.maxy-code/logs/server.log}"
+: "${MAXY_HOOK_STDERR_CAP:=4096}"
+# Task 563 — mkdir-based mutex serialises emitter append vs drainer rename.
+# 100 attempts × 10ms = ~1s ceiling. Portable across Linux (Pi) and macOS
+# (tests) without flock(1).
+: "${MAXY_HOOK_LOCK_ATTEMPTS:=100}"
+: "${MAXY_HOOK_LOCK_SLEEP:=0.01}"
+# Task 569 — TTL for orphaned lockdirs left behind when a holder dies
+# between `mkdir lock` and `rmdir lock` (SIGKILL, OOM, systemd restart).
+# Default 5s is far longer than the legitimate hold (microseconds for a
+# rename or append) and shorter than operator-noticeable propagation lag.
+: "${MAXY_HOOK_LOCK_TTL_SECONDS:=5}"
+
+# _hook_lockdir_age_seconds <lockdir> — prints integer age in seconds, or
+# -1 if the lockdir cannot be stat'd. Portable across Linux (`stat -c`)
+# and macOS (`stat -f`).
+_hook_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))
+}
+
+# _hook_acquire_lock <lockdir> — returns 0 on success, 1 on timeout.
+# On each mkdir failure, if the lockdir is older than
+# MAXY_HOOK_LOCK_TTL_SECONDS, the orphaned holder is presumed dead: the
+# lockdir is force-removed, a stale-lock-reclaimed observability line is
+# emitted, and one mkdir retry is attempted before resuming the spin.
+_hook_acquire_lock() {
+  local lockdir="$1" i=0 age
+  while ! mkdir "$lockdir" 2>/dev/null; do
+    age=$(_hook_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
+}
+
+# _hook_release_lock <lockdir>
+_hook_release_lock() {
+  rmdir "$1" 2>/dev/null || true
+}
+
+# hook_emit_decision <agentId> <hookName> <toolName> <decision> <reason>
+#                    <stderrPayload> <exitCode> <durationMs>
+hook_emit_decision() {
+  local agentId="$1" hookName="$2" toolName="$3" decision="$4" reason="$5"
+  local stderrPayload="$6" exitCode="$7" durationMs="$8"
+
+  local rec
+  rec=$(MAXY_HOOK_STDERR_CAP="$MAXY_HOOK_STDERR_CAP" python3 - \
+    "$agentId" "$hookName" "$toolName" "$decision" "$reason" \
+    "$stderrPayload" "$exitCode" "$durationMs" <<'PY' 2>/dev/null
+import json, os, sys, datetime
+cap = int(os.environ.get("MAXY_HOOK_STDERR_CAP", "4096"))
+(agentId, hookName, toolName, decision, reason,
+ stderrPayload, exitCode, durationMs) = sys.argv[1:9]
+truncated = False
+if len(stderrPayload) > cap:
+    dropped = len(stderrPayload) - cap
+    stderrPayload = stderrPayload[:cap] + f"…[truncated {dropped} bytes]"
+    truncated = True
+print(json.dumps({
+    "ts": datetime.datetime.utcnow().replace(microsecond=0).isoformat() + "Z",
+    "agentId": agentId,
+    "hookName": hookName,
+    "toolName": toolName,
+    "decision": decision,
+    "reason": reason,
+    "stderr": stderrPayload,
+    "exitCode": int(exitCode) if exitCode.lstrip("-").isdigit() else 0,
+    "durationMs": int(durationMs) if durationMs.lstrip("-").isdigit() else 0,
+    "truncated": truncated,
+}, separators=(",", ":")))
+PY
+  )
+  if [[ -z "$rec" ]]; then
+    mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+    printf '[hook-propagate-error] reason=record-build agentId=%s hook=%s\n' \
+      "$agentId" "$hookName" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null
+    return 0
+  fi
+
+  mkdir -p "$MAXY_HOOK_BUFFER_DIR" 2>/dev/null
+  local buf="$MAXY_HOOK_BUFFER_DIR/$agentId.jsonl"
+  local lock="${buf}.lock"
+  if ! _hook_acquire_lock "$lock"; then
+    mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+    printf '[hook-propagate-error] reason=lock-timeout agentId=%s hook=%s\n' \
+      "$agentId" "$hookName" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null
+    return 0
+  fi
+  if ! printf '%s\n' "$rec" >>"$buf" 2>/dev/null; then
+    _hook_release_lock "$lock"
+    mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+    printf '[hook-propagate-error] reason=buffer-write agentId=%s hook=%s\n' \
+      "$agentId" "$hookName" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null
+    return 0
+  fi
+  _hook_release_lock "$lock"
+
+  local bytesIn="${#stderrPayload}"
+  local bytesOut="${#rec}"
+  local trunc=false
+  [[ "$rec" == *'"truncated":true'* ]] && trunc=true
+  mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+  printf '[hook-propagate] agentId=%s hookName=%s tool=%s decision=%s bytesIn=%s bytesOut=%s truncated=%s\n' \
+    "$agentId" "$hookName" "$toolName" "$decision" "$bytesIn" "$bytesOut" "$trunc" \
+    >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null
+  return 0
+}
+
+# hook_block_with_emit <agentId> <hookName> <toolName> <reason>
+#                      <userMessage> [durationMs]
+# Convenience wrapper for any PreToolUse hook that records a block decision:
+# emits the propagation record, echoes the user-facing block message to stderr,
+# and exits 2.
+hook_block_with_emit() {
+  local agentId="$1" hookName="$2" toolName="$3" reason="$4"
+  local userMessage="$5" durationMs="${6:-0}"
+  hook_emit_decision "$agentId" "$hookName" "$toolName" "block" "$reason" \
+    "$userMessage" 2 "$durationMs"
+  printf '%s\n' "$userMessage" >&2
+  exit 2
+}

package/payload/platform/plugins/admin/hooks/lib/maxy-mcp-plugins.txt

@@ -0,0 +1,16 @@
+admin
+aeo
+browser
+contacts
+email
+graph
+graph-viewer
+memory
+outlook
+replicate
+scheduling
+telegram
+url-get
+whatsapp
+work
+workflows

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/pin-identity-gate.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# Native-CC admin PIN identity gate (Task 619).
+#
+# PreToolUse hook, registered under the universal (no-matcher) entry so it fires
+# for EVERY tool call on a native-CC admin session. It denies all tools until the
+# operator authenticates: the agent must call `admin-identity-authenticate` with a
+# PIN that the loopback validate endpoint matches against users.json. On match the
+# hook records per-session auth state (keyed by the conversation `session_id` it
+# reads from stdin) and lets every subsequent tool through. Enforcement is here —
+# a model that skips the prompt cannot reach any other tool.
+#
+# Scope: only native loopback admin sessions (MAXY_SESSION_ROLE=admin). Specialist
+# subagents dispatched via the Task tool share the parent conversation's
+# session_id, so they pass once the operator session is authenticated.
+#
+# Protocol: exit 0 = allow, exit 2 = block (stderr message shown to the agent),
+# matching the sibling gate hooks. Fail-closed on terminal stdin.
+#
+# Lifecycle (one [admin-identity] line per step, correlated by sessionId):
+#   op=loopback-spawn-received → op=pin-prompted → (op=pin-bound source=pin |
+#   op=pin-miss → op=session-terminated) ; the MCP tool emits op=about-owner-loaded.
+
+set -uo pipefail
+
+if [ -t 0 ]; then
+  echo "Blocked: pin-identity-gate received no stdin (cannot inspect tool call). Failing closed." >&2
+  exit 2
+fi
+INPUT=$(cat)
+
+# Only native loopback admin OPERATOR sessions are in scope:
+#  - MAXY_SESSION_ROLE=admin excludes public/access sessions.
+#  - MAXY_SPECIALIST empty excludes pty-spawned specialist/recorder sessions,
+#    which carry role=admin but are not human operators and never enter a PIN
+#    (mirrors the recursion guard the other admin hooks use). Task-tool
+#    specialist subagents share the operator's session_id + empty MAXY_SPECIALIST,
+#    so they pass via the operator's auth-state file once it is bound.
+[ "${MAXY_SESSION_ROLE:-}" = "admin" ] || exit 0
+[ -z "${MAXY_SPECIALIST:-}" ] || exit 0
+
+# ----- Parse fields from stdin (python3, robust on nested tool_input) -------
+SESSION_ID=$(printf '%s' "$INPUT" | python3 -c 'import json,sys
+try: d=json.load(sys.stdin)
+except Exception: d={}
+print(d.get("session_id","") or "")' 2>/dev/null)
+TOOL_NAME=$(printf '%s' "$INPUT" | python3 -c 'import json,sys
+try: d=json.load(sys.stdin)
+except Exception: d={}
+print(d.get("tool_name","") or "")' 2>/dev/null)
+
+SID8="${SESSION_ID:0:8}"; [ -z "$SID8" ] && SID8='-'
+log() { echo "[admin-identity] $1" >&2; }
+
+# ----- Resolve account/state dir -------------------------------------------
+# The account dir basename IS the ACCOUNT_ID (resolve-account-dir.sh), and the
+# rc child env carries ACCOUNT_ID, so resolve deterministically rather than
+# `find | head -1` — which does not skip dotfiles and could pick the sibling
+# `data/accounts/.trash/`, diverging from the manager's `spawnCwd` (= the
+# account dir) and stranding state the standing audit can never reconcile.
+HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+PLATFORM_ROOT_RESOLVED="${HOOK_DIR}/../../.."
+ACCOUNTS_DIR="${PLATFORM_ROOT_RESOLVED}/../data/accounts"
+ACCOUNT_DIR=""
+if [ -n "${ACCOUNT_ID:-}" ]; then
+  ACCOUNT_DIR="${ACCOUNTS_DIR}/${ACCOUNT_ID}"
+elif [ -d "$ACCOUNTS_DIR" ]; then
+  # Defensive fallback only when ACCOUNT_ID is unset — exclude dot-entries.
+  ACCOUNT_DIR=$(find "$ACCOUNTS_DIR" -mindepth 1 -maxdepth 1 -type d ! -name '.*' 2>/dev/null | head -1)
+fi
+STATE_DIR="${MAXY_IDENTITY_GATE_STATE_DIR:-${ACCOUNT_DIR}/state/admin-identity}"
+STATE_FILE="${STATE_DIR}/${SESSION_ID}.json"
+
+AUTH_TOOL='mcp__plugin_admin_admin__admin-identity-authenticate'
+VALIDATE_URL="${MAXY_IDENTITY_VALIDATE_URL:-http://127.0.0.1:${MAXY_UI_INTERNAL_PORT:-0}/api/admin/identity/validate}"
+
+# Already authenticated for this conversation → pass everything through.
+if [ -n "$SESSION_ID" ] && [ -f "$STATE_FILE" ]; then
+  exit 0
+fi
+
+log "op=loopback-spawn-received sessionId=${SID8}"
+
+# ----- The authenticate tool: validate, bind on match, terminate on miss ----
+if [ "$TOOL_NAME" = "$AUTH_TOOL" ]; then
+  PIN=$(printf '%s' "$INPUT" | python3 -c 'import json,sys
+try: d=json.load(sys.stdin)
+except Exception: d={}
+ti=d.get("tool_input") or {}
+print(ti.get("pin","") or "")' 2>/dev/null)
+
+  REQ=$(python3 -c 'import json,sys
+print(json.dumps({"pin": sys.argv[1], "sessionId": sys.argv[2]}))' "$PIN" "$SESSION_ID" 2>/dev/null)
+  RESP=$(printf '%s' "$REQ" | curl -s --max-time 5 -X POST -H 'content-type: application/json' -d @- "$VALIDATE_URL" 2>/dev/null)
+  KIND=$(printf '%s' "$RESP" | python3 -c 'import json,sys
+try: print((json.load(sys.stdin) or {}).get("kind","") or "")
+except Exception: print("")' 2>/dev/null)
+
+  case "$KIND" in
+    match)
+      USERID=$(printf '%s' "$RESP" | python3 -c 'import json,sys
+print(json.load(sys.stdin).get("userId","") or "")' 2>/dev/null)
+      mkdir -p "$STATE_DIR" 2>/dev/null
+      printf '{"userId":%s,"ts":"%s"}' \
+        "$(python3 -c 'import json,sys;print(json.dumps(sys.argv[1]))' "$USERID")" \
+        "$(date -u +%FT%TZ)" > "$STATE_FILE" 2>/dev/null
+      log "op=pin-bound sessionId=${SID8} userId=${USERID:0:8} source=pin authSurface=loopback"
+      exit 0
+      ;;
+    miss)
+      log "op=pin-miss sessionId=${SID8} reason=no-matching-user"
+      log "op=session-terminated sessionId=${SID8} reason=pin-auth-failed"
+      echo "PIN did not match. This session is being terminated. Start a new session and enter a valid PIN." >&2
+      exit 2
+      ;;
+    unavailable)
+      log "op=pin-unavailable sessionId=${SID8} reason=users-json-empty"
+      echo "No admin PIN is configured for this install. Complete onboarding before using the admin agent." >&2
+      exit 2
+      ;;
+    corrupt)
+      log "op=pin-error sessionId=${SID8} reason=users-json-corrupt"
+      echo "Admin user configuration is corrupt. Re-run the seed script before authenticating." >&2
+      exit 2
+      ;;
+    *)
+      log "op=pin-error sessionId=${SID8} reason=validate-unreachable"
+      echo "Identity validation is unavailable; cannot proceed without authentication." >&2
+      exit 2
+      ;;
+  esac
+fi
+
+# ----- Unauthenticated and not the auth tool → block -----------------------
+log "op=pin-prompted sessionId=${SID8}"
+echo "Authenticate first: call admin-identity-authenticate with the operator's PIN. No other tool is reachable until a matching PIN is bound for this session." >&2
+exit 2