nodwyn Scheme — language reference

nodwyn embeds a small Scheme for orchestration only. Scheme code decides what to do; every effect — reading a file, running a command, calling a model — is a Go primitive, and every primitive application crosses the guard. Scheme never touches the network or the filesystem on its own.

This document is the contract for the language (ADR 7). The interpreter implements what is written here and nothing else; the conformance suite has a snippet for every form and builtin below, and a builtin that is not documented here fails the suite.

§10 lists what is deliberately absent.

The language itself (§§1-8 and §10) is implemented by Brote, the Scheme interpreter nodwyn imports as github.com/fclaude/brote/scheme (a module of its own since 2026-10-22, ADR 7). Brote's docs/scheme.md is the source of truth for those sections, which are kept here so that this file reads whole; where the two differ, Brote's wins for the language. What is nodwyn's own is the host primitives (§5), the guard (§7) and the agent loop (§9).

1. Lexical syntax

A token is parsed as an integer if strconv.ParseInt accepts it in base 10, else as a float if strconv.ParseFloat accepts it and it is made only of digits, signs, a point and an exponent, else it is a symbol: inf, nan and 1_000 are symbols, and an integer too large for 64 bits reads as a float.

Unbalanced input is reported as incomplete, which the REPL uses to keep reading lines.

1.1 Raw strings

""" begins a raw string and the next """ ends it. Nothing between them is an escape, so quotes and backslashes are themselves:

(define pattern """\d+\.\d+""")

When the opening delimiter is followed immediately by a newline the block is read as indented text: that first newline is dropped, the indentation shared by every non-blank line and by the closing delimiter's line is removed, and the newline before the closing delimiter is dropped. A block therefore reads at the indentation it is written at and produces text with none:

(define instructions
  """
  Prefer table-driven tests.
  Run `make accept` before saying a change is done.
  """)

is exactly "Prefer table-driven tests.\nRunmake acceptbefore saying a change is done.". Lines indented further than the margin keep the difference, and blank lines stay blank.

Anything else is verbatim: """a "b" c""" is a "b" c.

Note that """ always starts a raw string, so an empty string written immediately before another string ("""x") is read as a raw string rather than as "" followed by "x". Separate them, as ordinary formatting already does.

2. Data types

number? is true for integers and floats.

3. Evaluation

• A symbol evaluates to its binding; an unbound symbol is an error.
• Numbers, strings, booleans and void are self-evaluating.
• () unquoted is an error ("empty application").
• A list whose head is one of the special form names below is that form. These names are reserved: binding one as a variable does not change how the form is parsed (this includes with-output-to-string).
• Any other list is an application: the head and every argument are evaluated left to right, then the procedure is applied.
• Proper tail calls. The last expression of a lambda body, begin, let/let* body, cond clause, and/or, and either branch of if is in tail position. A loop written as a tail-recursive function runs in constant stack space.
• Nesting is bounded. Evaluations nested inside each other (calls not in tail position, recursion through a primitive such as map) are limited to 10,000; past that the evaluation raises eval: recursion too deep: more than 10000 nested evaluations, an ordinary error guard can catch. The reader refuses a datum nested deeper than that, json-emit refuses a value nested deeper, equal? treats values nested deeper as equal only when they are the same object, and the printer writes ... past that depth, so a vector that holds itself (vector-set!) prints, compares and emits without end. load refuses a file that is already being loaded. Without these bounds a runaway recursion overflowed Go's stack, which ends the whole process.

Special forms

define inside a lambda body binds in that call's environment (internal definitions). When define names a fresh anonymous closure, the closure takes that name for printing and error messages.

4. Errors

(error message irritant …) raises an error whose text is message followed by the written irritants. Runtime failures (unbound variable, wrong argument count, wrong type, division by zero, a denied primitive) raise the same kind of error with a message of the form who: what.

Errors may be caught with guard (§3):

