@rubytech/create-maxy-code 0.1.157 → 0.1.159

package/payload/platform/plugins/admin/hooks/__tests__/pre-turn-graph-pass.test.sh

@@ -26,13 +26,13 @@
 #     "additionalContext":"..."}}` whose additionalContext begins with
 #     `[system: pre-turn-graph-pass-hook]`, names `database-operator` as
 #     the dispatch target, carries a `<prior-writes>` block with the
-#     fetched node, interpolates conversationId from CONVERSATION_NODE_ID,
+#     fetched node, interpolates sessionId from SESSION_NODE_ID,
 #     and carries NO `<conversation>` block (admin has the turn already).
 #     Dispatch log line carries `directive-shape=admin-walks`.
 #   - Prior-writes fetch fails (context endpoint 500): exit 0, dispatch
 #     still fires, `<prior-writes>` block resolves to `(none)`.
-#   - CONVERSATION_NODE_ID unset: exit 0, additionalContext names
-#     `conversationId: <unset>`, and no GET to /api/admin/post-turn-context
+#   - SESSION_NODE_ID unset: exit 0, additionalContext names
+#     `sessionId: <unset>`, and no GET to /api/admin/post-turn-context
 #     is attempted.
 #   - UserPromptSubmit stdin-shape regression: a synthetic UserPromptSubmit
 #     payload produces the documented stdout envelope; a stale Stop-shaped
