pi-ultracode 0.3.2 → 0.5.0

package/src/mode.ts

@@ -1,16 +1,21 @@
 /**
  * Ultracode mode controller.
  *
- * Ultracode is a session-scoped effort mode. While on, it:
- *   - raises the thinking level to the model's maximum (remembering the previous level),
+ * Ultracode is a session-scoped semantic analysis-depth mode. While active, it:
+ *   - applies the configured mode's default thinking level while preserving the
+ *     user's previous level,
  *   - keeps the `workflow` tool active,
- *   - injects a standing "author and run a workflow by default" system block on
- *     every turn,
- *   - persists its on/off state in session custom entries so it survives
- *     reload, resume, fork, and compaction.
+ *   - injects the configured auto/focused/standard/deep policy on every turn,
+ *   - persists branch-local mode state across reload, resume, fork, and compaction.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  isActiveUltracodeMode,
+  thinkingLevelForMode,
+  type ActiveUltracodeMode,
+  type UltracodeModeName,
+} from "./depth.ts";
 import { ULTRACODE_ACTIVE_REMINDER, ULTRACODE_TAGLINE, ultracodeSystemBlock } from "./prompts.ts";
 import {
   LEGACY_ULTRACODE_THINKING_LEVEL,
@@ -24,7 +29,7 @@ export type { ThinkingLevel } from "./thinking.ts";
 export const MODE_ENTRY_TYPE = "ultracode-mode";
 
 interface PersistedModeState {
-  enabled: boolean;
+  mode: UltracodeModeName;
   previousThinking?: ThinkingLevel;
   /** `null` records that the setting was originally absent (Pi defaults to medium). */
   previousDefaultThinking?: ThinkingLevel | null;
@@ -47,13 +52,13 @@ export interface ThinkingPreferenceStore {
 }
 
 export class UltracodeMode {
-  private enabled = false;
+  private mode: UltracodeModeName = "off";
   private suspended = false;
   private previousThinking: ThinkingLevel | undefined;
   private previousDefaultThinking: ThinkingLevel | null | undefined;
   /** Restore a level later if the current non-reasoning model clamps it to off. */
   private pendingPreviousThinking: ThinkingLevel | undefined;
-  /** The level Pi actually applied after clamping the maximum request. */
+  /** The level Pi actually applied after clamping the configured request. */
   private appliedThinking: ThinkingLevel | undefined;
   /** Prevent mode-owned thinking changes from being mistaken for manual overrides. */
   private applyingThinking = false;
@@ -95,36 +100,45 @@ export class UltracodeMode {
     }
   }
 
