@cleocode/caamp 2026.4.15 → 2026.4.16

package/dist/cli.js

@@ -52,7 +52,7 @@ import {
   tokenizeCriteriaValue,
   updateInstructionsSingleOperation,
   validateSkill
-} from "./chunk-VD2JJXE7.js";
+} from "./chunk-K7AO3SE7.js";
 import {
   buildSkillsMap,
   checkAllInjections,

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { WorktreeHandle } from '@cleocode/cant';
+
 /**
  * Priority tier identifier stored in registry.json.
  *
@@ -2111,11 +2113,33 @@ interface SubagentSpawnOptions {
      *
      * @remarks
      * Useful when the same task description is reused across multiple
-     * working directories.
+     * working directories. When {@link worktree} is also set, the worktree
+     * path is used as the cwd and this field is ignored.
      *
      * @defaultValue undefined
      */
     cwd?: string;
+    /**
+     * Git worktree handle providing physical + logical isolation for the
+     * spawned subagent (ADR-041 §D2).
+     *
+     * @remarks
+     * When set, `PiHarness.spawnSubagent` MUST:
+     * 1. Pass `cwd: worktree.path` to the Pi subprocess.
+     * 2. Inject the following env vars (before `opts.env` and `task.env`):
+     *    - `CLEO_WORKTREE_ROOT`   = worktree.path
+     *    - `CLEO_WORKTREE_BRANCH` = worktree.branch
+     *    - `CLEO_PROJECT_HASH`    = worktree.projectHash
+     *
+     * These env vars allow `getProjectRoot()` inside the worker to resolve
+     * DB paths against the correct worktree directory via the
+     * `worktreeScope` AsyncLocalStorage (ADR-041 §D3) or direct env-var
+     * inspection when AsyncLocalStorage is not in scope.
+     *
+     * @defaultValue undefined
+     * @task T380
+     */
+    worktree?: WorktreeHandle;
 }
 /**
  * One streaming event surfaced through {@link SubagentSpawnOptions.onStream}.
@@ -3219,9 +3243,24 @@ declare class PiHarness implements Harness {
      * `spawnCommand` so callers see configuration errors early rather
      * than at child-exit time.
      *
+     * **Worktree isolation (T380/ADR-041 §D2)** — Pass a
+     * {@link SubagentSpawnOptions.worktree} handle to bind the spawned
+     * process to a physical git worktree. When set, this method:
+     * - Uses `worktree.path` as the child cwd.
+     * - Injects `CLEO_WORKTREE_ROOT`, `CLEO_WORKTREE_BRANCH`, and
+     *   `CLEO_PROJECT_HASH` env vars so the child's path resolvers
+     *   (including `getProjectRoot()` via `worktreeScope`) direct DB I/O
+     *   to the correct worktree directory.
+     *
+     * The spawned worker MUST run the worktree guard defined in
+     * `packages/agents/cleo-subagent/AGENT.md §WORKTREE GUARD` as its
+     * first Bash call. That guard verifies the cwd binding was applied
+     * correctly before any file I/O occurs.
+     *
      * @param task - Subagent task specification.
-     * @param opts - Per-call streaming and cleanup overrides.
+     * @param opts - Per-call streaming, cleanup, and worktree overrides.
      * @returns A live subagent handle.
+     * @task T380
      */
     spawnSubagent(task: SubagentTask, opts?: SubagentSpawnOptions): Promise<SubagentHandle>;
     /**
@@ -6319,11 +6358,27 @@ declare function providerSupportsById(idOrAlias: string, capabilityPath: string)
  *
  * This is an interface-only module — no concrete implementations yet.
  * CLEO will consume this interface to build provider-specific adapters.
+ *
+ * @remarks
+ * T380/ADR-041: `SpawnOptions.isolate: boolean` has been superseded by
+ * `SpawnOptions.worktree: WorktreeHandle`. The boolean alias is kept for one
+ * release cycle (removal target: v2026.5.x) so existing callers compile
+ * without changes during the migration window.
  */
 
 /**
  * Options for spawning a subagent.
  *
+ * @remarks
+ * When `worktree` is present, the spawn adapter MUST bind the child process
+ * cwd to `worktree.path` and export the following environment variables:
+ *   - `CLEO_WORKTREE_ROOT`   = worktree.path
+ *   - `CLEO_WORKTREE_BRANCH` = worktree.branch
+ *   - `CLEO_PROJECT_HASH`    = worktree.projectHash
+ *
+ * See ADR-041 §D2 and ULTRAPLAN §14 for the full isolation contract.
+ *
+ * @task T380
  * @public
  */
 interface SpawnOptions {
@@ -6335,7 +6390,33 @@ interface SpawnOptions {
     tools?: string[];
     /** Timeout in milliseconds for the spawned agent. @defaultValue undefined */
     timeout?: number;
-    /** Whether to isolate the spawned agent (e.g. in a worktree). @defaultValue undefined */
+    /**
+     * Git worktree handle that provides physical + logical isolation for the
+     * spawned subagent (ADR-041 §D1).
+     *
+     * @remarks
+     * When set, the adapter MUST pass `cwd: worktree.path` to the child process
+     * and export `CLEO_WORKTREE_ROOT`, `CLEO_WORKTREE_BRANCH`, and
+     * `CLEO_PROJECT_HASH` into its environment so that path resolvers inside
+     * the worker direct DB I/O to the correct worktree directory.
+     *
+     * Supersedes the deprecated {@link SpawnOptions.isolate} boolean which
+     * carried no data and could not drive cwd binding or env-var injection.
+     *
+     * @defaultValue undefined
+     * @task T380
+     */
+    worktree?: WorktreeHandle;
+    /**
+     * Whether to isolate the spawned agent (e.g. in a worktree).
+     *
+     * @deprecated Use `worktree` instead. The boolean flag has no associated
+     *   data and cannot drive cwd binding or env-var injection. Pass a
+     *   {@link WorktreeHandle} via `worktree` to achieve isolation.
+     *   Removal target: v2026.5.x.
+     *
+     * @defaultValue undefined
+     */
     isolate?: boolean;
 }
 /**

package/dist/index.js

@@ -70,7 +70,7 @@ import {
   validateRecommendationCriteria,
   validateSkill,
   writeConfig
-} from "./chunk-VD2JJXE7.js";
+} from "./chunk-K7AO3SE7.js";
 import {
   buildInjectionContent,
   buildSkillsMap,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/caamp",
-  "version": "2026.4.15",
+  "version": "2026.4.16",
   "description": "Central AI Agent Managed Packages - unified provider registry and package manager for AI coding agents",
   "type": "module",
   "bin": {
@@ -10,8 +10,8 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
   "files": [
@@ -51,8 +51,8 @@
     "jsonc-parser": "^3.3.1",
     "picocolors": "^1.1.1",
     "simple-git": "3.33.0",
-    "@cleocode/cant": "2026.4.15",
-    "@cleocode/lafs": "2026.4.15"
+    "@cleocode/lafs": "2026.4.16",
+    "@cleocode/cant": "2026.4.16"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.8",