@theronap/agnoclast-mcp 0.9.176 → 0.9.178

package/bin/cortex-mcp.mjs

@@ -112,7 +112,7 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `  docs-scan       detect new/changed local docs pending Agnoclast authoring (used by /cortex-author-docs)\n` +
     `  graphify-sync [path] [--brain <name-or-id>]  rebuild the local code graph + log a timeline event\n` +
     `  snapshot-context save the exact startup context Agnoclast served to a local snapshot\n` +
-  `  arrivals-notice  hook pair: detect incoming-record offers (PostToolUse) and surface them (--emit, UserPromptSubmit)\n` +
+  `  arrivals-notice  --emit: surface incoming-record offers to you (UserPromptSubmit hook)\n` +
     `  hydrate         UserPromptSubmit hook — inject query-centered context on the first substantive turn\n` +
     `  migrate-key [--dry-run]  move the MCP config key to its new name, allow rules first\n` +
     `  with-token -- <cmd>    run <cmd> with your token in its environment (for cron/launchd wrappers)\n` +
@@ -221,16 +221,28 @@ if (cmd === 'login') {
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
 } else if (cmd === 'arrivals-notice') {
-  // PostToolUse hook: surface the arrivals offer to the PERSON. The ⚡ block is appended to TOOL
-  // RESULTS, which only the agent reads — and an audit on 2026-09-21 found the agent acting on it
-  // once in a day. Pure text extraction from the payload it is handed: no network, no token, always
-  // exit 0. It reports; it never blocks a tool call.
-  // Two halves, one subcommand. `--emit` is the UserPromptSubmit side (drain + print); without it
-  // this is the PostToolUse side (detect + spool, prints nothing). Neither can do the job alone:
-  // PostToolUse sees tool output but its stdout is not injected; UserPromptSubmit is injected but
-  // never sees tool output. See lib/arrivals_notice.mjs's header.
-  const mod = await import('../lib/arrivals_notice.mjs')
-  process.exitCode = rest.includes('--emit') ? await mod.runArrivalsDrain() : await mod.runArrivalsNotice()
+  // UserPromptSubmit hook: surface the arrivals offer to the PERSON. The signals are appended to
+  // TOOL RESULTS, which only the agent reads — and an audit on 2026-09-21 found the agent acting on
+  // it once in a day. One cheap authenticated GET, fail-open, always exit 0. It reports; it never
+  // blocks a prompt.
+  // ONE half now. `--emit` (UserPromptSubmit) ASKS THE SERVER for the two turn-time signals and
+  // prints them. The PostToolUse scraper + spool it replaced could never surface anything before the
+  // next UserPromptSubmit anyway, because PostToolUse stdout is not injected — so this delivers at
+  // the same moment, from the source. See lib/arrivals_notice.mjs's header.
+  // ⚠ WITHOUT --emit THIS IS A DELIBERATE NO-OP, not a fallthrough. That was the PostToolUse half,
+  // retired 2026-09-25 along with the spool. A seat whose settings.json still has that hook must do
+  // NOTHING here: the live path CONSUMES a watermark, so letting a stale PostToolUse call reach it
+  // would announce arrivals into a stdout that is never injected and leave the next prompt — the one
+  // the person actually reads — correctly reporting nothing. Deleting a hook from one machine's
+  // settings does not delete it from anyone else's, so the old invocation has to stay harmless.
+  if (rest.includes('--emit')) {
+    const mod = await import('../lib/arrivals_notice.mjs')
+    process.exitCode = await mod.runArrivalsDrain()
+    const { closeFetch } = await import('../lib/diagnose.mjs')
+    await closeFetch()
+  } else {
+    process.exitCode = 0
+  }
 } else if (cmd === 'hydrate') {
   // UserPromptSubmit hook (① discovery): hydrate the model with query-centered Agnoclast context on the
   // FIRST substantive turn, before it answers — then never again this session (topic-shift refresh stays

package/lib/arrivals_notice.mjs

@@ -1,11 +1,10 @@
-// PostToolUse hook — make the arrivals offer visible to the PERSON, not just the agent.
+// UserPromptSubmit hook — make the arrivals offer visible to the PERSON, not just the agent.
 //
-// 🔴 WHY THIS EXISTS, and it is not a nicety. The `⚡ ARRIVED WHILE YOU WERE WORKING` block and the
-// per-turn delta line are appended to TOOL RESULTS, which only the agent reads. Measured on
-// 2026-09-21 against a single session's own record: the block fired repeatedly through the day and
-// the agent acted on it ONCE, and only because the user asked it to prove the mechanism existed. An
-// audit of the four records it named found one that plainly belonged to that session's own work and
-// had simply been let pass.
+// 🔴 WHY THIS EXISTS, and it is not a nicety. The per-turn delta line and the settling feed are
+// appended to TOOL RESULTS, which only the agent reads. Measured on 2026-09-21 against a single
+// session's own record: the block fired repeatedly through the day and the agent acted on it ONCE,
+// and only because the user asked it to prove the mechanism existed. An audit of the four records
+// it named found one that plainly belonged to that session's own work and had simply been let pass.
 //
 // The failure is structural rather than a lapse: the offer arrives MID-TASK, inside a result the
 // agent requested for an unrelated reason, and nothing forces a decision. A signal that only the
@@ -13,196 +12,110 @@
 // coverage. So this does not ask the agent to be more diligent; it removes the agent from the
 // delivery path.
 //
-// ⚠ IT IS NOT A GATE. Exit is always 0: this reports, it never blocks a tool call, and it never
-// fails one. A notifier that can break the thing it observes gets disabled, and then it observes
-// nothing.
+// ⚠ IT IS NOT A GATE. Exit is always 0. A notifier that can break the thing it observes gets
+// disabled, and then it observes nothing.
 //
-// 🔴 TWO EVENTS, BECAUSE NEITHER ONE CAN DO THIS ALONE. Measured 2026-09-21, after shipping a
-// version that could not work:
+// 🔴 IT ASKS THE SERVER. IT USED TO SCRAPE ITS OWN CONVERSATION. (Rewritten 2026-09-25.)
 //
-//   PostToolUse       has the arrivals block   — but its stdout is NOT injected into the conversation
-//   UserPromptSubmit  IS injected (proven)     — but never receives tool output at all
+// The previous design was a two-hook round trip: PostToolUse read the rendered English off tool
+// results with two regexes, spooled the matches to ~/.cortex/arrivals-spool, and this half drained
+// the spool on the next prompt. The server had computed both numbers and written that text itself —
+// the scraper existed only to read them back out of its own output.
 //
-// The first version wired only PostToolUse and printed to stdout. It ran perfectly: correct parse,
-// correct ids, state file written seconds after the block appeared. And NOBODY SAW ANY OF IT —
-// which is precisely the failure this file exists to fix, reproduced by the fix. The assumption came
-// from seeing SessionStart and UserPromptSubmit output every turn and generalising to all hooks;
-// those two are context-INJECTING events by design.
+// It failed in both directions:
 //
-// So: PostToolUse DETECTS and spools. UserPromptSubmit DRAINS and surfaces. Arrivals appear at the
-// top of the person's next turn, which is when they are actually looking at the screen.
+//   MISSED — the signal rode on Agnoclast TOOL RESULTS, so a turn of bash and edits produced none,
+//            and nothing arrived no matter how much had actually arrived.
+//   INVENTED — any text containing the pattern was scraped as if it were a signal. This agent's own
+//            Bash output, while quoting the regex to debug it, was ingested as arrivals.
 //
-// ⚠ NO NETWORK, NO TOKEN, NO DECRYPT. Everything printed is already in the payload the hook was
-// handed. That keeps it fast enough to run after every tool call and means it cannot leak anything
-// the agent was not already shown.
-import { readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-
-const MATCHED = '⚡ ARRIVED WHILE YOU WERE WORKING'
-const DELTA_RE = /⚡ (\d+) new arrivals? in your pile/
-// The listing lines look like:  - Title  (email · 5.1h ago · id <uuid>) — …
-const ITEM_RE = /^\s*-\s+(.*?)\s+\((\S+)\s+·\s+([^·]+?)\s+·\s+id\s+([0-9a-f-]{36})\)/gmu
-
-function readStdin() {
-  try { return readFileSync(0, 'utf8') } catch { return '' }
-}
-
-/** Every string in the payload, so this does not depend on which key holds the tool's text. */
-function* strings(v, depth = 0) {
-  if (depth > 8 || v == null) return
-  if (typeof v === 'string') { yield v; return }
-  if (Array.isArray(v)) { for (const x of v) yield* strings(x, depth + 1); return }
-  if (typeof v === 'object') { for (const x of Object.values(v)) yield* strings(x, depth + 1) }
-}
+// A parser whose input is the conversation it is printing into cannot distinguish the world from
+// its own echo. So it now asks the one party that knows.
+//
+// ⚠ AND IT COSTS NOTHING IN TIMING, which is the part that looks like a regression and is not.
+// PostToolUse stdout is NOT injected into the conversation — that is measured, and it is why the
+// spool existed at all. The spool could never surface anything before the next UserPromptSubmit.
+// Asking at that same moment delivers at the identical time, from the source, with no state on disk.
+//
+// ⚠ THE NETWORK CALL IS NEW, AND DELIBERATE. The old header promised NO NETWORK, NO TOKEN, because
+// it ran after EVERY TOOL CALL. That event is deleted. This runs once per prompt — the same budget
+// SessionStart already spends — and fails open to silence.
+//
+// ⚠ THE SERVER OWNS THE DEDUPE NOW. arrivalDelta advances session_arrival_watermarks, announcing an
+// arrival to a session exactly once, which is what the local `seen` files were approximating with
+// filesystem state that no other party could see. A consequence worth stating: fetching CONSUMES
+// the announcement, so this prints whatever it gets. Losing one notice is recoverable — the record
+// is still unclaimed and the server will offer it again.
+import { fetchCortex, resolveBase, resolveTokenSource } from './diagnose.mjs'
 
 /**
- * Pull the arrivals offer out of a PostToolUse payload.
+ * Render both turn-time signals for a person skimming their terminal.
  *
- * Exported for tests: the parsing is the part that can silently rot when the server changes the
- * block's wording, and a hook that stops matching fails SILENTLY — it just prints nothing forever,
- * which is indistinguishable from "nothing arrived".
+ * Deliberately shallow: names, ages and ids, never page contents. The settling half is owner-scoped
+ * at the query (private_intake_items joined to the caller's own account), so there is nobody to leak
+ * to — but this is a hook that prints unprompted, and a notice that dumps content trains its reader
+ * to skip it. Exported for the tests.
  */
-export function extractArrivals(payloadText) {
-  let blob = payloadText
-  try {
-    const parsed = JSON.parse(payloadText)
-    blob = [...strings(parsed)].join('\n')
-  } catch {
-    // Not JSON — scan the raw text. Fail open toward reporting rather than staying silent.
-  }
-  if (!blob) return null
-
-  const deltaMatch = blob.match(DELTA_RE)
-  const delta = deltaMatch ? Number(deltaMatch[1]) : 0
+export function formatNotice(signals) {
+  const lines = []
+  const offers = signals?.settling?.offers ?? []
+  const total = Number(signals?.settling?.total ?? offers.length)
+  const delta = Number(signals?.arrival?.count ?? 0)
 
-  const items = []
-  if (blob.includes(MATCHED)) {
-    // Only the section AFTER the marker, so an unrelated bulleted list earlier in a page read is
-    // not mistaken for arrivals.
-    const section = blob.slice(blob.indexOf(MATCHED))
-    for (const m of section.matchAll(ITEM_RE)) {
-      items.push({ title: m[1].trim(), source: m[2], age: m[3].trim(), id: m[4] })
-    }
+  if (delta) {
+    lines.push(`⚡ ${delta} new arrival${delta === 1 ? '' : 's'} in the pile since this session was last told.`)
   }
-  if (!delta && items.length === 0) return null
-  return { delta, items }
-}
-
-/** Ids already announced, so the same arrival is not re-reported on every tool call until claimed. */
-function seenPath(sessionKey) {
-  const dir = join(homedir(), '.cortex', 'arrivals-announced')
-  try { mkdirSync(dir, { recursive: true }) } catch { /* best effort */ }
-  return join(dir, `${(sessionKey || 'nosession').replace(/[^a-zA-Z0-9_-]/g, '_')}.json`)
-}
-
-function loadSeen(p) {
-  try { return new Set(JSON.parse(readFileSync(p, 'utf8'))) } catch { return new Set() }
-}
-
-function saveSeen(p, set) {
-  // Bounded: a long session must not grow this file without limit.
-  try { writeFileSync(p, JSON.stringify([...set].slice(-500))) } catch { /* best effort */ }
-}
-
-export function formatNotice(arrivals) {
-  const lines = []
-  if (arrivals.items.length) {
-    lines.push(`⚡ ${arrivals.items.length} record${arrivals.items.length === 1 ? '' : 's'} offered to this session:`)
-    for (const it of arrivals.items.slice(0, 6)) {
-      lines.push(`   · ${it.title.slice(0, 92)}  (${it.source} · ${it.age})`)
-      lines.push(`     ${it.id}`)
+  if (offers.length) {
+    lines.push(`⚡ ${total} arrival${total === 1 ? '' : 's'} asking THIS session to decide:`)
+    // ⚠ EVERY OFFER, GROUPED BY CASCADE STAGE — changed 2026-09-25 from the first SIX.
+    //
+    // Six of a deterministically-ordered twelve showed the SAME handful every turn while the rest of
+    // the pile stayed unreachable, and a session cannot claim what it is never shown. via_reason is
+    // still carried through verbatim rather than flattened — a reader who learns the stated reason is
+    // unreliable stops reading it — but it is printed ONCE PER GROUP instead of on every row, which
+    // is what makes listing all of them fit at all.
+    const STAGES = [
+      ['matched', 'matches your work'],
+      ['orphan', 'nothing matched them anywhere'],
+      ['declined', 'every other matching session declined them'],
+    ]
+    for (const [key, why] of STAGES) {
+      const group = offers.filter((o) => o.via_reason === key)
+      if (!group.length) continue
+      lines.push(`   ${why} (${group.length}):`)
+      for (const o of group) lines.push(`     ${o.intakeItemId}  ${o.source} · ${o.hoursAgo}h`)
     }
-    if (arrivals.items.length > 6) lines.push(`   … and ${arrivals.items.length - 6} more`)
-  }
-  if (arrivals.delta) {
-    lines.push(`⚡ ${arrivals.delta} new arrival${arrivals.delta === 1 ? '' : 's'} in the pile since this session was last told.`)
+    // Only when the pile genuinely exceeds the server's scan window; `total` is counted before it.
+    if (total > offers.length) lines.push(`   … and ${total - offers.length} beyond the scan window`)
+    lines.push('   (Claim + route them, or say they are not yours — they stay unclaimed until someone decides.)')
   }
-  // Said plainly, because the whole point is that the person can tell whether anything happened.
-  if (arrivals.items.length) lines.push(`   (Claim + route them, or say they are not yours — they stay unclaimed until someone decides.)`)
   return lines.join('\n')
 }
 
-/** The handoff between the two hook events. One file per session, drained on the next prompt. */
-function spoolPath(sessionKey) {
-  const dir = join(homedir(), '.cortex', 'arrivals-spool')
-  try { mkdirSync(dir, { recursive: true }) } catch { /* best effort */ }
-  return join(dir, `${(sessionKey || 'nosession').replace(/[^a-zA-Z0-9_-]/g, '_')}.json`)
-}
-
-/**
- * PostToolUse: detect, de-duplicate, SPOOL. Prints nothing — its stdout goes nowhere a person reads.
- *
- * ⚠ The spool ACCUMULATES across tool calls rather than overwriting. Several tool calls commonly
- * land between two prompts, and only the first carries a given arrival; overwriting would mean the
- * last tool call before the prompt decides what the person sees, which is usually nothing.
- */
-export async function runArrivalsNotice() {
-  try {
-    const raw = readStdin()
-    if (!raw) return 0
-
-    let sessionKey = ''
-    try { sessionKey = String(JSON.parse(raw)?.session_id ?? '') } catch { /* fine */ }
-
-    const arrivals = extractArrivals(raw)
-    if (!arrivals) return 0
-
-    const p = seenPath(sessionKey)
-    const seen = loadSeen(p)
-    const fresh = arrivals.items.filter((it) => !seen.has(it.id))
-
-    // Nothing new to say. The delta line is server-side watermarked and already fires once per
-    // change, so it is reported whenever present.
-    if (fresh.length === 0 && !arrivals.delta) return 0
-
-    // Merge into whatever is already spooled for this session.
-    const sp = spoolPath(sessionKey)
-    let pending = { delta: 0, items: [] }
-    try { pending = JSON.parse(readFileSync(sp, 'utf8')) } catch { /* first one this turn */ }
-    const byId = new Map((pending.items ?? []).map((it) => [it.id, it]))
-    for (const it of fresh) byId.set(it.id, it)
-    try {
-      writeFileSync(sp, JSON.stringify({
-        // The server watermarks the delta, so the freshest sighting is the right one — not a sum,
-        // which would double-count the same pile across two tool calls in one turn.
-        delta: arrivals.delta || pending.delta || 0,
-        items: [...byId.values()].slice(-40),
-      }))
-    } catch { /* best effort */ }
-
-    for (const it of fresh) seen.add(it.id)
-    saveSeen(p, seen)
-    return 0
-  } catch {
-    // ⚠ ALWAYS 0. This observes; it must never be the reason a tool call failed.
-    return 0
-  }
-}
-
 /**
- * UserPromptSubmit: DRAIN the spool and print. This is the half the person actually sees.
+ * UserPromptSubmit: ask, then print. This is the half the person actually sees.
  *
- * ⚠ CLEAR THE SPOOL BEFORE PRINTING FAILS, not after. A crash between print and clear would repeat
- * the same arrivals on every subsequent prompt forever, and a notifier that nags is one that gets
- * removed. Losing one notice is recoverable — the record is still unclaimed and will be offered
- * again by the server.
+ * The session key is not read here: bin/cortex-mcp.mjs stamps it for every CONTEXT_HOOK_COMMAND, so
+ * fetchCortex already carries x-cortex-session-key. That also means this no longer touches stdin —
+ * which matters, because `hydrate` runs on the SAME event and consumes stdin itself, and two hooks
+ * racing to drain one pipe is a bug waiting on a scheduler.
  */
 export async function runArrivalsDrain() {
   try {
-    const raw = readStdin()
-    let sessionKey = ''
-    try { sessionKey = String(JSON.parse(raw)?.session_id ?? '') } catch { /* fine */ }
-
-    const sp = spoolPath(sessionKey)
-    let pending = null
-    try { pending = JSON.parse(readFileSync(sp, 'utf8')) } catch { return 0 }
-    try { unlinkSync(sp) } catch { /* best effort */ }
-
-    if (!pending || (!pending.delta && !(pending.items ?? []).length)) return 0
-    process.stdout.write(formatNotice({ delta: pending.delta ?? 0, items: pending.items ?? [] }) + '\n')
+    const { token } = resolveTokenSource()
+    if (!token) return 0
+    const base = resolveBase(process.env.CORTEX_URL)
+    const res = await fetchCortex(`${base}/api/session-signals`, {
+      headers: { Authorization: `Bearer ${token}` },
+    })
+    if (!res?.ok) return 0
+    const signals = await res.json().catch(() => null)
+    if (!signals) return 0
+    const out = formatNotice(signals)
+    if (out) process.stdout.write(out + '\n')
     return 0
   } catch {
+    // Fail open and silent: a prompt must never be blocked or slowed by its own notifier.
     return 0
   }
 }

package/lib/editors/claude.mjs

@@ -105,22 +105,33 @@ export function mergeClaudeSettings(existing, spec) {
   }
   sgrp.hooks.push({ type: 'command', command: snapshotCmd })
 
-  // PostToolUse — arrivals-notice.
+  // PostToolUse — arrivals-notice: RETIRED 2026-09-25. This block now REMOVES it and installs nothing.
   //
-  // 🔴 THE ARRIVALS OFFER WAS INVISIBLE TO THE PERSON. `⚡ ARRIVED WHILE YOU WERE WORKING` and the
-  // per-turn delta are appended to TOOL RESULTS, which only the agent reads. Measured 2026-09-21
-  // against one session's own record: the block fired repeatedly through the day, the agent acted on
-  // it once, and an audit of the records it named found one belonging to that session's own work
-  // that had simply been let pass. A signal only the agent sees, and reliably scrolls past, LOOKS
-  // like coverage while providing none.
+  // It existed because the arrivals signals are appended to TOOL RESULTS, which only the agent reads,
+  // and an audit on 2026-09-21 found the agent acting on them once in a day. The hook scraped those
+  // rendered results with two regexes and spooled the matches for the next prompt to drain.
   //
-  // ⚠ SO THIS IS WIRED AS SOFTWARE, NOT LEFT TO INSTRUCTION. Asking the agent to relay arrivals is
-  // asking it to be reliable at exactly the thing it was just measured failing at; a hook takes the
-  // agent out of the delivery path entirely.
+  // Deleted because the scraper could not tell the world from its own echo. It MISSED every turn that
+  // called no Agnoclast tool (the signal rides on tool results), and it INVENTED arrivals from any
+  // text containing the pattern — including an agent's own Bash output quoting the regex to debug it.
+  // The UserPromptSubmit half below now ASKS THE SERVER, which is the only party that knows.
   //
-  // ⚠ Matcher is '' (every tool). The block only appears on three surfaces, so the filtering is
-  // server-side and this stays a cheap no-op elsewhere: it reads its stdin, finds no marker, exits 0.
+  // ⚠ AND IT COST NOTHING TO DELETE. PostToolUse stdout is not injected into the conversation — the
+  // measured fact that forced the spool to exist — so this hook could never surface anything before
+  // the next UserPromptSubmit. Asking there delivers at the identical moment.
+  //
+  // ⚠ THE FILTER STAYS, AND IS NOW THE POINT. Seats wired before today still have this hook. Left in
+  // place it would call a subcommand that is a deliberate no-op — harmless only because bin makes it
+  // one. Re-running setup RETIRES it, which is the only reach this package has into an existing
+  // settings.json.
   s.hooks.PostToolUse = Array.isArray(s.hooks.PostToolUse) ? s.hooks.PostToolUse : []
+  for (const pg of s.hooks.PostToolUse) {
+    if (Array.isArray(pg.hooks)) pg.hooks = pg.hooks.filter((h) => !isManagedSubcommand(h.command, 'arrivals-notice'))
+  }
+  // Drop any group this emptied, so retirement does not leave a bare {matcher:'',hooks:[]} behind.
+  s.hooks.PostToolUse = s.hooks.PostToolUse.filter((g) => (g.hooks ?? []).length)
+  if (!s.hooks.PostToolUse.length) delete s.hooks.PostToolUse
+
   // 🔴 THIS HOOK DOES NOT FOLLOW `spec`, AND THE REASON IS A DEFECT THIS FILE SHIPPED ONCE.
   //
   // `spec` pins @stable, which is what desktop-wired seats deliberately follow. But a hook wired at
@@ -134,19 +145,15 @@ export function mergeClaudeSettings(existing, spec) {
   // WIRED AT A SPEC THAT CANNOT EXECUTE IT. A version floor is the narrowest way to hold that, and
   // npx resolves a semver range (verified 2026-09-21 against a real invocation, not assumed).
   //
+  // ⚠ FLOOR RAISED TO 0.9.177 ON 2026-09-25, and it is load-bearing rather than tidy. Below it,
+  // `--emit` drains a spool that nothing writes any more: it would exit 0, print nothing, and look
+  // exactly like a quiet queue. The floor is what makes that impossible instead of silent.
+  //
   // ⚠ And it uses the CANONICAL name. Every other command here carries `cortex-mcp` for
   // compatibility with frozen launchd/cron scripts on unreachable machines (ADR-0033) — but a
   // BRAND-NEW hook has no frozen scripts to be compatible with, so there is no reason to mint more
   // references to the retiring name. New wiring uses the name the product actually has.
-  const ARRIVALS_MIN_VERSION = '0.9.162'
-  const arrivalsCmd = markCommand(`npx -y @theronap/agnoclast-mcp@^${ARRIVALS_MIN_VERSION} arrivals-notice`)
-  for (const pg of s.hooks.PostToolUse) {
-    if (Array.isArray(pg.hooks)) pg.hooks = pg.hooks.filter((h) => !isManagedSubcommand(h.command, 'arrivals-notice'))
-  }
-  let pgrp = s.hooks.PostToolUse.find((g) => (g.matcher ?? '') === '')
-  if (!pgrp) { pgrp = { matcher: '', hooks: [] }; s.hooks.PostToolUse.push(pgrp) }
-  pgrp.hooks = pgrp.hooks ?? []
-  pgrp.hooks.push({ type: 'command', command: arrivalsCmd })
+  const ARRIVALS_MIN_VERSION = '0.9.177'
 
   // UserPromptSubmit — hydrate (① discovery). Makes the FIRST context load of a session
   // non-discretionary: without it, hydration is a skill the agent may simply forget, and an agent

package/lib/server.mjs

@@ -1428,6 +1428,197 @@ function renderNudge(payload) {
     },
   )
 
+  // ── GMAIL WRITES — V5 / W5 of the Google write-scopes plan ───────────────────────────────────────
+  //
+  // Three tools over the W3 engine and its routes: change labels, save a reply draft, ask to send.
+  // Modelled on search_spam_email and send_imessage, as W5 specifies, and they inherit that pair's two
+  // habits — the 409 "which mailbox?" answer, and saying plainly what was NOT done.
+  //
+  // ⚠ THE OWNER CHECK IS THE SERVER'S, NOT OURS (review D14). Every route resolves the mailbox through
+  // loadOwnerGmailConnectors + canAccessMailbox, so being able to READ an email record in a shared brain
+  // never authorizes a write to it. These tools add no authorization of their own and must not imply any.
+  //
+  // ⚠ DARK UNTIL GOOGLE APPROVES THE WRITE SCOPES. In production GOOGLE_WRITE_SCOPES_LIVE is unset and
+  // every Gmail connector is read-only, so these return the auth/upgrade path. That is correct behaviour,
+  // not something to route around — they ship now so they are ready the day the scopes land.
+  //
+  // ⚠ NEVER SAY "NOTHING CHANGED" ON A FAILURE. modifyMessages chunks by BATCH_LIMIT and loops, and a
+  // throw in a later chunk discards the results already collected — so a 5xx can follow real changes. V4
+  // fixed exactly this lie in the web UI; the wording below is what keeps it fixed here.
+
+  /** ONE place a Gmail write failure becomes agent-readable text, so three tools cannot drift on it. */
+  const gmailWriteError = (res, body, tool) => {
+    const msg = typeof body?.error === 'string' ? body.error : null
+    if (res.status === 409 && Array.isArray(body?.accounts) && body.accounts.length) {
+      return toolError(`More than one connected Gmail account. Call ${tool} again with account: ${body.accounts.join(', ')}`)
+    }
+    if (res.status === 401 || res.status === 403) {
+      return toolError(
+        `${msg ?? 'Gmail refused that write.'} Gmail write access may not be granted on this account yet — ` +
+        `the person can check Connectors in Agnoclast. Nothing was changed.`)
+    }
+    if (res.status >= 500) {
+      return toolError(
+        `${msg ?? `Agnoclast could not finish that (${res.status}).`} ⚠ Part of it MAY already have happened. ` +
+        `Do not call ${tool} again — ask the person to check their mailbox first.`)
+    }
+    return toolError(msg ?? `${tool} failed (${res.status}).`)
+  }
+
+  server.registerTool(
+    'gmail_modify',
+    {
+      title: 'Change labels on the user\'s own Gmail messages',
+      description:
+        'Mark read or unread, archive, move back to the inbox, or add/remove a label on messages in the USER\'S OWN connected Gmail. Only the mailbox owner can act on a message — being able to read an email record in a shared brain does NOT authorize changing it, and the server enforces that. Identify messages with recordIds (Agnoclast email record ids) or messageIds (Gmail ids); they must all be in ONE mailbox. For add_label/remove_label pass labelId — one of the user\'s own labels (Label_…), or STARRED or IMPORTANT; call without labelId to get the list. THIS CHANGES THE USER\'S MAILBOX: confirm what they want before calling unless they just asked for it plainly. move_to_inbox is the undo for archive.',
+      inputSchema: {
+        action: z.enum(['mark_read', 'mark_unread', 'archive', 'move_to_inbox', 'add_label', 'remove_label'])
+          .describe('what to do to every message named; move_to_inbox undoes archive'),
+        recordIds: z.array(z.string()).optional().describe('Agnoclast email record ids, all in the same mailbox'),
+        messageIds: z.array(z.string()).optional().describe('Gmail message ids, all in the same mailbox — an alternative to recordIds'),
+        labelId: z.string().optional().describe('required for add_label / remove_label: one of the user\'s own labels (Label_…), or STARRED or IMPORTANT. Omit to be shown the available labels.'),
+        account: z.string().email().optional().describe('which connected Gmail account, when the user has more than one'),
+      },
+    },
+    async ({ action, recordIds, messageIds, labelId, account }) => {
+      if (!recordIds?.length && !messageIds?.length) {
+        return toolError('Name the messages to change: recordIds (Agnoclast email records) or messageIds (Gmail ids).')
+      }
+      // A label action with no id is not an error worth bouncing — answer it with the list, so the agent
+      // can act on the reply instead of guessing an id or asking the person for one.
+      if ((action === 'add_label' || action === 'remove_label') && !labelId) {
+        const lr = await fetchCortex(`${BASE}/api/gmail/labels${account ? `?account=${encodeURIComponent(account)}` : ''}`,
+          { headers: { Authorization: `Bearer ${TOKEN}` } })
+        const lb = await lr.json().catch(() => null)
+        if (!lr.ok) return gmailWriteError(lr, lb, 'gmail_modify')
+        const labels = Array.isArray(lb?.labels) ? lb.labels : []
+        if (!labels.length) return toolError(`${lb?.account ?? 'That mailbox'} has no labels you can add or remove. Nothing was changed.`)
+        return toolError(
+          `labelId is required for ${action}. Labels in ${lb.account}:\n` +
+          labels.map((l) => `- ${l.name} → ${l.id}${l.type === 'system' ? ' (system)' : ''}`).join('\n') +
+          `\nCall gmail_modify again with one of those ids. Nothing was changed.`)
+      }
+      const res = await fetchCortex(`${BASE}/api/gmail/messages/modify`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          action,
+          ...(labelId ? { labelId } : {}),
+          ...(account ? { account } : {}),
+          ...(recordIds?.length ? { recordIds } : { messageIds }),
+        }),
+      })
+      const body = await res.json().catch(() => null)
+      if (!res.ok) return gmailWriteError(res, body, 'gmail_modify')
+      // Per-message results, because a batch can partly fail and the person needs to know which.
+      const results = Array.isArray(body?.results) ? body.results : []
+      const failed = results.filter((r) => r && r.ok === false)
+      const changed = results.length - failed.length
+      const lines = [`${action} in ${body.account}: ${changed} of ${results.length} message${results.length === 1 ? '' : 's'} changed.`]
+      if (failed.length) {
+        lines.push(`⚠ ${failed.length} did NOT change:`)
+        for (const f of failed.slice(0, 10)) lines.push(`- ${f.id}: ${f.error ?? 'unknown error'}`)
+        if (failed.length > 10) lines.push(`- …and ${failed.length - 10} more`)
+      }
+      return { content: [{ type: 'text', text: lines.join('\n') }] }
+    },
+  )
+
+  server.registerTool(
+    'draft_email_reply',
+    {
+      title: 'Save a reply as a draft in the user\'s Gmail',
+      description:
+        'Write a reply to one of the USER\'S OWN emails and save it as a DRAFT in their Gmail, threaded under the original. NOTHING IS SENT — the user reviews and sends it themselves from Gmail, so this is the safe way to help with a reply. Identify the email by recordId (an Agnoclast email record) or messageId (a Gmail id). Only the mailbox owner can draft against a message; the server enforces that. Use request_send_email instead when the user wants it actually sent.',
+      inputSchema: {
+        recordId: z.string().optional().describe('the Agnoclast email record to reply to'),
+        messageId: z.string().optional().describe('the Gmail message id to reply to — an alternative to recordId'),
+        text: z.string().min(1).describe('the reply body, as plain text'),
+        account: z.string().email().optional().describe('which connected Gmail account, when the user has more than one'),
+      },
+    },
+    async ({ recordId, messageId, text, account }) => {
+      if (!recordId && !messageId) return toolError('Name the email to reply to: recordId or messageId.')
+      const res = await fetchCortex(`${BASE}/api/gmail/drafts`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ...(recordId ? { recordId } : { messageId }), text, ...(account ? { account } : {}) }),
+      })
+      const body = await res.json().catch(() => null)
+      if (!res.ok) return gmailWriteError(res, body, 'draft_email_reply')
+      return { content: [{ type: 'text', text:
+        `Draft saved in ${body.account} — NOT sent. The user reviews and sends it from Gmail: ${body.openUrl}` }] }
+    },
+  )
+
+  // request_send_email — the one tool here that can put mail in front of a person's contacts.
+  //
+  // ⚠ D5: THIS POST IS NOT IDEMPOTENT AND MUST NEVER BE RETRIED. `idempotent: false` is passed
+  // EXPLICITLY rather than relying on fetchCortex's GET/HEAD-only default, so that widening the default
+  // later cannot silently make sending an email retriable. A 5xx here may mean the mail went out.
+  //
+  // ⚠ THE reviewUrl CONTRACT (the V5 hand-off documented in send-requests/route.ts). The route OMITS the
+  // key when there is nothing to approve, so PRESENCE is the signal and `in` must not be used. Present →
+  // pending, and the sentence below is relayed verbatim. ABSENT → the send rule allowed it and the mail
+  // has ALREADY GONE; never invent a link or claim an approval is pending in that case.
+  server.registerTool(
+    'request_send_email',
+    {
+      title: 'Ask to send an email from the user\'s Gmail',
+      description:
+        'Send an email from the USER\'S OWN connected Gmail. By default this does NOT send immediately: it creates a request that WAITS for the user to approve it in Agnoclast, and it goes out at once only if their own send rule allows it. The message is frozen when the request is made, so write the final wording. Always show the user what you are about to send and get their agreement first. Returns either an approval link to relay to them, or confirmation that it already went. ⚠ NEVER call this twice for the same email — it is not idempotent, and a retry can send twice.',
+      inputSchema: {
+        to: z.array(z.string()).min(1).describe('recipient email addresses'),
+        subject: z.string().min(1).describe('the subject line'),
+        text: z.string().min(1).describe('the message body, as plain text'),
+        cc: z.array(z.string()).optional().describe('cc addresses'),
+        bcc: z.array(z.string()).optional().describe('bcc addresses'),
+        replyToRecordId: z.string().optional().describe('reply in the thread of this Agnoclast email record'),
+        replyToMessageId: z.string().optional().describe('reply in the thread of this Gmail message id'),
+        account: z.string().email().optional().describe('which connected Gmail account to send from, when the user has more than one'),
+      },
+    },
+    async ({ to, subject, text, cc, bcc, replyToRecordId, replyToMessageId, account }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/gmail/send-requests`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            to, subject, text,
+            ...(cc?.length ? { cc } : {}), ...(bcc?.length ? { bcc } : {}),
+            ...(replyToRecordId ? { replyToRecordId } : {}),
+            ...(replyToMessageId ? { replyToMessageId } : {}),
+            ...(account ? { account } : {}),
+          }),
+        }, { idempotent: false, retries: 0 })
+      } catch (e) {
+        // No response at all: the request may still have reached the server. Say so and stop.
+        return toolError(
+          `Could not confirm the send request: ${e.message} ⚠ It may have been created anyway. ` +
+          `Do NOT call request_send_email again — ask the user to check Email in Agnoclast.`)
+      }
+      const body = await res.json().catch(() => null)
+      if (!res.ok) return gmailWriteError(res, body, 'request_send_email')
+
+      // PRESENCE, not `in` — the route omits the key rather than sending null (pinned by
+      // src/send_request_verbs_test.ts). Absent means it already sent.
+      const reviewUrl = body?.reviewUrl
+      const acct = body?.request?.account ?? 'your Gmail'
+      const n = body?.request?.recipientCount ?? to.length
+      if (reviewUrl) {
+        // Relayed VERBATIM — this exact sentence is the contract the create route records.
+        return { content: [{ type: 'text', text:
+          `Send request created from ${acct} to ${n} recipient${n === 1 ? '' : 's'}. It is NOT sent yet. ` +
+          `Tell the user, in these words: It's waiting for your OK: ${reviewUrl}` }] }
+      }
+      const state = body?.request?.state ?? 'sent'
+      return { content: [{ type: 'text', text:
+        `Sent from ${acct} to ${n} recipient${n === 1 ? '' : 's'} — the user's send rule allowed it, so there is ` +
+        `nothing to approve (state: ${state}). Do not offer an approval link; the email has already gone.` }] }
+    },
+  )
+
   server.registerTool(
     'grep',
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/agnoclast-mcp",
-  "version": "0.9.176",
+  "version": "0.9.178",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {