Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions MANIFEST.in
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ recursive-include src/kiro_crew/docs *.md
# a missing line here drops the file from every published artifact.
recursive-include src/kiro_crew/docs *.json
recursive-include src/kiro_crew/tests_fixtures *
# The claude CLI launcher the Claude backend starts its CLI through (acp/client.py).
include src/kiro_crew/acp/claude_launcher.mjs

# --- Pruning: never ship test trees, vendored node deps, or build cruft ------
prune test
Expand Down
2 changes: 1 addition & 1 deletion docs/system-specs/modules/acp-client.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ expose new global files in order for later MCP callbacks to identify themselves.
`AcpClient(acp_backend=...)` selects which subprocess to launch:

- `""` (default): `kiro-cli acp --agent <name>` (resolved by `_resolve_kiro_bin`). Per-session kiro settings are layered in via the workspace overlay `<work_dir>/.kiro/settings/cli.json` (written by `AcpProvider`, not the client): reasoning **effort** (`chat.modelDefaults`) and **MCP Tool Search** (`toolSearch.enabled` + activation thresholds from `agent.tool_search_min_pct` / `tool_search_min_tokens`, gated by `agent.tool_search`, default on) — see providers.md.
- `"claude"` (`ACP_BACKEND_CLAUDE`): `claude-agent-acp` (resolved by `_resolve_claude_acp_bin` → `(list[str] | None, str)` (argv plus the augmented PATH actually searched)). Resolution order: `CLAUDE_AGENT_ACP_BIN` env var, then the **vendored copy** (`_resolve_vendored_claude_acp` — `<node_modules>/@agentclientprotocol/claude-agent-acp/dist/index.js` found under the package's `_vendor/node_modules` from the distribution bundle, the sibling `KiroCrewWebsite/node_modules` in a source checkout, or `KIROCREW_PROJECT_DIR`; needs no global npm install or network — matters on hosts that have no package-registry token at gateway runtime), then `mise which claude-agent-acp` (respects MISE_DATA_DIR and all mise config), then a direct glob under mise's Node installs dir (`_mise_node_installs_dir` — `<mise-data>/installs/node`, root from `env.mise_data_dir` so MISE_DATA_DIR / XDG_DATA_HOME are honoured), then augmented PATH (`env.augmented_path` — mise shims, `~/.npm-packages/bin`, `~/.volta/bin`, `/opt/homebrew/bin`, plus EVERY per-version manager bin dir via `env.node_all_bin_dirs` (mise/asdf/nvm/fnm, all installed versions — a global npm binary can live under any of them), so a non-login launchd/systemd gateway also finds globally-installed binaries). The adapter is vendored into the distribution bundle and the pip build by `setup.py` (`_vendor_acp_into_pkg` → `kiro_crew/_vendor/node_modules`), so every install method ships it without asking the user to `npm i -g`. Vendoring copies the adapter **plus its full transitive dependency closure** (`_acp_dependency_closure` walks `dependencies`/`optionalDependencies` from the resolved website `node_modules`, ~96 flat top-level packages) — npm hoists deps like `@agentclientprotocol/sdk` flat, so copying only the adapter package crashes the ESM loader with `ERR_MODULE_NOT_FOUND`. `_resolve_vendored_claude_acp` accepts a root only when the hoisted dependency marker `@agentclientprotocol/sdk` is present alongside the entry, so an incomplete vendored copy is skipped in favour of a complete one instead of being spawned and crashed. For scripts under mise installs, returns `[node_binary, script_path]` to bypass `#!/usr/bin/env node` shebang resolution which fails in non-interactive daemon contexts. For standalone binaries, returns `[binary_path]`. Pre-spawn the client writes `<work_dir>/.claude/settings.local.json` with `defaultMode: default` so the adapter routes every tool decision back to Kiro Crew via `session/request_permission`. This makes claude-agent-acp participate in the same approve / trust_reads / trust / yolo protocol as kiro-cli — dashboard, subagents, channel agents, cron, and heartbeat all share the path. Kiro Crew still enforces per-tool security via `HooksConfig.auto_deny_tools` (evaluated by `HookManager.on_tool_call` in `hooks.py`) on every `session/request_permission` event. `CLAUDE_CONFIG_DIR` (an isolated config root, distinct from the project-scope `<work_dir>/.claude/settings.local.json` the client writes itself) is **not** set by this core: `_spawn` merges a caller's `extra_env` into the child environment, so an edition can point the adapter's `SettingsManager` and the SDK at a seeded root, but with nothing supplied they read the user's global `~/.claude` — which is a live gate-bypass hazard for inherited `permissions.allow` entries, recorded as a known gap in claude-code-provider.md. The env also carries `CLAUDE_CODE_EXECUTABLE` (claude backend only, set in `_spawn` when unset): the adapter delegates the model turn to `@anthropic-ai/claude-agent-sdk`, which needs a per-platform native Claude binary (~250 MB each) shipped as npm `optionalDependencies` that the website install omits — so the vendored closure does **not** include it and the SDK fails `session/new` with `Claude native binary not found for <platform>`. The SDK does **not** search PATH for `claude` itself (so the host merely having the external agent CLI installed is not enough), and bundling a quarter-GB binary per platform is not viable; instead `_resolve_claude_code_executable` finds an existing `claude` (`CLAUDE_CODE_EXECUTABLE` override → `mise which claude` → augmented PATH incl. `~/.toolbox/bin`, where a managed distribution may ship the external agent CLI) and the adapter forwards it to the SDK as `pathToClaudeCodeExecutable` (no version check). If none is found the var is left unset (with a warning) so the adapter's native-binary error surfaces rather than a guessed bad path; an explicit operator-set value always wins.
- `"claude"` (`ACP_BACKEND_CLAUDE`): `claude-agent-acp` (resolved by `_resolve_claude_acp_bin` → `(list[str] | None, str)` (argv plus the augmented PATH actually searched)). Resolution order: `CLAUDE_AGENT_ACP_BIN` env var, then a **project-local copy** (`_resolve_vendored_claude_acp` — `<node_modules>/@agentclientprotocol/claude-agent-acp/dist/index.js` found under the package's optional `_vendor/node_modules` or under `KIROCREW_PROJECT_DIR/node_modules`; needs no global npm install or network at gateway runtime), then `mise which claude-agent-acp` (respects MISE_DATA_DIR and all mise config), then a direct glob under mise's Node installs dir (`_mise_node_installs_dir` — `<mise-data>/installs/node`, root from `env.mise_data_dir` so MISE_DATA_DIR / XDG_DATA_HOME are honoured), then augmented PATH (`env.augmented_path` — mise shims, `~/.npm-packages/bin`, `~/.volta/bin`, `/opt/homebrew/bin`, plus EVERY per-version manager bin dir via `env.node_all_bin_dirs` (mise/asdf/nvm/fnm, all installed versions — a global npm binary can live under any of them), so a non-login launchd/systemd gateway also finds globally-installed binaries). This build does **not** ship the adapter: neither `setup.py` nor `website/package.json` carries it, so the operator installs it (`npm i -g @agentclientprotocol/claude-agent-acp`, the command `agent_sdk.backend_install` prints) or drops a copy into one of the roots above. A copy there must include the adapter's full dependency closure — npm hoists deps like `@agentclientprotocol/sdk` flat, and the adapter package alone crashes the ESM loader with `ERR_MODULE_NOT_FOUND`. `_resolve_vendored_claude_acp` accepts a root only when the hoisted dependency marker `@agentclientprotocol/sdk` is present alongside the entry, so an incomplete vendored copy is skipped in favour of a complete one instead of being spawned and crashed. For scripts under mise installs, returns `[node_binary, script_path]` to bypass `#!/usr/bin/env node` shebang resolution which fails in non-interactive daemon contexts. For standalone binaries, returns `[binary_path]`. Pre-spawn the client writes `<work_dir>/.claude/settings.local.json` with `defaultMode: default` so the adapter routes every tool decision back to Kiro Crew via `session/request_permission`. This makes claude-agent-acp participate in the same approve / trust_reads / trust / yolo protocol as kiro-cli — dashboard, subagents, channel agents, cron, and heartbeat all share the path. Kiro Crew still enforces per-tool security via `HooksConfig.auto_deny_tools` (evaluated by `HookManager.on_tool_call` in `hooks.py`) on every `session/request_permission` event. `CLAUDE_CONFIG_DIR` (an isolated config root, distinct from the project-scope `<work_dir>/.claude/settings.local.json` the client writes itself) is **not** set by this core: `_spawn` merges a caller's `extra_env` into the child environment, so an edition can point the adapter's `SettingsManager` and the SDK at a seeded root, but with nothing supplied they read the user's global `~/.claude` — which is a live gate-bypass hazard for inherited `permissions.allow` entries, recorded as a known gap in claude-code-provider.md. The env also carries `CLAUDE_CODE_EXECUTABLE` (claude backend only, set in `_spawn` when unset): the adapter delegates the model turn to `@anthropic-ai/claude-agent-sdk`, which needs a per-platform native Claude binary (~250 MB each) shipped as npm `optionalDependencies` that the website install omits — so the vendored closure does **not** include it and the SDK fails `session/new` with `Claude native binary not found for <platform>`. The SDK does **not** search PATH for `claude` itself (so the host merely having the external agent CLI installed is not enough), and bundling a quarter-GB binary per platform is not viable; instead `_point_adapter_at_claude_cli` names an existing `claude` (an operator-set `CLAUDE_CODE_EXECUTABLE` wins; else `_resolve_claude_code_executable`: `mise which claude` → augmented PATH incl. `~/.toolbox/bin`, where a managed distribution may ship the external agent CLI; no version check). It does not hand that path to the adapter directly: `CLAUDE_CODE_EXECUTABLE` is set to **`acp/claude_launcher.mjs`** and the real CLI travels in `KIROCREW_CLAUDE_CODE_EXECUTABLE`. The SDK runs a `.mjs` executable with node, and the launcher drops `--allow-dangerously-skip-permissions` (which the adapter adds for every non-root session) before it starts the real CLI with every other argument, stdio and the environment unchanged, `CLAUDE_CODE_EXECUTABLE` set back to the real path — see [claude-code-provider.md](claude-code-provider.md#the-bypass-capability-is-withheld-by-a-launcher). If no CLI is found the vars are left unset (with a warning) so the adapter's native-binary error surfaces rather than a guessed bad path; a launcher missing from the install falls back to the direct path, with a warning. The resolution runs off the loop through `_to_thread_guarding_sandbox`.

When the Claude adapter is not found, the spawn error reports the augmented PATH
captured by that resolution attempt. The failed result and its PATH are cached
Expand Down
61 changes: 56 additions & 5 deletions docs/system-specs/modules/claude-code-provider.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,12 +48,13 @@ plain public build:
returns `(argv, searched_path)`; the result is memoized process-wide in
`_claude_acp_argv_cache`, so the search runs once and the "not found" message
names exactly the directories that were searched.
- `_resolve_claude_code_executable()` finds the `claude` CLI and `_spawn` exports
it as `CLAUDE_CODE_EXECUTABLE` when the caller has not set one. The adapter
forwards it to `@anthropic-ai/claude-agent-sdk` as
`pathToClaudeCodeExecutable`; without it the SDK fails `session/new` with
- `_point_adapter_at_claude_cli()` names the `claude` CLI (an operator-set
`CLAUDE_CODE_EXECUTABLE` wins, else `_resolve_claude_code_executable()`). The
adapter forwards `CLAUDE_CODE_EXECUTABLE` to `@anthropic-ai/claude-agent-sdk`
as `pathToClaudeCodeExecutable`; without it the SDK fails `session/new` with
"Claude native binary not found", because it does not search `PATH` for
`claude` on its own.
`claude` on its own. Crew points that variable at its own launcher rather than
at the CLI; see below.
- The adapter is a **public** npm package, `CLAUDE_ACP_NPM_PKG =
"@agentclientprotocol/claude-agent-acp"`. Nothing on this path is
edition-private.
Expand Down Expand Up @@ -124,6 +125,56 @@ the untrusted copy being read at all. Whether `claude-agent-acp` forwards either
ACP is not answered in this repository, and is the prerequisite for Crew gating
*every* Claude tool call rather than every call Claude asks about.

### The bypass capability is withheld by a launcher

The adapter sets the Agent SDK option `allowDangerouslySkipPermissions` for every
session that is not running as root (`ALLOW_BYPASS = !IS_ROOT ||
!!process.env.IS_SANDBOX`), and assigns it after spreading the caller's
`_meta.claudeCode.options`, so a host cannot turn it off over ACP. The SDK turns
it into `--allow-dangerously-skip-permissions` on the `claude` command line: the
*capability* to enter `bypassPermissions`, the one mode in which the adapter never
sends `session/request_permission` at all. Crew never selects that mode
(`CC_PERMISSION_MODE_BYPASS` is named only so guards have one spelling), and it
does not ship the adapter, so it cannot patch that line either.

What Crew does own is `CLAUDE_CODE_EXECUTABLE`. `_point_adapter_at_claude_cli`
sets it to `acp/claude_launcher.mjs` and passes the real CLI in
`KIROCREW_CLAUDE_CODE_EXECUTABLE`. The SDK runs a `.mjs` executable with node,
and the launcher drops exactly that one flag, then starts the real CLI with
every other argument in order, stdio inherited, the exit status and a
terminating signal propagated, and `CLAUDE_CODE_EXECUTABLE` set back to the real
path so the CLI's own environment is the one it would have had without the hop.
The launcher carries a `#!/usr/bin/env node` shebang and the executable bit,
because the adapter also spawns `CLAUDE_CODE_EXECUTABLE` directly for `claude
auth status`; without them that spawn fails with `EACCES` and every session logs
an auth-status failure even though the session itself runs.

On Windows the launcher is not used: `_point_adapter_at_claude_cli` starts the
CLI directly there, the pre-launcher path, and logs that the capability is not
withheld. An npm-installed `claude` resolves to a `.cmd` shim on Windows, and
neither the SDK running a `.mjs` executable under node on win32 nor a cmd.exe
routing of that shim has been exercised on a Windows host; a wrong guess on
either would fail every Windows Claude session at `session/new` where the
direct path works today. Enabling the launcher on Windows waits on an
end-to-end verification there, and is a change to this paragraph plus
`test_windows_starts_the_cli_directly_until_verified`.
The operator's choice of binary is kept; only the capability request is
withheld. A CLI that refuses the flag in its environment — it does so as root,
for example — therefore starts instead of failing `session/new` with `Claude
Code process exited with code 1`.

Scope, stated exactly: the launcher withholds the capability flag and nothing
else. An explicit `--permission-mode bypassPermissions` — which the adapter
passes when a settings file Crew did not author sets `defaultMode` to it — goes
through unchanged, so the inherited-settings boundary described above and in
the known gap below is not closed by this. Such a session still starts: the CLI
accepts `--permission-mode bypassPermissions` without the capability flag when
not running as root (verified on Claude Code 2.1.269), and as root it refuses
exactly as it did before the launcher existed. A launcher missing from the install
falls back to starting the CLI directly, with a warning. Pinned by
`test/test_claude_launcher.py`, which runs the launcher under node against fake
CLIs and pins that the kiro spawn gets neither variable.

### MCP tools on a Claude session

The `claude-agent-acp` adapter reads **no** agent file: the `mcpServers` array on
Expand Down
4 changes: 4 additions & 0 deletions setup.cfg
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,10 @@ kiro_crew =
# Without this entry the `apple` STT provider silently reports unavailable on
# every pip/DMG install while working perfectly from a source checkout.
apple_speech/*.swift
# Launcher the claude-agent-acp adapter's SDK runs in place of the claude CLI
# (acp/client.py, _point_adapter_at_claude_cli). Without it every Claude
# session falls back to starting the CLI directly.
acp/claude_launcher.mjs
config/defaults.json
config/prompt.md
config/prompt-orchestrator.md
Expand Down
68 changes: 68 additions & 0 deletions src/kiro_crew/acp/claude_launcher.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
#!/usr/bin/env node
// Runs the claude CLI for the claude-agent-acp adapter without asking for the
// bypassPermissions capability.
//
// The adapter sets the Agent SDK option allowDangerouslySkipPermissions for
// every session that is not running as root, and the SDK turns that into
// --allow-dangerously-skip-permissions on the CLI command line. That flag is
// the capability to enter bypassPermissions, the one permission mode in which
// the adapter stops sending session/request_permission, so a session in it
// never reaches the host gate. Kiro Crew never selects that mode, so this
// launcher drops the flag before it starts the real CLI. A CLI that refuses
// the flag in its environment (it does so as root, for example) then starts
// normally instead of failing session/new.
//
// Everything else passes through: the remaining arguments in order, stdio,
// and the environment. An explicit --permission-mode is not rewritten.
//
// Wiring (acp/client.py): CLAUDE_CODE_EXECUTABLE points here, which makes the
// SDK run this file with node, and KIROCREW_CLAUDE_CODE_EXECUTABLE names the
// real CLI. The child sees CLAUDE_CODE_EXECUTABLE set back to the real CLI and
// no KIROCREW_CLAUDE_CODE_EXECUTABLE, so its environment is the one it would
// have had without this hop.
import { spawn } from 'node:child_process'

const TARGET_ENV = 'KIROCREW_CLAUDE_CODE_EXECUTABLE'
const DROPPED_FLAGS = new Set(['--allow-dangerously-skip-permissions'])
// A JavaScript entry point cannot be exec'd on every platform, so run it with
// this node, the way the SDK itself runs a script-valued executable.
const SCRIPT_SUFFIXES = ['.js', '.mjs', '.cjs']
// Exit status when the real CLI could not be started at all.
const EXIT_CANNOT_EXECUTE = 127

const target = process.env[TARGET_ENV]
if (!target) {
process.stderr.write(`claude launcher: ${TARGET_ENV} is not set\n`)
process.exit(EXIT_CANNOT_EXECUTE)
}

const args = process.argv.slice(2).filter((arg) => !DROPPED_FLAGS.has(arg))
const env = { ...process.env, CLAUDE_CODE_EXECUTABLE: target }
delete env[TARGET_ENV]

const isScript = SCRIPT_SUFFIXES.some((suffix) => target.toLowerCase().endsWith(suffix))
const command = isScript ? process.execPath : target
const argv = isScript ? [target, ...args] : args

const child = spawn(command, argv, { stdio: 'inherit', env, windowsHide: true })

for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
process.on(signal, () => {
if (child.exitCode === null && child.signalCode === null) child.kill(signal)
})
}

child.on('error', (err) => {
process.stderr.write(`claude launcher: cannot start ${target}: ${err.message}\n`)
process.exit(EXIT_CANNOT_EXECUTE)
})

child.on('exit', (code, signal) => {
if (signal) {
// Die the way the child died, so the SDK sees the same termination.
process.removeAllListeners(signal)
process.kill(process.pid, signal)
return
}
process.exit(code ?? 1)
})
Loading
Loading