pi-subagents 0.57.0 → 0.58.0

package/src/agents/agents.ts

@@ -62,6 +62,7 @@ export interface BuiltinAgentOverrideBase {
 	thinking?: string | false;
 	systemPromptMode: SystemPromptMode;
 	inheritProjectContext: boolean;
+	inheritGlobalContext: boolean;
 	inheritSkills: boolean;
 	defaultContext?: AgentDefaultContext;
 	acceptanceRole?: AcceptanceRole;
@@ -73,6 +74,7 @@ export interface BuiltinAgentOverrideBase {
 	mcpDirectTools?: string[];
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
+	mutationTools?: string[];
 	completionGuard?: boolean;
 	toolBudget?: ToolBudgetConfig;
 }
@@ -89,6 +91,7 @@ interface BuiltinAgentOverrideConfig {
 	thinking?: string | false;
 	systemPromptMode?: SystemPromptMode;
 	inheritProjectContext?: boolean;
+	inheritGlobalContext?: boolean;
 	inheritSkills?: boolean;
 	defaultContext?: AgentDefaultContext | false;
 	acceptanceRole?: AcceptanceRole | false;
@@ -98,6 +101,7 @@ interface BuiltinAgentOverrideConfig {
 	tools?: string[] | false | "inherit";
 	extensions?: string[] | false;
 	subagentOnlyExtensions?: string[] | false;
+	mutationTools?: string[] | false;
 	completionGuard?: boolean;
 	toolBudget?: ToolBudgetConfig | false;
 }
@@ -135,6 +139,7 @@ export interface AgentConfig {
 	thinking?: string | false;
 	systemPromptMode: SystemPromptMode;
 	inheritProjectContext: boolean;
+	inheritGlobalContext: boolean;
 	inheritSkills: boolean;
 	defaultContext?: AgentDefaultContext;
 	defaultAsync?: boolean;
@@ -152,6 +157,7 @@ export interface AgentConfig {
 	extensions?: string[];
 	extensionsFromDefault?: boolean;
 	subagentOnlyExtensions?: string[];
+	mutationTools?: string[];
 	output?: string;
 	outputMode?: OutputMode;
 	defaultReads?: string[];
@@ -710,6 +716,7 @@ function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
 		...(agent.thinking !== undefined ? { thinking: agent.thinking } : {}),
 		systemPromptMode: agent.systemPromptMode,
 		inheritProjectContext: agent.inheritProjectContext,
+		inheritGlobalContext: agent.inheritGlobalContext,
 		inheritSkills: agent.inheritSkills,
 		...(agent.defaultContext !== undefined ? { defaultContext: agent.defaultContext } : {}),
 		...(agent.acceptanceRole !== undefined ? { acceptanceRole: agent.acceptanceRole } : {}),
@@ -721,6 +728,7 @@ function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
 		...(agent.mcpDirectTools ? { mcpDirectTools: [...agent.mcpDirectTools] } : {}),
 		...(!agent.extensionsFromDefault && agent.extensions ? { extensions: [...agent.extensions] } : {}),
 		...(agent.subagentOnlyExtensions ? { subagentOnlyExtensions: [...agent.subagentOnlyExtensions] } : {}),
+		...(agent.mutationTools ? { mutationTools: [...agent.mutationTools] } : {}),
 		...(agent.completionGuard !== undefined ? { completionGuard: agent.completionGuard } : {}),
 		...(agent.toolBudget !== undefined ? { toolBudget: agent.toolBudget } : {}),
 	};
@@ -741,6 +749,7 @@ function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentO
 		...(override.thinking !== undefined ? { thinking: override.thinking } : {}),
 		...(override.systemPromptMode !== undefined ? { systemPromptMode: override.systemPromptMode } : {}),
 		...(override.inheritProjectContext !== undefined ? { inheritProjectContext: override.inheritProjectContext } : {}),
+		...(override.inheritGlobalContext !== undefined ? { inheritGlobalContext: override.inheritGlobalContext } : {}),
 		...(override.inheritSkills !== undefined ? { inheritSkills: override.inheritSkills } : {}),
 		...(override.defaultContext !== undefined ? { defaultContext: override.defaultContext } : {}),
 		...(override.acceptanceRole !== undefined ? { acceptanceRole: override.acceptanceRole } : {}),
@@ -750,6 +759,7 @@ function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentO
 		...(override.tools !== undefined ? { tools: Array.isArray(override.tools) ? [...override.tools] : override.tools } : {}),
 		...(override.extensions !== undefined ? { extensions: override.extensions === false ? false : [...override.extensions] } : {}),
 		...(override.subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions: override.subagentOnlyExtensions === false ? false : [...override.subagentOnlyExtensions] } : {}),
+		...(override.mutationTools !== undefined ? { mutationTools: override.mutationTools === false ? false : [...override.mutationTools] } : {}),
 		...(override.completionGuard !== undefined ? { completionGuard: override.completionGuard } : {}),
 		...(override.toolBudget !== undefined ? { toolBudget: override.toolBudget === false ? false : { ...override.toolBudget, ...(Array.isArray(override.toolBudget.block) ? { block: [...override.toolBudget.block] } : {}) } } : {}),
 	};
@@ -799,7 +809,7 @@ export function findNearestProjectRoot(cwd: string): string | null {
 	return findProjectRootCandidates(cwd)[0] ?? null;
 }
 
-function findConfiguredProjectRoot(cwd: string): string | null {
+export function findConfiguredProjectRoot(cwd: string): string | null {
 	const candidates = findProjectRootCandidates(cwd);
 	const nearestRoot = candidates[0];
 	if (!nearestRoot) return null;
@@ -958,6 +968,14 @@ function parseBuiltinOverrideEntry(
 		}
 	}
 
+	if ("inheritGlobalContext" in input) {
+		if (typeof input.inheritGlobalContext === "boolean") {
+			override.inheritGlobalContext = input.inheritGlobalContext;
+		} else {
+			throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'inheritGlobalContext'; expected a boolean.`);
+		}
+	}
+
 	if ("inheritSkills" in input) {
 		if (typeof input.inheritSkills === "boolean") {
 			override.inheritSkills = input.inheritSkills;
@@ -1037,6 +1055,9 @@ function parseBuiltinOverrideEntry(
 	const subagentOnlyExtensions = parseOverrideStringArrayOrFalse(input.subagentOnlyExtensions, { filePath, name, field: "subagentOnlyExtensions" });
 	if (subagentOnlyExtensions !== undefined) override.subagentOnlyExtensions = subagentOnlyExtensions;
 
+	const mutationTools = parseOverrideStringArrayOrFalse(input.mutationTools, { filePath, name, field: "mutationTools" });
+	if (mutationTools !== undefined) override.mutationTools = mutationTools;
+
 	return Object.keys(override).length > 0 ? override : undefined;
 }
 
@@ -1272,6 +1293,7 @@ function applyBuiltinOverride(
 	if (override.thinking !== undefined) { if (override.thinking === false) delete next.thinking; else next.thinking = override.thinking; }
 	if (override.systemPromptMode !== undefined) next.systemPromptMode = override.systemPromptMode;
 	if (override.inheritProjectContext !== undefined) next.inheritProjectContext = override.inheritProjectContext;
+	if (override.inheritGlobalContext !== undefined) next.inheritGlobalContext = override.inheritGlobalContext;
 	if (override.inheritSkills !== undefined) next.inheritSkills = override.inheritSkills;
 	if (override.defaultContext !== undefined) { if (override.defaultContext === false) delete next.defaultContext; else next.defaultContext = override.defaultContext; }
 	if (override.acceptanceRole !== undefined) { if (override.acceptanceRole === false) delete next.acceptanceRole; else next.acceptanceRole = override.acceptanceRole; }
@@ -1281,6 +1303,7 @@ function applyBuiltinOverride(
 	if (override.tools !== undefined) applyToolsOverride(next, override.tools);
 	if (override.extensions !== undefined) { if (override.extensions === false) delete next.extensions; else next.extensions = [...override.extensions]; }
 	if (override.subagentOnlyExtensions !== undefined) { if (override.subagentOnlyExtensions === false) delete next.subagentOnlyExtensions; else next.subagentOnlyExtensions = [...override.subagentOnlyExtensions]; }
+	if (override.mutationTools !== undefined) { if (override.mutationTools === false) delete next.mutationTools; else next.mutationTools = [...override.mutationTools]; }
 	if (override.completionGuard !== undefined) next.completionGuard = override.completionGuard;
 	if (override.toolBudget !== undefined) { if (override.toolBudget === false) delete next.toolBudget; else next.toolBudget = override.toolBudget; }
 
@@ -1418,6 +1441,9 @@ function applyCustomAgentOverride(
 	if (override.inheritProjectContext !== undefined) {
 		fill("inheritProjectContext", ["inheritProjectContext"], override.inheritProjectContext);
 	}
+	if (override.inheritGlobalContext !== undefined) {
+		fill("inheritGlobalContext", ["inheritGlobalContext"], override.inheritGlobalContext);
+	}
 	if (override.inheritSkills !== undefined) {
 		fill("inheritSkills", ["inheritSkills"], override.inheritSkills);
 	}
@@ -1449,6 +1475,9 @@ function applyCustomAgentOverride(
 			override.subagentOnlyExtensions === false ? undefined : [...override.subagentOnlyExtensions],
 		);
 	}
+	if (override.mutationTools !== undefined) {
+		fill("mutationTools", ["mutationTools"], override.mutationTools === false ? undefined : [...override.mutationTools]);
+	}
 	if (override.completionGuard !== undefined) {
 		fill("completionGuard", ["completionGuard"], override.completionGuard);
 	}
@@ -1488,7 +1517,7 @@ function applyCustomAgentOverrides(
 
 export function buildBuiltinOverrideConfig(
 	base: BuiltinAgentOverrideBase,
-	draft: Pick<AgentConfig, "model" | "modelProvider" | "fallbackModels" | "fast" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "acceptanceRole" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "extensions" | "subagentOnlyExtensions" | "completionGuard" | "toolBudget"> & Partial<Pick<AgentConfig, "description" | "output" | "outputMode" | "defaultReads">>,
+	draft: Pick<AgentConfig, "model" | "modelProvider" | "fallbackModels" | "fast" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritGlobalContext" | "inheritSkills" | "defaultContext" | "acceptanceRole" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "extensions" | "subagentOnlyExtensions" | "mutationTools" | "completionGuard" | "toolBudget"> & Partial<Pick<AgentConfig, "description" | "output" | "outputMode" | "defaultReads">>,
 ): BuiltinAgentOverrideConfig | undefined {
 	const override: BuiltinAgentOverrideConfig = {};
 
@@ -1506,6 +1535,7 @@ export function buildBuiltinOverrideConfig(
 	if (draft.thinking !== base.thinking) override.thinking = draft.thinking ?? false;
 	if (draft.systemPromptMode !== base.systemPromptMode) override.systemPromptMode = draft.systemPromptMode;
 	if (draft.inheritProjectContext !== base.inheritProjectContext) override.inheritProjectContext = draft.inheritProjectContext;
+	if (draft.inheritGlobalContext !== base.inheritGlobalContext) override.inheritGlobalContext = draft.inheritGlobalContext;
 	if (draft.inheritSkills !== base.inheritSkills) override.inheritSkills = draft.inheritSkills;
 	if (draft.defaultContext !== base.defaultContext) override.defaultContext = draft.defaultContext ?? false;
 	if (draft.acceptanceRole !== base.acceptanceRole) override.acceptanceRole = draft.acceptanceRole ?? false;
@@ -1520,6 +1550,7 @@ export function buildBuiltinOverrideConfig(
 	if (!arraysEqual(draft.subagentOnlyExtensions, base.subagentOnlyExtensions)) {
 		override.subagentOnlyExtensions = draft.subagentOnlyExtensions ? [...draft.subagentOnlyExtensions] : false;
 	}
+	if (!arraysEqual(draft.mutationTools, base.mutationTools)) override.mutationTools = draft.mutationTools ? [...draft.mutationTools] : false;
 	if ((draft.completionGuard !== false) !== (base.completionGuard !== false)) {
 		override.completionGuard = draft.completionGuard !== false;
 	}
@@ -1863,7 +1894,7 @@ function parseAgentRunnerFrontmatter(raw: string | undefined, agentName: string)
 
 function validateExternalRunnerProfile(frontmatter: Record<string, string>, agentName: string, runner: AgentRunnerConfig | undefined): void {
 	if (runner?.type !== "external-cli" && runner?.type !== "external-job") return;
-	const unsupported = ["tools", "model", "fallbackModels", "thinking", "extensions", "subagentOnlyExtensions", "maxSubagentDepth", "completionGuard", "skills", "skill", "skillPath", "toolBudget", "permission", "permissions"]
+	const unsupported = ["tools", "model", "fallbackModels", "thinking", "extensions", "subagentOnlyExtensions", "mutationTools", "maxSubagentDepth", "completionGuard", "skills", "skill", "skillPath", "toolBudget", "permission", "permissions"]
 		.filter((field) => frontmatter[field] !== undefined);
 	if (unsupported.length > 0) {
 		throw new Error(`Agent '${agentName}' uses runner.type='${runner.type}' and declares unsupported Pi-only fields: ${unsupported.join(", ")}.`);
@@ -1963,6 +1994,7 @@ function loadAgentsFromDefinitionFiles(files: AgentDefinitionFile[], source: Age
 			: frontmatter.inheritProjectContext === "false"
 				? false
 				: defaultInheritProjectContext(localName);
+		const inheritGlobalContext = frontmatter.inheritGlobalContext === "true";
 		const inheritSkills = frontmatter.inheritSkills === "true"
 			? true
 			: frontmatter.inheritSkills === "false"
@@ -2016,6 +2048,7 @@ function loadAgentsFromDefinitionFiles(files: AgentDefinitionFile[], source: Age
 
 		const extensions = resolveAgentRelativeExtensionPaths(parseFrontmatterList(frontmatter.extensions), filePath);
 		const subagentOnlyExtensions = resolveAgentRelativeExtensionPaths(parseFrontmatterList(frontmatter.subagentOnlyExtensions), filePath);
+		const mutationTools = parseFrontmatterList(frontmatter.mutationTools);
 		let fast: boolean | undefined;
 		if (frontmatter.fast !== undefined) {
 			if (frontmatter.fast === "true") fast = true;
@@ -2072,6 +2105,7 @@ function loadAgentsFromDefinitionFiles(files: AgentDefinitionFile[], source: Age
 			...(frontmatter.thinking !== undefined ? { thinking: frontmatter.thinking === "false" ? false : frontmatter.thinking } : {}),
 			systemPromptMode,
 			inheritProjectContext,
+			inheritGlobalContext,
 			inheritSkills,
 			...(defaultContext !== undefined ? { defaultContext } : {}),
 			...(defaultAsync !== undefined ? { defaultAsync } : {}),
@@ -2088,6 +2122,7 @@ function loadAgentsFromDefinitionFiles(files: AgentDefinitionFile[], source: Age
 			...(skillPath?.length ? { skillPath } : {}),
 			...(extensions !== undefined ? { extensions } : {}),
 			...(subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions } : {}),
+			...(mutationTools?.length ? { mutationTools } : {}),
 			...(frontmatter.output !== undefined ? { output: frontmatter.output } : {}),
 			...(outputMode !== undefined ? { outputMode } : {}),
 			...(defaultReads?.length ? { defaultReads } : {}),

package/src/agents/runtime-agent-events.ts

@@ -0,0 +1,70 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerRuntimeAgent, type RuntimeAgentDefinition, type RuntimeAgentRegistration } from "./runtime-agent-registry.ts";
+
+export const RUNTIME_AGENT_REGISTER_EVENT = "pi-subagents:runtime-agent-register:v1";
+export const RUNTIME_AGENT_REGISTER_VERSION = 1;
+
+export type RuntimeAgentRegistrationResult =
+	| { ok: true; registration: RuntimeAgentRegistration }
+	| { ok: false; error: Error };
+
+export interface RuntimeAgentRegistrationRequest {
+	version: 1;
+	name: string;
+	definition: RuntimeAgentDefinition;
+	result?: RuntimeAgentRegistrationResult;
+}
+
+export interface RegisterRuntimeAgentViaEventsInput {
+	pi: Pick<ExtensionAPI, "events">;
+	name: string;
+	definition: RuntimeAgentDefinition;
+}
+
+function errorFrom(value: unknown): Error {
+	return value instanceof Error ? value : new Error(String(value));
+}
+
+/** Register through the installed pi-subagents owner in this Pi process. */
+export function registerAgentViaEvents(input: RegisterRuntimeAgentViaEventsInput): RuntimeAgentRegistration {
+	const request: RuntimeAgentRegistrationRequest = {
+		version: RUNTIME_AGENT_REGISTER_VERSION,
+		name: input.name,
+		definition: input.definition,
+	};
+	input.pi.events.emit(RUNTIME_AGENT_REGISTER_EVENT, request);
+	const result = request.result as unknown;
+	if (result === undefined) {
+		throw new Error("pi-subagents is not installed, not ready, or does not support runtime agent event registration.");
+	}
+	if (result && typeof result === "object" && !Array.isArray(result)) {
+		const candidate = result as Record<string, unknown>;
+		if (candidate.ok === true && candidate.registration && typeof candidate.registration === "object" && typeof (candidate.registration as { dispose?: unknown }).dispose === "function") {
+			return candidate.registration as RuntimeAgentRegistration;
+		}
+		if (candidate.ok === false && candidate.error instanceof Error) throw candidate.error;
+	}
+	throw new Error("pi-subagents returned a malformed runtime agent registration result.");
+}
+
+/** Install the process-local registration listener for the owning pi-subagents runtime. */
+export function registerRuntimeAgentEventListener(pi: ExtensionAPI): () => void {
+	return pi.events.on(RUNTIME_AGENT_REGISTER_EVENT, (rawRequest) => {
+		if (!rawRequest || typeof rawRequest !== "object" || Array.isArray(rawRequest)) return;
+		const request = rawRequest as Record<string, unknown>;
+		if (request.result !== undefined) return;
+		try {
+			if (request.version !== RUNTIME_AGENT_REGISTER_VERSION) {
+				throw new Error(`Unsupported runtime agent registration event version '${String(request.version)}'.`);
+			}
+			const registration = registerRuntimeAgent({
+				pi,
+				name: request.name as string,
+				definition: request.definition as RuntimeAgentDefinition,
+			});
+			request.result = { ok: true, registration } satisfies RuntimeAgentRegistrationResult;
+		} catch (error) {
+			request.result = { ok: false, error: errorFrom(error) } satisfies RuntimeAgentRegistrationResult;
+		}
+	});
+}

package/src/agents/runtime-agent-registry.ts

@@ -27,6 +27,7 @@ export interface RuntimeAgentDefinition {
 	thinking?: string | false;
 	systemPromptMode?: "append" | "replace";
 	inheritProjectContext?: boolean;
+	inheritGlobalContext?: boolean;
 	inheritSkills?: boolean;
 	defaultContext?: AgentDefaultContext;
 	defaultAsync?: boolean;
@@ -40,6 +41,7 @@ export interface RuntimeAgentDefinition {
 	skillPath?: readonly string[];
 	extensions?: readonly string[];
 	subagentOnlyExtensions?: readonly string[];
+	mutationTools?: readonly string[];
 	output?: string;
 	outputMode?: OutputMode;
 	defaultReads?: readonly string[];
@@ -204,9 +206,9 @@ function validateDefinition(value: unknown): RuntimeAgentDefinition {
 	const definition = value as Record<string, unknown>;
 	const supported = new Set([
 		"description", "systemPrompt", "aliases", "tools", "mcpDirectTools", "model", "fallbackModels", "thinking",
-		"systemPromptMode", "inheritProjectContext", "inheritSkills", "defaultContext", "defaultAsync", "defaultTimeoutMs",
+		"systemPromptMode", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "defaultContext", "defaultAsync", "defaultTimeoutMs",
 		"defaultToolTimeoutMs", "defaultTurnBudget", "defaultAcceptance", "acceptanceRole", "runner", "skills", "skillPath",
-		"extensions", "subagentOnlyExtensions", "output", "outputMode", "defaultReads", "defaultProgress", "interactive",
+		"extensions", "subagentOnlyExtensions", "mutationTools", "output", "outputMode", "defaultReads", "defaultProgress", "interactive",
 		"maxSubagentDepth", "completionGuard", "toolBudget", "permissions",
 	]);
 	const unknown = Object.keys(definition).filter((key) => !supported.has(key));
@@ -227,6 +229,7 @@ function validateDefinition(value: unknown): RuntimeAgentDefinition {
 	const model = validateOptionalString(definition.model, "Runtime agent definition model");
 	const fallbackModels = validateStringList(definition.fallbackModels, "Runtime agent definition fallbackModels");
 	const inheritProjectContext = validateBoolean(definition.inheritProjectContext, "Runtime agent definition inheritProjectContext");
+	const inheritGlobalContext = validateBoolean(definition.inheritGlobalContext, "Runtime agent definition inheritGlobalContext");
 	const inheritSkills = validateBoolean(definition.inheritSkills, "Runtime agent definition inheritSkills");
 	const defaultAsync = validateBoolean(definition.defaultAsync, "Runtime agent definition defaultAsync");
 	const defaultTimeoutMs = validatePositiveInteger(definition.defaultTimeoutMs, "Runtime agent definition defaultTimeoutMs");
@@ -238,6 +241,7 @@ function validateDefinition(value: unknown): RuntimeAgentDefinition {
 	const skillPath = validateStringList(definition.skillPath, "Runtime agent definition skillPath");
 	const extensions = validateStringList(definition.extensions, "Runtime agent definition extensions");
 	const subagentOnlyExtensions = validateStringList(definition.subagentOnlyExtensions, "Runtime agent definition subagentOnlyExtensions");
+	const mutationTools = validateStringList(definition.mutationTools, "Runtime agent definition mutationTools");
 	const output = validateOptionalString(definition.output, "Runtime agent definition output");
 	const defaultReads = validateStringList(definition.defaultReads, "Runtime agent definition defaultReads");
 	const defaultProgress = validateBoolean(definition.defaultProgress, "Runtime agent definition defaultProgress");
@@ -257,6 +261,7 @@ function validateDefinition(value: unknown): RuntimeAgentDefinition {
 		...(thinking !== undefined ? { thinking: thinking as string | false } : {}),
 		...(systemPromptMode !== undefined ? { systemPromptMode: systemPromptMode as "append" | "replace" } : {}),
 		...(inheritProjectContext !== undefined ? { inheritProjectContext } : {}),
+		...(inheritGlobalContext !== undefined ? { inheritGlobalContext } : {}),
 		...(inheritSkills !== undefined ? { inheritSkills } : {}),
 		...(defaultContext !== undefined ? { defaultContext: defaultContext as AgentDefaultContext } : {}),
 		...(defaultAsync !== undefined ? { defaultAsync } : {}),
@@ -270,6 +275,7 @@ function validateDefinition(value: unknown): RuntimeAgentDefinition {
 		...(skillPath ? { skillPath } : {}),
 		...(extensions ? { extensions } : {}),
 		...(subagentOnlyExtensions ? { subagentOnlyExtensions } : {}),
+		...(mutationTools ? { mutationTools } : {}),
 		...(output ? { output } : {}),
 		...(outputMode !== undefined ? { outputMode: outputMode as OutputMode } : {}),
 		...(defaultReads ? { defaultReads } : {}),
@@ -334,6 +340,7 @@ function toAgentConfig(name: string, definition: RuntimeAgentDefinition): AgentC
 		...(definition.thinking !== undefined ? { thinking: definition.thinking } : {}),
 		systemPromptMode: definition.systemPromptMode ?? defaultSystemPromptMode(name),
 		inheritProjectContext: definition.inheritProjectContext ?? defaultInheritProjectContext(name),
+		inheritGlobalContext: definition.inheritGlobalContext ?? false,
 		inheritSkills: definition.inheritSkills ?? defaultInheritSkills(),
 		...(definition.defaultContext !== undefined ? { defaultContext: definition.defaultContext } : {}),
 		...(definition.defaultAsync !== undefined ? { defaultAsync: definition.defaultAsync } : {}),
@@ -349,6 +356,7 @@ function toAgentConfig(name: string, definition: RuntimeAgentDefinition): AgentC
 		...(definition.skillPath !== undefined ? { skillPath: [...definition.skillPath] } : {}),
 		...(definition.extensions !== undefined ? { extensions: [...definition.extensions] } : {}),
 		...(definition.subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions: [...definition.subagentOnlyExtensions] } : {}),
+		...(definition.mutationTools !== undefined ? { mutationTools: [...definition.mutationTools] } : {}),
 		...(definition.output !== undefined ? { output: definition.output } : {}),
 		...(definition.outputMode !== undefined ? { outputMode: definition.outputMode } : {}),
 		...(definition.defaultReads !== undefined ? { defaultReads: [...definition.defaultReads] } : {}),

package/src/api/agents.ts

@@ -1,7 +1,12 @@
-import { registerRuntimeAgent, type RegisterRuntimeAgentInput, type RuntimeAgentDefinition, type RuntimeAgentRegistration } from "../agents/runtime-agent-registry.ts";
+import type { RegisterRuntimeAgentInput, RuntimeAgentDefinition, RuntimeAgentRegistration } from "../agents/runtime-agent-registry.ts";
+export { registerRuntimeAgent as registerAgent } from "../agents/runtime-agent-registry.ts";
+export {
+	RUNTIME_AGENT_REGISTER_EVENT,
+	RUNTIME_AGENT_REGISTER_VERSION,
+	registerAgentViaEvents,
+	type RegisterRuntimeAgentViaEventsInput,
+	type RuntimeAgentRegistrationRequest,
+	type RuntimeAgentRegistrationResult,
+} from "../agents/runtime-agent-events.ts";
 
 export type { RegisterRuntimeAgentInput, RuntimeAgentDefinition, RuntimeAgentRegistration };
-
-export function registerAgent(input: RegisterRuntimeAgentInput): RuntimeAgentRegistration {
-	return registerRuntimeAgent(input);
-}

package/src/api/preflight.ts

@@ -42,8 +42,10 @@ export type SubagentLaunchContractReasonCode =
 	| "thinking_ceiling"
 	| "invalid_extension_bindings";
 
+export type SubagentLaunchContractDiagnosticCode = SubagentLaunchContractReasonCode | "host_required" | "snapshot_warning" | "workspace_scope_authority";
+
 export interface SubagentLaunchContractDiagnostic {
-	code: SubagentLaunchContractReasonCode | "host_required" | "snapshot_warning";
+	code: SubagentLaunchContractDiagnosticCode;
 	severity: "error" | "warning" | "host-required";
 	message: string;
 }
@@ -157,6 +159,7 @@ export interface SubagentLaunchContract {
 	thinkingCeiling?: ThinkingLevel;
 	systemPromptMode: AgentConfig["systemPromptMode"];
 	inheritProjectContext: boolean;
+	inheritGlobalContext: boolean;
 	inheritSkills: boolean;
 	skills: SubagentLaunchContractSkills;
 	tools: SubagentLaunchContractTools;
@@ -204,6 +207,24 @@ function resolveLaunchContractContext(input: SubagentLaunchContractInput, agent:
 	});
 }
 
+function taskWorkspaceScopeAuthorityDiagnostic(task: string | undefined): SubagentLaunchContractDiagnostic | undefined {
+	if (!task) return undefined;
+	const text = task.replace(/\s+/g, " ").trim();
+	if (!text) return undefined;
+	const createsWorkspacePackage = /\b(?:add|create|introduce|make|set up)\b.{0,80}\b(?:new\s+)?(?:workspace\s+)?package\b/i.test(text)
+		|| /\b(?:new\s+)?package\b.{0,80}\b(?:workspace|monorepo)\b/i.test(text);
+	if (!createsWorkspacePackage) return undefined;
+	const packageOnlyAuthority = /\b(?:only|solely)\b.{0,40}\b(?:edit|change|modify|touch|write(?:\s+to)?)\b.{0,80}\b(?:package(?:\s+directory)?|packages\/[\w.-]+)\b/i.test(text)
+		|| /\b(?:do not|don't|must not)\b.{0,40}\b(?:edit|change|modify|touch|write(?:\s+to)?)\b.{0,80}\b(?:root|workspace|lockfile|metadata)\b/i.test(text)
+		|| /\bwithout\b.{0,40}\b(?:root|workspace|lockfile|metadata)\b.{0,40}\b(?:edit|change|modification|write)s?\b/i.test(text);
+	if (!packageOnlyAuthority) return undefined;
+	return {
+		code: "workspace_scope_authority",
+		severity: "warning",
+		message: "Task asks for a workspace package change while limiting authority to package-scope edits. New workspace packages often need root workspace metadata or lockfile changes, so confirm that authority before launch.",
+	};
+}
+
 function candidateList(inputAgent: string, selected: AgentConfig | undefined, cwd: string): SubagentLaunchContractAgentCandidate[] {
 	const all = discoverAgentsAll(cwd);
 	return [...all.builtin, ...all.package, ...all.user, ...all.project]
@@ -221,6 +242,8 @@ function candidateList(inputAgent: string, selected: AgentConfig | undefined, cw
 
 export async function resolveSubagentLaunchContract(input: SubagentLaunchContractInput): Promise<SubagentLaunchContractResult> {
 	const diagnostics: SubagentLaunchContractDiagnostic[] = [];
+	const authorityDiagnostic = taskWorkspaceScopeAuthorityDiagnostic(input.task);
+	if (authorityDiagnostic) diagnostics.push(authorityDiagnostic);
 	const effectiveCwd = path.resolve(input.cwd);
 	try {
 		if (!fs.statSync(effectiveCwd).isDirectory()) {
@@ -400,6 +423,7 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 		...(thinkingCeiling ? { thinkingCeiling } : {}),
 		systemPromptMode: agent.systemPromptMode,
 		inheritProjectContext: agent.inheritProjectContext,
+		inheritGlobalContext: agent.inheritGlobalContext,
 		inheritSkills: agent.inheritSkills,
 		skills: {
 			requested: requestedSkills,
@@ -455,6 +479,7 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 			systemPrompt: effectiveSystemPrompt,
 			systemPromptMode: agent.systemPromptMode,
 			inheritProjectContext: agent.inheritProjectContext,
+			inheritGlobalContext: agent.inheritGlobalContext,
 			inheritSkills: agent.inheritSkills,
 			skills: requestedSkills,
 			tools: toolPlan.effectiveToolAllowlist,

package/src/extension/index.ts

@@ -21,6 +21,7 @@ import { keyText, type ExtensionAPI, type ExtensionContext, type ToolDefinition
 import { Box, Container, Spacer, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
 import { discoverAgents, discoverAgentsAll, type AgentConfig, type AgentScope } from "../agents/agents.ts";
 import { clearRuntimeAgentsForPi, listRuntimeAgentConfigs, mergeRuntimeAgents } from "../agents/runtime-agent-registry.ts";
+import { registerRuntimeAgentEventListener } from "../agents/runtime-agent-events.ts";
 import { ensureAccessibleDir } from "../shared/accessible-dir.ts";
 import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "../shared/artifacts.ts";
 import { resolveCurrentSessionId } from "../shared/session-identity.ts";
@@ -37,6 +38,7 @@ import { getActiveAsyncCapacitySnapshot, resolveAbandonedSlotReleaseAfterMs, res
 import { cleanupResultIndexes, missionObserverResultCandidateFiles } from "../runs/background/result-files.ts";
 import { ASYNC_RETENTION_DELAY_MS, cleanupAsyncRetention } from "../runs/background/async-retention.ts";
 import { createResultWatcher } from "../runs/background/result-watcher.ts";
+import { createResultDeliveryOwnership } from "../runs/background/result-delivery-ownership.ts";
 import { createScheduledRunManager } from "../runs/background/scheduled-runs.ts";
 import { registerSlashCommands } from "../slash/slash-commands.ts";
 import { registerPromptTemplateDelegationBridge } from "../slash/prompt-template-bridge.ts";
@@ -466,7 +468,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const supervisorChannel = createNativeSupervisorChannel(pi, state);
 	const waitSubscriptionManager = createWaitSubscriptionManager(pi, state);
 	const mainWatchdog = registerMainWatchdog(pi);
-	const completionNotifier = registerSubagentNotify(pi, state, { batchConfig: config.completionBatch });
+	const resultDeliveryOwnership = createResultDeliveryOwnership(state);
+	const completionNotifier = registerSubagentNotify(pi, state, { batchConfig: config.completionBatch, ownership: resultDeliveryOwnership });
 	const fleetStatus = fleetViewEnabled
 		? new SubagentFleetStatus(state, async (itemKey) => {
 			const ctx = state.lastUiContext;
@@ -528,6 +531,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		10 * 60 * 1000,
 		{
 			notifier: completionNotifier,
+			ownership: resultDeliveryOwnership,
 			observeCompletion: (result) => scheduledRunManager.handleAsyncCompletion(result),
 			observedCompletionRunIds: () => scheduledRunManager.observedCompletionRunIds(),
 			hasDeliveryDemand: hasResultDeliveryDemand,
@@ -535,7 +539,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			resultScanLogging: config.resultScanLogging,
 		},
 	);
-	const { startResultWatcher, primeExistingResults, stopResultWatcher } = resultWatcher;
+	const { startResultWatcher, transitionResultDelivery, primeExistingResults, stopResultWatcher } = resultWatcher;
 	refreshResultDelivery = resultWatcher.refreshResultDelivery;
 	const asyncRetentionAbort = new AbortController();
 	const asyncRetentionTimer = setTimeout(async () => {
@@ -791,6 +795,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		fleetStatus?.refresh();
 	};
 	const eventUnsubscribes = [
+		registerRuntimeAgentEventListener(pi),
 		pi.events.on(SUBAGENT_ASYNC_STARTED_EVENT, asyncStartedHandler),
 		pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, asyncCompleteHandler),
 		pi.events.on(SUBAGENT_PROCESS_TERMINAL_EVENT, () => {
@@ -807,7 +812,9 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		if (event.toolName !== "subagent") return;
 		if (!ctx.hasUI) return;
 		state.lastUiContext = ctx;
+		const activeJobCount = state.asyncJobs.size;
 		restoreActiveJobs(ctx);
+		if (state.asyncJobs.size > activeJobCount) herdrStatusBridge.syncRuns();
 		fleetStatus?.setContext(ctx);
 		fleetStatus?.refresh();
 		if (state.asyncJobs.size > 0) {
@@ -853,11 +860,14 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		);
 	};
 
-	const resetSessionState = (ctx: ExtensionContext, recovering: boolean) => {
+	const resetSessionState = (ctx: ExtensionContext, recovering: boolean, previousSessionFile?: string) => {
 		state.widgetsSuspended = false;
 		state.baseCwd = ctx.cwd;
 		goalTurnId = 0;
+		const previousRuntimeSessionId = state.currentSessionId;
+		resultDeliveryOwnership.claimPredecessor(previousSessionFile, previousRuntimeSessionId);
 		state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
+		transitionResultDelivery();
 		state.parentSessionFile = ctx.sessionManager.getSessionFile();
 		state.trustedSessionFileRoot = state.parentSessionFile ? path.join(getAgentDir(), "sessions") : undefined;
 		state.trustedSessionRoots = [...new Set([
@@ -934,6 +944,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			clearTimeout(asyncRetentionTimer);
 			asyncRetentionAbort.abort();
 			stopResultWatcher();
+			resultDeliveryOwnership.clear();
 			completionNotifier.dispose();
 			mainWatchdog.dispose();
 			scheduledRunManager.stop();
@@ -1034,7 +1045,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	pi.on("session_start", (event, ctx) => {
 		installRuntime(ctx);
 		const recovering = event.reason === "startup" || event.reason === "reload" || event.reason === "resume";
-		resetSessionState(ctx, recovering);
+		resetSessionState(ctx, recovering, event.previousSessionFile);
 		herdrStatusBridge.sessionStarted({
 			hasUI: ctx.hasUI === true,
 			runs: activeHerdrRuns(),

package/src/extension/rpc.ts

@@ -557,7 +557,7 @@ function stopAsyncRun(
 			childId: stoppedChild.id,
 			status: "stopping",
 			ts,
-			reason: "user",
+			reason: "rpc",
 			source: "rpc",
 			asyncDir,
 			stepIndex: stoppedChild.index,
@@ -579,20 +579,21 @@ function stopAsyncRun(
 	if (initialStatus.mode === "workflow" && initialStatus.state === "running") {
 		if (child) {
 			const stopChild = options.state?.workflowChildStops?.get(initialRunId);
-			if (!stopChild) throw new SubagentRpcError("invalid_state", `Workflow ${initialRunId} is not controlled by this extension runtime; child stop is unavailable.`);
-			if (!stopChild(child.id, `Workflow child '${child.id}' stopped by RPC.`)) throw new SubagentRpcError("invalid_state", `Child '${childId}' in workflow ${initialRunId} is not available to stop.`);
-			emitChildStopping(initialRunId, location.asyncDir, child);
-			return {
-				runId: initialRunId,
-				asyncDir: location.asyncDir,
-				previousState: initialStatus.state,
-				state: "stopping",
-				childId: child.id,
-				message: `Stop requested for child ${child.id} in async run ${initialRunId}.`,
-			};
+			if (stopChild) {
+				if (!stopChild(child.id, `Workflow child '${child.id}' stopped by RPC.`)) throw new SubagentRpcError("invalid_state", `Child '${childId}' in workflow ${initialRunId} is not available to stop.`);
+				emitChildStopping(initialRunId, location.asyncDir, child);
+				return {
+					runId: initialRunId,
+					asyncDir: location.asyncDir,
+					previousState: initialStatus.state,
+					state: "stopping",
+					childId: child.id,
+					message: `Stop requested for child ${child.id} in async run ${initialRunId}.`,
+				};
+			}
 		}
 		const workflowController = options.state?.workflowControllers?.get(initialRunId);
-		if (workflowController) {
+		if (workflowController && !child) {
 			workflowController.abort(new Error("Workflow stopped by RPC."));
 			return {
 				runId: initialRunId,
@@ -602,7 +603,27 @@ function stopAsyncRun(
 				message: `Stop requested for async run ${initialRunId}.`,
 			};
 		}
-		throw new SubagentRpcError("invalid_state", `Workflow ${initialRunId} is not controlled by this extension runtime; reload recovery cannot stop it safely.`);
+		try {
+			deliverStopRequest({
+				asyncDir: location.asyncDir,
+				pid: initialStatus.pid,
+				kill: options.kill,
+				now: options.now,
+				source: "rpc-stop",
+				...(child ? { targetIndex: child.index, childId: child.id } : {}),
+			});
+		} catch (error) {
+			throw new SubagentRpcError("execution_failed", error instanceof Error ? error.message : String(error));
+		}
+		if (child) emitChildStopping(initialRunId, location.asyncDir, child);
+		return {
+			runId: initialRunId,
+			asyncDir: location.asyncDir,
+			previousState: initialStatus.state,
+			state: "stopping",
+			...(child ? { childId: child.id } : {}),
+			message: child ? `Stop requested for child ${child.id} in async run ${initialRunId}.` : `Stop requested for async run ${initialRunId}.`,
+		};
 	}
 
 	let status;

package/src/extension/schemas.ts

@@ -289,7 +289,7 @@ const SubagentParamProperties = {
 	scope: Type.Optional(Type.String({ enum: ["session", "user", "project"], description: "Scope for action='watchdog.configure'. Defaults to session to avoid persistent settings writes unless user/project is explicit." })),
 	target: Type.Optional(Type.String({ enum: ["main", "children", "child"], description: "Target for watchdog actions." })),
 	focus: Type.Optional(Type.Boolean({ description: "Focus the new Herdr pane for inspector.open or project.open." })),
-	thinking: Type.Optional(Type.Unsafe({ anyOf: [{ type: "string" }, { type: "boolean", enum: [false] }], description: "Thinking level for action='watchdog.configure' (off/minimal/low/medium/high/xhigh/max, inherit, or false for off)." })),
+	thinking: Type.Optional(Type.Unsafe({ anyOf: [{ type: "string" }, { type: "boolean", enum: [false] }], description: "Thinking level for action='watchdog.configure' only (off/minimal/low/medium/high/xhigh/max, inherit, or false for off). Ignored on dispatch; set per-run child thinking with a suffix on the model string, e.g. model: 'provider/id:high'." })),
 	at: Type.Optional(Type.String({ description: "One-shot trigger for action='schedule.create': a relative delay such as '+10m' or an ISO timestamp with timezone." })),
 	every: Type.Optional(Type.String({ description: "Fixed recurring interval for action='schedule.create', such as '30m', '6h', '2d', or '2w'." })),
 	on: Type.Optional(Type.Unsafe({ anyOf: [{ type: "string" }, { type: "integer" }], description: "Calendar selector reserved for a later schedule slice." })),
@@ -347,7 +347,7 @@ const SubagentParamProperties = {
 	})),
 	outputMode: Type.Optional(OutputModeOverride),
 	skill: Type.Optional(SkillOverride),
-	model: Type.Optional(Type.String({ description: "Default child model override. Full provider/id values are accepted; bare ids resolve from the active registry." })),
+	model: Type.Optional(Type.String({ description: "Default child model override. Full provider/id values are accepted; bare ids resolve from the active registry. Append a thinking suffix (off/minimal/low/medium/high/xhigh/max, e.g. 'provider/id:low') to set the child's thinking level for the run; the suffix wins over the agent's thinking default." })),
 	fast: Type.Optional(Type.Boolean({ description: "Opt into priority service tier for supported native OpenAI-Codex child models. Default false. This can increase quota or cost." })),
 	outputSchema: Type.Optional(JsonSchemaObject),
 	agentContract: Type.Optional(AgentContractOverride),