@paigy/mcp 0.31.1 → 0.33.0

package/README.md

@@ -4,7 +4,7 @@
 > QR scan; no pairing codes. Everything below is the manual per-client reference for
 > machines that can't run the harness.
 
-A voice inbox for your AI agents. This MCP server lets an agent **notify a user** and **await their reply** — so a long-running agent can ask a question, hand off, and resume on the answer. It's a thin MCP-tool wrapper over `@paigy/sdk` (`packages/sdk`) — use the SDK directly from any Node process that isn't an MCP client.
+The AI agent harness that calls you. This MCP server lets an agent **notify a user** and **await their reply** — so a long-running agent can ask a question, hand off, and resume on the answer. It's a thin MCP-tool wrapper over `@paigy/sdk` (`packages/sdk`) — use the SDK directly from any Node process that isn't an MCP client.
 
 ## Install
 
@@ -118,7 +118,7 @@ Then pair: `PAIGY_AGENT=gemini npx -p @paigy/mcp@latest paigy-mcp-onboard`.
 
 - **`pair`** — pair this agent with the user's Paigy account (one-time). No args to start: returns the code to show the user **and begins polling for approval in the background**; pass the returned `device_code` to collect the result (it returns the moment the user approves). On success it prompts you to allowlist Paigy's notify/await tools so they run without an approval prompt each time.
 - **`unpair`** — log this agent out of the user's Paigy account; revokes the token server-side and deletes the local one.
