diff --git a/doc/SPEC-implementation.md b/doc/SPEC-implementation.md index cf0a49b1094..f0eb256c26e 100644 --- a/doc/SPEC-implementation.md +++ b/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 diff --git a/doc/agent-interaction-permissions.md b/doc/agent-interaction-permissions.md new file mode 100644 index 00000000000..f32cd94d7eb --- /dev/null +++ b/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 + +paperclipai agent interaction-permissions:update \ + --payload-json '{"canReceiveCommentsFromAgents":false}' + +paperclipai agent interaction-permissions:update \ + --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 --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. diff --git a/doc/agent-permission-defaults.md b/doc/agent-permission-defaults.md index edf9fa18f4e..637f173e560 100644 --- a/doc/agent-permission-defaults.md +++ b/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. diff --git a/maps/agent-access-map/agents.md b/maps/agent-access-map/agents.md index 96f9550ca37..1e4cfbd740c 100644 --- a/maps/agent-access-map/agents.md +++ b/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; diff --git a/maps/agent-access-map/documents-artifacts.md b/maps/agent-access-map/documents-artifacts.md index 4d840550cc5..73b646880f9 100644 --- a/maps/agent-access-map/documents-artifacts.md +++ b/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. diff --git a/maps/agent-access-map/steering.md b/maps/agent-access-map/steering.md index 0655c5b7955..d124fbd82d6 100644 --- a/maps/agent-access-map/steering.md +++ b/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). diff --git a/maps/agent-access-map/tasks.md b/maps/agent-access-map/tasks.md index 07604564b8a..dbb21285648 100644 --- a/maps/agent-access-map/tasks.md +++ b/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).