@tangle-network/agent-profile-materialize 0.9.3 → 0.10.0

package/dist/index.d.ts

@@ -21,7 +21,13 @@
  * `node:fs` IO consumer. It was previously copied byte-for-byte into both
  * cli-bridge and agent-dev-container — this is the single source those re-export.
  */
-import type { AgentCandidateConfigValue, AgentCandidateProfile, AgentCandidateProfileActivation, AgentCandidateProfileApplication, AgentCandidateProfilePlanEvidence, AgentCandidateProfilePlanMaterial, AgentProfile, AgentProfileMcpServer, Sha256Digest } from "@tangle-network/agent-interface";
+import type { AgentCandidateConfigValue, AgentCandidateProfile, AgentCandidateProfileActivation, AgentCandidateProfileApplication, AgentCandidateProfilePlanEvidence, AgentCandidateProfilePlanMaterial, AgentProfile, AgentProfileConfigValue, AgentProfileMcpServer, AgentProfileSecretProvider, AgentProfileSecretRef, Sha256Digest } from "@tangle-network/agent-interface";
+export declare const UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER: AgentProfileSecretProvider;
+/**
+ * The harnesses this materializer can lower an AgentProfile into. `satisfies` binds every id to
+ * the canonical harness enum, so a rename upstream is a compile error here rather than an
+ * `isMaterializerHarness` that silently returns false for a harness that still exists.
+ */
 export declare const MATERIALIZER_HARNESSES: readonly ["claude-code", "nanoclaw", "codex", "opencode", "kimi-code", "pi", "gemini", "hermes", "openclaw"];
 export type HarnessId = (typeof MATERIALIZER_HARNESSES)[number];
 export declare function isMaterializerHarness(harness: string): harness is HarnessId;
@@ -50,24 +56,94 @@ export interface PlanFile {
      * this on every file it emits.
      */
     source?: "user" | "generated";
+    /**
+     * Secret leaves in a generated JSON document. `content` contains `null` at
+     * each path until the private executor resolves the named reference. The
+     * public plan, its digest, and its receipt retain only these references.
+     */
+    secretSlots?: PlanFileSecretSlot[];
 }
+export interface PlanFileSecretSlot {
+    path: Array<string | number>;
+    ref: AgentProfileSecretRef;
+}
+export interface WorkspacePlanSecretSegment {
+    kind: "secret";
+    ref: AgentProfileSecretRef;
+    /** Encoding applied after private resolution. */
+    encoding: "raw" | "json-string";
+}
+/** A launch argument whose private leaves are resolved immediately before spawn. */
+export interface WorkspacePlanArgumentTemplate {
+    kind: "workspace-plan-argument-template";
+    segments: Array<string | WorkspacePlanSecretSegment>;
+}
+export type WorkspacePlanArgument = string | WorkspacePlanArgumentTemplate;
+/** Public bytes stay strings; secret references stay opaque until application. */
+export type WorkspacePlanConfigValue = string | AgentProfileSecretRef;
 export interface Unsupported {
     dimension: "files" | "skills" | "mcp" | "hooks" | "subagents" | "commands" | "instructions" | "systemPrompt" | "connections" | "confidential" | "permissions" | "tools" | "modes" | "extensions";
     reason: string;
 }
+/**
+ * The dimensions `materializeProfile`'s `skip` option honors.
+ *
+ * Every other dimension is materialized unconditionally: generated plan files are pushed through
+ * a single site that carries no dimension tag, so there is nothing to gate them on. Naming the
+ * honored set keeps `skip: ["hooks"]` a loud rejection instead of a silent no-op.
+ */
+export declare const SKIPPABLE_DIMENSIONS: readonly ["mcp", "extensions"];
+export type SkippableDimension = (typeof SKIPPABLE_DIMENSIONS)[number];
+export declare function isSkippableDimension(value: string): value is SkippableDimension;
 /** The plan a caller writes into the run cwd, then applies to the spawn. */
 export interface WorkspacePlan {
     harness: HarnessId;
     /** Files to write relative to the run workspace (cwd). */
     files: PlanFile[];
     /** Env vars to set on the spawned process (for harnesses needing them). */
-    env: Record<string, string>;
+    env: Record<string, WorkspacePlanConfigValue>;
     /** Extra CLI flags to pass (e.g. kimi --mcp-config-file <path>). */
-    flags: string[];
+    flags: WorkspacePlanArgument[];
     /** Exact system-prompt replacement supplied to the harness. */
     systemPrompt?: string;
     /** Dimensions requested but with NO cwd path on this harness — fail-closed record. */
     unsupported: Unsupported[];
+    /**
+     * Prerequisites the workspace files CANNOT establish on their own.
+     *
+     * A plan is a set of files, an env map, and flags. Some harness capabilities need more than
+     * that to actually function: pi's MCP support is not built in, it arrives from an extension
+     * that must be installed into the harness's own package directory and permitted to load. No
+     * file written into a run workspace can make either true.
+     *
+     * Writing the config anyway and hoping is the failure this field exists to prevent: the
+     * harness starts, silently has no MCP, and the agent runs without the tools it was configured
+     * with while nothing reports a problem. So the plan states the requirement and the executor —
+     * which knows where its harness is installed and how it spawns — verifies or refuses it.
+     *
+     * Optional because this is an additive field on a published type: a plan built before it
+     * existed, or by a caller that does not construct one, is still a valid plan with no
+     * prerequisites. Every plan this package builds sets it.
+     */
+    requires?: PlanRequirement[];
+}
+/**
+ * One prerequisite a {@link WorkspacePlan} depends on but cannot create.
+ *
+ * Declarative on purpose: this package builds plans and never probes a filesystem, spawns a
+ * process, or reaches the network. The executor holds that context and does the checking.
+ */
+export interface PlanRequirement {
+    /** The only kind so far: a harness extension/plugin that must be loaded for a dimension to work. */
+    kind: "harness-extension";
+    /** Dimension that produced the requirement, so a refusal can name what will not work. */
+    dimension: Unsupported["dimension"];
+    /** Package spec in the harness's own vocabulary, e.g. `npm:pi-mcp-adapter`. */
+    id: string;
+    /** Why the plan needs it — goes verbatim into the executor's refusal message. */
+    reason: string;
+    /** The exact command that satisfies it, so a failure is actionable without a doc lookup. */
+    remedy: string;
 }
 /**
  * Proof of the profile workspace inputs applied before a harness is spawned.
@@ -76,12 +152,27 @@ export interface WorkspacePlan {
  */
 export interface WorkspacePlanReceipt {
     workspacePlanDigest: string;
-    env: Record<string, string>;
-    flags: string[];
+    /** Public launch identity only; secret values never enter this receipt. */
+    env: Record<string, WorkspacePlanConfigValue>;
+    /** Public launch identity only; templates retain opaque secret references. */
+    flags: WorkspacePlanArgument[];
     systemPrompt?: string;
     unsupported: Unsupported[];
     written: string[];
 }