@@ -125,7 +125,7 @@ PY
 }
 
 run_hook() {
-  # Args: role, specialist, ui_port, conversation_node_id, stdin_json
+  # Args: role, specialist, ui_port, session_node_id, stdin_json
   local role="$1"; local specialist="$2"; local ui_port="$3"
   local conv="$4"; local stdin_json="$5"
   local stderr_file; stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
@@ -137,7 +137,7 @@ run_hook() {
     env_cmd+=("MAXY_UI_INTERNAL_PORT=${ui_port}")
   fi
   if [[ -n "$conv" ]]; then
-    env_cmd+=("CONVERSATION_NODE_ID=${conv}")
+    env_cmd+=("SESSION_NODE_ID=${conv}")
   fi
   env_cmd+=("ACCOUNT_ID=acct-test-0001")
   printf '%s' "$stdin_json" | "${env_cmd[@]}" bash "$HOOK" >"$stdout_file" 2>"$stderr_file"
@@ -328,14 +328,14 @@ fi
 if ! printf '%s' "$CTX_BODY" | grep -q 'database-operator'; then
   fail "case-5 additionalContext must name the database-operator dispatch target"
 fi
-if ! printf '%s' "$CTX_BODY" | grep -q "conversationId: ${CONV_ID}"; then
-  fail "case-5 additionalContext must interpolate conversationId=${CONV_ID}"
+if ! printf '%s' "$CTX_BODY" | grep -q "sessionId: ${CONV_ID}"; then
+  fail "case-5 additionalContext must interpolate sessionId=${CONV_ID}"
 fi
 if ! printf '%s' "$CTX_BODY" | grep -q 'KnowledgeDocument'; then
   fail "case-5 additionalContext <prior-writes> must include fetched labels"
 fi
-if ingest_lines | grep -qE "^dispatch sessionId=${OP_ID} conversationId=${CONV_ID} directive-shape=admin-walks "; then
-  pass "case-5 dispatch path → exit 0 + JSON envelope with prior-writes, conversationId, admin-walks shape"
+if ingest_lines | grep -qE "^dispatch claudeSessionId=${OP_ID} sessionId=${CONV_ID} directive-shape=admin-walks "; then
+  pass "case-5 dispatch path → exit 0 + JSON envelope with prior-writes, sessionId, admin-walks shape"
 else
   fail "case-5 expected dispatch log line with directive-shape=admin-walks, got: $(ingest_lines)"
 fi
@@ -356,7 +356,7 @@ else
 fi
 
 # ---------------------------------------------------------------------------
-# Case 7: CONVERSATION_NODE_ID unset → conversationId:<unset>, no context GET.
+# Case 7: SESSION_NODE_ID unset → sessionId:<unset>, no context GET.
 # ---------------------------------------------------------------------------
 cat > "$CTX_FILE" <<'JSON'
 {"writes":[]}
@@ -365,12 +365,12 @@ JSON
 run_hook "admin" "" "$LISTENER_PORT" "" "$ENV_BASIC"
 [[ "$HOOK_RC" -eq 0 ]] || fail "case-7 expected rc=0, got $HOOK_RC"
 CTX_BODY=$(additional_context)
-if ! printf '%s' "$CTX_BODY" | grep -q 'conversationId: <unset>'; then
-  fail "case-7 additionalContext must contain 'conversationId: <unset>'"
+if ! printf '%s' "$CTX_BODY" | grep -q 'sessionId: <unset>'; then
+  fail "case-7 additionalContext must contain 'sessionId: <unset>'"
 fi
 GET_COUNT=$(context_get_count)
 if [[ "$GET_COUNT" == "0" ]]; then
-  pass "case-7 CONVERSATION_NODE_ID unset → no GET /api/admin/post-turn-context attempted"
+  pass "case-7 SESSION_NODE_ID unset → no GET /api/admin/post-turn-context attempted"
 else
   fail "case-7 expected zero context GETs, got: $GET_COUNT"
 fi

package/payload/platform/plugins/admin/hooks/__tests__/turn-completed-graph-write.test.sh

@@ -194,7 +194,7 @@ fi
 # --- Case 5 (Task 177): ordered-turns happy path -----------------------
 # Transcript with four turns: user-A, asst-A-reply, user-B, asst-B-reply.
 # Envelope `turns` array must carry exactly that order, oldest first.
-# Envelope shape: { turns, conversationId, accountId, occurredAt } — no
+# Envelope shape: { turns, sessionId, accountId, occurredAt } — no
 # top-level operatorMessage / assistantReply.
 ORDERED_TRANSCRIPT=$(mktemp); TMPFILES+=("$ORDERED_TRANSCRIPT")
 {

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

@@ -0,0 +1,242 @@
+#!/usr/bin/env bash
+# Shared plumbing for the two admin-side hooks that orchestrate admin-walked
+# graph writes: `pre-turn-graph-pass.sh` (UserPromptSubmit) and
+# `session-end-retrospective.sh` (Stop on operator end-intent). Task 439.
+#
+# Both hooks are the same process — same stdin parse, same role / specialist
+# / transcript guards, same log-ingest envelope, same admin-walks contract
+# dispatching per-write briefs to `database-operator`. Divergence across
+# Tasks 303 → 412 → 425 → 430 → 282 made shared plumbing a recurring-bug
+# surface; this file is the single body. Only the trigger-specific gating
+# and the dispatch directive text live in each hook.
+#
+# Caller contract:
+#   1. Set `AGP_LOG_TAG` to the hook's identifying tag before sourcing.
+#      `pre-turn-graph-pass` and `session-retrospective` are the two
+#      current values; 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`. The pre-turn-graph-pass hook calls without the flag because
+# its `wrong-hook-event` guard already runs before this point and 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
+}

package/payload/platform/plugins/admin/hooks/per-turn-graph-pass-gate.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Stop hook — per-turn gate. Task 440.
+#
+# Mirrors `session-end-retrospective.sh`'s structural primitive (exit 2 +
+# stderr instruction + sentinel-grep release) but fires on every admin turn
+# end rather than only on operator end-intent. Closes the gap left when
+# Task 425 moved the per-turn graph pass off Stop onto UserPromptSubmit:
+# the UserPromptSubmit `additionalContext` directive carries the prior-writes
+# skip-list and the instruction, but admin can silently drop the directive
+# because UserPromptSubmit's only blocking shape erases the prompt without
+# feeding stderr to Claude. The structural fix is here — Stop's exit-2
+# stderr-to-Claude contract gives the gate a release path admin can act on.
+#
+# Release conditions, evaluated against the operator's JSONL since the
+# latest real-user message (string content OR a content list with at least
+# one non-`tool_result` block):
+#   A. admin dispatched the writes — a `Task` `tool_use` whose
+#      `input.subagent_type` is `database-operator` appeared.
+#   B. admin declined the writes — a `tool_use` whose `name` is exactly
+#      `mcp__admin__pre-turn-graph-pass-skip` appeared. The sentinel takes a
+#      `reason` string (free-form, e.g. `no-new-entities`,
+#      `turn-is-acknowledgement`); the tool records the call for audit but
+#      takes no graph action.
+#
+# Either release path emits `gate-released sessionId=<id> via=<dispatch|skip-sentinel>`
+# and exits 0. Both Stop-hook tags emit independently and compose: the
+# session-end retrospective gates only on `/end` intent and uses its own
+# sentinel; this hook gates every turn and uses the two release patterns
+# above.
+#
+# Recursion guard — the shared `agp_guard_role_specialist` skips when
+# `MAXY_SPECIALIST` is set, so the database-operator subagent's own turn
+# end never re-triggers this gate.
+#
+# Loop-safety — once release path A or B fires, the matching tool_use sits
+# in the JSONL and every subsequent Stop on the same operator-prompt window
+# sees it and exits 0 with `gate-released`. The Task 412 loop case is
+# avoided because the release decision is JSONL-based, never a re-fire of
+# the directive.
+#
+# Input: Claude Code's Stop hook stdin shape
+#   { "session_id": "<intrinsic>", "transcript_path": "<jsonl path>", ... }
+
+set -uo pipefail
+
+AGP_LOG_TAG="per-turn-graph-pass-gate"
+AGP_LIB="$(dirname "$0")/lib/admin-graph-pass-common.sh"
+if [ ! -f "$AGP_LIB" ]; then
+  echo "[${AGP_LOG_TAG}] trigger-skipped sessionId=unknown reason=missing-helper path=${AGP_LIB}" >&2
+  exit 0
+fi
+# shellcheck source=lib/admin-graph-pass-common.sh
+source "$AGP_LIB"
+
+agp_setup_logging
+agp_read_stdin
+agp_parse_stdin
+agp_guard_role_specialist
+agp_guard_transcript require-stdin
+
+# Release alternation: the MCP-prefixed skip-sentinel name, or a Task
+# tool_use with `input.subagent_type=database-operator` (matched as the
+# synthetic name `Task:database-operator` by the helper).
+RELEASE_PATTERN='mcp__admin__pre-turn-graph-pass-skip|Task:database-operator'
+
+INSPECTION=$(agp_scan_post_user_toolnames "$RELEASE_PATTERN")
+USER_PRESENT="${INSPECTION%%	*}"
+MATCHED_NAME="${INSPECTION#*	}"
+
+if [ "$USER_PRESENT" != "yes" ]; then
+  # No real-user message in the transcript yet — e.g. the SessionStart
+  # bootstrap turn, an empty transcript, or a session that only contains
+  # tool_result-shaped user records. Nothing to gate against.
+  agp_emit_log "trigger-skipped sessionId=${SESSION_ID} reason=no-real-user"
+  exit 0
+fi
+
+if [ -n "$MATCHED_NAME" ]; then
+  case "$MATCHED_NAME" in
+    Task:database-operator)
+      VIA="dispatch"
+      ;;
+    mcp__admin__pre-turn-graph-pass-skip)
+      VIA="skip-sentinel"
+      ;;
+    *)
+      VIA="unknown"
+      ;;
+  esac
+  agp_emit_log "gate-released sessionId=${SESSION_ID} via=${VIA}"
+  exit 0
+fi
+
+agp_emit_log "gate-blocked sessionId=${SESSION_ID} reason=sentinel-absent"
+
+cat >&2 <<'INSTRUCTION'
+Before this turn closes, do the per-turn graph pass. Scan the operator's latest message for any new graph-worthy content not already covered by the prior-writes block in this turn's pre-turn-graph-pass directive — mentions of named entities, ideas or learnings the operator stated, contacts named for the first time, tasks the operator committed to, decisions, anything the schema admits.
+
+For each candidate write, dispatch one Task to the `database-operator` specialist with a brief that names the label, the relevant properties, and (when attaching to an existing node) the elementId from the prior-writes list. Skip writes the prior-writes list already covers.
+
+If the turn supports no new writes, call the `pre-turn-graph-pass-skip` MCP tool with a short `reason` (e.g. `no-new-entities`, `turn-is-acknowledgement`) so the gate releases. Calling that tool is the deterministic signal that you considered the turn and chose not to write.
+
+Either path releases this gate and lets the turn close. Do not surface this dispatch in your reply to the operator.
+INSTRUCTION
+
+exit 2

