Every agent write that goes through files:propose lands as a pending review — not as a direct change. This guide covers how proposals work and how to review them effectively.
What a proposal is
When an agent creates a proposal, it stages a change to a file: what it wants to add, what it wants to remove. The file is not updated until you accept the proposal.
Proposals are created with:
POST /agent-api/v1/workspaces/:workspaceId/files/:fileNodeId/proposals
You review them in Filepad in the Reviews panel. The status bar shows pending proposal counts.
Reading the diff
The diff view is line-by-line:
- Lines starting with
+are additions (shown in accent color) - Lines starting with
−are removals (shown in error color) - Context lines show unchanged surrounding content
Each proposal is attributed to the agent key that created it and timestamped.
Accepting a proposal
Click Accept. The change is applied to the file and logged in the audit trail. The proposal is closed.
If the change is almost right but not quite, accept it and edit the file directly, or reject it and update the agent's instructions before re-running.
Rejecting a proposal
Click Reject. The file is unchanged. The rejection is logged. The agent can be re-run with better instructions.
Do not reject silently. If a proposal is wrong, it usually means the agent's instructions, skills, or memory are off. Use FilepadAI to diagnose.
Using FilepadAI to understand a proposal
Before accepting or rejecting, you can ask FilepadAI why the agent proposed what it did:
"Why did external-agent propose changing
primary_languagefrom Python to TypeScript?"
FilepadAI can use workspace context and activity history to explain the proposal.
Per-folder approval configuration
Not every folder needs a review step. Agents that write to artifacts/ directly don't create proposals — their writes land immediately. Proposals only occur when the agent uses the files:propose scope.
A common setup:
artifacts/— direct write, no approval (low-risk outputs)memory/— propose only (high-risk, persistent context).filepad/,agents/,skills/— locked (no agent writes at all)
Configure this in the Agent Access key scopes and document it in an operating note under agents/.
Team access and roles
On the Team plan, workspace members with Editor or Admin roles can review and approve proposals. Viewer roles can see proposals but cannot approve or reject.
Assign reviewers intentionally. The person who reviews memory/ proposals should understand what the agent is supposed to know.
What the audit log records
Every proposal action is logged:
- Proposal created (agent key id, file, timestamp)
- Proposal accepted or rejected (user id, timestamp)
- Direct artifact writes (agent key id, artifact id, timestamp)
- Key creation, rotation, and revocation
The audit log is available to workspace admins and can be exported on the Team plan.