[codex] Add agent permissions and controls plan (#6386)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies by keeping
task ownership, approvals, and operator control inside one control
plane.
> - Agent permissions and plugin-hosted company settings sit on the
boundary between autonomy and governance.
> - V1 needs scoped task assignment rules, plugin extension points, and
clearer company access surfaces without weakening company boundaries.
> - The branch builds the core authorization service, plugin SDK/host
APIs, and UI simplifications needed to support those controls.
> - Paperclip EE plugin surfaces were intentionally moved out of this
core PR per review direction, so this PR now carries only the public
core/plugin infrastructure work.
> - The latest updates preserve the PAP-9937 branch changes that belong
in this PR, remove the `design/` artifacts, and exclude the experimental
`plugin-briefs` package.
> - Greptile feedback was applied through the authorization/audit paths
and the final cleanup commit was re-reviewed at 5/5 with no unresolved
Greptile threads.
> - The benefit is safer assignment control with extension hooks for
richer permission products while preserving simple defaults for normal
operators.

## What Changed

- Added scoped task-assignment authorization decisions and routed
issue/agent assignment mutations through the authorization service.
- Added plugin SDK and host APIs for company settings slots,
authorization policy/grant management, assignment previews, and bridge
invocation scope propagation.
- Simplified core company access UI and moved advanced controls behind
plugin-provided settings surfaces.
- Added retry-now affordances for blocked issue next-step notices.
- Added protected-assignment enforcement for persisted
agent/project/issue policies, including explicit-grant fallback
behavior.
- Added incremental principal-access compatibility backfill for active
agent memberships and role-default human permission grants.
- Added the Markdown code block wrap action fix from the latest branch
changes.
- Removed `design/` artifacts from the PR and removed
`packages/plugins/plugin-briefs` from the final diff.
- Addressed Greptile feedback for plugin actor sanitization, legacy
membership handling, audit pagination, unknown grant-scope metadata, and
startup test mocks.

## Verification

- `pnpm exec vitest run server/src/__tests__/access-service.test.ts
server/src/__tests__/company-portability.test.ts` -> 2 files passed, 54
tests passed.
- `pnpm exec vitest run
server/src/__tests__/server-startup-feedback-export.test.ts
server/src/__tests__/access-service.test.ts
server/src/__tests__/company-portability.test.ts` -> 3 files passed, 62
tests passed.
- `pnpm exec vitest run
server/src/__tests__/authorization-service.test.ts
server/src/__tests__/plugin-access-authorization-host-services.test.ts
server/src/__tests__/server-startup-feedback-export.test.ts` -> 3 files
passed, 28 tests passed.
- `pnpm --filter @paperclipai/server typecheck` -> passed.
- `git diff --check` -> passed.
- `node ./scripts/check-docker-deps-stage.mjs` -> passed.
- `CI=true pnpm install --frozen-lockfile --ignore-scripts` -> passed
with no lockfile update.
- `pnpm exec vitest run
ui/src/components/MarkdownBody.interaction.test.tsx` -> 1 test passed.
- `git ls-files design packages/plugins/plugin-briefs | wc -l` -> 0.
- GitHub CI on `40cd83b53` -> all checks passed, merge state `CLEAN`.
- Greptile on `40cd83b53` -> 5/5, 102 files reviewed, 0
comments/annotations added, 0 unresolved review threads.
- Confirmed the PR diff contains no `design/`,
`packages/plugins/plugin-briefs`, `pnpm-lock.yaml`, or
`.github/workflows` changes.

## Risks

- Medium: task assignment authorization paths are behaviorally stricter
for protected/private policy data, so existing plugin-authored policies
may block assignment until explicit grants or approval flows are
configured.
- Medium: plugin-host authorization APIs expand the surface area
available to trusted plugins and need careful review for company
scoping.
- Low: startup now performs a principal-access compatibility backfill,
but the migration and runtime backfill use conflict-tolerant inserts.

> 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, GPT-5 coding agent, tool-enabled workflow with shell,
git, and GitHub CLI access.

## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

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

ui/src/pages/CompanyAccess.test.tsx

@@ -4,23 +4,25 @@ import { act } from "react";
 import { createRoot } from "react-dom/client";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { CompanyAccess } from "./CompanyAccess";
+import { CompanyAccess, CompanyAccessLegacyRoute } from "./CompanyAccess";
 
 const listMembersMock = vi.hoisted(() => vi.fn());
 const listJoinRequestsMock = vi.hoisted(() => vi.fn());
-const updateMemberAccessMock = vi.hoisted(() => vi.fn());
+const updateMemberMock = vi.hoisted(() => vi.fn());
 const archiveMemberMock = vi.hoisted(() => vi.fn());
 const listAgentsMock = vi.hoisted(() => vi.fn());
 const listIssuesMock = vi.hoisted(() => vi.fn());
+const mockUsePluginSlots = vi.hoisted(() => vi.fn());
+const mockNavigate = vi.hoisted(() => vi.fn());
 
 vi.mock("@/api/access", () => ({
   accessApi: {
     listMembers: (companyId: string) => listMembersMock(companyId),
     listJoinRequests: (companyId: string, status: string) => listJoinRequestsMock(companyId, status),
-    updateMember: vi.fn(),
+    updateMember: (companyId: string, memberId: string, input: unknown) =>
+      updateMemberMock(companyId, memberId, input),
     updateMemberPermissions: vi.fn(),
-    updateMemberAccess: (companyId: string, memberId: string, input: unknown) =>
-      updateMemberAccessMock(companyId, memberId, input),
+    updateMemberAccess: vi.fn(),
     archiveMember: (companyId: string, memberId: string, input: unknown) =>
       archiveMemberMock(companyId, memberId, input),
     approveJoinRequest: vi.fn(),
@@ -40,6 +42,18 @@ vi.mock("@/api/issues", () => ({
   },
 }));
 
+vi.mock("@/lib/router", () => ({
+  Link: ({ to, children }: { to: string; children: React.ReactNode }) => <a href={to}>{children}</a>,
+  Navigate: ({ to, replace }: { to: string; replace?: boolean }) => {
+    mockNavigate(to, replace);
+    return <div data-testid="navigate">{to}</div>;
+  },
+}));
+
+vi.mock("@/plugins/slots", () => ({
+  usePluginSlots: mockUsePluginSlots,
+}));
+
 vi.mock("@/context/CompanyContext", () => ({
   useCompany: () => ({
     selectedCompanyId: "company-1",
@@ -146,7 +160,7 @@ describe("CompanyAccess", () => {
         },
       },
     ]);
-    updateMemberAccessMock.mockResolvedValue({});
+    updateMemberMock.mockResolvedValue({});
     archiveMemberMock.mockResolvedValue({ reassignedIssueCount: 1 });
     listAgentsMock.mockResolvedValue([
       {
@@ -164,6 +178,11 @@ describe("CompanyAccess", () => {
         status: "todo",
       },
     ]);
+    mockUsePluginSlots.mockReturnValue({
+      slots: [],
+      isLoading: false,
+      errorMessage: null,
+    });
   });
 
   afterEach(() => {
@@ -172,7 +191,7 @@ describe("CompanyAccess", () => {
     vi.clearAllMocks();
   });
 
-  it("keeps the page human-focused and explains implicit versus explicit grants", async () => {
+  it("keeps the page human-focused and hides advanced permission controls", async () => {
     const root = createRoot(container);
     const queryClient = new QueryClient({
       defaultOptions: { queries: { retry: false } },
@@ -188,10 +207,15 @@ describe("CompanyAccess", () => {
     await flushReact();
     await flushReact();
 
-    expect(container.textContent).toContain("Manage company user memberships");
+    expect(container.textContent).toContain("Manage the people who can work in Paperclip");
+    expect(container.textContent).toContain("Members can collaborate across the company by default");
+    expect(container.textContent).toContain("Core keeps this page focused on membership");
     expect(container.textContent).toContain("Humans");
     expect(container.textContent).toContain("Pending human joins");
     expect(container.textContent).toContain("User account");
+    expect(container.textContent).not.toContain("Grants");
+    expect(container.textContent).not.toContain("explicit grants");
+    expect(container.textContent).not.toContain("Assign scoped tasks");
     expect(container.textContent).not.toContain("Agents");
     expect(container.textContent).not.toContain("Pending agent joins");
     expect(container.textContent).not.toContain("Open join request queue");
@@ -210,18 +234,16 @@ describe("CompanyAccess", () => {
     });
     await flushReact();
 
-    expect(document.body.textContent).toContain("Implicit grants from role");
-    expect(document.body.textContent).toContain("Owner currently includes these permissions automatically.");
-    expect(document.body.textContent).toContain(
-      "Included implicitly by the Owner role. Add an explicit grant only if it should stay after the role changes.",
-    );
+    expect(document.body.textContent).toContain("Update company role and membership status");
+    expect(document.body.textContent).not.toContain("Implicit grants from role");
+    expect(document.body.textContent).not.toContain("permissionKey");
 
     await act(async () => {
       root.unmount();
     });
   });
 
-  it("saves member role, status, and grants in one request", async () => {
+  it("saves member role and status without touching grants", async () => {
     const root = createRoot(container);
     const queryClient = new QueryClient({
       defaultOptions: { queries: { retry: false } },
@@ -248,7 +270,7 @@ describe("CompanyAccess", () => {
     await flushReact();
 
     const saveButton = Array.from(document.body.querySelectorAll("button")).find(
-      (button) => button.textContent === "Save access",
+      (button) => button.textContent === "Save member",
     );
     expect(saveButton).toBeTruthy();
 
@@ -257,10 +279,9 @@ describe("CompanyAccess", () => {
     });
     await flushReact();
 
-    expect(updateMemberAccessMock).toHaveBeenCalledWith("company-1", "member-1", {
+    expect(updateMemberMock).toHaveBeenCalledWith("company-1", "member-1", {
       membershipRole: "owner",
       status: "active",
-      grants: [],
     });
 
     await act(async () => {
@@ -382,4 +403,65 @@ describe("CompanyAccess", () => {
       root.unmount();
     });
   });
+
+  it("redirects legacy access deep links to the permissions extension route when installed", async () => {
+    mockUsePluginSlots.mockReturnValue({
+      slots: [
+        {
+          type: "companySettingsPage",
+          id: "permissions",
+          displayName: "Permissions",
+          routePath: "permissions",
+          pluginKey: "permissions-extension",
+        },
+      ],
+      isLoading: false,
+      errorMessage: null,
+    });
+    const root = createRoot(container);
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+
+    await act(async () => {
+      root.render(
+        <QueryClientProvider client={queryClient}>
+          <CompanyAccessLegacyRoute />
+        </QueryClientProvider>,
+      );
+    });
+    await flushReact();
+
+    expect(mockNavigate).toHaveBeenCalledWith("/company/settings/permissions", true);
+    expect(container.textContent).toContain("/company/settings/permissions");
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
+
+  it("shows a read-only unavailable fallback for legacy access deep links", async () => {
+    const root = createRoot(container);
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+
+    await act(async () => {
+      root.render(
+        <QueryClientProvider client={queryClient}>
+          <CompanyAccessLegacyRoute />
+        </QueryClientProvider>,
+      );
+    });
+    await flushReact();
+
+    expect(container.textContent).toContain("Advanced Permissions");
+    expect(container.textContent).toContain("Advanced permissions unavailable");
+    expect(container.textContent).toContain("Open Members");
+    expect(container.textContent).toContain("Open Invites");
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
 });