@wrongstack/core 0.308.1 → 0.308.2

package/dist/coordination/index.d.ts

@@ -69,6 +69,7 @@ TIMEOUT_PREEMPT_FRACTION, } from './subagent-budget.js';
 export { assignNickname } from './subagent-nicknames.js';
 export { formatSubagentStructuredReport, MAX_SUBAGENT_STRUCTURED_REPORT_CHARS, makeSubagentResultTool, normalizeSubagentStructuredReport, readSubagentStructuredReport, SUBAGENT_STRUCTURED_REPORT_META_KEY, } from './subagent-result-tool.js';
 export { startTechStackConsumer, type TechStackConsumerOptions, } from './techstack-mailbox-consumer.js';
+export { composeBoundedTaskDescription, type TaskBoundary, parseTaskBoundary, renderTaskBoundaryBlock, taskBoundarySchemaProperties, } from './task-boundary.js';
 export { type FleetWorktreePolicy, resolveSubagentWorktreeDecision, subagentNeedsWorktree, WorktreeIntegrationError, type WorktreeIsolationDecision, type WorktreeTaskRunnerOptions, type WorktreeTaskStateUpdate, wrapSubagentRunnerWithWorktrees, } from './worktree-task-runner.js';
 export { collabInjectMiddleware, collabPauseMiddleware, } from '../middleware/collab-pause.js';
 export { AdaptiveConcurrencyController, type AdaptiveConcurrencyState, } from './adaptive-concurrency.js';

package/dist/coordination/index.js

@@ -10481,6 +10481,80 @@ var FLEET_ROSTER_WITHACP = {
   ...Object.fromEntries(ACP_AGENTS.map((a) => [a.role, a]))
 };
 
