@tangle-network/agent-profile-materialize 0.4.0 → 0.5.0

package/dist/index.js

@@ -22,13 +22,11 @@
  * cli-bridge and agent-dev-container — this is the single source those re-export.
  */
 import { createHash, randomUUID } from "node:crypto";
-import { closeSync, fchmodSync, constants as fsConstants, lstatSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve, sep, win32, } from "node:path";
-import { agentCandidateProfilePlanEvidenceSchema, agentCandidateProfilePlanMaterialSchema, agentCandidateProfileSchema, } from "@tangle-network/agent-interface";
-/** Resolve an inline resource ref to {name, content}. github refs need an async fetch
- *  (the providers' resolveProfileResource does this); the sync materializer can't, so a
- *  github ref is reported unsupported and the caller pre-resolves it. A ref with
- *  `content` (or kind 'inline') is inline. */
+import { closeSync, fchmodSync, constants as fsConstants, 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";
+/** Resolve inline bytes already present on the profile. Remote resources must
+ * be resolved by {@link resolveAgentProfileResources} before materialization. */
 function resolveInlineRef(ref) {
     const r = ref;
     if (r.kind === "inline" || typeof r.content === "string") {
@@ -39,6 +37,12 @@ function resolveInlineRef(ref) {
     }
     return null; // github / unresolved
 }
+/** Fail when a profile asks for controls the chosen harness cannot execute. */
+export function assertWorkspacePlanSupported(plan) {
+    if (plan.unsupported.length > 0) {
+        throw new Error(formatUnsupported(plan.unsupported));
+    }
+}
 // ─── Verified per-harness conventions (capability matrix) ───────────────────
 /** Project context file each harness actually reads from cwd. NEVER a constant. */
 const CONTEXT_FILE = {
@@ -47,7 +51,7 @@ const CONTEXT_FILE = {
     claudish: "CLAUDE.md",
     nanoclaw: "CLAUDE.md",
     codex: "AGENTS.md",
-    opencode: "AGENTS.md",
+    opencode: ".opencode/profile-instructions.md",
     "kimi-code": "AGENTS.md",
     kimi: "AGENTS.md",
     pi: "AGENTS.md",
@@ -83,10 +87,74 @@ 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 EXECUTABLE_FILE_MODE = 0o755;
+const DEFAULT_RESOURCE_FETCH_TIMEOUT_MS = 30_000;
+const MAX_RESOURCE_BYTES = 10 * 1024 * 1024;
+const MAX_PROFILE_RESOURCE_BYTES = 32 * 1024 * 1024;
+const MAX_PROFILE_RESOURCE_REFS = 128;
+const MAX_CONCURRENT_RESOURCE_FETCHES = 8;
+const CLAUDE_SETTINGS_PATH = ".tangle/claude-settings.json";
 const SAFE_WRITE_FLAGS = fsConstants.O_WRONLY |
     fsConstants.O_CREAT |
     fsConstants.O_EXCL |
     (typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0);
+async function readResourceBody(response, description, consumeBytes) {
+    if (!response.body)
+        return "";
+    const reader = response.body.getReader();
+    const chunks = [];
+    let totalBytes = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            totalBytes += value.byteLength;
+            if (totalBytes > MAX_RESOURCE_BYTES) {
+                await reader.cancel().catch(() => undefined);
+                throw new Error(`GitHub profile resource exceeds ${MAX_RESOURCE_BYTES} bytes: ${description}`);
+            }
+            try {
+                consumeBytes(value.byteLength);
+            }
+            catch (error) {
+                await reader.cancel().catch(() => undefined);
+                throw error;
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength)), totalBytes).toString("utf8");
+}
+async function mapWithConcurrency(values, concurrency, controller, transform) {
+    const results = new Array(values.length);
+    let nextIndex = 0;
+    let firstFailure;
+    const worker = async () => {
+        while (!firstFailure) {
+            const index = nextIndex++;
+            if (index >= values.length)
+                return;
+            try {
+                results[index] = await transform(values[index]);
+            }
+            catch (error) {
+                if (!firstFailure) {
+                    firstFailure = { error };
+                    controller.abort(error);
+                }
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, async () => worker()));
+    if (firstFailure)
+        throw firstFailure.error;
+    return results;
+}
 function normalizeWorkspaceRelativePath(pathValue) {
     if (typeof pathValue !== "string" ||
         !pathValue ||
@@ -102,6 +170,7 @@ function normalizeWorkspaceRelativePath(pathValue) {
     if (segments.some((segment) => !segment ||
         segment === "." ||
         segment === ".." ||
+        segment === ".git" ||
         segment === ".sidecar")) {
         throw new Error(`Workspace file path must be canonical: ${pathValue}`);
     }
@@ -122,6 +191,115 @@ function validateFileMode(mode) {
     }
     return normalized;
 }
+/** Resolve every GitHub resource to exact inline bytes before materialization. */
+export async function resolveAgentProfileResources(inputProfile, options = {}) {
+    const profile = agentProfileSchema.parse(inputProfile);
+    const resources = profile.resources;
+    if (!resources)
+        return profile;
+    const refs = [
+        ...(resources.files?.map((mount) => mount.resource) ?? []),
+        ...(resources.tools ?? []),
+        ...(resources.skills ?? []),
+        ...(resources.agents ?? []),
+        ...(resources.commands ?? []),
+        ...(typeof resources.instructions === "object"
+            ? [resources.instructions]
+            : []),
+    ];
+    if (refs.length > MAX_PROFILE_RESOURCE_REFS) {
+        throw new Error(`AgentProfile may contain at most ${MAX_PROFILE_RESOURCE_REFS} resource references`);
+    }
+    const batchController = new AbortController();
+    let fetchedBytes = 0;
+    const consumeFetchedBytes = (bytes) => {
+        fetchedBytes += bytes;
+        if (fetchedBytes > MAX_PROFILE_RESOURCE_BYTES) {
+            throw new Error(`GitHub profile resources exceed ${MAX_PROFILE_RESOURCE_BYTES} total bytes`);
+        }
+    };
+    const resolveRef = async (ref) => {
+        if (ref.kind === "inline")
+            return ref;
+        const repository = ref.repository ?? options.repository;
+        if (!repository) {
+            throw new Error(`GitHub profile resource "${ref.path}" requires repository`);
+        }
+        const [owner, repo, ...extraRepositoryParts] = repository.split("/");
+        if (!owner ||
+            !repo ||
+            extraRepositoryParts.length > 0 ||
+            !/^[A-Za-z0-9_.-]+$/.test(owner) ||
+            !/^[A-Za-z0-9_.-]+$/.test(repo)) {
+            throw new Error(`GitHub profile resource repository must be owner/repo: ${repository}`);
+        }
+        const resourcePath = normalizeWorkspaceRelativePath(ref.path);
+        const gitRef = ref.ref ?? "main";
+        if (!gitRef ||
+            hasControlCharacter(gitRef) ||
+            gitRef.split("/").some((segment) => !segment || segment === "..")) {
+            throw new Error(`Invalid GitHub profile resource ref: ${gitRef}`);
+        }
+        const encoded = (value) => value.split("/").map(encodeURIComponent).join("/");
+        const url = `https://raw.githubusercontent.com/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/${encoded(gitRef)}/${encoded(resourcePath)}`;
+        const controller = new AbortController();
+        const abortRequest = () => controller.abort(batchController.signal.reason);
+        batchController.signal.addEventListener("abort", abortRequest, {
+            once: true,
+        });
+        const timeoutError = new Error(`GitHub profile resource timed out: ${repository}/${resourcePath}@${gitRef}`);
+        const timeout = setTimeout(() => controller.abort(timeoutError), options.timeoutMs ?? DEFAULT_RESOURCE_FETCH_TIMEOUT_MS);
+        try {
+            const fetchResource = options.fetch ?? globalThis.fetch;
+            const response = await fetchResource(url, { signal: controller.signal });
+            if (!response.ok) {
+                throw new Error(`Failed to fetch GitHub profile resource ${repository}/${resourcePath}@${gitRef}: ${response.status} ${response.statusText}`);
+            }
+            const contentLength = Number(response.headers.get("content-length"));
+            if (Number.isFinite(contentLength) &&
+                contentLength > MAX_RESOURCE_BYTES) {
+                throw new Error(`GitHub profile resource exceeds ${MAX_RESOURCE_BYTES} bytes: ${repository}/${resourcePath}`);
+            }
+            const content = await readResourceBody(response, `${repository}/${resourcePath}`, consumeFetchedBytes);
+            return {
+                kind: "inline",
+                name: ref.name ?? basename(resourcePath),
+                content,
+            };
+        }
+        catch (error) {
+            if (controller.signal.aborted && controller.signal.reason !== undefined) {
+                throw controller.signal.reason;
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+            batchController.signal.removeEventListener("abort", abortRequest);
+        }
+    };
+    const resolvedRefs = await mapWithConcurrency(refs, MAX_CONCURRENT_RESOURCE_FETCHES, batchController, resolveRef);
+    let resolvedIndex = 0;
+    const takeRef = () => resolvedRefs[resolvedIndex++];
+    const takeRefs = (values) => values?.map(takeRef);
+    const resolvedResources = {
+        ...resources,
+        files: resources.files === undefined
+            ? undefined
+            : resources.files.map((mount) => ({
+                ...mount,
+                resource: takeRef(),
+            })),
+        tools: takeRefs(resources.tools),
+        skills: takeRefs(resources.skills),
+        agents: takeRefs(resources.agents),
+        commands: takeRefs(resources.commands),
+        instructions: typeof resources.instructions === "object"
+            ? takeRef()
+            : resources.instructions,
+    };
+    return agentProfileSchema.parse({ ...profile, resources: resolvedResources });
+}
 /** Normalize any skill markdown (VB frontmatter `skill:`/`description:`, or raw) into a
  *  harness SKILL.md with `name:`/`description:` frontmatter the harnesses require. */
 export function normalizeSkillMd(name, raw) {
@@ -160,7 +338,8 @@ const tomlStr = (s) => JSON.stringify(s); // valid TOML basic string
  * Build the WorkspacePlan for `profile` on `harness`. Pure — no IO. The caller
  * writes plan.files into the run cwd and applies plan.env/plan.flags to the spawn.
  */
-export function materializeProfile(profile, harness, opts = {}) {
+export function materializeProfile(inputProfile, harness, opts = {}) {
+    const profile = agentProfileSchema.parse(inputProfile);
     const h = canonicalHarness(harness);
     const skip = new Set(opts.skip ?? []);
     const plan = {
@@ -234,12 +413,36 @@ export function materializeProfile(profile, harness, opts = {}) {
             unsupported("subagents", `${h}: agent definitions have no verified cwd-native resource path`);
             continue;
         }
-        addExplicitResource("subagents", `${directory}/${resource.name}`, resource.content);
+        const relPath = `${directory}/${resource.name}`;
+        addExplicitResource("subagents", relPath, resource.content);
+        if (h === "codex") {
+            const roleName = codexAgentRoleName(resource.name);
+            if (!roleName) {
+                unsupported("subagents", `codex: agent resource "${resource.name}" must use a lowercase role name`);
+            }
+            else {
+                registerCodexAgent(plan, roleName, relPath, roleName);
+            }
+        }
+    }
+    // 4) PROMPT. A system prompt is a replacement, while instructions are
+    // additive workspace context. Never lower one into the other.
+    if (profile.prompt?.systemPrompt !== undefined) {
+        if (h === "claude-code" ||
+            h === "codex" ||
+            h === "opencode" ||
+            h === "pi") {
+            plan.systemPrompt = profile.prompt.systemPrompt;
+        }
+        else if (h === "gemini") {
+            add(".gemini/system.md", profile.prompt.systemPrompt);
+            plan.env.GEMINI_SYSTEM_MD = "1";
+        }
+        else {
+            unsupported("systemPrompt", `${h}: no verified exact system-prompt replacement control`);
+        }
     }
-    // 4) CONTEXT (instructions + systemPrompt → the harness's native context file).
     const instr = [];
-    if (profile.prompt?.systemPrompt)
-        instr.push(profile.prompt.systemPrompt);
     if (profile.prompt?.instructions?.length)
         instr.push(...profile.prompt.instructions);
     const resInstr = profile.resources?.instructions;
@@ -247,11 +450,31 @@ export function materializeProfile(profile, harness, opts = {}) {
         instr.push(resInstr);
     else if (resInstr && resInstr.kind === "inline")
         instr.push(resInstr.content);
+    else if (resInstr) {
+        unsupported("instructions", "instruction ref is not inline (github refs need async pre-resolution)");
+    }
     if (instr.length) {
-        add(CONTEXT_FILE[h], `${instr.join("\n\n")}\n`);
+        const instructionPath = CONTEXT_FILE[h];
+        add(instructionPath, `${instr.join("\n\n")}\n`);
+        if (h === "opencode") {
+            add("opencode.json", JSON.stringify({
+                $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.
     }
-    // 5) SKILLS → native skill dir, from resources.skills refs (the box's shape), or
+    // 5) ACTIVE EXECUTION CONTROLS. These alter the tools visible to the primary
+    // process and its permission policy, so they must be lowered into native
+    // launch/config inputs rather than merely retained in profile metadata.
+    materializeExecutionControls(h, profile.tools, profile.permissions, profile.modes, plan, add, unsupported);
+    if ((profile.connections?.length ?? 0) > 0) {
+        unsupported("connections", `${h}: Hub connections must be resolved to authorized MCP servers by the execution runtime`);
+    }
+    if (profile.confidential !== undefined) {
+        unsupported("confidential", `${h}: confidential execution requires runtime placement and attestation, not workspace files`);
+    }
+    // 6) SKILLS → native skill dir, from resources.skills refs (the box's shape), or
     //    fail-closed (hermes has no cwd skill dir; github refs need async pre-resolution).
     for (const ref of profile.resources?.skills ?? []) {
         const r = resolveInlineRef(ref);
@@ -266,20 +489,27 @@ export function materializeProfile(profile, harness, opts = {}) {
         }
         addExplicitResource("skills", `${dir}/${r.name}/SKILL.md`, normalizeSkillMd(r.name, r.content));
     }
-    // 6) MCP → per-harness format (the divergence the matrix names). Skippable so the
-    //    additive host-wiring can leave MCP on cli-bridge's existing per-harness path.
-    const mcp = profile.mcp ?? {};
+    // 7) MCP -> each harness's native configuration and launch controls.
+    const mcp = activeMcpServers(profile.mcp);
     if (!skip.has("mcp") && Object.keys(mcp).length)
         materializeMcp(h, mcp, plan, add, unsupported);
-    // 7) HOOKS → per-harness format; cwd-native only for claude/codex/gemini/opencode(plugin).
+    // 8) HOOKS → per-harness format; cwd-native only for claude/codex/gemini/opencode(plugin).
     const hooks = profile.hooks ?? {};
     if (Object.keys(hooks).length)
         materializeHooks(h, hooks, add, unsupported, plan);
-    // 8) SUBAGENTS → cwd-native for claude/codex/opencode/gemini; flag/global elsewhere.
+    // 9) SUBAGENTS → cwd-native for claude/codex/opencode/gemini; flag/global elsewhere.
     const subagents = profile.subagents ?? {};
     for (const [name, sa] of Object.entries(subagents))
-        materializeSubagent(h, name, sa, add, unsupported);
-    // 9) COMMANDS → cwd-native (resources.commands refs); "commands are skills" on kimi.
+        materializeSubagent(h, name, sa, plan, add, unsupported);
+    if (!skip.has("extensions")) {
+        for (const namespace of extensionNamespaces(h)) {
+            const extension = profile.extensions?.[namespace];
+            if (extension && Object.keys(extension).length > 0) {
+                unsupported("extensions", `${h}: extension namespace "${namespace}" requires provider-native handling`);
+            }
+        }
+    }
+    // 10) COMMANDS → cwd-native (resources.commands refs); "commands are skills" on kimi.
     for (const ref of profile.resources?.commands ?? []) {
         const r = resolveInlineRef(ref);
         if (!r) {
@@ -294,7 +524,7 @@ export function materializeProfile(profile, harness, opts = {}) {
             throw new Error(`Profile ${dimension} resource conflicts with generated harness file: ${relPath}`);
         }
     }
-    // Merge native multi-writer JSON files (e.g. .claude/settings.json from both
+    // Merge native multi-writer JSON files (for example Claude settings from both
     // mcp and hooks) so the second writer cannot clobber the first.
     plan.files = mergeJsonFiles(plan.files).sort((a, b) => compareStrings(a.relPath, b.relPath));
     if (profile.resources?.failOnError && plan.unsupported.length) {
@@ -302,11 +532,23 @@ export function materializeProfile(profile, harness, opts = {}) {
     }
     return plan;
 }
+function activeMcpServers(servers) {
+    return Object.fromEntries(Object.entries(servers ?? {}).filter((entry) => entry[1].enabled !== false));
+}
+function extensionNamespaces(harness) {
+    switch (harness) {
+        case "claude-code":
+            return ["claude-code", "claude"];
+        case "kimi-code":
+            return ["kimi-code", "kimi"];
+        default:
+            return [harness];
+    }
+}
 /**
  * Materialize a sealed candidate profile without weakening its process values.
- * Candidate hooks deliberately fail closed because the currently supported
- * native hook formats accept a shell command string rather than executable +
- * argv + env as separate fields.
+ * Codex and Claude hooks use generated no-shell wrappers to preserve executable,
+ * argv, and environment values separately. Other hook formats fail closed.
  */
 export function materializeCandidateProfile(profile, harness, opts = {}) {
     const candidate = agentCandidateProfileSchema.parse(profile);
@@ -326,13 +568,6 @@ export function materializeCandidateProfile(profile, harness, opts = {}) {
         hooks: hookLowering.hooks,
     };
     const classicPlan = materializeProfile(classicProfile, harness);
-    if (canonicalHarness(harness) === "opencode" &&
-        Object.values(candidate.mcp ?? {}).some((server) => server.enabled !== false && server.cwd !== undefined)) {
-        classicPlan.unsupported.push({
-            dimension: "mcp",
-            reason: "opencode local MCP configuration does not support a cwd field",
-        });
-    }
     if (hookLowering.unsupportedReason) {
         classicPlan.unsupported.push({
             dimension: "hooks",
@@ -340,24 +575,27 @@ export function materializeCandidateProfile(profile, harness, opts = {}) {
         });
     }
     classicPlan.unsupported.sort((left, right) => compareStrings(`${left.dimension}\0${left.reason}`, `${right.dimension}\0${right.reason}`));
-    if (classicPlan.unsupported.length > 0) {
-        throw new Error(formatUnsupported(classicPlan.unsupported));
-    }
+    assertWorkspacePlanSupported(classicPlan);
     return {
+        sourceProfileDigest: canonicalCandidateDigest(candidate),
         harness: classicPlan.harness,
         files: classicPlan.files,
         env: candidatePublicRecord(classicPlan.env),
         flags: classicPlan.flags.map(candidatePublicValue),
+        ...(classicPlan.systemPrompt === undefined
+            ? {}
+            : { systemPrompt: candidatePublicValue(classicPlan.systemPrompt) }),
         unsupported: classicPlan.unsupported,
     };
 }
 function lowerCandidateHooks(hooks, harness) {
     if (!hooks || Object.keys(hooks).length === 0)
         return { wrapperFiles: [] };
-    if (canonicalHarness(harness) !== "codex") {
+    const nativeHarness = canonicalHarness(harness);
+    if (nativeHarness !== "codex" && nativeHarness !== "claude-code") {
         return {
             wrapperFiles: [],
-            unsupportedReason: `${canonicalHarness(harness)} hook configuration requires an unverified command-string mapping; ` +
+            unsupportedReason: `${nativeHarness} hook configuration requires an unverified command-string mapping; ` +
                 "sealed candidate hooks preserve executable, argv, and env separately",
         };
     }
@@ -389,7 +627,7 @@ function candidateHookWrapper(event, index, command) {
     const env = Object.fromEntries(Object.entries(command.env ?? {})
         .sort(([left], [right]) => compareStrings(left, right))
         .map(([name, value]) => [name, candidatePublicString(value)]));
-    const identity = rfc8785Serialize({
+    const wrapperId = canonicalCandidateDigest({
         event,
         index,
         executable: command.executable,
@@ -398,30 +636,9 @@ function candidateHookWrapper(event, index, command) {
         timeoutMs: command.timeoutMs ?? null,
         blocking: command.blocking ?? null,
         matcher: command.matcher ?? null,
-    });
-    const wrapperId = sha256(identity);
+    }).slice("sha256:".length);
     const path = `.tangle/profile-hooks/${wrapperId}.mjs`;
-    const content = [
-        'import { spawnSync } from "node:child_process"',
-        `const executable = ${JSON.stringify(command.executable)}`,
-        `const args = ${JSON.stringify(args)}`,
-        `const extraEnv = ${JSON.stringify(env)}`,
-        "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");
+    const content = hookWrapperSource(command.executable, args, env);
     return { path, content };
 }
 function agentResourceDirectory(harness) {
@@ -443,7 +660,7 @@ function candidateMcpRecordForClassicMaterializer(servers) {
     if (!servers)
         return undefined;
     return Object.fromEntries(Object.entries(servers)
-        .filter(([, server]) => server.enabled !== false)
+        .filter((entry) => entry[1].enabled !== false)
         .map(([name, server]) => [
         name,
         candidateMcpForClassicMaterializer(server),
@@ -451,17 +668,20 @@ function candidateMcpRecordForClassicMaterializer(servers) {
 }
 function candidateMcpForClassicMaterializer(server) {
     return {
-        transport: server.transport,
         command: server.command,
-        args: server.args?.map(candidatePublicString),
-        env: server.env
-            ? Object.fromEntries(Object.entries(server.env).map(([name, value]) => [
-                name,
-                candidatePublicString(value),
-            ]))
-            : undefined,
-        cwd: server.cwd,
-        enabled: server.enabled,
+        ...(server.transport === undefined ? {} : { transport: server.transport }),
+        ...(server.args === undefined
+            ? {}
+            : { args: server.args.map(candidatePublicString) }),
+        ...(server.env === undefined
+            ? {}
+            : {
+                env: Object.fromEntries(Object.entries(server.env).map(([name, value]) => [
+                    name,
+                    candidatePublicString(value),
+                ])),
+            }),
+        ...(server.cwd === undefined ? {} : { cwd: server.cwd }),
     };
 }
 function candidateResourcesForClassicMaterializer(resources, resolvedResources) {
@@ -622,6 +842,9 @@ export function hashWorkspacePlan(plan) {
         files,
         env,
         flags: [...plan.flags],
+        ...(plan.systemPrompt === undefined
+            ? {}
+            : { systemPrompt: plan.systemPrompt }),
         unsupported,
     });
     return `sha256:${sha256(canonical)}`;
@@ -629,6 +852,7 @@ export function hashWorkspacePlan(plan) {
 /** Build the exact digest-free identity document required by agent-interface. */
 export function agentCandidateProfilePlanMaterial(plan) {
     const material = {
+        sourceProfileDigest: plan.sourceProfileDigest,
         harness: canonicalHarness(plan.harness),
         files: normalizePlanFiles(plan.files).map((file) => ({
             relPath: file.relPath,
@@ -637,6 +861,9 @@ export function agentCandidateProfilePlanMaterial(plan) {
         })),
         env: Object.fromEntries(Object.entries(plan.env).sort(([left], [right]) => compareStrings(left, right))),
         flags: [...plan.flags],
+        ...(plan.systemPrompt === undefined
+            ? {}
+            : { systemPrompt: plan.systemPrompt }),
         unsupported: [...plan.unsupported].sort((left, right) => compareStrings(`${left.dimension}\0${left.reason}`, `${right.dimension}\0${right.reason}`)),
     };
     return agentCandidateProfilePlanMaterialSchema.parse(material);
@@ -647,10 +874,8 @@ export function agentCandidateProfilePlanMaterial(plan) {
  */
 export function canonicalizeAgentCandidateProfilePlan(plan) {
     const material = agentCandidateProfilePlanMaterial(plan);
-    const bytes = Uint8Array.from(Buffer.from(rfc8785Serialize(material), "utf8"));
-    const digest = `sha256:${createHash("sha256")
-        .update(bytes)
-        .digest("hex")}`;
+    const bytes = canonicalCandidateBytes(material);
+    const digest = canonicalCandidateDigest(material);
     return { material, bytes, digest };
 }
 /** Capture portable evidence of the exact canonical profile-plan bytes. */
@@ -674,10 +899,22 @@ export function captureAgentCandidateProfilePlan(plan) {
  * canonical evidence. No caller needs to re-serialize or reinterpret the plan.
  */
 export function applyAgentCandidateWorkspacePlan(plan, workspaceDir, targetWorkspace) {
-    if (plan.unsupported.length > 0) {
-        throw new Error(formatUnsupported(plan.unsupported));
-    }
+    assertWorkspacePlanSupported(plan);
     const profilePlan = captureAgentCandidateProfilePlan(plan);
+    const activationFiles = normalizePlanFiles(plan.files).map((file) => ({
+        path: file.relPath,
+        mode: file.mode,
+        content: file.content,
+    }));
+    const activationMaterial = {
+        kind: "agent-candidate-profile-activation",
+        profilePlan,
+        files: activationFiles,
+    };
+    const profileActivation = agentCandidateProfileActivationSchema.parse({
+        ...activationMaterial,
+        digest: canonicalCandidateDigest(activationMaterial),
+    });
     const applied = applyWorkspacePlan({
         harness: plan.harness,
         files: plan.files,
@@ -686,10 +923,13 @@ export function applyAgentCandidateWorkspacePlan(plan, workspaceDir, targetWorks
             candidatePublicString(value),
         ])),
         flags: plan.flags.map(candidatePublicString),
+        ...(plan.systemPrompt === undefined
+            ? {}
+            : { systemPrompt: candidatePublicString(plan.systemPrompt) }),
         unsupported: plan.unsupported,
     }, workspaceDir);
     return {
-        profilePlan,
+        profileActivation,
         application: {
             planDigest: profilePlan.digest,
             targetWorkspace,
@@ -697,41 +937,24 @@ export function applyAgentCandidateWorkspacePlan(plan, workspaceDir, targetWorks
         },
         env: { ...plan.env },
         flags: [...plan.flags],
+        ...(plan.systemPrompt === undefined
+            ? {}
+            : { systemPrompt: plan.systemPrompt }),
         unsupported: [...plan.unsupported],
     };
 }
-function rfc8785Serialize(value) {
-    if (value === null || typeof value === "boolean")
-        return JSON.stringify(value);
-    if (typeof value === "string")
-        return JSON.stringify(value);
-    if (typeof value === "number") {
-        if (!Number.isFinite(value)) {
-            throw new Error("RFC 8785 cannot serialize a non-finite number");
-        }
-        return JSON.stringify(value);
-    }
-    if (Array.isArray(value)) {
-        return `[${value.map(rfc8785Serialize).join(",")}]`;
-    }
-    if (typeof value === "object") {
-        const record = value;
-        return `{${Object.keys(record)
-            .sort(compareStrings)
-            .map((key) => `${JSON.stringify(key)}:${rfc8785Serialize(record[key])}`)
-            .join(",")}}`;
-    }
-    throw new Error(`RFC 8785 cannot serialize ${typeof value}`);
-}
 /**
  * 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.
  */
-export function applyWorkspacePlan(plan, workspaceDir) {
+export function applyWorkspacePlan(plan, workspaceDir, options = {}) {
     const workspaceRoot = resolve(workspaceDir);
-    const files = normalizePlanFiles(plan.files).map((file) => ({
+    const runtimeOnlyFiles = new Set((options.runtimeOnlyFiles ?? []).map(normalizeWorkspaceRelativePath));
+    const files = normalizePlanFiles(plan.files)
+        .filter((file) => !runtimeOnlyFiles.has(file.relPath))
+        .map((file) => ({
         ...file,
         absPath: resolveWorkspaceFilePath(workspaceRoot, file.relPath),
     }));
@@ -739,6 +962,9 @@ export function applyWorkspacePlan(plan, workspaceDir) {
     // existing symlink cannot leave a partially materialized workspace.
     for (const file of files) {
         assertNoSymlinkPathComponents(workspaceRoot, file.absPath);
+        if (workspaceFileExists(file.absPath) && !workspaceFileMatches(file)) {
+            throw new Error(`Refusing to replace existing workspace file: ${file.relPath}`);
+        }
     }
     for (const file of files) {
         mkdirSync(dirname(file.absPath), { recursive: true });
@@ -748,17 +974,39 @@ export function applyWorkspacePlan(plan, workspaceDir) {
     }
     const written = [];
     for (const file of files) {
-        writeWorkspaceFile(workspaceRoot, file);
+        if (!workspaceFileExists(file.absPath)) {
+            writeWorkspaceFile(workspaceRoot, file);
+        }
         written.push(file.relPath);
     }
     return {
         workspacePlanDigest: hashWorkspacePlan(plan),
         env: plan.env,
         flags: plan.flags,
+        ...(plan.systemPrompt === undefined
+            ? {}
+            : { systemPrompt: plan.systemPrompt }),
         unsupported: plan.unsupported,
         written,
     };
 }
+function workspaceFileExists(pathValue) {
+    try {
+        lstatSync(pathValue);
+        return true;
+    }
+    catch (error) {
+        if (isFsError(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+}
+function workspaceFileMatches(file) {
+    const stats = lstatSync(file.absPath);
+    return (stats.isFile() &&
+        (stats.mode & 0o777) === file.mode &&
+        readFileSync(file.absPath, "utf8") === file.content);
+}
 function resolveWorkspaceFilePath(workspaceRoot, relativePath) {
     const targetPath = resolve(workspaceRoot, ...relativePath.split("/"));
     const targetRelativePath = relative(workspaceRoot, targetPath);
@@ -809,7 +1057,15 @@ function writeWorkspaceFile(workspaceRoot, file) {
         closeSync(descriptor);
         descriptor = undefined;
         assertNoSymlinkPathComponents(workspaceRoot, file.absPath);
-        renameSync(temporaryPath, file.absPath);
+        try {
+            linkSync(temporaryPath, file.absPath);
+        }
+        catch (error) {
+            if (!isFsError(error, "EEXIST") || !workspaceFileMatches(file)) {
+                throw error;
+            }
+        }
+        unlinkSync(temporaryPath);
     }
     catch (error) {
         if (descriptor !== undefined)
@@ -831,55 +1087,337 @@ function isFsError(error, code) {
         error.code === code);
 }
 // ─── Per-dimension routing (verified matrix) ────────────────────────────────
+function materializeExecutionControls(h, tools, permissions, modes, plan, add, unsupported) {
+    const toolEntries = Object.entries(tools ?? {}).sort(([left], [right]) => compareStrings(left, right));
+    const permissionEntries = Object.entries(permissions ?? {}).sort(([left], [right]) => compareStrings(left, right));
+    switch (h) {
+        case "claude-code": {
+            if (toolEntries.length > 0 || permissionEntries.length > 0) {
+                const nativeTools = mapSupportedBooleanEntries(toolEntries, claudeToolName, (name) => unsupported("tools", `claude-code: no verified native tool mapping for "${name}"`), "claude-code tool");
+                const nativePermissions = mapSupportedPermissionEntries(permissionEntries, claudeToolName, (name) => unsupported("permissions", `claude-code: no verified native permission mapping for "${name}"`), "claude-code permission");
+                const rules = claudePermissionRules(nativePermissions);
+                for (const [tool, enabled] of nativeTools) {
+                    rules[enabled ? "allow" : "deny"].push(tool);
+                }
+                add(CLAUDE_SETTINGS_PATH, JSON.stringify({ permissions: sealClaudePermissionRules(rules) }, null, 2));
+                registerClaudeSettings(plan);
+            }
+            break;
+        }
+        case "opencode": {
+            const enforceableTools = toolEntries.filter(([name, enabled]) => {
+                if (normalizedControlName(name) !== "lsp" || !enabled)
+                    return true;
+                unsupported("tools", "opencode: the LSP tool is disabled by the runtime and cannot be enabled exactly");
+                return false;
+            });
+            const enforceablePermissions = permissionEntries.filter(([name, policy]) => {
+                if (normalizedControlName(name) !== "read")
+                    return true;
+                if (!permissionAllowsEverything(policy)) {
+                    unsupported("permissions", "opencode: read access cannot be denied or approval-gated");
+                }
+                return false;
+            });
+            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({
+                    $schema: "https://opencode.ai/config.json",
+                    ...(nativeTools.length > 0
+                        ? { tools: Object.fromEntries(nativeTools) }
+                        : {}),
+                    ...(nativePermissions.length > 0
+                        ? { permission: Object.fromEntries(nativePermissions) }
+                        : {}),
+                }, null, 2));
+            }
+            break;
+        }
+        case "codex": {
+            const searchEntries = [];
+            for (const [name, enabled] of toolEntries) {
+                const posture = resolveNativeWebTools({ [name]: enabled });
+                if (posture.search === enabled && posture.fetch === undefined) {
+                    searchEntries.push([name, enabled]);
+                    continue;
+                }
+                if (posture.fetch === enabled && posture.search === undefined) {
+                    if (enabled) {
+                        unsupported("tools", `codex: native web fetch is unavailable for "${name}"`);
+                    }
+                    continue;
+                }
+                unsupported("tools", `codex: no verified primary-process tool mapping for "${name}"`);
+            }
+            const nativeSearch = mapSupportedBooleanEntries(searchEntries, () => "web_search", () => undefined, "codex tool");
+            if (nativeSearch[0]) {
+                plan.flags.push("-c", `tools.web_search=${nativeSearch[0][1]}`);
+            }
+            if (permissionEntries.length > 0) {
+                unsupported("permissions", "codex: no verified primary-process permission policy mapping");
+            }
+            break;
+        }
+        default:
+            if (toolEntries.length > 0) {
+                unsupported("tools", `${h}: no verified primary-process tool availability mapping`);
+            }
+            if (permissionEntries.length > 0) {
+                unsupported("permissions", `${h}: no verified primary-process permission policy mapping`);
+            }
+    }
+    if (modes && Object.keys(modes).length > 0) {
+        unsupported("modes", `${h}: resolve one named AgentProfile mode before materialization`);
+    }
+}
+function normalizedControlName(name) {
+    return name.replace(/[^a-zA-Z0-9_]/g, "").toLowerCase();
+}
+function nativeWebToolKind(name) {
+    const posture = resolveNativeWebTools({ [name]: true });
+    if (posture.search === true && posture.fetch === undefined)
+        return "search";
+    if (posture.fetch === true && posture.search === undefined)
+        return "fetch";
+    return undefined;
+}
+const CLAUDE_TOOL_NAMES = {
+    askuserquestion: "AskUserQuestion",
+    bash: "Bash",
+    edit: "Edit",
+    glob: "Glob",
+    grep: "Grep",
+    notebookedit: "NotebookEdit",
+    read: "Read",
+    skill: "Skill",
+    task: "Task",
+    taskoutput: "TaskOutput",
+    todowrite: "TodoWrite",
+    webfetch: "WebFetch",
+    websearch: "WebSearch",
+    write: "Write",
+};
+function claudeToolName(name) {
+    const web = nativeWebToolKind(name);
+    if (web === "search")
+        return "WebSearch";
+    if (web === "fetch")
+        return "WebFetch";
+    return CLAUDE_TOOL_NAMES[normalizedControlName(name)];
+}
+const OPENCODE_TOOL_NAMES = new Set([
+    "bash",
+    "batch",
+    "codesearch",
+    "edit",
+    "glob",
+    "grep",
+    "list",
+    "lsp",
+    "multiedit",
+    "patch",
+    "read",
+    "task",
+    "todoread",
+    "todowrite",
+    "webfetch",
+    "websearch",
+    "write",
+]);
+function openCodeToolName(name) {
+    const web = nativeWebToolKind(name);
+    if (web === "search")
+        return "websearch";
+    if (web === "fetch")
+        return "webfetch";
+    const normalized = normalizedControlName(name);
+    return OPENCODE_TOOL_NAMES.has(normalized) ? normalized : undefined;
+}
+function openCodePermissionName(name) {
+    const normalized = normalizedControlName(name);
+    if (["write", "edit"].includes(normalized))
+        return "edit";
+    const web = nativeWebToolKind(name);
+    if (web === "search")
+        return "websearch";
+    if (web === "fetch")
+        return "webfetch";
+    if (["bash", "mcp", "doom_loop", "external_directory"].includes(normalized)) {
+        return normalized;
+    }
+    return normalized !== "read" && OPENCODE_TOOL_NAMES.has(normalized)
+        ? normalized
+        : undefined;
+}
+function mapSupportedBooleanEntries(entries, mapName, onUnsupported, label) {
+    return mapControlEntries(entries, mapName, onUnsupported, (left, right, nativeName) => {
+        if (left !== right)
+            throw new Error(`${label} aliases disagree for "${nativeName}"`);
+        return left;
+    });
+}
+function permissionAllowsEverything(policy) {
+    return typeof policy === "string"
+        ? policy === "allow"
+        : Object.values(policy).every((value) => value === "allow");
+}
+function mapSupportedPermissionEntries(entries, mapName, onUnsupported, label) {
+    return mapControlEntries(entries, mapName, onUnsupported, (left, right, nativeName) => mergePermissionPolicies(left, right, `${label} "${nativeName}"`));
+}
+function mapControlEntries(entries, mapName, onUnsupported, merge) {
+    const mapped = new Map();
+    for (const [name, value] of entries) {
+        const nativeName = mapName(name);
+        if (!nativeName) {
+            onUnsupported(name);
+            continue;
+        }
+        const previous = mapped.get(nativeName);
+        mapped.set(nativeName, previous === undefined ? value : merge(previous, value, nativeName));
+    }
+    return [...mapped.entries()].sort(([left], [right]) => compareStrings(left, right));
+}
+function mergePermissionPolicies(left, right, label) {
+    if (typeof left === "string" || typeof right === "string") {
+        if (left !== right)
+            throw new Error(`${label} aliases disagree`);
+        return left;
+    }
+    const merged = { ...left };
+    for (const [specifier, decision] of Object.entries(right)) {
+        const previous = merged[specifier];
+        if (previous !== undefined && previous !== decision) {
+            throw new Error(`${label} aliases disagree for "${specifier}"`);
+        }
+        merged[specifier] = decision;
+    }
+    return Object.fromEntries(Object.entries(merged).sort(([leftKey], [rightKey]) => compareStrings(leftKey, rightKey)));
+}
+function claudePermissionRules(entries) {
+    const rules = {
+        allow: [],
+        ask: [],
+        deny: [],
+    };
+    for (const [tool, policy] of entries) {
+        if (typeof policy === "string") {
+            rules[policy].push(tool);
+            continue;
+        }
+        for (const [specifier, decision] of Object.entries(policy).sort(([left], [right]) => compareStrings(left, right))) {
+            rules[decision].push(specifier === "*" ? tool : `${tool}(${specifier})`);
+        }
+    }
+    rules.allow.sort(compareStrings);
+    rules.ask.sort(compareStrings);
+    rules.deny.sort(compareStrings);
+    return rules;
+}
+function sealClaudePermissionRules(rules) {
+    const owner = new Map();
+    for (const decision of ["allow", "ask", "deny"]) {
+        for (const rule of rules[decision]) {
+            const previous = owner.get(rule);
+            if (previous && previous !== decision) {
+                throw new Error(`claude-code execution control "${rule}" conflicts between ${previous} and ${decision}`);
+            }
+            owner.set(rule, decision);
+        }
+    }
+    return {
+        allow: [...new Set(rules.allow)].sort(compareStrings),
+        ask: [...new Set(rules.ask)].sort(compareStrings),
+        deny: [...new Set(rules.deny)].sort(compareStrings),
+    };
+}
 function materializeMcp(h, mcp, plan, add, unsupported) {
     switch (h) {
-        case "claude-code":
+        case "claude-code": {
+            const servers = {};
+            for (const [name, server] of Object.entries(mcp)) {
+                if (server.url) {
+                    servers[name] = {
+                        type: server.transport ?? "http",
+                        url: server.url,
+                        ...(server.headers ? { headers: server.headers } : {}),
+                    };
+                    continue;
+                }
+                if (server.cwd !== undefined) {
+                    unsupported("mcp", `${h}: local MCP server "${name}" does not support a cwd field`);
+                }
+                servers[name] = {
+                    type: "stdio",
+                    command: server.command,
+                    ...(server.args ? { args: server.args } : {}),
+                    ...(server.env ? { env: server.env } : {}),
+                };
+            }
+            const relPath = ".tangle/claude-mcp.json";
+            add(relPath, JSON.stringify({ mcpServers: servers }, null, 2));
+            plan.flags.push("--mcp-config", relPath, "--strict-mcp-config");
+            break;
+        }
         case "nanoclaw":
-            // claude reads ./.mcp.json but each server needs per-project APPROVAL; we also
-            // enable them via .claude/settings.json enabledMcpjsonServers to skip the prompt.
-            add(".mcp.json", JSON.stringify({ mcpServers: mcp }, null, 2));
-            add(".claude/settings.json", JSON.stringify({ enabledMcpjsonServers: Object.keys(mcp) }, null, 2));
-            if (h === "nanoclaw")
-                unsupported("mcp", "nanoclaw MCP is SDK-injected (options.mcpServers); .mcp.json may be ignored — inject via the SDK adapter");
+            unsupported("mcp", "nanoclaw MCP must be injected through options.mcpServers by its SDK adapter");
             break;
         case "codex": {
-            // codex reads [mcp_servers.<id>] in .codex/config.toml; trusted projects only.
-            const lines = ['[projects."."]', 'trust_level = "trusted"', ""];
-            for (const [name, s] of Object.entries(mcp)) {
-                lines.push(`[mcp_servers.${name}]`);
-                if (s.command)
-                    lines.push(`command = ${tomlStr(s.command)}`);
-                if (s.args?.length)
-                    lines.push(`args = [${s.args.map(tomlStr).join(", ")}]`);
-                if (s.cwd)
-                    lines.push(`cwd = ${tomlStr(s.cwd)}`);
-                if (s.url)
-                    lines.push(`url = ${tomlStr(s.url)}`);
-                if (s.env)
-                    lines.push(`env = { ${Object.entries(s.env)
-                        .map(([k, v]) => `${k} = ${tomlStr(v)}`)
-                        .join(", ")} }`);
-                lines.push("");
+            const servers = [];
+            for (const [name, server] of Object.entries(mcp).sort(([left], [right]) => compareStrings(left, right))) {
+                if (server.url && server.transport === "sse") {
+                    unsupported("mcp", `codex: remote MCP server "${name}" uses unsupported SSE transport`);
+                    continue;
+                }
+                servers.push(`${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(", ")} }`);
             }
-            add(".codex/config.toml", lines.join("\n"));
             break;
         }
         case "opencode":
             // opencode.json "mcp" block (local|remote).
-            add("opencode.json", JSON.stringify({ $schema: "https://opencode.ai/config.json", mcp: opencodeMcp(mcp) }, null, 2));
+            add("opencode.json", JSON.stringify({
+                $schema: "https://opencode.ai/config.json",
+                mcp: openCodeMcpConfig(mcp),
+            }, null, 2));
             break;
-        case "gemini":
-            add(".gemini/settings.json", JSON.stringify({ mcpServers: mcp }, null, 2));
+        case "gemini": {
+            const servers = {};
+            for (const [name, server] of Object.entries(mcp)) {
+                if (server.url) {
+                    servers[name] = {
+                        [server.transport === "sse" ? "url" : "httpUrl"]: server.url,
+                        ...(server.headers ? { headers: server.headers } : {}),
+                    };
+                    continue;
+                }
+                servers[name] = {
+                    command: server.command,
+                    ...(server.args ? { args: server.args } : {}),
+                    ...(server.env ? { env: server.env } : {}),
+                    ...(server.cwd ? { cwd: server.cwd } : {}),
+                };
+            }
+            add(".gemini/settings.json", JSON.stringify({ mcpServers: servers }, null, 2));
             break;
+        }
         case "kimi-code": {
             // NO cwd auto-discovery — kimi needs an explicit --mcp-config-file FLAG.
             const rel = ".kimi/mcp.json";
-            add(rel, JSON.stringify({ mcpServers: mcp }, null, 2));
+            const servers = Object.fromEntries(Object.entries(mcp).map(([name, server]) => [
+                name,
+                kimiMcpServer(server),
+            ]));
+            add(rel, JSON.stringify({ mcpServers: servers }, null, 2));
             plan.flags.push("--mcp-config-file", rel);
             break;
         }
         case "pi":
-            unsupported("mcp", "pi MCP is wired via a TS extension (.pi/extensions/*.ts), not a declarative cwd file — build an extension");
+            unsupported("mcp", "pi MCP requires a loaded MCP extension; the base Pi runtime has no MCP control");
             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");
@@ -889,70 +1427,182 @@ function materializeMcp(h, mcp, plan, add, unsupported) {
             break;
     }
 }
-function opencodeMcp(mcp) {
+function tomlInlineStringTable(values) {
+    return `{ ${Object.entries(values)
+        .sort(([left], [right]) => compareStrings(left, right))
+        .map(([key, value]) => `${tomlStr(key)} = ${tomlStr(value)}`)
+        .join(", ")} }`;
+}
+function codexMcpServerToml(name, server, plan) {
+    const fields = [];
+    if (server.url) {
+        fields.push(`url = ${tomlStr(server.url)}`);
+        if (server.headers && Object.keys(server.headers).length > 0) {
+            const envHeaders = {};
+            for (const [header, value] of Object.entries(server.headers).sort(([left], [right]) => compareStrings(left, right))) {
+                const envName = `TANGLE_MCP_HEADER_${sha256(`${name}\0${header}`)
+                    .slice(0, 24)
+                    .toUpperCase()}`;
+                setPlanEnvironment(plan, envName, value);
+                envHeaders[header] = envName;
+            }
+            fields.push(`env_http_headers = ${tomlInlineStringTable(envHeaders)}`);
+        }
+    }
+    else {
+        if (!server.command) {
+            throw new Error(`Codex MCP server "${name}" must define url or command`);
+        }
+        fields.push(`command = ${tomlStr(server.command)}`);
+        if (server.args?.length) {
+            fields.push(`args = [${server.args.map(tomlStr).join(", ")}]`);
+        }
+        if (server.cwd)
+            fields.push(`cwd = ${tomlStr(server.cwd)}`);
+        if (server.env && Object.keys(server.env).length > 0) {
+            const envNames = Object.keys(server.env).sort(compareStrings);
+            for (const envName of envNames) {
+                setPlanEnvironment(plan, envName, server.env[envName]);
+            }
+            fields.push(`env_vars = [${envNames.map(tomlStr).join(", ")}]`);
+        }
+    }
+    return `{ ${fields.join(", ")} }`;
+}
+function setPlanEnvironment(plan, name, value) {
+    const previous = plan.env[name];
+    if (previous !== undefined && previous !== value) {
+        throw new Error(`profile environment values disagree for ${name}`);
+    }
+    plan.env[name] = value;
+}
+function kimiMcpServer(server) {
+    if (server.url) {
+        return {
+            url: server.url,
+            transport: server.transport ?? "http",
+            ...(server.headers ? { headers: server.headers } : {}),
+        };
+    }
+    return {
+        command: server.command,
+        ...(server.args ? { args: server.args } : {}),
+        ...(server.env ? { env: server.env } : {}),
+        ...(server.cwd ? { cwd: server.cwd } : {}),
+    };
+}
+/** Lower canonical MCP definitions to OpenCode's native startup configuration. */
+export function openCodeMcpConfig(mcp) {
     const out = {};
     for (const [name, s] of Object.entries(mcp)) {
-        out[name] = s.url
-            ? {
+        if (s.enabled === false)
+            continue;
+        if (s.url) {
+            if (s.transport === "sse") {
+                throw new Error(`OpenCode MCP server "${name}" uses unsupported SSE transport`);
+            }
+            out[name] = {
                 type: "remote",
                 url: s.url,
-                enabled: s.enabled !== false,
+                enabled: true,
                 ...(s.headers ? { headers: s.headers } : {}),
-            }
-            : {
-                type: "local",
-                command: [s.command, ...(s.args ?? [])].filter(Boolean),
-                enabled: s.enabled !== false,
-                ...(s.env ? { environment: s.env } : {}),
             };
+            continue;
+        }
+        if (!s.command) {
+            throw new Error(`OpenCode MCP server "${name}" must define either url or command`);
+        }
+        if (s.cwd !== undefined) {
+            throw new Error(`OpenCode MCP server "${name}" does not support a cwd field`);
+        }
+        out[name] = {
+            type: "local",
+            command: [s.command, ...(s.args ?? [])],
+            enabled: true,
+            ...(s.env ? { environment: s.env } : {}),
+        };
     }
     return out;
 }
 function materializeHooks(h, hooks, add, unsupported, plan) {
     switch (h) {
-        case "claude-code":
-        case "nanoclaw": {
-            // .claude/settings.json hooks{} — each event → [{matcher, hooks:[{type:command,command}]}].
+        case "claude-code": {
+            // Claude settings hooks{} — each event → [{matcher, hooks:[{type:command,command}]}].
             const settingsHooks = {};
             for (const [event, cmds] of Object.entries(hooks)) {
+                if (!hookEventSupported("claude-code", event)) {
+                    unsupported("hooks", `claude-code: unsupported hook event "${event}"`);
+                    continue;
+                }
                 settingsHooks[event] = cmds.map((c) => ({
                     matcher: c.matcher ?? "*",
                     hooks: [
                         {
                             type: "command",
-                            command: c.command,
-                            ...(c.timeoutMs
-                                ? { timeout: Math.round(c.timeoutMs / 1000) }
-                                : {}),
+                            command: materializedHookCommand(event, c, add),
+                            ...(c.timeoutMs ? { timeout: timeoutSeconds(c.timeoutMs) } : {}),
+                            ...(c.blocking === false ? { async: true } : {}),
                         },
                     ],
                 }));
             }
-            add(".claude/settings.json", JSON.stringify({ hooks: settingsHooks }, null, 2));
+            add(CLAUDE_SETTINGS_PATH, JSON.stringify({ hooks: settingsHooks }, null, 2));
+            registerClaudeSettings(plan);
             break;
         }
+        case "nanoclaw":
+            unsupported("hooks", "nanoclaw's chat bridge does not expose Claude Code hook settings to the spawned agent");
+            break;
         case "gemini": {
             const settingsHooks = {};
-            for (const [event, cmds] of Object.entries(hooks))
+            for (const [event, cmds] of Object.entries(hooks)) {
+                if (!hookEventSupported("gemini", event)) {
+                    unsupported("hooks", `gemini: unsupported hook event "${event}"`);
+                    continue;
+                }
+                if (cmds.some((command) => command.blocking === false)) {
+                    unsupported("hooks", `gemini: hook event "${event}" does not support non-blocking commands`);
+                }
                 settingsHooks[event] = cmds.map((c) => ({
                     matcher: c.matcher ?? "*",
-                    hooks: [{ type: "command", command: c.command }],
+                    hooks: [
+                        {
+                            type: "command",
+                            command: materializedHookCommand(event, c, add),
+                            ...(c.timeoutMs ? { timeout: c.timeoutMs } : {}),
+                        },
+                    ],
                 }));
+            }
             add(".gemini/settings.json", JSON.stringify({ hooks: settingsHooks }, null, 2));
             break;
         }
         case "codex": {
-            // codex hooks.json (event → commands).
-            add(".codex/hooks.json", JSON.stringify({ hooks }, null, 2));
+            for (const [event, cmds] of Object.entries(hooks).sort(([left], [right]) => compareStrings(left, right))) {
+                if (!hookEventSupported("codex", event)) {
+                    unsupported("hooks", `codex: unsupported hook event "${event}"`);
+                    continue;
+                }
+                if (cmds.some((command) => command.blocking === false)) {
+                    unsupported("hooks", `codex: hook event "${event}" cannot execute asynchronous commands`);
+                    continue;
+                }
+                const entries = cmds.map((command) => {
+                    const handler = [
+                        `type = ${tomlStr("command")}`,
+                        `command = ${tomlStr(materializedHookCommand(event, command, add))}`,
+                        ...(command.timeoutMs
+                            ? [`timeout = ${timeoutSeconds(command.timeoutMs)}`]
+                            : []),
+                    ];
+                    return `{ matcher = ${tomlStr(command.matcher ?? "*")}, hooks = [{ ${handler.join(", ")} }] }`;
+                });
+                plan.flags.push("-c", `hooks.${event}=[${entries.join(", ")}]`);
+            }
             break;
         }
         case "opencode":
-            // opencode hooks are PLUGINS (JS/TS), not a settings block — emit a plugin stub.
-            for (const [event, cmds] of Object.entries(hooks)) {
-                const body = cmds.map((c) => `  // ${event}: ${c.command}`).join("\n");
-                add(`.opencode/plugins/vb-hooks-${event}.js`, `// auto-generated hook plugin for ${event}\nexport default async function () {\n${body}\n}\n`);
-            }
-            unsupported("hooks", "opencode hooks are JS/TS plugins — generated a stub; a real handler must run the command (format differs from settings.json)");
+            unsupported("hooks", "opencode hooks require executable JS/TS plugins; command hooks cannot be translated exactly");
             break;
         case "kimi-code":
             unsupported("hooks", "kimi hooks are [[hooks]] in the config TOML loaded via --config-file, not cwd — pass --config-file");
@@ -960,31 +1610,159 @@ function materializeHooks(h, hooks, add, unsupported, plan) {
         case "pi":
             unsupported("hooks", "pi hooks are TS extensions (.pi/extensions/*.ts) — build an extension");
             break;
-        case "hermes": {
-            // opt-in project plugins; requires HERMES_ENABLE_PROJECT_PLUGINS=1.
-            for (const [event, cmds] of Object.entries(hooks))
-                add(`.hermes/plugins/vb-${event}/plugin.md`, cmds.map((c) => c.command).join("\n"));
-            plan.env.HERMES_ENABLE_PROJECT_PLUGINS = "1";
+        case "hermes":
+            unsupported("hooks", "hermes project plugins do not expose an exact command-hook mapping");
             break;
-        }
         case "openclaw":
             unsupported("hooks", "openclaw hooks are DISABLED by default — enable in ~/.openclaw/openclaw.json; cwd hooks/ alone is a no-op");
             break;
     }
 }
-function materializeSubagent(h, name, sa, add, unsupported) {
+function registerClaudeSettings(plan) {
+    for (let index = 0; index < plan.flags.length - 1; index += 1) {
+        if (plan.flags[index] === "--settings" &&
+            plan.flags[index + 1] === CLAUDE_SETTINGS_PATH) {
+            return;
+        }
+    }
+    plan.flags.push("--settings", CLAUDE_SETTINGS_PATH);
+}
+const CLAUDE_HOOK_EVENTS = new Set([
+    "ConfigChange",
+    "CwdChanged",
+    "Elicitation",
+    "ElicitationResult",
+    "FileChanged",
+    "InstructionsLoaded",
+    "MessageDisplay",
+    "Notification",
+    "PermissionDenied",
+    "PermissionRequest",
+    "PostCompact",
+    "PostToolBatch",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PreCompact",
+    "PreToolUse",
+    "SessionEnd",
+    "SessionStart",
+    "Setup",
+    "Stop",
+    "StopFailure",
+    "SubagentStart",
+    "SubagentStop",
+    "TaskCompleted",
+    "TaskCreated",
+    "TeammateIdle",
+    "UserPromptExpansion",
+    "UserPromptSubmit",
+    "WorktreeCreate",
+    "WorktreeRemove",
+]);
+const CODEX_HOOK_EVENTS = new Set([
+    "PermissionRequest",
+    "PostCompact",
+    "PostToolUse",
+    "PreCompact",
+    "PreToolUse",
+    "SessionStart",
+    "Stop",
+    "SubagentStart",
+    "SubagentStop",
+    "UserPromptSubmit",
+]);
+const GEMINI_HOOK_EVENTS = new Set([
+    "AfterAgent",
+    "AfterModel",
+    "AfterTool",
+    "BeforeAgent",
+    "BeforeModel",
+    "BeforeTool",
+    "BeforeToolSelection",
+    "Notification",
+    "PreCompress",
+    "SessionEnd",
+    "SessionStart",
+]);
+function hookEventSupported(harness, event) {
+    switch (canonicalHarness(harness)) {
+        case "claude-code":
+            return CLAUDE_HOOK_EVENTS.has(event);
+        case "codex":
+            return CODEX_HOOK_EVENTS.has(event);
+        case "gemini":
+            return GEMINI_HOOK_EVENTS.has(event);
+        default:
+            return false;
+    }
+}
+function timeoutSeconds(timeoutMs) {
+    return Math.max(1, Math.ceil(timeoutMs / 1000));
+}
+function materializedHookCommand(event, command, add) {
+    if (!command.env || Object.keys(command.env).length === 0) {
+        return command.command;
+    }
+    const wrapperId = canonicalCandidateDigest({
+        event,
+        command: command.command,
+        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));
+    return `node ${path}`;
+}
+function hookWrapperSource(executable, args, env) {
+    return [
+        'import { spawnSync } from "node:child_process"',
+        `const executable = ${JSON.stringify(executable)}`,
+        `const args = ${JSON.stringify(args)}`,
+        `const extraEnv = ${JSON.stringify(env)}`,
+        "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 materializeSubagent(h, name, sa, plan, add, unsupported) {
+    if (!/^[a-z0-9][a-z0-9_-]*$/.test(name)) {
+        unsupported("subagents", `${h}: subagent name "${name}" must use lowercase letters, digits, underscores, or hyphens`);
+        return;
+    }
     switch (h) {
         case "claude-code":
         case "nanoclaw": {
             const fm = ["---", `name: ${name}`];
-            if (sa.description)
-                fm.push(`description: ${JSON.stringify(sa.description)}`);
+            fm.push(`description: ${JSON.stringify(sa.description ?? name)}`);
             if (sa.model)
-                fm.push(`model: ${sa.model}`);
-            if (sa.tools)
-                fm.push(`tools: ${Object.keys(sa.tools)
-                    .filter((t) => sa.tools?.[t])
-                    .join(", ")}`);
+                fm.push(`model: ${JSON.stringify(sa.model)}`);
+            if (sa.tools) {
+                const tools = Object.entries(sa.tools);
+                const allowed = tools
+                    .filter(([, enabled]) => enabled)
+                    .map(([tool]) => tool);
+                const denied = tools
+                    .filter(([, enabled]) => !enabled)
+                    .map(([tool]) => tool);
+                if (allowed.length > 0)
+                    fm.push(`tools: ${JSON.stringify(allowed)}`);
+                if (denied.length > 0)
+                    fm.push(`disallowedTools: ${JSON.stringify(denied)}`);
+            }
+            if (sa.maxSteps !== undefined)
+                fm.push(`maxTurns: ${sa.maxSteps}`);
+            reportUnsupportedSubagentFields(h, name, sa, new Set(["description", "prompt", "model", "tools", "maxSteps"]), unsupported);
             fm.push("---", "", sa.prompt ?? sa.description ?? name);
             add(`.claude/agents/${name}.md`, `${fm.join("\n")}\n`);
             break;
@@ -993,31 +1771,92 @@ function materializeSubagent(h, name, sa, add, unsupported) {
             const fm = [
                 "---",
                 `description: ${JSON.stringify(sa.description ?? name)}`,
+                "mode: subagent",
             ];
             if (sa.model)
-                fm.push(`model: ${sa.model}`);
+                fm.push(`model: ${JSON.stringify(sa.model)}`);
+            if (sa.tools)
+                fm.push(`tools: ${JSON.stringify(sa.tools)}`);
+            if (sa.permissions)
+                fm.push(`permission: ${JSON.stringify(sa.permissions)}`);
+            if (sa.maxSteps !== undefined)
+                fm.push(`steps: ${sa.maxSteps}`);
+            reportUnsupportedSubagentFields(h, name, sa, new Set([
+                "description",
+                "prompt",
+                "model",
+                "tools",
+                "permissions",
+                "maxSteps",
+            ]), unsupported);
             fm.push("---", "", sa.prompt ?? "");
             add(`.opencode/agents/${name}.md`, `${fm.join("\n")}\n`);
             break;
         }
-        case "gemini":
-            add(`.gemini/agents/${name}.md`, `---\nname: ${name}\ndescription: ${JSON.stringify(sa.description ?? name)}\n---\n\n${sa.prompt ?? ""}\n`);
+        case "gemini": {
+            const tools = sa.tools
+                ? Object.entries(sa.tools)
+                    .filter(([, enabled]) => enabled)
+                    .map(([tool]) => tool)
+                : undefined;
+            reportUnsupportedSubagentFields(h, name, sa, new Set(["description", "prompt", "model", "tools", "maxSteps"]), unsupported);
+            add(`.gemini/agents/${name}.md`, [
+                "---",
+                `name: ${name}`,
+                `description: ${JSON.stringify(sa.description ?? name)}`,
+                "kind: local",
+                ...(sa.model ? [`model: ${JSON.stringify(sa.model)}`] : []),
+                ...(tools ? [`tools: ${JSON.stringify(tools)}`] : []),
+                ...(sa.maxSteps !== undefined ? [`max_turns: ${sa.maxSteps}`] : []),
+                "---",
+                "",
+                sa.prompt ?? "",
+                "",
+            ].join("\n"));
             break;
+        }
         case "codex": {
-            const lines = [`name = ${tomlStr(name)}`];
-            if (sa.description)
-                lines.push(`description = ${tomlStr(sa.description)}`);
+            const relPath = `.codex/agents/${name}.toml`;
+            const lines = [
+                `name = ${tomlStr(name)}`,
+                `description = ${tomlStr(sa.description ?? name)}`,
+                `developer_instructions = ${tomlStr(sa.prompt ?? sa.description ?? name)}`,
+            ];
             if (sa.model)
                 lines.push(`model = ${tomlStr(sa.model)}`);
-            if (sa.prompt)
-                lines.push(`prompt = ${tomlStr(sa.prompt)}`);
-            add(`.codex/agents/${name}.toml`, `${lines.join("\n")}\n`);
+            reportUnsupportedSubagentFields(h, name, sa, new Set(["description", "prompt", "model"]), unsupported);
+            add(relPath, `${lines.join("\n")}\n`);
+            registerCodexAgent(plan, name, relPath, sa.description ?? name);
             break;
         }
         default:
             unsupported("subagents", `${h}: subagents have no cwd file (config/flag/global only); "${name}" not mounted`);
     }
 }
+function codexAgentRoleName(resourceName) {
+    const name = resourceName.endsWith(".toml")
+        ? resourceName.slice(0, -".toml".length)
+        : resourceName;
+    return /^[a-z0-9][a-z0-9_-]*$/.test(name) ? name : undefined;
+}
+function registerCodexAgent(plan, name, configFile, description) {
+    plan.flags.push("-c", `agents.${name}.description=${tomlStr(description)}`, "-c", `agents.${name}.config_file=${tomlStr(configFile)}`);
+}
+function reportUnsupportedSubagentFields(harness, name, subagent, supported, unsupported) {
+    for (const field of [
+        "description",
+        "prompt",
+        "model",
+        "tools",
+        "permissions",
+        "maxSteps",
+        "metadata",
+    ]) {
+        if (subagent[field] !== undefined && !supported.has(field)) {
+            unsupported("subagents", `${harness}: subagent "${name}" does not support ${field}`);
+        }
+    }
+}
 function materializeCommand(h, name, body, add, unsupported) {
     switch (h) {
         case "claude-code":