@narumitw/pi-subagents 0.43.0 → 0.43.1

package/README.md

@@ -18,7 +18,8 @@ Use it to split independent research, planning, implementation, and review work
 - Loads custom user agents from `~/.pi/agent/agents/*.md`.
 - Optionally loads project agents from `.pi/agents/*.md` with confirmation.
 - Provides a current-session-first `/subagents` manager, direct `settings|status|help` routes, and compatibility aliases for agent tools and retained agents.
-- Supports per-task `cwd`, hard subprocess `timeoutMs`, task-selected `thinkingLevel`, abort propagation, and streaming progress.
+- Supports trust-aware per-task `cwd` policies, hard subprocess `timeoutMs`, task-selected `thinkingLevel`, abort propagation, and streaming progress.
+- Renders all seven tools with Pi-native compact/expanded transcript rows; long-running blocking and consultation calls show bounded live activity.
 - Bounds JSON lines, captured messages, stderr, final output, chain substitution, and fan-in context.
 - Enforces a recursion-depth guard and deterministic process-group termination.
 - Provides addressable stateful agents with follow-up, consolidated mailbox/management actions, context selection, and persistence.
@@ -63,6 +64,18 @@ The available tools are:
 - `subagent_inspect` — inspect agent/model/run/runtime metadata without launching work or changing state.
 - `subagent_consult` — run one ephemeral read-only consultation and wait for its answer.
 
+### Interactive tool rows
+
+In Pi's interactive TUI, every registered tool uses Pi's native tool shell and theme. Call rows identify the action, agent or retained id, scope, and a bounded task/message preview. Result rows use explicit `Starting`, `Running`, `Completed`, `Failed`, `Cancelled`, `Interrupted`, or `Closed` text in addition to icons and color.
+
+Collapsed rows stay scan-friendly: consultation and blocking calls show recent activity while running, completed answers show up to three lines, and list actions show up to five items. Use Pi's configured `app.tools.expand` keybinding (Ctrl+O by default) for the additional bounded task, policy, activity, answer, usage, inspection, or mailbox details available to that tool. The hint follows the user's keybinding rather than assuming Ctrl+O.
+
+`subagent_consult` emits an initial starting update before launching its child and then reports the actual provider/model, thinking request, usage, and a safe projection of recent `read`, `grep`, `find`, and `ls` activity. Progress never includes full child messages, prompts, credentials, headers, or environment values. Tool-row previews remove terminal controls and redact private text.
+
+`subagent_spawn` remains deliberately detached and non-polling: its tool row ends after returning the new `agentId` and initial retained state. It does not pretend to stream the background child after the tool call has completed; the existing completion message and configured delivery policy report eventual completion.
+
+Custom transcript rendering is TUI presentation only. Tool names, parameter schemas, model-facing final content/details, errors, completion delivery, and print/JSON/RPC final output remain unchanged; JSON/RPC observers may see additive bounded consultation partial-progress details.
+
 After each session starts, the descriptions of the registered `subagent`, `subagent_spawn`, and
 `subagent_consult` tools include the same bounded parent-facing catalog of the agents available in
 that session. Entries show the source (`built-in`, `user`, or `project`) and the `agentScope` needed to
@@ -92,12 +105,29 @@ Execution modes:
 
 Common controls:
 
-- `cwd` — run a job from a different working directory.
+- `cwd` — choose a launch directory subject to the user-owned trust-aware target policy described below.
 - `timeoutMs` — set a hard subprocess timeout.
 - `thinkingLevel` — request `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` thinking for the spawned Pi process or in-process child.
 
 For `subagent_spawn`, the root agent selects the lowest thinking level sufficient for the delegated task. This is a tool-argument decision made from the task already in context; `pi-subagents` does not run a string heuristic or an extra classifier model call.
 
+## 🔐 Working-directory trust policy
+
+Pi records saved project trust in `~/.pi/agent/trust.json`. The closest saved decision for the canonical target or one of its parents wins, so trusting a worktree parent covers worktrees below it while a nearer `false` overrides a trusted parent. `pi-subagents` reads this through Pi's public `ProjectTrustStore`; it never parses, writes, or migrates the file. Open Pi in a folder and use `/trust` to manage trust, then restart Pi before expecting retained-runtime behavior to change.
+
+The default target policies are:
+
+| Setting | Values | Default behavior |
+| --- | --- | --- |
+| `cwdPolicy.consultation` | `"anywhere"`, `"current-workspace"` | `"anywhere"`: consultation may start in any existing directory, but a target without effective trust is forced to `resources: "none"` |
+| `cwdPolicy.delegation` | `"trusted-targets"`, `"current-workspace"`, `"anywhere"` | `"trusted-targets"`: blocking and detached delegation may target the current workspace or an external folder covered by a saved `true` decision |
+
+All paths are resolved relative to the current session workspace and canonicalized before containment and trust checks. Missing paths, non-directories, sibling paths, and symlink escapes cannot bypass the policy. Blocking parallel, chain, and fan-in calls preflight every target before any child starts. A generated `workspaceMode: "worktree"` inherits the resolved trust of its approved base cwd.
+
+`"anywhere"` for general delegation restores the previous external-target flexibility. An external target without effective trust starts with `projectTrusted: false`, so Pi-protected project settings, packages, extensions, skills, prompts, and system resources stay disabled. General agents still have their configured tools and ordinary Pi/OS permissions, and Pi may still load `AGENTS.md` or `CLAUDE.md` because those context files are not protected by project trust. Resource-free consultation is stricter: it also passes `--no-context-files`, `--no-skills`, `--no-prompt-templates`, `--no-approve`, and `--no-extensions`.
+
+These controls govern child starting directories and automatically loaded resources. They do **not** restrict absolute paths, shell commands, custom tools, network access, extension code, or filesystem access available to the Pi process. For real isolation, run Pi in a container, VM, micro-VM, or OS sandbox with only the required paths and credentials mounted.
+
 ## 🧭 Proactive use
 
 When registered, the blocking `subagent` tool advertises only blocking guidance. When stateful lifecycle tools