package/payload/platform/plugins/admin/hooks/pre-turn-graph-pass.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# UserPromptSubmit hook — pre-turn graph pass. Tasks 425, 430.
+# UserPromptSubmit hook — pre-turn graph pass. Tasks 425, 430, 439.
 #
 # Fires once per admin-agent operator prompt submission. Emits a
 # directive into the admin agent's `additionalContext` that instructs
@@ -9,32 +9,19 @@
 # per candidate write. Admin is the session-walker; the specialist only
 # sees a narrowly-scoped per-write brief, never the conversation.
 #
-# Task 430 corrects the Task 425 orchestration shape. The Task 425 hook
-# packaged the full conversation blob into the specialist's prompt; that
-# collapsed the data channel and the instruction channel into one
-# context, so operator prose pattern-matching as a writer-binding
-# instruction ("memory-update is denied this session") was treated as
-# binding and the pass self-denied. Same failure class as the writer-POV
-# schema doctrine read as binding the agent (Task 199 / 995). The
-# session-end retrospective never had this defect because admin walked
-# the transcript itself and dispatched per-item briefs to the
-# specialist — Task 430 brings the per-turn pass to the same shape.
+# Task 430 corrects the Task 425 orchestration shape (the Task 425 hook
+# packaged the full conversation blob into the specialist's prompt and
+# collapsed data and instruction channels into one context, so operator
+# prose pattern-matching as a writer-binding instruction was treated as
+# binding and the pass self-denied — same failure class as the writer-POV
+# schema doctrine read as binding the agent, Tasks 199 / 995).
 #
