chainlesschain 0.162.161 → 0.162.163

package/src/runtime/agent-core.js

@@ -26,6 +26,7 @@ import sharedHookRunner from "../lib/hook-runner.cjs";
 import sharedHookEvents from "../lib/settings-hook-events.cjs";
 import { mergeProviderOptions } from "../lib/provider-options.js";
 import { applyCredentialProxy } from "../lib/credential-proxy.js";
+import { buildTelemetryAttributes } from "../lib/telemetry-ids.js";
 import { getPlanModeManager } from "../lib/plan-mode.js";
 import { CLISkillLoader } from "../lib/skill-loader.js";
 import { executeHooks, HookEvents } from "../lib/hook-manager.js";
@@ -1470,6 +1471,8 @@ export async function executeTool(name, args, context = {}) {
   try {
     toolResult = await executeToolInner(name, args, {
       skillLoader,
+      // Subagent skill capability INTERSECT — forwarded to run_skill/list_skills.
+      skillAllowlist: context.skillAllowlist ?? null,
       cwd,
       parentMessages: context.parentMessages,
       interaction: context.interaction,
@@ -1495,6 +1498,13 @@ export async function executeTool(name, args, context = {}) {
       settingsVerdict,
       subAgentDepth: context.subAgentDepth || 0,
       subAgentBudget: context.subAgentBudget || null,
+      // Effective contract of THIS loop (parent ceiling for a nested spawn) +
+      // the MCP tool definitions this loop exposes (inheritable by a spawn).
+      subAgentContract: context.subAgentContract || null,
+      extraToolDefinitions: context.extraToolDefinitions || null,
+      // Parent memory source — forwarded so a memory-granted spawn inherits it.
+      memoryDb: context.memoryDb || null,
+      permanentMemory: context.permanentMemory || null,
       interactiveApproval: context.interactiveApproval || false,
       settingsHooks: context.settingsHooks || null,
       signal: context.signal || null,
@@ -2095,6 +2105,7 @@ async function executeToolInner(
   args,
   {
     skillLoader,
+    skillAllowlist = null,
     cwd,
     parentMessages,
     interaction,
@@ -2102,7 +2113,11 @@ async function executeToolInner(
     hostManagedToolPolicy,
     externalToolDescriptors,
     externalToolExecutors,
+    extraToolDefinitions = null,
     mcpClient,
+    memoryDb = null,
+    permanentMemory = null,
+    subAgentContract = null,
     llmOptions,
     shellPolicyOverrides,
     classifyAllShell = false,
@@ -2127,6 +2142,13 @@ async function executeToolInner(
       : null;
   const runtimeDescriptor =
     getRuntimeToolDescriptor(name) || localToolDescriptor;
+  // Subagent skill capability INTERSECT: null = unrestricted; a list (possibly
+  // empty) restricts which skills run_skill/list_skills expose in this loop.
+  const _skillAllowlist = Array.isArray(skillAllowlist) ? skillAllowlist : null;
+  const skillAllowed = (s) =>
+    !_skillAllowlist ||
+    _skillAllowlist.includes(s.id) ||
+    _skillAllowlist.includes(s.dirName);
   const hostToolPolicies =
     hostManagedToolPolicy?.tools || hostManagedToolPolicy?.toolPolicies || null;
   const hostToolPolicy =
@@ -2902,8 +2924,20 @@ async function executeToolInner(
       // the run_shell gate). A settings `allow` rule (ruleAllowed) pre-
       // authorizes; headless leaves interactiveApproval false so its existing
       // per-permission-mode behavior is unchanged.
+      //
+      // A spawned sub-agent gets a dedicated CONFIRMER-LESS ApprovalGate for a
+      // strict/trusted mode (2026-07-13). It has no human to prompt, so gate
+      // run_code under it too — decide() auto-denies CONFIRM via no-confirmer,
+      // enforcing the tier on arbitrary code exactly like run_shell/browser_act
+      // (which already gate whenever an approvalGate is present). This is the
+      // child's gate specifically: the main headless + REPL gates ALWAYS carry a
+      // confirmer, so `!hasConfirmer()` leaves them byte-identical.
+      const policyGateNoConfirmer =
+        approvalGate &&
+        typeof approvalGate.hasConfirmer === "function" &&
+        !approvalGate.hasConfirmer();
       if (
-        interactiveApproval &&
+        (interactiveApproval || policyGateNoConfirmer) &&
         approvalGate &&
         !ruleAllowed &&
         typeof approvalGate.decide === "function"
@@ -2946,7 +2980,17 @@ async function executeToolInner(
           llmOptions,
           subAgentDepth,
           subAgentBudget,
+          subAgentContract,
           settingsHooks,
+          // Parent MCP plumbing — a spawn can inherit these into the child,
+          // filtered by the resolved contract's mcpServers allow-list.
+          mcpClient,
+          externalToolDescriptors,
+          externalToolExecutors,
+          extraToolDefinitions,
+          // Parent memory — inherited into the child only when contract grants it.
+          memoryDb,
+          permanentMemory,
           signal,
           backgroundSubAgents,
           subAgentUsageSink,
@@ -3157,6 +3201,26 @@ async function executeToolInner(
         const { parseDuration } = await import("../lib/loop.js");
         const store = new AgentScheduleStore();
         const action = String(args.action || "").toLowerCase();
+        // Optional lifecycle knobs shared by all create actions: `expires` is a
+        // duration after which an un-fired entry retires (never re-fires); `jitter`
+        // is a per-entry spread so tasks sharing a cron minute fan out instead of
+        // firing as a thundering herd.
+        const expiresInMs = args.expires ? parseDuration(args.expires) : null;
+        const jitterMs = args.jitter ? parseDuration(args.jitter) : 0;
+        // Optional per-task execution policy for wakeup/cron: the scheduled run
+        // can carry its OWN permission mode, worktree isolation and turn budget
+        // instead of inheriting whatever ambient env `cc agenda run` runs in.
+        // The store validates/drops each field; monitors ignore it.
+        const runPolicy = {
+          permissionMode: args.permission_mode || null,
+          worktree: args.worktree === true,
+          maxTurns: args.max_turns ?? null,
+          goalCondition: args.goal_condition || null,
+          maxOuterTurns: args.max_outer_turns ?? null,
+          goalMaxTokens: args.goal_max_tokens ?? null,
+          goalMaxCost: args.goal_max_cost ?? null,
+          goalMaxTime: args.goal_max_time ?? null,
+        };
         if (action === "wakeup") {
           if (!args.prompt) {
             return attachDescriptor({
@@ -3168,6 +3232,9 @@ async function executeToolInner(
             prompt: args.prompt,
             delayMs,
             label: args.label || null,
+            expiresInMs,
+            jitterMs,
+            ...runPolicy,
           });
           return attachDescriptor({
             scheduled: entry,
@@ -3184,6 +3251,9 @@ async function executeToolInner(
             prompt: args.prompt,
             cron: args.cron,
             label: args.label || null,
+            expiresInMs,
+            jitterMs,
+            ...runPolicy,
           });
           return attachDescriptor({ scheduled: entry });
         }
@@ -3203,6 +3273,8 @@ async function executeToolInner(
             notify: args.notify_title ? { title: args.notify_title } : null,
             maxChecks: args.max_checks ?? null,
             label: args.label || null,
+            expiresInMs,
+            jitterMs,
           });
           return attachDescriptor({ scheduled: entry });
         }
@@ -3548,11 +3620,12 @@ async function executeToolInner(
     }
 
     case "run_skill": {
-      const allSkills = skillLoader.getResolvedSkills();
+      const allSkills = skillLoader.getResolvedSkills().filter(skillAllowed);
       if (allSkills.length === 0) {
         return attachDescriptor({
-          error:
-            "No skills found. Make sure you're in the ChainlessChain project root or have skills installed.",
+          error: _skillAllowlist
+            ? "No skills are available to this sub-agent (restricted by its contract's skill allow-list)."
+            : "No skills found. Make sure you're in the ChainlessChain project root or have skills installed.",
         });
       }
       const match = allSkills.find(
@@ -3693,9 +3766,13 @@ async function executeToolInner(
     }
 
     case "list_skills": {
-      let skills = skillLoader.getResolvedSkills();
+      let skills = skillLoader.getResolvedSkills().filter(skillAllowed);
       if (skills.length === 0) {
-        return attachDescriptor({ error: "No skills found." });
+        return attachDescriptor({
+          error: _skillAllowlist
+            ? "No skills are available to this sub-agent (restricted by its contract's skill allow-list)."
+            : "No skills found.",
+        });
       }
       if (args.category) {
         skills = skills.filter(
@@ -4281,6 +4358,25 @@ async function _executeSpawnSubAgent(args, ctx) {
       error: `spawn_sub_agent: max nesting depth (${MAX_SUB_AGENT_DEPTH}) reached — complete the task directly instead of delegating further.`,
     };
   }
+  // Contract-aware recursion tightening: a parent's EFFECTIVE contract can only
+  // LOWER the absolute hard caps (fail-closed, tighten-only). Evaluated before
+  // the breadth counter increments so spawnedCount is this-spawn-exclusive.
+  if (ctx.subAgentContract) {
+    try {
+      const { enforceRecursionLimits } =
+        await import("../lib/subagent-contract.js");
+      const recur = enforceRecursionLimits({
+        depth: currentDepth,
+        spawnedCount: ctx.subAgentBudget?.spawned || 0,
+        contract: ctx.subAgentContract,
+        hardDepthCap: MAX_SUB_AGENT_DEPTH,
+        hardChildrenCap: ctx.subAgentBudget?.max ?? MAX_SUB_AGENTS_PER_RUN,
+      });
+      if (!recur.ok) return { error: `spawn_sub_agent: ${recur.reason}` };
+    } catch {
+      /* contract module unavailable — hard caps above still apply */
+    }
+  }
   // Breadth cap: a shared counter (one object for the whole tree) bounds the
   // TOTAL sub-agents a run may spawn, so a wide fan-out can't blow up even
   // within the depth limit. Refuse + count BEFORE any work so the increment
@@ -4321,6 +4417,7 @@ async function _executeSpawnSubAgent(args, ctx) {
   // Explicit role/tools still win over the agent file's values.
   let mdProfile = null;
   let mdModel = null;
+  let mdContract = null; // agent-file's normalized subagent contract (definition)
   if (args.agent) {
     try {
       const { getAgent } = await import("../lib/agents.js");
@@ -4340,6 +4437,7 @@ async function _executeSpawnSubAgent(args, ctx) {
         subIsolation = "worktree";
       }
       if (md.model) mdModel = md.model;
+      if (md.contract) mdContract = md.contract;
       if (md.systemPrompt) {
         mdProfile = { name: md.name, systemPrompt: md.systemPrompt };
       }
@@ -4356,6 +4454,118 @@ async function _executeSpawnSubAgent(args, ctx) {
     };
   }
 
+  // Resolve the child's EFFECTIVE subagent contract: spawnArgs > agent-file
+  // definition (mdContract) > parent ceiling (ctx.subAgentContract). The safe,
+  // tighten-only fields are consumed below (isolation fail-closed, budget,
+  // effort, context inheritance); this child's contract becomes the ceiling for
+  // ITS own nested spawns (threaded via SubAgentContext.subAgentContract).
+  let effectiveContract = null;
+  let explicitContext = null;
+  let skillAllowlist = null;
+  // MCP-server + hook allow-lists for child INHERITANCE. Default `[]` = inherit
+  // NONE, which equals today's behavior (a spawned child gets zero MCP tools /
+  // zero Pre-PostToolUse hooks). `context: fork` resolves these to `null` (all);
+  // an explicit list subsets them. See filterInherited* below.
+  let mcpAllow = [];
+  let hookAllow = [];
+  // Was the child's permission mode EXPLICITLY driven — a `permissionMode` in the
+  // spawn args / agent file, OR a NON-"default" parent ceiling from the run
+  // (`--permission-mode manual|acceptEdits|…`)? Only then do we attach an
+  // ApprovalGate to the child (below), so a plain default spawn stays ungated
+  // = byte-identical.
+  let permModeDriven = false;
+  try {
+    const { resolveSubagentContract, normalizeSubagentContract } =
+      await import("../lib/subagent-contract.js");
+    const spawnContract = normalizeSubagentContract(args);
+    explicitContext = spawnContract.context ?? mdContract?.context ?? null;
+    effectiveContract = resolveSubagentContract({
+      parent: ctx.subAgentContract || {},
+      definition: mdContract,
+      spawnArgs: spawnContract,
+    });
+    permModeDriven =
+      spawnContract.permissionMode != null ||
+      mdContract?.permissionMode != null ||
+      (ctx.subAgentContract?.permissionMode != null &&
+        ctx.subAgentContract.permissionMode !== "default");
+    // Skill capability INTERSECT: restrict the child's skills ONLY when it was
+    // explicitly driven — an explicit `skills` list (spawn args or agent file)
+    // OR an explicit `context` mode. A fully-defaulted spawn stays unrestricted
+    // (null) so the silent-`fresh`→[] default can never strip ALL skills from a
+    // plain sub-agent. `effectiveContract.skills` already encodes the intersect
+    // against the parent ceiling (tighten-only across depth).
+    const skillsDriven =
+      spawnContract.skills != null ||
+      mdContract?.skills != null ||
+      explicitContext != null;
+    skillAllowlist = skillsDriven ? (effectiveContract.skills ?? null) : null;
+    // MCP/hooks work the OTHER way from skills: their pre-inheritance default is
+    // "none", so the silent-`fresh`→[] resolution IS the safe current behavior —
+    // no explicit-driven guard needed. A list (or `null` on fork) opts the child
+    // into inheriting the corresponding parent capabilities.
+    mcpAllow = effectiveContract.mcpServers ?? null;
+    hookAllow = effectiveContract.hooks ?? null;
+  } catch {
+    effectiveContract = null; // contract resolution is best-effort
+    skillAllowlist = null;
+    mcpAllow = []; // inherit no MCP / hooks when resolution fails
+    hookAllow = [];
+    permModeDriven = false; // no gate when resolution fails
+  }
+
+  // Filter the parent loop's live MCP plumbing + settings hooks down to what the
+  // child may inherit. Default `[]` → null → the spawn passes nothing, so a plain
+  // sub-agent is byte-identical to before.
+  let inheritedMcp = null;
+  let inheritedHooks = null;
+  try {
+    const { filterInheritedMcp, filterInheritedHooks } =
+      await import("../lib/subagent-inheritance.js");
+    inheritedMcp = filterInheritedMcp(
+      {
+        extraToolDefinitions: ctx.extraToolDefinitions,
+        externalToolDescriptors: ctx.externalToolDescriptors,
+        externalToolExecutors: ctx.externalToolExecutors,
+        mcpClient: ctx.mcpClient,
+      },
+      mcpAllow,
+    );
+    inheritedHooks = filterInheritedHooks(ctx.settingsHooks || null, hookAllow);
+  } catch {
+    inheritedMcp = null; // inheritance is best-effort; never break the spawn
+    inheritedHooks = null;
+  }
+
+  // Memory INHERITANCE (contract `memory` boolean, tighten-only across depth):
+  // grant the child the parent's hierarchical-memory DB ONLY when the resolved
+  // contract says memory:true (explicit, or context:fork from a memory-bearing
+  // parent). Default (silent-`fresh`→memory:false) → no db + memoryEnabled:false
+  // → no recall = today's behavior. `effectiveContract.memory` already encodes
+  // the intersect (a parent that denied memory can never re-grant downstream).
+  const memoryGranted = effectiveContract?.memory === true;
+  const inheritedMemory =
+    memoryGranted && ctx.memoryDb
+      ? { db: ctx.memoryDb, permanentMemory: ctx.permanentMemory || null }
+      : null;
+
+  // Worktree isolation must FAIL CLOSED: if requested but the cwd is not a git
+  // repo, refuse the spawn instead of silently running in the parent checkout.
+  if (subIsolation === "worktree") {
+    try {
+      const { resolveIsolationFailClosed } =
+        await import("../lib/subagent-contract.js");
+      const { isGitRepo } = await import("../lib/git-integration.js");
+      const iso = resolveIsolationFailClosed({
+        requested: "worktree",
+        available: isGitRepo(ctx.cwd),
+      });
+      if (!iso.ok) return { error: `spawn_sub_agent: ${iso.reason}` };
+    } catch {
+      /* helper unavailable — sub-agent-context.js still fails closed at run() */
+    }
+  }
+
   // Phase 3: resolve declarative profile if requested. Explicit tools/context
   // override profile defaults; missing fields fall back to the profile.
   let profile = null;
@@ -4392,9 +4602,68 @@ async function _executeSpawnSubAgent(args, ctx) {
     allowedTools = base.filter((t) => !deny.has(t));
   }
 
-  // Auto-condense parent context if caller didn't provide explicit context
+  // permissionMode enforcement into the child gate. Reuses the runner's own
+  // resolvers (single-sourced, no drift); best-effort so it never breaks a spawn.
+  //  • `plan` → clamp to the read-only tool set (same rule as resolveEnabledTools),
+  //    so a plan sub-agent physically cannot mutate anything.
+  //  • confirmer threading → hand the child the mode's NON-interactive confirmer
+  //    as `permissionConfirm` (governs the ask / sensitive-file / destructive-git
+  //    gates) ONLY when it is the autopilot (bypassPermissions) ALLOW confirmer.
+  //    Every other mode's headless child already denies implicitly (no confirmer),
+  //    so we leave it unset to stay byte-identical — crucially preserving the
+  //    parallel-read fast-path + IDE-diff branch, both of which key off whether a
+  //    permissionConfirm is present.
+  //  • ApprovalGate sessionPolicy → attach the child its OWN ApprovalGate seeded
+  //    with the mode's tier (perm.sessionPolicy) and NO confirmer, so run_shell /
+  //    browser_act are gated per tier headlessly: strict denies MED/HIGH, trusted
+  //    denies only HIGH, autopilot allows all (CONFIRM→no-confirmer→DENY). A fresh
+  //    per-child gate (never the shared singleton) means zero interference with
+  //    the parent's global confirmer. Attached ONLY when the mode was explicitly
+  //    driven (permModeDriven) AND the tier actually gates (non-autopilot) — a
+  //    plain default spawn stays ungated = byte-identical; autopilot's gate would
+  //    be a pure no-op so it is skipped.
+  // `tightenPermissionMode` already stops a child EXCEEDING the parent's mode; a
+  // fully-defaulted spawn (→ "default") touches neither tools nor confirmer nor gate.
+  let childPermissionConfirm = null;
+  let childApprovalGate = null;
+  if (effectiveContract?.permissionMode) {
+    try {
+      const { resolvePermissionMode, resolveEnabledTools } =
+        await import("./headless-runner.js");
+      const perm = resolvePermissionMode(effectiveContract.permissionMode);
+      if (perm.readOnly) {
+        allowedTools = resolveEnabledTools({ allowedTools, readOnly: true });
+      }
+      // autopilot ⟺ bypassPermissions — the only mode whose headless confirmer
+      // ALLOWS. Threading a deny confirmer would needlessly disable the child's
+      // parallel-read fast-path, so restrict to the allow case.
+      if (
+        perm.sessionPolicy === "autopilot" &&
+        typeof perm.confirmer === "function"
+      ) {
+        childPermissionConfirm = perm.confirmer;
+      }
+      // Dedicated, confirmer-less child ApprovalGate for the strict/trusted tiers.
+      if (permModeDriven && perm.sessionPolicy !== "autopilot") {
+        const { ApprovalGate } = await import("@chainlesschain/session-core");
+        childApprovalGate = new ApprovalGate({
+          defaultPolicy: perm.sessionPolicy,
+        });
+      }
+    } catch {
+      // Enforcement is best-effort — never break the spawn.
+    }
+  }
+
+  // Auto-condense parent context if caller didn't provide explicit context.
+  // An explicit `context: fresh` contract suppresses this inheritance (the
+  // child starts clean); `fork` / unset keep the existing auto-condense.
   let resolvedContext = inheritedContext || null;
-  if (!resolvedContext && Array.isArray(ctx.parentMessages)) {
+  if (
+    !resolvedContext &&
+    explicitContext !== "fresh" &&
+    Array.isArray(ctx.parentMessages)
+  ) {
     const recentMsgs = ctx.parentMessages
       .filter((m) => m.role === "assistant" && typeof m.content === "string")
       .slice(-3)
@@ -4448,6 +4717,9 @@ async function _executeSpawnSubAgent(args, ctx) {
   const subLlmOptions = {
     ...parentLlm,
     model: mdModel || parentLlm.model || undefined,
+    // Contract `effort` is a compute hint (reasoning level), not authority —
+    // forwarded to the child loop; harmless if the provider ignores it.
+    ...(effectiveContract?.effort ? { effort: effectiveContract.effort } : {}),
   };
 
   // 用量归因: forward the child's real token usage into the parent run's sink
@@ -4502,6 +4774,48 @@ async function _executeSpawnSubAgent(args, ctx) {
     // worktree isolation. undefined keeps the profile/flag defaults intact.
     ...(subMaxTurns ? { maxIterations: subMaxTurns } : {}),
     ...(subIsolation === "worktree" ? { useWorktree: true } : {}),
+    // Resolved contract (gap 2026-07-12): cap the child's token budget and hand
+    // it its EFFECTIVE contract so its OWN spawns inherit this ceiling.
+    ...(effectiveContract?.budget?.tokens
+      ? { tokenBudget: effectiveContract.budget.tokens }
+      : {}),
+    ...(effectiveContract ? { subAgentContract: effectiveContract } : {}),
+    // Skill capability INTERSECT (2026-07-12): a non-null allow-list (possibly
+    // empty) restricts run_skill/list_skills in the child loop.
+    ...(skillAllowlist != null ? { skillAllowlist } : {}),
+    // MCP + hook capability INHERITANCE (2026-07-12): only non-null when the
+    // contract opted the child into inheriting (context:fork or an explicit
+    // list). filterInherited* already subset these to the allowed servers /
+    // matchers. Absent → child inherits neither (today's default).
+    ...(inheritedMcp
+      ? {
+          extraToolDefinitions: inheritedMcp.extraToolDefinitions,
+          externalToolDescriptors: inheritedMcp.externalToolDescriptors,
+          externalToolExecutors: inheritedMcp.externalToolExecutors,
+          mcpClient: inheritedMcp.mcpClient,
+        }
+      : {}),
+    ...(inheritedHooks ? { settingsHooks: inheritedHooks } : {}),
+    // Memory INHERITANCE (2026-07-12): grant the child the parent's memory DB
+    // (namespaced by the child's task id) only when the contract allows; else
+    // memoryEnabled:false hard-suppresses recall even if a db leaks through.
+    ...(inheritedMemory
+      ? {
+          db: inheritedMemory.db,
+          permanentMemory: inheritedMemory.permanentMemory,
+          memoryEnabled: true,
+        }
+      : { memoryEnabled: false }),
+    // permissionMode confirmer (2026-07-12): only set for the autopilot (bypass)
+    // ALLOW confirmer; absent for every other mode so the child stays
+    // implicitly-deny + byte-identical (parallel-read fast-path preserved).
+    ...(childPermissionConfirm
+      ? { permissionConfirm: childPermissionConfirm }
+      : {}),
+    // permissionMode ApprovalGate (2026-07-13): a dedicated confirmer-less gate
+    // seeded with the mode's tier gates the child's run_shell / browser_act;
+    // absent (ungated) for a plain default spawn = byte-identical.
+    ...(childApprovalGate ? { approvalGate: childApprovalGate } : {}),
   });
   subCtxRef = subCtx;
 
@@ -6041,6 +6355,30 @@ function _usageTokens(usage) {
   return { input, output, cacheRead, cacheWrite };
 }
 
+/**
+ * Best-effort text of the first user prompt in a message list, for the
+ * `--otlp-content` span attribute. Handles both string content and the
+ * multimodal `[{type:"text",text}, …]` shape; returns "" when none is found.
+ * Not exported (no shim-parity impact) — only the telemetry seam uses it.
+ */
+function extractInitialPromptText(messages) {
+  if (!Array.isArray(messages)) return "";
+  for (const msg of messages) {
+    if (!msg || msg.role !== "user") continue;
+    const content = msg.content;
+    if (typeof content === "string") return content;
+    if (Array.isArray(content)) {
+      const text = content
+        .filter((part) => part && part.type === "text" && part.text)
+        .map((part) => part.text)
+        .join("\n")
+        .trim();
+      if (text) return text;
+    }
+  }
+  return "";
+}
+
 export async function* agentLoop(messages, options) {
   // Shared iteration budget — replaces hardcoded MAX_ITERATIONS.
   // When options.iterationBudget is provided (e.g. from parent agent),
@@ -6055,13 +6393,28 @@ export async function* agentLoop(messages, options) {
   const toolContext = {
     hookDb: options.hookDb || null,
     skillLoader: options.skillLoader || _defaultSkillLoader,
+    // Contract-driven skill allow-list (subagent capability INTERSECT). null =
+    // unrestricted; [] = none; a list restricts run_skill/list_skills to those
+    // ids/dirNames. Set by the spawn path from the resolved subagent contract.
+    skillAllowlist: options.skillAllowlist ?? null,
     cwd: options.cwd || process.cwd(),
     planManager: options.planManager || null,
     sessionId: options.sessionId || null,
     hostManagedToolPolicy: options.hostManagedToolPolicy || null,
     externalToolDescriptors: options.externalToolDescriptors || null,
     externalToolExecutors: options.externalToolExecutors || null,
+    // MCP tool DEFINITIONS the LLM sees (mcp__server__tool). Threaded here so a
+    // spawn can inherit the parent's MCP tools into the child (filtered by the
+    // contract's mcpServers allow-list). Otherwise consumed only at agentLoop.
+    extraToolDefinitions: options.extraToolDefinitions || null,
     mcpClient: options.mcpClient || null,
+    // Parent memory source — a spawn can inherit the parent's hierarchical
+    // memory DB into the child ONLY when the resolved contract grants memory
+    // (context:fork from a memory-bearing parent, or explicit memory:true).
+    // Read off this loop's context engine (REPL sets one with db+permanentMemory).
+    memoryDb: options.contextEngine?.db ?? options.db ?? null,
+    permanentMemory:
+      options.contextEngine?.permanentMemory ?? options.permanentMemory ?? null,
     // Parent LLM config — forwarded to spawn_sub_agent so a delegated subagent
     // inherits the provider/key and can override just the model (cc agents `model:`).
     llmOptions: {
@@ -6105,6 +6458,10 @@ export async function* agentLoop(messages, options) {
       spawned: 0,
       max: MAX_SUB_AGENTS_PER_RUN,
     },
+    // This loop's EFFECTIVE subagent contract (set when this loop IS a spawned
+    // sub-agent). Threaded so a nested spawn_sub_agent sees it as the parent
+    // ceiling (tighten-only). null at the top level (no ceiling).
+    subAgentContract: options.subAgentContract || null,
     // Abort signal — forwarded to background sub-agents so cancelling the
     // parent run also cancels children still running detached.
     signal,
@@ -6234,12 +6591,28 @@ export async function* agentLoop(messages, options) {
   // an optional caller-provided workflow name) onto EVERY span this run emits,
   // so a collector can group one run's model/tool spans into one workflow.
   if (recorder && typeof recorder.setDefaultAttribute === "function") {
-    recorder.setDefaultAttribute("workflow.run_id", runId);
-    if (options.workflowName) {
-      recorder.setDefaultAttribute(
-        "workflow.name",
-        String(options.workflowName),
-      );
+    // Normalize the unified id set (P2 observability): every id is charset-
+    // sanitized + length-capped, and only these allow-listed keys are stamped,
+    // so span cardinality stays bounded and no content leaks in as an id.
+    const telemetryCtx = {
+      "workflow.run_id": runId,
+      "workflow.name": options.workflowName || undefined,
+      "session.id": options.sessionId || undefined,
+      "agent.id": options.agentId || undefined,
+      "parent_agent.id": options.parentAgentId || undefined,
+    };
+    // --otlp-content opt-in (P2): only when explicitly enabled do we feed the
+    // initial prompt through the redactor with includeContent — so a debugger
+    // can see which prompt a span belongs to. Default OFF omits the field
+    // entirely (not just redacts it), keeping default OTLP output byte-identical.
+    const includeContent = options.otlpIncludeContent === true;
+    if (includeContent) {
+      const promptText = extractInitialPromptText(messages);
+      if (promptText) telemetryCtx.prompt = promptText;
+    }
+    const idAttrs = buildTelemetryAttributes(telemetryCtx, { includeContent });
+    for (const [k, v] of Object.entries(idAttrs)) {
+      recorder.setDefaultAttribute(k, v);
     }
   }
   yield {

package/src/runtime/coding-agent-contract-shared.cjs

@@ -614,7 +614,7 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
           type: "string",
           enum: ["worktree"],
           description:
-            "Optional isolation mode: \"worktree\" runs the sub-agent in a fresh git worktree so its file edits land on an isolated branch (diff/merge summary comes back with the result).",
+            'Optional isolation mode: "worktree" runs the sub-agent in a fresh git worktree so its file edits land on an isolated branch (diff/merge summary comes back with the result).',
         },
       },
       required: ["task"],
@@ -959,6 +959,65 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
           type: "string",
           description: "Optional human label for list/cancel",
         },
+        expires: {
+          type: "string",
+          description:
+            "For wakeup/cron/monitor: retire the entry after this long if it hasn't fired (e.g. 2h, 7d); it then never fires",
+        },
+        jitter: {
+          type: "string",
+          description:
+            "For wakeup/cron/monitor: a random-but-stable spread (e.g. 30s) so entries sharing a schedule fan out instead of firing all at once",
+        },
+        permission_mode: {
+          type: "string",
+          enum: [
+            "plan",
+            "manual",
+            "default",
+            "acceptEdits",
+            "auto",
+            "dontAsk",
+            "bypassPermissions",
+          ],
+          description:
+            "For wakeup/cron: run the fired `cc agent` with this permission mode instead of the ambient one (e.g. `plan` for a read-only report, `manual` to gate every action)",
+        },
+        worktree: {
+          type: "boolean",
+          description:
+            "For wakeup/cron: run the fired `cc agent` in a fresh git worktree so its changes stay isolated",
+        },
+        max_turns: {
+          type: "number",
+          description:
+            "For wakeup/cron: cap the fired agent's loop iterations (a per-task budget)",
+        },
+        goal_condition: {
+          type: "string",
+          description:
+            "For wakeup/cron: run the fired agent to a completion condition, re-driving outer turns until met. Prefix exit-zero:/file-exists:/contains:/regex: (deterministic) or model:<desc> (model-judged). Invalid specs are dropped.",
+        },
+        max_outer_turns: {
+          type: "number",
+          description:
+            "For wakeup/cron with goal_condition: max outer re-drive turns (default 10, hard cap 100)",
+        },
+        goal_max_tokens: {
+          type: "number",
+          description:
+            "For wakeup/cron with goal_condition: token budget across outer turns",
+        },
+        goal_max_cost: {
+          type: "number",
+          description:
+            "For wakeup/cron with goal_condition: cost budget (USD) across outer turns",
+        },
+        goal_max_time: {
+          type: "number",
+          description:
+            "For wakeup/cron with goal_condition: wall-clock budget (ms) across outer turns",
+        },
         id: {
           type: "string",
           description: "For cancel: the schedule entry id to remove",