@rubytech/create-maxy-code 0.1.212 → 0.1.214

package/package.json

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

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

@@ -141,6 +141,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,77 @@
+#!/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"
+
+rm -rf "$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

@@ -2,10 +2,13 @@
 # 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).
+# 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`.
 
 set -u
 
@@ -27,23 +30,27 @@ 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() {
-  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 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"
@@ -59,39 +66,58 @@ 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) ───────────────────────
+run Write     "" 2 '\[admin-tool-gate\] role=admin parent_tool_use_id=- specialist=- 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 ──────────────
+# Uses the Task 559 classifier (no parent_tool_use_id → admin-direct).
+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" | 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
 
 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=$?

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

@@ -0,0 +1,84 @@
+#!/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}"
+
+# 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"
+  if ! printf '%s\n' "$rec" >>"$buf" 2>/dev/null; then
+    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
+
+  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 pre-tool-use.sh: 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/post-tool-use-agent.sh

@@ -0,0 +1,84 @@
+#!/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.
+
+set -uo pipefail
+
+: "${MAXY_HOOK_BUFFER_DIR:=$HOME/.maxy-code/logs/hook-decisions}"
+: "${MAXY_HOOK_SERVER_LOG:=$HOME/.maxy-code/logs/server.log}"
+
+if [ -t 0 ]; then
+  # No stdin — no correlation possible. Fail-open.
+  exit 0
+fi
+INPUT=$(cat)
+PARENT_SESSION=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    print(json.load(sys.stdin).get("session_id", "") or "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
+fi
+NOW_EPOCH=$(date +%s)
+
+N_OBSERVED=0
+N_EMITTED=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
+    continue
+  fi
+  # Ground-truth observed count: non-empty lines in the buffer file. The
+  # printf-success M_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)
+  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
+    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
+  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"
+
+mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+printf '[hook-propagate-census] parentSession=%s subagentHooksObserved=%d attachmentsEmitted=%d\n' \
+  "$PARENT_SESSION" "$N_OBSERVED" "$N_EMITTED" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null || true
+
+exit 0

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

@@ -8,72 +8,93 @@ set -uo pipefail
 
 AGENT_TYPE="${1:-public}"
 
+# Source the propagation emitter (Task 560). The library is fail-open;
+# any error path inside it logs to server.log and returns 0, so sourcing
+# never blocks the hook's primary allow/block contract.
+HOOKS_LIB_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)/lib"
+# shellcheck disable=SC1091
+[ -f "$HOOKS_LIB_DIR/hook-emit.sh" ] && source "$HOOKS_LIB_DIR/hook-emit.sh"
+
 # Read stdin — fail closed if unavailable
 if [ -t 0 ]; then
+  # No INPUT yet; propagate with agentId=unknown so the regression is visible.
+  if declare -F hook_emit_decision >/dev/null 2>&1; then
+    hook_emit_decision "unknown" "admin-tool-gate" "?" "block" \
+      "stdin-missing" "Blocked: Cannot determine tool call (no stdin). Failing closed." 2 0
+  fi
   echo "Blocked: Cannot determine tool call (no stdin). Failing closed." >&2
   exit 2
 fi
 INPUT=$(cat)
 TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | cut -d'"' -f4)
 
+# Session id for propagation. Empty / parse-failure routes to "unknown" —
+# the propagator emits the record under agentId=unknown rather than dropping.
+SESSION_ID=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    print(json.load(sys.stdin).get("session_id", "") or "unknown")
+except Exception:
+    print("unknown")
+' 2>/dev/null || echo "unknown")
+
 # ---------------------------------------------------------------------------
 # Admin agent — code directory protection + approval gating
 # ---------------------------------------------------------------------------
 if [ "$AGENT_TYPE" = "admin" ]; then
 
-  # ── Orchestration-only authoring + research block (Task 529) ─────────────
+  # ── Orchestration-only authoring + research block (Task 529, 559) ────────
   # 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) — the discriminator is the transcript_path: Claude Code stores
-  # subagent turns in separate `*/subagents/agent-*.jsonl` files.
+  # class).
+  #
+  # 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.
   #
-  # Admin direct → exit 2 with dispatch hint.
-  # Subagent → exit 0 (passthrough).
-  # Missing/malformed transcript_path → fail-closed block (matches Task 222).
+  # Admin direct (no parent_tool_use_id) → exit 2 with dispatch hint.
+  # Subagent (parent_tool_use_id non-empty) → exit 0 (passthrough).
   case "$TOOL_NAME" in
     Write|Edit|MultiEdit|Bash|WebFetch|WebSearch)
