@borgee/agents-host 0.2.29 → 0.2.31

package/README.md

@@ -84,7 +84,7 @@ Codex now ships on the same default hosted-provider surface as Claude and Copilo
 
 The current shipped internal compatibility surface resolves gates in this order:
 
-1. start from the shipped defaults: `claude-provider-v2`, `copilot-provider-v2`, `codex-provider`, `managed-runtime-convergence`, and `policy-audit-enforcement`
+1. start from the shipped defaults: `copilot-provider-v2`, `codex-provider`, `managed-runtime-convergence`, and `policy-audit-enforcement`
 2. add any explicit entries from `AGENTS_HOST_INTERNAL_COMPATIBILITY_GATES`
 3. subtract any explicit entries from `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES`
 
@@ -98,7 +98,7 @@ Legacy managed roots created before `managed-runtime-settings.json` existed need
 Rollback and hardening controls stay explicit:
 
 - `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES=<comma-list>` disables shipped gates for rollback
-- `AGENTS_HOST_INTERNAL_PROVIDER_IMPLEMENTATIONS=claude:v1,copilot:v1` forces Claude and/or Copilot back to the v1 adapters while their v2 gates stay enabled
+- `AGENTS_HOST_INTERNAL_PROVIDER_IMPLEMENTATIONS=copilot:v1` forces Copilot back to the v1 adapter while its v2 gate stays enabled; stale `claude:v1|v2` entries are tolerated as no-ops for compatibility
 - `AGENTS_HOST_INTERNAL_POLICY_MODE=enforce` hardens the shipped `policy-audit-enforcement` gate beyond its default `audit-only` mode
 
 Or with the CLI:
@@ -234,7 +234,7 @@ Notes:
 | `AGENTS_HOST_DEBUG`                | `--debug`                              | no       | off                                           | Extra host/provider lifecycle logs. Set `AGENTS_HOST_DEBUG=1` to enable without the CLI flag.   |
 | `BORGEE_AGENT_NAME`                | `--name`                               | no       | `Assistant`                                   | Display name used in prompts                                                                     |
 | `RUNTIME_PROVIDER`                 | `--provider`                           | no       | `claude`                                      | `claude`, `copilot`, or `codex`                                                                  |
-| `CLAUDE_COMMAND` / `CLAUDE_ARGS`   | `--claude-command` / `--claude-args`   | no       | `claude` / `--print --permission-mode bypassPermissions` | Local Claude CLI command + args                                                                  |
+| `CLAUDE_COMMAND` / `CLAUDE_ARGS`   | `--claude-command` / `--claude-args`   | no       | `claude-agent-acp` / empty                    | Local Claude ACP adapter command + args. The shipped bundled `claude-agent-acp` path requires empty `CLAUDE_ARGS`; non-empty args are only valid when `CLAUDE_COMMAND` points at a custom ACP adapter command. Legacy `claude --print --permission-mode bypassPermissions` is tolerated as a compatibility alias. |
 | `CODEX_COMMAND` / `CODEX_ARGS`     | `--codex-command` / `--codex-args`     | no       | `codex-acp` / empty                           | Local Codex ACP adapter command + args. The default launch resolves the bundled `@agentclientprotocol/codex-acp` entrypoint. |
 | `COPILOT_COMMAND` / `COPILOT_ARGS` | `--copilot-command` / `--copilot-args` | no       | `copilot` / parsed but ignored by ACP runtime | Local Copilot CLI command. The persistent Copilot ACP prototype always launches `copilot --acp`. |
 | `COPILOT_SESSION_TTL_MINUTES`      | `--copilot-session-ttl-minutes`        | no       | `2880`                                        | Idle TTL for per-channel Copilot ACP sessions                                                    |
