registry

How it works

Read this first: four facts that decide what a registry write does.

1. HKCU is the agent’s own hive, not the logged-on user’s. The agent runs as LocalSystem, so hive=HKCU reaches HKU\.DEFAULT, LocalSystem’s own profile hive. To read or change a person’s settings use get_user_value, set_user_value or delete_user_value with their sid or username (list_profiles lists them), or hive=HKU with their SID as the first key component while their hive is loaded.
2. Only apply previews by default. apply is a dry run unless you send dry_run=false. delete_key deletes unless you send dry_run=true. set_value, delete_value, set_user_value and delete_user_value have no preview at all: they act at once.
3. The undo manifest exists only in the reply. Nothing is kept on the endpoint. Save the reply of every write to the change record when it arrives; the stored response is deleted after 90 days by default.
4. Destructive actions need explicit targets. delete_value, delete_key, delete_user_value and apply take explicit agent_ids on POST /api/command, MCP execute_instruction, the REST instruction routes and the dashboard console; a scope or a broadcast is refused there, for a dry run too. A schedule can still fan an approved Destructive write out by scope. Every write, and get_user_value, also needs an administrator or an approval.

The plugin reads and changes the Windows registry on demand, in-process, with no scheduled collection. Six actions only read: get_value, key_exists, enumerate_keys and enumerate_values open one key of HKLM, HKCU, HKCR or HKU; list_profiles lists the machine’s user profiles; get_user_value reads one value from a user’s hive. Six actions change it: set_value and delete_value write or delete one value, delete_key deletes one key (with recursive=true, a whole tree), set_user_value and delete_user_value change one value in a user’s hive, and apply runs a plan of up to 256 HKLM items with an undo manifest. Every change runs on a checked handle (the key is proven to be the one you named, never one reached through a registry link), is read back before it reports success (an apply create_key item is the exception: the checked handle is its evidence and verify is -), and writes one audit| line that the server turns into a registry.write audit row. A user’s hive is the live HKEY_USERS\<SID> hive when it is loaded, otherwise the profile’s NTUSER.DAT, mounted for the one call behind the hive-file guard and flushed before it is unloaded. The plugin keeps nothing on the endpoint and has no key policy of its own: the role, the approval, the per-action kill switch and the audit row are the controls. On macOS and Linux every action answers one registry|unsupported|... line.

What you can do with it

I want to …

• change a setting for one person: list_profiles, then set_user_value with the sid. hive=HKCU would change the agent’s own hive.
• change several machine settings and keep an undo: apply as a dry run, then the same plan with dry_run=false; save both replies.
• delete a whole branch: delete_key with recursive=true and dry_run=true, read the counts, then run it with dry_run=false. There is no undo.
• delete a leaf key and be able to put it back: an apply plan with one delete_key item: its undo rows hold every value of the key.
• reach a 32-bit application’s key: name WOW6432Node in the path.

What it deliberately does not do. It has no 32-bit registry view flag (the x64 agent uses the 64-bit view only, with no KEY_WOW64_* flag), no protected-key list (an owner decision), no watch or trigger, and no transactions: apply is HKLM only and not transactional, and its undo restores values, not a deleted key’s owner, permissions, class or volatility. It never follows a registry link, so a write under HKLM\SYSTEM\CurrentControlSet (itself a link) is refused: write under HKLM\SYSTEM\ControlSet001, or the numbered set Select\Current names. A creating write never creates a key directly under a hive root (root_level_create).

The words used in this document

A safe workflow

1. Target. Name the devices with explicit agent_ids, verified at registry 2.1.0 (“Before you roll out”).
2. Read first. Record the current state with get_value, get_user_value, enumerate_values or key_exists. For set_value, delete_value and the per-user writes this is the only preview.
3. Preview. Run apply as it defaults, or delete_key with dry_run=true. Every item row should say would_apply and the summary row undo_complete 1; a delete_key preview gives counted_keys, counted_values and capped.
4. Change, and save the reply. Run with dry_run=false, or run the single action. Save the reply to the change record when it arrives: it holds the only undo manifest.
5. Verify. status|ok already means the plugin read the change back on its own handle; read it again with the read actions to see what the next reader sees.
6. Undo if needed. Follow “Undoing a change” under Data contract. Worked recipes are in docs/user-manual/cookbook.md, section 1.7: preview, apply and undo a plan; change one value in a user’s hive; remove a registry branch safely.

Before you roll out

