Skip to content

The open-source app everyone uses to manage agents at work

fix(auth): clarify protected-agent assignment blocks (#10893)

Dotta6ffe9df842aa
diff --git a/doc/SPEC-implementation.md b/doc/SPEC-implementation.md
index 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 Contract
A 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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" }
);