@poncho-ai/harness 0.44.0 → 0.46.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.44.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.46.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
 > node scripts/embed-docs.js && tsup src/index.ts --format esm --dts
 
 [embed-docs] Generated poncho-docs.ts with 4 topics
@@ -8,9 +8,9 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/index.js            516.00 KB
+ESM dist/index.js            525.40 KB
 ESM dist/isolate-VY35DGLM.js 49.43 KB
-ESM ⚡️ Build success in 209ms
+ESM ⚡️ Build success in 214ms
 DTS Build start
-DTS ⚡️ Build success in 6795ms
-DTS dist/index.d.ts 83.51 KB
+DTS ⚡️ Build success in 7043ms
+DTS dist/index.d.ts 85.30 KB

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @poncho-ai/harness
 
+## 0.46.0
+
+### Minor Changes
+
+- [#118](https://github.com/cesr/poncho-ai/pull/118) [`e8df464`](https://github.com/cesr/poncho-ai/commit/e8df4649618cba0b408a6c143f923f0dcb2046c8) Thanks [@cesr](https://github.com/cesr)! - harness: 1h static system-prompt cache breakpoint + per-run cache kill-switch
+
+  Two related changes to Anthropic prompt caching:
+
+  **1-hour static system-prompt breakpoint.** The harness now splits the
+  assembled system prompt into a static portion (agent body + skill
+  context + browser/fs/isolate context — stable across many turns and
+  jobs within an hour) and a dynamic tail (memory, todos, time). On
+  Anthropic models, these are sent as two `role: "system"` messages with
+  `cacheControl: { ttl: "1h" }` on the static block. The existing 5-min
+  tail breakpoint on the last user/assistant/tool message is retained.
+
+  This lets later turns and job runs read ~95% of the system prompt at
+  0.1× (cache read) instead of paying 1× whenever the 5-min tail cache
+  has expired — the previous setup only cached for 5 minutes via the
+  tail breakpoint. Within-user cross-conversation and interactive-vs-job
+  all share the static cache.
+
+  **Per-run cache kill-switch.** Added `RunInput.disablePromptCache?:
+boolean` (also exposed on `RunConversationTurnOpts.disablePromptCache`,
+  forwarded into `runInput`). When set, the harness skips the 5-min tail
+  breakpoint for that run. The 1-hour static breakpoint is still
+  applied — the run still benefits from reading the shared static cache,
+  just doesn't write a new tail entry that won't be read before TTL.
+
+  Intended for one-shot programmatic invocations (cron-fired jobs,
+  subagent dispatch) where no follow-up turn is coming within the 5-min
+  TTL window, so the 1.25× write surcharge would be pure waste.
+
+  Non-Anthropic providers fall through to the previous single concatenated
+  `system:` string with no cache control — those providers auto-cache.
+
+  Internal: `isAnthropicModel` is now exported from `prompt-cache.ts`
+  for reuse at the streamText site.
+
+### Patch Changes
+
+- Updated dependencies [[`e8df464`](https://github.com/cesr/poncho-ai/commit/e8df4649618cba0b408a6c143f923f0dcb2046c8)]:
+  - @poncho-ai/sdk@1.12.0
+
+## 0.45.0
+
+### Minor Changes
+
+- [`1adaae2`](https://github.com/cesr/poncho-ai/commit/1adaae2d4cc55800f01d602f2a7d6ecc65031443) Thanks [@cesr](https://github.com/cesr)! - harness: device-dispatch mode for tools that execute on a connected client
+
+  Tools can now be marked `dispatch: "device"` on `loadedConfig.tools`. When
+  the model calls such a tool the dispatcher pauses the run, emits a new
+  `tool:device:required` event, and checkpoints with the new
+  `kind: "device"` discriminator on `pendingApprovals` — same plumbing as
+  the approval flow, different trigger and different resume payload.
+  Consumers (e.g. PonchOS for iOS device tools) drive the external
+  execution and feed the result back via `continueFromToolResult`.
+
+  Approval can be combined: `{access: "approval", dispatch: "device"}`
+  yields the approval card first, then on resume falls through to the
+  device-required event. The wire vocabulary for approvals
+  (`approvalId` etc.) is unchanged; the `pendingApprovals` column /
+  field name stays.
+
+  `ToolAccess` is broadened to accept both the legacy string `"approval"`
+  and the new `{access?, dispatch?}` object form. Existing configs keep
+  working unchanged.
+
+- [`6132601`](https://github.com/cesr/poncho-ai/commit/613260159cdd80fcc02d68aa58ad52d4465bcede) Thanks [@cesr](https://github.com/cesr)! - harness: add `read_subagent` tool for fetching subagent transcripts
+
+  Parent agents can now read a spawned subagent's conversation directly
+  instead of using `message_subagent` to ask it to repeat its work. The
+  new tool accepts a `mode` parameter — `"final"` (last assistant message,
+  default), `"assistant"` (assistant messages only), or `"full"` (every
+  message including tool calls and results) — plus optional `since_index`
+  and `max_messages` for paging long transcripts.
+
+  Access is restricted to direct children: a parent can only read
+  transcripts of subagents whose `parentConversationId` matches its own
+  conversation. The `SubagentManager` interface gains a corresponding
+  `getTranscript` method.
+
+### Patch Changes
+
+- Updated dependencies [[`1adaae2`](https://github.com/cesr/poncho-ai/commit/1adaae2d4cc55800f01d602f2a7d6ecc65031443)]:
+  - @poncho-ai/sdk@1.11.0
+
 ## 0.44.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -167,6 +167,15 @@ interface Conversation {
             input: Record<string, unknown>;
         }>;
         decision?: "approved" | "denied";
+        /**
+         * Checkpoint kind discriminator.
+         * - "approval" (default for legacy rows): user approve/deny gate.
+         * - "device":   tool executes on a connected client device (e.g. iOS); the
+         *               consumer of the harness POSTs a tool result back to resume.
+         * Treat `undefined` as "approval" for backward compatibility with rows
+         * persisted before this field existed.
+         */
+        kind?: "approval" | "device";
     }>;
     runStatus?: "running" | "idle";
     ownerId: string;
@@ -450,7 +459,20 @@ interface UploadsConfig {
     region?: string;
     endpoint?: string;
 }
-type ToolAccess = boolean | "approval";
+type ToolAccess = boolean | "approval" | {
+    access?: "approval";
+    dispatch?: "device";
+};
+/**
+ * Normalize any ToolAccess value into a {access, dispatch} struct.
+ * `boolean` collapses to no special handling — the boolean only encodes
+ * enable/disable, not dispatch — callers gate behavior on `dispatch` and
+ * `access`.
+ */
+declare const normalizeToolAccess: (value: ToolAccess | undefined) => {
+    access?: "approval";
+    dispatch?: "device";
+};
 /** @deprecated Use flat tool keys on `tools` instead. Kept for backward compat. */
 type BuiltInToolToggles = {
     list_directory?: boolean;
@@ -1101,6 +1123,16 @@ interface SubagentSummary {
 interface SubagentSpawnResult {
     subagentId: string;
 }
+type SubagentTranscriptMode = "final" | "assistant" | "full";
+interface SubagentTranscript {
+    subagentId: string;
+    task: string;
+    status: string;
+    totalMessages: number;
+    startIndex: number;
+    messages: Message[];
+    truncated: boolean;
+}
 interface SubagentManager {
     spawn(opts: {
         task: string;
@@ -1111,6 +1143,13 @@ interface SubagentManager {
     sendMessage(subagentId: string, message: string): Promise<SubagentSpawnResult>;
     stop(subagentId: string): Promise<void>;
     list(parentConversationId: string): Promise<SubagentSummary[]>;
+    getTranscript(opts: {
+        subagentId: string;
+        parentConversationId: string;
+        mode: SubagentTranscriptMode;
+        sinceIndex?: number;
+        maxMessages?: number;
+    }): Promise<SubagentTranscript>;
 }
 
 interface ToolCall {
@@ -1229,6 +1268,8 @@ declare class AgentHarness {
     /** Read-only virtual mounts overlaid on the VFS. Empty by default. */
     private virtualMounts;
     private resolveToolAccess;
+    /** Returns the normalized {access, dispatch} mode for the tool. */
+    private resolveToolMode;
     private isToolEnabled;
     private registerIfMissing;
     /**
@@ -1820,12 +1861,13 @@ declare const executeConversationTurn: ({ harness, runInput, events, initialCont
     onEvent?: (event: AgentEvent, draft: TurnDraftState) => void | Promise<void>;
 }) => Promise<ExecuteTurnResult>;
 declare const normalizeApprovalCheckpoint: (approval: StoredApproval, fallbackMessages: Message[]) => StoredApproval;
-declare const buildApprovalCheckpoints: ({ approvals, runId, checkpointMessages, baseMessageCount, pendingToolCalls, }: {
+declare const buildApprovalCheckpoints: ({ approvals, runId, checkpointMessages, baseMessageCount, pendingToolCalls, kind, }: {
     approvals: ApprovalEventItem[];
     runId: string;
     checkpointMessages: Message[];
     baseMessageCount: number;
     pendingToolCalls: PendingToolCall[];
+    kind?: "approval" | "device";
 }) => NonNullable<Conversation["pendingApprovals"]>;
 declare const applyTurnMetadata: (conv: Conversation, meta: TurnResultMetadata, opts?: {
     clearContinuation?: boolean;
@@ -1994,6 +2036,12 @@ interface RunConversationTurnOpts {
     parameters?: Record<string, unknown>;
     abortSignal?: AbortSignal;
     tenantId?: string | null;
+    /**
+     * Forwarded to `RunInput.disablePromptCache`. Set true for one-shot
+     * turns with no follow-up coming (cron-fired jobs, etc.) so the
+     * harness skips the Anthropic cache write.
+     */
+    disablePromptCache?: boolean;
     /** Per-event hook — called for every AgentEvent yielded by the run, in order. */
     onEvent?: (event: AgentEvent) => void | Promise<void>;
 }
@@ -2013,4 +2061,4 @@ interface RunConversationTurnResult {
 }
 declare const runConversationTurn: (opts: RunConversationTurnOpts) => Promise<RunConversationTurnResult>;
 
-export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type ContinuationHooks, type Conversation, type ConversationCreateInit, type ConversationState, type ConversationStatusSnapshot, type ConversationStore, type ConversationSummary, type CreateSkillToolsOptions, type CronJobConfig, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_NAME, DEFAULT_MAX_STEPS, DEFAULT_MODEL_NAME, DEFAULT_MODEL_PROVIDER, DEFAULT_TEMPERATURE, DEFAULT_TIMEOUT, type DefaultAgentDefinitionOptions, type EventSink, type ExecuteTurnResult, type HarnessOptions, type HarnessRunOutput, type HistorySource, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, MAX_CONCURRENT_SUBAGENTS, MAX_CONTINUATION_COUNT, MAX_SUBAGENT_CALLBACK_COUNT, MAX_SUBAGENT_NESTING, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type NetworkConfig, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OrchestratorHooks, type OrchestratorOptions, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentApproval, type PendingSubagentResult, type PendingToolCall, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Recurrence, type RecurrenceType, type Reminder, type ReminderCreateInput, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RunConversationTurnOpts, type RunConversationTurnResult, type RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, type SkillSource, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type StoredApproval, type SubagentManager, type SubagentResult, type SubagentSpawnResult, type SubagentSummary, TOOL_RESULT_ARCHIVE_PARAM, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type TurnDraftState, type TurnResultMetadata, type TurnSection, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, type VirtualMount, applyTurnMetadata, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildSkillContextWindow, buildToolCompletedText, cloneSections, compactMessages, completeOpenAICodexDeviceAuth, computeNextOccurrence, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createTurnDraftState, createUploadStore, createWriteTool, decodeFileInputData, defaultAgentDefinition, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };
+export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type ContinuationHooks, type Conversation, type ConversationCreateInit, type ConversationState, type ConversationStatusSnapshot, type ConversationStore, type ConversationSummary, type CreateSkillToolsOptions, type CronJobConfig, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_NAME, DEFAULT_MAX_STEPS, DEFAULT_MODEL_NAME, DEFAULT_MODEL_PROVIDER, DEFAULT_TEMPERATURE, DEFAULT_TIMEOUT, type DefaultAgentDefinitionOptions, type EventSink, type ExecuteTurnResult, type HarnessOptions, type HarnessRunOutput, type HistorySource, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, MAX_CONCURRENT_SUBAGENTS, MAX_CONTINUATION_COUNT, MAX_SUBAGENT_CALLBACK_COUNT, MAX_SUBAGENT_NESTING, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type NetworkConfig, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OrchestratorHooks, type OrchestratorOptions, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentApproval, type PendingSubagentResult, type PendingToolCall, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Recurrence, type RecurrenceType, type Reminder, type ReminderCreateInput, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RunConversationTurnOpts, type RunConversationTurnResult, type RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, type SkillSource, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type StoredApproval, type SubagentManager, type SubagentResult, type SubagentSpawnResult, type SubagentSummary, type SubagentTranscript, type SubagentTranscriptMode, TOOL_RESULT_ARCHIVE_PARAM, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type TurnDraftState, type TurnResultMetadata, type TurnSection, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, type VirtualMount, applyTurnMetadata, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildSkillContextWindow, buildToolCompletedText, cloneSections, compactMessages, completeOpenAICodexDeviceAuth, computeNextOccurrence, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createTurnDraftState, createUploadStore, createWriteTool, decodeFileInputData, defaultAgentDefinition, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, normalizeToolAccess, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };

package/dist/index.js

@@ -505,6 +505,13 @@ var compactMessages = async (model, messages, config, options) => {
 import { access } from "fs/promises";
 import { resolve as resolve3 } from "path";
 import { createJiti } from "jiti";
+var normalizeToolAccess = (value) => {
+  if (value === "approval") return { access: "approval" };
+  if (value && typeof value === "object") {
+    return { access: value.access, dispatch: value.dispatch };
+  }
+  return {};
+};
 var resolveTtl = (ttl, key) => {
   if (typeof ttl === "number") {
     return ttl;
@@ -8256,6 +8263,57 @@ var createSubagentTools = (manager) => [
       }
       return { subagents };
     }
+  }),
+  defineTool11({
+    name: "read_subagent",
+    description: "Fetch the conversation transcript of a subagent you spawned. Use this to inspect a subagent's intermediate reasoning, tool calls, or full output -- instead of asking it to repeat its work via message_subagent.\n\nModes:\n- 'final' (default): just the last assistant message. Cheap.\n- 'assistant': all assistant messages, no tool calls/results.\n- 'full': every message including tool calls and results. Can be large.\n\nUse since_index / max_messages to page through long transcripts. Only works on subagents directly spawned by this conversation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        subagent_id: {
+          type: "string",
+          description: "The subagent ID (from spawn_subagent or list_subagents)."
+        },
+        mode: {
+          type: "string",
+          enum: ["final", "assistant", "full"],
+          description: "How much of the transcript to return. Defaults to 'final'."
+        },
+        since_index: {
+          type: "number",
+          description: "Skip messages before this index (applied after mode filter)."
+        },
+        max_messages: {
+          type: "number",
+          description: "Cap the number of messages returned."
+        }
+      },
+      required: ["subagent_id"],
+      additionalProperties: false
+    },
+    handler: async (input, context) => {
+      const subagentId = typeof input.subagent_id === "string" ? input.subagent_id : "";
+      if (!subagentId) {
+        return { error: "subagent_id is required" };
+      }
+      const parentConversationId = context.conversationId;
+      if (!parentConversationId) {
+        return { error: "no active conversation" };
+      }
+      const rawMode = typeof input.mode === "string" ? input.mode : "final";
+      const mode = rawMode === "assistant" || rawMode === "full" ? rawMode : "final";
+      try {
+        return await manager.getTranscript({
+          subagentId,
+          parentConversationId,
+          mode,
+          sinceIndex: typeof input.since_index === "number" ? input.since_index : void 0,
+          maxMessages: typeof input.max_messages === "number" ? input.max_messages : void 0
+        });
+      } catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+      }
+    }
   })
 ];
 
@@ -9044,11 +9102,20 @@ var AgentHarness = class _AgentHarness {
     const envOverride = tools.byEnvironment?.[env]?.[toolName];
     if (envOverride !== void 0) return envOverride;
     const flatValue = tools[toolName];
-    if (typeof flatValue === "boolean" || flatValue === "approval") return flatValue;
+    if (typeof flatValue === "boolean" || flatValue === "approval" || flatValue !== null && typeof flatValue === "object" && !Array.isArray(flatValue) && // distinguish a ToolAccess object from the nested `defaults` /
+    // `byEnvironment` sibling fields by checking it has only the
+    // expected ToolAccess keys.
+    Object.keys(flatValue).every((k) => k === "access" || k === "dispatch")) {
+      return flatValue;
+    }
     const legacyValue = tools.defaults?.[toolName];
     if (legacyValue !== void 0) return legacyValue;
     return true;
   }
+  /** Returns the normalized {access, dispatch} mode for the tool. */
+  resolveToolMode(toolName) {
+    return normalizeToolAccess(this.resolveToolAccess(toolName));
+  }
   isToolEnabled(name) {
     const access4 = this.resolveToolAccess(name);
     if (access4 === false) return false;
@@ -9536,7 +9603,7 @@ var AgentHarness = class _AgentHarness {
     );
   }
   requiresApprovalForToolCall(toolName, input) {
-    if (this.resolveToolAccess(toolName) === "approval") {
+    if (this.resolveToolMode(toolName).access === "approval") {
       return true;
     }
     if (toolName === "run_skill_script") {
@@ -10062,10 +10129,13 @@ var AgentHarness = class _AgentHarness {
       );
     }
     const hasFullToolResults = hasUntruncatedToolResults(messages);
-    if (hasFullToolResults) {
-      costLog.debug(`cache breakpoint before untruncated tool results (run=${runId.slice(0, 12)})`);
+    const skipTailCache = input.disablePromptCache === true;
+    if (skipTailCache) {
+      costLog.debug(`tail cache breakpoint skipped \u2014 disablePromptCache (run=${runId.slice(0, 12)})`);
+    } else if (hasFullToolResults) {
+      costLog.debug(`tail cache breakpoint before untruncated tool results (run=${runId.slice(0, 12)})`);
     } else {
-      costLog.debug(`cache breakpoint at history tail (run=${runId.slice(0, 12)})`);
+      costLog.debug(`tail cache breakpoint at history tail (run=${runId.slice(0, 12)})`);
     }
     const inputMessageCount = messages.length;
     const events = [];
@@ -10154,11 +10224,11 @@ ${typeStubs}
 
 Code is wrapped in an async IIFE \u2014 use \`return\` to return a value to the tool result.`;
     }
-    const buildSystemPrompt = async () => {
+    const buildSystemPromptParts = async () => {
       const agentPrompt = renderCurrentAgentPrompt();
       const tenantSkills = await this.getSkillsForTenant(input.tenantId);
       const skillContextWindow = buildSkillContextWindow(tenantSkills);
-      const promptWithSkills = skillContextWindow ? `${agentPrompt}${developmentContext}
+      const staticPart = skillContextWindow ? `${agentPrompt}${developmentContext}
 
 ${skillContextWindow}${browserContext}${fsContext}${isolateContext}` : `${agentPrompt}${developmentContext}${browserContext}${fsContext}${isolateContext}`;
       const hourlyTime = (() => {
@@ -10170,9 +10240,11 @@ ${skillContextWindow}${browserContext}${fsContext}${isolateContext}` : `${agentP
       const timeContext = this.reminderStore ? `
 
 Current UTC time (hour precision): ${hourlyTime}` : "";
-      return `${promptWithSkills}${memoryContext}${todoContext}${timeContext}`;
+      const dynamicPart = `${memoryContext}${todoContext}${timeContext}`;
+      return { staticPart, dynamicPart };
     };
-    let systemPrompt = await buildSystemPrompt();
+    let { staticPart: staticSystemPart, dynamicPart: dynamicSystemPart } = await buildSystemPromptParts();
+    let systemPrompt = `${staticSystemPart}${dynamicSystemPart}`;
     let lastPromptFingerprint = `${this.agentFileFingerprint}
 ${this.skillFingerprint}`;
     const pushEvent = (event) => {
@@ -10606,17 +10678,28 @@ ${textContent}` };
           const coreMessages = cachedCoreMessages;
           const temperature = agent.frontmatter.model?.temperature ?? 0.2;
           const maxTokens = agent.frontmatter.model?.maxTokens;
-          const breakpointIndex = hasFullToolResults ? findLastStableCacheIndex(coreMessages) : coreMessages.length - 1;
-          const cachedMessages = addPromptCacheBreakpoints(
+          const cachedMessages = skipTailCache ? coreMessages : addPromptCacheBreakpoints(
             coreMessages,
             modelInstance,
-            breakpointIndex
+            hasFullToolResults ? findLastStableCacheIndex(coreMessages) : coreMessages.length - 1
           );
+          const useStaticCache = isAnthropicModel(modelInstance);
+          const finalMessages = useStaticCache ? [
+            {
+              role: "system",
+              content: staticSystemPart,
+              providerOptions: {
+                anthropic: { cacheControl: { type: "ephemeral", ttl: "1h" } }
+              }
+            },
+            ...dynamicSystemPart.length > 0 ? [{ role: "system", content: dynamicSystemPart }] : [],
+            ...cachedMessages
+          ] : cachedMessages;
           const telemetryEnabled = this.loadedConfig?.telemetry?.enabled !== false;
           const result = await streamText({
             model: modelInstance,
-            system: systemPrompt,
-            messages: cachedMessages,
+            ...useStaticCache ? {} : { system: systemPrompt },
+            messages: finalMessages,
             tools,
             temperature,
             abortSignal: input.abortSignal,
@@ -10895,6 +10978,7 @@ ${textContent}` };
           const richToolResults = [];
           const approvedCalls = [];
           const approvalNeeded = [];
+          const deviceNeeded = [];
           for (const call of toolCalls) {
             if (isCancelled()) {
               yield emitCancellation();
@@ -10909,6 +10993,13 @@ ${textContent}` };
                 name: runtimeToolName,
                 input: call.input
               });
+            } else if (this.resolveToolMode(runtimeToolName).dispatch === "device") {
+              deviceNeeded.push({
+                approvalId: `device_${randomUUID5()}`,
+                id: call.id,
+                name: runtimeToolName,
+                input: call.input
+              });
             } else {
               approvedCalls.push({
                 id: call.id,
@@ -10957,6 +11048,46 @@ ${textContent}` };
             });
             return;
           }
+          if (deviceNeeded.length > 0) {
+            for (const dn of deviceNeeded) {
+              yield pushEvent({
+                type: "tool:device:required",
+                tool: dn.name,
+                input: dn.input,
+                requestId: dn.approvalId
+              });
+            }
+            const assistantContent2 = JSON.stringify({
+              text: fullText,
+              tool_calls: toolCalls.map((tc) => ({
+                id: tc.id,
+                name: exposedToolNames.get(tc.name) ?? tc.name,
+                input: tc.input
+              }))
+            });
+            const assistantMsg = {
+              role: "assistant",
+              content: assistantContent2,
+              metadata: { timestamp: now(), id: randomUUID5(), step, runId }
+            };
+            const deltaMessages = [...messages.slice(inputMessageCount), assistantMsg];
+            yield pushEvent({
+              type: "tool:device:checkpoint",
+              approvals: deviceNeeded.map((dn) => ({
+                approvalId: dn.approvalId,
+                tool: dn.name,
+                toolCallId: dn.id,
+                input: dn.input
+              })),
+              checkpointMessages: deltaMessages,
+              pendingToolCalls: toolCalls.map((tc) => ({
+                id: tc.id,
+                name: exposedToolNames.get(tc.name) ?? tc.name,
+                input: tc.input
+              }))
+            });
+            return;
+          }
           const batchStart = now();
           if (isCancelled()) {
             yield emitCancellation();
@@ -11193,7 +11324,8 @@ ${textContent}` };
               const currentFingerprint = `${this.agentFileFingerprint}
 ${this.skillFingerprint}`;
               if (currentFingerprint !== lastPromptFingerprint) {
-                systemPrompt = await buildSystemPrompt();
+                ({ staticPart: staticSystemPart, dynamicPart: dynamicSystemPart } = await buildSystemPromptParts());
+                systemPrompt = `${staticSystemPart}${dynamicSystemPart}`;
                 lastPromptFingerprint = currentFingerprint;
               }
             }
@@ -11970,7 +12102,8 @@ var buildApprovalCheckpoints = ({
   runId,
   checkpointMessages,
   baseMessageCount,
-  pendingToolCalls
+  pendingToolCalls,
+  kind = "approval"
 }) => approvals.map((approval) => ({
   approvalId: approval.approvalId,
   runId,
@@ -11979,7 +12112,8 @@ var buildApprovalCheckpoints = ({
   input: approval.input,
   checkpointMessages,
   baseMessageCount,
-  pendingToolCalls
+  pendingToolCalls,
+  kind
 }));
 var applyTurnMetadata = (conv, meta, opts = {}) => {
   const {
@@ -13268,6 +13402,48 @@ ${resultBody}`,
           }
         }
         return results;
+      },
+      getTranscript: async (opts) => {
+        const conversation = await this.conversationStore.get(opts.subagentId);
+        if (!conversation) {
+          throw new Error(`Subagent "${opts.subagentId}" not found.`);
+        }
+        if (!conversation.parentConversationId) {
+          throw new Error(`Conversation "${opts.subagentId}" is not a subagent.`);
+        }
+        if (conversation.parentConversationId !== opts.parentConversationId) {
+          throw new Error(`Subagent "${opts.subagentId}" was not spawned by this conversation.`);
+        }
+        const all = conversation.messages;
+        let filtered;
+        if (opts.mode === "final") {
+          let lastAssistant;
+          for (let i = all.length - 1; i >= 0; i--) {
+            if (all[i].role === "assistant") {
+              lastAssistant = all[i];
+              break;
+            }
+          }
+          filtered = lastAssistant ? [lastAssistant] : [];
+        } else if (opts.mode === "assistant") {
+          filtered = all.filter((m) => m.role === "assistant");
+        } else {
+          filtered = all;
+        }
+        const startIndex = Math.max(0, opts.sinceIndex ?? 0);
+        const sliced = filtered.slice(startIndex);
+        const cap = opts.maxMessages !== void 0 && opts.maxMessages >= 0 ? opts.maxMessages : sliced.length;
+        const messages = sliced.slice(0, cap);
+        const truncated = startIndex + messages.length < filtered.length;
+        return {
+          subagentId: conversation.conversationId,
+          task: conversation.subagentMeta?.task ?? conversation.title,
+          status: conversation.subagentMeta?.status ?? "stopped",
+          totalMessages: filtered.length,
+          startIndex,
+          messages,
+          truncated
+        };
       }
     };
   }
@@ -13418,7 +13594,8 @@ var runConversationTurn = async (opts) => {
         ),
         messages: harnessMessages,
         files: opts.files && opts.files.length > 0 ? opts.files : void 0,
-        abortSignal: opts.abortSignal
+        abortSignal: opts.abortSignal,
+        disablePromptCache: opts.disablePromptCache
       },
       initialContextTokens: conversation.contextTokens ?? 0,
       initialContextWindow: conversation.contextWindow ?? 0,
@@ -13467,7 +13644,33 @@ var runConversationTurn = async (opts) => {
                 input: event.input ?? {},
                 checkpointMessages: void 0,
                 baseMessageCount: historyMessages.length,
-                pendingToolCalls: []
+                pendingToolCalls: [],
+                kind: "approval"
+              }
+            ];
+            conversation.updatedAt = Date.now();
+            await opts.conversationStore.update(conversation);
+          }
+          await persistDraft();
+        }
+        if (event.type === "tool:device:required") {
+          const toolText = `- device dispatch \`${event.tool}\``;
+          draft.toolTimeline.push(toolText);
+          draft.currentTools.push(toolText);
+          const existing = Array.isArray(conversation.pendingApprovals) ? conversation.pendingApprovals : [];
+          if (!existing.some((a) => a.approvalId === event.requestId)) {
+            conversation.pendingApprovals = [
+              ...existing,
+              {
+                approvalId: event.requestId,
+                runId: latestRunId || conversation.runtimeRunId || "",
+                tool: event.tool,
+                toolCallId: void 0,
+                input: event.input ?? {},
+                checkpointMessages: void 0,
+                baseMessageCount: historyMessages.length,
+                pendingToolCalls: [],
+                kind: "device"
               }
             ];
             conversation.updatedAt = Date.now();
@@ -13482,7 +13685,25 @@ var runConversationTurn = async (opts) => {
             runId: latestRunId,
             checkpointMessages: event.checkpointMessages,
             baseMessageCount: historyMessages.length,
-            pendingToolCalls: event.pendingToolCalls
+            pendingToolCalls: event.pendingToolCalls,
+            kind: "approval"
+          });
+          conversation._toolResultArchive = opts.harness.getToolResultArchive(
+            opts.conversationId
+          );
+          conversation.updatedAt = Date.now();
+          await opts.conversationStore.update(conversation);
+          checkpointedRun = true;
+        }
+        if (event.type === "tool:device:checkpoint") {
+          conversation.messages = buildMessages();
+          conversation.pendingApprovals = buildApprovalCheckpoints({
+            approvals: event.approvals,
+            runId: latestRunId,
+            checkpointMessages: event.checkpointMessages,
+            baseMessageCount: historyMessages.length,
+            pendingToolCalls: event.pendingToolCalls,
+            kind: "device"
           });
           conversation._toolResultArchive = opts.harness.getToolResultArchive(
             opts.conversationId
@@ -13716,6 +13937,7 @@ export {
   normalizeApprovalCheckpoint,
   normalizeOtlp,
   normalizeScriptPolicyPath,
+  normalizeToolAccess,
   parseAgentFile,
   parseAgentMarkdown,
   parseSkillFrontmatter,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.44.0",
+  "version": "0.46.0",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",
@@ -34,7 +34,7 @@
     "mustache": "^4.2.0",
     "yaml": "^2.4.0",
     "zod": "^3.22.0",
-    "@poncho-ai/sdk": "1.10.0"
+    "@poncho-ai/sdk": "1.12.0"
   },
   "peerDependencies": {
     "esbuild": ">=0.17.0",

package/src/config.ts

@@ -37,7 +37,26 @@ export interface UploadsConfig {
   endpoint?: string;
 }
 
-export type ToolAccess = boolean | "approval";
+export type ToolAccess =
+  | boolean
+  | "approval"
+  | { access?: "approval"; dispatch?: "device" };
+
+/**
+ * Normalize any ToolAccess value into a {access, dispatch} struct.
+ * `boolean` collapses to no special handling — the boolean only encodes
+ * enable/disable, not dispatch — callers gate behavior on `dispatch` and
+ * `access`.
+ */
+export const normalizeToolAccess = (
+  value: ToolAccess | undefined,
+): { access?: "approval"; dispatch?: "device" } => {
+  if (value === "approval") return { access: "approval" };
+  if (value && typeof value === "object") {
+    return { access: value.access, dispatch: value.dispatch };
+  }
+  return {};
+};
 
 /** @deprecated Use flat tool keys on `tools` instead. Kept for backward compat. */
 export type BuiltInToolToggles = {

package/src/harness.ts

@@ -38,7 +38,7 @@ import { createEditFileTool } from "./vfs/edit-file-tool.js";
 import { createWriteFileTool } from "./vfs/write-file-tool.js";
 import { PonchoFsAdapter } from "./vfs/poncho-fs-adapter.js";
 import { parseAgentFile, parseAgentMarkdown, renderAgentPrompt, type ParsedAgent, type AgentFrontmatter } from "./agent-parser.js";
-import { loadPonchoConfig, resolveMemoryConfig, resolveStateConfig, type PonchoConfig, type ToolAccess, type BuiltInToolToggles } from "./config.js";
+import { loadPonchoConfig, normalizeToolAccess, resolveMemoryConfig, resolveStateConfig, type PonchoConfig, type ToolAccess, type BuiltInToolToggles } from "./config.js";
 import { ponchoDocsTool } from "./default-tools.js";
 import {
   createMemoryStore,
@@ -59,7 +59,7 @@ import {
   mergeSkills,
 } from "./skill-context.js";
 import { generateText, streamText, type ModelMessage } from "ai";
-import { addPromptCacheBreakpoints } from "./prompt-cache.js";
+import { addPromptCacheBreakpoints, isAnthropicModel } from "./prompt-cache.js";
 import { jsonSchemaToZod } from "./schema-converter.js";
 import type { SkillMetadata } from "./skill-context.js";
 import { createSkillTools, normalizeScriptPolicyPath } from "./skill-tools.js";
@@ -878,7 +878,17 @@ export class AgentHarness {
     if (envOverride !== undefined) return envOverride;
 
     const flatValue = tools[toolName];
-    if (typeof flatValue === "boolean" || flatValue === "approval") return flatValue;
+    if (
+      typeof flatValue === "boolean" ||
+      flatValue === "approval" ||
+      (flatValue !== null && typeof flatValue === "object" && !Array.isArray(flatValue) &&
+        // distinguish a ToolAccess object from the nested `defaults` /
+        // `byEnvironment` sibling fields by checking it has only the
+        // expected ToolAccess keys.
+        Object.keys(flatValue as object).every((k) => k === "access" || k === "dispatch"))
+    ) {
+      return flatValue as ToolAccess;
+    }
 
     const legacyValue = tools.defaults?.[toolName as keyof BuiltInToolToggles];
     if (legacyValue !== undefined) return legacyValue;
@@ -886,6 +896,11 @@ export class AgentHarness {
     return true;
   }
 
+  /** Returns the normalized {access, dispatch} mode for the tool. */
+  private resolveToolMode(toolName: string): { access?: "approval"; dispatch?: "device" } {
+    return normalizeToolAccess(this.resolveToolAccess(toolName));
+  }
+
   private isToolEnabled(name: string): boolean {
     const access = this.resolveToolAccess(name);
     if (access === false) return false;
@@ -1470,7 +1485,7 @@ export class AgentHarness {
     toolName: string,
     input: Record<string, unknown>,
   ): boolean {
-    if (this.resolveToolAccess(toolName) === "approval") {
+    if (this.resolveToolMode(toolName).access === "approval") {
       return true;
     }
     if (toolName === "run_skill_script") {
@@ -2089,10 +2104,17 @@ export class AgentHarness {
       );
     }
     const hasFullToolResults = hasUntruncatedToolResults(messages);
-    if (hasFullToolResults) {
-      costLog.debug(`cache breakpoint before untruncated tool results (run=${runId.slice(0, 12)})`);
+    // The 5-min tail breakpoint is skipped only when the caller explicitly
+    // declares no follow-up is coming (jobs, programmatic one-shots). The
+    // 1-hour static breakpoint on the system prompt is always on — it
+    // amortizes across every later turn or job within the hour.
+    const skipTailCache = input.disablePromptCache === true;
+    if (skipTailCache) {
+      costLog.debug(`tail cache breakpoint skipped — disablePromptCache (run=${runId.slice(0, 12)})`);
+    } else if (hasFullToolResults) {
+      costLog.debug(`tail cache breakpoint before untruncated tool results (run=${runId.slice(0, 12)})`);
     } else {
-      costLog.debug(`cache breakpoint at history tail (run=${runId.slice(0, 12)})`);
+      costLog.debug(`tail cache breakpoint at history tail (run=${runId.slice(0, 12)})`);
     }
     const inputMessageCount = messages.length;
     const events: AgentEvent[] = [];
@@ -2195,11 +2217,17 @@ ${typeStubs}
 Code is wrapped in an async IIFE — use \`return\` to return a value to the tool result.`;
     }
 
-    const buildSystemPrompt = async (): Promise<string> => {
+    // Split the system prompt into a static portion (stable across turns
+    // and jobs within an hour, modulo MCP connect/skill author/memory edit)
+    // and a dynamic tail (memory, todos, time). The static portion gets a
+    // 1-hour Anthropic cache breakpoint downstream; the tail rides the
+    // existing 5-min message-level breakpoint. See the streamText site for
+    // the breakpoint wiring.
+    const buildSystemPromptParts = async (): Promise<{ staticPart: string; dynamicPart: string }> => {
       const agentPrompt = renderCurrentAgentPrompt();
       const tenantSkills = await this.getSkillsForTenant(input.tenantId);
       const skillContextWindow = buildSkillContextWindow(tenantSkills);
-      const promptWithSkills = skillContextWindow
+      const staticPart = skillContextWindow
         ? `${agentPrompt}${developmentContext}\n\n${skillContextWindow}${browserContext}${fsContext}${isolateContext}`
         : `${agentPrompt}${developmentContext}${browserContext}${fsContext}${isolateContext}`;
       // Quantize to the hour so the system prompt is stable across runs
@@ -2215,9 +2243,13 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
       const timeContext = this.reminderStore
         ? `\n\nCurrent UTC time (hour precision): ${hourlyTime}`
         : "";
-      return `${promptWithSkills}${memoryContext}${todoContext}${timeContext}`;
+      const dynamicPart = `${memoryContext}${todoContext}${timeContext}`;
+      return { staticPart, dynamicPart };
     };
-    let systemPrompt = await buildSystemPrompt();
+    let { staticPart: staticSystemPart, dynamicPart: dynamicSystemPart } =
+      await buildSystemPromptParts();
+    // Concatenated form for legacy consumers (token estimation, telemetry).
+    let systemPrompt = `${staticSystemPart}${dynamicSystemPart}`;
     let lastPromptFingerprint = `${this.agentFileFingerprint}\n${this.skillFingerprint}`;
 
     const pushEvent = (event: AgentEvent): AgentEvent => {
@@ -2757,25 +2789,55 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
 
         const temperature = agent.frontmatter.model?.temperature ?? 0.2;
         const maxTokens = agent.frontmatter.model?.maxTokens;
-        // Place the breakpoint before any untruncated tool-result so we
-        // cache only the stable prefix when prior-run tool results are
-        // still full-fidelity. Otherwise cache at the history tail.
-        const breakpointIndex = hasFullToolResults
-          ? findLastStableCacheIndex(coreMessages)
-          : coreMessages.length - 1;
-        const cachedMessages = addPromptCacheBreakpoints(
-          coreMessages,
-          modelInstance,
-          breakpointIndex,
-        );
+        // Place the tail breakpoint before any untruncated tool-result so
+        // we cache only the stable prefix when prior-run tool results are
+        // still full-fidelity. Otherwise cache at the history tail. When
+        // `skipTailCache` is set (per-run override), don't write the tail
+        // breakpoint at all. The 1-hour static-prefix breakpoint is added
+        // separately when assembling the final messages array.
+        const cachedMessages = skipTailCache
+          ? coreMessages
+          : addPromptCacheBreakpoints(
+              coreMessages,
+              modelInstance,
+              hasFullToolResults
+                ? findLastStableCacheIndex(coreMessages)
+                : coreMessages.length - 1,
+            );
+
+        // Anthropic: split system into two blocks with a 1-hour cache
+        // breakpoint at the boundary between the static portion (agent
+        // body + skills + browser/fs/isolate context — stable across many
+        // turns and jobs) and the dynamic tail (memory, todos, time).
+        // The static block becomes a hot cache that every later turn and
+        // job in the hour reads at 0.1× — much bigger payoff than the
+        // 5-min tail breakpoint, which only survives active back-and-forth.
+        // For non-Anthropic models, fall back to the single concatenated
+        // string via `system:` — those providers auto-cache.
+        const useStaticCache = isAnthropicModel(modelInstance);
+        const finalMessages: ModelMessage[] = useStaticCache
+          ? [
+              {
+                role: "system",
+                content: staticSystemPart,
+                providerOptions: {
+                  anthropic: { cacheControl: { type: "ephemeral", ttl: "1h" } },
+                },
+              },
+              ...(dynamicSystemPart.length > 0
+                ? [{ role: "system" as const, content: dynamicSystemPart }]
+                : []),
+              ...cachedMessages,
+            ]
+          : cachedMessages;
 
         const telemetryEnabled = this.loadedConfig?.telemetry?.enabled !== false;
 
 
         const result = await streamText({
           model: modelInstance,
-          system: systemPrompt,
-          messages: cachedMessages,
+          ...(useStaticCache ? {} : { system: systemPrompt }),
+          messages: finalMessages,
           tools,
           temperature,
           abortSignal: input.abortSignal,
@@ -3119,8 +3181,19 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
         name: string;
         input: Record<string, unknown>;
       }> = [];
+      const deviceNeeded: Array<{
+        approvalId: string;
+        id: string;
+        name: string;
+        input: Record<string, unknown>;
+      }> = [];
 
-      // Phase 1: classify all tool calls
+      // Phase 1: classify all tool calls.
+      // Approval gates run first; device dispatch fires only after approval is
+      // cleared. On a device+approval tool the first dispatch pass yields the
+      // approval, and the post-resume pass (where access is no longer required
+      // because the message stream has the approve decision baked in) sees
+      // dispatch="device" still set and falls into deviceNeeded below.
       for (const call of toolCalls) {
         if (isCancelled()) {
           yield emitCancellation();
@@ -3135,6 +3208,13 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
             name: runtimeToolName,
             input: call.input,
           });
+        } else if (this.resolveToolMode(runtimeToolName).dispatch === "device") {
+          deviceNeeded.push({
+            approvalId: `device_${randomUUID()}`,
+            id: call.id,
+            name: runtimeToolName,
+            input: call.input,
+          });
         } else {
           approvedCalls.push({
             id: call.id,
@@ -3187,6 +3267,52 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
         return;
       }
 
+      // Phase 2a': if any tools must dispatch to a connected device, emit
+      // tool:device:required events for each and checkpoint with kind="device".
+      // Consumers (e.g. PonchOS) route the events to the right WS and POST
+      // the resulting tool output back through resumeRunFromCheckpoint.
+      if (deviceNeeded.length > 0) {
+        for (const dn of deviceNeeded) {
+          yield pushEvent({
+            type: "tool:device:required",
+            tool: dn.name,
+            input: dn.input,
+            requestId: dn.approvalId,
+          });
+        }
+
+        const assistantContent = JSON.stringify({
+          text: fullText,
+          tool_calls: toolCalls.map(tc => ({
+            id: tc.id,
+            name: exposedToolNames.get(tc.name) ?? tc.name,
+            input: tc.input,
+          })),
+        });
+        const assistantMsg: Message = {
+          role: "assistant",
+          content: assistantContent,
+          metadata: { timestamp: now(), id: randomUUID(), step, runId },
+        };
+        const deltaMessages = [...messages.slice(inputMessageCount), assistantMsg];
+        yield pushEvent({
+          type: "tool:device:checkpoint",
+          approvals: deviceNeeded.map(dn => ({
+            approvalId: dn.approvalId,
+            tool: dn.name,
+            toolCallId: dn.id,
+            input: dn.input,
+          })),
+          checkpointMessages: deltaMessages,
+          pendingToolCalls: toolCalls.map(tc => ({
+            id: tc.id,
+            name: exposedToolNames.get(tc.name) ?? tc.name,
+            input: tc.input,
+          })),
+        });
+        return;
+      }
+
       // Phase 2b: no approvals needed — execute all auto-approved calls
       const batchStart = now();
       if (isCancelled()) {
@@ -3453,7 +3579,9 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
             agent = this.parsedAgent as ParsedAgent;
             const currentFingerprint = `${this.agentFileFingerprint}\n${this.skillFingerprint}`;
             if (currentFingerprint !== lastPromptFingerprint) {
-              systemPrompt = await buildSystemPrompt();
+              ({ staticPart: staticSystemPart, dynamicPart: dynamicSystemPart } =
+                await buildSystemPromptParts());
+              systemPrompt = `${staticSystemPart}${dynamicSystemPart}`;
               lastPromptFingerprint = currentFingerprint;
             }
           }

package/src/index.ts

@@ -21,7 +21,7 @@ export * from "./telemetry.js";
 export * from "./secrets-store.js";
 export * from "./storage/index.js";
 export * from "./storage/store-adapters.js";
-export { PonchoFsAdapter } from "./vfs/poncho-fs-adapter.js";
+export { PonchoFsAdapter, type VirtualMount } from "./vfs/poncho-fs-adapter.js";
 export { BashEnvironmentManager } from "./vfs/bash-manager.js";
 export { createBashTool } from "./vfs/bash-tool.js";
 export * from "./tenant-token.js";

package/src/orchestrator/orchestrator.ts

@@ -1511,6 +1511,52 @@ export class AgentOrchestrator {
         }
         return results;
       },
+
+      getTranscript: async (opts) => {
+        const conversation = await this.conversationStore.get(opts.subagentId);
+        if (!conversation) {
+          throw new Error(`Subagent "${opts.subagentId}" not found.`);
+        }
+        if (!conversation.parentConversationId) {
+          throw new Error(`Conversation "${opts.subagentId}" is not a subagent.`);
+        }
+        if (conversation.parentConversationId !== opts.parentConversationId) {
+          throw new Error(`Subagent "${opts.subagentId}" was not spawned by this conversation.`);
+        }
+
+        const all = conversation.messages;
+        let filtered: Message[];
+        if (opts.mode === "final") {
+          let lastAssistant: Message | undefined;
+          for (let i = all.length - 1; i >= 0; i--) {
+            if (all[i]!.role === "assistant") {
+              lastAssistant = all[i];
+              break;
+            }
+          }
+          filtered = lastAssistant ? [lastAssistant] : [];
+        } else if (opts.mode === "assistant") {
+          filtered = all.filter((m) => m.role === "assistant");
+        } else {
+          filtered = all;
+        }
+
+        const startIndex = Math.max(0, opts.sinceIndex ?? 0);
+        const sliced = filtered.slice(startIndex);
+        const cap = opts.maxMessages !== undefined && opts.maxMessages >= 0 ? opts.maxMessages : sliced.length;
+        const messages = sliced.slice(0, cap);
+        const truncated = startIndex + messages.length < filtered.length;
+
+        return {
+          subagentId: conversation.conversationId,
+          task: conversation.subagentMeta?.task ?? conversation.title,
+          status: conversation.subagentMeta?.status ?? "stopped",
+          totalMessages: filtered.length,
+          startIndex,
+          messages,
+          truncated,
+        };
+      },
     };
   }
 

package/src/orchestrator/run-conversation-turn.ts

@@ -62,6 +62,12 @@ export interface RunConversationTurnOpts {
   parameters?: Record<string, unknown>;
   abortSignal?: AbortSignal;
   tenantId?: string | null;
+  /**
+   * Forwarded to `RunInput.disablePromptCache`. Set true for one-shot
+   * turns with no follow-up coming (cron-fired jobs, etc.) so the
+   * harness skips the Anthropic cache write.
+   */
+  disablePromptCache?: boolean;
   /** Per-event hook — called for every AgentEvent yielded by the run, in order. */
   onEvent?: (event: AgentEvent) => void | Promise<void>;
 }
@@ -203,6 +209,7 @@ export const runConversationTurn = async (
         messages: harnessMessages,
         files: opts.files && opts.files.length > 0 ? opts.files : undefined,
         abortSignal: opts.abortSignal,
+        disablePromptCache: opts.disablePromptCache,
       },
       initialContextTokens: conversation.contextTokens ?? 0,
       initialContextWindow: conversation.contextWindow ?? 0,
@@ -257,6 +264,34 @@ export const runConversationTurn = async (
                 checkpointMessages: undefined,
                 baseMessageCount: historyMessages.length,
                 pendingToolCalls: [],
+                kind: "approval",
+              },
+            ];
+            conversation.updatedAt = Date.now();
+            await opts.conversationStore.update(conversation);
+          }
+          await persistDraft();
+        }
+        if (event.type === "tool:device:required") {
+          const toolText = `- device dispatch \`${event.tool}\``;
+          draft.toolTimeline.push(toolText);
+          draft.currentTools.push(toolText);
+          const existing = Array.isArray(conversation.pendingApprovals)
+            ? conversation.pendingApprovals
+            : [];
+          if (!existing.some((a) => a.approvalId === event.requestId)) {
+            conversation.pendingApprovals = [
+              ...existing,
+              {
+                approvalId: event.requestId,
+                runId: latestRunId || conversation.runtimeRunId || "",
+                tool: event.tool,
+                toolCallId: undefined,
+                input: (event.input ?? {}) as Record<string, unknown>,
+                checkpointMessages: undefined,
+                baseMessageCount: historyMessages.length,
+                pendingToolCalls: [],
+                kind: "device",
               },
             ];
             conversation.updatedAt = Date.now();
@@ -272,6 +307,24 @@ export const runConversationTurn = async (
             checkpointMessages: event.checkpointMessages,
             baseMessageCount: historyMessages.length,
             pendingToolCalls: event.pendingToolCalls,
+            kind: "approval",
+          });
+          conversation._toolResultArchive = opts.harness.getToolResultArchive(
+            opts.conversationId,
+          );
+          conversation.updatedAt = Date.now();
+          await opts.conversationStore.update(conversation);
+          checkpointedRun = true;
+        }
+        if (event.type === "tool:device:checkpoint") {
+          conversation.messages = buildMessages();
+          conversation.pendingApprovals = buildApprovalCheckpoints({
+            approvals: event.approvals,
+            runId: latestRunId,
+            checkpointMessages: event.checkpointMessages,
+            baseMessageCount: historyMessages.length,
+            pendingToolCalls: event.pendingToolCalls,
+            kind: "device",
           });
           conversation._toolResultArchive = opts.harness.getToolResultArchive(
             opts.conversationId,

package/src/orchestrator/turn.ts

@@ -304,12 +304,14 @@ export const buildApprovalCheckpoints = ({
   checkpointMessages,
   baseMessageCount,
   pendingToolCalls,
+  kind = "approval",
 }: {
   approvals: ApprovalEventItem[];
   runId: string;
   checkpointMessages: Message[];
   baseMessageCount: number;
   pendingToolCalls: PendingToolCall[];
+  kind?: "approval" | "device";
 }): NonNullable<Conversation["pendingApprovals"]> =>
   approvals.map((approval) => ({
     approvalId: approval.approvalId,
@@ -320,6 +322,7 @@ export const buildApprovalCheckpoints = ({
     checkpointMessages,
     baseMessageCount,
     pendingToolCalls,
+    kind,
   }));
 
 // ── Turn metadata persistence ──

package/src/prompt-cache.ts

@@ -1,6 +1,6 @@
 import type { ModelMessage, LanguageModel } from "ai";
 
-function isAnthropicModel(model: LanguageModel): boolean {
+export function isAnthropicModel(model: LanguageModel): boolean {
   if (typeof model === "string") {
     return model.includes("anthropic") || model.includes("claude");
   }

package/src/state.ts

@@ -47,6 +47,15 @@ export interface Conversation {
     baseMessageCount?: number;
     pendingToolCalls?: Array<{ id: string; name: string; input: Record<string, unknown> }>;
     decision?: "approved" | "denied";
+    /**
+     * Checkpoint kind discriminator.
+     * - "approval" (default for legacy rows): user approve/deny gate.
+     * - "device":   tool executes on a connected client device (e.g. iOS); the
+     *               consumer of the harness POSTs a tool result back to resume.
+     * Treat `undefined` as "approval" for backward compatibility with rows
+     * persisted before this field existed.
+     */
+    kind?: "approval" | "device";
   }>;
   runStatus?: "running" | "idle";
   ownerId: string;

package/src/subagent-manager.ts

@@ -19,6 +19,18 @@ export interface SubagentSpawnResult {
   subagentId: string;
 }
 
+export type SubagentTranscriptMode = "final" | "assistant" | "full";
+
+export interface SubagentTranscript {
+  subagentId: string;
+  task: string;
+  status: string;
+  totalMessages: number;
+  startIndex: number;
+  messages: Message[];
+  truncated: boolean;
+}
+
 export interface SubagentManager {
   spawn(opts: {
     task: string;
@@ -32,4 +44,12 @@ export interface SubagentManager {
   stop(subagentId: string): Promise<void>;
 
   list(parentConversationId: string): Promise<SubagentSummary[]>;
+
+  getTranscript(opts: {
+    subagentId: string;
+    parentConversationId: string;
+    mode: SubagentTranscriptMode;
+    sinceIndex?: number;
+    maxMessages?: number;
+  }): Promise<SubagentTranscript>;
 }

package/src/subagent-tools.ts

@@ -131,4 +131,66 @@ export const createSubagentTools = (
       return { subagents };
     },
   }),
+
+  defineTool({
+    name: "read_subagent",
+    description:
+      "Fetch the conversation transcript of a subagent you spawned. Use this to inspect a " +
+      "subagent's intermediate reasoning, tool calls, or full output -- instead of asking it " +
+      "to repeat its work via message_subagent.\n\n" +
+      "Modes:\n" +
+      "- 'final' (default): just the last assistant message. Cheap.\n" +
+      "- 'assistant': all assistant messages, no tool calls/results.\n" +
+      "- 'full': every message including tool calls and results. Can be large.\n\n" +
+      "Use since_index / max_messages to page through long transcripts. Only works on " +
+      "subagents directly spawned by this conversation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        subagent_id: {
+          type: "string",
+          description: "The subagent ID (from spawn_subagent or list_subagents).",
+        },
+        mode: {
+          type: "string",
+          enum: ["final", "assistant", "full"],
+          description: "How much of the transcript to return. Defaults to 'final'.",
+        },
+        since_index: {
+          type: "number",
+          description: "Skip messages before this index (applied after mode filter).",
+        },
+        max_messages: {
+          type: "number",
+          description: "Cap the number of messages returned.",
+        },
+      },
+      required: ["subagent_id"],
+      additionalProperties: false,
+    },
+    handler: async (input: Record<string, unknown>, context: ToolContext) => {
+      const subagentId = typeof input.subagent_id === "string" ? input.subagent_id : "";
+      if (!subagentId) {
+        return { error: "subagent_id is required" };
+      }
+      const parentConversationId = context.conversationId;
+      if (!parentConversationId) {
+        return { error: "no active conversation" };
+      }
+      const rawMode = typeof input.mode === "string" ? input.mode : "final";
+      const mode: "final" | "assistant" | "full" =
+        rawMode === "assistant" || rawMode === "full" ? rawMode : "final";
+      try {
+        return await manager.getTranscript({
+          subagentId,
+          parentConversationId,
+          mode,
+          sinceIndex: typeof input.since_index === "number" ? input.since_index : undefined,
+          maxMessages: typeof input.max_messages === "number" ? input.max_messages : undefined,
+        });
+      } catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+      }
+    },
+  }),
 ];