@narumitw/pi-subagents 0.42.0 → 0.43.0

package/README.md

@@ -2,13 +2,15 @@
 
 [![npm](https://img.shields.io/npm/v/@narumitw/pi-subagents)](https://www.npmjs.com/package/@narumitw/pi-subagents) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
-`@narumitw/pi-subagents` is a native [Pi coding agent](https://pi.dev) extension for delegating work to specialized agents. By default, the blocking batch `subagent` tool uses isolated Pi subprocesses while four detached tools run reusable agents either as subprocess-backed logical sessions or as public-SDK in-process child sessions. Users can keep all five tools, choose async-only delegation, or retain only blocking batches.
+`@narumitw/pi-subagents` is a native [Pi coding agent](https://pi.dev) extension for delegating work to specialized agents. By default, it exposes seven capability-specific tools: blocking batches, four detached lifecycle tools, side-effect-free inspection, and synchronous read-only consultation. Users can keep every delegation method, choose async-only delegation, retain only blocking delegation, or disable delegation while keeping inspection available.
 
 Use it to split independent research, planning, implementation, and review work across focused workers. Under the default next-turn delivery policy, background delegation is for work the current response does not depend on. Opt-in auto-resume also supports final-answer-dependent background work by requesting a synthesis turn after completion.
 
 ## ✨ Features
 
-- Offers all delegation methods by default, with goal-oriented presets for async-only or blocking-only workflows.
+- Offers all delegation methods by default, with goal-oriented presets for async-only, blocking-only, or disabled delegation.
+- Adds `subagent_inspect` for bounded metadata without child launch, mailbox-content access, acknowledgement, or mutation.
+- Adds `subagent_consult` for one synchronous ephemeral child constrained to built-in `read`, `grep`, `find`, and `ls` tools (or a narrower agent allow-list).
 - Keeps batch workers isolated in `pi --mode json -p --no-session` subprocesses.
 - Registers detached stateful lifecycle tools by default; completion can stay queued for the next turn or opt into an idle root synthesis turn.
 - Supports an opt-in public-SDK `in-process` stateful transport with one reusable child `AgentSession` per `agentId`.
@@ -43,13 +45,14 @@ pi -e ./extensions/pi-subagents
 
 ## 🛠️ Pi tool
 
-`pi-subagents` registers all five tools by default. Run `/subagents`, choose **Change delegation**, review the concrete tool changes, then select **Save and reload** to apply one of these workflows:
+`pi-subagents` registers seven tools by default. Run `/subagents`, choose **Change delegation**, review the concrete tool changes, then select **Save and reload** to apply one of these workflows:
 
 | Workflow | Registered tools |
 | --- | --- |
-| **All delegation methods** (default) | Blocking `subagent` plus all four detached lifecycle tools |
-| **Async only** | `subagent_spawn`, `subagent_send`, `subagent_manage`, and `subagent_mailbox`; blocking `subagent` is omitted |
-| **Blocking only** | Blocking `subagent` only; equivalent to the existing `stateful.enabled: false` behavior |
+| **All delegation methods** (default) | Existing five delegation/lifecycle tools, `subagent_inspect`, and `subagent_consult` |
+| **Async only** | Four detached lifecycle tools plus `subagent_inspect`; blocking `subagent` and `subagent_consult` are omitted |
+| **Blocking only** | `subagent`, `subagent_consult`, and `subagent_inspect` |
+| **Disabled** | `subagent_inspect` only; delegation is disabled |
 
 The preview compares the selection with the tools registered in the current session, even when a manual settings edit is pending, and remains read-only until confirmation. Escape or **Cancel** leaves settings unchanged. Tool removal requires an extension reload because Pi does not expose extension tool unregistration. To avoid aborting work or removing isolated worktrees during `session_shutdown`, workflow changes are blocked while detached agents are retained; finish or clear them through **Current agents** first. Pi owns reload-error reporting and does not return a success result to extensions, so the save notification also tells users to run `/reload` if the tool surface does not refresh.
 
@@ -57,12 +60,16 @@ The available tools are:
 
 - `subagent` — delegate blocking single, parallel, fan-in, or chained batch work. The main agent cannot process queued steering until the call returns.
 - `subagent_spawn` and related lifecycle tools — when enabled, start reusable detached work, return immediately, and receive bounded completion messages automatically.
+- `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.
 
-After each session starts, both delegation tools include a 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 invoke them; the `agent` parameters remain unconstrained strings for cwd and
-scope flexibility. The catalog is rebuilt on `/reload` or the next session start, and omitted entries
-are reported explicitly when the catalog exceeds its metadata bounds.
+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
+invoke them; the `agent` parameters remain unconstrained strings for cwd and scope flexibility. The
+catalog is rebuilt on
+`/reload` or the next session start, and omitted entries are reported explicitly when the catalog
+exceeds its metadata bounds.
 
 Choose the API by lifecycle:
 
@@ -72,6 +79,8 @@ Choose the API by lifecycle:
 | Broad research/review the current response does not depend on | Prefer one `subagent_spawn` covering related branches, when lifecycle tools are enabled |
 | Final-answer-dependent broad work with `completionDelivery: "auto-resume"` | Prefer one `subagent_spawn`; completion requests a synthesis turn |
 | Reusable history, follow-ups, or mailboxes | `subagent_spawn` and lifecycle tools, when enabled |
+| Side-effect-free agent/model/run diagnostics | `subagent_inspect` |
+| Synchronous reconnaissance, planning, or review that must not write | `subagent_consult`, when blocking delegation is enabled |
 | One simple or critical-path action the root can perform directly | No subagent |
 
 Execution modes:
@@ -95,10 +104,11 @@ When registered, the blocking `subagent` tool advertises only blocking guidance.
 are registered, `subagent_spawn` adds detached guidance for the active completion-delivery policy.
 Changing the policy through `/subagents settings` refreshes that guidance immediately.
 
-The same descriptions also advertise the current agent catalog automatically; no preliminary list call is
-needed. Built-ins and user agents appear under the default `agentScope: "user"`. Trusted project
-agents appear separately and explicitly require `agentScope: "project"` or `"both"`; project-authored
-names and descriptions are not read into metadata for untrusted projects. If a project definition
+The `subagent`, `subagent_spawn`, and `subagent_consult` descriptions advertise the current agent
+catalog automatically; no preliminary list call is needed. Built-ins and user agents appear under the
+default `agentScope: "user"`. Trusted project agents appear separately and explicitly require
+`agentScope: "project"` or `"both"`; project-authored names and descriptions are not read into
+metadata for untrusted projects. If a project definition
 shares a name with a user or built-in definition, the user version is the default and the project
 version is used only for `"project"`/`"both"`. A user override of a built-in also shows the
 built-in fallback available with `agentScope: "project"`; `"both"` keeps the user definition. The
@@ -169,6 +179,58 @@ A blocking fan-out is reserved for output that must be synthesized before the ro
 }
 ```
 
+## 🔎 Read-only inspection
+
+`subagent_inspect` is registered in every workflow, including disabled delegation. It never starts a child, sends or acknowledges mailbox messages, interrupts or closes a run, changes settings, refreshes providers, resolves credentials, or modifies files.
+
+| Action | Parameters | Result |
+| --- | --- | --- |
+| `list_agents` | Optional `agentScope` (default `user`) and `limit` (default 32, maximum 100) | Bounded agent metadata and omission counts |
+| `get_agent` | Required `agent`; optional `agentScope` | One resolved definition, safe source path, configured tools, and consultation-effective tools; never the system prompt |
+| `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 |
+| `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.
+
+Compatibility: `subagent_manage({ "action": "list" })` remains supported with its existing behavior. Prefer `subagent_inspect` when a whole tool must be safe to activate on a read-only surface.
+
+## 📖 Read-only consultation
+
+`subagent_consult` is registered whenever blocking delegation is enabled. It runs exactly one synchronous, non-retained child with `--no-session`, `--no-extensions`, and only the effective intersection of the agent tools with `read`, `grep`, `find`, and `ls`. A missing tool list receives those four defaults; an explicit `tools: []` receives `--no-tools`; write, shell, lifecycle, custom, and extension tools cannot enter the child allow-list. The executor policy remains authoritative even when the task or agent prompt asks for implementation.
+
+```json
+{
+  "agent": "reviewer",
+  "task": "Inspect the authentication changes and report correctness and security findings with paths.",
+  "thinkingLevel": "high"
+}
+```
+
+The actionless schema requires `agent` and `task` and accepts optional `agentScope`,
+`confirmProjectAgents`, `cwd`, `timeoutMs`, and `thinkingLevel`. Any agent resolved from that scope may
+be selected; consultation always intersects its configured tools with the enforced read-only
+allow-list rather than defining a separate read-only agent category. An unknown name fails before
+launch with a bounded name/source list for the requested scope. Project scope is rejected before
+discovery when the project is untrusted. A trusted project agent still asks for confirmation by
+default; non-interactive calls fail closed unless they explicitly send
+`confirmProjectAgents: false`. Declining an interactive confirmation returns a normal cancelled result
+without launching or charging a child.
+
+`consult.resources` controls automatically inherited instruction resources:
+
+| Value | Behavior |
+| --- | --- |
+| `"project-context"` (default) | Keep ordinary user context/system files and trusted project `AGENTS.md`, `CLAUDE.md`, and `SYSTEM.md`; disable skills and prompt templates |
+| `"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.
+
+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.
+
 ## 🚀 Blocking batch examples
 
 Every example in this section calls `subagent` and keeps the main agent unavailable until the batch
@@ -258,14 +320,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, and active/retained counts. **Change
-delegation**, **Current agents**, and **Completion behavior** 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-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 user completion delivery and applies it immediately, including refreshing the model-facing spawn guidance; `/subagents status` reports current-session runtime values separately from the configured value, source, 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 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:
 
 ```json
 {
@@ -285,11 +345,14 @@ The direct routes remain predictable: `/subagents settings` changes user complet
     "idleTtlMs": 3600000,
     "retentionDays": 30,
     "maxStoredAgents": 50
+  },
+  "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. 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. `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.
 
 | Tool | Purpose |
 | --- | --- |
@@ -318,7 +381,7 @@ The action schemas are flat for provider compatibility and reject parameters tha
 
 Use the **Current agents** action in `/subagents` to inspect the indented agent tree, lifecycle state, unread count, and available actions, or to confirm clearing retained agents. Active turns are FIFO-limited by `maxActiveTurns`; excess retained work remains in `starting` state until a slot is available. `maxAgents` separately bounds running, queued, and idle records. `parentId` creates a bounded child relationship; subtree interrupt and close operate child-first.
 
-### Migrating from the seven-tool lifecycle surface
+### Migrating from the previous seven-tool lifecycle surface
 
 The five replaced names are intentionally not registered as aliases. Update explicit prompts and integrations as follows:
 
@@ -418,7 +481,7 @@ Compatibility: a valid legacy `pi-subagents-config.json` remains readable with a
 - Choose **Save changes** to write the draft, choose **Discard draft** to abandon it, or press Esc to
   return to agent selection without writing.
 - Save the default selection to remove a custom override and use the agent defaults again.
-- Deselect every tool and save to run that agent with no tools.
+- Deselect every tool and save to run that agent with no tools. An explicit empty list remains distinct from an absent list; blank `tools:` or `tools: []` in agent frontmatter also means no tools.
 
 Configured tool names that are not currently registered are preserved, so settings for tools from
 other extension sessions are not silently dropped.
@@ -445,6 +508,8 @@ You are an API review subagent. Do not edit files. Check compatibility,
 test coverage, and migration risks. Report PASS/FAIL/PARTIAL with evidence.
 ```
 
+`tools` accepts either the comma-separated form above or a YAML string array such as `tools: [read, grep]`. An omitted field keeps the agent's default tools; blank, `null`, or `[]` explicitly selects no tools.
+
 `agentScope` is a top-level tool argument supplied per invocation. It is not a setting in
 `~/.pi/agent/pi-subagents.json` and does not belong in agent frontmatter. The parent-facing tool
 metadata discovers these definitions after session start and labels their source and required scope.
@@ -491,6 +556,7 @@ Each subprocess has a hard timeout to avoid runaway workers.
 
 - Set `timeoutMs` on the top-level call to apply a default for all jobs.
 - Set `timeoutMs` on a task, chain step, or aggregator to override it locally.
+- Valid timeout values range from 1 to 2,147,483,647 milliseconds, matching the runtime timer limit.
 - If omitted, the default is `PI_SUBAGENT_TIMEOUT_MS`, or `600000` milliseconds (10 minutes) when unset.
 
 Set `thinkingLevel` to request one of Pi's supported levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Blocking subprocess calls pass the resolved value through `--thinking <level>`.
@@ -520,7 +586,7 @@ The child event protocol limits each JSON line to 256 KiB. Captured output uses
 - stderr: 16 KiB;
 - captured messages: 200.
 
-Truncated text includes a `truncated by pi-subagents` marker and details expose `truncated: true`. `PI_SUBAGENT_MAX_DEPTH` controls nested delegation depth and defaults to 1; child processes receive `PI_SUBAGENT_DEPTH` automatically.
+Truncated text includes a `truncated by pi-subagents` marker and details expose `truncated: true`. Inspection and consultation model-facing content also stops at 2,000 lines, whichever limit is reached first. `PI_SUBAGENT_MAX_DEPTH` controls nested delegation depth and defaults to 1; child processes receive `PI_SUBAGENT_DEPTH` automatically.
 
 ## 📡 Runtime status
 
@@ -528,7 +594,7 @@ While the `subagent` tool is running, `pi-subagents` publishes compact activity
 
 ## 🔒 Safety notes
 
-Subagents have separate processes and context windows, but they are **not security sandboxes**. They run as the same OS user, share the host filesystem and network access, and may conflict if they edit the same files. Tool allow-lists reduce available Pi tools but do not reduce operating-system permissions.
+Subagents have separate processes and context windows, but they are **not security sandboxes**. They run as the same OS user, share the host filesystem and network access, and may conflict if they edit the same files. Tool allow-lists reduce available Pi tools but do not reduce operating-system permissions. `subagent_consult` prevents writes through its Pi tool surface and disables extensions, but it can read accessible paths, call the configured model over the network, and incur cost; its instruction-resource policy is not a filesystem or confidentiality boundary.
 
 The runner explicitly reports policy continuity in result details:
 
@@ -547,16 +613,20 @@ extensions/pi-subagents/
 ├── src/
 │   ├── index.ts                  # Pi package entrypoint
 │   ├── subagents.ts              # Extension registration and blocking tool schema
+│   ├── inspect.ts                # Side-effect-free metadata inspection tool
+│   ├── consult.ts                # Synchronous read-only consultation tool
+│   ├── consult-policy.ts         # Enforced read-only tool intersection
+│   ├── safe-text.ts              # Shared byte/line/path sanitization
 │   ├── stateful.ts               # Detached lifecycle registration and dispatch
 │   ├── stateful-tool-params.ts   # Consolidated action schemas and validation
-│   └── *.ts                      # Package-local discovery, execution, rendering, and config modules
+│   └── *.ts                      # Package-local discovery, execution, rendering, and settings modules
 ├── README.md
 ├── LICENSE
 ├── tsconfig.json
 └── 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` keep the five-tool default, existing `stateful.enabled: false` files remain blocking-only, and older package releases ignore the new `blocking` 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` object. The package exposes its Pi extension through `package.json`:
 
 ```json
 {

package/package.json

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

package/src/agents.ts

@@ -41,6 +41,14 @@ export type SubagentTransportKind = "subprocess" | "in-process";
 
 export type CompletionDelivery = "next-turn" | "auto-resume";
 
+export const CONSULT_RESOURCE_POLICIES = ["project-context", "none", "all"] as const;
+
+export type ConsultResourcePolicy = (typeof CONSULT_RESOURCE_POLICIES)[number];
+
+export interface SubagentConsultSettings {
+	resources?: ConsultResourcePolicy;
+}
+
 export interface SubagentBlockingSettings {
 	enabled?: boolean;
 }
@@ -64,6 +72,7 @@ export interface SubagentSettings {
 	agents?: Record<string, SubagentAgentConfig>;
 	blocking?: SubagentBlockingSettings;
 	stateful?: SubagentRuntimeSettings;
+	consult?: SubagentConsultSettings;
 }
 
 const BUILT_IN_AGENTS: AgentConfig[] = [
@@ -238,20 +247,36 @@ function loadAgentsFromDir(
 			continue;
 		}
 
-		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(loaded.content);
+		const { frontmatter, body } = parseFrontmatter<Record<string, unknown>>(loaded.content);
 
-		if (!frontmatter.name || !frontmatter.description) continue;
+		if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") {
+			continue;
+		}
 
-		const tools = frontmatter.tools
-			?.split(",")
-			.map((t: string) => t.trim())
-			.filter(Boolean);
+		const hasTools = hasOwn(frontmatter, "tools");
+		const rawTools = frontmatter.tools;
+		let tools: string[] | undefined;
+		if (hasTools) {
+			if (rawTools === null) {
+				tools = [];
+			} else if (Array.isArray(rawTools)) {
+				if (!rawTools.every((tool): tool is string => typeof tool === "string")) continue;
+				tools = rawTools.map((tool) => tool.trim()).filter(Boolean);
+			} else if (typeof rawTools === "string") {
+				tools = rawTools
+					.split(",")
+					.map((tool) => tool.trim())
+					.filter(Boolean);
+			} else {
+				continue;
+			}
+		}
 
 		agents.push({
 			name: frontmatter.name,
 			description: frontmatter.description,
-			tools: tools && tools.length > 0 ? tools : undefined,
-			model: frontmatter.model,
+			...(hasTools ? { tools: tools ?? [] } : {}),
+			model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
 			thinkingLevel: isThinkingLevel(frontmatter.thinkingLevel)
 				? frontmatter.thinkingLevel
 				: undefined,

package/src/config-ui.ts

@@ -1,23 +1,25 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
-import { type CompletionDelivery, discoverAgents } from "./agents.js";
+import { type CompletionDelivery, type ConsultResourcePolicy, discoverAgents } from "./agents.js";
 import type { ManagedAgent } from "./registry.js";
 import {
 	type DelegationWorkflow,
 	hasOwn,
 	inspectCompletionDeliverySettings,
+	inspectConsultResourceSettings,
 	inspectDelegationWorkflowSettings,
 	readSubagentSettings,
 	sameToolSet,
 	uniqueToolNames,
 	updateAgentToolsSetting,
 	updateCompletionDeliverySetting,
+	updateConsultResourceSetting,
 	updateDelegationWorkflowSetting,
 } from "./settings.js";
 import { formatStatefulAgentLine, type StatefulSubagentRuntimeStatus } from "./stateful.js";
 
 const SUBCOMMANDS = [
-	{ value: "settings", label: "settings", description: "Configure completion behavior" },
+	{ value: "settings", label: "settings", description: "Configure subagent user settings" },
 	{ value: "status", label: "status", description: "Show effective subagent settings" },
 	{ value: "help", label: "help", description: "Show subagent settings help" },
 ];
@@ -26,7 +28,9 @@ const TOOL_VIEWPORT_SIZE = 10;
 export interface SubagentSettingsRuntime {
 	getBlockingEnabled(): boolean;
 	getCompletionDelivery(): CompletionDelivery;
+	getConsultResourcePolicy(): ConsultResourcePolicy;
 	setCompletionDelivery(value: CompletionDelivery): void;
+	setConsultResourcePolicy(value: ConsultResourcePolicy): void;
 	getRuntimeStatus(): StatefulSubagentRuntimeStatus;
 	listAgents(includeClosed?: boolean): ManagedAgent[];
 	clearAgents(): Promise<number>;
@@ -114,7 +118,7 @@ async function showSubagentManager(
 		| "main"
 		| "workflow"
 		| "agents"
-		| "completion"
+		| "settings"
 		| "advanced"
 		| "status"
 		| "help"
@@ -124,6 +128,7 @@ async function showSubagentManager(
 		| "set-workflow"
 		| "clear-agents"
 		| "set-completion"
+		| "set-consult-resources"
 		| "load-agent-picker"
 		| "pick-agent"
 		| "toggle-tool"
@@ -154,10 +159,10 @@ async function showSubagentManager(
 							to: "agents",
 						},
 						{
-							id: "completion",
-							label: "Completion behavior",
-							description: "Choose whether async completion waits or resumes automatically",
-							to: "completion",
+							id: "settings",
+							label: "Settings",
+							description: "Configure async completion and read-only consultation resources",
+							to: "settings",
 						},
 						{
 							id: "advanced",
@@ -236,7 +241,7 @@ async function showSubagentManager(
 					hint: "back",
 				};
 			},
-			completion: () => completionSettingsScreen(),
+			settings: () => subagentSettingsScreen(runtime),
 			advanced: () => ({
 				kind: "actions",
 				title: "Advanced Subagent Settings",
@@ -388,6 +393,8 @@ async function showSubagentManager(
 				return { kind: "stay" };
 			},
 			"set-completion": async ({ value }) => applyCompletionSetting(value, ctx, runtime),
+			"set-consult-resources": async ({ value }) =>
+				applyConsultResourceSetting(value, ctx, runtime),
 			"load-agent-picker": async () => {
 				availableAgents = discoverAgents(ctx.cwd, "user", readSubagentSettings() ?? {}).agents;
 				if (availableAgents.length === 0) {
@@ -468,7 +475,7 @@ async function showSubagentSettings(
 	runtime: SubagentSettingsRuntime,
 	owner: MenuOwner,
 ) {
-	const snapshot = inspectCompletionDeliverySettings();
+	const snapshot = inspectConsultResourceSettings();
 	if (ctx.mode !== "tui") {
 		if (ctx.hasUI) {
 			ctx.ui.notify(
@@ -479,11 +486,14 @@ async function showSubagentSettings(
 		return;
 	}
 	const generation = owner.generation;
-	const menu = defineMenu<undefined, "completion", "set-completion", ExtensionCommandContext>({
-		start: "completion",
-		screens: { completion: () => completionSettingsScreen() },
+	type SettingsAction = "set-completion" | "set-consult-resources";
+	const menu = defineMenu<undefined, "settings", SettingsAction, ExtensionCommandContext>({
+		start: "settings",
+		screens: { settings: () => subagentSettingsScreen(runtime) },
 		actions: {
 			"set-completion": async ({ value }) => applyCompletionSetting(value, ctx, runtime),
+			"set-consult-resources": async ({ value }) =>
+				applyConsultResourceSetting(value, ctx, runtime),
 		},
 	});
 	await runMenu(ctx, menu, {
@@ -493,17 +503,19 @@ async function showSubagentSettings(
 	});
 }
 
-function completionSettingsScreen() {
-	const snapshot = inspectCompletionDeliverySettings();
+function subagentSettingsScreen(runtime: SubagentSettingsRuntime) {
+	const completion = inspectCompletionDeliverySettings();
+	const consult = inspectConsultResourceSettings();
+	const error = completion.error ?? consult.error;
 	return {
 		kind: "settings" as const,
-		title: snapshot.error ? "Subagent User Settings · Read only" : "Subagent User Settings",
+		title: error ? "Subagent User Settings · Read only" : "Subagent User Settings",
 		lines: [
 			"Applies now and to future sessions",
-			safeTerminalText(snapshot.path),
-			...(snapshot.error ? [`Settings cannot be edited: ${safeTerminalText(snapshot.error)}`] : []),
+			safeTerminalText(consult.path),
+			...(error ? [`Settings cannot be edited: ${safeTerminalText(error)}`] : []),
 		],
-		items: snapshot.error
+		items: error
 			? []
 			: [
 					{
@@ -511,10 +523,19 @@ function completionSettingsScreen() {
 						label: "When async work finishes",
 						description:
 							"Wait for your next turn, or request one synthesis turn after the root settles.",
-						currentValue: completionLabel(snapshot.value),
+						currentValue: completionLabel(runtime.getCompletionDelivery()),
 						values: ["Wait until my next turn", "Resume automatically when finished"],
 						action: "set-completion" as const,
 					},
+					{
+						id: "consultResources",
+						label: "Read-only consultation resources",
+						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,
+					},
 				],
 	};
 }
@@ -539,6 +560,30 @@ function applyCompletionSetting(
 	}
 }
 
+function applyConsultResourceSetting(
+	value: string | undefined,
+	ctx: ExtensionCommandContext,
+	runtime: SubagentSettingsRuntime,
+) {
+	const previous = runtime.getConsultResourcePolicy();
+	const next: ConsultResourcePolicy =
+		value === "No inherited resources"
+			? "none"
+			: value === "All trusted resources"
+				? "all"
+				: "project-context";
+	if (next === previous) return { kind: "stay" as const };
+	try {
+		updateConsultResourceSetting(next);
+		runtime.setConsultResourcePolicy(next);
+		ctx.ui.notify(`Saved and applied: ${consultResourceLabel(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,
@@ -597,7 +642,7 @@ function helpLines(): string[] {
 	const snapshot = inspectCompletionDeliverySettings();
 	return [
 		"/subagents — choose delegation workflow, manage current agents, and configure agent tools",
-		"/subagents settings — configure async completion behavior",
+		"/subagents settings — configure async completion and read-only consultation resources",
 		"/subagents status — show current-session and user-setting values",
 		"/subagents help — show this help",
 		`User settings: ${safeTerminalText(snapshot.path)}`,
@@ -613,6 +658,7 @@ function formatManagerSummary(
 	return [
 		`Delegation: ${workflowLabel(current)}`,
 		`Completion: ${completionLabel(status.completionDelivery)}`,
+		`Consult resources: ${consultResourceLabel(runtime.getConsultResourcePolicy())}`,
 		`Agents: ${status.activeAgents} active · ${status.retainedAgents} retained`,
 		...(configured.value !== current
 			? [`Configured after reload: ${workflowLabel(configured.value)}`]
@@ -627,6 +673,7 @@ function formatStatus(
 	runtime?: SubagentSettingsRuntime,
 ): string {
 	const configuredWorkflow = inspectDelegationWorkflowSettings();
+	const consult = inspectConsultResourceSettings();
 	const current = runtime ? currentWorkflow(runtime, status) : configuredWorkflow.value;
 	return [
 		"Current session",
@@ -640,6 +687,8 @@ function formatStatus(
 		`  Configured delegation: ${workflowLabel(configuredWorkflow.value)}`,
 		`  Completion source: ${snapshot.source}`,
 		`  Configured completion: ${completionLabel(snapshot.value)}`,
+		`  Consultation resources: ${consultResourceLabel(runtime?.getConsultResourcePolicy() ?? consult.value)}`,
+		`  Consultation resource source: ${consult.source}`,
 		`  Path: ${safeTerminalText(snapshot.path)}`,
 		configuredWorkflow.error || snapshot.error
 			? `  Warning: ${safeTerminalText(configuredWorkflow.error ?? snapshot.error ?? "invalid settings")}`
@@ -688,13 +737,28 @@ function completionLabel(value: CompletionDelivery): string {
 	return value === "auto-resume" ? "Resume automatically when finished" : "Wait until my next turn";
 }
 
+function consultResourceLabel(value: ConsultResourcePolicy): string {
+	switch (value) {
+		case "project-context":
+			return "Project context only";
+		case "none":
+			return "No inherited resources";
+		case "all":
+			return "All trusted resources";
+	}
+}
+
 function workflowEffects(current: DelegationWorkflow, next: DelegationWorkflow): string[] {
 	const blockingEnabled = (value: DelegationWorkflow) =>
 		value === "all" || value === "blocking-only";
 	const asyncEnabled = (value: DelegationWorkflow) => value === "all" || value === "async-only";
 	const effects: string[] = [];
 	if (blockingEnabled(current) !== blockingEnabled(next)) {
-		effects.push(blockingEnabled(next) ? "Add blocking `subagent`" : "Remove blocking `subagent`");
+		effects.push(
+			blockingEnabled(next)
+				? "Add blocking `subagent` and read-only `subagent_consult`"
+				: "Remove blocking `subagent` and read-only `subagent_consult`",
+		);
 	}
 	if (asyncEnabled(current) !== asyncEnabled(next)) {
 		effects.push(

package/src/consult-policy.ts

@@ -0,0 +1,15 @@
+export const READ_ONLY_CONSULT_TOOLS = ["read", "grep", "find", "ls"] as const;
+
+const READ_ONLY_CONSULT_TOOL_SET = new Set<string>(READ_ONLY_CONSULT_TOOLS);
+
+export function resolveConsultTools(tools: readonly string[] | undefined): string[] {
+	if (tools === undefined) return [...READ_ONLY_CONSULT_TOOLS];
+	const seen = new Set<string>();
+	const effective: string[] = [];
+	for (const tool of tools) {
+		if (!READ_ONLY_CONSULT_TOOL_SET.has(tool) || seen.has(tool)) continue;
+		seen.add(tool);
+		effective.push(tool);
+	}
+	return effective;
+}