portable-agent-layer 0.111.0 → 0.112.0

package/README.md

@@ -88,6 +88,7 @@ pal cli status        # check your setup
 | `pal cli cost` | What each month was paid against its API-equivalent cost, per agent |
 | `pal cli wrapped [--year <yyyy>]` | A year of your work in numbers, read from the event log |
 | `pal cli patterns` | How you work across projects, read from the event log |
+| `pal cli work [show\|list\|open\|enter\|park\|wait\|done\|stopped\|decide\|attach\|follow-up]` | The work tree: what you are on in this project, where it stopped, what is parked or waiting, and the decisions and artifacts on each node. Detours are child nodes and `done` returns to the parent. With `dynamicContext.workTree` opted into, the active node rides along in every session and prompt, and your own commits attach to it at turn end |
 | `pal cli content preserve` | Copy every Claude Code transcript, gzipped, into `memory/content/` before Claude Code deletes it (30 days by default). Runs on its own whenever a session closes; the content store never leaves the machine, so `export` skips it |
 | `pal cli events discord-nag <sent\|answered>` | For a bot outside PAL: record a nag it sent (`--kind <kind>`), or the answer to one and how long it took (`--after-sec <n>`), in the local event log |
 | `pal cli infer` | One model call for scripts and bots, on the active agent's route: prompt on stdin, reply on stdout. `--tier small\|medium\|large\|flagship` (on Claude: Haiku, Sonnet, Opus, Fable; on Codex: Luna, Sol, Sol at high effort, Astra; on Antigravity: Flash at low, medium and high effort, and no flagship; an agent without the tier asked refuses it), `--system <file>`, `--schema <file>` for a JSON reply checked against it, `--timeout <seconds>`. The call loads no PAL hooks or context; exits 1 with the reason when no route answers |

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

@@ -74,6 +74,14 @@
           "type": "boolean",
           "description": "One line with every prompt saying whether the work in the current directory is committed, pushed and released; a registered project without git is named as such."
         },
