pi-taskflow 0.0.22 → 0.0.23

package/extensions/schema.ts

@@ -8,6 +8,7 @@
 import * as path from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
+import { WORKSPACE_KEYWORDS } from "./workspace.ts";
 
 // ---------------------------------------------------------------------------
 // Phase types
@@ -208,7 +209,7 @@ const PhaseSchema = Type.Object(
 		model: Type.Optional(Type.String({ description: "Model override for this phase" })),
 		thinking: Type.Optional(Type.String({ description: "Thinking level override for this phase" })),
 		tools: Type.Optional(Type.Array(Type.String(), { description: "Restrict tools for this phase's agent" })),
-		cwd: Type.Optional(Type.String({ description: "Working directory for this phase's subagent" })),
+		cwd: Type.Optional(Type.String({ description: "Working directory for this phase's subagent. A literal path, or a reserved keyword: 'temp' (ephemeral dir, removed after the phase), 'dedicated' (persistent dir under the run state, kept), or 'worktree' (a git worktree on a throwaway branch, removed after the phase)." })),
 		final: Type.Optional(Type.Boolean({ description: "Mark this phase's output as the workflow result" })),
 		optional: Type.Optional(
 			Type.Boolean({ description: "If true, a failure does not abort the run", default: false }),
@@ -240,6 +241,12 @@ const PhaseSchema = Type.Object(
 			}),
 		),
 		cache: Type.Optional(CacheSchema),
+		shareContext: Type.Optional(
+			Type.Boolean({
+				description:
+					"Opt into the Shared Context Tree for this phase: the subagent gets ctx_read/ctx_write (a blackboard shared with siblings/ancestors, to avoid re-reading files) and ctx_report/ctx_spawn (report upward + queue child tasks the runtime picks up). Default false — existing flows are unaffected.",
+			}),
+		),
 	},
 	{ additionalProperties: false },
 );
@@ -271,6 +278,12 @@ export const TaskflowSchema = Type.Object(
 				default: false,
 			}),
 		),
+		contextSharing: Type.Optional(
+			Type.Boolean({
+				description:
+					"Enable the Shared Context Tree for ALL phases in this flow (shorthand for setting shareContext on every phase). Default false.",
+			}),
+		),
 		phases: Type.Array(PhaseSchema, { minItems: 1, description: "Ordered phase definitions (DAG via dependsOn)" }),
 	},
 	{ additionalProperties: false },
@@ -485,11 +498,18 @@ export function validateTaskflow(def: unknown, opts: ValidationOptions = {}): Va
 			if (typeof p.concurrency === "number" && p.concurrency > MAX_DYNAMIC_CONCURRENCY) {
 				errors.push(`Dynamic sub-flow phase '${p.id}': concurrency too high (${p.concurrency}, max ${MAX_DYNAMIC_CONCURRENCY})`);
 			}
-			// cwd containment: a generated phase may not escape the run's cwd.
-			if (typeof p.cwd === "string" && root) {
-				const resolved = path.resolve(root, p.cwd);
-				if (resolved !== root && !resolved.startsWith(root + path.sep)) {
-					errors.push(`Dynamic sub-flow phase '${p.id}': cwd '${p.cwd}' escapes the run directory`);
+			// cwd containment: a generated phase may not escape the run's cwd, and
+			// may not request a reserved workspace keyword (temp/dedicated/worktree)
+			// — LLM-authored sub-flows must not allocate isolated dirs or git
+			// worktrees that mutate the repo. Only author-written flows may.
+			if (typeof p.cwd === "string") {
+				if (WORKSPACE_KEYWORDS.includes(p.cwd as (typeof WORKSPACE_KEYWORDS)[number])) {
+					errors.push(`Dynamic sub-flow phase '${p.id}': cwd '${p.cwd}' is a reserved workspace keyword not allowed in generated flows`);
+				} else if (root) {
+					const resolved = path.resolve(root, p.cwd);
+					if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+						errors.push(`Dynamic sub-flow phase '${p.id}': cwd '${p.cwd}' escapes the run directory`);
+					}
 				}
 			}
 		}
@@ -508,6 +528,14 @@ export function validateTaskflow(def: unknown, opts: ValidationOptions = {}): Va
 		if (ids.has(p.id)) errors.push(`Duplicate phase id: ${p.id}`);
 		ids.add(p.id);
 
