@cleocode/cant 2026.4.15 → 2026.4.16

package/dist/composer.d.ts

@@ -102,6 +102,50 @@ export interface SpawnPayload {
     /** Whether mental model was injected. */
     mentalModelInjected: boolean;
 }
+/**
+ * Path-scoped file permissions for a CANT agent (T423 — ULTRAPLAN §9.2).
+ *
+ * Mirrors the Rust `PathPermissions` struct in `crates/cant-core/src/dsl/ast.rs`.
+ * Enforced at runtime by the `tool_call` hook in `cleo-cant-bridge.ts`.
+ *
+ * Security rules:
+ * - An **empty `write` array means no writes are allowed** (default-deny).
+ * - An absent field (`undefined`) means that access level is unrestricted.
+ *
+ * @example
+ * ```cant
+ * agent backend-dev:
+ *   permissions:
+ *     files:
+ *       write: ["packages/cleo/**", "crates/**"]
+ *       read:  ["**\/*"]
+ *       delete: ["packages/cleo/**"]
+ * ```
+ *
+ * @task T423
+ */
+export interface PathPermissions {
+    /**
+     * Glob patterns for paths this agent may write (Edit/Write tool).
+     *
+     * An empty array means no writes are allowed (read-only agent).
+     * `undefined` means no write ACL was declared (unrestricted).
+     */
+    write?: string[];
+    /**
+     * Glob patterns for paths this agent may read.
+     *
+     * `undefined` means reads are unrestricted (default-allow).
+     */
+    read?: string[];
+    /**
+     * Glob patterns for paths this agent may delete.
+     *
+     * An empty array means no deletes are allowed.
+     * `undefined` means deletes are unrestricted.
+     */
+    delete?: string[];
+}
 /** Agent definition extracted from a compiled `.cant` bundle. */
 export interface AgentDefinition {
     /** The agent name as declared in the `.cant` file. */
@@ -143,6 +187,15 @@ export interface AgentDefinition {
     } | null;
     /** Behavior when total tokens exceed the tier cap. */
     onOverflow: 'escalate_tier' | 'fail';
+    /**
+     * Path-scoped file permissions declared via `permissions: files:` in the `.cant` file.
+     *
+     * `undefined` means no path ACL was declared (tool-level enforcement only).
+     * When present, the `tool_call` hook enforces write/delete path restrictions.
+     *
+     * @task T423
+     */
+    filePermissions?: PathPermissions;
 }
 /**
  * Compose a spawn payload for an agent.

package/dist/context-provider-brain.d.ts

@@ -0,0 +1,47 @@
+/**
+ * BRAIN-backed ContextProvider implementation for the JIT Agent Composer.
+ *
+ * Wires the `ContextProvider` interface from `composer.ts` to the live BRAIN
+ * database via `memoryFind` from `@cleocode/core`. This is the critical T432
+ * activation — without this provider, `composeSpawnPayload` cannot pull real
+ * context from BRAIN at spawn time.
+ *
+ * The `agent` filter (T417/T418) ensures that mental model observations written
+ * by a specific agent are returned rather than unrelated global observations.
+ *
+ * @epic T377
+ * @task T432
+ * @packageDocumentation
+ */
+import type { ContextProvider } from './composer.js';
+/**
+ * A {@link ContextProvider} implementation that retrieves context from the
+ * BRAIN database (`brain.db`) via the `memoryFind` and `memoryFetch` functions
+ * from `@cleocode/core`.
+ *
+ * @remarks
+ * This provider is designed for use in the canonical spawn path:
+ * `composeSpawnPayload(agentDef, brainContextProvider(projectRoot), projectHash)`.
+ *
+ * The `source` parameter maps to BRAIN table categories:
+ * - `"patterns"` → searches the patterns table
+ * - `"decisions"` → searches the decisions table
+ * - `"learnings"` → searches the learnings table
+ * - `"observations"` → searches the observations table (default)
+ *
+ * @param projectRoot - Absolute path to the project root (where `.cleo/` lives).
+ * @returns A `ContextProvider` instance backed by the project's BRAIN database.
+ *
+ * @example
+ * ```typescript
+ * import { composeSpawnPayload } from '@cleocode/cant';
+ * import { brainContextProvider } from '@cleocode/cant/context-provider-brain';
+ *
+ * const payload = await composeSpawnPayload(
+ *   agentDef,
+ *   brainContextProvider('/project/root'),
+ *   projectHash,
+ * );
+ * ```
+ */
+export declare function brainContextProvider(projectRoot: string): ContextProvider;

