pi-vault-mind 0.16.28 → 0.16.30

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.16.30 — 2026-08-27
+
+### Added
+
+- **First-class `pvm` executable.** The npm package now exposes `pvm run [vault-path]`; it uses the current directory when the vault path is omitted and supports both global installation and `npx pi-vault-mind run`.
+- **Explicit launch modes.** `pvm run` stays in the current terminal by default, with `--same-terminal`, `--new-window`, and `--auto` overrides.
+
+### Fixed
+
+- **Portable vault launcher.** `vault-pi.sh` now handles interactive terminals directly, normalizes relative vault paths before deriving runtime state, removes inline-session PID files on exit, and rejects unknown flags instead of treating them as vault paths.
+
+### Verification
+
+- Root and Obsidian builds passed; full test suite: 910/910 passing.
+- `npm pack` includes `scripts/pvm.mjs` as an executable, and `npm exec` resolved the packed tarball's `pvm` command successfully.
+
+## 0.16.29 — 2026-08-27
+
+### Fixed
+
+- **Main-terminal identity isolation.** Ambient bundled specialist skills no longer make the interactive Pi session inherit the first matching specialist boundary. Identity injection now defaults to the unrestricted main agent and only activates from an explicit vault or environment selection.
+- **Explicit persona controls.** Added `/vm identity status | set <role> | on | off`, `VAULT_MIND_AGENT_ROLE`, and `VAULT_MIND_IDENTITY_INJECTION`, with canonical persistence under `vaultMind.identities`.
+- **Identity configuration migration and write safety.** Legacy top-level identity settings migrate without losing role allowlists, new scaffolds use the canonical path, and malformed JSON is reported without overwriting the existing vault configuration or leaking an unhandled HTTP rejection.
+
+### Verification
+
+- Root and Obsidian builds passed; full test suite: 899/899 passing.
+- Real-vault startup probe confirmed ambient Broadcaster resources keep the unrestricted main identity while an explicit Broadcaster override activates the boundary.
 
 ## 0.16.28 — 2026-08-09
 

package/README.md

@@ -194,10 +194,25 @@ The Broadcaster agent can generate podcasts, study guides, and slide decks from
 
 ```bash
 pi install npm:pi-vault-mind              # latest
-pi install npm:pi-vault-mind@0.7.0        # pinned
+pi install npm:pi-vault-mind@0.16.30       # pinned release
 pi -e npm:pi-vault-mind                   # try without installing
 ```
 
+`pi install` loads the extension but does not expose its npm executable on your
+shell `PATH`. Install the first-class launcher once when you want the bare
+`pvm` command:
+
+```bash
+npm install --global pi-vault-mind
+pvm run /path/to/your/vault
+```
+
+Or run it without a global installation:
+
+```bash
+npx --yes pi-vault-mind run /path/to/your/vault
+```
+
 Or from git:
 
 ```bash
@@ -269,6 +284,174 @@ Edit `<vault>/.vault-mind/vault-mind.config.json` to match your domain:
 }
 ```
 
