@themoltnet/pi-runtime 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -49,6 +49,8 @@ export declare interface AllowedToolsClient {
                 argvPrefix: string[];
             }>;
             runtimeKind: string;
+            policySnapshotHash?: string;
+            runtimeProfileRevision?: number;
         }>;
     };
 }
@@ -446,8 +448,8 @@ export declare interface ExecutePiTaskOptions {
     runtimeProfileContext?: readonly ContextRef[];
     /**
      * Runtime profile id, used to resolve the tool-policy allow-set at session
-     * start. Required together with a non-`off` `toolEnforcement` for the
-     * `tool_call` gate to run.
+     * start. Required with `toolEnforcement`; the resolved mode determines
+     * whether a `tool_call` gate is installed.
      */
     runtimeProfileId?: string;
     /** Tool-policy enforcement mode for the selected runtime profile. */
@@ -604,21 +606,18 @@ export declare function filterModelVisibleTools(tools: readonly ToolDefinition[]
  */
 export declare function findMainWorktree(startPath?: string): string;
 
-/**
- * The gate's verdict:
- * - `{ allow: true }` — let the tool run.
- * - `{ allow: false, reason }` — block it (enforce mode).
- * - `{ audit, ... }` — would-block, but proceed and record it (watch mode).
- */
 export declare type GateDecision = {
     allow: true;
+    reasonCode: ToolPolicyDecisionReason;
     matchedShellCommands?: MatchedShellCommand[];
 } | {
     allow: false;
+    reasonCode: ToolPolicyDecisionReason;
     reason: string;
     missing?: string[];
     missingShellCommands?: MissingShellCommand[];
 } | {
+    reasonCode: ToolPolicyDecisionReason;
     audit: string;
     missing?: string[];
     missingShellCommands?: MissingShellCommand[];
@@ -1106,8 +1105,9 @@ export declare function resolveHostExecBaseEnv(guestCredentialMode: GuestCredent
 /**
  * Resolve the session's tool policy at start-up.
  *
- * `off` short-circuits without a network call. Otherwise the allowed-tool set
- * is fetched from the API. If that fetch fails, the mode decides the fallback:
+ * The latest allowed-tool set and enforcement mode are fetched from the API,
+ * including when the daemon's cached profile says `off`. If that fetch fails,
+ * the cached mode decides the fallback:
  * `enforce` **fails closed** (empty allow-set → every non-`off` tool is
  * blocked); `watch` fails open (empty allow-set → every tool is audited but
  * allowed).
@@ -1291,6 +1291,10 @@ export declare interface SessionToolPolicy {
     enforcement: ToolEnforcement;
     allowedTools: ReadonlySet<string>;
     allowedShellCommands: readonly ShellCommandRule[];
+    /** Latest effective policy hash resolved for this Pi session. */
+    executionPolicySnapshotHash?: string;
+    /** Latest runtime profile revision resolved with the session policy. */
+    executionRuntimeProfileRevision?: number;
     /**
      * `true` when the allow-set is a **degraded fallback** — the allowed-tools
      * fetch failed or timed out and this policy is the fail-closed/fail-open
@@ -1298,7 +1302,7 @@ export declare interface SessionToolPolicy {
      * empty-but-resolved policy (e.g. a profile with no bound tools) has
      * `degraded: false`. Surfaced in every audit/block log so an operator can tell
      * "blocked because the policy is empty" from "blocked because we couldn't read
-     * the policy". `off` and successful resolutions are never degraded.
+     * the policy". Successful resolutions are never degraded.
      */
     degraded: boolean;
 }
@@ -1354,10 +1358,35 @@ declare const ToolEnforcementSchema = Type.Union(toolEnforcementLiterals, {
     'Runtime tool-policy enforcement mode: off (inert), watch (audit only), enforce (block disallowed tools, fail-closed).',
 });
 
+/** Correlation and claim evidence repeated on every tool-policy decision. */
+export declare interface ToolPolicyDecisionContext {
+    taskId: string;
+    attemptN: number;
+    teamId: string;
+    claimantAgentId?: string;
+    leaseId?: string;
+    proposerKind?: 'agent' | 'human';
+    proposerId?: string;
+    claimRuntimeProfileId?: string;
+    executionRuntimeProfileId?: string;
+    claimRuntimeProfileRevision?: number;
+    claimPolicySnapshotHash?: string;
+    claimedExecutorFingerprint?: string;
+}
+
+/**
+ * The gate's verdict:
+ * - `{ allow: true }` — let the tool run.
+ * - `{ allow: false, reason }` — block it (enforce mode).
+ * - `{ audit, ... }` — would-block, but proceed and record it (watch mode).
+ */
+export declare type ToolPolicyDecisionReason = 'policy_off' | 'executor_protocol_tool' | 'policy_allowed' | 'shell_command_prefix_allowed' | 'shell_command_unresolvable' | 'arbitrary_code_interpreter' | 'shell_output_redirection_requires_broad_permission' | 'tool_not_permitted';
+
 export declare interface ToolPolicyExtensionDeps {
     policy: SessionToolPolicy;
     analyzer: ShellCommandAnalyzer;
     logger: ToolPolicyLogger;
+    context?: ToolPolicyDecisionContext;
 }
 
 /**

package/dist/index.js

@@ -1925,6 +1925,11 @@ Type$1.Object({ id: UuidSchema });
 Type$1.Object({
 	publicKey: PublicKeySchema,
 	fingerprint: FingerprintSchema,
+	proof: Type$1.String({
+		minLength: 1,
+		maxLength: 256
+	}),
+	credentialType: Type$1.Literal("oauth2"),
 	agentName: Type$1.String({
 		minLength: 1,
 		maxLength: 34
@@ -2198,7 +2203,6 @@ var ProblemCodeSchema = Type$1.Union([
 	Type$1.Literal("VALIDATION_FAILED"),
 	Type$1.Literal("INVALID_CHALLENGE"),
 	Type$1.Literal("INVALID_SIGNATURE"),
-	Type$1.Literal("VOUCHER_LIMIT"),
 	Type$1.Literal("RATE_LIMIT_EXCEEDED"),
 	Type$1.Literal("SERIALIZATION_EXHAUSTED"),
 	Type$1.Literal("SIGNING_REQUEST_EXPIRED"),
@@ -5420,16 +5424,25 @@ function createGondolinBashOps(vm, localCwd, guestWorkspace) {
 * capability-aware allow-set) is tracked as future work.
 */
 function decideToolCall(input) {
-	if (input.enforcement === "off") return { allow: true };
-	if (input.toolName.startsWith("submit_") || input.toolName === "subagent") return { allow: true };
+	if (input.enforcement === "off") return {
+		allow: true,
+		reasonCode: "policy_off"
+	};
+	if (input.toolName.startsWith("submit_") || input.toolName === "subagent") return {
+		allow: true,
+		reasonCode: "executor_protocol_tool"
+	};
 	const resolved = resolveNames(input);
-	if (resolved.kind === "unresolvable") return fenced(input.enforcement, "shell command could not be statically authorized", "unresolvable shell command (watch)");
+	if (resolved.kind === "unresolvable") return fenced(input.enforcement, "shell_command_unresolvable", "shell command could not be statically authorized", "unresolvable shell command (watch)");
 	const arbitraryCode = [...new Set(resolved.tools.filter((tool) => tool.risk === "arbitrary-code").map((tool) => tool.name))];
-	if (arbitraryCode.length > 0) return fenced(input.enforcement, `arbitrary-code interpreter not authorizable by tool policy: ${arbitraryCode.join(", ")}`, `would block — arbitrary-code interpreter (watch): ${arbitraryCode.join(", ")}`, arbitraryCode);
+	if (arbitraryCode.length > 0) return fenced(input.enforcement, "arbitrary_code_interpreter", `arbitrary-code interpreter not authorizable by tool policy: ${arbitraryCode.join(", ")}`, `would block — arbitrary-code interpreter (watch): ${arbitraryCode.join(", ")}`, arbitraryCode);
 	if (input.toolName !== "bash") {
 		const missing = resolved.tools.map((tool) => tool.name).filter((name) => !input.allowedTools.has(name));
-		if (missing.length === 0) return { allow: true };
-		return fenced(input.enforcement, `not permitted by tool policy: ${missing.join(", ")}`, `would block (watch): ${missing.join(", ")}`, missing);
+		if (missing.length === 0) return {
+			allow: true,
+			reasonCode: "policy_allowed"
+		};
+		return fenced(input.enforcement, "tool_not_permitted", `not permitted by tool policy: ${missing.join(", ")}`, `would block (watch): ${missing.join(", ")}`, missing);
 	}
 	const matchedShellCommands = [];
 	const missingShellCommands = resolved.tools.filter((tool) => {
@@ -5439,7 +5452,7 @@ function decideToolCall(input) {
 		matchedShellCommands.push(toMatchedShellCommand(tool.name, matched.argvPrefix));
 		return false;
 	}).map(toMissingShellCommand);
-	if (missingShellCommands.length === 0 && resolved.hasOutputRedirection && matchedShellCommands.length > 0) return fenced(input.enforcement, "shell output redirection requires broad executable permission", "would block shell output redirection under scoped command policy", [...new Set(matchedShellCommands.map(({ executable }) => executable))], matchedShellCommands.map(({ executable, argvPrefixFingerprint, argvPrefixLength }) => ({
+	if (missingShellCommands.length === 0 && resolved.hasOutputRedirection && matchedShellCommands.length > 0) return fenced(input.enforcement, "shell_output_redirection_requires_broad_permission", "shell output redirection requires broad executable permission", "would block shell output redirection under scoped command policy", [...new Set(matchedShellCommands.map(({ executable }) => executable))], matchedShellCommands.map(({ executable, argvPrefixFingerprint, argvPrefixLength }) => ({
 		executable,
 		argvFingerprint: argvPrefixFingerprint,
 		argvLength: argvPrefixLength,
@@ -5447,10 +5460,14 @@ function decideToolCall(input) {
 	})));
 	if (missingShellCommands.length === 0) return matchedShellCommands.length > 0 ? {
 		allow: true,
+		reasonCode: "shell_command_prefix_allowed",
 		matchedShellCommands
-	} : { allow: true };
+	} : {
+		allow: true,
+		reasonCode: "policy_allowed"
+	};
 	const missing = [...new Set(missingShellCommands.map(({ executable }) => executable))];
-	return fenced(input.enforcement, `not permitted by tool policy: ${missing.join(", ")}`, `would block (watch): ${missing.join(", ")}`, missing, missingShellCommands);
+	return fenced(input.enforcement, "tool_not_permitted", `not permitted by tool policy: ${missing.join(", ")}`, `would block (watch): ${missing.join(", ")}`, missing, missingShellCommands);
 }
 function fingerprintArgv(argv) {
 	return `sha256:${createHash$1("sha256").update(JSON.stringify(argv.map((token) => token === null ? { dynamic: true } : token))).digest("hex").slice(0, 16)}`;
@@ -5477,14 +5494,16 @@ function matchesArgvPrefix(argv, prefix) {
 * Shared enforce/watch branch: block in `enforce`, audit-and-allow in `watch`.
 * `enforcement` is never `off` here (short-circuited by the caller).
 */
-function fenced(enforcement, blockReason, auditReason, missing, missingShellCommands) {
+function fenced(enforcement, reasonCode, blockReason, auditReason, missing, missingShellCommands) {
 	if (enforcement === "enforce") return {
 		allow: false,
+		reasonCode,
 		reason: blockReason,
 		...missing ? { missing } : {},
 		...missingShellCommands?.length ? { missingShellCommands } : {}
 	};
 	return {
+		reasonCode,
 		audit: auditReason,
 		...missing ? { missing } : {},
 		...missingShellCommands?.length ? { missingShellCommands } : {}
@@ -5527,8 +5546,9 @@ function resolveNames(input) {
 /**
 * Resolve the session's tool policy at start-up.
 *
-* `off` short-circuits without a network call. Otherwise the allowed-tool set
-* is fetched from the API. If that fetch fails, the mode decides the fallback:
+* The latest allowed-tool set and enforcement mode are fetched from the API,
+* including when the daemon's cached profile says `off`. If that fetch fails,
+* the cached mode decides the fallback:
 * `enforce` **fails closed** (empty allow-set → every non-`off` tool is
 * blocked); `watch` fails open (empty allow-set → every tool is audited but
 * allowed).
@@ -5539,12 +5559,6 @@ function resolveNames(input) {
 * session, stable enforcement for the run) accepted over re-fetching per call.
 */
 async function resolveSessionToolPolicy(input) {
-	if (input.enforcement === "off") return {
-		enforcement: "off",
-		allowedTools: /* @__PURE__ */ new Set(),
-		allowedShellCommands: [],
-		degraded: false
-	};
 	const timeoutMs = input.timeoutMs ?? 5e3;
 	try {
 		const resolved = await withTimeout$1(input.agent.runtimeProfiles.allowedTools(input.profileId, { teamId: input.teamId }), timeoutMs);
@@ -5560,6 +5574,8 @@ async function resolveSessionToolPolicy(input) {
 				if (rule.argvPrefix.length < 2 || rule.argvPrefix.length > 8 || rule.argvPrefix.some((token) => !token)) throw new Error("runtime returned an invalid shell command rule");
 				return { argvPrefix: rule.argvPrefix };
 			}),
+			executionPolicySnapshotHash: resolved.policySnapshotHash,
+			executionRuntimeProfileRevision: resolved.runtimeProfileRevision,
 			degraded: false
 		};
 	} catch (err) {
@@ -5632,34 +5648,46 @@ function decideForEvent(event, policy, analyze) {
 * `off`. Register it in a session's `extensionFactories`.
 */
 function createToolPolicyExtension(deps) {
+	if (deps.context?.claimPolicySnapshotHash && deps.policy.executionPolicySnapshotHash && deps.context.claimPolicySnapshotHash !== deps.policy.executionPolicySnapshotHash) deps.logger.info({
+		...decisionContext(deps),
+		decision: "continue",
+		reason: "claim_execution_policy_drift"
+	}, "tool_policy.snapshot_drift");
 	return (pi) => {
 		if (deps.policy.enforcement === "off") return;
 		pi.on("tool_call", (event) => {
 			const decision = decideForEvent(event, deps.policy, (command) => deps.analyzer.analyze(command));
 			if ("allow" in decision && decision.allow) {
-				if (decision.matchedShellCommands?.length) deps.logger.debug({
+				deps.logger.info({
+					...decisionContext(deps),
 					toolName: event.toolName,
 					toolCallId: event.toolCallId,
-					matchedShellCommands: decision.matchedShellCommands
-				}, "tool_policy.shell_command_allowed");
+					decision: "allowed",
+					reason: decision.reasonCode,
+					...decision.matchedShellCommands?.length ? { shellFingerprints: decision.matchedShellCommands } : {}
+				}, "tool_policy.allowed");
 				return;
 			}
 			if ("audit" in decision) {
 				deps.logger.info({
+					...decisionContext(deps),
 					toolName: event.toolName,
 					toolCallId: event.toolCallId,
-					degraded: deps.policy.degraded,
-					decision
+					decision: "audit",
+					reason: decision.reasonCode,
+					...decision.missing?.length ? { missingExecutables: decision.missing } : {},
+					...decision.missingShellCommands?.length ? { shellFingerprints: decision.missingShellCommands } : {}
 				}, "tool_policy.audit");
 				return;
 			}
 			deps.logger.warn({
+				...decisionContext(deps),
 				toolName: event.toolName,
 				toolCallId: event.toolCallId,
-				degraded: deps.policy.degraded,
-				reason: decision.reason,
-				missingExecutables: decision.missing,
-				missingShellCommands: decision.missingShellCommands
+				decision: "blocked",
+				reason: decision.reasonCode,
+				...decision.missing?.length ? { missingExecutables: decision.missing } : {},
+				...decision.missingShellCommands?.length ? { shellFingerprints: decision.missingShellCommands } : {}
 			}, "tool_policy.blocked");
 			return {
 				block: true,
@@ -5668,6 +5696,15 @@ function createToolPolicyExtension(deps) {
 		});
 	};
 }
+function decisionContext(deps) {
+	return {
+		...deps.context ?? {},
+		enforcement: deps.policy.enforcement,
+		degraded: deps.policy.degraded,
+		executionPolicySnapshotHash: deps.policy.executionPolicySnapshotHash,
+		executionRuntimeProfileRevision: deps.policy.executionRuntimeProfileRevision
+	};
+}
 //#endregion
 //#region src/runtime/capability-discovery.ts
 var GuestExecutableProbeError = class extends Error {
@@ -7647,28 +7684,34 @@ async function executePiTask(claimedTask, reporter, opts) {
 					...obj
 				}))
 			};
-			if (opts.runtimeProfileId && opts.toolEnforcement && opts.toolEnforcement !== "off") {
-				const [analyzer, policy] = await Promise.all([ShellCommandAnalyzer.create(), resolveSessionToolPolicy({
+			const toolPolicyDecisionContext = buildToolPolicyDecisionContext(claimedTask, opts.runtimeProfileId);
+			if (opts.runtimeProfileId && opts.toolEnforcement) {
+				const policy = await resolveSessionToolPolicy({
 					agent: moltnetAgent,
 					profileId: opts.runtimeProfileId,
 					teamId: taskTeamId,
 					runtimeKind: opts.runtimeDefinition?.runtimeKind ?? "gondolin_pi",
 					enforcement: opts.toolEnforcement,
 					logger: toolPolicyLogger
-				})]);
-				verifiedGuestExecutables = (await discoverGuestExecutables(managed.vm, [...policy.allowedShellCommands.map(({ argvPrefix }) => argvPrefix[0]), ...policy.enforcement === "watch" ? resolvedVmTemplate?.executables ?? [] : []], { signal: reporter.cancelSignal })).available;
-				const availableExecutables = new Set(verifiedGuestExecutables);
-				const allowedShellCommands = policy.allowedShellCommands.filter(({ argvPrefix }) => availableExecutables.has(argvPrefix[0]));
-				unavailableRuntimeShellCommands = policy.allowedShellCommands.filter(({ argvPrefix }) => !availableExecutables.has(argvPrefix[0]));
-				resolvedToolPolicy = {
-					...policy,
-					allowedShellCommands
-				};
-				toolPolicyExtensions.push(createToolPolicyExtension({
-					policy: resolvedToolPolicy,
-					analyzer,
-					logger: toolPolicyLogger
-				}));
+				});
+				resolvedToolPolicy = policy;
+				if (policy.enforcement !== "off") {
+					const analyzer = await ShellCommandAnalyzer.create();
+					verifiedGuestExecutables = (await discoverGuestExecutables(managed.vm, [...policy.allowedShellCommands.map(({ argvPrefix }) => argvPrefix[0]), ...policy.enforcement === "watch" ? resolvedVmTemplate?.executables ?? [] : []], { signal: reporter.cancelSignal })).available;
+					const availableExecutables = new Set(verifiedGuestExecutables);
+					const allowedShellCommands = policy.allowedShellCommands.filter(({ argvPrefix }) => availableExecutables.has(argvPrefix[0]));
+					unavailableRuntimeShellCommands = policy.allowedShellCommands.filter(({ argvPrefix }) => !availableExecutables.has(argvPrefix[0]));
+					resolvedToolPolicy = {
+						...policy,
+						allowedShellCommands
+					};
+					toolPolicyExtensions.push(createToolPolicyExtension({
+						policy: resolvedToolPolicy,
+						analyzer,
+						logger: toolPolicyLogger,
+						context: toolPolicyDecisionContext
+					}));
+				}
 			}
 			const runtimeToolContext = {
 				agent: moltnetAgent,
@@ -8048,6 +8091,29 @@ async function executePiTask(claimedTask, reporter, opts) {
 		});
 	}
 }
+function buildToolPolicyDecisionContext(claimedTask, executionRuntimeProfileId) {
+	const { task, attemptN, claimAuthority } = claimedTask;
+	const proposer = task.proposedByAgentId ? {
+		proposerKind: "agent",
+		proposerId: task.proposedByAgentId
+	} : task.proposedByHumanId ? {
+		proposerKind: "human",
+		proposerId: task.proposedByHumanId
+	} : {};
+	return {
+		taskId: task.id,
+		attemptN,
+		teamId: task.teamId,
+		...proposer,
+		...claimAuthority?.claimantAgentId ? { claimantAgentId: claimAuthority.claimantAgentId } : {},
+		...claimAuthority?.leaseId ? { leaseId: claimAuthority.leaseId } : {},
+		...claimAuthority?.runtimeProfileId ? { claimRuntimeProfileId: claimAuthority.runtimeProfileId } : {},
+		...executionRuntimeProfileId ? { executionRuntimeProfileId } : {},
+		...typeof claimAuthority?.runtimeProfileRevision === "number" ? { claimRuntimeProfileRevision: claimAuthority.runtimeProfileRevision } : {},
+		...claimAuthority?.policySnapshotHash ? { claimPolicySnapshotHash: claimAuthority.policySnapshotHash } : {},
+		...claimAuthority?.executorFingerprint ? { claimedExecutorFingerprint: claimAuthority.executorFingerprint } : {}
+	};
+}
 function createSessionTurnState() {
 	return {
 		assistantText: "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@themoltnet/pi-runtime",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "license": "MIT",
   "type": "module",
   "description": "Composable MoltNet runtime kernel for Pi agents in Gondolin VMs",
@@ -31,9 +31,9 @@
     "@opentelemetry/api": "^1.9.0",
     "multiformats": "^13.3.0",
     "typebox": "^1.2.8",
-    "@themoltnet/agent-runtime": "0.41.3",
+    "@themoltnet/agent-runtime": "0.42.0",
     "@themoltnet/os-keyring": "0.2.0",
-    "@themoltnet/sdk": "0.132.0",
+    "@themoltnet/sdk": "0.133.0",
     "@themoltnet/shell-command-analyzer": "0.3.0"
   },
   "peerDependencies": {
@@ -51,9 +51,9 @@
     "vite": "^8.0.0",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^3.0.0",
-    "@moltnet/crypto-service": "0.1.0",
+    "@moltnet/models": "0.1.0",
     "@moltnet/tasks": "0.1.0",
-    "@moltnet/models": "0.1.0"
+    "@moltnet/crypto-service": "0.1.0"
   },
   "engines": {
     "node": ">=24"