mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 20:12:20 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The board controls which agents can hire, with the "Can create
agents" permission on each agent
> - A CEO agent with that permission turned off could still hire,
because the CEO role allowed hiring before the server read the saved
permission
> - In chat, a CEO agent asked to hire then created the agent through
the `hire_agent` tool, against the board's policy
> - This pull request makes the saved permission decide, and uses the
CEO role only for old rows that never saved a value
> - It also tells a denied agent that the denial is final and where a
person can act
> - The benefit is that the permissions page and the server now agree,
and the board can trust a hiring denial
## Linked Issues or Issue Description
**What happened**
A board user turned off "Can create agents" for a CEO agent. Then the
user asked the CEO in chat to hire a QA engineer. The CEO called
`hire_agent` (`POST /api/companies/{companyId}/agent-hires`). The server
returned 201 and created the agent. The legacy creator rule allowed any
agent with `role: "ceo"` before it read `permissions.canCreateAgents`.
**Expected behavior**
An explicit `canCreateAgents: false` denies hiring for every role,
including CEO. The agent gets a 403 that says the denial is final, and
it sends the person to the hire form or to its permissions page.
**Steps to reproduce**
1. Create a company with a CEO agent.
2. On the CEO's permissions page, turn off "Can create agents".
3. In chat with the CEO, send "Hire a QA engineer named Morgan."
4. See that a new agent named Morgan exists.
Found by the chat eval case `agents.hire-denied`. Related: #19614 (chat
eval harness).
## What Changed
- `canCreateAgentsLegacy` (authorization) uses the role-aware permission
normalization. A CEO keeps hiring unless the board recorded a hiring
denial.
- New `ceoHiringDeniedBy` record in `permissions` (`{ actorType,
actorId, at }`). `PATCH /agents/:id/permissions` writes it when an
authorized actor saves a CEO's hiring as off (an earlier record is
kept). The page shows the effective value, so a saved off is the board's
choice. Turning the toggle off also removes an explicit `agents:create`
grant. A saved `canCreateAgents: false` restricts a CEO only together
with this record.
- Reads report the effective value. A CEO row with no value, or with an
unrecorded false, shows hiring on. A CEO with a recorded denial shows it
off.
- Create and hire inputs cannot supply the record. Configuration updates
keep an existing record unless they turn hiring on. Company export keeps
a CEO's recorded denial, and import restores it, stamped by the
importing user.
- `PATCH /agents/:id/permissions`: an agent actor needs `agents:create`
to change `canCreateAgents`. A denied CEO cannot restore hiring for
itself or grant it to another agent.
- `assertCanCreateAgentsForCompany` adds a final, actionable sentence to
an agent's `agents:create` denial on hiring routes only (`POST /agents`,
`POST /agent-hires`, the hiring toggle on `PATCH /permissions`).
- `POST /api/companies/:companyId/imports/apply` (CEO-safe import): an
agent import that would create agents needs an `agents:create` decision
before any write. Before, any CEO agent could create agents this way.
Import also removes an existing `agents:create` grant when it restores a
CEO's denial.
- Chat guidance tells the agent to link `/<prefix>/agents/new` and its
own `/permissions` page when it cannot hire.
- Regression tests: authorization (a recorded denial is honored; an
unrecorded false keeps CEO hiring), normalization, route tests (denial
text, self-escalation, the record is written only when a CEO is turned
off), service tests for the permission and configuration write paths,
chat guidance text.
### Why a recorded denial and not a plain false
These normal paths save `canCreateAgents: false` on a CEO without a
board choice:
- The permissions page posts the full object. Before this change, a
legacy CEO row with `{}` was read as false, so saving any other toggle
stored false.
- A company import that updates an existing agent normalizes the
manifest permissions in the "stored" context. A manifest without the
field stores false. Export drops false values, so this is common.
- Low-trust creation stores false. If the trust preset later changes to
standard, the false remains.
These paths store true or nothing for a CEO: onboarding seed
(`requestHire`, create context: true), teams-catalog and import creation
(create context: true; the bundled catalog sets true only for a CTO),
built-in agents (no CEO roles), migrations and seed data (no writes to
this field).
A plain-false rule would remove hiring from those CEOs. With the record,
existing data keeps today's behavior, and no data migration is
necessary.
## Verification
- `cd server && npx vitest run
src/__tests__/agent-permissions-service.test.ts
src/__tests__/authorization-service.test.ts
src/__tests__/agent-permissions-routes.test.ts
src/__tests__/agent-conversations.test.ts` passes (244 tests).
- `teams-catalog-service`, `company-portability` and `built-in-agents`
tests pass (189 tests).
- Red check: the new authorization test fails without the
`authorization.ts` change.
- `npx tsc --noEmit -p server` passes.
- End to end: the chat eval `agents.hire-denied` on the OpenCode runner.
The baseline run (Actions run 42478870236) created Morgan through
`hire_agent`. With this fix (Actions run 42480936881), the agent got the
403, created no agent, and linked the hire form and its permissions
page. The eval clicked the rendered hire-form link.
## Risks
- Behavior change: a CEO whose hiring the board turns off after this
change can no longer hire.
- A CEO that already has a saved false keeps hiring until a board user
turns it off again on the permissions page. The page now shows such a
CEO as on, so the board can see and change it.
- A request that creates a CEO with `canCreateAgents: false` does not
restrict it. The board must turn hiring off on the permissions page.
- A CEO agent whose hiring is denied can no longer import a package that
creates agents. A board user can still import it.
- Other CEO special cases are not hiring routes: `issues.ts` lets a CEO
link approvals to issues, and `agents.ts` gives a CEO task assignment.
`teams-catalog.ts` and `llms.ts` read the normalized permissions, so
they follow the same effective value.
- The denial text is longer. No existing test compares this route's
exact error text.
## Model Used
- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code
execution in Claude Code.
## 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>
128 lines
4.9 KiB
TypeScript
128 lines
4.9 KiB
TypeScript
import { LOW_TRUST_REVIEW_PRESET, type PermissionKey } from "@paperclipai/shared";
|
|
|
|
/** Direct grants for newly activated standard agents. Existing agents are not backfilled. */
|
|
export const NEW_STANDARD_AGENT_DEFAULT_GRANT_KEYS = [
|
|
"agents:read",
|
|
"agents:configure",
|
|
"agents:suggest-changes",
|
|
"skills:create",
|
|
"skills:suggest-changes",
|
|
"tools:manage_connections",
|
|
"tools:manage_profiles",
|
|
"tools:view_audit",
|
|
"audit:view_agent_actions",
|
|
"tools:use",
|
|
"tools:manage_runtime",
|
|
"inbox:manage",
|
|
"tasks:assign",
|
|
"tasks:assign_scope",
|
|
"tasks:manage_active_checkouts",
|
|
] as const satisfies readonly PermissionKey[];
|
|
|
|
export function newStandardAgentGrantScope(
|
|
permissionKey: PermissionKey,
|
|
agentId: string,
|
|
): Record<string, unknown> | null {
|
|
if (permissionKey === "tasks:assign_scope") return { subtreeRootAgentId: agentId };
|
|
if (permissionKey === "inbox:manage") return { responsibleUserOnly: true };
|
|
return null;
|
|
}
|
|
|
|
export type NormalizedAgentPermissions = Record<string, unknown> & {
|
|
canCreateAgents: boolean;
|
|
canCreateSkills: boolean;
|
|
};
|
|
|
|
function asRecord(value: unknown): Record<string, unknown> | null {
|
|
return typeof value === "object" && value !== null && !Array.isArray(value)
|
|
? (value as Record<string, unknown>)
|
|
: null;
|
|
}
|
|
|
|
/**
|
|
* Mirrors the agent-source low-trust markers consumed by
|
|
* resolveCoreTrustPreset: the low-trust review preset (top-level or inside
|
|
* authorizationPolicy) or a low-trust boundary. Defaults must never grant
|
|
* agent-creation authority to a low-trust agent.
|
|
*/
|
|
export function permissionsImplyLowTrust(permissions: unknown): boolean {
|
|
const record = asRecord(permissions);
|
|
if (!record) return false;
|
|
const authorizationPolicy = asRecord(record.authorizationPolicy);
|
|
return (
|
|
record.trustPreset === LOW_TRUST_REVIEW_PRESET ||
|
|
authorizationPolicy?.trustPreset === LOW_TRUST_REVIEW_PRESET ||
|
|
asRecord(record.reviewPreset)?.id === LOW_TRUST_REVIEW_PRESET ||
|
|
asRecord(authorizationPolicy?.reviewPreset)?.id === LOW_TRUST_REVIEW_PRESET ||
|
|
asRecord(authorizationPolicy?.trustBoundary) !== null
|
|
);
|
|
}
|
|
|
|
/**
|
|
* "create" is the context for permissions arriving on a new-agent write: the
|
|
* hire/create default applies and the resolved value is persisted. "stored"
|
|
* is the context for rows read back from the database: a row without an
|
|
* explicit value stays fail-closed, so the default is never granted
|
|
* retroactively to legacy or malformed records at read or enforcement time.
|
|
*/
|
|
export type AgentPermissionsContext = "create" | "stored";
|
|
|
|
export function defaultAgentPermissions(
|
|
options?: { lowTrust?: boolean; context?: AgentPermissionsContext; role?: string | null },
|
|
): NormalizedAgentPermissions {
|
|
return {
|
|
// A CEO row without a recorded hiring restriction keeps its legacy hiring
|
|
// authority, so reads report what enforcement allows.
|
|
canCreateAgents: (options?.context === "create" || options?.role === "ceo") && options?.lowTrust !== true,
|
|
canCreateSkills: true,
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Records who turned off a CEO's hiring through the permissions control.
|
|
* Several ordinary writes save canCreateAgents: false without meaning to
|
|
* restrict a CEO: a full-object save of a stale read, an import update whose
|
|
* manifest omits the field, and the low-trust default. So a saved false
|
|
* restricts a CEO only together with this record.
|
|
*/
|
|
export const CEO_HIRING_DENIAL_KEY = "ceoHiringDeniedBy";
|
|
export type CeoHiringDenial = { actorType: "user" | "agent"; actorId: string | null; at: string };
|
|
|
|
export function ceoHiringDenial(permissions: unknown): CeoHiringDenial | null {
|
|
const denial = asRecord(asRecord(permissions)?.[CEO_HIRING_DENIAL_KEY]);
|
|
return denial && (denial.actorType === "user" || denial.actorType === "agent") && typeof denial.at === "string"
|
|
? { actorType: denial.actorType, actorId: typeof denial.actorId === "string" ? denial.actorId : null, at: denial.at }
|
|
: null;
|
|
}
|
|
|
|
export function normalizeAgentPermissions(
|
|
permissions: unknown,
|
|
options?: { context?: AgentPermissionsContext; role?: string | null },
|
|
): NormalizedAgentPermissions {
|
|
const lowTrust = permissionsImplyLowTrust(permissions);
|
|
const defaults = defaultAgentPermissions({
|
|
lowTrust,
|
|
context: options?.context ?? "stored",
|
|
role: options?.role,
|
|
});
|
|
const record = asRecord(permissions);
|
|
if (!record) {
|
|
return defaults;
|
|
}
|
|
|
|
const { [CEO_HIRING_DENIAL_KEY]: _denial, ...rest } = record;
|
|
const denial = ceoHiringDenial(record);
|
|
let canCreateAgents = typeof record.canCreateAgents === "boolean" ? record.canCreateAgents : defaults.canCreateAgents;
|
|
// An unrecorded false on a CEO is not a restriction the board chose.
|
|
if (options?.role === "ceo" && canCreateAgents === false && !denial) canCreateAgents = !lowTrust;
|
|
return {
|
|
...rest,
|
|
...(canCreateAgents === false && denial ? { [CEO_HIRING_DENIAL_KEY]: denial } : {}),
|
|
canCreateAgents,
|
|
canCreateSkills:
|
|
typeof record.canCreateSkills === "boolean"
|
|
? record.canCreateSkills
|
|
: defaults.canCreateSkills,
|
|
};
|
|
}
|