+## Using Vault Mind agent identities
+
+Vault Mind keeps the interactive Pi session on the unrestricted `main` persona
+unless you explicitly select a specialist boundary. Bundled specialist skills
+are available resources; merely loading them does not change the active
+persona.
+
+### Start the vault-local main agent
+
+From the vault directory, start Pi in the current terminal:
+
+```bash
+pvm run
+```
+
+You can launch a different vault from anywhere or use the package without a
+global install:
+
+```bash
+pvm run /path/to/your/vault
+npx --yes pi-vault-mind run /path/to/your/vault
+```
+
+`pvm run` defaults to the current terminal. This is the recommended Obsidian
+Terminal profile command. Use a vault-path placeholder supplied by the plugin,
+or provide the vault's absolute path. Override the launch mode when needed:
+
+```bash
+pvm run --same-terminal /path/to/your/vault
+pvm run --new-window /path/to/your/vault
+pvm run --auto /path/to/your/vault
+```
+
+`--new-window` opens a dedicated Terminal/iTerm window. `--auto` uses the
+current terminal when attached to a TTY and falls back to a new window
+otherwise. The packaged shell launcher remains available for direct use as
+`scripts/vault-pi.sh`.
+
+In every mode, the launcher runs Pi inside the target vault with its
+configuration isolated under `<vault>/.vault-mind/.pi/agent/`. It also prevents
+two launcher-managed Pi processes from running for the same vault and removes
+the PID file when an inline session exits.
+
+Check the active persona after startup:
+
+```text
+/vm identity status
+```
+
+A normal main-agent session reports:
+
+```text
+Persona: main
+Effective boundary: none (main agent)
+```
+
+`Injection` may report `enabled` or `disabled`. An enabled injector still
+applies no boundary while the persona is `main`.
+
+### Use specialist agents without changing the main session
+
+Normally, leave the interactive session on `main` and dispatch specialist work
+through the passive watcher:
+
+```text
+@agent-Miner
+Research and extract the durable facts from this note.
+```
+
+The watcher runs that work as an isolated specialist job. It does not turn the
+interactive terminal into the Miner persona. The same distinction applies to
+`@agent-Broadcaster`, `@agent-Manager`, and `@agent-Heavy-Lifter`.
+
+### Explicitly change the interactive persona
+
+Use an identity boundary only when the current interactive session itself
+should follow a specialist capability contract:
+
+```text
+/vm identity set miner
+/vm identity set broadcaster
+/vm identity set manager
+/vm identity set heavy-lifter
+```
+
+| Persona | Intended interactive boundary |
+|---|---|
+| `main` | Unrestricted primary agent with the full configured toolset |
+| `manager` | Orchestrates collections, publishing, and subagents; does not run Bash |
+| `miner` | Extracts and stores knowledge; does not run Bash or publish |
+| `broadcaster` | Produces presentation artifacts; does not run Bash or write durable knowledge |
+| `heavy-lifter` | Performs file and Bash work in isolation; does not write durable knowledge or publish |
+
+`/vm identity set <role>` persists the selected persona, enables boundary
+injection, and applies on the next agent turn.
+
+Use the remaining controls to inspect or suspend that selection:
+
+```text
+/vm identity status
+/vm identity off
+/vm identity on
+```
+
+- `off` disables boundary injection without discarding the selected persona.
+- `on` re-enables the configured persona boundary on the next agent turn.
+- `status` shows the configured persona, injection switch, effective boundary,
+  and any environment overrides.
+
+Restore the safe main-agent default with:
+
+```text
+/vm identity set main
+/vm identity off
+/vm identity status
+```
+
+The final status should show `Effective boundary: none (main agent)`.
+
+### Configuration and environment overrides
+
+Identity controls are stored in the vault-local configuration:
+
+```json
+{
+  "vaultMind": {
+    "identities": {
+      "activeRole": "main",
+      "injectBoundaries": false
+    }
+  }
+}
+```
+
+The canonical path is
+`<vault>/.vault-mind/vault-mind.config.json` under
+`vaultMind.identities`. Identity commands preserve any existing
+`vaultMind.identities.roles` allowlists.
+
+Launch automation and explicit specialist forks can override the saved values
+for one process:
+
+```bash
+VAULT_MIND_AGENT_ROLE=miner VAULT_MIND_IDENTITY_INJECTION=on pi
+VAULT_MIND_IDENTITY_INJECTION=off pi
+```
+
+`VAULT_MIND_AGENT_ROLE` takes precedence over `activeRole`.
+`VAULT_MIND_IDENTITY_INJECTION=off` suppresses every boundary, while `on`
+enables the explicitly selected role. Missing, `main`, `none`, and unknown
+roles all resolve safely to the unrestricted main agent.
+
+### Troubleshoot an unexpected specialist boundary
+
+1. Run `/vm identity status` and check both the configured persona and any
+   reported environment overrides.
+2. If an environment override is present, exit Pi, unset
+   `VAULT_MIND_AGENT_ROLE` and `VAULT_MIND_IDENTITY_INJECTION`, then relaunch.
+3. Run `/vm identity set main`, followed by `/vm identity off`.
+4. Send the next agent turn and re-run `/vm identity status`; boundary changes
+   take effect on the next turn.
+5. Confirm Pi was started for the intended vault and uses
+   `<vault>/.vault-mind/.pi/agent/` as `PI_CODING_AGENT_DIR`.
+
+Do not edit `SYSTEM.md` or an agent skill to change the interactive identity.
+Those files provide operating instructions and resources; persona selection
+belongs in `vaultMind.identities` or an explicit environment override.
+
 ## Example domains
 
 ### Research project