+// src/coordination/task-boundary.ts
+var PLACEHOLDER_VALUES = /* @__PURE__ */ new Set([
+  "n/a",
+  "na",
+  "none",
+  "nothing",
+  "tbd",
+  "todo",
+  "unknown",
+  "unspecified",
+  "-",
+  "\u2014",
+  ".",
+  "as above",
+  "same as above",
+  "see above",
+  "see task",
+  "same as task"
+]);
+var isPlaceholder = (value) => PLACEHOLDER_VALUES.has(value.trim().toLowerCase());
+var MIN_SCOPE_CHARS = 8;
+var MIN_NON_GOAL_CHARS = 3;
+function parseTaskBoundary(raw) {
+  const scope = typeof raw.scope === "string" ? raw.scope.trim() : "";
+  if (scope.length < MIN_SCOPE_CHARS) {
+    return {
+      ok: false,
+      error: `\`scope\` is missing or too vague \u2014 state in one concrete sentence what work this task covers (files, components, or commands in-bounds).`,
+      hint: 'Example \u2014 scope: "Audit packages/core/src/parser/*.ts for unhandled token errors and report findings."'
+    };
+  }
+  if (!Array.isArray(raw.outOfScope) || raw.outOfScope.length === 0) {
+    return {
+      ok: false,
+      error: "`outOfScope` must be an array with at least one explicit non-goal \u2014 things the worker must NOT do.",
+      hint: 'Example \u2014 outOfScope: ["Do not modify files outside packages/core", "Do not fix the bugs you find, only report them"].'
+    };
+  }
+  const concrete = raw.outOfScope.filter((item) => typeof item === "string").map((item) => item.trim()).filter((item) => item.length >= MIN_NON_GOAL_CHARS && !isPlaceholder(item));
+  if (concrete.length === 0) {
+    return {
+      ok: false,
+      error: 'Every `outOfScope` entry was a placeholder ("none", "n/a", \u2026). Name at least one concrete non-goal: files or areas not to touch, changes not to make, features not to add.',
+      hint: 'There is always an edge worth stating \u2014 "read-only, no edits", "no dependency changes", "do not touch other packages". If truly nothing comes to mind, the task is not decomposed enough yet.'
+    };
+  }
+  return { ok: true, boundary: { scope, outOfScope: concrete } };
+}
+function renderTaskBoundaryBlock(boundary) {
+  return [
+    "\u2500\u2500 TASK BOUNDARY (hard contract \u2014 these lines define your edges) \u2500\u2500",
+    `Scope (what this task covers):
+${boundary.scope}`,
+    `Out of scope (explicit non-goals \u2014 do NOT do any of these):
+${boundary.outOfScope.map((item) => `- ${item}`).join("\n")}`
+  ].join("\n");
+}
+function composeBoundedTaskDescription(objective, boundary) {
+  return `${objective.trim()}
+
+${renderTaskBoundaryBlock(boundary)}`;
+}
+var taskBoundarySchemaProperties = {
+  scope: {
+    type: "string",
+    description: "REQUIRED. One concrete sentence stating what work this task covers \u2014 the in-bounds. The call is rejected without it."
+  },
+  outOfScope: {
+    type: "array",
+    items: { type: "string", minLength: 1 },
+    description: 'REQUIRED. At least one explicit non-goal the worker must NOT do (files/areas not to touch, changes not to make, features not to add). Placeholders like "none" are rejected.'
+  }
+};
+
 // src/coordination/delegate-tool.ts
 function createDelegateTool(opts) {
   const defaultTimeoutMs = opts.defaultTimeoutMs ?? 4 * 60 * 60 * 1e3;
@@ -10490,8 +10564,9 @@ function createDelegateTool(opts) {
     properties: {
       task: {
         type: "string",
-        description: "What the subagent should do \u2014 natural language, complete sentence(s)."
+        description: "The objective \u2014 what the subagent should do, natural language, complete sentence(s). Pair it with the required `scope` and `outOfScope` boundary fields."
       },
+      ...taskBoundarySchemaProperties,
       role: {
         type: "string",
         description: rosterIds.length > 0 ? "Roster role id. Common: bug-hunter, security-scanner, refactor-planner, critic, audit-log, executor, shadow-agent, architect." : "No roster configured \u2014 pass `name` instead."
@@ -10549,12 +10624,12 @@ function createDelegateTool(opts) {
         description: "Max fresh-worker continuations after budget exhaustion. Default 1. Each gets the prior partial report."
       }
     },
-    required: ["task"]
+    required: ["task", "scope", "outOfScope"]
   };
   return {
     name: "delegate",
     description: "Hand a piece of work to a subagent and block until it returns. This call is synchronous: the leader's iteration pauses for the full duration of the subagent's run. (Multiple `delegate` calls fired in the same assistant turn still parallelize through the provider's parallel-tool-call surface, but each one eats wall-clock time \u2014 so for fan-out you actually control, reach for the async path below.) Use `delegate` when your next step genuinely needs the subagent's verdict \u2014 a review, a fact-check, a sign-off. Has own context, own LLM call, auto-extending budget, and a partial-completion handoff path (maxHandoffs, default 1). Workers cannot recursively spawn.\n\n**Do NOT use `delegate` for long-running work.** While `delegate` is in flight, the leader is fully blocked \u2014 it cannot act on other tools, read mail, or react to the user. If the work might run for tens of minutes or hours (multi-file refactor, monorepo audit, long-running build/test, sweeping migration), the blocking call wastes the leader's time. Use the async tool family instead: `spawn_subagent` to create each worker (returns a `subagentId` immediately), `assign_task` to queue work on it (returns a `taskId` immediately), then `await_tasks` to retrieve results later. The leader keeps doing other work while the worker churns, and a worker that realizes its task will run long can mail the leader (type `steer` or `ask` via `mail_send`) saying *\"my task is going to run long, please spawn a subagent instead\"* so the leader re-dispatches asynchronously instead of waiting.\n\n**Do NOT use `delegate` for fan-out you control.** Multiple sequential `delegate` calls each block the leader, wasting wall-clock time. For independent investigations you want to run in parallel \u2014 security scan + bug hunt + perf review on the same PR \u2014 use the async tool family: `spawn_subagent` to create each worker (returns a `subagentId` immediately), `assign_task` to queue work on it (returns a `taskId` immediately), then the `await_tasks` tool with `{mode: 'any'}` to fold the first useful result into the next decision while the rest keep churning. Reach for `delegate` only when the result gates your next move AND the work is short enough that blocking the leader is acceptable.",
-    usageHint: "Set `task` to a complete instruction. Pick `role` from roster or pass `name` for free-form. Reach for `delegate` only when the result gates your next move AND the work is short enough that blocking the leader is acceptable (minutes, not hours). For long-running work or fan-out you control, use `spawn_subagent` + `assign_task` + `await_tasks` instead. Raise `maxHandoffs` (default 1, cap 8) for multi-day or multi-refactor tasks; pass larger `timeoutMs`/`maxIterations`/`maxToolCalls` only when needed.",
+    usageHint: "Set `task` to the objective, then make the edges explicit: `scope` (what the work covers) and `outOfScope` (at least one concrete non-goal) are REQUIRED \u2014 the call is rejected without them, and the worker treats the rendered boundary block as a hard contract. Pick `role` from roster or pass `name` for free-form. Reach for `delegate` only when the result gates your next move AND the work is short enough that blocking the leader is acceptable (minutes, not hours). For long-running work or fan-out you control, use `spawn_subagent` + `assign_task` + `await_tasks` instead. Raise `maxHandoffs` (default 1, cap 8) for multi-day or multi-refactor tasks; pass larger `timeoutMs`/`maxIterations`/`maxToolCalls` only when needed.",
     permission: "auto",
     mutating: false,
     managesOwnTimeout: true,
@@ -10574,6 +10649,14 @@ function createDelegateTool(opts) {
           error: "Delegation cancelled before spawn \u2014 the run was interrupted."
         };
       }
+      const boundary = parseTaskBoundary(i);
+      if (!boundary.ok) {
+        return {
+          ok: false,
+          error: `delegate rejected \u2014 task boundary incomplete: ${boundary.error}`,
+          hint: boundary.hint
+        };
+      }
       const target = i.role ?? i.name ?? "subagent";
       const launchModePreface = [
         "Launch-mode guidance (delegate): you were launched via the synchronous `delegate` tool, so the leader is blocked on this call for the full duration of your run.",
@@ -10644,7 +10727,8 @@ function createDelegateTool(opts) {
         const dir = director;
         const maxHandoffs = Math.min(8, Math.max(0, Math.floor(i.maxHandoffs ?? 1)));
         const handoffs = [];
-        let delegatedTask = i.task;
+        const baseBrief = composeBoundedTaskDescription(i.task, boundary.boundary);
+        let delegatedTask = baseBrief;
         let handoffCount = 0;
         for (; ; ) {
           const attemptConfig = (() => {
@@ -10784,7 +10868,7 @@ function createDelegateTool(opts) {
               remainingWork: continuation.remainingWork
             });
             handoffCount += 1;
-            delegatedTask = buildHandoffTask(i.task, continuation, handoffCount, maxHandoffs);
+            delegatedTask = buildHandoffTask(baseBrief, continuation, handoffCount, maxHandoffs);
             continue;
           }
           const incomplete = result.report?.completion === "partial";
@@ -12688,8 +12772,9 @@ function makeAssignTool(director) {
       description: {
         type: "string",
         minLength: 1,
-        description: "The task in natural language \u2014 what you want this subagent to do."
+        description: "The objective in natural language \u2014 what you want this subagent to do. Pair it with the required `scope` and `outOfScope` boundary fields."
       },
+      ...taskBoundarySchemaProperties,
       maxToolCalls: {
         type: "number",
         minimum: 1,
@@ -12697,20 +12782,28 @@ function makeAssignTool(director) {
       },
       timeoutMs: { type: "number", minimum: 1, description: "Optional per-task timeout in ms." }
     },
-    required: ["subagentId", "description"]
+    required: ["subagentId", "description", "scope", "outOfScope"]
   };
   return {
     name: "assign_task",
-    description: "Queue a task on a previously spawned subagent. NON-BLOCKING: returns a `taskId` IMMEDIATELY \u2014 the subagent processes the task on its next iteration with its own LLM budget. The `taskId` is the durable handle for retrieving the result later via `await_tasks`, `roll_up`, or `ask_result`. Many `assign_task` calls can be in flight in parallel against the same or different subagents. This is the primary tool for fan-out work; do NOT use `delegate` to spawn multiple investigations sequentially.",
+    description: "Queue a task on a previously spawned subagent. NON-BLOCKING: returns a `taskId` IMMEDIATELY \u2014 the subagent processes the task on its next iteration with its own LLM budget. The `taskId` is the durable handle for retrieving the result later via `await_tasks`, `roll_up`, or `ask_result`. Every assignment MUST carry an explicit boundary: `scope` (what the work covers) and `outOfScope` (at least one concrete non-goal) \u2014 the call is rejected without them, and the worker treats the rendered boundary block as a hard contract. Many `assign_task` calls can be in flight in parallel against the same or different subagents. This is the primary tool for fan-out work; do NOT use `delegate` to spawn multiple investigations sequentially.",
     permission: "auto",
     mutating: false,
     capabilities: [ToolCapabilities.SUBAGENT_SPAWN],
     inputSchema,
     async execute(input) {
       const i = input;
+      const boundary = parseTaskBoundary(i);
+      if (!boundary.ok) {
+        return {
+          ok: false,
+          error: `assign_task rejected \u2014 task boundary incomplete: ${boundary.error}`,
+          hint: boundary.hint
+        };
+      }
       const task = {
         id: randomUUID8(),
-        description: i.description,
+        description: composeBoundedTaskDescription(i.description, boundary.boundary),
         subagentId: i.subagentId,
         maxToolCalls: i.maxToolCalls,
         timeoutMs: i.timeoutMs
@@ -20503,8 +20596,8 @@ var DefaultMultiAgentCoordinator = class _DefaultMultiAgentCoordinator extends E
   withNickname(subagent, subagentId) {
     const role = subagent.role ?? "subagent";
     const name = subagent.name?.trim() ?? "";
-    const isPlaceholder = name === "" || name.toLowerCase() === role.toLowerCase() || name === "subagent" || name === "adhoc" || name === "generic" || /^slot-/.test(name);
-    if (!isPlaceholder) return subagent;
+    const isPlaceholder2 = name === "" || name.toLowerCase() === role.toLowerCase() || name === "subagent" || name === "adhoc" || name === "generic" || /^slot-/.test(name);
+    if (!isPlaceholder2) return subagent;
     const { key, display } = assignNickname(role, this.usedNicknames);
     this.usedNicknames.add(key);
     this.subagentNicknames.set(subagentId, key);
@@ -31367,6 +31460,7 @@ export {
   clearProjectSkillAugmentation,
   collabInjectMiddleware,
   collabPauseMiddleware,
+  composeBoundedTaskDescription,
   composeDirectorPrompt,
   composeSubagentPrompt,
   consolidatedDocumentPath,
@@ -31451,6 +31545,7 @@ export {
   parseMailboxAckInput,
   parseMailboxQueryInput,
   parseMailboxSendInput,
+  parseTaskBoundary,
   phaseForRole,
   quarantinePath,
   rankRoleSkills,
@@ -31467,6 +31562,7 @@ export {
   refreshProjectAgentIdentity,
   release,
   renderSkillAugmentation,
+  renderTaskBoundaryBlock,
   resetCaptureWindow,
   resetCaptureWindows,
   resetProjectAgentIdentity,
@@ -31497,6 +31593,7 @@ export {
   startPackageOutdatedWatcher,
   startTechStackConsumer,
   subagentNeedsWorktree,
+  taskBoundarySchemaProperties,
   terminalPolicyDecision,
   unwrapWholeDocumentFence,
   updatePackageOutdatedStatus,

package/dist/coordination/task-boundary.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Hard task-boundary contract for leader → subagent assignment tools.
+ *
+ * `delegate` and `assign_task` reject any assignment that does not carry an
+ * explicit in-bounds `scope` and at least one concrete out-of-scope non-goal.
+ * Prompt-only guidance ("state the scope and non-goals") degrades under
+ * pressure: a rushed leader writes "fix it", the worker guesses the edges, and
+ * the drift only surfaces at review time — the most expensive place to find
+ * it. Forcing the boundary into structured fields makes the edges
+ * machine-checkable at assignment time and lets the tool return a teaching
+ * error that names exactly what is missing, so the leader self-corrects on
+ * the next call instead of shipping a vague brief.
+ *
+ * The parsed boundary is composed into `TaskSpec.description` as a clearly
+ * delimited block. That is deliberate: the description is the canonical brief
+ * every runner, transcript, handoff continuation, and roll-up already
+ * consumes, so the boundary travels with the task everywhere without new
+ * plumbing (and `buildHandoffTask`'s "Original task:" carry-over preserves it
+ * into fresh workers for free).
+ */
+import type { JSONSchema } from '../types/tool.js';
+export interface TaskBoundary {
+    /** What the work covers — the in-bounds statement. */
+    scope: string;
+    /** Explicit non-goals: things the worker must NOT do. */
+    outOfScope: string[];
+}
+export type TaskBoundaryParseResult = {
+    ok: true;
+    boundary: TaskBoundary;
+} | {
+    ok: false;
+    error: string;
+    hint: string;
+};
+/**
+ * Validate and normalize the `scope` / `outOfScope` pair from a tool input.
+ * Returns the cleaned boundary, or an error + hint pair worded so the calling
+ * leader can fix the call in one retry.
+ */
+export declare function parseTaskBoundary(raw: {
+    scope?: unknown;
+    outOfScope?: unknown;
+}): TaskBoundaryParseResult;
+/**
+ * Render the boundary as the block appended to `TaskSpec.description`. The
+ * heading is loud on purpose: the worker treats these lines as hard edges,
+ * and review-time drift checks quote them verbatim.
+ */
+export declare function renderTaskBoundaryBlock(boundary: TaskBoundary): string;
+/**
+ * Compose the leader's objective with its boundary into the canonical brief
+ * delivered to the runner. The objective stays verbatim and first; the
+ * boundary block follows so handoffs, transcripts, and roll-ups that quote
+ * the description carry the edges with them.
+ */
+export declare function composeBoundedTaskDescription(objective: string, boundary: TaskBoundary): string;
+/**
+ * Shared schema property definitions so `delegate` and `assign_task` state
+ * the identical contract. Declaring the fields here (rather than inline per
+ * tool) keeps the required-field teaching text single-sourced.
+ */
+export declare const taskBoundarySchemaProperties: Record<string, JSONSchema>;
+//# sourceMappingURL=task-boundary.d.ts.map

package/dist/defaults/index.js

@@ -5512,6 +5512,80 @@ var FLEET_ROSTER_WITHACP = {
   ...Object.fromEntries(ACP_AGENTS.map((a) => [a.role, a]))
 };
 
+// src/coordination/task-boundary.ts
+var PLACEHOLDER_VALUES = /* @__PURE__ */ new Set([
+  "n/a",
+  "na",
+  "none",
+  "nothing",
+  "tbd",
+  "todo",
+  "unknown",
+  "unspecified",
+  "-",
+  "\u2014",
+  ".",
+  "as above",
+  "same as above",
+  "see above",
+  "see task",
+  "same as task"
+]);
+var isPlaceholder = (value) => PLACEHOLDER_VALUES.has(value.trim().toLowerCase());
+var MIN_SCOPE_CHARS = 8;
+var MIN_NON_GOAL_CHARS = 3;
+function parseTaskBoundary(raw) {
+  const scope = typeof raw.scope === "string" ? raw.scope.trim() : "";
+  if (scope.length < MIN_SCOPE_CHARS) {
+    return {
+      ok: false,
+      error: `\`scope\` is missing or too vague \u2014 state in one concrete sentence what work this task covers (files, components, or commands in-bounds).`,
+      hint: 'Example \u2014 scope: "Audit packages/core/src/parser/*.ts for unhandled token errors and report findings."'
+    };
+  }
+  if (!Array.isArray(raw.outOfScope) || raw.outOfScope.length === 0) {
+    return {
+      ok: false,
+      error: "`outOfScope` must be an array with at least one explicit non-goal \u2014 things the worker must NOT do.",
+      hint: 'Example \u2014 outOfScope: ["Do not modify files outside packages/core", "Do not fix the bugs you find, only report them"].'
+    };
+  }
+  const concrete = raw.outOfScope.filter((item) => typeof item === "string").map((item) => item.trim()).filter((item) => item.length >= MIN_NON_GOAL_CHARS && !isPlaceholder(item));
+  if (concrete.length === 0) {
+    return {
+      ok: false,
+      error: 'Every `outOfScope` entry was a placeholder ("none", "n/a", \u2026). Name at least one concrete non-goal: files or areas not to touch, changes not to make, features not to add.',
+      hint: 'There is always an edge worth stating \u2014 "read-only, no edits", "no dependency changes", "do not touch other packages". If truly nothing comes to mind, the task is not decomposed enough yet.'
+    };
+  }
+  return { ok: true, boundary: { scope, outOfScope: concrete } };
+}
+function renderTaskBoundaryBlock(boundary) {
+  return [
+    "\u2500\u2500 TASK BOUNDARY (hard contract \u2014 these lines define your edges) \u2500\u2500",
+    `Scope (what this task covers):
+${boundary.scope}`,
+    `Out of scope (explicit non-goals \u2014 do NOT do any of these):
+${boundary.outOfScope.map((item) => `- ${item}`).join("\n")}`
+  ].join("\n");
+}
+function composeBoundedTaskDescription(objective, boundary) {
+  return `${objective.trim()}
+
+${renderTaskBoundaryBlock(boundary)}`;
+}
+var taskBoundarySchemaProperties = {
+  scope: {
+    type: "string",
+    description: "REQUIRED. One concrete sentence stating what work this task covers \u2014 the in-bounds. The call is rejected without it."
+  },
+  outOfScope: {
+    type: "array",
+    items: { type: "string", minLength: 1 },
+    description: 'REQUIRED. At least one explicit non-goal the worker must NOT do (files/areas not to touch, changes not to make, features not to add). Placeholders like "none" are rejected.'
+  }
+};
+
 // src/coordination/delegate-tool.ts
 function createDelegateTool(opts) {
   const defaultTimeoutMs = opts.defaultTimeoutMs ?? 4 * 60 * 60 * 1e3;
@@ -5521,8 +5595,9 @@ function createDelegateTool(opts) {
     properties: {
       task: {
         type: "string",
-        description: "What the subagent should do \u2014 natural language, complete sentence(s)."
+        description: "The objective \u2014 what the subagent should do, natural language, complete sentence(s). Pair it with the required `scope` and `outOfScope` boundary fields."
       },
+      ...taskBoundarySchemaProperties,
       role: {
         type: "string",
         description: rosterIds.length > 0 ? "Roster role id. Common: bug-hunter, security-scanner, refactor-planner, critic, audit-log, executor, shadow-agent, architect." : "No roster configured \u2014 pass `name` instead."
@@ -5580,12 +5655,12 @@ function createDelegateTool(opts) {
         description: "Max fresh-worker continuations after budget exhaustion. Default 1. Each gets the prior partial report."
       }
     },
-    required: ["task"]
+    required: ["task", "scope", "outOfScope"]
   };
   return {
     name: "delegate",
     description: "Hand a piece of work to a subagent and block until it returns. This call is synchronous: the leader's iteration pauses for the full duration of the subagent's run. (Multiple `delegate` calls fired in the same assistant turn still parallelize through the provider's parallel-tool-call surface, but each one eats wall-clock time \u2014 so for fan-out you actually control, reach for the async path below.) Use `delegate` when your next step genuinely needs the subagent's verdict \u2014 a review, a fact-check, a sign-off. Has own context, own LLM call, auto-extending budget, and a partial-completion handoff path (maxHandoffs, default 1). Workers cannot recursively spawn.\n\n**Do NOT use `delegate` for long-running work.** While `delegate` is in flight, the leader is fully blocked \u2014 it cannot act on other tools, read mail, or react to the user. If the work might run for tens of minutes or hours (multi-file refactor, monorepo audit, long-running build/test, sweeping migration), the blocking call wastes the leader's time. Use the async tool family instead: `spawn_subagent` to create each worker (returns a `subagentId` immediately), `assign_task` to queue work on it (returns a `taskId` immediately), then `await_tasks` to retrieve results later. The leader keeps doing other work while the worker churns, and a worker that realizes its task will run long can mail the leader (type `steer` or `ask` via `mail_send`) saying *\"my task is going to run long, please spawn a subagent instead\"* so the leader re-dispatches asynchronously instead of waiting.\n\n**Do NOT use `delegate` for fan-out you control.** Multiple sequential `delegate` calls each block the leader, wasting wall-clock time. For independent investigations you want to run in parallel \u2014 security scan + bug hunt + perf review on the same PR \u2014 use the async tool family: `spawn_subagent` to create each worker (returns a `subagentId` immediately), `assign_task` to queue work on it (returns a `taskId` immediately), then the `await_tasks` tool with `{mode: 'any'}` to fold the first useful result into the next decision while the rest keep churning. Reach for `delegate` only when the result gates your next move AND the work is short enough that blocking the leader is acceptable.",
-    usageHint: "Set `task` to a complete instruction. Pick `role` from roster or pass `name` for free-form. Reach for `delegate` only when the result gates your next move AND the work is short enough that blocking the leader is acceptable (minutes, not hours). For long-running work or fan-out you control, use `spawn_subagent` + `assign_task` + `await_tasks` instead. Raise `maxHandoffs` (default 1, cap 8) for multi-day or multi-refactor tasks; pass larger `timeoutMs`/`maxIterations`/`maxToolCalls` only when needed.",
+    usageHint: "Set `task` to the objective, then make the edges explicit: `scope` (what the work covers) and `outOfScope` (at least one concrete non-goal) are REQUIRED \u2014 the call is rejected without them, and the worker treats the rendered boundary block as a hard contract. Pick `role` from roster or pass `name` for free-form. Reach for `delegate` only when the result gates your next move AND the work is short enough that blocking the leader is acceptable (minutes, not hours). For long-running work or fan-out you control, use `spawn_subagent` + `assign_task` + `await_tasks` instead. Raise `maxHandoffs` (default 1, cap 8) for multi-day or multi-refactor tasks; pass larger `timeoutMs`/`maxIterations`/`maxToolCalls` only when needed.",
     permission: "auto",
     mutating: false,
     managesOwnTimeout: true,
@@ -5605,6 +5680,14 @@ function createDelegateTool(opts) {
           error: "Delegation cancelled before spawn \u2014 the run was interrupted."
         };
       }
+      const boundary = parseTaskBoundary(i);
+      if (!boundary.ok) {
+        return {
+          ok: false,
+          error: `delegate rejected \u2014 task boundary incomplete: ${boundary.error}`,
+          hint: boundary.hint
+        };
+      }
       const target = i.role ?? i.name ?? "subagent";
       const launchModePreface = [
         "Launch-mode guidance (delegate): you were launched via the synchronous `delegate` tool, so the leader is blocked on this call for the full duration of your run.",
@@ -5675,7 +5758,8 @@ function createDelegateTool(opts) {
         const dir = director;
         const maxHandoffs = Math.min(8, Math.max(0, Math.floor(i.maxHandoffs ?? 1)));
         const handoffs = [];
-        let delegatedTask = i.task;
+        const baseBrief = composeBoundedTaskDescription(i.task, boundary.boundary);
+        let delegatedTask = baseBrief;
         let handoffCount = 0;
         for (; ; ) {
           const attemptConfig = (() => {
@@ -5815,7 +5899,7 @@ function createDelegateTool(opts) {
               remainingWork: continuation.remainingWork
             });
             handoffCount += 1;
-            delegatedTask = buildHandoffTask(i.task, continuation, handoffCount, maxHandoffs);
+            delegatedTask = buildHandoffTask(baseBrief, continuation, handoffCount, maxHandoffs);
             continue;
           }
           const incomplete = result.report?.completion === "partial";
@@ -8503,8 +8587,9 @@ function makeAssignTool(director) {
       description: {
         type: "string",
         minLength: 1,
-        description: "The task in natural language \u2014 what you want this subagent to do."
+        description: "The objective in natural language \u2014 what you want this subagent to do. Pair it with the required `scope` and `outOfScope` boundary fields."
       },
+      ...taskBoundarySchemaProperties,
       maxToolCalls: {
         type: "number",
         minimum: 1,
@@ -8512,20 +8597,28 @@ function makeAssignTool(director) {
       },
       timeoutMs: { type: "number", minimum: 1, description: "Optional per-task timeout in ms." }
     },
-    required: ["subagentId", "description"]
+    required: ["subagentId", "description", "scope", "outOfScope"]
   };
   return {
     name: "assign_task",
-    description: "Queue a task on a previously spawned subagent. NON-BLOCKING: returns a `taskId` IMMEDIATELY \u2014 the subagent processes the task on its next iteration with its own LLM budget. The `taskId` is the durable handle for retrieving the result later via `await_tasks`, `roll_up`, or `ask_result`. Many `assign_task` calls can be in flight in parallel against the same or different subagents. This is the primary tool for fan-out work; do NOT use `delegate` to spawn multiple investigations sequentially.",
+    description: "Queue a task on a previously spawned subagent. NON-BLOCKING: returns a `taskId` IMMEDIATELY \u2014 the subagent processes the task on its next iteration with its own LLM budget. The `taskId` is the durable handle for retrieving the result later via `await_tasks`, `roll_up`, or `ask_result`. Every assignment MUST carry an explicit boundary: `scope` (what the work covers) and `outOfScope` (at least one concrete non-goal) \u2014 the call is rejected without them, and the worker treats the rendered boundary block as a hard contract. Many `assign_task` calls can be in flight in parallel against the same or different subagents. This is the primary tool for fan-out work; do NOT use `delegate` to spawn multiple investigations sequentially.",
     permission: "auto",
     mutating: false,
     capabilities: [ToolCapabilities.SUBAGENT_SPAWN],
     inputSchema,
     async execute(input) {
       const i = input;
+      const boundary = parseTaskBoundary(i);
+      if (!boundary.ok) {
+        return {
+          ok: false,
+          error: `assign_task rejected \u2014 task boundary incomplete: ${boundary.error}`,
+          hint: boundary.hint
+        };
+      }
       const task = {
         id: randomUUID6(),
-        description: i.description,
+        description: composeBoundedTaskDescription(i.description, boundary.boundary),
         subagentId: i.subagentId,
         maxToolCalls: i.maxToolCalls,
         timeoutMs: i.timeoutMs
@@ -19228,8 +19321,8 @@ var DefaultMultiAgentCoordinator = class _DefaultMultiAgentCoordinator extends E
   withNickname(subagent, subagentId) {
     const role = subagent.role ?? "subagent";
     const name = subagent.name?.trim() ?? "";
-    const isPlaceholder = name === "" || name.toLowerCase() === role.toLowerCase() || name === "subagent" || name === "adhoc" || name === "generic" || /^slot-/.test(name);
-    if (!isPlaceholder) return subagent;
+    const isPlaceholder2 = name === "" || name.toLowerCase() === role.toLowerCase() || name === "subagent" || name === "adhoc" || name === "generic" || /^slot-/.test(name);
+    if (!isPlaceholder2) return subagent;
     const { key, display } = assignNickname(role, this.usedNicknames);
     this.usedNicknames.add(key);
     this.subagentNicknames.set(subagentId, key);
@@ -22497,6 +22590,7 @@ function normalizeTargetLoad(targetLoad, thresholds) {
 
 // src/types/context-window.ts
 var DEFAULT_CONTEXT_WINDOW_MODE_ID = "balanced";
+var LARGE_WINDOW_DEEP_MODE_THRESHOLD = 1e6;
 var DEPRECATED_CONTEXT_WINDOW_MODE_ALIASES = Object.freeze({
   archival: "balanced"
 });
@@ -22504,7 +22598,7 @@ var CONTEXT_WINDOW_MODES = Object.freeze([
   {
     id: "balanced",
     name: "Balanced",
-    description: "Default rolling compaction: recent work stays verbatim, old tool output is trimmed.",
+    description: "Default rolling compaction: recent work stays verbatim, old tool output is trimmed. Windows of 1M+ tokens default to Deep.",
     thresholds: { warn: 0.55, soft: 0.7, hard: 0.85 },
     aggressiveOn: "soft",
     preserveK: 8,
@@ -22555,9 +22649,11 @@ function getContextWindowMode(id) {
 function isContextWindowModeId(id) {
   return CONTEXT_WINDOW_MODES.some((m) => m.id === id);
 }
-function resolveContextWindowPolicy(config = {}, overrideMode) {
+function resolveContextWindowPolicy(config = {}, overrideMode, maxContext) {
   const requested = overrideMode ?? config.mode ?? DEFAULT_CONTEXT_WINDOW_MODE_ID;
-  const mode = getContextWindowMode(requested) ?? expectDefined(getContextWindowMode(DEFAULT_CONTEXT_WINDOW_MODE_ID));
+  const normalized = normalizeContextWindowModeId(requested) ?? DEFAULT_CONTEXT_WINDOW_MODE_ID;
+  const baseId = normalized === DEFAULT_CONTEXT_WINDOW_MODE_ID && typeof maxContext === "number" && maxContext >= LARGE_WINDOW_DEEP_MODE_THRESHOLD ? "deep" : normalized;
+  const mode = expectDefined(getContextWindowMode(baseId));
   return {
     ...mode,
     thresholds: {
@@ -22972,7 +23068,7 @@ function readContextWindowPolicy(ctx) {
 function installSubagentAutoCompaction(pipelines, ctx, contextConfig, events) {
   const maxContext = ctx.provider?.capabilities?.maxContext ?? 0;
   if (!(maxContext > 0)) return void 0;
-  const policy = resolveContextWindowPolicy(contextConfig ?? {});
+  const policy = resolveContextWindowPolicy(contextConfig ?? {}, void 0, maxContext);
   ctx.meta ??= {};
   ctx.meta["contextWindowPolicy"] = policy;
   const compactor = new HybridCompactor({

package/dist/execution/index.js

@@ -21421,6 +21421,7 @@ function readPolicy(ctx) {
 
 // src/types/context-window.ts
 var DEFAULT_CONTEXT_WINDOW_MODE_ID = "balanced";
+var LARGE_WINDOW_DEEP_MODE_THRESHOLD = 1e6;
 var DEPRECATED_CONTEXT_WINDOW_MODE_ALIASES = Object.freeze({
   archival: "balanced"
 });
@@ -21428,7 +21429,7 @@ var CONTEXT_WINDOW_MODES = Object.freeze([
   {
     id: "balanced",
     name: "Balanced",
-    description: "Default rolling compaction: recent work stays verbatim, old tool output is trimmed.",
+    description: "Default rolling compaction: recent work stays verbatim, old tool output is trimmed. Windows of 1M+ tokens default to Deep.",
     thresholds: { warn: 0.55, soft: 0.7, hard: 0.85 },
     aggressiveOn: "soft",
     preserveK: 8,
@@ -21470,9 +21471,11 @@ function getContextWindowMode(id) {
 function isContextWindowModeId(id) {
   return CONTEXT_WINDOW_MODES.some((m) => m.id === id);
 }
-function resolveContextWindowPolicy(config = {}, overrideMode) {
+function resolveContextWindowPolicy(config = {}, overrideMode, maxContext) {
   const requested = overrideMode ?? config.mode ?? DEFAULT_CONTEXT_WINDOW_MODE_ID;
-  const mode = getContextWindowMode(requested) ?? expectDefined(getContextWindowMode(DEFAULT_CONTEXT_WINDOW_MODE_ID));
+  const normalized = normalizeContextWindowModeId(requested) ?? DEFAULT_CONTEXT_WINDOW_MODE_ID;
+  const baseId = normalized === DEFAULT_CONTEXT_WINDOW_MODE_ID && typeof maxContext === "number" && maxContext >= LARGE_WINDOW_DEEP_MODE_THRESHOLD ? "deep" : normalized;
+  const mode = expectDefined(getContextWindowMode(baseId));
   return {
     ...mode,
     thresholds: {
@@ -21490,7 +21493,7 @@ function resolveContextWindowPolicy(config = {}, overrideMode) {
 function installSubagentAutoCompaction(pipelines, ctx, contextConfig, events) {
   const maxContext = ctx.provider?.capabilities?.maxContext ?? 0;
   if (!(maxContext > 0)) return void 0;
-  const policy = resolveContextWindowPolicy(contextConfig ?? {});
+  const policy = resolveContextWindowPolicy(contextConfig ?? {}, void 0, maxContext);
   ctx.meta ??= {};
   ctx.meta["contextWindowPolicy"] = policy;
   const compactor = new HybridCompactor({

package/dist/index.d.ts

@@ -134,7 +134,7 @@ export { createMcpUseTool } from './tools/mcp-use.js';
 export { type CreateOneShotLLMToolOptions, createOneShotLLMTool, ONE_SHOT_LLM_TOOL_NAME, } from './tools/one-shot-llm-tool.js';
 export { type CreatePluginManagerToolOptions, createPluginManagerTool, PLUGIN_MANAGER_TOOL_NAME, type PluginManagerCatalogEntry, type PluginManagerMutationResult, } from './tools/plugin-manager.js';
 export type { Compactor, CompactReport } from './types/compactor.js';
-export { CONTEXT_WINDOW_MODES, type ContextWindowAggressiveOn, type ContextWindowConfigLike, type ContextWindowMode, type ContextWindowModeId, type ContextWindowModeSelectionId, type ContextWindowPolicy, type ContextWindowThresholds, DEFAULT_CONTEXT_WINDOW_MODE_ID, DEPRECATED_CONTEXT_WINDOW_MODE_ALIASES, type DeprecatedContextWindowModeId, formatContextWindowModeList, getContextWindowMode, isContextWindowModeId, isContextWindowModeSelectionId, isDeprecatedContextWindowModeId, listContextWindowModes, normalizeContextWindowModeId, resolveContextWindowPolicy, } from './types/context-window.js';
+export { CONTEXT_WINDOW_MODES, type ContextWindowAggressiveOn, type ContextWindowConfigLike, type ContextWindowMode, type ContextWindowModeId, type ContextWindowModeSelectionId, type ContextWindowPolicy, type ContextWindowThresholds, DEFAULT_CONTEXT_WINDOW_MODE_ID, DEPRECATED_CONTEXT_WINDOW_MODE_ALIASES, type DeprecatedContextWindowModeId, formatContextWindowModeList, getContextWindowMode, isContextWindowModeId, isContextWindowModeSelectionId, isDeprecatedContextWindowModeId, LARGE_WINDOW_DEEP_MODE_THRESHOLD, CONTEXT_WINDOW_MODE_PINNED_META_KEY, listContextWindowModes, normalizeContextWindowModeId, resolveContextWindowPolicy, } from './types/context-window.js';
 export { DEFAULT_SESSION_PRUNE_DAYS } from './types/default-config.js';
 export type { FileEventRecord } from './types/file-event-record.js';
 export * from './types/index.js';

package/dist/index.js

@@ -3042,6 +3042,8 @@ function expectDefined(value, label) {
 
 // src/types/context-window.ts
 var DEFAULT_CONTEXT_WINDOW_MODE_ID = "balanced";
+var LARGE_WINDOW_DEEP_MODE_THRESHOLD = 1e6;
+var CONTEXT_WINDOW_MODE_PINNED_META_KEY = "contextWindowModePinned";
 var DEPRECATED_CONTEXT_WINDOW_MODE_ALIASES = Object.freeze({
   archival: "balanced"
 });
@@ -3049,7 +3051,7 @@ var CONTEXT_WINDOW_MODES = Object.freeze([
   {
     id: "balanced",
     name: "Balanced",
-    description: "Default rolling compaction: recent work stays verbatim, old tool output is trimmed.",
+    description: "Default rolling compaction: recent work stays verbatim, old tool output is trimmed. Windows of 1M+ tokens default to Deep.",
     thresholds: { warn: 0.55, soft: 0.7, hard: 0.85 },
     aggressiveOn: "soft",
     preserveK: 8,
@@ -3100,9 +3102,11 @@ function getContextWindowMode(id) {
 function isContextWindowModeId(id) {
   return CONTEXT_WINDOW_MODES.some((m) => m.id === id);
 }
-function resolveContextWindowPolicy(config = {}, overrideMode) {
+function resolveContextWindowPolicy(config = {}, overrideMode, maxContext) {
   const requested = overrideMode ?? config.mode ?? DEFAULT_CONTEXT_WINDOW_MODE_ID;
-  const mode = getContextWindowMode(requested) ?? expectDefined(getContextWindowMode(DEFAULT_CONTEXT_WINDOW_MODE_ID));
+  const normalized = normalizeContextWindowModeId(requested) ?? DEFAULT_CONTEXT_WINDOW_MODE_ID;
+  const baseId = normalized === DEFAULT_CONTEXT_WINDOW_MODE_ID && typeof maxContext === "number" && maxContext >= LARGE_WINDOW_DEEP_MODE_THRESHOLD ? "deep" : normalized;
+  const mode = expectDefined(getContextWindowMode(baseId));
   return {
     ...mode,
     thresholds: {
@@ -31216,6 +31220,82 @@ function makeLLMClassifier(complete2) {
 // src/coordination/director-basic-tools.ts
 import { randomUUID as randomUUID12 } from "node:crypto";
 init_error();
+
+// src/coordination/task-boundary.ts
+var PLACEHOLDER_VALUES = /* @__PURE__ */ new Set([
+  "n/a",
+  "na",
+  "none",
+  "nothing",
+  "tbd",
+  "todo",
+  "unknown",
+  "unspecified",
+  "-",
+  "\u2014",
+  ".",
+  "as above",
+  "same as above",
+  "see above",
+  "see task",
+  "same as task"
+]);
+var isPlaceholder = (value) => PLACEHOLDER_VALUES.has(value.trim().toLowerCase());
+var MIN_SCOPE_CHARS = 8;
+var MIN_NON_GOAL_CHARS = 3;
+function parseTaskBoundary(raw) {
+  const scope = typeof raw.scope === "string" ? raw.scope.trim() : "";
+  if (scope.length < MIN_SCOPE_CHARS) {
+    return {
+      ok: false,
+      error: `\`scope\` is missing or too vague \u2014 state in one concrete sentence what work this task covers (files, components, or commands in-bounds).`,
+      hint: 'Example \u2014 scope: "Audit packages/core/src/parser/*.ts for unhandled token errors and report findings."'
+    };
+  }
+  if (!Array.isArray(raw.outOfScope) || raw.outOfScope.length === 0) {
+    return {
+      ok: false,
+      error: "`outOfScope` must be an array with at least one explicit non-goal \u2014 things the worker must NOT do.",
+      hint: 'Example \u2014 outOfScope: ["Do not modify files outside packages/core", "Do not fix the bugs you find, only report them"].'
+    };
+  }
+  const concrete = raw.outOfScope.filter((item) => typeof item === "string").map((item) => item.trim()).filter((item) => item.length >= MIN_NON_GOAL_CHARS && !isPlaceholder(item));
+  if (concrete.length === 0) {
+    return {
+      ok: false,
+      error: 'Every `outOfScope` entry was a placeholder ("none", "n/a", \u2026). Name at least one concrete non-goal: files or areas not to touch, changes not to make, features not to add.',
+      hint: 'There is always an edge worth stating \u2014 "read-only, no edits", "no dependency changes", "do not touch other packages". If truly nothing comes to mind, the task is not decomposed enough yet.'
+    };
+  }
+  return { ok: true, boundary: { scope, outOfScope: concrete } };
+}
+function renderTaskBoundaryBlock(boundary) {
+  return [
+    "\u2500\u2500 TASK BOUNDARY (hard contract \u2014 these lines define your edges) \u2500\u2500",
+    `Scope (what this task covers):
+${boundary.scope}`,
+    `Out of scope (explicit non-goals \u2014 do NOT do any of these):
+${boundary.outOfScope.map((item) => `- ${item}`).join("\n")}`
+  ].join("\n");
+}
+function composeBoundedTaskDescription(objective, boundary) {
+  return `${objective.trim()}
+
+${renderTaskBoundaryBlock(boundary)}`;
+}
+var taskBoundarySchemaProperties = {
+  scope: {
+    type: "string",
+    description: "REQUIRED. One concrete sentence stating what work this task covers \u2014 the in-bounds. The call is rejected without it."
+  },
+  outOfScope: {
+    type: "array",
+    items: { type: "string", minLength: 1 },
+    description: 'REQUIRED. At least one explicit non-goal the worker must NOT do (files/areas not to touch, changes not to make, features not to add). Placeholders like "none" are rejected.'
+  }
+};
+
+// src/coordination/director-basic-tools.ts
 function makeAssignTool(director) {
   const inputSchema = {
     type: "object",
@@ -31224,8 +31304,9 @@ function makeAssignTool(director) {
       description: {
         type: "string",
         minLength: 1,
-        description: "The task in natural language \u2014 what you want this subagent to do."
+        description: "The objective in natural language \u2014 what you want this subagent to do. Pair it with the required `scope` and `outOfScope` boundary fields."
       },
+      ...taskBoundarySchemaProperties,
       maxToolCalls: {
         type: "number",
         minimum: 1,
@@ -31233,20 +31314,28 @@ function makeAssignTool(director) {
       },
       timeoutMs: { type: "number", minimum: 1, description: "Optional per-task timeout in ms." }
     },
-    required: ["subagentId", "description"]
+    required: ["subagentId", "description", "scope", "outOfScope"]
   };
   return {
     name: "assign_task",
-    description: "Queue a task on a previously spawned subagent. NON-BLOCKING: returns a `taskId` IMMEDIATELY \u2014 the subagent processes the task on its next iteration with its own LLM budget. The `taskId` is the durable handle for retrieving the result later via `await_tasks`, `roll_up`, or `ask_result`. Many `assign_task` calls can be in flight in parallel against the same or different subagents. This is the primary tool for fan-out work; do NOT use `delegate` to spawn multiple investigations sequentially.",
+    description: "Queue a task on a previously spawned subagent. NON-BLOCKING: returns a `taskId` IMMEDIATELY \u2014 the subagent processes the task on its next iteration with its own LLM budget. The `taskId` is the durable handle for retrieving the result later via `await_tasks`, `roll_up`, or `ask_result`. Every assignment MUST carry an explicit boundary: `scope` (what the work covers) and `outOfScope` (at least one concrete non-goal) \u2014 the call is rejected without them, and the worker treats the rendered boundary block as a hard contract. Many `assign_task` calls can be in flight in parallel against the same or different subagents. This is the primary tool for fan-out work; do NOT use `delegate` to spawn multiple investigations sequentially.",
     permission: "auto",
     mutating: false,
     capabilities: [ToolCapabilities.SUBAGENT_SPAWN],
     inputSchema,
     async execute(input) {
       const i = input;
+      const boundary = parseTaskBoundary(i);
+      if (!boundary.ok) {
+        return {
+          ok: false,
+          error: `assign_task rejected \u2014 task boundary incomplete: ${boundary.error}`,
+          hint: boundary.hint
+        };
+      }
       const task = {
         id: randomUUID12(),
-        description: i.description,
+        description: composeBoundedTaskDescription(i.description, boundary.boundary),
         subagentId: i.subagentId,
         maxToolCalls: i.maxToolCalls,
         timeoutMs: i.timeoutMs
@@ -39083,8 +39172,8 @@ var DefaultMultiAgentCoordinator = class _DefaultMultiAgentCoordinator extends E
   withNickname(subagent, subagentId) {
     const role = subagent.role ?? "subagent";
     const name = subagent.name?.trim() ?? "";
-    const isPlaceholder = name === "" || name.toLowerCase() === role.toLowerCase() || name === "subagent" || name === "adhoc" || name === "generic" || /^slot-/.test(name);
-    if (!isPlaceholder) return subagent;
+    const isPlaceholder2 = name === "" || name.toLowerCase() === role.toLowerCase() || name === "subagent" || name === "adhoc" || name === "generic" || /^slot-/.test(name);
+    if (!isPlaceholder2) return subagent;
     const { key, display } = assignNickname(role, this.usedNicknames);
     this.usedNicknames.add(key);
     this.subagentNicknames.set(subagentId, key);
@@ -43320,8 +43409,9 @@ function createDelegateTool(opts) {
     properties: {
       task: {
         type: "string",
-        description: "What the subagent should do \u2014 natural language, complete sentence(s)."
+        description: "The objective \u2014 what the subagent should do, natural language, complete sentence(s). Pair it with the required `scope` and `outOfScope` boundary fields."
       },
+      ...taskBoundarySchemaProperties,
       role: {
         type: "string",
         description: rosterIds.length > 0 ? "Roster role id. Common: bug-hunter, security-scanner, refactor-planner, critic, audit-log, executor, shadow-agent, architect." : "No roster configured \u2014 pass `name` instead."
@@ -43379,12 +43469,12 @@ function createDelegateTool(opts) {
         description: "Max fresh-worker continuations after budget exhaustion. Default 1. Each gets the prior partial report."
       }
     },
-    required: ["task"]
+    required: ["task", "scope", "outOfScope"]
   };
   return {
     name: "delegate",
     description: "Hand a piece of work to a subagent and block until it returns. This call is synchronous: the leader's iteration pauses for the full duration of the subagent's run. (Multiple `delegate` calls fired in the same assistant turn still parallelize through the provider's parallel-tool-call surface, but each one eats wall-clock time \u2014 so for fan-out you actually control, reach for the async path below.) Use `delegate` when your next step genuinely needs the subagent's verdict \u2014 a review, a fact-check, a sign-off. Has own context, own LLM call, auto-extending budget, and a partial-completion handoff path (maxHandoffs, default 1). Workers cannot recursively spawn.\n\n**Do NOT use `delegate` for long-running work.** While `delegate` is in flight, the leader is fully blocked \u2014 it cannot act on other tools, read mail, or react to the user. If the work might run for tens of minutes or hours (multi-file refactor, monorepo audit, long-running build/test, sweeping migration), the blocking call wastes the leader's time. Use the async tool family instead: `spawn_subagent` to create each worker (returns a `subagentId` immediately), `assign_task` to queue work on it (returns a `taskId` immediately), then `await_tasks` to retrieve results later. The leader keeps doing other work while the worker churns, and a worker that realizes its task will run long can mail the leader (type `steer` or `ask` via `mail_send`) saying *\"my task is going to run long, please spawn a subagent instead\"* so the leader re-dispatches asynchronously instead of waiting.\n\n**Do NOT use `delegate` for fan-out you control.** Multiple sequential `delegate` calls each block the leader, wasting wall-clock time. For independent investigations you want to run in parallel \u2014 security scan + bug hunt + perf review on the same PR \u2014 use the async tool family: `spawn_subagent` to create each worker (returns a `subagentId` immediately), `assign_task` to queue work on it (returns a `taskId` immediately), then the `await_tasks` tool with `{mode: 'any'}` to fold the first useful result into the next decision while the rest keep churning. Reach for `delegate` only when the result gates your next move AND the work is short enough that blocking the leader is acceptable.",
-    usageHint: "Set `task` to a complete instruction. Pick `role` from roster or pass `name` for free-form. Reach for `delegate` only when the result gates your next move AND the work is short enough that blocking the leader is acceptable (minutes, not hours). For long-running work or fan-out you control, use `spawn_subagent` + `assign_task` + `await_tasks` instead. Raise `maxHandoffs` (default 1, cap 8) for multi-day or multi-refactor tasks; pass larger `timeoutMs`/`maxIterations`/`maxToolCalls` only when needed.",
+    usageHint: "Set `task` to the objective, then make the edges explicit: `scope` (what the work covers) and `outOfScope` (at least one concrete non-goal) are REQUIRED \u2014 the call is rejected without them, and the worker treats the rendered boundary block as a hard contract. Pick `role` from roster or pass `name` for free-form. Reach for `delegate` only when the result gates your next move AND the work is short enough that blocking the leader is acceptable (minutes, not hours). For long-running work or fan-out you control, use `spawn_subagent` + `assign_task` + `await_tasks` instead. Raise `maxHandoffs` (default 1, cap 8) for multi-day or multi-refactor tasks; pass larger `timeoutMs`/`maxIterations`/`maxToolCalls` only when needed.",
     permission: "auto",
     mutating: false,
     managesOwnTimeout: true,
@@ -43404,6 +43494,14 @@ function createDelegateTool(opts) {
           error: "Delegation cancelled before spawn \u2014 the run was interrupted."
         };
       }
+      const boundary = parseTaskBoundary(i);
+      if (!boundary.ok) {
+        return {
+          ok: false,
+          error: `delegate rejected \u2014 task boundary incomplete: ${boundary.error}`,
+          hint: boundary.hint
+        };
+      }
       const target = i.role ?? i.name ?? "subagent";
       const launchModePreface = [
         "Launch-mode guidance (delegate): you were launched via the synchronous `delegate` tool, so the leader is blocked on this call for the full duration of your run.",
@@ -43474,7 +43572,8 @@ function createDelegateTool(opts) {
         const dir = director;
         const maxHandoffs = Math.min(8, Math.max(0, Math.floor(i.maxHandoffs ?? 1)));
         const handoffs = [];
-        let delegatedTask = i.task;
+        const baseBrief = composeBoundedTaskDescription(i.task, boundary.boundary);
+        let delegatedTask = baseBrief;
         let handoffCount = 0;
         for (; ; ) {
           const attemptConfig = (() => {
@@ -43614,7 +43713,7 @@ function createDelegateTool(opts) {
               remainingWork: continuation.remainingWork
             });
             handoffCount += 1;
-            delegatedTask = buildHandoffTask(i.task, continuation, handoffCount, maxHandoffs);
+            delegatedTask = buildHandoffTask(baseBrief, continuation, handoffCount, maxHandoffs);
             continue;
           }
           const incomplete = result.report?.completion === "partial";
@@ -58285,7 +58384,7 @@ function readContextWindowPolicy(ctx) {
 function installSubagentAutoCompaction(pipelines, ctx, contextConfig, events) {
   const maxContext = ctx.provider?.capabilities?.maxContext ?? 0;
   if (!(maxContext > 0)) return void 0;
-  const policy = resolveContextWindowPolicy(contextConfig ?? {});
+  const policy = resolveContextWindowPolicy(contextConfig ?? {}, void 0, maxContext);
   ctx.meta ??= {};
   ctx.meta["contextWindowPolicy"] = policy;
   const compactor = new HybridCompactor({
@@ -97079,6 +97178,7 @@ export {
   COMPLETED_WORK_LEDGER_MARKER,
   CONFIG_BEHAVIOR_DEFAULTS,
   CONTEXT_WINDOW_MODES,
+  CONTEXT_WINDOW_MODE_PINNED_META_KEY,
   CORE_RECONSTRUCT_EVENTS,
   COUNCIL_JUDGE_PROMPT_PATH,
   COUNCIL_REFUSAL_OPTION_ID,
@@ -97270,6 +97370,7 @@ export {
   KNOWN_TOKEN_GROUPS,
   KNOWN_TOKEN_NAMES,
   KnowledgeGraph,
+  LARGE_WINDOW_DEEP_MODE_THRESHOLD,
   LAYER_1_IDENTITY,
   LEADER_MODEL_SET_TOOL_NAME,
   LEARNED_HARD_LIMIT,
@@ -97546,6 +97647,7 @@ export {
   compileUserRegex,
   completeBrainLlm,
   completePartialObject,
+  composeBoundedTaskDescription,
   composeDirectorPrompt,
   composeSubagentPrompt,
   computeMessageTokens,
@@ -97963,6 +98065,7 @@ export {
   parseReviewSeverity,
   parseSkillFrontmatter,
   parseSkillRef,
+  parseTaskBoundary,
   peekQueuedMessages,
   pendingBtwCount,
   persistReviewReport,
@@ -98021,6 +98124,7 @@ export {
   renderPrometheus,
   renderPrompt,
   renderSkillAugmentation,
+  renderTaskBoundaryBlock,
   repairConfigDefaults,
   repairToolUseAdjacency,
   repeatedReadPressure,
@@ -98185,6 +98289,7 @@ export {
   syncReportCompletion,
   syncReportReopen,
   takeHeapSample,
+  taskBoundarySchemaProperties,
   terminalPolicyDecision,
   tightenHqRedactionPolicy,
   toAlertMessage,

package/dist/infrastructure/index.js

@@ -2895,7 +2895,7 @@ var CONTEXT_WINDOW_MODES = Object.freeze([
   {
     id: "balanced",
     name: "Balanced",
-    description: "Default rolling compaction: recent work stays verbatim, old tool output is trimmed.",
+    description: "Default rolling compaction: recent work stays verbatim, old tool output is trimmed. Windows of 1M+ tokens default to Deep.",
     thresholds: { warn: 0.55, soft: 0.7, hard: 0.85 },
     aggressiveOn: "soft",
     preserveK: 8,

package/dist/storage/index.js

@@ -4656,7 +4656,7 @@ var CONTEXT_WINDOW_MODES = Object.freeze([
   {
     id: "balanced",
     name: "Balanced",
-    description: "Default rolling compaction: recent work stays verbatim, old tool output is trimmed.",
+    description: "Default rolling compaction: recent work stays verbatim, old tool output is trimmed. Windows of 1M+ tokens default to Deep.",
     thresholds: { warn: 0.55, soft: 0.7, hard: 0.85 },
     aggressiveOn: "soft",
     preserveK: 8,

package/dist/types/context-window.d.ts

@@ -45,6 +45,23 @@ export interface ContextWindowConfigLike {
     targetLoad?: number | undefined;
 }
 export declare const DEFAULT_CONTEXT_WINDOW_MODE_ID: ContextWindowModeId;
+/**
+ * Windows at or above this size default to the `deep` policy instead of
+ * `balanced`: 1M-class windows exist to be filled, and balanced's hard line
+ * (0.85) would compact at ~890K of a 1.05M window, stranding the tail. Deep
+ * holds compaction until 0.96 and keeps a wider verbatim tail. An explicit
+ * `frugal`/`deep` choice, custom modes, and per-field threshold overrides are
+ * always respected as-is; only the balanced default is swapped.
+ */
+export declare const LARGE_WINDOW_DEEP_MODE_THRESHOLD = 1000000;
+/**
+ * Meta key the mode-switch surfaces (`/context mode`, WebUI `context.mode.switch`,
+ * `/context thresholds`) set after the user deliberately picks a policy for the
+ * session. Window-change flows re-resolve the default policy against the new
+ * window (so a 1M↔200K model switch keeps the policy scaled to the window) but
+ * must leave a user-pinned choice alone.
+ */
+export declare const CONTEXT_WINDOW_MODE_PINNED_META_KEY = "contextWindowModePinned";
 export declare const DEPRECATED_CONTEXT_WINDOW_MODE_ALIASES: Readonly<Record<DeprecatedContextWindowModeId, ContextWindowModeId>>;
 export declare const CONTEXT_WINDOW_MODES: readonly ContextWindowMode[];
 export declare function listContextWindowModes(): ContextWindowMode[];
@@ -53,6 +70,6 @@ export declare function isDeprecatedContextWindowModeId(id: string): id is Depre
 export declare function isContextWindowModeSelectionId(id: string): id is ContextWindowModeSelectionId;
 export declare function getContextWindowMode(id: string | null | undefined): ContextWindowMode | null;
 export declare function isContextWindowModeId(id: string): id is ContextWindowModeId;
-export declare function resolveContextWindowPolicy(config?: ContextWindowConfigLike, overrideMode?: string | null | undefined): ContextWindowPolicy;
+export declare function resolveContextWindowPolicy(config?: ContextWindowConfigLike, overrideMode?: string | null | undefined, maxContext?: number | undefined): ContextWindowPolicy;
 export declare function formatContextWindowModeList(activeId?: string | null): string;
 //# sourceMappingURL=context-window.d.ts.map

package/dist/types/index.d.ts

@@ -7,7 +7,7 @@ export type { AdaptiveConcurrencyConfig, AgentLearningConfig, AutonomyConfig, Br
 export { DEFAULT_TUI_THINKING_WORD, FLEET_CHAT_VERBOSITY_VALUES, MAX_TUI_THINKING_WORD_LENGTH, normalizeTokenSavingTier, normalizeTuiThinkingWord, resolveFleetChatVerbosity, resolveTokenSavingTier, THEME_PRESET_IDS, } from './config.js';
 export type { CompletedWorkEvidence, CompletedWorkSource, ContextEvidenceState, ContextFileEvidence, ContextIntentEvidence, ContextRepeatedReadEvidence, ToolEvidenceStatus, ToolOutputMetadata, } from './context-evidence.js';
 export type { ContextSnapshot, ContextWindowAggressiveOn, ContextWindowConfigLike, ContextWindowMode, ContextWindowModeId, ContextWindowModeSelectionId, ContextWindowPolicy, ContextWindowThresholds, DeprecatedContextWindowModeId, } from './context-window.js';
-export { CONTEXT_WINDOW_MODES, DEFAULT_CONTEXT_WINDOW_MODE_ID, DEPRECATED_CONTEXT_WINDOW_MODE_ALIASES, formatContextWindowModeList, getContextWindowMode, isContextWindowModeId, isContextWindowModeSelectionId, isDeprecatedContextWindowModeId, listContextWindowModes, normalizeContextWindowModeId, resolveContextWindowPolicy, } from './context-window.js';
+export { CONTEXT_WINDOW_MODES, CONTEXT_WINDOW_MODE_PINNED_META_KEY, DEFAULT_CONTEXT_WINDOW_MODE_ID, DEPRECATED_CONTEXT_WINDOW_MODE_ALIASES, LARGE_WINDOW_DEEP_MODE_THRESHOLD, formatContextWindowModeList, getContextWindowMode, isContextWindowModeId, isContextWindowModeSelectionId, isDeprecatedContextWindowModeId, listContextWindowModes, normalizeContextWindowModeId, resolveContextWindowPolicy, } from './context-window.js';
 export type { CouncilDistinctness, CouncilLLMCaller, CouncilModelTarget, CouncilOption, CouncilPersona, CouncilProfileConfig, CouncilQuestion, CouncilResolutionMethod, CouncilResult, CouncilSeatConfig, CouncilUsage, CouncilVoteResult, CouncilVoteStatus, ResolvedCouncilProfile, ResolvedCouncilSeat, } from './council.js';
 export { DEFAULT_AUTONOMY_CONFIG, DEFAULT_CIRCUIT_BREAKER_CONFIG, DEFAULT_CONTEXT_CONFIG, DEFAULT_SESSION_LOGGING_CONFIG, DEFAULT_SESSION_PRUNE_DAYS, DEFAULT_TOOLS_CONFIG, } from './default-config.js';
 export type { DesignKitEntry, DesignKitLoader, DesignKitManifest, DesignKitTokens, DesignStack, DesignStudioState, DesignTokenSet, TokenValueKind, } from './design-kit.js';

package/dist/types/index.js

@@ -111,6 +111,8 @@ function expectDefined(value, label) {
 
 // src/types/context-window.ts
 var DEFAULT_CONTEXT_WINDOW_MODE_ID = "balanced";
+var LARGE_WINDOW_DEEP_MODE_THRESHOLD = 1e6;
+var CONTEXT_WINDOW_MODE_PINNED_META_KEY = "contextWindowModePinned";
 var DEPRECATED_CONTEXT_WINDOW_MODE_ALIASES = Object.freeze({
   archival: "balanced"
 });
@@ -118,7 +120,7 @@ var CONTEXT_WINDOW_MODES = Object.freeze([
   {
     id: "balanced",
     name: "Balanced",
-    description: "Default rolling compaction: recent work stays verbatim, old tool output is trimmed.",
+    description: "Default rolling compaction: recent work stays verbatim, old tool output is trimmed. Windows of 1M+ tokens default to Deep.",
     thresholds: { warn: 0.55, soft: 0.7, hard: 0.85 },
     aggressiveOn: "soft",
     preserveK: 8,
@@ -169,9 +171,11 @@ function getContextWindowMode(id) {
 function isContextWindowModeId(id) {
   return CONTEXT_WINDOW_MODES.some((m) => m.id === id);
 }
-function resolveContextWindowPolicy(config = {}, overrideMode) {
+function resolveContextWindowPolicy(config = {}, overrideMode, maxContext) {
   const requested = overrideMode ?? config.mode ?? DEFAULT_CONTEXT_WINDOW_MODE_ID;
-  const mode = getContextWindowMode(requested) ?? expectDefined(getContextWindowMode(DEFAULT_CONTEXT_WINDOW_MODE_ID));
+  const normalized = normalizeContextWindowModeId(requested) ?? DEFAULT_CONTEXT_WINDOW_MODE_ID;
+  const baseId = normalized === DEFAULT_CONTEXT_WINDOW_MODE_ID && typeof maxContext === "number" && maxContext >= LARGE_WINDOW_DEEP_MODE_THRESHOLD ? "deep" : normalized;
+  const mode = expectDefined(getContextWindowMode(baseId));
   return {
     ...mode,
     thresholds: {
@@ -1313,6 +1317,7 @@ export {
   BUILTIN_PROMPT_CATEGORIES,
   CHAT_MARKER_SOURCES,
   CONTEXT_WINDOW_MODES,
+  CONTEXT_WINDOW_MODE_PINNED_META_KEY,
   ConfigError,
   DEFAULT_AUTONOMY_CONFIG,
   DEFAULT_CIRCUIT_BREAKER_CONFIG,
@@ -1333,6 +1338,7 @@ export {
   GOVERNED_TOOL_EXECUTOR_META_KEY,
   KNOWN_TOKEN_GROUPS,
   KNOWN_TOKEN_NAMES,
+  LARGE_WINDOW_DEEP_MODE_THRESHOLD,
   MALFORMED_ARG_MARKERS,
   MAX_TUI_THINKING_WORD_LENGTH,
   MEMORY_TYPE_LABELS,

package/instructions/coordination/director-preamble.md

@@ -48,7 +48,7 @@ For controlled fan-out, use `spawn_subagent` → `assign_task` →
 
 ## Dispatch contract
 
-Every assigned task should state:
+Every assigned task must state:
 
 - the objective and why it matters;
 - exact scope and non-goals;
@@ -58,6 +58,14 @@ Every assigned task should state:
 - the narrowest required verification;
 - known dependencies, risks, and assumptions.
 
+The assignment tools enforce the boundary: `delegate` and `assign_task` reject
+any call without an explicit `scope` (what the work covers) and at least one
+concrete `outOfScope` non-goal (what the worker must not do). Treat a
+rejection as a design checkpoint, not paperwork — if you cannot name what is
+out of scope, the task is not decomposed enough yet. The boundary is rendered
+into the worker's brief as a hard contract and survives into handoff
+continuations, so write it once, precisely.
+
 Match role and model to the work: use economical workers for bounded discovery
 and capable workers for ambiguous implementation or synthesis. Provider
 diversity is useful for independent review, not an end in itself.

package/instructions/coordination/subagent-baseline.md

@@ -7,6 +7,10 @@ self-contained handoff; do not take over fleet orchestration.
 - Treat the assigned objective, scope, write authority, non-goals, and
   completion criteria as your boundary. Later role, task, and per-spawn
   instructions may narrow this baseline.
+- Your brief carries an explicit "TASK BOUNDARY" block (scope plus
+  out-of-scope non-goals). It is a hard contract, not a suggestion: stay
+  inside it even when an out-of-scope change looks quick or obviously right —
+  report it back instead of doing it.
 - Inspect before editing. Resolve discoverable context yourself and use the
   project's existing conventions, tests, and tooling.
 - Make only task-relevant changes. Preserve unrelated work and avoid broad

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/core",
-  "version": "0.308.1",
+  "version": "0.308.2",
   "license": "MIT",
   "description": "WrongStack core: kernel, types, defaults, and shared utilities for the WrongStack CLI agent.",
   "repository": {
@@ -94,7 +94,8 @@
     },
     "./storage": {
       "types": "./dist/storage/index.d.ts",
-      "import": "./dist/storage/index.js"
+      "import": "./dist/storage/index.js",
+      "require": "./dist/storage/index.js"
     },
     "./session-catalog": {
       "types": "./dist/session-catalog/index.d.ts",
@@ -181,8 +182,8 @@
   "wrongstackApiVersion": "0.1.10",
   "dependencies": {
     "zod": "4.4.3",
-    "@wrongstack/kanban": "0.308.1",
-    "@wrongstack/persistence": "0.308.1"
+    "@wrongstack/persistence": "0.308.2",
+    "@wrongstack/kanban": "0.308.2"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",