Skip to content

Architecture decisions

ADRs explain why the current architecture takes its shape. The manual pages linked from the documentation map describe behavior and operation.

Maintaining decisions

Keep one record per coherent decision with a current decision, rationale and consequences, and a decision history when the choice has changed. Fold amendments into the current explanation. Preserve the prior choice, reason for changing it, replacement, and original IDs in history; do not make readers follow obsolete records to understand today's design. Keep independently meaningful decisions separate. Reference-only details belong in the manual.

Update the record with its implementation. A reversal needs explicit historical rationale, not a plan presented as current behavior. State missing evidence honestly. When consolidating records, update the index and all in-repository references before removing redundant files. New decisions receive new IDs; existing records keep theirs.

scripts/check-standards.py, run by the repository check, validates unique and preserved IDs, current-record coverage, and current/history link destinations.

Decision index

Every original ID has a destination below. A historical destination preserves that record's rationale inside the current decision. Other rows lead directly to the decision bearing that ID.

Original ID Decision Current location
0001 Worktree command and skill ADR 0001
0002 Agent Resource Roots ADR 0002
0003 Plugin Activation Enables Implemented Components ADR 0003
0004 Session cockpit owns view status ADR 0004
0005 Pending Plugin Hook Consent Interrupts Interactive Startup ADR 0005
0006 Tabulated Cockpit Surfaces Share Table Plumbing ADR 0105 — history
0007 Worktree Has A Status Menu And List Surface ADR 0007
0008 Skill Roster Is Prompt Context ADR 0008
0009 Hook Audit Surfaces ADR 0009
0010 Worktree session owns plan execution ADR 0010
0011 Repair model tool input before pipeline execution ADR 0011
0012 Layer Bash authority within the selected permission mode ADR 0012
0013 Full-auto includes unconfined live Eval ADR 0081 — history
0014 Delegate invocation approval before human interruption ADR 0014
0015 Best-effort confinement falls back only before execution ADR 0116 — history
0016 Deny network by default and escalate additively ADR 0016
0017 Confine protected paths by default ADR 0017
0018 Reuse Codex execution escalation vocabulary ADR 0018
0019 Remove model-visible RequestAccess ADR 0019
0020 Run Bash through a login shell ADR 0020
0021 Isolate guardian prompt boundaries ADR 0070 — history
0022 Bound automatic plan revision ADR 0067 — history
0023 Goal outcomes outrank plan details ADR 0023
0024 Yield Bash through session-owned executions ADR 0024
0025 Agents execute asynchronously ADR 0025
0026 Remove the privileged coordinator ADR 0026
0027 Restrict agent messaging to tree edges ADR 0037 — history
0028 Support nested agent delegation ADR 0030 — history
0029 Limit active agent turns per session tree ADR 0029
0030 Agent tool grants transitive delegation authority ADR 0030
0031 Agent roles are optional overlays ADR 0031
0032 Agent follow-ups retain conversation context ADR 0033 — history
0033 Retain settled agents for the session lifetime ADR 0033
0034 Address agents by canonical task path ADR 0034
0035 Wake retained agents through messages ADR 0035
0036 Wait for agents explicitly ADR 0036
0037 Allow tree-wide agent communication ADR 0037
0038 List the addressable agent roster ADR 0038
0039 Interrupt agent turns without removing agents ADR 0039
0040 Fork an explicit parent context snapshot ADR 0095 — history
0041 Allow explicit agent model overrides ADR 0041
0042 Use one minimal agent spawn schema ADR 0095 — history
0043 Split agent observation from control tools ADR 0030 — history
0044 Bound agent waits with a successful timeout ADR 0036 — history
0045 Address agent tools only by path ADR 0034 — history
0046 Use plain-text agent messages ADR 0035 — history
0047 Keep agent command acknowledgements minimal ADR 0035 — history
0048 Deliver agent mail separately from wait results ADR 0035 — history
0049 Persist unread agent mail ADR 0035 — history
0050 Return every agent turn result to the spawn parent ADR 0035 — history
0051 Use one agent result envelope ADR 0035 — history
0052 Bound inline agent results ADR 0035 — history
0053 Limit automatic agent roster context ADR 0053
0054 Render agent activity from canonical events ADR 0054
0055 Charge capacity only for new follow-up turns ADR 0029 — history
0056 Fork effective post-compaction context ADR 0095 — history
0057 Compact agent conversations independently ADR 0057
0058 Freeze agent role configuration at spawn ADR 0058
0059 Centralize agent permissions in the root session ADR 0059
0060 Centralize agent interactions in the root session ADR 0060
0061 Recover abandoned agent turns as interrupted ADR 0061
0062 Do not clone live agents into session forks ADR 0062
0063 Persist the agent registry explicitly ADR 0063
0064 Publish agent spawns atomically ADR 0064
0065 Give worker an independent implementation toolset ADR 0030 — history
0066 Hooks Follow Lifecycle Boundaries, Not Model Requests ADR 0066
0067 Separate planning from Goal execution ADR 0067
0068 Keep Goal authority outside conversation history ADR 0068
0069 Drive Goals with idle continuation ADR 0069
0070 Compose system prompts from ordered profiles ADR 0070
0071 Isolate agent tasks by default ADR 0095 — history
0072 Make rewind in-place undo ADR 0072
0073 Identify fork points independently of turn numbers ADR 0073
0074 Keep direct user authority above heuristics ADR 0074
0075 Use one canonical permission-mode vocabulary ADR 0075
0076 Name fail-open confinement best-effort ADR 0076
0077 Scope sandbox policy to the session ADR 0077
0078 Default to best-effort confinement ADR 0078
0079 Require an explicit escalation retry ADR 0086 — history
0080 Do not depend on guardian availability ADR 0080
0081 Full-auto authorizes live Eval ADR 0081
0082 Full-auto authorizes additive network access ADR 0086 — history
0083 Store network authority in qualified tool rules ADR 0086 — history
0084 Limit reusable full escalation to literal operations ADR 0084
0085 Full-auto permits destructive operations ADR 0085
0086 Reuse approved execution permission profiles ADR 0086
0087 Keep directive identity outside source overlays ADR 0087
0088 Keep directive activity outside main chat ADR 0091 — history
0089 Make revision state-dependent implementation ADR 0089
0090 Enforce discussion as a read-only capability ADR 0090
0091 Render directive turns in the shared session view ADR 0091
0092 Use one patch-oriented file mutation tool ADR 0092
0093 Treat /btw as an ephemeral side conversation ADR 0093
0094 Centralize context-summary generation without centralizing workflows ADR 0094
0095 Select child-agent context explicitly ADR 0095
0096 Bind each session to one execution target ADR 0096
0097 Store durable sessions with their execution target ADR 0097
0098 Store unsettled mutation in the session lease ADR 0098
0099 Project live collaboration from host-authoritative state ADR 0099
0100 Use one portable authority for project sessions ADR 0100
0101 Carry control operations as one pinned program ADR 0101
0102 Settle remote stops by zombie-aware probing ADR 0102
0103 Spawn remote Bash on a private channel ADR 0103
0104 Keep resource addresses closed and capability-neutral ADR 0104
0105 Cockpit Surfaces Follow Three Archetypes ADR 0105
0106 The Directive Frame Is A Child Frame, Not An Overlay ADR 0106
0107 Non-Owner Buffers Follow Published State ADR 0107
0108 Buddy notes are not instructions ADR 0108
0109 Edit patch changes side by side ADR 0109
0110 Request config lives in the sidecar, not Org properties ADR 0110
0111 Run programmatic tool calls in a closed machine ADR 0111
0112 Debounce observational agent persists ADR 0112
0113 Show Ask Samples Inline Under Their Question ADR 0113
0114 Tie collaboration room lifetime to the host share ADR 0114
0115 Retain delivered reminders and completed provider response fragments ADR 0115
0116 Return failed confined launches without retry ADR 0116
0117 Publish journal results from fenced outcomes ADR 0117

Additional current records