Repository navigation
Adr 0003 Tool Permission Matrix
- Status: Accepted
- Date: 2026-10-09
- Parent: #93 (AG8 Tools & Actions)
-
Blocks: #208 (the
permissionunion), #209 (what each level shows), #212 (one scenario per cell) - Related: #114 confirmation envelope (PR #126), ADR 0001, ADR 0002
The epic's line is LLM → Structured Tool Call → Validation → Domain Command → Event, and the agent
never touches storage. Three of the four links exist today:
- domain commands and the event log (
dispatch,LEARNING_EVENT_TYPES, the store's replay detection inappendEvent); - the confirmation envelope from #114 — propose → confirm → execute, hash-bound so a confirmation
after the state moved is refused, idempotent, expiring, cross-session-proof, audited in
agent_proposalsand evented asAGENT_PROPOSAL_EXECUTED; - the structured door AG9 left unused —
AgentRuntime.executeStructuredvalidates model output against a schema (docs/ag9-conformance.mdrecords that no skill calls it yet).
What does not exist is the layer between the model and those three: no AgentTool type, no
registry, no permission vocabulary, no check anywhere in the repo, and no renderer code that calls
confirmProposal. Registering tools without freezing what the three permission levels mean would
write the meaning into whichever slice landed first — which is how a convention becomes the only
thing enforcing permission.
This ADR freezes the levels and maps the epic's fourteen candidate tools over the commands the app already has, before any registry code. It is a decision record, not an implementation: the matrix is what #208's types will express and what #212's scenarios will try to cross.
| Level | The question it answers | Cost when the model is wrong | Obligations |
|---|---|---|---|
| safe-read | Nothing happens. | Nothing. | No confirmation. No store write on the path (asserted, not assumed). Bounded output. Session-scoped. |
| reversible-write | If it is wrong, a way back already exists inside the contract. | One tap of undo — or the effect expires on its own. | Quick confirmation. idempotencyKey. An undo path or self-expiry, named in the matrix. |
| structural-write | If it is wrong, nothing in the system can take it back. | A confirmation the learner gave with full information, once. | The proposal envelope: hash/TOCTOU, expiry, idempotency, the #209 screen, an event on success. |
The rule in one line: reversible ⇔ a tested way back already exists — an undo tool, self-expiry,
or re-derivation on read. No way back ⇔ structural. Granting an undo tool is how a tool gets
re-graded downward, and a re-grade amends this ADR; it is never a silent change of a kind value.
The levels grade risk to the learner's world, not vocabulary: a tool that stores nothing can sit
at read risk even though the learner sees an action (see openMaterialSection below). Whether the
agent may interrupt at all is not a permission question — that decision stays in the deterministic
intervention policy, unchanged by this ADR.
Every write — reversible or structural — goes propose → confirm → execute through the existing envelope. The level drives presentation and obligations, not a second pipeline:
- reads never create a proposal;
-
AGENT_PROPOSAL_KINDSgrew to['reversible-write', 'structural-write']when the first reversible tool registered (AG8.3,#238), and the adaptive rewrites were re-graded toreversible-writewith AG8.4 (#227) — the deferral this bullet used to carry is now spent, which is the change being deliberate: the matrix row and the proposal kind agree. What still typesstructural-writeis exactly what has no way back:completeTask,reorderSessionPlan,saveCheckpoint; - refusals reuse the
ProposalRefusalvocabulary (closed reasons, translatable keys), extended by #208 for the read-path reasons (unknown-tool,bad-schema,wrong-session,permission).
Every tool named in #93's goal, its level, what exists today (with the evidence), and why it holds
that level. "Today" is main at d9f1783.
| Tool | Existing implementation today (evidence) | Why this level |
|---|---|---|
readCurrentTask |
getAgentContext().task, getCurrentSession / getSessionProgress (IPC agent:context, session:current/progress) |
Reads a projection; the path writes nothing. |
readConcept |
getAgentContext().concept — summary, key points, title |
Same projection, same path. |
readMaterial |
listMaterials → excerptMaterial: the bounded excerpt the context already carries (AGENT_CONTEXT_LIMITS.materialCharacters), never the imported document |
The agent has never held the whole document; the tool cannot widen that. |
readCheckpoint |
getLatestCheckpoint (IPC checkpoint:latest) |
A row read. |
openMaterialSection |
Renderer view state only — course.page.ts's <summary> disclosure; no engine method, no IPC write, nothing persisted |
Graded by effect: it stores nothing, so it runs without asking. If it ever becomes an interruption, the intervention policy — not permission — governs it, and this cell is amended. |
| Tool | Existing implementation today (evidence) | Way back (why it is not structural) |
|---|---|---|
startTask |
dispatch(TASK_STARTED); appendEvent already reports current truth on a replayed event instead of writing twice |
Switching back is another TASK_STARTED; nothing is deleted, progress is unaffected. Session precondition checked in main. |
pauseTask |
Renderer focus-timer.ts pause() — phases ready/active/paused/expired, no domain event today; the tool lands in phase 2 over IPC |
Undo is resumeTask; the timer never outlives the session. |
resumeTask |
acceptResume / dismissResume + dispatch(TASK_STARTED); renderer focus-timer.ts resume()
|
The mirror of pause; the learner can always dismiss instead. |
extendTask |
Renderer focus-timer.ts addMinute() — no engine write today |
Self-expiring: an extension ends at expiry or session end; there is nothing to clean up afterwards. |
createAdaptiveTask |
AG4's rewrites through the envelope (engine.ts proposes kind structural-write); the rewrite is derived on every read, the stored course is never written |
Derived on read and ends with the task or with Continue — the reversibility AG2 documented. Registers as reversible-write when the kind vocabulary grows (AG8.4); typed structural until then. |
startBreak |
The BREAK rescue path (#169): the deterministic policy offers, resolveRescue accepts, steps come from buildRescuePlan
|
Self-expiring — three minutes that keep the position. Policy-gated: the tool cannot break where policy did not offer one. |
| Tool | Existing implementation today (evidence) | Why there is no way back (why it is not reversible) |
|---|---|---|
completeTask |
dispatch(TASK_COMPLETED) → progress and dashboard counts |
No compensating event exists; a wrong completion is counted forever. Structural until an un-complete design exists — that re-grade amends §1's rule here, with its own test. |
reorderSessionPlan |
TASKS_REORDERED (#23, #158) — the learner's own decision, recorded as the complete intended order |
Plan order is the learner's decision to make; #93 names it as structural. Another reorder by the agent is not an undo, it is a second structural write. |
saveCheckpoint |
createCheckpoint (IPC checkpoint:create); the resume path reads the latest checkpoint |
No checkpoint delete exists; a wrong row steers every later resume. |
Each level has at least one command the app already performs today (reads, focus-timer's
pause/addMinute, TASK_COMPLETED/TASKS_REORDERED/createCheckpoint), so the matrix grades
existing behaviour rather than a hypothetical API. Cells that name a future IPC surface say so.
Idempotency and session preconditions, per group. Every tool is validated against the current session in main before it runs — that column is one value for all fourteen, so it lives in §4 rather than being repeated. The idempotency mechanism differs by what the tool already is:
- The four reads are naturally idempotent (no write, nothing to double) and carry no key.
-
Every write that touches the store — the seven non-renderer rows — carries the tool call's
idempotencyKeyas its proposal key, because §2 routes all writes through the envelope: a second execute with the same key is a no-op replay, which #114 already tests. Where executing the proposal means dispatching an event (startTask,completeTask,reorderSessionPlan), the store's replay detection —appendEventreporting current truth instead of appending twice — is the second belt under the key. -
Renderer-local tools (
pauseTask,extendTask) have no store write today, so there is nothing to double — and §3b settles that they will not gain a model-facing IPC surface, so the double this paragraph worried about (addMinutetwice is two minutes) stays where it already is: in the renderer's own control, where a second press is the learner's second press.
The original fourteen tools predate learner-derived preferences. This adds a domain command cell, not a fourth permission level or a new model tool:
| Command | Level | Existing way back | Contract |
|---|---|---|---|
preference-write |
reversible-write | AG7.6 deletePreference: physical deletion, including the confirmation snapshots added here |
proposeStructuralChange({ preferenceCandidateId }) → main re-derives and freezes value + evidence → the existing hash-bound screen → confirm → execution transaction → insertLearnerPreference
|
Why reversible: the learner can inspect and physically forget the claim. The proposal/event snapshots must be scrubbed in that same delete transaction; a surviving copy would defeat the way back this grade relies on (ADR 0001). Opaque proposal identity/status and deletion audit remain.
- Only a candidate id arrives from the renderer; client-authored preference values cannot propose.
- The screen shows scope, bounded value, sample count and both window endpoints separately, so truncating a value cannot hide the evidence the learner confirms.
- The identity is
preference:<sessionId>:<candidateId>. Candidate ids fingerprint scope + value, not read time; stored preference ids include the session to prevent cross-session collisions. - A decline records
refused / declinedon that proposal. Pending, declined, expired, invalidated and executed decisions suppress the same claim on subsequent suggestion reads. A changed claim gets a new identity; clearing session memory removes the decision records as ADR 0001 specifies. - Confirm/execute reuses the envelope's expiry, state fingerprint, hash and replay checks. The preference insert runs inside its execution transaction; a failed insert rolls back the row, event and executed status together. Confirm-only and every refusal store no preference.
This cell is driven by a learner's suggestion button; it does not add a provider call, an unmetered skill, or a registry bypass for model-written claims. Proposal status/events are its audit record.
pauseTask and extendTask keep the reversible level §3 gave them — the grade was never the
problem: a pause resumes, and an extension expires with the session. What is decided here is that
the model may invoke neither, so no path to their effect is built:
| Tool | Level | Model-facing contract |
|---|---|---|
pauseTask |
reversible-write |
None. The learner's own control in focus-timer.ts; the agent's one interruption stays the policy-gated startBreak row. |
extendTask |
reversible-write | None. The learner's own control; an extension is the learner changing a promise they made to themselves, and the model may not move it. |
- A pause nobody asked for is an interruption, and §2's invariant leaves that decision with the deterministic policy rather than with the model. Asking "may I stop what you are doing?" does not avoid the interruption — the asking is it.
- An extension edits the learner's own commitment. "Five minutes" is the line that helps them stop; a model that can move it — even through a confirmation — makes the promise negotiable by the party that benefits from more time.
-
The need is already served.
startBreak(reversible, policy-gated, quick-confirmed) is the door for "I need to stop for a moment", and what the agent offers a stuck learner is AG2's smaller next step (MICRO_START,SIMPLIFY), not a louder interruption. -
Enforced, not agreed. Both names stay out of the registry, so a call naming either is refused
unknown-toollike any other unregistered name, andtool-registry.spec.tspins that absence — registering one later fails CI instead of arriving as a quiet addition.
Consequences: no FOCUS_TIMER_PAUSED/FOCUS_TIMER_EXTENDED event, no new IPC command, no new
proposal kind, and §2's kind vocabulary is unchanged. The "future IPC surface" §3 mentioned for
these two rows is spent in the negative.
- Validation lives in main: input schema, permission level, and current-session preconditions are checked before anything runs. The renderer displays; it does not judge arguments.
-
The model's entry is one schema, not a channel list. Tool calls arrive through
AgentRuntime.executeStructuredwith a closed tool vocabulary; no SQL, no table name, no arbitrary IPC channel is expressible. - The renderer still has no database permission — unchanged by everything above.
-
A successful write has an event; a failed write leaves no half-state; every call — attempt or
refusal — leaves a
ToolCallaudit row (#210), with ADR 0001's redaction discipline: args are recorded to answer "what was attempted", not as a second copy of the learner's content. -
Idempotency is required of every write: envelope
idempotencyKeyfor proposals, event replay detection for dispatches.
- #208's permission union is exactly
'safe-read' | 'reversible-write' | 'structural-write'— closed; adding a level amends this ADR. - #209 renders the level: structural gets the full confirm screen (params, impact, undo, refusal reasons); reversible gets the quick confirmation over the same envelope.
- #212 writes at least one scenario per permission level attempting to cross it, plus a forged-confirmation case; its Expected values name the closed refusal reason from this document.
- Phase 2 (AG8.3/8.4/8.5) registers the write tools against this matrix; two regrades are already
named and deferred —
createAdaptiveTask's kind when the vocabulary grows,completeTask's level if an un-complete design ever exists. Both amend this ADR. - AG8.7's confirmation UI, AG8.8's audit, and AG10.6's safety scenarios all read §3 rather than inventing their own permission story.
Confirmation wording and layout (#209's concern), which tools ship in which slice (#93's scope
comment), and whether the intervention policy offers an action at all (unchanged — deterministic,
in packages/intervention-policy).