@rubytech/create-realagent-code 0.1.254 → 0.1.256

package/payload/platform/plugins/admin/hooks/__tests__/session-end-retrospective.test.sh

@@ -1,396 +0,0 @@
-#!/usr/bin/env bash
-# Task 282 — session-end retrospective Stop hook test suite.
-#
-# Listener-mock pattern: a local Python HTTP server stands in for
-# /api/admin/log-ingest and records every POST so the assertions can read
-# every log line the hook emitted.
-#
-# Contract under test:
-#   - All log emissions go through POST /api/admin/log-ingest. Hook stderr
-#     stays silent on every path EXCEPT the gate-blocked path, which writes
-#     the three-pass retrospective instruction block to stderr (Stop-hook
-#     contract — that is how the agent receives the instruction).
-#   - Every gated-off path emits one `trigger-skipped reason=<r>` line and
-#     exits 0:
-#       role-not-admin | is-specialist | empty-stdin | missing-transcript |
-#       no-intent-match
-#   - End-intent triggers: `/end`, `/archive`, `end session`,
-#     `archive this session`, applied case-insensitively to the latest
-#     real-user message. `tool_result`-only user records are NOT the
-#     latest user message. Embedded prose ("I'll end session by 5pm")
-#     does NOT trigger.
-#   - When the intent matches and the sentinel `tool_use` of
-#     `session-retrospective-mark-complete` is absent from the JSONL:
-#     exit 2, stderr carries the instruction block,
-#     `gate-blocked sessionId=<id> reason=sentinel-absent` emitted.
-#   - When the intent matches and the sentinel `tool_use` is present:
-#     exit 0, `gate-released sessionId=<id>` emitted.
-#   - Re-entry: a second Stop fired after the sentinel call still releases
-#     (the sentinel-grep is the re-entry guard).
-#   - Per-session scoping: a sentinel in a DIFFERENT session's JSONL does
-#     NOT release the active gate.
-
-set -u
-
-HOOK="$(cd "$(dirname "$0")/.." && pwd)/session-end-retrospective.sh"
-if [[ ! -x "$HOOK" ]]; then
-  echo "FAIL: $HOOK not executable" >&2
-  exit 1
-fi
-
-OP_ID='aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb'
-OTHER_ID='99999999-7777-6666-5555-444444444444'
-
-TMPFILES=()
-LISTENER_PIDS=()
-cleanup_test_state() {
-  for pid in "${LISTENER_PIDS[@]:-}"; do
-    if [[ -n "$pid" ]]; then
-      kill "$pid" 2>/dev/null || true
-      wait "$pid" 2>/dev/null || true
-    fi
-  done
-  for f in "${TMPFILES[@]:-}"; do
-    [[ -n "$f" ]] && rm -f "$f" 2>/dev/null || true
-  done
-}
-trap cleanup_test_state EXIT
-
-PASS=0
-FAIL=0
-pass() { echo "PASS: $1"; PASS=$((PASS + 1)); }
-fail() { echo "FAIL: $1" >&2; FAIL=$((FAIL + 1)); }
-
-start_listener() {
-  REQ_LOG=$(mktemp); TMPFILES+=("$REQ_LOG")
-  LISTENER_PORT=$((39500 + RANDOM % 100))
-  python3 - "$LISTENER_PORT" "$REQ_LOG" <<'PY' &
-import sys, http.server, json
-port = int(sys.argv[1])
-log_path = sys.argv[2]
-class H(http.server.BaseHTTPRequestHandler):
-  def log_message(self, *a, **k): pass
-  def do_POST(self):
-    n = int(self.headers.get('Content-Length','0') or 0)
-    body = self.rfile.read(n).decode('utf-8','replace')
-    with open(log_path, 'a', encoding='utf-8') as f:
-      f.write(self.path + '\t' + body + '\n')
-    self.send_response(200)
-    self.send_header('Content-Type','application/json')
-    self.end_headers()
-    self.wfile.write(json.dumps({"ok": True}).encode('utf-8'))
-http.server.HTTPServer(('127.0.0.1', port), H).serve_forever()
-PY
-  LISTENER_PIDS+=("$!")
-  for _ in $(seq 1 20); do
-    if curl -sS --max-time 1 -X POST "http://127.0.0.1:${LISTENER_PORT}/ping" -d '{}' >/dev/null 2>&1; then
-      break
-    fi
-    sleep 0.1
-  done
-  : > "$REQ_LOG"
-}
-
-run_hook() {
-  local role="$1"; local specialist="$2"; local stdin_json="$3"
-  local stderr_file; stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
-  local stdout_file; stdout_file=$(mktemp); TMPFILES+=("$stdout_file")
-  printf '%s' "$stdin_json" | \
-    MAXY_SESSION_ROLE="$role" \
-    MAXY_SPECIALIST="$specialist" \
-    MAXY_UI_INTERNAL_PORT="$LISTENER_PORT" \
-    bash "$HOOK" >"$stdout_file" 2>"$stderr_file"
-  HOOK_RC=$?
-  HOOK_STDERR=$(cat "$stderr_file")
-  HOOK_STDOUT=$(cat "$stdout_file")
-  sleep 0.1
-}
-
-ingest_lines() {
-  grep -E '^/api/admin/log-ingest	' "$REQ_LOG" 2>/dev/null | python3 -c '
-import sys, json
-for raw in sys.stdin:
-  try:
-    _, body = raw.rstrip("\n").split("\t", 1)
-    d = json.loads(body)
-    if isinstance(d, dict) and isinstance(d.get("line"), str):
-      print(d["line"])
-  except Exception:
-    pass
-' || true
-}
-
-# Build a JSONL transcript from positional jq-style triples. Each triple is
-# role|text|extra where extra is one of:
-#   ""                                  → plain user/assistant text record
-#   "tool_use:<NAME>"                   → assistant record carrying a
-#                                          tool_use block of that name
-#   "tool_result"                       → user record carrying only a
-#                                          tool_result block (not a real
-#                                          user turn)
-write_transcript() {
-  local out="$1"; shift
-  : > "$out"
-  python3 - "$out" "$@" <<'PY'
-import sys, json
-out = sys.argv[1]
-spec = sys.argv[2:]
-with open(out, "w", encoding="utf-8") as f:
-    for entry in spec:
-        role, text, extra = entry.split("|", 2)
-        rec = {"type": role, "timestamp": "2026-05-24T10:00:00.000Z"}
-        if role == "user":
-            if extra == "tool_result":
-                rec["message"] = {
-                    "role": "user",
-                    "content": [
-                        {"type": "tool_result",
-                         "tool_use_id": "tu_x",
-                         "content": text or "ok"},
-                    ],
-                }
-            else:
-                rec["message"] = {"role": "user", "content": text}
-        else:
-            content_blocks = []
-            if text:
-                content_blocks.append({"type": "text", "text": text})
-            if extra.startswith("tool_use:"):
-                tool_name = extra.split(":", 1)[1]
-                content_blocks.append({
-                    "type": "tool_use",
-                    "id": f"toolu_{tool_name}",
-                    "name": tool_name,
-                    "input": {},
-                })
-            rec["message"] = {
-                "id": f"msg_{role}_{hash(text) & 0xffff:04x}",
-                "role": "assistant",
-                "content": content_blocks,
-            }
-        f.write(json.dumps(rec) + "\n")
-PY
-}
-
-envelope_for() {
-  python3 -c '
-import json, sys
-print(json.dumps({"session_id": sys.argv[1], "transcript_path": sys.argv[2]}))
-' "$1" "$2"
-}
-
-# ---------------------------------------------------------------------------
-# Case 1: role != admin → trigger-skipped reason=role-not-admin
-# ---------------------------------------------------------------------------
-start_listener
-TRANSCRIPT_PUBLIC=$(mktemp); TMPFILES+=("$TRANSCRIPT_PUBLIC")
-write_transcript "$TRANSCRIPT_PUBLIC" "user|/end|"
-ENV_PUBLIC=$(envelope_for "$OP_ID" "$TRANSCRIPT_PUBLIC")
-: > "$REQ_LOG"
-run_hook "public" "" "$ENV_PUBLIC"
-[[ "$HOOK_RC" -eq 0 ]] || fail "case-1 rc=$HOOK_RC"
-[[ -z "$HOOK_STDERR" ]] || fail "case-1 stderr must be empty, got: $HOOK_STDERR"
-if ingest_lines | grep -qE '^trigger-skipped sessionId=.* reason=role-not-admin$'; then
-  pass "case-1 role=public → trigger-skipped reason=role-not-admin"
-else
-  fail "case-1 expected role-not-admin, got: $(ingest_lines)"
-fi
-
-# ---------------------------------------------------------------------------
-# Case 2: MAXY_SPECIALIST set → trigger-skipped is-specialist
-# ---------------------------------------------------------------------------
-: > "$REQ_LOG"
-run_hook "admin" "database-operator" "$ENV_PUBLIC"
-[[ "$HOOK_RC" -eq 0 ]] || fail "case-2 rc=$HOOK_RC"
-[[ -z "$HOOK_STDERR" ]] || fail "case-2 stderr must be empty, got: $HOOK_STDERR"
-if ingest_lines | grep -qE '^trigger-skipped sessionId=.* reason=is-specialist specialist=database-operator$'; then
-  pass "case-2 specialist=database-operator → trigger-skipped is-specialist"
-else
-  fail "case-2 expected is-specialist, got: $(ingest_lines)"
-fi
-
-# ---------------------------------------------------------------------------
-# Case 3: empty stdin → trigger-skipped reason=empty-stdin
-# ---------------------------------------------------------------------------
-: > "$REQ_LOG"
-run_hook "admin" "" ""
-[[ "$HOOK_RC" -eq 0 ]] || fail "case-3 rc=$HOOK_RC"
-if ingest_lines | grep -qE '^trigger-skipped sessionId=.* reason=empty-stdin$'; then
-  pass "case-3 empty stdin → trigger-skipped reason=empty-stdin"
-else
-  fail "case-3 expected empty-stdin, got: $(ingest_lines)"
-fi
-
-# ---------------------------------------------------------------------------
-# Case 4: missing transcript_path → trigger-skipped missing-transcript
-# ---------------------------------------------------------------------------
-: > "$REQ_LOG"
-BAD_ENV=$(python3 -c 'import json,sys; print(json.dumps({"session_id": sys.argv[1]}))' "$OP_ID")
-run_hook "admin" "" "$BAD_ENV"
-[[ "$HOOK_RC" -eq 0 ]] || fail "case-4 rc=$HOOK_RC"
-if ingest_lines | grep -qE "^trigger-skipped sessionId=${OP_ID} reason=missing-transcript$"; then
-  pass "case-4 missing transcript → trigger-skipped reason=missing-transcript"
-else
-  fail "case-4 expected missing-transcript, got: $(ingest_lines)"
-fi
-
-# ---------------------------------------------------------------------------
-# Case 5: no end-intent token → trigger-skipped reason=no-intent-match
-# ---------------------------------------------------------------------------
-TRANSCRIPT_BORING=$(mktemp); TMPFILES+=("$TRANSCRIPT_BORING")
-write_transcript "$TRANSCRIPT_BORING" \
-  "user|hello|" \
-  "assistant|hi|" \
-  "user|what's the weather|"
-ENV_BORING=$(envelope_for "$OP_ID" "$TRANSCRIPT_BORING")
-: > "$REQ_LOG"
-run_hook "admin" "" "$ENV_BORING"
-[[ "$HOOK_RC" -eq 0 ]] || fail "case-5 rc=$HOOK_RC"
-[[ -z "$HOOK_STDERR" ]] || fail "case-5 stderr must be empty"
-if ingest_lines | grep -qE "^trigger-skipped sessionId=${OP_ID} reason=no-intent-match$"; then
-  pass "case-5 no intent token → trigger-skipped reason=no-intent-match"
-else
-  fail "case-5 expected no-intent-match, got: $(ingest_lines)"
-fi
-
-# ---------------------------------------------------------------------------
-# Case 6: each intent token triggers gate-blocked (sentinel absent)
-# ---------------------------------------------------------------------------
-for TOKEN in "/end" "/archive" "end session" "archive this session"; do
-  T_FILE=$(mktemp); TMPFILES+=("$T_FILE")
-  write_transcript "$T_FILE" "user|hi|" "assistant|hello|" "user|${TOKEN}|"
-  ENV_BLOCK=$(envelope_for "$OP_ID" "$T_FILE")
-  : > "$REQ_LOG"
-  run_hook "admin" "" "$ENV_BLOCK"
-  if [[ "$HOOK_RC" -ne 2 ]]; then
-    fail "case-6:${TOKEN} expected rc=2, got $HOOK_RC"
-    continue
-  fi
-  if ! ingest_lines | grep -qE "^trigger sessionId=${OP_ID} token=${TOKEN}$"; then
-    fail "case-6:${TOKEN} missing trigger line, got: $(ingest_lines)"
-    continue
-  fi
-  if ! ingest_lines | grep -qE "^gate-blocked sessionId=${OP_ID} reason=sentinel-absent$"; then
-    fail "case-6:${TOKEN} missing gate-blocked line, got: $(ingest_lines)"
-    continue
-  fi
-  if ! printf '%s' "$HOOK_STDERR" | grep -q "session-retrospective-mark-complete"; then
-    fail "case-6:${TOKEN} instruction block missing sentinel tool name on stderr"
-    continue
-  fi
-  if ! printf '%s' "$HOOK_STDERR" | grep -q "database-operator"; then
-    fail "case-6:${TOKEN} instruction block missing database-operator reference"
-    continue
-  fi
-  pass "case-6:${TOKEN} triggers gate-blocked exit 2 + instruction stderr"
-done
-
-# ---------------------------------------------------------------------------
-# Case 7: intent token + sentinel present → gate-released exit 0
-# ---------------------------------------------------------------------------
-T_RELEASE=$(mktemp); TMPFILES+=("$T_RELEASE")
-write_transcript "$T_RELEASE" \
-  "user|hi|" \
-  "assistant|hello|" \
-  "user|/end|" \
-  "assistant|running retrospective|" \
-  "assistant||tool_use:mcp__admin__session-retrospective-mark-complete"
-ENV_REL=$(envelope_for "$OP_ID" "$T_RELEASE")
-: > "$REQ_LOG"
-run_hook "admin" "" "$ENV_REL"
-[[ "$HOOK_RC" -eq 0 ]] || fail "case-7 expected rc=0, got $HOOK_RC"
-[[ -z "$HOOK_STDERR" ]] || fail "case-7 stderr must be empty, got: $HOOK_STDERR"
-if ingest_lines | grep -qE "^gate-released sessionId=${OP_ID}$"; then
-  pass "case-7 sentinel present → gate-released exit 0"
-else
-  fail "case-7 expected gate-released, got: $(ingest_lines)"
-fi
-
-# ---------------------------------------------------------------------------
-# Case 8: re-entry — Stop fires twice after sentinel call, both release
-# ---------------------------------------------------------------------------
-: > "$REQ_LOG"
-run_hook "admin" "" "$ENV_REL"
-[[ "$HOOK_RC" -eq 0 ]] || fail "case-8 second-stop rc=$HOOK_RC"
-if ingest_lines | grep -qE "^gate-released sessionId=${OP_ID}$"; then
-  pass "case-8 re-entry: second Stop after sentinel still releases"
-else
-  fail "case-8 second Stop did not emit gate-released, got: $(ingest_lines)"
-fi
-
-# ---------------------------------------------------------------------------
-# Case 9: per-session scoping — sentinel lives in a different session's
-#          JSONL; active gate must NOT release
-# ---------------------------------------------------------------------------
-T_OTHER=$(mktemp); TMPFILES+=("$T_OTHER")
-write_transcript "$T_OTHER" \
-  "user|/end|" \
-  "assistant||tool_use:mcp__admin__session-retrospective-mark-complete"
-# Active gate inspects only T_ACTIVE (no sentinel inside).
-T_ACTIVE=$(mktemp); TMPFILES+=("$T_ACTIVE")
-write_transcript "$T_ACTIVE" "user|/end|"
-ENV_ACTIVE=$(envelope_for "$OP_ID" "$T_ACTIVE")
-: > "$REQ_LOG"
-run_hook "admin" "" "$ENV_ACTIVE"
-[[ "$HOOK_RC" -eq 2 ]] || fail "case-9 expected rc=2 (other session's sentinel must not release), got $HOOK_RC"
-if ingest_lines | grep -qE "^gate-blocked sessionId=${OP_ID} reason=sentinel-absent$"; then
-  pass "case-9 per-session scoping: sentinel in another transcript does not release"
-else
-  fail "case-9 expected gate-blocked, got: $(ingest_lines)"
-fi
-
-# ---------------------------------------------------------------------------
-# Case 10: `tool_result`-only user record is NOT the latest user message;
-#           the prior real user message wins.
-# ---------------------------------------------------------------------------
-T_TR_ONLY=$(mktemp); TMPFILES+=("$T_TR_ONLY")
-write_transcript "$T_TR_ONLY" \
-  "user|/end|" \
-  "assistant||tool_use:Read" \
-  "user|noise|tool_result"
-ENV_TR=$(envelope_for "$OP_ID" "$T_TR_ONLY")
-: > "$REQ_LOG"
-run_hook "admin" "" "$ENV_TR"
-[[ "$HOOK_RC" -eq 2 ]] || fail "case-10 expected rc=2 (tool_result must not mask /end), got $HOOK_RC"
-if ingest_lines | grep -qE "^gate-blocked sessionId=${OP_ID} reason=sentinel-absent$"; then
-  pass "case-10 tool_result-only user record does not mask latest real user /end"
-else
-  fail "case-10 expected gate-blocked, got: $(ingest_lines)"
-fi
-
-# ---------------------------------------------------------------------------
-# Case 11: embedded prose does NOT trigger ("I'll end session by 5pm")
-# ---------------------------------------------------------------------------
-T_PROSE=$(mktemp); TMPFILES+=("$T_PROSE")
-write_transcript "$T_PROSE" "user|I'll end session by 5pm|"
-ENV_PROSE=$(envelope_for "$OP_ID" "$T_PROSE")
-: > "$REQ_LOG"
-run_hook "admin" "" "$ENV_PROSE"
-[[ "$HOOK_RC" -eq 0 ]] || fail "case-11 expected rc=0 (prose must not trigger), got $HOOK_RC"
-if ingest_lines | grep -qE "^trigger-skipped sessionId=${OP_ID} reason=no-intent-match$"; then
-  pass "case-11 embedded prose 'end session' does not trigger gate"
-else
-  fail "case-11 expected no-intent-match, got: $(ingest_lines)"
-fi
-
-# ---------------------------------------------------------------------------
-# Case 12: case-insensitive match — `/END` triggers like `/end`
-# ---------------------------------------------------------------------------
-T_CASE=$(mktemp); TMPFILES+=("$T_CASE")
-write_transcript "$T_CASE" "user|/END|"
-ENV_CASE=$(envelope_for "$OP_ID" "$T_CASE")
-: > "$REQ_LOG"
-run_hook "admin" "" "$ENV_CASE"
-[[ "$HOOK_RC" -eq 2 ]] || fail "case-12 expected rc=2 for /END, got $HOOK_RC"
-if ingest_lines | grep -qE "^trigger sessionId=${OP_ID} token=/end$"; then
-  pass "case-12 case-insensitive: /END normalises to /end"
-else
-  fail "case-12 expected token=/end, got: $(ingest_lines)"
-fi
-
-# ---------------------------------------------------------------------------
-# Summary
-# ---------------------------------------------------------------------------
-echo
-echo "session-end-retrospective tests: $PASS passed, $FAIL failed"
-[[ "$FAIL" -eq 0 ]]