+/** Private values handed directly to the provider spawn, never to receipts. */
+export interface WorkspacePlanSpawnInputs {
+    env: Record<string, string>;
+    flags: string[];
+    systemPrompt?: string;
+}
+/** Result of applying a public plan at the private executor boundary. */
+export interface WorkspacePlanApplication {
+    receipt: WorkspacePlanReceipt;
+    spawn: WorkspacePlanSpawnInputs;
+    /** Resolved generated files intentionally consumed in memory by the runtime. */
+    runtimeOnlyFiles: Record<string, string>;
+}
 /** The plan was applied, but one or more private staging files remain. */
 export declare class WorkspacePlanCleanupError extends AggregateError {
     readonly receipt: WorkspacePlanReceipt;
@@ -185,7 +276,7 @@ export declare function normalizeSkillMd(name: string, raw: string): string;
  * The explicit target harness takes precedence over the profile's default.
  */
 export declare function materializeProfile(inputProfile: AgentProfile, harness: HarnessId, opts?: {
-    skip?: Unsupported["dimension"][];
+    skip?: SkippableDimension[];
 }): WorkspacePlan;
 /**
  * Materialize a sealed candidate profile without weakening its process values.
@@ -218,12 +309,18 @@ export declare function captureAgentCandidateProfilePlan(plan: AgentCandidateWor
  */
 export declare function applyAgentCandidateWorkspacePlan(plan: AgentCandidateWorkspacePlan, workspaceDir: string, targetWorkspace: AgentCandidateProfileApplication["targetWorkspace"]): AgentCandidateWorkspacePlanReceipt;
 /**
- * Apply a WorkspacePlan to a real workspace dir: write every file (creating parent
- * dirs), and return the env + flags the caller must hand the spawn. This is the IO
- * consumer of the pure `materializeProfile` — used by the cli-bridge host spawn, the
- * agent-dev-container box, and VB. Returns `unsupported` so the caller can log/fail.
+ * Apply a public-only WorkspacePlan. A plan with any secret reference fails
+ * before the first write; private executors use
+ * {@link applyWorkspacePlanWithSecretProvider} instead.
  */
 export declare function applyWorkspacePlan(plan: WorkspacePlan, workspaceDir: string, options?: ApplyWorkspacePlanOptions): WorkspacePlanReceipt;
+/**
+ * Resolve opaque profile references through an executor-owned provider, then
+ * apply the resulting private native files and launch inputs. Resolution
+ * completes before any workspace write, and resolved values never enter the
+ * public plan, digest, receipt, logs, or error messages.
+ */
+export declare function applyWorkspacePlanWithSecretProvider(plan: WorkspacePlan, workspaceDir: string, secretProvider: AgentProfileSecretProvider, options?: ApplyWorkspacePlanOptions): Promise<WorkspacePlanApplication>;
 /** Tool IDs reported by the OpenCode binary shipped in the Sandbox image. */
 export declare const OPENCODE_NATIVE_TOOL_IDS: readonly ["apply_patch", "bash", "codesearch", "edit", "glob", "grep", "question", "read", "skill", "task", "todowrite", "webfetch", "websearch", "write"];
 /** Resolve portable and legacy profile names to current OpenCode tool IDs. */
@@ -233,12 +330,12 @@ export type OpenCodeMcpConfig = Record<string, {
     type: "remote";
     url: string;
     enabled: boolean;
-    headers?: Record<string, string>;
+    headers?: Record<string, AgentProfileConfigValue>;
 } | {
     type: "local";
-    command: string[];
+    command: Array<string | AgentProfileConfigValue>;
     enabled: boolean;
-    environment?: Record<string, string>;
+    environment?: Record<string, AgentProfileConfigValue>;
 }>;
 /** Lower canonical MCP definitions to OpenCode's native startup configuration. */
 export declare function openCodeMcpConfig(mcp: Record<string, AgentProfileMcpServer>): OpenCodeMcpConfig;

package/dist/index.js

@@ -24,7 +24,12 @@
 import { createHash, randomUUID } from "node:crypto";
 import { closeSync, fchmodSync, constants as fsConstants, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep, win32, } from "node:path";
-import { agentCandidateProfileActivationSchema, agentCandidateProfilePlanEvidenceSchema, agentCandidateProfilePlanMaterialSchema, agentCandidateProfileSchema, agentProfileSchema, canonicalCandidateBytes, canonicalCandidateDigest, resolveNativeWebTools, } from "@tangle-network/agent-interface";
+import { agentCandidateProfileActivationSchema, agentCandidateProfilePlanEvidenceSchema, agentCandidateProfilePlanMaterialSchema, agentCandidateProfileSchema, agentProfileSchema, agentProfileSecretRefSchema, canonicalCandidateBytes, canonicalCandidateDigest, resolveNativeWebTools, } from "@tangle-network/agent-interface";
+export const UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER = Object.freeze({
+    async get() {
+        return undefined;
+    },
+});
 function describeUnresolvedRef(r) {
     const name = typeof r.name === "string" ? r.name : undefined;
     const path = typeof r.path === "string" ? r.path : undefined;
@@ -54,6 +59,11 @@ function resolveInlineRef(ref) {
     }
     return null; // github / unresolved
 }
+/**
+ * The harnesses this materializer can lower an AgentProfile into. `satisfies` binds every id to
+ * the canonical harness enum, so a rename upstream is a compile error here rather than an
+ * `isMaterializerHarness` that silently returns false for a harness that still exists.
+ */
 export const MATERIALIZER_HARNESSES = [
     "claude-code",
     "nanoclaw",
@@ -74,6 +84,32 @@ function assertMaterializerHarness(harness) {
         throw new Error(`Unsupported profile materialization harness "${harness}"`);
     }
 }
+/**
+ * The dimensions `materializeProfile`'s `skip` option honors.
+ *
+ * Every other dimension is materialized unconditionally: generated plan files are pushed through
+ * a single site that carries no dimension tag, so there is nothing to gate them on. Naming the
+ * honored set keeps `skip: ["hooks"]` a loud rejection instead of a silent no-op.
+ */
+export const SKIPPABLE_DIMENSIONS = [
+    "mcp",
+    "extensions",
+];
+const SKIPPABLE_DIMENSION_SET = new Set(SKIPPABLE_DIMENSIONS);
+export function isSkippableDimension(value) {
+    return SKIPPABLE_DIMENSION_SET.has(value);
+}
+/** Reject a dimension `materializeProfile` would not actually skip, rather than ignoring it. */
+function assertSkippableDimensions(skip) {
+    if (!skip)
+        return [];
+    const unsupportedSkips = skip.filter((dimension) => !isSkippableDimension(dimension));
+    if (unsupportedSkips.length > 0) {
+        throw new Error(`materializeProfile: cannot skip ${unsupportedSkips.join(", ")}. ` +
+            `Skippable dimensions are: ${SKIPPABLE_DIMENSIONS.join(", ")}.`);
+    }
+    return skip;
+}
 /** The plan was applied, but one or more private staging files remain. */
 export class WorkspacePlanCleanupError extends AggregateError {
     receipt;
@@ -187,6 +223,7 @@ const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
 const collapse = (s) => s.replace(/\s+/g, " ").trim();
 const compareStrings = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
 const DEFAULT_FILE_MODE = 0o644;
+const PRIVATE_FILE_MODE = 0o600;
 const EXECUTABLE_FILE_MODE = 0o755;
 const DEFAULT_RESOURCE_FETCH_TIMEOUT_MS = 30_000;
 const MAX_RESOURCE_BYTES = 10 * 1024 * 1024;
@@ -437,6 +474,96 @@ export function normalizeSkillMd(name, raw) {
     return `---\nname: ${name}\ndescription: ${JSON.stringify(desc)}\n---\n\n${body}\n`;
 }
 const tomlStr = (s) => JSON.stringify(s); // valid TOML basic string
+function isProfilePublicConfigValue(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value.kind === "public" &&
+        typeof value.value === "string");
+}
+function isProfileSecretRef(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value.kind === "secret-ref" &&
+        typeof value.key === "string");
+}
+function workspacePlanConfigValue(value) {
+    return isProfilePublicConfigValue(value) ? value.value : { ...value };
+}
+function serializeWorkspacePlanJson(value) {
+    const secretSlots = [];
+    const lower = (current, path, arrayEntry = false) => {
+        if (isProfilePublicConfigValue(current))
+            return current.value;
+        if (isProfileSecretRef(current)) {
+            secretSlots.push({ path: [...path], ref: { ...current } });
+            return null;
+        }
+        if (Array.isArray(current)) {
+            return current.map((entry, index) => lower(entry, [...path, index], true));
+        }
+        if (current && typeof current === "object") {
+            const output = Object.create(null);
+            for (const [key, entry] of Object.entries(current)) {
+                const lowered = lower(entry, [...path, key]);
+                if (lowered !== undefined) {
+                    Object.defineProperty(output, key, {
+                        value: lowered,
+                        enumerable: true,
+                        configurable: true,
+                        writable: true,
+                    });
+                }
+            }
+            return output;
+        }
+        return current === undefined && arrayEntry ? null : current;
+    };
+    const content = JSON.stringify(lower(value, []), null, 2);
+    if (content === undefined) {
+        throw new Error("Generated profile JSON must have a serializable root");
+    }
+    return {
+        content,
+        ...(secretSlots.length === 0 ? {} : { secretSlots }),
+    };
+}
+function workspacePlanArgumentSegments(value) {
+    return typeof value === "string" ? [value] : [...value.segments];
+}
+function concatWorkspacePlanArguments(...values) {
+    const segments = values.flatMap(workspacePlanArgumentSegments);
+    if (segments.every((segment) => typeof segment === "string")) {
+        return segments.join("");
+    }
+    return { kind: "workspace-plan-argument-template", segments };
+}
+function joinWorkspacePlanArguments(values, separator) {
+    if (values.length === 0)
+        return "";
+    const joined = [];
+    for (const [index, value] of values.entries()) {
+        if (index > 0)
+            joined.push(separator);
+        joined.push(value);
+    }
+    return concatWorkspacePlanArguments(...joined);
+}
+function tomlProfileConfigValue(value) {
+    if (isProfilePublicConfigValue(value))
+        return tomlStr(value.value);
+    return {
+        kind: "workspace-plan-argument-template",
+        segments: [
+            {
+                kind: "secret",
+                ref: { ...value },
+                encoding: "json-string",
+            },
+        ],
+    };
+}
 // ─── The materializer ─────────────────────────────────────────────────────────
 /**
  * Build the WorkspacePlan for `profile` on `harness`. Pure — no IO. The caller
@@ -447,13 +574,14 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
     assertMaterializerHarness(harness);
     const profile = agentProfileSchema.parse(inputProfile);
     const h = harness;
-    const skip = new Set(opts.skip ?? []);
+    const skip = new Set(assertSkippableDimensions(opts.skip));
     const plan = {
         harness: h,
         files: [],
         env: {},
         flags: [],
         unsupported: [],
+        requires: [],
     };
     // Every plan file is tagged by provenance at the single push site: `add`
     // (harness-generated native config) vs `addExplicitResource` (a profile
@@ -462,13 +590,27 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
     // the synthetic native config) must gate on `source === "generated"` —
     // otherwise a user resource mounted at the same conventional path is
     // silently misread as trusted harness config.
-    const pushPlanFile = (relPath, content, source, mode) => {
+    const pushPlanFile = (relPath, serialized, source, mode) => {
         const normalizedPath = normalizeWorkspaceRelativePath(relPath);
+        const content = typeof serialized === "string" ? serialized : serialized.content;
+        const secretSlots = typeof serialized === "string" ? undefined : serialized.secretSlots;
+        const fileMode = mode ??
+            (secretSlots !== undefined && secretSlots.length > 0
+                ? PRIVATE_FILE_MODE
+                : undefined);
         plan.files.push({
             relPath: normalizedPath,
             content,
             source,
-            ...(mode === undefined ? {} : { mode: validateFileMode(mode) }),
+            ...(fileMode === undefined ? {} : { mode: validateFileMode(fileMode) }),
+            ...(secretSlots === undefined
+                ? {}
+                : {
+                    secretSlots: secretSlots.map((slot) => ({
+                        path: [...slot.path],
+                        ref: { ...slot.ref },
+                    })),
+                }),
         });
     };
     const add = (relPath, content, mode) => pushPlanFile(relPath, content, "generated", mode);
@@ -572,10 +714,10 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
         const instructionPath = CONTEXT_FILE[h];
         add(instructionPath, `${instr.join("\n\n")}\n`);
         if (h === "opencode") {
-            add("opencode.json", JSON.stringify({
+            add("opencode.json", serializeWorkspacePlanJson({
                 $schema: "https://opencode.ai/config.json",
                 instructions: [instructionPath],
-            }, null, 2));
+            }));
         }
         // gemini reads AGENTS.md only via settings; we write GEMINI.md so no extra step.
     }
@@ -690,7 +832,7 @@ export function materializeCandidateProfile(profile, harness, opts = {}) {
         harness: classicPlan.harness,
         files: classicPlan.files,
         env: candidatePublicRecord(classicPlan.env),
-        flags: classicPlan.flags.map(candidatePublicValue),
+        flags: classicPlan.flags.map(candidatePublicArgument),
         ...(classicPlan.systemPrompt === undefined
             ? {}
             : { systemPrompt: candidatePublicValue(classicPlan.systemPrompt) }),
@@ -781,13 +923,15 @@ function candidateMcpForClassicMaterializer(server) {
         ...(server.transport === undefined ? {} : { transport: server.transport }),
         ...(server.args === undefined
             ? {}
-            : { args: server.args.map(candidatePublicString) }),
+            : {
+                args: server.args.map((value) => profilePublicValue(candidatePublicString(value))),
+            }),
         ...(server.env === undefined
             ? {}
             : {
                 env: Object.fromEntries(Object.entries(server.env).map(([name, value]) => [
                     name,
-                    candidatePublicString(value),
+                    profilePublicValue(candidatePublicString(value)),
                 ])),
             }),
         ...(server.cwd === undefined ? {} : { cwd: server.cwd }),
@@ -844,11 +988,22 @@ function candidatePublicString(value) {
 function candidatePublicValue(value) {
     return { kind: "public", value };
 }
+function profilePublicValue(value) {
+    return { kind: "public", value };
+}
+function candidatePublicArgument(value) {
+    if (typeof value !== "string") {
+        throw new Error("Candidate materialization cannot emit private launch arguments");
+    }
+    return candidatePublicValue(value);
+}
 function candidatePublicRecord(values) {
-    return Object.fromEntries(Object.entries(values).map(([name, value]) => [
-        name,
-        candidatePublicValue(value),
-    ]));
+    return Object.fromEntries(Object.entries(values).map(([name, value]) => {
+        if (typeof value !== "string") {
+            throw new Error("Candidate materialization cannot emit private environment values");
+        }
+        return [name, candidatePublicValue(value)];
+    }));
 }
 function verifyCandidateInlineResources(profile) {
     const resources = profile.resources;
@@ -894,13 +1049,23 @@ function mergeJsonFiles(files) {
         }
         if (f.relPath.endsWith(".json")) {
             try {
+                const next = JSON.parse(f.content);
                 const merged = {
                     ...JSON.parse(prev.content),
-                    ...JSON.parse(f.content),
+                    ...next,
                 };
+                const replacedRoots = new Set(Object.keys(next));
+                const secretSlots = [
+                    ...(prev.secretSlots ?? []).filter((slot) => typeof slot.path[0] === "string" &&
+                        !replacedRoots.has(slot.path[0])),
+                    ...(f.secretSlots ?? []),
+                ];
+                const { secretSlots: _previousSecretSlots, ...previousFile } = prev;
                 byPath.set(f.relPath, {
-                    ...prev,
+                    ...previousFile,
                     content: JSON.stringify(merged, null, 2),
+                    ...(secretSlots.length > 0 ? { mode: PRIVATE_FILE_MODE } : {}),
+                    ...(secretSlots.length === 0 ? {} : { secretSlots }),
                 });
                 continue;
             }
@@ -912,6 +1077,60 @@ function mergeJsonFiles(files) {
     }
     return [...byPath.values()];
 }
+function valueAtJsonPath(root, path) {
+    let current = root;
+    for (const segment of path) {
+        if (current === null ||
+            typeof current !== "object" ||
+            !Object.hasOwn(current, segment)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+function normalizePlanFileSecretSlots(file) {
+    if (file.secretSlots === undefined)
+        return [];
+    if (file.source !== "generated" ||
+        !file.relPath.endsWith(".json") ||
+        file.secretSlots.length === 0) {
+        throw new Error(`Workspace secret slots require a generated JSON file: ${file.relPath}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(file.content);
+    }
+    catch {
+        throw new Error(`Workspace secret slots require valid JSON content: ${file.relPath}`);
+    }
+    const seen = new Set();
+    return file.secretSlots.map((slot) => {
+        if (!Array.isArray(slot.path) || slot.path.length === 0) {
+            throw new Error(`Workspace secret slot path must be non-empty: ${file.relPath}`);
+        }
+        const path = slot.path.map((segment) => {
+            if ((typeof segment !== "string" && typeof segment !== "number") ||
+                (typeof segment === "number" &&
+                    (!Number.isSafeInteger(segment) || segment < 0))) {
+                throw new Error(`Workspace secret slot path is invalid: ${file.relPath}`);
+            }
+            return segment;
+        });
+        const identity = JSON.stringify(path);
+        if (seen.has(identity)) {
+            throw new Error(`Duplicate workspace secret slot path: ${file.relPath} ${identity}`);
+        }
+        seen.add(identity);
+        if (valueAtJsonPath(parsed, path) !== null) {
+            throw new Error(`Workspace secret slot must point at a null placeholder: ${file.relPath} ${identity}`);
+        }
+        return {
+            path,
+            ref: agentProfileSecretRefSchema.parse(slot.ref),
+        };
+    });
+}
 function normalizePlanFiles(files) {
     const seen = new Set();
     return files
@@ -924,15 +1143,56 @@ function normalizePlanFiles(files) {
         if (typeof file.content !== "string") {
             throw new Error(`Workspace file content must be a string: ${relPath}`);
         }
+        const mode = validateFileMode(file.mode);
+        const secretSlots = normalizePlanFileSecretSlots(file);
+        if (secretSlots.length > 0 && (mode & 0o077) !== 0) {
+            throw new Error(`Workspace secret-bearing file must not grant group or other access: ${relPath}`);
+        }
         return {
             relPath,
             content: file.content,
-            mode: validateFileMode(file.mode),
+            mode,
+            secretSlots,
         };
     })
         .sort((a, b) => compareStrings(a.relPath, b.relPath));
 }
 const sha256 = (value) => createHash("sha256").update(value, "utf8").digest("hex");
+function normalizeWorkspacePlanArgument(value) {
+    if (typeof value === "string")
+        return value;
+    if (value.kind !== "workspace-plan-argument-template" ||
+        !Array.isArray(value.segments) ||
+        value.segments.length === 0) {
+        throw new Error("Workspace plan argument template is malformed");
+    }
+    const segments = [];
+    for (const segment of value.segments) {
+        if (typeof segment === "string") {
+            const previous = segments.at(-1);
+            if (typeof previous === "string") {
+                segments[segments.length - 1] = previous + segment;
+            }
+            else if (segment.length > 0) {
+                segments.push(segment);
+            }
+            continue;
+        }
+        if (segment.kind !== "secret" ||
+            (segment.encoding !== "raw" && segment.encoding !== "json-string")) {
+            throw new Error("Workspace plan secret argument segment is malformed");
+        }
+        segments.push({
+            kind: "secret",
+            ref: agentProfileSecretRefSchema.parse(segment.ref),
+            encoding: segment.encoding,
+        });
+    }
+    if (segments.every((segment) => typeof segment === "string")) {
+        return segments.join("");
+    }
+    return { kind: "workspace-plan-argument-template", segments };
+}
 /**
  * Hash the exact files, modes, flags, environment, and unsupported dimensions
  * represented by a plan. Array order is preserved only where it changes spawn
@@ -943,18 +1203,34 @@ export function hashWorkspacePlan(plan) {
         relPath: file.relPath,
         mode: file.mode,
         contentSha256: sha256(file.content),
+        ...(file.secretSlots.length === 0
+            ? {}
+            : {
+                secretSlots: [...file.secretSlots].sort((left, right) => compareStrings(JSON.stringify(left.path), JSON.stringify(right.path))),
+            }),
     }));
-    const env = Object.fromEntries(Object.entries(plan.env).sort(([a], [b]) => compareStrings(a, b)));
+    const env = Object.fromEntries(Object.entries(plan.env)
+        .sort(([a], [b]) => compareStrings(a, b))
+        .map(([name, value]) => [
+        name,
+        typeof value === "string"
+            ? value
+            : agentProfileSecretRefSchema.parse(value),
+    ]));
     const unsupported = [...plan.unsupported].sort((a, b) => compareStrings(`${a.dimension}\0${a.reason}`, `${b.dimension}\0${b.reason}`));
+    // A plan that needs an extension is not the same plan as one that does not, even when every
+    // byte it writes is identical — the digest is what a receipt proves, so it must say so.
+    const requires = [...(plan.requires ?? [])].sort((a, b) => compareStrings(`${a.kind}\0${a.id}`, `${b.kind}\0${b.id}`));
     const canonical = JSON.stringify({
         harness: plan.harness,
         files,
         env,
-        flags: [...plan.flags],
+        flags: plan.flags.map(normalizeWorkspacePlanArgument),
         ...(plan.systemPrompt === undefined
             ? {}
             : { systemPrompt: plan.systemPrompt }),
         unsupported,
+        ...(requires.length === 0 ? {} : { requires }),
     });
     return `sha256:${sha256(canonical)}`;
 }
@@ -1053,19 +1329,186 @@ export function applyAgentCandidateWorkspacePlan(plan, workspaceDir, targetWorks
     };
 }
 /**
- * Apply a WorkspacePlan to a real workspace dir: write every file (creating parent
- * dirs), and return the env + flags the caller must hand the spawn. This is the IO
- * consumer of the pure `materializeProfile` — used by the cli-bridge host spawn, the
- * agent-dev-container box, and VB. Returns `unsupported` so the caller can log/fail.
+ * Apply a public-only WorkspacePlan. A plan with any secret reference fails
+ * before the first write; private executors use
+ * {@link applyWorkspacePlanWithSecretProvider} instead.
  */
 export function applyWorkspacePlan(plan, workspaceDir, options = {}) {
+    return applyResolvedWorkspacePlan(plan, resolvePublicWorkspacePlan(plan), workspaceDir, options).receipt;
+}
+/**
+ * Resolve opaque profile references through an executor-owned provider, then
+ * apply the resulting private native files and launch inputs. Resolution
+ * completes before any workspace write, and resolved values never enter the
+ * public plan, digest, receipt, logs, or error messages.
+ */
+export async function applyWorkspacePlanWithSecretProvider(plan, workspaceDir, secretProvider, options = {}) {
+    const planDigest = hashWorkspacePlan(plan);
+    const resolved = await resolvePrivateWorkspacePlan(plan, secretProvider);
+    return applyResolvedWorkspacePlan(plan, resolved, workspaceDir, options, planDigest);
+}
+function secretRefLabel(ref) {
+    return JSON.stringify(ref.key);
+}
+function requireResolvedSecretValue(ref, value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`AgentProfile secret provider returned no value for ${secretRefLabel(ref)}`);
+    }
+    return value;
+}
+function setValueAtJsonPath(root, path, value) {
+    let current = root;
+    for (const segment of path.slice(0, -1)) {
+        if (current === null ||
+            typeof current !== "object" ||
+            !Object.hasOwn(current, segment)) {
+            throw new Error("Generated profile JSON secret path no longer exists");
+        }
+        current = current[segment];
+    }
+    const finalSegment = path.at(-1);
+    if (finalSegment === undefined ||
+        current === null ||
+        typeof current !== "object" ||
+        !Object.hasOwn(current, finalSegment)) {
+        throw new Error("Generated profile JSON secret path no longer exists");
+    }
+    Object.defineProperty(current, finalSegment, {
+        value,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+    });
+}
+function resolvePublicWorkspacePlan(plan) {
+    const files = normalizePlanFiles(plan.files);
+    for (const file of files) {
+        const ref = file.secretSlots[0]?.ref;
+        if (ref) {
+            throw new Error(`Workspace plan requires an AgentProfileSecretProvider for ${secretRefLabel(ref)}`);
+        }
+    }
+    const env = Object.fromEntries(Object.entries(plan.env).map(([name, value]) => {
+        if (typeof value !== "string") {
+            throw new Error(`Workspace plan requires an AgentProfileSecretProvider for ${secretRefLabel(value)}`);
+        }
+        return [name, value];
+    }));
+    const flags = plan.flags.map((argument) => {
+        const normalized = normalizeWorkspacePlanArgument(argument);
+        if (typeof normalized !== "string") {
+            const segment = normalized.segments.find((value) => typeof value !== "string");
+            if (!segment) {
+                throw new Error("Workspace plan argument template is malformed");
+            }
+            throw new Error(`Workspace plan requires an AgentProfileSecretProvider for ${secretRefLabel(segment.ref)}`);
+        }
+        return normalized;
+    });
+    return {
+        files,
+        env,
+        flags,
+        ...(plan.systemPrompt === undefined
+            ? {}
+            : { systemPrompt: plan.systemPrompt }),
+    };
+}
+async function resolvePrivateWorkspacePlan(plan, secretProvider) {
+    if (!secretProvider || typeof secretProvider.get !== "function") {
+        throw new Error("AgentProfileSecretProvider.get is required");
+    }
+    const pending = new Map();
+    const resolveRef = async (input) => {
+        const ref = agentProfileSecretRefSchema.parse(input);
+        let raw = pending.get(ref.key);
+        if (!raw) {
+            raw = (async () => {
+                let value;
+                try {
+                    value = await secretProvider.get(ref.key);
+                }
+                catch {
+                    throw new Error(`AgentProfile secret provider failed for ${secretRefLabel(ref)}`);
+                }
+                return requireResolvedSecretValue(ref, value);
+            })();
+            pending.set(ref.key, raw);
+        }
+        const value = await raw;
+        return ref.format === "bearer" ? `Bearer ${value}` : value;
+    };
+    const files = await Promise.all(normalizePlanFiles(plan.files).map(async (file) => {
+        if (file.secretSlots.length === 0)
+            return file;
+        const parsed = JSON.parse(file.content);
+        const values = await Promise.all(file.secretSlots.map(async (slot) => ({
+            path: slot.path,
+            value: await resolveRef(slot.ref),
+        })));
+        for (const resolved of values) {
+            setValueAtJsonPath(parsed, resolved.path, resolved.value);
+        }
+        return {
+            ...file,
+            content: JSON.stringify(parsed, null, 2),
+            secretSlots: [],
+        };
+    }));
+    const env = Object.fromEntries(await Promise.all(Object.entries(plan.env).map(async ([name, value]) => [
+        name,
+        typeof value === "string" ? value : await resolveRef(value),
+    ])));
+    const flags = await Promise.all(plan.flags.map(async (argument) => {
+        const normalized = normalizeWorkspacePlanArgument(argument);
+        if (typeof normalized === "string")
+            return normalized;
+        const segments = await Promise.all(normalized.segments.map(async (segment) => {
+            if (typeof segment === "string")
+                return segment;
+            const value = await resolveRef(segment.ref);
+            return segment.encoding === "json-string"
+                ? JSON.stringify(value)
+                : value;
+        }));
+        return segments.join("");
+    }));
+    return {
+        files,
+        env,
+        flags,
+        ...(plan.systemPrompt === undefined
+            ? {}
+            : { systemPrompt: plan.systemPrompt }),
+    };
+}
+function safeWorkspacePlanReceipt(plan, written, workspacePlanDigest = hashWorkspacePlan(plan)) {
+    return {
+        workspacePlanDigest,
+        env: Object.fromEntries(Object.entries(plan.env).map(([name, value]) => [
+            name,
+            typeof value === "string" ? value : { ...value },
+        ])),
+        flags: plan.flags.map(normalizeWorkspacePlanArgument),
+        ...(plan.systemPrompt === undefined
+            ? {}
+            : { systemPrompt: plan.systemPrompt }),
+        unsupported: plan.unsupported.map((entry) => ({ ...entry })),
+        written: [...written],
+    };
+}
+function applyResolvedWorkspacePlan(publicPlan, resolvedPlan, workspaceDir, options, publicPlanDigest = hashWorkspacePlan(publicPlan)) {
     const workspaceRoot = resolve(workspaceDir);
     const runtimeOnlyFiles = new Set((options.runtimeOnlyFiles ?? []).map(normalizeWorkspaceRelativePath));
     const existingFiles = options.existingFiles ?? "allow-identical";
     if (existingFiles !== "allow-identical" && existingFiles !== "reject") {
         throw new Error(`Unsupported existing workspace file policy: ${existingFiles}`);
     }
-    const files = normalizePlanFiles(plan.files)
+    const resolvedFiles = resolvedPlan.files;
+    const privateRuntimeFiles = Object.fromEntries(resolvedFiles
+        .filter((file) => runtimeOnlyFiles.has(file.relPath))
+        .map((file) => [file.relPath, file.content]));
+    const files = resolvedFiles
         .filter((file) => !runtimeOnlyFiles.has(file.relPath))
         .map((file) => ({
         ...file,
@@ -1145,16 +1588,7 @@ export function applyWorkspacePlan(plan, workspaceDir, options = {}) {
         }
         throw error;
     }
-    const receipt = {
-        workspacePlanDigest: hashWorkspacePlan(plan),
-        env: plan.env,
-        flags: plan.flags,
-        ...(plan.systemPrompt === undefined
-            ? {}
-            : { systemPrompt: plan.systemPrompt }),
-        unsupported: plan.unsupported,
-        written: files.map((file) => file.relPath),
-    };
+    const receipt = safeWorkspacePlanReceipt(publicPlan, files.map((file) => file.relPath), publicPlanDigest);
     const cleanupErrors = [];
     const temporaryPaths = [];
     for (const entry of prepared) {
@@ -1171,7 +1605,17 @@ export function applyWorkspacePlan(plan, workspaceDir, options = {}) {
     if (cleanupErrors.length > 0) {
         throw new WorkspacePlanCleanupError(cleanupErrors, receipt, temporaryPaths);
     }
-    return receipt;
+    return {
+        receipt,
+        spawn: {
+            env: { ...resolvedPlan.env },
+            flags: [...resolvedPlan.flags],
+            ...(resolvedPlan.systemPrompt === undefined
+                ? {}
+                : { systemPrompt: resolvedPlan.systemPrompt }),
+        },
+        runtimeOnlyFiles: privateRuntimeFiles,
+    };
 }
 function workspaceFileExists(pathValue) {
     try {
@@ -1301,7 +1745,9 @@ function materializeExecutionControls(h, tools, permissions, modes, plan, add, u
                 for (const [tool, enabled] of nativeTools) {
                     rules[enabled ? "allow" : "deny"].push(tool);
                 }
-                add(CLAUDE_SETTINGS_PATH, JSON.stringify({ permissions: sealClaudePermissionRules(rules) }, null, 2));
+                add(CLAUDE_SETTINGS_PATH, serializeWorkspacePlanJson({
+                    permissions: sealClaudePermissionRules(rules),
+                }));
                 registerClaudeSettings(plan);
             }
             break;
@@ -1324,7 +1770,7 @@ function materializeExecutionControls(h, tools, permissions, modes, plan, add, u
             const nativeTools = mapSupportedBooleanEntries(enforceableTools, openCodeToolName, (name) => unsupported("tools", `opencode: no verified native tool mapping for "${name}"`), "opencode tool");
             const nativePermissions = mapSupportedPermissionEntries(enforceablePermissions, openCodePermissionName, (name) => unsupported("permissions", `opencode: no verified native permission mapping for "${name}"`), "opencode permission");
             if (enforceableTools.length > 0 || permissionEntries.length > 0) {
-                add("opencode.json", JSON.stringify({
+                add("opencode.json", serializeWorkspacePlanJson({
                     $schema: "https://opencode.ai/config.json",
                     ...(nativeTools.length > 0
                         ? { tools: Object.fromEntries(nativeTools) }
@@ -1332,7 +1778,7 @@ function materializeExecutionControls(h, tools, permissions, modes, plan, add, u
                     ...(nativePermissions.length > 0
                         ? { permission: Object.fromEntries(nativePermissions) }
                         : {}),
-                }, null, 2));
+                }));
             }
             break;
         }
@@ -1361,6 +1807,46 @@ function materializeExecutionControls(h, tools, permissions, modes, plan, add, u
             }
             break;
         }
+        case "pi": {
+            const nativeTools = mapSupportedBooleanEntries(toolEntries, piToolId, (name) => unsupported("tools", `pi: tool name "${name}" is empty after trimming`), "pi tool");
+            const nativePermissions = mapSupportedPermissionEntries(permissionEntries, piToolId, (name) => unsupported("permissions", `pi: permission name "${name}" is empty after trimming`), "pi permission");
+            const enabled = new Set(nativeTools
+                .filter(([, value]) => value)
+                .map(([name]) => name)
+                .sort(compareStrings));
+            const excluded = new Set(nativeTools
+                .filter(([, value]) => !value)
+                .map(([name]) => name)
+                .sort(compareStrings));
+            for (const [name, policy] of nativePermissions) {
+                if (typeof policy !== "string") {
+                    unsupported("permissions", `pi: conditional permission policy for "${name}" has no verified headless mapping`);
+                    continue;
+                }
+                if (policy === "ask") {
+                    unsupported("permissions", `pi: permission policy "ask" for "${name}" requires an interactive decision surface`);
+                    continue;
+                }
+                if (policy === "allow") {
+                    if (excluded.has(name)) {
+                        throw new Error(`pi execution control "${name}" conflicts between disabled and allow`);
+                    }
+                    continue;
+                }
+                if (enabled.has(name)) {
+                    throw new Error(`pi execution control "${name}" conflicts between enabled and deny`);
+                }
+                excluded.add(name);
+            }
+            if (enabled.size > 0 || excluded.size > 0) {
+                add(PI_EXECUTION_CONTROL_EXTENSION_PATH, piExecutionControlExtensionSource([...enabled], [...excluded]));
+                plan.flags.push("--extension", PI_EXECUTION_CONTROL_EXTENSION_PATH);
+            }
+            if (excluded.size > 0) {
+                plan.flags.push("--exclude-tools", [...excluded].sort(compareStrings).join(","));
+            }
+            break;
+        }
         default:
             if (toolEntries.length > 0) {
                 unsupported("tools", `${h}: no verified primary-process tool availability mapping`);
@@ -1373,6 +1859,56 @@ function materializeExecutionControls(h, tools, permissions, modes, plan, add, u
         unsupported("modes", `${h}: resolve one named AgentProfile mode before materialization`);
     }
 }
+function piExecutionControlExtensionSource(enabledTools, excludedTools) {
+    return [
+        `const enabledTools = Object.freeze(${JSON.stringify(enabledTools)});`,
+        `const excludedTools = Object.freeze(${JSON.stringify(excludedTools)});`,
+        "",
+        "function failProfile(message) {",
+        '  process.stderr.write("Pi profile execution controls failed: " + message + "\\n");',
+        "  process.exit(78);",
+        "}",
+        "",
+        "function resolveTool(reference, available, required) {",
+        "  if (available.includes(reference)) return reference;",
+        "  const folded = reference.toLowerCase();",
+        "  const matches = available.filter((name) => name.toLowerCase() === folded);",
+        "  if (matches.length === 1) return matches[0];",
+        "  if (matches.length > 1) {",
+        "    failProfile('tool \"' + reference + '\" is ambiguous: ' + matches.join(\", \"));",
+        "  }",
+        "  if (required) {",
+        "    failProfile('requested tool \"' + reference + '\" is unavailable');",
+        "  }",
+        "  return undefined;",
+        "}",
+        "",
+        "function applyControls(pi) {",
+        "  const available = pi.getAllTools().map((tool) => tool.name);",
+        "  for (const reference of excludedTools) {",
+        "    const remaining = resolveTool(reference, available, false);",
+        "    if (remaining !== undefined) {",
+        "      failProfile(",
+        "        'excluded tool \"' + reference + '\" remains available as \"' + remaining +",
+        "        '\"; pass its exact registered Pi name',",
+        "      );",
+        "    }",
+        "  }",
+        "  const enabled = enabledTools.map((name) =>",
+        "    resolveTool(name, available, true),",
+        "  );",
+        "  const active = new Set(pi.getActiveTools());",
+        "  for (const name of enabled) active.add(name);",
+        "  pi.setActiveTools([...active]);",
+        "}",
+        "",
+        "export default function applyProfileExecutionControls(pi) {",
+        '  pi.on("before_agent_start", () => applyControls(pi));',
+        '  pi.on("turn_start", () => applyControls(pi));',
+        "}",
+        "",
+    ].join("\n");
+}
 function normalizedControlName(name) {
     return name.replace(/[^a-zA-Z0-9_]/g, "").toLowerCase();
 }
@@ -1457,6 +1993,24 @@ function openCodePermissionName(name) {
         ? normalized
         : undefined;
 }
+const PI_EXECUTION_CONTROL_EXTENSION_PATH = ".tangle/pi-execution-controls.ts";
+/**
+ * Translate only portable spellings whose Pi equivalent differs.
+ *
+ * Every other exact name is resolved against Pi's live registry, keeping
+ * extension and MCP tools profile-configurable without a static catalog.
+ */
+function piToolId(name) {
+    const trimmed = name.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    const portableName = trimmed.toLowerCase();
+    if (portableName === "shell")
+        return "bash";
+    if (portableName === "glob")
+        return "find";
+    return trimmed;
+}
 function mapSupportedBooleanEntries(entries, mapName, onUnsupported, label) {
     return mapControlEntries(entries, mapName, onUnsupported, (left, right, nativeName) => {
         if (left !== right)
@@ -1562,7 +2116,7 @@ function materializeMcp(h, mcp, plan, add, unsupported) {
                 };
             }
             const relPath = ".tangle/claude-mcp.json";
-            add(relPath, JSON.stringify({ mcpServers: servers }, null, 2));
+            add(relPath, serializeWorkspacePlanJson({ mcpServers: servers }));
             plan.flags.push("--mcp-config", relPath, "--strict-mcp-config");
             break;
         }
@@ -1576,21 +2130,21 @@ function materializeMcp(h, mcp, plan, add, unsupported) {
                     unsupported("mcp", `codex: remote MCP server "${name}" uses unsupported SSE transport`);
                     continue;
                 }
-                servers.push(`${tomlStr(name)} = ${codexMcpServerToml(name, server, plan)}`);
+                servers.push(concatWorkspacePlanArguments(`${tomlStr(name)} = `, codexMcpServerToml(name, server, plan)));
             }
             if (servers.length > 0) {
                 // Runtime overrides do not require persisted project trust. Header values
                 // ride environment variables so credentials never appear in argv.
-                plan.flags.push("-c", `mcp_servers={ ${servers.join(", ")} }`);
+                plan.flags.push("-c", concatWorkspacePlanArguments("mcp_servers={ ", joinWorkspacePlanArguments(servers, ", "), " }"));
             }
             break;
         }
         case "opencode":
             // opencode.json "mcp" block (local|remote).
-            add("opencode.json", JSON.stringify({
+            add("opencode.json", serializeWorkspacePlanJson({
                 $schema: "https://opencode.ai/config.json",
                 mcp: openCodeMcpConfig(mcp),
-            }, null, 2));
+            }));
             break;
         case "gemini": {
             const servers = {};
@@ -1609,7 +2163,7 @@ function materializeMcp(h, mcp, plan, add, unsupported) {
                     ...(server.cwd ? { cwd: server.cwd } : {}),
                 };
             }
-            add(".gemini/settings.json", JSON.stringify({ mcpServers: servers }, null, 2));
+            add(".gemini/settings.json", serializeWorkspacePlanJson({ mcpServers: servers }));
             break;
         }
         case "kimi-code": {
@@ -1619,13 +2173,43 @@ function materializeMcp(h, mcp, plan, add, unsupported) {
                 name,
                 kimiMcpServer(server),
             ]));
-            add(rel, JSON.stringify({ mcpServers: servers }, null, 2));
+            add(rel, serializeWorkspacePlanJson({ mcpServers: servers }));
             plan.flags.push("--mcp-config-file", rel);
             break;
         }
-        case "pi":
-            unsupported("mcp", "pi MCP requires a loaded MCP extension; the base Pi runtime has no MCP control");
+        case "pi": {
+            // pi ships NO MCP. It arrives from the `pi-mcp-adapter` extension, which discovers
+            // `<cwd>/.pi/mcp.json` (adapter 2.17.0 config.ts:17) and also registers a `--mcp-config`
+            // flag (index.ts:252). The flag is registered BY the extension, so passing it when the
+            // extension is absent is not a fallback — it is an unknown flag.
+            //
+            // This was previously marked unsupported because a workspace file cannot install an
+            // extension. That reasoning was right about the constraint and wrong about the conclusion:
+            // the file half is perfectly materializable, and the half that is not becomes a declared
+            // requirement the executor enforces. Marking the whole dimension unsupported pushed both
+            // halves onto every consumer, and two of them independently rebuilt it.
+            const rel = ".pi/mcp.json";
+            const servers = Object.fromEntries(Object.entries(mcp).map(([name, server]) => [
+                name,
+                // `directTools` promotes this server's verbs to first-class pi tools. Without it the
+                // agent gets one generic `mcp` tool and must connect, then describe, then call — three
+                // round trips of discovery before it can do anything. Per-server, because the adapter
+                // lets a per-server value override the global `settings.directTools` (direct-tools.ts:135).
+                { ...piMcpServer(server), directTools: true },
+            ]));
+            // serializeWorkspacePlanJson, NOT JSON.stringify: it unwraps public config values to their
+            // bytes and lifts any secret-ref into a tracked slot the applier resolves. Stringifying
+            // straight would write `{"kind":"public","value":"..."}` into the file as an argv entry.
+            add(rel, serializeWorkspacePlanJson({ mcpServers: servers }));
+            plan.requires?.push({
+                kind: "harness-extension",
+                dimension: "mcp",
+                id: "npm:pi-mcp-adapter",
+                reason: "pi has no built-in MCP; without this extension the servers in .pi/mcp.json are never read and the agent starts with none of their tools",
+                remedy: "pi install npm:pi-mcp-adapter",
+            });
             break;
+        }
         case "hermes":
             unsupported("mcp", "hermes MCP is global config.yaml (mcp_servers), no cwd discovery — write to the hermes global config or pass a config flag");
             break;
@@ -1662,7 +2246,7 @@ function codexMcpServerToml(name, server, plan) {
         }
         fields.push(`command = ${tomlStr(server.command)}`);
         if (server.args?.length) {
-            fields.push(`args = [${server.args.map(tomlStr).join(", ")}]`);
+            fields.push(concatWorkspacePlanArguments("args = [", joinWorkspacePlanArguments(server.args.map(tomlProfileConfigValue), ", "), "]"));
         }
         if (server.cwd)
             fields.push(`cwd = ${tomlStr(server.cwd)}`);
@@ -1674,14 +2258,27 @@ function codexMcpServerToml(name, server, plan) {
             fields.push(`env_vars = [${envNames.map(tomlStr).join(", ")}]`);
         }
     }
-    return `{ ${fields.join(", ")} }`;
+    return concatWorkspacePlanArguments("{ ", joinWorkspacePlanArguments(fields, ", "), " }");
 }
 function setPlanEnvironment(plan, name, value) {
+    const normalized = typeof value === "string" ? value : workspacePlanConfigValue(value);
     const previous = plan.env[name];
-    if (previous !== undefined && previous !== value) {
+    if (previous !== undefined &&
+        JSON.stringify(previous) !== JSON.stringify(normalized)) {
         throw new Error(`profile environment values disagree for ${name}`);
     }
-    plan.env[name] = value;
+    plan.env[name] = normalized;
+}
+/**
+ * Lower one canonical MCP server to the shape `pi-mcp-adapter` reads from `.pi/mcp.json`.
+ *
+ * The adapter consumes the same `{mcpServers: {...}}` document Claude and Kimi use, so this
+ * mirrors {@link kimiMcpServer} rather than inventing a pi dialect. `directTools` is added by the
+ * caller, not here, because it is a policy about tool surfacing rather than a property of the
+ * server definition.
+ */
+function piMcpServer(server) {
+    return kimiMcpServer(server);
 }
 function kimiMcpServer(server) {
     if (server.url) {
@@ -1746,14 +2343,14 @@ function materializeHooks(h, hooks, add, unsupported, plan) {
                     hooks: [
                         {
                             type: "command",
-                            command: materializedHookCommand(event, c, add),
+                            command: materializedHookCommand(event, c, add, plan),
                             ...(c.timeoutMs ? { timeout: timeoutSeconds(c.timeoutMs) } : {}),
                             ...(c.blocking === false ? { async: true } : {}),
                         },
                     ],
                 }));
             }
-            add(CLAUDE_SETTINGS_PATH, JSON.stringify({ hooks: settingsHooks }, null, 2));
+            add(CLAUDE_SETTINGS_PATH, serializeWorkspacePlanJson({ hooks: settingsHooks }));
             registerClaudeSettings(plan);
             break;
         }