Read the two registry sections of docs/user-manual/upgrading.md first. The server does not compare a plugin version at dispatch (the definitions’ minAgentVersion is declared and exported, not enforced; #6484), so which agents receive a write is the operator’s responsibility.

• The hazard. A registry 1.x or 2.0.x agent (every agent released before 2.1.0, v0.14.1 included) reads neither dry_run nor recursive: a delete_key sent to it with dry_run=true DELETES the key when it has no subkeys. A bare status|ok (1.x) or a dry_run|0 row (2.0.x) in answer to dry_run=true means the key was deleted. The three 2.1.0 actions answer error|unknown action there.
• The order. Upgrade the server replicas, then the agents. Aim previews and writes only at devices verified at 2.1.0: mark them with a tag (ostype == "windows" AND tag:<key> == "<value>"), use that scope in schedules, workflows, policies and bundles as well as scripts, and resolve it to the explicit agent_ids a Destructive action needs on the API, MCP and dashboard routes. Until the fleet is upgraded, switch delete_key off: PUT /api/v1/plugin-config/registry/kill-switch?action=delete_key with the body {"enabled": false, "reason": "registry 1.x/2.0.x agents still in the fleet"} (enabled is required; PluginConfig:Write).
• Registry 1.x writes. A 1.x agent writes an EMPTY REG_SZ for a data_hex-only set_value, stores REG_QWORD, REG_MULTI_SZ, REG_EXPAND_SZ and REG_BINARY values as REG_SZ text, follows a write under HKLM\SYSTEM\CurrentControlSet, and answers status|ok with no audit| line. A status|ok with no audit| line before it came from a 1.x agent (a 2.x agent also answers a request refused before anything opened with a bare error| line): read the value back with get_value.
• Stored definitions. Bundled definitions are inserted only when absent, so an existing server keeps its stored windows.registry.* text and parameters until they are exported, deleted and re-imported (docs/user-manual/instructions.md, “Replacing a stored parameter schema”). Re-import delete_key 1.2.0 only after every targeted agent is verified at 2.1.0: the stored schema without dry_run is what keeps the instruction route from sending it.
• Audit rows and NULs. Only agents from the release that contains #6294 stamp the action the server needs to mint registry.write rows. A NUL inside a parameter sent through POST /api/command cuts the value at the NUL on every agent version; the instruction and MCP routes refuse control bytes.

Diagrams

End-to-end request path

flowchart LR
  OP["Operator, API, MCP, workflow or schedule"] --> SV["Server: RBAC on Infrastructure Read, Write or Delete, the kill switch, admin or approval for 7 of 12 actions"]
  SV --> DG{"Destructive action?"}
  DG -->|"yes: delete_value, delete_key, delete_user_value, apply"| TG["API, MCP and dashboard: explicit agent_ids only, scope and broadcast refused. A schedule may fan out by scope"]
  DG -->|"no"| AG
  TG --> AG["Agent runs the plugin and stamps the action on its output frames"]
  AG --> WIN["Windows: one try and catch at the plugin boundary"]
  AG --> UNS["macOS and Linux: one registry unsupported line"]
  WIN --> RD["6 reads: display text, no audit line"]
  WIN --> WR["6 writes: checked handle, capture, change, read back, audit line"]
  RD --> REP["Reply frames"]
  WR --> REP
  UNS --> REP
  REP --> RS[("ResponseStore, 90 days: the only copy of the undo rows")]
  REP --> GATE{"Server: stamped as one of the six writes, on a command id in the shape the server mints?"}
  GATE -->|"yes"| AU[("AuditStore: one registry.write row per audit line, 365 days")]

The server decides who may run which action before anything reaches an agent, and on the API, MCP and dashboard routes a Destructive action also needs explicit device ids (a schedule can still fan an approved one out by scope). The agent stamps each reply frame with the action it ran; the server, not the plugin, mints a registry.write row, and only for the six writes on a command id in the shape the server mints for a registry command (registry- plus 16 or 32 hex digits). It checks that shape and the stamped action, not a dispatch record, so a read action’s output never mints a row; the rows are asserted by the agent. The reply goes to the ResponseStore, the one place an apply undo manifest is kept.

Opening a key: the checked handle

flowchart TD
  S["A write needs its key"] --> FE{"Hive is HKLM or HKU?"}
  FE -->|"yes"| F1["Fast open: one open of the whole path. A link before the leaf would be followed; a link at the leaf is opened as itself"]
  F1 --> F2{"Kernel name of the opened key equals the requested path, and the leaf is not a link?"}
  F2 -->|"yes"| OK["Hand over the handle: capture, write, read back"]
  F2 -->|"no, or any doubt"| W
  FE -->|"no: HKCU, HKCR or a user hive"| W["Walk: open the next part from the previous handle"]
  W --> M{"Does the part exist?"}
  M -->|"yes"| L{"Is it a link?"}
  L -->|"yes"| KL["Refuse key_is_link"]
  L -->|"no, more parts"| W
  L -->|"no, last part"| N
  M -->|"no, and the action does not create"| KNF["Refuse key_not_found"]
  M -->|"no, first part, creating"| RLC["Refuse root_level_create"]
  M -->|"no, later part, creating"| CR["Create the remaining parts. A part that appears meanwhile: concurrent_change"]
  CR --> N{"Leaf kernel name equals the first part's name plus the rest?"}
  N -->|"yes"| OK
  N -->|"no"| RB["Delete the keys this call made, leaf first, then refuse key_is_link"]

The fast open only ever accepts: a link anywhere before the leaf makes the kernel open the link’s target, whose name cannot match, so any doubt falls back to the walk. The walk reads the kernel name of the first part as soon as it opens it and compares the leaf’s name with it at the end, so a link finished after its check, or a part renamed mid-walk, is refused rather than followed. A delete_key leaf is opened as a possible link and deleted as the link object, never its target.

Recursive delete_key

flowchart TD
  A["delete_key with recursive=true"] --> B["Open the named key. A link there is deleted as the link, never its target"]
  B --> C["Vet: open every child from its parent with DELETE access, probe it for a link, count keys and values"]
  C --> D{"Vet result"}
  D -->|"a link, a child it cannot open, or a malformed name"| R1["Refused: key_is_link, access_denied or another token, unrepresentable_name. Nothing deleted"]
  D -->|"over 10,000 keys and values or 600 levels"| E{"dry_run?"}
  E -->|"true"| E1["ok with capped=1: the counts are a lower bound"]
  E -->|"false"| E2["Refused tree_too_large. Nothing deleted"]
  D -->|"clean"| F{"dry_run?"}
  F -->|"true"| G["ok with the vet's counts. Nothing deleted"]
  F -->|"false"| H["Delete children first: re-open and re-probe each child, NtDeleteKey on its own handle"]
  H -->|"a link appears, or the tree outgrows the bound"| I["Stops: key_is_link or concurrent_change. Keys already removed stay removed"]
  H -->|"done"| J["Read back as deleted: ok, the counts are what was removed"]

The plugin never uses RegDeleteTreeW, which follows a link met inside a tree. The vet refuses a tree it cannot delete whole before anything is removed; the real delete checks every key again as it reaches it, so a key added since the vet is deleted and counted, and a link added since stops the run (failed once anything was removed, otherwise refused). The counts of a real run are what it removed, which can exceed a dry run’s.

Per-user write

flowchart TD
  S["set_user_value or delete_user_value"] --> P{"sid or username in the ProfileList, and not a SID.bak leftover?"}
  P -->|"no, or only a SID.bak leftover"| E0["Bare error line, no audit line"]
  P -->|"yes"| V{"Key, name and data valid?"}
  V -->|"no"| R0["Audited as refused"]
  V -->|"yes"| L{"Does the live HKU hive for the SID open?"}
  L -->|"yes, normally logged on"| W1["Write on the live hive: walk, read back. No lock, no flush"]
  L -->|"no"| G["Take the offline-hive lock, enable the backup and restore privileges"]
  G --> HG{"Hive-file guard passes and the mount loads?"}
  HG -->|"no"| R1["Refused, audited: privilege_missing, hive_mount_failed or a guard token such as hive_hardlinked"]
  HG -->|"yes"| W2["Write on the mounted hive, read back, flush to the file. A failed flush is flush_failed"]
  W2 --> U["Unload. A failure is warning hive_unload_failed; the write still stands"]
  U --> PR["Probe HKU for the SID: loaded now is warning hive_loaded_after_offline_write"]
  W1 --> O["Warnings, the audit line with hive=HKU and sid, then status or error"]
  PR --> O

A write never targets a <SID>.bak leftover in the ProfileList: its folder may hold the user’s real hive and its name could shadow the live profile’s. A sid naming a leftover, or a username that only a leftover carries, is answered as a profile that is not found; a username that a live profile also carries resolves to the live profile (get_user_value and list_profiles still see the leftover). The live hive is tried first; the offline mount runs whenever it cannot be opened, normally because the user is not logged on (a profile with no path answers hive_not_found). The flush matters because unloading a hive does not itself write the file; a failed flush fails the write and removes any keys it created. The post-unload probe reports a hive that a logon loaded after the write returned.

The apply plan

flowchart TD
  P["parse_plan: JSON shape, 256 items, 64 KiB, no dependent items"] -->|"a shape, size or dependency defect"| PX["Whole plan refused: one error line, nothing opened, no audit line"]
  P -->|"valid"| I{"Next item?"}
  I -->|"none left"| SM["summary row with undo_complete; error partial_failure when any item was refused or failed"]
  I -->|"after a stop"| SK["skipped: item row only"]
  SK --> I
  I -->|"yes"| O["Open its key on a checked handle, once per distinct key. A dry run only asks whether it could create"]
  O --> F["Capture the facts: the previous value, subkeys, every value of a key to delete"]
  F --> VD{"refusal_reason: one verdict, the same in a dry run and a real run"}
  VD -->|"refuse"| RF["refused, or failed when keys it created stayed"]
  VD -->|"proceed, dry run"| WA["would_apply"]
  VD -->|"proceed, real run"| MU["Change and read back: applied or failed"]
  RF --> ROW["Write its audit line, item row and undo rows now"]
  WA --> ROW
  MU --> ROW
  ROW -->|"refused or failed stops the rest unless continue_on_error=true"| I

The parser refuses a plan whose items depend on each other, so a dry run gives the same verdicts a real run would. Each item’s rows go out as the item ends, before the next item opens anything, so a later failure cannot take them back. The plan is not transactional: items already applied stay applied when a later one stops it.

Design notes for reviewers

OS capability

Declared limits per leg (descriptor fallback text, verbatim):

• apply / macOS — planned stub: not implemented, the action answers registry|unsupported|…
• apply / Linux — planned stub: not implemented, the action answers registry|unsupported|…
• delete_key / macOS — planned stub: not implemented, the action answers registry|unsupported|…
• delete_key / Linux — planned stub: not implemented, the action answers registry|unsupported|…
• delete_user_value / macOS — planned stub: not implemented, the action answers registry|unsupported|…
• delete_user_value / Linux — planned stub: not implemented, the action answers registry|unsupported|…
• delete_value / macOS — planned stub: not implemented, the action answers registry|unsupported|…
• delete_value / Linux — planned stub: not implemented, the action answers registry|unsupported|…
• enumerate_keys / macOS — planned stub: not implemented, the action answers registry|unsupported|…
• enumerate_keys / Linux — planned stub: not implemented, the action answers registry|unsupported|…
• enumerate_values / macOS — planned stub: not implemented, the action answers registry|unsupported|…
• enumerate_values / Linux — planned stub: not implemented, the action answers registry|unsupported|…
• get_user_value / macOS — planned stub: not implemented, the action answers registry|unsupported|…
• get_user_value / Linux — planned stub: not implemented, the action answers registry|unsupported|…
• get_value / macOS — planned stub: not implemented, the action answers registry|unsupported|…
• get_value / Linux — planned stub: not implemented, the action answers registry|unsupported|…
• key_exists / macOS — planned stub: not implemented, the action answers registry|unsupported|…
• key_exists / Linux — planned stub: not implemented, the action answers registry|unsupported|…
• list_profiles / macOS — planned stub: not implemented, the action answers registry|unsupported|…
• list_profiles / Linux — planned stub: not implemented, the action answers registry|unsupported|…
• set_user_value / macOS — planned stub: not implemented, the action answers registry|unsupported|…
• set_user_value / Linux — planned stub: not implemented, the action answers registry|unsupported|…
• set_value / macOS — planned stub: not implemented, the action answers registry|unsupported|…
• set_value / Linux — planned stub: not implemented, the action answers registry|unsupported|…

Privileges and prerequisites

No external binaries, no subprocesses, no network access: every call is an in-process Win32 Reg*W/AdjustTokenPrivileges/NtDeleteKey/NtQueryKey call (registry_win.cpp, agents/shared/win_profiles.hpp, agents/shared/win_reg_handle.hpp).

Controlling the write actions. There is no built-in key policy (no protected-key denylist, by owner decision): the controls are the endpoint-admin role with approval (AdminOrApproval) on every mutating definition, the explicit-target rule for the Destructive ones, the registry.write audit row, and the per-action kill switch (PUT /api/v1/plugin-config/registry/kill-switch, add ?action=set_value for one action; PluginConfig:Write; no row means allowed). A scheduled execution can fan an approved write out to many devices.

Data contract

Inputs

Outputs

Each action has its own line shape; there is no uniform row. A line is name|value or a tagged row, split on |, and - inside an audit| line means “not applicable” (the read actions never use - as a placeholder).

A request that fails before anything is opened (a missing or unknown hive, a missing key, a profile that is not found, a plan whose shape or flags are invalid) is one bare error|... line with no audit line; a key path or value name that fails validation after the target resolved is audited as result=refused. The delete_key counts are point in time: without recursive they are what the key held (counted_keys|1), with it what the delete removed, or on a dry run what the vet counted.

How to read a result.

The field grammar of every row is in the generated table below and in the integrator references after “Undoing a change”.

windows.registry.apply — row_kind|field_1|field_2|field_3|field_4|field_5|field_6|field_7|field_8|field_9|field_10|field_11|field_12|field_13

windows.registry.delete_key — status|counted_keys|counted_values|dry_run|capped

windows.registry.delete_user_value — status

windows.registry.delete_value — status

windows.registry.enumerate_keys — subkey

windows.registry.enumerate_values — name|type

windows.registry.get_user_value — username|value|type

windows.registry.get_value — value|type

windows.registry.key_exists — exists

windows.registry.list_profiles — sid|profile_name|profile_path|hive_state

windows.registry.set_user_value — status

windows.registry.set_value — status

Result status

This plugin does not set a typed result status; the agent records UNDECLARED and every sample shows UNDECLARED / UNKNOWN /.

Where the data goes

• Instruction result. Rows/lines travel over the agent’s mTLS gRPC channel as the command response and land in the ResponseStore (90 days), queryable at /api/responses/{id}.
• Audit log. The server, not the plugin, writes the registry.write rows: it parses the audit| lines of a reply frame (server/core/src/plugin_result_audit.hpp) only when the agent stamped the frame with one of the six write actions and the frame’s command id has the shape the server mints for a registry command (registry- plus 16 or 32 hex digits), so a read action’s output, or a line that merely starts with audit|, mints nothing. The server checks that shape and the stamped action, not a dispatch record: the rows are asserted by the agent. result=ok is recorded as success, refused and failed as failure, with the whole line in the row’s detail. An agent older than the release that contains #6294 stamps no action and produces no rows (docs/user-manual/upgrading.md). Principal, retention and the join to the operator’s row: docs/user-manual/audit-log.md.
• Where each copy lives. The reply (its rows and audit lines) is in the ResponseStore for 90 days by default (--response-retention-days), and it is the only copy of an apply undo manifest (the item rows’ old values and the undo rows, up to 4,096 bytes per value); the AuditStore keeps one registry.write row per audit line for 365 days by default (--audit-retention-days), with old and new values cut to their first 256 bytes, as hex; executions.parameter_values keeps the request parameters (value, data_hex, the whole plan) and no pass prunes it; the endpoint keeps nothing.
• Agent log. The plugin’s own spdlog error lines (for example registry: <action> raised an exception) carry no command id: the plugin ABI hands a plugin no command identifier. Attribute a command through the response and audit rows above, which are joined on the command id.
• A partial or failed create. A set_value row with result=failed and created=<n> above 0, an error|exception reply, or an agent that stopped in the middle of a command can leave keys the call made (and, for a write that landed, its value). Take the hive, key and value name from the request that dispatched the command, not from the audit row: the exception row has hive=-|key=-|created=-, and the command.dispatch row carries only registry:set_value -> N agent(s). The request parameters are in executions.parameter_values of the execution that holds the row’s command_id (join on it; the command-to-execution mapping is reaped after 24 hours, so the join can come back empty, and then only the dispatching script, workflow or schedule holds the request). A call creates only the trailing components of a path that did not exist, and a pre-existing empty parent looks exactly like a created one; the rollback goes leaf first, so the keys a failed call leaves are normally the shallowest of the ones it made, but when the leaf holds a value or key another party put there, the leaf is kept and every ancestor above it survives with it. Read the candidates with key_exists, enumerate_values and enumerate_keys, and remove a key with delete_key (leaf first, one call per key) only when this call’s creation of it can be shown (for example an earlier key_exists for the path answered false) and it is empty; a key that holds a value you did not write is another party’s and stays. For an exception whose audit line could not be written, and for an agent that died mid-command (it sends output at command end or each 64 KiB), there is no registry.write row: only the command.dispatch row and the stored response show the attempt. A recursive delete_key stopped that way can leave the tree partly deleted with no row at all: run it again as a dry run to see what is left, then for real. An apply stopped that way keeps the rows the agent had already sent; an item with no row may still have run, and a deleted key’s manifest is whole only when its undo rows number its audit counted_values, so read the keys of those items back before replaying anything.
• Not consumed by daily-sync inventory, the Echo warehouse, DEX, or metrics: nothing here runs on a schedule; the plugin executes only when an operator or workflow dispatches one of its twelve definitions.
• Sensitivity. The audit rows of every mutating action (apply and the per-user writes included) and the set_value/delete_value/set_user_value/delete_user_value responses carry registry data OLD and NEW (hex of the raw bytes, 256 bytes at most per value in an audit row, for every value type) and key paths; an apply reply also carries its undo manifest, the previous value of each value item and every value of each deleted key (up to 4,096 bytes per value and 512 KiB per reply), readable by Response:Read holders for 90 days. All of these can hold secrets that live in the registry (a service account’s autologon password, a product key, an agent token). Owner risk acceptance: old and new values are recorded as raw hex and can contain secrets; the product owner accepted this risk on 2026-10-20 and masking is a planned later change, and nothing in the plugin redacts them today. A key path can name a person. get_value/enumerate_values/get_user_value can return arbitrary registry data, among it RegisteredOwner/DigitalProductId (a person’s name and a device-specific product-key hash); get_user_value’s username and list_profiles’ profile_name/profile_path (e.g. jsmith/C:\Users\jsmith) directly identify a person and their home directory. The readers are wider than the writers: AuditLog:Read and Response:Read (the Viewer, Operator, PlatformEngineer, ITServiceOwner and Administrator roles hold both; Response:Read is not floored while RBAC is off), the legacy /events stream (any authenticated non-service-scoped session) and MCP query_audit_log; the executions’ parameter_values carries the write parameters unredacted: value and data_hex of set_value and set_user_value, and the whole apply plan with every value in it. By default audit rows are retained 365 days (--audit-retention-days) and the response store 90 days (--response-retention-days); the executions table is not in the server’s retention settings and no pass prunes it, so parameter_values stays until the database is purged. Read-time redaction is not built.
• Siblings: none. Guardian’s own real-time registry-key watch (guard_type: "registry") is an unrelated detection mechanism; this plugin is on-demand only, with no watch/trigger surface.
• MCP / REST. Discover: discover_plugins (summary) -> yuzu://plugin-docs (this page as data) -> discover_instructions / get_definition("windows.registry.get_value"). Run: execute_instruction {definition_id, parameters}. Read: /api/responses/{id}; the audit rows: the audit log API filtered on registry.write.

Undoing a change

Undo needs the saved reply: the plugin keeps nothing on the endpoint, and a single action’s previous value is only in its audit line (its first 256 bytes, as hex).

Undoing a single action. set_value or set_user_value: when the audit line says old_state=present, write back type = old_type and data_hex = old. That works only when old is not cut (no ~<total> at its end), old_type is one of the six types set_value writes, and the bytes fit that type’s shape (a string type ends in its NUL, a REG_DWORD is 4 bytes, a REG_QWORD 8, a REG_MULTI_SZ ends in a double NUL); an empty old counts as an omitted data_hex, which restores only a zero-byte REG_BINARY exactly. Restore any other value with another tool (an apply refuses such a value before changing it, unsupported_old_type). old_state=absent -> delete_value (or delete_user_value); created above 0 -> remove those trailing key components with delete_key, deepest first (for a per-user write, hive=HKU key=<SID>\... while the user’s hive is loaded: no per-user action deletes a key). delete_value or delete_user_value: write back the old_type and old the same way, under the same conditions. delete_key records no values and cannot be undone from its reply.

Undoing a plan. Save the dry run’s and the real run’s replies to the change record at once: the manifest exists nowhere else (the stored response is kept 90 days by default, --response-retention-days). Undo only the items whose verdict is applied, and those failed with created above 0 or with a mutation (a failed value write may have landed; a failed delete_key with undo rows took its values); refused, would_apply and skipped rows changed nothing (a refused row’s old_hex holds no bytes, at most ~<total>, the size: nothing to replay). Replay in REVERSE item order. A row name of - is the default value: omit name in the replayed item (a plan refuses -). Per op:

What undo_complete|1 means, and what it does not. It means every previous value the plan needed was retained whole within the budget and no creating item stopped part-way leaving keys its created count cannot name. It speaks for VALUES only: a deleted key’s owner, DACL and SACL, class and volatility are not captured, so a replayed create_key recreates it with the parent’s inherited security, non-volatile and with no class (a key readable only by SYSTEM can become readable by whoever the parent grants; under a volatile parent the recreate fails). The manifest is a snapshot taken at capture: a value another writer changes or adds between the capture and the write or delete is lost, or stale, even with undo_complete|1. A reply that ended early (an exception, a dead agent, a failed output channel) has no summary| row and so no undo_complete at all.

Reference for integrators: apply rows, exact names and the undo budget

The row shapes (cells split on |):

The key and name cells of an item that proceeds are exact (representable); a refused item’s cells are the folded display form (a trailing backslash shows as _). An item refused before its previous value or its key’s contents were read (an invalid item, one whose open failed, a delete_key refused for subkeys, or one whose vet or enumeration failed) shows - in its old_* cells and, for a delete_key, in the audit line’s counted_* fields: - means “not read”, never absent. A refused real creating item removes the keys its open made before its row goes out: refused with created 0 when all were removed, failed with the number that stayed otherwise. An audit| row is the same 20-part line as for a single action, with op=apply.<op>; an item skipped after a stop has only its item| row.

The exact-name rule. Every key path and value name a manifest row carries must read back as exactly what is in the registry, so one predicate (representable) decides: row_field(name) == name — no |, no control character (TAB aside), no DEL, C1 control, U+2028 or U+2029, no invalid UTF-8, no NUL, no trailing backslash (the server’s column splitter reads \| as an escaped pipe) — and not the literal - (a row spells the default value that way). A name that fails it is refused unrepresentable_name before anything is changed, for the plan’s own names and for every value of a key an item would delete. That value name is the raw UTF-16 name the registry enumerates and must be well-formed: one holding a lone surrogate or a NUL has no exact UTF-8 spelling (a display read shows the surrogate as U+FFFD, which names a different value or none), so it is refused the same way, in the dry run and the real run alike; a value really named with U+FFFD is deleted and restored like any other. So is a value whose name this plugin could not write back with set_value (a TAB, which representable accepts, or another control byte): on a delete_key item the token means “the manifest could not restore it by that name”. A previous value this plugin could not write back (REG_NONE or another type it cannot write, a shape it would refuse, over 1 MiB) is unsupported_old_type.

The undo budget. One 512 KiB CaptureBudget charges every retained byte (the data, the name and 64 bytes per row) BEFORE anything is kept; a refused item is not charged (it changed nothing, so its previous value is no undo evidence, and it cannot make a later item’s manifest incomplete); a row that does not fit is not retained and the summary says undo_complete|0, in the dry run too, so the operator sees an incomplete manifest before mutating. Each value keeps at most 4,096 bytes (a longer one is cut, which also makes undo_complete|0). The reply stays under the dispatcher’s 2 MiB capture cap (local_dispatcher.hpp): the retained rows render to about 1 MiB of hex, at most 256 audit lines (each under 2 KiB) add 512 KiB, and the item rows and the summary about 100 KiB.

Reference for integrators: error tokens

Error tokens of the mutating actions (the token table). error|<token> and the audit line’s reason= carry the bare token and nothing more, and the agent logs nothing about an ordinary failure (an exception is the exception: it is logged with the action name). A misspelt or missing value parameter on a REG_SZ, REG_EXPAND_SZ, REG_MULTI_SZ or REG_BINARY write is not an error: it writes an empty value of the type and answers status|ok (REG_DWORD and REG_QWORD refuse it as invalid_data).

Audit line grammar and producer contract (for integrators)

The plugin is the producer of the audit| line the server parses (server/core/src/plugin_result_audit.hpp). One line is the tag audit and 19 name=value fields, 20 |-separated parts, in this order:

The contract the server relies on (it cannot recover from a violation):

• One record per operation, one LF-terminated line. The agent writes the LF; the server tolerates one trailing CR and strips it. An apply is one operation per plan item it attempts: up to 256 records in one reply (the agent may split a reply across frames at its 64 KiB flush; either way inside the server’s 300-line frame bound); three 256-item applies inside one 60-second window exceed the 600-row-per-agent budget, and the later rows are suppressed (counted and logged, docs/user-manual/audit-log.md). Each item’s audit| line is written as the item concludes, before its item| row and before the next item opens anything, so a later exception inside the plugin, or a failed output channel, cannot take back the rows already written; an agent that dies mid-plan loses whatever it had not yet sent (it sends at command end or each 64 KiB); a dry run mints success rows with dry_run=1.
• No |, LF, CR or other control byte inside a field. audit_token replaces every control byte, |, space, =, ,, the C1 controls U+0080-U+009F, U+2028 and U+2029 with _ and invalid UTF-8 with ?, and cuts a field at 256 bytes (64 for op, hive, reason, sid; 32 for type) with ~<length>, so a registry key or value name that holds a delimiter cannot forge a field, pick the row’s result or start a second row.
• result=, reason= and verify= come before the caller-sized key= and name=. The server reads result as the first |result= token of the whole line (never dry_run=), but a line past its 4,096-byte bound loses its tail; the whole line stays under 2 KiB by construction.
• Server bounds. At most 300 lines of 4,096 bytes per output frame and 600 rows per agent per 60-second window; a bound that bites is counted and logged (docs/user-manual/audit-log.md).
• What old= and new= carry. The registry data itself, as hex of the raw bytes, the first 256 per value, then ~<total> when cut, for every value type (REG_SZ, REG_EXPAND_SZ, REG_MULTI_SZ, REG_BINARY, REG_DWORD, REG_QWORD), with no filter by key or value type: an audit row can therefore hold a secret. OWNER RISK ACCEPTANCE: the product owner accepted this risk on 2026-10-20 and masking is a planned later change; no redaction code exists. The readers are every role that holds AuditLog:Read or Response:Read (Viewer, Operator, PlatformEngineer, ITServiceOwner and Administrator), the legacy /events stream (any authenticated non-service-scoped session), MCP query_audit_log, and, for the write parameters (value and data_hex of set_value and set_user_value, the apply plan), executions.parameter_values. The same applies to the apply and per-user rows, and an apply reply’s undo manifest holds previous values at up to 4,096 bytes each (512 KiB per reply). By default audit rows are retained 365 days and the response store 90 days; no server pass prunes the executions table. A row is evidence of the change (except a dry_run=1 row, which records that a vet ran), not a restore point (a value cut at 256 bytes cannot be rebuilt from it).
• Pinned by tests. The byte-exact line and the contract case in tests/unit/test_registry_parsers.cpp; the plugin’s real renderer fed through the server’s extractor in tests/unit/server/test_plugin_result_audit.cpp.

Sample output

Windows — captured: windows Windows 10.0.26200 x86_64 · bare-metal · 2026-10-23 · interactive user (elevated; username, SID and profile path anonymised) · leg-hash 2db0b6e73233

== action=get_value hive=HKLM key="SOFTWARE\Microsoft\Windows NT\CurrentVersion" name=ProductName
value|Windows 10 Pro
type|REG_SZ
[result_status] UNDECLARED / UNKNOWN

== action=set_value hive=HKCU key=Software\YuzuCaptureTmp name=probe value=1
audit|op=set_value|hive=HKCU|result=ok|reason=-|verify=ok|key=Software\YuzuCaptureTmp|name=probe|type=REG_SZ|len=4|dry_run=-|counted_keys=-|counted_values=-|capped=-|created=1|sid=-|old_state=absent|old_type=-|old=-|new=31000000
status|ok
[result_status] UNDECLARED / UNKNOWN

== action=delete_value hive=HKCU key=Software\YuzuCaptureTmp name=probe
audit|op=delete_value|hive=HKCU|result=ok|reason=-|verify=ok|key=Software\YuzuCaptureTmp|name=probe|type=-|len=-|dry_run=-|counted_keys=-|counted_values=-|capped=-|created=0|sid=-|old_state=present|old_type=REG_SZ|old=31000000|new=-
status|ok
[result_status] UNDECLARED / UNKNOWN

== action=delete_key hive=HKCU key=Software\YuzuCaptureTmp
audit|op=delete_key|hive=HKCU|result=ok|reason=-|verify=ok|key=Software\YuzuCaptureTmp|name=-|type=-|len=-|dry_run=0|counted_keys=1|counted_values=0|capped=0|created=0|sid=-|old_state=-|old_type=-|old=-|new=-
status|ok
counted_keys|1
counted_values|0
dry_run|0
capped|0
[result_status] UNDECLARED / UNKNOWN

== action=key_exists hive=HKLM key="SOFTWARE\Microsoft\Windows NT\CurrentVersion"
exists|true
[result_status] UNDECLARED / UNKNOWN

== action=enumerate_keys hive=HKLM key="SOFTWARE\Microsoft\Windows NT\CurrentVersion"
subkey|Accessibility
subkey|AdaptiveDisplayBrightness
subkey|AeDebug
subkey|AppCompatFlags
subkey|ASR
subkey|Audit
subkey|BackgroundModel
subkey|ClipSVC
subkey|Compatibility32
subkey|Console
subkey|Containers
subkey|CorruptedFileRecovery
… 12 of 101 rows shown
[result_status] UNDECLARED / UNKNOWN

== action=enumerate_values hive=HKLM key="SOFTWARE\Microsoft\Windows NT\CurrentVersion"
value|SystemRoot|REG_SZ
value|BaseBuildRevisionNumber|REG_DWORD
value|BuildBranch|REG_SZ
value|BuildGUID|REG_SZ
value|BuildLab|REG_SZ
value|BuildLabEx|REG_SZ
value|CompositionEditionID|REG_SZ
value|CurrentBuild|REG_SZ
value|CurrentBuildNumber|REG_SZ
value|CurrentMajorVersionNumber|REG_DWORD
value|CurrentMinorVersionNumber|REG_DWORD
value|CurrentType|REG_SZ
… 12 of 32 rows shown
[result_status] UNDECLARED / UNKNOWN

== action=get_user_value username=jsmith key=Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced name=Hidden
username|jsmith
value|2
type|REG_DWORD
[result_status] UNDECLARED / UNKNOWN

== action=list_profiles
S-1-5-21-1111111111-2222222222-3333333333-1001|jsmith|C:\Users\jsmith|loaded
[result_status] UNDECLARED / UNKNOWN

== action=set_user_value username=jsmith key=Software\YuzuCaptureTmp name=probe value=1
[not captured] Mutating/Irreversible: added in registry 2.1.0 after this leg's 2026-10-23 capture; captured on a Windows host later

== action=delete_user_value username=jsmith key=Software\YuzuCaptureTmp name=probe
[not captured] Destructive/Irreversible: added in registry 2.1.0 after this leg's 2026-10-23 capture; captured on a Windows host later

== action=apply plan=[{"op":"create_key","key":"SOFTWARE\\YuzuCaptureTmp"}]
[not captured] Destructive/Irreversible: added in registry 2.1.0 after this leg's 2026-10-23 capture; captured on a Windows host later

macOS — captured: macos macOS 26.6.2 arm64 · bare-metal · 2026-10-26 · euid 501 · leg-hash 2db0b6e73233

== action=get_value hive=HKLM key="SOFTWARE\Microsoft\Windows NT\CurrentVersion" name=ProductName
registry|unsupported|Windows registry has no macOS equivalent; use defaults/plists
[result_status] UNDECLARED / UNKNOWN

== action=set_value hive=HKCU key=Software\YuzuCaptureTmp name=probe value=1
registry|unsupported|Windows registry has no macOS equivalent; use defaults/plists
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=delete_value hive=HKCU key=Software\YuzuCaptureTmp name=probe
registry|unsupported|Windows registry has no macOS equivalent; use defaults/plists
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=delete_key hive=HKCU key=Software\YuzuCaptureTmp
registry|unsupported|Windows registry has no macOS equivalent; use defaults/plists
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=key_exists hive=HKLM key="SOFTWARE\Microsoft\Windows NT\CurrentVersion"
registry|unsupported|Windows registry has no macOS equivalent; use defaults/plists
[result_status] UNDECLARED / UNKNOWN

== action=enumerate_keys hive=HKLM key="SOFTWARE\Microsoft\Windows NT\CurrentVersion"
registry|unsupported|Windows registry has no macOS equivalent; use defaults/plists
[result_status] UNDECLARED / UNKNOWN

== action=enumerate_values hive=HKLM key="SOFTWARE\Microsoft\Windows NT\CurrentVersion"
registry|unsupported|Windows registry has no macOS equivalent; use defaults/plists
[result_status] UNDECLARED / UNKNOWN

== action=get_user_value username=jsmith key=Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced name=Hidden
registry|unsupported|Windows registry has no macOS equivalent; use defaults/plists
[result_status] UNDECLARED / UNKNOWN

== action=list_profiles
registry|unsupported|Windows registry has no macOS equivalent; use defaults/plists
[result_status] UNDECLARED / UNKNOWN

== action=set_user_value username=jsmith key=Software\YuzuCaptureTmp name=probe value=1
registry|unsupported|Windows registry has no macOS equivalent; use defaults/plists
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=delete_user_value username=jsmith key=Software\YuzuCaptureTmp name=probe
registry|unsupported|Windows registry has no macOS equivalent; use defaults/plists
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=apply plan=[{"op":"create_key","key":"SOFTWARE\\YuzuCaptureTmp"}]
registry|unsupported|Windows registry has no macOS equivalent; use defaults/plists
[result_status] UNDECLARED / UNKNOWN
[rc] 1

Linux — captured: linux Ubuntu 26.04.1 LTS x86_64 · vm · 2026-10-26 · euid 0 · leg-hash 2db0b6e73233

== action=get_value hive=HKLM key="SOFTWARE\Microsoft\Windows NT\CurrentVersion" name=ProductName
registry|unsupported|Windows registry is not available on this platform
[result_status] UNDECLARED / UNKNOWN

== action=set_value hive=HKCU key=Software\YuzuCaptureTmp name=probe value=1
registry|unsupported|Windows registry is not available on this platform
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=delete_value hive=HKCU key=Software\YuzuCaptureTmp name=probe
registry|unsupported|Windows registry is not available on this platform
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=delete_key hive=HKCU key=Software\YuzuCaptureTmp
registry|unsupported|Windows registry is not available on this platform
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=key_exists hive=HKLM key="SOFTWARE\Microsoft\Windows NT\CurrentVersion"
registry|unsupported|Windows registry is not available on this platform
[result_status] UNDECLARED / UNKNOWN

== action=enumerate_keys hive=HKLM key="SOFTWARE\Microsoft\Windows NT\CurrentVersion"
registry|unsupported|Windows registry is not available on this platform
[result_status] UNDECLARED / UNKNOWN

== action=enumerate_values hive=HKLM key="SOFTWARE\Microsoft\Windows NT\CurrentVersion"
registry|unsupported|Windows registry is not available on this platform
[result_status] UNDECLARED / UNKNOWN

== action=get_user_value username=jsmith key=Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced name=Hidden
registry|unsupported|Windows registry is not available on this platform
[result_status] UNDECLARED / UNKNOWN

== action=list_profiles
registry|unsupported|Windows registry is not available on this platform
[result_status] UNDECLARED / UNKNOWN

== action=set_user_value username=jsmith key=Software\YuzuCaptureTmp name=probe value=1
registry|unsupported|Windows registry is not available on this platform
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=delete_user_value username=jsmith key=Software\YuzuCaptureTmp name=probe
registry|unsupported|Windows registry is not available on this platform
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=apply plan=[{"op":"create_key","key":"SOFTWARE\\YuzuCaptureTmp"}]
registry|unsupported|Windows registry is not available on this platform
[result_status] UNDECLARED / UNKNOWN
[rc] 1

Caveats and known gaps

1. The walk refuses a few writes that are not redirects. An ancestor the agent may traverse but not read (access_denied), an ordinary ancestor that holds a value named SymbolicLinkValue (key_is_link) and a path whose case differs from the stored spelling outside ASCII (key_is_link) are refused by the walk; on HKLM and HKU the fast open accepts the first two, and the write lands on the real key. HKCR can be refused key_is_link where its merged view puts a lower component in the other backing hive than the first (measured on Windows 11, 2026-10-23, for an interactive user; as SYSTEM, HKCR shows only HKLM\SOFTWARE\Classes), and for a real user HKCU\Software\Classes is itself a link (measured 2026-10-25), so a creating write below it is refused. Write such keys under HKLM\SOFTWARE\Classes or HKU\<SID>_Classes directly; an HKCR write that succeeds lands in the backing hive while its audit row says HKCR.
2. The audit trail identifies a change but cannot always reproduce it, and it can hold secrets. Names are folded for the line (audit_token: space, =, ,, |, control characters, the C1 controls, U+2028, U+2029 and a trailing backslash become _, cut at 256 bytes), old and new data are raw hex cut at 256 bytes, a delete_key row carries counts and no values, and a dry run mints result=success rows with dry_run=1; the hex can hold a registry secret (owner risk acceptance, 2026-10-20: masking is planned and nothing redacts it today, see Sensitivity.). An exception inside a write is contained at the plugin boundary and leaves a fixed result=failed, reason=exception line with every other field - (for apply, op=apply, after the rows of the items already done), while an agent that dies mid-command leaves no row at all, so in both cases read the key back.
3. Registry 2.0.0 and later ask a key for more access than 1.0.0 did. set_value opens the leaf with KEY_SET_VALUE and KEY_QUERY_VALUE and creates under each parent with KEY_CREATE_SUB_KEY, delete_value asks the same two on the leaf, delete_key asks DELETE, KEY_ENUMERATE_SUB_KEYS and KEY_QUERY_VALUE, and the walk adds KEY_QUERY_VALUE on every component; an ACL that grants less answers access_denied. A key the plugin creates is created with DELETE access, so that a stopped walk can remove it by handle: where an inherited ACL gives the agent identity no DELETE on a new key the create answers access_denied, deliberately with no retry.
4. The offline per-user arm and apply have limits of their own. The offline mount runs under one process-wide lock (a long write delays every other offline hive reader), its post-unload probe sees a hive loaded after the write returned but not a logon that failed while it was mounted, and a mount that fails to unload (hive_unload_failed), or one left by an agent that died mid-write, stays until reg unload or a reboot: the user’s next logon can get a temporary profile, and the plugin neither retries the unload nor sweeps old mounts (#5292, #3140). apply is HKLM only and not transactional, its dry run cannot see the ACL a key that does not exist yet will inherit (so would_apply is a prediction for a missing key and a fact for an existing one), each delete_key item can vet up to 10,000 values with no deadline, and a 256-item plan mints up to 256 of the 600 registry.write rows an agent may write per minute. The per-key handle map folds ASCII only while the kernel folds all of Unicode, so dependent_items refuses, conservatively, any plan in which two items share a path prefix (a parent or the whole key) that could be one key spelt with a different non-ASCII case; it also refuses two distinct sibling keys whose names differ only inside runs of non-ASCII characters (two all-CJK vendor keys, say) in one plan, so split those into separate plans. A single action on a key spelt in a different non-ASCII case from its stored form is still refused key_is_link.
5. Read output is display text, not exact bytes. In every registry string a read renders, |, control characters other than TAB, DEL, the C1 controls, U+2028 and U+2029 become _ and trailing NULs are dropped, so a<U+2028>b, a<VT>b and a_b render alike, and get_value has no exact-bytes mode for a string value; get_user_value reads a string value up to its first NUL and decodes REG_MULTI_SZ and REG_LINK, which get_value and enumerate_values leave as hex, and enumerate_values writes value|<name>|<type> with value as a literal tag, not a column. Do not drop the ReturnLength argument of the AdjustTokenPrivileges call in PrivilegeScope (agents/shared/win_profiles.hpp): without it the offline fallback silently never enabled its privileges until #2771. The get_user_value capture exercised the live-hive path, not the offline mount.

Source and tests

• Plugin: agents/plugins/registry/src/registry_core.hpp · agents/plugins/registry/src/registry_parsers.hpp · agents/plugins/registry/src/registry_plan.hpp · agents/plugins/registry/src/registry_plugin.cpp · agents/plugins/registry/src/registry_win.cpp
• Definitions: content/definitions/registry.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_a.hpp
• Tests: tests/test_registry_definition.py · tests/unit/test_registry_core.cpp · tests/unit/test_registry_local_dispatcher.cpp · tests/unit/test_registry_parsers.cpp · tests/unit/test_registry_plan.cpp · tests/unit/test_registry_win_internals.cpp · tests/unit/test_registry_write_local_dispatcher.cpp
• Privilege row: docs/agent-privilege-model.md