-# Supersedes Task 412's Stop-hook registration. The Stop hook fired on
-# every assistant `end_turn`, including the agent's own ack after the
-# dispatch, producing an unbounded loop. Firing on `UserPromptSubmit`
-# fires once per operator turn and removes the loop primitive entirely.
-# The agent's response to the most recent operator turn is not covered
-# by a per-turn pass until the next operator turn; the
-# `session-end-retrospective.sh` Stop hook walks the full transcript at
-# `/end` and picks up the final assistant reply.
-#
-# The doctrinal early exits remain:
-#   - MAXY_SESSION_ROLE must equal "admin"  → reason=role-not-admin
-#   - MAXY_SPECIALIST must be empty         → reason=is-specialist
-# `missing-transcript` is retained as a safety exit (the prior-writes
-# context fetch still needs a real session). `wrong-hook-event` rejects
-# stale Stop-shaped fires.
+# Task 439 converges the shared plumbing — stdin parse, role / specialist
+# / transcript guards, log-ingest envelope — with `session-end-retrospective.sh`
+# via `lib/admin-graph-pass-common.sh`. The only event-specific code in
+# this hook is the wrong-hook-event check, the post-turn-context fetch,
+# the directive-body composition, and the UserPromptSubmit JSON envelope
+# emission on stdout.
 #
 # Input: Claude Code's UserPromptSubmit hook stdin shape
 #   { "session_id": "<intrinsic>", "transcript_path": "<jsonl path>",
