@rubytech/create-maxy-code 0.1.212 → 0.1.216

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

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# Task 560 — emit subagent hook decisions to a sidecar buffer that the
+# parent-side post-tool-use-agent.sh propagator reads on its next fire.
+#
+# This library is fail-open: every error path is logged to server.log
+# under [hook-propagate-error] and returns success so the hook's primary
+# allow/block contract is never coupled to propagation succeeding.
+
+: "${MAXY_HOOK_BUFFER_DIR:=$HOME/.maxy-code/logs/hook-decisions}"
+: "${MAXY_HOOK_SERVER_LOG:=$HOME/.maxy-code/logs/server.log}"
+: "${MAXY_HOOK_STDERR_CAP:=4096}"
+# Task 563 — mkdir-based mutex serialises emitter append vs drainer rename.
+# 100 attempts × 10ms = ~1s ceiling. Portable across Linux (Pi) and macOS
+# (tests) without flock(1).
+: "${MAXY_HOOK_LOCK_ATTEMPTS:=100}"
+: "${MAXY_HOOK_LOCK_SLEEP:=0.01}"
+
+# _hook_acquire_lock <lockdir> — returns 0 on success, 1 on timeout.
+_hook_acquire_lock() {
+  local lockdir="$1" i=0
+  while ! mkdir "$lockdir" 2>/dev/null; do
+    i=$((i+1))
+    [[ "$i" -ge "$MAXY_HOOK_LOCK_ATTEMPTS" ]] && return 1
+    sleep "$MAXY_HOOK_LOCK_SLEEP" 2>/dev/null || true
+  done
+  return 0
+}
+
+# _hook_release_lock <lockdir>
+_hook_release_lock() {
+  rmdir "$1" 2>/dev/null || true
+}
+
+# hook_emit_decision <agentId> <hookName> <toolName> <decision> <reason>
+#                    <stderrPayload> <exitCode> <durationMs>
+hook_emit_decision() {
+  local agentId="$1" hookName="$2" toolName="$3" decision="$4" reason="$5"
+  local stderrPayload="$6" exitCode="$7" durationMs="$8"
+
+  local rec
+  rec=$(MAXY_HOOK_STDERR_CAP="$MAXY_HOOK_STDERR_CAP" python3 - \
+    "$agentId" "$hookName" "$toolName" "$decision" "$reason" \
+    "$stderrPayload" "$exitCode" "$durationMs" <<'PY' 2>/dev/null
+import json, os, sys, datetime
+cap = int(os.environ.get("MAXY_HOOK_STDERR_CAP", "4096"))
+(agentId, hookName, toolName, decision, reason,
+ stderrPayload, exitCode, durationMs) = sys.argv[1:9]
+truncated = False
+if len(stderrPayload) > cap:
+    dropped = len(stderrPayload) - cap
+    stderrPayload = stderrPayload[:cap] + f"…[truncated {dropped} bytes]"
+    truncated = True
+print(json.dumps({
+    "ts": datetime.datetime.utcnow().replace(microsecond=0).isoformat() + "Z",
+    "agentId": agentId,
+    "hookName": hookName,
+    "toolName": toolName,
+    "decision": decision,
+    "reason": reason,
+    "stderr": stderrPayload,
+    "exitCode": int(exitCode) if exitCode.lstrip("-").isdigit() else 0,
+    "durationMs": int(durationMs) if durationMs.lstrip("-").isdigit() else 0,
+    "truncated": truncated,
+}, separators=(",", ":")))
+PY
+  )
+  if [[ -z "$rec" ]]; then
+    mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+    printf '[hook-propagate-error] reason=record-build agentId=%s hook=%s\n' \
+      "$agentId" "$hookName" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null
+    return 0
+  fi
+
+  mkdir -p "$MAXY_HOOK_BUFFER_DIR" 2>/dev/null
+  local buf="$MAXY_HOOK_BUFFER_DIR/$agentId.jsonl"
+  local lock="${buf}.lock"
+  if ! _hook_acquire_lock "$lock"; then
+    mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+    printf '[hook-propagate-error] reason=lock-timeout agentId=%s hook=%s\n' \
+      "$agentId" "$hookName" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null
+    return 0
+  fi
+  if ! printf '%s\n' "$rec" >>"$buf" 2>/dev/null; then
+    _hook_release_lock "$lock"
+    mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+    printf '[hook-propagate-error] reason=buffer-write agentId=%s hook=%s\n' \
+      "$agentId" "$hookName" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null
+    return 0
+  fi
+  _hook_release_lock "$lock"
+
+  local bytesIn="${#stderrPayload}"
+  local bytesOut="${#rec}"
+  local trunc=false
+  [[ "$rec" == *'"truncated":true'* ]] && trunc=true
+  mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+  printf '[hook-propagate] agentId=%s hookName=%s tool=%s decision=%s bytesIn=%s bytesOut=%s truncated=%s\n' \
+    "$agentId" "$hookName" "$toolName" "$decision" "$bytesIn" "$bytesOut" "$trunc" \
+    >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null
+  return 0
+}
+
+# hook_block_with_emit <agentId> <hookName> <toolName> <reason>
+#                      <userMessage> [durationMs]
+# Convenience wrapper for 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,136 @@
+#!/usr/bin/env bash
+# Task 560 — PostToolUse hook scoped to tool_name=Agent in the admin role.
+# Drains every subagent hook-decision buffer in the dir, prints each record
+# as a [hook-propagate] line to stdout (Claude Code attaches the stdout to
+# the parent JSONL as a hook_success attachment), and emits one
+# [hook-propagate-census] line. N != M in the census is the propagation
+# regression signal.
+#
+# Task 563 — concurrency hardening:
+#   - Atomic claim before read. Each buffer is renamed under a mkdir mutex
+#     to a per-fire `claimed/<basename>-<epoch>-<pid>.jsonl` path. The lock
+#     is held only for the rename syscall; reading happens against the
+#     renamed inode, which no emitter can address. The race window between
+#     the drainer's read and the buffer rotation is closed.
+#   - No cursor. The cursor file was load-bearing only because consumed
+#     buffers could be re-seen; with atomic claim the file's presence in
+#     the directory is the unambiguous signal. Dropping the cursor closes
+#     two further races (concurrent-drainer cursor write, shared
+#     `.unknown.cursor` across broken-stdin fires).
+#   - Unknown-parent observability. When stdin's `session_id` is missing
+#     or unparseable, an explicit `[hook-propagate] parentSession=unknown
+#     reason=session-id-missing` line is emitted to both stdout and
+#     server.log so the broken-stdin path is no longer silent.
+
+set -uo pipefail
+
+: "${MAXY_HOOK_BUFFER_DIR:=$HOME/.maxy-code/logs/hook-decisions}"
+: "${MAXY_HOOK_SERVER_LOG:=$HOME/.maxy-code/logs/server.log}"
+: "${MAXY_HOOK_LOCK_ATTEMPTS:=100}"
+: "${MAXY_HOOK_LOCK_SLEEP:=0.01}"
+
+if [ -t 0 ]; then
+  # No stdin — no correlation possible. Fail-open.
+  exit 0
+fi
+INPUT=$(cat)
+PARENT_SESSION=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    sid = json.load(sys.stdin).get("session_id") or ""
+    print(sid if sid else "unknown")
+except Exception:
+    print("unknown")
+' 2>/dev/null || echo "unknown")
+
+if [[ "$PARENT_SESSION" == "unknown" ]]; then
+  # Conservative play (Task 563 brief option C): emit observability and
+  # exit without draining. A broken-stdin fire has no business processing
+  # buffers — the next valid parent fire will pick them up.
+  mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+  printf '[hook-propagate] parentSession=unknown reason=session-id-missing\n'
+  printf '[hook-propagate] parentSession=unknown reason=session-id-missing\n' \
+    >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null || true
+  exit 0
+fi
+
+mkdir -p "$MAXY_HOOK_BUFFER_DIR/claimed" "$MAXY_HOOK_BUFFER_DIR/consumed" 2>/dev/null
+
+# Sweep orphaned `.<session>.cursor` files left behind by an older
+# version of this script. The cursor mechanism is gone; without this
+# they would persist forever as dir noise.
+rm -f "$MAXY_HOOK_BUFFER_DIR"/.*.cursor 2>/dev/null || true
+
+NOW_EPOCH=$(date +%s)
+N_OBSERVED=0
+N_EMITTED=0
+
+_drain_acquire_lock() {
+  local lockdir="$1" i=0
+  while ! mkdir "$lockdir" 2>/dev/null; do
+    i=$((i+1))
+    [[ "$i" -ge "$MAXY_HOOK_LOCK_ATTEMPTS" ]] && return 1
+    sleep "$MAXY_HOOK_LOCK_SLEEP" 2>/dev/null || true
+  done
+  return 0
+}
+
+shopt -s nullglob
+for buf in "$MAXY_HOOK_BUFFER_DIR"/*.jsonl; do
+  [[ -f "$buf" ]] || continue
+  case "$(basename "$buf")" in
+    .*) continue;;
+  esac
+  lock="${buf}.lock"
+  if ! _drain_acquire_lock "$lock"; then
+    mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+    printf '[hook-propagate-error] reason=lock-timeout parentSession=%s buffer=%s\n' \
+      "$PARENT_SESSION" "$(basename "$buf")" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null || true
+    continue
+  fi
+  # Re-check existence under lock — a peer drainer may have claimed it
+  # between our `for` iteration and our lock acquisition.
+  if [[ ! -f "$buf" ]]; then
+    rmdir "$lock" 2>/dev/null || true
+    continue
+  fi
+  CLAIMED="$MAXY_HOOK_BUFFER_DIR/claimed/$(basename "$buf" .jsonl)-${NOW_EPOCH}-$$.jsonl"
+  if ! mv "$buf" "$CLAIMED" 2>/dev/null; then
+    rmdir "$lock" 2>/dev/null || true
+    mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+    printf '[hook-propagate-error] reason=claim-mv parentSession=%s buffer=%s\n' \
+      "$PARENT_SESSION" "$(basename "$buf")" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null || true
+    continue
+  fi
+  rmdir "$lock" 2>/dev/null || true
+
+  # Ground-truth observed count: non-empty lines in the claimed file. The
+  # printf-success N_EMITTED is incremented independently below, so a
+  # printf failure (SIGPIPE on a closed downstream pipe, EIO on stdout)
+  # produces N_OBSERVED > N_EMITTED — the propagation regression signal
+  # the census promises. The two counters must not be bumped together.
+  BUF_LINES=$(grep -c . "$CLAIMED" 2>/dev/null || echo 0)
+  N_OBSERVED=$((N_OBSERVED + BUF_LINES))
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    [[ -z "$line" ]] && continue
+    if printf '[hook-propagate] %s\n' "$line" 2>/dev/null; then
+      N_EMITTED=$((N_EMITTED+1))
+    fi
+  done <"$CLAIMED"
+  TARGET="$MAXY_HOOK_BUFFER_DIR/consumed/$(basename "$CLAIMED")"
+  if ! mv "$CLAIMED" "$TARGET" 2>/dev/null; then
+    mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+    printf '[hook-propagate-error] reason=consumed-mv parentSession=%s buffer=%s\n' \
+      "$PARENT_SESSION" "$(basename "$CLAIMED")" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null || true
+  fi
+done
+shopt -u nullglob
+
+printf '[hook-propagate-census] parentSession=%s subagentHooksObserved=%d attachmentsEmitted=%d\n' \
+  "$PARENT_SESSION" "$N_OBSERVED" "$N_EMITTED"
+
+mkdir -p "$(dirname "$MAXY_HOOK_SERVER_LOG")" 2>/dev/null
+printf '[hook-propagate-census] parentSession=%s subagentHooksObserved=%d attachmentsEmitted=%d\n' \
+  "$PARENT_SESSION" "$N_OBSERVED" "$N_EMITTED" >>"$MAXY_HOOK_SERVER_LOG" 2>/dev/null || true
+
+exit 0

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

@@ -8,72 +8,110 @@ 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, 566) ───
   # The admin seat is orchestration + clarification + delivery only.
   # Write/Edit/MultiEdit/Bash/WebFetch/WebSearch are specialist-owned —
   # content-producer for authoring, research-assistant for research, the
   # shell tools for whichever specialist owns the workflow that needs them.
   # In-window Task subagents must keep these tools (Task 222 regression
-  # class) — the discriminator is the transcript_path: Claude Code stores
-  # subagent turns in separate `*/subagents/agent-*.jsonl` files.
+  # class). Maxy MCP `Agent`-spawned specialists are separate top-level
+  # `claude rc` processes — they have no `parent_tool_use_id` but pty-spawner
+  # stamps `MAXY_SPECIALIST=<name>` on the child env (pty-spawner.ts:1601).
+  #
+  # Discriminator (union of positive markers, never path-shape inference):
+  #   parent_tool_use_id non-empty  → in-window Task subagent (allow)
+  #   $MAXY_SPECIALIST non-empty    → maxy MCP Agent specialist (allow)
+  #   $MAXY_SESSION_ROLE = admin    → admin-direct (block, orchestration-only)
+  #   none of the above             → fail closed (missing-marker)
   #
-  # Admin direct → exit 2 with dispatch hint.
-  # Subagent → exit 0 (passthrough).
-  # Missing/malformed transcript_path → fail-closed block (matches Task 222).
+  # Adding a future spawn shape that lands neither marker surfaces as a loud
+  # `reason=missing-marker` block, not a silent passthrough or a silent
+  # admin-direct block on legitimate specialist work.
   case "$TOOL_NAME" in
     Write|Edit|MultiEdit|Bash|WebFetch|WebSearch)
-      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:-}"
+      SESSION_ROLE="${MAXY_SESSION_ROLE:-}"
+      if [ -n "$PARENT_TOOL_USE_ID" ] || [ -n "$SPECIALIST" ]; then
+        # Subagent — passthrough. Tool name resolves on the subagent's
+        # own frontmatter `tools:` allowlist downstream.
+        SOURCE="task-subagent"
+        if [ -n "$SPECIALIST" ] && [ -n "$PARENT_TOOL_USE_ID" ]; then
+          SOURCE="task-subagent+mcp-specialist"
+        elif [ -n "$SPECIALIST" ]; then
+          SOURCE="mcp-specialist"
+        fi
+        echo "[admin-tool-gate] role=subagent parent_tool_use_id=${PARENT_TOOL_USE_ID:--} specialist=${SPECIALIST:--} session_role=${SESSION_ROLE:--} tool=${TOOL_NAME} decision=allow source=${SOURCE}" >&2
+      elif [ "$SESSION_ROLE" = "admin" ]; then
+        # Admin direct invocation — refuse with dispatch hint.
+        case "$TOOL_NAME" in
+          Write|Edit|MultiEdit)
+            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=- session_role=admin tool=${TOOL_NAME} decision=block reason=orchestration-only owner=${OWNER}" >&2
+        hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "${TOOL_NAME}" \
+          "orchestration-only" \
+          "Blocked: \`${TOOL_NAME}\` is not callable from the admin seat. The admin seat is orchestration + clarification + delivery only — authoring, shell work, and web research are owned by specialists.
+Dispatch the work to ${OWNER} via the Agent tool."
+      else
+        # No positive marker — fail closed. A new spawn shape that lands
+        # neither parent_tool_use_id nor MAXY_SPECIALIST and is not the
+        # admin seat should surface visibly, not silently pass or silently
+        # block under the wrong reason.
+        echo "[admin-tool-gate] role=unknown parent_tool_use_id=- specialist=- session_role=${SESSION_ROLE:--} tool=${TOOL_NAME} decision=block reason=missing-marker" >&2
+        hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "${TOOL_NAME}" \
+          "missing-marker" \
+          "Blocked: \`${TOOL_NAME}\` call carries no positive role marker (no parent_tool_use_id, no MAXY_SPECIALIST, MAXY_SESSION_ROLE is not 'admin'). Failing closed so a new spawn shape cannot silently bypass orchestration gating."
+      fi
       ;;
   esac
 
@@ -84,13 +122,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 +139,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 +153,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 +170,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 +276,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 +362,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 +382,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/plugins/admin/mcp/dist/__tests__/capabilities-here.test.d.ts

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

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

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