[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>

packages/plugins/sdk/src/protocol.ts

@@ -39,6 +39,7 @@ import type {
   Agent,
   Goal,
   PluginLocalFolderDeclaration,
+  PrincipalPermissionGrant,
 } from "@paperclipai/shared";
 export type { PluginLauncherRenderContextSnapshot } from "@paperclipai/shared";
 
@@ -57,6 +58,13 @@ import type {
   ToolResult,
   PluginLocalFolderListing,
   PluginLocalFolderStatus,
+  PluginAccessInvite,
+  PluginAccessMember,
+  PluginAssignmentPreviewInput,
+  PluginAuthorizationAuditEntry,
+  PluginAuthorizationDecisionResult,
+  PluginAuthorizationPolicyRecord,
+  PluginAuthorizationPolicySummary,
 } from "./types.js";
 import type {
   PluginHealthDiagnostics,
@@ -96,6 +104,14 @@ export interface JsonRpcRequest<
   readonly method: TMethod;
   /** Structured parameters for the method call. */
   readonly params: TParams;
+  /**
+   * Host-issued metadata for the top-level plugin invocation that is currently
+   * executing. The worker treats this as opaque and echoes only the id on
+   * worker→host calls made from the same async execution context.
+   */
+  readonly paperclipInvocation?: PluginInvocationContext;
+  /** Opaque top-level invocation id echoed by worker→host requests. */
+  readonly paperclipInvocationId?: string;
 }
 
 /**
@@ -156,6 +172,13 @@ export interface JsonRpcNotification<
   readonly method: TMethod;
   /** Structured parameters for the notification. */
   readonly params: TParams;
+  /**
+   * Host-issued metadata for host→worker push notifications such as events.
+   * Worker→host notifications echo only `paperclipInvocationId`.
+   */
+  readonly paperclipInvocation?: PluginInvocationContext;
+  /** Opaque top-level invocation id echoed by worker→host notifications. */
+  readonly paperclipInvocationId?: string;
 }
 
 /**
@@ -217,6 +240,36 @@ export const PLUGIN_RPC_ERROR_CODES = {
 export type PluginRpcErrorCode =
   (typeof PLUGIN_RPC_ERROR_CODES)[keyof typeof PLUGIN_RPC_ERROR_CODES];
 
+// ---------------------------------------------------------------------------
+// Invocation scope metadata
+// ---------------------------------------------------------------------------
+
+/**
+ * Company scope attached by the host to one top-level plugin invocation.
+ * Absence of this metadata means the invocation is instance/global scoped.
+ */
+export interface PluginInvocationScope {
+  companyId: string;
+}
+
+/**
+ * Opaque invocation metadata generated by the host. Workers must not derive or
+ * mutate this. They only echo the id on nested worker→host RPC calls.
+ */
+export interface PluginInvocationContext {
+  id: string;
+  scope: PluginInvocationScope;
+}
+
+/**
+ * Context provided to host-side worker→host handlers after the worker echoes a
+ * host-issued invocation id.
+ */
+export interface WorkerHostCallContext {
+  invocationScope?: PluginInvocationScope | null;
+  invalidInvocationScope?: boolean;
+}
+
 // ---------------------------------------------------------------------------
 // Host → Worker Method Signatures (§13 Host-Worker Protocol)
 // ---------------------------------------------------------------------------
@@ -302,6 +355,8 @@ export interface RunJobParams {
 export interface GetDataParams {
   /** Plugin-defined data key (e.g. `"sync-health"`). */
   key: string;
+  /** Host-authorized active company scope, when this bridge call is company-scoped. */
+  companyId?: string | null;
   /** Context and query parameters from the UI. */
   params: Record<string, unknown>;
   /** Optional launcher/container metadata from the host render environment. */
@@ -316,6 +371,8 @@ export interface GetDataParams {
 export interface PerformActionParams {
   /** Plugin-defined action key (e.g. `"resync"`). */
   key: string;
+  /** Host-authorized active company scope, when this bridge call is company-scoped. */
+  companyId?: string | null;
   /** Action parameters from the UI. */
   params: Record<string, unknown>;
   /** Optional launcher/container metadata from the host render environment. */
@@ -1128,6 +1185,105 @@ export interface WorkerToHostMethods {
     },
     result: Goal,
   ];
+
+  // Access
+  "access.members.list": [
+    params: { companyId: string; includeArchived?: boolean },
+    result: PluginAccessMember[],
+  ];
+  "access.members.get": [
+    params: { memberId: string; companyId: string },
+    result: PluginAccessMember | null,
+  ];
+  "access.members.update": [
+    params: {
+      memberId: string;
+      companyId: string;
+      patch: {
+        membershipRole?: string | null;
+        status?: "pending" | "active" | "suspended";
+      };
+    },
+    result: PluginAccessMember,
+  ];
+  "access.invites.list": [
+    params: {
+      companyId: string;
+      state?: "active" | "revoked" | "accepted" | "expired";
+      limit?: number;
+      offset?: number;
+    },
+    result: { invites: PluginAccessInvite[]; nextOffset: number | null },
+  ];
+  "access.invites.create": [
+    params: {
+      companyId: string;
+      allowedJoinTypes?: "human" | "agent" | "both";
+      humanRole?: string | null;
+      defaultsPayload?: Record<string, unknown> | null;
+      agentMessage?: string | null;
+    },
+    result: PluginAccessInvite & { token: string },
+  ];
+  "access.invites.revoke": [
+    params: { inviteId: string; companyId: string },
+    result: PluginAccessInvite,
+  ];
+
+  // Authorization
+  "authorization.grants.list": [
+    params: { companyId: string; principalType?: string; principalId?: string },
+    result: PrincipalPermissionGrant[],
+  ];
+  "authorization.grants.set": [
+    params: {
+      companyId: string;
+      principalType: string;
+      principalId: string;
+      grants: Array<{ permissionKey: string; scope?: Record<string, unknown> | null }>;
+      grantedByUserId?: string | null;
+    },
+    result: PrincipalPermissionGrant[],
+  ];
+  "authorization.policies.summary": [
+    params: { companyId: string },
+    result: PluginAuthorizationPolicySummary,
+  ];
+  "authorization.policies.get": [
+    params: { companyId: string; resourceType: "company" | "agent" | "project" | "issue"; resourceId: string },
+    result: PluginAuthorizationPolicyRecord | null,
+  ];
+  "authorization.policies.update": [
+    params: {
+      companyId: string;
+      resourceType: "company" | "agent" | "project" | "issue";
+      resourceId: string;
+      policy: Record<string, unknown> | null;
+    },
+    result: PluginAuthorizationPolicyRecord,
+  ];
+  "authorization.policies.previewAssignment": [
+    params: PluginAssignmentPreviewInput,
+    result: PluginAuthorizationDecisionResult,
+  ];
+  "authorization.policies.explainAssignment": [
+    params: PluginAssignmentPreviewInput,
+    result: PluginAuthorizationDecisionResult,
+  ];
+  "authorization.audit.search": [
+    params: {
+      companyId: string;
+      action?: string;
+      actorType?: string;
+      actorId?: string;
+      entityType?: string;
+      entityId?: string;
+      decision?: string;
+      limit?: number;
+      offset?: number;
+    },
+    result: PluginAuthorizationAuditEntry[],
+  ];
 }
 
 /** Union of all worker→host method names. */