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
fix(auth): clarify protected-agent assignment blocks (#10893)
Dotta6ffe9df842aa
diff --git a/doc/SPEC-implementation.md b/doc/SPEC-implementation.mdindex 8c22d9d776..a27d3dd21e 100644--- a/doc/SPEC-implementation.md+++ b/doc/SPEC-implementation.md@@ -646,6 +646,15 @@ The approved term set is:When multiple constraint families are present, assignment must satisfy all of them. Denials return `403` with a generic scope explanation and do not disclose details about hidden or unrelated resources.+A protected-agent hard block is represented canonically as+`authorizationPolicy.protectedAgent.blockAssignment: true`. It denies assignment+even when the caller has a broad or scoped assignment grant. A company+administrator must remove the block before assignment can be retried; no pending+approval is created. The legacy fields `protectedAgent.requiresApproval` and+`assignmentPolicy.protectedAgentRequiresApproval` remain fail-closed compatibility+aliases for the same hard block, but API denial copy must describe the block and+administrator remediation rather than promising a nonexistent approval step.+## 9.9 Task Watchdog Authority ContractA task watchdog is a scoped execution capacity for a configured watchdog agent on one watched issue subtree. It is not a separate principal, does not inherit board auth, and does not expand the selected agent's company boundary. The server must enforce the watchdog contract from persisted watchdog configuration and run context; custom instructions and prompt text can narrow the mandate but cannot expand it.diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.tsindex 9259598469..9715de7c8a 100644--- a/packages/shared/src/index.ts+++ b/packages/shared/src/index.ts@@ -223,6 +223,8 @@ export {type LowTrustOutputPromotionTarget,type LowTrustBoundary,type LowTrustReviewPresetPolicy,+ type AssignmentAuthorizationPolicy,+ type ProtectedAgentAuthorizationPolicy,type TrustAuthorizationPolicy,type SourceTrustArtifactKind,type SourceTrustDisposition,@@ -1531,6 +1533,8 @@ export {trustPresetSchema,lowTrustBoundarySchema,lowTrustReviewPresetPolicySchema,+ assignmentAuthorizationPolicySchema,+ protectedAgentAuthorizationPolicySchema,trustAuthorizationPolicySchema,type PatchInstanceExperimentalSettings,type PatchInstanceSettings,diff --git a/packages/shared/src/trust-policy.ts b/packages/shared/src/trust-policy.tsindex e078f11ffb..88001a8d62 100644--- a/packages/shared/src/trust-policy.ts+++ b/packages/shared/src/trust-policy.ts@@ -38,10 +38,28 @@ export interface LowTrustReviewPresetPolicy {rawOutputDisposition: typeof LOW_TRUST_REVIEW_RAW_OUTPUT_DISPOSITION;}+export interface AssignmentAuthorizationPolicy extends Record<string, unknown> {+ mode?: "company_default" | "protected";+ /** @deprecated Use `protectedAgent.blockAssignment`. */+ protectedAgentRequiresApproval?: boolean;+}++export interface ProtectedAgentAuthorizationPolicy extends Record<string, unknown> {+ /** Hard-block assignment until a company administrator removes the block. */+ blockAssignment?: boolean;+ blockReason?: string;+ /** @deprecated Legacy hard-block alias. This does not create an approval. */+ requiresApproval?: boolean;+ /** @deprecated Legacy metadata retained for compatibility. */+ approvalReason?: string;+}+export interface TrustAuthorizationPolicy extends Record<string, unknown> {trustPreset?: TrustPreset;reviewPreset?: LowTrustReviewPresetPolicy;trustBoundary?: LowTrustBoundary;+ assignmentPolicy?: AssignmentAuthorizationPolicy;+ protectedAgent?: ProtectedAgentAuthorizationPolicy;}export type SourceTrustArtifactKind = "issue" | "comment" | "document" | "work_product";diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.tsindex 7e0c2fcb97..e0822c7164 100644--- a/packages/shared/src/types/index.ts+++ b/packages/shared/src/types/index.ts@@ -128,6 +128,8 @@ export {type LowTrustOutputPromotionTarget,type LowTrustBoundary,type LowTrustReviewPresetPolicy,+ type AssignmentAuthorizationPolicy,+ type ProtectedAgentAuthorizationPolicy,type TrustAuthorizationPolicy,} from "../trust-policy.js";export type {diff --git a/packages/shared/src/validators/index.ts b/packages/shared/src/validators/index.tsindex 0e20cbfeb5..4fc51c47ac 100644--- a/packages/shared/src/validators/index.ts+++ b/packages/shared/src/validators/index.ts@@ -313,6 +313,8 @@ export {trustPresetSchema,lowTrustBoundarySchema,lowTrustReviewPresetPolicySchema,+ assignmentAuthorizationPolicySchema,+ protectedAgentAuthorizationPolicySchema,trustAuthorizationPolicySchema,sourceTrustArtifactKindSchema,sourceTrustMetadataSchema,diff --git a/packages/shared/src/validators/trust-policy.test.ts b/packages/shared/src/validators/trust-policy.test.tsnew file mode 100644index 0000000000..1fc4818984--- /dev/null+++ b/packages/shared/src/validators/trust-policy.test.ts@@ -0,0 +1,29 @@+import { describe, expect, it } from "vitest";+import { trustAuthorizationPolicySchema } from "./trust-policy.js";++describe("trustAuthorizationPolicySchema", () => {+ it("accepts an empty legacy protected-agent approval reason", () => {+ const result = trustAuthorizationPolicySchema.parse({+ protectedAgent: {+ requiresApproval: true,+ approvalReason: "",+ },+ });++ expect(result.protectedAgent).toMatchObject({+ requiresApproval: true,+ approvalReason: "",+ });+ });++ it("still requires a non-empty canonical assignment block reason", () => {+ const result = trustAuthorizationPolicySchema.safeParse({+ protectedAgent: {+ blockAssignment: true,+ blockReason: "",+ },+ });++ expect(result.success).toBe(false);+ });+});diff --git a/packages/shared/src/validators/trust-policy.ts b/packages/shared/src/validators/trust-policy.tsindex 9252d04f91..39496b5e43 100644--- a/packages/shared/src/validators/trust-policy.ts+++ b/packages/shared/src/validators/trust-policy.ts@@ -31,10 +31,26 @@ export const lowTrustReviewPresetPolicySchema = z.object({rawOutputDisposition: z.literal(LOW_TRUST_REVIEW_RAW_OUTPUT_DISPOSITION),}).strict();+export const assignmentAuthorizationPolicySchema = z.object({+ mode: z.enum(["company_default", "protected"]).optional(),+ // Legacy compatibility only. This remains a hard block and never creates an approval.+ protectedAgentRequiresApproval: z.boolean().optional(),+}).catchall(z.unknown());++export const protectedAgentAuthorizationPolicySchema = z.object({+ blockAssignment: z.boolean().optional(),+ blockReason: z.string().trim().min(1).optional(),+ // Legacy compatibility only. These fields do not create an approval.+ requiresApproval: z.boolean().optional(),+ approvalReason: z.string().optional(),+}).catchall(z.unknown());+export const trustAuthorizationPolicySchema = z.object({trustPreset: trustPresetSchema.optional(),reviewPreset: lowTrustReviewPresetPolicySchema.optional(),trustBoundary: lowTrustBoundarySchema.optional(),+ assignmentPolicy: assignmentAuthorizationPolicySchema.optional(),+ protectedAgent: protectedAgentAuthorizationPolicySchema.optional(),}).catchall(z.unknown());export const sourceTrustArtifactKindSchema = z.enum(["issue", "comment", "document", "work_product"]);diff --git a/server/src/__tests__/authorization-service.test.ts b/server/src/__tests__/authorization-service.test.tsindex 3874d5a60d..1894fc33ba 100644--- a/server/src/__tests__/authorization-service.test.ts+++ b/server/src/__tests__/authorization-service.test.ts@@ -1081,9 +1081,48 @@ describeEmbeddedPostgres("authorization service", () => {})).resolves.toMatchObject({ allowed: false, reason: "deny_low_trust_boundary" });});- it("denies simple-mode assignment when the target agent requires protected-assignment approval", async () => {+ it("hard-blocks assignment when the target agent blocks protected assignment", async () => {const company = await createCompany(db, "ProtectedAssignment");const actorAgent = await createAgent(db, company.id, { role: "engineer" });+ const targetAgent = await createAgent(db, company.id, {+ role: "engineer",+ permissions: {+ authorizationPolicy: {+ assignmentPolicy: {+ mode: "protected",+ },+ protectedAgent: {+ blockAssignment: true,+ blockReason: "Production deployment authority",+ },+ managedBy: "permissions-extension",+ },+ },+ });++ await grantAgentPermission(db, company.id, actorAgent.id, "tasks:assign");++ const decision = await authorizationService(db).decide({+ actor: { type: "agent", agentId: actorAgent.id, companyId: company.id, source: "agent_key" },+ action: "tasks:assign",+ resource: { type: "issue", companyId: company.id, assigneeAgentId: targetAgent.id },+ scope: { assigneeAgentId: targetAgent.id },+ });++ expect(decision).toMatchObject({+ allowed: false,+ reason: "deny_policy_restricted",+ });+ expect(decision.explanation).toBe(+ "Target agent assignment is blocked by protected-agent policy. " ++ "A company administrator can remove the assignment block, then retry.",+ );+ expect(decision.explanation).not.toContain("approval");+ });++ it("keeps legacy protected-assignment approval flags as hard blocks without approval copy", async () => {+ const company = await createCompany(db, "LegacyProtectedAssignment");+ const actorAgent = await createAgent(db, company.id, { role: "engineer" });const targetAgent = await createAgent(db, company.id, {role: "engineer",permissions: {@@ -1094,13 +1133,13 @@ describeEmbeddedPostgres("authorization service", () => {},protectedAgent: {requiresApproval: true,- approvalReason: "Production deployment authority",},- managedBy: "permissions-extension",},},});+ await grantAgentPermission(db, company.id, actorAgent.id, "tasks:assign");+const decision = await authorizationService(db).decide({actor: { type: "agent", agentId: actorAgent.id, companyId: company.id, source: "agent_key" },action: "tasks:assign",@@ -1112,7 +1151,9 @@ describeEmbeddedPostgres("authorization service", () => {allowed: false,reason: "deny_policy_restricted",});- expect(decision.explanation).toContain("requires approval");+ expect(decision.explanation).toContain("assignment is blocked");+ expect(decision.explanation).toContain("company administrator");+ expect(decision.explanation).not.toContain("approval");});it("requires an explicit grant before assigning to a private target agent", async () => {diff --git a/server/src/__tests__/plugin-access-authorization-host-services.test.ts b/server/src/__tests__/plugin-access-authorization-host-services.test.tsindex 87737816a3..5b588aa8d2 100644--- a/server/src/__tests__/plugin-access-authorization-host-services.test.ts+++ b/server/src/__tests__/plugin-access-authorization-host-services.test.ts@@ -209,11 +209,10 @@ describeEmbeddedPostgres("plugin access and authorization host services", () =>policy: {assignmentPolicy: {mode: "protected",- protectedAgentRequiresApproval: true,},protectedAgent: {- requiresApproval: true,- approvalReason: "Needs board approval",+ blockAssignment: true,+ blockReason: "Protected assignment",},managedBy: "permissions-extension",},@@ -235,12 +234,15 @@ describeEmbeddedPostgres("plugin access and authorization host services", () =>]);expect(policy.policy).toMatchObject({- protectedAgent: { requiresApproval: true },+ protectedAgent: { blockAssignment: true },});expect(preview).toMatchObject({allowed: false,reason: "deny_policy_restricted",});+ expect(preview.explanation).toContain("assignment is blocked");+ expect(preview.explanation).toContain("company administrator");+ expect(preview.explanation).not.toContain("approval");expect(explanation).toMatchObject(preview);const injectedBoardPreview = await services.authorization.previewAssignment({diff --git a/server/src/services/authorization.ts b/server/src/services/authorization.tsindex b41b3aff2d..8ea80a41fe 100644--- a/server/src/services/authorization.ts+++ b/server/src/services/authorization.ts@@ -221,7 +221,7 @@ function readBoolean(value: unknown): boolean | null {type AssignmentPolicyEffect =| { kind: "none" }| { kind: "restricted"; explanation: string }- | { kind: "requires_approval"; explanation: string }+ | { kind: "blocked"; explanation: string }| { kind: "unknown"; explanation: string };type AgentHierarchyRow = { id: string; reportsTo: string | null };@@ -293,13 +293,19 @@ function evaluateAuthorizationPolicyForAssignment(};}- const requiresApproval =+ // `requiresApproval` and `protectedAgentRequiresApproval` are legacy aliases.+ // They never had an approval workflow behind them, so preserve their hard-block+ // behavior without continuing to promise an approval step that does not exist.+ const blockAssignment =+ readBoolean(protectedAgent?.blockAssignment) === true ||readBoolean(protectedAgent?.requiresApproval) === true ||readBoolean(assignmentPolicy?.protectedAgentRequiresApproval) === true;- if (requiresApproval) {+ if (blockAssignment) {return {- kind: "requires_approval",- explanation: `${label} requires approval before task assignment.`,+ kind: "blocked",+ explanation:+ `${label} assignment is blocked by protected-agent policy. ` ++ "A company administrator can remove the assignment block, then retry.",};}@@ -1300,7 +1306,7 @@ export function authorizationService(db: Db) {const effects = await Promise.all(checks);return (effects.find((effect) => effect.kind === "unknown") ??- effects.find((effect) => effect.kind === "requires_approval") ??+ effects.find((effect) => effect.kind === "blocked") ??effects.find((effect) => effect.kind === "restricted") ??{ kind: "none" });