Files
PaperClipAI/packages
DottaandClaude Opus 5.5 45c3f4caa2 fix(connectors): require an install before an agent reaches a plugin connector (#22237)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Plugins can add connectors that serve their own tools (`transport:
"plugin"`, #22004, #22019, #22201)
> - The activation rule is that an agent gets a connector's tools only
through an install of an active connection for that agent
> - An agent with no install could still list and call a plugin
connector's tools, and the plugin worker ran them with that agent's run
context
> - This pull request makes the tool access policy require the install
for plugin-served connections
> - The benefit is that a plugin connector reaches only the agents it is
installed for

## Linked Issues or Issue Description

Refs #22004
Refs #22019
Refs #22201

**Subsystem affected**
Tool access policy and tool gateway (plugin-served connectors).

**Problem or motivation**
A plugin connection was installed for agent A only. Agent B, a standard
agent with no install, called one of its tools. The plugin worker got a
run context with B's agent id.

**Root cause**
An install gives access only through the connection's app profile
binding. The policy does not check installs. For an agent outside that
profile, the policy goes on to its other allow routes. The common route
is the unscoped `tools:use` grant that every new standard agent receives
(`NEW_STANDARD_AGENT_DEFAULT_GRANT_KEYS`). `governedByConnectionProfile`
is false for B, because B is not bound to the connection's profile. So
`explicitGrant` allowed the tool for discovery and invocation.
Organization-grant connections ran the worker. Per-agent connections
listed the tools and reached grant resolution.

**Expected behavior**
An agent without an install for the connection (or a company install)
sees no tools and cannot call them. An installed agent is not affected.

## What Changed

- `server/src/services/tool-access-policy.ts`: for an agent caller on a
connection whose stored transport is `plugin`, deny with the new reason
`deny_connection_not_installed` unless an install exists for that agent
or the company. The check runs before profiles, grants, trust rules and
allow policies, so none of them can replace the install. It reads the
transport from the stored connection, not from the caller. The install
read uses the decision cache, so a listing batch reads it once per
connection.
- `packages/shared/src/types/tool-access.ts`: add
`deny_connection_not_installed` to `ToolAccessReasonCode`.
- `doc/connections/CONNECTOR-PLAYBOOK.md`: document the rule.
- Legacy plugin tools (`paperclip_plugin`) keep their own
implicit-install gate and are not changed.

## Verification

- New `server/src/__tests__/plugin-connector-install-gate.test.ts`
(embedded Postgres, real routes). Both agents get the default
standard-agent grants, including the unscoped `tools:use`. For an
organization-grant connection and a per-agent connection installed for A
only:
- A lists the tool through its gateway session and its Paperclip Runner
assigned-tool gateway, and a call reaches the worker.
- B (with its own install of an unrelated connection) lists none of them
in either path.
- B's direct call by name through its gateway session, its runner
gateway, and the runner's `paperclip_call_assigned_tool` is refused. The
worker is never called.
  - Before the fix, both cases failed: B listed the tool.
- Regression suites pass: `tool-access-policy-service`,
`tool-access-policy-index`, `tool-gateway`, `tool-gateway-service`,
`tool-gateway-*`, `prompt-injection-gateway`,
`plugin-connectors-plugin-transport` (legacy plugin tools),
`plugin-connectors-circleback-parity`, `plugin-connector-agent-grant`,
`heartbeat-runtime-mcp-servers`, `run-preparation`,
`tool-access-service`, `generic-mcp-connection`,
`remote-mcp-connectors`, `railway-connection`, `aws-mcp-connector`,
`mcp-protocol-versions`, `google-workspace-*`.
- `tsc --noEmit` passes for `server`, `packages/shared` and `ui` source.

## Risks

- Behavior change: an uninstalled agent loses access to plugin-served
connection tools it reached before through a general grant, a trust rule
or an allow policy. That access broke the activation rule. Installed
agents and company installs are not affected.
- The board's per-agent access check now shows
`deny_connection_not_installed` for agents without an install.
- Built-in (non-plugin) connections are not changed by this pull
request. They have the same policy path. Whether to require installs for
them is a separate decision, because existing setups may depend on it.
- No migration.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edits, test runs).

## 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
- [x] 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>
2026-11-18 17:34:09 -06:00
..