portable-agent-layer 0.78.3 → 0.79.0

package/assets/schema/pal-settings.schema.json

@@ -57,7 +57,6 @@
         "wisdom": { "type": "boolean", "description": "Crystallized wisdom principles." },
         "opinions": { "type": "boolean", "description": "Tracked user opinions." },
         "relationship": { "type": "boolean", "description": "Recent relationship notes." },
-        "learningDigest": { "type": "boolean", "description": "Lessons-from-failures digest." },
         "failurePatterns": { "type": "boolean", "description": "Recurring failure patterns." },
         "projectHistory": { "type": "boolean", "description": "Per-project session history." },
         "projects": { "type": "boolean", "description": "Active projects list." },

package/assets/templates/pal-settings.json

@@ -19,7 +19,6 @@
     "wisdom": true,
     "opinions": true,
     "relationship": true,
-    "learningDigest": true,
     "failurePatterns": true,
     "projectHistory": true,
     "projects": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.78.3",
+  "version": "0.79.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/hooks/LoadContext.ts

@@ -18,11 +18,13 @@ import { logContextSnapshot, logDebug, logError } from "./lib/log";
 import { platform } from "./lib/paths";
 import {
   contextEnvelope,
+  contextForSource,
   copilotInstructions,
   isSubagentSession,
   needsAgentsMd,
 } from "./lib/session-context";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
+import { readStdinJSON } from "./lib/stdin";
 
 // Recursion guard — when this process is a PAL-spawned inference subprocess,
 // skip all context loading so we don't trigger another inference call.