@@ -190,7 +220,7 @@ A blocking fan-out is reserved for output that must be synthesized before the ro
 | `list_runs` | Optional `includeClosed` and `limit` (default 50, maximum 100) | Metadata-only retained-run summaries and unread counts |
 | `get_run` | Required `agentId` | Safe `cwd`, current-task/error summaries, thinking level, policy, history count, and unread count |
 | `list_models` | Optional `limit` (default 50, maximum 100) | Session-scoped models, or the already-loaded available snapshot |
-| `status` | No additional fields | Effective workflow, runtime counts/transport, completion delivery, and consultation-resource setting |
+| `status` | No additional fields | Effective workflow, runtime counts/transport, completion delivery, consultation resources, and configured/runtime cwd policies with per-field sources |
 | `diagnose` | No additional fields | Structured `pass`, `warning`, and `fail` checks; failed checks are report data rather than a tool error |
 
 The schema rejects fields that do not belong to the selected action. Explicit `project` or `both` scope fails before project-agent discovery unless Pi already trusts the project. Run inspection never returns history output, stored context, or mailbox content; unread counts come from a metadata-only snapshot and do not acknowledge messages. Paths beneath the Pi agent directory use `~`, project paths are workspace-relative, model objects are projected through an allow-list, and model-facing text is bounded to 50 KiB or 2,000 lines.
@@ -227,9 +257,11 @@ without launching or charging a child.
 | `"none"` | Use only the package consultation base, selected agent prompt, and enforced read-only instruction |
 | `"all"` | Keep ordinarily discoverable trusted context/system/append-system files, skills, and prompt templates |
 
-Extensions remain disabled for all three values. For an untrusted current project, project resources are omitted; because Pi's context-file switch cannot separate user and project `AGENTS.md` files, `project-context` and `all` fail closed by disabling context files while still permitting the user `SYSTEM.md` selected by the extension. The setting is user-owned in `~/.pi/agent/pi-subagents.json`; projects cannot override it. An external or symlink-escaped `cwd` is accepted only with `consult.resources: "none"`, but this is not a path sandbox: read-only tools can still read an explicitly requested accessible absolute path.
+Extensions remain disabled for all three values. A current target uses the session's effective project trust, including session-only or CLI overrides. An external target uses the nearest saved trust decision. For an untrusted, explicitly denied, unsaved, or trust-error target, consultation remains available when `cwdPolicy.consultation` permits it but automatically downgrades to `resources: "none"`. This also disables context files because Pi does not protect `AGENTS.md` and `CLAUDE.md` with project trust alone. A saved-trusted external target uses the configured resource policy and discovers `SYSTEM.md`, `APPEND_SYSTEM.md`, and ordinary child context from that target rather than the parent workspace.
 
-Result details report requested/effective tools and resources, agent/model/thinking/timeout metadata, and the facts that extensions, session persistence, and retained-agent state are disabled. Nested model usage is returned through Pi's usage field, so footer, `/session`, and RPC totals include consultation cost. Validation, trust, unsafe-cwd, and launch failures throw. Failures after model launch preserve bounded partial evidence and usage while the finalized Pi tool result is marked as an error. Abort, timeout, session replacement, and shutdown use the existing process-tree termination and temporary-file cleanup path.
+Both settings are user-owned in `~/.pi/agent/pi-subagents.json`; projects cannot override them. `cwdPolicy.consultation: "current-workspace"` rejects every canonical external target before agent discovery or launch even when that target is saved-trusted. This is not a path sandbox: read-only tools can still read an explicitly requested accessible absolute path.
+
+Result details report the canonical safe cwd, current/external boundary, bounded target-trust decision/source/warning, requested and effective tools/resources, downgrade reason, agent/model/thinking/timeout metadata, and the facts that extensions, session persistence, and retained-agent state are disabled. They never dump prompt contents or the full trust store. Nested model usage is returned through Pi's usage field, so footer, `/session`, and RPC totals include consultation cost. Validation, disallowed targets, and launch failures throw. Failures after model launch preserve bounded partial evidence and usage while the finalized Pi tool result is marked as an error. Abort, timeout, session replacement, and shutdown use the existing process-tree termination and temporary-file cleanup path.
 
 ## 🚀 Blocking batch examples
 
