@rubytech/create-maxy-code 0.1.212 → 0.1.216

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.212",
+  "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
@@ -141,6 +144,7 @@ Tools are available via the `admin` MCP server.
 - `hooks/askuserquestion-investigate-gate.sh` — PreToolUse matcher=`AskUserQuestion`. Blocks the question (exit 2) 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 fabricates a menu before evidence-gathering (session `c085ec2c-46fb-4b73-8865-68cf85866ea8` 2026-05-22 — "change remote access password" → invented options "Admin PIN / Cloudflare tunnel / WiFi password" with zero prior tool_use; post-correction the agent immediately fired `remote-auth-status` → `ToolSearch` → `remote-auth-set-password`, proving it knew the moves). **Allowlist** (exact, with trailing `__<tool>` suffix-match for namespaced `mcp__plugin_<plugin>_<server>__<tool>` aliases): `ToolSearch`, `Grep`, `Glob`, `Read`, `LS`, `NotebookRead`, `Bash`, `WebFetch`, `WebSearch`, plus the read-only admin / memory MCP tools (`*-status`, `*-list`, `*-read`, `skill-find`, `memory-find-candidates`, `profile-read`, `conversation-list`, `memory-list-attachments`, `memory-read-attachment`). **Block message:** `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.` **Log line** (stderr, one per call): `[ask-gate] decision=<allow|block> sessionId=<id8> seen=<csv|-> reason=<allowlist-hit|no-investigation|fail-open-no-transcript|fail-open-parse-error>`. **Fail-open** on missing transcript or parse error — nudges, never bricks the UI.
 - `hooks/session-end-retrospective.sh` — **Stop hook.** Fires on every assistant end_turn but exits 0 with `trigger-skipped reason=<role-not-admin|is-specialist|empty-stdin|missing-transcript|no-intent-match>` on every path EXCEPT when the operator's latest real-user message carries an end-intent token (`/end`, `/archive`, `end session`, `archive this session`, case-insensitive, must match the whole message or a standalone line — not embedded in prose). On that path the hook blocks (exit 2 + structured retrospective instruction on stderr per Stop-hook contract) and emits `[session-retrospective] gate-blocked sessionId=<id> reason=sentinel-absent` until the admin agent calls the `session-retrospective-mark-complete` MCP sentinel tool. Completion is recognised by greping the operator's own JSONL (`transcript_path` on the Stop envelope) for a `tool_use` block whose `name` equals that exact string — never by parsing prose ([[feedback_no_stdout_parsing_for_control_flow]], [[feedback_doctrine_paragraph_is_not_a_gate]]). The sentinel-grep doubles as the re-entry guard: every Stop after the sentinel call sees it and exits 0 with `gate-released sessionId=<id>`. Recursion guard: any session whose `MAXY_SPECIALIST` env is set (specialist subagent dispatched via Task tool) skips the gate. The Sidebar archive button POSTs `/:sessionId/archive` directly to the manager which kills the PTY — no Stop fires after that, so clicking archive is the operator's current escape hatch (opt-out remains deferred per the task spec). All emits go through `POST /api/admin/log-ingest`; the only stderr writer is the gate-blocked path (the instruction block the agent reads). The retrospective itself runs as one or more additional turns inside the operator's existing admin session — Task-tool delegation to `database-operator` is the existing IDENTITY.md "Recording" route, not a parallel admin session ([[feedback_deterministic_means_remove_llm]]).
 - `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 `pre-tool-use.sh` and writes one record per 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/turn-completed-graph-write.sh` — **Dormant since Task 214** — the Stop-hook registration is no longer written to account settings.json; admin delegates graph writes to `database-operator` via the Task tool. The script, envelope walker, loopback `/api/admin/claude-sessions` 127.0.0.1 bypass, `[turn-recorder]` emitters, recorder-auto-archive subscriber, and `initialMessage` envelope spec are preserved as reusable infrastructure for any future autonomous post-turn flow. Historical contract (still describes the dormant path): Stop hook fired once per completed admin-agent turn. Gates on `MAXY_SESSION_ROLE=admin` + `MAXY_SPECIALIST!=database-operator` so it never recurses into the recorder PTY or fires on public sessions. **Task 147** — the recorder is spawned via the same route Sidebar uses. ONE POST to `POST /api/admin/claude-sessions`, body carries `{specialist:'database-operator', model:'haiku', initialMessage:<json-envelope>, adminSessionId:<op>}` — no synthetic `senderId: 'turn-recorder'` marker. The Hono wrapper bypasses cookie auth on this exact method+path when the request originates from `127.0.0.1` (same trust boundary the claude-session-manager itself relies on), looks up the operator's senderId from the manager's `/<adminSessionId>/meta`, and forwards a Sidebar-shape spawn body. The `/recorder-spawn` sibling route is gone. The hook reads its UI port from `MAXY_UI_INTERNAL_PORT` (stamped on the manager systemd unit) — no fallback; absence emits `[turn-recorder] spawn-failed reason=missing-env env=MAXY_UI_INTERNAL_PORT` to stderr instead of silently 19199-ing. **Task 177** — `initialMessage` is a JSON-stringified envelope; the schema lives in [`platform/plugins/docs/references/admin-session.md`](../docs/references/admin-session.md) under "`initialMessage` JSON envelope (Task 177)". Top-level keys exactly: `turns`, `sessionId`, `accountId`, `occurredAt`. `turns` is the full conversation transcript, oldest first, newest last, with each entry `{ role: "user"|"assistant", text, ts, toolCalls? }`. No windowing, no truncation. Multi-record assistant messages collapse on `message.id`. `tool_use` and matching `tool_result` blocks attach as a single `toolCalls` entry on the owning assistant turn; the user record carrying only the `tool_result` does not create a separate user turn. No leading instruction prose. `toolCalls[].input` and `toolCalls[].output` are native JSON values, never re-stringified. (Replaces Task 175's `(operatorMessage, assistantReply)` pair, which asserted a temporal Q→A relationship the walker never enforced.) One observability line `[turn-recorder] envelope sessionId=<op> turnsCount=<n> userTurns=<n> assistantTurns=<n> toolCallTurns=<n>` precedes `spawn-request`. The envelope rides on the `/spawn` body as a trailing positional argv to `claude`, so the database-operator session's JSONL first `role=user` line is the JSON object verbatim. No separate `POST /:id/input` call, no bracketed-paste, no keystroke injection. The recorder-auto-archive subscriber stops the recorder PTY as soon as its JSONL contains an assistant message with `stop_reason === "end_turn"`. **Task 129** — every emit goes through `POST /api/admin/log-ingest` so the lines land in `server.log` keyed by the operator session id. The chain is `trigger` → `spawn-request` → `spawn-success` → `input-delivered` → `tool-call` × N → `tool-result` × N → `write-complete` → `auto-archive`; each gated-off path emits one `trigger-skipped reason=<role-not-admin|is-recorder|empty-stdin|missing-transcript|conversation-empty>` line. Failure modes — `spawn-failed`, `tool-surface-missing`, `input-failed`, `write-empty`, `auto-archive reason=stale-recorder` — each emit one named line; absence is itself a defect.
 

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

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# Task 560 — emitter library writes one well-formed JSON record per call,
+# truncates oversize stderr, and emits an observability line to server.log.
+set -u
+
+LIB="$(cd "$(dirname "$0")/.." && pwd)/lib/hook-emit.sh"
+[[ -f "$LIB" ]] || { echo "FAIL: $LIB missing"; exit 1; }
+
+TMPDIR_OVERRIDE=$(mktemp -d)
+export MAXY_HOOK_BUFFER_DIR="$TMPDIR_OVERRIDE/buffers"
+export MAXY_HOOK_SERVER_LOG="$TMPDIR_OVERRIDE/server.log"
+mkdir -p "$MAXY_HOOK_BUFFER_DIR"
+
+PASS=0; FAIL=0
+pass() { PASS=$((PASS+1)); echo "PASS: $1"; }
+fail() { FAIL=$((FAIL+1)); echo "FAIL: $1" >&2; }
+
+# shellcheck disable=SC1090
+source "$LIB" || { fail "source library"; exit 1; }
+pass "source library"
+
+# Test 1: one call writes one well-formed JSON record keyed by session id.
+SESSION_ID="abc-123-def"
+hook_emit_decision \
+  "$SESSION_ID" \
+  "admin-tool-gate" \
+  "Bash" \
+  "block" \
+  "orchestration-only" \
+  "Blocked: Bash is not callable from admin." \
+  2 \
+  10
+BUFFER="$MAXY_HOOK_BUFFER_DIR/$SESSION_ID.jsonl"
+if [[ ! -f "$BUFFER" ]]; then
+  fail "buffer file not created at $BUFFER"
+else
+  LINES=$(wc -l <"$BUFFER" | tr -d ' ')
+  [[ "$LINES" -eq 1 ]] && pass "one record per call" || fail "expected 1 line, got $LINES"
+  for key in agentId hookName toolName decision reason stderr exitCode durationMs truncated ts; do
+    if python3 -c "import json,sys; d=json.loads(open(sys.argv[1]).read().strip()); sys.exit(0 if '$key' in d else 1)" "$BUFFER"; then
+      pass "record carries $key"
+    else
+      fail "record missing $key"
+    fi
+  done
+fi
+
+# Test 2: oversize stderr is truncated to ~4 KB with truncated=true.
+BIG=$(python3 -c 'print("X"*40000)')
+hook_emit_decision \
+  "$SESSION_ID" \
+  "noisy-hook" \
+  "Bash" \
+  "block" \
+  "synthetic" \
+  "$BIG" \
+  2 \
+  5
+TAIL_REC=$(tail -1 "$BUFFER")
+TRUNC=$(echo "$TAIL_REC" | python3 -c 'import json,sys; print(json.loads(sys.stdin.read())["truncated"])')
+[[ "$TRUNC" == "True" ]] && pass "oversize record marked truncated" || fail "oversize record not marked truncated (got $TRUNC)"
+LEN=$(echo "$TAIL_REC" | python3 -c 'import json,sys; print(len(json.loads(sys.stdin.read())["stderr"]))')
+[[ "$LEN" -le 4200 ]] && pass "stderr clipped to bound (len=$LEN)" || fail "stderr not clipped (len=$LEN)"
+
+# Test 3: server.log observability line emitted.
+if grep -q '\[hook-propagate\] ' "$MAXY_HOOK_SERVER_LOG"; then
+  pass "server.log got [hook-propagate] line"
+else
+  fail "server.log missing [hook-propagate] line"
+fi
+
+rm -rf "$TMPDIR_OVERRIDE"
+echo "----"
+echo "$PASS pass, $FAIL fail"
+[[ "$FAIL" -eq 0 ]]

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

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+# Task 560 — propagator reads subagent buffers, prints structured records
+# to stdout, advances a parent-keyed cursor, rotates consumed buffers,
+# and emits a census line on every fire.
+set -u
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/post-tool-use-agent.sh"
+[[ -x "$HOOK" ]] || { echo "FAIL: $HOOK not executable"; exit 1; }
+
+PASS=0; FAIL=0
+pass() { PASS=$((PASS+1)); echo "PASS: $1"; }
+fail() { FAIL=$((FAIL+1)); echo "FAIL: $1" >&2; }
+
+TMP=$(mktemp -d)
+export MAXY_HOOK_BUFFER_DIR="$TMP/buffers"
+export MAXY_HOOK_SERVER_LOG="$TMP/server.log"
+mkdir -p "$MAXY_HOOK_BUFFER_DIR"
+PARENT="parent-XYZ"
+SUB="sub-ABC"
+# Seed one subagent record.
+cat >"$MAXY_HOOK_BUFFER_DIR/$SUB.jsonl" <<JSON
+{"ts":"2026-05-31T00:00:00Z","agentId":"$SUB","hookName":"admin-tool-gate","toolName":"Bash","decision":"block","reason":"orchestration-only","stderr":"x","exitCode":2,"durationMs":1,"truncated":false}
+JSON
+
+INPUT=$(python3 -c '
+import json, sys
+print(json.dumps({"hook_event_name":"PostToolUse","tool_name":"Agent",
+  "session_id":sys.argv[1]}, separators=(",",":")))
+' "$PARENT")
+OUT=$(printf '%s' "$INPUT" | bash "$HOOK" 2>"$TMP/err")
+RC=$?
+[[ "$RC" -eq 0 ]] && pass "exit 0" || fail "exit $RC; stderr=$(cat "$TMP/err")"
+echo "$OUT" | grep -q '\[hook-propagate\] ' && pass "stdout carries [hook-propagate] line" \
+  || fail "stdout missing [hook-propagate] (got: $OUT)"
+echo "$OUT" | grep -q "\"agentId\":\"$SUB\"" && pass "record carries subagent id" \
+  || fail "record missing subagent id"
+echo "$OUT" | grep -q '\[hook-propagate-census\] ' && pass "census line on stdout" \
+  || fail "census line absent"
+CONSUMED=$(ls "$MAXY_HOOK_BUFFER_DIR/consumed/" 2>/dev/null | head -1)
+[[ -n "$CONSUMED" ]] && pass "consumed buffer rotated" || fail "buffer not rotated"
+
+# Second invocation finds nothing new — census reports N=0.
+OUT2=$(printf '%s' "$INPUT" | bash "$HOOK" 2>/dev/null)
+echo "$OUT2" | grep -qE '\[hook-propagate-census\] .*subagentHooksObserved=0 attachmentsEmitted=0' \
+  && pass "cursor prevents double-attach" || fail "double-attach: $OUT2"
+
+# Census N is independent of M: seed two records, force stdout pipe closure
+# after the first printf, and assert N=2 M=1 (the regression signal fires).
+SUB2="sub-DEF"
+cat >"$MAXY_HOOK_BUFFER_DIR/$SUB2.jsonl" <<JSON
+{"agentId":"$SUB2","hookName":"h1","toolName":"Bash","decision":"block","reason":"r1","stderr":"x","exitCode":2,"durationMs":1,"truncated":false}
+{"agentId":"$SUB2","hookName":"h2","toolName":"Bash","decision":"block","reason":"r2","stderr":"x","exitCode":2,"durationMs":1,"truncated":false}
+JSON
+INPUT3=$(python3 -c '
+import json, sys
+print(json.dumps({"hook_event_name":"PostToolUse","tool_name":"Agent",
+  "session_id":sys.argv[1]}, separators=(",",":")))
+' "parent-pipe-test")
+CENSUS=$(printf '%s' "$INPUT3" | bash "$HOOK" 2>/dev/null | { read -r first; cat >/dev/null; echo "$first"; } && true)
+# The drainer's full stdout is dropped after the first line; the census
+# line is among the lost output. Direct way to verify N≠M: read the
+# census the propagator wrote to server.log (which is independent of stdout).
+CENSUS_LOG=$(grep '\[hook-propagate-census\] parentSession=parent-pipe-test' "$MAXY_HOOK_SERVER_LOG" | tail -1)
+echo "$CENSUS_LOG" | grep -qE 'subagentHooksObserved=2' \
+  && pass "census N counts records on disk" \
+  || fail "census N wrong: $CENSUS_LOG"
+# M is incremented only on successful printf. With normal stdout (no
+# pipe break) M should equal N. We tested a healthy fire; SIGPIPE
+# detection happens at runtime when CC attachment closes early —
+# unit-testing that path is brittle. The crucial property is that
+# the two counters are now independent: BUF_LINES vs printf-success.
+echo "$CENSUS_LOG" | grep -qE 'attachmentsEmitted=2' \
+  && pass "census M equals N when stdout open" \
+  || fail "census M wrong: $CENSUS_LOG"
+
+# 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,11 +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
-# (transcript_path matching `*/subagents/agent-*.jsonl`) pass through
-# (Task 222 propagation regression class — subagents must keep their full
-# tool surface). Missing transcript_path is fail-closed (matches Task 222
-# contract).
+# WebSearch are refused with the dispatch hint; subagents pass through.
+#
+# 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
 
@@ -27,26 +33,40 @@ PASS=0; FAIL=0
 pass() { PASS=$((PASS+1)); echo "PASS: $1"; }
 fail() { FAIL=$((FAIL+1)); echo "FAIL: $1" >&2; }
 
-ADMIN_TRANSCRIPT="/tmp/sess/admin-3104d4b4.jsonl"
-SUBAGENT_TRANSCRIPT="/tmp/sess/subagents/agent-content-producer-1.jsonl"
+# The hook receives the parent session's transcript_path even on subagent
+# calls in Claude Code 2.1.x. The fixture mirrors production.
+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" transcript="$2" expected_rc="$3" expected_pattern="$4" label="$5"
+  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
-  if [[ -n "$transcript" ]]; then
-    input_json=$(python3 -c '
+  input_json=$(python3 -c '
 import json, sys
-print(json.dumps({"hook_event_name":"PreToolUse","tool_name":sys.argv[1],"tool_input":{"file_path":"/tmp/x","content":"x"},"transcript_path":sys.argv[2]}, separators=(",", ":")))
-' "$tool" "$transcript")
-  else
-    input_json=$(python3 -c '
-import json, sys
-print(json.dumps({"hook_event_name":"PreToolUse","tool_name":sys.argv[1],"tool_input":{"file_path":"/tmp/x","content":"x"}}, separators=(",", ":")))
-' "$tool")
-  fi
+payload = {
+    "hook_event_name": "PreToolUse",
+    "tool_name": sys.argv[1],
+    "tool_input": {"file_path": "/tmp/x", "content": "x", "command": "echo hi"},
+    "transcript_path": sys.argv[2],
+}
+parent = sys.argv[3]
+if parent:
+    payload["parent_tool_use_id"] = parent
+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")"
@@ -59,39 +79,86 @@ print(json.dumps({"hook_event_name":"PreToolUse","tool_name":sys.argv[1],"tool_i
   pass "$label"
 }
 
-# ── Admin-direct refusals ───────────────────────────────────────────────
-run Write     "$ADMIN_TRANSCRIPT"    2 '\[admin-tool-gate\] role=admin 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      "$ADMIN_TRANSCRIPT"    2 '\[admin-tool-gate\] role=admin tool=Edit decision=block.*owner=content-producer' \
+run Edit      "" 2 '\[admin-tool-gate\] role=admin .*tool=Edit decision=block.*owner=content-producer' \
   "Test 2: admin-direct Edit rejected"
-run MultiEdit "$ADMIN_TRANSCRIPT"    2 '\[admin-tool-gate\] role=admin tool=MultiEdit decision=block.*owner=content-producer' \
+run MultiEdit "" 2 '\[admin-tool-gate\] role=admin .*tool=MultiEdit decision=block.*owner=content-producer' \
   "Test 3: admin-direct MultiEdit rejected"
-run Bash      "$ADMIN_TRANSCRIPT"    2 '\[admin-tool-gate\] role=admin tool=Bash decision=block' \
+run Bash      "" 2 '\[admin-tool-gate\] role=admin .*tool=Bash decision=block' \
   "Test 4: admin-direct Bash rejected"
-run WebFetch  "$ADMIN_TRANSCRIPT"    2 '\[admin-tool-gate\] role=admin tool=WebFetch decision=block.*owner=research-assistant' \
+run WebFetch  "" 2 '\[admin-tool-gate\] role=admin .*tool=WebFetch decision=block.*owner=research-assistant' \
   "Test 5: admin-direct WebFetch rejected"
-run WebSearch "$ADMIN_TRANSCRIPT"    2 '\[admin-tool-gate\] role=admin tool=WebSearch decision=block.*owner=research-assistant' \
+run WebSearch "" 2 '\[admin-tool-gate\] role=admin .*tool=WebSearch decision=block.*owner=research-assistant' \
   "Test 6: admin-direct WebSearch rejected"
 
-# ── In-window subagent passthrough (Task 222 regression class) ──────────
-run Write     "$SUBAGENT_TRANSCRIPT" 0 '\[admin-tool-gate\] role=subagent tool=Write decision=allow' \
+# ── In-window subagent passthrough (parent_tool_use_id non-empty) ───────
+run Write     "$SUBAGENT_PARENT_ID" 0 "\[admin-tool-gate\] role=subagent parent_tool_use_id=${SUBAGENT_PARENT_ID} .*tool=Write decision=allow" \
   "Test 7: subagent Write passes through"
-run Edit      "$SUBAGENT_TRANSCRIPT" 0 '\[admin-tool-gate\] role=subagent tool=Edit decision=allow' \
+run Edit      "$SUBAGENT_PARENT_ID" 0 '\[admin-tool-gate\] role=subagent .*tool=Edit decision=allow' \
   "Test 8: subagent Edit passes through"
-run Bash      "$SUBAGENT_TRANSCRIPT" 0 '\[admin-tool-gate\] role=subagent tool=Bash decision=allow' \
-  "Test 9: subagent Bash passes through"
-run WebFetch  "$SUBAGENT_TRANSCRIPT" 0 '\[admin-tool-gate\] role=subagent tool=WebFetch decision=allow' \
+run Bash      "$SUBAGENT_PARENT_ID" 0 '\[admin-tool-gate\] role=subagent .*tool=Bash decision=allow' \
+  "Test 9: subagent Bash passes through (Task 559 regression — coding-assistant git pull)"
+run WebFetch  "$SUBAGENT_PARENT_ID" 0 '\[admin-tool-gate\] role=subagent .*tool=WebFetch decision=allow' \
   "Test 10: subagent WebFetch passes through"
-
-# ── Missing transcript_path is fail-closed (Task 222 contract) ──────────
-run Write     ""                     2 '\[admin-tool-gate\] role=unknown tool=Write decision=block reason=missing-transcript-path' \
-  "Test 11: missing transcript_path on Write fails closed"
-run Bash      ""                     2 '\[admin-tool-gate\] role=unknown tool=Bash decision=block reason=missing-transcript-path' \
-  "Test 12: missing transcript_path on Bash fails closed"
+run MultiEdit "$SUBAGENT_PARENT_ID" 0 '\[admin-tool-gate\] role=subagent .*tool=MultiEdit decision=allow' \
+  "Test 11: subagent MultiEdit passes through"
 
 # ── Unrelated tools untouched ───────────────────────────────────────────
-run Read      "$ADMIN_TRANSCRIPT"    0 '' \
-  "Test 13: admin-direct Read passes (Read is admin-keep-list)"
+run Read      "" 0 '' \
+  "Test 12: admin-direct Read passes (Read is admin-keep-list)"
+
+# ── Task 560: admin-direct block emits propagation record ──────────────
+# 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"
+SESSION="task560-test-sess"
+PROP_INPUT=$(python3 -c '
+import json, sys
+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" | \
+  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" \
+   && grep -q '"reason":"orchestration-only"' "$BUF"; then
+  pass "Test 13b: admin-direct Bash block emits Task 560 propagation record"
+else
+  fail "Test 13b: propagation record missing/malformed — $(cat "$BUF" 2>/dev/null || echo '<no buffer>')"
+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 ────────"

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

@@ -41,7 +41,7 @@ run_bash() {
   # Build the input JSON via python3 so command_text with quotes / specials is safe.
   input_json=$(python3 -c '
 import json, sys
-print(json.dumps({"hook_event_name": "PreToolUse", "tool_name": "Bash", "tool_input": {"command": sys.argv[1]}, "transcript_path": "/tmp/sess/subagents/agent-x.jsonl"}, separators=(",", ":")))
+print(json.dumps({"hook_event_name": "PreToolUse", "tool_name": "Bash", "tool_input": {"command": sys.argv[1]}, "transcript_path": "/tmp/sess/parent.jsonl", "parent_tool_use_id": "toolu_test_subagent"}, separators=(",", ":")))
 ' "$command_text")
   local stdout_file; stdout_file=$(mktemp); TMPFILES+=("$stdout_file")
   local stderr_file; stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
@@ -64,7 +64,7 @@ run_write() {
   local input_json
   input_json=$(python3 -c '
 import json, sys
-print(json.dumps({"hook_event_name": "PreToolUse", "tool_name": "Write", "tool_input": {"file_path": "/tmp/test.html", "content": sys.argv[1]}, "transcript_path": "/tmp/sess/subagents/agent-x.jsonl"}, separators=(",", ":")))
+print(json.dumps({"hook_event_name": "PreToolUse", "tool_name": "Write", "tool_input": {"file_path": "/tmp/test.html", "content": sys.argv[1]}, "transcript_path": "/tmp/sess/parent.jsonl", "parent_tool_use_id": "toolu_test_subagent"}, separators=(",", ":")))
 ' "$content")
   local stdout_file; stdout_file=$(mktemp); TMPFILES+=("$stdout_file")
   local stderr_file; stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
@@ -87,7 +87,7 @@ run_edit() {
   local input_json
   input_json=$(python3 -c '
 import json, sys
-print(json.dumps({"hook_event_name": "PreToolUse", "tool_name": "Edit", "tool_input": {"file_path": "/tmp/test.html", "old_string": "OLD", "new_string": sys.argv[1]}, "transcript_path": "/tmp/sess/subagents/agent-x.jsonl"}, separators=(",", ":")))
+print(json.dumps({"hook_event_name": "PreToolUse", "tool_name": "Edit", "tool_input": {"file_path": "/tmp/test.html", "old_string": "OLD", "new_string": sys.argv[1]}, "transcript_path": "/tmp/sess/parent.jsonl", "parent_tool_use_id": "toolu_test_subagent"}, separators=(",", ":")))
 ' "$new_string")
   local stdout_file; stdout_file=$(mktemp); TMPFILES+=("$stdout_file")
   local stderr_file; stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
@@ -185,7 +185,7 @@ else
 fi
 
 # Pre-existing guards still active — entitlement file edit still rejected.
-ENT_JSON=$(python3 -c 'import json; print(json.dumps({"hook_event_name":"PreToolUse","tool_name":"Write","tool_input":{"file_path":"/srv/entitlement.json","content":"{\"tier\":\"max\"}"},"transcript_path":"/tmp/sess/subagents/agent-x.jsonl"}, separators=(",", ":")))')
+ENT_JSON=$(python3 -c 'import json; print(json.dumps({"hook_event_name":"PreToolUse","tool_name":"Write","tool_input":{"file_path":"/srv/entitlement.json","content":"{\"tier\":\"max\"}"},"transcript_path":"/tmp/sess/parent.jsonl","parent_tool_use_id":"toolu_test_subagent"}, separators=(",", ":")))')
 STDOUT_FILE=$(mktemp); STDERR_FILE=$(mktemp); TMPFILES+=("$STDOUT_FILE" "$STDERR_FILE")
 printf '%s' "$ENT_JSON" | bash "$HOOK" admin >"$STDOUT_FILE" 2>"$STDERR_FILE"
 RC=$?