@tt-a1i/openpi 0.6.0 → 0.7.0

package/extensions/workflows/index.ts

@@ -53,7 +53,11 @@ import {
   formatActivityStatus,
 } from "../shared/activity-status.ts";
 import { fitNavigationSides } from "../shared/below-editor-navigation.ts";
-import { waitBounded } from "../shared/child-session.ts";
+import {
+  inheritedChildToolAllowlist,
+  resolveStandaloneChildProjectTrust,
+  waitBounded,
+} from "../shared/child-session.ts";
 import { contextPercent } from "../shared/context-utilization.ts";
 import { completionOwnerFor } from "../shared/completion-inbox.ts";
 import {
@@ -544,6 +548,7 @@ interface ScriptAgentResult {
 }
 
 interface AgentCallOptions {
+  working_dir?: unknown;
   agent_type?: unknown;
   label?: unknown;
   phase?: unknown;
@@ -1339,11 +1344,12 @@ export default function workflows(
         structured: boolean,
         cwd: string,
         agentTypePrompt?: string,
+        childProjectTrusted = projectTrusted,
       ) =>
         createWorkflowResources(
           cwd,
           structured ? "structured" : "plain",
-          projectTrusted,
+          childProjectTrusted,
           agentTypePrompt,
         );
 
@@ -1638,6 +1644,36 @@ export default function workflows(
           );
         }
 
+        const childTools = inheritedChildToolAllowlist(
+          pi.getActiveTools(),
+          agentType?.tools,
+        );
+        if (
+          opts.working_dir !== undefined &&
+          (typeof opts.working_dir !== "string" || !opts.working_dir.trim())
+        ) {
+          return fail(
+            `agent "${label}": working_dir must be a non-empty string`,
+          );
+        }
+        const requestedCwd = path.resolve(
+          ctx.cwd,
+          typeof opts.working_dir === "string" ? opts.working_dir : ".",
+        );
+        try {
+          if (!fs.statSync(requestedCwd).isDirectory())
+            throw new Error("not a directory");
+        } catch {
+          return fail(
+            `agent "${label}": working_dir is not a directory: ${requestedCwd}`,
+          );
+        }
+        const childProjectTrusted = resolveStandaloneChildProjectTrust({
+          parentCwd: ctx.cwd,
+          childCwd: requestedCwd,
+          parentTrusted: projectTrusted,
+        });
+
         const explicitModel =
           typeof opts.model === "string" && opts.model.trim()
             ? opts.model.trim()
@@ -1708,11 +1744,14 @@ export default function workflows(
         const operatorFingerprint = operatorKey
           ? agentCallKey("workflow-operator", {
               execution: {
+                cwd: requestedCwd,
+                projectTrusted: childProjectTrusted,
+                tools: childTools,
                 agentType: agentType
                   ? {
                       name: agentType.name,
                       body: agentType.body,
-                      tools: agentType.tools,
+                      tools: childTools,
                     }
                   : undefined,
                 model: model ? `${model.provider}/${model.id}` : undefined,
@@ -1732,7 +1771,7 @@ export default function workflows(
         const replaySafe =
           operatorKey === undefined &&
           isReplaySafeAgentCall({
-            tools: agentType?.tools,
+            tools: agentType?.tools === undefined ? undefined : childTools,
             isolation: opts.isolation,
           });
         const replayLease = beginProcessReplayWorkspaceLease(replaySafe);
@@ -1744,13 +1783,14 @@ export default function workflows(
           try {
             replayResources = await getResources(
               effectiveSchema !== undefined,
-              ctx.cwd,
+              requestedCwd,
               agentType?.body,
+              childProjectTrusted,
             );
             replayIdentity = createReplayIdentity(
-              ctx.cwd,
+              requestedCwd,
               replayResources.loader,
-              projectTrusted,
+              childProjectTrusted,
             );
           } catch {
             // Fingerprinting is an optimization boundary. If resources cannot
@@ -1768,7 +1808,7 @@ export default function workflows(
                 ? {
                     name: agentType.name,
                     body: agentType.body,
-                    tools: agentType.tools,
+                    tools: childTools,
                   }
                 : undefined,
               model: model ? `${model.provider}/${model.id}` : undefined,
@@ -1925,7 +1965,7 @@ export default function workflows(
                 );
               }
               const created = await createWorktree({
-                cwd: ctx.cwd,
+                cwd: requestedCwd,
                 label,
                 id: `${details.runId}-${record.index}`,
               });
@@ -1937,18 +1977,19 @@ export default function workflows(
               worktree = created.worktree;
               if (!runSettled) record.worktreeBranch = worktree.branch;
             }
-            if (runSignal.aborted || runSettled) {
-              throw runSignal.reason instanceof Error
-                ? runSignal.reason
-                : new Error("Workflow was aborted");
-            }
-            const agentCwd = worktree?.path ?? ctx.cwd;
+            const agentCwd = worktree?.path ?? requestedCwd;
 
             // Inside the try, not before it: building resources can throw
             // (bad settings, an unreadable skills dir), and a throw out here
             // would skip the finally and leak the worktree permanently —
             // nothing sweeps `.git/pi-worktrees/` afterwards.
             try {
+              if (runSignal.aborted || runSettled) {
+                throw runSignal.reason instanceof Error
+                  ? runSignal.reason
+                  : new Error("Workflow was aborted");
+              }
+
               let rejectResourceLoad: (() => void) | undefined;
               const resourceAbort = new Promise<never>((_resolve, reject) => {
                 rejectResourceLoad = () =>
@@ -1968,6 +2009,7 @@ export default function workflows(
                     effectiveSchema !== undefined,
                     agentCwd,
                     agentType?.body,
+                    childProjectTrusted,
                   ),
                 resourceAbort,
               ]).finally(() => {
@@ -1992,7 +2034,7 @@ export default function workflows(
                   settingsManager: resources.settingsManager,
                   ...(sessionManager ? { sessionManager } : {}),
                   modelRegistry: ctx.modelRegistry,
-                  ...(agentType?.tools ? { tools: agentType.tools } : {}),
+                  tools: childTools,
                   ...(testAgentSessionFactory
                     ? { sessionFactory: testAgentSessionFactory }
                     : {}),
@@ -2108,9 +2150,9 @@ export default function workflows(
               // unfingerprintable calls always run for real.
               const completedIdentity = callKey
                 ? createReplayIdentity(
-                    ctx.cwd,
+                    requestedCwd,
                     resources.loader,
-                    projectTrusted,
+                    childProjectTrusted,
                   )
                 : undefined;
               const completedKey = completedIdentity
@@ -2157,7 +2199,7 @@ export default function workflows(
                   runId: details.runId,
                   agentIndex: record.index,
                   agentLabel: record.label,
-                  repoCwd: ctx.cwd,
+                  repoCwd: requestedCwd,
                   worktree,
                 });
                 let cleanup: WorktreeCleanup;
@@ -2174,7 +2216,7 @@ export default function workflows(
                   const reclaimer =
                     workflowLifecycleTestHooks?.reclaimWorktree ??
                     reclaimWorktree;
-                  cleanup = await reclaimer(ctx.cwd, worktree).catch(
+                  cleanup = await reclaimer(requestedCwd, worktree).catch(
                     (error): WorktreeCleanup => ({
                       removed: false,
                       branchDeleted: false,

package/extensions/workflows/progress-projection.ts

@@ -250,8 +250,11 @@ export class AgentProgressProjection {
   snapshot(
     toolTimings: ReadonlyMap<string, ProgressToolTiming> = new Map(),
   ): AgentProgressProjectionSnapshot {
+    // Reserve the initial task, then spend the remaining byte budget on the
+    // newest evidence. Forward selection would silently discard final errors
+    // after enough large tool results, even below the entry-count limit.
     const selected = this.firstEntry
-      ? [this.firstEntry, ...this.tailEntries]
+      ? [this.firstEntry, ...this.tailEntries.slice().reverse()]
       : [];
     const transcript: TranscriptEntry[] = [];
     let totalBytes = 0;
@@ -277,6 +280,9 @@ export class AgentProgressProjection {
           : { timestamp: entry.timestamp }),
       });
     }
+    // Budgeting order is not display order: keep the retained tail chronological.
+    const newestFirstTail = transcript.splice(1);
+    transcript.push(...newestFirstTail.reverse());
     if (transcript.length < this.totalEntries) {
       transcript.push({
         role: "toolResult",

package/extensions/workflows/runner.ts

@@ -50,7 +50,6 @@ import { truncateUtf8 } from "./serialization.ts";
 import { bindWorkflowToolRenderer } from "./tool-renderer.ts";
 
 const AGENT_OUTPUT_MAX_BYTES = 64 * 1024;
-export const MODEL_PROGRESS_TIMEOUT_MS = 45_000;
 
 export type WorkflowModel = NonNullable<ExtensionContext["model"]>;
 export type ThinkingLevel = ReturnType<ExtensionAPI["getThinkingLevel"]>;
@@ -111,8 +110,6 @@ export interface RunAgentOptions {
   replayFilesystemBoundary?: ReplayFilesystemBoundaryOptions;
   /** Test-only override for the per-tool execution timeout. */
   toolCallTimeoutMs?: number;
-  /** Test-only override for the per-provider-turn model-progress timeout. */
-  modelProgressTimeoutMs?: number;
   /** Test-only override for the end-to-end abort/shutdown deadline. */
   shutdownTimeoutMs?: number;
   /** Test seam for lifecycle races; production always uses createAgentSession. */
@@ -245,119 +242,6 @@ function errorText(error: unknown): string {
   );
 }
 
-function formatTimeout(timeoutMs: number) {
-  return timeoutMs % 1_000 === 0
-    ? `${timeoutMs / 1_000} seconds`
-    : `${timeoutMs} ms`;
-}
-
-export function resolveModelProgressTimeoutMs(
-  settingsManager: SettingsManager,
-  override?: number,
-) {
-  if (override !== undefined) return override;
-  const configured =
-    settingsManager.getProjectSettings().httpIdleTimeoutMs ??
-    settingsManager.getGlobalSettings().httpIdleTimeoutMs;
-  return typeof configured === "number" && Number.isFinite(configured)
-    ? Math.max(MODEL_PROGRESS_TIMEOUT_MS, Math.floor(configured))
-    : MODEL_PROGRESS_TIMEOUT_MS;
-}
-
-/** Abort any provider turn that stops producing model-visible progress. */
-export function createModelProgressWatchdog(
-  onTimeout: (error: Error) => Promise<unknown>,
-  options: { timeoutMs?: number; model?: string } = {},
-) {
-  const timeoutMs = options.timeoutMs ?? MODEL_PROGRESS_TIMEOUT_MS;
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  let activeTurn = false;
-  let closed = false;
-  let rejectTimeout!: (error: Error) => void;
-  const timeout = new Promise<never>((_resolve, reject) => {
-    rejectTimeout = reject;
-  });
-
-  const clear = () => {
-    if (timer) clearTimeout(timer);
-    timer = undefined;
-  };
-  const schedule = () => {
-    clear();
-    if (!activeTurn || closed) return;
-    // This timer owns the awaited watchdog outcome. Keep it referenced so a
-    // short-lived Node 22 process cannot exit with the promise still pending.
-    timer = setTimeout(() => {
-      timer = undefined;
-      activeTurn = false;
-      closed = true;
-      const model = options.model ? ` for ${options.model}` : "";
-      const error = new Error(
-        `Agent provider turn${model} produced no model-visible progress for ${formatTimeout(timeoutMs)}; the provider request may be stalled. Retry the workflow.`,
-      );
-      rejectTimeout(error);
-      try {
-        void onTimeout(error).catch(() => {});
-      } catch {
-        // The timeout result remains authoritative even if abort throws before
-        // returning its promise; bounded shutdown below gets another chance.
-      }
-    }, timeoutMs);
-  };
-  const armTurn = () => {
-    if (closed) return;
-    activeTurn = true;
-    schedule();
-  };
-  const markProgress = () => {
-    if (!activeTurn || closed) return;
-    schedule();
-  };
-  const completeTurn = () => {
-    activeTurn = false;
-    clear();
-  };
-  const cancel = () => {
-    closed = true;
-    activeTurn = false;
-    clear();
-  };
-
-  return {
-    armTurn,
-    markProgress,
-    completeTurn,
-    cancel,
-    async waitFor<T>(operation: Promise<T>) {
-      try {
-        return await Promise.race([operation, timeout]);
-      } finally {
-        cancel();
-      }
-    },
-  };
-}
-
-function isModelVisibleProgress(event: AgentSessionEvent) {
-  if (event.type !== "message_update" || event.message.role !== "assistant") {
-    return false;
-  }
-  // Raw transport heartbeats never become AgentSession events. Empty stream,
-  // text, and thinking starts likewise cannot keep a provider turn alive.
-  const update = event.assistantMessageEvent;
-  if (
-    update.type === "text_delta" ||
-    update.type === "thinking_delta" ||
-    update.type === "toolcall_delta"
-  ) {
-    return update.delta.length > 0;
-  }
-  if (update.type === "text_end" || update.type === "thinking_end") {
-    return update.content.length > 0;
-  }
-  return update.type === "toolcall_start" || update.type === "toolcall_end";
-}
-
 export async function runAgent(
   options: RunAgentOptions,
 ): Promise<AgentOutcome> {
@@ -367,8 +251,6 @@ export async function runAgent(
   let session: AgentSession | undefined;
   let unsubscribeToolGuards: (() => void) | undefined;
   let aborted = false;
-  let terminalCause: "abort" | "model-progress-timeout" | undefined;
-  let modelProgressTimeoutMessage: string | undefined;
   let abortOperation: Promise<unknown> | undefined;
   let rejectForAbort: ((error: Error) => void) | undefined;
   let rejectForProjectionFailure: ((error: Error) => void) | undefined;
@@ -389,7 +271,6 @@ export async function runAgent(
   const onAbort = () => {
     if (aborted) return;
     aborted = true;
-    terminalCause ??= "abort";
     if (session) {
       try {
         abortOperation ??= session.abort();
@@ -594,10 +475,6 @@ export async function runAgent(
     });
   };
 
-  let armModelProgress = () => {};
-  let markModelProgress = () => {};
-  let completeModelTurn = () => {};
-  let cancelModelProgressWatchdog = () => {};
   let compactionReconcileQueued = false;
   const queueCompactionReconcile = () => {
     if (compactionReconcileQueued) return;
@@ -625,7 +502,6 @@ export async function runAgent(
   };
   const unsubscribe = childSession.subscribe((event) => {
     if (settled) return;
-    if (event.type === "turn_start") armModelProgress();
     if (event.type === "tool_execution_start") {
       toolRenderer.start(
         event.toolCallId,
@@ -648,10 +524,6 @@ export async function runAgent(
         event.isError,
       );
     }
-    if (isModelVisibleProgress(event)) markModelProgress();
-    if (event.type === "message_end" && event.message.role === "assistant") {
-      completeModelTurn();
-    }
     if (event.type === "message_end") {
       assistantSettlement = observeAssistantSettlement(
         assistantSettlement,
@@ -686,32 +558,10 @@ export async function runAgent(
     captureToolRenderData(childSession.messages);
     snapshotProjection();
     if (!aborted) {
-      const watchdog = createModelProgressWatchdog(
-        (error) => {
-          terminalCause ??= "model-progress-timeout";
-          if (terminalCause === "model-progress-timeout") {
-            modelProgressTimeoutMessage ??= error.message;
-          }
-          abortOperation ??= childSession.abort();
-          void abortOperation.catch(() => {});
-          return abortOperation;
-        },
-        {
-          timeoutMs: resolveModelProgressTimeoutMs(
-            options.settingsManager,
-            options.modelProgressTimeoutMs,
-          ),
-          model: modelId,
-        },
-      );
-      armModelProgress = watchdog.armTurn;
-      markModelProgress = watchdog.markProgress;
-      completeModelTurn = watchdog.completeTurn;
-      cancelModelProgressWatchdog = watchdog.cancel;
+      // Pi owns transport liveness and retries. Quiet model output is not
+      // evidence of a stalled request (thinking and retry backoff can be silent).
       await Promise.race([
-        watchdog.waitFor(
-          childSession.prompt(buildWorkflowAgentPrompt(options.prompt)),
-        ),
+        childSession.prompt(buildWorkflowAgentPrompt(options.prompt)),
         abortRace,
         projectionFailureRace,
       ]);
@@ -719,7 +569,6 @@ export async function runAgent(
   } catch (error) {
     promptErrorMessage ??= errorText(error);
   } finally {
-    cancelModelProgressWatchdog();
     options.signal?.removeEventListener("abort", onAbort);
     settled = true;
     unsubscribe();
@@ -758,11 +607,7 @@ export async function runAgent(
       ? `Cleanup failed: ${cleanupErrors.join("; ")}`
       : undefined;
 
-  if (
-    terminalCause === "abort" ||
-    (terminalCause === undefined &&
-      assistantSettlement?.stopReason === "aborted")
-  ) {
+  if (aborted || assistantSettlement?.stopReason === "aborted") {
     return {
       ok: false,
       output,
@@ -779,9 +624,7 @@ export async function runAgent(
   }
 
   const failureMessage =
-    (terminalCause === "model-progress-timeout"
-      ? modelProgressTimeoutMessage
-      : agentFailureMessage(assistantSettlement, promptErrorMessage)) ??
+    agentFailureMessage(assistantSettlement, promptErrorMessage) ??
     cleanupError;
   if (failureMessage !== undefined) {
     return {

package/extensions/workflows/sandbox.ts

@@ -35,6 +35,7 @@ export interface SandboxAgentOptions {
   provider?: unknown;
   effort?: unknown;
   isolation?: unknown;
+  working_dir?: unknown;
   operator?: unknown;
   inputs?: unknown;
 }
@@ -110,6 +111,9 @@ function sanitizeAgentOptions(value: unknown): SandboxAgentOptions {
     ...(value.provider !== undefined ? { provider: value.provider } : {}),
     ...(value.effort !== undefined ? { effort: value.effort } : {}),
     ...(value.isolation !== undefined ? { isolation: value.isolation } : {}),
+    ...(value.working_dir !== undefined
+      ? { working_dir: value.working_dir }
+      : {}),
     ...(value.operator !== undefined ? { operator: value.operator } : {}),
     ...(value.inputs !== undefined ? { inputs: value.inputs } : {}),
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tt-a1i/openpi",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "OpenPI — a Pi-native multi-agent workbench with background execution, isolated subagents, replay-safe workflows, goals, tasks, and observable TUI",
   "license": "MIT",
   "author": "tt-a1i",
@@ -58,21 +58,43 @@
     "acorn": "^8.17.0",
     "effect": "^4.0.0-beta.99",
     "jiti": "2.7.0",
-    "marked": "^18.0.5",
     "undici": "8.9.0"
   },
   "devDependencies": {
+    "@astryxdesign/core": "0.5.2",
+    "@astryxdesign/theme-neutral": "0.5.2",
+    "@axe-core/playwright": "4.13.0",
     "@biomejs/biome": "2.5.8",
     "@earendil-works/pi-ai": "^0.85.1",
     "@earendil-works/pi-coding-agent": "^0.85.1",
     "@earendil-works/pi-tui": "^0.85.1",
     "@effect/tsgo": "^0.24.2",
     "@effect/vitest": "^4.0.0-beta.99",
+    "@playwright/test": "1.62.1",
+    "@stylexjs/stylex": "0.19.0",
+    "@tailwindcss/vite": "4.3.3",
+    "@testing-library/react": "16.3.3",
     "@types/node": "^26.1.1",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.5",
+    "@vitejs/plugin-react": "6.1.1",
+    "eventsource-parser": "4.1.0",
+    "i18next": "26.4.1",
+    "jsdom": "30.0.1",
+    "lucide-react": "1.39.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "react-i18next": "17.0.13",
+    "react-markdown": "10.1.0",
+    "rehype-sanitize": "6.0.0",
+    "remark-breaks": "4.0.0",
+    "remark-gfm": "4.0.1",
+    "tailwindcss": "4.3.3",
     "typebox": "^1.3.6",
     "typescript": "^7.0.2",
     "vite": "^8.2.0",
-    "vitest": "4.1.10"
+    "vitest": "4.1.10",
+    "zustand": "5.0.15"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.85.1",
@@ -98,7 +120,9 @@
     "dev:web": "node --experimental-strip-types scripts/dev-web.mjs",
     "dev:web:ui": "vite --config web/vite.config.mjs --host 127.0.0.1",
     "dev:web:backend": "node scripts/dev-web-backend.mjs",
-    "check:web": "node --check scripts/dev-web.mjs && node --check web/vite.config.mjs && node --check web/ui/app.js",
+    "build:web": "vite build --config web/vite.config.mjs",
+    "check:web": "node --check scripts/dev-web.mjs && node --check web/vite.config.mjs && tsc --noEmit --project web/ui/tsconfig.json && bun run build:web",
+    "test:web:e2e": "bun run build:web && playwright test --config tests/web/playwright.config.ts",
     "benchmark:workflow-child-startup": "node --experimental-strip-types scripts/benchmark-workflow-child-startup.mjs",
     "test": "node scripts/run-tests.mjs",
     "provenance": "node scripts/provenance.mjs"

package/skills/subagents/REFERENCE.md

@@ -32,7 +32,7 @@ file:line references. You cannot modify files — do not attempt to.
 | ------------------ | -------- | ------------------------------------------------------------------------------------ |
 | `name`             | yes      | `[a-z0-9-]`, ≤64 chars, and must equal the filename stem.                            |
 | `description`      | yes      | Shown to the parent model when it picks a type. ≤1024 chars.                         |
-| `tools`            | no       | Tool allowlist. **Omit to inherit the normal tool set.**                             |
+| `tools`            | no       | Tool allowlist. **Omit to inherit active parent child-eligible tools.**                             |
 | `model`            | no       | `provider/model-id`, or a bare id resolved against the current provider; ≤256 chars. |
 | `reasoning_effort` | no       | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`.                           |
 | body               | no       | Appended to the child's system prompt. ≤16384 chars.                                 |
@@ -50,16 +50,15 @@ file with the same name.
 
 | Role          | Tools                                                               | Relative effort guidance | Purpose                                                |
 | ------------- | ------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------ |
-| `explorer`    | `read grep find ls fd rg git_show git_diff git_log`                 | Moderate                 | Read-only codebase tracing; increase for harder tasks. |
-| `implementer` | `read bash edit write grep find ls fd rg git_show git_diff git_log` | Medium-high              | Focused implementation; adjust for scope and risk.     |
-| `reviewer`    | `read grep find ls fd rg git_show git_diff git_log`                 | High                     | Read-only correctness, safety, and regression review.  |
-| `advisor`     | `read grep find ls fd rg git_show git_diff git_log`                 | High                     | Deep read-only analysis and technical advice.          |
+| `explorer`    | Active parent child-eligible tools                 | Moderate                 | Read-only codebase tracing; increase for harder tasks. |
+| `implementer` | Active parent child-eligible tools | Medium-high              | Focused implementation; adjust for scope and risk.     |
+| `reviewer`    | Active parent child-eligible tools                 | High                     | Read-only correctness, safety, and regression review.  |
+| `advisor`     | Active parent child-eligible tools                 | High                     | Deep read-only analysis and technical advice.          |
 
 These are relative selection hints, not fixed Pi thinking levels. Built-ins set
 no model or reasoning-effort default. An explicit user requirement takes
 priority; otherwise the parent model chooses from levels supported by the
-resolved child model according to the role and task difficulty. Their tool
-allowlists still intersect with plan mode and the child denylist.
+resolved child model according to the role and task difficulty. Custom role allowlists intersect with active parent tools, Plan Mode, and the child denylist. Built-in read-only task guidance is a role instruction, not a filesystem sandbox. Existing custom role files are never widened automatically.
 
 ## Discovery
 

package/skills/subagents/SKILL.md

@@ -10,7 +10,7 @@ The tool definitions are canonical for parameters, limits, model syntax, isolati
 - Delegate substantial independent work, not a lookup or edit the parent can do directly.
 - Give the child a standalone prompt with paths, constraints, relevant context, and the expected report; it cannot see the parent conversation or ask the user.
 - Inherit the parent model by default. When choosing the child's reasoning effort, honor an explicit user requirement first; otherwise use the selected role's relative guidance and the task's difficulty, choosing from levels supported by the resolved child model.
-- Prefer a matching agent type when one exists; its tool restriction is enforced. Model precedence is explicit spawn override, selected type-file model, configured built-in role model, then parent model. Reasoning precedence is explicit spawn override, selected type default, then parent effort. Types live in `~/.pi/agent/agents/*.md` and, for trusted projects, `.pi/agents/*.md`; see [Agent types](REFERENCE.md).
+- Prefer a matching agent type when one exists; built-ins inherit active parent tools, while an explicit custom tool list is enforced as a narrowing restriction. Model precedence is explicit spawn override, selected type-file model, configured built-in role model, then parent model. Reasoning precedence is explicit spawn override, selected type default, then parent effort. Types live in `~/.pi/agent/agents/*.md` and, for trusted projects, `.pi/agents/*.md`; see [Agent types](REFERENCE.md).
 - Isolate concurrent writers in worktrees according to the `subagent_spawn` schema so they cannot overwrite one checkout or git index. While Plan Mode is active, use only read-only exploration types (or no type); worktree isolation and types narrowed by Plan Mode are rejected.
 - After spawning, continue useful parent work. In an interactive session, if none remains, tell the user the child is still running and end the turn; automatic result delivery will re-invoke the parent when it settles. Do not block merely because the next step depends on the result or because there is nothing else to do. Use `subagent_wait` only when the user explicitly asks to keep the current response open for the result, or when non-interactive automation must return it in the same invocation.
 - Use optional `output_schema` when downstream work needs a machine-validated result rather than prose. The child then receives one terminating `structured_output` tool, and the run fails if it finishes without submitting a matching value. Keep schemas small and task-specific; the validated JSON is delivered to the parent and preserved in a private content-addressed artifact. Omit the option for ordinary text reports.

package/skills/workflows/REFERENCE.md

@@ -14,8 +14,10 @@ The `workflow` script is an async JavaScript function body executed in a restric
 
 `await agent(prompt, options)` runs one child and always resolves to `{ ok, output, structured?, ref?, acceptance?, acceptanceWarning?, error? }`. Check `ok` before reading output. Children receive normal trust-aware resources but cannot recursively orchestrate or ask the user.
 
-Useful options include `agent_type`, `label`, `phase`, `schema`, `model`, `provider`, `effort`, `isolation`, `operator`, and `inputs`. The legacy `acceptance` option remains readable only during the 0.x migration window described below.
+Useful options include `agent_type`, `label`, `phase`, `schema`, `model`, `provider`, `effort`, `working_dir`, `isolation`, `operator`, and `inputs`. The legacy `acceptance` option remains readable only during the 0.x migration window described below.
 
+- Set `working_dir` when tools must run in another repository. Relative paths resolve against the parent cwd; prompt text alone does not change it. The directory must exist. Project resource trust is checked for the target independently.
+- Built-in roles inherit currently active parent child-eligible tools, including shell/network when available. Explicit custom tool lists only narrow this surface. Built-ins with inherited tools execute for real on resume; custom bounded read-only calls retain the replay filesystem boundary below.
 - Prefer a matching `agent_type`. Model precedence is explicit model/provider, type file, configured built-in role, then parent. Effort precedence is explicit effort, type default, then parent.
 - `schema` validates structured output. Use it whenever later workflow logic branches on fields.
 - `acceptance` is deprecated since OpenPI 0.5 and scheduled for removal in 1.0. Compatibility calls still return the child-authored ledger with `authority: "model-self-attestation"` and a migration warning, but it never determines `ok`. Use ordinary `schema` for findings, then let the parent evaluate them alongside runtime-observed exit codes, test receipts, file fingerprints, and tool results. Old DSL, journals, and artifacts remain readable during 0.x.