## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents run on AI accounts that people connect as AI connections
> - Before a run, `aiConnectionService.select` resolves the agent's
binding to one account grant and checks who may use it
> - The grant-kind checks cover only the `responsible_user`, `shared`
and `delegated` modes
> - Every caller parses the binding first, so no other mode reaches
`select` today. But if one did, it would skip the grant-kind checks
> - This pull request rejects any other mode before `select` reads any
data
> - The benefit is that an authorization check cannot be skipped through
a bad binding in the future
## Linked Issues or Issue Description
No issue exists. The new test typecheck in #18739 showed that a test
passed `mode: "connection"`, which is not a valid mode. #18739 fixed the
test and listed the production question.
**What existing behavior does this improve?**
`select` in `server/src/services/ai-connections.ts` reads
`binding.grantId` for every mode except `responsible_user`. It checks
the grant kind only when the mode is `shared` or `delegated`.
**Current behavior**
All runtime callers parse the binding with
`aiRuntimeConnectionBindingSchema` or `aiConnectionBindingSchema` first
(`heartbeat.ts`, `agent-harness-verification.ts`, `routes/agents.ts`).
So no live path sends an unknown mode. If a future caller skipped
parsing, an unknown mode would pass with no grant-kind check.
**Proposed behavior**
`select` rejects an unknown mode with the existing
`ai_connection_incompatible` failure (422), before it reads any data.
**Reason and benefit**
A guard in the owner of the check is cheaper than trusting every future
caller.
**Breaking changes**
None. Valid bindings behave the same.
## What Changed
- `server/src/services/ai-connections.ts`: `select` throws
`ai_connection_incompatible` for any mode other than `responsible_user`,
`shared` or `delegated`.
- `server/src/__tests__/ai-connection-binding-mode.test.ts`: new test.
It sends `mode: "connection"` and expects a 422 with no database read.
## Verification
- `pnpm exec vitest run
server/src/__tests__/ai-connection-binding-mode.test.ts`: passes.
Without the service change, the same test fails because `select` reads
the database.
- `pnpm exec vitest run server/src/__tests__/ai-connections.test.ts
server/src/__tests__/agent-hire-ai-connections.test.ts
server/src/__tests__/ai-connection-binding-mode.test.ts`: 3 files, 243
tests pass.
- `cd server && pnpm typecheck`: passes. This includes the source layers
and the three test-tree shards.
- Not run locally: the full `pnpm test:run` and the root `pnpm build`.
Required CI covers them.
## Risks
- Low risk. The new check only rejects bindings that the schemas already
reject.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits) and extended thinking.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