@@ -320,12 +352,12 @@ Auto-resume is best-effort because Pi's custom-message API is fire-and-forget. S
 The default `subprocess` transport preserves compatibility: each turn starts a fresh isolated `pi --mode json -p --no-session` child and receives sanitized, bounded history. Set `transport` to `in-process` to retain one public Pi SDK `AgentSession` per stateful `agentId`, avoiding repeated process startup while preserving native child history in memory.
 
 Run `/subagents` in TUI mode to open the standard primary manager. It leads with the current
-delegation workflow, human-readable async completion behavior, consultation-resource policy, and active/retained counts. **Change delegation**, **Current agents**, and **Settings** cover the common workflows; agent permissions, transport/runtime details, source, and settings path remain under **Advanced settings**.
+delegation workflow, human-readable async completion behavior, consultation/delegation target policies, consultation-resource policy, and active/retained counts. **Change delegation**, **Current agents**, and **Settings** cover the common workflows; agent permissions, transport/runtime details, source, and settings path remain under **Advanced settings**.
 Escape returns from a nested screen to a newly refreshed manager; Ctrl+C closes the full flow.
 Exact workflow/reload and project-agent safety confirmations remain extension-owned because they
 guard live agent and trust-boundary policy rather than ordinary navigation.
 
-The direct routes remain predictable: `/subagents settings` changes completion delivery and consultation resources and applies them immediately, including refreshing model-facing spawn guidance; `/subagents status` reports current-session runtime values separately from configured values, sources, and path; `/subagents help` summarizes the single-command interface. In RPC mode, bare `/subagents` emits the same bounded status through Pi's notification protocol instead of opening a custom TUI. JSON and print modes do not emit ad hoc command output. Manual edits use `~/.pi/agent/pi-subagents.json` and take effect after reloading Pi:
+The direct routes remain predictable: `/subagents settings` changes both target policies, consultation resources, and completion delivery and applies them immediately, including refreshing model-facing tool guidance; `/subagents status` reports current-session runtime values separately from configured values, per-field sources, and path; `/subagents help` summarizes the single-command interface and the non-sandbox limitation. In RPC mode, bare `/subagents` emits the same bounded status through Pi's notification protocol instead of opening a custom TUI. JSON and print modes do not emit ad hoc command output. Manual edits use `~/.pi/agent/pi-subagents.json` and take effect after reloading Pi:
 
 ```json
 {
@@ -346,13 +378,17 @@ The direct routes remain predictable: `/subagents settings` changes completion d
     "retentionDays": 30,
     "maxStoredAgents": 50
   },
+  "cwdPolicy": {
+    "consultation": "anywhere",
+    "delegation": "trusted-targets"
+  },
   "consult": {
     "resources": "project-context"
   }
 }
 ```
 
-The settings UI patches the raw JSON atomically and preserves unknown fields; it refuses to overwrite malformed or invalid settings. Supported Pi writers serialize the latest-document read and same-directory temporary-file rename through `pi-subagents.json.mutation-lock`. Editors and older extension versions do not participate in that lock, so avoid manual edits while a settings save is in progress. `blocking.enabled` defaults to `true`; set it to `false` for async-only delegation. `stateful.enabled` also defaults to `true`; its existing `false` value remains the blocking-only workflow. `consult.resources` defaults to `"project-context"`; the Settings UI applies a saved change to subsequent consultations immediately, while manual edits take effect on session start or `/reload`. When stateful tools are enabled, their membership stays fixed across spawn, completion, interrupt, close, and mailbox transitions. This avoids lifecycle-driven tool-schema churn and preserves a stable provider prompt prefix for KV caching.
+The settings UI patches the raw JSON atomically and preserves unknown fields; it refuses to overwrite malformed or invalid settings. Supported Pi writers serialize the latest-document read and same-directory temporary-file rename through `pi-subagents.json.mutation-lock`. Editors and older extension versions do not participate in that lock, so avoid manual edits while a settings save is in progress. `blocking.enabled` defaults to `true`; set it to `false` for async-only delegation. `stateful.enabled` also defaults to `true`; its existing `false` value remains the blocking-only workflow. `cwdPolicy.consultation` defaults to `"anywhere"`, `cwdPolicy.delegation` defaults to `"trusted-targets"`, and `consult.resources` defaults to `"project-context"`. The Settings UI applies a saved change immediately to subsequent launches and refreshes the affected tool descriptions; manual edits take effect on session start or `/reload`. The UI explicitly states that target/trust settings are not filesystem sandboxing and directs trust changes to Pi `/trust`. When stateful tools are enabled, their membership stays fixed across spawn, completion, interrupt, close, and mailbox transitions. This avoids lifecycle-driven tool-schema churn and preserves a stable provider prompt prefix for KV caching.
 
 | Tool | Purpose |
 | --- | --- |
