docs: explain individual agent interaction permissions (#20422)

Document all eleven interaction controls, sparse defaults, CLI administration, ownership rules, pending-delivery behavior, and access boundaries.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

doc/SPEC-implementation.md

@@ -881,6 +881,18 @@ Agent-authenticated changes cannot set or restore host-executed process adapter
 configuration, including commands and environment values. Agent-authenticated
 rollbacks cannot restore host-executed workspace commands either.
 
+### Individual agent interaction restrictions
+
+The optional `agents.permissions.interactions` object holds independent incoming
+and outgoing controls for assignments, mentions, comments, task edits and peer
+configuration, plus a separate outgoing assignment-to-humans control. Absence
+adds no restriction; explicit false cannot be bypassed by grants or agent roles.
+Human permission managers alone write the subtree through the dedicated API/CLI.
+No migration, default write, grant backfill or UI is introduced. Mutation and
+pending-delivery authorization use current settings while preserving history and
+running work. See [the interaction permission contract](agent-interaction-permissions.md)
+for the settings, ownership rules, atomic updates and compatibility boundaries.
+
 ### 9.3.1 Shared default-open issue writes
 
 For standard-trust agents, issue comments, issue field/status updates, child

doc/agent-interaction-permissions.md

@@ -0,0 +1,142 @@
+# Individual agent interaction permissions
+
+Interaction permissions are optional restrictions on actions between agents.
+They are independent of low-trust presets and principal permission grants. They
+have no UI or bundled preset; a human permission manager configures individual
+agents through the CLI or API.
+
+Every setting defaults to unrestricted when absent. Existing agents are not
+rewritten, new agents do not persist default values, and no migration or grant
+backfill is required. An explicit `true` removes this restriction only: company
+boundaries, visibility, trust, responsible-user authority, grants, approvals,
+checkout and execution rules still apply.
+
+## Settings
+
+| Operation | Outgoing setting | Incoming setting |
+| --- | --- | --- |
+| Assign/delegate work to an agent | `canAssignTasksToAgents` | `canReceiveAssignmentsFromAgents` |
+| Assign work to a human | `canAssignTasksToHumans` | Existing human authorization |
+| Mention another agent | `canMentionAgents` | `canReceiveMentionsFromAgents` |
+| Comment on another task | `canCommentOnOtherTasks` | `canReceiveCommentsFromAgents` |
+| Edit another task | `canEditOtherTasks` | `canReceiveTaskEditsFromAgents` |
+| Configure another agent | `canConfigureOtherAgents` | `canReceiveConfigurationChangesFromAgents` |
+
+An operation must pass both applicable sides. An explicit `false` is not
+overridden by a CEO role, manager relationship, assignment grant, parent-report
+exception, or the human responsible for the acting agent's run. Authenticated
+human actions retain their ordinary authorization without these agent-only
+restrictions.
+
+An ordinary task is owned by its current agent assignee; an agent's own
+conversation belongs to its canonical conversation agent. Human-assigned and
+unassigned tasks are other tasks for outgoing comments and edits. Creating a
+task, owning its parent, or formerly being its assignee does not establish current
+ownership. Self-interactions retain existing authorization.
+
+Assignments to a new agent check the sender and destination. Reassigning,
+unassigning, or claiming an existing task also checks edits against its current
+owner. Initial content on a newly assigned task is part of assignment; it does
+not require permission to edit that agent's existing tasks. Creating or moving
+a child under someone else's task checks the affected parent.
+
+Comments and task messages share the comment controls. Mentions are checked
+separately, so a permitted comment can still be denied for mentioning a protected
+agent. A denial rejects the entire operation. Structured Paperclip agent links
+are mentions; an ordinary name in prose is not. Allowed mentions retain their
+existing context-link behavior and do not start execution or forward messages.
+New or changed mention-bearing text is checked; unrelated edits do not rescan
+untouched history. Delegated reports have no automatic exception.
+
+Task edits include instructions, status, assignment, hierarchy, dependencies,
+execution policy, documents, attachments, work products, and feedback results.
+Compound operations must pass every applicable control. Posting a comment does
+not require edit permission solely because the server updates bookkeeping.
+
+Configuration controls cover peer instructions, settings, runtime configuration,
+skill/tool assignments, and restores. Shared company resources retain their
+existing permissions; changing a shared skill is not treated as editing every
+agent that uses it. Initial hiring remains governed by hiring authorization.
+
+## CLI and API
+
+Use a board-authenticated CLI context whose human has `users:manage_permissions`.
+Read access follows agent configuration read authorization. Agents, including
+CEOs, cannot change these restrictions.
+
+```sh
+paperclipai agent interaction-permissions <agent-id>
+
+paperclipai agent interaction-permissions:update <agent-id> \
+  --payload-json '{"canReceiveCommentsFromAgents":false}'
+
+paperclipai agent interaction-permissions:update <agent-id> \
+  --payload-json '{"canReceiveCommentsFromAgents":null}'
+```
+
+The last command removes that override. Omitted keys are preserved; `null`
+restores the default. Human-readable output identifies explicit versus default
+values. Both commands support `--json`.
+
+The underlying endpoints are `GET /api/agents/:id/interaction-permissions` and
+`PATCH /api/agents/:id/interaction-permissions`. PATCH accepts a nonempty partial map
+of the setting names to booleans or `null`. Unknown keys and malformed values
+are rejected. Responses contain `agentId`, `companyId`, sparse `overrides`, and
+the resolved `effective` map. Effective values describe this restriction layer,
+not the outcome of every other authorization rule.
+
+For an agent that should accept only human-directed interactions, explicitly
+set all five incoming controls to false:
+
+```sh
+paperclipai agent interaction-permissions:update <agent-id> --payload-json '{
+  "canReceiveAssignmentsFromAgents": false,
+  "canReceiveMentionsFromAgents": false,
+  "canReceiveCommentsFromAgents": false,
+  "canReceiveTaskEditsFromAgents": false,
+  "canReceiveConfigurationChangesFromAgents": false
+}'
+```
+
+This is a configuration example, not a stored preset. Outgoing controls remain
+independent and can be set individually.
+
+## Persistence and changes in flight
+
+Only the dedicated endpoint changes `agents.permissions.interactions`. It merges
+under the agent row lock and records the before/after audit in the same
+transaction. Saving does not start work, retry a task, reactivate membership, or
+alter unrelated grants. Pending hires cannot be changed before approval.
+
+Other permission/configuration saves preserve the subtree, including when an
+older client omits it. Attempts to change it through those APIs are rejected.
+Restores cannot revive older interaction permissions. Company package exports
+omit this instance's restrictions with a warning; configure the imported agent
+explicitly after creation rather than copying another agent's authority.
+
+Current restrictions are checked before pending execution and input delivery,
+including queued steering. Coalesced input retains per-item origin, so a human
+message does not authorize an otherwise prohibited agent message. Refused
+delivery retains an inspectable permanent policy outcome instead of retrying
+indefinitely. Removing the restriction later does not automatically replay the
+refused delivery.
+
+A refused child-completion report does not undo the child's completed work.
+The report keeps a terminal refusal receipt. Dependency completion can still
+notify the parent with a system event that contains no agent-authored report.
+
+Permission changes do not delete saved comments, rewrite assignments, terminate
+running work, or sanitize historical context. Subsequent actions from running
+agents use current permissions. Older queue records use existing source
+provenance when available; explicitly restricted work with insufficient
+provenance cannot be assumed to be human-authorized.
+
+Deploy compatible servers and workers before configuring restrictions. An older
+binary cannot enforce these controls. No existing agent is configured during
+deployment. These are addressed-action controls, not filesystem/network
+isolation or a new read-access boundary: agents can still read otherwise
+accessible history, shared files, skills, and external content.
+
+Direct connection installs, profile bindings, and gateways that target an agent are configuration changes. Shared connection/profile changes and connection reads keep their existing authorization checks without treating every consumer as a configuration recipient. Mutation services recheck direct targets under ordered agent locks, independently of the shared-resource authorization check.
+
+Plugin tool invocations retain the host-issued originating agent and run through host calls and queued delivery. A worker cannot replace that identity with a user or system label. Background plugin work without an originating agent retains its existing authority.

doc/agent-permission-defaults.md

@@ -44,3 +44,13 @@ Connection management always intersects the current human's authority, including
 See [the authorization and qualification record](plans/2026-10-13-connection-api-parity.md) and the operation-reviewed [agent access maps](../maps/agent-access-map/connection-setup.md). Human consent, credential entry and identity confirmation remain bounded handoffs to saved setup.
 
 Authorized policy administration includes user-requested changes that loosen the acting agent’s own tool controls. These writes remain bounded by management grants, resource scope and the responsible user’s current authority; they do not need an additional approval solely because the agent is a target. Subsequent tool calls obey the resulting policy. Agents cannot approve their own governed action requests or edit their own principal permission grants.
+
+## Individual interaction restrictions
+
+Optional incoming and outgoing [interaction permissions](agent-interaction-permissions.md)
+can narrow assignments, mentions, comments, task edits, and peer configuration.
+Missing settings preserve these defaults; no existing agent is backfilled and
+new agents do not persist default overrides. A human permission manager sets
+individual controls with `agent interaction-permissions:update`; explicit `true`
+does not override another authorization denial. These controls are separate from
+principal grants, `canAssignTasks`, and low-trust presets.

maps/agent-access-map/agents.md

@@ -63,6 +63,12 @@ bypass hiring authorization. Source: [runner resolver](../../server/src/services
 Policy: Agent creation/configuration uses action grants, resource policies and change
 consent; some controls require a board actor.
 
+`GET /api/agents/{id}/interaction-permissions` follows configuration-read access.
+`PATCH /api/agents/{id}/interaction-permissions` is restricted to board-authenticated
+human permission managers (`users:manage_permissions`); agents cannot change it.
+Optional [interaction restrictions](../../doc/agent-interaction-permissions.md)
+can independently deny peer configuration despite a configure/suggest grant.
+
 `agents:read` permits redacted configuration, configured skills, instruction content,
 and configuration/instruction history reads. It does not permit changes, restore,
 or environment probes. `agents:configure` still includes read/write authority;

maps/agent-access-map/documents-artifacts.md

@@ -5,6 +5,12 @@ products](../feature-map/documents-artifacts.md).
 
 Feature ID: `documents-artifacts`.
 
+[Agent interaction restrictions](../../doc/agent-interaction-permissions.md)
+apply to task document, attachment and work-product mutations, and to annotation
+comments. Newly submitted or changed structured mentions are checked separately.
+Initial content on a new task uses assignment authority. Existing read access
+and historical content remain unchanged.
+
 Review date: 2026-10-12. Source commit: `f981fa3cc10cb8663a87dec60345fbff46d54d0a`.
 
 This is a source-reviewed baseline of representative operations and known gaps.

maps/agent-access-map/steering.md

@@ -4,6 +4,12 @@ Product map: [Steering and queued messages](../feature-map/steering.md).
 
 Feature ID: `steering`.
 
+Pending agent-authored input is rechecked against current
+[interaction restrictions](../../doc/agent-interaction-permissions.md) per item,
+including when a human steers it. A denied item receives a permanent refusal;
+other allowed items retain their own authority. History and already running
+execution remain intact. Restoring a setting does not replay refused input.
+
 Review date: 2026-10-12. Source commit: `58e16dbddfc9c8d0cf60867f9d9847f0feda055b`.
 Native REST transport reconciled in this change; see the
 [shared transport contract](README.md#native-rest-transport).

maps/agent-access-map/tasks.md

@@ -4,6 +4,12 @@ Product map: [Task creation and lifecycle](../feature-map/tasks.md).
 
 Feature ID: `tasks`.
 
+Optional [agent interaction restrictions](../../doc/agent-interaction-permissions.md)
+add sender and recipient checks to assignments, comments, task mutations and
+structured mentions. Current assignment establishes ownership. Self-claim and
+reassignment also check the previous owner; child placement checks the parent.
+These restrictions add no grants and leave absent settings unrestricted.
+
 Source revision: `3bbc2104b65caf9f7763938a01260a5673e12f7a`.
 
 Review depth and executed proof are separate. The operation records enumerate the named behavior and access boundaries. Their evidence states describe the reviewed sources; run results and environment limits belong in the PR or verification artifacts. A listed API or source test does not establish a live authorized journey. Follow the [map contract](../README.md).