feat(claude): implement agent configuration for workspace preparation

[fbricon]

Replaces the configurationFiles and preWorkspaceStart stubs with a real
implementation, mirroring the Cursor extension pattern (#2181).

Configuration files:

• .claude/settings.json: validates with zod, writes model label
• .claude.json: skips onboarding (hasCompletedOnboarding, trust dialog
  for /sandbox), configures MCP servers (stdio for commands, sse for
  URL-based), mirroring kdn claude.go

Both files preserve existing fields and reject invalid/non-object JSON.

There are 2 caveats for now:

• we can't automatically trust the openshell injected ANTHROPIC_API_KEY, as it looks like

ANTHROPIC_API_KEY=openshell:resolve:env:v16994155543811787309_ANTHROPIC_API_KEY

and .claude.json needs to look like

"customApiKeyResponses": {
      "approved": [
        "09_ANTHROPIC_API_KEY"
      ],
      "rejected": []
    },

So we can't predict which value to approve. I tried storing "_ANTHROPIC_API_KEY" but it didn't work

• vertex ai provider is not recognized at this point

Fixes #2169

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 73da7c9d-3e1e-47d7-831f-1581c6bf799f

📥 Commits

Reviewing files that changed from the base of the PR and between 677e04b and ad63829.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (3)

• extensions/claude/package.json
• extensions/claude/src/claude-extension.spec.ts
• extensions/claude/src/claude-extension.ts

📜 Recent review details

⏰ Context from checks skipped due to timeout. (10)

• GitHub Check: macOS
• GitHub Check: smoke-e2e-tests (dev) / ubuntu-24.04 (ollama)
• GitHub Check: smoke-e2e-tests (prod) / ubuntu-24.04 (ollama)
• GitHub Check: linter, formatters
• GitHub Check: Linux
• GitHub Check: unit tests / ubuntu-24.04
• GitHub Check: typecheck
• GitHub Check: Windows
• GitHub Check: unit tests / macos-15
• GitHub Check: unit tests / windows-2022

🧰 Additional context used

📓 Path-based instructions (4)

extensions/*/package.json

📄 CodeRabbit inference engine (AGENTS.md)

extensions/*/package.json: Extensions must declare engines.kaiden version compatibility in their package.json
Extension package.json must have main field pointing to ./dist/extension.js
Configuration properties for API keys, tokens, or secrets must use "format": "password" in the configuration definition to ensure input masking in the UI

Files:

• extensions/claude/package.json

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

Use /@/ path aliases instead of relative paths for imports outside the current directory's module group; use relative imports only for sibling modules within the same directory

Files:

• extensions/claude/src/claude-extension.spec.ts
• extensions/claude/src/claude-extension.ts

**/*.spec.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.spec.{ts,tsx,js,jsx}: Use test() instead of it() for test cases in Vitest unit tests
Use vi.mock(import('...')) for auto-mocking modules in unit tests; avoid manual mock factories when possible
Use vi.resetAllMocks() in beforeEach hooks instead of vi.clearAllMocks() for resetting mocks between tests
When an auto-mocked function or class method needs a real implementation, use vi.mocked(...) with the prototype pattern for class methods: vi.mocked(MyClass.prototype.myMethod).mockImplementation(...)

Files:

• extensions/claude/src/claude-extension.spec.ts

extensions/*/src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Register inference, container, and Kubernetes providers through the ProviderRegistry via extension APIs

Files:

• extensions/claude/src/claude-extension.spec.ts
• extensions/claude/src/claude-extension.ts

🧠 Learnings (5)

📚 Learning: 2026-05-06T11:29:33.170Z

Learnt from: MarsKubeX
Repo: openkaiden/kaiden PR: 1671
File: extensions/vertex-ai/package.json:9-11
Timestamp: 2026-05-06T11:29:33.170Z
Learning: In the openkaiden/kaiden repo, all built-in extensions under extensions/ should specify engines with kaiden: "^0.0.1" in package.json. Do not flag each extension individually; enforce a repo-wide alignment in a single PR. During reviews, verify that every extensions/*/package.json has "engines": { "kaiden": "^0.0.1" }. If a file deviates, surface the discrepancy as a single repo-wide task rather than per-file.

Applied to files:

• extensions/claude/package.json

📚 Learning: 2026-05-05T17:30:20.418Z

Learnt from: MarsKubeX
Repo: openkaiden/kaiden PR: 1671
File: extensions/vertex-ai/src/vertex-ai.ts:272-302
Timestamp: 2026-05-05T17:30:20.418Z
Learning: In the openkaiden/kaiden repo, for cloud inference provider extension code under `extensions/*/src/*.ts`, treat `ProviderConnectionStatus = 'unknown'` as a valid/expected value when registering provider connections (e.g., Gemini/Claude/Mistral/OpenAI-compatible/Vertex AI). `'unknown'` indicates the connection was set up but is not continuously monitored—so do not flag it as incorrect. Only Ollama is expected to use `'started'` because it actively polls a local server.

Applied to files:

• extensions/claude/src/claude-extension.spec.ts
• extensions/claude/src/claude-extension.ts

📚 Learning: 2026-05-05T17:44:50.991Z

Learnt from: MarsKubeX
Repo: openkaiden/kaiden PR: 1671
File: extensions/vertex-ai/src/vertex-ai.ts:363-387
Timestamp: 2026-05-05T17:44:50.991Z
Learning: In this repo (openkaiden/kaiden), do not raise a code review issue when an extension’s `InferenceProviderConnectionFactory.create` factory method implementation omits (or does not use) the optional `logger` and/or `CancellationToken` parameters in its method signature/implementation. Current extensions (e.g., Vertex AI, Gemini, Claude, Mistral, OpenAI-compatible) follow this pattern, so reviewers should treat it as acceptable for `extensions/*` TypeScript source files.

Applied to files:

• extensions/claude/src/claude-extension.spec.ts
• extensions/claude/src/claude-extension.ts

📚 Learning: 2026-05-12T10:01:14.248Z

Learnt from: MarsKubeX
Repo: openkaiden/kaiden PR: 1810
File: extensions/kdn/src/kdn-extension.ts:43-46
Timestamp: 2026-05-12T10:01:14.248Z
Learning: In this repo’s extension code, when logging from binary discovery/resolution logic (e.g., choosing/validating custom paths, extension storage locations, or bundled resource paths), it’s intentional to include full filesystem paths in `console.log`/`console.warn` (such as in `extensions/**/src/*-extension.ts`). During review, do not flag these specific full-path messages as a privacy/security issue as long as they are clearly part of the binary resolution steps. If full-path logging appears outside binary discovery/resolution, review/flag it as usual.

Applied to files:

• extensions/claude/src/claude-extension.spec.ts
• extensions/claude/src/claude-extension.ts

📚 Learning: 2026-05-12T17:14:02.153Z

Learnt from: MarsKubeX
Repo: openkaiden/kaiden PR: 1850
File: packages/renderer/src/lib/agent-workspaces/AgentWorkspaceList.svelte:66-70
Timestamp: 2026-05-12T17:14:02.153Z
Learning: When reviewing code that uses `AgentWorkspaceSummaryUI.runtime`, treat it as a required, non-null `string` per the `openkaiden/kdn-api` 0.12.0 schema. Therefore, code like `a.runtime.localeCompare(b.runtime)` is safe and should not trigger warnings about possible `undefined`/`null` values or suggestions to use nullish coalescing/optional chaining for `runtime` (unless the current local types still mark `runtime` as optional, indicating a schema/version mismatch).

Applied to files:

• extensions/claude/src/claude-extension.spec.ts
• extensions/claude/src/claude-extension.ts

🔇 Additional comments (8)

extensions/claude/package.json (1)

59-60: LGTM!

extensions/claude/src/claude-extension.ts (3)

19-31: LGTM!

---

33-45: LGTM!

---

83-145: LGTM!

extensions/claude/src/claude-extension.spec.ts (4)

19-24: LGTM!

---

110-118: LGTM!

---

120-133: LGTM!

---

135-380: LGTM!

---

📝 Walkthrough

Walkthrough

The Claude extension gains a concrete preWorkspaceStart lifecycle implementation. Two Zod schemas validate .claude/settings.json and .claude.json configuration files, which are now registered on agent activation. The hook writes the selected model label to settings, sets onboarding and trust-dialog flags, and converts workspace MCP entries to stdio/sse server definitions in .claude.json.

Changes

Claude workspace configuration lifecycle

Layer / File(s)	Summary
Zod schemas, path constants, and zod dependency extensions/claude/package.json, extensions/claude/src/claude-extension.ts	Adds zod@^4.3.5 dependency and defines ClaudeSettingsSchema, ClaudeProjectSchema, and ClaudeJsonSchema validators alongside exported CLAUDE_SETTINGS_PATH and CLAUDE_JSON_PATH constants.
configurationFiles registration and preWorkspaceStart implementation extensions/claude/src/claude-extension.ts	Replaces empty configurationFiles array and unimplemented preWorkspaceStart stub with concrete file registration and an async hook that parses, updates, and persists both config files including model label, onboarding flags, trust-dialog state, and MCP server mappings.
Tests for registration and preWorkspaceStart extensions/claude/src/claude-extension.spec.ts	Adds imports for AgentConfigurationFile and AgentWorkspaceContext, asserts two configuration files are registered at the defined paths, and covers the full preWorkspaceStart behavior across model writes, JSON validation, onboarding handling, MCP stdio/sse mapping, and field preservation.

Sequence Diagram(s)

sequenceDiagram
  participant WorkspaceOrchestrator
  participant ClaudeExtension
  participant SettingsFile as .claude/settings.json
  participant ClaudeJsonFile as .claude.json

  WorkspaceOrchestrator->>ClaudeExtension: preWorkspaceStart(AgentWorkspaceContext)
  ClaudeExtension->>SettingsFile: read current content
  SettingsFile-->>ClaudeExtension: raw JSON string
  ClaudeExtension->>ClaudeExtension: ClaudeSettingsSchema.parse(content)
  ClaudeExtension->>SettingsFile: update({ ...existing, model: context.model.label })
  ClaudeExtension->>ClaudeJsonFile: read current content
  ClaudeJsonFile-->>ClaudeExtension: raw JSON string
  ClaudeExtension->>ClaudeExtension: ClaudeJsonSchema.parse(content)
  ClaudeExtension->>ClaudeExtension: set hasCompletedOnboarding + hasTrustDialogAccepted
  ClaudeExtension->>ClaudeExtension: map mcp.commands → stdio mcpServers
  ClaudeExtension->>ClaudeExtension: map mcp.servers → sse mcpServers
  ClaudeExtension->>ClaudeJsonFile: update(JSON.stringify(updatedConfig))
  ClaudeExtension-->>WorkspaceOrchestrator: resolved

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• openkaiden/kaiden#2168: Introduced configurationFiles and the preWorkspaceStart hook on the agent registry API that this PR directly implements for the Claude extension.
• openkaiden/kaiden#2187: Wired the agent.preWorkspaceStart call into OpenShell workspace creation and handled writable agent configuration files, which is the caller side of the hook implemented here.
• openkaiden/kaiden#2196: Added context.workspace.mcp fields to AgentWorkspaceContext that the new preWorkspaceStart logic reads to build mcpServers entries.

Suggested reviewers

• benoitf
• jeffmaury
• gastoner

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: implementing agent configuration for workspace preparation in the Claude extension.
Description check	✅ Passed	The description clearly explains the implementation of configurationFiles and preWorkspaceStart, details the two configuration files and their purposes, and notes known limitations.
Linked Issues check	✅ Passed	The PR implements the requirements from #2169 by adding agent configuration capabilities with configurationFiles and preWorkspaceStart hooks for workspace preparation.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing agent configuration as specified in #2169: adding zod dependency, implementing configuration files, tests, and workspace preparation logic.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[fbricon]

another issue is skills don't seem to be listed, even though they've been added to the sandbox

[codecov]

Codecov Report

❌ Patch coverage is 90.00000% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
extensions/claude/src/claude-extension.ts	90.00%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!