paseo-follow-up 1.1.0-beta.0 → 1.2.0-beta.0

package/OVERVIEW.md

@@ -24,6 +24,8 @@ Auto-send starts off for every workspace. Until you turn it on, each repair batc
 
 ## Data and access
 
-This is a trusted, unsandboxed plugin. It reads workspace metadata, saved agent history and configuration, GitHub status and existing CLI authentication, and keeps its state in `plugin-data/follow-through` on the daemon host. It registers scoped MCP tools and reversible provider hooks only for tracked sessions. To find the spec link it reads completed Claude Artifact publish results in the workspace's root sessions, never page content, chat links or the repository; a link you set wins over the agent's, which wins over detection. Repair prompts go to your configured agent and provider. It has no Slack identity and no background channel scanning; replies to stakeholders need your authorization and a sent-message receipt from the agent.
+This is a trusted, unsandboxed plugin. It reads workspace metadata, saved agent history and configuration, GitHub status and existing CLI authentication, and keeps its state in `plugin-data/follow-through` on the daemon host. It registers scoped MCP tools and reversible provider hooks for tracked sessions and, while the Needs-you inbox is on, the `needs_you` tool and its Stop-hook nudge for root agents (see below). To find the spec link it reads completed Claude Artifact publish results in the workspace's root sessions, never page content, chat links or the repository; a link you set wins over the agent's, which wins over detection. Repair prompts go to your configured agent and provider. It has no Slack identity and no background channel scanning; replies to stakeholders need your authorization and a sent-message receipt from the agent.
 
-The Needs-you inbox (beta) keeps one flag per root agent in `plugin-data/follow-through/inbox.json`. When a turn starts it reads the newest user message from the agent's recent timeline to tell your messages from automation, and it reads, never writes, Defer's `plugin-data/defer/queue.json`, Smart Session's `plugin-data/smart-session/compactions.json`, Session Guard's `plugin-data/session-guard/state.json` and Paseo's schedule records. An unknown or unreadable format counts as your message, which clears a flag rather than adding one. Signing off also clears Paseo's own unread dot for that agent. Turning the inbox off stops all of this.
+The Needs-you inbox (beta) keeps one flag per root agent in `plugin-data/follow-through/inbox.json`. When a turn starts it reads the newest user message from the agent's recent timeline to tell your messages from automation, and it reads, never writes, Defer's `plugin-data/defer/queue.json`, Smart Session's `plugin-data/smart-session/compactions.json`, Session Guard's `plugin-data/session-guard/state.json` and Paseo's schedule records. An unknown or unreadable format counts as your message, which clears a flag rather than adding one. Signing off also clears Paseo's own unread dot for that agent. The first-run import and the restart check read only Paseo's agent list: an agent's last activity is its unread time or your last message to it, never Paseo's `updatedAt` (which the daemon rewrites in bulk), and they don't fetch timelines, which would load every agent. Closed and archived agents are never imported. Turning the inbox off stops all of this.
+
+The brief (beta) is stored on the agent's inbox entry and appended to its timeline as a Follow-up row; re-appending replaces that row, and the restart check ignores the `updatedAt` change the append causes because it never reads `updatedAt`. To build a brief Follow-up reads only what it already has: the agent's `needs_you` call, the permission request's title, the failed turn's error message, Session Guard's note and reset time for a paused agent, and its own PR state. It does not read or quote the agent's reply. While the inbox is on, every root Paseo agent on Claude Code or Codex gets Follow-up's MCP bridge with the `needs_you` tool only (tracked main agents keep their full set), and `plugin-data/follow-through/brief.json` records whether the inbox and the nudge are on and which agents have a permission prompt showing. Clicking an option or Retry sends one message as you; it is logged in the delivery ledger as yours, so it clears the flag. The Stop hook, part of the same reversible provider hooks Follow-up already installs, now also runs for those root Claude Code sessions: if the turn ended without `needs_you`, it blocks the stop once with a one-line request to call it, records that it did in `hook-state`, and never blocks the same turn again. It reads `brief.json`, its own per-turn marker and the time of the agent's last `needs_you` call, and nothing else. Turn it off with *Ask agents to state what they need*; turning the inbox off stops it too.

package/README.md

@@ -84,10 +84,23 @@ The 1.1 beta adds an inbox for your agents. An agent lands in **Needs you** when
 - On Paseo builds with sidebar views (Paseo `main` after 2026-11-07, expected in the next release), **Settings > Sidebar > Sidebar view > Follow-up: Needs you** puts the inbox in the sidebar, with your workspace list folded below it.
 - Turn the whole inbox off in **Follow-up: display settings** (⌘K). Off means nothing is flagged and no pill or sidebar item is shown.
 
