Runtime and tool governance
Runtime and tool governance controls where agent work runs, which tools it may use, how credentials reach those tools, and what evidence remains after each action. It joins trust policy, low-trust containment, runtime leases, provider capabilities, tool catalogs, access profiles, gateway checks, OAuth, native-run controls, and audit records. This page is part of Security and governance; see Identity and access control for actor permissions and Secrets and credentials for secret ownership.
Governance model
The governance model combines policy from the agent, project, workspace source project, issue, and run before execution. A workspace source project is the project whose workspace policy also applies when it supplies the execution workspace. The result is standard execution, a bounded low-trust review, or denial.
The main trust outcomes are:
- Standard: normal execution rules apply.
- Low-trust review: work uses an isolated workspace and a sandbox. Its issue, agent, tools, secrets, and promotion target stay inside the active boundary.
- Denied: malformed, unsafe, conflicting, or out-of-scope policy stops the operation.
Policy layers intersect their scopes. A later layer cannot widen an earlier boundary. Missing boundary scope, cross-company data, conflicting roots, and invalid policy shapes fail closed. Agent-to-agent work adds a second boundary: assignment, comment, edit, configuration, and mention operations check both the actor's outgoing permission and the target agent's incoming permission.
Low-trust containment
Low-trust execution is a review lane for work whose source or output must not flow directly into a higher-trust context. Its boundary can limit the company, project, issue set, allowed agents, secret bindings, tool classes, and promotion target. Inbound chat review uses the same bounded lane and marks its output as quarantined.
Before a low-trust run starts, runtime admission checks the issue and agent boundary, isolated workspace mode, and sandbox driver. A low-trust run cannot start a runtime service unless its boundary grants runtime.manage. The containment flow narrows authority before it selects an execution environment.
flowchart LR
A[Agent, project, issue, and run policy] --> B[Intersect trust boundary]
B --> C{Valid bounded scope?}
C -->|No| D[Deny]
C -->|Yes| E{Low-trust review?}
E -->|No| F[Standard runtime admission]
E -->|Yes| G[Isolated workspace and sandbox]
G --> H[Quarantined output]
Source trust
Source trust marks data produced by a low-trust run so downstream agents do not treat it as trusted work. New output stays quarantined until a trusted actor promotes a selected artifact. Promotion retains the source artifact and promoting actor for review. Agent writes are checked against the agent, project, issue, and heartbeat run; an unknown or mismatched run cannot prove higher trust.
References: server/…/source-trust.ts• L1-240 server/…/trust-preset-resolver.ts• L1-260 server/…/low-trust-runtime-containment.ts• L1-230
Agent interaction boundaries
Agent interaction boundaries control whether one agent may change or address another agent's work. A denied interaction stops before the task or delivery mutation and reports the direction and permission that blocked it, which keeps agent autonomy separate from human management authority.
References: server/…/agent-interaction-policy.ts• L9-23 server/…/agent-interaction-policy.ts• L47-137
Execution workspace selection
Execution workspace selection turns project and issue settings into one workspace mode, strategy, and environment. Issue settings take precedence over an enabled project policy, while legacy settings remain a fallback; mode alone does not silently imply a Git worktree.
The system supports shared workspaces, isolated workspaces, operator branches, adapter-managed work, and cloud sandboxes. A project without a reusable workspace is denied rather than given an unrunnable worktree. Managed-sandbox-only mode redirects a local default to an active managed environment and fails closed when none exists.
References: server/…/execution-workspace-policy.ts• L55-109 server/…/execution-workspace-policy.ts• L164-209 server/…/execution-workspace-policy.ts• L268-347 server/…/execution-workspace-policy.ts• L381-486
Runtime boundaries
Runtime boundaries keep agent code, tools, and workspace data inside an execution context with a known lifetime and limited capabilities. The host resolves configuration and secrets, acquires or resumes a lease, realizes the workspace, exposes only verified capabilities, and records release or cleanup evidence.
Sandbox providers
The sandbox provider contract gives runtime execution one lifecycle for configuration checks, probes, leases, workspace preparation, command execution, file transfer, and cleanup. A provider's effective capability snapshot is the intersection of static support, verified worker methods, provider declarations, and per-lease narrowing. Opt-in features such as duplex streams, runner ingress, concurrent sync, and incremental output are denied unless the provider explicitly declares and verifies them.
Provider configuration is validated before persistence or probing. Provider-defined secret fields become secret references; runtime resolution supplies values only for the active environment and run. Host-owned run behavior, such as runner lifecycle and idle limits, remains effective after provider normalization. Old removed sandbox flags are ignored rather than allowed to change runtime behavior.
Lease expiry cannot exceed the caller deadline. Reusable leases match company, environment, workspace or issue, agent, adapter, provider, workspace sentinel, and effective configuration. A failed provider configuration lookup narrows sensitive runtime features instead of granting them.
Providers keep their isolation and transfer guarantees behind the same host contract. Local and SSH drivers expose no sandbox capability model. A sandbox Job backend can use the normal transfer path when it has no native sync channel. Provider cleanup retains immutable lease evidence so an orphan can be retried even after the environment changes or is deleted.
References: server/…/environment-runtime.ts• L152-180 server/…/environment-runtime.ts• L286-395 server/…/environment-config.ts• L183-216 server/…/environment-config.ts• L425-457 server/…/environment-config.ts• L627-663 server/…/sandbox-provider-runtime.ts• L1-260
Environment run lifecycle
The environment run lifecycle resolves the selected environment, checks its company binding and active state, acquires or reattaches a lease, resolves transport, realizes the workspace, and releases the lease. The orchestrator is the single control point for these stages, so adapters do not create parallel lease or workspace rules.
flowchart LR
A[Select active environment] --> B[Acquire or reattach lease]
B --> C[Resolve transport]
C --> D[Realize workspace]
D --> E[Run adapter work]
E --> F[Release, retain, or destroy]
F --> G[Activity and cleanup evidence]
Provider acquisition failures are retried only before agent work starts and only when structured evidence marks them as transient. The retry lane uses bounded waits of one, two, and five minutes, a 30-minute ceiling, and a finite attempt count. Each retry is a new idempotent creation attempt; an unfinished allocation remains owned by its own cleanup record rather than being reused by a later attempt.
References: server/…/environment-run-orchestrator.ts• L5-18 server/…/environment-run-orchestrator.ts• L225-267 server/…/environment-run-orchestrator.ts• L301-485 server/…/environment-provider-unavailable-error.ts• L31-111 server/…/environment-provider-wait.ts• L1-73
Native runtime selection
The Paperclip Runner is the controlled path for native agent runtimes. A fresh run enters native mode only when its provider profile, rollout gates, agent state, work mode, and rollout policy are valid. Provider identity is selected from the persisted agent configuration and then projected into a closed runtime profile; task overrides may change a supported model or effort, but cannot switch the harness or its bound remote resource.
Native profiles qualify the provider, model, permission mode, runtime version, and any required managed account. Codex compatibility uses an explicit stable version window rather than a registry lookup. A persisted native run keeps its selected driver and provider identity during recovery. Unknown drivers, inactive agents, adapter changes, invalid profiles, and stale managed identities fail closed.
References: server/…/provider-profile.ts• L247-272 server/…/provider-profile.ts• L451-489 server/…/provider-profile.ts• L699-749 server/…/codex-runtime-compatibility.ts• L1-43
Native tool exposure
Native tool exposure is rebuilt from the current run mode and server-owned binding. Standard runs can receive first-party Paperclip tools, approved connector tools, assigned MCP tools, and bounded workspace or API surfaces. Planning, ask, skill-test, review, first-party-only, Muse, and Dot profiles narrow that surface rather than relying on the provider to enforce the mode.
Assigned MCP discovery is not a grant. A native session pins a catalog for stable names and schemas, but every call returns through the configured gateway so revocation, policy, approval, rate limits, OAuth refresh, and audit still apply. Large or provider-sensitive schemas use bounded search and schema pages instead of widening the provider's tool payload.
Review runs expose only task inspection and review resolution. State-changing native tools use durable receipts and idempotency keys. A crash therefore preserves an unknown effect for reconciliation instead of replaying a mutation without proof.
References: server/…/paperclip-runner-tool-authority.ts• L394-487 server/…/paperclip-runner-tool-authority.ts• L490-589 server/…/assigned-mcp-tools.ts• L286-355 server/…/assigned-mcp-tools.ts• L430-465
Native session recovery
Native recovery preserves the boundary between a controller, a provider session, a workspace lease, and the run that owns them. Durable checkpoints bind session evidence to company, issue, run, session, runner, and environment identities. Recovery can reattach or resume only when those identities and ownership leases still match.
The system distinguishes a provider turn that never started from a turn whose outcome is unknown. A setup failure with proof that no provider turn was accepted can move to a fresh sandbox. A scheduled same-run resume requires an exact checkpoint, an established provider session, an admitted attempt, and verified local stop evidence. Remote or unproven cases do not use that shortcut.
Controller migration and warm-session handoff preserve old state only when the source is bound, immutable, and proven settled. If retirement is unproven, the successor does not launch over the old owner; it waits, uses another sandbox, or leaves the source for cleanup. Checkpoints are encrypted and rejected when their binding does not match.
References: server/…/native-runner-checkpoint.ts• L30-55 server/…/native-runner-checkpoint.ts• L91-129 server/…/native-runner-checkpoint.ts• L405-467 server/…/scheduled-resume-continuation.ts• L56-94 server/…/plugin-runner-task.ts• L136-178
Native input and completion contracts
Native turns use a server-owned completion contract that states the current objective, criteria, completion authority, risk, and source provenance. A newer request creates a new contract revision. The run must report against its bound revision and exact criterion set before the server considers the report.
Messages that arrive while a native run is preparing can join its first provider turn only when they are plain comments from the responsible user. The run seals that input before the turn starts. Delivery is complete only after the provider accepts the turn, so a restart before acceptance does not lose or duplicate the message. Quarantined source text is sanitized before it crosses into a higher-trust run.
Completion feedback checks current task state, wake comments, review assignments, deliverable evidence, quality review, dependencies, and configured review stages. A model's done claim is evidence for the arbiter, not a status command. Pull-request work products cannot complete the task until their canonical GitHub references are verified as merged.
References: server/…/completion-contracts.ts• L80-143 server/…/completion-contracts.ts• L149-239 server/…/first-turn-queued-input.ts• L83-114 server/…/first-turn-queued-input.ts• L209-269 server/…/native-completion-feedback.ts• L85-170 server/…/native-pull-request-completion.ts• L17-57
Native status arbitration
Native status arbitration converts verified run evidence into one durable issue decision. It preserves the task when work is incomplete, binds a concrete blocker or review, schedules an allowed continuation, or moves the task to its authoritative status. A newer run or reassignment can supersede an older result without allowing the older result to change current ownership.
The decision is committed before its effects are delivered. Interactions, reviewer wakes, blockers, retries, recovery actions, and status projections are recorded as idempotent effects with target checks. Delivery can resume from the ledger without re-running arbitration. This keeps a crash between decision and notification from creating a second completion or losing a required recovery action.
Automatic recovery is bounded. Environment blockers may receive fresh sessions only within their retry limit. An agent-owned blocker receives at most one continuation. Provider overload, tool receipt limits, failed turns, provider usage limits, and workspace finalization each use their own evidence and retry lane. A full sandbox disk does not trigger an identical automatic retry because the same work would fill the same capacity again.
References: server/…/status-arbiter.ts• L208-279 server/…/status-arbiter.ts• L383-451 server/…/status-arbiter.ts• L618-708 server/…/status-decision-committer.ts• L107-206 server/…/native-sandbox-disk-full.ts• L4-56
Cleanup and orphan recovery
Cleanup preserves ownership evidence when acquisition or release fails. Durable pending-cleanup records, bounded work, and a local deferred spool allow a later sweep to stop or delete a live sandbox. A timeout is not treated as proof that provider termination failed. If termination and durable cleanup both fail, the live orphan remains visible for manual action.
Workspace recovery can re-arm an exhausted save only when the source run and coordinator are over and a newer capture policy can handle the retained files safely. The recovery records its policy version and generation, then queues one save without submitting another provider turn.
References: server/…/environment-runtime.ts• L734-767 server/…/environment-runtime.ts• L1191-1199 server/…/environment-runtime.ts• L1290-1297 server/…/workspace-recovery-capture-policy.ts• L13-77
Runtime exposure and supervision
Managed runtime exposure publishes an eligible development service only through an approved HTTPS contract. Explicit opt-out wins, explicit opt-in fails when HTTPS is unavailable, and automatic exposure applies only to eligible managed runtimes. Local stdio connections use an approved built-in or active administrator template. Authenticated public deployments require a trusted runtime host before local stdio can be enabled.
The runtime supervisor manages local stdio slots. It limits company and host capacity, bounds redacted logs, detects stuck slots, applies restart backoff, and suppresses restart storms. Health joins slot, connection, call, credential, capacity, restart, and audit-write signals. Removing a connection revokes its grants and access records, discards OAuth state, revokes gateway tokens and sessions, and attempts to stop every associated slot before credential cleanup.
References: packages/…/runtime-exposure.ts• L1-160 server/…/tool-access.ts• L873-932 server/…/workspace-runtime.ts• L1-250 server/…/tool-runtime-supervisor.ts• L1-300 server/…/health.ts• L46-229 server/…/removal.ts• L484-519
Tool catalogs and access profiles
Tool governance separates what a connection offers from who may use it. Discovery produces a reviewed catalog. Profiles, installations, and policies then decide whether a catalog entry is reachable, visible, callable, or subject to review.
Catalog discovery
Discovery probes a connection through its approved credential path before it publishes tools. Remote MCP connections use guarded HTTP and negotiate the server's protocol shape. Read-only discovery may renew a stale session once, but malformed pagination, invalid responses, scope failures, unsafe reserved names, and failed provider probes are not accepted.
Reviewed REST adapters, native provider catalogs, plugin connectors, local stdio templates, and remote MCP servers share the catalog boundary. Provider rules and declarations classify risk. A legacy plugin tool without a reviewed declaration is classified from its name, with delete-like names treated as destructive and write-like names treated as writes. A new or changed action can enter quarantine, while a removed action becomes unavailable. A current-entry check runs again before dispatch.
Health checks use the same discovery and credential path but bypass a cached tool list. They persist a classified connection state, mirror local runtime slot health, audit the result, and notify dependent work. An unreachable saved MCP URL is a final configuration result rather than a reason to try alternate hosts.
flowchart LR
A[Connection and grant] --> B[Approved provider probe]
B --> C{Connection type}
C -->|Remote MCP| D[Guarded tools/list]
C -->|Reviewed REST or native| E[Provider contract]
C -->|Plugin or stdio| F[Owned catalog]
D --> G[Risk and schema catalog]
E --> G
F --> G
G --> H[Active, quarantined, disabled, or removed]
References: server/…/discovery.ts• L117-177 server/…/discovery.ts• L223-343 server/…/discovery.ts• L503-535 server/…/failures.ts• L180-195 server/…/health.ts• L83-248
Tool access profiles
Tool access profiles describe which catalog tools an actor may use. A profile has a default allow or deny action and can include or exclude tools by application, connection, catalog entry, tool name, or risk level. Bindings attach profiles to a company, agent, project, routine, issue, or gateway. The narrowest matching scope wins, followed by policy priority and stable creation order.
The catalog is a review boundary. A review covers the complete current pending set and creates explicit entries only for actions the reviewer allows. Profile views and review counts use active catalog entries, so disabled, archived, and removed entries do not remain visible through an old profile. The access view presents each action as allowed, ask first, or off.
Installation grants connection reach and creates a tagged binding. Uninstall removes only that installation binding; a direct access-model binding remains. Assignment changes lock the connection, application, profiles, policies, and affected agents before they change reach.
References: server/…/service.ts• L28-240 server/…/projection.ts• L89-260 server/…/resolution.ts• L19-266 server/…/installs.ts• L105-337 server/…/publication.ts• L295-355
Connection identities and credential reach
Connection identities define whose provider authorization can reach a tool. The service supports organization grants, personal user grants, and dedicated agent grants. Organization audiences contain active company members; personal identity stays tied to its owner; delegation requires the personal grant owner and an active company member.
At call time, credential access selects the actor's personal grant when required, otherwise the default organization grant. A per-agent connection has one active agent identity and cannot be silently reused by another agent. The service resolves the secret only for that connection and actor, refreshes OAuth when needed, and records credential resolution without storing bearer values in ordinary connection data.
References: server/…/grants.ts• L117-268 server/…/agent-grant.ts• L17-109 server/…/credential-access.ts• L45-145 server/…/credential-access.ts• L181-323
Connection removal and content deletion
Connection removal is a credential-revoking teardown rather than a status change. It closes database access paths, grants, installs, app-managed profiles, gateway tokens and sessions, OAuth state, catalog actions, and live runtime slots before it removes secrets. Shared or operator-managed secrets are retained. The connection identity and activity history remain so a later reconnect requires fresh authentication and access setup.
Stored tool content has a separate deletion flow. It clears eligible invocation summaries, approval previews and signed arguments, tool-call event content, app views, delivered action results, run output, and external run logs in bounded phases. Unsettled runs and in-flight actions remain until they settle, so deletion does not break work that still needs a result.
Managed Google access removal reports whether provider access ended, remains through another connection, or could not be confirmed. It records the provider outcome and deletes a refresh secret only when the secret is owned solely by the removed grant or connection.
References: server/…/removal.ts• L218-233 server/…/removal.ts• L359-481 server/…/removal.ts• L521-685 server/…/content-deletion.ts• L182-235 server/…/content-deletion.ts• L329-411 server/…/google-access-removal.ts• L44-55 server/…/google-access-removal.ts• L191-265
Execution policies
Execution policies add ordered decisions around profiles and explicit grants. A policy can allow a call, block it, require human approval, or enforce a rate limit. Conditions can inspect arguments, actor and work context, risk, credential scope, trust boundary, and UTC time. Unsupported policy types, malformed conditions, unsafe argument patterns, and invalid limits deny a call.
Risk is part of the decision contract. Reads can pass under a read profile. Writes can require approval, and destructive actions can require formal approval. A remembered rule remains valid only while its arguments, catalog version, and schema constraints match. An explicit block remains stronger than a remembered approval.
Human review is a control-plane transaction. Only a human can resolve a tool review. The decision checks the request, invocation, task, interaction, expiry, and formal approval before it updates the invocation and interaction. Approved arguments are signed and reused exactly. Sensitive arguments use a protected identity and encrypted approval payload rather than a plain audit preview.
References: server/…/tool-access-policy.ts• L1-300 server/…/tool-content-guards.ts• L84-287 server/…/review-queue.ts• L8-114 server/…/tool-gateway.ts• L2414-2719
Gateway dispatch
The tool gateway is the common entry point for agent and external MCP calls. It exposes filtered discovery and calls through short-lived run sessions or named gateways with bearer tokens. Each request is tied to its company and, where needed, its agent, active run, issue, project, gateway, and token action.
The dispatch path applies governance before provider execution:
sequenceDiagram
participant C as Client or agent
participant G as Tool gateway
participant P as Profile and policy checks
participant A as Approval and audit
participant R as Runtime or provider
C->>G: Authenticate and discover or call
G->>P: Resolve context and access
P-->>G: Allow, deny, rate limit, or approval
alt Approval required
G->>A: Store signed request and notify reviewer
A-->>G: Human decision
end
G->>R: Dispatch governed action
R-->>G: Result or failure
G->>A: Store redacted outcome
G-->>C: Structured response
Provider dispatch supports remote HTTP MCP, supervised local stdio MCP, reviewed REST adapters, native providers, plugin tools, and Paperclip-owned tools. Caller headers use an allowlist; reserved and sensitive headers are dropped, and managed credentials win collisions. Provider results pass content checks before storage or return.
Discovery applies policy to the whole listing with bounded concurrency. Long or colliding upstream names receive bounded aliases while the original connection and upstream name remain the dispatch identity. On-demand connections expose virtual search_tools and run_tool surfaces, but the target tool still receives its own profile, policy, approval, and rate-limit checks.
Native runner authority
The native runner authority exposes Paperclip's own tools for the current work mode and run context. It checks the company, agent, issue, assignment, and active-run binding again before execution. Review runs use a separate narrow surface and cannot perform ordinary work or change task ownership. State-changing actions use durable receipts and idempotency keys so a crash preserves an unknown outcome instead of replaying a possibly committed mutation.
References: server/…/paperclip-runner-tool-authority.ts• L362-487 server/…/paperclip-runner-tool-authority.ts• L658-747 server/…/paperclip-runner-tool-authority.ts• L778-832
Plugin tool dispatch
Plugin tools enter the gateway through a namespaced registry derived from ready plugin manifests. Legacy top-level plugin tools are visible only when an active installed plugin connection grants them. The dispatcher validates the declared input shape, checks that the owning worker is running, and removes names when a plugin is disabled or unloaded.
References: server/…/plugin-tool-dispatcher.ts• L1-220 server/…/tool-gateway.ts• L1726-1787 server/…/tool-gateway.ts• L1884-2001
Connection token brokering
Connection token brokering gives an agent a short-lived exchange token only when the connection opts into brokering and the agent has an exact broker profile grant. The broker checks active run context, responsible-user membership, audience, connection health, scope, policy, and rate limits. The issuance record stores scope, expiry, and a token hash, not the bearer value. Static credentials use an audited environment lease instead of token delivery.
Named gateway delegation applies the same rule to the gateway issuer. The token must remain active, unexpired, unrevoked, bound to the issuing agent and gateway, and allowed for the requested action.
References: server/…/tool-gateway.ts• L1184-1220 server/…/tool-gateway.ts• L1253-1318 server/…/admission.ts• L72-253
Tool content safeguards
Tool content safeguards treat provider output as data that may contain secrets or instructions aimed at changing agent behavior. They redact sensitive values and can detect prompt-injection findings before a result reaches the caller.
The classifier runs with the admitted session identity and run cancellation signal. When model classification is unavailable or its input would differ from the redacted content delivered to the caller, bounded pattern checks provide the fallback. Findings block results by default and record detector type, fallback reason, findings, and invocation identity.
References: server/…/tool-content-guards.ts• L17-22 server/…/tool-content-guards.ts• L310-370 server/…/tool-gateway.ts• L1184-1207 server/…/tool-gateway.ts• L10999-11098
OAuth handling
OAuth connects a tool connection to a provider without storing access or refresh tokens in ordinary connection configuration. Credentials live in the Paperclip vault or Vercel Connect. The gateway resolves them at call time and can refresh a customer-owned grant before one retry.
Authorization start validates the app connector policy, redirect target, actor, subject, and requested scopes. Curated app scopes come from reviewed defaults. Generic MCP scopes come from the discovered provider contract. Redirects use HTTPS, or HTTP only for loopback callbacks. Short-lived state binds the flow to the actor, session, subject, issuer, resource, interaction, and requested scopes, then uses authorization-code PKCE.
Provider endpoints and OAuth clients are bound to the company, issuer, resource, and callback used to create them. Learned endpoints pass the shared safe-URL check. The resource indicator binds the token to the connected server. The callback validates the same issuer and consumes state once before it stores credentials.
OAuth completion keeps personal credentials on a user grant when the connection is personal. An organization grant records the subject that consented so provider access removal can revoke under that subject, while refresh continues to use the grant's established subject rule. A dedicated agent identity stays bound to that agent. Reconnect cannot change the fixed owner of a personal connection.
First setup remains a draft until its catalog and recommended access are finalized. Reconnect refreshes credentials and the catalog without rebuilding the operator's profile, policy rules, or access bindings. New or changed actions can remain quarantined. Callback completion rechecks connection-management authority and resolves linked issue interactions so a waiting workflow receives the terminal result.
Refresh uses in-process single-flight and a database lease so concurrent workers do not rotate the same credentials at once. A replacement refresh token is stored before the new access token is returned. A failed or superseded refresh becomes a visible reconnect or health state. Scope checks use the grant's original requested baseline, so a provider cannot silently widen a grant during refresh.
The OAuth state store validates the initiating actor and authenticated session before callback consumption. A callback can be consumed only once. A provider decline changes a linked connection request to a retry state or closes its pending interaction, so the requesting workflow does not wait forever on an authorization that did not occur.
Public MCP OAuth
Public MCP OAuth gives external clients a bounded Paperclip connection to a personal or agent resource. The endpoint accepts HTTPS origins, public-client PKCE, exact resource and redirect checks, short-lived access tokens, and rotating refresh tokens where the grant allows offline access.
Personal grants receive only the explicitly consented company. Agent grants require an active non-viewer membership, a valid agent binding, and the current provider authority. Device authorization and public client registration have shared capacity limits, one-time state or code consumption, and revocation indexing so disabled or revoked grants stop authenticating.
References: server/…/oauth.ts• L39-57 server/…/oauth.ts• L114-177 server/…/oauth.ts• L180-250 server/…/oauth.ts• L410-420 server/…/oauth.ts• L488-615
References: server/…/authorization-start.ts• L42-141 server/…/authorization-start.ts• L448-561 server/…/client-settings.ts• L133-172 server/…/direct-callback.ts• L57-156 server/…/direct-callback.ts• L165-416 server/…/cloud-callback.ts• L45-166 server/…/cloud-callback.ts• L165-229 server/…/catalog-completion.ts• L16-151 server/…/grant-refresh.ts• L41-245 server/…/grant-refresh.ts• L248-665 server/…/state.ts• L19-117
Audit controls
Audit records make governance decisions inspectable without copying sensitive payloads. Tool records include actor and run context, profiles, matched policies, risk, redaction state, request identity, rate-limit state, provider metadata, content findings, and outcome. Gateway records preserve client and correlation data across discovery, rejection, approval, dispatch, completion, elicitation, and failure.
Activity views combine connection lifecycle events, token issuance outcomes, tool invocations, action requests, and tool-call events. They return bounded, redacted views. Content deletion keeps structural evidence while clearing stored result text and approval material after settled work. Audit-write failures are counted and surfaced as runtime health signals rather than hidden inside an ordinary tool error.
Native runs add durable evidence for provider turns, tool receipts, completion contracts, status decisions, recovery actions, checkpoints, workspace finalization, and runtime ownership. This lets the system distinguish an unstarted turn, an accepted result awaiting finalization, a superseded result, and an unknown external effect. The distinction controls whether Paperclip may retry, resume, preserve, or require a person.
References: server/…/tool-gateway.ts• L1810-1860 server/…/tool-gateway.ts• L2188-2258 server/…/service.ts• L12-356 server/…/content-deletion.ts• L452-583 server/…/content-deletion.ts• L677-727 server/…/tool-access.ts• L780-818 server/…/native-runner-checkpoint.ts• L214-260 server/…/native-run-finalizer.ts• L228-307
Change checklist
When these files or sections are changed, remember to consider these:
- Changing trust presets or boundary fields requires aligned validation, policy intersection, low-trust preflight, and source-trust provenance.
- Changing workspace mode, environment precedence, provider configuration, or runtime lifecycle requires checking secret-reference handling, host-owned flags, capability narrowing, lease deadlines, reattachment, and cleanup evidence.
- Changing transient provider classification or wait behavior requires checking structured evidence, pre-agent retry boundaries, new creation identities, parked-run state, wake reasons, and the cleanup reconciler.
- Changing provider capabilities requires checking static support, verified worker methods, declarations, per-lease narrowing, native transfer gates, duplex or ingress gates, and the caller-facing capability snapshot.
- Changing native provider profiles or compatibility windows requires checking immutable provider identity, model qualification, permission modes, managed-profile binding, persisted driver selection, and recovery behavior.
- Changing native tool exposure or assigned MCP delivery requires checking work-mode surfaces, pinned catalog identity, fresh grant reauthorization, schema budgets, gateway routing, and durable mutation receipts.
- Changing completion contracts, queued first-turn input, or completion feedback requires checking source provenance, contract revision binding, exact criteria, responsible-user authority, delivery acceptance, review stages, deliverables, and pull-request merge verification.
- Changing native status arbitration or effect delivery requires checking stale-owner suppression, decision versioning, idempotent effects, blocker ownership, continuation limits, pending interactions, and reconciliation without re-arbitration.
- Changing native recovery, checkpoints, controller migration, warm handoff, or provider-task reattachment requires checking run/session/environment identity, lease fencing, stop proof, source retirement, credential handoff, and no-launch recovery paths.
- Changing runtime exposure or local stdio controls requires checking approved templates, trusted-host admission, loopback ownership, capacity, restart suppression, slot health, and connection-removal shutdown.
- Changing catalog discovery or connector risk requires checking credentialed probes, current-entry checks, provider declarations, legacy plugin risk fallback, quarantine, removed actions, health classification, and dispatch.
- Changing profile selectors, installations, or access bindings requires checking active catalog matching, exclusions, company and agent scope, install-created binding removal, mutation locks, and call-time access.
- Changing grants or connection removal requires checking personal identity, active audiences, delegations, secret ownership, provider revocation, runtime slots, gateway tokens and sessions, OAuth state, and retained history.
- Changing content deletion requires checking settled-run guards, in-flight action preservation, invocation and approval summaries, event payloads, app views, delivered results, run logs, bounded progress, and retry safety.
- Changing OAuth redirect, discovery, client registration, callbacks, or public MCP OAuth requires checking safe origins, issuer and resource binding, PKCE, actor and subject state, exact scopes, client reuse, device limits, grant purpose, and one-time consumption.
- Changing OAuth refresh or managed connector subjects requires checking single-flight and durable leases, compare-and-set writes, grant-specific scope baselines, replacement refresh tokens, consent-subject revocation, connection health, and reauthorization state.
- Changing gateway discovery, aliases, headers, virtual tools, or token brokering requires checking active catalog rows, name collisions, target policy rechecks, header precedence, rate limits, token actions, run identity, and digest-only audit data.
- Changing content checks or audit projections requires checking redaction parity, classifier fallback, cancellation, detector metadata, content deletion behavior, and audit-write health signals.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A low-trust run selects a shared workspace or non-sandbox driver | Untrusted work can run outside its boundary | Runtime admission requires isolated workspace mode and a sandbox driver |
| A provider capability is declared but not verified, or config resolution fails | The host may expose an unsafe stream, session, sync, or ingress path | Effective capabilities are the intersection of support, verification, declaration, and lease narrowing |
| A fresh native profile changes harness identity or a persisted run loses its provider binding | Recovery may run unintended code or use an unqualified account | Provider selection is closed and persisted; recovery rechecks profile identity and qualification |
| A native checkpoint or warm owner does not prove its run, session, runner, or environment binding | A successor may replay or launch over another owner | Checkpoints, leases, stop proof, and controller state must match before adoption or resume |
| A queued user comment is sealed before the provider accepts the first turn | Input may appear delivered even though no provider turn can process it | The receipt is sealed transactionally and delivery completes only after turn acceptance |
| A completion report names an old contract or omits a required criterion | Stale evidence can close or review the wrong request | Feedback checks the bound contract revision and exact criterion IDs |
| A native result arrives after reassignment or a newer status decision | An old run can change the current owner's task | Status arbitration preserves or supersedes stale-owner results |
| A workspace finalization fails after provider success | Work can be stranded or a second provider turn can duplicate it | Finalization has its own bounded recovery path and retries the saved result, not provider work |
| A sandbox disk is full | Repeating the same run fails again and can hide the saved result | Disk-full classification preserves the result and requires space cleanup before Retry |
| A plugin tool has no reviewed risk declaration | A write can be treated as a harmless read | Legacy plugin risk is inferred conservatively from the tool name, with destructive verbs taking precedence |
| A reviewed action is new, changed, removed, or no longer current | An old profile can enable the wrong provider action | Catalog quarantine, active-entry filtering, current-entry checks, and removed status protect dispatch |
| A connection is removed while a gateway token, OAuth state, or local runtime is live | A caller or child process can retain an access path | Removal revokes grants and gateway sessions, discards state, stops slots, archives access, and clears or revokes credentials |
| Stored tool content belongs to an unsettled run or action | Deletion can break a workflow that still needs its result | Content deletion keeps unsettled items and processes settled content in bounded resumable phases |
| OAuth callback state, issuer, resource, subject, or scope does not match | Credentials are not stored and the flow must restart | State is actor-bound and single-use; callback and grant checks fail closed |
| OAuth refresh returns widened or unverifiable scopes, or loses its lease | A grant can silently gain authority or overwrite a newer refresh | Per-grant scope baselines, leases, compare-and-set writes, and visible reauthorization states serialize refresh |
| Caller headers contain credentials or collide with managed headers | A caller can replace or leak the credential used for dispatch | Sensitive headers are dropped and managed credentials win collisions |
| A provider result contains prompt-injection instructions or audit writing fails | The caller may trust unsafe output, or governance evidence may be lost | Content checks block findings; audit-write failures surface through runtime health |
Key files
| File | Why to read it |
|---|---|
| server/…/trust-preset-resolver.ts | Defines how trust sources become one effective decision. |
| server/…/low-trust-runtime-containment.ts | Shows the preflight boundary for isolated sandbox execution. |
| server/…/source-trust.ts | Shows quarantine, provenance, and promotion of low-trust output. |
| server/…/execution-workspace-policy.ts | Defines workspace mode, strategy, environment precedence, and managed-sandbox-only selection. |
| server/…/environment-config.ts | Defines environment validation, secret references, provider config, and host-owned runtime settings. |
| server/…/environment-run-orchestrator.ts | Coordinates environment selection, acquisition, workspace realization, transport, retries, and release. |
| server/…/environment-runtime.ts | Defines provider capability snapshots, lease scope, and cleanup contracts. |
| server/…/provider-profile.ts | Defines qualified native provider identity and the closed runtime profile. |
| server/…/codex-runtime-compatibility.ts | Defines the explicit remote Codex compatibility window. |
| server/…/paperclip-runner-tool-authority.ts | Defines native tool exposure, run binding, review scope, and mutation receipts. |
| server/…/assigned-mcp-tools.ts | Defines assigned MCP catalog pinning, bounded schema delivery, and gateway reauthorization. |
| server/…/native-session-executor.ts | Coordinates native provider sessions, leases, handoff, recovery, and cleanup. |
| server/…/native-runner-checkpoint.ts | Defines encrypted checkpoint persistence, ownership fences, and recovery proof. |
| server/…/completion-contracts.ts | Defines server-owned completion objectives, criteria, policy, and provenance. |
| server/…/first-turn-queued-input.ts | Defines safe first-turn delivery for user messages that arrive during setup. |
| server/…/status-arbiter.ts | Defines evidence-based native task status and bounded continuation decisions. |
| server/…/status-decision-committer.ts | Defines durable status decisions and idempotent effect delivery. |
| server/…/native-run-finalizer.ts | Coordinates result finalization, workspace recovery, and terminal run state. |
| server/…/discovery.ts | Defines credentialed provider probing and bounded catalog discovery. |
| server/…/publication.ts | Defines risk, quarantine, active catalog state, and default access changes. |
| server/…/service.ts | Defines profile action selection, bindings, and new-tool review. |
| server/…/tool-access-policy.ts | Defines policy decisions, approvals, rate limits, and evidence. |
| server/…/tool-gateway.ts | Coordinates discovery, context checks, dispatch, headers, virtual tools, and gateway audit. |
| server/…/agent-grant.ts | Defines one-agent connection identity and grant ownership. |
| server/…/credential-access.ts | Defines actor-scoped grant selection and call-time credential resolution. |
| server/…/removal.ts | Defines credential-revoking connection teardown. |
| server/…/content-deletion.ts | Defines bounded deletion of stored tool and run content. |
| server/…/authorization-start.ts | Defines OAuth scope selection, state binding, redirect checks, and PKCE start. |
| server/…/state.ts | Defines actor-bound, single-use callback state and decline handling. |
| server/…/direct-callback.ts | Shows direct OAuth callback validation, grant persistence, and catalog completion. |
| server/…/cloud-callback.ts | Shows managed connector claims, consent subject handling, and grant persistence. |
| server/…/grant-refresh.ts | Defines per-grant refresh leases, scope provenance, and reconnect states. |
| server/…/oauth.ts | Defines public MCP OAuth resources, grants, tokens, device flow, and revocation checks. |
| server/…/tool-content-guards.ts | Defines redaction, prompt-injection checks, and protected request identity. |