@@ -46,76 +33,45 @@
 # Output: stdout JSON of the documented UserPromptSubmit shape:
 #   { "hookSpecificOutput": { "hookEventName": "UserPromptSubmit",
 #                              "additionalContext": "<directive body>" } }
-# exit 0. The directive body is self-contained: it names the dispatch
-# shape, the skip-list, and the silent-execution rule at fire time, so
-# the admin agent does not need a matching IDENTITY.md section to act
-# on it (Task 437 — IDENTITY is operator-facing prose, not a protocol
-# manual). The agent performs the per-write dispatches as a background
-# pass and then continues with its normal response to the operator.
+# exit 0.
 
 set -uo pipefail
 
-UI_PORT="${MAXY_UI_INTERNAL_PORT:-}"
-if [ -z "$UI_PORT" ]; then
-  echo "[pre-turn-graph-pass] trigger-skipped sessionId=unknown reason=missing-env env=MAXY_UI_INTERNAL_PORT" >&2
+AGP_LOG_TAG="pre-turn-graph-pass"
+AGP_LIB="$(dirname "$0")/lib/admin-graph-pass-common.sh"
+if [ ! -f "$AGP_LIB" ]; then
+  echo "[${AGP_LOG_TAG}] trigger-skipped sessionId=unknown reason=missing-helper path=${AGP_LIB}" >&2
   exit 0
 fi
-UI_BASE="http://127.0.0.1:${UI_PORT}"
-LOG_INGEST_URL="${UI_BASE}/api/admin/log-ingest"
-CONTEXT_URL="${UI_BASE}/api/admin/post-turn-context"
+# shellcheck source=lib/admin-graph-pass-common.sh
+source "$AGP_LIB"
 
-emit_log() {
-  local line="$1"
-  curl -sS -o /dev/null -X POST \
-    -H 'Content-Type: application/json' \
-    --max-time 2 \
-    --data "$(python3 -c '
-import sys, json
-print(json.dumps({"tag": "pre-turn-graph-pass", "level": "info", "line": sys.argv[1]}))
-' "$line")" \
-    "$LOG_INGEST_URL" 2>/dev/null || true
-}
-
-INPUT=""
-if [ ! -t 0 ]; then
-  INPUT=$(cat)
-fi
+agp_setup_logging
+CONTEXT_URL="${UI_BASE}/api/admin/post-turn-context"
 
-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%%	*}"
-REST="${PARSED#*	}"
-TRANSCRIPT_PATH="${REST%%	*}"
-HOOK_EVENT_NAME="${REST#*	}"
-SESSION_ID_REPORTED="${SESSION_ID:-unknown}"
+agp_read_stdin
+agp_parse_stdin
 
+# Wrong-hook-event guard. Pre-turn-graph-pass is UserPromptSubmit-only;
+# reject stale Stop-shaped payloads before the role / transcript guards
+# run so the operator observes a `wrong-hook-event` skip line, not a
+# misleading `missing-transcript`.
 if [ -n "$HOOK_EVENT_NAME" ] && [ "$HOOK_EVENT_NAME" != "UserPromptSubmit" ]; then