package/dist/context-provider-brain.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * BRAIN-backed ContextProvider implementation for the JIT Agent Composer.
+ *
+ * Wires the `ContextProvider` interface from `composer.ts` to the live BRAIN
+ * database via `memoryFind` from `@cleocode/core`. This is the critical T432
+ * activation — without this provider, `composeSpawnPayload` cannot pull real
+ * context from BRAIN at spawn time.
+ *
+ * The `agent` filter (T417/T418) ensures that mental model observations written
+ * by a specific agent are returned rather than unrelated global observations.
+ *
+ * @epic T377
+ * @task T432
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.brainContextProvider = brainContextProvider;
+const composer_js_1 = require("./composer.js");
+/** Lazy-load memoryFind and memoryFetch from @cleocode/core/internal. */
+async function loadBrainOps() {
+    // Variable path prevents tsc from resolving the module at type-check time.
+    const modPath = '@cleocode/core/internal';
+    const mod = await import(/* webpackIgnore: true */ modPath);
+    return { memoryFind: mod.memoryFind, memoryFetch: mod.memoryFetch };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Truncate text to fit within a token budget using a 4 chars/token estimate.
+ *
+ * @param text - The text to truncate.
+ * @param maxTokens - The maximum token count.
+ * @returns The (possibly truncated) text.
+ */
+function truncateToTokenBudget(text, maxTokens) {
+    if (maxTokens <= 0)
+        return '';
+    const maxChars = maxTokens * 4;
+    if (text.length <= maxChars)
+        return text;
+    return text.slice(0, maxChars);
+}
+// ---------------------------------------------------------------------------
+// BRAIN ContextProvider
+// ---------------------------------------------------------------------------
+/**
+ * A {@link ContextProvider} implementation that retrieves context from the
+ * BRAIN database (`brain.db`) via the `memoryFind` and `memoryFetch` functions
+ * from `@cleocode/core`.
+ *
+ * @remarks
+ * This provider is designed for use in the canonical spawn path:
+ * `composeSpawnPayload(agentDef, brainContextProvider(projectRoot), projectHash)`.
+ *
+ * The `source` parameter maps to BRAIN table categories:
+ * - `"patterns"` → searches the patterns table
+ * - `"decisions"` → searches the decisions table
+ * - `"learnings"` → searches the learnings table
+ * - `"observations"` → searches the observations table (default)
+ *
+ * @param projectRoot - Absolute path to the project root (where `.cleo/` lives).
+ * @returns A `ContextProvider` instance backed by the project's BRAIN database.
+ *
+ * @example
+ * ```typescript
+ * import { composeSpawnPayload } from '@cleocode/cant';
+ * import { brainContextProvider } from '@cleocode/cant/context-provider-brain';
+ *
+ * const payload = await composeSpawnPayload(
+ *   agentDef,
+ *   brainContextProvider('/project/root'),
+ *   projectHash,
+ * );
+ * ```
+ */
+function brainContextProvider(projectRoot) {
+    return {
+        /**
+         * Query BRAIN for context entries matching a source category and query string.
+         *
+         * @param source - BRAIN table category (patterns, decisions, learnings, observations).
+         * @param query - The search query string.
+         * @param maxTokens - Maximum token budget for the returned content.
+         * @returns A ContextSlice with content truncated to the token budget.
+         */
+        async queryContext(source, query, maxTokens) {
+            if (maxTokens <= 0) {
+                return { source, content: '', tokens: 0 };
+            }
+            try {
+                // Map source to a BRAIN table filter.
+                const validTables = ['patterns', 'decisions', 'learnings', 'observations'];
+                const table = validTables.includes(source)
+                    ? [source]
+                    : undefined;
+                const { memoryFind, memoryFetch } = await loadBrainOps();
+                const findResult = await memoryFind({
+                    query,
+                    limit: 10,
+                    tables: table,
+                }, projectRoot);
+                if (!findResult.success || !findResult.data) {
+                    return { source, content: '', tokens: 0 };
+                }
+                // memoryFind returns { results: BrainCompactHit[] }
+                const data = findResult.data;
+                const hits = data.results ?? [];
+                if (hits.length === 0) {
+                    return { source, content: '', tokens: 0 };
+                }
+                // Fetch full content for the top hits within the budget.
+                const ids = hits.map((h) => h.id);
+                const fetchResult = await memoryFetch({ ids }, projectRoot);
+                let content = '';
+                if (fetchResult.success && fetchResult.data) {
+                    const fetchData = fetchResult.data;
+                    const entries = fetchData.entries ?? [];
+                    content = entries.map((e) => `[${e.title}]\n${e.content ?? e.text ?? ''}`).join('\n\n');
+                }
+                else {
+                    // Fallback to compact titles if fetch failed.
+                    content = hits.map((h) => h.title).join('\n');
+                }
+                const truncated = truncateToTokenBudget(content, maxTokens);
+                return {
+                    source,
+                    content: truncated,
+                    tokens: (0, composer_js_1.estimateTokens)(truncated),
+                };
+            }
+            catch {
+                // Return empty slice on any error — the composer handles missing context gracefully.
+                return { source, content: '', tokens: 0 };
+            }
+        },
+        /**
+         * Load the mental model for an agent from BRAIN observations.
+         *
+         * Uses the T417/T418 `agent` filter to retrieve only observations
+         * produced by the specific agent for this project scope.
+         *
+         * @param agentName - The agent name to load the mental model for.
+         * @param projectHash - Project identifier ('global' for global scope).
+         * @param maxTokens - Maximum token budget for the mental model content.
+         * @returns A MentalModelSlice with content truncated to the token budget.
+         */
+        async loadMentalModel(agentName, projectHash, maxTokens) {
+            if (maxTokens <= 0) {
+                return { content: '', tokens: 0, lastConsolidated: null };
+            }
+            try {
+                const { memoryFind, memoryFetch } = await loadBrainOps();
+                // Query brain_observations filtered by agent name (T417/T418).
+                const findResult = await memoryFind({
+                    query: `mental model ${agentName}`,
+                    limit: 5,
+                    tables: ['observations'],
+                    agent: agentName,
+                }, projectRoot);
+                if (!findResult.success || !findResult.data) {
+                    return { content: '', tokens: 0, lastConsolidated: null };
+                }
+                const data = findResult.data;
+                const hits = data.results ?? [];
+                if (hits.length === 0) {
+                    return { content: '', tokens: 0, lastConsolidated: null };
+                }
+                // Sort by date descending and take the most recent entries.
+                const sorted = [...hits].sort((a, b) => (b.date ?? '').localeCompare(a.date ?? ''));
+                const ids = sorted.map((h) => h.id);
+                const fetchResult = await memoryFetch({ ids }, projectRoot);
+                let content = '';
+                let lastConsolidated = null;
+                if (fetchResult.success && fetchResult.data) {
+                    const fetchData = fetchResult.data;
+                    const entries = fetchData.entries ?? [];
+                    content = entries.map((e) => `[${e.title}]\n${e.content ?? e.text ?? ''}`).join('\n\n');
+                    lastConsolidated = entries[0]?.date ?? null;
+                }
+                else {
+                    content = sorted.map((h) => h.title).join('\n');
+                    lastConsolidated = sorted[0]?.date ?? null;
+                }
+                // Scope prefix to help the agent understand its mental model context.
+                const prefix = projectHash === 'global'
+                    ? `[Global mental model for ${agentName}]\n`
+                    : `[Project mental model for ${agentName} — scope: ${projectHash}]\n`;
+                const full = prefix + content;
+                const truncated = truncateToTokenBudget(full, maxTokens);
+                return {
+                    content: truncated,
+                    tokens: (0, composer_js_1.estimateTokens)(truncated),
+                    lastConsolidated,
+                };
+            }
+            catch {
+                return { content: '', tokens: 0, lastConsolidated: null };
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export type { LAFSEnvelope, LAFSError, LAFSMeta, MVILevel } from '@cleocode/lafs';
 export type { AgentEntry, BundleDiagnostic, CompiledBundle, ParsedCantDocument, TeamEntry, ToolEntry, } from './bundle';
 export { compileBundle } from './bundle';
-export type { AgentDefinition, ContextProvider, ContextSlice, MentalModelSlice, SpawnPayload, Tier, } from './composer.js';
+export type { AgentDefinition, ContextProvider, ContextSlice, MentalModelSlice, PathPermissions, SpawnPayload, Tier, } from './composer.js';
 export { composeSpawnPayload, escalateTier, estimateTokens, TIER_CAPS } from './composer.js';
+export { brainContextProvider } from './context-provider-brain.js';
 export type { CantDocumentResult, CantListResult, CantPipelineResult, CantValidationResult, SectionKind, } from './document';
 export { executePipeline, listSections, parseDocument, validateDocument, } from './document';
 export type { Role, SpawnValidation, TeamDefinition, TeamRouting } from './hierarchy.js';

package/dist/index.js

@@ -1,7 +1,8 @@
 "use strict";
 // JIT Agent Composer (ULTRAPLAN Wave 5)
+// Wave 7a: BRAIN-backed ContextProvider (T432)
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveWorktreeRoot = exports.mergeWorktree = exports.listWorktrees = exports.createWorktree = exports.parseCANTMessage = exports.initCantParser = exports.isWasmAvailable = exports.isNativeAvailable = exports.initWasm = exports.cantValidateDocumentNative = exports.cantParseNative = exports.cantParseDocumentNative = exports.cantExtractAgentProfilesNative = exports.cantExecutePipelineNative = exports.cantClassifyDirectiveNative = exports.showSummary = exports.showDiff = exports.serializeCantDocument = exports.migrateMarkdown = exports.renderMentalModel = exports.harvestObservations = exports.createEmptyModel = exports.consolidate = exports.validateSpawnRequest = exports.ORCHESTRATOR_FORBIDDEN_TOOLS = exports.LEAD_FORBIDDEN_TOOLS = exports.filterToolsForRole = exports.validateDocument = exports.parseDocument = exports.listSections = exports.executePipeline = exports.TIER_CAPS = exports.estimateTokens = exports.escalateTier = exports.composeSpawnPayload = exports.compileBundle = void 0;
+exports.resolveWorktreeRoot = exports.mergeWorktree = exports.listWorktrees = exports.createWorktree = exports.parseCANTMessage = exports.initCantParser = exports.isWasmAvailable = exports.isNativeAvailable = exports.initWasm = exports.cantValidateDocumentNative = exports.cantParseNative = exports.cantParseDocumentNative = exports.cantExtractAgentProfilesNative = exports.cantExecutePipelineNative = exports.cantClassifyDirectiveNative = exports.showSummary = exports.showDiff = exports.serializeCantDocument = exports.migrateMarkdown = exports.renderMentalModel = exports.harvestObservations = exports.createEmptyModel = exports.consolidate = exports.validateSpawnRequest = exports.ORCHESTRATOR_FORBIDDEN_TOOLS = exports.LEAD_FORBIDDEN_TOOLS = exports.filterToolsForRole = exports.validateDocument = exports.parseDocument = exports.listSections = exports.executePipeline = exports.brainContextProvider = exports.TIER_CAPS = exports.estimateTokens = exports.escalateTier = exports.composeSpawnPayload = exports.compileBundle = void 0;
 // Bundle compiler
 var bundle_1 = require("./bundle");
 Object.defineProperty(exports, "compileBundle", { enumerable: true, get: function () { return bundle_1.compileBundle; } });
@@ -10,6 +11,8 @@ Object.defineProperty(exports, "composeSpawnPayload", { enumerable: true, get: f
 Object.defineProperty(exports, "escalateTier", { enumerable: true, get: function () { return composer_js_1.escalateTier; } });
 Object.defineProperty(exports, "estimateTokens", { enumerable: true, get: function () { return composer_js_1.estimateTokens; } });
 Object.defineProperty(exports, "TIER_CAPS", { enumerable: true, get: function () { return composer_js_1.TIER_CAPS; } });
+var context_provider_brain_js_1 = require("./context-provider-brain.js");
+Object.defineProperty(exports, "brainContextProvider", { enumerable: true, get: function () { return context_provider_brain_js_1.brainContextProvider; } });
 // High-level API (replaces standalone cant-cli binary)
 var document_1 = require("./document");
 Object.defineProperty(exports, "executePipeline", { enumerable: true, get: function () { return document_1.executePipeline; } });

package/dist/worktree.d.ts

@@ -18,7 +18,16 @@ export interface WorktreeRequest {
     /** Why this worktree is being created. */
     reason: 'subagent' | 'experiment' | 'parallel-wave';
 }
-/** Handle returned after worktree creation; used for merge and cleanup. */
+/**
+ * Handle returned after worktree creation; used for merge, env-var binding, and cleanup.
+ *
+ * @remarks
+ * The `projectHash` field was added in T380/ADR-041 so callers can populate
+ * `CLEO_PROJECT_HASH` in spawned subagent environments without threading
+ * {@link WorktreeConfig} through every call site.
+ *
+ * @task T380
+ */
 export interface WorktreeHandle {
     /** Absolute path to the worktree directory. */
     path: string;
@@ -28,6 +37,17 @@ export interface WorktreeHandle {
     baseRef: string;
     /** Task ID. */
     taskId: string;
+    /**
+     * Project hash used to scope this worktree under the XDG worktree root.
+     *
+     * @remarks
+     * Sourced from {@link WorktreeConfig.projectHash} at creation time.
+     * Exposed here so spawn adapters can populate the `CLEO_PROJECT_HASH`
+     * environment variable without re-threading the full config.
+     *
+     * @task T380
+     */
+    projectHash: string;
     /** Clean up: remove the worktree and optionally delete the branch. */
     cleanup(deleteBranch?: boolean): void;
 }

package/dist/worktree.js

@@ -71,7 +71,7 @@ function createWorktree(request, config) {
         cwd: config.gitRoot,
         stdio: 'pipe',
     });
-    return buildHandle(worktreePath, branch, request.baseRef, request.taskId, config.gitRoot);
+    return buildHandle(worktreePath, branch, request.baseRef, request.taskId, config.gitRoot, config.projectHash);
 }
 /**
  * Merge a worktree's branch back into the current branch.
@@ -148,14 +148,20 @@ function listWorktrees(config) {
 /**
  * Build a WorktreeHandle with a cleanup closure.
  *
+ * @remarks
+ * The `projectHash` parameter was added in T380/ADR-041 and is stored on the
+ * returned handle so spawn adapters can populate `CLEO_PROJECT_HASH` without
+ * re-threading {@link WorktreeConfig}.
+ *
  * @internal
  */
-function buildHandle(worktreePath, branch, baseRef, taskId, gitRoot) {
+function buildHandle(worktreePath, branch, baseRef, taskId, gitRoot, projectHash) {
     return {
         path: worktreePath,
         branch,
         baseRef,
         taskId,
+        projectHash,
         cleanup(deleteBranch = false) {
             try {
                 (0, node_child_process_1.execSync)(`git worktree remove "${worktreePath}" --force`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cant",
-  "version": "2026.4.15",
+  "version": "2026.4.16",
   "description": "CANT protocol parser and runtime for CLEO — wraps cant-core via napi-rs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,8 +9,9 @@
     "napi/"
   ],
   "dependencies": {
-    "@cleocode/lafs": "2026.4.15",
-    "@cleocode/contracts": "2026.4.15"
+    "@cleocode/contracts": "2026.4.16",
+    "@cleocode/core": "2026.4.16",
+    "@cleocode/lafs": "2026.4.16"
   },
   "devDependencies": {
     "typescript": "^6.0.2",