Skip to main content
Version: 2026.3

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:

LaneProposes
data-object-updateField changes on existing data objects
data-object-createNew data objects, up to 20 in one change set
asset-metadata-updateCustom metadata on assets
tag-assignmentTag assignments on elements
tag-creationA new tag and the elements it is assigned to, created on approve
document-updateEditable and settings changes on documents (page / snippet / email content)
document-createNew documents, up to 20 in one change set, created parent first on approve
class-definition-updateA class definition with the bricks, collections, stores and option lists it needs
subject-updateAny other subject with nothing of its own around the merge: saved searches, classification stores, select options
agent-templateAgent-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.

GroupWrite toolsMode
pimcore-data-objects-writepropose_data_object_creation, propose_data_object_updateHITL (propose + approve)
pimcore-data-objects-direct-writecreate_data_object, update_data_objectDirect (no approval)
pimcore-assets-writepropose_asset_metadata_updateHITL
pimcore-assets-direct-writeupdate_asset, upload_assetDirect
pimcore-tags-writepropose_tag_assignment, propose_tag_creationHITL
pimcore-tags-direct-writeassign_tag, unassign_tag, create_tagDirect
pimcore-documents-writepropose_document_creation, propose_document_updateHITL - new documents and their content are proposed
pimcore-documents-direct-writecreate_document, update_documentDirect (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 modificationDate against 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:

  1. Type a refinement message in the proposal widget or diff modal.
  2. The proposal status changes to refined.
  3. A system message is appended with structured context identifying which elements to re-propose.
  4. The user's refinement text is sent as a visible user message.
  5. 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.

  1. 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.
  2. 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.
  3. 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.
  4. 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/preUpdate listener 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:

EndpointDoes
GET /proposals/change-sets/{id}The proposal a change request's change set holds now: sessionId, proposalId, proposalType
POST /proposals/change-sets/{id}/applyApplies 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}/continueStarts 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}/rejectRejects 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:

ColumnTypeDescription
session_idvarchar(36)FK to session
proposal_idvarchar(36)32-char hex
statusvarchar(20)pending / applied / rejected / refined / error
timestampbigintLast status change (ms)
datajsonFull 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 modificationDate comparison 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​