-      TRANSCRIPT_PATH=$(echo "$INPUT" | python3 -c '
+      PARENT_TOOL_USE_ID=$(echo "$INPUT" | python3 -c '
 import sys, json
 try:
-    print(json.load(sys.stdin).get("transcript_path", "") or "")
+    v = json.load(sys.stdin).get("parent_tool_use_id", "")
+    print(v if isinstance(v, str) else "")
 except Exception:
     print("")
 ' 2>/dev/null)
-      case "$TRANSCRIPT_PATH" in
-        */subagents/agent-*.jsonl)
-          # In-window subagent — passthrough. Tool name resolves on the
-          # subagent's own frontmatter `tools:` allowlist downstream.
-          echo "[admin-tool-gate] role=subagent tool=${TOOL_NAME} decision=allow source=hook-passthrough" >&2
-          ;;
-        "")
-          # Missing transcript_path on a denied native tool — fail closed
-          # rather than guess (Task 222 fail-closed contract).
-          echo "[admin-tool-gate] role=unknown tool=${TOOL_NAME} decision=block reason=missing-transcript-path" >&2
-          echo "Blocked: ${TOOL_NAME} is unavailable from the admin seat and the caller cannot be classified (no transcript_path). Failing closed." >&2
-          exit 2
-          ;;
-        *)
-          # Admin direct invocation — refuse with dispatch hint.
-          case "$TOOL_NAME" in
-            Write|Edit|MultiEdit)
-              OWNER="content-producer"
-              ;;
-            Bash)
-              OWNER="the specialist that owns the workflow needing shell access"
-              ;;
-            WebFetch|WebSearch)
-              OWNER="research-assistant"
-              ;;
-          esac
-          echo "[admin-tool-gate] role=admin tool=${TOOL_NAME} decision=block reason=orchestration-only owner=${OWNER}" >&2
-          echo "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." >&2
-          echo "Dispatch the work to ${OWNER} via the Agent tool." >&2
-          exit 2
-          ;;
-      esac
+      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
+        # Admin direct invocation — refuse with dispatch hint.
+        case "$TOOL_NAME" in
+          Write|Edit|MultiEdit)
+            OWNER="content-producer"
+            ;;
+          Bash)
+            OWNER="the specialist that owns the workflow needing shell access"
+            ;;
+          WebFetch|WebSearch)
+            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
+        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."
+      fi
       ;;
   esac
 
@@ -84,13 +105,15 @@ except Exception:
       case "$FILE_PATH" in
         # Platform UI source (platform/ui/) — source lives here, not on device
         */platform/ui/app/*|*/platform/ui/lib/*|*/platform/ui/*.ts|*/platform/ui/*.tsx|*/platform/ui/*.mjs)
-          echo "Blocked: Admin agent cannot modify platform UI source at $FILE_PATH" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "${TOOL_NAME}" \
+            "code-dir-protection-ui" \
+            "Blocked: Admin agent cannot modify platform UI source at $FILE_PATH"
           ;;
         # Compiled MCP servers, hooks, and scripts — what actually ships to device
         */platform/plugins/*/mcp/dist/*|*/platform/plugins/*/hooks/*|*/platform/scripts/*)
-          echo "Blocked: Admin agent cannot modify platform code at $FILE_PATH" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "${TOOL_NAME}" \
+            "code-dir-protection-platform" \
+            "Blocked: Admin agent cannot modify platform code at $FILE_PATH"
           ;;
         # Entitlement library — verifier source, compiled output, vendored
         # pubkey, hash file, and any signed entitlement.json. Tampering here is the
@@ -99,9 +122,10 @@ except Exception:
         # Patterns intentionally cover both absolute (*/...) and relative
         # (no leading slash) paths so an agent can't bypass via cwd-relative writes.
         */platform/lib/entitlement/*|platform/lib/entitlement/*|*/entitlement.json|entitlement.json)
-          echo "Blocked: Admin agent cannot modify entitlement files at $FILE_PATH. Effective tier and purchasedPlugins derive from a Rubytech-signed payload." >&2
           echo "[entitlement] tool-deny: tool=${TOOL_NAME} path=${FILE_PATH} field=entitlement-file" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "${TOOL_NAME}" \
