@parall/claude-agent 1.42.1 → 1.43.0

package/dist/dispatch.d.ts

@@ -18,11 +18,20 @@ type ClaudeCodeAdapterOptions = Pick<ClaudeAgentConfig, 'additionalDirs' | 'allo
      * resolve no_action instead of reply-effect dedupe).
      */
     contextDirPath?: string;
+    /**
+     * Channel-capability shim directory (agent-core's capabilityBinDir),
+     * prepended to the subprocess PATH unconditionally. The DIRECTORY is
+     * constant for the bridge's lifetime; its CONTENT tracks capability
+     * grants, so a grant or revocation reaches even a long-lived claude
+     * subprocess on its next shell command — no respawn needed.
+     */
+    capabilityBinDir?: string;
 };
 export declare function buildSpawnEnv(parentEnv: NodeJS.ProcessEnv, claudeHome: string, context: DispatchOpts['context'], opts: {
     allowApiKey: boolean;
     effortLevel?: string;
     wikiMountRoot?: string;
+    capabilityBinDir?: string;
 }): NodeJS.ProcessEnv;
 export declare class ClaudeCodeAdapter implements DispatchAdapter {
     private readonly opts;
@@ -38,6 +47,7 @@ export declare class ClaudeCodeAdapter implements DispatchAdapter {
         model?: string | null;
         effort?: string | null;
     }): void;
+    requestProcessRestart(): void;
     enqueueDuringDispatch(sessionKey: string, body: string): boolean;
     abortDispatch(sessionKey: string): void;
     hasPendingInjections(sessionKey: string): boolean;

package/dist/dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"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"}

package/dist/dispatch.js