+		// When a phase opts into the Shared Context Tree, its id becomes a filesystem
+		// node id; restrict the charset so two ids can't sanitize to the same node
+		// (which would silently merge their blackboards). Non-sharing phases are
+		// unaffected (full backward compat).
+		if ((p.shareContext === true || flow.contextSharing === true) && !/^[A-Za-z0-9._-]+$/.test(p.id)) {
+			errors.push(`Phase '${p.id}': ids used with context sharing must match [A-Za-z0-9._-]+`);
+		}
+
 		const type = (p.type ?? "agent") as PhaseType;
 		if (!PHASE_TYPES.includes(type)) errors.push(`Phase '${p.id}': unknown type '${type}'`);
 

package/extensions/store.ts

@@ -190,13 +190,14 @@ function lockPathForRun(runsRoot: string, flowName: string, runId: string): stri
  * Validate that a runId looks safe before performing any filesystem access.
  * Legitimate runIds are produced by newRunId() and contain only [A-Za-z0-9._-].
  */
-function validateRunId(runId: string): boolean {
+export function validateRunId(runId: string): boolean {
 	return (
 		typeof runId === "string" &&
 		runId.length > 0 &&
 		!runId.includes("/") &&
 		!runId.includes("\\") &&
-		!runId.includes("\0")
+		!runId.includes("\0") &&
+		!runId.includes("..")
 	);
 }
 
@@ -509,6 +510,16 @@ function cleanupTerminalRuns(
 		try { fs.unlinkSync(filePath); } catch { /* already gone */ }
 		// Also remove any orphaned lock file.
 		try { fs.unlinkSync(filePath + ".lock"); } catch { /* ignore */ }
+		// Also remove the per-run Shared Context Tree directory (C6). Orphaned
+		// ctx dirs would otherwise accumulate under runs/ctx/ over many runs.
+		try { fs.rmSync(path.join(runsRoot, "ctx", e.runId), { recursive: true, force: true }); } catch { /* ignore */ }
+		// Also remove the per-run isolated-workspace dir tree (cwd:"dedicated").
+		// `dedicated` workspaces are persistent by design; reclaim them once the
+		// run is pruned. The dir name uses the same sanitization as workspace.ts.
+		try {
+			const wsSeg = e.runId.replace(/[^A-Za-z0-9._-]/g, "_").replace(/^\.+/, "_").slice(0, 100) || "phase";
+			fs.rmSync(path.join(runsRoot, "ws", wsSeg), { recursive: true, force: true });
+		} catch { /* ignore */ }
 	}
 
 	// Remove empty flow subdirectories.
@@ -622,7 +633,7 @@ export function saveFlow(
 
 // --- Run state ---
 
-function runsDir(cwd: string): string {
+export function runsDir(cwd: string): string {
 	// Safe non-null assertion: create=true guarantees a non-null return because
 	// findProjectFlowsDirInternal falls back to path.join(cwd, ".pi", "taskflows").
 	const projDir = findProjectFlowsDir(cwd, true)!;
@@ -636,7 +647,9 @@ export function cacheDir(cwd: string): string {
 }
 
 export function newRunId(flowName: string): string {
-	const safe = flowName.replace(/[^\w.-]+/g, "_").slice(0, 24);
+	// Collapse to a safe charset AND fold any dot-runs so the result can never
+	// contain a '..' traversal token (validateRunId rejects '..').
+	const safe = flowName.replace(/[^\w.-]+/g, "_").replace(/\.{2,}/g, "_").slice(0, 24);
 	return `${safe}-${Date.now().toString(36)}-${crypto.randomBytes(3).toString("hex")}`;
 }
 

package/extensions/workspace.ts

@@ -0,0 +1,206 @@
+/**
+ * Per-phase workspace isolation ("worktree isolation", STRATEGY H2).
+ *
+ * By default a phase's `cwd` is a literal path (or inherited from the run).
+ * Three reserved keywords ask the runtime to ALLOCATE an isolated working
+ * directory for the phase's subagent(s) and tear it down afterwards:
+ *
+ *   - `"temp"`      — an ephemeral dir under the OS tmpdir; removed when the
+ *                     phase finishes (success or failure). For scratch work that
+ *                     must not touch the main tree.
+ *   - `"dedicated"` — a persistent dir under the run's own state directory
+ *                     (`<runs>/ws/<runId>/<phaseId>`); kept after the phase so
+ *                     its artifacts survive for inspection / downstream reuse.
+ *                     Idempotent across resume (same path for the same phase).
+ *   - `"worktree"`  — a real `git worktree` on a throwaway branch, rooted at the
+ *                     run's git repo; removed (`git worktree remove --force`)
+ *                     when the phase finishes. For changes you want to diff /
+ *                     commit / discard in isolation. Falls back to a `temp` dir
+ *                     (fail-open) when the base dir is not a git work tree.
+ *
+ * Invariants honoured (AGENTS.md "Critical invariants"):
+ *  - Fail-open: any allocation/teardown error degrades gracefully and never
+ *    sinks the phase (a failed allocation falls back to the base cwd).
+ *  - No new deps: OS tmpdir via `fs.mkdtemp`, git via `child_process` (already
+ *    a peer of the runner). No third-party libraries.
+ *  - Resume-safe: `dedicated` is deterministic per (runId, phaseId) so a resume
+ *    reuses the same dir; `temp`/`worktree` are re-allocated cleanly.
+ *  - Path containment: `dedicated` dirs are contained under the run dir;
+ *    sanitized phase ids prevent traversal.
+ */
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** The reserved `cwd` keywords that trigger workspace allocation. */
+export const WORKSPACE_KEYWORDS = ["temp", "dedicated", "worktree"] as const;
+export type WorkspaceKind = (typeof WORKSPACE_KEYWORDS)[number];
+
+export function isWorkspaceKeyword(cwd: string | undefined): cwd is WorkspaceKind {
+	return cwd === "temp" || cwd === "dedicated" || cwd === "worktree";
+}
+
+/** A handle to an allocated workspace. `dir` is where the subagent runs. */
+export interface Workspace {
+	/** Resolved absolute working directory for the phase's subagent(s). */
+	dir: string;
+	/** What was actually allocated (may differ from requested on fail-open). */
+	kind: WorkspaceKind | "inherited";
+	/** Idempotent teardown — safe to call once, after the phase completes. */
+	teardown(): void;
+	/** For `worktree`: the throwaway branch name (diagnostics only). */
+	branch?: string;
+	/** Non-fatal diagnostic if allocation degraded (e.g. worktree→temp). */
+	note?: string;
+}
+
+/** A no-op workspace: the phase runs in `baseCwd` and nothing is torn down. */
+function inherited(baseCwd: string, note?: string): Workspace {
+	return { dir: baseCwd, kind: "inherited", note, teardown() {} };
+}
+
+/** Sanitize a phase id for use as a path segment (mirrors safeFlowDirName). */
+function safeSegment(id: string): string {
+	const cleaned = id.replace(/[^A-Za-z0-9._-]/g, "_").replace(/^\.+/, "_");
+	return cleaned.slice(0, 100) || "phase";
+}
+
+/**
+ * Best-effort recursive delete, restricted to dirs we ourselves allocate
+ * (under the OS tmpdir or a run's `ws/` tree). The containment check is
+ * defense-in-depth: every `dir` passed here is already constructed by this
+ * module, but guarding ensures a future caller can't turn `rmrf` into an
+ * arbitrary-path delete.
+ */
+function rmrf(dir: string, allowedRoots?: string[]): void {
+	try {
+		const resolved = path.resolve(dir);
+		const roots = [path.resolve(os.tmpdir()), ...(allowedRoots ?? []).map((r) => path.resolve(r))];
+		const contained = roots.some((root) => resolved === root || resolved.startsWith(root + path.sep));
+		if (!contained) return; // refuse to delete outside our own allocation roots
+		fs.rmSync(resolved, { recursive: true, force: true });
+	} catch {
+		/* fail-open: best-effort cleanup */
+	}
+}
+
+/** Is `dir` inside a git work tree? (cheap, no network, fail-closed to false) */
+function isGitRepo(dir: string): boolean {
+	try {
+		const r = spawnSync("git", ["-C", dir, "rev-parse", "--is-inside-work-tree"], {
+			encoding: "utf-8",
+			timeout: 5000,
+		});
+		return r.status === 0 && String(r.stdout).trim() === "true";
+	} catch {
+		return false;
+	}
+}
+
+/** The absolute toplevel of the git work tree containing `dir`, or undefined. */
+function gitToplevel(dir: string): string | undefined {
+	try {
+		const r = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
+			encoding: "utf-8",
+			timeout: 5000,
+		});
+		if (r.status === 0) return String(r.stdout).trim() || undefined;
+	} catch {
+		/* fall through */
+	}
+	return undefined;
+}
+
+interface AllocOpts {
+	/** The phase's effective base cwd (where it would run without isolation). */
+	baseCwd: string;
+	/** Run id — anchors `dedicated` dirs and names throwaway worktree branches. */
+	runId: string;
+	/** Phase id — second path segment / branch suffix. */
+	phaseId: string;
+	/** The run's state dir root (`runsDir(cwd)`) for `dedicated` workspaces. */
+	runsRoot: string;
+}
+
+/**
+ * Allocate an isolated workspace for a phase. Always returns a usable handle:
+ * on any failure it falls back to the base cwd (fail-open) with a `note`.
+ */
+export function allocateWorkspace(kind: WorkspaceKind, opts: AllocOpts): Workspace {
+	const { baseCwd, runId, phaseId, runsRoot } = opts;
+	const seg = safeSegment(phaseId);
+
+	if (kind === "temp") {
+		try {
+			const dir = fs.mkdtempSync(path.join(os.tmpdir(), `pi-tf-ws-${seg}-`));
+			return { dir, kind: "temp", teardown: () => rmrf(dir) };
+		} catch (e) {
+			return inherited(baseCwd, `temp workspace alloc failed: ${errMsg(e)}`);
+		}
+	}
+
+	if (kind === "dedicated") {
+		try {
+			// Deterministic per (runId, phaseId) → resume reuses the same dir.
+			const dir = path.join(runsRoot, "ws", safeSegment(runId), seg);
+			fs.mkdirSync(dir, { recursive: true });
+			// Persistent by design: teardown is a no-op (kept for inspection).
+			return { dir, kind: "dedicated", teardown() {} };
+		} catch (e) {
+			return inherited(baseCwd, `dedicated workspace alloc failed: ${errMsg(e)}`);
+		}
+	}
+
+	// kind === "worktree"
+	if (!isGitRepo(baseCwd)) {
+		// Fail-open: not a git repo → degrade to an ephemeral temp dir so the
+		// phase still gets isolation (just without git semantics).
+		const fb = allocateWorkspace("temp", opts);
+		return { ...fb, note: "worktree requested but base cwd is not a git work tree; used a temp dir instead" };
+	}
+	const top = gitToplevel(baseCwd) ?? baseCwd;
+	const branch = `tf/${safeSegment(runId)}/${seg}-${Date.now().toString(36)}`;
+	let dir: string;
+	try {
+		dir = fs.mkdtempSync(path.join(os.tmpdir(), `pi-tf-wt-${seg}-`));
+	} catch (e) {
+		const fb = allocateWorkspace("temp", opts);
+		return { ...fb, note: `worktree temp path alloc failed: ${errMsg(e)}` };
+	}
+	// `git worktree add -b <branch> <dir>` creates the dir's contents itself, so
+	// remove the empty mkdtemp dir first and let git recreate it.
+	rmrf(dir);
+	const add = spawnSync("git", ["-C", top, "worktree", "add", "-b", branch, dir, "HEAD"], {
+		encoding: "utf-8",
+		timeout: 60000,
+	});
+	if (add.status !== 0) {
+		rmrf(dir);
+		const fb = allocateWorkspace("temp", opts);
+		return {
+			...fb,
+			note: `git worktree add failed (${String(add.stderr).trim().slice(0, 200)}); used a temp dir instead`,
+		};
+	}
+	const teardown = () => {
+		// Remove the worktree, then delete its throwaway branch. Both best-effort.
+		try {
+			spawnSync("git", ["-C", top, "worktree", "remove", "--force", dir], { timeout: 30000 });
+		} catch {
+			/* fall through to rmrf */
+		}
+		rmrf(dir);
+		try {
+			spawnSync("git", ["-C", top, "branch", "-D", branch], { timeout: 10000 });
+		} catch {
+			/* fail-open: leftover branch is harmless */
+		}
+	};
+	return { dir, kind: "worktree", branch, teardown };
+}
+
+function errMsg(e: unknown): string {
+	return e instanceof Error ? e.message : String(e);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-taskflow",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "description": "A declarative, verifiable graph of task nodes for the Pi coding agent — not a workflow you script, but a DAG you declare: statically verified before it runs, with dynamic fan-out, gates, isolated subagent context, resumable runs, and saveable commands.",
   "keywords": [
     "pi-package",
@@ -37,8 +37,12 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "PI_TASKFLOW_BUILTIN_AGENTS_DIR= node --experimental-strip-types --test test/interpolate.test.ts test/condition.test.ts test/schema.test.ts test/usage.test.ts test/runtime.test.ts test/features.test.ts test/runner.test.ts test/store.test.ts test/agents.test.ts test/init.test.ts test/render.test.ts test/approval-view.test.ts test/desugar.test.ts test/cache.test.ts test/loop.test.ts test/tournament.test.ts test/verify.test.ts test/gate-eval.test.ts test/transient-error.test.ts test/runtime-branches.test.ts test/interpolate-extended.test.ts test/store-extended.test.ts test/flow-def.test.ts test/detached.test.ts test/runs-view.test.ts",
+    "test": "PI_TASKFLOW_BUILTIN_AGENTS_DIR= node --experimental-strip-types --test 'test/*.test.ts'",
     "test:e2e": "PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e.mts",
+    "test:e2e-context": "PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e-context.mts",
+    "test:e2e-context-value": "PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e-context-value.mts",
+    "test:e2e-team": "PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e-team.mts",
+    "test:e2e-spawn-subflow": "PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e-spawn-subflow.mts",
     "test:dogfood-cache": "node --experimental-strip-types test/dogfood-cache.mts"
   },
   "pi": {

package/skills/taskflow/SKILL.md

@@ -253,6 +253,34 @@ of several drafts, or a synthesis of diverse approaches.
 }
 ```
 
+### Workspace isolation (`cwd` keywords)
+
+A phase's `cwd` is normally a literal path (or inherited from the run). Three
+**reserved keywords** instead ask the runtime to allocate an isolated working
+directory for the phase's subagent and tear it down afterwards — so a phase can
+do scratch work, or mutate files, without touching the main tree:
+
+| `cwd` value | what the runtime does | lifecycle |
+|-------------|-----------------------|-----------|
+| `"temp"` | makes an ephemeral dir under the OS tmpdir | removed when the phase finishes |
+| `"dedicated"` | makes a persistent dir under the run state (`runs/ws/<runId>/<phaseId>`) | **kept** for inspection; deterministic per phase (resume reuses it) |
+| `"worktree"` | `git worktree add` on a throwaway branch off `HEAD` | `git worktree remove` + branch delete when the phase finishes |
+
+```jsonc
+{ "id": "experiment", "type": "agent", "agent": "executor", "cwd": "worktree",
+  "task": "Try the risky refactor and run the tests. Your edits are isolated in a git worktree." }
+```
+
+- **Fail-open.** If allocation fails (e.g. `worktree` requested but the repo
+  isn't a git work tree), the phase degrades — `worktree`→`temp`, and any other
+  failure → the base cwd — and records a `warnings` diagnostic. A phase never
+  fails to run because of isolation.
+- **Security.** The keywords are honoured only in **author-written** flows.
+  An LLM-authored sub-flow (`flow{def}` / `ctx_spawn` subflow) that asks for a
+  reserved keyword is **rejected at validation** — generated plans cannot
+  allocate worktrees or temp dirs that mutate the repo.
+- A literal path is passed through unchanged (fully backward-compatible).
+
 ### Budget (cost / token caps)
 
 Add a run-wide ceiling at the top level. When accumulated cost/tokens exceed it,
@@ -434,6 +462,82 @@ Use the shorthand if you literally just want `a → b → c → d`:
 …or write the full DAG with explicit `dependsOn` (so reviewers/fixers can run
 in parallel against multiple review streams when you want that).
 
+### Shared Context Tree (blackboard + supervision) — opt-in
+
+By default subagents are fully isolated: they share nothing and only return a
+final output string. Opt a phase into the **Shared Context Tree** with
+`shareContext: true` (or set `contextSharing: true` at the flow level for every
+phase) to give its subagent four extra tools backed by a per-run, file-based
+blackboard:
+
+| tool | direction | use |
+|------|-----------|-----|
+| `ctx_write(key, value)` | horizontal | publish a finding so siblings/descendants can reuse it (avoid re-reading the same files) |
+| `ctx_read(key?)` | horizontal | read findings visible to this node: its own + ancestors' + **completed** other nodes' (omit `key` to list all) |
+| `ctx_report(summary, structured?)` | vertical ↑ | report a result upward to the parent |
+| `ctx_spawn(assignments[])` | vertical ↓ | delegate child tasks; after this node finishes the runtime runs each child (isolated) and **folds their reports into this phase's output**. Each assignment is either a flat `{task, agent?}` OR a `{subflow, defaultAgent?}` — an inline plan `{phases:[...]}` (a dependency-bearing DAG) the runtime validates and runs as a nested sub-flow |
+
+Visibility is eventually-consistent: a sibling's findings become visible once
+that sibling **completes** (a running sibling's half-written blackboard is
+hidden). Own findings beat ancestors' beat completed-others' on key conflicts.
+
+Use it when fan-out items share expensive context (one map item maps the repo,
+the rest read its findings), or when a task should discover work at runtime and
+delegate it (`ctx_spawn`) rather than the author pre-declaring every branch.
+
+**Spawning a sub-graph (not just flat tasks).** A `ctx_spawn` assignment can be
+a whole inline plan instead of a single task — use `subflow` when the delegated
+work has multiple coordinated steps with dependencies:
+
+```jsonc
+ctx_spawn({ assignments: [
+  { task: "quick standalone check", agent: "analyst" },          // flat task
+  { subflow: {                                                   // a DAG
+      phases: [
+        { id: "scan",  type: "agent",  agent: "scout",  task: "list endpoints" },
+        { id: "audit", type: "map",    over: "{steps.scan.json}", task: "audit {item}", dependsOn: ["scan"] },
+        { id: "sum",   type: "reduce", from: ["audit"], task: "summarize", dependsOn: ["audit"], final: true }
+      ]
+    },
+    defaultAgent: "analyst"   // inner phases without their own `agent` use this
+  }
+] })
+```
+
+The subflow is validated (cycles / dangling refs / dead-ends) before it runs;
+a bad plan fails **open** (a diagnostic is folded into the report, the run
+continues). `agent` (flat task) = who executes; `defaultAgent` (subflow) =
+fallback for inner phases — different fields because the semantics differ.
+Nesting is bounded: spawn-subflows and `flow{def}` share one depth counter
+capped at `MAX_DYNAMIC_NESTING` (5), so neither can multiply with the other.
+
+```jsonc
+{ "id": "survey", "type": "agent", "agent": "scout", "shareContext": true,
+  "task": "Map the API surface. ctx_write key 'endpoints' with the JSON list so the auditors don't re-scan." },
+{ "id": "audit", "type": "map", "over": "{steps.survey.json}", "shareContext": true,
+  "dependsOn": ["survey"], "agent": "analyst",
+  "task": "ctx_read 'endpoints' for shared context, then audit {item} for missing auth." }
+```
+
+Guards & limits: ids used with sharing must match `[A-Za-z0-9._-]+`; keys are
+`[A-Za-z0-9._-]` (≤128 chars); values ≤256 KB; ≤256 keys/node; `ctx_spawn`
+≤16 tasks/call, task ≤64 KB, depth-capped at 5. All bookkeeping is fail-open
+(it can never sink a phase) and the per-run blackboard is cleaned up with the
+run. Backward compatible: flows that don't opt in behave exactly as before.
+
+You do **not** need to teach the tools in your `task` text — enabling
+`shareContext` auto-appends usage guidance to the subagent's system prompt
+(read-first discipline, publish reusable findings, report up, delegate on
+fan-out). Mentioning a specific key in the task (e.g. "ctx_write the endpoint
+list under 'endpoints'") just makes the cross-phase contract explicit.
+
+**Producer tip (learned from real runs):** the phase that *publishes* shared
+context should be a **capable** agent (high thinking), and the `ctx_write`
+should be framed as its **primary deliverable** ("if you did not call ctx_write
+you failed the task"). A fast / `thinking: off` agent asked to "survey AND
+ctx_write" will often do the survey and skip the write. Consumers (the agents
+that `ctx_read`) can be lighter — reading is a single reliable step.
+
 ## Configuration
 
 For the full set of knobs — per-phase `model`/`thinking`/`tools`/`cwd`, the