@cydm/pie 2.7.6 → 2.7.7

package/dist/chunks/{chunk-YWWLRZSG.js → chunk-UPGEXDEQ.js}

@@ -2,7 +2,7 @@ import { createRequire as __createRequire } from "node:module"; const require =
 import {
   Agent,
   getToolCallerIdentity
-} from "./chunk-5YWEUFLM.js";
+} from "./chunk-W5B3OXHQ.js";
 import {
   AssistantMessageEventStream,
   FileSystemGateway,
@@ -12,7 +12,7 @@ import {
   getPlatformConfig,
   hashText,
   streamSimple
-} from "./chunk-ZF5FHTES.js";
+} from "./chunk-2FEDB5GR.js";
 import {
   Type
 } from "./chunk-XXGYUYXI.js";
@@ -899,11 +899,6 @@ function shouldPreserveExecutionStateForUserText(text) {
   return CONTINUE_PATTERNS.some((pattern) => pattern.test(trimmed));
 }
 
-// ../../packages/shared-headless-capabilities/src/capability.ts
-function defineSharedCapability(definition) {
-  return definition;
-}
-
 // ../../packages/shared-headless-capabilities/src/tool-policy.ts
 var BUILTIN_TOOL_CAPABILITY_METADATA = {
   search_context: { riskClass: "read_only", concurrencySafe: true, permissionScope: "session", availableInPlanMode: true, allowedForSubagentByDefault: false, maxOutputChars: 2e4 },
@@ -914,6 +909,7 @@ var BUILTIN_TOOL_CAPABILITY_METADATA = {
   write_file: { riskClass: "write", concurrencySafe: false, requiresPermission: true, permissionScope: "filesystem", writesFile: true, highRisk: true },
   edit_file: { riskClass: "write", concurrencySafe: false, requiresPermission: true, permissionScope: "filesystem", writesFile: true, highRisk: true },
   bash: { riskClass: "shell", concurrencySafe: false, requiresPermission: true, permissionScope: "shell", executesShell: true, availableInPlanMode: true, allowedForSubagentByDefault: true, highRisk: true, maxOutputChars: 1e5 },
+  shell: { riskClass: "shell", concurrencySafe: false, requiresPermission: true, permissionScope: "shell", executesShell: true, availableInPlanMode: true, allowedForSubagentByDefault: true, highRisk: true, maxOutputChars: 1e5 },
   web_research: { riskClass: "network", concurrencySafe: true, permissionScope: "network", readsNetwork: true, availableInPlanMode: true, allowedForSubagentByDefault: true, maxOutputChars: 1e5 },
   web_search: { riskClass: "network", concurrencySafe: true, permissionScope: "network", readsNetwork: true, availableInPlanMode: true, allowedForSubagentByDefault: true, maxOutputChars: 1e5 },
   web_fetch: { riskClass: "network", concurrencySafe: true, permissionScope: "network", readsNetwork: true, availableInPlanMode: true, allowedForSubagentByDefault: true, maxOutputChars: 1e5 },
@@ -975,6 +971,11 @@ function getSubagentToolPolicyDecision(tool) {
 }
 var DEFAULT_PLAN_MODE_TOOL_NAMES = Object.entries(BUILTIN_TOOL_CAPABILITY_METADATA).filter(([, metadata]) => metadata.availableInPlanMode).map(([name]) => name);
 
+// ../../packages/shared-headless-capabilities/src/capability.ts
+function defineSharedCapability(definition) {
+  return definition;
+}
+
 // ../../packages/shared-headless-capabilities/src/plan.ts
 var import_shell_quote = __toESM(require_shell_quote(), 1);
 var SIMPLE_READ_COMMANDS = /* @__PURE__ */ new Set(["pwd", "ls", "cat", "head", "tail", "wc", "grep", "rg", "which", "type", "echo", "printf", "cd", "true", "false", "tree", "jq", "stat", "file", "du", "df", "basename", "dirname", "date", "uname", "sort", "uniq", "cut", "column", "shasum", "printenv"]);
@@ -1752,6 +1753,9 @@ function normalizeUserContentBlock(block) {
   if (block.type === "text") {
     return { type: "text", text: block.text };
   }
+  if (block.type === "hostContext") {
+    return { type: "text", text: "x".repeat(512) };
+  }
   if (block.type === "image") {
     return { type: "image", mimeType: block.mimeType };
   }
@@ -1932,6 +1936,107 @@ function getSessionEntryText(entry) {
   }).filter(Boolean).join("\n");
 }
 
+// ../../packages/agent-framework/src/session/host-envelope.ts
+import { createHash } from "node:crypto";
+function createHostEnvelopeProjectorRegistry(projectors = []) {
+  const byKey = /* @__PURE__ */ new Map();
+  const latestByKind = /* @__PURE__ */ new Map();
+  const key = (kind, version) => `${kind}@${version}`;
+  for (const projector of projectors) validateAndIndex(projector);
+  function validateAndIndex(input) {
+    if (!input.kind || typeof input.kind !== "string") throw new Error("Host envelope projector requires a kind.");
+    if (!Number.isInteger(input.version) || input.version < 1) throw new Error(`Host envelope projector ${input.kind} requires an integer version >= 1.`);
+    if (typeof input.project !== "function") throw new Error(`Host envelope projector ${input.kind} requires a project function.`);
+    const projector = Object.freeze({
+      kind: input.kind,
+      version: input.version,
+      project: input.project
+    });
+    const existing = byKey.get(key(projector.kind, projector.version));
+    if (existing && existing.project !== projector.project) {
+      throw new Error(`Duplicate host envelope projector registration for ${projector.kind}@${projector.version}: a version's text must never change after registration.`);
+    }
+    byKey.set(key(projector.kind, projector.version), projector);
+    const currentLatest = latestByKind.get(projector.kind);
+    if (!currentLatest || projector.version > currentLatest.version) latestByKind.set(projector.kind, projector);
+  }
+  return {
+    register: validateAndIndex,
+    resolve: (kind, version) => byKey.get(key(kind, version)),
+    latest: (kind) => latestByKind.get(kind),
+    listPins: () => [...byKey.values()].map(({ kind, version }) => ({ kind, version }))
+  };
+}
+function projectHostContextBlock(block, registry) {
+  let hash;
+  try {
+    hash = createHash("sha256").update(JSON.stringify({ kind: block.kind, version: block.version, data: block.data })).digest("hex").slice(0, 16);
+  } catch {
+    hash = "unhashable";
+  }
+  const projector = registry.resolve(block.kind, block.version);
+  if (!projector) {
+    return {
+      text: `runtime state: unknown (projector missing: ${block.kind}@${block.version})`,
+      degraded: true,
+      audit: { kind: block.kind, version: block.version, hash }
+    };
+  }
+  try {
+    const text = projector.project(block.data);
+    if (typeof text !== "string" || text.trim().length === 0) throw new Error("projector returned empty text");
+    return { text, degraded: false, audit: { kind: block.kind, version: block.version, hash } };
+  } catch (error) {
+    return {
+      text: `runtime state: unknown (projector failed: ${block.kind}@${block.version}: ${error instanceof Error ? error.message.slice(0, 120) : String(error).slice(0, 120)})`,
+      degraded: true,
+      audit: { kind: block.kind, version: block.version, hash }
+    };
+  }
+}
+function leadingHostContextBlock(message) {
+  if (message.role !== "user") return void 0;
+  const content = message.content;
+  if (!Array.isArray(content) || content.length === 0) return void 0;
+  const first = content[0];
+  if (!isHostContextBlock(first)) return void 0;
+  return first;
+}
+function projectHostEnvelopes(messages, registry, onProjection) {
+  let changed = false;
+  const next = [];
+  for (const message of messages) {
+    const block = leadingHostContextBlock(message);
+    if (!block) {
+      next.push(message);
+      continue;
+    }
+    const outcome = projectHostContextBlock(block, registry);
+    onProjection?.(outcome);
+    const content = message.content;
+    const rest = content.slice(1);
+    const first = rest[0];
+    let projectedContent;
+    if (first && first.type === "text" && typeof first.text === "string") {
+      const merged = first.text.trim().length > 0 ? `${outcome.text}
+
+${first.text}` : outcome.text;
+      projectedContent = [{ ...first, text: merged }, ...rest.slice(1)];
+    } else {
+      projectedContent = [{ type: "text", text: outcome.text }, ...rest];
+    }
+    next.push({ ...message, content: projectedContent });
+    changed = true;
+  }
+  return changed ? next : messages;
+}
+function isHostContextBlock(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const block = value;
+  const version = block.version;
+  return block.type === "hostContext" && typeof block.kind === "string" && block.kind.length > 0 && block.kind.length <= 128 && typeof version === "number" && Number.isInteger(version) && version >= 1 && !!block.data && typeof block.data === "object" && !Array.isArray(block.data);
+}
+
 // ../../packages/agent-framework/src/session/store.ts
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
@@ -2972,7 +3077,19 @@ function normalizeSessionDisplayName(raw) {
 }
 function isSyntheticEnvelopePreview(preview) {
   const trimmed = preview.trimStart();
-  return trimmed.startsWith("<environment_context>") || trimmed.startsWith("<turn_aborted>") || trimmed.startsWith("# AGENTS.md instructions") || trimmed.startsWith("## Project Context\nProject-specific instructions from AGENTS.md");
+  if (trimmed.startsWith("<environment_context>") || trimmed.startsWith("<turn_aborted>") || trimmed.startsWith("# AGENTS.md instructions") || trimmed.startsWith("## Project Context\nProject-specific instructions from AGENTS.md")) {
+    return true;
+  }
+  const runtimeMatch = trimmed.match(/^<runtime-mode-context>[\s\S]*?<\/runtime-mode-context>/);
+  if (runtimeMatch) {
+    const rest = trimmed.slice(runtimeMatch[0].length).trim();
+    if (rest.length === 0) return true;
+    return false;
+  }
+  if (trimmed.startsWith("<runtime-mode-context>")) {
+    return true;
+  }
+  return /^HE_INPUT kind=(?:USER_REQUEST|QUEUE_WAKE) source=/.test(trimmed);
 }
 function isAutoGeneratedSessionName(name) {
   return /^Session (\d|[a-z0-9]{6,8}$)/i.test(name.trim());
@@ -2986,7 +3103,10 @@ function userEntryPreview(entry) {
   if (!message) return "";
   if (typeof message.content === "string") return message.content;
   if (!Array.isArray(message.content)) return "";
-  return message.content.map((block) => isRecord2(block) && block.type === "text" && typeof block.text === "string" ? block.text : "").join(" ").trim();
+  return message.content.map((block) => {
+    if (isRecord2(block) && block.type === "hostContext") return "";
+    return isRecord2(block) && block.type === "text" && typeof block.text === "string" ? block.text : "";
+  }).join(" ").trim();
 }
 function entryJsonBytes(entry) {
   try {
@@ -4917,7 +5037,7 @@ function isUserContentBlock(value) {
     return false;
   }
   const type = value.type;
-  return type === "text" || type === "image" || type === "audio" || type === "video" || type === "fileRef";
+  return type === "text" || type === "image" || type === "audio" || type === "video" || type === "fileRef" || type === "hostContext";
 }
 function normalizePromptInput(input) {
   if (typeof input === "string") {
@@ -5629,7 +5749,7 @@ function toolOutcomeKind(event) {
   return typeof kind === "string" ? kind : void 0;
 }
 function isCommandNonzero(event) {
-  return event.toolName === "bash" && toolOutcomeKind(event) === "command_nonzero";
+  return toolOutcomeKind(event) === "command_nonzero";
 }
 function isStateChangingSuccess(event) {
   if (event.isError) return false;
@@ -5637,7 +5757,7 @@ function isStateChangingSuccess(event) {
   if (outcomeKind === "command_nonzero" || outcomeKind === "timeout" || outcomeKind === "signal") return false;
   if (event.toolName === "edit_file" || event.toolName === "write_file") return true;
   const details = event.result && typeof event.result === "object" ? event.result.details : void 0;
-  return event.toolName === "bash" && details?.commandClass === "filesystem_write";
+  return details?.commandClass === "filesystem_write";
 }
 var AgentSessionRuntimeGuard = class {
   constructor(trigger, advise) {
@@ -7915,14 +8035,22 @@ var SessionTraceSnapshotWriter = class {
 
 // ../../packages/agent-framework/src/delegation.ts
 var DELEGATION_REPORT_MAX_CHARS = 24e3;
-var DELEGATION_REPORT_INSTRUCTION = 'Return your final response once as a JSON object: {"summary":string,"result":string,"remainingWork"?:string[],"evidenceRefs"?:string[]}. Do not make an extra tool call to report. Evidence references are your claims, not runtime verification.';
+var DELEGATION_REPORT_INSTRUCTION = 'Return your final response once as a JSON object: {"summary":string,"result":string,"remainingWork"?:string[],"evidenceRefs"?:string[]}. Keep the entire JSON response within 24,000 characters: give concise conclusions and bounded evidence references, not repeated drafting notes. Do not make an extra tool call to report. Evidence references are your claims, not runtime verification.';
 function parseDelegationReport(text, runId, truncated = false) {
   const raw = (text ?? "").slice(0, DELEGATION_REPORT_MAX_CHARS);
   const base = { version: 1, runId: runId.slice(0, 160), raw };
-  if (truncated || (text?.length ?? 0) > DELEGATION_REPORT_MAX_CHARS) return { ...base, availability: "truncated" };
-  if (!raw.trim()) return { ...base, availability: "missing" };
+  const stopReason = typeof truncated === "string" ? truncated.slice(0, 40) : void 0;
+  const reason = stopReason === "length" ? "provider_length" : ["error", "aborted", "deadline", "cancelled", "no_terminal"].includes(stopReason ?? "") ? stopReason : stopReason && stopReason !== "stop" ? "no_terminal" : truncated === true ? "provider_length" : void 0;
+  if (reason) return { ...base, stopReason, reason, availability: raw ? "truncated" : "missing" };
+  if ((text?.length ?? 0) > DELEGATION_REPORT_MAX_CHARS) return { ...base, availability: "truncated", reason: "char_cap" };
+  if (!raw.trim()) return { ...base, availability: "missing", reason: "empty" };
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return { ...base, availability: "malformed", reason: "invalid_json" };
+  }
   try {
-    const value = JSON.parse(raw);
     if (!value || typeof value !== "object" || Array.isArray(value) || typeof value.summary !== "string" || typeof value.result !== "string") throw new Error();
     if (Object.keys(value).some((key) => !["summary", "result", "remainingWork", "evidenceRefs"].includes(key))) throw new Error();
     for (const key of ["remainingWork", "evidenceRefs"]) {
@@ -7930,7 +8058,7 @@ function parseDelegationReport(text, runId, truncated = false) {
     }
     return { ...base, availability: "available", report: value };
   } catch {
-    return { ...base, availability: "malformed" };
+    return { ...base, availability: "malformed", reason: "invalid_shape" };
   }
 }
 function observeDelegationPhase(observation, phase, workActivity = true) {
@@ -7959,6 +8087,58 @@ function observeDelegationTool(observation, event) {
   if (observation.receipts.length > 32) observation.receipts.shift();
 }
 
+// ../../packages/shared-headless-capabilities/src/subagent-usage.ts
+function createSubagentUsage(sessionId, runId) {
+  return { sessionId, runId, attempts: 0, reportedAttempts: 0, unknownAttempts: 0, pendingAttempts: 0, status: "pending", reportedTokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cacheWriteLong: 0, totalTokens: 0 }, estimatedCost: null };
+}
+function settleSubagentUsage(usage, settled) {
+  usage.status = !settled || usage.pendingAttempts > 0 ? "pending" : usage.attempts === 0 || usage.reportedAttempts === 0 ? "unknown" : usage.unknownAttempts > 0 ? "partial" : "complete";
+}
+function beginSubagentUsage(usage, model) {
+  usage.attempts++;
+  usage.pendingAttempts++;
+  let ended = false;
+  return (message) => {
+    if (ended) return;
+    ended = true;
+    usage.pendingAttempts--;
+    const values = message?.usage;
+    const known = message?.usageReported === true && values && [values.input, values.output, values.cacheRead, values.cacheWrite, values.totalTokens].every((n) => Number.isFinite(n) && n >= 0);
+    if (known) {
+      usage.reportedAttempts++;
+      for (const key of Object.keys(usage.reportedTokens)) usage.reportedTokens[key] += values[key] ?? 0;
+    } else usage.unknownAttempts++;
+    const priced = known && ["input", "output", "cacheRead", "cacheWrite"].every((key) => typeof model?.cost?.[key] === "number" && Number.isFinite(model.cost[key]) && model.cost[key] >= 0) && Object.values(model.cost).some((value) => typeof value === "number" && value > 0) && Number.isFinite(values.cost?.total) && values.cost.total >= 0;
+    if (usage.attempts === 1 && priced) usage.estimatedCost = values.cost.total;
+    else if (priced && usage.estimatedCost !== null) usage.estimatedCost += values.cost.total;
+    else usage.estimatedCost = null;
+  };
+}
+function restoreSubagentUsageRuns(value) {
+  if (!Array.isArray(value)) return void 0;
+  return value.slice(-4).flatMap((item) => {
+    if (!item || typeof item !== "object" || typeof item.sessionId !== "string" || typeof item.runId !== "string" || item.sessionId.length > 160 || item.runId.length > 160 || !["pending", "partial", "complete", "unknown"].includes(item.status)) return [];
+    if (![item.attempts, item.reportedAttempts, item.unknownAttempts, item.pendingAttempts].every((n) => Number.isSafeInteger(n) && n >= 0)) return [];
+    if (item.reportedAttempts + item.unknownAttempts + item.pendingAttempts !== item.attempts) return [];
+    const tokens = item.reportedTokens;
+    const keys = ["input", "output", "cacheRead", "cacheWrite", "cacheWriteLong", "totalTokens"];
+    if (!tokens || !keys.every((key) => Number.isFinite(tokens[key]) && tokens[key] >= 0)) return [];
+    const expectedStatus = item.pendingAttempts > 0 ? "pending" : item.reportedAttempts === 0 ? "unknown" : item.unknownAttempts > 0 ? "partial" : "complete";
+    if (item.status !== expectedStatus && !(item.status === "pending" && item.attempts === 0)) return [];
+    return [{
+      sessionId: item.sessionId,
+      runId: item.runId,
+      attempts: item.attempts,
+      reportedAttempts: item.reportedAttempts,
+      unknownAttempts: item.unknownAttempts,
+      pendingAttempts: item.pendingAttempts,
+      status: item.status,
+      reportedTokens: Object.fromEntries(keys.map((key) => [key, tokens[key]])),
+      estimatedCost: item.reportedAttempts > 0 && item.unknownAttempts === 0 && item.pendingAttempts === 0 && typeof item.estimatedCost === "number" && Number.isFinite(item.estimatedCost) && item.estimatedCost >= 0 ? item.estimatedCost : null
+    }];
+  });
+}
+
 // ../../packages/shared-headless-capabilities/src/subagent-stream.ts
 var SUBAGENT_FINALIZATION_HINT = "The run's soft deadline has arrived. Do not start new tools. Return the requested final report now, including remaining work; already-running tools may finish.";
 function subagentSoftDeadlineMs(budgetMs) {
@@ -7969,6 +8149,10 @@ function withSubagentRunContext(stream, hooks) {
     if (hooks.hardDeadlineAt !== void 0 && Date.now() >= hooks.hardDeadlineAt) throw new Error("Subagent hard deadline reached");
     if (hooks.softDeadlineAt !== void 0 && Date.now() >= hooks.softDeadlineAt) hooks.finalizing = true;
     if (hooks.observation) observeDelegationPhase(hooks.observation, hooks.finalizing ? "finalizing" : "request");
+    try {
+      hooks.onPhase?.(hooks.finalizing ? "finalizing" : "request");
+    } catch {
+    }
     return stream(model, hooks.finalizing ? { ...context, systemPrompt: `${context.systemPrompt ?? ""}
 
 ${SUBAGENT_FINALIZATION_HINT}` } : context, options);
@@ -7992,11 +8176,17 @@ function cancellableBackoff(ms, signal) {
     if (signal?.aborted) finish();
   });
 }
-function withSubagentResponseRecovery(stream, backoffMs = 2e3, onRetry, onActivity) {
+function withSubagentResponseRecovery(stream, backoffMs = 2e3, onRetry, onActivity, hooks) {
   return async (model, context, options) => {
     for (let attempt = 0; ; attempt++) {
+      if (hooks) {
+        hooks.terminalText = void 0;
+        hooks.terminalStopReason = void 0;
+      }
       if (options?.signal?.aborted) throw new Error("Subagent aborted by parent");
+      if (hooks?.hardDeadlineAt !== void 0 && Date.now() >= hooks.hardDeadlineAt) throw new Error("Subagent hard deadline reached");
       let message;
+      const finishUsage = hooks?.usage ? beginSubagentUsage(hooks.usage, model) : void 0;
       try {
         const response = await stream(model, context, options);
         let terminal;
@@ -8009,8 +8199,19 @@ function withSubagentResponseRecovery(stream, backoffMs = 2e3, onRetry, onActivi
               onActivity?.(next.value.type);
             } catch {
             }
-            if (next.value.type === "done") terminal = next.value.message;
-            if (next.value.type === "error") terminal = next.value.error;
+            if (next.value.type === "done") {
+              terminal = next.value.message;
+              finishUsage?.(terminal);
+            }
+            if (next.value.type === "error") {
+              terminal = next.value.error;
+              finishUsage?.(terminal);
+            }
+            if (hooks && (next.value.type === "done" || next.value.type === "error")) {
+              const reportTerminal = terminal && ["stop", "length", "error", "aborted"].includes(terminal.stopReason) && !terminal.content.some((block) => block.type === "toolCall");
+              hooks.terminalStopReason = reportTerminal && terminal ? terminal.stopReason : void 0;
+              hooks.terminalText = reportTerminal && terminal ? terminal.content.filter((block) => block.type === "text").map((block) => block.text).join("\n").slice(0, 24001) : void 0;
+            }
           }
         } finally {
           try {
@@ -8021,6 +8222,7 @@ function withSubagentResponseRecovery(stream, backoffMs = 2e3, onRetry, onActivi
         if (!terminal) throw new Error("Provider protocol error: response ended without a terminal event");
         message = terminal;
       } catch (error) {
+        finishUsage?.();
         if (!options?.signal?.aborted && attempt < 2 && isRetryableSubagentFailure(error instanceof Error ? error.message : String(error))) {
           try {
             onRetry?.();
@@ -8110,6 +8312,7 @@ function toSessionRecord(session, messages) {
     runCount: session.runCount,
     revision: session.revision,
     reports: session.reports?.slice(-4),
+    usageRuns: session.usageRuns?.slice(-4).map((usage) => ({ ...usage, reportedTokens: { ...usage.reportedTokens } })),
     messages
   };
 }
@@ -8184,6 +8387,7 @@ var POWERSHELL_DESTRUCTIVE_PATTERNS = [
   { pattern: /\bRemove-Item\b[^;\n|]*(?:HKLM:|HKCU:|Registry::)/i, warning: "may remove registry entries", commandClass: "infra_destructive" },
   { pattern: /\b(Set-ExecutionPolicy|Start-Process\b[^;\n|]*-Verb\s+RunAs)\b/i, warning: "may change execution policy or request elevation", commandClass: "privilege_escalation" },
   { pattern: /\b(Stop-Computer|Restart-Computer)\b/i, warning: "may stop or restart the machine", commandClass: "infra_destructive" },
+  { pattern: /(^|[;|&\n])\s*(?:Invoke-Expression|iex)\b/i, warning: "evaluates a dynamically constructed string as code", commandClass: "privilege_escalation" },
   { pattern: /\bgit\s+reset\s+--hard\b/i, warning: "may discard uncommitted changes", commandClass: "git_destructive" },
   { pattern: /\bgit\s+push\b[^;&|\n]*[ \t](--force|--force-with-lease|-f)\b/i, warning: "may overwrite remote history", commandClass: "git_destructive" }
 ];
@@ -8602,13 +8806,13 @@ function wrapBashGuard(tool, plan) {
   return {
     ...tool,
     description: `${tool.description}
-Subagent guarded mode uses the same bash risk policy as the parent agent. Destructive commands are blocked; normal diagnostic, search, test, and build commands are allowed.`,
+Subagent guarded mode blocks destructive shell commands while preserving the parent's execution checks. Destructive commands are blocked; normal diagnostic, search, test, and build commands are allowed.`,
     execute: async (toolCallId, params, signal, onUpdate) => {
       const command = typeof params?.command === "string" ? params.command : "";
       const classification = classifyBashCommand(command);
       if (classification.destructive) {
-        const reason = `destructive bash command blocked for subagent: ${classification.riskWarnings.join("; ")}`;
-        plan.toolsExcluded.push({ name: "bash", reason });
+        const reason = `destructive shell command blocked for subagent: ${classification.riskWarnings.join("; ")}`;
+        plan.toolsExcluded.push({ name: tool.name, reason });
         return {
           content: [{ type: "text", text: reason }],
           details: {
@@ -8636,10 +8840,6 @@ function filterToolsForSubagent(runtimeTools, parentTools, plan, mode) {
       plan.toolsExcluded.push({ name: tool.name, reason: "not available in parent tool set" });
       continue;
     }
-    if (tool.name === "bash") {
-      filtered.push(wrapBashGuard(tool, plan));
-      continue;
-    }
     if (mode === "edit" && (tool.name === "write_file" || tool.name === "edit_file")) {
       filtered.push(tool);
       continue;
@@ -8649,7 +8849,7 @@ function filterToolsForSubagent(runtimeTools, parentTools, plan, mode) {
       plan.toolsExcluded.push({ name: tool.name, reason: policy.reason || "not allowed for subagent" });
       continue;
     }
-    filtered.push(tool);
+    filtered.push(getToolCapabilityMetadata(tool)?.executesShell === true ? wrapBashGuard(tool, plan) : tool);
   }
   return filtered;
 }
@@ -8745,12 +8945,13 @@ function createAgentInstance(deps, systemPrompt, tools, model, apiKey, thinkingL
     }
   }), hooks), deps.transientRetryBackoffMs, () => {
     if (hooks.observation) observeDelegationPhase(hooks.observation, "response_retry");
+    hooks.onPhase?.("response_retry");
   }, () => {
     if (hooks.observation) {
       hooks.observation.lastWorkAt = Date.now();
       hooks.observation.lastActivity = "response_event";
     }
-  });
+  }, hooks);
   if (deps.createAgent) {
     const agent2 = deps.createAgent({
       streamFn,
@@ -8780,7 +8981,7 @@ function createAgentInstance(deps, systemPrompt, tools, model, apiKey, thinkingL
   return agent;
 }
 function isParentHandoffRequired(task) {
-  return task.mode === "edit" || task.status === "timeout" || task.status === "failed" || task.confidenceSignals.some((signal) => signal.type === "tool_error" || signal.type === "no_tool_use" || signal.type === "no_text_report");
+  return task.report?.availability !== "available" || task.mode === "edit" || task.status === "timeout" || task.status === "failed" || task.confidenceSignals.some((signal) => signal.type === "tool_error" || signal.type === "no_tool_use" || signal.type === "no_text_report");
 }
 function shellFromRecord(record) {
   return {
@@ -8794,7 +8995,12 @@ function shellFromRecord(record) {
     timeoutSeconds: record.timeoutSeconds,
     agent: null,
     pendingMessages: record.messages,
-    reports: Array.isArray(record.reports) ? record.reports.slice(-4).map((report) => parseDelegationReport(typeof report?.raw === "string" ? report.raw : void 0, typeof report?.runId === "string" ? report.runId : "legacy", report?.availability === "truncated")) : void 0,
+    reports: Array.isArray(record.reports) ? record.reports.slice(-4).map((report) => {
+      const parsed = parseDelegationReport(typeof report?.raw === "string" ? report.raw : void 0, typeof report?.runId === "string" ? report.runId : "legacy", report?.stopReason ?? report?.availability === "truncated");
+      if (["empty", "invalid_json", "invalid_shape", "char_cap", "provider_length", "error", "aborted", "deadline", "cancelled", "no_terminal"].includes(report?.reason ?? "")) parsed.reason = report.reason;
+      return parsed;
+    }) : void 0,
+    usageRuns: restoreSubagentUsageRuns(record.usageRuns),
     createdAt: record.createdAt,
     lastUsedAt: record.lastUsedAt,
     runCount: record.runCount,
@@ -8876,7 +9082,7 @@ async function persistSubagentSession(deps, session, task) {
   if (task.status === "completed" && task.result && transcriptChars > SESSION_TRANSCRIPT_WARN_CHARS) {
     task.result += `
 
-[Session growth warning: session ${session.id} now carries ~${Math.round(transcriptChars / 4)} tokens of transcript; every recall pays for the whole history. For the next round, consider a fresh subagent with a compact brief instead of recalling.]`;
+[Session growth warning: session ${session.id} now carries approximately ${transcriptChars} JSON characters of transcript (not billing tokens); full recall carries that history, report recall excludes it. Cost is unknown. For the next round, consider a fresh subagent with a compact brief instead of recalling.]`;
   }
   if (!deps.sessionStore) return;
   if (transcriptChars > SESSION_RECORD_MAX_CHARS) {
@@ -8908,6 +9114,13 @@ async function runSubagentWithProgress(deps, task, reportProgress, signal, sessi
   let heartbeat;
   let session;
   let runStarted = false;
+  let runUsage;
+  const shownPhases = /* @__PURE__ */ new Set();
+  const phaseProgress = (phase) => {
+    if (shownPhases.has(phase) || shownPhases.size >= 16) return;
+    shownPhases.add(phase);
+    report({ message: `[${task.name}] Phase: ${phase}` });
+  };
   let baseline = 0;
   let hardDeadlineAt;
   let pendingRun;
@@ -8916,7 +9129,9 @@ async function runSubagentWithProgress(deps, task, reportProgress, signal, sessi
     if (!runStarted || !session?.agent) return;
     const last = [...session.agent.state.messages.slice(baseline)].reverse().find((m) => m?.role === "assistant");
     const terminal = isReportTerminal(last) ? last : void 0;
-    task.report = parseDelegationReport(terminal ? collectLastAssistantText([terminal]) || void 0 : void 0, `${task.id}:${session.runCount + 1}`, ["length", "error", "aborted"].includes(terminal?.stopReason));
+    const hooks = agentRunHooks.get(session.agent);
+    const capturedText = terminal && hooks?.terminalStopReason === terminal.stopReason ? hooks?.terminalText : void 0;
+    task.report = parseDelegationReport(terminal ? collectLastAssistantText([terminal]) || capturedText || void 0 : void 0, `${task.id}:${session.runCount + 1}`, terminal?.stopReason ?? (timedOut ? "deadline" : signal?.aborted ? "cancelled" : "no_terminal"));
   };
   let agentSettled = true;
   let releaseLease;
@@ -8959,7 +9174,12 @@ async function runSubagentWithProgress(deps, task, reportProgress, signal, sessi
       }
       const nextModelOverride = task.modelOverride ?? session.modelOverride;
       const nextThinking = task.thinkingLevel ?? session.thinkingLevel;
-      if (task.resumeMode === "report" && session.reports?.at(-1)?.availability !== "available") throw new Error("Report recall unavailable: the latest run has no valid report.");
+      const latestReport = session.reports?.at(-1);
+      if (task.resumeMode === "report" && latestReport?.availability !== "available") throw new Error(`Report recall unavailable: session=${session.id}, run=${latestReport?.runId ?? session.runCount}, availability=${latestReport?.availability ?? "missing"}, reason=${latestReport?.reason ?? "legacy_or_missing"}. Explicitly choose resumeMode:"full" (full history; cost unknown), or spawn a new bounded task. No older report or transcript fallback was used.`);
+      const history = session.agent?.state.messages ?? session.pendingMessages ?? [];
+      const historyChars = task.resumeMode === "report" ? 0 : estimateTranscriptChars(history);
+      task.recallInput = { mode: task.resumeMode ?? "full", messageCount: task.resumeMode === "report" ? 0 : history.length, jsonChars: historyChars, warning: historyChars > SESSION_TRANSCRIPT_WARN_CHARS, cost: "unknown" };
+      report({ message: task.resumeMode === "report" ? `[${task.name}] Report recall: old transcript is not carried into the prompt; cost unknown.` : `[${task.name}] Full recall input: ${task.recallInput.messageCount} historical messages, approximately ${task.recallInput.jsonChars} JSON characters (not billing tokens); cost unknown.${task.recallInput.warning ? " Large history: context risk; consider report recall or a new bounded task." : ""}` });
       const mustRebuild = task.resumeMode === "report" || session.agent === null || task.requestedMode !== void 0 || task.modelOverride !== void 0 || task.thinkingLevel !== void 0;
       if (!mustRebuild) {
         subagent = session.agent;
@@ -9063,6 +9283,14 @@ async function runSubagentWithProgress(deps, task, reportProgress, signal, sessi
     if (sessions) retainLiveSession(sessions, session, Math.max(1, deps.maxLiveSessions ?? DEFAULT_MAX_LIVE_SESSIONS));
     if (signal?.aborted || sessions?.disposed) throw new Error("Subagent capability disposed or aborted by parent");
     const hooks = agentRunHooks.get(subagent);
+    runUsage = createSubagentUsage(session.id, `${task.id}:${session.runCount + 1}`);
+    (task.usageRuns ??= []).push(runUsage);
+    if (hooks) {
+      hooks.usage = runUsage;
+      hooks.onPhase = phaseProgress;
+      hooks.terminalText = void 0;
+      hooks.terminalStopReason = void 0;
+    }
     hardDeadlineAt = Date.now() + runTimeoutSeconds * 1e3;
     if (hooks) {
       hooks.observation = task.observation;
@@ -9086,6 +9314,7 @@ async function runSubagentWithProgress(deps, task, reportProgress, signal, sessi
       softTimeout = setTimeout(() => {
         if (hooks) hooks.finalizing = true;
         observeDelegationPhase(task.observation, "finalizing", false);
+        phaseProgress("finalizing");
       }, subagentSoftDeadlineMs(runTimeoutSeconds * 1e3));
       timeout = setTimeout(() => {
         timedOut = true;
@@ -9189,7 +9418,7 @@ ${DELEGATION_REPORT_INSTRUCTION}`;
     const terminalStopReason = lastAssistant?.stopReason;
     const terminalError = typeof lastAssistant?.errorMessage === "string" ? lastAssistant.errorMessage : void 0;
     const collectedResponse = isReportTerminal(lastAssistant) ? collectLastAssistantText([lastAssistant]) || void 0 : void 0;
-    task.report = parseDelegationReport(collectedResponse, `${task.id}:${(session?.runCount ?? 0) + 1}`, terminalStopReason === "length" || terminalStopReason === "error" || terminalStopReason === "aborted");
+    task.report = parseDelegationReport(collectedResponse, `${task.id}:${(session?.runCount ?? 0) + 1}`, terminalStopReason ?? "no_terminal");
     const streamInterrupted = terminalStopReason === "error" || terminalStopReason === "aborted" || terminalError || !collectedResponse && terminalStopReason !== "stop" || terminalStopReason === "length" && !messageHasOwnText(lastAssistant);
     if (streamInterrupted) {
       if (terminalStopReason === "length") {
@@ -9238,6 +9467,7 @@ ${DELEGATION_REPORT_INSTRUCTION}`;
     refreshReport();
     task.status = timedOut ? "timeout" : signal?.aborted ? "cancelled" : "failed";
     observeDelegationPhase(task.observation, timedOut ? "deadline" : signal?.aborted ? "cancelled" : "failed");
+    phaseProgress(task.observation.phase);
     task.error = errorMessage.slice(0, 2e3);
     task.report ??= parseDelegationReport(void 0, task.id);
     task.parentHandoffRequired = isParentHandoffRequired(task);
@@ -9247,14 +9477,21 @@ ${DELEGATION_REPORT_INSTRUCTION}`;
     if (heartbeat) {
       clearInterval(heartbeat);
     }
+    if (runUsage) settleSubagentUsage(runUsage, agentSettled);
     const finalize = async () => {
+      if (runUsage) settleSubagentUsage(runUsage, true);
       try {
         if (session) {
           const hooks = session.agent ? agentRunHooks.get(session.agent) : void 0;
-          if (hooks && hooks.observation === task.observation) hooks.observation = void 0;
+          if (hooks && hooks.observation === task.observation) {
+            hooks.observation = void 0;
+            hooks.onPhase = void 0;
+            hooks.usage = void 0;
+          }
           if (runStarted) {
             refreshReport();
             session.runCount++;
+            if (runUsage) session.usageRuns = [...session.usageRuns ?? [], runUsage].slice(-4);
             session.reports = [...session.reports ?? [], task.report ?? parseDelegationReport(void 0, task.id)].slice(-4);
           }
           session.lastUsedAt = Date.now();
@@ -9305,7 +9542,9 @@ function buildParallelResult(tasks, totalDuration) {
     if (task.details) {
       resultText += `, ${task.details.durationMs}ms, ${task.details.toolCalls} tools`;
     }
-    resultText += `, report=${task.report?.availability ?? "missing"})
+    resultText += `, report=${task.report?.availability ?? "missing"}${task.report?.reason ? ` (${task.report.reason})` : ""})
+`;
+    for (const usage of task.usageRuns ?? []) resultText += `Child usage ${usage.sessionId}/${usage.runId}: ${usage.status}, ${usage.attempts} attempts (${usage.reportedAttempts} reported, ${usage.unknownAttempts} unknown, ${usage.pendingAttempts} pending); reported token subtotal=${usage.reportedTokens.totalTokens}; estimated cost=${usage.estimatedCost ?? "unknown"}. Not added to parent ledger.
 `;
     if (task.observation) resultText += `Phase: ${task.observation.phase}; last activity: ${task.observation.lastActivity} at ${task.observation.lastWorkAt}
 `;
@@ -9501,7 +9740,7 @@ Default mode="read" is for investigation, search, review, or triage and cannot e
             thinkingLevel: Type.Optional(Type.Union([Type.Literal("off"), Type.Literal("minimal"), Type.Literal("low"), Type.Literal("medium"), Type.Literal("high"), Type.Literal("xhigh")], { description: "off|minimal|low|medium|high|xhigh. Default medium; override only when the user asks or for cheap lookups (off)." })),
             timeout: Type.Optional(Type.Number({ description: "Seconds. Default 1200; set higher for long tasks." })),
             resumeMode: Type.Optional(Type.Union([Type.Literal("full"), Type.Literal("report")], { description: "Default full retains prior transcript. Explicit report rebuilds with current tools/model/credentials and only the latest valid historical report as data plus the new task; fails if unavailable." })),
-            sessionId: Type.Optional(Type.String({ description: "Continue a previous subagent session by id (from an earlier result's Session line); accumulated context makes iteration cheaper. Optional mode/model/thinkingLevel reconfigure it; one task at a time; recalls never replay on failure and must target an idle session; prefer a fresh task for independent reviews." }))
+            sessionId: Type.Optional(Type.String({ description: "Continue a previous subagent session by id (from an earlier result's Session line); full mode retains historical input with unknown cost. Optional mode/model/thinkingLevel reconfigure it; one task at a time; recalls never replay on failure and must target an idle session; prefer a fresh task for independent reviews." }))
           }
           // No additionalProperties lock: legacy callers may send task aliases
           // (description/prompt/objective); normalizeTaskDefs resolves them at
@@ -9631,6 +9870,8 @@ ${SPAWN_USAGE_HINT}` }],
             reportedEvidenceCount: task.reportedEvidence.length,
             confidenceSignalCount: task.confidenceSignals.length,
             report: task.report,
+            recallInput: task.recallInput,
+            usageRuns: task.usageRuns?.map((usage) => ({ ...usage, reportedTokens: { ...usage.reportedTokens } })),
             observation: task.observation,
             parentHandoffRequired: task.parentHandoffRequired,
             failureReason: task.error,
@@ -10978,7 +11219,7 @@ function createReadTool(cwd, options) {
     label: "read",
     description: `Read a file's contents. Use this before editing, and use offset/limit for large files, or tail=N to read the last N lines when the line count is unknown. Images are attached for the current model when it supports vision; otherwise a configured file-understanding service analyzes them. Video, audio, and documents require a configured understanding service. Pass question to specify what to focus on; it does not force a separate model request. Example: read_file path='Scripts/PlayerController.cs' or read_file path='Data/config.json'. ${pathResolutionDescription} For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). When you need the full file, continue with a larger offset until complete.`,
     parameters: readSchema,
-    execute: async (_toolCallId, params, signal) => {
+    execute: async (_toolCallId, params, signal, _onUpdate) => {
       const { path: path3, root, question } = params;
       const tail = params.tail;
       let offset = params.offset;
@@ -11005,7 +11246,7 @@ function createReadTool(cwd, options) {
         const message = error instanceof Error ? error.message : String(error);
         if (/outside sandbox|outside root|escapes sandbox/i.test(message)) {
           return createReadErrorResult(
-            `${message}. read_file is workspace-scoped; for intentional runtime logs or temporary files outside the workspace, use bash with a bounded command such as head, tail, sed -n, or cat on that path.`
+            `${message}. read_file is workspace-scoped; for intentional runtime logs or temporary files outside the workspace, use the shell tool with a bounded command such as head, tail, sed -n, or cat on that path.`
           );
         }
         return createReadErrorResult(message);
@@ -16914,7 +17155,7 @@ function unavailableResult(query, requestedMode, reason) {
       text: [
         `Web search is unavailable for "${query}".`,
         reason,
-        "Do not use bash, curl, Python, or DuckDuckGo scraping as a fallback; report that web_search is unavailable or ask the user to configure a provider that supports native web search."
+        "Do not use shell, curl, Python, or DuckDuckGo scraping as a fallback; report that web_search is unavailable or ask the user to configure a provider that supports native web search."
       ].join("\n")
     }],
     details: {
@@ -17422,7 +17663,7 @@ function createSharedWebSearchTool(deps) {
   return {
     name: "web_search",
     label: "web_search",
-    description: "Search the public web using a provider-native web search capability. Use for current information, online research, or documentation outside the local workspace. Results include sources. Do not use bash/curl/python as a web-search fallback. Only set domain filters when the user explicitly asks to limit sources.",
+    description: "Search the public web using a provider-native web search capability. Use for current information, online research, or documentation outside the local workspace. Results include sources. Do not use shell/curl/python as a web-search fallback. Only set domain filters when the user explicitly asks to limit sources.",
     parameters: webSearchSchema,
     execute: async (_toolCallId, rawParams, signal) => {
       const input = rawParams;
@@ -18013,7 +18254,7 @@ function createSharedWebFetchTool(deps = {}) {
   return {
     name: "web_fetch",
     label: "web_fetch",
-    description: "Fetch and read a specific public web URL. Use web_search to discover sources, then web_fetch to inspect a chosen URL. Do not use bash/curl/Python as a fallback for web page fetching.",
+    description: "Fetch and read a specific public web URL. Use web_search to discover sources, then web_fetch to inspect a chosen URL. Do not use shell/curl/Python as a fallback for web page fetching.",
     parameters: webFetchSchema,
     capabilityMetadata: {
       riskClass: "network",
@@ -18637,7 +18878,7 @@ function createSharedWebResearchTool(deps) {
   return {
     name: "web_research",
     label: "web_research",
-    description: "Canonical web tool. For normal research, pass query. To read a known page, pass url. For low-level search results only, pass query with mode='search'. Use for current information, official docs, news, releases, issues, and webpage summaries. Do not use bash/curl/Python as a web fallback.",
+    description: "Canonical web tool. For normal research, pass query. To read a known page, pass url. For low-level search results only, pass query with mode='search'. Use for current information, official docs, news, releases, issues, and webpage summaries. Do not use shell/curl/Python as a web fallback.",
     parameters: webResearchSchema,
     capabilityMetadata: {
       riskClass: "network",
@@ -19208,6 +19449,8 @@ export {
   findFirstKeptEntrySummaryId,
   createCompactionSummary,
   generateEntryId,
+  createHostEnvelopeProjectorRegistry,
+  projectHostEnvelopes,
   FileSessionStore,
   createSessionManager,
   prepareSessionCompaction,
@@ -19248,6 +19491,7 @@ export {
   supersedeExecutionState,
   shouldPreserveExecutionStateForUserText,
   BUILTIN_TOOL_CAPABILITY_METADATA,
+  getToolCapabilityMetadata,
   isToolAllowedInPlanMode,
   extractPlanTodoItems,
   isPlanModeSafeCommand,