@@ -52,6 +52,23 @@ export function buildSpawnEnv(parentEnv, claudeHome, context, opts) {
     if (opts.effortLevel) {
         result.CLAUDE_CODE_EFFORT_LEVEL = opts.effortLevel;
     }
+    // Channel-capability shims resolve ahead of any globally-installed CLI of
+    // the same name (the shim owns auth; the real binary is found further down
+    // the PATH by the shim itself). On Windows env keys are case-insensitive and
+    // the host key is usually `Path`; after the plain-object spread a literal
+    // `PATH` write would SPLIT the key (undefined which wins in the child), so
+    // reuse the parent's casing. On POSIX keys are case-SENSITIVE — `PATH` is
+    // the real one and a stray `Path` is unrelated, so match exactly there or we
+    // could prepend to the wrong variable and silently bypass the shim.
+    if (opts.capabilityBinDir) {
+        const pathKey = process.platform === 'win32'
+            ? (Object.keys(result).find((k) => k.toUpperCase() === 'PATH') ?? 'PATH')
+            : 'PATH';
+        const existing = result[pathKey];
+        result[pathKey] = existing
+            ? `${opts.capabilityBinDir}${path.delimiter}${existing}`
+            : opts.capabilityBinDir;
+    }
     return result;
 }
 export class ClaudeCodeAdapter {
@@ -79,9 +96,18 @@ export class ClaudeCodeAdapter {
         if (effortChanged)
             this._effortLevel = config.effort ?? undefined;
         if (modelChanged || effortChanged) {
-            for (const [, state] of this.processes) {
-                state.needsRestart = true;
-            }
+            this.requestProcessRestart();
+        }
+    }
+    // Mark every live subprocess for a lazy respawn (applied at its next
+    // dispatch; the session survives via --resume) — the same mechanism
+    // updateConfig uses for model/effort changes. For spawn-time inputs that
+    // live OUTSIDE this adapter's config, e.g. the .parall/system-prompt.md
+    // file: a long-lived process read it via --append-system-prompt-file at
+    // spawn, so a capability declaration change only reaches it by respawning.
+    requestProcessRestart() {
+        for (const [, state] of this.processes) {
+            state.needsRestart = true;
         }
     }
     enqueueDuringDispatch(sessionKey, body) {
@@ -389,6 +415,7 @@ export class ClaudeCodeAdapter {
             allowApiKey: this.opts.allowApiKey,
             effortLevel: this._effortLevel,
             wikiMountRoot: this.opts.workspaceDir,
+            capabilityBinDir: this.opts.capabilityBinDir,
         });
         log?.info(`spawn long-lived ${this.opts.claudeBin} (session ${sessionKey}, model=${this._model || 'default'}, effort=${this._effortLevel || 'default'}, mode=${this.opts.permissionMode})`);
         const proc = spawn(IS_WIN32 ? quoteWin32Arg(this.opts.claudeBin) : this.opts.claudeBin, IS_WIN32 ? args.map(quoteWin32Arg) : args, {

package/dist/index.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import * as os from 'node:os';
-import { ParallAgentGateway, createPlatformConfigManager, createLogger, createOtelLogger, childLogger, deriveModelIsPin, resolveRuntimeModel, parseShutdownDeadlineMs, parseForkDeadlineMs, parseDispatchDeadlineMs, parseProviderConfig, clearAllProviderCreds, llmSource, initAgentTelemetry, } from '@parall/agent-core';
+import { ParallAgentGateway, capabilityBinDir, createPlatformConfigManager, createLogger, createOtelLogger, childLogger, deriveModelIsPin, materializeChannelCapabilities, resolveRuntimeModel, parseShutdownDeadlineMs, parseForkDeadlineMs, parseDispatchDeadlineMs, parseProviderConfig, clearAllProviderCreds, llmSource, initAgentTelemetry, } from '@parall/agent-core';
 import { ApiError, ParallClient, ParallWs } from '@parall/sdk';
 import { buildClaudeRuntimeKey, contextFilePathForSession, dispatchContextDirPath, resolveClaudeAgentConfig, resolveWsUrl, sessionStateFilePathForRuntime, stepIdFilePathForSession, } from './config.js';
 import { ClaudeCodeAdapter } from './dispatch.js';
 import { ClaudeSessionManager } from './session-manager.js';
-import { ensureClaudeWorkspace } from './workspace.js';
+import { ensureClaudeWorkspace, writeClaudeSystemPrompt } from './workspace.js';
 const log = createLogger('claude-agent');
 let activeLog = log;
 async function getAgentMeWithLegacyFallback(client, orgId) {
@@ -61,11 +61,13 @@ async function main() {
         const agentUserId = me.id;
         const agentLog = childLogger(activeLog, agentUserId);
         activeLog = agentLog;
-        ensureClaudeWorkspace(config.workspaceDir, agentLog, {
+        // Shared by the initial workspace write and the config-refresh rewrite of
+        // .parall/system-prompt.md — both need identity + capability fragments.
+        const agentIdentity = {
             userId: agentUserId,
             displayName: me.display_name,
             description: me.agent_profile?.description ?? undefined,
-        });
+        };
         const runtimeKey = config.runtimeKey || buildClaudeRuntimeKey(agentUserId);
         const sessionStateFilePath = sessionStateFilePathForRuntime(config.stateDir, runtimeKey);
         const sessionManager = new ClaudeSessionManager(runtimeKey, sessionStateFilePath, agentLog);
@@ -81,6 +83,22 @@ async function main() {
             log: agentLog,
         });
         const platformDefaults = await configMgr.fetch();
+        // Channel capabilities: ONE call materializes the local artifacts (the
+        // lark-cli auth shim under capabilityBinDir) and yields the system-prompt
+        // fragments, so declaration and shim can never diverge within a refresh.
+        // No freshness gate — a stale (LKG-cached) declaration fail-closes at the
+        // mint endpoint, which re-evaluates the grant on every token request.
+        const applyChannelCapabilities = () => {
+            const caps = configMgr.capabilities();
+            materializeChannelCapabilities(config.stateDir, caps, agentLog);
+            return caps.map((c) => c.fragment);
+        };
+        // Assemble the workspace AFTER the first config fetch so system-prompt.md
+        // carries the capability declarations from boot (not just from the first
+        // heat-update).
+        const bootCapabilityFragments = applyChannelCapabilities();
+        let lastCapabilityFragments = bootCapabilityFragments.join('\n\n');
+        ensureClaudeWorkspace(config.workspaceDir, agentLog, agentIdentity, bootCapabilityFragments);
         // Model precedence: operator PIN (override) > env > server FLOOR. The server
         // now says which it is via model_is_pin (deriveModelIsPin presence-gates the
         // dual-read: old servers omit it → fall back to model_management). A PIN beats
@@ -115,6 +133,9 @@ async function main() {
             contextFilePathForSession: (sessionKey) => contextFilePathForSession(config.stateDir, sessionKey),
             stepIdFilePathForSession: (sessionKey) => stepIdFilePathForSession(config.stateDir, sessionKey),
             contextDirPath: dispatchContextDirPath(config.stateDir),
+            // Constant PATH prepend; the directory's content (the lark-cli shim)
+            // tracks capability grants, so add/remove reaches live subprocesses.
+            capabilityBinDir: capabilityBinDir(config.stateDir),
         });
         if (resolvedEffort) {
             adapter.updateConfig({ effort: resolvedEffort });
@@ -144,6 +165,39 @@ async function main() {
                 model: resolveRuntimeModel(isPin, updated.model, config.model) ?? null,
                 effort: updated.thinkingEffort ?? localEffort,
             });
+            // Channel capabilities heat-update with the config: re-materialize the
+            // shim and rewrite the standing system prompt on EVERY refresh. The
+            // rewrite is unconditional on purpose — it is self-healing: the prompt
+            // file lives in the agent-writable workspace, so a subprocess or its
+            // tools can delete or tamper with it, and rewriting each refresh/reconnect
+            // restores the authoritative copy (do NOT gate this on a fragment change).
+            // Revocation keeps the constant pointer in place (no deny stub, no local
+            // token cache): the mint endpoint's 403 IS the revocation, nothing local
+            // to purge. The shim swap reaches even live long-lived subprocesses
+            // immediately (PATH re-resolves per command), but the system prompt was
+            // loaded at spawn — so a CHANGED declaration also marks live processes for
+            // a lazy --resume respawn, the same mechanism model changes use.
+            const fragments = applyChannelCapabilities();
+            const joinedFragments = fragments.join('\n\n');
+            // Refresh path: TOLERATE a prompt-write failure (boot is fatal instead) —
+            // a transient failure must not break the whole config heat-update. But do
+            // NOT advance the snapshot / restart unless the write actually LANDED:
+            // otherwise a later successful retry sees "no change" and never restarts
+            // the long-lived Claude subprocess, stranding it on the stale prompt. The
+            // rewrite is self-healing; leaving the snapshot put makes the next refresh
+            // retry and, on success, restart.
+            let promptWritten = true;
+            try {
+                writeClaudeSystemPrompt(config.workspaceDir, agentIdentity, fragments);
+            }
+            catch (err) {
+                promptWritten = false;
+                agentLog.warn(`system prompt refresh write failed (retrying next refresh): ${String(err)}`);
+            }
+            if (promptWritten && joinedFragments !== lastCapabilityFragments) {
+                lastCapabilityFragments = joinedFragments;
+                adapter.requestProcessRestart();
+            }
         };
         const gateway = new ParallAgentGateway({
             accountId: agentUserId,
@@ -166,6 +220,11 @@ async function main() {
             },
             dispatchAdapter: adapter,
             log: agentLog,
+            // Live capability view for hint routing: the channel reply hint points
+            // at the vendor CLI only while the grant is active (config manager
+            // re-fetches on agent_config.update, so revocation reaches the very
+            // next dispatch's hint).
+            getCapabilityKeys: () => configMgr.capabilities().map((c) => c.key),
             shutdownDeadlineMs: parseShutdownDeadlineMs(process.env.PRLL_SHUTDOWN_DEADLINE_MS),
             forkDeadlineMs: parseForkDeadlineMs(process.env.PRLL_FORK_DEADLINE_MS),
             dispatchDeadlineMs: parseDispatchDeadlineMs(process.env.PRLL_DISPATCH_DEADLINE_MS),

package/dist/workspace.d.ts

@@ -1,5 +1,6 @@
 import type { AgentIdentity } from '@parall/agent-core';
+export declare function writeClaudeSystemPrompt(workspaceDir: string, agentIdentity?: AgentIdentity, capabilityFragments?: string[]): void;
 export declare function ensureClaudeWorkspace(workspaceDir: string, log?: {
     warn: (msg: string) => void;
-}, agentIdentity?: AgentIdentity): void;
+}, agentIdentity?: AgentIdentity, capabilityFragments?: string[]): void;
 //# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,EACrC,aAAa,CAAC,EAAE,aAAa,QAmB9B"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AA8BxD,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,aAAa,CAAC,EAAE,aAAa,EAC7B,mBAAmB,CAAC,EAAE,MAAM,EAAE,QAgB/B;AAED,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,EACrC,aAAa,CAAC,EAAE,aAAa,EAC7B,mBAAmB,CAAC,EAAE,MAAM,EAAE,QAW/B"}

package/dist/workspace.js

@@ -2,19 +2,46 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { BRIDGE_WORKSPACE_INSTRUCTIONS, PRLL_BEHAVIOR, PRLL_REFERENCE_GUIDE, buildIdentity, buildSkillReferences, writeSkillFiles, } from '@parall/agent-core';
 import { ensureLocalAttachmentGitExclude } from '@parall/agent-core/internal/attachment-input';
-export function ensureClaudeWorkspace(workspaceDir, log, agentIdentity) {
-    const systemPrompt = [
+// buildClaudeSystemPrompt assembles the standing system prompt. capabilityFragments
+// are platform-derived capability declarations (agents.capabilities[].fragment
+// from platform-config) — placed after the platform reference guide, before
+// skill references. Empty/absent = no capability section.
+function buildClaudeSystemPrompt(workspaceDir, agentIdentity, capabilityFragments) {
+    const parts = [
         buildIdentity(agentIdentity),
         BRIDGE_WORKSPACE_INSTRUCTIONS,
         PRLL_BEHAVIOR,
         PRLL_REFERENCE_GUIDE,
-        buildSkillReferences(workspaceDir),
-    ].join('\n\n');
-    fs.mkdirSync(workspaceDir, { recursive: true });
-    fs.mkdirSync(path.join(workspaceDir, '.claude'), { recursive: true });
+    ];
+    if (capabilityFragments && capabilityFragments.length > 0) {
+        parts.push(capabilityFragments.join('\n\n'));
+    }
+    parts.push(buildSkillReferences(workspaceDir));
+    return parts.join('\n\n');
+}
+// writeClaudeSystemPrompt (re)writes .parall/system-prompt.md. Split out from
+// ensureClaudeWorkspace so the bridge can rewrite it when platform-config
+// capabilities heat-update — the file is read via --append-system-prompt-file
+// on every claude spawn, so a rewrite reaches the next turn without a
+// workspace rebuild.
+export function writeClaudeSystemPrompt(workspaceDir, agentIdentity, capabilityFragments) {
+    // Throws on failure BY DESIGN — tolerance is a property of the CALLER, not
+    // this function. At boot (ensureClaudeWorkspace) the prompt is mandatory
+    // (every claude spawn passes it via --append-system-prompt-file), so a write
+    // failure must fail startup loudly for recovery, not degrade to an agent
+    // running without its platform instructions. The refresh hot path (index.ts)
+    // wraps this in try/catch instead, so a transient failure there degrades to a
+    // warning and the next refresh retries (the rewrite is self-healing).
     const parallDir = path.join(workspaceDir, '.parall');
     fs.mkdirSync(parallDir, { recursive: true });
-    fs.writeFileSync(path.join(parallDir, 'system-prompt.md'), systemPrompt, 'utf8');
-    writeSkillFiles(path.join(parallDir, 'skills'));
+    fs.writeFileSync(path.join(parallDir, 'system-prompt.md'), buildClaudeSystemPrompt(workspaceDir, agentIdentity, capabilityFragments), 'utf8');
+}
+export function ensureClaudeWorkspace(workspaceDir, log, agentIdentity, capabilityFragments) {
+    fs.mkdirSync(workspaceDir, { recursive: true });
+    fs.mkdirSync(path.join(workspaceDir, '.claude'), { recursive: true });
+    // Boot: let a write failure PROPAGATE (fatal) — startup must not proceed
+    // without the mandatory system prompt. The refresh path tolerates failure.
+    writeClaudeSystemPrompt(workspaceDir, agentIdentity, capabilityFragments);
+    writeSkillFiles(path.join(workspaceDir, '.parall', 'skills'));
     ensureLocalAttachmentGitExclude(workspaceDir);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/claude-agent",
-  "version": "1.42.1",
+  "version": "1.43.0",
   "description": "Claude Code bridge runtime for self-hosted Parall agents",
   "license": "MIT",
   "repository": {
@@ -25,9 +25,9 @@
     "src"
   ],
   "dependencies": {
-    "@parall/cli": "1.42.1",
-    "@parall/sdk": "1.42.1",
-    "@parall/agent-core": "1.42.1"
+    "@parall/agent-core": "1.43.0",
+    "@parall/sdk": "1.43.0",
+    "@parall/cli": "1.43.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/dispatch.ts

@@ -47,6 +47,14 @@ type ClaudeCodeAdapterOptions = Pick<
    * resolve no_action instead of reply-effect dedupe).
    */
   contextDirPath?: string;
+  /**
+   * Channel-capability shim directory (agent-core's capabilityBinDir),
+   * prepended to the subprocess PATH unconditionally. The DIRECTORY is
+   * constant for the bridge's lifetime; its CONTENT tracks capability
+   * grants, so a grant or revocation reaches even a long-lived claude
+   * subprocess on its next shell command — no respawn needed.
+   */
+  capabilityBinDir?: string;
 };
 
 const IS_WIN32 = process.platform === 'win32';
@@ -69,7 +77,12 @@ export function buildSpawnEnv(
   parentEnv: NodeJS.ProcessEnv,
   claudeHome: string,
   context: DispatchOpts['context'],
-  opts: { allowApiKey: boolean; effortLevel?: string; wikiMountRoot?: string },
+  opts: {
+    allowApiKey: boolean;
+    effortLevel?: string;
+    wikiMountRoot?: string;
+    capabilityBinDir?: string;
+  },
 ): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = { ...parentEnv };
   if (!opts.allowApiKey) {
@@ -103,6 +116,24 @@ export function buildSpawnEnv(
   if (opts.effortLevel) {
     result.CLAUDE_CODE_EFFORT_LEVEL = opts.effortLevel;
   }
+  // Channel-capability shims resolve ahead of any globally-installed CLI of
+  // the same name (the shim owns auth; the real binary is found further down
+  // the PATH by the shim itself). On Windows env keys are case-insensitive and
+  // the host key is usually `Path`; after the plain-object spread a literal
+  // `PATH` write would SPLIT the key (undefined which wins in the child), so
+  // reuse the parent's casing. On POSIX keys are case-SENSITIVE — `PATH` is
+  // the real one and a stray `Path` is unrelated, so match exactly there or we
+  // could prepend to the wrong variable and silently bypass the shim.
+  if (opts.capabilityBinDir) {
+    const pathKey =
+      process.platform === 'win32'
+        ? (Object.keys(result).find((k) => k.toUpperCase() === 'PATH') ?? 'PATH')
+        : 'PATH';
+    const existing = result[pathKey];
+    result[pathKey] = existing
+      ? `${opts.capabilityBinDir}${path.delimiter}${existing}`
+      : opts.capabilityBinDir;
+  }
   return result;
 }
 
@@ -145,9 +176,19 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
     if (modelChanged) this._model = config.model ?? undefined;
     if (effortChanged) this._effortLevel = config.effort ?? undefined;
     if (modelChanged || effortChanged) {
-      for (const [, state] of this.processes) {
-        state.needsRestart = true;
-      }
+      this.requestProcessRestart();
+    }
+  }
+
+  // Mark every live subprocess for a lazy respawn (applied at its next
+  // dispatch; the session survives via --resume) — the same mechanism
+  // updateConfig uses for model/effort changes. For spawn-time inputs that
+  // live OUTSIDE this adapter's config, e.g. the .parall/system-prompt.md
+  // file: a long-lived process read it via --append-system-prompt-file at
+  // spawn, so a capability declaration change only reaches it by respawning.
+  requestProcessRestart(): void {
+    for (const [, state] of this.processes) {
+      state.needsRestart = true;
     }
   }
 
@@ -493,6 +534,7 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
         allowApiKey: this.opts.allowApiKey,
         effortLevel: this._effortLevel,
         wikiMountRoot: this.opts.workspaceDir,
+        capabilityBinDir: this.opts.capabilityBinDir,
       },
     );
 

package/src/index.ts

@@ -3,11 +3,13 @@
 import * as os from 'node:os';
 import {
   ParallAgentGateway,
+  capabilityBinDir,
   createPlatformConfigManager,
   createLogger,
   createOtelLogger,
   childLogger,
   deriveModelIsPin,
+  materializeChannelCapabilities,
   resolveRuntimeModel,
   parseShutdownDeadlineMs,
   parseForkDeadlineMs,
@@ -29,7 +31,7 @@ import {
 } from './config.js';
 import { ClaudeCodeAdapter } from './dispatch.js';
 import { ClaudeSessionManager } from './session-manager.js';
-import { ensureClaudeWorkspace } from './workspace.js';
+import { ensureClaudeWorkspace, writeClaudeSystemPrompt } from './workspace.js';
 
 const log = createLogger('claude-agent');
 let activeLog = log;
@@ -90,11 +92,13 @@ async function main() {
     const agentUserId = me.id;
     const agentLog = childLogger(activeLog, agentUserId);
     activeLog = agentLog;
-    ensureClaudeWorkspace(config.workspaceDir, agentLog, {
+    // Shared by the initial workspace write and the config-refresh rewrite of
+    // .parall/system-prompt.md — both need identity + capability fragments.
+    const agentIdentity = {
       userId: agentUserId,
       displayName: me.display_name,
       description: me.agent_profile?.description ?? undefined,
-    });
+    };
     const runtimeKey = config.runtimeKey || buildClaudeRuntimeKey(agentUserId);
     const sessionStateFilePath = sessionStateFilePathForRuntime(config.stateDir, runtimeKey);
     const sessionManager = new ClaudeSessionManager(runtimeKey, sessionStateFilePath, agentLog);
@@ -112,6 +116,22 @@ async function main() {
       log: agentLog,
     });
     const platformDefaults = await configMgr.fetch();
+    // Channel capabilities: ONE call materializes the local artifacts (the
+    // lark-cli auth shim under capabilityBinDir) and yields the system-prompt
+    // fragments, so declaration and shim can never diverge within a refresh.
+    // No freshness gate — a stale (LKG-cached) declaration fail-closes at the
+    // mint endpoint, which re-evaluates the grant on every token request.
+    const applyChannelCapabilities = () => {
+      const caps = configMgr.capabilities();
+      materializeChannelCapabilities(config.stateDir, caps, agentLog);
+      return caps.map((c) => c.fragment);
+    };
+    // Assemble the workspace AFTER the first config fetch so system-prompt.md
+    // carries the capability declarations from boot (not just from the first
+    // heat-update).
+    const bootCapabilityFragments = applyChannelCapabilities();
+    let lastCapabilityFragments = bootCapabilityFragments.join('\n\n');
+    ensureClaudeWorkspace(config.workspaceDir, agentLog, agentIdentity, bootCapabilityFragments);
     // Model precedence: operator PIN (override) > env > server FLOOR. The server
     // now says which it is via model_is_pin (deriveModelIsPin presence-gates the
     // dual-read: old servers omit it → fall back to model_management). A PIN beats
@@ -156,6 +176,9 @@ async function main() {
       stepIdFilePathForSession: (sessionKey) =>
         stepIdFilePathForSession(config.stateDir, sessionKey),
       contextDirPath: dispatchContextDirPath(config.stateDir),
+      // Constant PATH prepend; the directory's content (the lark-cli shim)
+      // tracks capability grants, so add/remove reaches live subprocesses.
+      capabilityBinDir: capabilityBinDir(config.stateDir),
     });
     if (resolvedEffort) {
       adapter.updateConfig({ effort: resolvedEffort });
@@ -189,6 +212,38 @@ async function main() {
         model: resolveRuntimeModel(isPin, updated.model, config.model) ?? null,
         effort: updated.thinkingEffort ?? localEffort,
       });
+      // Channel capabilities heat-update with the config: re-materialize the
+      // shim and rewrite the standing system prompt on EVERY refresh. The
+      // rewrite is unconditional on purpose — it is self-healing: the prompt
+      // file lives in the agent-writable workspace, so a subprocess or its
+      // tools can delete or tamper with it, and rewriting each refresh/reconnect
+      // restores the authoritative copy (do NOT gate this on a fragment change).
+      // Revocation keeps the constant pointer in place (no deny stub, no local
+      // token cache): the mint endpoint's 403 IS the revocation, nothing local
+      // to purge. The shim swap reaches even live long-lived subprocesses
+      // immediately (PATH re-resolves per command), but the system prompt was
+      // loaded at spawn — so a CHANGED declaration also marks live processes for
+      // a lazy --resume respawn, the same mechanism model changes use.
+      const fragments = applyChannelCapabilities();
+      const joinedFragments = fragments.join('\n\n');
+      // Refresh path: TOLERATE a prompt-write failure (boot is fatal instead) —
+      // a transient failure must not break the whole config heat-update. But do
+      // NOT advance the snapshot / restart unless the write actually LANDED:
+      // otherwise a later successful retry sees "no change" and never restarts
+      // the long-lived Claude subprocess, stranding it on the stale prompt. The
+      // rewrite is self-healing; leaving the snapshot put makes the next refresh
+      // retry and, on success, restart.
+      let promptWritten = true;
+      try {
+        writeClaudeSystemPrompt(config.workspaceDir, agentIdentity, fragments);
+      } catch (err) {
+        promptWritten = false;
+        agentLog.warn(`system prompt refresh write failed (retrying next refresh): ${String(err)}`);
+      }
+      if (promptWritten && joinedFragments !== lastCapabilityFragments) {
+        lastCapabilityFragments = joinedFragments;
+        adapter.requestProcessRestart();
+      }
     };
 
     const gateway = new ParallAgentGateway({
@@ -212,6 +267,11 @@ async function main() {
       },
       dispatchAdapter: adapter,
       log: agentLog,
+      // Live capability view for hint routing: the channel reply hint points
+      // at the vendor CLI only while the grant is active (config manager
+      // re-fetches on agent_config.update, so revocation reaches the very
+      // next dispatch's hint).
+      getCapabilityKeys: () => configMgr.capabilities().map((c) => c.key),
       shutdownDeadlineMs: parseShutdownDeadlineMs(process.env.PRLL_SHUTDOWN_DEADLINE_MS),
       forkDeadlineMs: parseForkDeadlineMs(process.env.PRLL_FORK_DEADLINE_MS),
       dispatchDeadlineMs: parseDispatchDeadlineMs(process.env.PRLL_DISPATCH_DEADLINE_MS),

package/src/workspace.ts

@@ -11,26 +11,67 @@ import {
 import type { AgentIdentity } from '@parall/agent-core';
 import { ensureLocalAttachmentGitExclude } from '@parall/agent-core/internal/attachment-input';
 
-export function ensureClaudeWorkspace(
+// buildClaudeSystemPrompt assembles the standing system prompt. capabilityFragments
+// are platform-derived capability declarations (agents.capabilities[].fragment
+// from platform-config) — placed after the platform reference guide, before
+// skill references. Empty/absent = no capability section.
+function buildClaudeSystemPrompt(
   workspaceDir: string,
-  log?: { warn: (msg: string) => void },
   agentIdentity?: AgentIdentity,
-) {
-  const systemPrompt = [
+  capabilityFragments?: string[],
+): string {
+  const parts = [
     buildIdentity(agentIdentity),
     BRIDGE_WORKSPACE_INSTRUCTIONS,
     PRLL_BEHAVIOR,
     PRLL_REFERENCE_GUIDE,
-    buildSkillReferences(workspaceDir),
-  ].join('\n\n');
+  ];
+  if (capabilityFragments && capabilityFragments.length > 0) {
+    parts.push(capabilityFragments.join('\n\n'));
+  }
+  parts.push(buildSkillReferences(workspaceDir));
+  return parts.join('\n\n');
+}
+
+// writeClaudeSystemPrompt (re)writes .parall/system-prompt.md. Split out from
+// ensureClaudeWorkspace so the bridge can rewrite it when platform-config
+// capabilities heat-update — the file is read via --append-system-prompt-file
+// on every claude spawn, so a rewrite reaches the next turn without a
+// workspace rebuild.
+export function writeClaudeSystemPrompt(
+  workspaceDir: string,
+  agentIdentity?: AgentIdentity,
+  capabilityFragments?: string[],
+) {
+  // Throws on failure BY DESIGN — tolerance is a property of the CALLER, not
+  // this function. At boot (ensureClaudeWorkspace) the prompt is mandatory
+  // (every claude spawn passes it via --append-system-prompt-file), so a write
+  // failure must fail startup loudly for recovery, not degrade to an agent
+  // running without its platform instructions. The refresh hot path (index.ts)
+  // wraps this in try/catch instead, so a transient failure there degrades to a
+  // warning and the next refresh retries (the rewrite is self-healing).
+  const parallDir = path.join(workspaceDir, '.parall');
+  fs.mkdirSync(parallDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(parallDir, 'system-prompt.md'),
+    buildClaudeSystemPrompt(workspaceDir, agentIdentity, capabilityFragments),
+    'utf8',
+  );
+}
 
+export function ensureClaudeWorkspace(
+  workspaceDir: string,
+  log?: { warn: (msg: string) => void },
+  agentIdentity?: AgentIdentity,
+  capabilityFragments?: string[],
+) {
   fs.mkdirSync(workspaceDir, { recursive: true });
   fs.mkdirSync(path.join(workspaceDir, '.claude'), { recursive: true });
 
-  const parallDir = path.join(workspaceDir, '.parall');
-  fs.mkdirSync(parallDir, { recursive: true });
-  fs.writeFileSync(path.join(parallDir, 'system-prompt.md'), systemPrompt, 'utf8');
+  // Boot: let a write failure PROPAGATE (fatal) — startup must not proceed
+  // without the mandatory system prompt. The refresh path tolerates failure.
+  writeClaudeSystemPrompt(workspaceDir, agentIdentity, capabilityFragments);
 
-  writeSkillFiles(path.join(parallDir, 'skills'));
+  writeSkillFiles(path.join(workspaceDir, '.parall', 'skills'));
   ensureLocalAttachmentGitExclude(workspaceDir);
 }