@rubytech/create-maxy-code 0.1.64 → 0.1.66

package/package.json

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

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

@@ -129,7 +129,7 @@ Tools are available via the `admin` MCP server.
 - `hooks/pre-tool-use.sh` — enforces admin agent write boundaries
 - `hooks/playwright-file-guard.sh` — rewrites file:// URLs to a backgrounded loopback http.server before Playwright sees them
 - `hooks/webfetch-preflight.mjs` — short-circuits WebFetch on JS-SPA shells with a structured `WEBFETCH_CANNOT_READ_JS_SPA` error so the agent surfaces a loud failure to the owner instead of paying the 60s extraction timeout. Fail-open on any internal error.
-- `hooks/turn-completed-graph-write.sh` — Stop hook fired once per completed admin-agent turn. Gates on `MAXY_SESSION_ROLE=admin` + `MAXY_IS_RECORDER!=1` so it never recurses into the recorder PTY or fires on public sessions. **Task 134 redesign** — the recorder is spawned via the same route Sidebar uses. ONE POST to `POST /api/admin/claude-sessions`, body carries `{specialist:'database-operator', initialMessage:'<instruction>\n\n<last-turn-text>', originatingSessionId:<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 `/<originatingSessionId>/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 153** — `initialMessage` rides on the `/spawn` body as a trailing positional argv to `claude`, so the database-operator session's JSONL first `role=user` line equals `"update the graph with any new or missing information or intent\n\n<last-turn-text>"` 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|last-turn-empty>` line. The spawn body carries `originatingSessionId` as a structural top-level field so downstream loggers read the operator id without parsing prose. 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.
+- `hooks/turn-completed-graph-write.sh` — 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 175** — `initialMessage` is now a JSON-stringified envelope conforming to the database-operator agent file's `## Input shape`. Top-level keys exactly: `operatorMessage`, `assistantReply`, `toolCalls`, `conversationId`, `accountId`, `occurredAt`. No leading instruction prose. `toolCalls[].input` and `toolCalls[].output` are native JSON values, never re-stringified. 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.
 
 ## Session identifiers (Task 135)
 

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

@@ -1,18 +1,21 @@
 #!/usr/bin/env bash
-# Task 129/131 regression test for the Stop hook.
+# Task 129/131/165/175 regression test for the Stop hook.
 #
 # Contract:
 #   - Every log emission goes through `POST /api/admin/log-ingest`. Hook
 #     stderr is silent on every path.
 #   - Every gated-off path emits one `trigger-skipped` line carrying a
 #     distinct `reason=` (role-not-admin | is-recorder | empty-stdin |
-#     missing-transcript | last-turn-empty).
+#     missing-transcript | conversation-empty).
 #   - Happy path emits exactly ONE `trigger` line carrying
-#     `lastTurnBytes=<n>` (Task 131 replaces `filteredRecords`) and
-#     exactly ONE `recorder-spawn` POST. The body carries the operator
-#     session id as `originatingSessionId` and an `initialMessage` of
-#     the form `<instruction>\n\n<last-turn-text>` — no transcript tail,
-#     no `Conversation id:` prose.
+#     `conversationBytes=<n>` and exactly ONE POST to
+#     `/api/admin/claude-sessions`. The body carries the operator
+#     session id as `adminSessionId` and an `initialMessage` whose value
+#     is a JSON-stringified object with EXACTLY the six keys declared by
+#     the database-operator agent file: operatorMessage, assistantReply,
+#     toolCalls, conversationId, accountId, occurredAt. No leading
+#     instruction prose. No `Conversation id:` prose. No
+#     `user:`/`assistant:` walk format.
 #   - The hook never writes the legacy `spawn-with-input` / `fired` stderr
 #     lines.
 #
@@ -30,6 +33,7 @@ if [[ ! -x "$HOOK" ]]; then
 fi
 
 OP_ID='aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb'
+ACCT_ID='acct-test-0001'
 
 TMPFILES=()
 LISTENER_PIDS=()