@@ -1775,13 +2372,13 @@ function materializeHooks(h, hooks, add, unsupported, plan) {
                     hooks: [
                         {
                             type: "command",
-                            command: materializedHookCommand(event, c, add),
+                            command: materializedHookCommand(event, c, add, plan),
                             ...(c.timeoutMs ? { timeout: c.timeoutMs } : {}),
                         },
                     ],
                 }));
             }
-            add(".gemini/settings.json", JSON.stringify({ hooks: settingsHooks }, null, 2));
+            add(".gemini/settings.json", serializeWorkspacePlanJson({ hooks: settingsHooks }));
             break;
         }
         case "codex": {
@@ -1797,7 +2394,7 @@ function materializeHooks(h, hooks, add, unsupported, plan) {
                 const entries = cmds.map((command) => {
                     const handler = [
                         `type = ${tomlStr("command")}`,
-                        `command = ${tomlStr(materializedHookCommand(event, command, add))}`,
+                        `command = ${tomlStr(materializedHookCommand(event, command, add, plan))}`,
                         ...(command.timeoutMs
                             ? [`timeout = ${timeoutSeconds(command.timeoutMs)}`]
                             : []),
@@ -1906,7 +2503,7 @@ function hookEventSupported(harness, event) {
 function timeoutSeconds(timeoutMs) {
     return Math.max(1, Math.ceil(timeoutMs / 1000));
 }
-function materializedHookCommand(event, command, add) {
+function materializedHookCommand(event, command, add, plan) {
     if (!command.env || Object.keys(command.env).length === 0) {
         return command.command;
     }
@@ -1916,9 +2513,50 @@ function materializedHookCommand(event, command, add) {
         env: Object.fromEntries(Object.entries(command.env).sort(([left], [right]) => compareStrings(left, right))),
     }).slice("sha256:".length);
     const path = `.tangle/profile-hooks/${wrapperId}.mjs`;
-    add(path, hookWrapperSource("/bin/sh", ["-c", command.command], command.env));
+    const envSources = Object.fromEntries(Object.entries(command.env)
+        .sort(([left], [right]) => compareStrings(left, right))
+        .map(([name, value]) => {
+        const sourceName = `TANGLE_PROFILE_HOOK_${sha256(`${wrapperId}\0${name}`)
+            .slice(0, 24)
+            .toUpperCase()}`;
+        setPlanEnvironment(plan, sourceName, value);
+        return [name, sourceName];
+    }));
+    add(path, hookWrapperSourceFromEnvironment("/bin/sh", ["-c", command.command], envSources));
     return `node ${path}`;
 }
+function hookWrapperSourceFromEnvironment(executable, args, envSources) {
+    return [
+        'import { spawnSync } from "node:child_process"',
+        `const executable = ${JSON.stringify(executable)}`,
+        `const args = ${JSON.stringify(args)}`,
+        `const envSources = ${JSON.stringify(envSources)}`,
+        "const extraEnv = {}",
+        "for (const [name, source] of Object.entries(envSources)) {",
+        "  const value = process.env[source]",
+        "  if (value === undefined) {",
+        '    console.error("missing materialized hook environment " + source)',
+        "    process.exit(127)",
+        "  }",
+        "  extraEnv[name] = value",
+        "}",
+        "const result = spawnSync(executable, args, {",
+        '  stdio: "inherit",',
+        "  env: { ...process.env, ...extraEnv },",
+        "  shell: false,",
+        "})",
+        "if (result.error) {",
+        "  console.error(result.error.message)",
+        "  process.exit(127)",
+        "}",
+        "if (result.signal) {",
+        '  console.error("hook terminated by " + result.signal)',
+        "  process.exit(1)",
+        "}",
+        "process.exit(result.status ?? 1)",
+        "",
+    ].join("\n");
+}
 function hookWrapperSource(executable, args, env) {
     return [
         'import { spawnSync } from "node:child_process"',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "description": "Materialize an AgentProfile into the native per-harness workspace files (the one shared materializer for cli-bridge, agent-dev-container, and VB).",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,13 +20,13 @@
     "dist"
   ],
   "devDependencies": {
-    "@tangle-network/agent-interface": "0.36.0",
+    "@tangle-network/agent-interface": "0.38.0",
     "@types/node": "25.6.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "@tangle-network/agent-interface": ">=0.36.0 <0.38.0"
+    "@tangle-network/agent-interface": ">=0.38.0 <0.41.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",