docs(adr): ADR-039 agent execution model (pass a command, exit-code completion)#255
Open
NeuralEmpowerment wants to merge 1 commit into
Open
docs(adr): ADR-039 agent execution model (pass a command, exit-code completion)#255NeuralEmpowerment wants to merge 1 commit into
NeuralEmpowerment wants to merge 1 commit into
Conversation
…completion Records the decision (default = headless command in a tmux pane; exit-code completion; Stop-hook observability; send-keys demoted to a steering adapter; no heavy mode-selector) grounded in EXP-07/08/09 as rationale. Experiment records stay local; the ADR is the self-contained decision record. Refs okrs-51p.2, okrs-51p.7, ADR-038, #247, #254. Claude-Session: https://claude.ai/code/session_019TtekhJft4s2qBGRGgxToG
There was a problem hiding this comment.
Pull request overview
This pull request adds ADR-039 to document a decision on the default agent execution model for itmux-driven workspaces: run headless commands in tmux panes and treat process exit codes as completion, with Stop hook events as the primary observability signal.
Changes:
- Adds a new Architecture Decision Record (ADR-039) describing the “pass a command” execution model and why interactive send-keys is demoted to an opt-in steering adapter.
- Records experiment-based rationale for using
Stopas the completion signal and for preferring.env/env-based credential injection over host on-disk credential files.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+42
to
+45
| evidence captured from inside the container). This ADR records the decision those experiments | ||
| drove. The full experiment records (hypotheses committed before data per the running-experiments | ||
| two-commit protocol, plus `runs/` evidence) live in `experiments/EXP-07..09` and their setup + | ||
| outputs are summarized in Rationale below. |
Comment on lines
+184
to
+187
| - EXP-07 (stop-hook completion), EXP-08 (subscription auth + `-p`-on-Max), EXP-09 (mode vs | ||
| command) - experiment records in `experiments/`, run 2026-07-07, evidence under | ||
| `experiments/runs/EXP-0{7,8,9}/` (verified from container captures: written sentinels, session | ||
| ids, token counts, `ANTHROPIC_API_KEY`/`OPENAI_API_KEY` unset). |
| - Created: 2026-07-07 | ||
| - Updated: 2026-07-07 | ||
| - Author(s): Syntropic137 | ||
| - Related: ADR-038 (Rust-first execution + contracts), ADR-035 (workspace injection contract) |
Comment on lines
+188
to
+189
| - ADR-038: Rust-first execution and contracts. | ||
| - ADR-035: Workspace injection contract. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Captures the execution-model decision as a permanent ADR, with EXP-07/08/09 as the embedded rationale (experiment records kept local per request; the ADR is self-contained).
Decision: default execution = a headless command (
claude -p/codex exec) run in a tmux pane; completion = process exit code; observability = theStophook (fires even forclaude -pin a pane) + pane capture; persistence = the container. Interactive send-keys is demoted to an opt-in steering adapter; no heavy execution-mode selector.Rationale (validated 2026-07-07, evidence verified from inside the container):
Stop= clean 1-per-turn completion; daemons survive;SubagentStopadvisory (spurious afterStop).-p;claude -pNOT blocked on Max (the 401 was the stale on-disk file; live token is in the Keychain).Stop, persists, uniform across harnesses; only send-keys can steer mid-run.Contract + R7 orchestrator (#247) unchanged. Companion: #254 (.env credentials).
Status: proposed - please review/accept.