The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(agents): grant new agents hire permission by default (#12814)
Devin Foley54dd0f4868f8
diff --git a/doc/CLI.md b/doc/CLI.mdindex 971648137e..0cdd67107b 100644--- a/doc/CLI.md+++ b/doc/CLI.md@@ -716,8 +716,10 @@ Preview/install options:`paperclipai company current --json`, or `PAPERCLIP_COMPANY_ID` to select thetarget company. `company list` falls back to the scoped current company whenboard-wide listing is forbidden. `teams install` creates agents and therefore- requires board authentication, an `agents:create` grant, or an agent with- explicit `canCreateAgents` permission.+ requires board authentication, an `agents:create` grant, or an agent with the+ `canCreateAgents` permission (enabled by default for newly created+ standard-trust agents; low-trust agents and pre-existing agents without an+ explicit value stay disabled).- `--request-approval-on-forbidden` turns a 403 install denial into a linkedboard approval request instead of a raw failed command; use`--approval-issue-id <id>` to attach it to a specific issue. During Paperclipdiff --git a/packages/shared/src/validators/agent.ts b/packages/shared/src/validators/agent.tsindex 2be813ca6f..4a9416d14a 100644--- a/packages/shared/src/validators/agent.ts+++ b/packages/shared/src/validators/agent.ts@@ -12,7 +12,9 @@ import { agentDesiredSkillSelectionSchema } from "./adapter-skills.js";import { objectWithoutDefaults } from "./partial.js";export const agentPermissionsSchema = z.object({- canCreateAgents: z.boolean().optional().default(false),+ // No schema default: the server derives the default (enabled unless the+ // permissions record marks the agent low-trust) when the field is omitted.+ canCreateAgents: z.boolean().optional(),canCreateSkills: z.boolean().optional().default(true),trustPreset: trustPresetSchema.optional(),authorizationPolicy: trustAuthorizationPolicySchema.optional(),diff --git a/server/src/__tests__/agent-permissions-service.test.ts b/server/src/__tests__/agent-permissions-service.test.tsindex ddd7dc9b22..6f8e37e300 100644--- a/server/src/__tests__/agent-permissions-service.test.ts+++ b/server/src/__tests__/agent-permissions-service.test.ts@@ -1,37 +1,103 @@import { describe, expect, it } from "vitest";import {+ LOW_TRUST_REVIEW_PRESET,agentPermissionsSchema,updateAgentPermissionsSchema,} from "@paperclipai/shared";import {- defaultPermissionsForRole,+ defaultAgentPermissions,normalizeAgentPermissions,+ permissionsImplyLowTrust,} from "../services/agent-permissions.js";describe("agent permissions service", () => {- it("keeps agent-creation authority least-privileged by default", () => {- expect(defaultPermissionsForRole("ceo").canCreateAgents).toBe(true);- expect(defaultPermissionsForRole("CTO").canCreateAgents).toBe(false);- expect(defaultPermissionsForRole("engineering-manager").canCreateAgents).toBe(false);- expect(defaultPermissionsForRole("engineer").canCreateAgents).toBe(false);+ it("grants agent-creation authority to new agents by default", () => {+ expect(defaultAgentPermissions({ context: "create" }).canCreateAgents).toBe(true);+ expect(normalizeAgentPermissions(undefined, { context: "create" }).canCreateAgents).toBe(true);+ expect(normalizeAgentPermissions({}, { context: "create" }).canCreateAgents).toBe(true);+ expect(+ normalizeAgentPermissions({ trustPreset: "standard" }, { context: "create" }).canCreateAgents,+ ).toBe(true);});- it("enables skill creation for every role by default", () => {- expect(defaultPermissionsForRole("ceo").canCreateSkills).toBe(true);- expect(defaultPermissionsForRole("CTO").canCreateSkills).toBe(true);- expect(defaultPermissionsForRole("engineering-manager").canCreateSkills).toBe(true);- expect(defaultPermissionsForRole("engineer").canCreateSkills).toBe(true);+ it("keeps stored rows without an explicit value fail-closed", () => {+ expect(defaultAgentPermissions().canCreateAgents).toBe(false);+ expect(defaultAgentPermissions({ context: "stored" }).canCreateAgents).toBe(false);+ expect(normalizeAgentPermissions(undefined).canCreateAgents).toBe(false);+ expect(normalizeAgentPermissions({}).canCreateAgents).toBe(false);+ expect(normalizeAgentPermissions("malformed").canCreateAgents).toBe(false);+ expect(normalizeAgentPermissions([]).canCreateAgents).toBe(false);});- it("preserves explicit canCreateAgents overrides", () => {- expect(normalizeAgentPermissions({ canCreateAgents: false }, "cto").canCreateAgents).toBe(false);- expect(normalizeAgentPermissions({ canCreateAgents: true }, "engineer").canCreateAgents).toBe(true);+ it("withholds agent-creation authority from new low-trust agents", () => {+ expect(defaultAgentPermissions({ lowTrust: true, context: "create" }).canCreateAgents).toBe(false);+ expect(+ normalizeAgentPermissions(+ { trustPreset: LOW_TRUST_REVIEW_PRESET },+ { context: "create" },+ ).canCreateAgents,+ ).toBe(false);+ expect(+ normalizeAgentPermissions(+ { authorizationPolicy: { trustPreset: LOW_TRUST_REVIEW_PRESET } },+ { context: "create" },+ ).canCreateAgents,+ ).toBe(false);+ expect(+ normalizeAgentPermissions(+ { authorizationPolicy: { trustBoundary: { mode: LOW_TRUST_REVIEW_PRESET } } },+ { context: "create" },+ ).canCreateAgents,+ ).toBe(false);+ });++ it("detects low-trust markers wherever the trust policy stores them", () => {+ expect(permissionsImplyLowTrust(undefined)).toBe(false);+ expect(permissionsImplyLowTrust({})).toBe(false);+ expect(permissionsImplyLowTrust({ trustPreset: "standard" })).toBe(false);+ expect(permissionsImplyLowTrust({ trustPreset: LOW_TRUST_REVIEW_PRESET })).toBe(true);+ expect(permissionsImplyLowTrust({ reviewPreset: { id: LOW_TRUST_REVIEW_PRESET } })).toBe(true);+ expect(+ permissionsImplyLowTrust({ authorizationPolicy: { trustPreset: LOW_TRUST_REVIEW_PRESET } }),+ ).toBe(true);+ expect(+ permissionsImplyLowTrust({+ authorizationPolicy: { reviewPreset: { id: LOW_TRUST_REVIEW_PRESET } },+ }),+ ).toBe(true);+ expect(+ permissionsImplyLowTrust({+ authorizationPolicy: { trustBoundary: { mode: LOW_TRUST_REVIEW_PRESET } },+ }),+ ).toBe(true);+ });++ it("enables skill creation by default", () => {+ expect(defaultAgentPermissions().canCreateSkills).toBe(true);+ expect(defaultAgentPermissions({ lowTrust: true, context: "create" }).canCreateSkills).toBe(true);+ });++ it("preserves explicit canCreateAgents overrides in both contexts", () => {+ expect(normalizeAgentPermissions({ canCreateAgents: false }, { context: "create" }).canCreateAgents).toBe(false);+ expect(normalizeAgentPermissions({ canCreateAgents: true }).canCreateAgents).toBe(true);+ expect(+ normalizeAgentPermissions({+ canCreateAgents: true,+ trustPreset: LOW_TRUST_REVIEW_PRESET,+ }).canCreateAgents,+ ).toBe(true);});it("defaults missing skill creation permission to true and preserves explicit false", () => {- expect(normalizeAgentPermissions({}, "engineer").canCreateSkills).toBe(true);- expect(normalizeAgentPermissions({ canCreateSkills: false }, "ceo").canCreateSkills).toBe(false);- expect(normalizeAgentPermissions({ canCreateSkills: true }, "engineer").canCreateSkills).toBe(true);+ expect(normalizeAgentPermissions({}).canCreateSkills).toBe(true);+ expect(normalizeAgentPermissions({ canCreateSkills: false }).canCreateSkills).toBe(false);+ expect(normalizeAgentPermissions({ canCreateSkills: true }).canCreateSkills).toBe(true);+ });++ it("leaves omitted canCreateAgents undefined at the schema layer", () => {+ expect(agentPermissionsSchema.parse({}).canCreateAgents).toBeUndefined();+ expect(agentPermissionsSchema.parse({ canCreateAgents: false }).canCreateAgents).toBe(false);+ expect(agentPermissionsSchema.parse({ canCreateAgents: true }).canCreateAgents).toBe(true);});it("validates skill creation permission with a default-on value", () => {diff --git a/server/src/__tests__/authorization-service.test.ts b/server/src/__tests__/authorization-service.test.tsindex 871aabb27e..7a303268f4 100644--- a/server/src/__tests__/authorization-service.test.ts+++ b/server/src/__tests__/authorization-service.test.ts@@ -1928,6 +1928,71 @@ describeEmbeddedPostgres("authorization service", () => {});});+ it("grants hire authority through the persisted new-agent default", async () => {+ const company = await createCompany(db, "DefaultHire");+ // The service create path persists the create-context default+ // (canCreateAgents: true for standard trust); enforcement reads it back.+ const actorAgent = await createAgent(db, company.id, {+ role: "engineer",+ permissions: { canCreateAgents: true, canCreateSkills: true },+ });++ const decision = await authorizationService(db).decide({+ actor: { type: "agent", agentId: actorAgent.id, companyId: company.id, source: "agent_jwt" },+ action: "agents:create",+ resource: { type: "company", companyId: company.id },+ });++ expect(decision).toMatchObject({+ allowed: true,+ reason: "allow_legacy_agent_creator",+ });+ });++ it("keeps legacy rows without an explicit canCreateAgents fail-closed", async () => {+ const company = await createCompany(db, "LegacyRowFailClosed");+ const actorAgent = await createAgent(db, company.id, { role: "engineer", permissions: {} });++ const decision = await authorizationService(db).decide({+ actor: { type: "agent", agentId: actorAgent.id, companyId: company.id, source: "agent_jwt" },+ action: "agents:create",+ resource: { type: "company", companyId: company.id },+ });++ expect(decision).toMatchObject({+ allowed: false,+ reason: "deny_missing_grant",+ });+ });++ it("denies agent creation for a low-trust boundary even with explicit canCreateAgents", async () => {+ const company = await createCompany(db, "LowTrustHireDenied");+ const project = await createProject(db, company.id, "Contained");+ const actorAgent = await createAgent(db, company.id, {+ permissions: {+ canCreateAgents: true,+ trustPreset: LOW_TRUST_REVIEW_PRESET,+ authorizationPolicy: {+ trustBoundary: {+ mode: LOW_TRUST_REVIEW_PRESET,+ projectIds: [project.id],+ },+ },+ },+ });++ const decision = await authorizationService(db).decide({+ actor: { type: "agent", agentId: actorAgent.id, companyId: company.id, source: "agent_jwt" },+ action: "agents:create",+ resource: { type: "company", companyId: company.id },+ });++ expect(decision).toMatchObject({+ allowed: false,+ reason: "deny_low_trust_boundary",+ });+ });+it("denies active-checkout management outside the CEO caller company scope", async () => {const sourceCompany = await createCompany(db, "CheckoutSource");const targetCompany = await createCompany(db, "CheckoutTarget");diff --git a/server/src/services/agent-permissions.ts b/server/src/services/agent-permissions.tsindex 49eba9aa4e..e628a62ec5 100644--- a/server/src/services/agent-permissions.ts+++ b/server/src/services/agent-permissions.ts@@ -1,28 +1,68 @@+import { LOW_TRUST_REVIEW_PRESET } from "@paperclipai/shared";+export type NormalizedAgentPermissions = Record<string, unknown> & {canCreateAgents: boolean;canCreateSkills: boolean;};-export function defaultPermissionsForRole(role: string): NormalizedAgentPermissions {+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 },+): NormalizedAgentPermissions {return {- canCreateAgents: role.trim().toLowerCase() === "ceo",+ canCreateAgents: options?.context === "create" && options?.lowTrust !== true,canCreateSkills: true,};}export function normalizeAgentPermissions(permissions: unknown,- role: string,+ options?: { context?: AgentPermissionsContext },): NormalizedAgentPermissions {- const defaults = defaultPermissionsForRole(role);- if (typeof permissions !== "object" || permissions === null || Array.isArray(permissions)) {+ const defaults = defaultAgentPermissions({+ lowTrust: permissionsImplyLowTrust(permissions),+ context: options?.context ?? "stored",+ });+ const record = asRecord(permissions);+ if (!record) {return defaults;}- const record = permissions as Record<string, unknown>;- const preserved = { ...record };return {- ...preserved,+ ...record,canCreateAgents:typeof record.canCreateAgents === "boolean"? record.canCreateAgentsdiff --git a/server/src/services/agents.ts b/server/src/services/agents.tsindex 86dee4a2a2..f785397746 100644--- a/server/src/services/agents.ts+++ b/server/src/services/agents.ts@@ -344,7 +344,7 @@ export function agentService(db: Db) {function normalizeAgentBaseRow(row: typeof agents.$inferSelect) {return withUrlKey({...row,- permissions: normalizeAgentPermissions(row.permissions, row.role),+ permissions: normalizeAgentPermissions(row.permissions),});}@@ -676,8 +676,7 @@ export function agentService(db: Db) {const normalizedPatch = { ...data } as Partial<typeof agents.$inferInsert>;if (data.permissions !== undefined) {- const role = (data.role ?? existing.role) as string;- normalizedPatch.permissions = normalizeAgentPermissions(data.permissions, role);+ normalizedPatch.permissions = normalizeAgentPermissions(data.permissions);}if (Object.prototype.hasOwnProperty.call(normalizedPatch, "adapterConfig") &&@@ -806,7 +805,7 @@ export function agentService(db: Db) {const uniqueName = deduplicateAgentName(data.name, existingAgents);const role = data.role ?? "general";- const normalizedPermissions = normalizeAgentPermissions(data.permissions, role);+ const normalizedPermissions = normalizeAgentPermissions(data.permissions, { context: "create" });const runtimeConfig = normalizeRuntimeConfigForNewAgent(data.runtimeConfig);const adapterType = data.adapterType ?? "process";const rawAdapterConfig = isPlainRecord(data.adapterConfig)@@ -1039,10 +1038,9 @@ export function agentService(db: Db) {);}if (patch.permissions !== undefined) {- patch.permissions = normalizeAgentPermissions(- patch.permissions,- (patch.role ?? existing.role) as string,- );+ // The pending-approval activation replays the original hire+ // request, so the new-agent creation default applies.+ patch.permissions = normalizeAgentPermissions(patch.permissions, { context: "create" });}const updated = await tx.update(agents)@@ -1089,7 +1087,7 @@ export function agentService(db: Db) {const updated = await db.update(agents).set({- permissions: normalizeAgentPermissions({ ...existing.permissions, ...permissions }, existing.role),+ permissions: normalizeAgentPermissions({ ...existing.permissions, ...permissions }),updatedAt: new Date(),}).where(eq(agents.id, id))diff --git a/server/src/services/authorization.ts b/server/src/services/authorization.tsindex 6a20e38a3c..c6cad46937 100644--- a/server/src/services/authorization.ts+++ b/server/src/services/authorization.ts@@ -28,6 +28,7 @@ import {type TrustPresetResolution,} from "./trust-preset-resolver.js";import { logger } from "../middleware/logger.js";+import { normalizeAgentPermissions } from "./agent-permissions.js";import { grantsForHumanRole, normalizeHumanRole } from "./company-member-roles.js";export type AuthorizationActor =@@ -170,8 +171,10 @@ function permissionForAction(action: AuthorizationAction): PermissionKey | nullfunction canCreateAgentsLegacy(agent: { role: string; permissions: unknown }) {if (agent.role === "ceo") return true;- if (!agent.permissions || typeof agent.permissions !== "object") return false;- return Boolean((agent.permissions as Record<string, unknown>).canCreateAgents);+ // Raw agent rows may predate permission normalization; apply the same+ // defaults the agent service applies on read so enforcement matches what+ // the API reports.+ return normalizeAgentPermissions(agent.permissions).canCreateAgents;}function scopeValueList(value: unknown): string[] {@@ -984,6 +987,11 @@ export function authorizationService(db: Db | DbTransaction) {if (input.action === "company_scope:read" ||+ // Agent creation is a company-wide privileged action. The default-on+ // canCreateAgents flag must never reach the legacy creator allow when+ // the effective execution context (agent, project, issue, or run+ // policy) resolves to low trust.+ input.action === "agents:create" ||input.action === "decision_queue:manage" ||input.action === "decision_queue:read" ||input.action === "decision_triage:manage" ||@@ -2242,11 +2250,19 @@ export function authorizationService(db: Db | DbTransaction) {if (grantDecision.allowed) return grantDecision;}- if (- (input.action === "agents:create" ||- input.action === "tasks:manage_active_checkouts") &&- canCreateAgentsLegacy(actorAgent)- ) {+ if (input.action === "agents:create" && canCreateAgentsLegacy(actorAgent)) {+ return allow({+ action: input.action,+ reason: "allow_legacy_agent_creator",+ explanation: "Allowed by legacy agent creator authority.",+ });+ }++ // Active-checkout management deliberately does not ride on+ // canCreateAgents: that flag is default-on for standard-trust agents, and+ // coupling would let any peer write over another agent's checked-out+ // issue. CEOs, explicit grants, and the manager chain remain the paths.+ if (input.action === "tasks:manage_active_checkouts" && actorAgent.role === "ceo") {return allow({action: input.action,reason: "allow_legacy_agent_creator",diff --git a/ui/src/lib/trust-policy-ui.test.ts b/ui/src/lib/trust-policy-ui.test.tsindex c142c6bb6f..a791c62a15 100644--- a/ui/src/lib/trust-policy-ui.test.ts+++ b/ui/src/lib/trust-policy-ui.test.ts@@ -1,6 +1,7 @@// @vitest-environment nodeimport { describe, expect, it } from "vitest";import {+ buildPermissionsForTrustPreset,clearSingleLowTrustBoundaryTarget,getLowTrustBoundary,getSingleLowTrustBoundaryTarget,@@ -10,6 +11,19 @@ import {} from "./trust-policy-ui";describe("trust-policy-ui low-trust boundary helpers", () => {+ it("drops hire authority when switching to the low-trust preset", () => {+ const demoted = buildPermissionsForTrustPreset(+ { canCreateAgents: true, canCreateSkills: true },+ "low_trust_review",+ );+ expect(demoted.canCreateAgents).toBe(false);+ expect(demoted.canCreateSkills).toBe(true);++ const restored = buildPermissionsForTrustPreset(demoted, "standard");+ expect(restored.canCreateAgents).toBe(false);+ expect(restored.trustPreset).toBe("standard");+ });+it("writes one project boundary with mode and company id", () => {const permissions = setSingleLowTrustBoundaryTarget(null, "company-1", {type: "project",diff --git a/ui/src/lib/trust-policy-ui.ts b/ui/src/lib/trust-policy-ui.tsindex f2442435d8..86ee6d5f47 100644--- a/ui/src/lib/trust-policy-ui.ts+++ b/ui/src/lib/trust-policy-ui.ts@@ -52,6 +52,10 @@ export function buildPermissionsForTrustPreset(if (preset === LOW_TRUST_REVIEW_PRESET) {return {...current,+ // Hire authority is default-on for standard-trust agents, so demoting+ // to low-trust must drop it rather than carry the old value forward.+ // Operators can re-enable it explicitly afterwards.+ canCreateAgents: false,trustPreset: LOW_TRUST_REVIEW_PRESET,authorizationPolicy: buildLowTrustReviewPolicy(current.authorizationPolicy),};