@@ -92,6 +96,7 @@ run_hook() {
     MAXY_SESSION_ROLE="$role" \
     MAXY_SPECIALIST="$specialist" \
     MAXY_UI_INTERNAL_PORT="$LISTENER_PORT" \
+    ACCOUNT_ID="$ACCT_ID" \
     bash "$HOOK" >"$stdout_file" 2>"$stderr_file"
   HOOK_RC=$?
   HOOK_STDERR=$(cat "$stderr_file")
@@ -116,8 +121,7 @@ for raw in sys.stdin:
 
 # Common envelope: a valid Stop-hook stdin shape with a real UUID + a
 # transcript file the hook can read. Transcript has one user turn and
-# one assistant turn — Task 131 picks the most-recent assistant text as
-# the last-turn payload.
+# one assistant turn.
 start_listener
 TRANSCRIPT=$(mktemp); TMPFILES+=("$TRANSCRIPT")
 {
@@ -184,8 +188,7 @@ run_hook "admin" "" "$ENVELOPE"
 [[ -z "$HOOK_STDERR" ]] || fail "case-5 stderr must be empty, got: $HOOK_STDERR"
 
 # 5a. exactly ONE `trigger` log-ingest line carrying the operator session id
-#     and `conversationBytes=<n>` (Task 165 — full transcript walker
-#     replaces last-turn-only extractor; field is renamed for clarity).
+#     and `conversationBytes=<n>`.
 TRIGGER_COUNT=$(ingest_lines | grep -cE "^trigger sessionId=${OP_ID} turnIndex=0 transcriptBytes=[0-9]+ conversationBytes=[0-9]+$" || true)
 if [[ "$TRIGGER_COUNT" -eq 1 ]]; then
   pass "case-5a exactly one trigger line emitted via log-ingest carrying operator id + conversationBytes"
@@ -201,40 +204,50 @@ else
   fail "case-5b expected exactly 1 recorder-spawn POST, got $RECORDER_LINES"
 fi
 
-# 5c. Sidebar-shape body with three overrides (specialist, model,
-#     initialMessage); adminSessionId carries the operator's session id as
-#     the loopback-bypass lookup key. No senderId on the wire (the wrapper
-#     resolves it from the manager's /meta).
+# 5c. Task 175 — `initialMessage` is a JSON-stringified object with
+#     EXACTLY the six declared top-level keys. No instruction prose.
+#     `operatorMessage` / `assistantReply` carry the last user / assistant
+#     text blocks. `toolCalls` is `[]` (no tool_use in this transcript).
 RECORDER_BODY=$(grep -E '^/api/admin/claude-sessions	' "$REQ_LOG" | head -1 | cut -f2-)
 BODY_OK=$(printf '%s' "$RECORDER_BODY" | python3 -c '
-import sys, json
+import sys, json, re
 op = sys.argv[1]
-INSTRUCTION = "update the graph with any new or missing information or intent"
-# Task 165 — initialMessage carries the full transcript layout
-# "user: <text>\nassistant: <text>\n…", not just the last assistant text.
-EXPECTED_CONVERSATION = "user: hello operator\nassistant: hello, assistant reply"
+acct = sys.argv[2]
 try:
-  b = json.load(sys.stdin)
-  msg = b.get("initialMessage") or ""
+  outer = json.load(sys.stdin)
+  msg_str = outer.get("initialMessage")
+  # initialMessage must be a string carrying a JSON-stringified object.
+  if not isinstance(msg_str, str):
+    print("no:initialMessage-not-string:"+repr(type(msg_str).__name__))
+    sys.exit(0)
+  msg = json.loads(msg_str)
+  keys = set(msg.keys())
   conds = (
-    "senderId" not in b,
-    b.get("specialist") == "database-operator",
-    b.get("model") == "haiku",
-    b.get("adminSessionId") == op,
-    b.get("channel") == "browser",
-    msg == INSTRUCTION + "\n\n" + EXPECTED_CONVERSATION,
-    "Conversation id:" not in msg,
-    "Conversation transcript:" not in msg,
-    "originatingSessionId" not in b,
+    keys == {"operatorMessage", "assistantReply", "toolCalls", "conversationId", "accountId", "occurredAt"},
+    msg.get("operatorMessage") == "hello operator",
+    msg.get("assistantReply") == "hello, assistant reply",
+    msg.get("toolCalls") == [],
+    msg.get("conversationId") == op,
+    msg.get("accountId") == acct,
+    bool(re.match(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.000Z$", msg.get("occurredAt") or "")),
+    "update the graph" not in msg_str,
+    "user:" not in msg_str.lower() or "user:" not in (msg.get("operatorMessage") or "").lower(),
+    "Conversation id:" not in msg_str,
+    outer.get("specialist") == "database-operator",
+    outer.get("model") == "haiku",
+    outer.get("adminSessionId") == op,
+    outer.get("channel") == "browser",
+    "senderId" not in outer,
+    "originatingSessionId" not in outer,
   )
-  print("yes" if all(conds) else "no:"+repr(conds)+"|msg="+repr(msg))
+  print("yes" if all(conds) else "no:"+repr([(i,c) for i,c in enumerate(conds) if not c])+"|msg="+repr(msg))
 except Exception as e:
   print("parse-fail:"+str(e))
-' "$OP_ID" 2>/dev/null)
+' "$OP_ID" "$ACCT_ID" 2>/dev/null)
 if [[ "$BODY_OK" == "yes" ]]; then
-  pass "case-5c body carries full transcript layout (user: …\\nassistant: …) — Task 165"
+  pass "case-5c initialMessage is JSON envelope with exactly 6 declared keys"
 else
-  fail "case-5c body shape wrong ($BODY_OK): $RECORDER_BODY"
+  fail "case-5c envelope shape wrong ($BODY_OK): $RECORDER_BODY"
 fi
 
 # 5d. exactly ONE `spawn-request` log-ingest line
@@ -252,10 +265,9 @@ else
   pass "case-5e no legacy stderr emissions"
 fi
 
-# --- Case 6 (Task 165): transcript has zero qualifying records → --------
-#     trigger-skipped reason=conversation-empty. The hook emits the
-#     trigger line first (conversationBytes=0) and then the new skip
-#     reason.
+# --- Case 6 (Task 175): conversation-empty skip when there's no user/
+#     assistant text AND no tool_use. The hook emits the trigger line
+#     first (conversationBytes=0) and then the skip reason.
 EMPTY_TRANSCRIPT=$(mktemp); TMPFILES+=("$EMPTY_TRANSCRIPT")
 printf '{"type":"system","summary":"noop"}\n' > "$EMPTY_TRANSCRIPT"
 EMPTY_ENVELOPE=$(python3 -c '
@@ -266,7 +278,7 @@ print(json.dumps({"session_id": sys.argv[1], "transcript_path": sys.argv[2]}))
 run_hook "admin" "" "$EMPTY_ENVELOPE"
 [[ "$HOOK_RC" -eq 0 ]] || fail "case-6 rc=$HOOK_RC"
 if ingest_lines | grep -qE "^trigger-skipped sessionId=${OP_ID} reason=conversation-empty$"; then
-  pass "case-6 zero user/assistant records → trigger-skipped reason=conversation-empty emitted"
+  pass "case-6 zero user/assistant/tool records → trigger-skipped reason=conversation-empty emitted"
 else
   fail "case-6 expected trigger-skipped conversation-empty, got: $(ingest_lines)"
 fi
@@ -275,37 +287,104 @@ if grep -qE '^/api/admin/claude-sessions	' "$REQ_LOG"; then
   fail "case-6 recorder-spawn must NOT be called when conversation-empty"
 fi
 
-# --- Case 7 (Task 165): three-turn conversation walks user/assistant/user
-#     in transcript order; layout is "user: …\nassistant: …\nuser: …". ---
-THREE_TURN_TRANSCRIPT=$(mktemp); TMPFILES+=("$THREE_TURN_TRANSCRIPT")
-{
-  printf '{"type":"user","message":{"role":"user","content":"hello"}}\n'
-  printf '{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"what'"'"'s your business?"}]}}\n'
-  printf '{"type":"user","message":{"role":"user","content":"Smalleys"}}\n'
-} > "$THREE_TURN_TRANSCRIPT"
-THREE_ENVELOPE=$(python3 -c '
+# --- Case 7 (Task 175): tool-call passthrough — tool_use + tool_result
+#     pair surfaces in `toolCalls[]` with `input` and `output` as native
+#     JSON values, never re-stringified.
+TOOL_TRANSCRIPT=$(mktemp); TMPFILES+=("$TOOL_TRANSCRIPT")
+python3 - "$TOOL_TRANSCRIPT" <<'PY'
+import json, sys
+out = sys.argv[1]
+recs = [
+  {"type":"user","message":{"role":"user","content":"please write a node"}},
+  {"type":"assistant","message":{"role":"assistant","content":[
+    {"type":"tool_use","id":"toolu_001","name":"mcp__memory__memory-write","input":{"nodeType":"LocalBusiness","name":"Smalleys","nested":{"k":1}}}
+  ]}},
+  {"type":"user","message":{"role":"user","content":[
+    {"type":"tool_result","tool_use_id":"toolu_001","content":"ok: wrote LocalBusiness"}
+  ]}},
+  {"type":"assistant","message":{"role":"assistant","content":[
+    {"type":"text","text":"done"}
+  ]}},
+]
+with open(out,"w") as f:
+  for r in recs: f.write(json.dumps(r)+"\n")
+PY
+TOOL_ENVELOPE=$(python3 -c '
 import json, sys
 print(json.dumps({"session_id": sys.argv[1], "transcript_path": sys.argv[2]}))
-' "$OP_ID" "$THREE_TURN_TRANSCRIPT")
+' "$OP_ID" "$TOOL_TRANSCRIPT")
 : > "$REQ_LOG"
-run_hook "admin" "" "$THREE_ENVELOPE"
+run_hook "admin" "" "$TOOL_ENVELOPE"
 [[ "$HOOK_RC" -eq 0 ]] || fail "case-7 rc=$HOOK_RC stderr=$HOOK_STDERR"
-THREE_BODY=$(grep -E '^/api/admin/claude-sessions	' "$REQ_LOG" | head -1 | cut -f2-)
-THREE_OK=$(printf '%s' "$THREE_BODY" | python3 -c '
+TOOL_BODY=$(grep -E '^/api/admin/claude-sessions	' "$REQ_LOG" | head -1 | cut -f2-)
+TOOL_OK=$(printf '%s' "$TOOL_BODY" | python3 -c '
 import sys, json
-INSTRUCTION = "update the graph with any new or missing information or intent"
-EXPECTED = "user: hello\nassistant: what'"'"'s your business?\nuser: Smalleys"
 try:
-  b = json.load(sys.stdin)
-  msg = b.get("initialMessage") or ""
-  print("yes" if msg == INSTRUCTION + "\n\n" + EXPECTED else "no:"+repr(msg))
+  outer = json.load(sys.stdin)
+  msg = json.loads(outer.get("initialMessage"))
+  calls = msg.get("toolCalls") or []
+  if len(calls) != 1:
+    print("no:expected-1-call:"+repr(calls)); sys.exit(0)
+  c = calls[0]
+  conds = (
+    c.get("tool") == "mcp__memory__memory-write",
+    c.get("input") == {"nodeType":"LocalBusiness","name":"Smalleys","nested":{"k":1}},
+    c.get("output") == "ok: wrote LocalBusiness",
+    msg.get("operatorMessage") == "please write a node",
+    msg.get("assistantReply") == "done",
+  )
+  print("yes" if all(conds) else "no:"+repr([(i,c) for i,c in enumerate(conds) if not c])+"|call="+repr(c))
+except Exception as e:
+  print("parse-fail:"+str(e))
+' 2>/dev/null)
+if [[ "$TOOL_OK" == "yes" ]]; then
+  pass "case-7 toolCalls passthrough: input/output are JSON values, not strings"
+else
+  fail "case-7 toolCalls shape wrong ($TOOL_OK): $TOOL_BODY"
+fi
+
+# --- Case 8 (Task 175): escaping — quotes, backslashes, newlines, non-ASCII
+#     all round-trip cleanly through the JSON envelope.
+ESC_TRANSCRIPT=$(mktemp); TMPFILES+=("$ESC_TRANSCRIPT")
+python3 - "$ESC_TRANSCRIPT" <<'PY'
+import json, sys
+out = sys.argv[1]
+op_msg = 'hello "world"\\nline2\nlast — café 🦊'
+asst_msg = 'reply with backslash \\\\ and newline\nhere'
+recs = [
+  {"type":"user","message":{"role":"user","content":op_msg}},
+  {"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":asst_msg}]}},
+]
+with open(out,"w") as f:
+  for r in recs: f.write(json.dumps(r)+"\n")
+PY
+ESC_ENVELOPE=$(python3 -c '
+import json, sys
+print(json.dumps({"session_id": sys.argv[1], "transcript_path": sys.argv[2]}))
+' "$OP_ID" "$ESC_TRANSCRIPT")
+: > "$REQ_LOG"
+run_hook "admin" "" "$ESC_ENVELOPE"
+[[ "$HOOK_RC" -eq 0 ]] || fail "case-8 rc=$HOOK_RC stderr=$HOOK_STDERR"
+ESC_BODY=$(grep -E '^/api/admin/claude-sessions	' "$REQ_LOG" | head -1 | cut -f2-)
+ESC_OK=$(printf '%s' "$ESC_BODY" | python3 -c '
+import sys, json
+EXPECTED_OP = "hello \"world\"\\nline2\nlast — café \U0001F98A"
+EXPECTED_ASST = "reply with backslash \\\\ and newline\nhere"
+try:
+  outer = json.load(sys.stdin)
+  msg = json.loads(outer.get("initialMessage"))
+  conds = (
+    msg.get("operatorMessage") == EXPECTED_OP,
+    msg.get("assistantReply") == EXPECTED_ASST,
+  )
+  print("yes" if all(conds) else "no:"+repr([(i,c) for i,c in enumerate(conds) if not c])+"|op="+repr(msg.get("operatorMessage"))+"|asst="+repr(msg.get("assistantReply")))
 except Exception as e:
   print("parse-fail:"+str(e))
 ' 2>/dev/null)
-if [[ "$THREE_OK" == "yes" ]]; then
-  pass "case-7 three-turn conversation walks user/assistant/user in order"
+if [[ "$ESC_OK" == "yes" ]]; then
+  pass "case-8 escaping: quotes/backslashes/newlines/non-ASCII round-trip cleanly"
 else
-  fail "case-7 expected multi-turn layout, got: $THREE_OK | body: $THREE_BODY"
+  fail "case-8 escaping wrong ($ESC_OK): $ESC_BODY"
 fi
 
 # --- Summary ------------------------------------------------------------

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

@@ -1,21 +1,26 @@
 #!/usr/bin/env bash
 # Stop hook — fires on every completed admin-agent turn and dispatches one
-# headless database-operator session against the operator's most recent turn
-# text. The recorder is the only writer to the Neo4j graph; the admin agent
-# stays focused on the operator's request.
+# headless database-operator session against the operator's most recent
+# turn payload. The recorder is the only writer to the Neo4j graph; the
+# admin agent stays focused on the operator's request.
 #
 # Task 147 — the recorder spawn is byte-for-byte equivalent to a Sidebar
 # "New session" body, with three overrides:
 #   - specialist:     "database-operator"
 #   - model:          "haiku"
-#   - initialMessage: "update the graph with any new or missing information
-#                     or intent\n\n<last-turn-text>"
+#   - initialMessage: JSON-stringified envelope (Task 175)
+#
 # It POSTs to the SAME route the Sidebar uses
 # (`POST /api/admin/claude-sessions`). The wrapper accepts the loopback
 # request without a cookie, resolves the operator's `senderId` from the
 # manager's `/<adminSessionId>/meta`, and forwards a Sidebar-shape spawn
 # body. No recorder-only carving on the manager side.
 #
+# Task 175 — `initialMessage` is now a JSON object stringified to a
+# string. Top-level keys EXACTLY match the database-operator agent file
+# `## Input shape`: operatorMessage, assistantReply, toolCalls,
+# conversationId, accountId, occurredAt. No leading instruction prose.
+#
 # Gating (emits a `trigger-skipped` line via `/api/admin/log-ingest`;
 # stderr stays silent on the success path):
 #   - MAXY_SESSION_ROLE must equal "admin"        → reason=role-not-admin
@@ -23,8 +28,8 @@
 #     "database-operator"   (recursion guard)
 #   - Stop-hook stdin must be non-empty           → reason=empty-stdin
 #   - transcript_path must exist on disk          → reason=missing-transcript
-#   - at least one user or assistant record with   → reason=conversation-empty
-#     non-empty text must exist in the JSONL (Task 165)
+#   - operatorMessage, assistantReply, toolCalls   → reason=conversation-empty
+#     all empty after the walker runs
 #
 # Input: Claude Code's Stop hook stdin shape
 #   { "session_id": "<intrinsic>", "transcript_path": "<jsonl path>", ... }
@@ -91,58 +96,141 @@ if [ -z "$ADMIN_SESSION_ID" ] || [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIP
   exit 0
 fi
 
-# Task 165 — walk every user/assistant record in transcript order; emit
-# "<type>: <text>" per record; join with "\n". The recorder needs the
-# whole exchange to infer operator-asserted facts that span multiple
-# turns (e.g. "hello / what's your business? / Smalleys"). The earlier
-# "last-turn-only" extractor stripped the framing the recorder needed.
-CONVERSATION_TEXT=$(python3 - "$TRANSCRIPT_PATH" <<'PY'
+# Task 175 — build the JSON envelope the database-operator agent file
+# declares as its stdin contract. One Python pass walks the transcript
+# and emits:
+#   {
+#     "operatorMessage": <last role=user text>,
+#     "assistantReply":  <last role=assistant text>,
+#     "toolCalls":       [ {tool, input, output}, ... ],
+#     "conversationId":  <session_id>,
+#     "accountId":       <ACCOUNT_ID env>,
+#     "occurredAt":      <hook fire time, ISO-8601 UTC, .000Z>
+#   }
+# `python3 json.dumps` handles every escape so the hook never has to
+# concatenate strings into JSON by hand.
+OCCURRED_AT=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
+ACCOUNT_ID_ENV="${ACCOUNT_ID:-}"
+
+ENVELOPE=$(python3 - "$TRANSCRIPT_PATH" "$ADMIN_SESSION_ID" "$ACCOUNT_ID_ENV" "$OCCURRED_AT" <<'PY'
 import sys, json
 
-def block_text(block):
-    if not isinstance(block, dict): return ""
-    if block.get("type") != "text": return ""
-    t = block.get("text")
-    return t if isinstance(t, str) else ""
-
-def record_text(rec):
-    if not isinstance(rec, dict): return ""
-    msg = rec.get("message")
-    if not isinstance(msg, dict): return ""
-    content = msg.get("content")
-    if isinstance(content, str): return content
-    if isinstance(content, list):
-        parts = [block_text(b) for b in content]
-        return "\n".join(p for p in parts if p)
-    return ""
-
-path = sys.argv[1]
-turns = []
+def last_text(content):
+    """Return the last `text` block string in a content list, or '' if none."""
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        return ""
+    last = ""
+    for b in content:
+        if isinstance(b, dict) and b.get("type") == "text":
+            t = b.get("text")
+            if isinstance(t, str):
+                last = t
+    return last
+
+path, conversation_id, account_id, occurred_at = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4]
+
+last_user_text = ""
+last_assistant_text = ""
+pending_calls = {}  # tool_use_id -> {tool, input}
+tool_calls = []     # ordered as tool_results arrive
+
 try:
     with open(path, "r", encoding="utf-8") as f:
         for line in f:
             line = line.strip()
-            if not line: continue
-            try: rec = json.loads(line)
-            except Exception: continue
-            t = rec.get("type") if isinstance(rec, dict) else None
-            if t not in ("user", "assistant"): continue
-            tx = record_text(rec).strip()
-            if not tx: continue
-            turns.append(f"{t}: {tx}")
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+            except Exception:
+                continue
+            if not isinstance(rec, dict):
+                continue
+            t = rec.get("type")
+            msg = rec.get("message")
+            if not isinstance(msg, dict):
+                continue
+            content = msg.get("content")
+            if t == "user":
+                text = last_text(content)
+                if text:
+                    last_user_text = text
+                if isinstance(content, list):
+                    for b in content:
+                        if isinstance(b, dict) and b.get("type") == "tool_result":
+                            tu_id = b.get("tool_use_id")
+                            if not isinstance(tu_id, str):
+                                continue
+                            pending = pending_calls.pop(tu_id, None)
+                            if pending is None:
+                                continue
+                            tool_calls.append({
+                                "tool": pending["tool"],
+                                "input": pending["input"],
+                                "output": b.get("content"),
+                            })
+            elif t == "assistant":
+                text = last_text(content)
+                if text:
+                    last_assistant_text = text
+                if isinstance(content, list):
+                    for b in content:
+                        if isinstance(b, dict) and b.get("type") == "tool_use":
+                            tu_id = b.get("id")
+                            if not isinstance(tu_id, str):
+                                continue
+                            pending_calls[tu_id] = {
+                                "tool": b.get("name"),
+                                "input": b.get("input"),
+                            }
 except Exception:
     pass
 
-print("\n".join(turns), end="")
+# Unanswered tool_use blocks (tool_result never landed) still surface, so
+# the recorder sees the call attempt; `output` is null.
+for tu_id, pending in pending_calls.items():
+    tool_calls.append({
+        "tool": pending["tool"],
+        "input": pending["input"],
+        "output": None,
+    })
+
+envelope = {
+    "operatorMessage": last_user_text,
+    "assistantReply":  last_assistant_text,
+    "toolCalls":       tool_calls,
+    "conversationId":  conversation_id,
+    "accountId":       account_id,
+    "occurredAt":      occurred_at,
+}
+print(json.dumps(envelope, ensure_ascii=False), end="")
 PY
 )
 
-CONVERSATION_BYTES=$(printf '%s' "$CONVERSATION_TEXT" | wc -c | tr -d ' ')
+# Skip when the envelope carries no user text, no assistant text, and no
+# tool calls — same skip surface as the prior `conversation-empty` reason.
+EMPTY_CHECK=$(printf '%s' "$ENVELOPE" | python3 -c '
+import sys, json
+try:
+    e = json.load(sys.stdin)
+    empty = (
+        not (e.get("operatorMessage") or "")
+        and not (e.get("assistantReply") or "")
+        and not (e.get("toolCalls") or [])
+    )
+    print("empty" if empty else "ok")
+except Exception:
+    print("empty")
+')
+
+CONVERSATION_BYTES=$(printf '%s' "$ENVELOPE" | wc -c | tr -d ' ')
 TRANSCRIPT_BYTES=$(wc -c <"$TRANSCRIPT_PATH" 2>/dev/null | tr -d ' ' || echo 0)
 
 emit_log "trigger sessionId=${ADMIN_SESSION_ID} turnIndex=0 transcriptBytes=${TRANSCRIPT_BYTES} conversationBytes=${CONVERSATION_BYTES}"
 
-if [ -z "$CONVERSATION_TEXT" ]; then
+if [ "$EMPTY_CHECK" = "empty" ]; then
   emit_log "trigger-skipped sessionId=${ADMIN_SESSION_ID} reason=conversation-empty"
   exit 0
 fi
@@ -154,20 +242,18 @@ fi
 SPAWN_BODY=$(python3 -c '
 import sys, json
 sid = sys.argv[1]
-conversation = sys.argv[2]
-instruction = "update the graph with any new or missing information or intent"
-text = instruction + "\n\n" + conversation
+envelope_str = sys.argv[2]
 body = {
   "adminSessionId": sid,
   "channel": "browser",
   "specialist": "database-operator",
   "model": "haiku",
-  "initialMessage": text,
+  "initialMessage": envelope_str,
 }
 print(json.dumps(body))
-' "$ADMIN_SESSION_ID" "$CONVERSATION_TEXT" 2>/dev/null)
+' "$ADMIN_SESSION_ID" "$ENVELOPE" 2>/dev/null)
 
-INITIAL_BYTES=$(printf '%s\n\n%s' "update the graph with any new or missing information or intent" "$CONVERSATION_TEXT" | wc -c | tr -d ' ')
+INITIAL_BYTES=$(printf '%s' "$ENVELOPE" | wc -c | tr -d ' ')
 emit_log "spawn-request sessionId=${ADMIN_SESSION_ID} specialist=database-operator initialMessageBytes=${INITIAL_BYTES}"
 
 SPAWN_RES_FILE=$(mktemp)

package/payload/platform/plugins/docs/references/admin-session.md

@@ -92,11 +92,24 @@ After every completed operator admin turn, the Stop hook `platform/plugins/admin
 Body overrides relative to a plain Sidebar click:
 - `specialist: 'database-operator'`
 - `model: 'haiku'`
-- `initialMessage: "update the graph with any new or missing information or intent\n\n<conversation-text>"`
+- `initialMessage: <json-envelope>` (string carrying a JSON-stringified object — see below)
 
 **Spawn body.** The hook POSTs `{adminSessionId, channel: 'browser', specialist: 'database-operator', model: 'haiku', initialMessage}` to `POST /api/admin/claude-sessions`. `adminSessionId` is the loopback-bypass key — the wrapper resolves the operator's real `senderId` from `GET <managerBase>/<adminSessionId>/meta` and forwards a Sidebar-shape body to the manager.
 
-**`<conversation-text>`** is the operator JSONL walked in transcript order: every `user`/`assistant` record with non-empty text emitted as `"<type>: <text>"`, joined by `\n`. The full exchange is preserved so the recorder can infer operator-asserted facts that span multiple turns (e.g. "hello / what's your business? / Smalleys"). The earlier "last-turn-only" extractor stripped the framing the recorder needed. If no qualifying record exists, the hook emits `trigger-skipped reason=conversation-empty` and no recorder is spawned.
+**`initialMessage` JSON envelope (Task 175).** A single JSON object stringified to a string. Top-level keys exactly match the database-operator agent file `## Input shape`:
+
+```
+{
+  "operatorMessage": "<last role=user text block>",
+  "assistantReply":  "<last role=assistant text block, or '' if none>",
+  "toolCalls":       [ { "tool": "...", "input": {...}, "output": ... }, ... ],
+  "conversationId":  "<operator session_id>",
+  "accountId":       "<ACCOUNT_ID env, stamped on the manager systemd unit>",
+  "occurredAt":      "<hook fire time, ISO-8601 UTC, .000Z>"
+}
+```
+
+`toolCalls[].input` and `toolCalls[].output` are native JSON values, not re-stringified — `jq -r '.toolCalls[0].input.foo'` reaches the inner field directly. `tool_use` and `tool_result` blocks are paired by `tool_use_id`; unanswered `tool_use` calls surface with `output: null`. No leading instruction prose — the agent file's system prompt teaches the model what to do with the payload. If `operatorMessage`, `assistantReply`, and `toolCalls` are all empty after the walker runs, the hook emits `trigger-skipped reason=conversation-empty` and no recorder is spawned.
 
 **Manager-side specialist branches.** The recorder is the first specialist subagent that exercises the full specialist flag matrix:
 - The bundled `platform/templates/specialists/agents/database-operator.md` template is symlinked into `$CLAUDE_CONFIG_DIR/agents/database-operator.md` by the installer; without that link `claude --agent database-operator` silently falls back to the admin agent.
@@ -109,7 +122,7 @@ Body overrides relative to a plain Sidebar click:
 
 **Hook recursion gate.** `pty-spawner` stamps `MAXY_SPECIALIST=<specialist>` on every PTY env. The Stop hook short-circuits when `MAXY_SPECIALIST=database-operator` so the recorder's own end-of-turn does not re-fire the hook.
 
-**Observability.** The hook emits exactly two lines per operator turn via `/api/admin/log-ingest`: `[turn-recorder] trigger sessionId=<op> turnIndex=0 transcriptBytes=<n> conversationBytes=<n>` and `[turn-recorder] spawn-request sessionId=<op> specialist=database-operator initialMessageBytes=<n>`. The manager adds `pty-spawn-allowlist specialist=database-operator count=11 sourced-from=agent-frontmatter` and `pty-spawn-start … specialist=database-operator append-system-prompt-bytes=0` before the PTY launches. The remainder of the recorder lifecycle is covered by the Sidebar's existing lines (`pty-spawned`, JSONL events, `auto-archive`). Failure-mode names: `trigger-skipped reason=…` enumerates `role-not-admin | is-recorder | empty-stdin | missing-transcript | conversation-empty`. Hook-side spawn errors emit `[turn-recorder] spawn-failed reason=loopback-http http=<code>`.
+**Observability.** The hook emits exactly two lines per operator turn via `/api/admin/log-ingest`: `[turn-recorder] trigger sessionId=<op> turnIndex=0 transcriptBytes=<n> conversationBytes=<n>` and `[turn-recorder] spawn-request sessionId=<op> specialist=database-operator initialMessageBytes=<n>`. The manager adds `pty-spawn-allowlist specialist=database-operator count=11 stripped=0 sourced-from=agent-frontmatter` and `pty-spawn-start … specialist=database-operator append-system-prompt-bytes=0` before the PTY launches. The remainder of the recorder lifecycle is covered by the Sidebar's existing lines (`pty-spawned`, JSONL events, `auto-archive`). Failure-mode names: `trigger-skipped reason=…` enumerates `role-not-admin | is-recorder | empty-stdin | missing-transcript | conversation-empty`. Hook-side spawn errors emit `[turn-recorder] spawn-failed reason=loopback-http http=<code>`.
 
 ### Recorder lifecycle diagnostic
 
@@ -118,7 +131,7 @@ When the operator reports "the recorder did nothing this turn", run these six gr
 1. **Stop hook fired.** `grep '\[turn-recorder\] trigger sessionId=<op>' ~/.<brand>/logs/server.log` — expects one line of shape `[turn-recorder] trigger sessionId=<op> turnIndex=0 transcriptBytes=<n> conversationBytes=<n>`. Absent: the Stop hook didn't run; check that `MAXY_SESSION_ROLE=admin` was set on the operator PTY and that `MAXY_SPECIALIST!=database-operator` (recursion gate).
 2. **/spawn accepted.** `grep '\[turn-recorder\] spawn-request sessionId=<op>' ~/.<brand>/logs/server.log` — expects `[turn-recorder] spawn-request sessionId=<op> specialist=database-operator initialMessageBytes=<n>`. The response body of this POST carries `<rec>`. Absent: the hook fired but `/api/admin/claude-sessions` rejected; look for `[turn-recorder] spawn-failed reason=loopback-http http=<code>` on the next line.
 3. **PTY started.** `grep 'pty-spawn-start .* specialist=database-operator' ~/.<brand>/logs/server.log` — expects `pty-spawn-start claudeBin=<…> argv-count=<n> append-system-prompt-bytes=0 … specialist=database-operator prompt-positional=yes prompt-bytes=<n>`. Absent: the wrapper accepted but the manager rejected before exec; check the spawn-failure surfaces (`which-claude-not-found | pty-spawn-failed | pid-file-timeout | host-context-unresolved | identity-unresolved | mcp-config-write-failed`).
-4. **Agent file resolved.** `grep 'pty-spawn-allowlist specialist=database-operator count=11 sourced-from=agent-frontmatter' ~/.<brand>/logs/server.log` — expects exactly one line per recorder spawn. Absent (or `count` not equal to the frontmatter's tool count): the agent file at `$CLAUDE_CONFIG_DIR/agents/database-operator.md` is missing the `tools:` line, or the symlink the installer creates never landed. Re-run the installer.
+4. **Agent file resolved.** `grep 'pty-spawn-allowlist specialist=database-operator count=11 stripped=0 sourced-from=agent-frontmatter' ~/.<brand>/logs/server.log` — expects exactly one line per recorder spawn. Absent (or `count` not equal to the frontmatter's tool count, or `stripped>0` meaning the brand excluded a plugin the recorder template references — Task 173): the agent file at `$CLAUDE_CONFIG_DIR/agents/database-operator.md` is missing the `tools:` line, the symlink the installer creates never landed, or the brand-aware drift filter dropped tools. Re-run the installer; cross-reference `brand.json#plugins.excluded` against the agent frontmatter.
 5. **Graph write outcome.** `grep '\[mcp:memory\] memory-write .* session=<rec>' ~/.<brand>/logs/server.log` — expects one line ending `result=ok elementId=<id>` or `result=error reason=<slug>` (slug enumerated by the memory MCP write-path observability work). Absent: the recorder loaded but produced no tool calls — model-side decision, not infra. Read the recorder JSONL at `<accountDir>/.claude/projects/<slug>/<rec>.jsonl` to see what the LLM did.
 6. **Auto-archive.** `grep 'auto-archive .* sessionId=<rec> .* specialist=database-operator reason=end-turn' ~/.<brand>/logs/server.log` — expects one line. Absent: the recorder finished but the manager's end-turn watcher didn't fire; the fs-watcher row will get reaped on its TTL but the recorder hung longer than expected. Investigate `pty-spawn-stop` and `pid-file-removed` lines on the same `<rec>`.
 
@@ -163,6 +176,8 @@ grep '\[mcp:memory\] log-ingest-failed' ~/.${brand}/logs/mcp-memory-stderr-*.log
 
 The existing `mcp-memory-stderr-<date>.log` capture is unchanged on error paths — the new structured line is additive, not a relocation. Crash-mode debugging continues to read the stderr log; routine "did it land?" questions read `server.log`.
 
+**Test contract (Task 168).** Each of the 20 wired tools carries a `*-emit.test.ts` fixture under `platform/plugins/memory/mcp/src/tools/__tests__/` that mocks `fetch` and asserts the wire body. A refactor that drops `withWriteEvent` from any tool fails the matching tool's tests with a clear `expected "vi.fn()" to be called 1 times, but got 0 times` error, naming the tool. A shared helper at `__tests__/_helpers/emit-capture.ts` standardises the fetch capture + Neo4j Session stub so each tool test stays a few lines of mocks + one happy + one error assertion. Drift between the helper's body shape and the route's validator is pinned by an end-to-end test at `platform/ui/server/routes/admin/__tests__/log-ingest-mcp-end-to-end.test.ts`, which routes the helper's POST through the real Hono `log-ingest` route with a loopback `remoteAddress` shim.
+
 ## Out of scope
 
 - Public/WhatsApp/Telegram sessions — out of scope. Their sessionKeys remain `crypto.randomUUID()` and follow the existing rejection-on-restart contract.