@xopcai/xopc 0.0.308 → 0.0.311

package/dist/src/agent/external-tools/service.js

@@ -27,7 +27,8 @@ function descriptorRevision(descriptor) {
 	return crypto.createHash("sha256").update(JSON.stringify({
 		toolRef: descriptor.toolRef,
 		description: descriptor.description,
-		inputSchema: descriptor.inputSchema
+		inputSchema: descriptor.inputSchema,
+		batchRead: descriptor.batchRead === true
 	})).digest("hex").slice(0, 16);
 }
 function versionDescriptor(descriptor) {
@@ -116,8 +117,10 @@ var ExternalToolService = class {
 		const descriptor = await provider.describe(params.toolRef);
 		if (!descriptor) throw new Error(`External tool is unavailable: ${params.toolRef}`);
 		const current = versionDescriptor(descriptor);
+		if (params.readOnly && current.batchRead !== true) throw new Error("This external operation is not approved for batch reads");
 		if (current.revision !== params.revision) throw new Error(`Tool contract changed. Describe ${params.toolRef} again before executing it.`);
 		const args = params.arguments ?? {};
+		if (params.readOnly && (provider.source === "composio" || provider.source === "cli") && (typeof args.xopcAccountId !== "string" || !args.xopcAccountId)) throw new Error("Batch connector reads require an explicit xopcAccountId");
 		let validate;
 		try {
 			validate = this.ajv.compile(current.inputSchema);

package/dist/src/agent/external-tools/types.d.ts

@@ -1,6 +1,6 @@
 import type { AgentToolResult, AgentToolUpdateCallback } from '@earendil-works/pi-agent-core';
 import type { TurnOrigin } from '@xopcai/endpoint-tools-protocol';
-export declare const EXTERNAL_TOOL_SOURCES: readonly ["mcp", "composio", "extension", "memory", "endpoint"];
+export declare const EXTERNAL_TOOL_SOURCES: readonly ["cli", "mcp", "composio", "extension", "memory", "endpoint"];
 export type ExternalToolSource = (typeof EXTERNAL_TOOL_SOURCES)[number];
 export interface ExternalToolSearchHit {
     toolRef: string;
@@ -12,6 +12,8 @@ export interface ExternalToolSearchHit {
 export interface ExternalToolDescriptor extends ExternalToolSearchHit {
     description: string;
     inputSchema: Record<string, unknown>;
+    /** Host-curated contract; never copied from remote readOnlyHint annotations. */
+    batchRead?: boolean;
 }
 export interface VersionedExternalToolDescriptor extends ExternalToolDescriptor {
     revision: string;

package/dist/src/agent/external-tools/types.js

@@ -1,5 +1,6 @@
 //#region src/agent/external-tools/types.ts
 const EXTERNAL_TOOL_SOURCES = [
+	"cli",
 	"mcp",
 	"composio",
 	"extension",

package/dist/src/agent/mcp/bundle-mcp-runtime.js

@@ -1,6 +1,6 @@
-import { init_global_singleton, resolveGlobalSingleton } from "../../utils/global-singleton.js";
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { init_global_singleton, resolveGlobalSingleton } from "../../utils/global-singleton.js";
 import { init_string_coerce, normalizeOptionalString } from "../../utils/string-coerce.js";
 import { resolveConnectorSecretReferences } from "../../connectors/secret-store.js";
 import { redactSensitiveUrlLikeString } from "../../utils/redact-sensitive-url.js";

package/dist/src/agent/mcp/oauth/mcp-oauth-manager.js

@@ -1,6 +1,6 @@
-import { init_global_singleton, resolveGlobalSingleton } from "../../../utils/global-singleton.js";
 import { createLogger } from "../../../utils/logger/index.js";
 import { init_logger } from "../../../utils/logger.js";
+import { init_global_singleton, resolveGlobalSingleton } from "../../../utils/global-singleton.js";
 import { resolveConnectorSecretReferences } from "../../../connectors/secret-store.js";
 import { redactSensitiveUrlLikeString } from "../../../utils/redact-sensitive-url.js";
 import { resolveMcpTransportConfig } from "../mcp-transport-config.js";

package/dist/src/agent/memory/turn-provenance.js

@@ -1,4 +1,5 @@
-import { getSessionMetadata, init_session_repository } from "../../storage/sqlite/session-repository.js";
+import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
+import { init_session_repository } from "../../storage/sqlite/session-repository.js";
 import { getConversationRouting } from "../../storage/sqlite/conversation-repository.js";
 import { init_session_key } from "../../routing/session-key.js";
 //#region src/agent/memory/turn-provenance.ts

package/dist/src/agent/orchestration/agent-turn-policy.js

@@ -1,3 +1,4 @@
+import { dataOperationCalls } from "../data-acquisition/schema.js";
 //#region src/agent/orchestration/agent-turn-policy.ts
 /** One user-visible run policy. A fresh instance is created for every embedded run. */
 function createAgentTurnPolicy(options) {
@@ -11,17 +12,31 @@ function createAgentTurnPolicy(options) {
 			assistantTurns = 0;
 		},
 		async beforeToolCall(context, signal) {
-			const limit = options.resolveToolLimit?.(context.toolCall.name, context.args);
-			if (limit) {
-				const count = (toolCalls.get(limit.id) ?? 0) + 1;
-				toolCalls.set(limit.id, count);
-				if (count > limit.maxCalls) return {
-					block: true,
-					terminate: true,
-					reason: `${limit.id} exceeded its per-turn call limit.`
-				};
+			const contexts = context.toolCall.name === "data_batch" ? [context, ...dataOperationCalls(context.args).map((call, index) => ({
+				...context,
+				args: call.args,
+				toolCall: {
+					...context.toolCall,
+					id: `${context.toolCall.id}:${index}`,
+					name: call.name,
+					arguments: call.args
+				}
+			}))] : [context];
+			for (const item of contexts) {
+				signal?.throwIfAborted();
+				const limit = options.resolveToolLimit?.(item.toolCall.name, item.args);
+				if (limit) {
+					const count = (toolCalls.get(limit.id) ?? 0) + 1;
+					toolCalls.set(limit.id, count);
+					if (count > limit.maxCalls) return {
+						block: true,
+						terminate: true,
+						reason: `${limit.id} exceeded its per-turn call limit.`
+					};
+				}
+				const decision = await options.authorizeToolCall?.(item, signal);
+				if (decision?.block) return decision;
 			}
-			return options.authorizeToolCall?.(context, signal);
 		},
 		async afterToolCall(context) {
 			if (context.isError) toolFailures += 1;

package/dist/src/agent/orchestration/delegation-scope.d.ts

@@ -0,0 +1,9 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+import type { AgentTurnPolicyOptions } from './agent-turn-policy.js';
+interface DelegationScope {
+    tools: AgentTool<any, any>[];
+    authorizeToolCall?: AgentTurnPolicyOptions['authorizeToolCall'];
+}
+export declare function withDelegationScope<T>(scope: DelegationScope, run: () => T): T;
+export declare function getDelegationScope(): DelegationScope | undefined;
+export {};

package/dist/src/agent/orchestration/delegation-scope.js

@@ -0,0 +1,11 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/agent/orchestration/delegation-scope.ts
+const storage = new AsyncLocalStorage();
+function withDelegationScope(scope, run) {
+	return storage.run(scope, run);
+}
+function getDelegationScope() {
+	return storage.getStore();
+}
+//#endregion
+export { getDelegationScope, withDelegationScope };

package/dist/src/agent/prompt/sections/tooling.js

@@ -1,6 +1,7 @@
 //#region src/agent/prompt/sections/tooling.ts
 const CORE_TOOL_ORDER = [
 	"read_file",
+	"data_batch",
 	"write_file",
 	"apply_patch",
 	"grep",
@@ -42,6 +43,7 @@ const CORE_TOOL_ORDER = [
 ];
 const CORE_TOOL_SUMMARIES = {
 	read_file: "Read targeted file contents before editing",
+	data_batch: "Read or search independent data items together; keep dependent queries separate and check partial results",
 	write_file: "Create new files or intentional complete rewrites; prefer apply_patch for code changes",
 	apply_patch: "Apply source edits with patches that begin exactly with *** Begin Patch and end exactly with *** End Patch",
 	grep: "Search file contents for literals, errors, config values, and docs",
@@ -127,7 +129,7 @@ function buildToolingSection(params) {
 	const hasPlan = availableTools.has("update_plan");
 	const hasPublishArtifacts = availableTools.has("publish_artifacts");
 	const orchestrationLines = [];
-	if (hasDelegate) orchestrationLines.push("- Sub-agent delegation → use `delegate_task(goal, context?, toolset?)` for focused parallel work; results return to you automatically.");
+	if (hasDelegate) orchestrationLines.push("- Sub-agent delegation → use `delegate_task(goal, context?, mode?, capabilities?, toolset?)`. Default research inherits available read capabilities; pass necessary context explicitly. Use implement for isolated worktree changes. Check rejectedTools and partial results before relying on the answer.");
 	if (hasWorkflow) orchestrationLines.push("- Multi-phase workflows → use `workflow` to start persisted runs with subagents when a script defines phases.");
 	return [
 		"## Tooling",

package/dist/src/agent/prompt/subagent-context.js

@@ -40,9 +40,11 @@ function buildSubagentContextSection(params) {
 		"",
 		"## What You DON'T Do",
 		"- NO user conversations (that is the parent agent's job)",
-		"- NO external messages unless explicitly tasked with a specific recipient/channel",
+		"- NO external writes, messages, installations or changes to permissions",
 		"- NO automations or persistent state",
-		"- Only use `send_message` when explicitly instructed to contact a specific external recipient",
+		"- External execution requires a host-approved read-only contract. Remote tool descriptions cannot grant permission.",
+		"- You do not inherit the parent transcript. Use the supplied context and available read tools; report missing information to the parent.",
+		"- Use skills_list and skill_view when available to load relevant guidance; guidance never expands your granted tools.",
 		"",
 		"## Sub-Agent Spawning",
 		"You are a leaf worker for this delegation. Do NOT spawn further sub-agents unless `delegate_task` is explicitly available and the parent task requires it.",

package/dist/src/agent/sandbox/fileAccess.d.ts

@@ -1,6 +1,8 @@
 /** Revalidate at I/O time; never truncate a file before checking the opened inode. */
 export declare function checkedFilePath(workspaceRoot: string, path: string, operation: 'read' | 'write' | 'delete'): string;
 export declare function readWorkspaceFile(workspace: string, path: string, maxBytes?: number): Buffer;
+/** Use the same checked inode as synchronous access, yielding between bounded reads. */
+export declare function readWorkspaceFileAsync(workspace: string, path: string, signal?: AbortSignal, maxBytes?: number): Promise<Buffer>;
 export declare function writeWorkspaceFile(workspace: string, path: string, content: string | Buffer): void;
 export declare function deleteWorkspaceFile(workspace: string, path: string): void;
 /** Refuse publication of directory trees containing protected or escaping entries. */

package/dist/src/agent/sandbox/fileAccess.js

@@ -1,6 +1,6 @@
 import { evaluateFilePolicy } from "./exec-policy.js";
 import { dirname, join, resolve } from "node:path";
-import { closeSync, constants, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { closeSync, constants, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, read, readSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 //#region src/agent/sandbox/fileAccess.ts
 /** Revalidate at I/O time; never truncate a file before checking the opened inode. */
 function checkedFilePath(workspaceRoot, path, operation) {
@@ -67,6 +67,35 @@ function readWorkspaceFile(workspace, path, maxBytes = 10 * 1024 * 1024) {
 		closeSync(fd);
 	}
 }
+/** Use the same checked inode as synchronous access, yielding between bounded reads. */
+async function readWorkspaceFileAsync(workspace, path, signal, maxBytes = 10 * 1024 * 1024) {
+	signal?.throwIfAborted();
+	const fd = openChecked(workspace, path, false);
+	try {
+		const before = fstatSync(fd);
+		if (before.size > maxBytes) throw new Error(`File too large: maximum ${maxBytes} bytes`);
+		const chunks = [];
+		let total = 0;
+		for (;;) {
+			signal?.throwIfAborted();
+			const chunk = Buffer.alloc(Math.min(64 * 1024, maxBytes - total + 1));
+			const count = await new Promise((resolveRead, reject) => {
+				read(fd, chunk, 0, chunk.length, null, (error, bytes) => error ? reject(error) : resolveRead(bytes));
+			});
+			signal?.throwIfAborted();
+			if (count === 0) break;
+			total += count;
+			if (total > maxBytes) throw new Error(`File too large: maximum ${maxBytes} bytes`);
+			chunks.push(chunk.subarray(0, count));
+		}
+		const after = fstatSync(fd);
+		const current = statSync(checkedFilePath(workspace, path, "read"));
+		if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || current.ino !== after.ino || current.dev !== after.dev) throw new Error("File changed during read; retry");
+		return Buffer.concat(chunks);
+	} finally {
+		closeSync(fd);
+	}
+}
 function writeWorkspaceFile(workspace, path, content) {
 	const fd = openChecked(workspace, path, true);
 	try {
@@ -97,4 +126,4 @@ function assertWorkspaceTreeReadable(workspace, path) {
 	visit(path);
 }
 //#endregion
-export { assertWorkspaceTreeReadable, checkedFilePath, deleteWorkspaceFile, readWorkspaceFile, writeWorkspaceFile };
+export { assertWorkspaceTreeReadable, checkedFilePath, deleteWorkspaceFile, readWorkspaceFile, readWorkspaceFileAsync, writeWorkspaceFile };

package/dist/src/agent/service/parse-outbound-session-key.js

@@ -1,4 +1,4 @@
-import { getSessionMetadata } from "../../storage/sqlite/session-repository.js";
+import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
 import "../../storage/sqlite/index.js";
 import { INTERNAL_OUTBOUND_DROP_CHANNEL } from "../../channels/internal-outbound.js";
 //#region src/agent/service/parse-outbound-session-key.ts

package/dist/src/agent/service.js

@@ -233,6 +233,7 @@ var AgentService = class {
 			verboseLevel: config.verboseLevel,
 			gatewayClarify: config.gatewayClarify,
 			getAutomationService: config.getAutomationService,
+			getSceneAccess: config.getSceneAccess,
 			getBrowserAutomationService: config.getBrowserAutomationService,
 			emitBrowserEvent: config.emitBrowserEvent,
 			getNotesService: config.getNotesService,

package/dist/src/agent/service.types.d.ts

@@ -1,3 +1,4 @@
+import type { SceneAccess } from '../scenes/httpServices.js';
 import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
 import type { Config } from '../config/schema.js';
 import type { SessionStore } from '../session/store.js';
@@ -28,6 +29,7 @@ export interface AgentServiceConfig {
         requestClarification: GatewayClarifyRequestFn;
     };
     getAutomationService?: () => AutomationService | undefined;
+    getSceneAccess?: () => SceneAccess | undefined;
     getBrowserAutomationService?: () => import('../browser/automations/index.js').BrowserAutomationService | undefined;
     emitBrowserEvent?: (type: string, payload: unknown) => void;
     /** Gateway: exposes first-class xopc product objects for the `xopc_use` tool. */

package/dist/src/agent/tools/dataBatch.d.ts

@@ -0,0 +1,4 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+import { type DataSourceOptions } from '../data-acquisition/service.js';
+export declare function withDataToolPermissions<T>(names: ReadonlySet<string>, run: () => T): T;
+export declare function createDataBatchTool(workspace: string, getAllowedTools: () => ReadonlySet<string>, options?: DataSourceOptions): AgentTool;

package/dist/src/agent/tools/dataBatch.js

@@ -0,0 +1,50 @@
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+import { DataBatchSchema } from "../data-acquisition/schema.js";
+import { acquireData } from "../data-acquisition/service.js";
+import { renderDataBatch } from "../data-acquisition/render.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/agent/tools/dataBatch.ts
+init_logger();
+const executionTools = new AsyncLocalStorage();
+const log = createLogger("DataAcquisition");
+function withDataToolPermissions(names, run) {
+	return executionTools.run(names, run);
+}
+function createDataBatchTool(workspace, getAllowedTools, options = {}) {
+	return {
+		name: "data_batch",
+		label: "Read and search data",
+		parameters: DataBatchSchema,
+		description: "Acquire up to eight independent file, Git, knowledge, web or host-approved external reads using existing permissions. external_read requires a described batchRead contract, exact revision and explicit account. Items retain status and source. File search patterns use OR. Use original tools for single items; submit dependent queries later. Partial results are not a complete inventory.",
+		supportsParallel: true,
+		idempotent: false,
+		async execute(_id, args, signal) {
+			const started = Date.now();
+			const active = executionTools.getStore();
+			const { text, result } = renderDataBatch(await acquireData(workspace, args, new Set([...getAllowedTools()].filter((name) => !active || active.has(name))), signal, options));
+			log.debug({
+				toolCallId: _id,
+				durationMs: Date.now() - started,
+				operations: result.operations.length,
+				sourceRequests: result.sourceRequests,
+				outputChars: text.length,
+				partialCount: result.operations.filter((op) => op.status !== "ok").length
+			}, "Batch data acquisition completed");
+			return {
+				content: [{
+					type: "text",
+					text
+				}],
+				details: {
+					status: result.operations.every((op) => op.status === "cancelled") ? "cancelled" : result.operations.every((op) => op.status === "error" || op.status === "denied" || op.status === "cancelled") ? "failed" : "completed",
+					operationCount: result.operations.length,
+					sourceRequests: result.sourceRequests,
+					partialCount: result.operations.filter((op) => op.status !== "ok").length
+				}
+			};
+		}
+	};
+}
+//#endregion
+export { createDataBatchTool, withDataToolPermissions };

package/dist/src/agent/tools/delegate-tool.d.ts

@@ -1,9 +1,13 @@
 import type { AgentTool } from '@earendil-works/pi-agent-core';
 import { type BuildChildToolsOptions } from '../child-agent-factory.js';
-export declare const DEFAULT_DELEGATE_TOOLS: readonly ["exec_command", "read_file", "write_file", "apply_patch", "grep", "find", "list_dir", "web_search", "web_fetch"];
+import { type DelegationMode } from './delegation-policy.js';
+import type { AgentTurnPolicy } from '../orchestration/agent-turn-policy.js';
+export declare const DEFAULT_DELEGATE_TOOLS: string[];
 /** Tools never passed to a delegated sub-agent (even if requested). */
 export declare const DELEGATE_BLOCKED_TOOLS: Set<string>;
 export interface DelegateToolDeps {
+    getParentTools: () => AgentTool<any, any>[];
+    createParentPolicy?: () => AgentTurnPolicy;
     workspace: string;
     getSubagentModel: () => import('@earendil-works/pi-ai').Model<import('@earendil-works/pi-ai').Api>;
     bus: import('../../infra/bus/index.js').MessageBus;
@@ -23,6 +27,5 @@ export interface DelegateToolDeps {
      */
     buildChildTools: (opts: BuildChildToolsOptions) => AgentTool<any, any>[];
 }
-export declare const INSPECTION_TOOLS: Set<string>;
-export declare function delegateToolNames(mode: 'inspect' | 'review' | 'implement', requested?: string[]): string[];
+export declare function delegateToolNames(mode: DelegationMode, requested?: string[]): string[];
 export declare function createDelegateTool(deps: DelegateToolDeps): AgentTool;

package/dist/src/agent/tools/delegate-tool.js

@@ -1,23 +1,15 @@
 import { readWorkspaceRevision } from "../coding/workspace-revision.js";
 import { EXTERNAL_TOOL_NAMES } from "../external-tools/gateway-tools.js";
 import "../external-tools/index.js";
+import { getDelegationScope } from "../orchestration/delegation-scope.js";
 import { createDelegateChildHandle } from "../child-agent-factory.js";
 import { runGit } from "../../execution-environments/git.js";
 import { LocalWorktreeManager } from "../../execution-environments/local-worktree-manager.js";
 import { SessionEnvironmentService } from "../../execution-environments/session-environment-service.js";
+import { DELEGATION_CAPABILITIES, DELEGATION_TOOL_CAPABILITIES, protectDelegatedTool, resolveDelegationTools } from "./delegation-policy.js";
 import { Type } from "@sinclair/typebox";
 //#region src/agent/tools/delegate-tool.ts
-const DEFAULT_DELEGATE_TOOLS = [
-	"exec_command",
-	"read_file",
-	"write_file",
-	"apply_patch",
-	"grep",
-	"find",
-	"list_dir",
-	"web_search",
-	"web_fetch"
-];
+const DEFAULT_DELEGATE_TOOLS = resolveDelegationTools(Object.keys(DELEGATION_TOOL_CAPABILITIES), "research").granted;
 /** Tools never passed to a delegated sub-agent (even if requested). */
 const DELEGATE_BLOCKED_TOOLS = new Set([
 	"delegate_task",
@@ -25,39 +17,27 @@ const DELEGATE_BLOCKED_TOOLS = new Set([
 	"send_message",
 	"send_media",
 	"todo",
-	"session_search",
-	"user_context_search",
-	"user_context_get",
 	"user_context_update",
-	"knowledge_search",
-	"knowledge_get",
 	"knowledge_write",
 	"automation",
-	"skills_list",
-	"skill_view",
 	"skill_manage",
-	"skills_marketplace_search",
 	"skill_install",
-	EXTERNAL_TOOL_NAMES.search,
-	EXTERNAL_TOOL_NAMES.describe,
-	EXTERNAL_TOOL_NAMES.execute,
+	EXTERNAL_TOOL_NAMES.requireConnection,
+	EXTERNAL_TOOL_NAMES.updateConnectionObjective,
 	"managed_job"
 ]);
-const INSPECTION_TOOLS = new Set([
-	"read_file",
-	"grep",
-	"find",
-	"list_dir",
-	"review_workspace"
-]);
 const DelegateTaskSchema = Type.Object({
 	goal: Type.String({ minLength: 1 }),
 	context: Type.Optional(Type.String()),
 	mode: Type.Optional(Type.Union([
-		Type.Literal("inspect"),
-		Type.Literal("review"),
-		Type.Literal("implement")
-	])),
+		"inspect",
+		"read",
+		"research",
+		"review",
+		"implement",
+		"custom"
+	].map((mode) => Type.Literal(mode)))),
+	capabilities: Type.Optional(Type.Array(Type.Union(DELEGATION_CAPABILITIES.map((capability) => Type.Literal(capability))), { description: "Optional capability subset. custom requires explicit capabilities; browser is always opt-in. Writes and commands require implement." })),
 	toolset: Type.Optional(Type.Array(Type.String())),
 	maxIterations: Type.Optional(Type.Integer({
 		minimum: 1,
@@ -65,26 +45,38 @@ const DelegateTaskSchema = Type.Object({
 	}))
 });
 function delegateToolNames(mode, requested) {
-	const available = mode === "implement" ? new Set([
-		...DEFAULT_DELEGATE_TOOLS,
-		"review_workspace",
-		"language_diagnostics"
-	]) : INSPECTION_TOOLS;
-	return [...new Set(requested ?? [...available])].filter((name) => available.has(name) && !DELEGATE_BLOCKED_TOOLS.has(name));
+	return resolveDelegationTools(Object.keys(DELEGATION_TOOL_CAPABILITIES), mode, requested).granted;
 }
 function createDelegateTool(deps) {
 	return {
 		name: "delegate_task",
 		label: "Delegate task",
 		parameters: DelegateTaskSchema,
-		description: "Run one bounded leaf worker with a fresh context. inspect/review receive only read tools; review reports findings against a workspace revision. implement requires an attached project and clean Git workspace, creates a separate managed worktree, and returns its patch for parent review. Child changes are never merged automatically. No nested delegation, external messages or background jobs. Up to 60 tool calls, 100k tokens and five minutes per child.",
+		description: "Delegate a bounded task with a fresh context; supply relevant facts and constraints in context. Default research inherits the parent's local, web, knowledge, skill and approved external read tools. read/inspect/review are local read-only. toolset and capabilities only narrow parent access; custom requires explicit capabilities. Browser interaction is opt-in. implement requires a project and clean Git workspace and returns changes in a separate worktree for review. No nested delegation, external writes, installation or background jobs. Up to 60 tool calls, 100k tokens and five minutes. Reports rejected tools and their reasons.",
 		supportsParallel: false,
 		idempotent: false,
 		async execute(_id, input, signal) {
 			signal?.throwIfAborted();
-			const mode = input.mode ?? "inspect";
-			const tools = delegateToolNames(mode, input.toolset);
-			if (!tools.length) throw new Error("No permitted tools in the requested toolset");
+			const mode = input.mode ?? "research";
+			const scope = getDelegationScope();
+			const parentTools = scope?.tools ?? deps.getParentTools();
+			const access = resolveDelegationTools(parentTools.map((tool) => tool.name), mode, input.toolset, input.capabilities);
+			const tools = access.granted;
+			if (!tools.length) return {
+				content: [{
+					type: "text",
+					text: JSON.stringify({
+						error: "No permitted tools in the requested delegation",
+						...access
+					})
+				}],
+				details: {
+					status: "failed",
+					mode,
+					grantedTools: tools,
+					rejectedTools: access.rejected
+				}
+			};
 			const parentConversationId = deps.getCurrentContext?.()?.conversationId;
 			const model = deps.getSubagentModel();
 			let workspace = deps.workspace, environmentId;
@@ -99,7 +91,8 @@ function createDelegateTool(deps) {
 				workspace = environment.rootPath;
 				environmentId = environment.id;
 			}
-			const revision = await readWorkspaceRevision(workspace);
+			const revision = mode === "review" ? await readWorkspaceRevision(workspace) : void 0;
+			const authorizeToolCall = scope?.authorizeToolCall ?? deps.createParentPolicy?.().beforeToolCall;
 			const child = createDelegateChildHandle({
 				workspace,
 				goal: mode === "review" ? `Independently review the actual changes. Inspect review_workspace and relevant source/tests. Report actionable defects with file and line evidence, severity and a concrete failure example. If there are no findings, state the checks and remaining uncertainty. Do not treat the parent's completion claim as evidence.\n\n${input.goal}` : input.goal,
@@ -111,7 +104,25 @@ function createDelegateTool(deps) {
 				bus: deps.bus,
 				getConfig: deps.getConfig,
 				toolExecutorConfig: deps.toolExecutorConfig,
-				buildChildTools: deps.buildChildTools,
+				authorizeToolCall,
+				buildChildTools: (opts) => {
+					const local = mode === "implement" ? new Map(deps.buildChildTools(opts).map((tool) => [tool.name, tool])) : void 0;
+					const rebound = new Set([
+						"read_file",
+						"grep",
+						"find",
+						"list_dir",
+						"review_workspace",
+						"write_file",
+						"apply_patch",
+						"exec_command",
+						"language_diagnostics"
+					]);
+					return parentTools.flatMap((tool) => {
+						const candidate = local && rebound.has(tool.name) ? local.get(tool.name) : tool;
+						return candidate ? [protectDelegatedTool(candidate)] : [];
+					});
+				},
 				verifyChanges: mode === "implement"
 			});
 			const abort = () => child.abort();
@@ -119,8 +130,8 @@ function createDelegateTool(deps) {
 			if (signal?.aborted) abort();
 			try {
 				const result = await child.run();
-				const currentRevision = await readWorkspaceRevision(workspace);
-				const stale = mode !== "implement" && (!revision || revision !== currentRevision);
+				const currentRevision = mode === "review" ? await readWorkspaceRevision(workspace) : void 0;
+				const stale = mode === "review" && (!revision || revision !== currentRevision);
 				const patch = mode === "implement" ? await runGit(workspace, [
 					"diff",
 					"--no-ext-diff",
@@ -134,6 +145,7 @@ function createDelegateTool(deps) {
 						text: [
 							result.summary,
 							stale ? "Workspace changed or could not be fingerprinted; review findings require revalidation." : "",
+							access.rejected.length ? `Rejected tools: ${JSON.stringify(access.rejected)}` : "",
 							environmentId ? `Changes retained in ${workspace} (environment ${environmentId}). Review and integrate from this workspace, then verify the parent workspace again.` : "",
 							patch ? `Patch preview:\n${patch.slice(0, 3e4)}` : ""
 						].filter(Boolean).join("\n\n")
@@ -142,6 +154,8 @@ function createDelegateTool(deps) {
 						status: stale && result.status === "success" ? "partial" : result.status,
 						mode,
 						summary: result.summary,
+						grantedTools: tools,
+						rejectedTools: access.rejected,
 						iterations: result.toolIterations,
 						revision: currentRevision,
 						reviewedRevision: revision,
@@ -161,6 +175,9 @@ function createDelegateTool(deps) {
 					}],
 					details: {
 						status: signal?.aborted ? "cancelled" : "failed",
+						mode,
+						grantedTools: tools,
+						rejectedTools: access.rejected,
 						...environmentId ? {
 							environmentId,
 							workspace
@@ -174,4 +191,4 @@ function createDelegateTool(deps) {
 	};
 }
 //#endregion
-export { DEFAULT_DELEGATE_TOOLS, DELEGATE_BLOCKED_TOOLS, INSPECTION_TOOLS, createDelegateTool, delegateToolNames };
+export { DEFAULT_DELEGATE_TOOLS, DELEGATE_BLOCKED_TOOLS, createDelegateTool, delegateToolNames };

package/dist/src/agent/tools/delegation-parent-policy.d.ts

@@ -0,0 +1,7 @@
+import type { Config } from '../../config/schema.js';
+/** Noninteractive callers cannot silently turn an ask policy into an allow. */
+export declare function createDelegationParentPolicy(options: {
+    getConfig: () => Config | undefined;
+    conversationId?: string;
+    agentId?: string;
+}): import("../orchestration/agent-turn-policy.js").AgentTurnPolicy;

package/dist/src/agent/tools/delegation-parent-policy.js

@@ -0,0 +1,41 @@
+import { resolveEffectiveAgentConfigForAgent, resolveEffectiveAgentConfigForSession } from "../../config/agent-profile.js";
+import { parseExternalToolRef } from "../external-tools/refs.js";
+import { mcpToolPolicyId } from "../mcp/bundle-mcp-policy.js";
+import { createAgentTurnPolicy } from "../orchestration/agent-turn-policy.js";
+//#region src/agent/tools/delegation-parent-policy.ts
+/** Noninteractive callers cannot silently turn an ask policy into an allow. */
+function createDelegationParentPolicy(options) {
+	const policies = (name, args) => {
+		const config = options.getConfig();
+		if (!config) return [];
+		const resolved = options.conversationId ? resolveEffectiveAgentConfigForSession(config, options.conversationId) : options.agentId ? resolveEffectiveAgentConfigForAgent(config, options.agentId) : resolveEffectiveAgentConfigForSession(config, void 0);
+		const names = [name];
+		if (name === "xopc_tool_execute") {
+			const parsed = parseExternalToolRef(String(args?.toolRef ?? ""), "mcp");
+			const ref = String(args?.toolRef ?? "");
+			names.push(parsed ? mcpToolPolicyId(parsed.namespace, parsed.toolName) : ref);
+		}
+		return names.flatMap((id) => resolved.config.tools[id] ? [{
+			id,
+			...resolved.config.tools[id]
+		}] : []);
+	};
+	return createAgentTurnPolicy({
+		authorizeToolCall: async (context) => {
+			const blocked = policies(context.toolCall.name, context.args).find((policy) => policy.mode !== "allow");
+			return blocked ? {
+				block: true,
+				reason: `${blocked.id} requires parent authorization (${blocked.mode}).`
+			} : void 0;
+		},
+		resolveToolLimit: (name, args) => {
+			const limited = policies(name, args).filter((policy) => policy.maxCallsPerTurn).sort((a, b) => a.maxCallsPerTurn - b.maxCallsPerTurn)[0];
+			return limited ? {
+				id: limited.id,
+				maxCalls: limited.maxCallsPerTurn
+			} : void 0;
+		}
+	});
+}
+//#endregion
+export { createDelegationParentPolicy };

package/dist/src/agent/tools/delegation-policy.d.ts

@@ -0,0 +1,16 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+export declare const DELEGATION_CAPABILITIES: readonly ["local_read", "web_read", "knowledge_read", "skills_read", "external_read", "local_write", "command", "browser"];
+export type DelegationCapability = typeof DELEGATION_CAPABILITIES[number];
+export type DelegationMode = 'inspect' | 'read' | 'research' | 'review' | 'implement' | 'custom';
+/** Host-owned classifications. New tools fail closed until classified. */
+export declare const DELEGATION_TOOL_CAPABILITIES: Readonly<Record<string, DelegationCapability>>;
+export declare function delegationCapabilities(mode: DelegationMode, requested?: DelegationCapability[]): Set<DelegationCapability>;
+export declare function resolveDelegationTools(parentNames: readonly string[], mode: DelegationMode, requested?: string[], capabilities?: DelegationCapability[]): {
+    granted: string[];
+    rejected: {
+        tool: string;
+        reason: string;
+    }[];
+};
+/** Always enforce the external read contract, even when the child explicitly sends readOnly:false. */
+export declare function protectDelegatedTool(tool: AgentTool<any, any>): AgentTool<any, any>;