package/payload/platform/plugins/admin/hooks/lib/admin-graph-pass-common.sh

@@ -1,239 +0,0 @@
-#!/usr/bin/env bash
-# Shared plumbing for the admin-side hook that orchestrates admin-walked
-# graph writes: `session-end-retrospective.sh` (Stop on operator end-intent).
-# Originally introduced (Task 439) as shared plumbing across two hooks; the
-# per-turn sibling was removed in Task 447 because session-end Pass 3 already
-# performs the graph-completeness sweep. The library is retained — its
-# stdin parse, role / specialist / transcript guards, log-ingest envelope,
-# and post-user tool-name walker are still the single body for the
-# remaining hook.
-#
-# Caller contract:
-#   1. Set `AGP_LOG_TAG` to the hook's identifying tag before sourcing.
-#      `session-retrospective` is the current value; the helper itself
-#      does not log under its own tag.
-#   2. Source this file.
-#   3. Call `agp_setup_logging`, `agp_read_stdin`, `agp_parse_stdin`,
-#      `agp_guard_role_specialist`, `agp_guard_transcript` in that order.
-#      Each guard exits 0 from inside the helper when its condition fires
-#      (sourced `exit` exits the caller).
-#   4. After the guards return, the hook proceeds with its event-specific
-#      body (sentinel-grep + intent token for session-end; post-turn-context
-#      fetch + directive envelope for pre-turn).
-#
-# Globals set by the helper (read by callers):
-#   INPUT                — raw stdin (empty when none piped)
-#   SESSION_ID           — parsed `session_id` field, empty on parse failure
-#   TRANSCRIPT_PATH      — parsed `transcript_path` field
-#   HOOK_EVENT_NAME      — parsed `hook_event_name` field
-#   SESSION_ID_REPORTED  — `$SESSION_ID` or the literal "unknown"
-#   UI_BASE              — `http://127.0.0.1:${MAXY_UI_INTERNAL_PORT}`
-#   LOG_INGEST_URL       — `${UI_BASE}/api/admin/log-ingest`
-#
-# Functions:
-#   agp_setup_logging          — resolves UI port + URLs, or exits 0 with
-#                                a stderr loud-fail when the port is unset
-#                                (fail-open so a missing port never bricks
-#                                the operator).
-#   agp_emit_log <line>        — POSTs `{tag, level:"info", line}` to
-#                                log-ingest; silent on network failure.
-#   agp_read_stdin             — slurps stdin into `INPUT`, leaves it empty
-#                                when no input is piped.
-#   agp_parse_stdin            — populates `SESSION_ID`, `TRANSCRIPT_PATH`,
-#                                `HOOK_EVENT_NAME`, `SESSION_ID_REPORTED`.
-#   agp_guard_role_specialist  — exits 0 with `trigger-skipped` log on
-#                                `role-not-admin` or `is-specialist`.
-#   agp_guard_transcript       — exits 0 with `trigger-skipped` log on
-#                                `empty-stdin` (when $1="require-stdin") or
-#                                `missing-transcript`.
-
-if [ -z "${AGP_LOG_TAG:-}" ]; then
-  echo "[admin-graph-pass-common] AGP_LOG_TAG not set by caller" >&2
-  exit 1
-fi
-
-agp_setup_logging() {
-  local ui_port="${MAXY_UI_INTERNAL_PORT:-}"
-  if [ -z "$ui_port" ]; then
-    echo "[${AGP_LOG_TAG}] trigger-skipped sessionId=unknown reason=missing-env env=MAXY_UI_INTERNAL_PORT" >&2
-    exit 0
-  fi
-  UI_BASE="http://127.0.0.1:${ui_port}"
-  LOG_INGEST_URL="${UI_BASE}/api/admin/log-ingest"
-}
-
-agp_emit_log() {
-  local line="$1"
-  curl -sS -o /dev/null -X POST \
-    -H 'Content-Type: application/json' \
-    --max-time 2 \
-    --data "$(AGP_TAG="$AGP_LOG_TAG" AGP_LINE="$line" python3 -c '
-import os, json
-print(json.dumps({"tag": os.environ["AGP_TAG"], "level": "info", "line": os.environ["AGP_LINE"]}))
-')" \
-    "$LOG_INGEST_URL" 2>/dev/null || true
-}
-
-agp_read_stdin() {
-  INPUT=""
-  if [ ! -t 0 ]; then
-    INPUT=$(cat)
-  fi
-}
-
-agp_parse_stdin() {
-  local parsed
-  parsed=$(printf '%s' "$INPUT" | python3 -c '
-import sys, json
-try:
-    d = json.load(sys.stdin)
-    sid = d.get("session_id", "") or ""
-    tpath = d.get("transcript_path", "") or ""
-    event = d.get("hook_event_name", "") or ""
-    print(f"{sid}\t{tpath}\t{event}")
-except Exception:
-    print("\t\t")
-' 2>/dev/null)
-  SESSION_ID="${parsed%%	*}"
-  local rest="${parsed#*	}"
-  TRANSCRIPT_PATH="${rest%%	*}"
-  HOOK_EVENT_NAME="${rest#*	}"
-  SESSION_ID_REPORTED="${SESSION_ID:-unknown}"
-}
-
-agp_guard_role_specialist() {
-  if [ "${MAXY_SESSION_ROLE:-}" != "admin" ]; then
-    agp_emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=role-not-admin"
-    exit 0
-  fi
-  # Recursion guard. A specialist subagent dispatched via the Task tool
-  # (e.g. database-operator running the operator's graph writes) carries
-  # `MAXY_SPECIALIST=<name>` on the PTY env. Skip — the hooks only fire
-  # for the operator's own admin session.
-  #
-  # Invariant the PTY spawner is expected to honour: `MAXY_SPECIALIST` is
-  # either set to a non-empty specialist name OR absent. An explicit empty
-  # string from a wrapper would slip the recursion guard here (`-n ""` is
-  # false) — that would be a defect at the spawn site, not here.
-  if [ -n "${MAXY_SPECIALIST:-}" ]; then
-    agp_emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=is-specialist specialist=${MAXY_SPECIALIST}"
-    exit 0
-  fi
-}
-
-# Usage: agp_guard_transcript [require-stdin]
-# Pass `require-stdin` (session-end-retrospective) to emit `empty-stdin` on a
-# blank `INPUT`. Without the flag, parse failure on a non-empty INPUT
-# collapses to `missing-transcript` cleanly.
-agp_guard_transcript() {
-  if [ "${1:-}" = "require-stdin" ] && [ -z "$INPUT" ]; then
-    agp_emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=empty-stdin"
-    exit 0
-  fi
-  if [ -z "$SESSION_ID" ] || [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
-    agp_emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=missing-transcript"
-    exit 0
-  fi
-}
-
-# Walks $TRANSCRIPT_PATH and reports, in one line on stdout:
-#   <real-user-present:yes|no>\t<matched-tool-name-or-empty>
-# A "real user" record matches `session-end-retrospective.sh`'s `is_real_user`
-# — `type=user, message.role=user`, content is a string OR a list with at
-# least one non-`tool_result` block. `tool_result`-only user records are tool
-# replies, never turn starts.
-#
-# Every assistant `tool_use` block that appears AFTER the latest real-user
-# record is matched against the alternation passed as `$1` (an extended-regex
-# alternation of literal `tool_use.name` values). The synthetic name
-# `Task:<subagent_type>` is also matched, so callers can release on a
-# `Task` tool_use with `input.subagent_type=<name>` by including
-# `Task:<name>` in the alternation. Returns the first match encountered after
-# the latest real-user record (oldest-first) so the release log carries the
-# matched tool's actual name. Empty match means none of the release patterns
-# appeared since the operator's last turn.
-agp_scan_post_user_toolnames() {
-  local pattern="$1"
-  TRANSCRIPT_PATH="$TRANSCRIPT_PATH" AGP_PATTERN="$pattern" python3 - <<'PY'
-import os, json, re
-
-pattern = re.compile(os.environ["AGP_PATTERN"])
-path = os.environ["TRANSCRIPT_PATH"]
-
-def is_real_user(rec):
-    if not isinstance(rec, dict) or rec.get("type") != "user":
-        return False
-    msg = rec.get("message")
-    if not isinstance(msg, dict) or msg.get("role") != "user":
-        return False
-    content = msg.get("content")
-    if isinstance(content, str):
-        return True
-    if isinstance(content, list):
-        for b in content:
-            if isinstance(b, dict) and b.get("type") != "tool_result":
-                return True
-        return False
-    return True
-
-def assistant_tool_use_names(rec):
-    if not isinstance(rec, dict) or rec.get("type") != "assistant":
-        return []
-    msg = rec.get("message", {}) or {}
-    if msg.get("role") != "assistant":
-        return []
-    content = msg.get("content")
-    if not isinstance(content, list):
-        return []
-    names = []
-    for b in content:
-        if isinstance(b, dict) and b.get("type") == "tool_use":
-            n = b.get("name")
-            if not isinstance(n, str):
-                continue
-            names.append(n)
-            if n == "Task":
-                inp = b.get("input")
-                if isinstance(inp, dict):
-                    st = inp.get("subagent_type")
-                    if isinstance(st, str) and st:
-                        names.append(f"Task:{st}")
-    return names
-
-records = []
-try:
-    with open(path, "r", encoding="utf-8") as f:
-        for raw in f:
-            raw = raw.strip()
-            if not raw:
-                continue
-            try:
-                records.append(json.loads(raw))
-            except Exception:
-                continue
-except Exception:
-    print("no\t")
-    raise SystemExit(0)
-
-latest_user_idx = -1
-for i in range(len(records) - 1, -1, -1):
-    if is_real_user(records[i]):
-        latest_user_idx = i
-        break
-
-if latest_user_idx == -1:
-    print("no\t")
-    raise SystemExit(0)
-
-matched = ""
-for r in records[latest_user_idx + 1:]:
-    for n in assistant_tool_use_names(r):
-        if pattern.fullmatch(n):
-            matched = n
-            break
-    if matched:
-        break
-
-print(f"yes\t{matched}")
-PY
-}