@@ -356,6 +539,7 @@ Edit `<vault>/.vault-mind/vault-mind.config.json` to match your domain:
 | `/vm injector create`        | Interactive wizard to create a new injector                |
 | `/vm context enable \| disable \| status` | Manage pi-context integration              |
 | `/vm embedding status \| use \| model \| models \| pull` | Manage embedding provider |
+| `/vm identity status \| set <role> \| on \| off` | Inspect or explicitly control the interactive agent persona boundary |
 | `/vm remote status \| config \| sync \| jobs \| migrate` | Manage remote embedding + vector sync |
 | `/vm watcher start \| stop \| status` | Manage the passive file watcher                  |
 | `/vm server status` | Show HTTP server status, port, and uptime |

package/dist/src/commands.js

@@ -8,6 +8,8 @@ import { revokeToken, rotateToken } from "./auth.js";
 import { handleDiscoverSchema } from "./discover-schema.js";
 import { writeEnvEntry } from "./embedding-secrets.js";
 import { queryGraph } from "./graph.js";
+import { writeIdentitiesLayer } from "./identities-config.js";
+import { IDENTITY_BOUNDARY_ROLES, resolveIdentityBoundaryRole } from "./identity-injector.js";
 import { runAskIntake } from "./intake.js";
 import { connect, searchFts, searchHybrid, searchHybridRanked } from "./lance.js";
 import { createModalClient, isModalConfigured, MODAL_TOKEN_ENV, modalTokenEnvPath, resolveModalToken, } from "./modal-config.js";
@@ -39,6 +41,9 @@ const VM_USAGE = [
     "  /vm index [--all] [--reembed] [--remote]  Index collections (alias: reindex)",
     "  /vm discover-schema         Infer schema from a JSONL file",
     "  /vm injector create         Create a new injector (wizard)",
+    "  /vm identity status        Show configured and effective persona",
+    "  /vm identity set <role>    Set main|manager|miner|broadcaster|heavy-lifter",
+    "  /vm identity on|off        Enable or disable persona boundary injection",
     "  /vm context enable|disable  Enable/disable pi-context integration",
     "  /vm embedding status        Show embedding config",
     "  /vm remote status          Show remote provider config + health + collections",
@@ -1616,6 +1621,74 @@ const handleToken = (args, ctx) => {
             ctx.ui.notify(`Unknown: ${sub}. Try: show, rotate, revoke`, "error");
     }
 };