@@ -422,7 +458,7 @@ Stateful execution uses a transport boundary:
 
 - `subprocess` is the default compatibility and rollback path.
 - `in-process` uses only public Pi SDK APIs: `createAgentSession()`, `SessionManager.inMemory()`, `DefaultResourceLoader`, and normal session lifecycle methods. It isolates conversation/tool selection, not memory or crashes; child failures share the parent Node.js process.
-- Child resource loading sets `noExtensions: true`, preventing recursive `pi-subagents` loading and duplicate extension side effects while retaining normal context/skill resources and the selected agent prompt.
+- Child resource loading sets `noExtensions: true`, preventing recursive `pi-subagents` loading and duplicate extension side effects while retaining trust-eligible context/skill resources and the selected agent prompt. Both transports receive the same resolved target-trust boolean: subprocess children get explicit `--approve`/`--no-approve`, and in-process children set the same `SettingsManager.projectTrusted` value.
 - Agent model, thinking level, and built-in tool allow-list overrides are applied when the child is created. Parent model/thinking changes are snapshotted for subsequently created children; an existing child keeps its own session configuration.
 - Extension/custom tool names are rejected in-process with an actionable recommendation to use `subprocess`; permissions are never silently widened.
 - Timeout, parent abort, close, expiry, and session shutdown abort/dispose owned child sessions. A child that does not settle after abort grace is discarded rather than reused.
@@ -432,11 +468,11 @@ No private Pi imports, runtime casts, or `ExtensionAPI` monkey-patching are used
 
 Write-capable agents share the workspace by default. Concurrent write-capable starts in the same cwd are rejected unless `allowConcurrentWrites` is explicitly set. Classification is intentionally conservative: an agent with `bash`, `write`, or `edit` is write-capable even when its task prompt says “read only,” because prompt wording is not a filesystem sandbox. Prefer one detached agent when asynchronous work can be combined. If concurrent work is genuinely required, use the blocking batch only when synchronous outputs justify making the root unavailable, explicitly accept safe detached overlap with `allowConcurrentWrites`, or use isolated worktrees when repository isolation is needed.
 
-Set `workspaceMode: "worktree"` to opt into a disposable detached Git worktree; this requires a clean repository and the worktree is removed on close or session shutdown. Isolated worktree agents are intentionally not restored after shutdown.
+Set `workspaceMode: "worktree"` to opt into a disposable detached Git worktree; this requires a clean repository and the worktree is removed on close or session shutdown. The generated path inherits the approved base cwd's trust snapshot. Retained records mark disposable worktrees explicitly, so they are never restored even if cleanup could not remove the generated directory. Shared-workspace retained records store an additive bounded target-trust snapshot for transport and inspection parity; session restore canonicalizes the retained cwd and re-resolves current/saved trust rather than blindly trusting the persisted value. Older records without either field remain readable.
 
 ## 📜 Compatibility and failure contract
 
-Existing `subagent` requests remain unchanged:
+Existing `subagent` input schemas remain unchanged. The intentional compatibility change is that an external target without saved trust is rejected by the new default `cwdPolicy.delegation: "trusted-targets"`; set the user-owned policy to `"anywhere"` to restore the preceding target flexibility.
 
 | Mode | Ordering | Failure behavior |
 | --- | --- | --- |
@@ -448,7 +484,7 @@ Existing `subagent` requests remain unchanged:
 An aggregator whose `agent` or `task` is empty or whitespace-only is treated as absent, so successful
 parallel outputs remain available instead of being replaced by a malformed fan-in failure.
 
-Timeout precedence remains: task/step/aggregator → call → agent setting → `PI_SUBAGENT_TIMEOUT_MS` → 600000 ms. Blocking thinking precedence remains: task/step/aggregator → call → agent setting → child default. Stateful spawn thinking precedence is: `subagent_spawn.thinkingLevel` → agent setting → transport fallback. Project-agent resolution and confirmation behavior is unchanged.
+Timeout precedence remains: task/step/aggregator → call → agent setting → `PI_SUBAGENT_TIMEOUT_MS` → 600000 ms. Blocking thinking precedence remains: task/step/aggregator → call → agent setting → child default. Stateful spawn thinking precedence is: `subagent_spawn.thinkingLevel` → agent setting → transport fallback. Project-agent resolution and confirmation behavior is unchanged after target preflight. Blocking and retained result/inspection details add bounded target boundary and effective trust metadata.
 
 ## 🤖 Built-in agents
 
@@ -616,8 +652,12 @@ extensions/pi-subagents/
 │   ├── inspect.ts                # Side-effect-free metadata inspection tool
 │   ├── consult.ts                # Synchronous read-only consultation tool
 │   ├── consult-policy.ts         # Enforced read-only tool intersection
+│   ├── cwd-policy.ts             # Canonical target and saved-trust resolution
 │   ├── safe-text.ts              # Shared byte/line/path sanitization
 │   ├── stateful.ts               # Detached lifecycle registration and dispatch
