chainlesschain 0.162.188 → 0.162.193

package/src/lib/sub-agent-context.js

@@ -44,6 +44,7 @@ export class SubAgentContext {
    * @param {string[]} [options.allowedTools] - Tool whitelist (null = all tools)
    * @param {number} [options.maxIterations] - Iteration limit (fallback if no budget)
    * @param {import('./iteration-budget.js').IterationBudget} [options.iterationBudget] - Shared iteration budget (takes priority over maxIterations)
+   * @param {import('./session-resource-budget.js').SessionResourceBudget} [options.sessionBudget] - Shared session-wide resource authority
    * @param {number} [options.tokenBudget] - Optional token budget
    * @param {object} [options.db] - Database instance (memory recall source)
    * @param {object} [options.permanentMemory] - Permanent memory instance
@@ -72,9 +73,10 @@ export class SubAgentContext {
       this._profile?.maxIterations ||
       DEFAULT_MAX_ITERATIONS;
     this.iterationBudget = options.iterationBudget || null; // shared budget from parent
+    this.sessionBudget = options.sessionBudget || null;
     this.tokenBudget = options.tokenBudget || null;
     this.inheritedContext = options.inheritedContext || null;
-    this.allowedTools = options.allowedTools || null; // null = all
+    this.allowedTools = options.allowedTools ?? null; // null = all; [] = none
     this.depth = options.depth || 1; // nesting level (parent main loop = 0)
     // Shared run-wide TOTAL-sub-agent counter (one object across the whole tree)
     // so this sub-agent's own spawns draw from the same breadth pool.
@@ -163,7 +165,12 @@ export class SubAgentContext {
     // registry's `cancel(id)`), independent of any external signal.
     this._signal = options.signal || null;
     this._abortController = new AbortController();
+    this._runAbortController = null;
+    this._abortLinkCleanup = [];
     this._cancelReason = null;
+    this._sessionBudgetLease = null;
+    this._unregisterSessionAbortable = null;
+    this._running = false;
 
     // Optional MCP / external tool plumbing. These are forwarded into the
     // agentLoop options so MCP-backed tools (e.g. from a cowork template's
@@ -183,6 +190,8 @@ export class SubAgentContext {
         ? options.externalToolExecutors
         : {};
     this._mcpClient = options.mcpClient || null;
+    this._mcpCallLedger = options.mcpCallLedger || null;
+    this._mcpConflictScheduler = options.mcpConflictScheduler || null;
 
     // Inherited settings hooks (Pre/PostToolUse) for this child loop. null =
     // no hooks (the spawn default). The spawn path passes the parent's hooks
@@ -200,6 +209,22 @@ export class SubAgentContext {
     // gated headlessly (CONFIRM→no-confirmer→DENY).
     this._approvalGate = options.approvalGate || null;
 
+    // Parent execution authority. These values are applied AFTER any internal
+    // loop options so a child/worktree path can tighten but never replace the
+    // parent's policy, Plan lock, workspace sandbox, or unattended boundary.
+    this._parentAuthority = Object.freeze({
+      permissionRules: options.permissionRules || null,
+      hostManagedToolPolicy: options.hostManagedToolPolicy || null,
+      planManager: options.planManager || null,
+      sandbox: options.sandbox || null,
+      additionalDirectories: Array.isArray(options.additionalDirectories)
+        ? Object.freeze([...options.additionalDirectories])
+        : null,
+      shellPolicyOverrides: options.shellPolicyOverrides || null,
+      classifyAllShell: options.classifyAllShell === true,
+      unattendedActionPolicy: options.unattendedActionPolicy || null,
+    });
+
     // Build isolated system prompt
     const basePrompt = buildSystemPrompt(this.cwd);
     const profilePrompt = this._profile?.systemPrompt
@@ -231,28 +256,139 @@ export class SubAgentContext {
       );
     }
 
-    // If worktree isolation is enabled, wrap execution in isolated worktree.
-    if (this._useWorktree) {
-      if (isGitRepo(this._repoDir)) {
-        return this._runInWorktree(userPrompt, loopOptions);
-      }
-      // FAIL CLOSED: isolation was explicitly requested but this is not a git
-      // repo. Never silently fall back to the parent checkout — refuse.
+    const admission = this._acquireSessionBudget();
+    if (!admission.ok) {
       this.status = "failed";
       this.completedAt = new Date().toISOString();
       this.result = {
-        summary:
-          "Worktree isolation was requested but the working directory is not a git repository — refusing to run in the parent checkout.",
+        summary: `Sub-agent blocked by session budget: ${admission.reason}`,
         artifacts: [],
         tokenCount: this._tokenCount,
         toolsUsed: [...new Set(this._toolsUsed)],
         iterationCount: this._iterationCount,
-        isolationError: true,
+        budgetReason: admission.reason,
       };
       return this.result;
     }
 
-    return this._runCore(userPrompt, loopOptions);
+    this._running = true;
+    try {
+      this._activateAbortLinks(loopOptions.signal || null);
+
+      // If worktree isolation is enabled, wrap execution in isolated worktree.
+      if (this._useWorktree) {
+        if (isGitRepo(this._repoDir)) {
+          return await this._runInWorktree(userPrompt, loopOptions);
+        }
+        // FAIL CLOSED: isolation was explicitly requested but this is not a git
+        // repo. Never silently fall back to the parent checkout — refuse.
+        this.status = "failed";
+        this.completedAt = new Date().toISOString();
+        this.result = {
+          summary:
+            "Worktree isolation was requested but the working directory is not a git repository — refusing to run in the parent checkout.",
+          artifacts: [],
+          tokenCount: this._tokenCount,
+          toolsUsed: [...new Set(this._toolsUsed)],
+          iterationCount: this._iterationCount,
+          isolationError: true,
+        };
+        return this.result;
+      }
+
+      return await this._runCore(userPrompt, loopOptions);
+    } finally {
+      this._running = false;
+      this._deactivateAbortLinks();
+      this._releaseSessionBudget();
+    }
+  }
+
+  _acquireSessionBudget() {
+    if (!this.sessionBudget?.acquireWork) return { ok: true };
+    const lease = this.sessionBudget.acquireWork({
+      id: this.id,
+      kind: "sub-agent",
+      depth: this.depth,
+    });
+    if (!lease.ok) return lease;
+    this._sessionBudgetLease = lease;
+    try {
+      this._unregisterSessionAbortable =
+        this.sessionBudget.registerAbortable?.(
+          `sub-agent:${this.id}`,
+          (reason) =>
+            this.abort(
+              reason?.budgetReason || reason?.message || "session-budget",
+            ),
+        ) || null;
+    } catch (error) {
+      lease.release();
+      this._sessionBudgetLease = null;
+      throw error;
+    }
+    return lease;
+  }
+
+  _releaseSessionBudget() {
+    try {
+      this._unregisterSessionAbortable?.();
+    } catch {
+      // Session cancellation remains authoritative if observer cleanup fails.
+    }
+    this._unregisterSessionAbortable = null;
+    try {
+      this._sessionBudgetLease?.release?.();
+    } catch {
+      // A released/aborted budget lease is idempotent.
+    }
+    this._sessionBudgetLease = null;
+  }
+
+  _activateAbortLinks(extraSignal = null) {
+    this._deactivateAbortLinks();
+    this._runAbortController = new AbortController();
+    const signals = [
+      this._signal,
+      this._abortController.signal,
+      this.sessionBudget?.signal || null,
+      extraSignal,
+    ].filter(Boolean);
+    for (const source of signals) {
+      const propagate = () => {
+        if (!this._cancelReason) {
+          this._cancelReason =
+            source.reason?.budgetReason ||
+            source.reason?.message ||
+            "cancelled";
+        }
+        if (!this._runAbortController.signal.aborted) {
+          try {
+            this._runAbortController.abort(source.reason);
+          } catch {
+            this._runAbortController.abort();
+          }
+        }
+      };
+      if (source.aborted) propagate();
+      else {
+        source.addEventListener?.("abort", propagate, { once: true });
+        this._abortLinkCleanup.push(() =>
+          source.removeEventListener?.("abort", propagate),
+        );
+      }
+    }
+  }
+
+  _deactivateAbortLinks() {
+    for (const cleanup of this._abortLinkCleanup.splice(0)) {
+      try {
+        cleanup();
+      } catch {
+        // Abort-listener removal is best-effort cleanup only.
+      }
+    }
+    this._runAbortController = null;
   }
 
   /**
@@ -332,7 +468,7 @@ export class SubAgentContext {
       // computed via _getFilteredTools() but never handed to agentLoop, so a
       // sub-agent's `tools`/frontmatter allowlist was silently ignored at the
       // LLM surface. agentLoop consumes NAMES via enabledToolNames.
-      ...(Array.isArray(this.allowedTools) && this.allowedTools.length > 0
+      ...(Array.isArray(this.allowedTools)
         ? { enabledToolNames: this.allowedTools }
         : {}),
       contextEngine: this.contextEngine,
@@ -342,6 +478,7 @@ export class SubAgentContext {
       // Shared total-sub-agent counter so a nested spawn_sub_agent draws from
       // (and is bounded by) the run's single breadth pool.
       subAgentBudget: this.subAgentBudget,
+      sessionBudget: this.sessionBudget,
       // This context's effective contract = the ceiling for its nested spawns.
       subAgentContract: this.subAgentContract,
       toolAdmission: this.toolAdmission,
@@ -353,6 +490,39 @@ export class SubAgentContext {
         : {}),
       ...loopOptions,
     };
+    // Re-apply tighten-only capability fields after loopOptions. In particular,
+    // [] must survive as deny-all and cannot be replaced by a worktree/direct
+    // runner override.
+    if (Array.isArray(this.allowedTools)) {
+      options.enabledToolNames = [...this.allowedTools];
+      options.exactToolNames = true;
+    }
+    options.subAgentContract = this.subAgentContract;
+    options.sessionBudget = this.sessionBudget;
+    if (this._runAbortController) {
+      options.signal = this._runAbortController.signal;
+    }
+    options.toolAdmission = this.toolAdmission;
+    options.skillAllowlist = this.skillAllowlist;
+    const authority = this._parentAuthority;
+    if (authority.permissionRules) {
+      options.permissionRules = authority.permissionRules;
+    }
+    if (authority.hostManagedToolPolicy) {
+      options.hostManagedToolPolicy = authority.hostManagedToolPolicy;
+    }
+    if (authority.planManager) options.planManager = authority.planManager;
+    if (authority.sandbox) options.sandbox = authority.sandbox;
+    if (authority.additionalDirectories) {
+      options.additionalDirectories = [...authority.additionalDirectories];
+    }
+    if (authority.shellPolicyOverrides) {
+      options.shellPolicyOverrides = authority.shellPolicyOverrides;
+    }
+    if (authority.classifyAllShell) options.classifyAllShell = true;
+    if (authority.unattendedActionPolicy) {
+      options.unattendedActionPolicy = authority.unattendedActionPolicy;
+    }
     if (this.iterationBudget) {
       options.iterationBudget = this.iterationBudget;
     }
@@ -379,6 +549,12 @@ export class SubAgentContext {
     if (this._mcpClient) {
       options.mcpClient = this._mcpClient;
     }
+    if (this._mcpCallLedger) {
+      options.mcpCallLedger = this._mcpCallLedger;
+    }
+    if (this._mcpConflictScheduler) {
+      options.mcpConflictScheduler = this._mcpConflictScheduler;
+    }
     // Inherited Pre/PostToolUse hooks (spawn passes the parent's, filtered by
     // the contract's `hooks` allow-list). Only set when non-null so a plain
     // sub-agent keeps its no-hooks default.
@@ -420,18 +596,31 @@ export class SubAgentContext {
           }
         }
 
-        if (event.type === "token-usage" && this._onUsage) {
-          // Forward real usage to the spawner. A nested child's event already
-          // carries its own attribution frame — preserve it (deepest wins).
-          try {
-            this._onUsage({
+        if (event.type === "token-usage") {
+          // Attributed usage was already charged by the nested child sharing
+          // this same authority. Only direct usage is folded here, otherwise a
+          // child-of-child would be counted once at every ancestor level.
+          if (!event.attribution && this.sessionBudget?.recordUsage) {
+            this.sessionBudget.recordUsage({
               provider: event.provider || null,
               model: event.model || null,
               usage: event.usage || null,
-              attribution: event.attribution || null,
             });
-          } catch (_e) {
-            // Usage forwarding is best-effort — never break the child loop
+          }
+          if (this._onUsage) {
+            // Forward real usage to the spawner. A nested child's event already
+            // carries its own attribution frame — preserve it (deepest wins).
+            try {
+              this._onUsage({
+                provider: event.provider || null,
+                model: event.model || null,
+                usage: event.usage || null,
+                ...(event.source ? { source: event.source } : {}),
+                attribution: event.attribution || null,
+              });
+            } catch (_e) {
+              // Usage forwarding is best-effort — never break the child loop
+            }
           }
         }
 
@@ -499,6 +688,13 @@ export class SubAgentContext {
         }
       }
     } catch (err) {
+      if (this.isAborted()) {
+        this.forceComplete(this._cancelReason || "cancelled", {
+          partialContent: lastContent,
+          artifacts,
+        });
+        return this.result;
+      }
       this.status = "failed";
       this.completedAt = new Date().toISOString();
       // Return partial work to the parent instead of discarding it: the
@@ -527,6 +723,13 @@ export class SubAgentContext {
     if (this.status !== "active") {
       return this.result;
     }
+    if (this.isAborted()) {
+      this.forceComplete(this._cancelReason || "cancelled", {
+        partialContent: lastContent,
+        artifacts,
+      });
+      return this.result;
+    }
 
     // Summarize the result
     const summary = this.summarize(lastContent);
@@ -590,7 +793,7 @@ export class SubAgentContext {
    * @returns {Array} Filtered AGENT_TOOLS
    */
   _getFilteredTools() {
-    if (!this.allowedTools || this.allowedTools.length === 0) {
+    if (this.allowedTools === null) {
       return AGENT_TOOLS;
     }
     return AGENT_TOOLS.filter((t) =>
@@ -638,10 +841,8 @@ export class SubAgentContext {
       parentTraceId: this._hookParentTraceId || null,
       checkpointIds: [...this._checkpointIds],
       toolUseIds: [...this._toolUseIds],
-      worktreeId:
-        worktree?.branch || this._worktreeBranch || null,
-      worktreePath:
-        worktree?.path || this._worktreePath || null,
+      worktreeId: worktree?.branch || this._worktreeBranch || null,
+      worktreePath: worktree?.path || this._worktreePath || null,
     };
   }
 
@@ -653,7 +854,10 @@ export class SubAgentContext {
    */
   isAborted() {
     return Boolean(
-      this._signal?.aborted || this._abortController.signal.aborted,
+      this._signal?.aborted ||
+      this._abortController.signal.aborted ||
+      this._runAbortController?.signal.aborted ||
+      this.sessionBudget?.signal?.aborted,
     );
   }
 
@@ -668,7 +872,11 @@ export class SubAgentContext {
       return false;
     }
     this._cancelReason = reason;
-    this._abortController.abort();
+    try {
+      this._abortController.abort(reason);
+    } catch {
+      this._abortController.abort();
+    }
     return true;
   }
 

package/src/lib/sub-agent-registry.js

@@ -182,6 +182,10 @@ export class SubAgentRegistry {
   forceCompleteAll(sessionId) {
     for (const [id, subCtx] of this._active) {
       if (!sessionId || subCtx.parentId === sessionId) {
+        // Trip the live loop's AbortSignal before recording a terminal result.
+        // forceComplete() alone only changed bookkeeping, so a provider/tool
+        // call could continue after the session had supposedly closed.
+        subCtx.abort?.("session-closed");
         subCtx.forceComplete("session-closed");
         this.complete(id, subCtx.result);
       }
@@ -215,6 +219,7 @@ export class SubAgentRegistry {
     const cutoff = Date.now() - maxAgeMs;
     for (const [id, subCtx] of this._active) {
       if (new Date(subCtx.createdAt).getTime() < cutoff) {
+        subCtx.abort?.("timeout");
         subCtx.forceComplete("timeout");
         this.complete(id, subCtx.result);
       }

package/src/lib/subagent-contract.js

@@ -72,6 +72,100 @@ export const SUBAGENT_EFFORT_LEVELS = Object.freeze([
 ]);
 const EFFORT_SYNONYMS = Object.freeze({ med: "medium", max: "xhigh" });
 
+function contractValidationError(field, message) {
+  const error = new Error(
+    `invalid subagent contract field "${field}": ${message}`,
+  );
+  error.code = "CC_SUBAGENT_CONTRACT_INVALID";
+  return error;
+}
+
+/**
+ * Strict validation for authority-bearing declarations at the spawn boundary.
+ * The legacy normalizer remains permissive for read/display callers, but a
+ * malformed explicit field must never silently become "unspecified" and widen
+ * a live child session.
+ */
+export function assertValidSubagentContract(raw = {}) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw contractValidationError("contract", "expected an object");
+  }
+  if (
+    raw.permissionMode != null &&
+    !SUBAGENT_PERMISSION_MODES.includes(raw.permissionMode)
+  ) {
+    throw contractValidationError(
+      "permissionMode",
+      `expected one of ${SUBAGENT_PERMISSION_MODES.join(", ")}`,
+    );
+  }
+  if (raw.context != null && !SUBAGENT_CONTEXT_MODES.includes(raw.context)) {
+    throw contractValidationError(
+      "context",
+      `expected one of ${SUBAGENT_CONTEXT_MODES.join(", ")}`,
+    );
+  }
+  for (const field of ["skills", "mcpServers", "hooks"]) {
+    const value = raw[field];
+    if (value == null) continue;
+    if (
+      typeof value !== "string" &&
+      !(
+        Array.isArray(value) &&
+        value.every((entry) => typeof entry === "string")
+      )
+    ) {
+      throw contractValidationError(field, "expected a string or string array");
+    }
+  }
+  for (const field of ["tools", "disallowedTools"]) {
+    const value = raw[field];
+    if (
+      value != null &&
+      !(
+        Array.isArray(value) &&
+        value.every((entry) => typeof entry === "string")
+      )
+    ) {
+      throw contractValidationError(field, "expected a string array");
+    }
+  }
+  for (const field of ["memory", "background"]) {
+    if (raw[field] != null && toBool(raw[field]) == null) {
+      throw contractValidationError(field, "expected a boolean value");
+    }
+  }
+  if (raw.effort != null) {
+    const effort = String(raw.effort).trim().toLowerCase();
+    const canonical = EFFORT_SYNONYMS[effort] || effort;
+    if (!SUBAGENT_EFFORT_LEVELS.includes(canonical)) {
+      throw contractValidationError(
+        "effort",
+        `expected one of ${SUBAGENT_EFFORT_LEVELS.join(", ")}`,
+      );
+    }
+  }
+  for (const field of ["maxDepth", "maxChildren"]) {
+    if (raw[field] != null && toPosInt(raw[field]) == null) {
+      throw contractValidationError(field, "expected a positive integer");
+    }
+  }
+  if (raw.budget != null) {
+    if (typeof raw.budget !== "object" || Array.isArray(raw.budget)) {
+      throw contractValidationError("budget", "expected an object");
+    }
+    for (const field of ["tokens", "cost", "costUsd", "time", "timeMs"]) {
+      if (raw.budget[field] != null && toPosNum(raw.budget[field]) == null) {
+        throw contractValidationError(
+          `budget.${field}`,
+          "expected a positive number",
+        );
+      }
+    }
+  }
+  return raw;
+}
+
 // ─── small pure helpers ─────────────────────────────────────────────────────
 
 function toBool(v) {