@runtypelabs/sdk 4.10.0 → 4.12.0

package/dist/index.cjs

@@ -38,6 +38,8 @@ __export(index_exports, {
   ClientTokensEndpoint: () => ClientTokensEndpoint,
   ContextTemplatesEndpoint: () => ContextTemplatesEndpoint,
   ConversationsEndpoint: () => ConversationsEndpoint,
+  DEFAULT_RECOVERY_AFTER_EMPTY_SESSIONS: () => DEFAULT_RECOVERY_AFTER_EMPTY_SESSIONS,
+  DEFAULT_STALL_STOP_AFTER: () => DEFAULT_STALL_STOP_AFTER,
   DispatchEndpoint: () => DispatchEndpoint,
   EvalBuilder: () => EvalBuilder,
   EvalEndpoint: () => EvalEndpoint,
@@ -71,38 +73,59 @@ __export(index_exports, {
   SkillProposalsNamespace: () => SkillProposalsNamespace,
   SkillsNamespace: () => SkillsNamespace,
   SurfacesEndpoint: () => SurfacesEndpoint,
+  ToolDriftError: () => ToolDriftError,
+  ToolEnsureConflictError: () => ToolEnsureConflictError,
   ToolsEndpoint: () => ToolsEndpoint,
+  ToolsNamespace: () => ToolsNamespace,
   UsersEndpoint: () => UsersEndpoint,
   applyGeneratedRuntimeToolProposalToDispatchRequest: () => applyGeneratedRuntimeToolProposalToDispatchRequest,
   attachRuntimeToolsToDispatchRequest: () => attachRuntimeToolsToDispatchRequest,
+  buildEmptySessionNudge: () => buildEmptySessionNudge,
   buildGeneratedRuntimeToolGateOutput: () => buildGeneratedRuntimeToolGateOutput,
   buildLedgerOffloadReference: () => buildLedgerOffloadReference,
+  buildPolicyGuidance: () => buildPolicyGuidance,
   buildSendViewOffloadMarker: () => buildSendViewOffloadMarker,
+  compileWorkflowConfig: () => compileWorkflowConfig,
   computeAgentContentHash: () => computeAgentContentHash,
   computeFlowContentHash: () => computeFlowContentHash,
+  computeToolContentHash: () => computeToolContentHash,
   createClient: () => createClient,
   createExternalTool: () => createExternalTool,
   defaultWorkflow: () => defaultWorkflow,
+  defaultWorkflowConfig: () => defaultWorkflowConfig,
   defineAgent: () => defineAgent,
   defineFlow: () => defineFlow,
+  definePlaybook: () => definePlaybook,
+  defineTool: () => defineTool,
   deployWorkflow: () => deployWorkflow,
+  ensureDefaultWorkflowHooks: () => ensureDefaultWorkflowHooks,
   evaluateGeneratedRuntimeToolProposal: () => evaluateGeneratedRuntimeToolProposal,
   extractDeclaredToolResultChars: () => extractDeclaredToolResultChars,
   gameWorkflow: () => gameWorkflow,
   getDefaultPlanPath: () => getDefaultPlanPath,
   getLikelySupportingCandidatePaths: () => getLikelySupportingCandidatePaths,
+  interpolateWorkflowTemplate: () => interpolateWorkflowTemplate,
   isDiscoveryToolName: () => isDiscoveryToolName,
   isMarathonArtifactPath: () => isMarathonArtifactPath,
   isPreservationSensitiveTask: () => isPreservationSensitiveTask,
+  isWorkflowHookRef: () => isWorkflowHookRef,
+  listWorkflowHooks: () => listWorkflowHooks,
   normalizeAgentDefinition: () => normalizeAgentDefinition,
   normalizeCandidatePath: () => normalizeCandidatePath,
+  normalizeToolDefinition: () => normalizeToolDefinition,
   parseFinalBuffer: () => parseFinalBuffer,
   parseLedgerArtifactRelativePath: () => parseLedgerArtifactRelativePath,
   parseOffloadedOutputId: () => parseOffloadedOutputId,
   parseSSEChunk: () => parseSSEChunk,
   processStream: () => processStream,
+  registerWorkflowHook: () => registerWorkflowHook,
+  resolveStallStopAfter: () => resolveStallStopAfter,
+  resolveWorkflowHook: () => resolveWorkflowHook,
   sanitizeTaskSlug: () => sanitizeTaskSlug,
-  streamEvents: () => streamEvents
+  shouldInjectEmptySessionNudge: () => shouldInjectEmptySessionNudge,
+  shouldRequestModelEscalation: () => shouldRequestModelEscalation,
+  streamEvents: () => streamEvents,
+  unregisterWorkflowHook: () => unregisterWorkflowHook
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1202,20 +1225,20 @@ var FlowBuilder = class {
    */
   build() {
     const flow = this.existingFlowId ? { id: this.existingFlowId } : { name: this.flowConfig.name, steps: this.steps };
-    const request2 = { flow };
+    const request3 = { flow };
     if (this.recordConfig) {
-      request2.record = this.recordConfig;
+      request3.record = this.recordConfig;
     }
     if (this.messagesConfig) {
-      request2.messages = this.messagesConfig;
+      request3.messages = this.messagesConfig;
     }
     if (this.inputsConfig) {
-      request2.inputs = this.inputsConfig;
+      request3.inputs = this.inputsConfig;
     }
     if (Object.keys(this.optionsConfig).length > 0) {
-      request2.options = this.optionsConfig;
+      request3.options = this.optionsConfig;
     }
-    return request2;
+    return request3;
   }
   /**
    * Validate this prospective flow against the public validation endpoint
@@ -1538,6 +1561,9 @@ function collectStepNonPortableToolRefs(config, path) {
       scanArray(tools.codeModeConfig.toolPool, `${path}.tools.codeModeConfig.toolPool`);
     }
   }
+  if (isAccountScoped(config.toolId)) {
+    found.push(`${path}.toolId`);
+  }
   for (const branch of ["trueSteps", "falseSteps"]) {
     const nested = config[branch];
     if (!Array.isArray(nested)) continue;
@@ -1591,7 +1617,7 @@ function defineFlow(input) {
       const nonPortable = collectStepNonPortableToolRefs(config, `steps[${index}].config`);
       if (nonPortable.length > 0) {
         throw new Error(
-          `defineFlow: account-scoped tool reference(s) at ${nonPortable.join(", ")}. Definitions must be environment-portable \u2014 tool_\u2026 IDs belong to one account/environment. Use builtin:/platform:/mcp: references instead. Name-based resolution of saved tools is a planned follow-up.`
+          `defineFlow: account-scoped tool reference(s) at ${nonPortable.join(", ")}. Definitions must be environment-portable \u2014 tool_\u2026 IDs belong to one account/environment. Use builtin:/platform:/mcp: references, or reference a saved tool by name with tool:<name> instead.`
         );
       }
     }
@@ -2590,15 +2616,15 @@ var RuntypeFlowBuilder = class {
   build() {
     const flowMode = this.mode === "existing" ? "existing" : this.mode;
     const flow = this.existingFlowId ? { id: this.existingFlowId } : { name: this.flowConfig.name, steps: this.steps };
-    const request2 = { flow };
+    const request3 = { flow };
     if (this.recordConfig) {
-      request2.record = this.recordConfig;
+      request3.record = this.recordConfig;
     }
     if (this.messagesConfig) {
-      request2.messages = this.messagesConfig;
+      request3.messages = this.messagesConfig;
     }
     if (this.inputsConfig) {
-      request2.inputs = this.inputsConfig;
+      request3.inputs = this.inputsConfig;
     }
     const options = {
       flowMode,
@@ -2616,8 +2642,8 @@ var RuntypeFlowBuilder = class {
     if (this.mode === "upsert" && Object.keys(this.upsertOptions).length > 0) {
       options.upsertOptions = this.upsertOptions;
     }
-    request2.options = options;
-    return request2;
+    request3.options = options;
+    return request3;
   }
   /**
    * Validate this prospective flow against the public validation endpoint
@@ -3507,7 +3533,7 @@ function defineAgent(input) {
   const nonPortable = collectNonPortableToolRefs(config);
   if (nonPortable.length > 0) {
     throw new Error(
-      `defineAgent: account-scoped tool reference(s) at ${nonPortable.join(", ")}. Definitions must be environment-portable \u2014 tool_\u2026 IDs belong to one account/environment. Use builtin:/platform:/mcp: references instead. Name-based resolution of saved tools is a planned follow-up.`
+      `defineAgent: account-scoped tool reference(s) at ${nonPortable.join(", ")}. Definitions must be environment-portable \u2014 tool_\u2026 IDs belong to one account/environment. Use builtin:/platform:/mcp: references, or reference a saved tool by name with tool:<name> instead.`
     );
   }
   return {
@@ -3649,6 +3675,242 @@ var AgentsNamespace = class {
   }
 };
 
+// src/tools-ensure.ts
+function isPlainObject3(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeValue2(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeValue2(item));
+  }
+  if (isPlainObject3(value)) {
+    const normalized = {};
+    for (const key of Object.keys(value).sort()) {
+      const entry = value[key];
+      if (entry === void 0 || entry === null) continue;
+      normalized[key] = normalizeValue2(entry);
+    }
+    return normalized;
+  }
+  return value;
+}
+function normalizeToolDefinition(definition) {
+  const parametersSchema = isPlainObject3(definition.parametersSchema) ? normalizeValue2(definition.parametersSchema) : {};
+  const config = isPlainObject3(definition.config) ? normalizeValue2(definition.config) : {};
+  return {
+    toolType: definition.toolType,
+    ...definition.description ? { description: definition.description } : {},
+    parametersSchema,
+    config
+  };
+}
+async function computeToolContentHash(definition) {
+  const serialized = JSON.stringify(normalizeToolDefinition(definition));
+  const encoded = new TextEncoder().encode(serialized);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", encoded);
+  return Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var DEFINE_TOOL_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
+  "name",
+  "description",
+  "toolType",
+  "parametersSchema",
+  "config"
+]);
+var TOOL_DEFINITION_TYPES = /* @__PURE__ */ new Set([
+  "flow",
+  "custom",
+  "external",
+  "graphql",
+  "mcp",
+  "local",
+  "subagent"
+]);
+function defineTool(input) {
+  if (!input || typeof input !== "object") {
+    throw new Error("defineTool requires a definition object");
+  }
+  if (typeof input.name !== "string" || input.name.length === 0) {
+    throw new Error('defineTool requires a non-empty string "name"');
+  }
+  if (typeof input.description !== "string" || input.description.length === 0) {
+    throw new Error('defineTool requires a non-empty string "description"');
+  }
+  if (typeof input.toolType !== "string" || !TOOL_DEFINITION_TYPES.has(input.toolType)) {
+    throw new Error(
+      `defineTool requires "toolType" to be one of: ${[...TOOL_DEFINITION_TYPES].join(", ")}`
+    );
+  }
+  if (!isPlainObject3(input.parametersSchema)) {
+    throw new Error('defineTool requires a "parametersSchema" object (a JSON Schema)');
+  }
+  if (!isPlainObject3(input.config)) {
+    throw new Error('defineTool requires a "config" object');
+  }
+  const unknownKeys = Object.keys(input).filter((key) => !DEFINE_TOOL_TOP_LEVEL_KEYS.has(key));
+  if (unknownKeys.length > 0) {
+    throw new Error(
+      `defineTool: unknown field(s): ${unknownKeys.join(", ")}. Allowed fields are name, description, toolType, parametersSchema, config.`
+    );
+  }
+  return {
+    name: input.name,
+    description: input.description,
+    toolType: input.toolType,
+    parametersSchema: input.parametersSchema,
+    config: input.config
+  };
+}
+var ToolEnsureConflictError = class extends Error {
+  constructor(body) {
+    super(body.error ?? `Tool ensure conflict: ${body.code}`);
+    this.name = "ToolEnsureConflictError";
+    this.code = body.code;
+    this.lastModifiedSource = body.lastModifiedSource;
+    this.modifiedAt = body.modifiedAt;
+    this.currentHash = body.currentHash;
+  }
+};
+var ToolDriftError = class extends Error {
+  constructor(plan) {
+    super(
+      `Tool "${plan.toolId ?? "definition"}" drifted: plan is '${plan.changes}' (changed: ${plan.changedKeys.join(", ") || "n/a"}). Run client.tools.pull(name) to absorb the remote edit into your repo, or re-run ensure to converge.`
+    );
+    this.name = "ToolDriftError";
+    this.plan = plan;
+  }
+};
+function parseRequestError3(err) {
+  if (!(err instanceof Error)) return { status: null, body: null };
+  const match = err.message.match(/^API request failed: (\d{3}) .*? - ([\s\S]*)$/);
+  if (!match) return { status: null, body: null };
+  try {
+    return { status: Number(match[1]), body: JSON.parse(match[2]) };
+  } catch {
+    return { status: Number(match[1]), body: null };
+  }
+}
+function toConflictError3(err) {
+  const { status, body } = parseRequestError3(err);
+  if (status !== 409 || !isPlainObject3(body)) return null;
+  const code = body.code;
+  if (code !== "external_modification" && code !== "remote_changed") return null;
+  return new ToolEnsureConflictError(
+    body
+  );
+}
+var serverHashMemo3 = /* @__PURE__ */ new WeakMap();
+function memoFor3(client) {
+  let memo = serverHashMemo3.get(client);
+  if (!memo) {
+    memo = /* @__PURE__ */ new Map();
+    serverHashMemo3.set(client, memo);
+  }
+  return memo;
+}
+function memoize2(memo, memoKey, result) {
+  if (result.result !== "plan") memo.set(memoKey, result.contentHash);
+}
+async function request2(client, body) {
+  try {
+    return await client.post(
+      "/tools/ensure",
+      body
+    );
+  } catch (err) {
+    const conflict = toConflictError3(err);
+    if (conflict) throw conflict;
+    throw err;
+  }
+}
+async function ensureTool(client, definition, options = {}) {
+  const { dryRun, onConflict, expectedRemoteHash, expectNoChanges } = options;
+  const passthrough = {
+    ...onConflict ? { onConflict } : {},
+    ...expectedRemoteHash ? { expectedRemoteHash } : {}
+  };
+  if (dryRun || expectNoChanges) {
+    const plan = await request2(client, {
+      name: definition.name,
+      definition,
+      dryRun: true,
+      ...passthrough
+    });
+    if (plan.result !== "plan") {
+      throw new Error(`Expected a plan result from dryRun, got '${plan.result}'`);
+    }
+    if (expectNoChanges && plan.changes !== "none") {
+      throw new ToolDriftError(plan);
+    }
+    return plan;
+  }
+  const memo = memoFor3(client);
+  const localHash = await computeToolContentHash(definition);
+  const memoKey = `${definition.name} ${localHash}`;
+  const contentHash = memo.get(memoKey) ?? localHash;
+  const probe = await request2(client, {
+    name: definition.name,
+    contentHash,
+    ...passthrough
+  });
+  if (probe.result !== "definitionRequired") {
+    memoize2(memo, memoKey, probe);
+    return probe;
+  }
+  const converged = await request2(client, {
+    name: definition.name,
+    definition,
+    ...passthrough
+  });
+  if (converged.result === "definitionRequired") {
+    throw new Error("Server reported definitionRequired for a full-definition request");
+  }
+  memoize2(memo, memoKey, converged);
+  return converged;
+}
+async function pullTool(client, name) {
+  return client.get("/tools/pull", { name });
+}
+
+// src/tools-namespace.ts
+var ToolsNamespace = class {
+  constructor(getClient) {
+    this.getClient = getClient;
+  }
+  /**
+   * Idempotently converge a `defineTool` definition onto the platform.
+   * Hash-first: the steady state is one tiny probe request. Creates or updates
+   * the saved tool; never deletes. Identity is name + account scope.
+   *
+   * @example
+   * ```typescript
+   * const weather = defineTool({
+   *   name: 'Weather Lookup',
+   *   description: 'Fetch the current weather for a city',
+   *   toolType: 'external',
+   *   parametersSchema: { type: 'object', properties: { city: { type: 'string' } } },
+   *   config: { url: 'https://api.example.com/weather', method: 'GET' },
+   * })
+   *
+   * // Converge (CI/deploy).
+   * const result = await Runtype.tools.ensure(weather)
+   *
+   * // PR drift gate.
+   * await Runtype.tools.ensure(weather, { expectNoChanges: true })
+   * ```
+   */
+  async ensure(definition, options = {}) {
+    return ensureTool(this.getClient(), definition, options);
+  }
+  /**
+   * Pull the canonical definition + provenance for a tool by name — the
+   * absorb-drift direction of the ensure protocol.
+   */
+  async pull(name) {
+    return pullTool(this.getClient(), name);
+  }
+};
+
 // src/transform.ts
 function transformResponse(data) {
   return data;
@@ -4037,6 +4299,34 @@ var Runtype = class {
   static get agents() {
     return new AgentsNamespace(() => this.getClient());
   }
+  /**
+   * Tools namespace - Tool config-as-code (define / ensure / pull)
+   *
+   * @example
+   * ```typescript
+   * import { defineTool, Runtype } from '@runtypelabs/sdk'
+   *
+   * const weather = defineTool({
+   *   name: 'Weather Lookup',
+   *   description: 'Fetch the current weather for a city',
+   *   toolType: 'external',
+   *   parametersSchema: { type: 'object', properties: { city: { type: 'string' } } },
+   *   config: { url: 'https://api.example.com/weather', method: 'GET' },
+   * })
+   *
+   * // Converge at deploy time (idempotent; one tiny probe in steady state)
+   * await Runtype.tools.ensure(weather)
+   *
+   * // CI drift gate
+   * await Runtype.tools.ensure(weather, { expectNoChanges: true })
+   *
+   * // Absorb a dashboard edit back into the repo
+   * const { definition } = await Runtype.tools.pull('Weather Lookup')
+   * ```
+   */
+  static get tools() {
+    return new ToolsNamespace(() => this.getClient());
+  }
 };
 
 // src/generated-tool-gate.ts
@@ -4259,8 +4549,8 @@ function buildGeneratedRuntimeToolGateOutput(proposal, options = {}) {
     ...decision.tool ? { tool: decision.tool } : {}
   };
 }
-function attachRuntimeToolsToDispatchRequest(request2, runtimeTools, options = {}) {
-  const stepList = request2.flow.steps;
+function attachRuntimeToolsToDispatchRequest(request3, runtimeTools, options = {}) {
+  const stepList = request3.flow.steps;
   if (!stepList || !Array.isArray(stepList) || stepList.length === 0) {
     throw new Error("Cannot attach runtime tools: dispatch request must include flow.steps");
   }
@@ -4303,9 +4593,9 @@ function attachRuntimeToolsToDispatchRequest(request2, runtimeTools, options = {
     }
   };
   return {
-    ...request2,
+    ...request3,
     flow: {
-      ...request2.flow,
+      ...request3.flow,
       // `clonedSteps` is a structural clone of `request.flow.steps` (already
       // `FlowStepDefinition[]`); only the prompt step's `config.tools` was
       // merged, so every step's `type` discriminant is preserved. The clone is
@@ -4315,12 +4605,12 @@ function attachRuntimeToolsToDispatchRequest(request2, runtimeTools, options = {
     }
   };
 }
-function applyGeneratedRuntimeToolProposalToDispatchRequest(request2, proposal, options = {}) {
+function applyGeneratedRuntimeToolProposalToDispatchRequest(request3, proposal, options = {}) {
   const decision = evaluateGeneratedRuntimeToolProposal(proposal, options.gate);
   if (!decision.approved || !decision.tool) {
-    return { decision, request: request2 };
+    return { decision, request: request3 };
   }
-  const nextRequest = attachRuntimeToolsToDispatchRequest(request2, [decision.tool], options.attach);
+  const nextRequest = attachRuntimeToolsToDispatchRequest(request3, [decision.tool], options.attach);
   return {
     decision,
     request: nextRequest
@@ -4418,6 +4708,261 @@ function sanitizeTaskSlug(taskName) {
   return taskName.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
 }
 
+// src/workflows/hook-registry.ts
+var BUILTIN_NAMESPACE = "builtin";
+var HOOK_REF_PATTERN = /^[a-z0-9_-]+:[a-z0-9_-]+$/;
+function isWorkflowHookRef(value) {
+  return typeof value === "string" && HOOK_REF_PATTERN.test(value);
+}
+var registry = /* @__PURE__ */ new Map();
+function registerWorkflowHook(name, entry) {
+  if (!isWorkflowHookRef(name)) {
+    throw new Error(
+      `Invalid workflow hook name "${name}": must be "<namespace>:<id>" using lowercase letters, digits, "-" or "_" (e.g. "acme:my-completion").`
+    );
+  }
+  if (name.startsWith(`${BUILTIN_NAMESPACE}:`)) {
+    throw new Error(
+      `Cannot register "${name}": the "builtin:" namespace is reserved. Register under your own namespace and reference it from the workflow config instead.`
+    );
+  }
+  registry.set(name, entry);
+}
+function registerBuiltinWorkflowHook(name, entry) {
+  if (!name.startsWith(`${BUILTIN_NAMESPACE}:`) || !isWorkflowHookRef(name)) {
+    throw new Error(`Builtin workflow hooks must be named "builtin:<id>" (got "${name}").`);
+  }
+  if (registry.has(name)) return;
+  registry.set(name, entry);
+}
+function resolveWorkflowHook(name, expectedKind) {
+  const entry = registry.get(name);
+  if (!entry) {
+    const known = listWorkflowHooks().filter((hook) => hook.kind === expectedKind).map((hook) => hook.name);
+    throw new Error(
+      `Unknown workflow hook "${name}". ` + (known.length > 0 ? `Registered '${expectedKind}' hooks: ${known.join(", ")}.` : `No '${expectedKind}' hooks are registered.`) + " Custom hooks must be registered (e.g. via a playbook plugin) before the workflow is compiled."
+    );
+  }
+  if (entry.kind !== expectedKind) {
+    throw new Error(
+      `Workflow hook "${name}" is registered as '${entry.kind}' but referenced from a '${expectedKind}' slot.`
+    );
+  }
+  return entry.fn;
+}
+function listWorkflowHooks() {
+  return [...registry.entries()].map(([name, entry]) => ({ name, kind: entry.kind }));
+}
+function unregisterWorkflowHook(name) {
+  if (name.startsWith(`${BUILTIN_NAMESPACE}:`)) return false;
+  return registry.delete(name);
+}
+
+// src/workflows/workflow-config.ts
+var DISCOVERY_TOOLS = /* @__PURE__ */ new Set([
+  "search_repo",
+  "glob_files",
+  "tree_directory",
+  "list_directory"
+]);
+var DEFAULT_RECOVERY_AFTER_EMPTY_SESSIONS = 2;
+function definePlaybook(playbook) {
+  return playbook;
+}
+function interpolateWorkflowTemplate(template, state) {
+  return template.replace(/\{\{(\w+)\}\}/g, (_match, key) => {
+    const value = state[key];
+    if (value === void 0 || value === null) return `{{${key}}}`;
+    return String(value);
+  });
+}
+function buildIsComplete(criteria, configName, milestoneName) {
+  if (!criteria) return () => false;
+  switch (criteria.type) {
+    case "evidence":
+      return (ctx) => {
+        const minFiles = criteria.minReadFiles ?? 1;
+        return (ctx.state.recentReadPaths?.length ?? 0) >= minFiles;
+      };
+    case "sessions": {
+      let baselineSessionCount;
+      return (ctx) => {
+        const minSessions = criteria.minSessions ?? 1;
+        if (baselineSessionCount === void 0) {
+          baselineSessionCount = ctx.state.sessions.length;
+        }
+        return ctx.state.sessions.length - baselineSessionCount >= minSessions;
+      };
+    }
+    case "planWritten":
+      return (ctx) => {
+        return ctx.trace.planWritten;
+      };
+    case "never":
+      return () => false;
+    default: {
+      if (isWorkflowHookRef(criteria.type)) {
+        return resolveWorkflowHook(criteria.type, "completion");
+      }
+      throw new Error(
+        `Workflow config '${configName}': milestone '${milestoneName}' has unknown completionCriteria.type "${criteria.type}" (expected evidence | sessions | planWritten | never, or a 'completion' hook reference).`
+      );
+    }
+  }
+}
+function buildPolicyIntercept(policy, configName, deps) {
+  if (!policy.blockedTools?.length && !policy.blockDiscoveryTools && !policy.allowedReadGlobs?.length && !policy.allowedWriteGlobs?.length && !policy.requirePlanBeforeWrite) {
+    return void 0;
+  }
+  const blockedSet = new Set(
+    (policy.blockedTools ?? []).map((t) => t.trim()).filter(Boolean)
+  );
+  const readGlobs = policy.allowedReadGlobs ?? [];
+  const writeGlobs = policy.allowedWriteGlobs ?? [];
+  const matchPathGlobs = deps.matchPathGlobs;
+  if ((readGlobs.length > 0 || writeGlobs.length > 0) && !matchPathGlobs) {
+    throw new Error(
+      `Workflow config '${configName}': policy uses allowedReadGlobs/allowedWriteGlobs but no glob matcher was provided to compileWorkflowConfig (pass deps.matchPathGlobs).`
+    );
+  }
+  return (toolName, args, ctx) => {
+    if (blockedSet.has(toolName)) {
+      return `Blocked by playbook policy: ${toolName} is not allowed for this task.`;
+    }
+    if (policy.blockDiscoveryTools && DISCOVERY_TOOLS.has(toolName)) {
+      return `Blocked by playbook policy: discovery tools are disabled for this task.`;
+    }
+    const pathArg = typeof args.path === "string" && args.path.trim() ? ctx.normalizePath(String(args.path)) : void 0;
+    if (pathArg) {
+      const isWrite = toolName === "write_file" || toolName === "restore_file_checkpoint";
+      const isRead = toolName === "read_file";
+      if (isRead && readGlobs.length > 0) {
+        const allowed = matchPathGlobs(pathArg, readGlobs);
+        if (!allowed) {
+          return `Blocked by playbook policy: ${toolName} path "${pathArg}" is outside allowed read globs: ${readGlobs.join(", ")}`;
+        }
+      }
+      if (isWrite && writeGlobs.length > 0) {
+        const planPath = ctx.state.planPath ? ctx.normalizePath(ctx.state.planPath) : void 0;
+        if (planPath && pathArg === planPath) {
+        } else {
+          const allowed = matchPathGlobs(pathArg, writeGlobs);
+          if (!allowed) {
+            return `Blocked by playbook policy: ${toolName} path "${pathArg}" is outside allowed write globs: ${writeGlobs.join(", ")}`;
+          }
+        }
+      }
+      if (isWrite && policy.requirePlanBeforeWrite && !ctx.state.planWritten && !ctx.trace.planWritten) {
+        const planPath = ctx.state.planPath ? ctx.normalizePath(ctx.state.planPath) : void 0;
+        if (!planPath || pathArg !== planPath) {
+          return `Blocked by playbook policy: write the plan before creating other files.`;
+        }
+      }
+    }
+    return void 0;
+  };
+}
+function buildPolicyGuidance(policy) {
+  if (!policy) return [];
+  const lines = [];
+  if (policy.requirePlanBeforeWrite) {
+    lines.push(
+      "Policy: write the plan file before any other file. Once the plan is written, other writes are allowed in the same turn."
+    );
+  }
+  if (policy.allowedWriteGlobs?.length) {
+    lines.push(
+      `Policy: file writes are only allowed for paths matching: ${policy.allowedWriteGlobs.join(", ")} (the plan file is always allowed).`
+    );
+  }
+  if (policy.outputRoot) {
+    lines.push(`Policy: create new files under "${policy.outputRoot.replace(/\/$/, "")}/".`);
+  }
+  if (policy.allowedReadGlobs?.length) {
+    lines.push(
+      `Policy: file reads are only allowed for paths matching: ${policy.allowedReadGlobs.join(", ")}.`
+    );
+  }
+  if (policy.blockDiscoveryTools) {
+    lines.push(
+      "Policy: broad discovery tools (search_repo, glob_files, tree_directory, list_directory) are disabled for this task."
+    );
+  }
+  if (policy.blockedTools?.length) {
+    lines.push(`Policy: these tools are disabled for this task: ${policy.blockedTools.join(", ")}.`);
+  }
+  return lines;
+}
+function resolveSlotHook(value, kind) {
+  if (value === void 0) return void 0;
+  if (typeof value === "function") return value;
+  return resolveWorkflowHook(value, kind);
+}
+function compileMilestone(milestone, config, policyIntercept, policyGuidance) {
+  const buildInstructions = typeof milestone.instructions === "function" ? milestone.instructions : isWorkflowHookRef(milestone.instructions) ? resolveWorkflowHook(milestone.instructions, "instructions") : (state) => {
+    const header = `--- Workflow Phase: ${milestone.name} ---`;
+    const desc = milestone.description ? `
+${milestone.description}` : "";
+    const instructions = interpolateWorkflowTemplate(
+      milestone.instructions,
+      state
+    );
+    return `${header}${desc}
+${instructions}`;
+  };
+  const guidanceHook = typeof milestone.toolGuidance === "function" ? milestone.toolGuidance : milestone.toolGuidance !== void 0 && isWorkflowHookRef(milestone.toolGuidance) ? resolveWorkflowHook(milestone.toolGuidance, "toolGuidance") : void 0;
+  const buildToolGuidance = (state) => {
+    const base = guidanceHook ? guidanceHook(state) : milestone.toolGuidance ?? [];
+    return policyGuidance.length > 0 ? [...base, ...policyGuidance] : base;
+  };
+  const customIntercept = resolveSlotHook(milestone.intercept, "intercept");
+  const interceptToolCall = policyIntercept && customIntercept ? (toolName, args, ctx) => policyIntercept(toolName, args, ctx) ?? customIntercept(toolName, args, ctx) : policyIntercept ?? customIntercept;
+  const transitionHook = typeof milestone.transitionSummary === "function" ? milestone.transitionSummary : milestone.transitionSummary !== void 0 && isWorkflowHookRef(milestone.transitionSummary) ? resolveWorkflowHook(milestone.transitionSummary, "transitionSummary") : void 0;
+  const buildTransitionSummary = milestone.transitionSummary === void 0 ? void 0 : transitionHook ?? ((state, nextPhaseName) => interpolateWorkflowTemplate(milestone.transitionSummary, state).replace(
+    /\{\{nextPhase\}\}/g,
+    nextPhaseName
+  ));
+  const recoveryHook = typeof milestone.recovery === "function" ? milestone.recovery : milestone.recovery !== void 0 && isWorkflowHookRef(milestone.recovery) ? resolveWorkflowHook(milestone.recovery, "recovery") : void 0;
+  const buildRecoveryMessage = milestone.recovery === void 0 ? void 0 : recoveryHook ?? ((state) => {
+    const inline = milestone.recovery;
+    const threshold = inline.afterEmptySessions ?? DEFAULT_RECOVERY_AFTER_EMPTY_SESSIONS;
+    if ((state.consecutiveEmptySessions ?? 0) < threshold) return void 0;
+    return interpolateWorkflowTemplate(inline.message, state);
+  });
+  const canAcceptCompletion = milestone.canAcceptCompletion === void 0 ? void 0 : typeof milestone.canAcceptCompletion === "function" ? milestone.canAcceptCompletion : isWorkflowHookRef(milestone.canAcceptCompletion) ? resolveWorkflowHook(milestone.canAcceptCompletion, "acceptCompletion") : () => milestone.canAcceptCompletion;
+  const isComplete = typeof milestone.completionCriteria === "function" ? milestone.completionCriteria : buildIsComplete(milestone.completionCriteria, config.name, milestone.name);
+  return {
+    name: milestone.name,
+    description: milestone.description,
+    buildInstructions,
+    buildToolGuidance,
+    isComplete,
+    ...interceptToolCall ? { interceptToolCall } : {},
+    ...buildTransitionSummary ? { buildTransitionSummary } : {},
+    ...buildRecoveryMessage ? { buildRecoveryMessage } : {},
+    ...milestone.forceEndTurn ? { shouldForceEndTurn: resolveSlotHook(milestone.forceEndTurn, "forceEndTurn") } : {},
+    ...canAcceptCompletion ? { canAcceptCompletion } : {}
+  };
+}
+function compileWorkflowConfig(config, deps = {}) {
+  const policyIntercept = config.policy ? buildPolicyIntercept(config.policy, config.name, deps) : void 0;
+  const policyGuidance = buildPolicyGuidance(config.policy);
+  const phases = config.milestones.map(
+    (milestone) => compileMilestone(milestone, config, policyIntercept, policyGuidance)
+  );
+  const classifyVariant4 = resolveSlotHook(config.classifyVariant, "classify");
+  const generateBootstrapContext2 = resolveSlotHook(config.bootstrap, "bootstrap");
+  const buildCandidateBlock2 = resolveSlotHook(config.candidateBlock, "candidateBlock");
+  return {
+    name: config.name,
+    phases,
+    ...config.stallPolicy ? { stallPolicy: config.stallPolicy } : {},
+    ...classifyVariant4 ? { classifyVariant: classifyVariant4 } : {},
+    ...generateBootstrapContext2 ? { generateBootstrapContext: generateBootstrapContext2 } : {},
+    ...buildCandidateBlock2 ? { buildCandidateBlock: buildCandidateBlock2 } : {}
+  };
+}
+
 // src/workflows/default-workflow.ts
 function isExternalTask(state) {
   return state.workflowVariant === "external";
@@ -4567,6 +5112,45 @@ function summarizeTextBlock(value, maxLines = 4) {
   if (!text) return "";
   return text.split("\n").map((line) => line.trim()).filter(Boolean).slice(0, maxLines).join(" | ").slice(0, 240);
 }
+function interceptProductWriteTarget(toolName, normalizedPathArg, ctx, guardLabel) {
+  const normalizedPlanPath = ctx.state.planPath ? ctx.normalizePath(ctx.state.planPath) : void 0;
+  const normalizedBestCandidatePath = ctx.state.bestCandidatePath ? ctx.normalizePath(ctx.state.bestCandidatePath) : void 0;
+  if (!ctx.state.isCreationTask && normalizedPathArg && normalizedPathArg !== normalizedPlanPath) {
+    const allowedWriteTargets = new Set(
+      [
+        normalizedPlanPath,
+        normalizedBestCandidatePath,
+        ...(ctx.state.recentReadPaths || []).map((readPath) => ctx.normalizePath(readPath)),
+        ...ctx.trace.readPaths.map((readPath) => ctx.normalizePath(readPath))
+      ].filter((value) => Boolean(value))
+    );
+    if (!allowedWriteTargets.has(normalizedPathArg)) {
+      return [
+        `Blocked by marathon ${guardLabel}: ${toolName} is limited to the confirmed target, the plan file, or files already discovered/read for this task.`,
+        `Do not create scratch files like "${normalizedPathArg}".`,
+        normalizedBestCandidatePath ? `Edit "${normalizedBestCandidatePath}" or another previously discovered repo file instead.` : "Read the current target file before writing."
+      ].join(" ");
+    }
+  }
+  if (ctx.state.isCreationTask && normalizedPathArg && normalizedPathArg !== normalizedPlanPath) {
+    const outputRoot = ctx.state.outputRoot ? ctx.state.outputRoot.trim().replace(/\\/g, "/").replace(/\/+/g, "/").replace(/\/$/, "") || void 0 : void 0;
+    if (!outputRoot) {
+      return [
+        `Blocked by marathon ${guardLabel}: creation tasks require outputRoot. Writes outside the plan are not allowed.`,
+        `Plan path: "${normalizedPlanPath}". Create files only under the configured output root.`
+      ].join(" ");
+    }
+    const rootPrefix = outputRoot + "/";
+    const isUnderRoot = normalizedPathArg === outputRoot || normalizedPathArg.startsWith(rootPrefix);
+    if (!isUnderRoot) {
+      return [
+        `Blocked by marathon ${guardLabel}: ${toolName} must target the plan or paths under outputRoot "${outputRoot}/".`,
+        `"${normalizedPathArg}" is outside the allowed output root.`
+      ].join(" ");
+    }
+  }
+  return void 0;
+}
 var researchPhase = {
   name: "research",
   description: "Inspect the repo and identify the correct target file",
@@ -4651,11 +5235,15 @@ var researchPhase = {
         const normalizedPathArg2 = typeof _args.path === "string" && _args.path.trim() ? ctx.normalizePath(String(_args.path)) : void 0;
         const normalizedPlanPath = ctx.state.planPath ? ctx.normalizePath(ctx.state.planPath) : void 0;
         if (normalizedPathArg2 && normalizedPlanPath && normalizedPathArg2 !== normalizedPlanPath) {
-          return [
-            `Blocked by marathon research guard: ${toolName} cannot create product files during the research phase.`,
-            "Complete research first, then the system will advance you to planning.",
-            `You may write the plan to "${normalizedPlanPath}" once research is complete.`
-          ].join(" ");
+          const planWritten = ctx.trace.planWritten || Boolean(ctx.state.planWritten);
+          if (!planWritten) {
+            return [
+              `Blocked by marathon research guard: ${toolName} cannot create product files during the research phase.`,
+              "Complete research first, then the system will advance you to planning.",
+              `You may write the plan to "${normalizedPlanPath}" once research is complete.`
+            ].join(" ");
+          }
+          return interceptProductWriteTarget(toolName, normalizedPathArg2, ctx, "research guard");
         }
       }
       return void 0;
@@ -4778,19 +5366,24 @@ var planningPhase = {
         "Research is complete. Write the implementation plan for building this from scratch.",
         `Write the plan markdown to exactly: ${planPath}`,
         "List the files you will create, their locations, purpose, and any dependencies to install.",
+        ...state.outputRoot ? [
+          `All new files must be created under "${state.outputRoot}" \u2014 writes outside that directory are blocked, so plan every file location inside it.`
+        ] : [],
         'Include a "Verification steps" section listing the concrete checks you will run before TASK_COMPLETE.',
-        "If the plan already exists, update that same plan file instead of creating a different one."
+        "If the plan already exists, update that same plan file instead of creating a different one.",
+        "Once the plan is written, you may begin creating the planned files in the same turn."
       ].join("\n");
     }
     return [
       "--- Workflow Phase: Planning ---",
       "Research is complete. Your current job is to write the implementation plan before any product-file edits.",
       `Write the plan markdown to exactly: ${planPath}`,
-      "Do NOT edit the target product file yet.",
+      "Do NOT edit the target product file before the plan exists.",
       "The plan should summarize UX findings, explain why the current best candidate is the right file, and list concrete execution steps.",
       'The plan must include a "Preserve existing functionality" section that lists current behaviors, linked files, integrations, and constraints that must keep working.',
       'The plan must include a "Verification steps" section listing the concrete checks you will run before TASK_COMPLETE.',
-      "If the plan already exists, update that same plan file instead of creating a different one."
+      "If the plan already exists, update that same plan file instead of creating a different one.",
+      "Once the plan is written, you may begin editing the target file in the same turn."
     ].join("\n");
   },
   buildToolGuidance(state) {
@@ -4818,10 +5411,14 @@ var planningPhase = {
     const normalizedPlanPath = ctx.state.planPath ? ctx.normalizePath(ctx.state.planPath) : void 0;
     const isWriteLikeTool = toolName === "write_file" || toolName === "edit_file" || toolName === "restore_file_checkpoint";
     if (isWriteLikeTool && normalizedPathArg && normalizedPlanPath && normalizedPathArg !== normalizedPlanPath) {
-      return [
-        `Blocked by marathon planning guard: ${toolName} must target the exact plan path during planning.`,
-        `Write the plan to "${normalizedPlanPath}" before editing any product files.`
-      ].join(" ");
+      const planWritten = ctx.trace.planWritten || Boolean(ctx.state.planWritten);
+      if (!planWritten) {
+        return [
+          `Blocked by marathon planning guard: ${toolName} must target the exact plan path during planning.`,
+          `Write the plan to "${normalizedPlanPath}" before editing any product files.`
+        ].join(" ");
+      }
+      return interceptProductWriteTarget(toolName, normalizedPathArg, ctx, "planning guard");
     }
     return void 0;
   },
@@ -4881,6 +5478,9 @@ var executionPhase = {
   },
   buildToolGuidance(state) {
     return [
+      ...state.isCreationTask && state.outputRoot ? [
+        `Creation guard: create new files under "${state.outputRoot}". Writes outside it are blocked \u2014 the plan file is the only exception.`
+      ] : [],
       ...state.bestCandidatePath ? [
         `Execution-phase guard: broad discovery tools (search_repo, glob_files, tree_directory, list_directory) are locked while executing against "${state.bestCandidatePath}".`
       ] : [
@@ -4922,40 +5522,13 @@ var executionPhase = {
           `After that, you may update "${normalizedPlanPath}" with progress.`
         ].join(" ");
       }
-      if (!ctx.state.isCreationTask && normalizedPathArg && normalizedPathArg !== normalizedPlanPath) {
-        const allowedWriteTargets = new Set(
-          [
-            normalizedPlanPath,
-            normalizedBestCandidatePath,
-            ...(ctx.state.recentReadPaths || []).map((readPath) => ctx.normalizePath(readPath)),
-            ...ctx.trace.readPaths.map((readPath) => ctx.normalizePath(readPath))
-          ].filter((value) => Boolean(value))
-        );
-        if (!allowedWriteTargets.has(normalizedPathArg)) {
-          return [
-            `Blocked by marathon execution guard: ${toolName} is limited to the confirmed target, the plan file, or files already discovered/read for this task.`,
-            `Do not create scratch files like "${normalizedPathArg}".`,
-            normalizedBestCandidatePath ? `Edit "${normalizedBestCandidatePath}" or another previously discovered repo file instead.` : "Read the current target file before writing."
-          ].join(" ");
-        }
-      }
-      if (ctx.state.isCreationTask && normalizedPathArg && normalizedPathArg !== normalizedPlanPath) {
-        const outputRoot = ctx.state.outputRoot ? ctx.state.outputRoot.trim().replace(/\\/g, "/").replace(/\/+/g, "/").replace(/\/$/, "") || void 0 : void 0;
-        if (!outputRoot) {
-          return [
-            `Blocked by marathon execution guard: creation tasks require outputRoot. Writes outside the plan are not allowed.`,
-            `Plan path: "${normalizedPlanPath}". Create files only under the configured output root.`
-          ].join(" ");
-        }
-        const rootPrefix = outputRoot + "/";
-        const isUnderRoot = normalizedPathArg === outputRoot || normalizedPathArg.startsWith(rootPrefix);
-        if (!isUnderRoot) {
-          return [
-            `Blocked by marathon execution guard: ${toolName} must target the plan or paths under outputRoot "${outputRoot}/".`,
-            `"${normalizedPathArg}" is outside the allowed output root.`
-          ].join(" ");
-        }
-      }
+      const writeTargetBlock = interceptProductWriteTarget(
+        toolName,
+        normalizedPathArg,
+        ctx,
+        "execution guard"
+      );
+      if (writeTargetBlock) return writeTargetBlock;
     }
     return void 0;
   },
@@ -5188,13 +5761,163 @@ function buildCandidateBlock(state) {
     ...state.bestCandidateReason ? [`Why: ${state.bestCandidateReason}`] : []
   ].join("\n");
 }
-var defaultWorkflow = {
+var builtinHooksRegistered = false;
+function ensureDefaultWorkflowHooks() {
+  if (builtinHooksRegistered) return;
+  builtinHooksRegistered = true;
+  registerBuiltinWorkflowHook("builtin:classify-task-variant", {
+    kind: "classify",
+    fn: classifyVariant
+  });
+  registerBuiltinWorkflowHook("builtin:repo-bootstrap-discovery", {
+    kind: "bootstrap",
+    fn: generateBootstrapContext
+  });
+  registerBuiltinWorkflowHook("builtin:best-candidate-block", {
+    kind: "candidateBlock",
+    fn: buildCandidateBlock
+  });
+  registerBuiltinWorkflowHook("builtin:research-instructions", {
+    kind: "instructions",
+    fn: researchPhase.buildInstructions
+  });
+  registerBuiltinWorkflowHook("builtin:research-tool-guidance", {
+    kind: "toolGuidance",
+    fn: researchPhase.buildToolGuidance
+  });
+  registerBuiltinWorkflowHook("builtin:research-complete", {
+    kind: "completion",
+    fn: researchPhase.isComplete
+  });
+  registerBuiltinWorkflowHook("builtin:research-transition-summary", {
+    kind: "transitionSummary",
+    fn: researchPhase.buildTransitionSummary
+  });
+  registerBuiltinWorkflowHook("builtin:research-guard", {
+    kind: "intercept",
+    fn: researchPhase.interceptToolCall
+  });
+  registerBuiltinWorkflowHook("builtin:research-recovery", {
+    kind: "recovery",
+    fn: researchPhase.buildRecoveryMessage
+  });
+  registerBuiltinWorkflowHook("builtin:research-force-end-turn", {
+    kind: "forceEndTurn",
+    fn: researchPhase.shouldForceEndTurn
+  });
+  registerBuiltinWorkflowHook("builtin:research-accept-completion", {
+    kind: "acceptCompletion",
+    fn: researchPhase.canAcceptCompletion
+  });
+  registerBuiltinWorkflowHook("builtin:planning-instructions", {
+    kind: "instructions",
+    fn: planningPhase.buildInstructions
+  });
+  registerBuiltinWorkflowHook("builtin:planning-tool-guidance", {
+    kind: "toolGuidance",
+    fn: planningPhase.buildToolGuidance
+  });
+  registerBuiltinWorkflowHook("builtin:planning-complete", {
+    kind: "completion",
+    fn: planningPhase.isComplete
+  });
+  registerBuiltinWorkflowHook("builtin:planning-transition-summary", {
+    kind: "transitionSummary",
+    fn: planningPhase.buildTransitionSummary
+  });
+  registerBuiltinWorkflowHook("builtin:planning-guard", {
+    kind: "intercept",
+    fn: planningPhase.interceptToolCall
+  });
+  registerBuiltinWorkflowHook("builtin:planning-recovery", {
+    kind: "recovery",
+    fn: planningPhase.buildRecoveryMessage
+  });
+  registerBuiltinWorkflowHook("builtin:planning-force-end-turn", {
+    kind: "forceEndTurn",
+    fn: planningPhase.shouldForceEndTurn
+  });
+  registerBuiltinWorkflowHook("builtin:execution-instructions", {
+    kind: "instructions",
+    fn: executionPhase.buildInstructions
+  });
+  registerBuiltinWorkflowHook("builtin:execution-tool-guidance", {
+    kind: "toolGuidance",
+    fn: executionPhase.buildToolGuidance
+  });
+  registerBuiltinWorkflowHook("builtin:execution-guard", {
+    kind: "intercept",
+    fn: executionPhase.interceptToolCall
+  });
+  registerBuiltinWorkflowHook("builtin:execution-recovery", {
+    kind: "recovery",
+    fn: executionPhase.buildRecoveryMessage
+  });
+  registerBuiltinWorkflowHook("builtin:execution-force-end-turn", {
+    kind: "forceEndTurn",
+    fn: executionPhase.shouldForceEndTurn
+  });
+  registerBuiltinWorkflowHook("builtin:execution-accept-completion", {
+    kind: "acceptCompletion",
+    fn: executionPhase.canAcceptCompletion
+  });
+}
+var defaultWorkflowConfig = {
   name: "default",
-  phases: [researchPhase, planningPhase, executionPhase],
-  classifyVariant,
-  generateBootstrapContext,
-  buildCandidateBlock
+  // Empty-session escalation. The counter only counts tool actions, so
+  // narration-only sessions ("I'll create the files now" with no tool calls)
+  // escalate here even though the phase recovery conditions keyed on
+  // hadTextOutput skip them: nudge after the first actionless session, signal
+  // model escalation after the second (a no-op unless the caller configured a
+  // fallback model), and stop as 'stalled' after the third — the same total
+  // session budget as before stallPolicy existed.
+  stallPolicy: { nudgeAfter: 1, escalateModelAfter: 2, stopAfter: 3 },
+  classifyVariant: "builtin:classify-task-variant",
+  bootstrap: "builtin:repo-bootstrap-discovery",
+  candidateBlock: "builtin:best-candidate-block",
+  milestones: [
+    {
+      name: "research",
+      description: "Inspect the repo and identify the correct target file",
+      instructions: "builtin:research-instructions",
+      toolGuidance: "builtin:research-tool-guidance",
+      completionCriteria: { type: "builtin:research-complete" },
+      intercept: "builtin:research-guard",
+      transitionSummary: "builtin:research-transition-summary",
+      recovery: "builtin:research-recovery",
+      forceEndTurn: "builtin:research-force-end-turn",
+      canAcceptCompletion: "builtin:research-accept-completion"
+    },
+    {
+      name: "planning",
+      description: "Write the implementation plan before editing product files",
+      instructions: "builtin:planning-instructions",
+      toolGuidance: "builtin:planning-tool-guidance",
+      completionCriteria: { type: "builtin:planning-complete" },
+      intercept: "builtin:planning-guard",
+      transitionSummary: "builtin:planning-transition-summary",
+      recovery: "builtin:planning-recovery",
+      forceEndTurn: "builtin:planning-force-end-turn"
+      // canAcceptCompletion intentionally absent: the hand-written planning
+      // phase never defined it, and the SDK accepts completion when the slot
+      // is undefined. Keep parity.
+    },
+    {
+      name: "execution",
+      description: "Execute the plan by editing target files",
+      instructions: "builtin:execution-instructions",
+      toolGuidance: "builtin:execution-tool-guidance",
+      // Execution never auto-advances; completion is agent-driven via TASK_COMPLETE
+      completionCriteria: { type: "never" },
+      intercept: "builtin:execution-guard",
+      recovery: "builtin:execution-recovery",
+      forceEndTurn: "builtin:execution-force-end-turn",
+      canAcceptCompletion: "builtin:execution-accept-completion"
+    }
+  ]
 };
+ensureDefaultWorkflowHooks();
+var defaultWorkflow = compileWorkflowConfig(defaultWorkflowConfig);
 
 // src/workflows/deploy-workflow.ts
 var scaffoldPhase = {
@@ -5606,6 +6329,34 @@ var gameWorkflow = {
   }
 };
 
+// src/workflows/stall-policy.ts
+var DEFAULT_STALL_STOP_AFTER = 3;
+function isPositiveInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1;
+}
+function resolveStallStopAfter(policy) {
+  return isPositiveInteger(policy?.stopAfter) ? policy.stopAfter : DEFAULT_STALL_STOP_AFTER;
+}
+function shouldRequestModelEscalation(policy, consecutiveEmptySessions) {
+  const threshold = policy?.escalateModelAfter;
+  if (!isPositiveInteger(threshold)) return false;
+  return consecutiveEmptySessions === threshold;
+}
+function shouldInjectEmptySessionNudge(policy, consecutiveEmptySessions) {
+  const threshold = policy?.nudgeAfter;
+  if (!isPositiveInteger(threshold)) return false;
+  return consecutiveEmptySessions >= threshold;
+}
+function buildEmptySessionNudge(consecutiveEmptySessions) {
+  const sessionPhrase = consecutiveEmptySessions === 1 ? "Your previous session ended" : `Your previous ${consecutiveEmptySessions} sessions ended`;
+  return [
+    "Recovery instruction:",
+    `${sessionPhrase} without a single tool call. Describing what you plan to do does nothing \u2014 only tool calls make progress.`,
+    "Your next response MUST include at least one tool call (for example write_file, edit_file, read_file, or run_check) that advances the task.",
+    "If a previous tool call was blocked, re-read the block message and satisfy its requirement instead of ending the turn."
+  ].join("\n");
+}
+
 // src/endpoints.ts
 var FlowsEndpoint = class {
   constructor(client) {
@@ -5768,6 +6519,19 @@ var RecordsEndpoint = class {
   async getResults(id, params) {
     return this.client.get(`/records/${id}/results`, params);
   }
+  /**
+   * Get unified step-level execution results for a record, with filtering and
+   * pagination.
+   */
+  async getStepResults(id, params) {
+    return this.client.get(`/records/${id}/step-results`, params);
+  }
+  /**
+   * Get the aggregated cost breakdown (by model) for a record's executions.
+   */
+  async getCosts(id) {
+    return this.client.get(`/records/${id}/costs`);
+  }
   /**
    * Delete a specific result for a record
    */
@@ -6096,15 +6860,15 @@ var DispatchEndpoint = class {
    * Attach approved runtime tools to a prompt step in a redispatch request.
    * Returns a new request object and does not mutate the original.
    */
-  attachApprovedRuntimeTools(request2, runtimeTools, options) {
-    return attachRuntimeToolsToDispatchRequest(request2, runtimeTools, options);
+  attachApprovedRuntimeTools(request3, runtimeTools, options) {
+    return attachRuntimeToolsToDispatchRequest(request3, runtimeTools, options);
   }
   /**
    * Validate a generated runtime tool proposal and attach it to the redispatch
    * request if approved, in one call.
    */
-  applyGeneratedRuntimeToolProposal(request2, proposal, options) {
-    return applyGeneratedRuntimeToolProposalToDispatchRequest(request2, proposal, options);
+  applyGeneratedRuntimeToolProposal(request3, proposal, options) {
+    return applyGeneratedRuntimeToolProposalToDispatchRequest(request3, proposal, options);
   }
 };
 var ChatEndpoint = class {
@@ -6656,8 +7420,8 @@ var GENERATED_RUNTIME_TOOL_PROPOSAL_SCHEMA = {
   },
   required: ["name", "description", "toolType", "parametersSchema", "config"]
 };
-function appendRuntimeToolsToAgentRequest(request2, runtimeTools) {
-  const existing = request2.tools?.runtimeTools || [];
+function appendRuntimeToolsToAgentRequest(request3, runtimeTools) {
+  const existing = request3.tools?.runtimeTools || [];
   const existingNames = new Set(existing.map((tool) => tool.name));
   const converted = runtimeTools.filter((tool) => !existingNames.has(tool.name)).map((tool) => ({
     name: tool.name,
@@ -6667,9 +7431,9 @@ function appendRuntimeToolsToAgentRequest(request2, runtimeTools) {
     ...tool.config ? { config: tool.config } : {}
   }));
   return {
-    ...request2,
+    ...request3,
     tools: {
-      ...request2.tools,
+      ...request3.tools,
       runtimeTools: [...existing, ...converted]
     }
   };
@@ -6745,21 +7509,21 @@ var _AgentsEndpoint = class _AgentsEndpoint {
    * Attach approved runtime tools to an agent execute request.
    * Returns a new request object and does not mutate the original.
    */
-  attachApprovedRuntimeTools(request2, runtimeTools) {
-    return appendRuntimeToolsToAgentRequest(request2, runtimeTools);
+  attachApprovedRuntimeTools(request3, runtimeTools) {
+    return appendRuntimeToolsToAgentRequest(request3, runtimeTools);
   }
   /**
    * Validate a generated runtime tool proposal and append it to an agent execute
    * request if approved, in one call.
    */
-  applyGeneratedRuntimeToolProposal(request2, proposal, options) {
+  applyGeneratedRuntimeToolProposal(request3, proposal, options) {
     const decision = evaluateGeneratedRuntimeToolProposal(proposal, options);
     if (!decision.approved || !decision.tool) {
-      return { decision, request: request2 };
+      return { decision, request: request3 };
     }
     return {
       decision,
-      request: appendRuntimeToolsToAgentRequest(request2, [decision.tool])
+      request: appendRuntimeToolsToAgentRequest(request3, [decision.tool])
     };
   }
   /**
@@ -7518,11 +8282,13 @@ var _AgentsEndpoint = class _AgentsEndpoint {
    * setting. This never mutates persisted marathon history; masking/offloading
    * is a send-time view over the full-fidelity ledger/history.
    */
-  deriveToolContextMessages(messages, taskName, mode, window) {
+  deriveToolContextMessages(messages, taskName, mode, window, offloadRecorder) {
     if (mode === "full-inline") return [...messages];
     const maskMessage = (msg) => ({
       ...msg,
-      toolResults: (msg.toolResults ?? []).map((tr) => this.compactOneResult(tr, taskName, mode))
+      toolResults: (msg.toolResults ?? []).map(
+        (tr) => this.compactOneResult(tr, taskName, mode, offloadRecorder)
+      )
     });
     const view = [...messages];
     if (window === "session") {
@@ -7556,12 +8322,18 @@ var _AgentsEndpoint = class _AgentsEndpoint {
     }
     return view;
   }
-  compactOneResult(tr, taskName, mode) {
+  compactOneResult(tr, taskName, mode, offloadRecorder) {
     if (typeof tr.result === "string" && tr.result.startsWith("[")) return tr;
     if (mode === "hot-tail") {
       return {
         ...tr,
-        result: this.offloadToolResult(taskName, tr.toolCallId, tr.toolName, tr.result)
+        result: this.offloadToolResult(
+          taskName,
+          tr.toolCallId,
+          tr.toolName,
+          tr.result,
+          offloadRecorder
+        )
       };
     }
     return { ...tr, result: `[Output from ${tr.toolName} masked \u2014 re-run the tool if needed]` };
@@ -7577,9 +8349,16 @@ var _AgentsEndpoint = class _AgentsEndpoint {
     return taskName.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
   }
   // chars
-  offloadToolResult(taskName, toolCallId, toolName, result) {
+  offloadToolResult(taskName, toolCallId, toolName, result, offloadRecorder) {
     const resultStr = typeof result === "string" ? result : JSON.stringify(result, null, 2);
     if (resultStr.length <= this.TOOL_OUTPUT_INLINE_THRESHOLD) return result;
+    if (offloadRecorder) {
+      try {
+        const recorded = offloadRecorder({ toolCallId, toolName, content: resultStr });
+        if (recorded?.reference) return recorded.reference;
+      } catch {
+      }
+    }
     let fs;
     try {
       const dynamicRequire = (0, eval)('typeof require !== "undefined" ? require : undefined');
@@ -8152,8 +8931,11 @@ var _AgentsEndpoint = class _AgentsEndpoint {
   }
   buildStuckTurnRecoveryMessage(state, workflow) {
     const currentPhase = workflow.phases.find((p) => p.name === state.workflowPhase);
-    if (currentPhase?.buildRecoveryMessage) {
-      return currentPhase.buildRecoveryMessage(state);
+    const phaseMessage = currentPhase?.buildRecoveryMessage?.(state);
+    if (phaseMessage) return phaseMessage;
+    const emptySessions = state.consecutiveEmptySessions || 0;
+    if (shouldInjectEmptySessionNudge(workflow.stallPolicy, emptySessions)) {
+      return buildEmptySessionNudge(emptySessions);
     }
     return void 0;
   }
@@ -8279,6 +9061,10 @@ var _AgentsEndpoint = class _AgentsEndpoint {
         state.originalMessage = options.message;
       }
       const queuedSteeringMessages = options.getQueuedUserMessages?.() ?? [];
+      if (queuedSteeringMessages.length > 0) {
+        state.consecutiveEmptySessions = 0;
+        state.stallEscalationRequested = void 0;
+      }
       const preparedSession = await this.prepareSessionContext(
         options.message,
         state,
@@ -8299,7 +9085,8 @@ var _AgentsEndpoint = class _AgentsEndpoint {
           onContextCompaction: options.onContextCompaction,
           onContextNotice: options.onContextNotice,
           toolContextMode: options.toolContextMode || "hot-tail",
-          toolWindow: options.toolWindow ?? "session"
+          toolWindow: options.toolWindow ?? "session",
+          offloadRecorder: options.offloadRecorder
         },
         queuedSteeringMessages
       );
@@ -8519,11 +9306,15 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       } else {
         state.lastCompletionRejectionReason = void 0;
       }
-      const sessionHadActions = sessionTrace.wroteFiles || sessionTrace.readFiles || sessionTrace.discoveryPerformed || sessionTrace.verificationAttempted;
+      const sessionHadActions = sessionTrace.wroteFiles || sessionTrace.readFiles || sessionTrace.discoveryPerformed || sessionTrace.verificationAttempted || options.hasQueuedUserMessages?.() === true;
       if (sessionHadActions) {
         state.consecutiveEmptySessions = 0;
+        state.stallEscalationRequested = void 0;
       } else {
         state.consecutiveEmptySessions = (state.consecutiveEmptySessions || 0) + 1;
+        if (shouldRequestModelEscalation(workflow.stallPolicy, state.consecutiveEmptySessions)) {
+          state.stallEscalationRequested = true;
+        }
       }
       if (sessionResult.stopReason === "complete" && !detectedTaskCompletion) {
         const currentPhase = workflow.phases.find((p) => p.name === state.workflowPhase);
@@ -8552,7 +9343,7 @@ var _AgentsEndpoint = class _AgentsEndpoint {
         state.status = "budget_exceeded";
       } else if (acceptedTaskCompletion) {
         state.status = "complete";
-      } else if ((state.consecutiveEmptySessions || 0) >= 3) {
+      } else if ((state.consecutiveEmptySessions || 0) >= resolveStallStopAfter(workflow.stallPolicy)) {
         state.status = "stalled";
       } else if (maxCost && state.totalCost >= maxCost) {
         state.status = "budget_exceeded";
@@ -9155,7 +9946,8 @@ Do NOT redo any of the above work.`
         sourceReplayHistoryMessages,
         state.taskName,
         compactionOptions?.toolContextMode || "hot-tail",
-        compactionOptions?.toolWindow ?? "session"
+        compactionOptions?.toolWindow ?? "session",
+        compactionOptions?.offloadRecorder
       );
       const continuationGuardrail = this.buildContinuationGuardrail(state);
       const defaultContinueMessage = "Continue the task. Review your prior work above and proceed with any remaining work. If everything is already complete, respond with TASK_COMPLETE.";
@@ -9318,7 +10110,8 @@ Do NOT redo any of the above work.`
         sourceHistoryMessages,
         state.taskName,
         compactionOptions?.toolContextMode || "hot-tail",
-        compactionOptions?.toolWindow ?? "session"
+        compactionOptions?.toolWindow ?? "session",
+        compactionOptions?.offloadRecorder
       );
       const historyArtifactReferences = this.extractArtifactReferencesFromMessages(historyMessages);
       const summaryText = this.generateCompactSummary(
@@ -9965,7 +10758,7 @@ var RuntypeClient2 = class {
   clearApiKey() {
     delete this.headers.Authorization;
   }
-  async runWithLocalTools(request2, localTools, arg3, arg4) {
+  async runWithLocalTools(request3, localTools, arg3, arg4) {
     const isOptionsObject = (val) => typeof val === "object" && val !== null && "scope" in val;
     const callbacks = isOptionsObject(arg3) ? void 0 : arg3;
     const options = (isOptionsObject(arg3) ? arg3 : arg4) ?? {};
@@ -9979,12 +10772,12 @@ var RuntypeClient2 = class {
       ...entry.pageOrigin ? { pageOrigin: entry.pageOrigin } : {}
     })) : [];
     const modifiedRequest = {
-      ...request2,
+      ...request3,
       ...derivedClientTools.length > 0 ? {
-        clientTools: [...request2.clientTools ?? [], ...derivedClientTools]
+        clientTools: [...request3.clientTools ?? [], ...derivedClientTools]
       } : {},
       options: {
-        ...request2.options || {},
+        ...request3.options || {},
         streamResponse: isStreaming
       }
     };
@@ -10422,20 +11215,20 @@ var BatchBuilder = class {
     if (!this.recordType) {
       throw new Error("BatchBuilder: recordType is required. Call .forRecordType(type) first.");
     }
-    const request2 = {
+    const request3 = {
       flowId: this.flowId,
       recordType: this.recordType
     };
     if (Object.keys(this.batchOptions).length > 0) {
-      request2.options = this.batchOptions;
+      request3.options = this.batchOptions;
     }
     if (this.filterConfig) {
-      request2.filter = this.filterConfig;
+      request3.filter = this.filterConfig;
     }
     if (this.limitConfig !== void 0) {
-      request2.limit = this.limitConfig;
+      request3.limit = this.limitConfig;
     }
-    return request2;
+    return request3;
   }
   /**
    * Execute the batch operation
@@ -10592,32 +11385,32 @@ var EvalBuilder = class {
         "EvalBuilder: records are required. Call .forRecordType(type) or .withRecords([...]) first."
       );
     }
-    const request2 = {};
+    const request3 = {};
     if (this.flowId) {
-      request2.flowId = this.flowId;
+      request3.flowId = this.flowId;
     } else if (this.virtualFlow) {
-      request2.flow = this.virtualFlow;
+      request3.flow = this.virtualFlow;
     }
     if (this.recordType) {
-      request2.recordType = this.recordType;
+      request3.recordType = this.recordType;
     } else if (this.inlineRecords) {
-      request2.records = this.inlineRecords;
+      request3.records = this.inlineRecords;
     }
     if (this.modelOverrides) {
-      request2.modelOverrides = this.modelOverrides;
+      request3.modelOverrides = this.modelOverrides;
     } else if (this.modelConfigs) {
-      request2.modelConfigs = this.modelConfigs;
+      request3.modelConfigs = this.modelConfigs;
     }
     if (Object.keys(this.evalOptions).length > 0) {
-      request2.options = this.evalOptions;
+      request3.options = this.evalOptions;
     }
     if (this.filterConfig) {
-      request2.filter = this.filterConfig;
+      request3.filter = this.filterConfig;
     }
     if (this.limitConfig !== void 0) {
-      request2.limit = this.limitConfig;
+      request3.limit = this.limitConfig;
     }
-    return request2;
+    return request3;
   }
   /**
    * Execute the evaluation
@@ -11102,6 +11895,8 @@ var STEP_TYPE_TO_METHOD = {
   ClientTokensEndpoint,
   ContextTemplatesEndpoint,
   ConversationsEndpoint,
+  DEFAULT_RECOVERY_AFTER_EMPTY_SESSIONS,
+  DEFAULT_STALL_STOP_AFTER,
   DispatchEndpoint,
   EvalBuilder,
   EvalEndpoint,
@@ -11135,36 +11930,57 @@ var STEP_TYPE_TO_METHOD = {
   SkillProposalsNamespace,
   SkillsNamespace,
   SurfacesEndpoint,
+  ToolDriftError,
+  ToolEnsureConflictError,
   ToolsEndpoint,
+  ToolsNamespace,
   UsersEndpoint,
   applyGeneratedRuntimeToolProposalToDispatchRequest,
   attachRuntimeToolsToDispatchRequest,
+  buildEmptySessionNudge,
   buildGeneratedRuntimeToolGateOutput,
   buildLedgerOffloadReference,
+  buildPolicyGuidance,
   buildSendViewOffloadMarker,
+  compileWorkflowConfig,
   computeAgentContentHash,
   computeFlowContentHash,
+  computeToolContentHash,
   createClient,
   createExternalTool,
   defaultWorkflow,
+  defaultWorkflowConfig,
   defineAgent,
   defineFlow,
+  definePlaybook,
+  defineTool,
   deployWorkflow,
+  ensureDefaultWorkflowHooks,
   evaluateGeneratedRuntimeToolProposal,
   extractDeclaredToolResultChars,
   gameWorkflow,
   getDefaultPlanPath,
   getLikelySupportingCandidatePaths,
+  interpolateWorkflowTemplate,
   isDiscoveryToolName,
   isMarathonArtifactPath,
   isPreservationSensitiveTask,
+  isWorkflowHookRef,
+  listWorkflowHooks,
   normalizeAgentDefinition,
   normalizeCandidatePath,
+  normalizeToolDefinition,
   parseFinalBuffer,
   parseLedgerArtifactRelativePath,
   parseOffloadedOutputId,
   parseSSEChunk,
   processStream,
+  registerWorkflowHook,
+  resolveStallStopAfter,
+  resolveWorkflowHook,
   sanitizeTaskSlug,
-  streamEvents
+  shouldInjectEmptySessionNudge,
+  shouldRequestModelEscalation,
+  streamEvents,
+  unregisterWorkflowHook
 });