-- **`enable_tools`** — after pairing (and only with the user's consent), allowlist Paigy's notify/await tools so they run without an approval prompt each time. Writes Claude Code's `permissions.allow` — `scope:'user'` (default, every project) or `scope:'project'` (this repo). Merges, never clobbers; leaves `pair`/`unpair` human-approved.
+- **`paigy-enable-tools`** (a CLI, *not* a tool) — allowlist Paigy's notify/await tools so they run without an approval prompt each time. `npx -y -p @paigy/mcp@latest paigy-enable-tools` (or `paigy-harness enable-tools`); `--scope project` limits it to the current repo instead of `~/.claude/settings.json`. Merges, never clobbers; leaves `pair`/`unpair` human-approved. **This is deliberately not an MCP tool.** It writes the calling agent's own permission allowlist, which every host worth trusting treats as privilege escalation — Claude Code's auto mode denies it outright, and the user's consent inside Paigy is invisible to the classifier making that call. `pair` returns the command for the agent to print; a human runs it.
 - **`contact`** — THE way to reach the user: tell them something, or ask and get their answer. Core form is two fields — `ask` (plain prose: what you need to tell them or find out) and `waiting` (what happens to your work meanwhile: `none` = just informing, `soft` = want an answer but can keep working, `hard` = stopped until answered — reaches them urgently and escalates to a real phone call). Paigy's broker picks the channel, phrasing, and answer format. When the choices themselves must be *seen*, attach `options` (each may carry a sandboxed `html` or `image` preview); attach `visuals` for context screenshots. Returns `{ notificationId, threadId }`; a threaded follow-up supersedes that thread's pending items, and an identical threaded re-send escalates in place. If a reply comes back as `{kind:'clarify', chunks:[...]}`, contact again on the SAME threadId with an expanded ask. (The former `notify_user`/`notify` names remain accepted as hidden aliases for older setups, and the fully-shaped wire form — context/select/urgency — is still accepted from code; neither is part of the model surface anymore.)
 - **`await_reply`** — wait for the user's reply to a specific notification (pass its notificationId). Scoped: will not return replies meant for other notifications. Returns `reply` / `remind` / `idle`.
 - **`check_replies`** — catch-up sweep: returns replies you haven't consumed yet (now marked seen) plus still-pending notifications, new user-initiated requests, and owed callbacks.

package/dist/{chunk-2WPQJYJH.js → chunk-E3OWSUGJ.js}

@@ -2390,6 +2390,12 @@ var ReceiptEventSchema = z.enum([
   // the recipient opened it
   "answered",
   // the recipient replied
+  // The recipient TURNED THE RING DOWN — CallKit ended it and no answer was ever tapped.
+  // Written by the phone, on the same door that reports the ring itself, so it exists only
+  // when a ring reached a running app and a person did not take it. That is what separates
+  // it from "a ring with no answer", which our own crashes wrote just as readily and which
+  // is why the responsiveness back-off had to be removed (#1144).
+  "declined",
   "escalated",
   // re-reached at a higher level (re-ring / promote)
   "coalesced",
@@ -2398,8 +2404,14 @@ var ReceiptEventSchema = z.enum([
   // deadline passed unanswered
   "woke",
   // the agent was woken for an owed obligation (callback)
-  "gave_up"
+  "gave_up",
   // the budget was spent — stopped re-engaging
+  // The ladder starts over — a silent pickup (the owner's fresh-miss rule, 2026-07-28), a
+  // promote to call, a re-delivery. APPENDED, never a rewind: `ring_step` was a cache of
+  // the escalated-count and a writer rewound it to 0 on every unanswered call (2026-08-24,
+  // nine rings in an hour, `gaveUp` unreachable). A count since the last `restarted` cannot
+  // be rewound by a writer that forgot to advance it.
+  "restarted"
 ]);
 var AttentionSchema = z.object({
   urgency: NotifyLevelSchema,
@@ -2531,7 +2543,7 @@ var NotifyRequestSchema = z.object({
   if (r.ask !== void 0) {
     for (const f of ["context", "select", "points"]) {
       if (r[f] !== void 0)
-        ctx.addIssue({ code: z.ZodIssueCode.custom, path: [f], message: `the simplified \`ask\` form takes no ${f} \u2014 the broker derives it (use \`needs\` for multi-part asks)` });
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: [f], message: `the simplified \`ask\` form takes no ${f} \u2014 the broker derives the answer shape from your prose. Drop ${f} and say it in \`ask\` instead ("should I\u2026" for approve/deny, "which of these\u2026" for a pick), passing \`options\` when you're offering concrete alternatives.` });
     }
     return;
   }
@@ -2644,6 +2656,14 @@ var IntentSchema = z.object({
    *  about what cannot answer "is the bot looping less this week?". */
   fault: z.enum(["loop", "unanswered", "overridden", "misheard", "slow", "other"]).optional()
 });
+var RideAlongSchema = z.object({
+  /** The note this came from — assign/clarify/close it through /api/notes/:id. */
+  noteId: z.string(),
+  /** What to do, in the owner's own words (the note's headline). Never model-rewritten. */
+  text: z.string(),
+  /** The thread to report back on, when the note was dispatched over the request rail. */
+  parentId: z.string().nullable()
+});
 var AwaitItemSchema = z.discriminatedUnion("type", [
   z.object({
     type: z.literal("reply"),
@@ -2664,7 +2684,13 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
     transcript: z.string().optional(),
     /** Coverage report (#396), when the ask declared `points`: which of them this
      *  answer addressed. Missing points = re-ask or proceed knowingly partial. */
-    covered: z.array(z.string()).optional()
+    covered: z.array(z.string()).optional(),
+    /** Ride-alongs (RideAlongSchema) — pending work for you, attached to the moment you
+     *  became free. Only `reply` and `idle` carry it: those are the two outcomes that
+     *  END a wait. `remind`, `superseded` and `turn` are mid-flight, and handing an
+     *  agent a side-quest while it is still holding the line is how the main thing gets
+     *  dropped. Absent/empty = nothing owed. */
+    also: z.array(RideAlongSchema).optional()
   }),
   z.object({
     type: z.literal("remind"),
@@ -2699,7 +2725,7 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
       acts: z.array(IntentSchema).nullable().optional()
     })
   }),
-  z.object({ type: z.literal("idle") })
+  z.object({ type: z.literal("idle"), also: z.array(RideAlongSchema).optional() })
 ]);
 var CallbackTriggerSchema = z.enum(["on_done", "on_blocked", "scheduled"]);
 var ScheduleCallbackSchema = z.object({
@@ -2747,6 +2773,9 @@ var PendingRepliesSchema = z.object({
   /** Callbacks you owe the user that are now DUE (you said you'd follow up when done,
    *  if blocked, or at a time that has passed). Re-surfaced every sweep until you
    *  fulfill one by calling contact on its parentId. */
+  /** Ride-alongs (RideAlongSchema): notes assigned to this agent that no wake could
+   *  reach. Same array the contact/await replies carry — one queue, every carrier. */
+  also: z.array(RideAlongSchema).optional(),
   owedCallbacks: z.array(
     z.object({ parentId: z.string(), trigger: CallbackTriggerSchema, note: z.string() })
   ),
@@ -2782,7 +2811,11 @@ var NotifyResponseSchema = z.object({
   status: NotifyStatusSchema,
   createdAt: z.string().datetime(),
   answer: UserAnswerSchema.optional(),
-  answeredAt: z.string().datetime().optional()
+  answeredAt: z.string().datetime().optional(),
+  /** Ride-alongs for THIS agent — pending work it should pick up when it's done with
+   *  what it came for. Present on any reply, because an unwakeable agent's only
+   *  reliable moment is one it initiated. Absent/empty = nothing owed. */
+  also: z.array(RideAlongSchema).optional()
 });
 var NotifyPlanUnitSchema = z.object({
   notificationId: z.string(),
@@ -2795,7 +2828,22 @@ var NotifyPlanUnitSchema = z.object({
   settled: z.literal(true).optional(),
   /** What this unit would need to be answerable and does not carry (#894). A PROPOSAL to the
    *  agent — nothing here changed the ask, and ignoring it costs nothing. */
-  needs: z.array(z.enum(["options", "visuals"])).optional()
+  needs: z.array(z.enum(["options", "visuals"])).optional(),
+  /** The SHAPE the broker would give this unit, for the agent to ratify (#886/#894). The
+   *  split layer reads prose and can see that a paragraph is a yes/no or a pick-one — but a
+   *  broker that DECIDES that destroys the only fact separating a statement from a real ask
+   *  (#731), so it is offered, never applied: the unit is stored `text` until the agent
+   *  confirms the shape (POST /notify/:id/confirm). Ignoring it costs nothing. */
+  proposal: z.object({
+    select: SelectShapeSchema,
+    options: z.array(z.object({ label: z.string().min(1) })).optional()
+  }).optional(),
+  /** What the broker READ this unit as wanting from the human (#952 layer 2): a `decision`
+   *  between alternatives, an `approval` the agent is blocked on, or `knowledge` it just
+   *  needs to know. Reported so the agent can correct a misread the same way it ratifies a
+   *  shape — the read RAISES (a decision always asks) and never silences a question the
+   *  agent declared (#731, #923). */
+  wants: z.enum(["decision", "approval", "knowledge"]).optional()
 });
 var NotifyPlanSchema = z.object({
   units: z.array(NotifyPlanUnitSchema),
@@ -2819,6 +2867,9 @@ var UserResponseSchema = z.object({
 });
 var VoiceKeySchema = z.enum(["rachel", "george", "jessica", "brian", "lily"]);
 var AgendaTurnSchema = z.object({
+  /** Twin coverage (#1089): sibling claim ids this asking turn's answer ALSO settles —
+   *  the planner declares duplicates instead of asking them twice. */
+  coveredIds: z.array(z.string()).optional(),
   /** At most three short spoken sentences. Capped because a turn is a breath: a 1031-char
    *  line went out on 2026-07-28 and the caller could not answer it at all. */
   info: z.array(z.string().min(1)).max(3).default([]),
@@ -2852,6 +2903,7 @@ var AgendaTurnSchema = z.object({
    *  on, the claim stays pending; blocking:true on context = hold for a reply. */
   blocking: z.boolean().optional()
 });
+var CLAIM_STALE_MS = 30 * 6e4;
 var InboxItemSchema = z.object({
   id: z.string(),
   /** The conversation thread + connection this item lives on. Present on the replied
@@ -2871,6 +2923,15 @@ var InboxItemSchema = z.object({
    *  (live 2026-08-10, D35). The API already orders by it; this lets a reader that
    *  re-sorts (grouping, filtering) put an arrival back in the order it was written. */
   seq: z.number().int().optional(),
+  /** HOW MANY units the arrival was cut into. A device reads a LENS, never the arrival —
+   *  `/api/inbox` serves `open`, so the units already settled are gone from it — and a client
+   *  counting what it can see is counting what is LEFT. Walking a three-unit ask on the answer
+   *  screen read "1 of 3", then "1 of 2", then no chip at all, each answer having removed the
+   *  only evidence of itself. How big an arrival is, is a fact about the arrival, so the
+   *  server that can still see every row states it. Absent on any row with no `askId`: a
+   *  unit knows WHICH ask it came from and WHERE it sat in it, and how many there were is
+   *  the one part of its own arrival a single row cannot answer. */
+  units: z.number().int().positive().optional(),
   tokenId: z.string().optional(),
   status: NotifyStatusSchema,
   context: ContextSchema,
@@ -2886,6 +2947,21 @@ var InboxItemSchema = z.object({
    *  its acknowledge affordance: without it a status update offers a text box and a dismiss,
    *  and neither of those is "got it" (owner, 2026-08-10). */
   asks: z.boolean().optional(),
+  /** When a live process last pulsed for this row's agent — the liveness input for
+   *  "working requires a pulse" (#928): the list said "Working…" from agent_state alone
+   *  while the party called the same dead claim stalled. Absent = no token/no data,
+   *  which must never CLAIM stalled. */
+  lastSeenAt: z.string().optional(),
+  /** WHEN THE AGENT LAST SAID ANYTHING ABOUT THIS CLAIM — the newest `agent_state` row in
+   *  the `notification_events` ledger (trigger-written since 20260621010000, so every row a
+   *  user can see has one). The age input for `CLAIM_STALE_MS`, and it has to be this rather
+   *  than `createdAt`: a claim is very often picked up long after the row was born — the
+   *  inbox keeps an ANSWERED row visible while the agent works the follow-up, so a question
+   *  asked this morning and claimed a minute ago is eight hours old and one minute into its
+   *  work. Reading the row's birth as the claim's age brands that "No update in 8h" the
+   *  instant the agent picks it up (#997). Absent = pre-trigger row; fall back to
+   *  `createdAt`. */
+  agentStateAt: z.string().datetime().optional(),
   agenda: z.array(AgendaTurnSchema).optional(),
   /** On a replied detail (#397): the next steps the user attached to the answer
    *  ("call back after lunch") — shown so they can see the commitment was captured. */
@@ -2924,7 +3000,7 @@ var InboxItemSchema = z.object({
   why: z.object({
     asked: NotifyLevelSchema,
     got: NotifyLevelSchema,
-    because: z.enum(["unresponsive", "dismissed", "not_permitted", "silent", "coalesced", "agent_capped", "unplanned"]).optional(),
+    because: z.enum(["unresponsive", "dismissed", "not_permitted", "silent", "coalesced", "agent_capped", "unplanned", "learned_raise"]).optional(),
     line: z.string()
   }).optional(),
   select: z.enum(["one", "many", "rank", "confirm", "text"]).default("one"),
@@ -2957,11 +3033,23 @@ var SnoozeRequestSchema = z.object({
   requestId: z.string(),
   until: z.string().datetime()
 });
+var APNS_TOKEN_RE = /^[0-9a-fA-F]{64}$/;
 var PushTokenSchema = z.object({
   voipToken: z.string().min(1).optional(),
   alertToken: z.string().min(1).optional(),
   fcmToken: z.string().min(1).optional(),
   platform: z.enum(["ios", "android"])
+}).superRefine((v, ctx) => {
+  if (v.platform !== "ios") return;
+  for (const field of ["voipToken", "alertToken"]) {
+    const token = v[field];
+    if (token === void 0 || APNS_TOKEN_RE.test(token)) continue;
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: [field],
+      message: `not an APNs device token (want 64 hex chars, got ${token.length})`
+    });
+  }
 });
 var MissedCallSchema = z.enum([
   "retry_10m",
@@ -3012,6 +3100,15 @@ var UserSettingsSchema = z.object({
   /** Opt-in to real-phone (PSTN) calls when the app can't ring. Optional, not
    *  defaulted — an older client PATCHing the full object must not clobber it. */
   pstnCalls: z.boolean().optional(),
+  /** The user's IANA timezone (e.g. "America/Bogota"), recorded by the app — it is the
+   *  only party that knows it. REMINDERS are why it exists: "remind me at ten" becomes
+   *  an absolute `due_at` only if we know whose ten. Optional and never defaulted, for
+   *  the same reason `voiceMode` is (a stale client PATCHing the whole object must not
+   *  clobber it) and one more: a GUESSED timezone schedules reminders hours off, and
+   *  that failure reads as the reminder rail being unreliable rather than as a missing
+   *  setting. Absent = a spoken time can't be landed, so the reminder rides the next
+   *  call — honest about what we know. */
+  timezone: z.string().min(1).max(64).optional(),
   /** Account E2EE state (text lane): 'off' (default) = today's plaintext; 'on' =
    *  content is sealed end-to-end between the local agent and the phone. Like
    *  voiceMode, OPTIONAL and NOT defaulted so a stale client PATCHing the full
@@ -3037,6 +3134,15 @@ var HistoryItemSchema = z.object({
   /** When you answered the agent's notification (agent→user only). */
   humanAckedAt: z.string().nullable()
 });
+var ACTIVITY_LINES = 2;
+var ACTIVITY_LINE_MAX = 80;
+var AgentActivitySchema = z.object({
+  /** Oldest first, so the newest line is last — the one that replaces in place. */
+  lines: z.array(z.string().max(ACTIVITY_LINE_MAX)).max(ACTIVITY_LINES),
+  /** When the harness observed this tail. Its own timestamp, not the heartbeat's: a beat
+   *  that carries an UNCHANGED tail must not make a stalled agent look like it just moved. */
+  at: z.string().datetime()
+});
 var ConnectionSummarySchema = z.object({
   /** The connection = the agent's token id (used to address a request). */
   id: z.string(),
@@ -3070,6 +3176,11 @@ var ConnectionSummarySchema = z.object({
     harnesses: z.array(z.object({ name: z.string(), label: z.string(), status: z.string() })).optional(),
     workspaces: z.array(z.string()).optional()
   }).optional(),
+  /** The tail of this agent's working log, when a harness is driving it — the agent page's
+   *  live strip. Absent for anything the desktop harness isn't running (a hatched identity
+   *  used straight from a terminal emits no work events; the page says so rather than
+   *  drawing an empty box). */
+  activity: AgentActivitySchema.optional(),
   /** True = a provider-managed agent running in the provider's cloud (e.g. Anthropic CMA);
    *  false = a local MCP connection running on the user's computer (Claude Code/Codex/…). */
   managed: z.boolean()
@@ -3138,7 +3249,8 @@ var HandoffSchema = z.object({
   recap: z.boolean().optional()
 });
 var NoteSourceSchema = z.enum(["app", "call"]);
-var NoteStatusSchema = z.enum(["open", "assigned", "done"]);
+var NoteStatusSchema = z.enum(["open", "assigned", "in_progress", "done"]);
+var NoteRepeatSchema = z.enum(["once", "until_done"]);
 var DecisionSchema = z.object({
   id: z.string(),
   /** The note this decision refines; null = recorded on a bare thread (the
@@ -3163,11 +3275,29 @@ var NoteSchema = z.object({
   assignee: z.string().nullable(),
   /** The request thread minted at assignment; null until assigned. */
   parentId: z.string().nullable(),
+  /** REMINDERS (reminders-design.md): the NOT-BEFORE this becomes eligible to ride a
+   *  call — never a deadline, and nothing rings when it passes. Null = "the very next
+   *  call", the right reading of "remind me to…" with no time attached. */
+  //  Defaulted, not required: a Note from an API deploy older than the reminders
+  //  migration has none of these, and the defaults ARE what it means — no not-before,
+  //  one ride, never ridden. Parsing must not fail across a rolling deploy.
+  dueAt: z.string().nullable().default(null),
+  repeat: NoteRepeatSchema.default("once"),
+  /** How many calls have already carried it — the fatigue cap counts rides, not days. */
+  rides: z.number().int().default(0),
+  lastRideAt: z.string().nullable().default(null),
   createdAt: z.string()
 });
 var CreateNoteSchema = z.object({
   /** The intent, in the user's own words. Stored verbatim; the broker only titles it. */
-  text: z.string().min(1).max(4e3)
+  text: z.string().min(1).max(4e3),
+  /** Capture it as a REMINDER — a note assigned to the user themselves, which rides
+   *  their next call instead of being handed to an agent. Everything else about the
+   *  note is identical; this is the one parameter that separates the two. */
+  forMe: z.boolean().optional(),
+  /** The not-before, when the user already said one. Absent = the very next call. */
+  dueAt: z.string().datetime().optional(),
+  repeat: NoteRepeatSchema.optional()
 });
 var RecordDecisionSchema = z.object({
   /** An open decision (from /clarify) to answer. */
@@ -4114,10 +4244,14 @@ async function setIdentity(patch, opts = {}) {
   return await res.json();
 }
 async function heartbeat(runtime, opts = {}) {
+  const body = {
+    ...runtime !== void 0 ? { runtime } : {},
+    ...opts.activity !== void 0 ? { activity: opts.activity } : {}
+  };
   const res = ensureAuthed(await reach(`${BACKEND_URL}/api/presence`, {
     method: "POST",
     headers: { "content-type": "application/json", authorization: `Bearer ${authToken(opts.token)}` },
-    ...runtime !== void 0 ? { body: JSON.stringify({ runtime }) } : {}
+    ...Object.keys(body).length > 0 ? { body: JSON.stringify(body) } : {}
   }));
   if (!res.ok) throw new Error(`heartbeat failed: ${res.status}`);
 }

package/dist/{chunk-PYORUJ7Q.js → chunk-JT7I3EGY.js}

@@ -51,6 +51,12 @@ var ReceiptEventSchema = z.enum([
   // the recipient opened it
   "answered",
   // the recipient replied
+  // The recipient TURNED THE RING DOWN — CallKit ended it and no answer was ever tapped.
+  // Written by the phone, on the same door that reports the ring itself, so it exists only
+  // when a ring reached a running app and a person did not take it. That is what separates
+  // it from "a ring with no answer", which our own crashes wrote just as readily and which
+  // is why the responsiveness back-off had to be removed (#1144).
+  "declined",
   "escalated",
   // re-reached at a higher level (re-ring / promote)
   "coalesced",
@@ -59,8 +65,14 @@ var ReceiptEventSchema = z.enum([
   // deadline passed unanswered
   "woke",
   // the agent was woken for an owed obligation (callback)
-  "gave_up"
+  "gave_up",
   // the budget was spent — stopped re-engaging
+  // The ladder starts over — a silent pickup (the owner's fresh-miss rule, 2026-07-28), a
+  // promote to call, a re-delivery. APPENDED, never a rewind: `ring_step` was a cache of
+  // the escalated-count and a writer rewound it to 0 on every unanswered call (2026-08-24,
+  // nine rings in an hour, `gaveUp` unreachable). A count since the last `restarted` cannot
+  // be rewound by a writer that forgot to advance it.
+  "restarted"
 ]);
 var AttentionSchema = z.object({
   urgency: NotifyLevelSchema,
@@ -192,7 +204,7 @@ var NotifyRequestSchema = z.object({
   if (r.ask !== void 0) {
     for (const f of ["context", "select", "points"]) {
       if (r[f] !== void 0)
-        ctx.addIssue({ code: z.ZodIssueCode.custom, path: [f], message: `the simplified \`ask\` form takes no ${f} \u2014 the broker derives it (use \`needs\` for multi-part asks)` });
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: [f], message: `the simplified \`ask\` form takes no ${f} \u2014 the broker derives the answer shape from your prose. Drop ${f} and say it in \`ask\` instead ("should I\u2026" for approve/deny, "which of these\u2026" for a pick), passing \`options\` when you're offering concrete alternatives.` });
     }
     return;
   }
@@ -250,6 +262,14 @@ var IntentSchema = z.object({
    *  about what cannot answer "is the bot looping less this week?". */
   fault: z.enum(["loop", "unanswered", "overridden", "misheard", "slow", "other"]).optional()
 });
+var RideAlongSchema = z.object({
+  /** The note this came from — assign/clarify/close it through /api/notes/:id. */
+  noteId: z.string(),
+  /** What to do, in the owner's own words (the note's headline). Never model-rewritten. */
+  text: z.string(),
+  /** The thread to report back on, when the note was dispatched over the request rail. */
+  parentId: z.string().nullable()
+});
 var AwaitItemSchema = z.discriminatedUnion("type", [
   z.object({
     type: z.literal("reply"),
@@ -270,7 +290,13 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
     transcript: z.string().optional(),
     /** Coverage report (#396), when the ask declared `points`: which of them this
      *  answer addressed. Missing points = re-ask or proceed knowingly partial. */
-    covered: z.array(z.string()).optional()
+    covered: z.array(z.string()).optional(),
+    /** Ride-alongs (RideAlongSchema) — pending work for you, attached to the moment you
+     *  became free. Only `reply` and `idle` carry it: those are the two outcomes that
+     *  END a wait. `remind`, `superseded` and `turn` are mid-flight, and handing an
+     *  agent a side-quest while it is still holding the line is how the main thing gets
+     *  dropped. Absent/empty = nothing owed. */
+    also: z.array(RideAlongSchema).optional()
   }),
   z.object({
     type: z.literal("remind"),
@@ -305,7 +331,7 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
       acts: z.array(IntentSchema).nullable().optional()
     })
   }),
-  z.object({ type: z.literal("idle") })
+  z.object({ type: z.literal("idle"), also: z.array(RideAlongSchema).optional() })
 ]);
 var CallbackTriggerSchema = z.enum(["on_done", "on_blocked", "scheduled"]);
 var ScheduleCallbackSchema = z.object({
@@ -353,6 +379,9 @@ var PendingRepliesSchema = z.object({
   /** Callbacks you owe the user that are now DUE (you said you'd follow up when done,
    *  if blocked, or at a time that has passed). Re-surfaced every sweep until you
    *  fulfill one by calling contact on its parentId. */
+  /** Ride-alongs (RideAlongSchema): notes assigned to this agent that no wake could
+   *  reach. Same array the contact/await replies carry — one queue, every carrier. */
+  also: z.array(RideAlongSchema).optional(),
   owedCallbacks: z.array(
     z.object({ parentId: z.string(), trigger: CallbackTriggerSchema, note: z.string() })
   ),
@@ -388,7 +417,11 @@ var NotifyResponseSchema = z.object({
   status: NotifyStatusSchema,
   createdAt: z.string().datetime(),
   answer: UserAnswerSchema.optional(),
-  answeredAt: z.string().datetime().optional()
+  answeredAt: z.string().datetime().optional(),
+  /** Ride-alongs for THIS agent — pending work it should pick up when it's done with
+   *  what it came for. Present on any reply, because an unwakeable agent's only
+   *  reliable moment is one it initiated. Absent/empty = nothing owed. */
+  also: z.array(RideAlongSchema).optional()
 });
 var NotifyPlanUnitSchema = z.object({
   notificationId: z.string(),
@@ -401,7 +434,22 @@ var NotifyPlanUnitSchema = z.object({
   settled: z.literal(true).optional(),
   /** What this unit would need to be answerable and does not carry (#894). A PROPOSAL to the
    *  agent — nothing here changed the ask, and ignoring it costs nothing. */
-  needs: z.array(z.enum(["options", "visuals"])).optional()
+  needs: z.array(z.enum(["options", "visuals"])).optional(),
+  /** The SHAPE the broker would give this unit, for the agent to ratify (#886/#894). The
+   *  split layer reads prose and can see that a paragraph is a yes/no or a pick-one — but a
+   *  broker that DECIDES that destroys the only fact separating a statement from a real ask
+   *  (#731), so it is offered, never applied: the unit is stored `text` until the agent
+   *  confirms the shape (POST /notify/:id/confirm). Ignoring it costs nothing. */
+  proposal: z.object({
+    select: SelectShapeSchema,
+    options: z.array(z.object({ label: z.string().min(1) })).optional()
+  }).optional(),
+  /** What the broker READ this unit as wanting from the human (#952 layer 2): a `decision`
+   *  between alternatives, an `approval` the agent is blocked on, or `knowledge` it just
+   *  needs to know. Reported so the agent can correct a misread the same way it ratifies a
+   *  shape — the read RAISES (a decision always asks) and never silences a question the
+   *  agent declared (#731, #923). */
+  wants: z.enum(["decision", "approval", "knowledge"]).optional()
 });
 var NotifyPlanSchema = z.object({
   units: z.array(NotifyPlanUnitSchema),
@@ -425,6 +473,9 @@ var UserResponseSchema = z.object({
 });
 var VoiceKeySchema = z.enum(["rachel", "george", "jessica", "brian", "lily"]);
 var AgendaTurnSchema = z.object({
+  /** Twin coverage (#1089): sibling claim ids this asking turn's answer ALSO settles —
+   *  the planner declares duplicates instead of asking them twice. */
+  coveredIds: z.array(z.string()).optional(),
   /** At most three short spoken sentences. Capped because a turn is a breath: a 1031-char
    *  line went out on 2026-07-28 and the caller could not answer it at all. */
   info: z.array(z.string().min(1)).max(3).default([]),
@@ -458,6 +509,7 @@ var AgendaTurnSchema = z.object({
    *  on, the claim stays pending; blocking:true on context = hold for a reply. */
   blocking: z.boolean().optional()
 });
+var CLAIM_STALE_MS = 30 * 6e4;
 var InboxItemSchema = z.object({
   id: z.string(),
   /** The conversation thread + connection this item lives on. Present on the replied
@@ -477,6 +529,15 @@ var InboxItemSchema = z.object({
    *  (live 2026-08-10, D35). The API already orders by it; this lets a reader that
    *  re-sorts (grouping, filtering) put an arrival back in the order it was written. */
   seq: z.number().int().optional(),
+  /** HOW MANY units the arrival was cut into. A device reads a LENS, never the arrival —
+   *  `/api/inbox` serves `open`, so the units already settled are gone from it — and a client
+   *  counting what it can see is counting what is LEFT. Walking a three-unit ask on the answer
+   *  screen read "1 of 3", then "1 of 2", then no chip at all, each answer having removed the
+   *  only evidence of itself. How big an arrival is, is a fact about the arrival, so the
+   *  server that can still see every row states it. Absent on any row with no `askId`: a
+   *  unit knows WHICH ask it came from and WHERE it sat in it, and how many there were is
+   *  the one part of its own arrival a single row cannot answer. */
+  units: z.number().int().positive().optional(),
   tokenId: z.string().optional(),
   status: NotifyStatusSchema,
   context: ContextSchema,
@@ -492,6 +553,21 @@ var InboxItemSchema = z.object({
    *  its acknowledge affordance: without it a status update offers a text box and a dismiss,
    *  and neither of those is "got it" (owner, 2026-08-10). */
   asks: z.boolean().optional(),
+  /** When a live process last pulsed for this row's agent — the liveness input for
+   *  "working requires a pulse" (#928): the list said "Working…" from agent_state alone
+   *  while the party called the same dead claim stalled. Absent = no token/no data,
+   *  which must never CLAIM stalled. */
+  lastSeenAt: z.string().optional(),
+  /** WHEN THE AGENT LAST SAID ANYTHING ABOUT THIS CLAIM — the newest `agent_state` row in
+   *  the `notification_events` ledger (trigger-written since 20260621010000, so every row a
+   *  user can see has one). The age input for `CLAIM_STALE_MS`, and it has to be this rather
+   *  than `createdAt`: a claim is very often picked up long after the row was born — the
+   *  inbox keeps an ANSWERED row visible while the agent works the follow-up, so a question
+   *  asked this morning and claimed a minute ago is eight hours old and one minute into its
+   *  work. Reading the row's birth as the claim's age brands that "No update in 8h" the
+   *  instant the agent picks it up (#997). Absent = pre-trigger row; fall back to
+   *  `createdAt`. */
+  agentStateAt: z.string().datetime().optional(),
   agenda: z.array(AgendaTurnSchema).optional(),
   /** On a replied detail (#397): the next steps the user attached to the answer
    *  ("call back after lunch") — shown so they can see the commitment was captured. */
@@ -530,7 +606,7 @@ var InboxItemSchema = z.object({
   why: z.object({
     asked: NotifyLevelSchema,
     got: NotifyLevelSchema,
-    because: z.enum(["unresponsive", "dismissed", "not_permitted", "silent", "coalesced", "agent_capped", "unplanned"]).optional(),
+    because: z.enum(["unresponsive", "dismissed", "not_permitted", "silent", "coalesced", "agent_capped", "unplanned", "learned_raise"]).optional(),
     line: z.string()
   }).optional(),
   select: z.enum(["one", "many", "rank", "confirm", "text"]).default("one"),
@@ -563,11 +639,23 @@ var SnoozeRequestSchema = z.object({
   requestId: z.string(),
   until: z.string().datetime()
 });
+var APNS_TOKEN_RE = /^[0-9a-fA-F]{64}$/;
 var PushTokenSchema = z.object({
   voipToken: z.string().min(1).optional(),
   alertToken: z.string().min(1).optional(),
   fcmToken: z.string().min(1).optional(),
   platform: z.enum(["ios", "android"])
+}).superRefine((v, ctx) => {
+  if (v.platform !== "ios") return;
+  for (const field of ["voipToken", "alertToken"]) {
+    const token = v[field];
+    if (token === void 0 || APNS_TOKEN_RE.test(token)) continue;
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: [field],
+      message: `not an APNs device token (want 64 hex chars, got ${token.length})`
+    });
+  }
 });
 var MissedCallSchema = z.enum([
   "retry_10m",
@@ -579,6 +667,16 @@ var MissedCallSchema = z.enum([
   "inbox",
   "dismiss"
 ]);
+var MISSED_CALL_PLAN = {
+  retry_10m: { kind: "every", minutes: 10 },
+  retry_30m: { kind: "every", minutes: 30 },
+  retry_60m: { kind: "every", minutes: 60 },
+  backoff_gentle: { kind: "at", minutes: [30, 120, 360] },
+  backoff_standard: { kind: "at", minutes: [10, 30, 120] },
+  backoff_aggressive: { kind: "at", minutes: [5, 15, 45] },
+  inbox: { kind: "once" },
+  dismiss: { kind: "grace", minutes: 2 }
+};
 var BrokerTuningSchema = z.object({
   /** 'none' = skip the spoken ack after a mapped answer (power users find it slow). */
   ackVerbosity: z.enum(["normal", "none"]).optional(),
@@ -618,6 +716,15 @@ var UserSettingsSchema = z.object({
   /** Opt-in to real-phone (PSTN) calls when the app can't ring. Optional, not
    *  defaulted — an older client PATCHing the full object must not clobber it. */
   pstnCalls: z.boolean().optional(),
+  /** The user's IANA timezone (e.g. "America/Bogota"), recorded by the app — it is the
+   *  only party that knows it. REMINDERS are why it exists: "remind me at ten" becomes
+   *  an absolute `due_at` only if we know whose ten. Optional and never defaulted, for
+   *  the same reason `voiceMode` is (a stale client PATCHing the whole object must not
+   *  clobber it) and one more: a GUESSED timezone schedules reminders hours off, and
+   *  that failure reads as the reminder rail being unreliable rather than as a missing
+   *  setting. Absent = a spoken time can't be landed, so the reminder rides the next
+   *  call — honest about what we know. */
+  timezone: z.string().min(1).max(64).optional(),
   /** Account E2EE state (text lane): 'off' (default) = today's plaintext; 'on' =
    *  content is sealed end-to-end between the local agent and the phone. Like
    *  voiceMode, OPTIONAL and NOT defaulted so a stale client PATCHing the full
@@ -643,6 +750,15 @@ var HistoryItemSchema = z.object({
   /** When you answered the agent's notification (agent→user only). */
   humanAckedAt: z.string().nullable()
 });
+var ACTIVITY_LINES = 2;
+var ACTIVITY_LINE_MAX = 80;
+var AgentActivitySchema = z.object({
+  /** Oldest first, so the newest line is last — the one that replaces in place. */
+  lines: z.array(z.string().max(ACTIVITY_LINE_MAX)).max(ACTIVITY_LINES),
+  /** When the harness observed this tail. Its own timestamp, not the heartbeat's: a beat
+   *  that carries an UNCHANGED tail must not make a stalled agent look like it just moved. */
+  at: z.string().datetime()
+});
 var ConnectionSummarySchema = z.object({
   /** The connection = the agent's token id (used to address a request). */
   id: z.string(),
@@ -676,6 +792,11 @@ var ConnectionSummarySchema = z.object({
     harnesses: z.array(z.object({ name: z.string(), label: z.string(), status: z.string() })).optional(),
     workspaces: z.array(z.string()).optional()
   }).optional(),
+  /** The tail of this agent's working log, when a harness is driving it — the agent page's
+   *  live strip. Absent for anything the desktop harness isn't running (a hatched identity
+   *  used straight from a terminal emits no work events; the page says so rather than
+   *  drawing an empty box). */
+  activity: AgentActivitySchema.optional(),
   /** True = a provider-managed agent running in the provider's cloud (e.g. Anthropic CMA);
    *  false = a local MCP connection running on the user's computer (Claude Code/Codex/…). */
   managed: z.boolean()
@@ -744,7 +865,8 @@ var HandoffSchema = z.object({
   recap: z.boolean().optional()
 });
 var NoteSourceSchema = z.enum(["app", "call"]);
-var NoteStatusSchema = z.enum(["open", "assigned", "done"]);
+var NoteStatusSchema = z.enum(["open", "assigned", "in_progress", "done"]);
+var NoteRepeatSchema = z.enum(["once", "until_done"]);
 var DecisionSchema = z.object({
   id: z.string(),
   /** The note this decision refines; null = recorded on a bare thread (the
@@ -769,11 +891,29 @@ var NoteSchema = z.object({
   assignee: z.string().nullable(),
   /** The request thread minted at assignment; null until assigned. */
   parentId: z.string().nullable(),
+  /** REMINDERS (reminders-design.md): the NOT-BEFORE this becomes eligible to ride a
+   *  call — never a deadline, and nothing rings when it passes. Null = "the very next
+   *  call", the right reading of "remind me to…" with no time attached. */
+  //  Defaulted, not required: a Note from an API deploy older than the reminders
+  //  migration has none of these, and the defaults ARE what it means — no not-before,
+  //  one ride, never ridden. Parsing must not fail across a rolling deploy.
+  dueAt: z.string().nullable().default(null),
+  repeat: NoteRepeatSchema.default("once"),
+  /** How many calls have already carried it — the fatigue cap counts rides, not days. */
+  rides: z.number().int().default(0),
+  lastRideAt: z.string().nullable().default(null),
   createdAt: z.string()
 });
 var CreateNoteSchema = z.object({
   /** The intent, in the user's own words. Stored verbatim; the broker only titles it. */
-  text: z.string().min(1).max(4e3)
+  text: z.string().min(1).max(4e3),
+  /** Capture it as a REMINDER — a note assigned to the user themselves, which rides
+   *  their next call instead of being handed to an agent. Everything else about the
+   *  note is identical; this is the one parameter that separates the two. */
+  forMe: z.boolean().optional(),
+  /** The not-before, when the user already said one. Absent = the very next call. */
+  dueAt: z.string().datetime().optional(),
+  repeat: NoteRepeatSchema.optional()
 });
 var RecordDecisionSchema = z.object({
   /** An open decision (from /clarify) to answer. */
@@ -982,6 +1122,7 @@ var FeedbackOutcomeSchema = z.object({
 });
 
 export {
+  MISSED_CALL_PLAN,
   HandoffSchema,
   WAKE_EVENT,
   wakeChannel

package/dist/{chunk-ENE65M5Y.js → chunk-SASREQWV.js}

@@ -1,6 +1,6 @@
 import {
   AGENT_NAME
-} from "./chunk-2WPQJYJH.js";
+} from "./chunk-E3OWSUGJ.js";
 
 // src/clients.ts
 import { execFile } from "child_process";
@@ -87,6 +87,7 @@ function claudeInstallHint(skip = AGENT_NAME) {
   }
   return "Claude Code detected \u2014 to add Paigy there, run /plugin marketplace add paigy-ai/mcp then /plugin install paigy (pairing carries over; no need to pair again). Note: If you run this inside a live session, type /reload-plugins afterward so the agent connects to the new tools.";
 }
+var ENABLE_COMMAND = "npx -y -p @paigy/mcp@latest paigy-enable-tools";
 var PAIGY_TOOL_IDS = [
   "mcp__paigy__contact",
   "mcp__paigy__notify_user",
@@ -169,6 +170,7 @@ export {
   openBrowser,
   autoConfigureClients,
   claudeInstallHint,
+  ENABLE_COMMAND,
   PAIGY_TOOL_IDS,
   paigyToolsAllowlisted,
   enablePaigyTools

package/dist/enable.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import {
+  PAIGY_TOOL_IDS,
+  enablePaigyTools
+} from "./chunk-SASREQWV.js";
+import "./chunk-E3OWSUGJ.js";
+
+// src/enable.ts
+function main() {
+  const argv = process.argv.slice(2);
+  let scope = "user";
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      console.log("usage: paigy-enable-tools [--scope user|project]");
+      console.log("");
+      console.log("Allowlist Paigy's notify/await tools in Claude Code so they run without an");
+      console.log("approval prompt each time \u2014 an unattended session can't stall on a dialog.");
+      console.log("");
+      console.log("  --scope user     ~/.claude/settings.json (default) \u2014 every project");
+      console.log("  --scope project  ./.claude/settings.json \u2014 just this repo");
+      console.log("");
+      console.log(`Adds: ${PAIGY_TOOL_IDS.join(", ")}`);
+      console.log("Leaves pair/unpair out, so they stay human-approved. Safe to re-run.");
+      return;
+    }
+    if (arg === "--scope") {
+      const v = argv[++i];
+      if (v !== "user" && v !== "project") {
+        console.error(`paigy-enable-tools: --scope must be user or project, got ${v ?? "nothing"}`);
+        process.exit(2);
+      }
+      scope = v;
+    } else {
+      console.error(`paigy-enable-tools: unknown argument ${arg}`);
+      console.error("usage: paigy-enable-tools [--scope user|project]");
+      process.exit(2);
+    }
+  }
+  const result = enablePaigyTools(scope);
+  if (!result.ok) {
+    console.error(`\u2717 ${result.reason}`);
+    process.exit(1);
+  }
+  if (result.added.length) {
+    console.log(`\u2713 allowlisted ${result.added.length} Paigy tool${result.added.length === 1 ? "" : "s"} in ${result.path}`);
+    for (const id of result.added) console.log(`    ${id}`);
+  } else {
+    console.log(`\u2713 already allowlisted in ${result.path} \u2014 nothing to do`);
+  }
+  if (result.already.length && result.added.length) {
+    console.log(`  (${result.already.length} already present)`);
+  }
+}
+main();

package/dist/index.js

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 import {
-  HandoffSchema
-} from "./chunk-PYORUJ7Q.js";
+  HandoffSchema,
+  MISSED_CALL_PLAN
+} from "./chunk-JT7I3EGY.js";
 import {
+  ENABLE_COMMAND,
   PAIGY_TOOL_IDS,
   autoConfigureClients,
   claudeInstallHint,
-  enablePaigyTools,
   paigyToolsAllowlisted
-} from "./chunk-ENE65M5Y.js";
+} from "./chunk-SASREQWV.js";
 import {
   clearSurface,
   writeSurface
@@ -50,7 +51,7 @@ import {
   startE2ee,
   submitNotification,
   whoAmI
-} from "./chunk-2WPQJYJH.js";
+} from "./chunk-E3OWSUGJ.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -89,12 +90,20 @@ function json(s) {
 }
 
 // src/toolset.ts
+var fmtMin = (m) => m >= 60 ? `${m / 60} hr` : `${m} min`;
+var STANDARD_MEANS = (() => {
+  const plan = MISSED_CALL_PLAN.backoff_standard;
+  const mins = plan.kind === "at" ? plan.minutes : [];
+  const parts = mins.map(fmtMin);
+  const list = parts.length > 1 ? `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}` : parts[0] ?? "";
+  return `Rings again ${list} after the missed call, then leaves it in your inbox`;
+})();
 var CONTACT_SCHEMA = {
   type: "object",
   properties: {
     ask: {
       type: "string",
-      description: "What to tell the user, or what you need to find out from them. Plain prose \u2014 as long as it needs to be (up to 10k characters); Paigy splits it into topics and reads back a few sentences at a time, so do NOT compress a briefing into one line. May be spoken aloud on a call, so write natural speech and name things (not IDs). Contact at exactly two moments: BLOCKED on a decision only they can make, or DONE (one short report \u2014 what shipped, how you verified it, what you flagged). Progress is never a contact: set_task_state carries it, and working narration stays in your own terminal \u2014 the user sees you're working without being interrupted by it."
+      description: `What to tell the user, or what you need to find out from them. Plain prose \u2014 as long as it needs to be (up to 10k characters); Paigy splits it into topics and reads back a few sentences at a time, so do NOT compress a briefing into one line. May be spoken aloud on a call, so write natural speech and name things (not IDs). Contact at exactly two moments: BLOCKED on a decision only they can make, or DONE (one short report \u2014 what shipped, how you verified it, what you flagged). DONE IS SAID ONCE: "all set", "nothing open on my end", "that thread is complete" are the same report in new words, and each one reaches them separately (live 2026-08-12: three of them in three minutes). After the first, you are finished speaking; if they acknowledge it, stop rather than confirming the acknowledgement. Progress is never a contact: set_task_state carries it, and working narration stays in your own terminal \u2014 the user sees you're working without being interrupted by it.`
     },
     waiting: {
       type: "string",
@@ -129,8 +138,9 @@ var CONTACT_SCHEMA = {
   },
   required: ["ask"]
 };
-var CONTACT_DESCRIPTION = "Reach the user through Paigy \u2014 tell them something, or ask and get their answer. State what you need in `ask`, say what happens to your work while you wait in `waiting`, and Paigy handles the rest (channel, phrasing, answer format). If the user explicitly asks you to CALL them, send waiting:'hard' and say so in the ask. Returns { notificationId, parentId } \u2014 pass notificationId to await_reply for the answer, parentId to a later contact to continue the conversation. When it rang, the reply also carries { ifMissed: { mode, means } }: what the user's own policy does with a call they don't take (\"Rings again 10 min, 30 min and 2 hr after the missed call, then leaves it in your inbox\"), so a no-answer tells you how long to wait before coming back. THREADING REPLACES: a threaded follow-up SUPERSEDES your earlier pending items on that thread \u2014 right for updates to one ask, WRONG for a checklist (send independent to-dos un-threaded). A threaded re-send with IDENTICAL content escalates the pending ask in place. If a reply comes back as {kind:'clarify', chunks:[...]}, the user wants more detail \u2014 contact again on the SAME parentId with an expanded ask. ONE ASK, ONE ROW: never restate a still-pending ask's question inside a NEW contact (e.g. weaving it into a briefing) \u2014 the whole answer settles on the new row and the original can never receive it. Keep waiting on the original (a live call reads every pending ask out separately, each answer routes to its own row), and use `needs` for a genuinely multi-part NEW ask.";
-var ONBOARD_DESCRIPTION = "Get this agent talking to Paigy \u2014 call it FIRST, before contact/await_reply, and any time you're unsure who you are. One call, and it does whatever the situation needs: NOT SET UP \u2192 hatches an identity instantly if this machine holds a device credential (the user ran the Paigy desktop app or harness), otherwise starts the code ceremony; ALREADY SET UP \u2192 returns your current identity and offers the two things left to decide, renaming it or unpairing; TOKEN NO LONGER VALID \u2192 says so, then re-pairs. Pass { name, voice } to choose who you are when hatching, or to RENAME yourself when already set up (voices: rachel, george, jessica, brian, lily). Safe to call any time: idempotent, and it never writes settings \u2014 the tool-allowlist state it reports is read-only. If it returns a `user_code`, print it to the user immediately and call onboard again with the `device_code`. If it returns `enable_prompt`, ask the user that question and call `enable_tools` on yes.";
+var CONTACT_DESCRIPTION = `Reach the user through Paigy \u2014 tell them something, or ask and get their answer. State what you need in \`ask\`, say what happens to your work while you wait in \`waiting\`, and Paigy handles the rest (channel, phrasing, answer format). If the user explicitly asks you to CALL them, send waiting:'hard' and say so in the ask. Returns { notificationId, parentId } \u2014 pass notificationId to await_reply for the answer, parentId to a later contact to continue the conversation. When it rang, the reply also carries { ifMissed: { mode, means } }: what the user's own policy does with a call they don't take ("${STANDARD_MEANS}"), so a no-answer tells you how long to wait before coming back. THREADING REPLACES: a threaded follow-up SUPERSEDES your earlier pending items on that thread \u2014 right for updates to one ask, WRONG for a checklist (send independent to-dos un-threaded). A threaded re-send with IDENTICAL content escalates the pending ask in place. If a reply comes back as {kind:'clarify', chunks:[...]}, the user wants more detail \u2014 contact again on the SAME parentId with an expanded ask. ONE ASK, ONE ROW: never restate a still-pending ask's question inside a NEW contact (e.g. weaving it into a briefing) \u2014 the whole answer settles on the new row and the original can never receive it. Keep waiting on the original (a live call reads every pending ask out separately, each answer routes to its own row), and use \`needs\` for a genuinely multi-part NEW ask. ANSWERABLE, NOT JUST ASKED: when the reply comes back carrying \`plan.units[].needs\`, that unit asked for something it gave the user no way to answer \u2014 'options' means it posed a choice with nothing to choose from, 'visuals' means it asked about something to look at with nothing to look at. Send it again on the SAME parentId with 2-4 options (or the image), drawn from your own sentence. Paigy will not add them for you: a shape it guessed wrong cannot be undone, and you are the one who knows what the real alternatives are. \`units\` reports WHAT BECAME OF YOUR PROSE \u2014 { kept, raw, why }: how many topics Paigy compressed for delivery, how many kept your exact words, and the reason when it kept them (e.g. 'no_output' = compression produced nothing usable, so the user got your raw sentence). It needs no action and is not an error \u2014 read it only when the delivered wording matters to you; a high \`raw\` count means the user is hearing you verbatim.`;
+var ONBOARD_DESCRIPTION = "Get this agent talking to Paigy \u2014 call it FIRST, before contact/await_reply, and any time you're unsure who you are. One call, and it does whatever the situation needs: NOT SET UP \u2192 hatches an identity instantly if this machine holds a device credential (the user ran the Paigy desktop app or harness), otherwise starts the code ceremony; ALREADY SET UP \u2192 returns your current identity and offers the two things left to decide, renaming it or unpairing; TOKEN NO LONGER VALID \u2192 says so, then re-pairs. Pass { name, voice } to choose who you are when hatching, or to RENAME yourself when already set up (voices: rachel, george, jessica, brian, lily). Safe to call any time: idempotent, and it never writes settings \u2014 the tool-allowlist state it reports is read-only. If it returns a `user_code`, print it to the user immediately and call onboard again with the `device_code`. If it returns `enable_command`, PRINT that command for the user to run \u2014 you cannot apply it yourself (it writes your own permission allowlist, which hosts block as privilege escalation), so print it, don't wait for it, and carry on.";
+var SERVER_INSTRUCTIONS = "On startup, call check_replies once to pick up any replies or pending work you missed while away. A check_replies request whose parentId you don't recognize, or one carrying a contextParentId, means the user is resuming or seeding a past conversation \u2014 call get_thread on it FIRST and treat the transcript as prior conversation, not new input. To wait for the answer to something you just asked, call await_reply with that notificationId \u2014 it's scoped to that one notification, so it never returns replies meant for other notifications. Use check_replies again only when re-booting or after waiting a long time on something else. Never end a turn that still needs the user without contact + await_reply \u2014 WHEN THEY ARE NOT THERE TO ASK. In an interactive session with the user at the terminal, the prompt IS the channel: ending your turn with the question already reaches them, faster and richer than a push, so do NOT send one for an ordinary blocked-or-done moment. Reach for Paigy exactly when the terminal is not enough \u2014 work that will run more than a few minutes unattended (a long build, a deploy, a background job, a cloud session), anything you finish or get stuck on while they are away, or when they have said they are stepping out. If you cannot tell which situation you are in, ask them once, in passing, how they want to be reached, and follow that for the rest of the session. When you need a decision or input, WRITE THE QUESTION and Paigy derives the answer shape from it \u2014 there is no shape parameter to set, and passing one is an error. Ask a yes/no question and they get yes/no; ask them to approve an action and they get approve/deny; ask them to pick, and to pick several, and to rank, and each gets the control it needs. So phrase the ask precisely: 'which of these should I do first' and 'should I do this' are different questions and become different answers. The one thing the prose can't supply is the CHOICES themselves \u2014 when you're asking them to pick between concrete alternatives, pass `options` (2-4 of them, drawn from your own sentence), because Paigy will not invent alternatives it can't know. On a { kind: 'clarify' } reply, see contact's own description for how to respond. When you send waiting:'hard' (or the user asked you to call), remember the ask may be spoken aloud \u2014 write it short and conversational, and name things instead of using IDs (e.g. 'the pull request about the agents page', not 'PR #235'). When the user asks you to follow up later \u2014 when you're done, if you're blocked, or at a set time \u2014 record it with schedule_callback so you don't drop it if you go idle. If you're about to start a genuinely long-running or blocking piece of work \u2014 one where the user would otherwise sit and wait \u2014 mention ONCE, in passing, that you can reach them when it's done or if you hit a blocker, instead of them needing to babysit the terminal. Don't offer this for quick tasks, and don't repeat the offer if they've already said yes or no earlier in the conversation. NEVER go quietly idle while something might still be pending for you: whenever you end a turn with any Paigy notification unanswered (or any chance the user replied through the app while you worked), schedule your own ~2-minute wake-up (harness ScheduleWakeup or equivalent) and call check_replies when it fires; if still nothing, re-schedule and keep looping until resolved or the user says stop. For legibility, always use this exact wording \u2014 reason: 'Paigy idle check \u2014 waiting on <thing>', wake-up prompt: 'Paigy idle check: call check_replies and engage with anything unacknowledged; if idle, re-schedule (~2min).' \u2014 so the user can recognize every idle check at a glance. This self-polling in your own live session (full context intact) is the PRIMARY mechanism; the plugin's Stop hooks are only the dead-session safety net.";
 
 // src/pairing.ts
 async function resolvePairing(deviceCode, capMs, pollMs = 2e3) {
@@ -257,9 +267,6 @@ var GetThreadSchema = z.object({
 var SearchThreadsSchema = z.object({
   q: z.string().describe("What to look for \u2014 plain words or a phrase (e.g. 'the livekit timeout', 'deploy to prod').")
 });
-var EnableToolsSchema = z.object({
-  scope: z.enum(["user", "project"]).optional().describe("'user' (default) allowlists Paigy's tools for every project (~/.claude/settings.json); 'project' scopes them to this repo (.claude/settings.json).")
-});
 var SetTaskStateToolSchema = z.object({
   notificationId: z.string(),
   state: SetTaskStateSchema.shape.state
@@ -308,8 +315,9 @@ function pairedResult(token, sas, note, e2ee) {
   } catch {
   }
   base.enable_tool_ids = PAIGY_TOOL_IDS;
-  base.enable_prompt = `REQUIRED \u2014 before you do anything else, ask the user now: "Want me to let Paigy's tools run without an approval prompt each time? I'll only allowlist the notify/await tools \u2014 pair and unpair still ask." Prompt every time you pair; don't skip it.`;
-  base.enable_apply = "On yes: call the `enable_tools` tool \u2014 it writes the allowlist for you (scope:'user' = every project, the default; scope:'project' = just this repo). No hand-editing. If it returns ok:false (the host isn't Claude Code), fall back to adding `enable_tool_ids` to that tool's own allowlist by hand, merging \u2014 never clobbering. pair/unpair stay out, so they remain human-approved. On no: drop it, don't ask again this session.";
+  base.enable_command = ENABLE_COMMAND;
+  base.enable_prompt = "REQUIRED \u2014 before you do anything else, print `enable_command` to the user and say: \"Run this to let Paigy's tools work without an approval prompt each time \u2014 it only allowlists the notify/await tools; pair and unpair still ask.\" Print it every time you pair; don't skip it.";
+  base.enable_apply = "You cannot apply this yourself, and must not try: it writes YOUR OWN permission allowlist, which hosts block as privilege escalation no matter what the user said here. PRINT the command and move on \u2014 don't wait for them to run it, and don't re-ask. Paigy's tools still work meanwhile; they just prompt for approval each time until the user runs it. If the host isn't Claude Code, tell them to add `enable_tool_ids` to that tool's own allowlist instead, merging \u2014 never clobbering.";
   return { content: [{ type: "text", text: JSON.stringify(base) }] };
 }
 function awaitingConfirmResult(sas, device_code) {
@@ -359,7 +367,7 @@ function unidentifiedResult() {
   return { isError: true, content: [{ type: "text", text: JSON.stringify({
     error: "no_identity",
     slot: AGENT_NAME,
-    message: `This session has no Paigy identity yet, so nothing was sent \u2014 it will not speak as another session. This machine is already paired, so call \`pair\` (no arguments) to hatch this session its own identity instantly, then retry. To reuse an existing one instead, start the session with PAIGY_AGENT set to its slot (${listSlots().filter((s) => s !== "Desktop").join(", ") || "none yet"}).`
+    message: `This session has no Paigy identity yet, so nothing was sent \u2014 it will not speak as another session. This machine holds a device credential but hatching under it just failed (it may have been revoked), so call \`pair\` (no arguments) to set this session up, then retry \u2014 it re-hatches if the credential recovered and runs the code ceremony if it didn't. To reuse an existing identity instead, start the session with PAIGY_AGENT set to its slot (${listSlots().filter((s) => s !== "Desktop").join(", ") || "none yet"}).`
   }) }] };
 }
 function pairStartResult(start) {
@@ -388,29 +396,34 @@ var server = new Server(
   { name: "paigy", version: "0.0.0" },
   {
     capabilities: { tools: {} },
-    instructions: "On startup, call check_replies once to pick up any replies or pending work you missed while away. A check_replies request whose parentId you don't recognize, or one carrying a contextParentId, means the user is resuming or seeding a past conversation \u2014 call get_thread on it FIRST and treat the transcript as prior conversation, not new input. To wait for the answer to something you just asked, call await_reply with that notificationId \u2014 it's scoped to that one notification, so it never returns replies meant for other notifications. Use check_replies again only when re-booting or after waiting a long time on something else. Never end a turn that still needs the user without contact + await_reply. When you need a decision or input, MATCH the answer shape to the question \u2014 don't default everything to free text, and don't reflexively make everything yes/no. Pick the best tool for the job: yes/no \u2192 select:'confirm'; approve/deny an action \u2192 select:'confirm' + confirmStyle:'approve'; pick one of several \u2192 options + select:'one'; pick several / a subset \u2192 options + select:'many'; rank or prioritize \u2192 options + select:'rank'. Reserve select:'text' (free-form reply only) for plain updates and answers that genuinely can't be structured (the user can always add free text on top of any shape). On a { kind: 'clarify' } reply, see contact's own description for how to respond. When you send waiting:'hard' (or the user asked you to call), remember the ask may be spoken aloud \u2014 write it short and conversational, and name things instead of using IDs (e.g. 'the pull request about the agents page', not 'PR #235'). When the user asks you to follow up later \u2014 when you're done, if you're blocked, or at a set time \u2014 record it with schedule_callback so you don't drop it if you go idle. If you're about to start a genuinely long-running or blocking piece of work \u2014 one where the user would otherwise sit and wait \u2014 mention ONCE, in passing, that you can reach them when it's done or if you hit a blocker, instead of them needing to babysit the terminal. Don't offer this for quick tasks, and don't repeat the offer if they've already said yes or no earlier in the conversation. NEVER go quietly idle while something might still be pending for you: whenever you end a turn with any Paigy notification unanswered (or any chance the user replied through the app while you worked), schedule your own ~2-minute wake-up (harness ScheduleWakeup or equivalent) and call check_replies when it fires; if still nothing, re-schedule and keep looping until resolved or the user says stop. For legibility, always use this exact wording \u2014 reason: 'Paigy idle check \u2014 waiting on <thing>', wake-up prompt: 'Paigy idle check: call check_replies and engage with anything unacknowledged; if idle, re-schedule (~2min).' \u2014 so the user can recognize every idle check at a glance. This self-polling in your own live session (full context intact) is the PRIMARY mechanism; the plugin's Stop hooks are only the dead-session safety net."
+    instructions: SERVER_INSTRUCTIONS
   }
 );
 function prependNote(result, note) {
   return { content: [{ type: "text", text: note }, ...result.content] };
 }
+async function hatchUnderDevice(name, voice) {
+  if (!listSlots().includes("Desktop")) return null;
+  overrideToken(readToken("Desktop"));
+  try {
+    const minted = await hatch(name ?? suggestedAgentName() ?? "Agent", voice ?? null);
+    const dt = { ok: true, access_token: minted.token, name: minted.name, device: null };
+    saveToken(dt);
+    return dt;
+  } catch {
+    return null;
+  } finally {
+    overrideToken(null);
+  }
+}
 async function runPair(device_code, name, voice, note) {
-  if (!device_code && listSlots().includes("Desktop")) {
-    const device = readToken("Desktop");
-    overrideToken(device);
-    try {
-      const minted = await hatch(name ?? suggestedAgentName() ?? "Agent", voice ?? null);
-      const dt = { ok: true, access_token: minted.token, name: minted.name, device: null };
-      saveToken(dt);
-      return pairedResult(
-        dt,
-        void 0,
-        "Hatched instantly under this device's credential \u2014 no code needed. " + (name ? "" : "You were given a default name \u2014 choose your own name and voice and update them via the identity tools or by re-calling pair with { name, voice }.")
-      );
-    } catch {
-    } finally {
-      overrideToken(null);
-    }
+  if (!device_code) {
+    const dt = await hatchUnderDevice(name, voice);
+    if (dt) return pairedResult(
+      dt,
+      void 0,
+      "Hatched instantly under this device's credential \u2014 no code needed. " + (name ? "" : `You were given a default name ("${dt.name}") \u2014 the user never chose it, so don't announce it as their agent's identity. They can rename it in the app, or you can re-call pair with { name, voice }.`)
+    );
   }
   if (!device_code) {
     const started2 = pairStartResult(await startPairing(suggestedAgentName()));
@@ -440,7 +453,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     },
     {
       name: "pair",
-      description: "Pair this agent with the user's Paigy account (one-time) \u2014 required before contact/await_reply work. FAST PATH: if this machine already holds a device credential (the user ran the Paigy desktop harness or app), calling pair hatches a fresh identity INSTANTLY \u2014 no code, no approval. Pass { name, voice } to choose who you are (pick your own; voices: rachel, george, jessica, brian, lily). Only when no device credential exists does the code ceremony below run. It does NOT open a browser; the user enters the code in the Paigy app (or scans `qr`). Step 1: call with NO args \u2014 returns { user_code, device_code, qr, user_message } AND starts polling for approval in the background. REQUIRED: You MUST immediately print the `user_message` (the bare code) as a text message to the user, AND in that same turn call step 2 (pair with the device_code). This ensures the user sees the code in chat while the tool blocks/polls in the background for approval. Step 2: call with that device_code to collect the result. Because approval is already being polled in the background, this returns the moment the user approves; on { status:'pending' } just call again to keep waiting; on { status:'awaiting_confirmation' } (E2EE) show the bare `user_message` verify code and call again to finish. The leading text block of every result states the code plainly, so it shows even if you emit no prose. On { status:'paired' } ALWAYS follow the `enable_prompt` \u2014 ask the user to allowlist Paigy's tools so notify/await don't prompt each time.",
+      description: "Pair this agent with the user's Paigy account (one-time) \u2014 required before contact/await_reply work. FAST PATH: if this machine already holds a device credential (the user ran the Paigy desktop harness or app), calling pair hatches a fresh identity INSTANTLY \u2014 no code, no approval. Pass { name, voice } to choose who you are (pick your own; voices: rachel, george, jessica, brian, lily). Only when no device credential exists does the code ceremony below run. It does NOT open a browser; the user enters the code in the Paigy app (or scans `qr`). Step 1: call with NO args \u2014 returns { user_code, device_code, qr, user_message } AND starts polling for approval in the background. REQUIRED: You MUST immediately print the `user_message` (the bare code) as a text message to the user, AND in that same turn call step 2 (pair with the device_code). This ensures the user sees the code in chat while the tool blocks/polls in the background for approval. Step 2: call with that device_code to collect the result. Because approval is already being polled in the background, this returns the moment the user approves; on { status:'pending' } just call again to keep waiting; on { status:'awaiting_confirmation' } (E2EE) show the bare `user_message` verify code and call again to finish. The leading text block of every result states the code plainly, so it shows even if you emit no prose. On { status:'paired' } ALWAYS follow the `enable_prompt` \u2014 PRINT the returned `enable_command` so the user can allowlist Paigy's tools and notify/await stop prompting each time. Printing is the whole job: that command writes your own permission allowlist, so you must not run it and a host will block you if you try.",
       inputSchema: json(PairSchema)
     },
     {
@@ -448,11 +461,6 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       description: "Log out / unpair this agent from the user's Paigy account: revokes the token server-side (it stops working everywhere) and deletes the local ~/.paigy/token.json. Takes no arguments. After this, contact/await_reply won't work until the user pairs again with the pair tool.",
       inputSchema: json(z.object({}))
     },
-    {
-      name: "enable_tools",
-      description: "Allowlist Paigy's notify/await tools so they run WITHOUT an approval prompt each time \u2014 call this AFTER pairing, once the user has said yes to the `enable_prompt` (never without their consent). It writes the hosting tool's permission allowlist for you: `scope:'user'` (default) covers every project (~/.claude/settings.json), `scope:'project'` scopes it to this repo (.claude/settings.json). Merges into the existing file (never clobbers) and leaves pair/unpair OUT so they stay human-approved. Returns { ok, path, added, already } on success, or { ok:false, reason } when the host isn't Claude Code (add the ids to that tool's own allowlist by hand). Idempotent \u2014 re-running just reports everything already present.",
-      inputSchema: json(EnableToolsSchema)
-    },
     {
       name: "await_reply",
       description: "Wait for the user's reply to a specific notification you sent (pass the notificationId from contact). This is how you wait for your answer in-context. Polls ~45s per call \u2014 deliberately under the 60s cap most hosts put on a single tool call, so it ALWAYS returns you something (raise it with maxWaitSeconds only if you know your host allows longer). Returns { type:'reply', answer } when they respond, { type:'remind', remindInSeconds } on snooze (ScheduleWakeup then await_reply again), or { type:'idle' } (this window ended, no answer yet). While your contact is being handled on a LIVE call, you may receive { type:'partial', inFlight:true, turn } results: what the user said to each turn, as they say it. Use partials to PREPARE \u2014 fetch the data, draft the thing, warm the build \u2014 never to act irreversibly: the user can still revise any of them until the final reply arrives. Partial = intelligence, settled = authorization. If a partial's acts carry a question aimed at you and you know the answer, call contact on the SAME parentId right away \u2014 the caller hears your answer on the same call instead of waiting for a callback. Keep calling await_reply until you get the final reply \u2014 THAT one is the decision. On idle, if this is genuinely still blocking you and you have nothing else useful to do meanwhile, just call await_reply again immediately \u2014 keep looping. This is how you actually deliver on the point of calling: the user steps away for a while and comes back to find you'd already continued the moment they answered, not idle waiting to be checked on. Don't give up after one window. Only stop looping to do other work (and check back later), or after an unreasonably long stretch (tens of minutes to hours) worth telling the user about instead. Scoped to that one notification \u2014 it NEVER returns replies meant for other notifications, so concurrent contact calls don't cross. A CALL answer can come back as {kind:'turns', turns:[{prompt,reply}]} \u2014 the ordered log of that call. Read turns[0].reply as the user's main instruction. Usually that's the only turn; if there are more (e.g. an end-of-call 'call me back when it's done / I have a blocking question'), read each one in order as a further follow-up instruction, not a single combined one. If they asked for a callback, re-engage in the SAME thread (contact with the reply's parentId) when the task is done or you hit a blocker \u2014 waiting:'hard' for a blocker, waiting:'none' for done. Paigy has no scheduler; the callback is yours to send (use ScheduleWakeup/cron for timing). A call-mapped answer may carry `intents` \u2014 next steps the user attached, each { kind, detail } with detail quoting their words. ACT on them, don't just read them: 'defer' (\"call me after lunch\") \u2192 register it NOW with schedule_callback \u2014 when the intent carries `dueInSeconds` (Paigy pre-parsed the spoken time against the user's clock) pass it straight through; otherwise derive it from the detail yourself \u2014 then follow up on the same thread; 'delegate' (\"you pick\") \u2192 make the call yourself and tell them what you chose; 'channel' (\"text me next time\") \u2192 honor it on your next contact (channel:'message'); 'question' (an open question aimed back at you that the call couldn't answer) \u2192 you OWE them the answer \u2014 work it out and follow up on the same thread without being asked, the call deliberately skipped \"should I call you back?\" because the follow-up is implied. `transcript` is the user's raw words behind a shaped answer \u2014 read it for hedges and conditions (\"yes, IF tests pass\") before acting. If your ask declared `points`, the reply carries `covered` \u2014 the points actually addressed. Compare against what you declared: a missing point is STILL unanswered \u2014 re-ask it (contact on the same parentId) or proceed knowingly partial; never treat a partial answer as complete.",
@@ -460,7 +468,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     },
     {
       name: "check_replies",
-      description: "The catch-up sweep for everything outstanding \u2014 a PURE read, takes no arguments, safe to call as often as you like: nothing here is consumed by reading it. Returns `replies` (answers to notifications you sent), your still-pending notifications, and `requests` \u2014 requests the user started toward you (each { notificationId, parentId, text }). Each keeps reappearing on every call until you actually engage with it: call set_task_state on its notificationId, which is what claims/acknowledges it \u2014 a human-initiated reply or request must never be silently dropped just because you read the list without acting. Also returns `threads` \u2014 the SAME replies + requests grouped by conversation, oldest thread first, each with a `busy` flag and its `items` in arrival order. WORK ONE THREAD AT A TIME: take the oldest thread whose `busy` is false, handle ALL of its items together in a single turn (one set_task_state), then go to the next \u2014 don't interleave threads item-by-item. A `busy` thread already has a turn in progress; leave it and let its new items ride the next turn. Use check_replies when booting up / starting a session, or when you've been waiting a long time on something else. To wait on an answer to a contact call you just made, use await_reply instead. Also returns owedCallbacks: callbacks now due that you promised \u2014 fulfill each with contact on its parentId. Also returns `stalled`: work (either direction) you reported in_progress via set_task_state a while ago and never reported completed \u2014 likely left half-done by this session or a prior one that crashed or went idle. For each, either continue the work and report a real state, or investigate why it stalled. Replies may carry `intents`/`transcript`/`covered` (call-mapped answers) \u2014 handle intents exactly as await_reply's description says (defer \u2192 schedule_callback now; delegate \u2192 decide and say so; channel \u2192 honor next contact), and treat a `covered` list missing one of your declared points as that part still unanswered.",
+      description: "The catch-up sweep for everything outstanding \u2014 a PURE read, takes no arguments, safe to call as often as you like: nothing here is consumed by reading it. Returns `replies` (answers to notifications you sent), your still-pending notifications, and `requests` \u2014 requests the user started toward you (each { notificationId, parentId, text }). Each keeps reappearing on every call until you actually engage with it: call set_task_state on its notificationId, which is what claims/acknowledges it \u2014 a human-initiated reply or request must never be silently dropped just because you read the list without acting. Also returns `threads` \u2014 the SAME replies + requests grouped by conversation, oldest thread first, each with a `busy` flag and its `items` in arrival order. WORK ONE THREAD AT A TIME: take the oldest thread whose `busy` is false, handle ALL of its items together in a single turn (one set_task_state), then go to the next \u2014 don't interleave threads item-by-item. A `busy` thread already has a turn in progress; leave it and let its new items ride the next turn. Use check_replies when booting up / starting a session, or when you've been waiting a long time on something else. To wait on an answer to a contact call you just made, use await_reply instead. Also returns owedCallbacks: callbacks now due that you promised \u2014 fulfill each with contact on its parentId. EVERY Paigy reply \u2014 this one, await_reply's, and contact's \u2014 may carry `also`: work assigned to you that no wake could reach, handed to you because you happened to be here. It is NOT what you asked about and it is never urgent: FINISH what you came for first, then take it up. Each entry has a `noteId` and the owner's own words; report on its `parentId` thread when it has one, and call set_task_state on that thread as you would for any assigned work. Ignoring it costs nothing \u2014 it rides your next reply too. Also returns `stalled`: work (either direction) you reported in_progress via set_task_state a while ago and never reported completed \u2014 likely left half-done by this session or a prior one that crashed or went idle. For each, either continue the work and report a real state, or investigate why it stalled. Replies may carry `intents`/`transcript`/`covered` (call-mapped answers) \u2014 handle intents exactly as await_reply's description says (defer \u2192 schedule_callback now; delegate \u2192 decide and say so; channel \u2192 honor next contact), and treat a `covered` list missing one of your declared points as that part still unanswered.",
       inputSchema: json(z.object({}))
     },
     {
@@ -501,6 +509,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     return await handleTool(request, extra?.signal);
   } catch (e) {
     if (e instanceof UnpairedError) {
+      const IDENTITY_TOOLS = /* @__PURE__ */ new Set(["pair", "onboard", "unpair"]);
+      const hatched = IDENTITY_TOOLS.has(request.params.name) ? null : await hatchUnderDevice();
+      if (hatched) return await handleTool(request, extra?.signal);
       if (listSlots().includes("Desktop")) return unidentifiedResult();
       return pairStartResult(await startPairing(suggestedAgentName()));
     }
@@ -571,7 +582,8 @@ async function handleTool(request, signal) {
               tools_allowlisted: allowlisted,
               ...allowlisted ? {} : {
                 enable_tool_ids: PAIGY_TOOL_IDS,
-                enable_prompt: "Ask the user: \"Want me to let Paigy's tools run without an approval prompt each time? I'll only allowlist the notify/await tools \u2014 pair and unpair still ask.\" On yes, call `enable_tools`."
+                enable_command: ENABLE_COMMAND,
+                enable_prompt: "Print `enable_command` to the user: \"Run this to let Paigy's tools work without an approval prompt each time \u2014 it only allowlists the notify/await tools; pair and unpair still ask.\" You cannot run it yourself (it writes your own permission allowlist, which hosts block as privilege escalation) \u2014 print it, don't wait for it, and carry on."
               },
               // Setup is done, so the only things left are the user's to decide. Named here
               // rather than left implicit: an agent that reports "ready" and stops gives the
@@ -613,12 +625,6 @@ async function handleTool(request, signal) {
         }]
       };
     }
-    case "enable_tools": {
-      const { scope } = EnableToolsSchema.parse(request.params.arguments ?? {});
-      const result = enablePaigyTools(scope ?? "user");
-      const message = result.ok ? `Allowlisted ${result.added.length} Paigy tool(s) in ${result.path}` + (result.already.length ? ` (${result.already.length} already present).` : ".") + " They now run without an approval prompt; restart/reload the tool if it caches settings. pair/unpair stay human-approved." : result.reason;
-      return { content: [{ type: "text", text: JSON.stringify({ ...result, message }) }] };
-    }
     // `contact` (#575) is the one LISTED name; `notify` (#496) and `notify_user`
     // (the original) are HIDDEN aliases — unlisted but accepted, so stale prompts,
     // hooks, and cached 0.24 servers' habits keep working. Same handler, same wire.
@@ -697,7 +703,11 @@ async function beat() {
     if (beatDown) console.error("paigy: presence restored \u2014 the live dot is honest again");
     beatDown = false;
   } catch (err) {
-    if (err instanceof UnpairedError) return;
+    if (err instanceof UnpairedError) {
+      if (!beatDown) console.error("paigy: identity unpaired/revoked \u2014 the live dot goes dark on purpose");
+      beatDown = true;
+      return;
+    }
     if (!beatDown) console.error(`paigy: presence beat failed \u2014 the phone may show this agent offline (${String(err)})`);
     beatDown = true;
   }

package/dist/listen.js

@@ -2,11 +2,11 @@
 import {
   WAKE_EVENT,
   wakeChannel
-} from "./chunk-PYORUJ7Q.js";
+} from "./chunk-JT7I3EGY.js";
 import {
   checkReplies,
   registerDelivery
-} from "./chunk-2WPQJYJH.js";
+} from "./chunk-E3OWSUGJ.js";
 
 // src/listen.ts
 import { createClient } from "@supabase/supabase-js";

package/dist/onboard.js

@@ -3,7 +3,7 @@ import {
   autoConfigureClients,
   claudeInstallHint,
   openBrowser
-} from "./chunk-ENE65M5Y.js";
+} from "./chunk-SASREQWV.js";
 import {
   AGENT_NAME,
   TOKEN_PATH,
@@ -17,7 +17,7 @@ import {
   setIdentity,
   sleep,
   whoAmI
-} from "./chunk-2WPQJYJH.js";
+} from "./chunk-E3OWSUGJ.js";
 
 // src/onboard.ts
 async function main() {

package/dist/statusline.js

@@ -6,7 +6,7 @@ import {
   BACKEND_URL,
   reach,
   readToken
-} from "./chunk-2WPQJYJH.js";
+} from "./chunk-E3OWSUGJ.js";
 
 // src/statusline.ts
 import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@paigy/mcp",
-  "version": "0.31.1",
-  "description": "Paigy MCP server — a voice inbox for your AI agents. Lets an agent notify a user and await their reply.",
+  "version": "0.33.0",
+  "description": "Paigy MCP server — the AI agent harness that calls you. Lets an agent notify a user and await their reply.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
     "paigy-mcp": "./dist/index.js",
     "paigy-mcp-onboard": "./dist/onboard.js",
     "paigy-listen": "./dist/listen.js",
-    "paigy-statusline": "./dist/statusline.js"
+    "paigy-statusline": "./dist/statusline.js",
+    "paigy-enable-tools": "./dist/enable.js"
   },
   "files": [
     "dist"