mirror of
https://github.com/agentclientprotocol/claude-agent-acp.git
synced 2026-11-05 17:01:44 +00:00
fe8b69edd4
IDEs can pass their own Claude hooks through `_meta.claudeCode.options.settings.hooks` on `session/new` and `session/load`. Before this change, any session settings replaced `CLAUDE_MODEL_CONFIG` entirely, so adding a single hook dropped the deployment's `modelOverrides` / `availableModels`. The two are now merged, and the session settings win per key. The wrapper does not merge hooks itself: Claude Code already runs the hooks of every settings tier, so user and project hooks keep running next to the session ones. Hooks stay scoped to their session, and a `session/load` with different settings recreates the query, which replaces or removes them. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
57 lines
2.8 KiB
Markdown
57 lines
2.8 KiB
Markdown
# Model Configuration
|
|
|
|
When using claude-agent-acp with alternative providers (e.g. AWS Bedrock), model IDs differ from the direct Anthropic API. The `CLAUDE_MODEL_CONFIG` environment variable lets you configure model overrides and availability at the deployment level.
|
|
|
|
## `CLAUDE_MODEL_CONFIG`
|
|
|
|
A JSON string with two optional fields:
|
|
|
|
| Field | Type | Description |
|
|
| ----------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------- |
|
|
| `modelOverrides` | `Record<string, string>` | Maps Anthropic model IDs to provider-specific model IDs (e.g. Bedrock model IDs or ARNs) |
|
|
| `availableModels` | `string[]` | Restricts which models are offered to users. Accepts aliases (`"opus"`), prefixes (`"opus-4-5"`), or full IDs |
|
|
|
|
### Examples
|
|
|
|
**Bedrock model overrides:**
|
|
|
|
```bash
|
|
CLAUDE_MODEL_CONFIG='{"modelOverrides":{"claude-opus-4-6":"us.anthropic.claude-opus-4-6-v1","claude-sonnet-4-5":"us.anthropic.claude-sonnet-4-5-v1"}}'
|
|
```
|
|
|
|
**Restrict available models:**
|
|
|
|
```bash
|
|
CLAUDE_MODEL_CONFIG='{"availableModels":["opus","sonnet"]}'
|
|
```
|
|
|
|
**Both together:**
|
|
|
|
```bash
|
|
CLAUDE_MODEL_CONFIG='{"modelOverrides":{"claude-opus-4-6":"us.anthropic.claude-opus-4-6-v1","claude-sonnet-4-5":"us.anthropic.claude-sonnet-4-5-v1"},"availableModels":["opus","sonnet"]}'
|
|
```
|
|
|
|
**Full Bedrock example:**
|
|
|
|
```bash
|
|
CLAUDE_CODE_USE_BEDROCK=1 \
|
|
AWS_REGION=us-west-2 \
|
|
CLAUDE_MODEL_CONFIG='{"modelOverrides":{"claude-opus-4-6":"us.anthropic.claude-opus-4-6-v1"}}' \
|
|
node dist/index.js
|
|
```
|
|
|
|
## Precedence
|
|
|
|
An ACP caller can provide `settings` via `_meta.claudeCode.options.settings` in `session/new` or `session/load`, as an object or a path to a settings file. The adapter merges `CLAUDE_MODEL_CONFIG` into those settings, so a caller that only adds hooks keeps the model settings. When both set the same key, the caller wins; the merge is shallow, so a caller's `modelOverrides` replaces the env var's map.
|
|
|
|
| Source | Priority |
|
|
| -------------------------------------------- | ---------------------------------------------- |
|
|
| `_meta.claudeCode.options.settings` (caller) | Highest — wins for each key it sets |
|
|
| `CLAUDE_MODEL_CONFIG` (env var) | Used for the keys that the caller does not set |
|
|
|
|
## Format details
|
|
|
|
- The value must be valid JSON. Invalid JSON will cause session creation to fail with a parse error.
|
|
- Only `modelOverrides` and `availableModels` keys are read; other keys in the JSON are ignored.
|
|
- Both fields map directly to the Claude Agent SDK's `Settings` type.
|