@hobin/developer 0.1.7 → 0.1.8

package/README.md

@@ -74,6 +74,14 @@ workspace boundary. Developer recognizes Pi built-ins from their provenance,
 preserves unrelated active tools, and does not force-enable tools the user
 disabled.
 
+Before Pi tears down a session runtime, Developer releases its route-bound tool
+delta so a reload, session replacement, or later extension instance does not
+inherit orphaned restrictions. After that release, the package records a
+reload-safe lifecycle marker. If an in-process reload finds older Developer
+history without a later release marker, Developer stays off and requires a full
+Pi process restart. Neither `/reload` nor `/develop off` → `on` can safely infer
+which built-ins the user originally enabled.
+
 ## How a request runs
 
 Developer adds two model-facing protocol tools:
@@ -300,6 +308,10 @@ eligibility are derived from the same machine snapshot.
 The current event contract is `developer/v5`. Earlier protocol entries are not
 replayed; this breaking contract uses `target`, `implementation`, and
 `before-implementation` consistently across tools, events, and machine state.
+A process started on the current package may open a branch containing those
+entries, but hot-reloading directly from a pre-handoff runtime is rejected with
+a restart instruction so its in-memory tool ownership cannot be mistaken for
+user configuration.
 
 Developer deliberately leaves compaction ownership to Pi. It does not trigger,
 cancel, or replace threshold/overflow compaction, so it cannot override the
@@ -402,9 +414,11 @@ not append entries, submit answers, register tools, mutate active tools, restore
 sessions, start network work, or send model messages. Prepared answers are shown
 only as a character count.
 
-`check` validates package structure and deterministic behavior. `eval` launches
-the real Pi RPC surface without a model and covers package resources, commands,
-activation state, and route-bound tool gating. These are release-gating checks.
+`check` validates package structure and deterministic behavior, including
+reload migration detection and shutdown restoration of Developer-owned tool
+deltas. `eval` launches the real Pi RPC surface without a model and covers
+package resources, commands, activation state, and route-bound tool gating.
+These are release-gating checks.
 
 Model-dependent runs are probabilistic evaluations rather than binary tests:
 

package/extensions/developer.ts

@@ -53,9 +53,12 @@ import {
 	type RouteEvent,
 } from "./state.ts";
 import {
+	TOOL_POLICY_LIFECYCLE_ENTRY,
 	builtinControlledToolCapabilities,
 	isControlledToolAllowed,
 	reconcileProtocolTools,
+	reloadSafeToolPolicyMarker,
+	toolPolicyReloadRequiresRestart,
 	type ProtocolToolAccess,
 	type ToolPolicyMemory,
 } from "./tool-policy.ts";
@@ -88,6 +91,8 @@ const MAX_EVIDENCE_CHARS = 2_000;
 const MAX_RESULT_CHARS = 12_000;
 const MAX_ARTIFACT_CHARS = 4_096;
 const DEVELOPER_COMMAND_ACTIONS = ["on", "status", "questions", "off"] as const;
