@zihanw/pi-forge 0.4.0 → 0.5.0

package/dist/subagent/index.js

@@ -1,14 +1,13 @@
 /**
- * Experimental runner-neutral subagent adapter surface.
+ * Versioned `/subagent` host port: the minimal Forge DTO host contract.
  *
- * The package root continues to re-export these names for 0.4 compatibility.
- * New adapter integrations should import from `@zihanw/pi-forge/subagent` so
- * they do not depend on the Pi extension composition entry point.
- *
- * Execution ownership (backend registry, sealing, lifecycle, process
- * backends) now lives in `@zihanw/pi-subagent-runtime`; this surface keeps
- * the Forge host contracts: profiles, compilation, approval, and reporting.
+ * Wire messages, recursive validators, transport, and client/host lifecycle,
+ * plus the Forge-owned canonical fingerprint helpers used for host-issued
+ * profile snapshots. The main package carries no dependency on
+ * `@zihanw/pi-subagent-runtime`; the execution contract (request, preflight,
+ * plan, response, context, tool negotiation) lives in the optional
+ * `@zihanw/pi-forge-subagents` package, which consumes this port.
  */
-export * from "./contract.js";
-export { appendProtectedAgentTask, collectMacroCommandNames, collectSubagentPromptDependencies, compileProtectedAgentTaskMessages, currentSubagentPromptRegistrationCatalog, isProtectedAgentTaskPreserved, prepareSubagentHostPlan, resolveSubagentHostProfile, } from "../subagent-host.js";
+export { FORGE_HOST_CHANNEL, FORGE_HOST_PORT_NAMESPACE, FORGE_HOST_PORT_OPERATIONS, FORGE_HOST_PORT_VERSION, ForgeHost, ForgeHostClient, ForgeHostPortError, validateListProfilesRequest, validateListProfilesResponse, validatePrepareRequest, validatePrepareResponse, validateResolveProfileRequest, validateResolveProfileResponse, } from "./host-port.js";
+export { SUBAGENT_FINGERPRINT_PREFIX, canonicalSubagentJson, subagentFingerprint, subagentPromptStackFingerprint, subagentSourceProfileFingerprint, } from "./fingerprints.js";
 //# sourceMappingURL=index.js.map

package/dist/subagent/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/subagent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,cAAc,eAAe,CAAC;AAC9B,OAAO,EACN,wBAAwB,EACxB,wBAAwB,EACxB,iCAAiC,EACjC,iCAAiC,EACjC,wCAAwC,EACxC,6BAA6B,EAC7B,uBAAuB,EACvB,0BAA0B,GAI1B,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/subagent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACN,kBAAkB,EAClB,yBAAyB,EACzB,0BAA0B,EAC1B,uBAAuB,EACvB,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,2BAA2B,EAC3B,4BAA4B,EAC5B,sBAAsB,EACtB,uBAAuB,EACvB,6BAA6B,EAC7B,8BAA8B,GAC9B,MAAM,gBAAgB,CAAC;AA2BxB,OAAO,EACN,2BAA2B,EAC3B,qBAAqB,EACrB,mBAAmB,EACnB,8BAA8B,EAC9B,gCAAgC,GAEhC,MAAM,mBAAmB,CAAC"}

package/dist/subagent-host.d.ts