@@ -47,11 +49,21 @@ try {
 
 try {
   const active = getActiveAgent();
+  const input = await readStdinJSON<{ source?: string }>();
+  const wanted = contextForSource(active, input?.source);
+  if (wanted === "none") {
+    logDebug("LoadContext", `source=${input?.source}, context already present`);
+    process.exit(0);
+  }
+
   // The reminder is built for one of three targets; every other agent reads the
   // same shape Claude Code does.
   const target: AgentTarget =
     active === "copilot" || active === "cursor" ? active : "claude";
-  const reminder = buildSystemReminder({ agent: target });
+  const reminder = buildSystemReminder({
+    agent: target,
+    withoutHandoff: wanted === "without-handoff",
+  });
   if (!reminder) process.exit(0);
   logContextSnapshot(reminder);
 

package/src/hooks/PreCompactPersist.ts

@@ -17,6 +17,7 @@ import { resolve } from "node:path";
 import { persistLastExchange } from "./handlers/persist-last-exchange";
 import { logDebug, logError } from "./lib/log";
 import { paths } from "./lib/paths";
+import { sessionDir } from "./lib/session-dir";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
 import { readTranscriptFile } from "./lib/transcript";
@@ -27,7 +28,6 @@ if (isPalSpawnedInference()) process.exit(0);
 interface PreCompactInput {
   session_id?: string;
   transcript_path?: string;
-  cwd?: string;
   hook_event_name?: string;
   trigger?: "manual" | "auto";
   custom_instructions?: string;
@@ -47,7 +47,7 @@ const main = async () => {
       process.exit(0);
     }
     const sessionId = input.session_id ?? "unknown";
-    const cwd = input.cwd ?? process.cwd();
+    const cwd = sessionDir();
 
     // Stop fires after every response and is authoritative. Skip if it already
     // wrote latest.json for this session — PreCompact is a safety net only.

package/src/hooks/handlers/persist-last-exchange.ts

@@ -4,22 +4,22 @@
  * Writes two outputs:
  *  1. last-exchange/{sessionId}.json + last-exchange/latest.json
  *     → read by CompactRecover to re-inject after compaction
- *  2. last-handoff.json keyed by cwd
- *     → read by loadHandoff() to surface "Pick Up Where You Left Off"
+ *  2. last-handoff.json keyed by the session's start folder
+ *     → read by loadHandoffContext() to surface "Pick Up Where You Left Off"
  *
- * last-exchange is always overwritten — Stop is its source of truth. last-handoff
- * is NOT: a deliberate LEARN-phase note (written by handoff-note.ts with
- * source:"deliberate") outranks this raw auto-snapshot, so we leave it intact
- * while it is still fresh and in-progress. Otherwise the auto-snapshot would
- * clobber the curated handoff the moment the session stopped (ISC-39).
+ * last-exchange is always overwritten — Stop is its source of truth. In
+ * last-handoff only the exchange fields are: a deliberate LEARN-phase note
+ * (source:"deliberate") and the summary session intelligence wrote for this
+ * session both stay beside it (ISC-39).
  */
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { trimAtWord } from "../lib/handoff-context";
 import { logDebug, logError } from "../lib/log";
 import { ensureDir, paths } from "../lib/paths";
+import { sessionDir } from "../lib/session-dir";
 import { extractContent, extractLastAssistant, extractLastUser } from "../lib/transcript";
-import { detectStatus } from "../lib/work-tracking";
 
 type ParsedMessage = { role: string; content: unknown };
 
@@ -39,34 +39,124 @@ interface AutoHandoff {
   title: string;
   status: string;
   handoff: string;
+  waitingOn?: string;
+  sessionId?: string;
 }
 
-function readHandoffs(handoffPath: string): Record<string, unknown> {
+interface LastExchange {
+  sessionId: string;
+  lastUser: string;
+  lastAssistant: string;
+}
+
+type StoredHandoff = Partial<AutoHandoff & LastExchange> & {
+  timestamp?: string;
+  source?: string;
+  artifacts?: string[];
+};
+
+const LAST_USER_MAX_CHARS = 200;
+const LAST_ASSISTANT_MAX_CHARS = 300;
+
+function handoffPath(): string {
+  return resolve(ensureDir(paths.state()), "last-handoff.json");
+}
+
+function readHandoffs(): Record<string, StoredHandoff> {
   try {
-    return existsSync(handoffPath) ? JSON.parse(readFileSync(handoffPath, "utf-8")) : {};
+    const p = handoffPath();
+    return existsSync(p) ? JSON.parse(readFileSync(p, "utf-8")) : {};
   } catch {
     return {};
   }
 }
 
-/** Record this cwd's handoff unless a fresh deliberate note already owns it (ISC-39). */
+function writeHandoffs(handoffs: Record<string, StoredHandoff>): void {
+  writeFileSync(handoffPath(), JSON.stringify(handoffs, null, 2), "utf-8");
+}
+
+export function structuredHandoff(parts: {
+  done: string;
+  next: string;
+  waitingOn: string;
+}): string {
+  return [
+    parts.done && `Done: ${parts.done}`,
+    parts.next && `Next: ${parts.next}`,
+    parts.waitingOn && `Waiting on you: ${parts.waitingOn}`,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+function sameSession(entry: StoredHandoff | undefined, sessionId?: string): boolean {
+  return sessionId !== undefined && entry?.sessionId === sessionId;
+}
+
+/** Record this folder's summary unless a fresh deliberate note already owns it (ISC-39). */
 export function writeAutoHandoff(cwd: string, entry: AutoHandoff): void {
-  const handoffPath = resolve(ensureDir(paths.state()), "last-handoff.json");
-  const existing = readHandoffs(handoffPath);
-  if (isProtectedHandoff(existing[cwd])) return;
-  existing[cwd] = {
+  const handoffs = readHandoffs();
+  const existing = handoffs[cwd];
+  if (isProtectedHandoff(existing)) return;
+  const exchange = sameSession(existing, entry.sessionId)
+    ? { lastUser: existing?.lastUser, lastAssistant: existing?.lastAssistant }
+    : {};
+  handoffs[cwd] = {
     timestamp: new Date().toISOString(),
     ...entry,
+    ...exchange,
     artifacts: [],
     source: "auto",
   };
-  writeFileSync(handoffPath, JSON.stringify(existing, null, 2), "utf-8");
+  writeHandoffs(handoffs);
+}
+
+function closingParagraph(text: string): string {
+  const paragraphs = text
+    .split(/\n\s*\n/)
+    .map((p) => p.trim())
+    .filter((p) => p.length >= 15);
+  return paragraphs.at(-1) ?? text;
+}
+
+/**
+ * The raw exchange is written on every stop; the summary only every few
+ * messages. So within one session the exchange is refreshed beside the
+ * summary rather than over it, and a new session starts a clean entry.
+ */
+function recordLastExchange(cwd: string, exchange: LastExchange): void {
+  const handoffs = readHandoffs();
+  const existing = handoffs[cwd];
+  const trimmed = {
+    sessionId: exchange.sessionId,
+    lastUser: trimAtWord(exchange.lastUser, LAST_USER_MAX_CHARS),
+    lastAssistant: trimAtWord(
+      closingParagraph(exchange.lastAssistant),
+      LAST_ASSISTANT_MAX_CHARS
+    ),
+  };
+  if (isProtectedHandoff(existing)) {
+    handoffs[cwd] = { ...existing, ...trimmed };
+  } else if (sameSession(existing, exchange.sessionId)) {
+    handoffs[cwd] = { ...existing, ...trimmed, timestamp: new Date().toISOString() };
+  } else {
+    handoffs[cwd] = {
+      timestamp: new Date().toISOString(),
+      title: trimAtWord(exchange.lastUser, 80) || "Session",
+      status: "in-progress",
+      handoff: "",
+      artifacts: [],
+      source: "auto",
+      ...trimmed,
+    };
+  }
+  writeHandoffs(handoffs);
 }
 
 export function persistLastExchange(
   messages: ParsedMessage[],
   sessionId: string,
-  cwd: string = process.cwd()
+  cwd: string = sessionDir()
 ): void {
   try {
     const lastUser = extractContent(extractLastUser(messages));
@@ -87,17 +177,7 @@ export function persistLastExchange(
     writeFileSync(resolve(stateDir, `${sessionId}.json`), json, "utf-8");
     writeFileSync(resolve(stateDir, "latest.json"), json, "utf-8");
 
-    const handoff = [
-      lastUser ? `Last user message:\n${lastUser.slice(0, 500)}` : "",
-      lastAssistant ? `\nLast assistant response:\n${lastAssistant.slice(0, 500)}` : "",
-    ]
-      .filter(Boolean)
-      .join("");
-    writeAutoHandoff(cwd, {
-      title: (lastUser.slice(0, 80).replace(/\n/g, " ") || "Session").trim(),
-      status: detectStatus(lastAssistant),
-      handoff,
-    });
+    recordLastExchange(cwd, { sessionId, lastUser, lastAssistant });
 
     logDebug(
       "persist-last-exchange",

package/src/hooks/handlers/session-intelligence.ts

@@ -1,8 +1,8 @@
 /**
  * Stop handler: unified session intelligence capture.
  *
- * Produces: title, summary, insights, handoff via Haiku.
- * Writes: session learning file, project history, auto handoff (in-progress only).
+ * Produces: title, summary, insights, status and a done/next/waiting handoff via Haiku.
+ * Writes: session learning file, project history, auto handoff.
  *
  * Relationship notes → written in ALGORITHM LEARN phase via relationship-note.ts
  * Handoff notes     → written in ALGORITHM LEARN phase via handoff-note.ts
@@ -23,6 +23,7 @@ import { canInfer, inference } from "../lib/inference";
 import { categorizeLearning } from "../lib/learning-category";
 import { logDebug, logError } from "../lib/log";
 import { ensureDir, paths } from "../lib/paths";
+import { sessionDir } from "../lib/session-dir";
 import { fileTimestamp, monthPath } from "../lib/time";
 import { logTokenUsage } from "../lib/token-usage";
 import {
@@ -31,8 +32,8 @@ import {
   extractLastUser,
   parseMessages,
 } from "../lib/transcript";
-import { appendProjectHistory, detectStatus } from "../lib/work-tracking";
-import { writeAutoHandoff } from "./persist-last-exchange";
+import { appendProjectHistory } from "../lib/work-tracking";
+import { structuredHandoff, writeAutoHandoff } from "./persist-last-exchange";
 
 // ── JSON schema for merged Haiku call ──
 
@@ -51,20 +52,51 @@ const INTELLIGENCE_SCHEMA = {
       description:
         "What worked, what was surprising, what to do differently, 2-3 bullet points",
     },
-    handoff: {
+    status: {
       type: "string" as const,
+      enum: ["in-progress", "completed"],
       description:
-        "If status is in-progress: what remains to be done, key decisions made, blockers. If completed: empty string.",
+        "in-progress if work remains or the AI's last message awaits the user's answer; completed only if nothing is left",
+    },
+    done: {
+      type: "string" as const,
+      description: "What the latest piece of work finished, one sentence",
+    },
+    next: {
+      type: "string" as const,
+      description: "The concrete next step, one sentence, empty if none",
+    },
+    waitingOn: {
+      type: "string" as const,
+      description:
+        "What the AI needs from the user before it can continue, empty if nothing",
     },
   },
-  required: ["title", "summary", "insights", "handoff"] as const,
+  required: [
+    "title",
+    "summary",
+    "insights",
+    "status",
+    "done",
+    "next",
+    "waitingOn",
+  ] as const,
 };
 
 interface IntelligenceOutput {
   title: string;
   summary: string;
   insights: string;
-  handoff: string;
+  status: "in-progress" | "completed";
+  done: string;
+  next: string;
+  waitingOn: string;
+}
+
+/** A reply states its verdict first and its question to the user last. */
+export function openingAndClosing(text: string, each: number): string {
+  if (text.length <= each * 2) return text;
+  return `${text.slice(0, each)} … ${text.slice(-each)}`;
 }
 
 // ── Main handler ──
@@ -96,10 +128,9 @@ export async function captureSessionIntelligence(
   const lastAssistant = extractLastAssistant(messages);
   const lastAssistantText = extractContent(lastAssistant);
   const lastUser = extractLastUser(messages);
-  const status = detectStatus(lastAssistantText);
 
   const userWindow = userMessages.slice(-10).map((t) => t.slice(0, 200));
-  const assistantWindow = lastAssistantText.slice(0, 600);
+  const assistantWindow = openingAndClosing(lastAssistantText, 300);
 
   if (userWindow.length < 3) return;
 
@@ -111,17 +142,15 @@ export async function captureSessionIntelligence(
     const result = await inference({
       system: [
         "You analyze a session between a human user and an AI assistant. Sessions may involve coding, research, writing, planning, analysis, or any other task.",
-        `Session status: ${status}.`,
         "Produce ALL of the following:",
         "1. title: short title (5-10 words) describing what was accomplished",
         "2. summary: what the AI did for the user (2-4 sentences, AI perspective using 'we')",
         "3. insights: what worked, what was surprising, what to do differently (2-3 points, no markdown)",
-        status === "in-progress"
-          ? "4. handoff: what remains unfinished — decisions made so far, next steps, blockers (2-4 sentences)"
-          : "4. handoff: empty string (session completed)",
+        "4. status: in-progress if work remains or the last AI response ends with a question or offer awaiting the user; completed only if nothing is left",
+        "5. done, next, waitingOn: a handoff for whoever picks this up next. Describe the LATEST thread of work, the one the last messages are about, not earlier topics of the session. One sentence each; next and waitingOn may be empty.",
       ].join("\n"),
       user: `User messages:\n${numberedMessages}\n\nLast AI response:\n${assistantWindow}`,
-      maxTokens: 350,
+      maxTokens: 450,
       timeout: 90000,
       jsonSchema: INTELLIGENCE_SCHEMA,
       caller: "session-intelligence",
@@ -141,8 +170,14 @@ export async function captureSessionIntelligence(
   const title = output?.title || extractContent(lastUser).slice(0, 80) || "session";
   const summary = output?.summary || lastAssistantText.slice(0, 600);
   const insights = output?.insights || "";
-  if (status === "in-progress" && output?.handoff) {
-    writeAutoHandoff(process.cwd(), { title, status, handoff: output.handoff });
+  if (output) {
+    writeAutoHandoff(sessionDir(), {
+      title,
+      status: output.status,
+      handoff: structuredHandoff(output),
+      waitingOn: output.waitingOn,
+      sessionId,
+    });
   }
   // ── Write session learning file ──
 

package/src/hooks/lib/context.ts

@@ -9,15 +9,16 @@ import { loadReflectNudge } from "../handlers/reflect-trigger";
 import { loadAlgorithmReviewNudge } from "./algorithm-review";
 import { loadAnalyzeNudge } from "./analyze-nudge";
 import { resolveAnchor } from "./anchor";
-import { readLearnings } from "./learning-store";
+import { loadHandoffContext } from "./handoff-context";
 import { loadOpinionContext } from "./opinions";
 import { paths, toPath } from "./paths";
 import { loadActiveProjectsContext } from "./projects";
 import { loadRecentNotes } from "./relationship";
 import { loadFailurePatterns } from "./semi-static";
+import { sessionDir } from "./session-dir";
 import * as settings from "./settings";
 import { readFramePrinciples } from "./wisdom";
-import { readProjectHistory } from "./work-tracking";
+import { lastSessionTitle, readProjectHistory } from "./work-tracking";
 
 /** Load and concatenate loadAtStartup files */
 function loadStartupFiles(): string {
@@ -51,29 +52,6 @@ export function loadWisdomContext(): string {
   }
 }
 
-/** Load recent session learning files as digest, with detail for current project */
-export function loadLearningDigest(): string {
-  try {
-    const cwd = process.cwd();
-    const entries = readLearnings(paths.sessionLearning(), 10);
-    if (entries.length === 0) return "";
-
-    // This-project learnings are now in loadProjectHistoryContext(); only show cross-project here
-    const other = entries.filter((e) => e.cwd !== cwd).slice(0, 5);
-
-    if (other.length === 0) return "";
-
-    const lines: string[] = [];
-
-    lines.push("## Other Recent Learnings");
-    for (const e of other) lines.push(`- ${e.title}`);
-
-    return lines.join("\n");
-  } catch {
-    return "";
-  }
-}
-
 /** Load self-model for session context injection */
 function loadSelfModel(): string {
   try {
@@ -219,31 +197,6 @@ function loadSessionIntelligence(): string {
   }
 }
 
-/** Load handoff state for the current project */
-function loadHandoff(): string {
-  try {
-    const p = resolve(paths.state(), "last-handoff.json");
-    if (!existsSync(p)) return "";
-    const handoffs = JSON.parse(readFileSync(p, "utf-8"));
-    const cwd = process.cwd();
-    const entry = handoffs[cwd];
-    if (!entry?.handoff || entry.status !== "in-progress") return "";
-
-    const age = Date.now() - new Date(entry.timestamp).getTime();
-    if (age > 7 * 24 * 60 * 60 * 1000) return ""; // stale after 7 days
-
-    return [
-      "## Pick Up Where You Left Off",
-      `*Previous session: ${entry.title}*`,
-      "",
-      entry.handoff,
-      "→ Continue this work or explicitly close it before starting something new.",
-    ].join("\n");
-  } catch {
-    return "";
-  }
-}
-
 /** Truncate text to maxChars at the last complete line boundary */
 function capSection(text: string, maxChars: number): string {
   if (text.length <= maxChars) return text;
@@ -272,7 +225,9 @@ export type AgentTarget = "claude" | "opencode" | "cursor" | "copilot";
  * opts.agent — agent target; Claude Code skips semi-static sections (self-model,
  * wisdom, opinions) that load natively via @imports in CLAUDE.md.
  */
-export function buildSystemReminder(opts: { agent?: AgentTarget } = {}): string {
+export function buildSystemReminder(
+  opts: { agent?: AgentTarget; withoutHandoff?: boolean } = {}
+): string {
   // Semi-static sections loaded natively via @imports (Claude Code) or
   // instructions[] (opencode). Skip them from hook output for those agents.
   const skipSemiStatic =
@@ -287,12 +242,11 @@ export function buildSystemReminder(opts: { agent?: AgentTarget } = {}): string
   const relationship = settings.isEnabled("relationship")
     ? loadRelationshipContext()
     : "";
-  const digest = settings.isEnabled("learningDigest") ? loadLearningDigest() : "";
   const projectHistory = settings.isEnabled("projectHistory")
     ? loadProjectHistoryContext()
     : "";
   const activeProjects = settings.isEnabled("projects")
-    ? loadActiveProjectsContext()
+    ? loadActiveProjectsContext(process.cwd(), lastSessionTitle)
     : "";
   const failures =
     settings.isEnabled("failurePatterns") && !skipSemiStatic ? loadFailurePatterns() : "";
@@ -303,7 +257,10 @@ export function buildSystemReminder(opts: { agent?: AgentTarget } = {}): string
   const intelligence = settings.isEnabled("sessionIntelligence")
     ? loadSessionIntelligence()
     : "";
-  const handoff = settings.isEnabled("handoff") ? loadHandoff() : "";
+  const handoff =
+    !opts.withoutHandoff && settings.isEnabled("handoff")
+      ? loadHandoffContext(sessionDir())
+      : "";
   // Maintainer-only: self-gates to a repo checkout, "" for everyone else.
   const algoReview = loadAlgorithmReviewNudge();
   const reflectNudge = loadReflectNudge();
@@ -321,7 +278,6 @@ export function buildSystemReminder(opts: { agent?: AgentTarget } = {}): string
   if (relationship) parts.push(relationship);
   if (activeProjects) parts.push(activeProjects);
   if (projectHistory) parts.push(projectHistory);
-  if (digest) parts.push(digest);
   if (failures) parts.push(failures);
   if (parts.length === 0) return "";
 

package/src/hooks/lib/graduation.ts

@@ -12,7 +12,7 @@
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { hasApiKey } from "./inference";
+import { canInfer } from "./inference";
 import {
   type FailureEntry,
   type LearningEntry,
@@ -215,7 +215,7 @@ async function generateRecommendations(
   ratings: RatingsSummary | null
 ): Promise<string[]> {
   if (candidates.length === 0 && !ratings) return [];
-  if (!hasApiKey()) {
+  if (!canInfer()) {
     return candidates
       .slice(0, 3)
       .map(

package/src/hooks/lib/handoff-context.ts

@@ -0,0 +1,112 @@
+import { existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+
+interface HandoffEntry {
+  title?: string;
+  handoff?: string;
+  status?: string;
+  timestamp?: string;
+  lastUser?: string;
+  lastAssistant?: string;
+}
+
+const HANDOFF_STALE_MS = 7 * 24 * 60 * 60 * 1000;
+const ELSEWHERE_MAX_CHARS = 300;
+
+function readHandoffs(): Record<string, HandoffEntry> {
+  const p = resolve(paths.state(), "last-handoff.json");
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function isFresh(entry: HandoffEntry, now: number): boolean {
+  if (!(entry.handoff || entry.lastUser) || !entry.timestamp) return false;
+  return now - new Date(entry.timestamp).getTime() <= HANDOFF_STALE_MS;
+}
+
+function isScratchDir(dir: string): boolean {
+  return dir.startsWith(tmpdir());
+}
+
+export function trimAtWord(text: string, max: number): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  if (flat.length <= max) return flat;
+  const cut = flat.slice(0, max);
+  const lastSpace = cut.lastIndexOf(" ");
+  return `${lastSpace > 0 ? cut.slice(0, lastSpace) : cut}…`;
+}
+
+function formatAgo(timestamp: string, now: number): string {
+  const minutes = Math.floor((now - new Date(timestamp).getTime()) / 60_000);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
+function lastExchangeLines(entry: HandoffEntry): string[] {
+  if (!entry.lastUser) return [];
+  const lines = ["Last exchange:", `- User: ${entry.lastUser}`];
+  if (entry.lastAssistant) lines.push(`- You: ${entry.lastAssistant}`);
+  return lines;
+}
+
+/** A finished session is still shown, for follow-ups, just not as open work. */
+function hereSection(entry: HandoffEntry | undefined, now: number): string {
+  if (!entry || !isFresh(entry, now)) return "";
+  const open = entry.status !== "completed";
+  return [
+    "## Pick Up Where You Left Off",
+    `*Previous session: ${entry.title} · ${formatAgo(entry.timestamp ?? "", now)}*`,
+    ...(entry.handoff ? [entry.handoff] : []),
+    ...lastExchangeLines(entry),
+    ...(open
+      ? ["→ Continue this work or explicitly close it before starting something new."]
+      : []),
+  ].join("\n");
+}
+
+function latestElsewhere(
+  handoffs: Record<string, HandoffEntry>,
+  here: string,
+  now: number
+): [string, HandoffEntry] | undefined {
+  return Object.entries(handoffs)
+    .filter(([dir, entry]) => dir !== here && !isScratchDir(dir) && isFresh(entry, now))
+    .sort(([, a], [, b]) => (b.timestamp ?? "").localeCompare(a.timestamp ?? ""))[0];
+}
+
+function elsewhereSection(
+  handoffs: Record<string, HandoffEntry>,
+  here: string,
+  now: number
+): string {
+  const latest = latestElsewhere(handoffs, here, now);
+  if (!latest) return "";
+  const [dir, entry] = latest;
+  const hereEntry = handoffs[here];
+  if (hereEntry?.timestamp && hereEntry.timestamp > (entry.timestamp ?? "")) return "";
+  return [
+    "## Last Conversation Elsewhere",
+    `*${dir} · ${formatAgo(entry.timestamp ?? "", now)} · may be unrelated: ${entry.title}*`,
+    trimAtWord(entry.handoff || `User: ${entry.lastUser}`, ELSEWHERE_MAX_CHARS),
+  ].join("\n");
+}
+
+/**
+ * This folder's handoff comes first and in full, since it is what a session
+ * started here usually continues. The latest conversation from any other
+ * folder follows in brief, only when it is newer than this folder's.
+ */
+export function loadHandoffContext(here: string, now: number = Date.now()): string {
+  const handoffs = readHandoffs();
+  return [hereSection(handoffs[here], now), elsewhereSection(handoffs, here, now)]
+    .filter(Boolean)
+    .join("\n\n");
+}

package/src/hooks/lib/projects.ts

@@ -391,10 +391,14 @@ const MAX_INLINE_BULLETS = 3;
  * Format the SessionStart "Active Projects" section.
  *
  * For the cwd-resolved project (`→ here`): full detail with Context, Objectives
- * (from goal section), Next, and Blockers. For all others: compact one-liner with
- * next/blocker counts only. Stale flag (>14d) and browse-mode hint included.
+ * (from goal section), Next, and Blockers. Other recent projects: one line with
+ * counts and the last session's title, enough to follow up from any folder.
+ * Quiet ones (>14d) collapse to a single line of names.
  */
-export function loadActiveProjectsContext(cwd: string = process.cwd()): string {
+export function loadActiveProjectsContext(
+  cwd: string = process.cwd(),
+  lastSessionTitle: (project: string) => string | undefined = () => undefined
+): string {
   const all = readAllProjects();
   const visible = all.filter((p) => p.status === "active" || p.status === "paused");
   const resolved = resolveProjectFromCwd(cwd, visible);
@@ -411,6 +415,7 @@ export function loadActiveProjectsContext(cwd: string = process.cwd()): string {
   if (visible.length > 0) {
     lines.push("## Active Projects", "");
     const sorted = [...visible].sort((a, b) => b.updated.localeCompare(a.updated));
+    const quiet: string[] = [];
     for (const p of sorted) {
       const ago = formatAgo(p.updated);
       const stale = isStale(p) ? " ⚠ stale" : "";
@@ -447,14 +452,21 @@ export function loadActiveProjectsContext(cwd: string = process.cwd()): string {
         if (p.blockers?.length) {
           lines.push(`  Blockers: ${p.blockers.slice(0, MAX_INLINE_BULLETS).join("; ")}`);
         }
+      } else if (stale) {
+        quiet.push(p.name);
       } else {
         const counts: string[] = [];
         if (p.next?.length) counts.push(`${p.next.length} next`);
         if (p.blockers?.length) counts.push(`${p.blockers.length} blockers`);
         const countsSuffix = counts.length > 0 ? ` — ${counts.join(", ")}` : "";
-        lines.push(`- **${p.name}** (${statusPrefix}${ago})${countsSuffix}${stale}`);
+        const last = lastSessionTitle(p.name);
+        const lastSuffix = last ? ` — last: ${last}` : "";
+        lines.push(`- **${p.name}** (${statusPrefix}${ago})${countsSuffix}${lastSuffix}`);
       }
     }
+    if (quiet.length > 0) {
+      lines.push(`- Quiet for ${PROJECT_STALE_DAYS_DEFAULT}+ days: ${quiet.join(", ")}`);
+    }
   }
 
   if (showHint) {

package/src/hooks/lib/session-context.ts

@@ -24,6 +24,28 @@ export function isSubagentSession(env: NodeJS.ProcessEnv): boolean {
   return env.CLAUDE_PROJECT_DIR?.includes("/.claude/Agents/") ?? false;
 }
 
+export type SessionStartContext = "full" | "without-handoff" | "none";
+
+/**
+ * Claude Code and Codex replay the context injected at startup when a session
+ * is resumed. Copilot does not document it, and has shipped a release that
+ * dropped startup context, so it keeps getting the full context on resume.
+ */
+const RESUME_KEEPS_CONTEXT: ReadonlySet<string> = new Set(["claude", "codex"]);
+
+/**
+ * After a compaction, CompactRecover restores the last exchange, so the
+ * handoff is redundant. Agents that name no source get everything.
+ */
+export function contextForSource(
+  agent: string,
+  source: string | undefined
+): SessionStartContext {
+  if (source === "resume" && RESUME_KEEPS_CONTEXT.has(agent)) return "none";
+  if (source === "compact") return "without-handoff";
+  return "full";
+}
+
 /**
  * Copilot and Cursor read AGENTS.md natively from nothing, so it is prepended
  * here; Codex reaches it through a symlink and Claude Code loads it itself.

package/src/hooks/lib/session-dir.ts

@@ -0,0 +1,9 @@
+/**
+ * The folder a session was started in. A hook's own cwd follows every `cd`
+ * the agent makes, so keying by it files a session under whatever subfolder
+ * it happened to end in. Claude Code exports the start folder as
+ * CLAUDE_PROJECT_DIR; agents that do not fall back to the cwd.
+ */
+export function sessionDir(env: NodeJS.ProcessEnv = process.env): string {
+  return env.CLAUDE_PROJECT_DIR || process.cwd();
+}

package/src/hooks/lib/work-tracking.ts

@@ -169,7 +169,15 @@ export function appendProjectHistory(cwd: string, entry: ProjectHistoryEntry): v
 
 /** Read the session history for a given cwd */
 export function readProjectHistory(cwd: string, limit = 15): ProjectHistoryEntry[] {
-  const historyPath = historyFileFor(cwd);
+  return readHistoryFile(historyFileFor(cwd), limit);
+}
+
+export function lastSessionTitle(project: string): string | undefined {
+  const historyPath = resolve(paths.projectHistory(), project, "history.jsonl");
+  return readHistoryFile(historyPath, 1)[0]?.title;
+}
+
+function readHistoryFile(historyPath: string, limit: number): ProjectHistoryEntry[] {
   if (!existsSync(historyPath)) return [];
   try {
     const lines = readFileSync(historyPath, "utf-8").trim().split("\n").filter(Boolean);