HITL Proposals
Writes the agent wants to make to Pimcore data can go through a proposal: the agent proposes, the user reviews, the user approves or rejects. Nothing is written without a click. This is the central safety mechanism - HITL, "Human-in-the-Loop" - that makes it safe to let an LLM touch production data.
These proposal types (lanes) ship today:
| Lane | Proposes |
|---|---|
data-object-update | Field changes on existing data objects |
data-object-create | New data objects, up to 20 in one change set |
asset-metadata-update | Custom metadata on assets |
tag-assignment | Tag assignments on elements |
tag-creation | A new tag and the elements it is assigned to, created on approve |
document-update | Editable and settings changes on documents (page / snippet / email content) |
document-create | New documents, up to 20 in one change set, created parent first on approve |
class-definition-update | A class definition with the bricks, collections, stores and option lists it needs |
subject-update | Any other subject with nothing of its own around the merge: saved searches, classification stores, select options |
agent-template | Agent-generated Twig templates: create, update, delete |
All follow the same propose → review → resolve flow described below, and each proposal is a change request in Change Control (below). For the template-specific flow see Agent Templates.
Two write modes, chosen by MCP group
An agent's write authority is set by which MCP groups it has access to. Every write operation has either a proposal tool or a direct-write tool - and the tools are in different groups, so agent config alone decides which an agent can call.
| Group | Write tools | Mode |
|---|---|---|
pimcore-data-objects-write | propose_data_object_creation, propose_data_object_update | HITL (propose + approve) |
pimcore-data-objects-direct-write | create_data_object, update_data_object | Direct (no approval) |
pimcore-assets-write | propose_asset_metadata_update | HITL |
pimcore-assets-direct-write | update_asset, upload_asset | Direct |
pimcore-tags-write | propose_tag_assignment, propose_tag_creation | HITL |
pimcore-tags-direct-write | assign_tag, unassign_tag, create_tag | Direct |
pimcore-documents-write | propose_document_creation, propose_document_update | HITL - new documents and their content are proposed |
pimcore-documents-direct-write | create_document, update_document | Direct (no approval). For discovery and target-group rules see Architecture → Document Schema. |
An agent with pimcore-data-objects-write but not …-direct-write can only propose - there is no way for it to
bypass the gate. The recommended default is HITL for anything user-facing; direct writes are appropriate
only for tightly scoped, automation-style agents.
create_data_object used to sit in pimcore-data-objects-write. A custom agent that relied on it there
loses it; grant pimcore-data-objects-direct-write if it really must create without approval, or let it
propose new data objects with propose_data_object_creation.
create_document and list_document_types used to sit in pimcore-documents-write. A custom agent that relied on
create_document there loses it: drop a "create the page first" step from its system message (new documents are
proposed with propose_document_creation), or grant pimcore-documents-direct-write if it really must create without
approval. list_document_types is now in pimcore-documents-read; a custom agent with pimcore-documents-write but
not pimcore-documents-read needs pimcore-documents-read to keep it.
The flow
1. Propose
The agent calls a propose tool (e.g. propose_data_object_update). The PHP tool validates the payload
(a dry-run - no writes), stores the validated result server-side in bundle_agent_proposal_statuses keyed by a
generated proposalId, and returns only {proposalId} to the LLM. No element paths, IDs, or field values
flow back through the LLM. Keeping the LLM out of the transcription loop is deliberate: it prevents the model
from silently dropping fields on long batches.
The review widget then appears on its own - there is no show_*_proposal tool. When the propose tool
succeeds the agent-server emits the matching proposal widget automatically (on tool.execution_complete),
so the model just proposes and stops its turn. The propose call takes an optional summary parameter for the
widget caption; if omitted, the server generates a neutral one.
All propose tools support batching - one call can create multiple proposals, each with its own proposalId.
2. Review
What the user sees depends on how many proposals are in the batch:
- Single proposal - a compact card with View changes, Approve, Reject buttons. View changes opens a diff modal: current value on the left, proposed value on the right.
- Multiple proposals - a table with one row per element, showing path, status, and a per-row View changes. Batch actions (Approve selected, Reject selected) operate on the checked rows.
When the widget mounts, the router does one bulk fetch for every proposal payload in the batch:
GET /pimcore-studio/api/bundle/agent/proposals/{sessionId}/data?ids=a,b,c
The response is keyed by proposalId and contains elementPath, elementId, and the full diff payload. This is
the single source of truth for everything the widget renders - so anything the LLM might have forgotten or
misremembered is irrelevant. The diff modal calls the same RTK Query hook on open; its fetch is a deduped cache hit.
3. Resolve
Each proposal has four possible outcomes:
- Approve - the agent-server forwards the request to a PHP resolver, which fetches the stored payload and applies it.
The resolver re-checks permissions and compares
modificationDateagainst the stored snapshot to detect stale data before writing. After a successful resolve, the proposal widget tells Studio to reload the matching editor - but only when the element's editor tab is currently open AND has no unsaved local changes (useEditorRefresh.refreshIfOpenAndClean). An editor with pending edits is left alone so the user does not lose work. - Reject - status is recorded; nothing is modified.
- Refine - status becomes
refined; a system message with the previous change context is appended to the conversation. The user's refinement text goes in as a user message, and the agent produces a new proposal incorporating the feedback. - Error - the resolver hit a validation or permission failure. The proposal card turns red; the user sees the error message. When the failure happens while a diff / detail modal is open (data-object, document, tag, asset-metadata, or agent-template), the message is also rendered inside the modal footer next to the action buttons - otherwise the user would be stuck behind the modal with no visible feedback.
The sequence:
LLM Agent Server PHP Backend Studio Frontend
| | | |
|-- propose tool call --->|--- MCP HTTP -----> | |
| | validate + store |
|<-- {proposalId} --------|<-- scalar result--| |
| |--- widget event --> browser (auto-emitted on |
| (model stops turn) | | tool.execution_complete)
| | |<-- GET /proposals/ |
| | | {sid}/data?ids=.. |
| | |--- {data: stored} ----->|
| | [User: Approve] |
| |<-- POST /proposal-resolve ------------------------|
| |--- POST /resolve ------>| |
| | fetch stored, check perms, |
| | apply + save |
| |<-- {success} -----------| |
Refinement
Users can ask for changes without starting the proposal over:
- Type a refinement message in the proposal widget or diff modal.
- The proposal status changes to
refined. - A system message is appended with structured context identifying which elements to re-propose.
- The user's refinement text is sent as a visible user message.
- The agent produces new proposals incorporating the feedback.
For multi-proposal overviews, refinement can target individual elements or a selected subset. A batch-refine
action sets all selected proposals to refined and appends one combined system message listing which elements
to re-propose.
One proposal over several calls: branch
propose_data_object_update and the data-model tools (propose_class_definition_update,
propose_classification_store, propose_select_options) take an optional branch, a name. Every
call in the chat that names the same open branch adds to one proposal (one Change Control branch):
the user reviews it once and approves or rejects it whole. A definition or object named again
replaces what it proposed before; everything else on the branch stays. Without branch, each call
is a proposal of its own, as before.
A branch holds one kind of change. A data-model branch takes class definitions with their bricks and collections, classification stores and select options lists, all landing Publish only, in dependency order. Data objects, assets, documents, tags, saved searches and templates never join it: objects cannot use a definition before it lands. The store refuses such a call, writing nothing, and the resolve refuses a decision through another lane than the branch's own. The card and the change request tab list every definition the branch spans in the subject rail.
One named branch over several calls
propose_data_object_update, propose_asset_metadata_update and propose_document_update take an
optional branch, a name. Every call in the chat naming it adds to one change set: data objects, assets
and documents together, reviewed subject by subject in one card and in the change request's tab, and
applied or rejected once. A later call naming an element again replaces only the values it names; an entry
{"id": <id>, "takeOff": true} takes that element off the branch. Definitions never join such a branch:
the store refuses them on it, and the apply refuses a change set that holds anything but data objects,
assets and documents. propose_tag_assignment takes a branch of its own, for tags only.
Each element is checked as its own lane checks it before the one merge (a document's target group,
validation and render probe), and a document's editables orphaned by a changed brick are purged after it.
The approver picks one mode, and each element lands in the nearest it has: Save as draft keeps data
objects and documents as drafts and saves assets, which have no draft; Save and Save & publish
land all alike. Change Control's SDK names each subject's mode (MergeInterface::landsAs()).
propose_data_object_creation, propose_document_creation and propose_tag_creation take the same
branch. On a branch a call adds new elements instead of restating the proposal, and a ref (new:…
for objects and documents, a tag by its name and parent) names one new element across calls: a later
call refines it, places a new element under it (parentRef), relates to it, or assigns a new tag to it.
An entry {"ref": "<ref>", "takeOff": true} (takeOff: true for a tag) takes a new element off,
refused while another element of the branch still depends on it. One merge creates and changes
everything in dependency order: a new tag before the elements it is assigned to, a new parent before its
children, a new object before the elements that relate to it. A new object or document has no
draft: Save as draft creates it unpublished, as Save does; Save & publish refuses, before
writing anything, a new object that lacks a mandatory value. Rejecting the branch creates nothing.
Continuing a proposal in a new chat
A proposal can also be changed from its change request, also once its chat is deleted: Continue in chat in the change request's review starts a new, normal chat of the user who acts. It is offered to whom Change Control lets decide the change request (its owner, or for a service user's proposal its assignees and managers); a read-only review does not show it.
- The new chat starts from what the change set proposes: a first message lists its subjects and the values it changes, and the agent reads it as the chat's history. A value too long for it is named, not shown, so the agent asks for it instead of proposing a cut one. A large change set is listed in part (the first 60 lines), and a new proposal replaces it only when it makes the changes left out again. The chat runs the agent the proposal came from where the user may chat with it (with its chat deleted, the one its change set recorded), else the bundle's agent that proposes its type, else the default agent.
- The user says what to change, and the agent proposes the whole change again in the new chat. That proposal is a new one, with its own change request under the same rules as any proposal of this chat.
- Once the new chat stores its first proposal for one of the old proposal's subjects, the old one is discarded as the chat's reject discards it, in the same transaction, and its change request closes; its review then reads "Replaced by a continued chat", not as rejected by the user. If that discard fails, the new proposal is not stored either. A new element is named per chat, so for one the old proposal creates, a new object of the same class (or a new document of the same type) under the same parent counts as the same subject. Until then the old proposal, its chat and its change request stay as they are and can still be decided; a new chat that proposes nothing replaces nothing.
- The old proposal is left open, and the new chat no longer continues it, when it was refined after the new chat started from it (in its own chat, or by its task run again), since the new chat never showed that version, or when the user may no longer decide its change request.
Partial applies
A change set that spans several definitions (a class with its bricks, collections, stores and option lists) is applied in dependency order, and a definition write is PHP files plus DDL that does not undo. If a later step fails after an earlier one landed, the change set closes as partially applied: the card names what is on Main and what is not, and its Propose the rest button asks the agent for a new proposal of the missing definitions only.
New data objects
propose_data_object_creation proposes up to 20 new objects as one change set: they are reviewed
object by object and approved together, as Save unpublished or Save & publish. The objects are
saved one after another, so before anything is written, a publish of several objects checks each of them
the way Pimcore validates it on save (mandatory values in every container, relation targets, field
limits). If any would be refused, nothing is created, the card says which object and field, and the change
set stays open to fix it in the review or approve with Save unpublished.
That check runs Pimcore's field validation, not the whole save. It does not see:
- values a
preAdd/preUpdatelistener fills on save — a project that fills a mandatory value that way has such publishes refused, while Save unpublished works; - unique-field clashes, and listeners that throw on save — these still fail during the write, and the card reports the change set as partially applied, naming what was created;
- a change on Main made between the check and the writes (another request taking a key, say), which is reported the same way.
A child of an inheriting class under a parent the same change set creates is not checked for mandatory values: the parent may supply them, and only the save can tell.
New documents
propose_document_creation proposes up to 20 new documents (page, snippet, email, link, hardlink,
folder) as one change set, each with its content: a page, snippet or email carries its preset
(docTypeId), settings, editables and properties, a link its target, a hardlink its source. Nothing
exists before the approve; the approver chooses Save unpublished or Save & publish, and a
rejected proposal leaves no document, draft or version behind. A document whose parent is created by the
same proposal lands after it. The card previews a new page, snippet or email before it exists: an
existing page above it is loaded and the new document renders in its place through its own document
controller and template. The tool refuses, before anything is stored, a taken path, a parent the user
may not create under, a preset of another type, a link without a target and editables that fail
validation; the approve refuses an approver without the create right on the parent, a path taken since,
and a draft-only save, and the proposal stays open with the reason.
Proposals as change requests
Every proposal stored from 2026.4 on is also a change request in Change Control, of the type Agent
proposal (source key agent), with its lane as the column Proposal type. A refinement onto the same
change set updates that change request instead of adding one.
- Private. Only the user whose chat proposed it sees it: in the Reviews list, in its counts and on every endpoint. Another user sees none of it, an admin included, and its endpoints answer them as for a change request that does not exist.
- Never assigned. It is decided by its user alone: an assignment is refused, and the permission to manage change requests does not let anyone else decide it.
- A service user's proposal (an unattended task running as a service user) is not private: Change Control assigns it to the service user's responsible users and roles, and those who may decide it there (its assignees, and whoever may manage change requests) read, apply and reject it with the endpoints below. Another user still finds none of it, and the service user never applies its own.
- Reviewed in its change request tab with the lane's own card and review, as in the chat, and decided there with the card's own actions. Refine in the chat opens the chat the proposal came from; Continue in chat continues it in a new chat (see Continuing a proposal in a new chat). The chat's cards link to the change request (Open as change request).
- Closed only by the lane's own apply and reject. Apply goes through the lane's resolver, with the same permission and staleness checks as in the chat; reject records the rejection as the chat does. Both give the same result as in the chat. Change Control's own merge and discard never close a proposal's change request while its chat exists.
- Discarded once the chat is deleted. Deleting a chat (by its user, in bulk or by the retention pass) closes nothing; its open proposals' change requests offer Discard to whom Change Control lets decide them: their user alone, or for a service user's proposal its assignees and managers. Discard closes them as discarded through Change Control's discard. Applying them is no longer possible.
- No backfill. A proposal stored before the upgrade has no change request: it is not listed, and its user decides it in the chat as before.
The change request tab uses these endpoints, under /pimcore-studio/api/bundle/agent and the permission
pimcore_agent_use:
| Endpoint | Does |
|---|---|
GET /proposals/change-sets/{id} | The proposal a change request's change set holds now: sessionId, proposalId, proposalType |
POST /proposals/change-sets/{id}/apply | Applies it with the review's choices (review: what the chat's resolve payload carries); with expectedProposalId, refused with 409 when the change set holds a newer proposal. A refinement that lands while the apply runs refuses it too, with success: false and the chat's "newer proposal" error |
POST /proposals/change-sets/{id}/continue | Starts a new chat of the acting user that continues the proposal and answers with its sessionId (201). Moves nothing: the proposal stays open until that chat stores a proposal for one of its subjects. Works with the proposal's chat deleted |
POST /proposals/change-sets/{id}/reject | Rejects it; the body is optional: with expectedProposalId (the proposal the review shows), refused with 409 when the change set holds another proposal. Without it, the proposal the change set holds now is rejected. Refused with 409 when a refinement replaces it while the reject runs, or when it was applied already; with 503 (retryable, still open) while another writer holds its subject |
For a type of your own see Custom Proposal Types.
Storage
Proposal payloads live in bundle_agent_proposal_statuses:
| Column | Type | Description |
|---|---|---|
session_id | varchar(36) | FK to session |
proposal_id | varchar(36) | 32-char hex |
status | varchar(20) | pending / applied / rejected / refined / error |
timestamp | bigint | Last status change (ms) |
data | json | Full payload |
Why server-side? LLMs can lose JSON escaping, fabricate fields, or drop data when re-serialising complex structures. Storing the validated data at proposal time guarantees exactly that payload reaches the resolver, and saves context-window tokens on the way back through the LLM.
Security
- Proposal data is validated at creation time (dry-run via field adapters).
- Permissions are re-checked at resolution time - a user may lose access between propose and approve.
- Stale-data detection via
modificationDatecomparison prevents silent overwrites. - Session ownership is enforced on every proposal endpoint; the change request endpoints also admit those who decide a service user's proposal.
- The resolver reads from the database, not from the request body - no LLM-controlled writes.
Further reading
- Extending → Custom Proposal Types - add your own propose tool + resolver + widget for a domain-specific write flow.
- Rich Chat Widgets - the catalog of proposal-related widgets.
- Architecture → Authentication - how permissions are re-checked.