fix: attach local overlay config routing

[ian-pascoe]

Summary

• Preserve the caller's CAPLETS_CONFIG and CAPLETS_PROJECT_CONFIG paths when running caplets attach.
• Pass those paths into the native composite service so local overlay handles come from the intended config instead of the default user config.
• Route local Code Mode-only overlay handles locally instead of falling through to the remote attach client.
• Add a patch changeset for @caplets/core and caplets.

Root Cause

caplets attach resolved the remote target correctly, but the attach serve path did not forward the local overlay config paths into createNativeCapletsService. That made attached clients load local overlay Caplets from the default user config root, which could expose unrelated handles such as ast-grep, context7, linear, lsp, osv, or sourcegraph.

Validation

• PNPM_HOME=/opt/homebrew/bin pnpm --filter @caplets/core test -- test/attach-cli.test.ts
• PNPM_HOME=/opt/homebrew/bin pnpm --filter @caplets/core test -- test/native-remote.test.ts
• PNPM_HOME=/opt/homebrew/bin pnpm format:check
• PNPM_HOME=/opt/homebrew/bin pnpm typecheck
• Pre-push pnpm verify completed successfully: format:check, lint, code-mode:check-api, typecheck, schema:check, test, benchmark:check, and build.

Summary by CodeRabbit

• Bug Fixes

  • Code Mode local overlays now execute locally when attached to remote services instead of being forwarded remotely.

• New Features

  • caplets attach now preserves the caller's configuration paths for proper local overlay handling with intended configurations.

[coderabbitai]

Warning

Review limit reached

@ian-pascoe, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 32 minutes and 21 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 98a76b14-addf-4fcc-b798-7ee8188b2fd4

📥 Commits

Reviewing files that changed from the base of the PR and between e8eccaf and 50a4d54.

📒 Files selected for processing (4)

• packages/core/src/attach/options.ts
• packages/core/src/native/service.ts
• packages/core/test/attach-cli.test.ts
• packages/core/test/native-remote.test.ts

📝 Walkthrough

Walkthrough

AttachServeOptions gains configPath and projectConfigPath fields resolved from CAPLETS_CONFIG/CAPLETS_PROJECT_CONFIG env vars and forwarded into createNativeCapletsService. CompositeNativeCapletsService.execute switches from a direct tool-ID equality check to serviceHasCaplet, enabling Code Mode codeModeRun-nested caplets to be routed locally. Dev environment configs are updated to reference local.config.json.

Changes

Attach config path forwarding and Code Mode local routing

Layer / File(s)	Summary
Config path propagation through attach options and server packages/core/src/attach/options.ts, packages/core/src/attach/server.ts, .codex/config.toml, .caplets/config.json, .changeset/tame-cups-attach.md	AttachServeOptions gains required configPath and projectConfigPath fields; resolveAttachServeOptions reads them from CAPLETS_CONFIG/CAPLETS_PROJECT_CONFIG env vars or falls back to resolver defaults; createAttachNativeService forwards both into createNativeCapletsService; dev MCP server env blocks are updated to use local.config.json.
Code Mode local caplet routing fix and tests packages/core/src/native/service.ts, packages/core/test/native-remote.test.ts, packages/core/test/attach-cli.test.ts	CompositeNativeCapletsService.execute replaces direct tool.caplet === capletId with serviceHasCaplet(this.local, capletId) so codeModeRun-nested caplet IDs are correctly routed locally; new test asserts a mocked local Code Mode handle executes locally without reaching the remote; CLI test asserts configPath/projectConfigPath appear in attach options.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• spiritledsoftware/caplets#78: Implements the composite remote/local overlay service in packages/core/src/native/service.ts, directly related to the serviceHasCaplet routing fix in this PR.

Poem

🐰 A config path lost? No more!
The attach command now knows the score,
CAPLETS_CONFIG stays in hand,
Code Mode runs local as planned,
And nested caplets find their shore! 🗂️

🚥 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix: attach local overlay config routing' accurately describes the main change: fixing configuration path preservation and routing in the attach command.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-attach-overlay-config

---

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.}

[greptile-apps]