+const handleIdentity = (args, ctx) => {
+    const parts = args.trim().split(/\s+/g).filter(Boolean);
+    const subcommand = parts[0]?.toLowerCase() || "status";
+    const identities = loadConfig(ctx.cwd).vaultMind.identities;
+    const configuredRole = identities?.activeRole?.trim().toLowerCase() || "main";
+    const updateIdentity = (patch) => {
+        try {
+            writeIdentitiesLayer(ctx.cwd, patch);
+            return true;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.ui.notify(`Failed to update identity config: ${message}`, "error");
+            return false;
+        }
+    };
+    switch (subcommand) {
+        case "status": {
+            const effectiveRole = resolveIdentityBoundaryRole(ctx.cwd);
+            const injectionEnabled = identities?.injectBoundaries !== false;
+            const envRole = process.env.VAULT_MIND_AGENT_ROLE?.trim();
+            const envInjection = process.env.VAULT_MIND_IDENTITY_INJECTION?.trim();
+            ctx.ui.notify([
+                "**Identity Boundary**",
+                `Persona: ${configuredRole}`,
+                `Injection: ${injectionEnabled ? "enabled" : "disabled"}`,
+                `Effective boundary: ${effectiveRole ?? "none (main agent)"}`,
+                ...(envRole ? [`Environment role override: ${envRole}`] : []),
+                ...(envInjection ? [`Environment injection override: ${envInjection}`] : []),
+            ].join("\n"), "info");
+            return;
+        }
+        case "set": {
+            const role = parts[1]?.toLowerCase();
+            const validRole = role === "main" ||
+                (role !== undefined &&
+                    IDENTITY_BOUNDARY_ROLES.includes(role));
+            if (!role || !validRole) {
+                ctx.ui.notify(`Unknown persona: ${role ?? "(missing)"}. Use main, ${IDENTITY_BOUNDARY_ROLES.join(", ")}.`, "error");
+                return;
+            }
+            if (!updateIdentity({
+                activeRole: role,
+                injectBoundaries: true,
+            })) {
+                return;
+            }
+            ctx.ui.notify(`Persona set to ${role}. The boundary applies on the next agent turn.`, "info");
+            return;
+        }
+        case "off":
+        case "disable": {
+            if (!updateIdentity({ injectBoundaries: false }))
+                return;
+            ctx.ui.notify("Identity injection disabled. The main agent remains unrestricted.", "info");
+            return;
+        }
+        case "on":
+        case "enable": {
+            if (!updateIdentity({ injectBoundaries: true }))
+                return;
+            ctx.ui.notify(`Identity injection enabled for ${configuredRole}. The setting applies on the next agent turn.`, "info");
+            return;
+        }
+        default:
+            ctx.ui.notify("Usage: /vm identity status | set <role> | on | off", "error");
+    }
+};
 // ── Main /vm command ───────────────────────────────────────────────────────
 export const registerCommands = (pi) => {
     pi.registerCommand("vm", {
@@ -1633,6 +1706,7 @@ export const registerCommands = (pi) => {
                 "discover-schema",
                 "doctor",
                 "injector",
+                "identity",
                 "context",
                 "embedding",
                 "remote",
@@ -1662,6 +1736,11 @@ export const registerCommands = (pi) => {
                         .filter((c) => c.startsWith(prefix))
                         .map((c) => ({ label: c, value: c, description: `context ${c}` }));
                 }
+                if (subcommand === "identity") {
+                    return ["status", "set", "on", "off", "main", ...IDENTITY_BOUNDARY_ROLES]
+                        .filter((c) => c.startsWith(prefix))
+                        .map((c) => ({ label: c, value: c, description: `identity ${c}` }));
+                }
                 if (subcommand === "discover-schema") {
                     return ["--name", "--sample"]
                         .filter((c) => c.startsWith(prefix))
@@ -1736,6 +1815,8 @@ export const registerCommands = (pi) => {
                     return handleCollection(rest, ctx, pi);
                 case "injector":
                     return handleInjector(rest, ctx);
+                case "identity":
+                    return handleIdentity(rest, ctx);
                 case "context":
                     return handleContext(rest, ctx, pi);
                 case "embedding":

package/dist/src/identities-config.js

@@ -26,11 +26,27 @@ function deepMerge(base, overlay) {
  */
 export function writeIdentitiesLayer(cwd, identities) {
     const configPath = getConfigPath(cwd);
-    const existing = fs.existsSync(configPath)
-        ? JSON.parse(fs.readFileSync(configPath, "utf-8"))
-        : {};
+    let existing = {};
+    if (fs.existsSync(configPath)) {
+        const raw = fs.readFileSync(configPath, "utf-8");
+        try {
+            const parsed = JSON.parse(raw);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                throw new TypeError("the root value must be a JSON object");
+            }
+            existing = parsed;
+        }
+        catch (error) {
+            throw new Error(`Invalid JSON in ${configPath}; the file was not changed.`, {
+                cause: error,
+            });
+        }
+    }
     const vaultMind = existing.vaultMind || {};
-    vaultMind.identities = deepMerge(vaultMind.identities || {}, identities);
+    const legacyIdentities = existing.identities || {};
+    const canonicalIdentities = vaultMind.identities || {};
+    vaultMind.identities = deepMerge(deepMerge(legacyIdentities, canonicalIdentities), identities);
+    delete existing.identities;
     existing.vaultMind = vaultMind;
     const dir = path.dirname(configPath);
     if (!fs.existsSync(dir))

package/dist/src/identity-injector.d.ts

@@ -6,10 +6,21 @@
  * from pi-guideline-loader (kylebrodeur/pi-guideline-loader, MIT).
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export declare const IDENTITY_BOUNDARY_ROLES: readonly ["heavy-lifter", "miner", "broadcaster", "manager"];
+export type IdentityBoundaryRole = (typeof IDENTITY_BOUNDARY_ROLES)[number];
+/**
+ * Resolve an explicitly selected specialist persona.
+ *
+ * Specialist skills are ambient resources in every pi session, so their
+ * presence must never select a persona. The environment can override the
+ * vault-local config for launcher/fork use. Unset, "main", "none", and invalid
+ * roles all keep the unrestricted interactive main agent.
+ */
+export declare function resolveIdentityBoundaryRole(cwd: string, env?: NodeJS.ProcessEnv): IdentityBoundaryRole | undefined;
 /**
  * Register the identity injector on a pi ExtensionAPI.
  *
- * On every before_agent_start event, detects the current role and injects
- * the corresponding boundary prompt into the system prompt.
+ * On every before_agent_start event, injects a boundary only when a specialist
+ * persona was selected explicitly through environment or vault config.
  */
 export declare function registerIdentityInjector(pi: ExtensionAPI): void;

package/dist/src/identity-injector.js

@@ -5,7 +5,9 @@
  * per role stating capability boundaries as a contract. Pattern adapted
  * from pi-guideline-loader (kylebrodeur/pi-guideline-loader, MIT).
  */
+import { loadConfig } from "./utils.js";
 // ── Per-role boundary prompts ────────────────────────────────────────────────
+export const IDENTITY_BOUNDARY_ROLES = ["heavy-lifter", "miner", "broadcaster", "manager"];
 const BOUNDARY_PROMPTS = {
     "heavy-lifter": [
         "--- IDENTITY BOUNDARY: Heavy-Lifter ---",
@@ -50,46 +52,58 @@ const BOUNDARY_PROMPTS = {
         "------------------------------------------",
     ].join("\n"),
 };
-// ── Role detection ────────────────────────────────────────────────────────────
+// ── Role resolution ──────────────────────────────────────────────────────────
+const DISABLED_SWITCH_VALUES = {
+    "0": true,
+    false: true,
+    no: true,
+    off: true,
+    disabled: true,
+};
+const ENABLED_SWITCH_VALUES = {
+    "1": true,
+    true: true,
+    yes: true,
+    on: true,
+    enabled: true,
+};
 /**
- * Detect the current agent's role from a before_agent_start event.
- *
- * PRIMARY signal — event.systemPromptOptions.skills:
- *   pi loads `--agent vault-mind-{role}` as a named Skill (Skill.name == "vault-mind-{role}").
- *   Exact name match is structural and immune to prose false-positives.
- *
- * FALLBACK signal — system prompt XML:
- *   Only when no matching skill is present. Matches only the machine-generated
- *   `<name>vault-mind-{role}</name>` element emitted by formatSkillsForPrompt()
- *   inside <available_skills> — not any free-text prose mention of the role name.
+ * Resolve an explicitly selected specialist persona.
  *
- * Returns undefined for any non-vault-mind session; no injection occurs.
+ * Specialist skills are ambient resources in every pi session, so their
+ * presence must never select a persona. The environment can override the
+ * vault-local config for launcher/fork use. Unset, "main", "none", and invalid
+ * roles all keep the unrestricted interactive main agent.
  */
-function detectRole(event) {
-    // PRIMARY: exact skill name match — most reliable, no prose false-positive risk.
-    const skills = event.systemPromptOptions.skills;
-    if (skills) {
-        for (const skill of skills) {
-            const m = skill.name.match(/^vault-mind-(heavy-lifter|miner|broadcaster|manager)$/i);
-            if (m)
-                return m[1].toLowerCase();
-        }
+export function resolveIdentityBoundaryRole(cwd, env = process.env) {
+    const identities = loadConfig(cwd).vaultMind.identities;
+    const injectionOverride = env.VAULT_MIND_IDENTITY_INJECTION?.trim().toLowerCase();
+    if (injectionOverride && DISABLED_SWITCH_VALUES[injectionOverride])
+        return;
+    if ((!injectionOverride || !ENABLED_SWITCH_VALUES[injectionOverride]) &&
+        identities?.injectBoundaries === false) {
+        return;
     }
-    // FALLBACK: only the assembled system prompt is available — match the XML
-    // <name> token produced by formatSkillsForPrompt(), not free prose.
-    const m = event.systemPrompt.match(/<name>vault-mind-(heavy-lifter|miner|broadcaster|manager)<\/name>/i);
-    return m?.[1]?.toLowerCase();
+    const rawRole = Object.hasOwn(env, "VAULT_MIND_AGENT_ROLE")
+        ? env.VAULT_MIND_AGENT_ROLE
+        : identities?.activeRole;
+    const role = rawRole?.trim().toLowerCase();
+    if (!role || role === "main" || role === "none")
+        return;
+    if (!Object.hasOwn(BOUNDARY_PROMPTS, role))
+        return;
+    return role;
 }
 // ── Injector ──────────────────────────────────────────────────────────────────
 /**
  * Register the identity injector on a pi ExtensionAPI.
  *
- * On every before_agent_start event, detects the current role and injects
- * the corresponding boundary prompt into the system prompt.
+ * On every before_agent_start event, injects a boundary only when a specialist
+ * persona was selected explicitly through environment or vault config.
  */
 export function registerIdentityInjector(pi) {
     pi.on("before_agent_start", async (event) => {
-        const role = detectRole(event);
+        const role = resolveIdentityBoundaryRole(event.systemPromptOptions.cwd);
         if (!role)
             return;
         const boundaryPrompt = BOUNDARY_PROMPTS[role];

package/dist/src/scaffold.js

@@ -135,37 +135,37 @@ export const scaffoldVaultConfig = (vaultPath, collectionOverride) => {
             version: 2,
             collections: defaultCollections,
             injectors: defaultInjectors,
-            identities: {
-                roles: {
-                    main: {
-                        allowedTools: [
-                            "read",
-                            "write",
-                            "edit",
-                            "bash",
-                            "grep",
-                            "find",
-                            "ls",
-                            "vm_search",
-                            "vm_query",
-                            "vm_append",
-                            "vm_stats",
-                            "vm_status",
-                            "vm_describe",
-                            "vm_configure",
-                            "vault_read",
-                            "vault_search",
-                            "vault_list",
-                            "vault_tags",
-                            "vm_backlinks",
-                            "vm_related",
-                            "vm_broken_links",
-                            "vm_codegraph_impact",
-                        ],
+            vaultMind: {
+                identities: {
+                    roles: {
+                        main: {
+                            allowedTools: [
+                                "read",
+                                "write",
+                                "edit",
+                                "bash",
+                                "grep",
+                                "find",
+                                "ls",
+                                "vm_search",
+                                "vm_query",
+                                "vm_append",
+                                "vm_stats",
+                                "vm_status",
+                                "vm_describe",
+                                "vm_configure",
+                                "vault_read",
+                                "vault_search",
+                                "vault_list",
+                                "vault_tags",
+                                "vm_backlinks",
+                                "vm_related",
+                                "vm_broken_links",
+                                "vm_codegraph_impact",
+                            ],
+                        },
                     },
                 },
-            },
-            vaultMind: {
                 dataDir: ".vault-mind/.lancedb",
                 ftsEnabled: true,
                 graph: { enabled: true, canvasSync: false },

package/dist/src/server.js

@@ -832,19 +832,28 @@ export function startServer(pi, serverState, watcherState, readinessCallback) {
                         if (parts.length === 5) {
                             const role = parts[3];
                             withAuth(req, res, async () => {
-                                const body = (await readJsonBody(req));
-                                if (!body.allowedTools || !Array.isArray(body.allowedTools)) {
-                                    res.writeHead(400, { "Content-Type": "application/json" });
-                                    res.end(JSON.stringify({ error: "Missing allowedTools array in request body" }));
-                                    return;
+                                try {
+                                    const body = (await readJsonBody(req));
+                                    if (!body.allowedTools || !Array.isArray(body.allowedTools)) {
+                                        res.writeHead(400, { "Content-Type": "application/json" });
+                                        res.end(JSON.stringify({ error: "Missing allowedTools array in request body" }));
+                                        return;
+                                    }
+                                    // writeIdentitiesLayer deep-merges; pass a partial role config
+                                    writeIdentitiesLayer(process.cwd(), {
+                                        roles: { [role]: { allowedTools: body.allowedTools } },
+                                    });
+                                    refreshAgentIdentities([role]);
+                                    res.writeHead(200, { "Content-Type": "application/json" });
+                                    res.end(JSON.stringify({ ok: true, role, allowedTools: body.allowedTools }));
+                                }
+                                catch (error) {
+                                    const message = error instanceof Error ? error.message : String(error);
+                                    res.writeHead(500, { "Content-Type": "application/json" });
+                                    res.end(JSON.stringify({
+                                        error: `Failed to update identity config: ${message}`,
+                                    }));
                                 }
-                                // writeIdentitiesLayer deep-merges; pass a partial role config
-                                writeIdentitiesLayer(process.cwd(), {
-                                    roles: { [role]: { allowedTools: body.allowedTools } },
-                                });
-                                refreshAgentIdentities([role]);
-                                res.writeHead(200, { "Content-Type": "application/json" });
-                                res.end(JSON.stringify({ ok: true, role, allowedTools: body.allowedTools }));
                             }, { requireWrite: true });
                         }
                         else {

package/dist/src/types.d.ts

@@ -203,6 +203,10 @@ export interface VaultMindConfig {
         defaultProfile?: IdentityConfig;
         /** Per-role overrides. */
         roles?: Record<string, IdentityConfig>;
+        /** Master switch for system-prompt identity-boundary injection. */
+        injectBoundaries?: boolean;
+        /** Explicit persona to inject; unset, "main", or "none" keeps the main agent. */
+        activeRole?: string;
     };
     /**
      * Vault folder layout overrides. Each path is vault-relative and joined to
@@ -235,6 +239,10 @@ export interface IdentitiesConfig {
     defaultProfile?: IdentityConfig;
     /** Per-role overrides. */
     roles?: Record<string, IdentityConfig>;
+    /** Master switch for system-prompt identity-boundary injection. */
+    injectBoundaries?: boolean;
+    /** Explicit persona to inject; unset, "main", or "none" keeps the main agent. */
+    activeRole?: string;
 }
 export interface PiContextDef {
     enabled?: boolean;