@@ -317,8 +317,8 @@ The spec shape is:
   "host": {
     "borgeeBaseUrl": "https://borgee.example.com",
     "defaults": {
-      "claudeCommand": "claude",
-      "claudeArgs": ["--print", "--permission-mode", "bypassPermissions"],
+      "claudeCommand": "claude-agent-acp",
+      "claudeArgs": [],
       "codexCommand": "codex-acp",
       "codexArgs": [],
       "copilotCommand": "copilot",
@@ -384,11 +384,8 @@ paths are also allowed.
 borgeeBaseUrl: https://borgee.example.com
 agentsDir: ./agents
 defaults:
-  claudeCommand: claude
-  claudeArgs:
-    - --print
-    - --permission-mode
-    - bypassPermissions
+  claudeCommand: claude-agent-acp
+  claudeArgs: []
   codexCommand: codex-acp
   codexArgs: []
   copilotCommand: copilot
@@ -424,12 +421,6 @@ name: Support Bot
 apiKey: bgr_support_xxxxxxxx
 provider: claude
 enabled: true
-claudeArgs:
-  - --print
-  - --permission-mode
-  - bypassPermissions
-  - --model
-  - sonnet
 ```
 
 Agent config fields:
@@ -439,6 +430,7 @@ Agent config fields:
 - `apiKey` (**required**)
 - `provider` (**required**): `claude`, `copilot`, or `codex` (roll back Codex only with `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES=codex-provider`)
 - `enabled` (optional, default `true`)
+- `claudeCommand` / `claudeArgs` (optional): leave unset to use the shipped bundled `claude-agent-acp` path. On that bundled path `claudeArgs` must stay empty. Non-empty `claudeArgs` are only supported when `claudeCommand` points at a custom ACP adapter command.
 - optional overrides for `claudeCommand`, `claudeArgs`, `codexCommand`,
   `codexArgs`, `copilotCommand`, `copilotArgs`, and
   `copilotSessionTtlMinutes`
@@ -478,10 +470,16 @@ successfully applied snapshot running.
 Each Borgee channel is mapped 1:1 to a provider-native session while it stays
 active:
 
-- **Claude**: first turn for a channel uses `--session-id <uuid>`; every turn
-  after uses `-r/--resume <uuid>`. The host persists the channel→session map in
-  its state root, serializes cross-channel map rewrites, and retries once with a
-  fresh session immediately if Claude reports a stale `--resume` target.
+- **Claude**: one persistent `@agentclientprotocol/claude-agent-acp` subprocess
+  is shared by a single `AgentsHost`, with one ACP session per Borgee channel.
+  Same-channel turns are serialized; different channels keep isolated ACP
+  sessions. Ordinary threads keep the shared runtime workspace cwd, while
+  eligible `task_assignment` threads switch the real ACP session cwd to that
+  same hidden local task-scoped workspace. The host persists the
+  channel→ACP-session map in its state root, restores same-host continuity with
+  ACP `session/resume` when available, retries stale restores with a fresh
+  session immediately, and injects the per-channel local context paths through
+  Claude ACP `_meta.systemPrompt.append`.
 - **Codex**: one persistent `@agentclientprotocol/codex-acp` subprocess is
   shared by a single `AgentsHost`, with one ACP session per Borgee channel. When
   the current turn has a materialized channel context payload, Codex refreshes a
@@ -504,13 +502,6 @@ active:
   state root and restores same-host continuity with ACP `session/resume` when
   available, otherwise `session/load` plus local replay cleanup on runtimes
   that advertise only load support.
-- **Claude**: Claude still keeps one provider-native session mapping per Borgee
-  channel, but unlike the ACP-backed adapters it spawns a fresh CLI process for
-  each turn. Ordinary threads inherit the host runtime cwd; eligible
-  `task_assignment` threads run the CLI process with the hidden local
-  task-scoped workspace as the process cwd, again without implying that the
-  target repository is already checked out there.
-
 There is no separate transcript/history store on our side. Claude, Codex, and
 Copilot only persist the native session ids they should try to resume later;
 cross-host continuity still does not exist in this runtime.

package/dist/agents-host.d.ts

@@ -128,7 +128,7 @@ export declare class AgentsHost {
     private resolveVisibleTurnBody;
     private shouldRelayProtocolReply;
     private normalizeMessage;
-    private markAssignedTaskInProgress;
+    private resolveTaskAssignmentDelivery;
     private ensureSelfAgentId;
     private classifyAuthor;
     private refreshParticipantDirectory;

package/dist/agents-host.js

@@ -527,6 +527,11 @@ export class AgentsHost {
         if (!normalized) {
             return;
         }
+        const effective = await this.resolveTaskAssignmentDelivery(msg, normalized);
+        if (!effective) {
+            return;
+        }
+        msg = effective;
         let taskThreadContext = { state: 'inactive' };
         let attentionSnapshot;
         if (this.attentionFollowSemanticsEnabled
@@ -542,9 +547,6 @@ export class AgentsHost {
                 }
             }
         }
-        if (msg.message_type === 'task_assignment') {
-            await this.markAssignedTaskInProgress(msg.channel_id, normalized.content);
-        }
         await this.runUngatedTurn(msg, normalized.authorId, normalized.content, taskThreadContext, attentionSnapshot);
     }
     async handleCollaborationMessage(msg) {
@@ -552,9 +554,11 @@ export class AgentsHost {
         if (!normalized) {
             return;
         }
-        if (msg.message_type === 'task_assignment') {
-            await this.markAssignedTaskInProgress(msg.channel_id, normalized.content);
+        const effective = await this.resolveTaskAssignmentDelivery(msg, normalized);
+        if (!effective) {
+            return;
         }
+        msg = effective;
         const channelState = this.ensureCollaborationChannelState(msg.channel_id);
         await this.ensureProtocolStateLoaded(msg.channel_id, channelState);
         await this.ensureAttentionSnapshotLoaded(msg.channel_id, channelState);
@@ -2640,28 +2644,51 @@ export class AgentsHost {
             content,
         };
     }
-    async markAssignedTaskInProgress(threadId, content) {
+    // Only a task assigned to this agent drives a task-assignment turn: it keeps the message a
+    // task_assignment (and best-effort flips an open task to in_progress). An unassigned or
+    // other-assigned task_assignment degrades to an ordinary message, and this agent's own echo of
+    // it drops, so the creator never auto-starts work it was not assigned.
+    async resolveTaskAssignmentDelivery(msg, normalized) {
+        if (msg.message_type !== 'task_assignment') {
+            return msg;
+        }
+        const selfAgentId = await this.ensureSelfAgentId();
+        let task;
         try {
-            const selfAgentId = await this.ensureSelfAgentId();
-            const task = await waitForTaskForThread(this.borgee, threadId, {
-                preferredTaskId: extractTaskIdFromTaskAssignmentContent(content),
+            task = await waitForTaskForThread(this.borgee, msg.channel_id, {
+                preferredTaskId: extractTaskIdFromTaskAssignmentContent(normalized.content),
                 attempts: 10,
                 delayMs: 250,
             });
-            if (!task || task.status !== 'open' || task.assigneeId !== selfAgentId) {
-                return;
-            }
-            await this.borgee.updateTask({
-                taskId: task.id,
-                status: 'in_progress',
-            });
         }
         catch (error) {
-            this.logger.debugError('best-effort task auto-start failed', {
-                channelId: threadId,
+            this.logger.debugError('task-assignment resolution failed', {
+                channelId: msg.channel_id,
                 error,
             });
+            task = null;
+        }
+        if (task && task.assigneeId === selfAgentId) {
+            if (task.status === 'open') {
+                try {
+                    await this.borgee.updateTask({
+                        taskId: task.id,
+                        status: 'in_progress',
+                    });
+                }
+                catch (error) {
+                    this.logger.debugError('best-effort task auto-start failed', {
+                        channelId: msg.channel_id,
+                        error,
+                    });
+                }
+            }
+            return msg;
+        }
+        if (normalized.authorId === selfAgentId) {
+            return null;
         }
+        return { ...msg, message_type: 'default' };
     }
     async ensureSelfAgentId() {
         if (this.selfAgentId) {

package/dist/cli-args.d.ts

@@ -83,4 +83,4 @@ export declare function parseLogArgs(argv: string[]): ParsedLogArgs;
 export declare function parseDescribeManagedArgs(argv: string[]): ParsedDescribeManagedArgs;
 export declare function parseCleanupManagedArgs(argv: string[]): ParsedCleanupManagedArgs;
 export declare function parseApplyManagedArgs(argv: string[]): ParsedApplyManagedArgs;
-export declare const USAGE = "Usage:\n  agents-host start <serverUrl> <apiKey> [options]\n  agents-host start-managed <serverUrl>\n  agents-host start-managed <serverUrl> <apiKey> [agent-options]\n  agents-host describe-managed <serverUrl>\n  agents-host cleanup-managed <serverUrl> [--purge]\n  agents-host apply-managed <serverUrl> --stdin\n  agents-host apply-managed <serverUrl> --spec-json <json>\n  agents-host log <serverUrl> [--lines <n>] [--follow]\n  agents-host log <serverUrl> --path\n  agents-host start --config <path-to-host-config> [--debug]\n  agents-host validate --config <path-to-host-config>\n  agents-host describe --config <path-to-host-config>\n  agents-host print-layout --root <dir>\n  agents-host generate-config --root <dir> --stdin\n  agents-host generate-config --root <dir> --spec-json <json>\n\nForeground start options:\n  --debug                         Enable host/provider debug logs (or set AGENTS_HOST_DEBUG=1)\n\nSingle-agent agent options:\n  --name <name>                   Display name (default: Assistant)\n  --provider <claude|codex|copilot>\n                                   Runtime provider (default: claude)\n  --claude-command <cmd>          Local Claude CLI command (default: claude)\n  --claude-args <args>            Local Claude CLI args (default: --print --permission-mode bypassPermissions)\n  --codex-command <cmd>           Local Codex ACP adapter command (default: codex-acp)\n  --codex-args <args>             Local Codex ACP adapter args\n  --copilot-command <cmd>         Local Copilot CLI command (default: copilot)\n  --copilot-args <args>           Ignored by the Copilot ACP prototype\n  --copilot-session-ttl-minutes <minutes>\n                                   Idle session TTL for Copilot ACP sessions (default: 2880)\n\nCommand summary:\n  start <serverUrl> <apiKey>      Start one foreground hosted agent (legacy-compatible behavior)\n  start --config <path>           Start agents + supervisor + watchers from a host config file\n  start-managed <serverUrl>       Restart or resume an existing per-serverUrl managed daemon\n  start-managed <serverUrl> <apiKey>\n                                   Upsert one agent into the per-serverUrl local daemon and exit after reconcile\n  describe-managed <serverUrl>    Print managed-runtime spec JSON for machine callers\n  cleanup-managed <serverUrl>     Stop one managed-runtime daemon locally; --purge also removes its runtime root\n  apply-managed <serverUrl>       Apply one managed-runtime full-set spec for machine callers\n  log <serverUrl>                 Print the managed daemon log tail for one server runtime\n  validate --config <path>        Validate local-config files without starting agents or watchers\n  describe --config <path>        Print the current managed full-set spec as JSON\n  print-layout --root <dir>       Print the canonical default local-config layout as JSON\n  generate-config --root <dir> --stdin  Materialize canonical local-config files from stdin\n  generate-config --root <dir> --spec-json <json>\n                                   Compatibility input; JSON is exposed in process arguments\n\nExamples:\n  agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot --debug\n  agents-host start-managed https://borgee.example.com\n  agents-host start-managed https://borgee.example.com bgr_xxxxxxxx --provider copilot\n  agents-host describe-managed https://borgee.example.com\n  agents-host cleanup-managed https://borgee.example.com --purge\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host apply-managed https://borgee.example.com --stdin\n  agents-host log https://borgee.example.com --lines 200 --follow\n  agents-host log https://borgee.example.com --path\n  agents-host start --config ./agents-host.yaml --debug\n  agents-host validate --config ./agents-host.yaml\n  agents-host describe --config ./agents-host.yaml\n  agents-host print-layout --root ./runtime-root\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host generate-config --root ./runtime-root --stdin\n";
+export declare const USAGE = "Usage:\n  agents-host start <serverUrl> <apiKey> [options]\n  agents-host start-managed <serverUrl>\n  agents-host start-managed <serverUrl> <apiKey> [agent-options]\n  agents-host describe-managed <serverUrl>\n  agents-host cleanup-managed <serverUrl> [--purge]\n  agents-host apply-managed <serverUrl> --stdin\n  agents-host apply-managed <serverUrl> --spec-json <json>\n  agents-host log <serverUrl> [--lines <n>] [--follow]\n  agents-host log <serverUrl> --path\n  agents-host start --config <path-to-host-config> [--debug]\n  agents-host validate --config <path-to-host-config>\n  agents-host describe --config <path-to-host-config>\n  agents-host print-layout --root <dir>\n  agents-host generate-config --root <dir> --stdin\n  agents-host generate-config --root <dir> --spec-json <json>\n\nForeground start options:\n  --debug                         Enable host/provider debug logs (or set AGENTS_HOST_DEBUG=1)\n\nSingle-agent agent options:\n  --name <name>                   Display name (default: Assistant)\n  --provider <claude|codex|copilot>\n                                   Runtime provider (default: claude)\n  --claude-command <cmd>          Local Claude ACP adapter command (default: claude-agent-acp)\n  --claude-args <args>            Local Claude ACP adapter args (empty on the shipped bundled path)\n  --codex-command <cmd>           Local Codex ACP adapter command (default: codex-acp)\n  --codex-args <args>             Local Codex ACP adapter args\n  --copilot-command <cmd>         Local Copilot CLI command (default: copilot)\n  --copilot-args <args>           Ignored by the Copilot ACP prototype\n  --copilot-session-ttl-minutes <minutes>\n                                   Idle session TTL for Copilot ACP sessions (default: 2880)\n\nCommand summary:\n  start <serverUrl> <apiKey>      Start one foreground hosted agent (legacy-compatible behavior)\n  start --config <path>           Start agents + supervisor + watchers from a host config file\n  start-managed <serverUrl>       Restart or resume an existing per-serverUrl managed daemon\n  start-managed <serverUrl> <apiKey>\n                                   Upsert one agent into the per-serverUrl local daemon and exit after reconcile\n  describe-managed <serverUrl>    Print managed-runtime spec JSON for machine callers\n  cleanup-managed <serverUrl>     Stop one managed-runtime daemon locally; --purge also removes its runtime root\n  apply-managed <serverUrl>       Apply one managed-runtime full-set spec for machine callers\n  log <serverUrl>                 Print the managed daemon log tail for one server runtime\n  validate --config <path>        Validate local-config files without starting agents or watchers\n  describe --config <path>        Print the current managed full-set spec as JSON\n  print-layout --root <dir>       Print the canonical default local-config layout as JSON\n  generate-config --root <dir> --stdin  Materialize canonical local-config files from stdin\n  generate-config --root <dir> --spec-json <json>\n                                   Compatibility input; JSON is exposed in process arguments\n\nExamples:\n  agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot --debug\n  agents-host start-managed https://borgee.example.com\n  agents-host start-managed https://borgee.example.com bgr_xxxxxxxx --provider copilot\n  agents-host describe-managed https://borgee.example.com\n  agents-host cleanup-managed https://borgee.example.com --purge\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host apply-managed https://borgee.example.com --stdin\n  agents-host log https://borgee.example.com --lines 200 --follow\n  agents-host log https://borgee.example.com --path\n  agents-host start --config ./agents-host.yaml --debug\n  agents-host validate --config ./agents-host.yaml\n  agents-host describe --config ./agents-host.yaml\n  agents-host print-layout --root ./runtime-root\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host generate-config --root ./runtime-root --stdin\n";

package/dist/cli-args.js

@@ -494,8 +494,8 @@ Single-agent agent options:
   --name <name>                   Display name (default: Assistant)
   --provider <claude|codex|copilot>
                                    Runtime provider (default: claude)
-  --claude-command <cmd>          Local Claude CLI command (default: claude)
-  --claude-args <args>            Local Claude CLI args (default: --print --permission-mode bypassPermissions)
+  --claude-command <cmd>          Local Claude ACP adapter command (default: claude-agent-acp)
+  --claude-args <args>            Local Claude ACP adapter args (empty on the shipped bundled path)
   --codex-command <cmd>           Local Codex ACP adapter command (default: codex-acp)
   --codex-args <args>             Local Codex ACP adapter args
   --copilot-command <cmd>         Local Copilot CLI command (default: copilot)

package/dist/compatibility-gates.js

@@ -21,7 +21,6 @@ export const INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV = 'AGENTS_HOST_INTERNAL_PROVI
 export const MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION = 1;
 const VALID_PROVIDER_IMPLEMENTATION_ENTRIES = '"claude:v1", "claude:v2", "copilot:v1", or "copilot:v2"';
 export const DEFAULT_INTERNAL_COMPATIBILITY_GATES = Object.freeze([
-    CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE,
     COLLABORATION_CAPABILITIES_DIAGNOSTICS_COMPATIBILITY_GATE,
     COLLABORATION_OUTCOME_MODEL_COMPATIBILITY_GATE,
     CONNECTIONS_STATE_LAYER_COMPATIBILITY_GATE,
@@ -118,11 +117,15 @@ export function resolveManagedRuntimeProviderImplementationOverrides(env = proce
     const enabledGates = new Set(compatibilityGates);
     return normalizeInternalProviderImplementationOverrides(env[INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV]).filter((assignment) => {
         const [provider] = assignment.split(':');
+        if (provider === 'claude') {
+            return false;
+        }
         return enabledGates.has(PROVIDER_IMPLEMENTATION_COMPATIBILITY_GATES[provider]);
     });
 }
 export function resolveManagedRuntimeCompatibilityGates(env = process.env) {
     const compatibilityGates = new Set(resolveInternalCompatibilityGates(env));
+    compatibilityGates.delete(CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE);
     const explicitlyEnabledGates = parseCompatibilityGates(env[COMPATIBILITY_GATES_ENV]);
     if (compatibilityGates.has(MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE)) {
         compatibilityGates.add(CONNECTIONS_STATE_LAYER_COMPATIBILITY_GATE);

package/dist/config.d.ts

@@ -1,6 +1,9 @@
 import type { AgentsHostConfig, ProviderCommandConfig, ProviderKind } from './types.js';
 export declare const MAX_COPILOT_SESSION_TTL_MINUTES: number;
 export declare const DEFAULT_COPILOT_SESSION_TTL_MINUTES: number;
+export declare const DEFAULT_CLAUDE_COMMAND = "claude-agent-acp";
+export declare const LEGACY_CLAUDE_COMMAND = "claude";
+export declare const LEGACY_CLAUDE_ONE_SHOT_ARGS: readonly ["--print", "--permission-mode", "bypassPermissions"];
 export declare const DEFAULT_PROVIDER_COMMAND_CONFIG: ProviderCommandConfig;
 export declare function requireNonEmptyString(value: unknown, message: string): string;
 export declare function optionalNonEmptyString(value: unknown, fieldName: string, sourceLabel: string): string | undefined;
@@ -9,5 +12,10 @@ export declare function optionalStringArray(value: unknown, fieldName: string, s
 export declare function parseCopilotSessionTtlMinutesValue(value: unknown, sourceLabel: string): number;
 export declare function resolveProvider(rawValue: string, sourceLabel: string): ProviderKind;
 export declare function assertProviderCompatibility(provider: ProviderKind, sourceLabel: string, env?: NodeJS.ProcessEnv): void;
+export declare function isLegacyClaudeCompatibilityAlias(command: string, args: string[]): boolean;
+export declare function isLegacyClaudeBinaryCommand(command: string): boolean;
+export declare function hasLegacyClaudeOneShotArgs(args: string[]): boolean;
+export declare function assertClaudeCommandCompatibility(command: string, args: string[], sourceLabel: string): void;
+export declare function assertProviderCommandCompatibility(provider: ProviderKind, config: Pick<ProviderCommandConfig, 'claudeCommand' | 'claudeArgs'>, sourceLabel: string): void;
 export declare function resolveProviderCommandConfig(overrides?: Partial<ProviderCommandConfig>): ProviderCommandConfig;
 export declare function loadConfigFromEnv(env?: NodeJS.ProcessEnv): AgentsHostConfig;

package/dist/config.js

@@ -1,11 +1,15 @@
+import { basename } from 'node:path';
 import { resolveSingleAgentStateRoot } from './state-paths.js';
 import { CODEX_PROVIDER_COMPATIBILITY_GATE, resolveInternalCompatibilityGates, } from './compatibility-gates.js';
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 export const MAX_COPILOT_SESSION_TTL_MINUTES = MAX_TIMER_DELAY_MS / 60_000;
 export const DEFAULT_COPILOT_SESSION_TTL_MINUTES = 2 * 24 * 60;
+export const DEFAULT_CLAUDE_COMMAND = 'claude-agent-acp';
+export const LEGACY_CLAUDE_COMMAND = 'claude';
+export const LEGACY_CLAUDE_ONE_SHOT_ARGS = ['--print', '--permission-mode', 'bypassPermissions'];
 export const DEFAULT_PROVIDER_COMMAND_CONFIG = {
-    claudeCommand: 'claude',
-    claudeArgs: ['--print', '--permission-mode', 'bypassPermissions'],
+    claudeCommand: DEFAULT_CLAUDE_COMMAND,
+    claudeArgs: [],
     codexCommand: 'codex-acp',
     codexArgs: [],
     copilotCommand: 'copilot',
@@ -74,6 +78,38 @@ export function assertProviderCompatibility(provider, sourceLabel, env = process
         throw new Error(`${sourceLabel}: provider "codex" requires the shipped ${CODEX_PROVIDER_COMPATIBILITY_GATE} path to remain enabled`);
     }
 }
+export function isLegacyClaudeCompatibilityAlias(command, args) {
+    if (command !== LEGACY_CLAUDE_COMMAND || args.length !== LEGACY_CLAUDE_ONE_SHOT_ARGS.length) {
+        return false;
+    }
+    return args.every((arg, index) => arg === LEGACY_CLAUDE_ONE_SHOT_ARGS[index]);
+}
+export function isLegacyClaudeBinaryCommand(command) {
+    return basename(command) === LEGACY_CLAUDE_COMMAND;
+}
+export function hasLegacyClaudeOneShotArgs(args) {
+    return (args.length === LEGACY_CLAUDE_ONE_SHOT_ARGS.length
+        && args.every((arg, index) => arg === LEGACY_CLAUDE_ONE_SHOT_ARGS[index]));
+}
+export function assertClaudeCommandCompatibility(command, args, sourceLabel) {
+    if (command === DEFAULT_CLAUDE_COMMAND) {
+        if (args.length > 0) {
+            throw new Error(`Invalid Claude config in ${sourceLabel}: the shipped ${DEFAULT_CLAUDE_COMMAND} path does not accept CLAUDE_ARGS/claudeArgs. Leave them empty or point claudeCommand/CLAUDE_COMMAND at a custom ACP adapter command instead.`);
+        }
+        return;
+    }
+    if (isLegacyClaudeBinaryCommand(command)) {
+        if (isLegacyClaudeCompatibilityAlias(command, args)) {
+            return;
+        }
+        throw new Error(`Invalid Claude config in ${sourceLabel}: raw "${LEGACY_CLAUDE_COMMAND}" commands no longer speak ACP directly. Use the shipped ${DEFAULT_CLAUDE_COMMAND} default, keep only the exact legacy compatibility alias "${LEGACY_CLAUDE_COMMAND} ${LEGACY_CLAUDE_ONE_SHOT_ARGS.join(' ')}", or point claudeCommand/CLAUDE_COMMAND at a real ACP adapter command.`);
+    }
+}
+export function assertProviderCommandCompatibility(provider, config, sourceLabel) {
+    if (provider === 'claude') {
+        assertClaudeCommandCompatibility(config.claudeCommand, config.claudeArgs, sourceLabel);
+    }
+}
 export function resolveProviderCommandConfig(overrides = {}) {
     return {
         claudeCommand: overrides.claudeCommand ?? DEFAULT_PROVIDER_COMMAND_CONFIG.claudeCommand,
@@ -89,20 +125,22 @@ export function loadConfigFromEnv(env = process.env) {
     const provider = resolveProvider(envOr('RUNTIME_PROVIDER', 'claude', env), 'Unsupported RUNTIME_PROVIDER');
     assertProviderCompatibility(provider, 'Unsupported RUNTIME_PROVIDER', env);
     const agentApiKey = requireEnv('BORGEE_AGENT_API_KEY', env);
+    const providerConfig = resolveProviderCommandConfig({
+        claudeCommand: envOr('CLAUDE_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.claudeCommand, env),
+        claudeArgs: parseArgs(envOr('CLAUDE_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.claudeArgs.join(' '), env)),
+        codexCommand: envOr('CODEX_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.codexCommand, env),
+        codexArgs: parseArgs(envOr('CODEX_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.codexArgs.join(' '), env)),
+        copilotCommand: envOr('COPILOT_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.copilotCommand, env),
+        copilotArgs: parseArgs(envOr('COPILOT_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.copilotArgs.join(' '), env)),
+        copilotSessionTtlMinutes: env.COPILOT_SESSION_TTL_MINUTES && env.COPILOT_SESSION_TTL_MINUTES.trim().length > 0
+            ? parseCopilotSessionTtlMinutesValue(env.COPILOT_SESSION_TTL_MINUTES, 'environment variable COPILOT_SESSION_TTL_MINUTES')
+            : DEFAULT_PROVIDER_COMMAND_CONFIG.copilotSessionTtlMinutes,
+    });
+    assertProviderCommandCompatibility(provider, providerConfig, 'environment variables');
     return {
         borgeeBaseUrl: requireEnv('BORGEE_BASE_URL', env),
         stateRootDir: resolveSingleAgentStateRoot(env, undefined, agentApiKey),
-        ...resolveProviderCommandConfig({
-            claudeCommand: envOr('CLAUDE_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.claudeCommand, env),
-            claudeArgs: parseArgs(envOr('CLAUDE_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.claudeArgs.join(' '), env)),
-            codexCommand: envOr('CODEX_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.codexCommand, env),
-            codexArgs: parseArgs(envOr('CODEX_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.codexArgs.join(' '), env)),
-            copilotCommand: envOr('COPILOT_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.copilotCommand, env),
-            copilotArgs: parseArgs(envOr('COPILOT_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.copilotArgs.join(' '), env)),
-            copilotSessionTtlMinutes: env.COPILOT_SESSION_TTL_MINUTES && env.COPILOT_SESSION_TTL_MINUTES.trim().length > 0
-                ? parseCopilotSessionTtlMinutesValue(env.COPILOT_SESSION_TTL_MINUTES, 'environment variable COPILOT_SESSION_TTL_MINUTES')
-                : DEFAULT_PROVIDER_COMMAND_CONFIG.copilotSessionTtlMinutes,
-        }),
+        ...providerConfig,
         agent: {
             agentApiKey,
             agentName: envOr('BORGEE_AGENT_NAME', 'Assistant', env),

package/dist/gateway/localhost-gateway.js

@@ -778,8 +778,12 @@ function parseUpdateTaskInput(taskId, body) {
         status: readOptionalString(body.status),
         assigneeId: readOptionalString(body.assigneeId) ?? readOptionalString(body.assignee_id),
         title: readOptionalString(body.title),
+        description: readOptionalString(body.description),
     };
-    if (input.status === undefined && input.assigneeId === undefined && input.title === undefined) {
+    if (input.status === undefined &&
+        input.assigneeId === undefined &&
+        input.title === undefined &&
+        input.description === undefined) {
         throw new GatewayHttpError(400, { error: 'no_updates' }, 'bad-request');
     }
     return input;

package/dist/local-config.js

@@ -2,7 +2,7 @@ import { promises as fs } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
 import { parseDocument, stringify } from 'yaml';
-import { assertProviderCompatibility, optionalNonEmptyString, optionalStringArray, parseCopilotSessionTtlMinutesValue, requireNonEmptyString, resolveProvider, resolveProviderCommandConfig, } from './config.js';
+import { assertProviderCompatibility, assertProviderCommandCompatibility, optionalNonEmptyString, optionalStringArray, parseCopilotSessionTtlMinutesValue, requireNonEmptyString, resolveProvider, resolveProviderCommandConfig, } from './config.js';
 import { resolveLocalConfigAgentStateRoot } from './state-paths.js';
 const SUPPORTED_CONFIG_EXTENSIONS = new Set(['.json', '.yaml', '.yml']);
 export const DEFAULT_LOCAL_HOST_CONFIG_FILENAME = 'agents-host.yaml';
@@ -186,6 +186,8 @@ export function parseGenerateConfigSpec(value, sourceLabel, env = process.env) {
             throw new Error(`Invalid generate-config agents[${index}] in ${sourceLabel}: expected an object`);
         }
         const agent = parseAgentConfigFile(`generate-config agents[${index}] in ${sourceLabel}`, entry, env);
+        const providerConfig = resolveAgentProviderCommandConfig(host.defaults, agent);
+        assertProviderCommandCompatibility(agent.provider, providerConfig, `generate-config agents[${index}] in ${sourceLabel}`);
         const existingIndex = seenKeys.get(agent.key);
         if (existingIndex !== undefined) {
             throw new Error(`Duplicate generate-config agent key "${agent.key}" in ${sourceLabel} at indexes ${existingIndex} and ${index}`);
@@ -598,6 +600,7 @@ function buildManagedAgentSnapshot(host, stateRootBaseDir, sourcePath, agent) {
         ...host.defaults,
         ...parseProviderCommandOverrides(agent, `agent config ${sourcePath}`),
     });
+    assertProviderCommandCompatibility(agent.provider, providerConfig, `agent config ${sourcePath}`);
     const config = {
         borgeeBaseUrl: host.borgeeBaseUrl,
         stateRootDir: resolveLocalConfigAgentStateRoot(stateRootBaseDir, agent.key),
@@ -614,6 +617,20 @@ function buildManagedAgentSnapshot(host, stateRootBaseDir, sourcePath, agent) {
         config,
     };
 }
+function resolveAgentProviderCommandConfig(hostDefaults, agent) {
+    return resolveProviderCommandConfig({
+        ...hostDefaults,
+        ...(agent.claudeCommand !== undefined ? { claudeCommand: agent.claudeCommand } : {}),
+        ...(agent.claudeArgs !== undefined ? { claudeArgs: agent.claudeArgs } : {}),
+        ...(agent.codexCommand !== undefined ? { codexCommand: agent.codexCommand } : {}),
+        ...(agent.codexArgs !== undefined ? { codexArgs: agent.codexArgs } : {}),
+        ...(agent.copilotCommand !== undefined ? { copilotCommand: agent.copilotCommand } : {}),
+        ...(agent.copilotArgs !== undefined ? { copilotArgs: agent.copilotArgs } : {}),
+        ...(agent.copilotSessionTtlMinutes !== undefined
+            ? { copilotSessionTtlMinutes: agent.copilotSessionTtlMinutes }
+            : {}),
+    });
+}
 export async function loadLocalConfigSnapshot(hostConfigPath, deps = {}) {
     const fileSystem = deps.fileSystem ?? nodeFileSystem;
     const absoluteHostConfigPath = resolve(hostConfigPath);
@@ -698,6 +715,8 @@ export async function loadLocalConfigGenerateSpec(hostConfigPath, deps = {}) {
             }
             const agentRecord = await loadParsedDocument(fileSystem, agentFilePath, 'agent config');
             const agentConfig = parseAgentConfigFile(agentFilePath, agentRecord, deps.env);
+            const providerConfig = resolveAgentProviderCommandConfig(hostConfig.defaults, agentConfig);
+            assertProviderCommandCompatibility(agentConfig.provider, providerConfig, `agent config ${agentFilePath}`);
             const existingPath = seenKeys.get(agentConfig.key);
             if (existingPath) {
                 throw new Error(`Duplicate agent key "${agentConfig.key}" in ${existingPath} and ${agentFilePath}`);

package/dist/managed-daemon.js

@@ -5,8 +5,8 @@ import { createConnection, createServer } from 'node:net';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { AgentsHostSupervisor } from './agents-host-supervisor.js';
-import { COMPATIBILITY_GATES_ENV, createManagedRuntimeSettingsFingerprint, INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV, INTERNAL_POLICY_MODE_ENV, INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV, MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE, MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION, resolveDisabledDefaultCompatibilityGates, resolveManagedRuntimeSettingsSnapshot, normalizeInternalProviderImplementationOverrides, } from './compatibility-gates.js';
-import { loadConfigFromEnv } from './config.js';
+import { CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE, COMPATIBILITY_GATES_ENV, createManagedRuntimeSettingsFingerprint, INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV, INTERNAL_POLICY_MODE_ENV, INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV, MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE, MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION, resolveDisabledDefaultCompatibilityGates, resolveManagedRuntimeSettingsSnapshot, normalizeInternalProviderImplementationOverrides, } from './compatibility-gates.js';
+import { DEFAULT_PROVIDER_COMMAND_CONFIG, hasLegacyClaudeOneShotArgs, loadConfigFromEnv, } from './config.js';
 import { loadLocalConfigGenerateSpec, materializeLocalConfig, parseGenerateConfigSpec, resolveLocalConfigLayout, } from './local-config.js';
 import { normalizeManagedRuntimeKey, resolveManagedBootstrapLockPath, resolveManagedDaemonLogPath, resolveManagedDaemonSocketPath, resolveManagedRuntimeRoot, resolveManagedRuntimeSettingsPath, } from './state-paths.js';
 const MANAGED_ROOT_MODE = 0o700;
@@ -149,8 +149,9 @@ function resolveDesiredManagedRuntimeSettings(env = process.env) {
 function normalizeManagedRuntimeSettingsSnapshot(snapshot) {
     const compatibilityGates = [...new Set(snapshot.compatibilityGates.map((gate) => gate.trim()))]
         .filter((gate) => gate.length > 0)
+        .filter((gate) => gate !== CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE)
         .sort((left, right) => left.localeCompare(right));
-    const providerImplementationOverrides = normalizeInternalProviderImplementationOverrides(snapshot.providerImplementationOverrides.join(','));
+    const providerImplementationOverrides = normalizeInternalProviderImplementationOverrides(snapshot.providerImplementationOverrides.join(',')).filter((assignment) => !assignment.startsWith('claude:'));
     return {
         schemaVersion: MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION,
         compatibilityGates,
@@ -341,9 +342,18 @@ export function buildManagedLocalAgentConfig(options) {
         },
     };
 }
-function mergeManagedLocalAgentConfig(existingAgent, generatedAgent, envOverrides) {
+function mergeManagedLocalAgentConfig(hostDefaults, existingAgent, generatedAgent, envOverrides) {
     const overrides = envOverrides ?? {};
     const hasOverride = (key) => Object.prototype.hasOwnProperty.call(overrides, key);
+    const effectiveExistingClaudeCommand = existingAgent.claudeCommand ?? hostDefaults?.claudeCommand;
+    const effectiveExistingClaudeArgs = existingAgent.claudeArgs ?? hostDefaults?.claudeArgs ?? [];
+    const hasLegacyClaudeDefaults = effectiveExistingClaudeCommand === 'claude' && hasLegacyClaudeOneShotArgs(effectiveExistingClaudeArgs);
+    const shouldRefreshLegacyClaudeDefaults = hasLegacyClaudeDefaults
+        && generatedAgent.claudeCommand === DEFAULT_PROVIDER_COMMAND_CONFIG.claudeCommand
+        && JSON.stringify(generatedAgent.claudeArgs ?? []) === JSON.stringify(DEFAULT_PROVIDER_COMMAND_CONFIG.claudeArgs);
+    const shouldResetLegacyClaudeArgsForCommandOverride = hasLegacyClaudeDefaults
+        && hasOverride('CLAUDE_COMMAND')
+        && !hasOverride('CLAUDE_ARGS');
     return {
         ...cloneLocalAgentConfig(existingAgent),
         key: generatedAgent.key,
@@ -351,8 +361,12 @@ function mergeManagedLocalAgentConfig(existingAgent, generatedAgent, envOverride
         enabled: true,
         name: hasOverride('BORGEE_AGENT_NAME') ? generatedAgent.name : existingAgent.name,
         provider: hasOverride('RUNTIME_PROVIDER') ? generatedAgent.provider : existingAgent.provider,
-        claudeCommand: hasOverride('CLAUDE_COMMAND') ? generatedAgent.claudeCommand : existingAgent.claudeCommand,
+        claudeCommand: hasOverride('CLAUDE_COMMAND') || shouldRefreshLegacyClaudeDefaults
+            ? generatedAgent.claudeCommand
+            : existingAgent.claudeCommand,
         claudeArgs: hasOverride('CLAUDE_ARGS')
+            || shouldRefreshLegacyClaudeDefaults
+            || shouldResetLegacyClaudeArgsForCommandOverride
             ? [...(generatedAgent.claudeArgs ?? [])]
             : [...(existingAgent.claudeArgs ?? [])],
         codexCommand: hasOverride('CODEX_COMMAND') ? generatedAgent.codexCommand : existingAgent.codexCommand,
@@ -1005,7 +1019,7 @@ export async function bootstrapManagedDaemonStart(options, deps = {}) {
                 return existingAgent
                     ? {
                         ...generatedManagedAgent,
-                        agent: mergeManagedLocalAgentConfig(existingAgent, generatedManagedAgent.agent, explicitManagedAgentOverrides),
+                        agent: mergeManagedLocalAgentConfig(currentManagedSpec?.host.defaults, existingAgent, generatedManagedAgent.agent, explicitManagedAgentOverrides),
                     }
                     : generatedManagedAgent;
             })();

package/dist/providers/claude/cli-client.d.ts

@@ -1,19 +1,25 @@
 import spawn from 'cross-spawn';
+import { PROTOCOL_VERSION, client, methods, ndJsonStream } from '@agentclientprotocol/sdk';
 import { type DebugLogger } from '../../debug.js';
 import type { PreparedProviderTurnInput, ProviderGenerateOptions } from '../../types.js';
 import type { ClaudeChannelSessionStore } from './session-store.js';
-interface ClaudeCliRuntime {
+interface ClaudeAcpRuntime {
     spawn: typeof spawn;
+    client: typeof client;
+    ndJsonStream: typeof ndJsonStream;
+    methods: typeof methods;
+    protocolVersion: typeof PROTOCOL_VERSION;
     cwd: string;
+    shutdownGracePeriodMs: number;
+    shutdownForceKillWaitMs: number;
 }
 /**
- * CLI client for the Claude Code CLI (`claude`) non-interactive mode, with
- * native provider-session continuity.
+ * Persistent ACP-backed client for the Claude ACP adapter.
  *
- * Claude session memory remains entirely inside the Claude CLI. This client
- * only pins one native session id per routed provider session and serializes
- * turns per route so `--resume` is never called concurrently for the same
- * native session.
+ * The public caller surface intentionally stays stable: callers still create a
+ * `ClaudeCliClient`, then call `generateReply()` and `dispose()`. Internally,
+ * the shipped runtime now runs one Claude ACP adapter process and reuses one
+ * ACP session per routed Borgee channel.
  */
 export declare class ClaudeCliClient {
     private readonly command;
@@ -24,28 +30,61 @@ export declare class ClaudeCliClient {
     private readonly runtime;
     private readonly channels;
     private readonly persistedSessions;
+    private readonly closingSessions;
+    private readonly pendingSessionStarts;
+    private readonly pendingSessionCloses;
+    private readonly pendingSessionStoreOperations;
+    private readonly fatalPromise;
+    private rejectFatalPromise;
+    private child?;
+    private connection?;
+    private startPromise?;
+    private shutdownPromise?;
+    private childExitPromise?;
+    private resolveChildExit?;
+    private fatalError;
+    private disposing;
+    private backendClosed;
     private loadedSessionStoreAgentId;
-    private stopped;
     private sessionStoreLoadPromise;
     private sessionStoreWriteQueue;
-    constructor(command: string, args: string[], runtimeOverrides?: Partial<ClaudeCliRuntime>, sessionStore?: ClaudeChannelSessionStore | undefined, resolveSessionStoreAgentId?: () => string | undefined, logger?: DebugLogger);
+    private sessionCapabilities;
+    private childStderr;
+    constructor(command: string, args?: string[], runtimeOverrides?: Partial<ClaudeAcpRuntime>, sessionStore?: ClaudeChannelSessionStore | undefined, resolveSessionStoreAgentId?: () => string | undefined, logger?: DebugLogger);
     generateReply(turn: PreparedProviderTurnInput, options?: ProviderGenerateOptions): Promise<string>;
     generateReply(channelId: string, prompt: string, options?: ProviderGenerateOptions): Promise<string>;
     dispose(): Promise<void>;
+    private ensureStarted;
+    private startBackend;
     private getOrCreateChannelState;
     private processChannelQueue;
+    private getOrCreateSession;
+    private startFreshSession;
+    private restoreOrCreateSession;
+    private restoreSession;
+    private clearBufferedSessionReplay;
+    private resolveSessionCwd;
+    private recycleSessionIfScopeChanged;
     private runTurn;
-    private runTurnAttempt;
+    private raceWithFatal;
+    private failAll;
+    private handlePermissionRequest;
+    private invalidateSession;
+    private closeSession;
+    private rejectQueuedTurnsAfterSessionTaint;
+    private findChannelIdBySessionId;
     private currentSessionStoreAgentId;
     private ensureSessionStoreLoaded;
-    private hydrateChannelState;
+    private readPersistedSessionId;
     private persistSession;
     private persistSessionBestEffort;
-    private resetPersistedSession;
-    private resolveTurnCwd;
-    private resetSessionIfCwdChanged;
-    private resetPersistedSessionBestEffort;
+    private clearPersistedSession;
+    private clearPersistedSessionBestEffort;
     private enqueueSessionStoreWrite;
-    private run;
+    private trackSessionStoreOperation;
+    private shutdownBackend;
+    private waitForPendingSessionStarts;
+    private waitForPendingSessionCloses;
+    private waitForChildExit;
 }
 export {};