-  /** Enable if off, disable if on. Returns the new enabled state. */
+  /** Enable auto if off, otherwise disable. Returns the new enabled state. */
   toggle(pi: ExtensionAPI): boolean {
-    if (this.enabled) {
+    if (this.isEnabled()) {
       this.disable(pi);
       return false;
     }
-    this.enable(pi);
+    this.enable(pi, "auto");
     return true;
   }
 
-  /** The thinking level Pi actually applied (`max`, or the model/runtime fallback). */
+  getMode(): UltracodeModeName {
+    return this.mode;
+  }
+
+  /** The thinking level Pi actually applied after model/runtime clamping. */
   getAppliedThinking(): ThinkingLevel | undefined {
     return this.appliedThinking;
   }
 
   /**
-   * Return the raw maximum request, not the parent's applied value, so every
-   * workflow subagent is clamped independently against its own model.
+   * Return the configured raw effort request so every workflow subagent is
+   * clamped independently against its own model.
    */
   getSubagentThinkingLevel(): ThinkingLevel | undefined {
-    return this.isEnforcing() ? ULTRACODE_THINKING_LEVEL : undefined;
+    return this.isEnforcing() ? thinkingLevelForMode(this.mode) : undefined;
   }
 
-  /** Reassert the maximum before a turn or after a model change. */
-  reapplyMaximumThinking(pi: ExtensionAPI): boolean {
+  /** Reassert the configured mode effort before a turn or after a model change. */
+  reapplyConfiguredThinking(pi: ExtensionAPI): boolean {
     if (!this.isEnforcing()) return false;
-    this.applyUltracodeThinking(pi);
+    this.applyConfiguredThinking(pi);
     return true;
   }
 
+  /** @deprecated Use reapplyConfiguredThinking(). */
+  reapplyMaximumThinking(pi: ExtensionAPI): boolean {
+    return this.reapplyConfiguredThinking(pi);
+  }
+
   /**
    * Handle model switches both while active and after a clamped restoration.
    * Returns true when Ultracode remains active and the UI should be refreshed.
@@ -132,8 +146,8 @@ export class UltracodeMode {
   handleModelSelect(pi: ExtensionAPI): boolean {
     if (this.suspended) return false;
     this.pendingClearGeneration++;
-    if (this.enabled) {
-      this.applyUltracodeThinking(pi);
+    if (this.isEnabled()) {
+      this.applyConfiguredThinking(pi);
       return true;
     }
     if (this.pendingPreviousThinking) {
@@ -147,7 +161,7 @@ export class UltracodeMode {
 
   /** Restore the pre-mode effective effort without changing persisted mode state. */
   restorePreviousThinking(pi: ExtensionAPI): void {
-    if (this.enabled && this.previousThinking) this.applyCompatibleThinking(pi, this.previousThinking);
+    if (this.isEnabled() && this.previousThinking) this.applyCompatibleThinking(pi, this.previousThinking);
   }
 
   /** Stop enforcing synchronously, then restore effort before session teardown. */
@@ -162,34 +176,32 @@ export class UltracodeMode {
   }
 
   /**
-   * Enforce the mode after an external thinking-level selection. Stale events
-   * and events emitted by this mode are ignored to avoid recursive updates.
-   * Returns true when a manual selection was overridden.
+   * Enforce the configured effort after an external thinking-level selection.
+   * Stale events and events emitted by this mode are ignored to avoid recursion.
    */
   handleThinkingLevelSelect(pi: ExtensionAPI, level: ThinkingLevel): boolean {
     if (this.suspended || this.applyingThinking) return false;
     const current = safeGetThinking(pi);
     if (!current || current !== level) return false;
-    if (!this.enabled) {
+    if (!this.isEnabled()) {
       // Pi emits the same event for a user selection and an automatic model
       // re-clamp. Defer clearing until model_select has had a chance to consume it.
       if (this.pendingPreviousThinking) this.deferPendingClear(pi, level);
       return false;
     }
     if (current === this.appliedThinking) return false;
-    this.applyUltracodeThinking(pi);
+    this.applyConfiguredThinking(pi);
     return true;
   }
 
   isEnabled(): boolean {
-    return this.enabled;
+    return this.mode !== "off";
   }
 
   isSuspended(): boolean {
     return this.suspended;
   }
 
-
   /** Keep tool availability aligned with the current mode state. */
   syncWorkflowTool(pi: ExtensionAPI): void {
     if (this.isEnforcing()) this.activateWorkflowTool(pi);
@@ -200,12 +212,16 @@ export class UltracodeMode {
     return ULTRACODE_TAGLINE;
   }
 
-  /** Turn ultracode on. Idempotent. */
-  enable(pi: ExtensionAPI): void {
+  /**
+   * Enable or switch modes without replacing the saved baseline. The no-argument
+   * form retains the pre-0.5 programmatic deep behavior; user commands pass an
+   * explicit mode and bare `/ultracode` uses toggle() to enter auto.
+   */
+  enable(pi: ExtensionAPI, mode: ActiveUltracodeMode = "deep"): void {
     this.suspended = false;
     this.pendingPreviousThinking = undefined;
     this.pendingClearGeneration++;
-    if (!this.enabled) {
+    if (!this.isEnabled()) {
       const current = safeGetThinking(pi);
       const preference = this.captureThinkingPreference();
       const effectivePreference = this.runtimeCompatibleThinking(preference.effective) as
@@ -222,16 +238,16 @@ export class UltracodeMode {
         : current;
       this.previousDefaultThinking = this.runtimeCompatibleThinking(preference.global);
       this.legacyDefaultMigrationPending = false;
-      this.enabled = true;
     }
-    this.applyUltracodeThinking(pi);
+    this.mode = mode;
+    this.applyConfiguredThinking(pi);
     this.syncWorkflowTool(pi);
     this.persist(pi);
   }
 
-  /** Turn ultracode off, restoring the previous thinking level. */
+  /** Turn Ultracode off, restoring the pre-mode thinking level. */
   disable(pi: ExtensionAPI): void {
-    if (!this.enabled) {
+    if (!this.isEnabled()) {
       this.syncWorkflowTool(pi);
       return;
     }
@@ -241,7 +257,7 @@ export class UltracodeMode {
       ? previous
       : undefined;
     this.pendingClearGeneration++;
-    this.enabled = false;
+    this.mode = "off";
     this.suspended = false;
     this.syncWorkflowTool(pi);
     this.persist(pi);
@@ -286,7 +302,7 @@ export class UltracodeMode {
           ?? (wasEnforcing ? this.previousThinking : undefined)
           ?? effectivePreference,
       ) as ThinkingLevel | undefined;
-      this.enabled = false;
+      this.mode = "off";
       this.suspended = false;
       this.pendingPreviousThinking = undefined;
       this.previousThinking = target;
@@ -306,7 +322,7 @@ export class UltracodeMode {
     }
 
     this.suspended = false;
-    this.enabled = latest.enabled;
+    this.mode = latest.mode;
     this.syncWorkflowTool(pi);
     const maxIsUnknownToRuntime = !this.runtimeSupportsMaxThinking
       && preference.effective === ULTRACODE_THINKING_LEVEL;
@@ -319,7 +335,7 @@ export class UltracodeMode {
     // Pre-preference-store releases persisted only previousThinking while their
     // active xhigh request polluted Pi's global default. Recover that baseline
     // once instead of treating the known Ultracode value as a user preference.
-    const migratesLegacyDefault = latest.enabled
+    const migratesLegacyDefault = latest.mode !== "off"
       && latest.previousDefaultThinking === undefined
       && latest.previousThinking !== undefined
       && (preference.global === LEGACY_ULTRACODE_THINKING_LEVEL
@@ -331,9 +347,9 @@ export class UltracodeMode {
         : this.runtimeCompatibleThinking(latest.previousDefaultThinking);
     this.legacyDefaultMigrationPending = migratesLegacyDefault;
 
-    this.pendingPreviousThinking = this.enabled ? undefined : latest.pendingPreviousThinking;
-    if (this.enabled) {
-      this.applyUltracodeThinking(pi);
+    this.pendingPreviousThinking = this.isEnabled() ? undefined : latest.pendingPreviousThinking;
+    if (this.isEnabled()) {
+      this.applyConfiguredThinking(pi);
       if (migratesLegacyDefault) {
         this.queueDefaultThinkingRestore(() => {
           this.legacyDefaultMigrationPending = false;
@@ -374,30 +390,29 @@ export class UltracodeMode {
     }
   }
 
-  /**
-   * Build the before_agent_start result: appends the ultracode system block to the
-   * turn's system prompt when enabled.
-   */
+  /** Append the configured semantic-depth policy to the turn's system prompt. */
   beforeAgentStart(event: { systemPrompt: string }): { systemPrompt: string } | undefined {
-    if (!this.isEnforcing()) return undefined;
-    const block = ultracodeSystemBlock();
+    if (!this.isEnforcing() || !isActiveUltracodeMode(this.mode)) return undefined;
+    const block = ultracodeSystemBlock(this.mode);
     return { systemPrompt: `${event.systemPrompt}\n\n${block}\n\n${ULTRACODE_ACTIVE_REMINDER}` };
   }
 
   statusLine(): string {
-    if (!this.enabled) return `ultracode: off`;
-    const parts = ["ultracode: on"];
+    if (!this.isEnabled()) return "ultracode: off";
+    const parts = [`ultracode: ${this.mode}`];
     // Show the level that actually applied, including compatibility/model fallback.
     if (this.appliedThinking) parts.push(this.appliedThinking);
     return parts.join(" · ");
   }
 
-  private applyUltracodeThinking(pi: ExtensionAPI): void {
+  private applyConfiguredThinking(pi: ExtensionAPI): void {
+    const target = thinkingLevelForMode(this.mode);
+    if (!target) return;
     const writeGeneration = this.preferenceWriteGeneration;
-    this.applyCompatibleThinking(pi, ULTRACODE_THINKING_LEVEL);
+    this.applyCompatibleThinking(pi, target);
     // Pi normally skips persistence when the effective level is unchanged, but
     // the extension API does not promise that. Defensively restore the raw
-    // baseline even after a stable max -> max request.
+    // baseline even after a stable mode-owned request.
     if (writeGeneration === this.preferenceWriteGeneration) {
       this.queueDefaultThinkingRestore();
     }
@@ -433,7 +448,7 @@ export class UltracodeMode {
   }
 
   isEnforcing(): boolean {
-    return this.enabled && !this.suspended;
+    return this.isEnabled() && !this.suspended;
   }
 
   private pendingRestoreSucceeded(pending: ThinkingLevel): boolean {
@@ -495,7 +510,7 @@ export class UltracodeMode {
     setImmediate(() => {
       if (
         generation !== this.pendingClearGeneration
-        || this.enabled
+        || this.isEnabled()
         || this.suspended
         || safeGetThinking(pi) !== level
       ) return;
@@ -528,7 +543,7 @@ export class UltracodeMode {
 
   private persist(pi: ExtensionAPI): void {
     const state: PersistedModeState = {
-      enabled: this.enabled,
+      mode: this.mode,
       previousThinking: this.previousThinking,
       previousDefaultThinking: this.legacyDefaultMigrationPending
         ? undefined
@@ -547,8 +562,17 @@ function parsePersistedModeState(data: unknown): PersistedModeState | undefined
   if (!data || typeof data !== "object") return undefined;
   const value = data as Record<string, unknown>;
   const previousDefault = value.previousDefaultThinking;
+  // Sessions written before semantic-depth modes stored only enabled:boolean.
+  // Preserve their behavior by migrating enabled:true to the old deep mode.
+  const mode: UltracodeModeName = isActiveUltracodeMode(value.mode)
+    ? value.mode
+    : value.mode === "off"
+      ? "off"
+      : value.enabled === true
+        ? "deep"
+        : "off";
   return {
-    enabled: value.enabled === true,
+    mode,
     previousThinking: isThinkingLevel(value.previousThinking) ? value.previousThinking : undefined,
     previousDefaultThinking: previousDefault === null || isThinkingLevel(previousDefault)
       ? previousDefault

package/src/prompts.ts

@@ -1,59 +1,92 @@
-/**
- * Prompt text for ultracode mode.
- *
- * These strings reproduce the behavioural contract of Claude Code's "ultracode"
- * effort level: a standing opt-in to deterministic multi-agent workflow
- * orchestration, biased toward the most exhaustive, correct answer.
- */
+/** Prompt text for Ultracode's adaptive analysis-depth modes. */
+
+import type { ActiveUltracodeMode } from "./depth.ts";
 
 /** One-line description shown by `/ultracode status` and the footer. */
-export const ULTRACODE_TAGLINE = "max thinking + dynamic workflow orchestration";
+export const ULTRACODE_TAGLINE = "semantic-depth workflow orchestration";
 
 /**
- * The standing system-prompt block injected on every turn while ultracode is on.
- * Mirrors the "Ultracode" section of the Workflow tool contract.
+ * The standing system-prompt block injected on every turn while Ultracode is
+ * active. The parent model performs the semantic routing itself; starting a
+ * separate agent merely to classify depth would defeat the focused path.
  */
-export function ultracodeSystemBlock(): string {
+export function ultracodeSystemBlock(mode: ActiveUltracodeMode = "deep"): string {
   return [
     "<ultracode>",
-    "Ultracode is ON. This opt-in is standing: author and run a workflow for every substantive task by default.",
+    `Configured mode: ${mode}.`,
+    "Analysis depth is a semantic quality decision, never a wall-clock decision. Do not use elapsed time, deadlines, or duration limits to choose, lower, or stop analysis depth.",
+    "Use the smallest depth that can establish a correct answer. Depth is controlled by research rounds, independent perspectives, verification strength, evidence requirements, skeptic count, and per-agent reasoning effort.",
+    "Existing maxAgents/reserveAgents limits are structural admission bounds, not evidence that every available slot should be used.",
     "",
-    "The goal is a bounded, exhaustive-enough, correct answer: choose explicit fan-out and round limits before launching work.",
-    "For multi-phase work (understand → design → implement → review), prefer one bounded workflow and inspect the result before deciding whether another workflow is justified. Do not run consecutive workflows by default; continue only when new evidence changes the plan.",
+    ...modeInstructions(mode),
     "",
-    "Lean toward orchestrating with the workflow tool and adversarially verifying your findings, unless the work is trivial or already verified. Solo (no workflow) only on conversational turns or trivial mechanical edits.",
+    "Evidence-driven escalation and stopping:",
+    "- Escalate only for material correctness risk, missing direct evidence, conflicting findings, or an unresolved question that can change the answer.",
+    "- Treat security, GC, ABI, deoptimization, concurrency, data-loss, irreversible operations, and critical architecture semantics as high-risk unless bounded evidence proves otherwise.",
+    "- Stop when key claims have direct evidence, no material conflict or unresolved high-risk question remains, and another round would only repeat known evidence.",
+    "- Model-reported confidence alone is not sufficient. Prefer concrete citations, reproduction, tests, and independent agreement.",
+    "- If fixed focused/standard is insufficient, report the remaining uncertainty and recommend a deeper mode; in deep, report any irreducible uncertainty. Never silently exceed a fixed mode.",
     "",
-    "Quality patterns to compose as the task calls for it:",
-    "- Adversarial verify: spawn N independent skeptics per finding, each prompted to REFUTE it; kill the finding if a majority refute. Stops plausible-but-wrong findings from surviving.",
-    "- Perspective-diverse verify: when a finding can fail in more than one way, give each verifier a distinct lens (correctness, security, performance, does-it-reproduce) instead of N identical refuters.",
-    "- Multi-modal sweep: parallel agents each searching a different way (by-container, by-content, by-entity, by-time); each is blind to what the others surface.",
-    "- Loop-until-dry: for unknown-size discovery (bugs, edge cases), run at most 2 rounds by default (3 only when the user explicitly asks for comprehensive coverage); stop sooner when no fresh evidence appears.",
-    "- Completeness critic: a final agent that asks \"what's missing — a modality not run, a claim unverified, a source unread?\" What it finds becomes the next round of work.",
-    "- No silent caps: if a workflow bounds coverage (top-N, no-retry, sampling), log() what was dropped.",
-    "",
-    "Scale to the task: \"find any bugs\" → a few finders, single-vote verify; \"thoroughly audit\" / \"be comprehensive\" → a larger but explicit finder pool, 3–5 vote adversarial pass, and a synthesis stage within maxAgents.",
+    "Workflow policy:",
+    "- Use a workflow only when independent decomposition, verification, isolation, or context scale provides real value. Otherwise solve directly in the parent session.",
+    "- Make skeptics conditional: verify high-risk, conflicting, weakly evidenced, or low-confidence claims instead of automatically verifying every branch.",
+    "- Avoid a separate synthesis agent when deterministic merging or parent synthesis is enough. Use an adjudicator only when a material conflict remains.",
+    "- Match effort to the stage with per-call model suffixes when useful: focused discovery/synthesis may use :medium, standard analysis :high, and :max is reserved for deep or decisive high-risk verification.",
+    "- When a workflow runs, log `analysis-depth: <level> — <reason>` before launching agents, `analysis-escalation: ...` for each semantic escalation, and `analysis-stop: ...` for the final evidence-based stop reason. Never use time as an escalation or stop reason.",
     "</ultracode>",
   ].join("\n");
 }
 
-/** Short reminder appended to confirm the mode is active (system-reminder style). */
+function modeInstructions(mode: ActiveUltracodeMode): string[] {
+  switch (mode) {
+    case "auto":
+      return [
+        "Before acting, silently route this task to focused, standard, or deep. Do not spawn a router agent.",
+        "Choose from user intent, consequence risk, scope, ambiguity, available evidence, cross-module or cross-repository breadth, and whether independent verification is necessary.",
+        "Begin at the shallowest sufficient depth and escalate only when evidence triggers an escalation condition below.",
+      ];
+    case "focused":
+      return [
+        "Focused is a fixed lightweight depth: prefer one bounded line of inquiry and the normal parent-agent loop.",
+        "Do not run adversarial verification by default. Use at most a small, narrowly scoped delegation only when it clearly reduces duplicated exploration.",
+      ];
+    case "standard":
+      return [
+        "Standard is a fixed balanced depth: cover the few independent dimensions that can materially change the answer.",
+        "Prefer one discovery round and conditional verification of only disputed, high-risk, or weakly evidenced claims.",
+      ];
+    case "deep":
+      return [
+        "Deep is a fixed high-assurance depth: default to a bounded workflow for substantive tasks unless the work is conversational, trivial, or already verified.",
+        "Use multi-perspective investigation and adversarial verification where the task supports it. Choose fan-out and round limits before launch.",
+        "Use at most two discovery rounds by default; add a third only when the user explicitly requests exhaustive coverage and fresh evidence is still appearing.",
+      ];
+  }
+}
+
+/** Short reminder appended after the standing block. */
 export const ULTRACODE_ACTIVE_REMINDER =
-  "Reminder: ultracode is on — default to authoring and running a workflow for substantive tasks, and adversarially verify your findings.";
+  "Reminder: Ultracode is active — obey its configured semantic depth, escalate only from evidence, and never use elapsed time as an analysis budget.";
 
 /** Tool description for the `workflow` tool. */
 export const WORKFLOW_TOOL_DESCRIPTION = [
-  "Execute a deterministic JavaScript workflow that orchestrates multiple subagents to be comprehensive (decompose and cover in parallel), confident (independent perspectives and adversarial checks before committing), or to take on scale one context can't hold (migrations, audits, broad sweeps).",
+  "Execute a deterministic JavaScript workflow that orchestrates a proportionate set of subagents for independent coverage, targeted verification, or work that exceeds one context.",
+  "Choose the smallest workflow justified by the configured Ultracode depth and current evidence; workflow use and adversarial checks are not automatic.",
   "Each invocation must provide workflow source via `script`, `scriptPath`, or `name`. Inline `script` must be raw JavaScript (no Markdown fences) beginning with `export const meta = { name, description }` (a pure literal) and should call agent() at least once for useful orchestration.",
-  "Available globals: agent(prompt, opts), parallel(thunks, options?), pipeline(items, ...stages), phase(title), log(message), workflow(nameOrRef, args), args, cwd. The tool accepts maxAgents (default 128, max 1024) as a lifetime live-agent admission cap across resumes, not a token budget; cache replay is free.",
+  "Available globals: agent(prompt, opts), parallel(thunks, options?), pipeline(items, ...stages), phase(title), log(message), workflow(name, args), args, cwd. The tool accepts maxAgents (default 128, max 1024) as a lifetime live-agent admission cap across resumes, not a token or depth budget; cache replay is free.",
 ].join(" ");
 
 /** One-line snippet for the Available tools section. */
 export const WORKFLOW_PROMPT_SNIPPET =
-  "Run a deterministic JS workflow that fans out subagents. Header: export const meta = { name: 'snake_case', description: '...' }. Globals: agent/parallel/pipeline/phase/log/workflow/args/cwd.";
+  "Run a deterministic JS workflow with proportionate subagent fan-out. Header: export const meta = { name: 'snake_case', description: '...' }. Globals: agent/parallel/pipeline/phase/log/workflow/args/cwd.";
 
 /** Guideline bullets appended to the Guidelines section when the tool is active. */
 export const WORKFLOW_GUIDELINES: string[] = [
-  "While Ultracode is enabled, use the workflow tool to decompose-and-cover in parallel, gather independent perspectives that adversarially verify each other, or take on scale one context can't hold.",
+  "Use the workflow tool only when independent decomposition, targeted verification, isolation, or context scale adds value; use the parent agent directly for a bounded task.",
+  "For an auto-depth workflow, log `analysis-depth: <level> — <reason>` before launching agents, `analysis-escalation: ...` when evidence requires more depth, and `analysis-stop: ...` when evidence is sufficient. Elapsed time must never determine depth.",
+  "For workflow verification, run skeptics only for high-risk, conflicting, low-confidence, or weakly evidenced claims. Do not automatically attach a skeptic to every branch.",
+  "For workflow synthesis, prefer structured results plus deterministic or parent-session merging. Start a synthesis/adjudication agent only for a material unresolved conflict, and normally give pure synthesis lower effort and no broad source-search mandate.",
+  "For workflow agent effort, use a model suffix such as `:medium`, `:high`, or `:max` when the stage should differ from the mode default; reserve max for deep investigation or decisive high-risk verification.",
   "For the workflow tool, provide workflow source with `script`, `scriptPath`, or `name`. Inline `script` must be one raw JavaScript string: no Markdown fences, no prose around the script.",
   "For the workflow tool, the script's first statement must be `export const meta = { name: 'short_snake_case', description: 'non-empty human description' }`. meta must be a pure literal: no variables, function calls, spreads, or template interpolation. meta.phases is optional and should mirror your phase() titles.",
   "For the workflow tool, write plain JavaScript after the meta export. No TypeScript syntax, imports, require(), fs, network, Date/Intl/Temporal, Math.random(), binary memory constructors, WebAssembly, or dynamic method calls such as value[key](...) (they bypass deterministic checks or resource bounds). Stamp timestamps after the workflow returns; vary randomness by agent index.",
@@ -64,9 +97,9 @@ export const WORKFLOW_GUIDELINES: string[] = [
   "For the workflow tool, if agent() needs machine-readable output pass an inline JSON Schema via opts.schema; agent() then returns the validated object. Use only the bounded subset: types, object/array structure, enum/const, anyOf/allOf, length/numeric constraints, and annotations. Unknown keywords, $ref variants, oneOf, format, pattern, and patternProperties are rejected. Keep schemas under 256 KiB / 64 levels and every agent/workflow output under 2 MiB. Use JSON Schema, not TypeScript or TypeBox constructors.",
   "For the workflow tool, when agent() is called WITHOUT a schema, its return value is the subagent's final assistant text (the last text the subagent produced). With a schema it returns the validated structured_output object. Prefer a schema for machine-readable results; use the text form only for prose summaries.",
   "For the workflow tool, agent opts also accept: model (override the subagent model by pattern), agentType (use a custom subagent role/system-prompt), isolation:'worktree' (run the agent in an isolated git worktree — use ONLY when agents mutate files in parallel and would conflict), and phase (assign the agent to a progress group explicitly inside parallel()/pipeline()).",
-  "For the workflow tool, workflow(nameOrRef, args) runs a saved workflow (by name) or a scriptPath inline as a sub-step, sharing this run's concurrency, maxAgents, active reservations, and agent counter. Nesting is one level only. Child subagent sessions do not load ambient extensions or expose workflow/subagent orchestration tools, so they cannot start an independent recursive workflow chain.",
+  "For the workflow tool, workflow(name, args) runs a trust-aware saved workflow by name as a sub-step, sharing this run's concurrency, maxAgents, active reservations, and agent counter. Explicit nested script paths are not supported. Nesting is one level only. Child subagent sessions do not load ambient extensions or expose workflow/subagent orchestration tools, so they cannot start an independent recursive workflow chain.",
   "For workflow resumeFromRunId, reuse the exact same script and args. Resume is immutable, successful calls replay by stable structural call path, and maxAgents may only stay the same or increase; changed work must start a new run.",
-  "For the workflow tool, failed agent()/parallel()/pipeline() branches return null and log the failure (unless the whole run is aborted or a policy limit is hit). Check for nulls before synthesizing conclusions, and prefer a final synthesis/assertion agent that returns a compact JSON-serializable verdict.",
+  "For the workflow tool, failed agent()/parallel()/pipeline() branches return null and log the failure (unless the whole run is aborted or a policy limit is hit). Check for nulls before synthesizing conclusions, and prefer a final compact JSON-serializable result.",
   "For the workflow tool, directly await or return every orchestration promise (agent/parallel/pipeline/workflow). Native .then/.catch/.finally chains and Promise.all/allSettled/race/any are rejected; use parallel() or pipeline() so call identity stays deterministic. Unobserved, pending, or native same-scope concurrent orchestration is fatal.",
   "Workflow helpers that call orchestration must be directly declared functions/function variables or static methods on a declared object/stored class instance. Do not alias them, assign them later, forward through this.otherMethod(), or call them from temporary/awaited factory receivers; rewrite those forms as a direct declared helper so resume identity remains stable.",
   "For the workflow tool, do not assume subagents share the parent's repository context; include enough task context and relevant file paths in each agent prompt.",

package/src/thinking.ts

@@ -4,7 +4,7 @@ export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhig
 
 export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
 
-/** Ultracode always asks Pi for the strongest effort the selected model supports. */
+/** Deep mode asks Pi for the strongest effort the selected model supports. */
 export const ULTRACODE_THINKING_LEVEL: ThinkingLevel = "max";
 
 /** Compatibility retry for Pi versions released before the `max` level existed. */

package/src/workflow/agent-runner.ts

@@ -52,6 +52,7 @@ const PARENT_ONLY_CHILD_SKILLS = new Set(["pi-subagents"]);
 export interface WorkflowChildResourceLoaderOptions {
   cwd: string;
   agentDir: string;
+  projectTrusted?: boolean;
   settingsManager?: SettingsManager;
 }
 
@@ -67,7 +68,9 @@ export async function createWorkflowChildResourceLoader(
   options: WorkflowChildResourceLoaderOptions,
 ): Promise<DefaultResourceLoader> {
   const settingsManager = options.settingsManager
-    ?? SettingsManager.create(options.cwd, options.agentDir);
+    ?? SettingsManager.create(options.cwd, options.agentDir, {
+      projectTrusted: options.projectTrusted ?? false,
+    });
   const loader = new DefaultResourceLoader({
     cwd: options.cwd,
     agentDir: options.agentDir,
@@ -221,6 +224,8 @@ export type AgentSessionFactory = (
 
 export interface WorkflowAgentRunnerOptions {
   cwd: string;
+  /** Parent session's immutable project-trust decision. */
+  projectTrusted?: boolean;
   /** Synchronous extension facade used only for model selection and state replay. */
   modelRegistry?: ModelRegistryLike;
   /** Canonical runtime to share across child sessions when supplied by an SDK host. */
@@ -278,6 +283,7 @@ export interface AgentRunCall {
 
 export class WorkflowAgentRunner {
   private readonly baseCwd: string;
+  private readonly projectTrusted: boolean;
   private readonly modelRegistry?: ModelRegistryLike;
   private readonly providedModelRuntime?: ModelRuntimeLike;
   private readonly defaultModel?: ModelLike;
@@ -290,6 +296,7 @@ export class WorkflowAgentRunner {
 
   constructor(options: WorkflowAgentRunnerOptions) {
     this.baseCwd = options.cwd;
+    this.projectTrusted = options.projectTrusted ?? false;
     this.modelRegistry = options.modelRegistry;
     this.providedModelRuntime = options.modelRuntime;
     this.defaultModel = options.model;
@@ -304,10 +311,11 @@ export class WorkflowAgentRunner {
   async run(call: AgentRunCall): Promise<AgentRunResult> {
     if (call.signal?.aborted) throw new Error("Subagent was aborted");
 
-    const cwd = call.cwd ?? this.baseCwd;
+    const executionCwd = call.cwd ?? this.baseCwd;
+    const resourceCwd = this.baseCwd;
     const capture: StructuredOutputCapture<any> = { called: false, value: undefined };
 
-    const customTools: ToolDefinition[] = [...createCodingTools(cwd)];
+    const customTools: ToolDefinition[] = [...createCodingTools(executionCwd)];
     let toolAllowlist: string[] | undefined = call.agentTypeDef?.tools
       ? [...call.agentTypeDef.tools]
       : undefined;
@@ -346,14 +354,21 @@ export class WorkflowAgentRunner {
     }
 
     const createSession = async (level: ThinkingLevel | undefined) => {
-      const settingsManager = SettingsManager.create(cwd, agentDir);
+      const settingsManager = SettingsManager.create(resourceCwd, agentDir, {
+        projectTrusted: this.projectTrusted,
+      });
       const resourceLoader = this.usesPiSessionFactory
-        ? await createWorkflowChildResourceLoader({ cwd, agentDir, settingsManager })
+        ? await createWorkflowChildResourceLoader({
+            cwd: resourceCwd,
+            agentDir,
+            projectTrusted: this.projectTrusted,
+            settingsManager,
+          })
         : undefined;
       return this.createSession({
-        cwd,
+        cwd: executionCwd,
         agentDir,
-        sessionManager: SessionManager.inMemory(cwd),
+        sessionManager: SessionManager.inMemory(executionCwd),
         settingsManager,
         ...(resourceLoader ? { resourceLoader } : {}),
         customTools,
@@ -484,7 +499,7 @@ export class WorkflowAgentRunner {
         usage: readUsage(session, telemetryCounters),
         modelId: actualModelId,
         effort: actualEffort,
-        cwd,
+        cwd: executionCwd,
       };
     } catch (error) {
       hasPrimaryError = true;