@@ -1,10 +1,61 @@
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { LoadedAgentProfile } from "./agent-profile.ts";
-import { type AgentProfileSnapshot, type SubagentDependencyKind, type SubagentDiagnostic, type SubagentPromptDependency, type SubagentPreparationInput, type SubagentPreparationOutput } from "./subagent/contract.ts";
-import type { LoadedPromptStack, PromptRuntime, PromptStack } from "./types.ts";
+import type { AgentProfile } from "./codecs/agent-profile.ts";
+import { type SubagentFingerprint } from "./subagent/fingerprints.ts";
+import type { ForgeBackendFacts, ForgeBackendTool, ForgePromptAccessFacts } from "./subagent/host-port.ts";
+import type { LoadedPromptStack, PromptResourcePolicy, PromptStack } from "./types.ts";
+/**
+ * Host-owned diagnostic shape for delegation resolution and preparation.
+ * Structurally compatible with the optional package's contract diagnostics.
+ */
+export interface ForgeDelegationDiagnostic {
+    level: "error" | "warning" | "info";
+    code: string;
+    path?: string;
+    message: string;
+}
+export type ForgePromptDependencyKind = "macro" | "slot";
+export interface ForgePromptDependency {
+    kind: ForgePromptDependencyKind;
+    name: string;
+    identity: string;
+    source?: string;
+}
+/**
+ * Host-owned immutable profile snapshot artifact returned by `resolveProfile`
+ * and embedded in `prepare` responses. The optional package validates and
+ * binds it into execution plans; the wire schema version is shared with the
+ * execution contract by design.
+ */
+export declare const FORGE_PROFILE_SNAPSHOT_VERSION: 1;
+export interface ForgeProfileSnapshot {
+    schemaVersion: typeof FORGE_PROFILE_SNAPSHOT_VERSION;
+    /** Canonical scoped selector of the resolved profile (`project:<id>` or `global:<id>`). */
+    profileId: string;
+    profile: AgentProfile;
+    /** Canonical scoped selector of the resolved prompt stack, or null. */
+    promptStackId: string | null;
+    promptStack: PromptStack | null;
+    dependencies: ForgePromptDependency[];
+    profileFingerprint: SubagentFingerprint;
+    promptStackFingerprint: SubagentFingerprint | null;
+}
+/**
+ * Host-compiled delegation message. Text-only on the host side; the optional
+ * package projects these onto the runtime's portable prepared messages.
+ */
+export interface ForgeDelegationMessage {
+    role: "user" | "assistant" | "custom";
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    protectedTask?: boolean;
+    source?: "prompt-stack" | "delegated-task";
+}
 export interface SubagentPromptRegistration {
     name: string;
     source?: string;
+    dependencies?: string[];
 }
 export interface SubagentPromptRegistrationCatalog {
     macros: SubagentPromptRegistration[];
@@ -12,33 +63,63 @@ export interface SubagentPromptRegistrationCatalog {
 }
 export interface SubagentHostResolution {
     profileId: string;
-    snapshot?: AgentProfileSnapshot;
-    dependencies: SubagentPromptDependency[];
+    snapshot?: ForgeProfileSnapshot;
+    dependencies: ForgePromptDependency[];
     missingDependencies: Array<{
-        kind: SubagentDependencyKind;
+        kind: ForgePromptDependencyKind;
         name: string;
     }>;
-    diagnostics: SubagentDiagnostic[];
+    diagnostics: ForgeDelegationDiagnostic[];
+}
+export interface ForgeDelegationPreparationInput {
+    snapshot: ForgeProfileSnapshot;
+    task: {
+        text: string;
+    };
+    access: ForgePromptAccessFacts;
+    backend: ForgeBackendFacts;
+    cwd: string;
+}
+export interface ForgeDelegationPreparation {
+    systemPrompt: string;
+    messages: ForgeDelegationMessage[];
+    effectiveToolIds: string[];
+    effectiveToolNames: string[];
+    diagnostics: ForgeDelegationDiagnostic[];
+    preparedAt: string;
 }
 export declare function currentSubagentPromptRegistrationCatalog(): SubagentPromptRegistrationCatalog;
 export declare function resolveSubagentHostProfile(loaded: LoadedAgentProfile, resources: {
     promptStacks: readonly LoadedPromptStack[];
     registrations?: SubagentPromptRegistrationCatalog;
 }): SubagentHostResolution;
-export declare function prepareSubagentHostPlan(input: SubagentPreparationInput): SubagentPreparationOutput;
+/**
+ * Forge-native host-owned preparation: negotiate the client tool catalog
+ * against stack policy and access facts, compile the resolved stack through
+ * one compilation context, and append the protected delegated task. No
+ * execution/runtime material (AgentRequest, preflight, limits, or plan
+ * fingerprints) is involved; the optional package owns those.
+ */
+export declare function prepareForgeDelegation(input: ForgeDelegationPreparationInput): ForgeDelegationPreparation;
+interface ForgeToolNegotiation {
+    effectiveToolIds: string[];
+    effectiveToolNames: string[];
+    diagnostics: ForgeDelegationDiagnostic[];
+}
+/**
+ * Intersect the client-supplied tool catalog with stack tool policy and the
+ * prompt-compilation access facts. Semantics mirror the execution contract's
+ * tool negotiation in the optional package, which recomputes them as the
+ * plan-creation integrity check.
+ */
+export declare function negotiateForgeDelegationTools(catalog: readonly ForgeBackendTool[], policy: PromptResourcePolicy | undefined, access: ForgePromptAccessFacts): ForgeToolNegotiation;
 export declare function collectSubagentPromptDependencies(stack: PromptStack, registrations?: SubagentPromptRegistrationCatalog): {
-    dependencies: SubagentPromptDependency[];
+    dependencies: ForgePromptDependency[];
     missingDependencies: Array<{
-        kind: SubagentDependencyKind;
+        kind: ForgePromptDependencyKind;
         name: string;
     }>;
-    diagnostics: SubagentDiagnostic[];
-};
-export declare function collectMacroCommandNames(text: string): string[];
-export declare function appendProtectedAgentTask(compiledMessages: readonly AgentMessage[], protectedTask: AgentMessage): AgentMessage[];
-export declare function compileProtectedAgentTaskMessages(stack: LoadedPromptStack, runtime: PromptRuntime, originalMessages: readonly AgentMessage[]): {
-    messages: AgentMessage[];
-    diagnostics: import("./types.ts").PromptStackDiagnostic[];
+    diagnostics: ForgeDelegationDiagnostic[];
 };
-export declare function isProtectedAgentTaskPreserved(messages: readonly AgentMessage[], task: AgentMessage): boolean;
+export {};
 //# sourceMappingURL=subagent-host.d.ts.map

package/dist/subagent-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subagent-host.d.ts","sourceRoot":"","sources":["../src/subagent-host.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAUlE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,EAKN,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAE9B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEhF,MAAM,WAAW,0BAA0B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iCAAiC;IACjD,MAAM,EAAE,0BAA0B,EAAE,CAAC;IACrC,KAAK,EAAE,0BAA0B,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,sBAAsB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,YAAY,EAAE,wBAAwB,EAAE,CAAC;IACzC,mBAAmB,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,sBAAsB,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3E,WAAW,EAAE,kBAAkB,EAAE,CAAC;CAClC;AAcD,wBAAgB,wCAAwC,IAAI,iCAAiC,CAK5F;AAED,wBAAgB,0BAA0B,CACzC,MAAM,EAAE,kBAAkB,EAC1B,SAAS,EAAE;IACV,YAAY,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC3C,aAAa,CAAC,EAAE,iCAAiC,CAAC;CAClD,GACC,sBAAsB,CAyDxB;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,wBAAwB,GAAG,yBAAyB,CA4ClG;AAED,wBAAgB,iCAAiC,CAChD,KAAK,EAAE,WAAW,EAClB,aAAa,GAAE,iCAA8E,GAC3F;IACF,YAAY,EAAE,wBAAwB,EAAE,CAAC;IACzC,mBAAmB,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,sBAAsB,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3E,WAAW,EAAE,kBAAkB,EAAE,CAAC;CAClC,CAyBA;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAI/D;AAED,wBAAgB,wBAAwB,CACvC,gBAAgB,EAAE,SAAS,YAAY,EAAE,EACzC,aAAa,EAAE,YAAY,GACzB,YAAY,EAAE,CAGhB;AAED,wBAAgB,iCAAiC,CAChD,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,aAAa,EACtB,gBAAgB,EAAE,SAAS,YAAY,EAAE,GACvC;IAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;IAAC,WAAW,EAAE,OAAO,YAAY,EAAE,qBAAqB,EAAE,CAAA;CAAE,CAOzF;AAED,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAM5G"}
+{"version":3,"file":"subagent-host.d.ts","sourceRoot":"","sources":["../src/subagent-host.ts"],"names":[],"mappings":"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"}

package/dist/subagent-host.js

@@ -1,16 +1,20 @@
 import { getRegisteredMacros, } from "./macro-engine.js";
 import { getRegisteredSlots, } from "./slot-renderers.js";
-import { compileMessages, compileSystemPrompt, createPromptVariableStore } from "./compiler.js";
-import { subagentPromptStackFingerprint, subagentSourceProfileFingerprint, negotiateSubagentTools, prepareSubagentInitialMessages, } from "./subagent/contract.js";
-const BUILT_IN_MACROS = new Set([
-    "cwd", "date", "time", "lastUserMessage", "selectedTools", "tools", "activeModel",
-    "setvar", "setturnvar", "setsessionvar", "getvar", "var", "getturnvar", "getsessionvar",
-    "clearvar", "clearturnvar", "clearsessionvar", "trim", "upper", "lower", "json", "xml",
-    "ifvar", "ifeq", "iftools", "ifslot",
-]);
+import { PromptCompilationContext } from "./compiler.js";
+import { applyResourcePolicy, resourcePatternMatches } from "./policy.js";
+import { subagentPromptStackFingerprint, subagentSourceProfileFingerprint, } from "./subagent/fingerprints.js";
+import { formatResourceKey, parseResourceSelector } from "./resource-identity.js";
+import { analyzePromptStack } from "./prompt-analysis.js";
+/**
+ * Host-owned immutable profile snapshot artifact returned by `resolveProfile`
+ * and embedded in `prepare` responses. The optional package validates and
+ * binds it into execution plans; the wire schema version is shared with the
+ * execution contract by design.
+ */
+export const FORGE_PROFILE_SNAPSHOT_VERSION = 1;
 const BUILT_IN_SLOTS = new Set([
     "chat-history", "tools", "tool-guidelines", "skills", "project-context", "append-system-prompt",
-    "date", "cwd", "date-cwd", "active-model", "pi-docs", "variables",
+    "date", "cwd", "date-cwd", "active-model", "pi-docs",
 ]);
 export function currentSubagentPromptRegistrationCatalog() {
     return {
@@ -27,31 +31,54 @@ export function resolveSubagentHostProfile(loaded, resources) {
     }));
     const registrations = resources.registrations ?? currentSubagentPromptRegistrationCatalog();
     let promptStack;
+    let promptStackId = null;
     if (loaded.profile.promptStack !== null) {
-        const matches = resources.promptStacks.filter((candidate) => candidate.stack.id === loaded.profile.promptStack);
-        if (matches.length !== 1) {
+        const reference = loaded.profile.promptStack;
+        const parsed = parseResourceSelector(reference);
+        if (!parsed.ok) {
+            diagnostics.push({
+                level: "error",
+                code: "profile.stack-reference",
+                path: "profile.promptStack",
+                message: parsed.error,
+            });
+        }
+        else if (loaded.scope === "global" && parsed.selector.scope === "project") {
             diagnostics.push({
                 level: "error",
-                code: matches.length === 0 ? "profile.stack-missing" : "profile.stack-ambiguous",
+                code: "profile.stack-reference",
                 path: "profile.promptStack",
-                message: matches.length === 0
-                    ? `Unknown prompt stack: ${loaded.profile.promptStack}`
-                    : `Prompt stack id is ambiguous: ${loaded.profile.promptStack}`,
+                message: `Global profile ${loaded.profile.id} cannot reference project prompt stack ${parsed.selector.id}.`,
             });
         }
         else {
-            promptStack = matches[0];
-            for (const diagnostic of promptStack.diagnostics) {
+            const scope = parsed.selector.scope ?? loaded.scope;
+            const matches = resources.promptStacks.filter((candidate) => candidate.scope === scope && candidate.stack.id === parsed.selector.id);
+            if (matches.length !== 1) {
                 diagnostics.push({
-                    level: diagnostic.level,
-                    code: "profile.stack-validation",
-                    path: diagnostic.itemId ? `promptStack.items.${diagnostic.itemId}` : "promptStack",
-                    message: diagnostic.message,
+                    level: "error",
+                    code: matches.length === 0 ? "profile.stack-missing" : "profile.stack-ambiguous",
+                    path: "profile.promptStack",
+                    message: matches.length === 0
+                        ? `Unknown prompt stack: ${reference}`
+                        : `Prompt stack id is ambiguous: ${reference}`,
                 });
             }
-            if (!promptStack.stack.mode || !["replace", "append", "prepend"].includes(promptStack.stack.mode)) {
-                if (promptStack.stack.mode !== undefined)
-                    diagnostics.push({ level: "error", code: "profile.stack-mode", path: "promptStack.mode", message: `Unsupported prompt stack mode: ${String(promptStack.stack.mode)}` });
+            else {
+                promptStack = matches[0];
+                promptStackId = formatResourceKey({ scope, id: parsed.selector.id });
+                for (const diagnostic of promptStack.diagnostics) {
+                    diagnostics.push({
+                        level: diagnostic.level,
+                        code: "profile.stack-validation",
+                        path: diagnostic.itemId ? `promptStack.items.${diagnostic.itemId}` : "promptStack",
+                        message: diagnostic.message,
+                    });
+                }
+                if (!promptStack.stack.mode || !["replace", "append", "prepend"].includes(promptStack.stack.mode)) {
+                    if (promptStack.stack.mode !== undefined)
+                        diagnostics.push({ level: "error", code: "profile.stack-mode", path: "promptStack.mode", message: `Unsupported prompt stack mode: ${String(promptStack.stack.mode)}` });
+                }
             }
         }
     }
@@ -60,15 +87,17 @@ export function resolveSubagentHostProfile(loaded, resources) {
         : { dependencies: [], missingDependencies: [], diagnostics: [] };
     diagnostics.push(...dependencyResult.diagnostics);
     const resolution = {
-        profileId: loaded.profile.id,
+        profileId: formatResourceKey(loaded.key),
         dependencies: dependencyResult.dependencies,
         missingDependencies: dependencyResult.missingDependencies,
         diagnostics,
     };
     if (!diagnostics.some((diagnostic) => diagnostic.level === "error")) {
         resolution.snapshot = {
-            schemaVersion: 1,
+            schemaVersion: FORGE_PROFILE_SNAPSHOT_VERSION,
+            profileId: formatResourceKey(loaded.key),
             profile: structuredClone(loaded.profile),
+            promptStackId,
             promptStack: promptStack ? structuredClone(promptStack.stack) : null,
             dependencies: structuredClone(dependencyResult.dependencies),
             profileFingerprint: subagentSourceProfileFingerprint(loaded.profile),
@@ -77,107 +106,171 @@ export function resolveSubagentHostProfile(loaded, resources) {
     }
     return resolution;
 }
-export function prepareSubagentHostPlan(input) {
-    const toolNegotiation = negotiateSubagentTools(input.preflight.toolCatalog, input.snapshot.promptStack?.tools, input.request.access);
-    const options = {
-        ...structuredClone(input.runtime.options),
-        selectedTools: [...toolNegotiation.effectiveToolNames],
-        toolSnippets: Object.fromEntries(Object.entries(input.runtime.options.toolSnippets)
-            .filter(([name]) => toolNegotiation.effectiveToolNames.includes(name))),
-        promptGuidelines: toolNegotiation.effectiveToolNames.length > 0
-            ? [...input.runtime.options.promptGuidelines]
-            : [],
-        skills: structuredClone(input.runtime.options.skills),
-        contextFiles: [...input.runtime.options.contextFiles],
-    };
-    const model = {
-        provider: input.runtime.model.provider,
-        id: input.runtime.model.id,
-        api: "unknown",
-    };
+/**
+ * Forge-native host-owned preparation: negotiate the client tool catalog
+ * against stack policy and access facts, compile the resolved stack through
+ * one compilation context, and append the protected delegated task. No
+ * execution/runtime material (AgentRequest, preflight, limits, or plan
+ * fingerprints) is involved; the optional package owns those.
+ */
+export function prepareForgeDelegation(input) {
+    const negotiation = negotiateForgeDelegationTools(input.backend.toolCatalog, input.snapshot.promptStack?.tools, input.access);
+    const preparedAt = new Date().toISOString();
     const runtime = {
-        options,
-        ctx: { model },
-        latestUserMessage: input.request.input.text,
-        now: new Date(input.runtime.preparedAt),
-        variables: createPromptVariableStore(),
+        options: {
+            cwd: input.cwd,
+            selectedTools: negotiation.effectiveToolNames,
+            toolSnippets: {},
+            promptGuidelines: [],
+            contextFiles: [],
+            skills: [],
+        },
+        model: {
+            provider: input.backend.model.provider,
+            id: input.backend.model.id,
+            api: "unknown",
+        },
+        latestUserMessage: input.task.text,
+        now: new Date(preparedAt),
     };
-    let systemPrompt = input.runtime.baseSystemPrompt;
+    const diagnostics = [...negotiation.diagnostics];
+    let systemPrompt = "";
     let stackMessages = [];
-    const diagnostics = [];
-    if (input.snapshot.promptStack) {
-        const system = compileSystemPrompt(input.snapshot.promptStack, runtime, input.runtime.baseSystemPrompt);
+    const stack = input.snapshot.promptStack;
+    if (stack) {
+        const compilation = new PromptCompilationContext(stack, runtime);
+        const system = compilation.compileSystemPrompt("");
         systemPrompt = system.systemPrompt;
         diagnostics.push(...system.diagnostics.map((item) => promptDiagnostic("system", item)));
-        const messages = compileMessages(input.snapshot.promptStack, runtime, []);
+        const messages = compilation.compileMessages([]);
         stackMessages = messages.messages.map(preparedPromptStackMessage);
         diagnostics.push(...messages.diagnostics.map((item) => promptDiagnostic("messages", item)));
     }
-    const initial = prepareSubagentInitialMessages(input.request, stackMessages);
     return {
         systemPrompt,
-        messages: initial.messages,
-        contextBudget: initial.contextBudget,
-        toolNegotiation,
-        diagnostics: [...diagnostics, ...initial.diagnostics],
+        messages: appendProtectedDelegationTask(stackMessages, input.task),
+        effectiveToolIds: negotiation.effectiveToolIds,
+        effectiveToolNames: negotiation.effectiveToolNames,
+        diagnostics,
+        preparedAt,
+    };
+}
+/**
+ * Intersect the client-supplied tool catalog with stack tool policy and the
+ * prompt-compilation access facts. Semantics mirror the execution contract's
+ * tool negotiation in the optional package, which recomputes them as the
+ * plan-creation integrity check.
+ */
+export function negotiateForgeDelegationTools(catalog, policy, access) {
+    const diagnostics = [];
+    const tools = catalog.map((tool) => ({
+        id: tool.id,
+        name: tool.name ?? tool.id,
+        effects: [...(tool.effects ?? [])],
+    }));
+    const names = tools.map((tool) => tool.name);
+    const stackSelectedToolNames = applyResourcePolicy(names, policy);
+    const selected = new Set(stackSelectedToolNames);
+    const effective = tools.filter((tool) => selected.has(tool.name) && toolAllowedByAccess(tool, access));
+    const unmatchedAllowPatterns = policy && "allow" in policy
+        ? (policy.allow ?? []).filter((pattern) => pattern !== "*" && !names.some((name) => resourcePatternMatches(name, pattern)))
+        : [];
+    for (const pattern of unmatchedAllowPatterns) {
+        diagnostics.push({ level: "warning", code: "tools.unmatched-allow", path: "tools.allow", message: `Tool allow pattern matches no backend tools: ${pattern}` });
+    }
+    for (const tool of tools) {
+        if (selected.has(tool.name) && !effective.includes(tool)) {
+            diagnostics.push({ level: "info", code: "tools.access-filtered", path: `tools.${tool.name}`, message: `Tool ${tool.name} was removed by request access policy.` });
+        }
+    }
+    return {
+        effectiveToolIds: effective.map((tool) => tool.id),
+        effectiveToolNames: effective.map((tool) => tool.name),
+        diagnostics,
     };
 }
+function toolAllowedByAccess(tool, access) {
+    for (const effect of tool.effects) {
+        if (effect === "network" && access.network !== "allow")
+            return false;
+        if (effect === "process" && access.allowProcess !== true)
+            return false;
+        if (effect === "filesystem-read" && access.level === "none")
+            return false;
+        if (effect === "filesystem-write" && access.level !== "workspace-write")
+            return false;
+    }
+    return true;
+}
 export function collectSubagentPromptDependencies(stack, registrations = currentSubagentPromptRegistrationCatalog()) {
     const diagnostics = [];
     const dependencies = new Map();
     const missing = new Map();
     const macroCatalog = new Map(registrations.macros.map((entry) => [entry.name, entry]));
     const slotCatalog = new Map(registrations.slots.map((entry) => [entry.name, entry]));
-    const staticVariables = new Set(Object.keys(stack.variables ?? {}));
+    const parameters = new Set([
+        ...Object.keys(stack.parameters ?? {}),
+        ...Object.keys(stack.variables ?? {}),
+    ]);
+    const analysis = analyzePromptStack(stack, registrations);
+    for (const error of analysis.diagnostics) {
+        diagnostics.push({
+            level: "error",
+            code: "prompt-stack.template-analyze",
+            path: "promptStack",
+            message: error.message,
+        });
+    }
     for (const item of stack.items) {
         if (item.kind === "slot") {
             if (BUILT_IN_SLOTS.has(item.slot))
                 continue;
             addDependency("slot", item.slot, slotCatalog, dependencies, missing, diagnostics, `promptStack.items.${item.id}`);
-            continue;
         }
-        for (const name of collectMacroCommandNames(item.content)) {
-            if (BUILT_IN_MACROS.has(name) || staticVariables.has(name))
+    }
+    for (const block of analysis.blocks) {
+        for (const dependency of block.dependencies) {
+            let name;
+            if (dependency.kind === "extensions")
+                name = dependency.path?.[1];
+            if (dependency.kind === "legacy") {
+                const candidate = dependency.path?.[0];
+                if (!candidate || parameters.has(candidate) || LEGACY_BUILTIN_RUNTIME.has(candidate))
+                    continue;
+                name = candidate;
+            }
+            if (!name)
                 continue;
-            addDependency("macro", name, macroCatalog, dependencies, missing, diagnostics, `promptStack.items.${item.id}`);
+            addDependency("macro", name, macroCatalog, dependencies, missing, diagnostics, `promptStack.items.${block.itemId}`);
         }
     }
+    for (const name of analysis.transitiveExtensions) {
+        if (!name || macroCatalog.has(name))
+            continue;
+        addDependency("macro", name, macroCatalog, dependencies, missing, diagnostics, "promptStack");
+    }
     return {
         dependencies: [...dependencies.values()].sort(compareDependencies),
         missingDependencies: [...missing.values()].sort(compareDependencies),
         diagnostics,
     };
 }
-export function collectMacroCommandNames(text) {
-    const names = new Set();
-    collectMacroCommandsInto(text, names);
-    return [...names].sort();
-}
-export function appendProtectedAgentTask(compiledMessages, protectedTask) {
-    if (protectedTask.role !== "user")
-        throw new Error("Protected delegated task must be a user message.");
-    return [...structuredClone(compiledMessages), structuredClone(protectedTask)];
-}
-export function compileProtectedAgentTaskMessages(stack, runtime, originalMessages) {
-    const taskIndex = findLastUserMessageIndex(originalMessages);
-    if (taskIndex === -1)
-        throw new Error("Delegated context contains no final user task.");
-    const protectedTask = structuredClone(originalMessages[taskIndex]);
-    const history = originalMessages.filter((_message, index) => index !== taskIndex);
-    const compiled = compileMessages(stack.stack, runtime, history);
-    return { messages: appendProtectedAgentTask(compiled.messages, protectedTask), diagnostics: compiled.diagnostics };
-}
-export function isProtectedAgentTaskPreserved(messages, task) {
-    if (!messages.length || task.role !== "user")
-        return false;
-    const finalMessage = messages.at(-1);
-    if (finalMessage?.role !== "user")
-        return false;
-    return normalizeUserContent(finalMessage.content)
-        === normalizeUserContent(task.content);
+const LEGACY_BUILTIN_RUNTIME = new Set([
+    "cwd", "date", "time", "lastUserMessage", "selectedTools", "tools", "activeModel",
+]);
+function appendProtectedDelegationTask(messages, task) {
+    return [
+        ...structuredClone(messages),
+        {
+            role: "user",
+            content: [{ type: "text", text: task.text }],
+            protectedTask: true,
+            source: "delegated-task",
+        },
+    ];
 }
 function registrationEntry(definition) {
-    return { name: definition.name, source: definition.source };
+    return { name: definition.name, source: definition.source, dependencies: definition.dependencies };
 }
 function addDependency(kind, name, catalog, dependencies, missing, diagnostics, path) {
     const key = `${kind}:${name}`;
@@ -192,76 +285,6 @@ function addDependency(kind, name, catalog, dependencies, missing, diagnostics,
     if (!registration.source)
         diagnostics.push({ level: "warning", code: "profile.dependency-anonymous", path, message: `Custom ${kind} ${name} has no stable source identity.` });
 }
-function collectMacroCommandsInto(text, names) {
-    let index = 0;
-    while (index < text.length) {
-        const start = text.indexOf("{{", index);
-        if (start === -1)
-            return;
-        const end = findMacroEnd(text, start + 2);
-        if (end === undefined)
-            return;
-        const expression = text.slice(start + 2, end).trim();
-        const parts = splitMacroExpression(expression);
-        const command = parts[0]?.trim();
-        if (command && /^[A-Za-z][A-Za-z0-9_.-]*$/.test(command))
-            names.add(command);
-        for (const argument of parts.slice(1))
-            collectMacroCommandsInto(argument, names);
-        index = end + 2;
-    }
-}
-function findMacroEnd(text, start) {
-    let depth = 1;
-    for (let index = start; index < text.length - 1; index++) {
-        const pair = text.slice(index, index + 2);
-        if (pair === "{{") {
-            depth++;
-            index++;
-        }
-        else if (pair === "}}") {
-            depth--;
-            if (depth === 0)
-                return index;
-            index++;
-        }
-    }
-    return undefined;
-}
-function splitMacroExpression(expression) {
-    const parts = [];
-    let start = 0;
-    let depth = 0;
-    for (let index = 0; index < expression.length - 1; index++) {
-        const pair = expression.slice(index, index + 2);
-        if (pair === "{{") {
-            depth++;
-            index++;
-        }
-        else if (pair === "}}" && depth > 0) {
-            depth--;
-            index++;
-        }
-        else if (pair === "::" && depth === 0) {
-            parts.push(expression.slice(start, index));
-            start = index + 2;
-            index++;
-        }
-    }
-    parts.push(expression.slice(start));
-    return parts;
-}
-function findLastUserMessageIndex(messages) {
-    for (let index = messages.length - 1; index >= 0; index--) {
-        if (messages[index]?.role === "user")
-            return index;
-    }
-    return -1;
-}
-function normalizeUserContent(content) {
-    const normalized = typeof content === "string" ? [{ type: "text", text: content }] : Array.isArray(content) ? content : [content];
-    return JSON.stringify(normalized);
-}
 function preparedPromptStackMessage(message) {
     if (message.role !== "user" && message.role !== "assistant" && message.role !== "custom") {
         throw new Error(`Unsupported prompt-stack message role for subagent preparation: ${message.role}`);