+            "entitlement-file" \
+            "Blocked: Admin agent cannot modify entitlement files at $FILE_PATH. Effective tier and purchasedPlugins derive from a Rubytech-signed payload."
           ;;
         # account.json — agent must use the account-update
         # MCP tool (or plugin-toggle-enabled for enabledPlugins changes), which
@@ -112,14 +136,16 @@ except Exception:
         # incident showed a tier upgrade via raw Edit on account.json reach
         # the disk, exactly the failure mode this hook exists to prevent.
         */data/accounts/*/account.json|*/config/accounts/*/account.json|data/accounts/*/account.json|config/accounts/*/account.json|*/account.json|*account.json|account.json)
-          echo "Blocked: Admin agent cannot edit account.json directly. Use the account-update or plugin-toggle-enabled MCP tools — they whitelist editable fields server-side and exclude tier and purchasedPlugins by design." >&2
           echo "[entitlement] tool-deny: tool=${TOOL_NAME} path=${FILE_PATH} field=account-json" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "${TOOL_NAME}" \
+            "account-json" \
+            "Blocked: Admin agent cannot edit account.json directly. Use the account-update or plugin-toggle-enabled MCP tools — they whitelist editable fields server-side and exclude tier and purchasedPlugins by design."
           ;;
         # Pending action queue — only the hook and MCP tools may write here
         */pending-actions/*)
-          echo "Blocked: Admin agent cannot modify pending action files directly" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "${TOOL_NAME}" \
+            "pending-actions" \
+            "Blocked: Admin agent cannot modify pending action files directly"
           ;;
       esac
       ;;
@@ -127,24 +153,28 @@ except Exception:
       # Block shell commands referencing protected code directories or pending actions
       case "$INPUT" in
         *"platform/ui/app/"*|*"platform/ui/lib/"*|*"platform/plugins/"*"hooks/"*|*"platform/scripts/"*)
-          echo "Blocked: Admin agent cannot run shell commands against code directories" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "Bash" \
+            "code-dir-protection-bash" \
+            "Blocked: Admin agent cannot run shell commands against code directories"
           ;;
         # Entitlement files via shell — same surface, blocked symmetrically
         *"platform/lib/entitlement/"*|*"entitlement.json"*)
-          echo "Blocked: Admin agent cannot reference entitlement files via shell." >&2
           echo "[entitlement] tool-deny: tool=Bash path=entitlement-file field=entitlement-file" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "Bash" \
+            "entitlement-shell" \
+            "Blocked: Admin agent cannot reference entitlement files via shell."
           ;;
         # account.json via shell — same rationale as Edit/Write block
         *"data/accounts/"*"account.json"*|*"config/accounts/"*"account.json"*)
-          echo "Blocked: Admin agent cannot edit account.json via shell. Use the account-update MCP tool." >&2
           echo "[entitlement] tool-deny: tool=Bash path=account-json field=account-json" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "Bash" \
+            "account-json-shell" \
+            "Blocked: Admin agent cannot edit account.json via shell. Use the account-update MCP tool."
           ;;
         *"pending-actions/"*)
-          echo "Blocked: Admin agent cannot modify pending action files via shell" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "Bash" \
+            "pending-actions-shell" \
+            "Blocked: Admin agent cannot modify pending action files via shell"
           ;;
       esac
       ;;
@@ -229,17 +259,19 @@ except Exception:
     REJECT:base64-write-content:*)
       BYTES="${GUARD_VERDICT##*:}"
       echo "[pre-tool-use] guard=base64-write-content bytes=${BYTES} action=reject" >&2
-      echo "Blocked: ${TOOL_NAME} content carries an inline base64 payload (>4 KB encoded). Inline binary in Write.content overloads the model context — the same path produced a main_stream_stalled at ~33 KB on 2026-05-09." >&2
-      echo "Save the bytes to \$ACCOUNT_DIR/tmp/<sha1>.<ext> via Bash (e.g. 'base64 -d > out.png'), then reference the file from the document: <img src=\"./<file>\"> or Read-by-path. Do not carry binary bytes through the assistant turn." >&2
-      exit 2
+      hook_block_with_emit "$SESSION_ID" "base64-guard" "${TOOL_NAME}" \
+        "base64-write-content" \
+        "Blocked: ${TOOL_NAME} content carries an inline base64 payload (>4 KB encoded). Inline binary in Write.content overloads the model context — the same path produced a main_stream_stalled at ~33 KB on 2026-05-09.
+Save the bytes to \$ACCOUNT_DIR/tmp/<sha1>.<ext> via Bash (e.g. 'base64 -d > out.png'), then reference the file from the document: <img src=\"./<file>\"> or Read-by-path. Do not carry binary bytes through the assistant turn."
       ;;
     REJECT:base64-encoder:*|REJECT:xxd-plain-hex:*)
       REASON="${GUARD_VERDICT#REJECT:}"; REASON="${REASON%:*}"
       BYTES="${GUARD_VERDICT##*:}"
       echo "[pre-tool-use] guard=base64-tool-result bytes=${BYTES} tool=Bash reason=${REASON} action=reject" >&2
-      echo "Blocked: Bash command would emit binary as inline base64/hex to stdout, which lands in the assistant turn and overloads the model context (the 2026-05-09 Rubytech-invoice path hit 66% context after a single ~33 KB tool_result)." >&2
-      echo "Instead: save the bytes directly to \$ACCOUNT_DIR/tmp/<sha1>.<ext> and operate on the file via path — Read for inspection, <img src=\"./<file>\"> for HTML embedding, the \`file-presentation\` skill for delivery. Decoding base64 (e.g. 'base64 -d in.b64 > out.bin') is allowed." >&2
-      exit 2
+      hook_block_with_emit "$SESSION_ID" "base64-guard" "Bash" \
+        "$REASON" \
+        "Blocked: Bash command would emit binary as inline base64/hex to stdout, which lands in the assistant turn and overloads the model context (the 2026-05-09 Rubytech-invoice path hit 66% context after a single ~33 KB tool_result).
+Instead: save the bytes directly to \$ACCOUNT_DIR/tmp/<sha1>.<ext> and operate on the file via path — Read for inspection, <img src=\"./<file>\"> for HTML embedding, the \`file-presentation\` skill for delivery. Decoding base64 (e.g. 'base64 -d in.b64 > out.bin') is allowed."
       ;;
     *)
       : # ALLOW — fall through to approval gating below
@@ -313,8 +345,9 @@ except Exception:
   # Write atomically: temp file + mv
   TEMP=$(mktemp "${PENDING_DIR}/.tmp.XXXXXX" 2>/dev/null)
   if [ -z "$TEMP" ]; then
-    echo "Blocked: Action requires approval but failed to create queue file (disk error). Failing closed." >&2
-    exit 2
+    hook_block_with_emit "$SESSION_ID" "approval-gate" "${TOOL_NAME}" \
+      "approval-queue-mktemp" \
+      "Blocked: Action requires approval but failed to create queue file (disk error). Failing closed."
   fi
 
   # The pending action file contains the full hook JSON (tool_name + tool_input)
@@ -332,10 +365,19 @@ ENDJSON
 
   if ! mv "$TEMP" "${PENDING_DIR}/${ACTION_ID}.json" 2>/dev/null; then
     rm -f "$TEMP" 2>/dev/null
-    echo "Blocked: Action requires approval but failed to queue (filesystem error). Failing closed." >&2
-    exit 2
+    hook_block_with_emit "$SESSION_ID" "approval-gate" "${TOOL_NAME}" \
+      "approval-queue-mv" \
+      "Blocked: Action requires approval but failed to queue (filesystem error). Failing closed."
   fi
 
+  # Record the queued-for-approval block in the propagation buffer; the
+  # readable summary still goes to stdout (CC attaches it as the agent's
+  # tool_result). hook_emit_decision is the no-exit variant — the
+  # subsequent echoes + exit 2 below remain the operator-facing surface.
+  hook_emit_decision "$SESSION_ID" "approval-gate" "${TOOL_NAME}" \
+    "block" "approval-queued" \
+    "Action ${ACTION_ID} queued for review" 2 0
+
   # Extract a readable summary of the action for the agent to present
   # tool_input is the second JSON value in the hook payload
   echo "Action requires approval before execution."

package/payload/platform/scripts/setup-account.sh

@@ -121,6 +121,12 @@ cat > "$ACCOUNT_SETTINGS" << SETTINGS_EOF
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "Agent",
+        "hooks": [
+          { "type": "command", "command": "bash $HOOKS_PATH/post-tool-use-agent.sh" }
+        ]
+      },
       {
         "matcher": "mcp__.*__.*-(export|import)-parse$",
         "hooks": [