+│   ├── stateful-guidance.ts      # Detached model-facing workflow guidance
+│   ├── stateful-lifecycle.ts     # Runtime disposal and spawn ownership guards
+│   ├── stateful-safety.ts        # Project-agent and shared-write safety checks
 │   ├── stateful-tool-params.ts   # Consolidated action schemas and validation
 │   └── *.ts                      # Package-local discovery, execution, rendering, and settings modules
 ├── README.md
@@ -626,7 +666,7 @@ extensions/pi-subagents/
 └── package.json
 ```
 
-`index.ts` is the Pi entrypoint and forwards to `subagents.ts`; the other source modules are internal. Workflow settings remain backward compatible: older files without `blocking.enabled` receive the seven-tool default, existing `stateful.enabled: false` files expose blocking delegation plus inspection/consultation, and older package releases ignore and preserve the optional `consult` object. The package exposes its Pi extension through `package.json`:
+`index.ts` is the Pi entrypoint and forwards to `subagents.ts`; the other source modules are internal. Workflow settings remain backward compatible: older files without `blocking.enabled` receive the seven-tool default, existing `stateful.enabled: false` files expose blocking delegation plus inspection/consultation, and older package releases ignore and preserve the optional `consult` and `cwdPolicy` objects. The package exposes its Pi extension through `package.json`:
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "0.43.0",
+	"version": "0.43.1",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",

package/src/agents.ts

@@ -49,6 +49,21 @@ export interface SubagentConsultSettings {
 	resources?: ConsultResourcePolicy;
 }
 
+export const CONSULTATION_CWD_POLICIES = ["anywhere", "current-workspace"] as const;
+export type ConsultationCwdPolicy = (typeof CONSULTATION_CWD_POLICIES)[number];
+
+export const DELEGATION_CWD_POLICIES = [
+	"trusted-targets",
+	"current-workspace",
+	"anywhere",
+] as const;
+export type DelegationCwdPolicy = (typeof DELEGATION_CWD_POLICIES)[number];
+
+export interface SubagentCwdPolicySettings {
+	consultation?: ConsultationCwdPolicy;
+	delegation?: DelegationCwdPolicy;
+}
+
 export interface SubagentBlockingSettings {
 	enabled?: boolean;
 }
@@ -73,6 +88,7 @@ export interface SubagentSettings {
 	blocking?: SubagentBlockingSettings;
 	stateful?: SubagentRuntimeSettings;
 	consult?: SubagentConsultSettings;
+	cwdPolicy?: SubagentCwdPolicySettings;
 }
 
 const BUILT_IN_AGENTS: AgentConfig[] = [

package/src/config-ui.ts

@@ -1,12 +1,19 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
-import { type CompletionDelivery, type ConsultResourcePolicy, discoverAgents } from "./agents.js";
+import {
+	type CompletionDelivery,
+	type ConsultationCwdPolicy,
+	type ConsultResourcePolicy,
+	type DelegationCwdPolicy,
+	discoverAgents,
+} from "./agents.js";
 import type { ManagedAgent } from "./registry.js";
 import {
 	type DelegationWorkflow,
 	hasOwn,
 	inspectCompletionDeliverySettings,
 	inspectConsultResourceSettings,
+	inspectCwdPolicySettings,
 	inspectDelegationWorkflowSettings,
 	readSubagentSettings,
 	sameToolSet,
@@ -14,6 +21,7 @@ import {
 	updateAgentToolsSetting,
 	updateCompletionDeliverySetting,
 	updateConsultResourceSetting,
+	updateCwdPolicySetting,
 	updateDelegationWorkflowSetting,
 } from "./settings.js";
 import { formatStatefulAgentLine, type StatefulSubagentRuntimeStatus } from "./stateful.js";
@@ -29,8 +37,12 @@ export interface SubagentSettingsRuntime {
 	getBlockingEnabled(): boolean;
 	getCompletionDelivery(): CompletionDelivery;
 	getConsultResourcePolicy(): ConsultResourcePolicy;
+	getConsultationCwdPolicy(): ConsultationCwdPolicy;
+	getDelegationCwdPolicy(): DelegationCwdPolicy;
 	setCompletionDelivery(value: CompletionDelivery): void;
 	setConsultResourcePolicy(value: ConsultResourcePolicy): void;
+	setConsultationCwdPolicy(value: ConsultationCwdPolicy): void;
+	setDelegationCwdPolicy(value: DelegationCwdPolicy): void;
 	getRuntimeStatus(): StatefulSubagentRuntimeStatus;
 	listAgents(includeClosed?: boolean): ManagedAgent[];
 	clearAgents(): Promise<number>;
@@ -90,7 +102,7 @@ function registerSubagentPrimaryCommand(
 					showSubagentStatus(ctx, runtime);
 					return;
 				case "help":
-					showSubagentHelp(ctx);
+					showSubagentHelp(ctx, runtime);
 					return;
 				default:
 					if (ctx.mode === "tui" || ctx.hasUI) {
@@ -129,6 +141,8 @@ async function showSubagentManager(
 		| "clear-agents"
 		| "set-completion"
 		| "set-consult-resources"
+		| "set-consultation-cwd"
+		| "set-delegation-cwd"
 		| "load-agent-picker"
 		| "pick-agent"
 		| "toggle-tool"
@@ -161,7 +175,7 @@ async function showSubagentManager(
 						{
 							id: "settings",
 							label: "Settings",
-							description: "Configure async completion and read-only consultation resources",
+							description: "Configure targets, trusted resources, and async completion",
 							to: "settings",
 						},
 						{
@@ -271,7 +285,7 @@ async function showSubagentManager(
 			help: () => ({
 				kind: "detail",
 				title: "Subagents help",
-				lines: helpLines(),
+				lines: helpLines(runtime),
 				hint: "back",
 			}),
 			"agent-picker": () => {
@@ -395,6 +409,8 @@ async function showSubagentManager(
 			"set-completion": async ({ value }) => applyCompletionSetting(value, ctx, runtime),
 			"set-consult-resources": async ({ value }) =>
 				applyConsultResourceSetting(value, ctx, runtime),
+			"set-consultation-cwd": async ({ value }) => applyConsultationCwdSetting(value, ctx, runtime),
+			"set-delegation-cwd": async ({ value }) => applyDelegationCwdSetting(value, ctx, runtime),
 			"load-agent-picker": async () => {
 				availableAgents = discoverAgents(ctx.cwd, "user", readSubagentSettings() ?? {}).agents;
 				if (availableAgents.length === 0) {
@@ -486,7 +502,11 @@ async function showSubagentSettings(
 		return;
 	}
 	const generation = owner.generation;
-	type SettingsAction = "set-completion" | "set-consult-resources";
+	type SettingsAction =
+		| "set-completion"
+		| "set-consult-resources"
+		| "set-consultation-cwd"
+		| "set-delegation-cwd";
 	const menu = defineMenu<undefined, "settings", SettingsAction, ExtensionCommandContext>({
 		start: "settings",
 		screens: { settings: () => subagentSettingsScreen(runtime) },
@@ -494,6 +514,8 @@ async function showSubagentSettings(
 			"set-completion": async ({ value }) => applyCompletionSetting(value, ctx, runtime),
 			"set-consult-resources": async ({ value }) =>
 				applyConsultResourceSetting(value, ctx, runtime),
+			"set-consultation-cwd": async ({ value }) => applyConsultationCwdSetting(value, ctx, runtime),
+			"set-delegation-cwd": async ({ value }) => applyDelegationCwdSetting(value, ctx, runtime),
 		},
 	});
 	await runMenu(ctx, menu, {
@@ -506,12 +528,15 @@ async function showSubagentSettings(
 function subagentSettingsScreen(runtime: SubagentSettingsRuntime) {
 	const completion = inspectCompletionDeliverySettings();
 	const consult = inspectConsultResourceSettings();
-	const error = completion.error ?? consult.error;
+	const cwdPolicy = inspectCwdPolicySettings();
+	const error = completion.error ?? consult.error ?? cwdPolicy.error;
 	return {
 		kind: "settings" as const,
 		title: error ? "Subagent User Settings · Read only" : "Subagent User Settings",
 		lines: [
 			"Applies now and to future sessions",
+			"Target and trust settings control startup resources, not filesystem access or sandboxing.",
+			"Manage folder trust with Pi /trust; restart Pi after changing it.",
 			safeTerminalText(consult.path),
 			...(error ? [`Settings cannot be edited: ${safeTerminalText(error)}`] : []),
 		],
@@ -519,23 +544,45 @@ function subagentSettingsScreen(runtime: SubagentSettingsRuntime) {
 			? []
 			: [
 					{
-						id: "completionDelivery",
-						label: "When async work finishes",
+						id: "consultationCwd",
+						label: "Read-only consultation target",
 						description:
-							"Wait for your next turn, or request one synthesis turn after the root settles.",
-						currentValue: completionLabel(runtime.getCompletionDelivery()),
-						values: ["Wait until my next turn", "Resume automatically when finished"],
-						action: "set-completion" as const,
+							"Untrusted external targets inherit no target/project resources; agent and package read-only prompts remain.",
+						currentValue: consultationCwdLabel(runtime.getConsultationCwdPolicy()),
+						values: ["Anywhere · untrusted targets inherit nothing", "Current workspace only"],
+						action: "set-consultation-cwd" as const,
+					},
+					{
+						id: "delegationCwd",
+						label: "General delegation target",
+						description:
+							"Controls starting directories, not absolute paths, shell commands, or OS permissions.",
+						currentValue: delegationCwdLabel(runtime.getDelegationCwdPolicy()),
+						values: [
+							"Current or saved-trusted folders",
+							"Current workspace only",
+							"Anywhere · normal Pi permissions",
+						],
+						action: "set-delegation-cwd" as const,
 					},
 					{
 						id: "consultResources",
-						label: "Read-only consultation resources",
+						label: "Consultation resources for trusted targets",
 						description:
 							"Choose which trusted context, system, skill, and prompt resources a consultation inherits.",
 						currentValue: consultResourceLabel(runtime.getConsultResourcePolicy()),
 						values: ["Project context only", "No inherited resources", "All trusted resources"],
 						action: "set-consult-resources" as const,
 					},
+					{
+						id: "completionDelivery",
+						label: "When async work finishes",
+						description:
+							"Wait for your next turn, or request one synthesis turn after the root settles.",
+						currentValue: completionLabel(runtime.getCompletionDelivery()),
+						values: ["Wait until my next turn", "Resume automatically when finished"],
+						action: "set-completion" as const,
+					},
 				],
 	};
 }
@@ -584,6 +631,50 @@ function applyConsultResourceSetting(
 	}
 }
 
+function applyConsultationCwdSetting(
+	value: string | undefined,
+	ctx: ExtensionCommandContext,
+	runtime: SubagentSettingsRuntime,
+) {
+	const previous = runtime.getConsultationCwdPolicy();
+	const next: ConsultationCwdPolicy =
+		value === "Current workspace only" ? "current-workspace" : "anywhere";
+	if (next === previous) return { kind: "stay" as const };
+	try {
+		updateCwdPolicySetting("consultation", next);
+		runtime.setConsultationCwdPolicy(next);
+		ctx.ui.notify(`Saved and applied: ${consultationCwdLabel(next)}.`, "info");
+		return { kind: "stay" as const };
+	} catch (error) {
+		ctx.ui.notify(`Subagent settings were not saved: ${formatError(error)}`, "error");
+		return { kind: "rejected" as const };
+	}
+}
+
+function applyDelegationCwdSetting(
+	value: string | undefined,
+	ctx: ExtensionCommandContext,
+	runtime: SubagentSettingsRuntime,
+) {
+	const previous = runtime.getDelegationCwdPolicy();
+	const next: DelegationCwdPolicy =
+		value === "Current workspace only"
+			? "current-workspace"
+			: value === "Anywhere · normal Pi permissions"
+				? "anywhere"
+				: "trusted-targets";
+	if (next === previous) return { kind: "stay" as const };
+	try {
+		updateCwdPolicySetting("delegation", next);
+		runtime.setDelegationCwdPolicy(next);
+		ctx.ui.notify(`Saved and applied: ${delegationCwdLabel(next)}.`, "info");
+		return { kind: "stay" as const };
+	} catch (error) {
+		ctx.ui.notify(`Subagent settings were not saved: ${formatError(error)}`, "error");
+		return { kind: "rejected" as const };
+	}
+}
+
 function blockReloadWithRetainedAgents(
 	ctx: ExtensionCommandContext,
 	runtime: SubagentSettingsRuntime,
@@ -628,9 +719,9 @@ function showSubagentStatus(ctx: ExtensionCommandContext, runtime: SubagentSetti
 	);
 }
 
-function showSubagentHelp(ctx: ExtensionCommandContext) {
+function showSubagentHelp(ctx: ExtensionCommandContext, runtime: SubagentSettingsRuntime) {
 	if (ctx.mode !== "tui" && !ctx.hasUI) return;
-	ctx.ui.notify(helpLines().join("\n"), "info");
+	ctx.ui.notify(helpLines(runtime).join("\n"), "info");
 }
 
 function statusLines(runtime: SubagentSettingsRuntime): string[] {
@@ -638,13 +729,20 @@ function statusLines(runtime: SubagentSettingsRuntime): string[] {
 	return formatStatus(runtime.getRuntimeStatus(), snapshot, runtime).split("\n");
 }
 
-function helpLines(): string[] {
+function helpLines(runtime: SubagentSettingsRuntime): string[] {
 	const snapshot = inspectCompletionDeliverySettings();
+	const cwdPolicy = inspectCwdPolicySettings();
 	return [
 		"/subagents — choose delegation workflow, manage current agents, and configure agent tools",
-		"/subagents settings — configure async completion and read-only consultation resources",
+		"/subagents settings — configure target locations, trusted resources, and async completion",
 		"/subagents status — show current-session and user-setting values",
 		"/subagents help — show this help",
+		"Target policies control startup directories and resources, not filesystem access or sandboxing.",
+		"Manage saved folder trust with Pi /trust and restart Pi after changing it.",
+		`Runtime consultation target: ${consultationCwdLabel(runtime.getConsultationCwdPolicy())}`,
+		`Configured consultation target: ${consultationCwdLabel(cwdPolicy.consultation.value)} (${cwdPolicy.consultation.source})`,
+		`Runtime delegation target: ${delegationCwdLabel(runtime.getDelegationCwdPolicy())}`,
+		`Configured delegation target: ${delegationCwdLabel(cwdPolicy.delegation.value)} (${cwdPolicy.delegation.source})`,
 		`User settings: ${safeTerminalText(snapshot.path)}`,
 	];
 }
@@ -655,10 +753,18 @@ function formatManagerSummary(
 	configured: ReturnType<typeof inspectDelegationWorkflowSettings>,
 ): string {
 	const current = currentWorkflow(runtime, status);
+	const cwdPolicy = inspectCwdPolicySettings();
+	const consult = inspectConsultResourceSettings();
 	return [
 		`Delegation: ${workflowLabel(current)}`,
 		`Completion: ${completionLabel(status.completionDelivery)}`,
+		`Consult target: ${consultationCwdLabel(runtime.getConsultationCwdPolicy())}`,
+		`Delegation target: ${delegationCwdLabel(runtime.getDelegationCwdPolicy())}`,
 		`Consult resources: ${consultResourceLabel(runtime.getConsultResourcePolicy())}`,
+		`Configured consult target: ${consultationCwdLabel(cwdPolicy.consultation.value)} · ${cwdPolicy.consultation.source}`,
+		`Configured delegation target: ${delegationCwdLabel(cwdPolicy.delegation.value)} · ${cwdPolicy.delegation.source}`,
+		`Configured consult resources: ${consultResourceLabel(consult.value)} · ${consult.source}`,
+		`Settings: ${safeTerminalText(cwdPolicy.path)}`,
 		`Agents: ${status.activeAgents} active · ${status.retainedAgents} retained`,
 		...(configured.value !== current
 			? [`Configured after reload: ${workflowLabel(configured.value)}`]
@@ -674,6 +780,7 @@ function formatStatus(
 ): string {
 	const configuredWorkflow = inspectDelegationWorkflowSettings();
 	const consult = inspectConsultResourceSettings();
+	const cwdPolicy = inspectCwdPolicySettings();
 	const current = runtime ? currentWorkflow(runtime, status) : configuredWorkflow.value;
 	return [
 		"Current session",
@@ -681,17 +788,24 @@ function formatStatus(
 		`  Async runtime: ${status.initialized ? "initialized" : status.enabled ? "not initialized" : "disabled"}`,
 		`  Transport: ${status.transport}`,
 		`  Completion: ${completionLabel(status.completionDelivery)}`,
+		`  Consultation target: ${consultationCwdLabel(runtime?.getConsultationCwdPolicy() ?? cwdPolicy.consultation.value)}`,
+		`  Delegation target: ${delegationCwdLabel(runtime?.getDelegationCwdPolicy() ?? cwdPolicy.delegation.value)}`,
+		`  Consultation resources: ${consultResourceLabel(runtime?.getConsultResourcePolicy() ?? consult.value)}`,
 		`  Agents: ${status.activeAgents} active, ${status.retainedAgents} retained`,
 		"User settings",
 		`  Delegation source: ${configuredWorkflow.source}`,
 		`  Configured delegation: ${workflowLabel(configuredWorkflow.value)}`,
 		`  Completion source: ${snapshot.source}`,
 		`  Configured completion: ${completionLabel(snapshot.value)}`,
-		`  Consultation resources: ${consultResourceLabel(runtime?.getConsultResourcePolicy() ?? consult.value)}`,
+		`  Configured consultation target: ${consultationCwdLabel(cwdPolicy.consultation.value)}`,
+		`  Consultation target source: ${cwdPolicy.consultation.source}`,
+		`  Configured delegation target: ${delegationCwdLabel(cwdPolicy.delegation.value)}`,
+		`  Delegation target source: ${cwdPolicy.delegation.source}`,
+		`  Configured consultation resources: ${consultResourceLabel(consult.value)}`,
 		`  Consultation resource source: ${consult.source}`,
 		`  Path: ${safeTerminalText(snapshot.path)}`,
-		configuredWorkflow.error || snapshot.error
-			? `  Warning: ${safeTerminalText(configuredWorkflow.error ?? snapshot.error ?? "invalid settings")}`
+		configuredWorkflow.error || snapshot.error || cwdPolicy.error
+			? `  Warning: ${safeTerminalText(configuredWorkflow.error ?? snapshot.error ?? cwdPolicy.error ?? "invalid settings")}`
 			: "  Warning: none",
 		configuredWorkflow.value !== current
 			? "Configured delegation differs from this session. Run /reload to apply it."
@@ -737,6 +851,23 @@ function completionLabel(value: CompletionDelivery): string {
 	return value === "auto-resume" ? "Resume automatically when finished" : "Wait until my next turn";
 }
 
+function consultationCwdLabel(value: ConsultationCwdPolicy): string {
+	return value === "current-workspace"
+		? "Current workspace only"
+		: "Anywhere · untrusted targets inherit nothing";
+}
+
+function delegationCwdLabel(value: DelegationCwdPolicy): string {
+	switch (value) {
+		case "trusted-targets":
+			return "Current or saved-trusted folders";
+		case "current-workspace":
+			return "Current workspace only";
+		case "anywhere":
+			return "Anywhere · normal Pi permissions";
+	}
+}
+
 function consultResourceLabel(value: ConsultResourcePolicy): string {
 	switch (value) {
 		case "project-context":