@agent-plan/core 0.3.0 → 0.3.1

package/dist/guard-decision.d.ts

@@ -1,24 +1,27 @@
 /**
- * Harness-agnostic decision logic for the "no task in progress" edit guard.
- * Any adapter (Claude Code PreToolUse hook, Pi's advisory guard, a future
- * harness) can feed it a parsed tool-use event plus already-fetched planner
- * state and get back the same decision. This never talks to the plan store
+ * Harness-agnostic logic for the "no task in progress" warning. The guard
+ * never blocks and never asks: every tool call proceeds, and a call that
+ * changes project code while no task is in progress only earns the agent a
+ * warning. Planner operations never need a task. Any adapter (Claude Code
+ * PreToolUse hook, Pi's tool_call handler, a future harness) feeds it a
+ * parsed tool-use event plus already-fetched planner state and gets back the
+ * same warning, or none. This never talks to the plan store
  * or stdin/stdout — callers own that I/O. It does read the filesystem in one
  * narrow way (see {@link canonicalize}): resolving symlinks so a path
  * comparison isn't fooled by one, which is cheap (a handful of stat calls,
  * not a plan load) and safe to call on paths that don't exist yet.
  */
-export type GuardPermissionDecision = "allow" | "ask" | "deny";
 /** The tool-use fields the decision needs, already pulled out of whatever
  * shape the harness's raw event uses (Claude Code's `tool_input.file_path`,
  * Pi's `event.input.path`, etc.). */
 export interface GuardEventInput {
+    /** Tool name in any case: Claude Code's `Edit`/`Bash` and Pi's `edit`/`bash` are the same tool. */
     toolName: string;
     /** Absolute (or resolvable) working directory used to resolve relative paths. */
     cwd: string;
     /** Absolute planner root, e.g. `join(cwd, ".planner")`. */
     plannerRoot: string;
-    /** Edit / Write target path. */
+    /** Edit / Write target path (Pi: `path`). */
     filePath?: string;
     /** NotebookEdit target path. */
     notebookPath?: string;
@@ -31,36 +34,39 @@ export interface GuardStateInput {
     totalTasks: number;
     hasInProgressTask: boolean;
     guardBypassed: boolean;
-    /** Human-readable "start this task" hint, or the generic fallback; empty allowed. */
-    startHint: string;
+    /** The task the warning suggests starting, when there is an obvious one. */
+    focusTask?: {
+        id: string;
+        title: string;
+    };
 }
 export interface GuardClassification {
-    /** Whether this tool call is one the guard evaluates at all. */
+    /** Whether this tool call may write project code, so the guard must look at task state. */
     guarded: boolean;
-    /** Best-effort candidate paths the call would write to (may be empty when unknown). */
+    /** The project paths outside `.planner/` the call would write to; empty when the target is unknown. */
     paths: string[];
 }
-export interface GuardDecision {
-    decision: GuardPermissionDecision;
-    reason?: string;
+export interface NoTaskWarning {
+    /** Text for the agent, present only when it should be warned. */
+    warning?: string;
 }
 /**
  * Whether a Bash command line contains a write-shaped operation: output
  * redirection, `tee`, in-place `sed`/`perl`, a file-creating `cp`/`mv`,
  * `rm`, or a `git` operation that rewrites tracked files. Deliberately
  * over-inclusive: `git`, build/test runners, `ls`, `cat`, `grep`, `find`
- * and friends must stay unmatched, but when in doubt this returns true — the
- * cost of a false positive here is one extra prompt, not a blocked
- * operation, so under-matching (missing a real edit) is the worse failure.
+ * and friends must stay unmatched, but when in doubt this returns true — a
+ * false positive costs one warning to the agent, never a blocked call or a
+ * prompt, so under-matching (missing a real edit) is the worse failure.
  */
 export declare function isWriteShapedBashCommand(command: string): boolean;
 /**
  * Best-effort extraction of the file path(s) a write-shaped Bash segment
- * targets, so a command that only touches `.planner/` can still be
- * recognized and allowed. This cannot see through a heredoc whose target is
- * computed (a variable, command substitution, etc.) rather than written
- * literally in the command line — that case is expected to fall through to
- * the normal in-progress/bypass checks below, not to be silently allowed.
+ * targets, so a command that only touches `.planner/` or files outside the
+ * project earns no warning. This cannot see through a heredoc whose target
+ * is computed (a variable, command substitution, etc.) rather than written
+ * literally in the command line — that case still reaches the in-progress /
+ * bypass checks and can warn, rather than being silently treated as safe.
  *
  * A wider gap of the same kind: a command that writes through an
  * interpreter (`python3 - <<PY` then `open(path, "w")`, `node -e`, a script
@@ -87,32 +93,36 @@ export declare function isWriteShapedBashCommand(command: string): boolean;
 export declare function extractBashWriteTargets(command: string): string[];
 /** Whether `candidate` resolves to a path inside `plannerRoot` (or is it exactly). */
 export declare function isPathInsidePlannerRoot(candidate: string, plannerRoot: string, cwd: string): boolean;
-/** True only when every candidate path is inside the planner root, and there
- * is at least one candidate — an empty/unknown path list must never count as
- * "inside", or an unresolvable target would be silently allowed. Exported so
- * a hook harness can use the exact same check for its cheap early-allow path
- * without duplicating the rule. */
-export declare function isEntirelyInsidePlannerRoot(paths: string[], plannerRoot: string, cwd: string): boolean;
+/** Whether writing `candidate` changes the project's code: it is inside the
+ * project (the directory that owns `.planner/`) and not inside `.planner/`.
+ * `/dev/null`, `~/.claude/...`, temp dirs and other repositories are not. */
+export declare function isProjectCodePath(candidate: string, plannerRoot: string, cwd: string): boolean;
 /**
- * Which tool calls the guard covers, and what path(s) they would write to.
- * Everything else (Read, Grep, WebFetch, MCP tools, read-only Bash, ...) is
- * unguarded and returns `{ guarded: false }` without touching the planner
- * store.
+ * Whether a tool call may change the project's code, and so needs the guard
+ * to look at task state. This is the one place that rule lives; the hook's
+ * cheap early exit and {@link noTaskWarning} both read `guarded`.
+ *
+ * - Tools that never write (Read, Grep, MCP tools, read-only Bash, ...) are
+ *   not guarded.
+ * - A write whose targets are all known and none is project code (inside
+ *   `.planner/`, `/dev/null`, `~/.claude/...`, a temp dir, another repo) is
+ *   not guarded: updating the planner or the user's own config never needs a
+ *   task.
+ * - A write with at least one project-code target is guarded, with `paths`
+ *   narrowed to those targets.
+ * - A write whose target is unknown (a computed heredoc, an Edit with no
+ *   path) is guarded with empty `paths` — never silently allowed.
  */
 export declare function classifyGuardedTool(event: GuardEventInput): GuardClassification;
 /**
- * The full "no task in progress" guard decision, as a pure function: given a
- * parsed tool-use event and planner state the caller already fetched, decide
- * allow or ask (deny is part of the type for a future genuinely-deny case,
- * but nothing here returns it today). No stdin/stdout and no plan-store
- * calls — the hook harness (or a Pi equivalent) does the reading and
- * printing around this; the only filesystem access is the cheap symlink
- * canonicalization in {@link isPathInsidePlannerRoot}.
+ * The warning for a tool call that changes project code while no task is in
+ * progress, or none. Never a block or a prompt: the adapter lets the call
+ * proceed either way and only passes the text to the agent. Pure apart from
+ * the cheap symlink canonicalization in {@link isPathInsidePlannerRoot}.
  *
- * Order matters and mirrors the cost of finding out: anything the guard
- * doesn't cover, and anything that resolves entirely inside the planner
- * root, is decided from the event alone (no planner state needed). Only a
- * real candidate for blocking reaches the state-based checks.
+ * Order mirrors the cost of finding out: anything that cannot change project
+ * code (see {@link classifyGuardedTool}) is settled from the event alone, so
+ * adapters can skip loading the plan for it.
  */
-export declare function decideGuardPreToolUse(event: GuardEventInput, state: GuardStateInput): GuardDecision;
+export declare function noTaskWarning(event: GuardEventInput, state: GuardStateInput): NoTaskWarning;
 //# sourceMappingURL=guard-decision.d.ts.map

package/dist/guard-decision.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guard-decision.d.ts","sourceRoot":"","sources":["../src/guard-decision.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAE/D;;qCAEqC;AACrC,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,OAAO,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,aAAa,EAAE,OAAO,CAAC;IACvB,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,OAAO,EAAE,OAAO,CAAC;IACjB,uFAAuF;IACvF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,uBAAuB,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAsCD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAGjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CA2BjE;AAsBD,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAKpG;AAED;;;;mCAImC;AACnC,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEtG;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,mBAAmB,CAa/E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,GAAG,aAAa,CAkBnG"}
+{"version":3,"file":"guard-decision.d.ts","sourceRoot":"","sources":["../src/guard-decision.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH;;qCAEqC;AACrC,MAAM,WAAW,eAAe;IAC9B,mGAAmG;IACnG,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,OAAO,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,aAAa,EAAE,OAAO,CAAC;IACvB,4EAA4E;IAC5E,SAAS,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED,MAAM,WAAW,mBAAmB;IAClC,2FAA2F;IAC3F,OAAO,EAAE,OAAO,CAAC;IACjB,uGAAuG;IACvG,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAiFD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAGjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CA2BjE;AAuCD,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpG;AAED;;6EAE6E;AAC7E,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAE9F;AAoBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,mBAAmB,CAM/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,GAAG,aAAa,CAa3F"}

package/dist/guard-decision.js

@@ -1,6 +1,7 @@
 import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
-const GUARDED_FILE_TOOLS = new Set(["Edit", "Write"]);
+const FILE_WRITE_TOOLS = new Set(["edit", "write"]);
 /** Strip fd-duplication idioms (`2>&1`, `>&2`, `1>&2`) before segmenting or
  * matching — they duplicate a stream, not a file, are extremely common in
  * otherwise read-only commands, and their bare `&` would otherwise be
@@ -8,11 +9,53 @@ const GUARDED_FILE_TOOLS = new Set(["Edit", "Write"]);
 function stripFdDuplication(command) {
     return command.replace(/\d*>&\d+/g, " ");
 }
+/** Blank out shell operators (`>`, `<`, `|`, `;`, `&`, newlines) that sit
+ * inside single or double quotes. They are literal text there — a commit
+ * message's `<name@example.com>`, a `grep "a|b"` pattern — not redirects or
+ * separators. Quoted paths keep their characters, so `> "/tmp/x"` still
+ * reads as a redirect to `/tmp/x`. */
+function maskQuotedOperators(command) {
+    let out = "";
+    let quote = null;
+    for (let i = 0; i < command.length; i += 1) {
+        const ch = command[i];
+        if (quote === null) {
+            if (ch === "\\") {
+                out += ch + (command[i + 1] ?? "");
+                i += 1;
+                continue;
+            }
+            if (ch === "'" || ch === '"')
+                quote = ch;
+            out += ch;
+            continue;
+        }
+        if (quote === '"' && ch === "\\") {
+            out += "__";
+            i += 1;
+            continue;
+        }
+        if (ch === quote) {
+            quote = null;
+            out += ch;
+            continue;
+        }
+        out += /[<>|;&\n]/.test(ch) ? "_" : ch;
+    }
+    return out;
+}
+/** The command line as write-detection reads it: quoted operators masked,
+ * then fd-duplication removed. Both detection and target extraction use
+ * this, so they always see the same text. */
+function normalizeBashCommand(command) {
+    return stripFdDuplication(maskQuotedOperators(command));
+}
 /** Split a Bash command line into pipe/list segments so write-detection on
  * one segment (e.g. `sed -i` on the left of a pipe) doesn't get confused by
  * an unrelated flag on the other side (e.g. `grep -i` on the right). Best
- * effort only — quoting and nested subshells are not fully parsed. Callers
- * must strip fd-duplication first, or a bare `2>&1` splits on its `&`. */
+ * effort only — nested subshells are not parsed. Callers must pass the
+ * command through {@link normalizeBashCommand} first, or a bare `2>&1`
+ * splits on its `&` and a quoted `|` splits a string in two. */
 function bashSegments(command) {
     return command
         .split(/(?:&&|\|\||[;&|\n])+/)
@@ -42,22 +85,22 @@ function isWriteShapedBashSegment(segment) {
  * redirection, `tee`, in-place `sed`/`perl`, a file-creating `cp`/`mv`,
  * `rm`, or a `git` operation that rewrites tracked files. Deliberately
  * over-inclusive: `git`, build/test runners, `ls`, `cat`, `grep`, `find`
- * and friends must stay unmatched, but when in doubt this returns true — the
- * cost of a false positive here is one extra prompt, not a blocked
- * operation, so under-matching (missing a real edit) is the worse failure.
+ * and friends must stay unmatched, but when in doubt this returns true — a
+ * false positive costs one warning to the agent, never a blocked call or a
+ * prompt, so under-matching (missing a real edit) is the worse failure.
  */
 export function isWriteShapedBashCommand(command) {
     if (!command || !command.trim())
         return false;
-    return bashSegments(stripFdDuplication(command)).some(isWriteShapedBashSegment);
+    return bashSegments(normalizeBashCommand(command)).some(isWriteShapedBashSegment);
 }
 /**
  * Best-effort extraction of the file path(s) a write-shaped Bash segment
- * targets, so a command that only touches `.planner/` can still be
- * recognized and allowed. This cannot see through a heredoc whose target is
- * computed (a variable, command substitution, etc.) rather than written
- * literally in the command line — that case is expected to fall through to
- * the normal in-progress/bypass checks below, not to be silently allowed.
+ * targets, so a command that only touches `.planner/` or files outside the
+ * project earns no warning. This cannot see through a heredoc whose target
+ * is computed (a variable, command substitution, etc.) rather than written
+ * literally in the command line — that case still reaches the in-progress /
+ * bypass checks and can warn, rather than being silently treated as safe.
  *
  * A wider gap of the same kind: a command that writes through an
  * interpreter (`python3 - <<PY` then `open(path, "w")`, `node -e`, a script
@@ -83,7 +126,7 @@ export function isWriteShapedBashCommand(command) {
  */
 export function extractBashWriteTargets(command) {
     const targets = [];
-    for (const segment of bashSegments(stripFdDuplication(command))) {
+    for (const segment of bashSegments(normalizeBashCommand(command))) {
         const redirect = segment.match(/>{1,2}\s*([^\s;&|>]+)/);
         if (redirect?.[1])
             targets.push(redirect[1]);
@@ -130,74 +173,97 @@ function canonicalize(path) {
         return join(canonicalize(parent), basename(path));
     }
 }
-/** Whether `candidate` resolves to a path inside `plannerRoot` (or is it exactly). */
-export function isPathInsidePlannerRoot(candidate, plannerRoot, cwd) {
-    const resolvedRoot = canonicalize(resolve(plannerRoot));
-    const resolvedCandidate = canonicalize(resolve(cwd, candidate));
+/** Turn a path as written in a command line into one `resolve` understands:
+ * drop surrounding quotes and expand a leading `~` or `$HOME`. Anything else
+ * the shell would expand (other variables, command substitution) is left
+ * as-is, so it resolves inside the project and the agent is still warned. */
+function shellPathToFsPath(candidate) {
+    const unquoted = candidate.replace(/^['"]|['"]$/g, "");
+    return unquoted.replace(/^(?:~|\$HOME|\$\{HOME\})(?=\/|$)/, homedir());
+}
+/** Whether `candidate` resolves to `root` itself or a path inside it. */
+function isPathInside(candidate, root, cwd) {
+    const resolvedRoot = canonicalize(resolve(root));
+    const resolvedCandidate = canonicalize(resolve(cwd, shellPathToFsPath(candidate)));
     const rel = relative(resolvedRoot, resolvedCandidate);
     return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
-/** True only when every candidate path is inside the planner root, and there
- * is at least one candidate — an empty/unknown path list must never count as
- * "inside", or an unresolvable target would be silently allowed. Exported so
- * a hook harness can use the exact same check for its cheap early-allow path
- * without duplicating the rule. */
-export function isEntirelyInsidePlannerRoot(paths, plannerRoot, cwd) {
-    return paths.length > 0 && paths.every((path) => isPathInsidePlannerRoot(path, plannerRoot, cwd));
+/** Whether `candidate` resolves to a path inside `plannerRoot` (or is it exactly). */
+export function isPathInsidePlannerRoot(candidate, plannerRoot, cwd) {
+    return isPathInside(candidate, plannerRoot, cwd);
 }
-/**
- * Which tool calls the guard covers, and what path(s) they would write to.
- * Everything else (Read, Grep, WebFetch, MCP tools, read-only Bash, ...) is
- * unguarded and returns `{ guarded: false }` without touching the planner
- * store.
- */
-export function classifyGuardedTool(event) {
-    if (GUARDED_FILE_TOOLS.has(event.toolName)) {
-        return { guarded: true, paths: event.filePath ? [event.filePath] : [] };
+/** Whether writing `candidate` changes the project's code: it is inside the
+ * project (the directory that owns `.planner/`) and not inside `.planner/`.
+ * `/dev/null`, `~/.claude/...`, temp dirs and other repositories are not. */
+export function isProjectCodePath(candidate, plannerRoot, cwd) {
+    return isPathInside(candidate, dirname(plannerRoot), cwd) && !isPathInside(candidate, plannerRoot, cwd);
+}
+/** Which paths a covered tool call would write to, before any filtering;
+ * empty when the target cannot be read from the event. */
+function rawWriteTargets(event) {
+    const tool = event.toolName.toLowerCase();
+    if (FILE_WRITE_TOOLS.has(tool)) {
+        return { covered: true, paths: event.filePath ? [event.filePath] : [] };
     }
-    if (event.toolName === "NotebookEdit") {
-        return { guarded: true, paths: event.notebookPath ? [event.notebookPath] : [] };
+    if (tool === "notebookedit") {
+        return { covered: true, paths: event.notebookPath ? [event.notebookPath] : [] };
     }
-    if (event.toolName === "Bash") {
+    if (tool === "bash") {
         const command = event.command ?? "";
         if (!isWriteShapedBashCommand(command))
-            return { guarded: false, paths: [] };
-        return { guarded: true, paths: extractBashWriteTargets(command) };
+            return { covered: false, paths: [] };
+        return { covered: true, paths: extractBashWriteTargets(command) };
     }
-    return { guarded: false, paths: [] };
+    return { covered: false, paths: [] };
+}
+/**
+ * Whether a tool call may change the project's code, and so needs the guard
+ * to look at task state. This is the one place that rule lives; the hook's
+ * cheap early exit and {@link noTaskWarning} both read `guarded`.
+ *
+ * - Tools that never write (Read, Grep, MCP tools, read-only Bash, ...) are
+ *   not guarded.
+ * - A write whose targets are all known and none is project code (inside
+ *   `.planner/`, `/dev/null`, `~/.claude/...`, a temp dir, another repo) is
+ *   not guarded: updating the planner or the user's own config never needs a
+ *   task.
+ * - A write with at least one project-code target is guarded, with `paths`
+ *   narrowed to those targets.
+ * - A write whose target is unknown (a computed heredoc, an Edit with no
+ *   path) is guarded with empty `paths` — never silently allowed.
+ */
+export function classifyGuardedTool(event) {
+    const { covered, paths } = rawWriteTargets(event);
+    if (!covered)
+        return { guarded: false, paths: [] };
+    if (paths.length === 0)
+        return { guarded: true, paths: [] };
+    const projectPaths = paths.filter((path) => isProjectCodePath(path, event.plannerRoot, event.cwd));
+    return { guarded: projectPaths.length > 0, paths: projectPaths };
 }
 /**
- * The full "no task in progress" guard decision, as a pure function: given a
- * parsed tool-use event and planner state the caller already fetched, decide
- * allow or ask (deny is part of the type for a future genuinely-deny case,
- * but nothing here returns it today). No stdin/stdout and no plan-store
- * calls — the hook harness (or a Pi equivalent) does the reading and
- * printing around this; the only filesystem access is the cheap symlink
- * canonicalization in {@link isPathInsidePlannerRoot}.
+ * The warning for a tool call that changes project code while no task is in
+ * progress, or none. Never a block or a prompt: the adapter lets the call
+ * proceed either way and only passes the text to the agent. Pure apart from
+ * the cheap symlink canonicalization in {@link isPathInsidePlannerRoot}.
  *
- * Order matters and mirrors the cost of finding out: anything the guard
- * doesn't cover, and anything that resolves entirely inside the planner
- * root, is decided from the event alone (no planner state needed). Only a
- * real candidate for blocking reaches the state-based checks.
+ * Order mirrors the cost of finding out: anything that cannot change project
+ * code (see {@link classifyGuardedTool}) is settled from the event alone, so
+ * adapters can skip loading the plan for it.
  */
-export function decideGuardPreToolUse(event, state) {
+export function noTaskWarning(event, state) {
     const classification = classifyGuardedTool(event);
     if (!classification.guarded)
-        return { decision: "allow" };
-    // Writing a handoff or recording task state is how an agent reports what
-    // it did, and it is most needed exactly when no task is in progress. Never
-    // block or ask for anything inside .planner/, regardless of task state.
-    if (isEntirelyInsidePlannerRoot(classification.paths, event.plannerRoot, event.cwd)) {
-        return { decision: "allow" };
-    }
-    if (!state.hasPlannerDir)
-        return { decision: "allow" };
-    if (state.totalTasks === 0)
-        return { decision: "allow" };
-    if (state.hasInProgressTask)
-        return { decision: "allow" };
-    if (state.guardBypassed)
-        return { decision: "allow" };
-    const reason = `Agent Plan guard: no task is in-progress, and this ${event.toolName} touches a file outside .planner/.${state.startHint} Or authorize a temporary bypass so this and further edits this session don't ask again (run /planner bypass, or call planner-authorize-bypass) — same bypass window an in-progress task already skips.`;
-    return { decision: "ask", reason };
+        return {};
+    if (!state.hasPlannerDir || state.totalTasks === 0)
+        return {};
+    if (state.hasInProgressTask || state.guardBypassed)
+        return {};
+    const target = classification.paths.length > 0 ? classification.paths.join(", ") : "a project file";
+    const start = state.focusTask
+        ? `start the task that covers it (/planner task start ${state.focusTask.id} — ${state.focusTask.title}, or another one)`
+        : "start the task that covers it (/planner task start <task>)";
+    return {
+        warning: `Agent Plan: no task is in progress, and this call changes project code (${target}). It was not blocked. If this is planned work, ${start} so the plan stays accurate. Planner changes never need a task.`,
+    };
 }

package/dist/guard-state.d.ts

@@ -0,0 +1,14 @@
+import type { PlanStore } from "./plan-store.js";
+import type { GuardStateInput } from "./guard-decision.js";
+export interface NoTaskGuardState extends GuardStateInput {
+    inProgressTaskIds: string[];
+}
+/**
+ * Read the planner state the no-task warning needs, once, for any adapter.
+ * The suggested task is the one the plan is already pointing at: the
+ * resume file's in-progress task, then an open task in the current phase,
+ * then a paused task, then the first open task. Never throws for a missing
+ * planner; it reports `hasPlannerDir: false` instead.
+ */
+export declare function loadNoTaskGuardState(st: PlanStore): Promise<NoTaskGuardState>;
+//# sourceMappingURL=guard-state.d.ts.map

package/dist/guard-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-state.d.ts","sourceRoot":"","sources":["../src/guard-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAID;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA4BnF"}

package/dist/guard-state.js

@@ -0,0 +1,35 @@
+const CLOSED_STATUSES = new Set(["done", "canceled", "rejected"]);
+/**
+ * Read the planner state the no-task warning needs, once, for any adapter.
+ * The suggested task is the one the plan is already pointing at: the
+ * resume file's in-progress task, then an open task in the current phase,
+ * then a paused task, then the first open task. Never throws for a missing
+ * planner; it reports `hasPlannerDir: false` instead.
+ */
+export async function loadNoTaskGuardState(st) {
+    const hasPlannerDir = await st.exists().catch(() => false);
+    if (!hasPlannerDir) {
+        return { hasPlannerDir, totalTasks: 0, hasInProgressTask: false, inProgressTaskIds: [], guardBypassed: false };
+    }
+    const [workspace, resume, guardBypassed] = await Promise.all([
+        st.loadAll(),
+        st.loadResume().catch(() => null),
+        st.isGuardBypassed().catch(() => false),
+    ]);
+    const allTasks = workspace.phases.flatMap((phase) => phase.tasks.map((task) => ({ phase, task })));
+    const inProgressTaskIds = allTasks.filter(({ task }) => task.status === "in-progress").map(({ task }) => task.id);
+    const isOpen = (status) => !CLOSED_STATUSES.has(status);
+    const focus = (resume?.inProgressTaskIds?.[0] ? allTasks.find(({ task }) => task.id === resume.inProgressTaskIds[0]) : undefined)
+        ?? (resume?.currentPhaseId ? allTasks.find(({ phase, task }) => phase.id === resume.currentPhaseId && isOpen(task.status)) : undefined)
+        ?? allTasks.find(({ task }) => task.pauseSnapshot)
+        ?? allTasks.find(({ task }) => task.status === "planned" || task.status === "blocked" || task.status === "waiting")
+        ?? allTasks.find(({ task }) => isOpen(task.status));
+    return {
+        hasPlannerDir,
+        totalTasks: allTasks.length,
+        hasInProgressTask: inProgressTaskIds.length > 0,
+        inProgressTaskIds,
+        guardBypassed,
+        ...(focus ? { focusTask: { id: focus.task.id, title: focus.task.title } } : {}),
+    };
+}

package/dist/handoff-reply.d.ts

@@ -11,6 +11,11 @@
  * per-field comments) rather than by a single blanket rule — see AGENTS.md
  * rule 4: this placement decision belongs in the core exactly once, not
  * once per adapter.
+ *
+ * Transport note: Claude Code shows the agent only structuredContent when a
+ * result has one, so the MCP server folds `text` into the structured part
+ * for every tool (foldTextIntoStructured in plan-mcp). The rule above still
+ * holds for what these builders return; the fold is the MCP transport's job.
  */
 import type { HandoffCompletenessAudit, Phase } from "./schema.js";
 import type { PhaseWorkMap } from "./task-context.js";

package/dist/handoff-reply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handoff-reply.d.ts","sourceRoot":"","sources":["../src/handoff-reply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,wBAAwB,EAA6B,KAAK,EAAE,MAAM,aAAa,CAAC;AAC9F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAGL,KAAK,oBAAoB,EAEzB,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,oBAAoB,EAAE,MAAM,GAAE,SAAS,GAAG,aAAyB,GAAG,aAAa,CAMrI;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;oBAMoB;AACpB,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,CAKjF;AA8CD;6CAC6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAmCD,MAAM,MAAM,qBAAqB,GAC7B;IACE,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC/C,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC/C,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,YAAY,EAAE,YAAY,CAAC;CAC5B,CAAC;AAEN;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,qBAAqB,GAAG,YAAY,CAsEhF;AAED;wDACwD;AACxD,eAAO,MAAM,iCAAiC,0IAC2F,CAAC;AAE1I,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,iBAAiB,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,wBAAwB,GAAG,YAAY,CAkFtF"}
+{"version":3,"file":"handoff-reply.d.ts","sourceRoot":"","sources":["../src/handoff-reply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,wBAAwB,EAA6B,KAAK,EAAE,MAAM,aAAa,CAAC;AAC9F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAGL,KAAK,oBAAoB,EAEzB,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,oBAAoB,EAAE,MAAM,GAAE,SAAS,GAAG,aAAyB,GAAG,aAAa,CAMrI;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;oBAMoB;AACpB,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,CAKjF;AA8CD;6CAC6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAmCD,MAAM,MAAM,qBAAqB,GAC7B;IACE,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC/C,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC/C,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,YAAY,EAAE,YAAY,CAAC;CAC5B,CAAC;AAEN;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,qBAAqB,GAAG,YAAY,CAsEhF;AAED;wDACwD;AACxD,eAAO,MAAM,iCAAiC,0IAC2F,CAAC;AAE1I,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,iBAAiB,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,wBAAwB,GAAG,YAAY,CAkFtF"}

package/dist/index.d.ts

@@ -27,11 +27,14 @@ export * from "./feature-delete.js";
 export * from "./accepted-decision-guard.js";
 export * from "./project-context-migration.js";
 export * from "./project-context.js";
+export * from "./load-reply.js";
+export * from "./on-hold.js";
 export * from "./requirement-macro-tasks.js";
 export * from "./package-version.js";
 export * from "./runtime-diagnostics.js";
 export * from "./write-coordination.js";
 export * from "./guard-decision.js";
+export * from "./guard-state.js";
 export { PlanStore, PlanStoreError, PlanStaleWriteError, PlanUnsupportedAllocationKindError, assertPlannerRevision, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock, nowISO, type IdeaCreateInput, type IdeaUpdateInput, type IdeaPromotionTargetInput, type AcceptedDecisionOwner, type AcceptedDecisionCreateInput, type AcceptedDecisionUpdateInput, type RecordProjectContextReadInput, type RecordProjectContextReadResult, type PhaseHandoffSummary, type OrphanPhaseSummary } from "./plan-store.js";
 export { PlanRenderer } from "./renderer.js";
 export { ExportService } from "./export-service.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,mBAAmB,EAAE,kCAAkC,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,wBAAwB,EAAE,KAAK,qBAAqB,EAAE,KAAK,2BAA2B,EAAE,KAAK,2BAA2B,EAAE,KAAK,6BAA6B,EAAE,KAAK,8BAA8B,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC3hB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,mBAAmB,EAAE,kCAAkC,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,wBAAwB,EAAE,KAAK,qBAAqB,EAAE,KAAK,2BAA2B,EAAE,KAAK,2BAA2B,EAAE,KAAK,6BAA6B,EAAE,KAAK,8BAA8B,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC3hB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -27,11 +27,14 @@ export * from "./feature-delete.js";
 export * from "./accepted-decision-guard.js";
 export * from "./project-context-migration.js";
 export * from "./project-context.js";
+export * from "./load-reply.js";
+export * from "./on-hold.js";
 export * from "./requirement-macro-tasks.js";
 export * from "./package-version.js";
 export * from "./runtime-diagnostics.js";
 export * from "./write-coordination.js";
 export * from "./guard-decision.js";
+export * from "./guard-state.js";
 export { PlanStore, PlanStoreError, PlanStaleWriteError, PlanUnsupportedAllocationKindError, assertPlannerRevision, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock, nowISO } from "./plan-store.js";
 export { PlanRenderer } from "./renderer.js";
 export { ExportService } from "./export-service.js";

package/dist/load-reply.d.ts

@@ -0,0 +1,63 @@
+import type { ProjectContextReply } from "./project-context.js";
+import type { PlanWorkspace } from "./schema.js";
+/**
+ * Reply shaping for an explicit planner load, shared by every adapter
+ * (MCP planner-load, Pi's planner-load tool and /planner load command).
+ *
+ * Every piece is sent once, in one text the agent reads top to bottom: the
+ * recap to show the user, then the agent-only context. `structured` carries
+ * only status fields; hosts that show the agent only structured content
+ * still get the text because the MCP server folds it in.
+ */
+/** How the planner operating guide reaches the agent on this load. */
+export type PlannerGuideDelivery = 
+/** The guide body is included (a host with no other way to deliver it). */
+{
+    mode: "include";
+    content: string;
+    customized: boolean;
+    message: string;
+}
+/** The host already delivers the guide (e.g. Claude Code's /planner
+ * command); send only where it lives, never the body again. */
+ | {
+    mode: "pointer";
+    path: string;
+    customized: boolean;
+    message: string;
+};
+export interface PlannerLoadReplyInput {
+    recap: string;
+    projectContext: ProjectContextReply;
+    /** Accepted Decisions below project scope (feature/phase/task). Project
+     * decisions are already inside the project context. */
+    scopedDecisions?: {
+        content: string;
+        total: number;
+        truncated: boolean;
+    };
+    plannerGuide: PlannerGuideDelivery;
+}
+export interface PlannerLoadReply {
+    text: string;
+    structured: Record<string, unknown>;
+}
+export declare const PLANNER_LOAD_RECAP_HEADING = "## Recap \u2014 show this to the user verbatim";
+export declare const PLANNER_LOAD_AGENT_HEADING = "## Agent-only context \u2014 read and keep it; never quote it in the recap";
+/** Split a load reply's text back into the recap the user sees and the
+ * agent-only context. Any client (or test) that must show only the recap
+ * uses this instead of guessing at the layout. */
+export declare function splitPlannerLoadText(text: string): {
+    recap: string;
+    agentContext: string;
+};
+export declare function buildPlannerLoadReply(input: PlannerLoadReplyInput): PlannerLoadReply;
+/** Accepted Decisions owned by features, phases and tasks, bounded for a
+ * load reply. Project decisions are left out: the project context already
+ * carries them. */
+export declare function buildScopedDecisionContext(plan: PlanWorkspace): {
+    content: string;
+    total: number;
+    truncated: boolean;
+};
+//# sourceMappingURL=load-reply.d.ts.map

package/dist/load-reply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-reply.d.ts","sourceRoot":"","sources":["../src/load-reply.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD;;;;;;;;GAQG;AAEH,sEAAsE;AACtE,MAAM,MAAM,oBAAoB;AAC9B,2EAA2E;AACzE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AAC5E;+DAC+D;GAC7D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,mBAAmB,CAAC;IACpC;2DACuD;IACvD,eAAe,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IACzE,YAAY,EAAE,oBAAoB,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,eAAO,MAAM,0BAA0B,mDAA8C,CAAC;AACtF,eAAO,MAAM,0BAA0B,+EAA0E,CAAC;AAElH;;kDAEkD;AAClD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAK1F;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,qBAAqB,GAAG,gBAAgB,CAmCpF;AAED;;mBAEmB;AACnB,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,aAAa,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAYtH"}