@poncho-ai/harness 0.44.0 → 0.45.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.45.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/isolate-VY35DGLM.js 49.43 KB
-ESM ⚡️ Build success in 209ms
+ESM dist/index.js            524.35 KB
+ESM ⚡️ Build success in 230ms
 DTS Build start
-DTS ⚡️ Build success in 6795ms
-DTS dist/index.d.ts 83.51 KB
+DTS ⚡️ Build success in 7575ms
+DTS dist/index.d.ts 85.07 KB

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @poncho-ai/harness
 
+## 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;
@@ -2013,4 +2055,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") {
@@ -10895,6 +10962,7 @@ ${textContent}` };
           const richToolResults = [];
           const approvedCalls = [];
           const approvalNeeded = [];
+          const deviceNeeded = [];
           for (const call of toolCalls) {
             if (isCancelled()) {
               yield emitCancellation();
@@ -10909,6 +10977,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 +11032,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();
@@ -11970,7 +12085,8 @@ var buildApprovalCheckpoints = ({
   runId,
   checkpointMessages,
   baseMessageCount,
-  pendingToolCalls
+  pendingToolCalls,
+  kind = "approval"
 }) => approvals.map((approval) => ({
   approvalId: approval.approvalId,
   runId,
@@ -11979,7 +12095,8 @@ var buildApprovalCheckpoints = ({
   input: approval.input,
   checkpointMessages,
   baseMessageCount,
-  pendingToolCalls
+  pendingToolCalls,
+  kind
 }));
 var applyTurnMetadata = (conv, meta, opts = {}) => {
   const {
@@ -13268,6 +13385,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
+        };
       }
     };
   }
@@ -13467,7 +13626,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 +13667,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 +13919,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.45.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.11.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,
@@ -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") {
@@ -3119,8 +3134,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 +3161,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 +3220,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()) {

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

@@ -257,6 +257,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 +300,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/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) };
+      }
+    },
+  }),
 ];