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

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Task assignment policies control which agents can receive work.
> - Protected-agent policy flags currently stop assignment.
> - The existing error says that the assignment requires approval.
> - Paperclip has no approval workflow for this policy.
> - This pull request models the policy as a hard block and gives the
operator an action that exists.
> - The benefit is accurate API guidance without weakening the existing
fail-closed behavior.

## Linked Issues or Issue Description

Refs #6386

**What happened?**

A protected-agent assignment denial said that approval was required. No
approval record or approval action existed for this policy, so the
message sent agents and operators to a dead end.

**Expected behavior**

The authorization result must state that protected-agent policy blocks
assignment. It must tell a company administrator to remove the block
before retrying.

**Steps to reproduce**

1. Set `authorizationPolicy.protectedAgent.requiresApproval` to `true`
on a target agent.
2. Give another agent the `tasks:assign` permission.
3. Preview or attempt assignment to the protected agent.
4. Observe that the old response promises an approval step that does not
exist.

**Paperclip version or commit**

`c54936e2e9` on `master`.

**Deployment mode**

Built from source. The behavior is in the core authorization service and
is not deployment-specific.

**Agent adapter(s) involved**

Not adapter-specific.

## What Changed

- Added canonical `protectedAgent.blockAssignment` and
`protectedAgent.blockReason` policy fields.
- Kept the legacy approval-named flags as fail-closed compatibility
aliases.
- Changed denial copy to name the hard block and the administrator
action.
- Added authorization and plugin-host regression coverage for canonical
and legacy policy data.
- Updated the V1 implementation contract with the protected-assignment
rule.

## Verification

- `pnpm exec vitest run
server/src/__tests__/authorization-service.test.ts
server/src/__tests__/plugin-access-authorization-host-services.test.ts`
— 2 files passed, 61 tests passed.
- `pnpm --filter @paperclipai/shared typecheck` — passed.
- `pnpm --filter @paperclipai/server typecheck` — passed.
- `pnpm --filter @paperclipai/shared build` — passed.
- `pnpm --filter @paperclipai/server build` — passed.
- `pnpm check:token-gates` — all gates clean.
- `git diff --check public-gh/master...HEAD` — passed.

The repository-wide local wrappers exceeded the execution host resource
limit before they printed a final summary. The PR check loop will use
GitHub CI as the complete test and build authority.

## Risks

- Low: assignment remains fail-closed. The change corrects the policy
name and denial guidance.
- Low: legacy fields remain supported, so existing plugin-owned policy
data does not change behavior.
- Low: the new policy schemas allow unknown keys for forward
compatibility, as the existing authorization policy schema already does.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex, exact model ID `gpt-5`, tool-enabled coding agent with
reasoning, shell, Git, and GitHub CLI access. The runtime does not
expose the context-window size.

## 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
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

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.

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,

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";

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 {

packages/shared/src/validators/index.ts

@@ -313,6 +313,8 @@ export {
   trustPresetSchema,
   lowTrustBoundarySchema,
   lowTrustReviewPresetPolicySchema,
+  assignmentAuthorizationPolicySchema,
+  protectedAgentAuthorizationPolicySchema,
   trustAuthorizationPolicySchema,
   sourceTrustArtifactKindSchema,
   sourceTrustMetadataSchema,

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);
+  });
+});

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"]);

server/src/__tests__/authorization-service.test.ts

@@ -1081,7 +1081,7 @@ 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, {
@@ -1090,17 +1090,18 @@ describeEmbeddedPostgres("authorization service", () => {
         authorizationPolicy: {
           assignmentPolicy: {
             mode: "protected",
-            protectedAgentRequiresApproval: true,
           },
           protectedAgent: {
-            requiresApproval: true,
-            approvalReason: "Production deployment authority",
+            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",
@@ -1112,7 +1113,47 @@ describeEmbeddedPostgres("authorization service", () => {
       allowed: false,
       reason: "deny_policy_restricted",
     });
-    expect(decision.explanation).toContain("requires approval");
+    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: {
+        authorizationPolicy: {
+          assignmentPolicy: {
+            mode: "protected",
+            protectedAgentRequiresApproval: true,
+          },
+          protectedAgent: {
+            requiresApproval: true,
+          },
+        },
+      },
+    });
+
+    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).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 () => {

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({

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" }
     );