+const TOOL_POLICY_RESTART_MESSAGE =
+	"Developer detected an in-process package reload from a version without reload-safe tool handoff. Restart the Pi process before enabling Developer; /reload and /develop off/on cannot safely reconstruct the prior built-in tool selection.";
 
 function textResult<T>(text: string, details: T) {
 	return {
@@ -560,6 +565,7 @@ export default async function developer(pi: ExtensionAPI) {
 	let routeOpening = false;
 	const routesWithMutation = new Set<string>();
 	let toolPolicyMemory: ToolPolicyMemory = { withheldBuiltins: new Set() };
+	let toolPolicyRestartRequired = false;
 
 	pi.registerFlag("develop", {
 		description: "Start with the Developer protocol enabled",
@@ -582,7 +588,31 @@ export default async function developer(pi: ExtensionAPI) {
 			pi.setActiveTools(next.activeTools);
 	};
 
+	const releaseProtocolTools = () => {
+		const current = pi.getActiveTools();
+		const next = reconcileProtocolTools({
+			activeTools: current,
+			allTools: pi.getAllTools(),
+			enabled: false,
+			access: protocolToolAccess(state),
+			protocolTools: PROTOCOL_TOOLS,
+			memory: toolPolicyMemory,
+		});
+		toolPolicyMemory = next.memory;
+		if (!sameToolSet(current, next.activeTools))
+			pi.setActiveTools(next.activeTools);
+	};
+
 	const refreshUI = (ctx: ExtensionContext) => {
+		if (toolPolicyRestartRequired) {
+			ctx.ui.setStatus("developer", "developer · restart required");
+			ctx.ui.setWidget(
+				"developer",
+				["blocked · restart Pi to reset Developer tool access"],
+				{ placement: "belowEditor" },
+			);
+			return;
+		}
 		if (!state.enabled) {
 			ctx.ui.setStatus("developer", undefined);
 			ctx.ui.setWidget("developer", undefined);
@@ -643,12 +673,19 @@ export default async function developer(pi: ExtensionAPI) {
 	};
 
 	const reconstruct = (ctx: ExtensionContext) => {
-		state = reconstructState(ctx.sessionManager.getBranch());
+		state = toolPolicyRestartRequired
+			? initialState()
+			: reconstructState(ctx.sessionManager.getBranch());
 		syncProtocolTools();
 		refreshUI(ctx);
 	};
 
-	const setEnabled = (enabled: boolean, ctx: ExtensionContext) => {
+	const setEnabled = (enabled: boolean, ctx: ExtensionContext): boolean => {
+		if (enabled && toolPolicyRestartRequired) {
+			ctx.ui.notify(TOOL_POLICY_RESTART_MESSAGE, "error");
+			refreshUI(ctx);
+			return false;
+		}
 		const event: ActivationEvent = {
 			protocol: PROTOCOL,
 			kind: "activation",
@@ -658,6 +695,7 @@ export default async function developer(pi: ExtensionAPI) {
 		state = applyDeveloperEvent(state, event);
 		syncProtocolTools();
 		refreshUI(ctx);
+		return true;
 	};
 
 	const SharedRouteParams = {
@@ -1576,9 +1614,10 @@ export default async function developer(pi: ExtensionAPI) {
 				return true;
 			};
 
-			const setAndNotifyEnabled = (enabled: boolean) => {
-				setEnabled(enabled, ctx);
+			const setAndNotifyEnabled = (enabled: boolean): boolean => {
+				if (!setEnabled(enabled, ctx)) return false;
 				ctx.ui.notify(`Developer: ${enabled ? "on" : "off"}`, "info");
+				return true;
 			};
 
 			const turnOff = async (): Promise<boolean> => {
@@ -1603,6 +1642,11 @@ export default async function developer(pi: ExtensionAPI) {
 			};
 
 			const inspectStatus = async () => {
+				if (toolPolicyRestartRequired) {
+					ctx.ui.notify(TOOL_POLICY_RESTART_MESSAGE, "error");
+					refreshUI(ctx);
+					return;
+				}
 				refreshAvailableSkills(ctx);
 				if (ctx.mode === "tui") {
 					await showDeveloperStatus(ctx, {
@@ -1796,14 +1840,33 @@ export default async function developer(pi: ExtensionAPI) {
 		};
 	});
 
-	pi.on("session_start", (_event, ctx) => {
+	pi.on("session_start", (event, ctx) => {
+		const branch = ctx.sessionManager.getBranch();
+		toolPolicyRestartRequired =
+			event.reason === "reload" &&
+			toolPolicyReloadRequiresRestart({
+				entries: branch,
+				protocol: PROTOCOL,
+				protocolTools: PROTOCOL_TOOLS,
+			});
 		reconstruct(ctx);
+		if (toolPolicyRestartRequired) {
+			ctx.ui.notify(TOOL_POLICY_RESTART_MESSAGE, "error");
+			return;
+		}
 		const startEnabled = pi.getFlag("develop");
 		if (startEnabled === true && !state.enabled) setEnabled(true, ctx);
 	});
 	pi.on("session_tree", (_event, ctx) => reconstruct(ctx));
 	pi.on("agent_settled", (_event, ctx) => refreshUI(ctx));
 	pi.on("session_shutdown", (_event, ctx) => {
+		releaseProtocolTools();
+		if (!toolPolicyRestartRequired) {
+			pi.appendEntry(
+				TOOL_POLICY_LIFECYCLE_ENTRY,
+				reloadSafeToolPolicyMarker(PROTOCOL),
+			);
+		}
 		ctx.ui.setStatus("developer", undefined);
 		ctx.ui.setWidget("developer", undefined);
 	});

package/extensions/tool-policy.ts

@@ -1,5 +1,8 @@
 export type ControlledToolCapability = "shell" | "artifact";
 
+export const TOOL_POLICY_LIFECYCLE_ENTRY = "developer.tool-policy-lifecycle";
+export const TOOL_POLICY_LIFECYCLE = "released-before-reload/v1";
+
 const CONTROLLED_BUILTIN_CAPABILITIES = new Map<
 	string,
 	ControlledToolCapability
@@ -29,6 +32,90 @@ export interface ProtocolToolAccess {
 	hasBeforeImplementationGate: boolean;
 }
 
+interface ToolPolicyBranchEntry {
+	type?: string;
+	customType?: string;
+	data?: unknown;
+	message?: {
+		role?: string;
+		toolName?: string;
+		details?: unknown;
+	};
+}
+
+interface ToolPolicyLifecycleMarker {
+	protocol: string;
+	kind: "tool-policy-lifecycle";
+	lifecycle: typeof TOOL_POLICY_LIFECYCLE;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+export function reloadSafeToolPolicyMarker(
+	protocol: string,
+): ToolPolicyLifecycleMarker {
+	return {
+		protocol,
+		kind: "tool-policy-lifecycle",
+		lifecycle: TOOL_POLICY_LIFECYCLE,
+	};
+}
+
+function isReloadSafeToolPolicyMarker(
+	entry: ToolPolicyBranchEntry,
+	protocol: string,
+): boolean {
+	if (
+		entry.type !== "custom" ||
+		entry.customType !== TOOL_POLICY_LIFECYCLE_ENTRY ||
+		!isObject(entry.data)
+	)
+		return false;
+	return (
+		entry.data.protocol === protocol &&
+		entry.data.kind === "tool-policy-lifecycle" &&
+		entry.data.lifecycle === TOOL_POLICY_LIFECYCLE
+	);
+}
+
+export function toolPolicyReloadRequiresRestart(input: {
+	entries: readonly ToolPolicyBranchEntry[];
+	protocol: string;
+	protocolTools: readonly string[];
+}): boolean {
+	const protocolTools = new Set(input.protocolTools);
+	for (let index = input.entries.length - 1; index >= 0; index -= 1) {
+		const entry = input.entries[index];
+		if (!entry) continue;
+		if (isReloadSafeToolPolicyMarker(entry, input.protocol)) return false;
+
+		let value: unknown;
+		if (
+			entry.type === "custom" &&
+			entry.customType?.startsWith("developer.") &&
+			entry.customType !== TOOL_POLICY_LIFECYCLE_ENTRY
+		) {
+			value = entry.data;
+		} else if (
+			entry.type === "message" &&
+			entry.message?.role === "toolResult" &&
+			entry.message.toolName &&
+			protocolTools.has(entry.message.toolName)
+		) {
+			value = entry.message.details;
+		}
+		if (
+			isObject(value) &&
+			typeof value.protocol === "string" &&
+			value.protocol.startsWith("developer/")
+		)
+			return true;
+	}
+	return false;
+}
+
 export function builtinControlledToolCapabilities(
 	tools: ToolMetadataLike[],
 ): Map<string, ControlledToolCapability> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hobin/developer",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Adaptive product-development reasoning and evidence for Pi.",
   "type": "module",
   "keywords": ["pi-package", "pi", "developer", "skills"],