+### What you need to do, front and center (1.2 beta)
+
+When an agent needs you, Follow-up adds a **brief** at the end of its chat, right above the composer, so it's the first thing you see when you open the agent:
+
+- **The ask in one line**, written as what you do: *Pick how the export API is rate-limited*, *Review and merge #813*, *Allow or deny: run the migration on staging*, or *Nothing needed. Daily updates are scheduled.* The same line shows on the inbox row and in the pill's tooltip, and the pill's label comes from it (*Asks*, *Merge*, *Error*, *Paused*, *Finished*).
+- **Decisions as option rows.** Click one and it goes to the agent as your message, which clears the flag. Typing the letter or the option's label in the composer counts too. On a phone, or a window too short for the whole card, each option shows its letter and label, with what it means one tap away, so the card fits above the composer.
+- **Only the context needed**, plus PR facts Follow-up already knows, and the one move for this kind of ask: *Squash & merge* (Follow-up's merge flow), *Retry the turn*, *Copy error* or *Sign off & next*. Permission briefs are a single line: Paseo's own prompt right below is the control.
+- **Where it came from**, always: stated by the agent, from the permission request, Session Guard, the failed turn or Follow-up's PR state. If the agent stated nothing, the card says so and points at its last paragraph. It never guesses an ask.
+
+The content comes from a new `needs_you` tool that every root agent gets while the inbox is on, with an instruction to call it once at the end of a turn. Contributors, recovery agents and subagents don't get it. After you answer, sign off or the agent keeps going, the card folds to one muted line, so the history still shows what was asked and what happened.
+
+**Ask agents to state what they need** (on by default, in **Follow-up: display settings**): when a Claude Code root agent ends a turn without calling `needs_you`, Follow-up's Stop hook asks it once to call it, then lets it stop. It never asks twice in one turn, and skips subagents, contributors, recovery agents and agents waiting on a permission prompt. Codex and other providers get the instruction only. The settings screen shows how often agents stated what they need over the last 7 days.
+
 Install the beta:
 
 ```sh
-paseo plugin update follow-through --version 1.1.0-beta.0
+paseo plugin update follow-through --version 1.2.0-beta.0
 # or, for a fresh install:
 paseo plugin install npm:paseo-follow-up@beta
 ```

package/client/brief.tsx

@@ -0,0 +1,221 @@
+import { useState } from "react";
+import { Platform, Pressable, Text, View, useWindowDimensions } from "react-native";
+import { useQuery } from "@tanstack/react-query";
+import { openExternalUrl, useRpc, type PluginClientContext, type PluginTimelineItemProps } from "@getpaseo/plugin/client";
+import { Icon, copyText } from "@getpaseo/plugin/client/ui";
+import { BRIEF_KIND, BRIEF_LABEL, BRIEF_VERSION, briefSchema, collapsedLine, extrasFit, isTight, type Brief, type BriefDecision, type BriefMove } from "../shared/brief";
+import { age } from "../shared/inbox";
+import { briefActionRpc, browserStatusRpc } from "../shared/contracts";
+import { errorText } from "../shared/errors";
+import type { Workspace } from "../shared/model";
+import { useNow } from "./kit";
+import { PrSheet } from "./pr-sheet";
+import { isLight, withAlpha, type Colors } from "./theme";
+
+/**
+ * The brief card (design §2): the ask in one line, decisions as option rows, only the context needed, and the one
+ * move for this kind of ask. It sits at the end of the timeline, right above the composer and the Needs-you control.
+ */
+export type BriefDeps = {
+  signOff(agentId: string): void;
+  openNext(from: string): void;
+  openAgent(agentId: string): void;
+  workspace(id: string): Workspace | undefined;
+  /** Opens Follow-up's panel for a workspace whose record this client hasn't loaded yet. */
+  openPanel(workspaceId: string): void;
+};
+
+const mono = () => (Platform.OS === "ios" ? "Menlo" : "ui-monospace, SFMono-Regular, Menlo, monospace");
+/** Kinds the developer has to act on wear the attention tone; a plain finish and the fallback stay neutral. */
+const ACTS: Brief["kind"][] = ["decision", "action", "review", "permission", "paused", "error"];
+const ICON: Record<Brief["kind"], string> = { decision: "MessageCircleQuestion", action: "Hand", review: "GitPullRequest", permission: "ShieldQuestion", paused: "CirclePause", error: "CircleX", done: "CircleCheck", unknown: "CircleDashed" };
+const kindTone = (kind: Brief["kind"], c: Colors) => kind === "error" ? c.statusDanger : kind === "review" || kind === "done" ? c.statusSuccess : kind === "unknown" ? c.foregroundMuted : c.statusWarning;
+const factTone = (tone: string, c: Colors) => tone === "ok" ? c.statusSuccess : tone === "warn" ? c.statusWarning : tone === "bad" ? c.statusDanger : c.foregroundMuted;
+const clock = (iso: string | null) => { if (!iso) return ""; const d = new Date(iso); return Number.isFinite(d.getTime()) ? d.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", hour12: false }) : ""; };
+/** Web keyboard focus: a visible ring, since sending an answer is one-shot. */
+const ring = (focused: boolean | undefined, c: Colors) => focused && Platform.OS === "web" ? ({ outlineWidth: 2, outlineStyle: "solid", outlineColor: withAlpha(c.accent, 0.6), outlineOffset: 2 } as object) : {};
+const letters = (d: BriefDecision) => { const l = d.options.map(o => o.letter); return l.length > 1 ? `${l.slice(0, -1).join(", ")} or ${l.at(-1)}` : l[0] ?? ""; };
+
+function Btn({ label, icon, primary, onPress, c, compact, disabled }: { label: string; icon?: string; primary?: boolean; onPress: () => void; c: Colors; compact: boolean; disabled?: boolean }) {
+  const fg = primary ? c.accentForeground : c.foreground;
+  return <Pressable accessibilityRole="button" accessibilityLabel={label} accessibilityState={{ disabled }} disabled={disabled} onPress={onPress}
+    style={({ hovered, pressed, focused }: { hovered?: boolean; pressed: boolean; focused?: boolean }) => ({ ...ring(focused, c), minHeight: compact ? 44 : 32, paddingHorizontal: compact ? 14 : 12, borderRadius: 6, flexDirection: "row", alignItems: "center", gap: 6, justifyContent: "center", opacity: disabled ? 0.5 : 1,
+      backgroundColor: primary ? (pressed ? withAlpha(c.accent, 0.85) : hovered ? withAlpha(c.accent, 0.92) : c.accent) : pressed || hovered ? c.surface2 : "transparent",
+      borderWidth: primary ? 0 : 1, borderColor: c.border, flexGrow: compact ? 1 : 0 })}>
+    {icon ? <Icon name={icon} size={compact ? 16 : 14} color={fg} /> : null}
+    <Text numberOfLines={1} style={{ color: fg, fontSize: compact ? 14 : 13, lineHeight: compact ? 19 : 17, fontWeight: "600" }}>{label}</Text>
+  </Pressable>;
+}
+
+function OptionRow({ option, recommended, sending, disabled, tight, open, onToggle, onPress, c, compact }: {
+  option: BriefDecision["options"][number]; recommended: boolean; sending: boolean; disabled: boolean; tight: boolean; open: boolean; onToggle: () => void; onPress: () => void; c: Colors; compact: boolean;
+}) {
+  const strong = withAlpha(c.foreground, isLight(c) ? 0.38 : 0.42);
+  const showDetail = !!option.consequence && (!tight || open);
+  return <View style={{ flexDirection: "row", alignItems: "stretch", borderRadius: 8, borderWidth: 1, borderColor: recommended ? strong : c.border, opacity: disabled && !sending ? 0.5 : 1, overflow: "hidden" }}>
+    <Pressable accessibilityRole="button" accessibilityLabel={`Answer ${option.letter}: ${option.label}${recommended ? " (recommended)" : ""}`} accessibilityHint={option.consequence ?? undefined} accessibilityState={{ disabled, busy: sending }} disabled={disabled} onPress={onPress}
+      style={({ hovered, pressed, focused }: { hovered?: boolean; pressed: boolean; focused?: boolean }) => ({ ...ring(focused, c), flex: 1, flexDirection: "row", alignItems: "flex-start", gap: 10, paddingVertical: compact ? 11 : 9, paddingHorizontal: 10, minHeight: compact ? 44 : 0,
+        backgroundColor: pressed ? c.surface2 : hovered && !disabled ? withAlpha(c.foreground, 0.05) : "transparent" })}>
+      <View style={{ width: 22, height: 22, borderRadius: 5, alignItems: "center", justifyContent: "center", backgroundColor: recommended ? c.foreground : c.surface2 }}>
+        <Text style={{ fontSize: 12, fontWeight: "700", color: recommended ? c.surface1 : c.foreground }}>{option.letter}</Text>
+      </View>
+      <View style={{ flex: 1, minWidth: 0, gap: 2 }}>
+        <View style={{ flexDirection: "row", alignItems: "center", columnGap: 8, flexWrap: "wrap" }}>
+          <Text style={{ color: c.foreground, fontSize: 14, lineHeight: 20, fontWeight: "600" }}>{option.label}</Text>
+          {recommended && <Text style={{ color: c.foregroundMuted, fontSize: 12, lineHeight: 16, fontWeight: "600" }}>Recommended</Text>}
+          {sending && <Text accessibilityLiveRegion="polite" style={{ color: c.foregroundMuted, fontSize: 12, lineHeight: 16 }}>Sending…</Text>}
+        </View>
+        {showDetail && <Text style={{ color: c.foregroundMuted, fontSize: 13, lineHeight: 18 }}>{option.consequence}</Text>}
+      </View>
+    </Pressable>
+    {tight && !!option.consequence && <Pressable accessibilityRole="button" aria-expanded={open} accessibilityLabel={`${open ? "Hide" : "Show"} what ${option.letter} means`} onPress={onToggle}
+      style={({ pressed, focused }: { pressed: boolean; focused?: boolean }) => ({ ...ring(focused, c), width: 44, alignItems: "center", justifyContent: "center", borderLeftWidth: 1, borderLeftColor: c.border, backgroundColor: pressed ? c.surface2 : "transparent" })}>
+      <View style={{ transform: [{ rotate: open ? "180deg" : "0deg" }] }}><Icon name="ChevronDown" size={16} color={c.foregroundMuted} /></View>
+    </Pressable>}
+  </View>;
+}
+
+function Collapsed({ b, c, now }: { b: Brief; c: Colors; now: number }) {
+  // F8: history keeps what was asked and what happened, as one muted line (two when an answer was picked).
+  const answered = b.state === "answered";
+  const icon = b.state === "superseded" ? "History" : "CircleCheck";
+  const color = b.state === "superseded" ? c.foregroundMuted : c.statusSuccess;
+  const right = answered && b.outcomeAt ? `sent ${clock(b.outcomeAt)}` : age(b.outcomeAt ?? b.at, now);
+  return <View accessibilityLiveRegion="polite" style={{ marginVertical: 10, flexDirection: "row", gap: 10, alignItems: answered ? "flex-start" : "center", minHeight: 40, paddingVertical: answered ? 10 : 8, paddingHorizontal: 12, borderRadius: 10, borderWidth: 1, borderColor: c.border }}>
+    <View style={{ paddingTop: answered ? 2 : 0 }}><Icon name={icon} size={15} color={color} /></View>
+    {answered
+      ? <View style={{ flex: 1, minWidth: 0, gap: 2 }}>
+          <Text numberOfLines={1} style={{ color: c.foregroundMuted, fontSize: 12, lineHeight: 16 }}>{b.ask}</Text>
+          <Text style={{ color: c.foreground, fontSize: 14, lineHeight: 20, fontWeight: "600" }}>{b.outcome}</Text>
+        </View>
+      : <Text numberOfLines={1} style={{ flex: 1, minWidth: 0, color: c.foregroundMuted, fontSize: 13, lineHeight: 18 }}>{collapsedLine(b)}</Text>}
+    <Text style={{ color: c.foregroundMuted, fontSize: 12, lineHeight: 16, fontVariant: ["tabular-nums"] }}>{right}</Text>
+  </View>;
+}
+
+export function BriefCard({ item, theme, layout, agentId, deps }: PluginTimelineItemProps<Brief> & { deps: BriefDeps }) {
+  const c = theme.colors; const b = item.data; const compact = layout.compact;
+  const now = useNow(60_000);
+  const { height } = useWindowDimensions();
+  const act = useRpc(briefActionRpc);
+  const browserRead = useRpc(browserStatusRpc);
+  const [busy, setBusy] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [open, setOpen] = useState<Record<string, boolean>>({});
+  const [details, setDetails] = useState(false);
+  const [sheet, setSheet] = useState<string | null>(null);
+  const workspace = b.workspaceId ? deps.workspace(b.workspaceId) : undefined;
+  const browser = useQuery({ queryKey: ["follow-through", "browser"], queryFn: () => browserRead({}), refetchInterval: 5000, enabled: !!sheet });
+  if (b.state !== "open") return <Collapsed b={b} c={c} now={now} />;
+
+  const attention = c.statusWarning;
+  const acts = b.flagged && ACTS.includes(b.kind);
+  const tone = acts || b.kind === "done" || b.kind === "review" || b.kind === "error" ? kindTone(b.kind, c) : c.foregroundMuted;
+  const ageText = age(b.at, now);
+  const border = acts ? withAlpha(attention, isLight(c) ? 0.5 : 0.45) : c.border;
+  const run = async (key: string, work: () => Promise<unknown>) => {
+    if (busy) return; setBusy(key); setError(null);
+    try { await work(); } catch (e) { setError(errorText(e)); } finally { setBusy(null); }
+  };
+  const press = (m: BriefMove) => {
+    if (m.kind === "merge" && m.prKey) { if (workspace?.prs.some(p => p.key === m.prKey)) setSheet(m.prKey); else if (b.workspaceId) deps.openPanel(b.workspaceId); }
+    else if (m.kind === "open_pr" && m.url) void openExternalUrl(m.url).catch(() => undefined);
+    else if (m.kind === "sign_off_next") { deps.signOff(agentId); deps.openNext(agentId); }
+    else if (m.kind === "retry") void run("retry", () => act({ agentId, briefId: b.id, move: "retry" }));
+    else if (m.kind === "copy_error" && b.mono) void copyText(b.mono).catch(() => undefined);
+    else if (m.kind === "open_subagent" && m.agentId) deps.openAgent(m.agentId);
+  };
+  // A merge runs Follow-up's own merge flow, so it needs the tracked workspace; without one it isn't offered.
+  const moves = b.moves.filter(m => m.kind !== "merge" || !!b.workspaceId);
+
+  if (b.slim) {
+    // One line. Permission: Paseo's own prompt below is the control (F9). Fallback: the paragraph is right above.
+    return <View accessibilityRole="summary" accessibilityLabel={`${acts ? "Needs you: " : ""}${b.ask}. ${b.sourceLine}`}
+      style={{ marginVertical: 10, flexDirection: "row", alignItems: "center", flexWrap: compact ? "wrap" : "nowrap", gap: 8, minHeight: 40, paddingHorizontal: 12, paddingVertical: 8, borderRadius: 10, borderWidth: 1, borderColor: border }}>
+      <Icon name={ICON[b.kind]} size={14} color={acts ? attention : tone} />
+      {acts && <Text style={{ color: attention, fontSize: 12, lineHeight: 16, fontWeight: "600" }}>Needs you</Text>}
+      <Text style={{ flex: 1, minWidth: compact ? 160 : 0, color: acts ? c.foreground : c.foregroundMuted, fontSize: 14, lineHeight: 20, fontWeight: acts ? "600" : "400" }}>{b.ask}</Text>
+      {moves.map(m => <Btn key={m.kind} label={m.label} onPress={() => press(m)} c={c} compact={compact} />)}
+      <Text style={{ color: c.foregroundMuted, fontSize: 12, lineHeight: 16, fontVariant: ["tabular-nums"] }}>{ageText}</Text>
+    </View>;
+  }
+
+  const tight = isTight(b, compact, height);
+  const extra = !!b.context || b.facts.length > 0 || b.links.length > 0;
+  const showExtra = !tight || details || extrasFit(b, height);
+  const pad = compact ? 14 : 16;
+  return <View accessibilityRole="summary" accessibilityLabel={`${acts ? "Needs you" : BRIEF_LABEL[b.kind]}: ${b.ask}`}
+    style={{ marginVertical: 10, borderRadius: 12, borderWidth: 1, borderColor: border, backgroundColor: c.surface1, overflow: "hidden" }}>
+    <View style={{ paddingHorizontal: pad, paddingTop: compact ? 12 : 14, paddingBottom: 14, gap: tight ? 10 : 12 }}>
+      <View style={{ gap: 4 }}>
+        <View style={{ flexDirection: "row", alignItems: "center", gap: 7 }}>
+          <Icon name={ICON[b.kind]} size={14} color={tone} />
+          <Text style={{ color: acts ? attention : tone, fontSize: 12, lineHeight: 16, fontWeight: "600" }}>{acts ? "Needs you" : BRIEF_LABEL[b.kind]}</Text>
+          {acts && <Text style={{ color: c.foregroundMuted, fontSize: 12, lineHeight: 16 }}>{BRIEF_LABEL[b.kind]}</Text>}
+          <View style={{ flex: 1 }} />
+          <Text style={{ color: c.foregroundMuted, fontSize: 12, lineHeight: 16, fontVariant: ["tabular-nums"] }}>{ageText}</Text>
+        </View>
+        <Text accessibilityRole="header" style={{ color: c.foreground, fontSize: compact ? 17 : 19, lineHeight: compact ? 23 : 26, fontWeight: "600", letterSpacing: -0.2 }}>{b.ask}</Text>
+      </View>
+
+      {b.decisions.map((d, i) => <View key={d.id} style={{ gap: 8 }}>
+        <Text style={{ color: c.foreground, fontSize: 14, lineHeight: 20 }}>{b.decisions.length > 1 ? `${i + 1}. ` : ""}{d.question}</Text>
+        {d.options.length > 0 && <View style={{ gap: 6 }}>
+          {d.options.map(o => <OptionRow key={o.letter} option={o} recommended={d.recommend === o.letter} sending={busy === `${d.id}:${o.letter}`} disabled={!!busy} tight={tight}
+            open={!!open[`${d.id}:${o.letter}`]} onToggle={() => setOpen(v => ({ ...v, [`${d.id}:${o.letter}`]: !v[`${d.id}:${o.letter}`] }))}
+            onPress={() => void run(`${d.id}:${o.letter}`, () => act({ agentId, briefId: b.id, decisionId: d.id, choice: o.letter }))} c={c} compact={compact} />)}
+        </View>}
+        {!tight && <Text style={{ color: c.foregroundMuted, fontSize: 12, lineHeight: 16 }}>{d.options.length ? `Or type ${letters(d)} in the composer, or reply in your own words.` : "Reply in the composer."}</Text>}
+        {tight && !d.options.length && <Text style={{ color: c.foregroundMuted, fontSize: 12, lineHeight: 16 }}>Reply in the composer.</Text>}
+      </View>)}
+
+      {!!b.mono && !b.ask.endsWith(b.mono) && <View style={{ borderRadius: 8, backgroundColor: withAlpha(c.statusDanger, isLight(c) ? 0.07 : 0.1), paddingHorizontal: 10, paddingVertical: 8 }}>
+        <Text selectable numberOfLines={tight ? 3 : undefined} style={{ color: c.foreground, fontFamily: mono(), fontSize: 12, lineHeight: 18 }}>{b.mono}</Text>
+      </View>}
+
+      {extra && tight && !extrasFit(b, height) && <Pressable accessibilityRole="button" aria-expanded={details} accessibilityLabel={details ? "Hide details" : "Show details"} onPress={() => setDetails(v => !v)} hitSlop={6}
+        style={{ flexDirection: "row", alignItems: "center", gap: 4, alignSelf: "flex-start", minHeight: compact ? 44 : 24 }}>
+        <View style={{ transform: [{ rotate: details ? "90deg" : "0deg" }] }}><Icon name="ChevronRight" size={14} color={c.foregroundMuted} /></View>
+        <Text style={{ color: c.foregroundMuted, fontSize: 13, lineHeight: 18, fontWeight: "500" }}>Details</Text>
+      </Pressable>}
+
+      {showExtra && !!b.context && <Text selectable numberOfLines={4} style={{ color: c.foregroundMuted, fontSize: 13, lineHeight: 19 }}>{b.context}</Text>}
+
+      {showExtra && (b.facts.length > 0 || b.links.length > 0) && <View style={{ flexDirection: "row", flexWrap: "wrap", gap: 6 }}>
+        {b.facts.slice(0, 3).map((f, i) => { const col = factTone(f.tone, c); return <View key={`f${i}`} style={{ flexDirection: "row", alignItems: "center", gap: 5, paddingHorizontal: 8, minHeight: 24, borderRadius: 6, backgroundColor: f.tone === "muted" ? c.surface2 : withAlpha(col, isLight(c) ? 0.1 : 0.14) }}>
+          <Icon name={f.icon} size={12} color={col} />
+          <Text style={{ color: f.tone === "muted" || isLight(c) ? c.foreground : col, fontSize: 12, lineHeight: 16, fontWeight: "500" }}>{f.label}</Text>
+        </View>; })}
+        {b.links.map((l, i) => <Pressable key={`l${i}`} accessibilityRole={l.url ? "link" : "text"} disabled={!l.url} onPress={() => l.url && void openExternalUrl(l.url).catch(() => undefined)} hitSlop={compact ? 10 : 4}
+          style={{ flexDirection: "row", alignItems: "center", gap: 5, paddingHorizontal: 8, minHeight: 24, borderRadius: 6, backgroundColor: c.surface2 }}>
+          <Icon name={l.url ? "ExternalLink" : l.pr ? "GitPullRequest" : "File"} size={12} color={c.foregroundMuted} />
+          <Text selectable={!l.url} numberOfLines={1} style={{ color: c.foreground, fontSize: 12, lineHeight: 16, fontWeight: "500", maxWidth: 260 }}>{l.label}</Text>
+        </Pressable>)}
+      </View>}
+
+      {moves.length > 0 && <View style={{ flexDirection: "row", flexWrap: "wrap", gap: 8 }}>
+        {moves.map((m, i) => <Btn key={m.kind} label={busy === m.kind ? `${m.label}…` : m.label} icon={MOVE_ICON[m.kind]} primary={i === 0} disabled={!!busy} onPress={() => press(m)} c={c} compact={compact} />)}
+      </View>}
+
+      {!!error && <Text accessibilityRole="alert" style={{ color: c.statusDanger, fontSize: 13, lineHeight: 18 }}>{error}</Text>}
+
+      {!!b.also && <View style={{ gap: 3, borderTopWidth: 1, borderTopColor: c.border, paddingTop: 10 }}>
+        <Text style={{ color: c.foregroundMuted, fontSize: 12, lineHeight: 16, fontWeight: "600" }}>Also, from the agent:</Text>
+        <Text style={{ color: c.foreground, fontSize: 14, lineHeight: 20 }}>{b.also.ask}</Text>
+        {showExtra && !!b.also.context && <Text numberOfLines={3} style={{ color: c.foregroundMuted, fontSize: 13, lineHeight: 19 }}>{b.also.context}</Text>}
+      </View>}
+    </View>
+    <View style={{ borderTopWidth: 1, borderTopColor: c.border, paddingHorizontal: pad, paddingVertical: 8, flexDirection: "row", alignItems: "center", gap: 6 }}>
+      <Icon name="Info" size={12} color={c.foregroundMuted} />
+      <Text style={{ flex: 1, color: c.foregroundMuted, fontSize: 12, lineHeight: 16 }}>{b.sourceLine}</Text>
+    </View>
+    {workspace && sheet && <PrSheet workspace={workspace} prKey={sheet} intent="merge" theme={theme} compact={compact} browserReady={browser.data?.ready ?? false} onClose={() => setSheet(null)} />}
+  </View>;
+}
+
+const MOVE_ICON: Record<BriefMove["kind"], string> = { merge: "GitMerge", open_pr: "ExternalLink", sign_off_next: "ArrowRight", retry: "RotateCcw", copy_error: "Copy", open_subagent: "SquareArrowOutUpRight" };
+
+export function contributeBrief(client: PluginClientContext, deps: BriefDeps) {
+  const Component = (props: PluginTimelineItemProps<Brief>) => <BriefCard {...props} deps={deps} />;
+  return client.addTimelineRenderer({ kind: BRIEF_KIND, version: BRIEF_VERSION, schema: briefSchema, Component });
+}

package/client/chat.tsx

@@ -104,7 +104,7 @@ function AnswerCardView({ item, theme }: PluginTimelineItemProps<AnswerCard>) {
     <View style={{ borderRadius: 10, borderWidth: 1, borderColor: c.border, backgroundColor: c.surface1, overflow: "hidden" }}>
       <View style={{ flexDirection: "row", alignItems: "center", gap: 8, paddingHorizontal: 12, paddingTop: 10, paddingBottom: 6 }}>
         <Icon name="MessageCircleReply" size={14} color={c.statusSuccess} />
-        <Text numberOfLines={1} style={{ flex: 1, color: c.foreground, fontSize: 13, lineHeight: 18, fontWeight: "600" }}>Your answer to {card.id} · {card.title}</Text>
+        <Text numberOfLines={1} style={{ flex: 1, color: c.foreground, fontSize: 13, lineHeight: 18, fontWeight: "600" }}>Your answer{/^D\d+$/.test(card.id) ? "" : ` to ${card.id}`} · {card.title}</Text>
         <Pressable accessibilityRole="button" aria-expanded={expanded} accessibilityLabel={expanded ? "Hide the full message" : "Show the full message"} onPress={() => setExpanded(v => !v)} hitSlop={6}
           style={state => ({ paddingHorizontal: 6, paddingVertical: 2, borderRadius: 4, backgroundColor: state.pressed ? c.surface2 : "transparent" })}>
           <Text style={{ color: c.foregroundMuted, fontSize: 12 }}>{expanded ? "Hide" : "Full message"}</Text>

package/client/display.tsx

@@ -1,5 +1,7 @@
 import type { PluginClientContext, PluginSidebarItemContribution, PluginSurfaceProps } from "@getpaseo/plugin/client";
-import { useSettings } from "@getpaseo/plugin/client";
+import { useRpc, useSettings } from "@getpaseo/plugin/client";
+import { useQuery } from "@tanstack/react-query";
+import { inboxListRpc } from "../shared/contracts";
 import { SettingsAction, SettingsCard, SettingsSection, SettingsSwitch } from "@getpaseo/plugin/client/ui";
 import { useEffect } from "react";
 import { ActivityIndicator, ScrollView, Text, View } from "react-native";
@@ -10,8 +12,19 @@ type Display = import("zod").infer<typeof displayPreferences.schema>;
 const listeners = new Set<(values: Display) => void>();
 export function subscribeDisplay(listener: (values: Display) => void) { listeners.add(listener); return () => { listeners.delete(listener); }; }
 
+/** R2's measurement, where it's cheap to look: how often agents stated what they need on a flagged turn. */
+export function briefShareText(stats: { days: number; total: number; tool: number; structured: number; fallback: number } | undefined): string {
+  if (!stats) return "";
+  if (!stats.total) return `No flagged turns in the last ${stats.days} days yet.`;
+  const pct = Math.round((stats.tool / stats.total) * 100);
+  const rest = [stats.structured ? `${stats.structured} from a permission, pause, error or PR` : "", stats.fallback ? `${stats.fallback} with nothing stated` : ""].filter(Boolean).join(", ");
+  return `Last ${stats.days} days: agents stated what they need on ${stats.tool} of ${stats.total} flagged turns (${pct}%).${rest ? ` ${rest[0].toUpperCase()}${rest.slice(1)}.` : ""}`;
+}
+
 function DisplaySettings({ theme }: PluginSurfaceProps) {
   const settings = useSettings(displayPreferences);
+  const list = useRpc(inboxListRpc);
+  const share = useQuery({ queryKey: ["follow-through", "brief-share"], queryFn: () => list({}), refetchInterval: 60_000 });
   const values = settings.status === "ready" ? settings.values : undefined;
   useEffect(() => {
     if (values !== undefined) for (const listener of listeners) listener(values);
@@ -46,7 +59,9 @@ function DisplaySettings({ theme }: PluginSurfaceProps) {
         <SettingsSwitch label="Needs-you inbox" hint="Off: nothing is flagged, and the pill and sidebar item are hidden." value={settings.values.enable_inbox} disabled={settings.saving} onValueChange={(enable_inbox) => save({ enable_inbox })} />
         <SettingsSwitch label="Show the sidebar item at zero" hint="By default the Needs you item appears only while something needs you." value={settings.values.enable_inbox_header_when_empty} disabled={settings.saving || !settings.values.enable_inbox} onValueChange={(enable_inbox_header_when_empty) => save({ enable_inbox_header_when_empty })} />
         <SettingsSwitch label="Flag merged and closed PRs" hint="At the lowest priority, as the cue to archive." value={settings.values.enable_inbox_pr_closed} disabled={settings.saving || !settings.values.enable_inbox} onValueChange={(enable_inbox_pr_closed) => save({ enable_inbox_pr_closed })} />
+        <SettingsSwitch label="Ask agents to state what they need" hint="A Claude Code agent that ends a turn without saying what you need is asked once to state it, for the card at the end of its chat. Other providers only get the instruction." value={settings.values.enable_brief_nudge} disabled={settings.saving || !settings.values.enable_inbox} onValueChange={(enable_brief_nudge) => save({ enable_brief_nudge })} />
       </SettingsCard>
+      {settings.values.enable_inbox && !!share.data?.briefStats && <Text style={{ color: theme.colors.foregroundMuted, fontSize: 12, lineHeight: 17, paddingHorizontal: 4 }}>{briefShareText(share.data.briefStats)}</Text>}
     </SettingsSection>
     </ScrollView>
   );

package/client/inbox.tsx

@@ -2,6 +2,7 @@ import { useEffect, useRef, useState, useSyncExternalStore, type ReactNode } fro
 import { Pressable, Text, View, type LayoutChangeEvent } from "react-native";
 import type { PluginButtonIconProps, PluginButtonRegistration, PluginClientContext, PluginSidebarItemProps } from "@getpaseo/plugin/client";
 import { Icon, SidebarRow } from "@getpaseo/plugin/client/ui";
+import { BRIEF_LABEL, BRIEF_WORD, briefLine } from "../shared/brief";
 import { age, displayReason, nextAfter, REASON_LABEL, REASON_WORD, rowTitle, sectionRows, snoozeUntil, wakeLabel, type InboxRow, type Reason } from "../shared/inbox";
 import { Button, IconButton, useNow, type Theme } from "./kit";
 import { Spinner } from "./motion";
@@ -71,17 +72,20 @@ export function InboxRowView({ row, theme, now, dense, touch, active, onOpen, on
   const reasonColor = shown && !row.snooze ? reasonGlyph(shown.reason, c).color : c.foregroundMuted;
   const second: ReactNode[] = [];
   if (title.agent && narrow) second.push(<Text key="a" style={{ color: c.foreground }}>{title.agent} · </Text>);
-  if (shown) second.push(<Text key="r" style={{ color: reasonColor, fontWeight: "600" }}>{REASON_LABEL[shown.reason]}</Text>);
+  if (shown) second.push(<Text key="r" style={{ color: reasonColor, fontWeight: "600" }}>{row.brief?.state === "open" && shown.reason === "finished" ? BRIEF_LABEL[row.brief.kind] : REASON_LABEL[shown.reason]}</Text>);
   else if (row.signedOffAt && !running(row)) second.push(<Text key="s" style={{ color: c.statusSuccess }}>Signed off</Text>);
   else if (row.resumesAt) second.push(<Text key="p">Paused at the limit</Text>);
   else if (running(row)) second.push(<Text key="w">Working</Text>);
-  if (shown?.detail) second.push(<Text key="d">{` · ${shown.detail}`}</Text>);
+  // §4: an open brief's ask is the reason line, so the row, the card and the composer say the same thing.
+  const asked = row.brief && shown ? briefLine(row.brief) : null;
+  const detail = asked ?? shown?.detail;
+  if (detail) second.push(<Text key="d">{` · ${detail}`}</Text>);
   if (more > 0) second.push(<Text key="m">{` · +${more}`}</Text>);
   if (!row.enable_finish_flags && !shown) second.push(<Text key="f">{second.length ? " · " : ""}Finishes not flagged</Text>);
   if (row.delegatedFrom && !shown) second.push(<Text key="g">{second.length ? " · " : ""}Delegated</Text>);
   const quiet = !row.needs || !!row.snooze;
   const showCheck = !!onSignOff && !selecting && (touch || hover || focused || !dense);
-  const a11y = [label(row), shown ? `${REASON_LABEL[shown.reason]}${shown.detail ? `: ${shown.detail}` : ""}` : "", right ? `waiting ${right}` : ""].filter(Boolean).join(". ");
+  const a11y = [label(row), shown ? `${REASON_LABEL[shown.reason]}${detail ? `: ${detail}` : ""}` : "", right ? `waiting ${right}` : ""].filter(Boolean).join(". ");
   return <View onLayout={(e: LayoutChangeEvent) => setWidth(e.nativeEvent.layout.width)}
     {...({ onMouseEnter: () => setHover(true), onMouseLeave: () => setHover(false), onFocus: () => setFocused(true), onBlur: () => setFocused(false) } as object)}
     style={{ flexDirection: "row", alignItems: "center", minHeight: touch ? 56 : dense ? 40 : 48, paddingLeft: dense ? 8 : 12, paddingRight: dense ? 4 : 8, borderRadius: dense ? 6 : 0, backgroundColor: active || moreOpen ? c.surface2 : hover && onOpen ? c.surface1 : "transparent" }}>
@@ -335,8 +339,11 @@ export function contributeInboxPills(client: PluginClientContext, store: InboxSt
       if (!row.workspaceId) continue;
       const shown = displayReason(row.needs);
       if (shown && !row.snooze) {
-        const status = `Needs you · ${REASON_WORD[shown.reason].toLowerCase()} ${age(row.needs!.since, now)}`;
-        wanted.set(row.agentId, { row, undo: false, label: `${REASON_WORD[shown.reason]} · ${age(row.needs!.since, now)}`, title: store.data()?.firstRun ? `${status}. Click to sign off. ${RULE}` : `${status}. Click to sign off.` });
+        // §4: with an open brief the label comes from its kind and the tooltip carries its ask, so the control never disagrees with the card.
+        const brief = row.brief?.state === "open" ? row.brief : null;
+        const word = brief && (shown.reason === "finished" || brief.kind === shown.reason) ? BRIEF_WORD[brief.kind] : REASON_WORD[shown.reason];
+        const status = brief ? `Needs you · ${briefLine(brief)}` : `Needs you · ${REASON_WORD[shown.reason].toLowerCase()} ${age(row.needs!.since, now)}`;
+        wanted.set(row.agentId, { row, undo: false, label: `${word} · ${age(row.needs!.since, now)}`, title: store.data()?.firstRun ? `${status}. Click to sign off. ${RULE}` : `${status}. Click to sign off.` });
       } else if (recent && recent.agentIds.includes(row.agentId) && now - recent.at < 6_000) {
         wanted.set(row.agentId, { row, undo: true, label: "Undo sign-off", title: "Signed off. Click to undo." });
       }
@@ -346,7 +353,7 @@ export function contributeInboxPills(client: PluginClientContext, store: InboxSt
       if (!next || next.row.workspaceId !== entry.workspaceId) { entry.status.remove(); entry.menu?.remove(); pills.delete(agentId); }
     }
     for (const [agentId, next] of wanted) try {
-      const key = `${next.label}|${next.undo}|${next.row.enable_finish_flags}|${running(next.row)}`;
+      const key = `${next.label}|${next.title}|${next.undo}|${next.row.enable_finish_flags}|${running(next.row)}`;
       const status = { title: next.title, label: next.label, behavior: { kind: "action" as const, onPress() { if (next.undo) void store.undo([agentId]); else void store.signOff([agentId]); } } };
       const entry = pills.get(agentId);
       if (!entry) {
@@ -401,7 +408,9 @@ export function useNextRelay(store: InboxStore, params: Record<string, string>,
     const token = params.next;
     if (!token || !openAgent || !ready || done.current === token) return;
     done.current = token;
+    // The brief card can't navigate on its own (timeline items get no navigation), so it relays "open this agent" here.
+    if (params.open) { openAgent({ agentId: params.open } as InboxRow); return; }
     const target = nextTarget(store, params.from ?? null);
     if (target) openAgent(target);
-  }, [params.next, params.from, ready, openAgent, store]);
+  }, [params.next, params.from, params.open, ready, openAgent, store]);
 }

package/index.client.tsx

@@ -11,6 +11,7 @@ import { FollowLarge, LARGE_SCREEN } from "./client/large";
 import { createInboxStore } from "./client/inbox-store";
 import { contributeHeaderItem, contributeInboxCommands, contributeInboxPills } from "./client/inbox";
 import { inboxSidebarView, sidebarViewHost } from "./client/sidebar-view";
+import { contributeBrief } from "./client/brief";
 
 const OVERVIEW = "follow-through";
 
@@ -57,6 +58,11 @@ export default function contribute(host: PluginClientContext) {
     contributeInboxPills(client, inbox, openNext),
     contributeInboxCommands(client, inbox, openNext),
     contributeHeaderItem(host, inbox),
+    contributeBrief(client, {
+      signOff: agentId => void inbox.signOff([agentId]), openNext,
+      openAgent: agentId => client.openScreen({ screenId: OVERVIEW, params: { next: String(++nextToken), open: agentId } }),
+      workspace: id => store.get(id), openPanel,
+    }),
   ];
   // Phase 2: only on hosts with the sidebar-view API (Paseo main after 2026-11-07).
   const views = sidebarViewHost(host);

package/index.server.ts

@@ -29,7 +29,8 @@ import { Inbox, type GuardPause } from "./server/inbox";
 import { daemonDirectory, guardPath } from "./server/inbox-directory";
 import { fileSources } from "./server/inbox-classifier";
 import { onBeforeSend } from "./server/daemon";
-import { readFile } from "node:fs/promises";
+import { readFile, rename } from "node:fs/promises";
+import { BRIEF_KIND, BRIEF_VERSION, prState, validateNeedsYou, type Brief, type NeedsYouRecord } from "./shared/brief";
 
 export default function contribute(server: PluginServerContext) {
   const displaySettings = server.registerSettings(displayPreferences);
@@ -48,8 +49,50 @@ export default function contribute(server: PluginServerContext) {
   const engine = new Engine(store, github, gateway);
   // Unknown is not off: an unreadable document keeps the inbox on with its defaults.
   const inboxSettings = async () => { try { const state = await displaySettings.read(); if (state.status === "ready") return state.values; } catch {} return displayPreferences.schema.parse({}); };
+  // The brief's timeline rows need a plugin session; the handler contexts carry one. Rows wait until one is seen.
+  type PaseoApi = PluginHandlerContext["paseo"];
+  let api: PaseoApi | null = null;
+  const unsent = new Map<string, { agentId: string; brief: Brief }>();
+  const append = async (agentId: string, brief: Brief) => {
+    if (!api) { unsent.set(`${agentId}|${brief.id}`, { agentId, brief }); return; }
+    await api.agents.ref(agentId).timeline.append({ type: "plugin", id: brief.id, kind: BRIEF_KIND, version: BRIEF_VERSION, data: brief });
+  };
+  const seen = (paseo: PaseoApi) => {
+    api = paseo;
+    for (const [key, row] of unsent) { unsent.delete(key); void append(row.agentId, row.brief).catch(() => undefined); }
+  };
+  const needsYouPath = (agentId: string) => join(directory, "hook-state", `needs-you-${agentId}.json`);
+  const trackedMain = async (agentId: string) => (await store.snapshot()).workspaces.find(w => w.enable_tracking && !w.archived && w.mainAgentId === agentId) ?? null;
   const inbox: Inbox = new Inbox(directory, {
     enabled: inboxSettings,
+    briefs: {
+      sink: append,
+      async call(agentId) {
+        if (!/^[\w-]+$/.test(agentId)) return null;
+        try { return JSON.parse(await readFile(needsYouPath(agentId), "utf8")) as NeedsYouRecord; } catch { return null; }
+      },
+      async pr(agentId, event) {
+        const w = (await store.snapshot()).workspaces.find(w => w.enable_tracking && !w.archived && (w.mainAgentId === agentId || w.prs.some(p => p.registeredAgentId === agentId)));
+        return prState(w, agentId, event ?? null);
+      },
+      async workspaceId(agentId) { return (await trackedMain(agentId))?.id ?? null; },
+      // Decisions stored as questions follow the brief: a picked option is the developer's answer; a brief the agent
+      // moved past closes its still-open questions so the panel doesn't keep stale ones.
+      async settled(agentId, brief) {
+        if (brief.state !== "answered" && brief.state !== "superseded") return;
+        await store.mutate(state => {
+          const w = state.workspaces.find(w => w.enable_tracking && w.mainAgentId === agentId);
+          if (!w) return;
+          const at = brief.outcomeAt ?? new Date().toISOString();
+          for (const d of brief.decisions) {
+            const q = w.questions.find(q => q.id === d.id && brief.questionIds.includes(q.id));
+            if (!q || q.answer || q.closed) continue;
+            if (brief.state === "answered" && d.chosen) q.answer = { choice: d.chosen, at, by: "developer", delivery: { state: "sent", to: agentId, messageId: null, at, reason: null } };
+            else if (brief.state === "superseded") q.closed = { at, reason: "The agent kept going past this brief.", by: null };
+          }
+        });
+      },
+    },
     directory: daemonDirectory(),
     sources: fileSources(paseoHome, async (): Promise<{ agentId: string; messageId: string | null; at: string }[]> => (await inbox.store.snapshot()).ledger),
     guard: async () => {
@@ -58,12 +101,20 @@ export default function contribute(server: PluginServerContext) {
     },
   });
   onBeforeSend((agentId, messageId) => inbox.noteDelivery(agentId, messageId));
+  /** What the bridge and the Stop hook read: is the inbox on, may agents be nudged, who has a prompt showing. */
+  const writeBriefState = async () => {
+    const values = await inboxSettings();
+    const path = join(directory, "brief.json");
+    const temporary = `${path}.${randomUUID()}`;
+    await writeFile(temporary, JSON.stringify({ enable_inbox: values.enable_inbox, enable_brief_nudge: values.enable_brief_nudge, pending: inbox.pendingPermissions(), at: Date.now() }), { mode: 0o600 });
+    await rename(temporary, path);
+  };
   let inboxError: string | null = null;
   let inboxTimer: ReturnType<typeof setTimeout> | null = null;
   const inboxLoop = async () => {
     await ready;
     if (stopped || loadError) return;
-    try { await inbox.tick(); await inbox.observeGuard(); await inbox.observeFollowUp(await store.snapshot()); inboxError = null; }
+    try { await writeBriefState().catch(() => undefined); await inbox.tick(); await inbox.observeGuard(); await inbox.observeFollowUp(await store.snapshot()); inboxError = null; }
     catch (error) { inboxError = error instanceof Error ? error.message : "The Needs-you inbox couldn't update."; }
     if (!stopped) inboxTimer = setTimeout(() => void inboxLoop(), 15_000);
   };
@@ -84,6 +135,7 @@ export default function contribute(server: PluginServerContext) {
     hooksStarted = true;
     await agentHooks.start().catch(() => { hookError = "Automatic sidebar instructions could not be registered for every provider. Check Claude/Codex hook settings; tracking is still available."; });
     hookTimer = setInterval(() => void agentHooks.heartbeat().catch(() => {}), 30_000);
+    await writeBriefState().catch(() => undefined);
   })().catch(() => { loadError = "Follow-through could not start. Check its saved state and worker lock."; });
   const requireReady = async () => { await ready; if (loadError || stopped) throw new Error(loadError ?? "Follow-through is stopping"); };
   const loop = async () => {
@@ -339,12 +391,60 @@ export default function contribute(server: PluginServerContext) {
 
   server.handle(rpc.inboxListRpc, async () => { await requireReady(); return { ...await inbox.list(), error: inboxError }; });
   server.handle(rpc.inboxActRpc, async input => { await requireReady(); return inbox.act(input); });
+  server.handle(rpc.needsYouRpc, async ({ agentId, ...input }, { paseo }) => {
+    await requireReady(); seen(paseo);
+    if (!(await inboxSettings()).enable_inbox) throw new Error("The Needs-you inbox is off, so there's no brief to fill. Finish with your normal reply.");
+    if (!/^[\w-]+$/.test(agentId)) throw new Error("Unsupported agent identity.");
+    const agent = (await paseo.agents.ref(agentId).refresh())?.agent;
+    if (!agent?.workspaceId) throw new Error("Cannot locate the caller's workspace.");
+    const saved = await store.snapshot();
+    const tracked = saved.workspaces.find(w => w.id === agent.workspaceId && w.enable_tracking && !w.archived);
+    // F2: root agents only. Contributors and recovery sessions report to the main agent; subagents to their parent.
+    if (agent.labels["follow-through.recovery"] || tracked && tracked.mainAgentId !== agentId) throw new Error("needs_you is for the workspace's main agent. Report to the main agent instead.");
+    if (!await isWorkspaceRoot(agent, async id => (await paseo.agents.ref(id).refresh())?.agent)) throw new Error("needs_you is for root agents. Report to your parent agent instead.");
+    const call = validateNeedsYou(input, ref => {
+      const key = ref.trim().replace(/^#/, "");
+      const match = tracked?.prs.find(p => p.key.toLowerCase() === key.toLowerCase()) ?? (tracked?.prs.filter(p => String(p.number) === key).length === 1 ? tracked.prs.find(p => String(p.number) === key) : undefined);
+      if (!match) throw new Error(`No registered PR matches ${ref}. Register it with register_pr first, or give the link as url.`);
+      return match.key;
+    });
+    const turn = inbox.currentTurn(agentId);
+    const previous = await readFile(needsYouPath(agentId), "utf8").then(t => JSON.parse(t) as NeedsYouRecord).catch(() => null);
+    const sameTurn = !!previous && (turn?.turnId ? previous.turnId === turn.turnId : !!turn && previous.at >= turn.at);
+    let questionIds: string[] = [];
+    if (tracked) {
+      const mode = await questionMode();
+      questionIds = await store.mutate(state => {
+        const w = findWorkspace(state, tracked.id);
+        const now = Date.now();
+        // Called twice in one turn: the last call wins, so the first call's questions close.
+        if (sameTurn) for (const q of w.questions) if (previous!.questionIds?.includes(q.id) && !q.answer && !q.closed) q.closed = { at: new Date(now).toISOString(), reason: "Replaced by a newer needs_you call.", by: agentId };
+        const ids = (call.decisions ?? []).map(d => askQuestion(w, agentId, { title: d.question.slice(0, 120), question: d.question, options: (d.options ?? []).map((o, i) => ({ letter: String.fromCharCode(65 + i), label: o.label, ...(o.consequence ? { consequence: o.consequence } : {}) })), ...(d.options?.length ? { recommend: String.fromCharCode(65 + d.recommend!) } : {}) }, mode, now).question.id);
+        if (ids.length) changed(w);
+        return ids;
+      });
+    }
+    const record: NeedsYouRecord = { at: Date.now(), turnId: turn?.turnId ?? null, call, questionIds };
+    await mkdir(join(directory, "hook-state"), { recursive: true, mode: 0o700 });
+    const temporary = `${needsYouPath(agentId)}.${randomUUID()}`;
+    await writeFile(temporary, JSON.stringify(record), { mode: 0o600 });
+    await rename(temporary, needsYouPath(agentId));
+    return { ok: true as const, briefId: `brief:${turn?.turnId ?? record.at}` };
+  });
+  server.handle(rpc.briefActionRpc, async ({ agentId, briefId, decisionId, choice, move }, { paseo }) => {
+    await requireReady(); seen(paseo);
+    const brief = await inbox.briefAction(agentId, { briefId, decisionId, choice, move }, async (text, messageId) => {
+      await paseo.agents.ref(agentId).send(text, { messageId, activeTurnBehavior: "steer" });
+    });
+    return { brief };
+  });
 
   const removers = [
-    server.on("agent.turn_started", async event => inboxHook(() => inbox.turnStarted(event.agent))),
-    server.on("agent.turn_ended", async event => inboxHook(() => inbox.turnEnded(event.agent, event.outcome, event.turnId))),
-    server.on("agent.permission_requested", async event => inboxHook(() => inbox.permissionRequested(event.agent, event.request))),
-    server.on("agent.permission_resolved", async event => inboxHook(() => inbox.permissionResolved(event.agent, event.requestId))),
+    displaySettings.subscribe(() => void writeBriefState().catch(() => undefined)),
+    server.on("agent.turn_started", async (event, { paseo }) => { seen(paseo); inboxHook(() => inbox.turnStarted(event.agent, event.turnId)); }),
+    server.on("agent.turn_ended", async (event, { paseo }) => { seen(paseo); inboxHook(() => inbox.turnEnded(event.agent, event.outcome, event.turnId)); }),
+    server.on("agent.permission_requested", async (event, { paseo }) => { seen(paseo); inboxHook(async () => { await inbox.permissionRequested(event.agent, event.request); await writeBriefState(); }); }),
+    server.on("agent.permission_resolved", async (event, { paseo }) => { seen(paseo); inboxHook(async () => { await inbox.permissionResolved(event.agent, event.requestId); await writeBriefState(); }); }),
     server.on("agent.closed", async event => inboxHook(() => inbox.closed(event.agent))),
     server.on("agent.archived", async event => inboxHook(() => inbox.archived([event.agent.id]))),
     server.on("workspace.archived", async event => inboxHook(() => inbox.workspaceArchived(event.workspace.id))),
@@ -368,16 +468,23 @@ export default function contribute(server: PluginServerContext) {
             return { ...request, env: { ...request.env, FOLLOW_THROUGH_CLI: bridge, FOLLOW_THROUGH_CLIENT_ENTRY: clientEntry() } };
         }
       }
-      if (!w && request.workspaceId && !request.labels["follow-through.recovery"] && await isWorkspaceRoot({ id: request.agentId, workspaceId: request.workspaceId, labels: request.labels }, async id => (await paseo.agents.ref(id).refresh())?.agent)) {
+      const root = !!request.workspaceId && !request.labels["follow-through.recovery"] && await isWorkspaceRoot({ id: request.agentId, workspaceId: request.workspaceId, labels: request.labels }, async id => (await paseo.agents.ref(id).refresh())?.agent);
+      // F2: needs_you and the Stop-hook nudge reach every root agent while the inbox is on, tracked or not.
+      const brief = (await inboxSettings()).enable_inbox && ["claude", "codex"].includes(request.provider) ? request.provider : null;
+      if (!w && root) {
         w = await store.mutate(state => {
           const workspace = state.workspaces.find(w => w.id === request.workspaceId && w.enable_tracking && !w.archived);
           if (workspace) workspace.contributorAgentIds = [...new Set([...(workspace.contributorAgentIds ?? []), request.agentId])];
           return workspace;
         });
       }
-      if (!w) return request;
+      if (!w) {
+        if (!brief || !root) return request;
+        return withSessionMcp({ ...request, env: { ...request.env, FOLLOW_THROUGH_BRIEF: brief } }, directory, clientEntry(), paseoHome, false, process.env, brief);
+      }
       const recovery = w.mainAgentId !== request.agentId && !w.contributorAgentIds?.includes(request.agentId);
-      return withSessionMcp({ ...request, env: { ...request.env, FOLLOW_THROUGH_CLI: bridge, FOLLOW_THROUGH_CLIENT_ENTRY: clientEntry(), ...(recovery ? { FOLLOW_THROUGH_RECOVERY: "1" } : {}) } }, directory, clientEntry(), paseoHome, recovery);
+      const main = !recovery && w.mainAgentId === request.agentId ? brief : null;
+      return withSessionMcp({ ...request, env: { ...request.env, FOLLOW_THROUGH_CLI: bridge, FOLLOW_THROUGH_CLIENT_ENTRY: clientEntry(), ...(recovery ? { FOLLOW_THROUGH_RECOVERY: "1" } : {}), ...(main ? { FOLLOW_THROUGH_BRIEF: main } : {}) } }, directory, clientEntry(), paseoHome, recovery, process.env, main);
     }),
     server.on("agent.turn_ended", async (event, { paseo, signal }) => {
       await ready;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "paseo-follow-up",
   "private": false,
-  "version": "1.1.0-beta.0",
+  "version": "1.2.0-beta.0",
   "description": "Follow every workspace PR stack in Paseo, answer agent questions, batch repairs for the main agent, and see what needs you.",
   "type": "module",
   "files": [