Agent instructions and revisions
Agent instructions are the durable guidance that shapes an agent's work across tasks. Paperclip stores a managed instruction bundle or reads an external bundle, gives each run a private working copy, and protects shared updates with authorization and revision checks. This page complements Agent work management, Issue execution and collaboration, Execution environments and workspaces, Agent adapter integrations, Native runner execution, Runner evaluation and conformance, Case handoffs and continuity, and Reusable workflows.
Instruction bundles
Bundle model
An instruction bundle is the set of files that defines an agent's standing guidance. One relative entry file is the main file that the agent reads first, while other files can support that guidance. The bundle is separate from a task prompt, a skill, or repository instructions.
Paperclip reports the bundle as a file list with content type, size, hash when available, entry-file status, and edit status. This gives the agent UI and runners one view of the guidance without requiring them to know how it is stored.
References: server/…/agent-instructions.ts• L32-72 server/…/agent-instructions.ts• L367-397
Managed and external storage
Managed storage lets Paperclip own the bundle and keep it with the agent. External storage points to an absolute directory that the operator owns. Managed bundles support Paperclip's safe write-back and run save flow; external bundles are readable but do not support revision write-back until an administrator moves them to managed storage.
The default entry file is AGENTS.md, but an agent can use another relative entry file. Paths stay inside the selected root, use regular files and directories, and do not follow symbolic links. Instruction content must be valid UTF-8 and no larger than 1 MiB. These rules keep an instruction read or write tied to the configured bundle rather than to an unexpected path.
References: server/…/agent-instructions.ts• L136-155 server/…/agent-instructions.ts• L245-295 server/…/agent-instruction-files.ts• L9-55 server/…/agent-instruction-files.ts• L57-97
Bundle configuration
The Agent detail page exposes the bundle mode, root path, entry file, file tree, and file content for local adapters. It lets users view files as rendered text, raw text, or an editable document, and lets them add or remove supported bundle files. Binary files remain in the agent directory and are downloaded for viewing. The page keeps the current bundle settings and file draft separate until the user saves them.
The editor tells users that saved instructions affect the next run. An active run keeps the instructions it received at start. A change can therefore affect a later run or cause a new adapter session rather than changing work already in progress.
References: ui/…/AgentDetail.tsx• L2310-2347 ui/…/AgentDetail.tsx• L2575-2635 ui/…/AgentDetail.tsx• L2641-2663 server/…/agents.ts• L5002-5155
Authorization boundary
Server-bound instruction identity
Instruction access uses a server-bound actor. For an agent call, the server checks the company, agent, run, API key, active identity context, responsible user, and active company membership. It does not trust a tool request to name its own user, company, run, or source.
Reads use the target agent's read policy. Writes also require current edit access and may require consent for a protected instruction change. A commit applies the agent interaction policy to the instruction content, including agent mentions, before it changes shared guidance. This lets a run update only the agent and company that its current authority permits.
A trusted host path can reset instructions for a declared, bound plugin-managed agent. The reset is limited to that plugin's declared entry file and is separate from HTTP and agent-tool access.
References: server/…/agent-instruction-authorization.ts• L23-134 server/…/agent-instruction-authorization.ts• L137-195 server/…/agent-instruction-revisions.ts• L235-265
Run working copies
Private run copy
A working copy gives a provider an isolated place to read or edit managed agent guidance during its task. The instruction-edit copy stays separate from the canonical agent bundle so a run can draft a change without changing guidance used by other runs. A separate persistent agent-directory copy serves files that persist across tasks and sessions; it does not use the preserved instruction-candidate path described below. The service does not silently rebase an unresolved edit when it prepares the copy again, and it serializes save work for the same run.
The runner receives the copy and the registered entry file. The private runtime area is excluded from Git so these working files do not enter normal repository changes. The runner must read the file before editing it and must use the save receipt before claiming that its changes are persistent. A temporary instruction copy is not a second history of every run. Persistent agent-directory changes use their own sync rules and storage limits.
References: server/…/agent-instruction-working-copies.ts• L84-86 server/…/agent-instruction-working-copies.ts• L157-263 server/…/agent-instruction-files.ts• L137-163 server/…/agent-instruction-files.ts• L165-211
Collection and save flow
Instruction collection waits for independent proof that the provider and its execution environment stopped. A terminal run status alone is not enough. If proof is not available, the copy remains pending and uses a growing retry delay with a six-hour cap; a later stop receipt brings eligible work forward. The service then reads the registered entry file, compares it with the saved baseline, stores changed bytes durably, and tries to commit them through the same authorization and compare-and-swap rules as an explicit update.
The private copy is staged for local or remote execution under a run-specific runtime area. Remote collection reads only the registered entry file from the original environment. The service excludes that private area from Git before remote work starts, so the copy remains an execution aid rather than a repository change.
This sequence keeps a provider edit safe across local and remote environments:
- Prepare a run-bound copy from the current managed content.
- Let the provider read or edit only that copy.
- Confirm provider and environment stop before collecting changed bytes.
- Read only the registered entry file from the stopped copy.
- Preserve the candidate before attempting the canonical save or releasing the environment.
- Save it if the baseline and authority are still valid.
- Retry captured candidates after a restart, or keep them for review when collection, permission, or baseline checks fail.
References: server/…/agent-instruction-working-copies.ts• L37-45 server/…/agent-instruction-working-copies.ts• L265-277 server/…/agent-instruction-working-copies.ts• L281-358 server/…/agent-instruction-working-copies.ts• L383-505
Preserved candidates
A preserved candidate is a durable copy of an edit that could not safely become current content. For managed instruction bundles, the UI lists candidates and lets a user load the candidate, refresh its current base, and resolve it explicitly. A candidate is not silently rebased over newer content.
The UI treats edits for the current entry as resolvable drafts. If a candidate belongs to an older entry file, it is read-only so the user can copy useful text into the current entry without changing the wrong file. Whole-folder failures from the persistent agent-directory flow stay in run diagnostics rather than appearing as instruction candidates.
The candidate state identifies whether collection is pending, a save is pending, a conflict exists, or the copy is unavailable. Canonical instructions remain unchanged until a later explicit resolution succeeds. Captured bytes survive a restart and can be retried without reading a live provider again. The separate persistent agent-directory flow reports file-sync failures without treating them as preserved instruction candidates.
References: server/…/agents.ts• L5271-5287 ui/…/AgentDetail.tsx• L2575-2619 ui/…/AgentDetail.tsx• L2620-2635 server/…/agent-instruction-working-copies.ts• L312-358 server/…/agent-instruction-working-copies.ts• L637-655
Revisions and current content
Canonical entry
The canonical entry is the current managed instruction file for an agent. Its content hash and revision token describe the baseline that a reader saw. The current bytes live in the managed agent directory, while older revision records and save records provide history and historical identities that clients may still use. The revision service can rebuild the managed file state after a restart, so the agent directory remains the source of current content.
The current content token identifies the bytes, not a read event. When a matching save record exists, a current read reports the writer, source, run, and save time from the latest save of those exact bytes. A reader is never credited as the writer. If no save record exists, the current content has no writer metadata.
Reads and writes restore a stale durable file projection before the locked operation when shared storage has a newer generation. The restore stages files outside the agent row lock, then installs them under the lock only when the durable generation still matches. This keeps current instruction access correct while limiting lock time during a storage download.
An update must name the same entry file and the revision identity or content baseline used for that read. A restore writes selected historical content as the new current content; it does not erase the history that led to the restore. A trusted plugin reset can preserve the former configured entry before restoring the plugin's declared entry.
References: server/…/agent-instruction-revisions.ts• L162-245 server/…/agent-instruction-revisions.ts• L257-263 server/…/agent-file-durability.ts• L77-133 server/…/agent-file-durability.ts• L180-215
Revision history
History is scoped to one company, agent, and entry file. It combines older revision records with durable agent.files_updated save records, so saves made by the board, an agent, or a run appear in one newest-first timeline. Each entry can show the source, actor, responsible user, source run, byte size, and time.
History uses bounded paging with a cursor ordered by the database timestamp and record ID. A save record keeps metadata rather than a copy of its bytes. The current content can be read through a save ID only while its hash still matches the current entry; otherwise the system reports that the historical content is no longer retained. This keeps audit history useful without treating every activity record as a permanent content store.
An exact re-save of already current bytes does not create a second history event. If the runtime journal has no save record for those bytes, the service can record an internal adoption event to repair that journal while preserving the bytes' original writer and history identity.
References: server/…/agent-instruction-revisions.ts• L186-235 server/…/agent-instruction-revisions.ts• L379-445 server/…/agents.ts• L5289-5328
Compare-and-swap updates
Compare-and-swap means that a write succeeds only when its supplied base still describes the current entry. The update path accepts the complete UTF-8 content, the exact entry file, and the base revision identity. A compatible historical base can still pass when its content hash matches the current content; otherwise a stale base returns a conflict and leaves the proposed content available for explicit resolution.
Before changed content is committed, the service also checks agent interaction rules for any agent mentions in the instruction text. This keeps an instruction update subject to the same interaction boundary as other agent configuration changes.
This rule applies to direct API saves, runner tool saves, restores, and collected run edits. An exact replay of already saved content can return its durable receipt without creating a second change. The compare-and-swap rule is the main protection against lost instruction changes when a user and an agent edit the same guidance at the same time.
References: server/…/agent-instruction-revisions.ts• L264-377 server/…/agents.ts• L5190-5218 packages/…/update-agent-instructions.ts• L26-29
Native runner actions
Action surface
Native runners use four provider-neutral actions for instruction access. The action registry places them on the live agent-tool surface, and the server maps them to the canonical instruction service rather than to direct file access.
| Action | Purpose |
|---|---|
read_agent_instructions | Read the current entry or an exact historical revision. |
update_agent_instructions | Save complete content against a previously read base. |
get_agent_instruction_history | List bounded history metadata. |
restore_agent_instructions | Make historical content current against the current base. |
References: packages/…/index.ts• L7-12 packages/…/index.ts• L67-82 packages/…/read-agent-instructions.ts• L1-30 packages/…/update-agent-instructions.ts• L1-29 packages/…/get-agent-instruction-history.ts• L1-31 packages/…/restore-agent-instructions.ts• L1-29
Read and write sequence
The normal runner flow is read, retain the returned entry and revision, edit a complete copy, and submit one guarded update. A restore follows the same pattern but sends both the historical revision to use and the current revision that the runner read before restoring.
The native binding creates the actor from the already authenticated run. Tool JSON can choose a same-company target agent, but it cannot supply identity or authority. A successful write returns a receipt that the working-copy service can use to align the run's baseline.
This diagram shows how a runner edit moves from a private run copy to canonical agent guidance.
sequenceDiagram
participant R as Native runner
participant A as Run-bound authority
participant S as Instruction service
participant C as Canonical managed entry
R->>A: read_agent_instructions
A->>S: authorize current run and target
S->>C: read current content and baseline
C-->>R: content, entryFile, revision identity
R->>A: update or restore with base revision
A->>S: authorize, interaction check, and compare current base
alt base still current
S->>C: materialize new canonical content
C-->>R: commit receipt
else base changed or interaction denied
S-->>R: conflict or denial; preserve candidate
end
References: server/…/agent-instruction-tools.ts• L24-47 server/…/agent-instruction-tools.ts• L49-74 server/…/agent-instruction-revisions.ts• L264-377
Tool input contract
The read action can use the calling agent or a same-company target. A historical read must include both entryFile and revisionId. Updates require complete content and baseRevisionId; a null base is only for an entry with no canonical revision. History requires the entry file and supports bounded paging. Restore requires the historical revision and the current base revision.
Instruction content is valid UTF-8 and is limited to 1 MiB. Entry paths are relative, contain no traversal segments, and cannot pass through symbolic links. These limits apply before the request reaches storage.
References: server/…/agent-instruction-tools.ts• L11-20 server/…/agent-instruction-files.ts• L9-97 packages/…/read-agent-instructions.ts• L44-87
Change checklist
When these files or sections are changed, remember to consider these:
- Change bundle mode or entry-file rules together with UI configuration, server path checks, managed-storage setup, and external-bundle write restrictions.
- Change authorization inputs together with run identity binding, responsible-user checks, target-agent containment, and protected-change consent.
- Change instruction commit rules together with agent interaction checks for mentioned agents and plugin reset boundaries.
- Change working-copy preparation together with local and remote runtime staging, Git exclusion, regular-file checks, and the rule that the registered entry is the only collected file.
- Change working-copy collection together with stop proof, local and remote retrieval, durable candidate storage, retry backoff, stop-proof notifications, environment release, and candidate resolution.
- Change working-copy lifecycle guards together with the rule that unresolved candidates block a new edit and that saves for one run are serialized.
- Change revision or hash fields together with read responses, update and restore compare-and-swap checks, current-file materialization, durable projection restoration, and stale-candidate handling.
- Change history sourcing or save metadata together with activity-log filtering, writer attribution, current-content retention, cursor ordering, and compatibility with legacy revision IDs.
- Change a native instruction action together with its schema, task-mode exposure, semantic catalog, server binding, receipt acknowledgement, and runner contract evidence.
- Change the entry content limit or path rules together with managed files, remote collection, API validation, and provider-facing tool schemas.
- Change candidate display or entry-file selection together with the UI's current-entry and read-only review rules so preserved edits cannot be applied to the wrong file.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A writer sends an old base revision | The update is rejected and newer canonical content is not overwritten. | Read first, send the exact entryFile and baseRevisionId, then resolve the preserved candidate explicitly. |
| A writer uses a legacy revision whose bytes do not match current content | The compatibility check rejects the write. | Read the current entry and use its current revision or content baseline. |
| A history save ID refers to bytes that are no longer current | The history entry remains visible, but its content read or restore is rejected as not retained. | Use a current revision for a new edit, or review the saved metadata and resolve against the current base. |
| The configured entry file changes during a write | The write is rejected because it no longer targets the current entry. | Lock the agent and compare the configured entry before materialization. |
| Instruction content mentions an agent outside the allowed interaction scope | The commit is denied before shared content changes. | Apply the agent interaction policy to changed instruction content. |
| The responsible user, API key, run, or membership is revoked | The instruction read or write is denied. | Rebind identity on every call and check current server state. |
| An external bundle is used for revision write-back | The update cannot become canonical through the revision service. | Migrate the bundle to managed storage or keep the external files operator-managed. |
| A run becomes terminal before provider or environment stop is proven | Collection remains pending and no save is claimed. | Require independent process-stop or remote-termination proof before reading the copy. |
| A stopped local or remote copy cannot be read safely | Canonical instructions stay unchanged and the run reports a retryable collection failure or unavailable copy. | Use the registered entry, safe path checks, bounded reads, and the original execution environment. |
| Private runtime staging or Git exclusion fails | The run cannot safely prepare or collect its private instruction copy. | Use a run-specific runtime area, reject unsafe files, and complete remote exclusion before execution. |
| A captured candidate cannot pass authorization or compare-and-swap | The candidate stays durable for retry or explicit resolution instead of overwriting current content. | Preserve bytes before save or release, then retry or resolve against the current base. |
| A run tries to prepare an instruction copy while its prior candidate is unresolved | The new edit is blocked so it cannot silently replace the pending candidate or its compare-and-swap base. | Resolve the candidate first, or wait for its pending collection or commit work to finish. |
| Instruction content is invalid UTF-8 or larger than 1 MiB | The read or write fails before storage. | Validate bytes at every service boundary. |
| A preserved candidate belongs to a changed entry file | The UI does not apply it to the new entry automatically. | Review it as read-only and copy only the needed text into the current entry. |
| A save repeats content that is already current | The system avoids creating a misleading second change. | Treat the content match as a safe replay and use the returned receipt. |
| Durable shared files change while a stale local projection is being restored | The first staged download is discarded and the read or write retries against the newer generation. | Install staged files only when their generation matches the locked durable head; use the locked restore fallback after repeated changes. |
Key files
| File | Why to read it |
|---|---|
| server/…/agent-instructions.ts | Defines the bundle model, managed and external storage, entry-file selection, and file projection. |
| server/…/agent-instruction-authorization.ts | Defines server-bound identity, read access, edit access, and protected-change consent. |
| server/…/agent-instruction-working-copies.ts | Coordinates run copies, local and remote staging, Git exclusion, stop-aware collection, retry backoff, serialized saves, durable candidates, retries, environment recovery, and save receipts. |
| server/…/agent-instruction-revisions.ts | Defines canonical reads, save-backed history, writer attribution, compare-and-swap writes, history, diffs, restore, current-file materialization, and safe replay receipts. |
| server/…/agent-file-durability.ts | Defines durable shared-file restore, generation checks, and staging before locked instruction access. |
| server/…/agent-instruction-files.ts | Defines the shared path, byte, UTF-8, regular-file, atomic-write, and runtime Git-exclusion safety rules. |
| server/…/agent-instruction-tools.ts | Binds authenticated native-runner calls to the instruction service and working-copy receipts. |
| server/…/agents.ts | Exposes bundle, file, candidate, history, diff, and restore behavior to clients. |
| ui/…/AgentDetail.tsx | Shows how the agent UI presents local-adapter bundle settings, file editing, active-run behavior, and preserved candidates. |
| packages/…/index.ts | Registers the instruction actions on the native runner protocol surface. |
| packages/…/read-agent-instructions.ts | Defines the live read action and its historical-read contract. |
| packages/…/update-agent-instructions.ts | Defines the guarded canonical update action. |
| packages/…/get-agent-instruction-history.ts | Defines bounded history access for native runners. |
| packages/…/restore-agent-instructions.ts | Defines guarded restoration of historical content. |
| packages/…/agent_instruction_revisions.ts | Shows the durable shapes for historical revisions, heads, and run working-copy records. |