-  emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=wrong-hook-event event=${HOOK_EVENT_NAME}"
-  exit 0
-fi
-if [ "${MAXY_SESSION_ROLE:-}" != "admin" ]; then
-  emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=role-not-admin"
-  exit 0
-fi
-if [ -n "${MAXY_SPECIALIST:-}" ]; then
-  emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=is-specialist specialist=${MAXY_SPECIALIST}"
-  exit 0
-fi
-if [ -z "$SESSION_ID" ] || [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
-  emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=missing-transcript"
+  agp_emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=wrong-hook-event event=${HOOK_EVENT_NAME}"
   exit 0
 fi
 
-CONVERSATION_ID="${CONVERSATION_NODE_ID:-}"
+agp_guard_role_specialist
+agp_guard_transcript
+
+# Task 429 — the env var carries the graph `:Conversation.sessionId`.
+# Claude Code's own stdin `session_id` field (parsed into `SESSION_ID`
+# by `agp_parse_stdin`) is a distinct identifier (JSONL filename); one
+# graph sessionId can map to many Claude session ids. Shadow the lib's
+# `SESSION_ID` into `CLAUDE_SESSION_ID` so the rest of this hook can
+# refer to the graph identifier as `SESSION_ID` without collision.
+CLAUDE_SESSION_ID="$SESSION_ID"
+SESSION_ID="${SESSION_NODE_ID:-}"
 
 # Fetch the actual content of every node already written under this
 # conversation, account-scoped. The route runs loopback-only — the hook
@@ -125,9 +81,9 @@ CONVERSATION_ID="${CONVERSATION_NODE_ID:-}"
 # elementId admin already resolved when attaching to an existing node).
 PRIOR_WRITES="(none)"
 PRIOR_WRITES_COUNT=0
-if [ -n "$CONVERSATION_ID" ]; then
+if [ -n "$SESSION_ID" ]; then
   CONTEXT_JSON=$(curl -sS --max-time 5 -G \
-    --data-urlencode "conversationId=${CONVERSATION_ID}" \
+    --data-urlencode "sessionId=${SESSION_ID}" \
     --data-urlencode "accountId=${ACCOUNT_ID:-}" \
     "$CONTEXT_URL" 2>/dev/null || echo '')
   if [ -n "$CONTEXT_JSON" ]; then
@@ -171,8 +127,8 @@ fi
 # Compose the directive body before logging so contextBytes reflects
 # the actual payload size handed to admin (skip-list + directive prose).
 DIRECTIVE_BODY=$(ACCOUNT_ID_OUT="${ACCOUNT_ID:-<unset>}" \
-  SESSION_ID_OUT="${SESSION_ID}" \
-  CONVERSATION_ID_OUT="${CONVERSATION_ID:-<unset>}" \
+  CLAUDE_SESSION_ID_OUT="${CLAUDE_SESSION_ID}" \
+  SESSION_ID_OUT="${SESSION_ID:-<unset>}" \
   PRIOR_WRITES_OUT="${PRIOR_WRITES}" \
   python3 - <<'PY'
 import os
@@ -186,8 +142,8 @@ body = (
     "If the turn supports no new writes, dispatch nothing. "
     "Do not surface these dispatches in your reply to the operator. After the dispatches return, continue with your normal response to the operator's prompt.\n\n"
     f"accountId: {os.environ['ACCOUNT_ID_OUT']}\n"
-    f"sessionId: {os.environ['SESSION_ID_OUT']}\n"
-    f"conversationId: {os.environ['CONVERSATION_ID_OUT']}\n\n"
+    f"claudeSessionId: {os.environ['CLAUDE_SESSION_ID_OUT']}\n"
+    f"sessionId: {os.environ['SESSION_ID_OUT']}\n\n"
     "<prior-writes>\n"
     f"{os.environ['PRIOR_WRITES_OUT']}\n"
     "</prior-writes>\n"
@@ -197,7 +153,7 @@ PY
 )
 CONTEXT_BYTES=${#DIRECTIVE_BODY}
 
-emit_log "dispatch sessionId=${SESSION_ID} conversationId=${CONVERSATION_ID:-<unset>} directive-shape=admin-walks priorWritesCount=${PRIOR_WRITES_COUNT} contextBytes=${CONTEXT_BYTES} ms=0"
+agp_emit_log "dispatch claudeSessionId=${CLAUDE_SESSION_ID} sessionId=${SESSION_ID:-<unset>} directive-shape=admin-walks priorWritesCount=${PRIOR_WRITES_COUNT} contextBytes=${CONTEXT_BYTES} ms=0"
 
 # Emit the documented UserPromptSubmit JSON envelope on stdout. Python
 # handles JSON encoding so embedded newlines, quotes, and backslashes