@rubytech/create-maxy-code 0.1.214 → 0.1.216

package/package.json

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

package/payload/platform/plugins/admin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "admin",
-  "description": "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver, single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), publish-site (move an extracted static-site tree under <accountDir>/sites/<slug>/, emit one canonical path slug, and refresh llms.txt at the site root — typed refusal taxonomy replaces the prior skill-prose contract), brand-settings, account-manage, account-update, admin-add, admin-remove, admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name, the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), session-reset, session-resume, wifi, action-approval tools (action-pending, action-approve, action-reject, action-edit), and session-retrospective-mark-complete (the deterministic sentinel the session-end Stop hook reads via JSONL grep to release the retrospective gate; admin calls it once per session after running the three-pass retrospective) for managing the Maxy platform.",
+  "description": "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver, single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), publish-site (move an extracted static-site tree under <accountDir>/sites/<slug>/, emit one canonical path slug, and refresh llms.txt at the site root — typed refusal taxonomy replaces the prior skill-prose contract), brand-settings, account-manage, capabilities-here (deterministic install-introspection — returns enabledPlugins, tier, models, installed platform + premium specialists, registered Claude Code agent types, and the brand block as a single JSON object; the canonical tool for grounding any claim about what is enabled on the current account), account-update, admin-add, admin-remove, admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name, the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), session-reset, session-resume, wifi, action-approval tools (action-pending, action-approve, action-reject, action-edit), and session-retrospective-mark-complete (the deterministic sentinel the session-end Stop hook reads via JSONL grep to release the retrospective gate; admin calls it once per session after running the three-pass retrospective) for managing the Maxy platform.",
   "version": "0.1.0",
   "author": {
     "name": "Rubytech LLC"

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

@@ -1,7 +1,7 @@
 ---
 name: admin
 surface: platform
-description: "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver, single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), publish-site (move an extracted static-site tree under <accountDir>/sites/<slug>/, emit one canonical path slug, and refresh llms.txt at the site root — typed refusal taxonomy replaces the prior skill-prose contract), brand-settings, account-manage, account-update, admin-add, admin-remove, admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name, the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), session-reset, session-resume, wifi, action-approval tools (action-pending, action-approve, action-reject, action-edit), and session-retrospective-mark-complete (the deterministic sentinel the session-end Stop hook reads via JSONL grep to release the retrospective gate; admin calls it once per session after running the three-pass retrospective) for managing the Maxy platform."
+description: "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver, single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), publish-site (move an extracted static-site tree under <accountDir>/sites/<slug>/, emit one canonical path slug, and refresh llms.txt at the site root — typed refusal taxonomy replaces the prior skill-prose contract), brand-settings, account-manage, capabilities-here (deterministic install-introspection — returns enabledPlugins, tier, models, installed platform + premium specialists, registered Claude Code agent types, and the brand block as a single JSON object; the canonical tool for grounding any claim about what is enabled on the current account), account-update, admin-add, admin-remove, admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name, the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), session-reset, session-resume, wifi, action-approval tools (action-pending, action-approve, action-reject, action-edit), and session-retrospective-mark-complete (the deterministic sentinel the session-end Stop hook reads via JSONL grep to release the retrospective gate; admin calls it once per session after running the three-pass retrospective) for managing the Maxy platform."
 tools:
   - name: system-status
     publicAllowlist: false
@@ -18,6 +18,9 @@ tools:
   - name: account-manage
     publicAllowlist: false
     adminAllowlist: false
+  - name: capabilities-here
+    publicAllowlist: false
+    adminAllowlist: false
   - name: account-update
     publicAllowlist: false
     adminAllowlist: false

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

@@ -72,6 +72,102 @@ echo "$CENSUS_LOG" | grep -qE 'attachmentsEmitted=2' \
   && pass "census M equals N when stdout open" \
   || fail "census M wrong: $CENSUS_LOG"
 
-rm -rf "$TMP"
+# Task 563 — concurrency hardening.
+
+# Concurrent emitter + drainer on the same buffer must not drop records.
+# Spawn an emitter that writes 50 records in a tight loop while two
+# drainer fires race against it. Union of attachments must equal 50.
+LIB="$(cd "$(dirname "$0")/.." && pwd)/lib/hook-emit.sh"
+[[ -f "$LIB" ]] || { fail "lib missing"; }
+CONCUR_TMP=$(mktemp -d)
+export MAXY_HOOK_BUFFER_DIR="$CONCUR_TMP/buffers"
+export MAXY_HOOK_SERVER_LOG="$CONCUR_TMP/server.log"
+mkdir -p "$MAXY_HOOK_BUFFER_DIR"
+PARENT_C="parent-CONC"
+SUB_C="sub-CONC"
+INPUT_C=$(python3 -c '
+import json, sys
+print(json.dumps({"hook_event_name":"PostToolUse","tool_name":"Agent",
+  "session_id":sys.argv[1]}, separators=(",",":")))
+' "$PARENT_C")
+
+# Emitter: 50 records as fast as possible.
+EMIT_OUT="$CONCUR_TMP/emit.log"
+(
+  # shellcheck disable=SC1090
+  source "$LIB"
+  for i in $(seq 1 50); do
+    hook_emit_decision "$SUB_C" "h" "Bash" "block" "r$i" "x" 2 1
+  done
+  echo "done" >"$EMIT_OUT"
+) &
+EMIT_PID=$!
+
+# Two drainer fires racing the emitter.
+DRAIN1="$CONCUR_TMP/drain1.out"
+DRAIN2="$CONCUR_TMP/drain2.out"
+(printf '%s' "$INPUT_C" | bash "$HOOK" >"$DRAIN1" 2>/dev/null) &
+D1=$!
+(printf '%s' "$INPUT_C" | bash "$HOOK" >"$DRAIN2" 2>/dev/null) &
+D2=$!
+wait "$EMIT_PID" "$D1" "$D2"
+
+# Drain any leftovers after emitter+drainers settled.
+DRAIN3="$CONCUR_TMP/drain3.out"
+printf '%s' "$INPUT_C" | bash "$HOOK" >"$DRAIN3" 2>/dev/null
+# A second sweep catches buffer files created after drainer 3 started.
+DRAIN4="$CONCUR_TMP/drain4.out"
+printf '%s' "$INPUT_C" | bash "$HOOK" >"$DRAIN4" 2>/dev/null
+
+TOTAL_ATTACHED=$(cat "$DRAIN1" "$DRAIN2" "$DRAIN3" "$DRAIN4" | grep -c '^\[hook-propagate\] {' || true)
+UNIQUE_R=$(cat "$DRAIN1" "$DRAIN2" "$DRAIN3" "$DRAIN4" | grep '^\[hook-propagate\] {' | \
+  python3 -c 'import json,sys
+seen=set()
+for line in sys.stdin:
+    rec=line.split(" ",1)[1]
+    d=json.loads(rec)
+    seen.add(d["reason"])
+print(len(seen))')
+[[ "$TOTAL_ATTACHED" -eq 50 ]] && pass "concurrent: 50 records attached, no duplicates" \
+  || fail "concurrent: expected 50 attached, got $TOTAL_ATTACHED"
+[[ "$UNIQUE_R" -eq 50 ]] && pass "concurrent: 50 unique records, no drops" \
+  || fail "concurrent: expected 50 unique reasons, got $UNIQUE_R"
+
+# No cursor file should exist (cursor mechanism removed).
+[[ -z "$(ls "$MAXY_HOOK_BUFFER_DIR"/.*.cursor 2>/dev/null)" ]] \
+  && pass "cursor mechanism removed (no .cursor files)" \
+  || fail "cursor file unexpectedly present: $(ls "$MAXY_HOOK_BUFFER_DIR"/.*.cursor 2>/dev/null)"
+
+rm -rf "$CONCUR_TMP"
+
+# Unknown-parent fallback emits observability line and does not corrupt
+# state across concurrent fires.
+UNK_TMP=$(mktemp -d)
+export MAXY_HOOK_BUFFER_DIR="$UNK_TMP/buffers"
+export MAXY_HOOK_SERVER_LOG="$UNK_TMP/server.log"
+mkdir -p "$MAXY_HOOK_BUFFER_DIR"
+# Stdin with no session_id at all.
+BAD_INPUT='{"hook_event_name":"PostToolUse","tool_name":"Agent"}'
+UNK1="$UNK_TMP/unk1.out"
+UNK2="$UNK_TMP/unk2.out"
+(printf '%s' "$BAD_INPUT" | bash "$HOOK" >"$UNK1" 2>/dev/null) &
+U1=$!
+(printf '%s' "$BAD_INPUT" | bash "$HOOK" >"$UNK2" 2>/dev/null) &
+U2=$!
+wait "$U1" "$U2"
+
+grep -q 'parentSession=unknown reason=session-id-missing' "$UNK1" "$UNK2" \
+  && pass "unknown parent emits observability line" \
+  || fail "unknown parent missing observability line: $(cat "$UNK1" "$UNK2")"
+grep -q 'parentSession=unknown reason=session-id-missing' "$MAXY_HOOK_SERVER_LOG" \
+  && pass "unknown parent line logged to server.log" \
+  || fail "server.log missing unknown-parent line"
+# No .unknown.cursor file — cursor mechanism is gone.
+[[ ! -e "$MAXY_HOOK_BUFFER_DIR/.unknown.cursor" ]] \
+  && pass "no shared .unknown.cursor file" \
+  || fail ".unknown.cursor unexpectedly present"
+
+rm -rf "$UNK_TMP"
+
 echo "----"; echo "$PASS pass, $FAIL fail"
 [[ "$FAIL" -eq 0 ]]

package/payload/platform/plugins/admin/hooks/__tests__/pre-tool-use-admin-tool-gate.test.sh

@@ -1,14 +1,17 @@
 #!/usr/bin/env bash
 # Task 529 — admin-tool-gate enforces orchestration-only at the PreToolUse
 # hook. Admin-direct invocations of Write/Edit/MultiEdit/Bash/WebFetch/
-# WebSearch are refused with the dispatch hint; in-window Task subagents
-# pass through.
+# WebSearch are refused with the dispatch hint; subagents pass through.
 #
-# Task 559 — the discriminator is `parent_tool_use_id` from the Claude
-# Code hook input. Non-empty → subagent (allow). Absent/empty → admin
-# direct (block). The earlier `transcript_path` glob was broken in
-# Claude Code 2.1.x because subagent hooks receive the parent session's
-# transcript_path, never one under `*/subagents/agent-*.jsonl`.
+# Task 559 — discriminator is `parent_tool_use_id` from the Claude Code
+# hook input. Non-empty → in-window Task subagent (allow).
+#
+# Task 566 — discriminator extended to `$MAXY_SPECIALIST` for maxy MCP
+# `Agent`-spawned specialists (separate top-level `claude rc` processes
+# with no `parent_tool_use_id` but `MAXY_SPECIALIST=<name>` on env, set
+# by pty-spawner.ts:1601). Calls with neither marker AND no
+# `MAXY_SESSION_ROLE=admin` fail closed with `reason=missing-marker` so a
+# future spawn shape cannot silently regress.
 
 set -u
 
@@ -35,8 +38,15 @@ fail() { FAIL=$((FAIL+1)); echo "FAIL: $1" >&2; }
 SESSION_TRANSCRIPT="/tmp/sess/44283ae1-2b82-4bd7-b8af-99a11141ed4b.jsonl"
 SUBAGENT_PARENT_ID="toolu_01QFC4W32wFUyHy6WJMNjHf6"
 
+# run <tool> <parent_id> <expected_rc> <expected_pattern> <label>
+# Env knobs (default mirror production admin spawn):
+#   MAXY_SESSION_ROLE_OVERRIDE — defaults to "admin"; set empty to drop the role
+#   MAXY_SPECIALIST_OVERRIDE   — defaults to empty; set to a name to simulate
+#                                an MCP-Agent-spawned specialist
 run() {
   local tool="$1" parent_id="$2" expected_rc="$3" expected_pattern="$4" label="$5"
+  local role="${MAXY_SESSION_ROLE_OVERRIDE-admin}"
+  local specialist="${MAXY_SPECIALIST_OVERRIDE-}"
   local input_json
   input_json=$(python3 -c '
 import json, sys
@@ -53,7 +63,10 @@ print(json.dumps(payload, separators=(",", ":")))
 ' "$tool" "$SESSION_TRANSCRIPT" "$parent_id")
   local stdout_file; stdout_file=$(mktemp); TMPFILES+=("$stdout_file")
   local stderr_file; stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
-  printf '%s' "$input_json" | bash "$HOOK" admin >"$stdout_file" 2>"$stderr_file"
+  printf '%s' "$input_json" | \
+    env -u MAXY_SESSION_ROLE -u MAXY_SPECIALIST \
+      MAXY_SESSION_ROLE="$role" MAXY_SPECIALIST="$specialist" \
+      bash "$HOOK" admin >"$stdout_file" 2>"$stderr_file"
   local rc=$?
   if [[ "$rc" -ne "$expected_rc" ]]; then
     fail "$label: expected exit $expected_rc, got $rc. Stderr: $(cat "$stderr_file")"
@@ -66,8 +79,8 @@ print(json.dumps(payload, separators=(",", ":")))
   pass "$label"
 }
 
-# ── Admin-direct refusals (no parent_tool_use_id) ───────────────────────
-run Write     "" 2 '\[admin-tool-gate\] role=admin parent_tool_use_id=- specialist=- tool=Write decision=block.*owner=content-producer' \
+# ── Admin-direct refusals (no parent_tool_use_id, no MAXY_SPECIALIST, role=admin) ───
+run Write     "" 2 '\[admin-tool-gate\] role=admin parent_tool_use_id=- specialist=- session_role=admin tool=Write decision=block.*owner=content-producer' \
   "Test 1: admin-direct Write rejected with content-producer dispatch hint"
 run Edit      "" 2 '\[admin-tool-gate\] role=admin .*tool=Edit decision=block.*owner=content-producer' \
   "Test 2: admin-direct Edit rejected"
@@ -97,7 +110,7 @@ run Read      "" 0 '' \
   "Test 12: admin-direct Read passes (Read is admin-keep-list)"
 
 # ── Task 560: admin-direct block emits propagation record ──────────────
-# Uses the Task 559 classifier (no parent_tool_use_id → admin-direct).
+# Admin-direct path: MAXY_SESSION_ROLE=admin, no MAXY_SPECIALIST, no parent.
 PROP_TMPDIR=$(mktemp -d); TMPFILES+=("$PROP_TMPDIR")
 export MAXY_HOOK_BUFFER_DIR="$PROP_TMPDIR/buffers"
 export MAXY_HOOK_SERVER_LOG="$PROP_TMPDIR/server.log"
@@ -108,7 +121,9 @@ print(json.dumps({"hook_event_name":"PreToolUse","tool_name":"Bash",
   "tool_input":{"command":"ls"},"transcript_path":sys.argv[1],
   "session_id":sys.argv[2]}, separators=(",",":")))
 ' "$SESSION_TRANSCRIPT" "$SESSION")
-printf '%s' "$PROP_INPUT" | bash "$HOOK" admin >/dev/null 2>/dev/null
+printf '%s' "$PROP_INPUT" | \
+  env -u MAXY_SPECIALIST MAXY_SESSION_ROLE=admin \
+    bash "$HOOK" admin >/dev/null 2>/dev/null
 BUF="$MAXY_HOOK_BUFFER_DIR/$SESSION.jsonl"
 if [[ -f "$BUF" ]] && grep -q '"hookName":"admin-tool-gate"' "$BUF" \
    && grep -q '"decision":"block"' "$BUF" \
@@ -119,6 +134,32 @@ else
 fi
 unset MAXY_HOOK_BUFFER_DIR MAXY_HOOK_SERVER_LOG
 
+# ── Task 566: maxy-MCP-Agent-spawned specialist passthrough ────────────
+# MCP-Agent specialists are separate top-level claude rc processes with no
+# parent_tool_use_id; pty-spawner stamps MAXY_SPECIALIST=<name> on the env.
+MAXY_SPECIALIST_OVERRIDE=content-producer \
+run Edit "" 0 '\[admin-tool-gate\] role=subagent .*specialist=content-producer .*tool=Edit decision=allow source=mcp-specialist' \
+  "Test 14: mcp-specialist Edit passes through (Task 566)"
+
+MAXY_SPECIALIST_OVERRIDE=coding-assistant \
+run Bash "" 0 '\[admin-tool-gate\] role=subagent .*specialist=coding-assistant .*tool=Bash decision=allow source=mcp-specialist' \
+  "Test 15: mcp-specialist Bash passes through (Task 559 regression class)"
+
+MAXY_SPECIALIST_OVERRIDE=research-assistant \
+run WebFetch "" 0 '\[admin-tool-gate\] role=subagent .*specialist=research-assistant .*tool=WebFetch decision=allow source=mcp-specialist' \
+  "Test 16: mcp-specialist WebFetch passes through"
+
+# ── Task 566: missing-marker fail-closed ───────────────────────────────
+# No parent_tool_use_id, no MAXY_SPECIALIST, MAXY_SESSION_ROLE not 'admin'.
+MAXY_SESSION_ROLE_OVERRIDE="" MAXY_SPECIALIST_OVERRIDE="" \
+run Edit "" 2 '\[admin-tool-gate\] role=unknown .*tool=Edit decision=block reason=missing-marker' \
+  "Test 17: missing-marker fail-closed (no positive role marker)"
+
+# ── Task 566: combined parent_tool_use_id + MAXY_SPECIALIST is also subagent ──
+MAXY_SPECIALIST_OVERRIDE=database-operator \
+run Bash "$SUBAGENT_PARENT_ID" 0 '\[admin-tool-gate\] role=subagent .*specialist=database-operator .*tool=Bash decision=allow source=task-subagent\+mcp-specialist' \
+  "Test 18: combined parent + specialist resolves as task-subagent+mcp-specialist"
+
 echo
 echo "──────── pre-tool-use admin-tool-gate test summary ────────"
 echo "PASS: $PASS"

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

@@ -9,6 +9,27 @@
 : "${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}"
+
+# _hook_acquire_lock <lockdir> — returns 0 on success, 1 on timeout.
+_hook_acquire_lock() {
+  local lockdir="$1" i=0
+  while ! mkdir "$lockdir" 2>/dev/null; do
+    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>
@@ -52,12 +73,21 @@ PY
 
   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}"

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

@@ -1,15 +1,33 @@
 #!/usr/bin/env bash
 # Task 560 — PostToolUse hook scoped to tool_name=Agent in the admin role.
-# Drains any subagent hook-decision buffers modified since this parent's
-# previous fire, 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.
+# 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}"
 
 if [ -t 0 ]; then
   # No stdin — no correlation possible. Fail-open.
@@ -19,61 +37,95 @@ INPUT=$(cat)
 PARENT_SESSION=$(printf '%s' "$INPUT" | python3 -c '
 import sys, json
 try:
-    print(json.load(sys.stdin).get("session_id", "") or "unknown")
+    sid = json.load(sys.stdin).get("session_id") or ""
+    print(sid if sid else "unknown")
 except Exception:
     print("unknown")
 ' 2>/dev/null || echo "unknown")
 
-CURSOR_FILE="$MAXY_HOOK_BUFFER_DIR/.${PARENT_SESSION}.cursor"
-mkdir -p "$MAXY_HOOK_BUFFER_DIR/consumed" 2>/dev/null
-
-PREV_CURSOR=0
-if [[ -f "$CURSOR_FILE" ]]; then
-  PREV_CURSOR=$(cat "$CURSOR_FILE" 2>/dev/null || echo 0)
-  [[ "$PREV_CURSOR" =~ ^[0-9]+$ ]] || PREV_CURSOR=0
+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
-NOW_EPOCH=$(date +%s)
 
+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
+
+_drain_acquire_lock() {
+  local lockdir="$1" i=0
+  while ! mkdir "$lockdir" 2>/dev/null; do
+    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
-  MTIME=$(stat -f %m "$buf" 2>/dev/null || stat -c %Y "$buf" 2>/dev/null || echo 0)
-  if [[ "$MTIME" -le "$PREV_CURSOR" ]]; then
+  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
-  # Ground-truth observed count: non-empty lines in the buffer file. The
-  # printf-success M_EMITTED is incremented independently below, so a
+  # 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 . "$buf" 2>/dev/null || echo 0)
+  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 <"$buf"
-  TARGET="$MAXY_HOOK_BUFFER_DIR/consumed/$(basename "$buf" .jsonl)-${NOW_EPOCH}.jsonl"
-  if ! mv "$buf" "$TARGET" 2>/dev/null; then
+  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 "$buf")" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null || true
+      "$PARENT_SESSION" "$(basename "$CLAIMED")" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null || true
   fi
 done
 shopt -u nullglob
 
-if ! printf '%s' "$NOW_EPOCH" >"$CURSOR_FILE" 2>/dev/null; then
-  mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
-  printf '[hook-propagate-error] reason=cursor-write parentSession=%s cursor=%s\n' \
-    "$PARENT_SESSION" "$CURSOR_FILE" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null || true
-fi
-
 printf '[hook-propagate-census] parentSession=%s subagentHooksObserved=%d attachmentsEmitted=%d\n' \
   "$PARENT_SESSION" "$N_OBSERVED" "$N_EMITTED"
 

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

@@ -43,24 +43,25 @@ except Exception:
 # ---------------------------------------------------------------------------
 if [ "$AGENT_TYPE" = "admin" ]; then
 
-  # ── Orchestration-only authoring + research block (Task 529, 559) ────────
+  # ── Orchestration-only authoring + research block (Task 529, 559, 566) ───
   # The admin seat is orchestration + clarification + delivery only.
   # Write/Edit/MultiEdit/Bash/WebFetch/WebSearch are specialist-owned —
   # content-producer for authoring, research-assistant for research, the
   # shell tools for whichever specialist owns the workflow that needs them.
   # In-window Task subagents must keep these tools (Task 222 regression
-  # class).
+  # class). Maxy MCP `Agent`-spawned specialists are separate top-level
+  # `claude rc` processes — they have no `parent_tool_use_id` but pty-spawner
+  # stamps `MAXY_SPECIALIST=<name>` on the child env (pty-spawner.ts:1601).
   #
-  # Discriminator (Task 559): Claude Code passes `parent_tool_use_id` in
-  # the hook input JSON when the call originates from a subagent (the id
-  # of the parent's Task tool_use). Admin-direct calls have it absent or
-  # empty. Earlier versions used the `transcript_path` glob, but Claude
-  # Code 2.1.x passes the parent session's transcript_path to subagent
-  # hooks, so the glob never matched and every specialist subagent Bash
-  # was blocked with the admin orchestration-only wording.
+  # Discriminator (union of positive markers, never path-shape inference):
+  #   parent_tool_use_id non-empty  → in-window Task subagent (allow)
+  #   $MAXY_SPECIALIST non-empty    → maxy MCP Agent specialist (allow)
+  #   $MAXY_SESSION_ROLE = admin    → admin-direct (block, orchestration-only)
+  #   none of the above             → fail closed (missing-marker)
   #
-  # Admin direct (no parent_tool_use_id) → exit 2 with dispatch hint.
-  # Subagent (parent_tool_use_id non-empty) → exit 0 (passthrough).
+  # Adding a future spawn shape that lands neither marker surfaces as a loud
+  # `reason=missing-marker` block, not a silent passthrough or a silent
+  # admin-direct block on legitimate specialist work.
   case "$TOOL_NAME" in
     Write|Edit|MultiEdit|Bash|WebFetch|WebSearch)
       PARENT_TOOL_USE_ID=$(echo "$INPUT" | python3 -c '
@@ -72,11 +73,18 @@ except Exception:
     print("")
 ' 2>/dev/null)
       SPECIALIST="${MAXY_SPECIALIST:-}"
-      if [ -n "$PARENT_TOOL_USE_ID" ]; then
-        # In-window subagent — passthrough. Tool name resolves on the
-        # subagent's own frontmatter `tools:` allowlist downstream.
-        echo "[admin-tool-gate] role=subagent parent_tool_use_id=${PARENT_TOOL_USE_ID} specialist=${SPECIALIST:--} tool=${TOOL_NAME} decision=allow source=hook-passthrough" >&2
-      else
+      SESSION_ROLE="${MAXY_SESSION_ROLE:-}"
+      if [ -n "$PARENT_TOOL_USE_ID" ] || [ -n "$SPECIALIST" ]; then
+        # Subagent — passthrough. Tool name resolves on the subagent's
+        # own frontmatter `tools:` allowlist downstream.
+        SOURCE="task-subagent"
+        if [ -n "$SPECIALIST" ] && [ -n "$PARENT_TOOL_USE_ID" ]; then
+          SOURCE="task-subagent+mcp-specialist"
+        elif [ -n "$SPECIALIST" ]; then
+          SOURCE="mcp-specialist"
+        fi
+        echo "[admin-tool-gate] role=subagent parent_tool_use_id=${PARENT_TOOL_USE_ID:--} specialist=${SPECIALIST:--} session_role=${SESSION_ROLE:--} tool=${TOOL_NAME} decision=allow source=${SOURCE}" >&2
+      elif [ "$SESSION_ROLE" = "admin" ]; then
         # Admin direct invocation — refuse with dispatch hint.
         case "$TOOL_NAME" in
           Write|Edit|MultiEdit)
@@ -89,11 +97,20 @@ except Exception:
             OWNER="research-assistant"
             ;;
         esac
-        echo "[admin-tool-gate] role=admin parent_tool_use_id=- specialist=${SPECIALIST:--} tool=${TOOL_NAME} decision=block reason=orchestration-only owner=${OWNER}" >&2
+        echo "[admin-tool-gate] role=admin parent_tool_use_id=- specialist=- session_role=admin tool=${TOOL_NAME} decision=block reason=orchestration-only owner=${OWNER}" >&2
         hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "${TOOL_NAME}" \
           "orchestration-only" \
           "Blocked: \`${TOOL_NAME}\` is not callable from the admin seat. The admin seat is orchestration + clarification + delivery only — authoring, shell work, and web research are owned by specialists.
 Dispatch the work to ${OWNER} via the Agent tool."
+      else
+        # No positive marker — fail closed. A new spawn shape that lands
+        # neither parent_tool_use_id nor MAXY_SPECIALIST and is not the
+        # admin seat should surface visibly, not silently pass or silently
+        # block under the wrong reason.
+        echo "[admin-tool-gate] role=unknown parent_tool_use_id=- specialist=- session_role=${SESSION_ROLE:--} tool=${TOOL_NAME} decision=block reason=missing-marker" >&2
+        hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "${TOOL_NAME}" \
+          "missing-marker" \
+          "Blocked: \`${TOOL_NAME}\` call carries no positive role marker (no parent_tool_use_id, no MAXY_SPECIALIST, MAXY_SESSION_ROLE is not 'admin'). Failing closed so a new spawn shape cannot silently bypass orchestration gating."
       fi
       ;;
   esac

package/payload/platform/plugins/admin/mcp/dist/__tests__/capabilities-here.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=capabilities-here.test.d.ts.map

package/payload/platform/plugins/admin/mcp/dist/__tests__/capabilities-here.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities-here.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/capabilities-here.test.ts"],"names":[],"mappings":""}