Greptile Summary

This PR fixes caplets attach so local overlay Caplets load from the caller's intended config paths (CAPLETS_CONFIG / CAPLETS_PROJECT_CONFIG) rather than always falling back to the default user config root. It also routes Code Mode-only local overlay handles locally instead of forwarding them to the remote attach client.

• attach/options.ts + attach/server.ts: Capture CAPLETS_CONFIG and CAPLETS_PROJECT_CONFIG from the environment when resolving attach options, then forward those resolved paths into createNativeCapletsService, closing the gap that exposed unrelated handles from the default config.
• native/service.ts: Replaces the inline listTools().some() check in execute() with the shared serviceHasCaplet helper (which understands codeModeCaplets), and extends serviceHasCaplet to also match by tool.sourceCaplet so that remote direct tools correctly shadow local Code Mode handles with the same caplet ID.

Confidence Score: 5/5

Safe to merge — the changes are targeted and additive, closing a config-path leak without altering any unrelated code paths.

All three code changes are focused: env-var capture in options, forwarding in server, and two small routing corrections in service. Each change is covered by a new test that exercises the exact scenario it fixes. The serviceHasCaplet expansion to sourceCaplet is consistent with how mergeTools() already uses sourceCaplet ?? caplet throughout, and the new test for remote direct tool shadowing confirms the edge case is handled correctly.

No files require special attention.

Important Files Changed

Filename	Overview
packages/core/src/attach/options.ts	Adds configPath and projectConfigPath to AttachServeOptions, resolved from CAPLETS_CONFIG/CAPLETS_PROJECT_CONFIG env vars with correct fallbacks to resolveConfigPath/resolveProjectConfigPath.
packages/core/src/attach/server.ts	Threads the new configPath and projectConfigPath fields through to createNativeCapletsService, completing the fix for local overlay config routing.
packages/core/src/native/service.ts	Two targeted fixes: execute() now uses serviceHasCaplet for local (correctly handles codeModeCaplets), and serviceHasCaplet now checks sourceCaplet so remote direct tools shadow same-ID local Code Mode handles.
packages/core/test/attach-cli.test.ts	Adds two well-scoped tests: one verifying env-var config paths flow through attach options, another verifying --project-root determines the default projectConfigPath.
packages/core/test/native-remote.test.ts	Adds two integration tests covering the new routing: local Code Mode handles execute locally, and remote direct tools correctly prevent local Code Mode handles from being routed locally.

Sequence Diagram

sequenceDiagram
    participant CLI as caplets attach (CLI)
    participant Opts as resolveAttachServeOptions
    participant Server as attachResolvedCaplets
    participant Composite as CompositeNativeCapletsService
    participant Local as LocalOverlayService
    participant Remote as RemoteNativeCapletsService

    CLI->>Opts: "env{ CAPLETS_CONFIG, CAPLETS_PROJECT_CONFIG }"
    Opts->>Opts: resolveConfigPath(env.CAPLETS_CONFIG)
    Opts->>Opts: resolveProjectConfigPath(projectRoot)
    Opts-->>Server: "AttachServeOptions{ configPath, projectConfigPath }"
    Server->>Composite: "createNativeCapletsService({ configPath, projectConfigPath })"
    Composite->>Local: createLocalOverlayService (uses configPath/projectConfigPath)
    Composite->>Remote: createRemoteService

    Note over Composite: execute(code_mode, code)
    Composite->>Composite: executeCodeModeRunNative(this, request)
    Composite->>Composite: runCodeMode calls execute(local-code, ...)

    Composite->>Local: serviceHasCaplet - codeModeCaplets includes local-code? YES
    Composite->>Remote: serviceHasCaplet - has local-code? NO
    Composite->>Local: local.execute(local-code, request)
    Local-->>Composite: result

    Note over Composite: Remote direct tool shadows local Code Mode
    Composite->>Remote: "serviceHasCaplet(shared) - sourceCaplet === shared? YES"
    Composite->>Remote: remote.execute(shared, request)

Loading

_{Reviews (2): Last reviewed commit: "fix(core): tighten attach overlay routin..." | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e8eccaf06e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".