## Thinking Path
> - Paperclip orchestrates AI agents for zero-human companies
> - Plugin tools are how agents call into plugin-contributed
capabilities (`GET /api/plugins/tools`, `POST
/api/plugins/tools/execute`)
> - Those two routes previously required board-level authentication, so
agent-issued JWTs were rejected — agents couldn't actually use the very
tools the plugin system was built to expose to them
> - Two community PRs (#3272 by @nullEFFORT and #5549 by @aperim-agent)
independently fixed this, but both went stale against master and neither
could be merged as-is
> - This pull request lands #3272's authz-helper approach
(`assertBoardOrAgent`) rebased on current master, and adds the
regression test suite from #5549 adapted to #3272's symbol names
> - The benefit is agents can finally call plugin tools while preserving
the existing board-scoped checks for the rest of the plugin admin
surface
## What Changed
- Adds `assertBoardOrAgent(req)` helper in `server/src/routes/authz.ts`
— accepts either a board user or an agent JWT
- Applies `assertBoardOrAgent` (in place of `assertBoard`) on `GET
/api/plugins/tools` and `POST /api/plugins/tools/execute` so
agent-issued tokens can list and execute plugin tools
- Updates the file-level doc comment on `server/src/routes/plugins.ts`
to note the agent-accessible routes
- Adds `server/src/__tests__/plugin-routes-authz.test.ts` (118 lines, 34
cases) covering: agent JWT can list tools, agent JWT can execute within
its company scope, agent JWT is rejected when `runContext.companyId` is
outside its authenticated scope, agent JWT is rejected when
`runContext.agentId` does not belong to `runContext.companyId`, plus the
existing board/admin paths
## Verification
- \`pnpm vitest run server/src/__tests__/plugin-routes-authz.test.ts\` →
**34/34 passing** locally
- Diff vs master is exactly 3 files: \`authz.ts\` (+6), \`plugins.ts\`
(+5/-3), \`plugin-routes-authz.test.ts\` (+118). No other surfaces
touched.
## Risks
Low risk.
- Authorization is being *widened* on two specific routes (board → board
or agent), not narrowed elsewhere. Every other plugin admin route still
uses \`assertBoard\` / \`assertInstanceAdmin\` /
\`assertBoardOrgAccess\`.
- Agent JWTs already encode \`companyId\` and \`agentId\`; the existing
\`validateToolRunContextScope\` queue still enforces that an agent
cannot execute a tool against a different company or impersonate another
agent. Regression coverage for both is included.
- No schema, migration, or wire-protocol changes.
## Model Used
- Claude (Anthropic), \`claude-opus-4-7\` via Claude Code, extended
thinking enabled, tool use enabled.
## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots — N/A, server-only change
- [x] I have updated relevant documentation to reflect my changes
(file-level doc comment on \`plugins.ts\`)
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge
## Provenance / credit
This PR supersedes two community PRs that addressed the same agent-JWT
plugin-tools authz gap:
- **#3272 by @nullEFFORT** — original \`assertBoardOrAgent\` helper and
the two route changes. \`fix: allow agent JWTs to access plugin tool
endpoints\` (commit \`6991380\`) is cherry-picked here with author
attribution preserved.
- **#5549 by @aperim-agent** — regression test suite. Adapted to #3272's
symbol names (\`assertBoardOrAgent\`, three-row
\`validateToolRunContextScope\` queue) and included here.
Both originals went stale against master and could not be force-pushed
to the contributor forks from our OAuth-app-scoped tooling (workflow
files in our \`master\` introduce a \`workflow\` scope requirement on
pushes to those forks). This PR ships the same fix from our own branch
so we can land it without that blocker.
---------
Co-authored-by: Chad <chad@nulleffort.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
Devin Foley
244a5b8002