ADR 0002: Plugins return intents; the core applies them¶
- Status: Accepted
- Date: 2026-10-27 (proposed)
- Accepted: 2026-10-28
Context¶
Horae reads untrusted content (mail, notes, web pages) and writes to things the user cares about (the vault, notifications, remote services). If plugins or the LLM could write directly, a buggy or compromised plugin, or a prompt injection, could change anything, and there would be no reliable dry run, journal or undo.
PLAN.md makes three tenets of this (§2.1 tenets 3–5) and three
of its guarantees (§2.2): --dry-run writes
nothing, schema-invalid LLM output is never applied, and horae undo <run-id> restores every file
the run touched.
Decision¶
Plugins and the LLM never write; they return intents, and only the core, through a sink, applies them.
- Plugins never write directly. Sources, transforms and the LLM step return intents: typed
requests for a change. Only a sink applies an intent, and only after the core has validated it,
checked it against the proposing plugin's declared
permissions.intents, shown a dry-run diff and journalled it (§3.3). - Intents are a closed set with schemas:
note.create,note.append_section,note.replace_owned_block,task.create,task.update_status,notify.push,http.post(http.postonly to declared hosts). - Untrusted content stays data. It can fill schema fields, but it can never choose an action, a recipient or a URL that was not already in the input set (§2.1 tenet 5).
- Every applied change is journalled per run, which is what makes undo possible (§3.1).
The contracts:
schemas/intent/v1.json: one intent,oneOftagged bytype; one file per intent inschemas/intents/(e.g.intents/http.post/v1.json), generated fromsrc/horae/contracts/intents.py.permissions.intentsinschemas/plugin-manifest/v1.json; empty means the plugin may neither propose nor apply writes.- The run record (
schemas/run-record/v1.json) keepsintents[](each withstepandproposed_by) andchanges[](applied changes, each an index intointents). A dry run has nochanges.
The contracts constrain shape (safe note paths, https-only URLs, https or obsidian
notification links, one-line titles, size limits); the runtime still checks meaning, e.g. the
http.post host against permissions.network
(schemas README).
Consequences¶
Positive¶
- One choke point for all writes: validation, permission checks, dry run, journal and undo are implemented once in the core, not in every plugin.
--dry-runis trustworthy because there is no other write path.- Through the core, a compromised plugin can at most propose the intents it declared (checked from M1, approved at install from M4). Until M5 it can still reach undeclared hosts or paths directly (ADR 0003).
Negative¶
- A new kind of write needs a new intent type and a schema change in the core; plugins cannot extend the set.
- Sinks must be written so their effects can be diffed and undone, which rules out some integrations (and costly targets are read-only by policy, §2.3).
notify.pushandhttp.postreach the outside world and cannot be undone by the journal;undorestores files only.
Open questions¶
- §2.1 names intents
create_task,append_note,notify; §3.3 lists the closed set above. The v1 contract uses the §3.3 names (schemas decision 1). permissions.intentscovers both "may propose" and "may apply" (sinks); whether these should be two lists is open (decision 12).- Untrusted-content tagging is not part of the v1 run record (decision 21); how the core tracks provenance so that untrusted data cannot pick a URL or recipient is left to the M2 guards (#35, Untrusted-content tagging and action guard).
Alternatives considered¶
- Plugins write directly, with permissions. Simpler plugins, but no global dry run or journal, and enforcement would rely on every plugin being correct.
- LLM tool calls perform writes. Rejected by ADR 0001.
- An open, plugin-defined intent vocabulary. Extensible, but the core could not validate, diff or journal intents it does not understand.
References¶
- PLAN.md §2.1, §2.2, §3.1, §3.3
schemas/intent/v1.json,schemas/intents/,schemas/run-record/v1.jsonschemas/README.md(decisions 1, 2, 4–7, 12, 21)
Amendments¶
The accepted text above is unchanged; these dated additions record what later work settled.
Amendment (2026-10-28, #17)¶
On the open question of untrusted-content tagging: until the M2 guards, the engine's routing
(schemas decision 30) binds every target to a trusted
pipeline parameter: a note path or http.post url to the entry's, a notification link to
the entry's link_prefix, and a task status change to a fingerprint the run collected. Titles
and bodies stay untrusted text that appliers treat as data.
Amendment (2026-10-28, #35)¶
35 adds no per-value tags: the action guard ([schemas decision¶
46](../reference/schemas.md#decisions)) checks the LLM's text instead, so every URL in it is an exact string of the viewed input, no embed or script link is ever proposed, and a skill's per-type limits hold; a violation degrades the whole step. Plugin proposals are left to #52.
Amendment (2026-11-01, #122)¶
task.create takes an optional https:// link (schemas decision
52), so the trusted bindings of the #17 amendment gain one:
like a notification link, a task link is routed only to a mode: tasks entry
whose trusted link_prefix (one, or a list, decision 60; an off-prefix task is skipped with a recorded violation) it falls under (no prefix, no route), and an LLM-proposed link must
be a URL of the viewed input. The host is a name, never an IP literal; the sink writes the link
inert, after the escaped title, with a fixed label.