(guard (e ((string-contains? (assoc-ref e 'message) "boom") 'caught)
          (else (assoc-ref e 'irritants)))
  (error "boom" 1 2))            ; caught

An error not caught by any clause unwinds to the host, which reports it (the REPL prints it, the agent loop feeds it back to the model as the tool result).

A primitive the guard denies raises <name>: denied: <reason> (fs-read: denied: …). Denials and the turn's own cancellation (an abort, the turn's deadline) pass through guard untouched: a program cannot hide that it was refused, and an abort always unwinds. A primitive's own timeout while the turn goes on (a judge's ten seconds, an MCP call's two minutes) is an ordinary error guard catches. So do the agent loop's stops (§9): a spent budget, the tool-call limit, a progress stop and a log that can no longer be written end the turn whatever the strategy's guard clauses say.

5. Builtins

Signatures use … for variadic and [x] for optional. Every builtin is a primitive in the table (§7) and can be listed with (primitives).

Numbers

Booleans and equivalence

Pairs and lists

Vectors

equal? compares vectors elementwise; eq?/eqv? compare vectors by identity.

Strings

There is no character type; one-character strings serve that purpose.

Output

Output goes to the interpreter's output writer, which the host provides (the REPL uses stdout; the agent loop captures it). All three yield void.

Control

JSON

Mapping, in both directions:

json-emit treats a proper list whose elements are all pairs with string cars as an object and any other proper list as an array. Consequently '() emits [], there is no way to emit {}, and parsed JSON does not always come back as it was: an array of arrays that each start with a string ([["a","b"]]) parses to a list that emits as an object ({"a":["b"]}). An MCP tool's arguments are written by its schema instead: an argument the schema calls an array is emitted as one, and one it calls an object as an object, {} when empty, so a server gets them as the model wrote them. Procedures, handles, vectors, void, symbols other than null, and a NaN or infinite float cannot be emitted.

This mapping is also how the agent loop turns a model's tool-call arguments into Scheme values (ADR 3).

Host primitives (registered by the session, not by nodwyn repl)

MCP servers you approve in the console (ADR 23) add one primitive per tool you turned on, named server__tool (model APIs refuse /; the console shows server/tool). Each is egress to that server's host, with the server's key, if it has one, bound to it, and a tool you did not declare as reading only confirms every call. Every argument is a payload: a literal key in it is refused unless its class is bound for that host (L1), and content from outside may go there because you approved the server, key or not (L2). Results are tagged external:mcp. They are offered to the model like the tools above.

A contained server's tools (ADR 23 W3b) send to its container, mcp:NAME, which may pass the arguments on to the hosts of its network list and nowhere else. A literal key in them, or a value derived from a credential, is refused unless its class is bound for every one of those hosts; with no network, always. The call carries no credential: the server's key went in when it started, and its binding is checked again before each call. The confirm and the tool's description name the contained server and what it can reach.

Provenance (L2)

Every value carries provenance tags: where it came from, not what it contains. A host primitive tags its result (fs-read, fs-list, fs-find, index-grep, git-status, git-diff, doc-export and policy-read mint external:file; shell-exec and the background-process primitives mint external:shell; http-request, the judge-* primitives and google-doc-upload mint external:http; MCP tools mint external:mcp; session-list, session-events, recall and index-search over the conversation and earlier tasks mint external:log, and index-search over the repository and index-update external:file), a credential handle carries cred:<class>, and the tags of a call's arguments flow into its result.

Propagation happens at the primitive dispatch. A list keeps each element's tags on the element, and a list built without a primitive (by map, by quasiquote, or holding what vector-set! put in a vector) may carry none of its own; so a string a primitive makes from a list or a vector (string-join, json-emit) takes the tags of everything in it, as do the output with-output-to-string captures and the message guard hands on from an error that quoted a tagged value. A primitive whose result measures its arguments rather than being made of them carries nothing: length, string-length, vector-length, every predicate (null?, string?, even?, …), the comparisons (=, <, string=?, string-contains?, …), not, and taint-of itself.

What provenance is for: the guard refuses to send content that came from outside to a destination no binding authorises, and refuses a command line built from tool output without a confirm. What it is not: a boundary against the user, who may wipe, and it does not survive a value being rebuilt a character at a time through the opaque primitives above. The real egress lines are the binding table, fail-closed defaults and ingress redaction (SPEC Risk 1).

Meta

6. Prelude

Brote's scheme/prelude/*.scm is embedded in the binary and loaded into the global environment before anything else. It defines, in Scheme:

After the prelude, nodwyn loads the current ./.nodwyn/init.scm only after external user trust (ADR 14, amended by ADR 45). nodwyn trust reviews and accepts the init/allow revision; a clone cannot grant its own startup authority.

7. Primitives and the guard

The primitive table maps a name to a Go handler plus metadata. It is the only surface through which Scheme reaches the host (SPEC invariant 4).

Every primitive declares:

Parameter roles (path, source, dest, payload, credential, and for commands and keyed requests argv, method and position) tell the guard what an argument is; they are declared by host primitives. A path is what the primitive acts on, and writes when it is irreversible; a source is a file it only reads, whatever else it does (doc-export's document, the file google-doc-upload sends). Both are pinned and checked against the credential-file denylist, but a read-only mount may supply a source even to an irreversible primitive. A write is an irreversible primitive with a path and something to put there: a payload, or a source. A field of a list parameter's elements may carry a role too (ADR 38): each new in fs-edit's edits is a payload, so the secret scan and the taint check see every replacement, and not the old text it replaces, as they see a single edit's new.

Application of a primitive — whether from the model, the prelude, a .scm file or the REPL — goes through exactly one Go function, which:

1. checks the argument count against params/variadic;
2. asks the guard (when one is installed) for a decision; a denial raises denied: <reason>;
3. calls the handler.

register-tool adds a primitive whose handler applies a Scheme procedure:

(register-tool "go-test"
  (lambda (pkg) (shell-exec "go" (list "test" "-race" pkg)))
  '((doc . "Run the Go tests for a package pattern")
    (params . (("pkg" "string" "package pattern, e.g. ./internal/log")))
    (irreversible . #f)))

Rules: the name must be new (builtins cannot be shadowed, and a tool cannot be re-registered — the tool list must be stable for the whole session, ADR 9); once the session has fixed its tool list, register-tool is an error wherever it is called from. doc and params are required; egress, irreversible and variadic default to #f. What a provider or the first call would reject is refused where the tool is registered: a name outside 1 to 64 letters, digits, - and _, a parameter listed twice, and a procedure whose arguments do not fit params (a variadic tool needs a rest parameter). A registered tool is indistinguishable from a builtin at the dispatch site, and its own primitive calls are guarded in turn.

register-check (ADR 20) adds a guard checker written in Scheme:

(register-check "no-external-llms" "confirm"
  (lambda (prim-name args)
    (or (equal? prim-name "shell-exec")
        (equal? prim-name "http-request"))))

• name is the checker name that appears in guard.decision events.
• verdict is fixed to "deny" or "confirm" at registration time. It can never be "allow" — the guard merges decisions strictest-wins, so a user checker can only tighten, never relax.
• predicate is a procedure (prim-name args). When it returns a true value (anything but #f, as everywhere in Scheme) the checker returns its fixed verdict; otherwise it has no opinion (allow). A predicate that raises an error fails closed as a denial.

The builtin is hidden (never offered to the model as a tool) and callable only from user-originated Scheme — the model cannot add or bypass checkers at runtime. Checkers registered this way run after all built-in Go checkers in the pipeline.

Read-only tools may run concurrently, but Scheme checker predicates are evaluated one at a time across all the session's registered checkers. They share the interpreter's bindings, so a predicate's state changes cannot race another predicate. Their strictest-wins and fail-closed rules still apply.

Loading a .scm file can grow the primitive table and the global environment. It cannot add special forms or change evaluation: eval and apply are two fixed Go functions, and the test suite checks, after loading arbitrary code, that the primitive table grew by the registered tools alone and that define-syntax is still a plain binding.

8. Embedding API (Go)

in := scheme.New(scheme.WithOutput(w))       // prelude loaded
v, err := in.EvalString(ctx, "(+ 1 2)")      // last value of the source
v, err = in.Apply(ctx, proc, args)           // call a procedure
err = in.Register(&scheme.Prim{...})         // add a host primitive
in.SetGate(g)                                // install the guard
snap := in.Global().Snapshot()               // copy the global bindings
in.Global().Restore(snap)                    // put them back, unbinding names bound since

ctx cancellation is checked at every application; a cancelled evaluation returns the context's error. ctx also says who started the evaluation (scheme.WithOrigin: the user, the model or the loop's strategy); a context that does not say is the strategy's, never the user's, so an embedder gives the user's powers (wipe, register-check, policy-write) only where it says so.

9. The agent loop

A turn is a Scheme procedure. The session records the user's message and calls (turn-start request) and then (nodwyn-turn request) with the recorded (redacted) text; nodwyn-turn runs the plan gate when the turn must plan and then (agent-turn request) (§9.5). turn-start resets what the default habits keep for one turn (the stop after a compaction that wrote nothing, the stalled count, the request second-look reads, whether the turn has edited code), so a project that replaces nodwyn-turn keeps those resets; one that redefines turn-start calls the definition it replaces, as the habit files do. The defaults are installed before .nodwyn/init.scm loads, so a project can redefine either. Stripped of /compact, /optimize, the plan gate, ask-model's retry of cut replies and the evidence loop for unattended turns (all below, and in internal/loop/strategy.scm), the default agent-turn is this loop:

(define (agent-turn request)
  (let loop ((reply (model-turn)))
    (let ((calls (assoc-ref reply 'tool-calls '())))
      (unless (null? calls)
        (run-calls calls)
        (maybe-compact request reply)
        (loop (model-turn))))))

When nobody reviews the work as it happens — (unattended?) (nodwyn run's --yolo, a run's auto_approve, --judge, --unattended) or a supervised run's turn (plan-required?) — the default agent-turn ends a turn on evidence, not on the model's word (evidence-loop): a reply that stops before anything changed, or with a change and no test run after it, gets finish-no-change-message or finish-untested-message, at most finish-reminders (2, and 0 in the lean profile, §9.8) times; one whose last test or check run after the last edit exited non-zero gets finish-failing-message once until the next edit, and may answer that the tests fail on the unchanged code too and end. The loop reads the tests a run reports failing (failure-names: Go's --- FAIL: and FAIL<tab>package, pytest's FAILED, unittest's FAIL: and ERROR:) and keeps those of the runs it knows are on the unchanged code through the edits after: any run on $TMPDIR/base, and a full test run (not -run, -k or a node id) before the turn's first edit, in a turn that began on the last commit. A run that fails only such tests, none of which the request, the plan or a file the turn wrote names (failures-known?), is not told: its result says they failed on the unchanged code (failure-known-hint) and the reminder is not due. When only some are such, the reminder names them (finish-failing-known-message: say so in your answer, do not fix them) and the others (ADR 32, amended 2026-10-16). An exit that says no test ran is no failure: not-run-statuses (126 and 127, a program not found or not executable) and, for a pytest command, pytest-not-run-statuses (4 and 5, a path it could not find, no tests collected). A run on the copy of the last commit ($TMPDIR/base, base-run?) tests nothing of the change; one that fails after the change's run failed is the comparison done, and the failing run is not told. After finish-no-change-message a turn that has run a test or check may end unchanged: the code may already do what the request asks, and the message says to show it with a check (ADR 32, amended 2026-10-10). In sandbox mode ((sandbox?), ADR 55) no turn is told that nothing changed: the whole machine is the workspace, and a command may change a file anywhere on it that neither git nor the file tools see. When such a turn first ends with a change and none of those reminders is due, the finish review (finish-review-points) gathers what the change lacks and says it in one message, (finish-review-message points): one point as it is, several numbered, closed by finish-review-close (asked once; run the check again after any change; the next reply without tool calls ends the turn). It is made once a turn, and the turn is accepted after it: an answer ends it, and the reminders above are not asked again (ADR 32, amended 2026-10-15). In a run nobody reads as it goes it is made at most finish-review-limit (2, and 0 in the lean profile) times in all, counted in finish-reviews over the session's turns; a turn after the second ends on its report. A turn whose answer a person reads ((reviewed?)) is not held to it (ADR 32, amended 2026-10-16). Its points: files new since the turn began that git does not track ((finish-new-files-message files), below); a plan's steps without their evidence (§9.5, plan-language-unmet-message; a test step may name a scenario or fixture file, a path through a scenarios, testdata or fixtures folder, which is met by that file, one the repository has or one the turn wrote whose name starts with the step's path, and by a go test run of the folder above it: plan-language-test-present?); the parts of the change the check or test run that exited 0 since the last edit and runs the most of what changed (broadest-passing: the one that names the most of the changed files' directories, ./... and the whole-check words naming all of them, one not narrowed to some tests before one that is, the newest of those that tie; not the last passing run, which was the exfiltration suite alone on 855e90e7) does not test, run again with each part taken out in turn (check-without) and naming the parts it still passes without, printing the same (finish-untested-parts-message): a check that cannot fail for a part does not test it, and one that prints something else without it does, whatever its exit status. The review asks for a test only a few times: it names at most finish-ask-limit (3) of those parts, the largest first, and of the plan's test steps whose test is missing or passes on the unchanged code, and of the dropped conditions, says how many more there were, and does not name an item again in a later review of the run (finish-ask, finish-asked); the parts message asks for a case only for a part that implements what the request asks for, and says a flag, a rename, a refactor or a skip gets no test (ADR 32, amended 2026-10-16). And a command the final report cites in backquotes, one the turn ran (shell-commands reads each command line as the shell does) and has not run since the last edit (stale-citations, finish-stale-citations-message). Runs on $TMPDIR/base never go stale, and once the repository's whole check (whole-check-words: make validate, make check, make test, …) has passed since the last edit, a cited check command stands on it. When the latest run since the last edit passed, so the model's own check did not notice, the review also names what the change removed (change-removals): definitions HEAD had in a changed file that its package no longer defines and the request does not name (finish-removed-definitions-message: keep it and have its callers go through it, unless removing it is the task), and lines of existing tests that stated an expectation, a case of a table or an assertion, removed or rewritten (finish-removed-expectations-message: restore each the request does not change, or quote the words that change it; not the lines whose answer to the question at the edit was read and supported, and, as the review's first point, the lines it was not: finish-unsupported-edits-message, below), and the existing tests the turn edited that fail when their files are as HEAD had them (original-tests, finish-original-tests-message: the tests are named; either the change is wrong, so change the code, appending to what a test pins rather than rewording it; or the request names the new result for that input or case, so the assertion changes and the answer says which sentence requires it; or the request contradicts the test's setup, a fixture, so change the setup and not its assertions, and say which sentence requires it; any language: the check the turn passed is run again with the edited test files as HEAD had them, and the tests are named from its output; the log says when no passing run runs the edited files), the tests of a run that failed that the last commit passes (regression-failures, finish-regressed-tests-message: the same command with every changed file as HEAD had it; your change breaks them, so change the code, or say which sentence of the request requires it), and the parts of a condition a rewritten Go function no longer checks (change-dropped-conditions, finish-dropped-conditions-message: add a test case where it is false if the task drops it, else put it back). And it names the lines the change adds to documents and Go and Scheme comments that state what nothing in the turn showed (change-claims, finish-unshown-claims-message): a sentence reporting a run (passed, warnings, found nothing, executions, a fuzz or benchmark figure) that no run of the command it names, exited 0 in the turn, backs with its figures among its last lines; an amendment date the file did not have that no command printed and the request does not give; three or more lines a document's edit inserted that stand word for word elsewhere in it; and entries a hand edit added to a generated file (its head says Code generated or Generated by, or names a "source" address, or a trusted .nodwyn/init.scm lists it in generated-files as (path command) rows) with no command after the edit that made or fetched it. The loop keeps the turn's commands for it (shown-entry: each command line, exit status and the first shown-head and last shown-tail characters it printed, at most shown-max of them; the file tools and the tools that only look are left out, since their answers show the model's own text) and the files it edited by hand with the commands run since (hand-edits-add). A command is a test run when its command line contains one of test-command-words (pytest, go test, cargo test, npm test, make test, make validate, …; a project may redefine the list), whether shell-exec ran it or shell-start did and shell-read or shell-stop saw it exit after the last edit (background-call: the shell-start call itself, never one rebuilt from the shell's output, whose taint the guard would refuse when check-without runs it again), or a tool the repository registers to run a command did (tool-commands: validate is make validate, go-test {pkg} go test , run-make {target} make ; a project may add rows): tool-call makes the shell-exec call that runs its command from the call's own arguments, and the tool's text gives its status ("exit N", or a background run's "pN: exited N"); a tool's whole check (validate) runs for minutes, so it is not the check check-without takes apart, though its pass stands for the whole check's. A run whose status may be another command's (masked-run?: a pipe without pipefail, an ||, a $? in the line) passed, for a plan's evidence and marks, only when its output shows tests passing and none failing, and a run on $TMPDIR/base never did (run-entry); a Go test step needs its test's --- PASS or its package's ok in the output (ADR 32, amended 2026-10-14). After unrunnable-after (6) test commands in a row fail to run, the model gets (finish-unrunnable-message n) once: finish and report the change as unverified rather than spend the budget on a broken environment. A run that shows tests ran here does not count, and ends the count (tests-ran?: a test it names failed, a test or package passed, or a package says FAIL with a time of its own, not [build failed]), and neither does a failing run after an edit that took part of the model's own change out (shrinking-edit?: the file's changes against HEAD got smaller, measured from the turn's first command on), which is a revert experiment, expected to fail, and leaves the count where it was (ADR 32, amended 2026-10-16, the original tests). In sandbox mode, the first time a turn of the session ends on the model's word (a reply without tool calls, with none of these messages due), default-agent-turn says sandbox-finish-message and goes on as the evidence loop, so the turn ends at the model's next answer unless a reminder is due: the model is asked to check its result as someone who did not watch it work would, and to replace what only makes its checks pass with a real solution or remove it and say what does not work. It is said once in the session (sandbox-finish-said), in either profile and under lean-quiet too, never after a stop or to a turn that is stopping (turn-stopping), and the log has a note beginning "sandbox finish check:" (ADR 55, amended 2026-10-19). When a person reads the turn's answer before anything else happens, (reviewed?) (a chat's turn, or a supervised run's turn that a run checkpoint follows; not an unattended run, nor a run's last turn), a reply that changed nothing gets finish-no-change-reviewed-message instead: make the change, unless the request asks for no change yet, such as a proposal to review first. After it the turn may end unchanged. Where git-status exists, it names every changed file, credential files included (a name is no secret; git-diff leaves their contents out), so a file changed through the shell counts. The scratch directory is not the repository: a file the model writes there (as $TMPDIR/… or by its path) is not a change, and a command that runs one of those files — its check script — is a test run. A check fails until the work is done, so its failing runs never count toward unrunnable-after. In a turn nobody reads ((unattended?)), a test or check run that passed after the turn changed something has the loop call (keep-passing): the host keeps the repository's changes as they are. If a hard limit or the progress guard then stops the turn, which no strategy can catch, the core puts the files back to that state, saves what they held after it, and says so in the log and in the turn's end (ADR 18, amended 2026-10-06). A turn that changed nothing keeps nothing, and a chat, a person's own stop or a soft limit put nothing back. Where git-status exists, git says whether anything changed, edits made through the shell included: a tracked file's status differs from the start of the turn, or the file tools wrote a file git now lists as new or listed already; files a run leaves behind are no change. Files new since the turn began that git does not track are a point of the finish review, (finish-new-files-message files): whatever is left in the repository is in the change. Files the turn's plan names, by path or by name (plan-names?), or whose name starts with a plan step's path (a scenario file: test/exfil/scenarios/019 for 019-key-before-private-key.scm), are left out of it: the plan asked for them. A shell run of make validate or go run ./scripts/validate (validate-commands) that ran to an exit counts, for a repository whose .nodwyn/init.scm defines validation-state and validated-state (nodwyn's does, to remind a turn that has not validated since its last change), as its validate tool's run: validated-run sets validated-state as the tool does, and either is a test run, the whole check, and no check for check-without to take apart. The untracked files a validate run, or a tool of tool-commands, leaves (files-made: new in git-status since the round began, not written by the file tools) are the run's output, not the change. The validate result names them (validate-left-note: delete them unless they are part of the change; that needs no new run), and the loop keeps the repository as validate left it: when the only thing that moved since is that some of those files are gone, validate still stands and validate-settle sets validated-state again, so the repository's reminder is not said for a deletion. A file still there when the finish review is made is named in it as one whose deletion needs no new run (ADR 32, amended 2026-10-16).

The loop also asks about an expectation of an existing test as the edit is made, not only at the finish. After a round whose calls wrote a test file (test-file-path?: x_test.go, test_x.py, x.test.js, a file under tests/) not yet asked about in the turn, it sets the change against HEAD with change-removals and, for the lines of that file, adds (edited-expectations-message lines) before the next request (test-edit-nudge, which returns (files . lines)): which sentence of the request requires the new expectation, for that input or case, answered in a form, one line for each row, the row and then a sentence copied word for word from the request that names the input or case the row tests; if none does, none, restore the line and change the code (appending to the phrase a test pins, not rewording it). The expectation lines are a case of a table, an assertion that carries one, a literal assigned to want, expect, expected or a name that starts with one (wantErr, expected_msg), and in Go a strings or bytes check (Contains, ContainsAny, HasPrefix, HasSuffix, EqualFold) of a string literal that is not a case line; a line whose string literals all stand on one line the change adds (a case moved from a map to a direct assertion) is not removed. The edit is never refused. The lines are HEAD's, so a test the turn added, or a case it adds to a table, is not asked about, and a file is asked about once in a turn.

The answer is read, not weighed (edit-answers, edit-support). The rows the question named are kept for the turn, each in the state asked, firm or ok. After every round whose reply has words, the rows still changed (the model may have restored one: then it is answered) are set against the reply with (edit-support lines request reply): a quote is a run of three words or more of the reply that stands in the request in the same order, case, punctuation and white space aside, and it supports a row when it shares a distinctive token with the row's string literals, its input and the message it expects, and with the line that replaces it (a word of three letters or more, or a number from 2 up, lightly stemmed, that is no stop word and no part of the name of a function the row calls; the words of its identifiers when its literals give none). A row whose replacement cuts words out of the phrase it expects, or puts words inside it, needs more: a quote with most of the words cut or all of the words put, so that appending to a pinned phrase is supported by the sentence that asks for the addition, and cutting or splitting it is not. A supported row is ok; a row with no token to judge it by is left to the review's other point. A reply that quotes the request and supports no more of a row gets one firmer message for it (edited-expectations-firm-message: what the request does not mention, the default of restoring the old expectation and changing the code, and that the row is kept only by quoting the sentence that names it), and its state becomes firm. A reply that quotes nothing is no answer yet, and the reply that ends the turn is read for the rows it supports and says nothing more. At the finish, the rows still unsupported are the review's first point, with the original tests that fail (finish-unsupported-edits-message). Nothing is reverted or refused: the model may keep an edit, against the evidence (ADR 32, amended 2026-10-16).

The finish review used to ask for the lines of the change that no test ran (finish-uncovered-lines-message, with coverage-extensions, branch-words and coverage-run?) and no longer does: on commit-bench 6e18b7ba (dsl22) the model spent 62 of its 167 calls and 1.12M of its 2.38M cost-eq running coverage and writing tests for branches of its own defensive code. source-extensions and source-path? remain, for the directories a change touches (changed-dirs, which broadest-passing uses).

Both loops also count, in stall-check, the rounds in a row whose reply thought at length (stall-reasoning-tokens, 10,000, or more reasoning tokens, as ask-model noted in last-reasoning) and whose calls wrote nothing; at stall-rounds (3; 0 turns it off) the model gets stall-message, to write down the design it reached and make the edit, and the count starts again. Each turn starts it at 0.

Both loops, the chat's and evidence-loop, count the rounds in a row whose calls only look, at the repository or the conversation: every call names one of look-tools (fs-read, fs-list, fs-find, index-grep, read-definition, git-status, git-diff, index-search, recall; a project adds the tools of its own that only look). After reading-reminder-after (12; a table, §9.7; never under lean-no-read-reminder, the lean profile's) such rounds the model gets (reading-reminder-message n), or (reading-reminder-reviewed-message n) when (reviewed?): its thinking may not come back to it, so write down what it found now, as a plan with plan-write, or, when a person reads the answer and the request asks a question or needs their decision, as the answer. A turn that has a plan ((plan-recorded?)) is told instead to make the change for the plan's next unmarked step, and to write the plan again only if it must change, since a step it rewords starts unmarked. Any other call starts the count again, and so does the reminder; 0 turns it off.

A reply's done is "length" when the model reached the output cap (the model's reply cap: its max_output, else the longest reply its provider publishes (at most a quarter of its context), else window.output_reserve, at most a quarter of a context too small for the window and that reply); the core notes it in the log. What to do is the strategy's: (ask-model …) is model-turn, asked again with output-cut-message when the reply was cut with no tool call to answer, at most output-cut-retries (2) times. A plain (ask-model), the one that offers every tool, is also asked again, once (empty-reply-retries), with empty-reply-message, when the reply has no words and no tool call: such a reply would end the turn with nothing to read. The default loop, the planner and sub-agent use it.

A strategy talks to the model through tools: a tool's description is an instruction, its result and a skip reason are feedback. add-message is for when there is no call to answer, such as a model that stopped with work left.

Routing work to another model is narrow-context, add-message and (model-turn name) in a loop: the other model gets a context the strategy built, and its tool calls run like any model's. Narrowing and routing are events in the log, so replay rebuilds every request whichever model it went to.

These primitives are hidden from the model. The ones that act on the conversation (model-turn, run-tools, skip-tools, answer-call, add-message, log-note, fold-result, record-plan, plan-steps, record-step, record-compaction, narrow-context, fold-context, widen) are refused outside a turn and from model-originated code; the ones that only describe the session (model-info, model-names, window-limits, session-system-prompt, session-requests, context-tokens, unattended?, sandbox?, reviewed?, plan-required?, plan-recorded?, run-plan, unfinished-plan, session-list, session-events) answer at any time (session-system-prompt and context-tokens once the session has started), which is how compact.scm reads (window-limits) as it loads. The strategy runs with harness origin, so it cannot strip provenance or change policy (wipe, register-check and policy-write are user-only); the tools it runs execute with model origin, as if the model had called them directly. Whatever the strategy does:

• it runs or skips only calls the model made, each once, with the arguments the model sent;
• every call gets exactly one result: calls left unanswered are skipped when the strategy asks the model again or when the turn ends;
• budgets, the tool-call limit and the progress guard (the same call four times in a row, a denied call retried three times, ten failures in a row, one tool failing on one file in six of the last sixteen responses, a background command still running read thirty times in a row) end the turn with an error no guard clause can catch (§4), and so does a failure to write the log, which is the source of truth. In sandbox mode the same call four times in a row does not end the turn: the fourth result, and every fourth after it, tells the model so after the tool's output (a fold-result of it keeps that note after its text; the value the strategy reads is the tool's own), and the log has a note beginning "progress warning:" (ADR 55, amended 2026-10-19).

9.1 Prompts

Every prompt nodwyn sends is Scheme. The defaults live in internal/loop/prompts.scm, which loads with the default strategy, before .nodwyn/init.scm; a project redefines any of them there, usually with raw strings (§1.1):

| plan-explore-system, (plan-explore-task request), (plan-draft-with-findings request findings) | the explorer that looks before a plan is drafted (§9.5): the code at the place the request describes first, every place the change must reach (each cited as path:line), the request's own examples and formats copied exactly, the options it finds without choosing one, the tests involved, and the documents and what the repository's instructions for coding agents (AGENTS.md) ask a change to include; and the draft request that carries what it found | | finish-no-change-message, finish-no-change-reviewed-message, finish-untested-message, finish-failing-message, (finish-unrunnable-message n), (finish-new-files-message files), (finish-untested-parts-message check parts omitted), (finish-stale-citations-message spans), (finish-removed-definitions-message defs), (finish-removed-expectations-message lines), (finish-original-tests-message failures), (finish-regressed-tests-message names), (finish-dropped-conditions-message dropped), (finish-unshown-claims-message claims), (finish-unsupported-edits-message rows original), (finish-review-message points), finish-review-close | what the evidence loop tells the model (§9); from finish-new-files-message on, points of the finish review, and the one message that carries them | | (reading-reminder-message n), (reading-reminder-reviewed-message n) | what the default loop tells a model whose last n rounds only looked (§9) | | (plan-findings-message findings) | what the model doing the work is told of the explorer's findings once a plan is recorded (§9.5): leads found without running anything, and any fix in them a guess to test; plan-hand-over adds the lines of the files they cite (plan-excerpts, below) | | task-header plan-header | the headers under which the window shows the user's request, at the head of their message, and its plan, as a message of its own after the calls it came with are answered; neither is ever trimmed away. The system prompt stays the same, so a new request or a plan keeps the server's cached prefix (window recipe v15); before v15 the system prompt carried both | | (run-turn-prompt task complete-line turn max-turns) | the message a supervised run sends for each turn; complete-line is the marker the run looks for. It asks for the plan's next unmarked step and says the plan carries over to the next turn (§9.5); under lean-plan-hidden it says nothing of a plan | | (plan-system-prompt repo) | the planner's system prompt | | (plan-shape) | the shape every plan is asked for, built from plan-kinds (§9.5): each step starts with its kind and a short name for what it does, then — and the detail the console folds away; a step that says all it should in its name needs no dash; the last is the Check:; a plan with no test or no doc to change says so, and why, in a step (Test: none — only docs change); a step carries only what the request states, behaviour it does not state goes on an unnumbered line after the steps, Assumptions: ..., checked against the existing tests before a step relies on it, and for each rule the request states the cases are listed by clause and, for a range, an overlap or an edge, by position (inside, crossing the start, crossing the end, equal, empty). With the plan language (planspec.scm) the planner writes forms, and (assumes "behaviour" "what it was checked against") is that line, written out after the steps as one unnumbered line (ADR 32, amended 2026-10-16) | | (plan-draft-prompt request) | the planner's request for a plan, in the shape (plan-shape) gives | | (plan-revise-prompt request plan score) | the request for a better plan after the judge scored it score (0..1), with the shape again: the planner revises in a context of its own | | plan-needed-question | the judge's yes/no question: does this request need a plan? A plan is a plan of changes: a question, a review, a comparison, an explanation or a proposal asks for an answer and needs none, however much reading the answer takes; a reply to the model's question or a correction carries on the request before it | | (plan-request-with-earlier earlier request) | a chat's latest request after the person's messages before it, earlier, as the gate's judge, explorer and planner read it (plan-chat-request) | | (plan-request-after-reply reply), (plan-request-attachments files) | what the explorer and the planner read beside that, never the judge (plan-model-request): the agent's last answer before it, and the names of the files the person attached, with the instruction to say what they cannot tell rather than guess | | compact-summary-prompt, (compact-handover-prompt request note) | compaction's request for a handover note and the start of the compacted context (§9.2) | | (optimizer-system-prompt), (optimizer-task history focus) | the optimizer's system prompt and task (§9.4) | | plan-score-rubric | the judge's instruction for scoring a plan: it fulfils the request, and its steps have the shape the planner is asked for | | plan-score-levels | the rubric's 2–10 levels, worst first. A plan whose tests do not say what they check and why they fail today, or that leaves out the docs, does not reach the top one | | working-rules | how to work, added to both system prompts (§9.6): shell command lines, programs that keep running or may hang (shell-start), the project's environment, reading with the file tools, calls that do not depend on each other in one reply, a plan as a first guess, the check loop, following the request's conclusion, widening in general form, whole test modules (and code a browser runs checked by the project's browser checks; a build or a syntax check is not a check that it works), comparing failures with the unchanged code only when tests fail, on a copy of the last commit and never with git stash, finding regressions file by file, keeping what a later session would need in the project notes (project-notes-save) | | (git-rule) | in both system prompts after working-rules, only where git-diff is offered: look at the change with git-status and git-diff before finishing; it holds nothing it does not use | | (worktree-section) | in both system prompts after (git-rule), only in a session given a git worktree of its own ((worktree) is not #f, ADR 34): the folder is a worktree made for the session, on its branch, from its base, of the repository at its path; other sessions may work in other worktrees of it at the same time, so work only here and leave other branches alone; the changes reach the repository only through the branch, which the answer names; before landing it says to run validate first, only where the session has a tool of that name (nodwyn's own repository does, most do not). It also says never to use git stash there, since every worktree shares one stash, and to compare with the unchanged code on a copy of the last commit (git archive HEAD \| tar -x -C "$TMPDIR/base") instead. "" in any other session, so their prompts are unchanged (ADR 32, amended 2026-10-03) | | (project-instructions-section) | in both system prompts after the workspace's folders and before the project notes, and at the end of the lean one, after its fixed sentences (§9.8; ADR 32, amended 2026-10-18): the repository's AGENTS.md under a heading that says to follow it where it applies and the request where they differ, or "" without one. Read when the session starts, so an edit to the file shows in the next session (ADR 36) |

(define base-system-prompt system-prompt)      ; keep the default to extend it
(define (system-prompt repo)
  (string-append (base-system-prompt repo) "\n"
    """
    Work unattended: nobody approves your calls.
    Run the tests of every module you change before you finish.
    """))

nodwyn reads the system prompt and the two headers once, after init.scm has run: they are then fixed for the session like the tool list (ADR 9), and recorded with the window's recipe so a replay rebuilds requests that used a project's own. A system prompt that is not a procedure returning a non-empty string, or a header that is not a non-empty string, stops the session from starting. The others are ordinary Scheme, read when the plan gate (§9.5) uses them, so a (reload) changes them from the next turn.

9.2 Compaction

A long turn fills the context with tool results the model no longer needs. nodwyn elides the oldest ones past [window] high_water on its own; compaction goes further, as user code over the primitives above, in internal/loop/compact.scm. When the context passes compact-threshold, measured as the window measures it ((context-tokens), not a reply's prompt-tokens, which a server counts its own way and which lacks the latest tool results), maybe-compact asks the model for a handover note (the task and its example as given, what it found with the evidence for each finding, what it changed, how to test, what is unsure or left, and its check script), then narrows the context to the session's system prompt, the request and that note, and gives the turn's plan back after the note, under plan-header with the steps marked so far (compact-plan), since the window shows a plan where it was recorded, which the narrowing leaves behind. The narrowing lasts (narrow-context with '((lasting . #t)), labelled compaction): the rest of the turn goes on from the note, and so do later turns, each under the session's system prompt with its own request, rather than from the whole conversation again. The repository keeps the model's changes, and the log keeps the whole conversation, as context.narrow with lasting and the note before it, so replay and audit see everything the note replaced. The note request may use the room between the window's high water and its ceiling, so a round that jumps past the high water is still compacted rather than trimmed; a context no bigger than the window has no such room.

The user compacts whenever they like, whatever the context's size, with a message; it works in every client, like /optimize (§9.4):

/compact                     compact now
/compact the failing tests   any words after it are what the note must keep

The default agent-turn runs compact-turn for it instead of the loop. It hands over the user's latest request before it, not counting other /compacts (session-requests), so a note written between turns keeps the task that was being worked on; the words after /compact are added to the note request with compact-focus-prompt. The turn ends once the note is handed over: the model is not asked to go on, so it does not start on what the note says is left, and the user's next message goes on from the note. A session with no request before the /compact has nothing to compact, and the model is not asked. Each outcome is a note in the log, which the clients show.

Every compaction, whatever set it off and whether it worked, is recorded as context.compact (record-compaction): the trigger (auto, command for /compact, requested for compact-next-round), whether it compacted, the context's size before and after in the window's estimated tokens, the threshold an automatic one passed, the focus, and the handover note's reply (its llm.resp seq, its length in tokens, and whether it stopped at the output limit). The clients show it as one line, such as compacted (past ~58,983 tokens): context ~59,210 → ~4,100 tokens, and one that gave up as a warning.

A strategy asks for compaction at the next round, whatever the size, with (compact-next-round [focus]): maybe-compact runs it where the loop next calls it, in this turn or the next, and the request is used once.

(define compact-threshold 40000)    ; in .nodwyn/init.scm

A strategy that redefines agent-turn calls maybe-compact itself, where the default does: after running the calls, before the next model-turn; it keeps /compact by calling (compact-turn request) when (compact-request? request). Compacting rewrites the start of the context, so the server re-reads the new, short prompt once instead of reusing its cache (ADR 9); a late threshold compacts rarely and keeps the prefix stable in between. A note that the model will not write (it keeps calling tools, or writes nothing) leaves the context as it was, and the model is told to go on.

9.3 Sub-agents

A sub-agent is a model loop in a context of its own: it gets a system prompt and a task, works with the tools it is given, and answers; the context then folds away, so whoever asked sees only the answer (ADR 27). They are user code, in internal/loop/agents.scm:

;; .nodwyn/init.scm: a reviewer the model can consult, reading but not writing
(define-agent-tool "ask-reviewer"
  "Ask a reviewer who can read the repository whether a change is finished."
  '(("change" "string" "what you changed and why, and how you tested it"))
  (lambda (call args)
    (sub-agent "You are a strict code reviewer. Read what you need, then reply VERDICT: done, or what is missing."
               (assoc-ref args "change")
               '("fs-read" "fs-list" "index-grep"))))

Every sub-agent leaves its whole transcript in the session log: its context.narrow names the agent and lists the model's calls it answers, then come its task, requests, replies, tool calls and guard decisions, up to its context.fold; the calls it answered follow as tool.result. Folding hides the span from later windows, never from the log, so an agent's work can be read, replayed (nodwyn replay --window) and learned from on its own.

A strategy can also run one itself, such as a review when the model stops: (sub-agent reviewer-system (string-append issue diff tests) '()). A sub-agent always asks the control model (whichever model its caller was routed to); a strategy that wants another writes its own loop with (model-turn name). Each fold costs the server one re-read of the caller's context: the prefix it had cached was the sub-agent's (ADR 9).

9.4 History, reload and the optimizer

A strategy can read this repository's past sessions and change how nodwyn works here, while the session runs:

The optimizer (internal/loop/optimize.scm) is user code over these. The user starts it with a message; the default agent-turn runs it instead of the loop:

/optimize                 every earlier session of this repository
/optimize 5               the latest five
/optimize ID ID ...       the sessions named (ids from session-list)
/optimize 5 test runs     any other words are a focus

It digests the sessions (requests, answers, the calls made, failures and refusals, judges' verdicts, sub-agents, notes) within optimize-session-chars per session and optimize-total-chars in all, and hands them to a sub-agent labelled optimizer. That agent may read the repository and write only under .nodwyn/, a protected path, so every write asks the user and shows the diff; a session nobody approves (nodwyn run's --yolo or --judge, an unattended run) refuses those writes, so /optimize needs a person at the prompt. A changed project init is kept pending review with nodwyn trust; the new code has not run. Once trusted, reload or resume to use it. For an explicitly authorised init, reload still applies immediately; an ordinary reload failure restores the old file. The model is told which outcome occurred. Its prompts are (optimizer-system-prompt) and (optimizer-task history focus), in prompts.scm with the others. A strategy that redefines agent-turn keeps /optimize by calling (optimize-turn request) when (optimize-request? request).

9.5 The plan gate

The plan gate is user code too, internal/loop/plan.scm. The host runs nodwyn-turn for every user message, not agent-turn directly:

(define (nodwyn-turn request)
  (when (plan-required?) (plan-gate request))   ; a supervised run's turns
  (agent-turn request))

and the default agent-turn calls (plan-gate request) before its loop, so an interactive turn is gated too. plan-gate does nothing once the turn has a plan, so a strategy may call it as well; a strategy that redefines agent-turn still plans in a run. A project that plans its own way redefines nodwyn-turn (a name specific to nodwyn, so a project's own turn, a counter say, cannot shadow it): the example above is the whole of the default, since the per-turn resets live in turn-start (§9). With a judge (§5: [judge] on a provider, its primitives registered and its server's key stored), it asks plan-needed-question about the request, in a chat's later turn after the person's messages before it (plan-chat-request); a request that needs a plan gets one drafted by the control model in a narrowed context of its own (§9), which also reads the agent's last answer and the names of the files attached (plan-model-request), offered no tools and folded away afterwards, then scored against the request and revised until it scores plan-accept-score or plan-max-revisions run out. The outcome is recorded as gate.plan, and the window shows the plan to the model for the rest of the turn. Without a judge there is no gate. If the judge's yes/no question fails, the model plans anyway, unscored ("degraded"); a judge the guard refuses (an unbound key) ends the turn, as any denial does.

A run's plan is the run's, not the turn's. Its first turn drafts the plan; each later turn carries it (plan-carry): it records the same plan again, decision carried, with the steps the run's turns have marked, so the steps keep their numbers, plan-step answers with the right next step, and the window shows the marks under the plan. Nothing is explored, drafted or scored for a carried plan. Only when every step is marked and the run goes on does a turn draft a new one, from the request with the previous plan and how each step went (plan-run-request). A model that finds the plan wrong marks the steps that no longer apply skipped, saying why.

A chat's plan is carried the same way past a turn that did not finish. When an error, a limit or the person's Stop ended the turn, the next message ("continue", or a correction) carries its plan with the steps marked so far (unfinished-plan, then plan-carry), so the model goes on from the next unmarked step instead of reading the repository again and writing the plan again. A turn that finished, its answer given, leaves no plan: the next message is a new request, gated as usual.

Every plan, the planner's and the model's own, is asked for in one shape (ADR 32, amended 2026-10-03): numbered steps, each starting with its kind and a short name for what it does, then a dash (—) and the detail after it; a step that says all it should in its name needs no dash. Change: names a file (or function) and what changes in it; Test: the test file and name, the behaviour it checks and why it fails on the unchanged code ("fails today: …"), or that it guards behaviour that already works ("passes today: guards …"); Docs: each file a person or a later session reads that the change makes wrong or incomplete; and the last step, Check:, the command that shows the whole change works. A plan with no test or no doc to change says so in a step, with the reason. The judge scores against the shape, and plan-write turns down a plan without it.

A turn that must plan (plan-required?) always drafts one, scored if there is a judge, and fails if the plan is empty. The core keeps one invariant whatever the Scheme does: until a non-empty plan is recorded, nothing irreversible runs, and a turn that records none fails. What it enforces is that a plan was recorded, not who wrote it: the default nodwyn-turn has the control model plan, and a project's own nodwyn-turn may record a plan of its own with record-plan, as trusted project code.

Judged approval. When the judge answers a session's confirms (nodwyn run --judge), the decision is Go's (internal/core/judge.go): it shows the judge the task, the turn's plan and the call, asks judge-choice whether to allow it, and allows it only at judge.approve_threshold (config) or above. Scheme cannot approve anything; it may refuse more:

The model marks each of the plan's steps as its work is done, before the next (plan-step), and the console's plan panel shows which are done, which were skipped and which is next. A strategy that does not use run-calls (where agent tools are answered) leaves plan-step unanswered; its own handler may call record-step.

9.6 Working habits

Beside the prompts' working-rules, the default loop carries the habits that held up on a coding benchmark (ADR 32), as user code in internal/loop/, loaded after the files above in this order. Each wraps run-calls (and fold-result, sub-agent, model-turn or nodwyn-turn where it says), so a project's init.scm can wrap them again or redefine them away.

• shell.scm: a command line sent through shell-exec's cmd/args (a program with its arguments in cmd, shell operators such as | or && in args) is answered, unrun, with the bash -c call that runs it as meant; shell results read as plain text, the exit status then the output, long output keeping its start and its end (shell-head-chars, shell-tail-chars), and, with lean-prompt on, the result's note (exit 141 after a head; a read that printed nothing) on a line of its own after the output, [note] …, which this text left out until 2026-10-17; and (ran-ok? result) counts a test run with failures as a run, so the evidence loop's way out is offered only for commands that never got that far.
• hygiene.scm: in the main context (not in sub-agents), a test command that never ran a test is folded to one line once a later one does (a command ran tests when it exited 0 or its output says so in a runner's words, hygiene-ran-words: pytest's, Go's ok, --- PASS/--- FAIL and === RUN, mocha's, jest's, node's, cargo's, and a repository validate's summary; a Go package that did not build ran none); a read of a file edited since is folded to its outline after hygiene-stale-age rounds; a read hygiene-age rounds old is folded to its outline; neither folds a read of a file edited in the last hygiene-editing-rounds (4) rounds, the file being worked on. Reads fold in batches of at least hygiene-min-bytes, and only when the fold pays for the prompt cache it costs: a fold makes a caching server read everything after the first folded read again, at the full input price. So a batch folds when it is at least as large as the rest of the window after it ((context-tokens result)), when the provider's cache is not serving the context anyway (it read less than hygiene-cache-share, a quarter, of the last hygiene-cache-requests prompts; a provider that does not say, such as an older Ollama server, counts as serving it), or when the context is past hygiene-pressure (three quarters) of the high water. The log note of each fold says which. A read (hygiene-keep? r) holds, which the plan language says of a file its plan will change and the turn has not edited, is left out of the batch until the context is past hygiene-keep-pressure (three quarters too): below it the held read stays and the others fold only when it pays, past it every due read folds in one sweep. Were hygiene-pressure above it, a held read would lose its hold before the others fold whatever the cache. It wraps sub-agent, to watch the main context only, and model-turn, to read the cache counts of its requests.
• readdef.scm: the tool read-definition (path, name) reads a function, method or class by name, its whole definition and line range, or the start and members of a long class; a shell script that only reads a file to print it gets a hint naming the file tools, readdef-hints times a session.
• envhint.scm: a command that fails for a missing module gets a hint to find the project's own environment, envhint-hints times a session (never under lean-no-envhint, the lean profile's).
• checkloop.scm: the tool second-look (check, saw): when the model's check script does not show the problem a request reports, one read-only helper reads the request alone and another compares that reading with the check, listing what may have been read differently. A history search (git log, git blame) before any code edit gets a hint to use it, second-look-hints times a session.

9.7 Per-model tuning

A round is one reply's calls, and models batch calls into rounds very differently (in the local session logs, gpt-6.1-sol made 2.75 calls a round and glm-5.3-flash 1.22), so a limit counted in rounds is a different amount of work for each. A knob that depends on the model is a number, which holds for every model, or a table: rows of (family . value) and a (default . value) row.

(define plan-explore-rounds
  '(("muse-spark" . 16) ("glm" . 16) ("qwen" . 8) ("deepseek" . 16) ("gpt-6-luna" . 16) (default . 12)))
(define reading-reminder-after '((default . 12)))

A narrower family goes before a broader one, since the first row that fits wins. The knobs that are tables are plan-explore-rounds (§9.5) and reading-reminder-after (§9.6); a project that redefines either as a number keeps that number for every model, and 0 still turns it off. The rows shipped come from the logs and say so in their comments (ADR 32, amended 2026-10-05): gpt-6.1-sol and claude-sonnet have none and take the default, and the reminder's table has only a default row. qwen's explorer row is 8 since commit-bench showed it using all 16 rounds in 39 of 48 runs, with the work reading again about half of what it read (amended 2026-10-15).

9.8 The profile: lean and full

The default loop comes in two profiles (ADR 32, amended 2026-10-17). Lean is the loop measured on the 121 clean SWE-bench Verified tasks, and it is what a session nobody approves runs: a system prompt of about 90 tokens (lean-system-prompt: who and where, unattended, one phrase per tool of lean-tools, throwaway files in $TMPDIR or /tmp, one sentence on the work and one on the answer, then the repository's AGENTS.md when it has one, by (project-instructions-section), but not the project notes; in sandbox mode, (sandbox?), it names the folder without calling it a repository, says the machine is a disposable sandbox whose every file is the model's to read, change, install or run, and that relative paths are relative to the folder); the control model offered shell-exec and fs-edit alone (lean-tools); a run's plan the one line plan-minimal-text, with no explorer, planner or judge (plan-minimal), recorded hidden, so the model is shown no plan and the run's turn prompt does not speak of one (lean-plan-hidden); and nothing said to the model while it works or as it ends (lean-quiet): no finish review, no finish reminders, no question on an edited test, no hint on failures the unchanged code has, no reading reminder (lean-no-read-reminder) and no environment hint (lean-no-envhint); a sandbox session's finish check (sandbox-finish-message, §9) is still said. A turn that changed nothing is told so once (lean-empty-reminders), in the words of finish-no-change-lean-message, and a shell-exec call that only reads (grep, sed -n, cat) counts toward the rounds that only look (lean-shell-look). Below the loop the lean session's tools differ too (§5): it registers scheme, outline and tests-for (the control model is offered them only when lean-tools names them), gives fs-read its symbol parameter, and answers an edit with the lines it added and removed, a write with the lines it wrote, and a search of a tree of more than 3000 files with the source files alone; its shell-exec and fs-edit say less and do more (§5), and a lean session nobody approves may write to and read from /tmp as from its scratch directory (prim.Options.Temp), a path outside the repository, $TMPDIR and /tmp then being refused with a message that says nothing ran. Full is the loop before that: the interactive or unattended prompt, every tool as it was, an explorer and a planner for a run, the finish review.

[loop] profile in config.toml chooses: "lean", "full", or "auto", the default. auto is lean when nobody approves the session's calls ((unattended?): --yolo, a run's auto_approve, judge or unattended) and full when a person does, since the lean prompt says nobody is watching and the lean loop was measured only on runs nobody watched. The environment variable NODWYN_PROFILE, when it is not empty, overrides the configuration for the sessions created in that environment (a test, or one run); a value that is not auto, lean or full stops the session from starting. The profile is fixed with the session, as the prompt and the tools are (ADR 9), and a resumed session resolves it again.

The lean profile is what plan.scm, prompts.scm and strategy.scm define. The full profile evaluates internal/loop/full.scm after them, as the host evaluates the defaults and before .nodwyn/init.scm, so a project's init.scm still has the last word under either. It is exactly these definitions:

(define lean-prompt #f)           ; the interactive or unattended prompt; every tool
(define plan-minimal #f)          ; a run's plan goes through the explorer and the planner
(define lean-quiet #f)            ; the finish review, the reminders and the hints
(define finish-reminders 2)       ; computed from lean-quiet when strategy.scm loads, so set again
(define finish-review-limit 2)    ; (0 when lean-quiet is true)
(define lean-empty-reminders 0)   ; (1 when lean-quiet is true)
(define lean-shell-look #f)       ; only the read tools count toward the reading nudge
(define lean-plan-hidden #f)      ; the model is shown the plan it has
(define lean-no-read-reminder #f) ; twelve rounds that only read get the reading reminder
(define lean-no-envhint #f)       ; a missing module gets the environment hint

A project mixes the two by redefining these names in init.scm, after the profile: (define lean-prompt #t) in a session a person approves gives it the lean prompt and tools; (define lean-tools (append lean-tools '("fs-read"))) adds a tool to the lean loop, and its prompt then says the model can read files; (define plan-minimal #f) brings the explorer and the planner back to a lean run. Under lean-quiet the finish review of a turn a person reads ((reviewed?): a chat's turn) is still made, as in the full profile. What the full profile does not undo, because it is an improvement in both: the finish review reads a run's output in any language and runs the original tests of the test files the turn edited whatever their language (original-tests), tests that a failed run shows failing and the last commit passes (finish-regressed-tests-message), a plan's run matched by what it runs (plan-language-ran?), a task template's fields left out of the names a plan must hold, repo-relative?, the guard's refusal of a path under /tmp saying the scratch directory's own path, and fs-edit's errors that say where an old that occurs twice occurs and where one that almost matches stops.

10. Not in nodwyn Scheme

Deliberately absent.

• characters and the full string-port API (only with-output-to-string)
• source positions in runtime errors (reader errors carry positions)
• define-macro — the prelude does not need it (ADR 7)
• set-car! / set-cdr! and string mutation
• nested quasiquote
• hygienic macros (define-syntax, syntax-rules)
• call/cc, dynamic-wind
• an eval primitive — the kernel surface is not exposed to programs
• exact rationals and bignums

Project authority (ADR 45)

The repository supplies init.scm and allow.toml; their presence is not a grant. Use nodwyn trust --repo PATH and accept its displayed revision before ordinary sessions load them. The user-owned registry is outside the project. The exact checked init bytes run with user origin and the guard still applies; standing approvals can permit actions during startup. Review transitive Scheme and scripts too, since their contents are not part of the two-file revision. A change to either authority file, including creating or removing it, needs review again. See Security boundaries for revocation, worktrees and HTTP choices.