+        "workTree": {
+          "type": "boolean",
+          "description": "Opt-in, off by default until 1.0. The work tree (pal cli work): the active node, the detours it sits inside, parked work and what waits on the user at session start and after compaction, one line of it with every prompt, and new commits and branches attached to the active node at the end of a turn."
+        },
+        "workTreeGate": {
+          "type": "boolean",
+          "description": "Opt-in, off by default until 1.0. Send a turn back when it committed, made a branch, opened a PR or published an artifact without recording it in the work tree (pal cli work). Needs workTree."
+        },
         "dueReminders": {
           "type": "boolean",
           "description": "Opt-in, off by default until 1.0. Due maintenance reminders (learning analysis, relationship reflect) with every prompt until a reply names their command; then quiet until the next day."

package/assets/templates/AGENTS.md.template

@@ -56,6 +56,7 @@ Start your response with the following header in this mode:
 - **Mandatory output format** — Every response MUST use exactly one of the output formats above (ALGORITHM, NATIVE, or MINIMAL). No freeform output.
 - **Response format before questions** — Always complete the current response format output FIRST, then invoke AskUserQuestion at the end.
 - **Named project → resume first** — Whenever the user references a project by name in ANY mode, run `pal cli project resume <slug>` before any file search or task execution. The project record has paths, context, and handoff notes that make manual searching unnecessary.
+{{IF workTree}}- **Keep the work tree true** — Record work in the tree with `pal cli work` as it happens, not at the end: `open` a node for new work (`--root` when it is unrelated), update `stopped` when the state moves, `decide` when a choice is settled, `attach` what the work produced, `done` when it is finished. When the user switches topic mid-work, `park --stopped "…"` the current node before starting the new one. Once a scope has work, the `Work:` line in each prompt shows where you are.
 
 ---
 

package/assets/templates/pal-settings.json

@@ -27,6 +27,8 @@
     "skillMatching": true,
     "wallClock": true,
     "repoState": true,
+    "workTree": false,
+    "workTreeGate": false,
     "dueReminders": false,
     "interactionAwareness": true,
     "reactionSampling": true,

package/package.json

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

package/src/cli/tree.ts

@@ -30,6 +30,7 @@ import { serverCommand } from "./server";
 import { skillCommand } from "./skill";
 import { subagentCommand } from "./subagent";
 import { usageCommand } from "./usage";
+import { workCommand } from "./work";
 import { wrappedCommand } from "./wrapped";
 
 type Handler = Leaf["run"];
@@ -171,6 +172,7 @@ export function cliTree(admin: AdminHandlers): Group {
       ledger: ledgerCommand,
       rule: ruleCommand,
       correction: correctionCommand,
+      work: workCommand,
       server: serverCommand,
       skill: skillCommand,
       subagent: subagentCommand,

package/src/cli/work.ts

@@ -0,0 +1,344 @@
+/**
+ * pal cli work — the work tree: what is active, what is parked and where it
+ * stopped, the decisions and artifacts of each piece of work.
+ */
+
+import {
+  ARTIFACT_KINDS,
+  type ArtifactKind,
+  appendEvent,
+  findNode,
+  newNodeId,
+  readTree,
+  type ScopeTree,
+  scopeOf,
+  type WorkNode,
+} from "../hooks/lib/work-tree";
+import {
+  renderNodeDetail,
+  renderSessionContext,
+  renderTreeList,
+  suffix,
+} from "../hooks/lib/work-tree-render";
+import { group, leaf, runCommand, UsageError } from "../tools/lib/command";
+
+const SCOPE = {
+  type: "string",
+  description: "Project or folder the work belongs to (default: the current one)",
+} as const;
+const NODE = {
+  type: "string",
+  description: "Node id or unambiguous prefix (default: the active node)",
+} as const;
+
+class NodeError extends Error {}
+
+function scopeFrom(values: { scope?: string }): string {
+  return values.scope ?? scopeOf(process.cwd());
+}
+
+function requireText(text: string | undefined, what: string): string {
+  if (!text?.trim()) throw new UsageError(`${what} is required`);
+  return text.trim();
+}
+
+function targetNode(tree: ScopeTree, idOrPrefix: string | undefined): WorkNode {
+  if (idOrPrefix) {
+    const node = findNode(tree, idOrPrefix);
+    if (!node)
+      throw new NodeError(`No single node matches "${idOrPrefix}" in ${tree.scope}`);
+    return node;
+  }
+  const active = tree.active ? tree.nodes.get(tree.active) : undefined;
+  if (!active)
+    throw new NodeError(
+      `No active node in ${tree.scope}; pass --node, or open or enter one first`
+    );
+  return active;
+}
+
+function guarded(run: () => void): number {
+  try {
+    run();
+    return 0;
+  } catch (err) {
+    if (!(err instanceof NodeError)) throw err;
+    console.error(err.message);
+    return 1;
+  }
+}
+
+function record<T extends Parameters<typeof appendEvent>[2]>(
+  values: { scope?: string; node?: string },
+  type: T,
+  payload: Parameters<typeof appendEvent<T>>[3],
+  done: (node: WorkNode) => string
+): number {
+  return guarded(() => {
+    const scope = scopeFrom(values);
+    const node = targetNode(readTree(scope), values.node);
+    appendEvent(scope, node.id, type, payload);
+    console.log(done(node));
+  });
+}
+
+function parentFor(tree: ScopeTree, under: string | undefined, root: boolean) {
+  if (root) return null;
+  if (under) return targetNode(tree, under).id;
+  return tree.active;
+}
+
+function optionalIsc(isc: string | undefined): number | undefined {
+  if (isc === undefined) return undefined;
+  const parsed = Number(isc);
+  if (!Number.isInteger(parsed) || parsed < 1)
+    throw new UsageError(`--isc must be an ISC number, got "${isc}"`);
+  return parsed;
+}
+
+function cmdOpen(
+  title: string | undefined,
+  values: {
+    scope?: string;
+    under?: string;
+    root?: boolean;
+    isc?: string;
+    commitment?: string;
+  }
+): number {
+  const text = requireText(title, "A title");
+  const isc = optionalIsc(values.isc);
+  return guarded(() => {
+    const scope = scopeFrom(values);
+    const tree = readTree(scope);
+    const parent = parentFor(tree, values.under, values.root === true);
+    const id = newNodeId();
+    const links = {
+      ...(isc !== undefined && { isc }),
+      ...(values.commitment && { commitment: values.commitment }),
+    };
+    appendEvent(scope, id, "open", { title: text, parent, links });
+    const under = parent ? ` under ${tree.nodes.get(parent)?.title ?? parent}` : "";
+    console.log(`Opened ${text} [${id}]${under}; it is now active.`);
+  });
+}
+
+function backTo(scope: string): string {
+  const tree = readTree(scope);
+  const active = tree.active ? tree.nodes.get(tree.active) : undefined;
+  if (!active) return "No node is active now.";
+  return `Back to ${active.title} [${active.id}]${suffix(", stopped at: ", active.stoppedAt)}.`;
+}
+
+function cmdDone(values: { scope?: string; node?: string; summary?: string }): number {
+  return guarded(() => {
+    const scope = scopeFrom(values);
+    const node = targetNode(readTree(scope), values.node);
+    appendEvent(
+      scope,
+      node.id,
+      "done",
+      values.summary ? { summary: values.summary } : {}
+    );
+    console.log(`Done: ${node.title} [${node.id}]. ${backTo(scope)}`);
+  });
+}
+
+function artifactKind(kind: string | undefined): ArtifactKind {
+  if (kind && (ARTIFACT_KINDS as readonly string[]).includes(kind))
+    return kind as ArtifactKind;
+  throw new UsageError(
+    `kind must be one of ${ARTIFACT_KINDS.join(", ")}, got "${kind ?? ""}"`
+  );
+}
+
+function cmdShow(values: { scope?: string; node?: string; json?: boolean }): number {
+  return guarded(() => {
+    const tree = readTree(scopeFrom(values));
+    if (!values.node && !tree.active) {
+      console.log(
+        renderSessionContext(tree) || `No work recorded for ${tree.scope} yet.`
+      );
+      return;
+    }
+    const node = targetNode(tree, values.node);
+    console.log(
+      values.json ? JSON.stringify(node, null, 2) : renderNodeDetail(tree, node)
+    );
+  });
+}
+
+function cmdList(values: { scope?: string; all?: boolean; json?: boolean }): number {
+  const tree = readTree(scopeFrom(values));
+  if (values.json) {
+    console.log(JSON.stringify({ ...tree, nodes: [...tree.nodes.values()] }, null, 2));
+    return 0;
+  }
+  console.log(renderTreeList(tree, values.all === true));
+  return 0;
+}
+
+export const workCommand = group({
+  summary: "The work tree: what is active, parked, waiting, and where each piece stopped",
+  fallback: "show",
+  commands: {
+    show: leaf({
+      summary: "The active node in full, or the whole picture when none is active",
+      options: {
+        scope: SCOPE,
+        node: NODE,
+        json: { type: "boolean", description: "As JSON" },
+      },
+      run: ({ values }) => cmdShow(values),
+    }),
+    list: leaf({
+      summary: "Every open node as a tree",
+      options: {
+        scope: SCOPE,
+        all: { type: "boolean", description: "Include finished nodes" },
+        json: { type: "boolean", description: "As JSON" },
+      },
+      run: ({ values }) => cmdList(values),
+    }),
+    open: leaf({
+      summary: "Open a node and make it active (a child of the active node by default)",
+      args: "<title...>",
+      options: {
+        scope: SCOPE,
+        under: { type: "string", description: "Parent node id or prefix" },
+        root: {
+          type: "boolean",
+          description: "Open at the top level, not under the active node",
+        },
+        isc: { type: "string", description: "The project ISC this node works on" },
+        commitment: {
+          type: "string",
+          description: "The commitment id this node fulfils",
+        },
+      },
+      run: ({ positionals, values }) => cmdOpen(positionals.join(" "), values),
+    }),
+    enter: leaf({
+      summary: "Make a node active, parking the one that was",
+      args: "<node>",
+      options: { scope: SCOPE },
+      run: ({ positionals, values }) =>
+        record(
+          { ...values, node: requireText(positionals[0], "A node") },
+          "enter",
+          {},
+          (n) => `Entered ${n.title} [${n.id}]${suffix(", stopped at: ", n.stoppedAt)}.`
+        ),
+    }),
+    park: leaf({
+      summary: "Park a node, saying where it stopped",
+      options: {
+        scope: SCOPE,
+        node: NODE,
+        stopped: { type: "string", description: "Where it stopped, to resume from" },
+      },
+      run: ({ values }) =>
+        record(
+          values,
+          "park",
+          values.stopped ? { stoppedAt: values.stopped } : {},
+          (n) => `Parked ${n.title} [${n.id}].`
+        ),
+    }),
+    wait: leaf({
+      summary: "Mark a node as waiting on the user",
+      args: "<waits-on...>",
+      options: { scope: SCOPE, node: NODE },
+      run: ({ positionals, values }) =>
+        record(
+          values,
+          "wait",
+          { on: requireText(positionals.join(" "), "What it waits on") },
+          (n) => `${n.title} [${n.id}] is waiting on the user.`
+        ),
+    }),
+    done: leaf({
+      summary: "Finish a node; a finished detour hands the work back to its parent",
+      options: {
+        scope: SCOPE,
+        node: NODE,
+        summary: { type: "string", description: "One line on what it ended with" },
+      },
+      run: ({ values }) => cmdDone(values),
+    }),
+    stopped: leaf({
+      summary: "Record where the work stands now",
+      args: "<text...>",
+      options: { scope: SCOPE, node: NODE },
+      run: ({ positionals, values }) =>
+        record(
+          values,
+          "stopped",
+          { text: requireText(positionals.join(" "), "Where it stopped") },
+          (n) => `Stopped-at recorded on ${n.title} [${n.id}].`
+        ),
+    }),
+    decide: leaf({
+      summary: "Record a decision on a node",
+      args: "<decision...>",
+      options: {
+        scope: SCOPE,
+        node: NODE,
+        why: { type: "string", description: "The reason" },
+      },
+      run: ({ positionals, values }) =>
+        record(
+          values,
+          "decide",
+          {
+            text: requireText(positionals.join(" "), "A decision"),
+            ...(values.why && { why: values.why }),
+          },
+          (n) => `Decision recorded on ${n.title} [${n.id}].`
+        ),
+    }),
+    attach: leaf({
+      summary: `Attach an artifact to a node (${ARTIFACT_KINDS.join(", ")})`,
+      args: "<kind> <ref...>",
+      options: {
+        scope: SCOPE,
+        node: NODE,
+        label: { type: "string", description: "What it is" },
+      },
+      run: ({ positionals, values }) =>
+        record(
+          values,
+          "attach",
+          {
+            kind: artifactKind(positionals[0]),
+            ref: requireText(positionals.slice(1).join(" "), "A ref"),
+            ...(values.label && { label: values.label }),
+          },
+          (n) => `Attached to ${n.title} [${n.id}].`
+        ),
+    }),
+    "follow-up": leaf({
+      summary: "Record a follow-up on a node",
+      args: "<text...>",
+      options: {
+        scope: SCOPE,
+        node: NODE,
+        due: { type: "string", description: "When it is due, such as 2026-10-25" },
+      },
+      run: ({ positionals, values }) =>
+        record(
+          values,
+          "follow-up",
+          {
+            text: requireText(positionals.join(" "), "A follow-up"),
+            ...(values.due && { due: values.due }),
+          },
+          (n) => `Follow-up recorded on ${n.title} [${n.id}].`
+        ),
+    }),
+  },
+});
+
+export function runWork(args: string[]): Promise<number> {
+  return runCommand(workCommand, args, ["pal", "cli", "work"]);
+}

package/src/hooks/StopOrchestrator.ts

@@ -20,6 +20,7 @@ import { logError } from "./lib/log";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
 import { type StopTurnPayload, stopTurn } from "./lib/stop";
+import { stopWorkTree } from "./lib/work-tree-gate";
 
 // Recursion guard — spawned inference subprocesses must not record session
 // learning, ratings, or handoffs from their throwaway transcript.
@@ -62,4 +63,13 @@ try {
 } catch (err) {
   logError("StopOrchestrator:adaptation-rules", err);
 }
+try {
+  const sendBack = stopWorkTree(payload);
+  if (sendBack) {
+    process.stdout.write(stopBlockResponse(sendBack));
+    process.exit(0);
+  }
+} catch (err) {
+  logError("StopOrchestrator:work-tree", err);
+}
 await stopTurn(payload);

package/src/hooks/handlers/inject-retrieval.ts

@@ -22,6 +22,7 @@ import { isEnabled } from "../lib/settings";
 import { getSkillReminder } from "../lib/skill-match";
 import { getSteeringReminder } from "../lib/steering";
 import { getWallClockReminder } from "../lib/wall-clock";
+import { workTreePromptLine } from "../lib/work-tree-context";
 
 const BUDGET_MS = 250;
 
@@ -88,6 +89,7 @@ export async function getPromptContext(
     getWallClockReminder(),
     userText && withinBudget(() => promptRulesReminder(userText, sessionId), BUDGET_MS),
     withinBudget(() => getRepoStateReminder(), BUDGET_MS),
+    withinBudget(() => workTreePromptLine(userText), BUDGET_MS),
     userText && withinBudget(() => observeTurn(userText, sessionId), BUDGET_MS),
     withinBudget(() => dueNudgeReminder(), BUDGET_MS),
     userText && getSteeringReminder(userText),

package/src/hooks/lib/claim-check.ts

@@ -139,21 +139,22 @@ function isUserPrompt(entry: TranscriptLine): boolean {
 
 const ran = (input: unknown) => JSON.stringify(input ?? {});
 
-function commandsIn(entry: TranscriptLine): string[] {
+function callsIn(entry: TranscriptLine, tools: ReadonlySet<string>): string[] {
   if (entry.type === "PLANNER_RESPONSE")
     return toolCallsOf(entry)
-      .filter((call) => COMMAND_TOOLS.has(call.name ?? ""))
+      .filter((call) => tools.has(call.name ?? ""))
       .map((call) => ran(call.args));
   if (entry.type === "assistant")
     return blocks(entry.message?.content)
-      .filter((b) => b.type === "tool_use" && COMMAND_TOOLS.has(b.name ?? ""))
+      .filter((b) => b.type === "tool_use" && tools.has(b.name ?? ""))
       .map((b) => ran(b.input));
   const call = entry.payload;
   if (entry.type !== "response_item" || !call) return [];
   const input = call.input ?? call.arguments ?? call.action;
-  if (call.type === "local_shell_call") return [ran(input)];
+  if (call.type === "local_shell_call")
+    return tools === COMMAND_TOOLS ? [ran(input)] : [];
   const isCall = call.type === "function_call" || call.type === "custom_tool_call";
-  return isCall && COMMAND_TOOLS.has(call.name ?? "") ? [ran(input)] : [];
+  return isCall && tools.has(call.name ?? "") ? [ran(input)] : [];
 }
 
 function isTurnEntry(entry: TranscriptLine): boolean {
@@ -162,17 +163,24 @@ function isTurnEntry(entry: TranscriptLine): boolean {
   );
 }
 
-/** What each command this turn ran. Null when no line reads as a turn, so an
- *  unknown transcript format never counts as none. */
-export function commandsThisTurn(lines: string[]): string[] | null {
+/** The input of each call this turn made to one of the tools. Null when no line reads
+ *  as a turn, so an unknown transcript format never counts as none. */
+export function callsThisTurn(
+  lines: string[],
+  tools: ReadonlySet<string>
+): string[] | null {
   const entries = lines.map(parsed).filter((e): e is TranscriptLine => e !== null);
   if (!entries.some(isTurnEntry)) return null;
-  let commands: string[] = [];
+  let calls: string[] = [];
   for (const entry of entries) {
-    if (isUserPrompt(entry)) commands = [];
-    commands.push(...commandsIn(entry));
+    if (isUserPrompt(entry)) calls = [];
+    calls.push(...callsIn(entry, tools));
   }
-  return commands;
+  return calls;
+}
+
+export function commandsThisTurn(lines: string[]): string[] | null {
+  return callsThisTurn(lines, COMMAND_TOOLS);
 }
 
 function isBacked(claim: string, commands: string[]): boolean {

package/src/hooks/lib/claim-log.ts

@@ -40,7 +40,7 @@ function monthFile(date: Date): string {
   return resolve(claimsDir(), `${date.toISOString().slice(0, 7)}.jsonl`);
 }
 
-function transcriptLines(payload: StopTurnPayload): string[] {
+export function transcriptLines(payload: StopTurnPayload): string[] {
   const path = payload.transcript_path ?? payload.transcriptPath;
   if (!path || !existsSync(path)) return [];
   return readFileSync(path, "utf-8").split("\n").filter(Boolean);

package/src/hooks/lib/claude-md.ts

@@ -110,7 +110,16 @@ export function needsRebuild(): boolean {
   return latestMtime(...sources) > outputMtime;
 }
 
-import { identity } from "./settings";
+import { identity, isOptedIn } from "./settings";
+
+const OPT_IN_LINE_RE = /^\{\{IF (\w+)\}\}(.*\n?)/gm;
+
+/** A `{{IF key}}` line stays, without its prefix, only when that setting is opted into. */
+function withOptedInLines(template: string): string {
+  return template.replace(OPT_IN_LINE_RE, (_, key: string, line: string) =>
+    isOptedIn(key) ? line : ""
+  );
+}
 
 /** Render AGENTS.md from the template using current state */
 export function buildClaudeMd(): string {
@@ -120,7 +129,7 @@ export function buildClaudeMd(): string {
 
   const id = identity();
 
-  return template
+  return withOptedInLines(template)
     .replaceAll("{{IDENTITY_NAME}}", id.ai.name)
     .replaceAll("{{IDENTITY_DISPLAY}}", id.ai.displayName)
     .replaceAll("{{IDENTITY_CATCHPHRASE}}", id.ai.catchphrase)

package/src/hooks/lib/context.ts

@@ -18,6 +18,7 @@ import { sessionDir } from "./session-dir";
 import * as settings from "./settings";
 import { readFramePrinciples } from "./wisdom";
 import { lastSessionTitle } from "./work-tracking";
+import { loadWorkTreeContext } from "./work-tree-context";
 
 /** Load and concatenate loadAtStartup files */
 function loadStartupFiles(): string {
@@ -223,10 +224,12 @@ export function buildSystemReminder(
     !opts.withoutHandoff && settings.isEnabled("handoff")
       ? loadHandoffContext(sessionDir())
       : "";
+  const workTree = loadWorkTreeContext(sessionDir());
   const dueNudges = opts.agent === "cursor" ? dueNudgeSections() : [];
   const parts: string[] = [];
   if (startup) parts.push(startup);
   if (handoff) parts.push(handoff);
+  if (workTree) parts.push(workTree);
   parts.push(...dueNudges);
   if (selfModel) parts.push(selfModel);
   if (wisdom) parts.push(wisdom);

package/src/hooks/lib/work-tree-context.ts

@@ -0,0 +1,25 @@
+/**
+ * Where the work tree enters an agent's context: the block every new or
+ * compacted session starts with, and the line every prompt carries.
+ */
+
+import { reactionTo } from "./interaction-reaction";
+import { sessionDir } from "./session-dir";
+import { isOptedIn } from "./settings";
+import { readTree, scopeOf } from "./work-tree";
+import { renderPromptLine, renderSessionContext } from "./work-tree-render";
+
+export function loadWorkTreeContext(cwd: string = sessionDir()): string {
+  if (!isOptedIn("workTree")) return "";
+  return renderSessionContext(readTree(scopeOf(cwd)));
+}
+
+export function workTreePromptLine(
+  userText: string,
+  cwd: string = sessionDir()
+): string | null {
+  if (!isOptedIn("workTree")) return null;
+  const newTopic = userText !== "" && reactionTo(userText, undefined) === "new-topic";
+  const line = renderPromptLine(readTree(scopeOf(cwd)), newTopic);
+  return line ? `<system-reminder>${line}</system-reminder>` : null;
+}

package/src/hooks/lib/work-tree-gate.ts

@@ -0,0 +1,67 @@
+/**
+ * The end-of-turn check that keeps the work tree true: a turn that produced
+ * something (a commit, a branch, a PR, a published artifact) and recorded
+ * nothing in the tree is sent back once to record it.
+ */
+
+import { callsThisTurn, commandsThisTurn } from "./claim-check";
+import { alreadySentBack, transcriptLines } from "./claim-log";
+import { sessionDir } from "./session-dir";
+import { isOptedIn } from "./settings";
+import type { StopTurnPayload } from "./stop";
+import { readTree, scopeOf } from "./work-tree";
+import { attachGitProgress } from "./work-tree-git";
+import { renderPromptLine } from "./work-tree-render";
+
+const RECORDS_WORK_RE = /\bpal\s+cli\s+work\b/;
+
+const PRODUCERS: { what: string; re: RegExp }[] = [
+  { what: "committed", re: /\bgit\s+commit\b/ },
+  { what: "made a branch", re: /\bgit\s+(?:checkout\s+-b|switch\s+-c|branch\s+(?!-)\S)/ },
+  { what: "opened a PR", re: /\bgh\s+pr\s+create\b/ },
+];
+
+const ARTIFACT_TOOLS: ReadonlySet<string> = new Set(["Artifact"]);
+const NON_PUBLISH_ACTION_RE = /"action":"(?!publish")/;
+
+function producedThisTurn(commands: string[], lines: string[]): string[] {
+  const produced = PRODUCERS.filter((p) => commands.some((c) => p.re.test(c))).map(
+    (p) => p.what
+  );
+  const artifacts = callsThisTurn(lines, ARTIFACT_TOOLS) ?? [];
+  if (artifacts.some((call) => !NON_PUBLISH_ACTION_RE.test(call)))
+    produced.push("published an artifact");
+  return produced;
+}
+
+function sendBackReason(produced: string[], scope: string): string {
+  const where = renderPromptLine(readTree(scope), false) ?? "Work: nothing recorded yet";
+  return [
+    `This turn ${produced.join(", ")} but recorded nothing in the work tree (${where}).`,
+    'Record where the work stands with `pal cli work stopped "…"`, plus `decide` or `attach` where they fit;',
+    'if no node fits, open one first with `pal cli work open "…"` (`--root` for unrelated work).',
+  ].join(" ");
+}
+
+export function workTreeSendBack(
+  payload: StopTurnPayload,
+  lines: string[],
+  cwd: string
+): string | null {
+  if (!isOptedIn("workTree") || !isOptedIn("workTreeGate")) return null;
+  if (alreadySentBack(payload)) return null;
+  const commands = commandsThisTurn(lines);
+  if (commands === null || commands.some((c) => RECORDS_WORK_RE.test(c))) return null;
+  const produced = producedThisTurn(commands, lines);
+  return produced.length > 0 ? sendBackReason(produced, scopeOf(cwd)) : null;
+}
+
+/** The reason to send the turn back with, or null after attaching what git moved. */
+export function stopWorkTree(payload: StopTurnPayload | null): string | null {
+  if (!payload || !isOptedIn("workTree")) return null;
+  const cwd = sessionDir();
+  const sendBack = workTreeSendBack(payload, transcriptLines(payload), cwd);
+  if (sendBack) return sendBack;
+  attachGitProgress(cwd);
+  return null;
+}

package/src/hooks/lib/work-tree-git.ts

@@ -0,0 +1,98 @@
+/**
+ * New commits and branch switches land on the active work-tree node at the end
+ * of a turn, so the tree knows what the work produced without being told.
+ */
+
+import { spawnSync } from "node:child_process";
+import { appendEvent, readTree, scopeOf } from "./work-tree";
+
+const GIT_TIMEOUT_MS = 1000;
+const MAX_COMMITS = 20;
+
+interface GitSnapshot {
+  branch: string;
+  head: string;
+  email: string;
+}
+
+interface Commit {
+  sha: string;
+  subject: string;
+}
+
+function git(cwd: string, ...args: string[]): string | null {
+  const result = spawnSync("git", ["-C", cwd, ...args], {
+    encoding: "utf-8",
+    timeout: GIT_TIMEOUT_MS,
+  });
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+function snapshot(cwd: string): GitSnapshot | null {
+  const head = git(cwd, "rev-parse", "HEAD");
+  const branch = git(cwd, "rev-parse", "--abbrev-ref", "HEAD");
+  if (!head || !branch) return null;
+  return { head, branch, email: git(cwd, "config", "user.email") ?? "" };
+}
+
+/** Only the user's own commits: a pull brings other people's work, which this turn did not make. */
+function ownCommitsSince(cwd: string, from: string, to: string, email: string): Commit[] {
+  const log = git(
+    cwd,
+    "log",
+    `-${MAX_COMMITS}`,
+    "--format=%h%x09%ae%x09%s",
+    `${from}..${to}`
+  );
+  if (!log) return [];
+  return log
+    .split("\n")
+    .map((line) => line.split("\t"))
+    .filter(([, author]) => author === email)
+    .map(([sha, , subject]) => ({ sha, subject }))
+    .reverse();
+}
+
+/** A scope with no work yet is left alone, so visiting a repo writes nothing. */
+export function attachGitProgress(
+  cwd: string,
+  file?: string,
+  now: Date = new Date()
+): void {
+  const scope = scopeOf(cwd);
+  const tree = readTree(scope, file);
+  if (tree.nodes.size === 0) return;
+  const current = snapshot(cwd);
+  if (!current) return;
+  const cursor = tree.gitCursor;
+  if (cursor?.head === current.head && cursor.branch === current.branch) return;
+
+  if (cursor && tree.active) {
+    if (cursor.branch !== current.branch)
+      appendEvent(
+        scope,
+        tree.active,
+        "attach",
+        { kind: "branch", ref: current.branch },
+        file,
+        now
+      );
+    for (const commit of ownCommitsSince(cwd, cursor.head, current.head, current.email))
+      appendEvent(
+        scope,
+        tree.active,
+        "attach",
+        { kind: "commit", ref: commit.sha, label: commit.subject },
+        file,
+        now
+      );
+  }
+  appendEvent(
+    scope,
+    "",
+    "git-cursor",
+    { branch: current.branch, head: current.head },
+    file,
+    now
+  );
+}

package/src/hooks/lib/work-tree-render.ts

@@ -0,0 +1,157 @@
+/**
+ * How the work tree reads as text: the CLI's views, the block a new or
+ * compacted session starts with, and the one line every prompt carries.
+ */
+
+import { activePath, nodesWithStatus, type ScopeTree, type WorkNode } from "./work-tree";
+
+const SESSION_BUDGET = 2_000;
+const RECENT_DECISIONS = 3;
+const LISTED_PARKED = 5;
+const PROMPT_LINE_MAX = 300;
+
+const RECORD_HINT =
+  "Record as you go: pal cli work stopped|decide|attach|follow-up|open|done (pal cli work --help)";
+
+export function suffix(
+  lead: string,
+  value: string | null | undefined,
+  tail = ""
+): string {
+  return value ? `${lead}${value}${tail}` : "";
+}
+
+function clip(text: string, max: number): string {
+  return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+
+function label(node: WorkNode): string {
+  return `${node.title} [${node.id}]`;
+}
+
+function stoppedClause(node: WorkNode): string {
+  return node.stoppedAt
+    ? ` — stopped at: ${node.stoppedAt}`
+    : " — no stopped-at recorded";
+}
+
+function due(followUp: { due?: string }): string {
+  return followUp.due ? ` (due ${followUp.due.slice(0, 10)})` : "";
+}
+
+export function renderNodeDetail(tree: ScopeTree, node: WorkNode): string {
+  const path = activePath({ ...tree, active: node.id })
+    .map((n) => n.title)
+    .join(" › ");
+  const lines = [
+    `${label(node)} — ${node.status}`,
+    `Path: ${path}`,
+    `Stopped at: ${node.stoppedAt ?? "(not recorded)"}`,
+  ];
+  if (node.waitingOn) lines.push(`Waiting on: ${node.waitingOn}`);
+  if (node.summary) lines.push(`Summary: ${node.summary}`);
+  if (node.links.isc !== undefined) lines.push(`ISC: ${node.links.isc}`);
+  if (node.links.commitment) lines.push(`Commitment: ${node.links.commitment}`);
+  const section = (title: string, rows: string[]) => {
+    if (rows.length) lines.push(`${title}:`, ...rows.map((r) => `  - ${r}`));
+  };
+  section(
+    "Decisions",
+    node.decisions.map(
+      (d) => `${d.ts.slice(0, 10)} ${d.text}${suffix(" (why: ", d.why, ")")}`
+    )
+  );
+  section(
+    "Artifacts",
+    node.artifacts.map((a) => `${a.kind} ${a.ref}${suffix(" — ", a.label)}`)
+  );
+  section(
+    "Follow-ups",
+    node.followUps.map((f) => `${f.text}${due(f)}`)
+  );
+  return lines.join("\n");
+}
+
+function childrenOf(tree: ScopeTree, parent: string | null): WorkNode[] {
+  return [...tree.nodes.values()]
+    .filter(
+      (n) => n.parent === parent || (parent === null && !tree.nodes.has(n.parent ?? ""))
+    )
+    .sort((a, b) => a.opened.localeCompare(b.opened));
+}
+
+const MARK: Record<WorkNode["status"], string> = {
+  active: "▶",
+  parked: "‖",
+  waiting: "?",
+  done: "✓",
+};
+
+export function renderTreeList(tree: ScopeTree, includeDone: boolean): string {
+  const lines: string[] = [];
+  const walk = (node: WorkNode, depth: number) => {
+    if (node.status === "done" && !includeDone) return;
+    const stop = node.status === "done" ? "" : stoppedClause(node);
+    lines.push(`${"  ".repeat(depth)}${MARK[node.status]} ${label(node)}${stop}`);
+    for (const child of childrenOf(tree, node.id)) walk(child, depth + 1);
+  };
+  for (const root of childrenOf(tree, null)) walk(root, 0);
+  return lines.length ? lines.join("\n") : `No work recorded for ${tree.scope} yet.`;
+}
+
+function activeSection(tree: ScopeTree): string[] {
+  const path = activePath(tree);
+  const active = path.at(-1);
+  if (!active) return ["Active: none — enter a parked node or open one."];
+  const lines = [`Active: ${label(active)}${stoppedClause(active)}`];
+  if (path.length > 1) lines.push(`  Inside: ${path.map((n) => n.title).join(" › ")}`);
+  for (const d of active.decisions.slice(-RECENT_DECISIONS))
+    lines.push(`  Decided ${d.ts.slice(0, 10)}: ${d.text}`);
+  return lines;
+}
+
+function listSection(title: string, rows: string[]): string[] {
+  return rows.length ? [title, ...rows.map((r) => `- ${r}`)] : [];
+}
+
+/** What a new or compacted session needs to pick the work back up without digging. */
+export function renderSessionContext(tree: ScopeTree): string {
+  if (tree.nodes.size === 0) return "";
+  const nodes = [...tree.nodes.values()];
+  const open = nodes.filter((n) => n.status !== "done");
+  const lines = [
+    `## Work tree — ${tree.scope}`,
+    ...activeSection(tree),
+    ...listSection(
+      "Waiting on the user:",
+      nodesWithStatus(tree, "waiting").map((n) => `${label(n)}: ${n.waitingOn}`)
+    ),
+    ...listSection(
+      "Parked:",
+      nodesWithStatus(tree, "parked")
+        .slice(0, LISTED_PARKED)
+        .map((n) => `${label(n)}${stoppedClause(n)}`)
+    ),
+    ...listSection(
+      "Follow-ups:",
+      open.flatMap((n) => n.followUps.map((f) => `${f.text}${due(f)} — on ${n.title}`))
+    ),
+    RECORD_HINT,
+  ];
+  return clip(lines.join("\n"), SESSION_BUDGET);
+}
+
+const NEW_TOPIC_HINT =
+  'New topic: if this is separate work, park the active node with its stopped-at (pal cli work park --stopped "…") and open one for this (pal cli work open "…").';
+
+/** The line every prompt carries, so the active node survives anything that drops context. */
+export function renderPromptLine(tree: ScopeTree, newTopic: boolean): string | null {
+  if (tree.nodes.size === 0) return null;
+  const active = tree.active ? tree.nodes.get(tree.active) : undefined;
+  const parked = nodesWithStatus(tree, "parked").length;
+  const head = active
+    ? `Work: ${label(active)}${stoppedClause(active)}`
+    : "Work: no active node";
+  const line = clip(`${head} · ${parked} parked`, PROMPT_LINE_MAX);
+  return newTopic ? `${line}\n${NEW_TOPIC_HINT}` : line;
+}

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

@@ -0,0 +1,307 @@
+/**
+ * The work tree: what the user is working on, what is parked and where each
+ * piece of work stopped, kept as an append-only event log so a compaction, a
+ * new session or a detour never loses it. The tree is derived on every read;
+ * nothing but the events is stored.
+ */
+
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ensureDir, paths } from "./paths";
+import { readAllProjects, resolveProjectFromCwd } from "./projects";
+
+export type NodeStatus = "active" | "parked" | "waiting" | "done";
+
+export type ArtifactKind =
+  | "commit"
+  | "branch"
+  | "pr"
+  | "artifact"
+  | "file"
+  | "run"
+  | "link";
+
+export const ARTIFACT_KINDS: readonly ArtifactKind[] = [
+  "commit",
+  "branch",
+  "pr",
+  "artifact",
+  "file",
+  "run",
+  "link",
+];
+
+interface NodeLinks {
+  isc?: number;
+  commitment?: string;
+}
+
+interface EventBase {
+  id: string;
+  ts: string;
+  scope: string;
+  node: string;
+}
+
+export type WorkEvent = EventBase &
+  (
+    | { type: "open"; title: string; parent: string | null; links?: NodeLinks }
+    | { type: "enter" }
+    | { type: "park"; stoppedAt?: string }
+    | { type: "wait"; on: string }
+    | { type: "done"; summary?: string }
+    | { type: "stopped"; text: string }
+    | { type: "decide"; text: string; why?: string }
+    | { type: "attach"; kind: ArtifactKind; ref: string; label?: string }
+    | { type: "follow-up"; text: string; due?: string }
+    | { type: "git-cursor"; branch: string; head: string }
+  );
+
+type Payload<T extends WorkEvent["type"]> = Omit<
+  Extract<WorkEvent, { type: T }>,
+  keyof EventBase | "type"
+>;
+
+interface Decision {
+  ts: string;
+  text: string;
+  why?: string;
+}
+
+interface Artifact {
+  ts: string;
+  kind: ArtifactKind;
+  ref: string;
+  label?: string;
+}
+
+interface FollowUp {
+  ts: string;
+  text: string;
+  due?: string;
+}
+
+export interface WorkNode {
+  id: string;
+  title: string;
+  parent: string | null;
+  status: NodeStatus;
+  stoppedAt: string | null;
+  waitingOn: string | null;
+  summary: string | null;
+  decisions: Decision[];
+  artifacts: Artifact[];
+  followUps: FollowUp[];
+  links: NodeLinks;
+  opened: string;
+  updated: string;
+}
+
+interface GitCursor {
+  branch: string;
+  head: string;
+}
+
+export interface ScopeTree {
+  scope: string;
+  active: string | null;
+  nodes: Map<string, WorkNode>;
+  gitCursor: GitCursor | null;
+}
+
+function workTreeFile(): string {
+  return resolve(ensureDir(resolve(paths.memory(), "work-tree")), "events.jsonl");
+}
+
+/** A registered project is its own scope wherever in it the agent stands; anything else is its folder. */
+export function scopeOf(cwd: string): string {
+  return resolveProjectFromCwd(cwd, readAllProjects())?.name ?? resolve(cwd);
+}
+
+export function newNodeId(
+  now: number = Date.now(),
+  random: () => number = Math.random
+): string {
+  return now.toString(36).slice(-5) + random().toString(36).slice(2, 5);
+}
+
+function parseLine(line: string): WorkEvent[] {
+  try {
+    return [JSON.parse(line) as WorkEvent];
+  } catch {
+    return [];
+  }
+}
+
+/** Ordered by time, so the union an import merges in replays the same as one machine's log. */
+export function readEvents(file: string = workTreeFile()): WorkEvent[] {
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf-8")
+    .split("\n")
+    .filter((line) => line.trim())
+    .flatMap(parseLine)
+    .sort((a, b) => a.ts.localeCompare(b.ts));
+}
+
+export function appendEvent<T extends WorkEvent["type"]>(
+  scope: string,
+  node: string,
+  type: T,
+  payload: Payload<T>,
+  file: string = workTreeFile(),
+  now: Date = new Date()
+): WorkEvent {
+  const event = {
+    id: newNodeId(now.getTime()),
+    ts: now.toISOString(),
+    scope,
+    node,
+    type,
+    ...payload,
+  } as WorkEvent;
+  appendFileSync(file, `${JSON.stringify(event)}\n`, "utf-8");
+  return event;
+}
+
+function emptyNode(
+  id: string,
+  title: string,
+  parent: string | null,
+  ts: string
+): WorkNode {
+  return {
+    id,
+    title,
+    parent,
+    status: "active",
+    stoppedAt: null,
+    waitingOn: null,
+    summary: null,
+    decisions: [],
+    artifacts: [],
+    followUps: [],
+    links: {},
+    opened: ts,
+    updated: ts,
+  };
+}
+
+function parkActive(tree: ScopeTree): void {
+  const current = tree.active ? tree.nodes.get(tree.active) : undefined;
+  if (current?.status === "active") current.status = "parked";
+  tree.active = null;
+}
+
+function activate(tree: ScopeTree, node: WorkNode): void {
+  if (tree.active !== node.id) parkActive(tree);
+  node.status = "active";
+  node.waitingOn = null;
+  tree.active = node.id;
+}
+
+/** Finishing a detour hands the work back to the nearest unfinished ancestor. */
+function returnToParent(tree: ScopeTree, node: WorkNode): void {
+  let parent = node.parent ? tree.nodes.get(node.parent) : undefined;
+  while (parent && parent.status === "done")
+    parent = parent.parent ? tree.nodes.get(parent.parent) : undefined;
+  if (parent) activate(tree, parent);
+}
+
+function applyToNode(tree: ScopeTree, node: WorkNode, event: WorkEvent): void {
+  switch (event.type) {
+    case "enter":
+      activate(tree, node);
+      break;
+    case "park":
+      if (event.stoppedAt) node.stoppedAt = event.stoppedAt;
+      node.status = "parked";
+      if (tree.active === node.id) tree.active = null;
+      break;
+    case "wait":
+      node.status = "waiting";
+      node.waitingOn = event.on;
+      if (tree.active === node.id) tree.active = null;
+      break;
+    case "done": {
+      const wasActive = tree.active === node.id;
+      node.status = "done";
+      node.summary = event.summary ?? node.summary;
+      if (wasActive) {
+        tree.active = null;
+        returnToParent(tree, node);
+      }
+      break;
+    }
+    case "stopped":
+      node.stoppedAt = event.text;
+      break;
+    case "decide":
+      node.decisions.push({ ts: event.ts, text: event.text, why: event.why });
+      break;
+    case "attach":
+      node.artifacts.push({
+        ts: event.ts,
+        kind: event.kind,
+        ref: event.ref,
+        label: event.label,
+      });
+      break;
+    case "follow-up":
+      node.followUps.push({ ts: event.ts, text: event.text, due: event.due });
+      break;
+  }
+  node.updated = event.ts;
+}
+
+function apply(tree: ScopeTree, event: WorkEvent): void {
+  if (event.type === "git-cursor") {
+    tree.gitCursor = { branch: event.branch, head: event.head };
+    return;
+  }
+  if (event.type === "open") {
+    const node = emptyNode(event.node, event.title, event.parent, event.ts);
+    node.links = event.links ?? {};
+    tree.nodes.set(node.id, node);
+    activate(tree, node);
+    return;
+  }
+  const node = tree.nodes.get(event.node);
+  if (node) applyToNode(tree, node, event);
+}
+
+export function buildTree(scope: string, events: WorkEvent[]): ScopeTree {
+  const tree: ScopeTree = { scope, active: null, nodes: new Map(), gitCursor: null };
+  for (const event of events) if (event.scope === scope) apply(tree, event);
+  return tree;
+}
+
+export function readTree(scope: string, file: string = workTreeFile()): ScopeTree {
+  return buildTree(scope, readEvents(file));
+}
+
+/** From the root down to the active node: the detours the user is inside of. */
+export function activePath(tree: ScopeTree): WorkNode[] {
+  const path: WorkNode[] = [];
+  let node = tree.active ? tree.nodes.get(tree.active) : undefined;
+  while (node) {
+    path.unshift(node);
+    node = node.parent ? tree.nodes.get(node.parent) : undefined;
+  }
+  return path;
+}
+
+function byRecent(a: WorkNode, b: WorkNode): number {
+  return b.updated.localeCompare(a.updated);
+}
+
+export function nodesWithStatus(tree: ScopeTree, status: NodeStatus): WorkNode[] {
+  return [...tree.nodes.values()].filter((n) => n.status === status).sort(byRecent);
+}
+
+/** An id, or any unambiguous prefix of one. */
+export function findNode(tree: ScopeTree, idOrPrefix: string): WorkNode | null {
+  const exact = tree.nodes.get(idOrPrefix);
+  if (exact) return exact;
+  const matches = [...tree.nodes.values()].filter((n) => n.id.startsWith(idOrPrefix));
+  return matches.length === 1 ? matches[0] : null;
+}

package/src/tools/lib/command.ts

@@ -78,7 +78,15 @@ export async function runCommand(
     : runLeaf(command, args, path);
 }
 
+function startsWithFallbackOption(command: Group, args: string[]): boolean {
+  const first = args[0];
+  if (!command.fallback || first === undefined || !first.startsWith("-")) return false;
+  return !HELP_FLAGS.has(first) && !command.aliases?.[first];
+}
+
 async function runGroup(command: Group, args: string[], path: string[]): Promise<number> {
+  if (command.fallback && startsWithFallbackOption(command, args))
+    return runGroup(command, [command.fallback, ...args], path);
   const [first, ...rest] = args;
   const name = first === undefined ? command.fallback : first;
   if (name === undefined || name === "help" || HELP_FLAGS.has(name)) {