toolang 0.3.2__tar.gz → 0.3.4__tar.gz

{toolang-0.3.2 → toolang-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: toolang
-Version: 0.3.2
+Version: 0.3.4
 Summary: A programming language and runtime for agents
 Project-URL: Homepage, https://toolang.ai/
 Project-URL: Documentation, https://toolang.ai/docs

{toolang-0.3.2 → toolang-0.3.4}/docs/agent-state.md

@@ -4,9 +4,9 @@ Agent State is the immutable runtime input derived from an agent's Programs,
 configuration, and capabilities. A module is a term for one named, sourced
 Program in State; it is not a separate runtime type. Agent State holds the
 complete module-name-to-Program index rather than a separate primary Program.
-It combines one root layer with one home layer. A top-level run starts with one
-Agent State revision. An explicit executor reload can change the State used by
-later step boundaries in that run tree without changing already-started work.
+It combines one root layer with one home layer. Each accepted Run keeps one
+Agent State revision. New named children select the latest valid publication
+independently; inline bodies retain their containing plan.
 
 Tasks and chores stored as independent Markdown files are work data, not Agent
 State. Task and chore declarations inside `agent.too` are part of State because
@@ -227,19 +227,15 @@ current-agent `me` tools.
 
 ## Execution Records
 
-Root `run` and `rerun` controls store the initial Agent State revision. A
-process-local `reload` control stores a replacement revision. Every run and
-physical step stores a `ControlRef` named `state` that identifies the control
-which introduced the exact State it used. New child-run and retry controls do
-not duplicate the revision; their run record is authoritative.
+Every Run entry stores its accepted Agent State revision, including named and
+inline children. Run and Step records carry a `ControlRef` named `state` pointing
+to that entry or an explicit execute transfer. Retry retains its existing
+entry reference.
 
-The executor holds the corresponding immutable `AgentState` object with that
-reference. Reload application and `StepBegin` share one root-tree lock, so a
-started step keeps its captured State and the next boundary uses the reload.
-A child run inherits the State captured by its calling step. Watcher
-publication alone never reloads an active run.
+The executor retains immutable State for active bindings and loads historical
+revisions from durable snapshots. Watcher publication affects future named
+acceptance and model catalogs, without changing accepted code or caps.
 
 Model/provider continuation is a different value and is named `cont` in model
 calls, model results, model step records, and runtime agic state. The runs
-database migrates version 28 model-step continuation keys from `state` to
-`cont` without modifying preparation-control Agent State fields.
+database accepts schema version 49 and rejects unsupported versions at open.

{toolang-0.3.2 → toolang-0.3.4}/docs/api.md

@@ -448,15 +448,48 @@ Every successful query selects one projector after its subject resolves:
 | `records` | collection subject | summarized record rows | canonical record array |
 | `fields` | browsable Pointer value | direct child fields | exact selected value |
 | `value` | scalar, empty, resolved, or specialized value | rendered value | exact selected value |
+| `output` | Run with the explicit terminal name | complete result body | resolved result value |
 | `tree` | Run with the explicit terminal name | hierarchical durable execution | flat depth-first node array |
 | `call` | supported Step with the explicit terminal name | Step-owned historical call | normalized call or flat node array |
 
 `records`, `fields`, and `value` are implicit view kinds, not accepted command
-tokens. `tree` is explicit only on a whole Run. `call` is explicit only on a
-whole model, tool, run, par, or loop Step. Run and Step subjects never expose
+tokens. `tree` and `output` are explicit only on a whole Run. `call` is explicit
+only on a whole model, tool, run, par, or loop Step. Run and Step subjects never expose
 equivalent projector names, and the removed `model-call` spelling is not an
 alias.
 
+Read a Run's result with `output` (`too` is an alias for `toolang`):
+
+```sh
+too SCRIPT inspect run_ab12 output
+too SCRIPT inspect run_ab12 output | rich -m
+too SCRIPT inspect run_ab12 output | jq '.'
+too SCRIPT inspect run_ab12 output --json
+```
+
+`output` resolves stored references and removes the `Output` / `Local` wrappers.
+The default view writes Text unchanged and concatenates TextPart bodies in
+order for textual Parts. It preserves whitespace and Markdown source, adding
+only a final newline when nonempty text lacks one. Empty text and empty Parts
+emit no body. Structured values and nontext Parts emit complete indented JSON.
+The view does not render Markdown, add colors, wrap, or truncate content; use
+external tools such as `rich` or `jq` to present it. The `jq` example requires
+structured output or text that itself contains valid JSON.
+
+Textual Parts omit reasoning and nontext content from the default text view.
+The existing `--json` flag preserves every resolved Part and nested value;
+Text becomes a JSON string with its original whitespace. A JSON-looking Text
+value remains text and is never parsed to infer a type. `--human` and `--json`
+remain mutually exclusive; no new formatting flags are added. Output behavior
+is the same in a terminal and a pipe, including when `FORCE_COLOR` is set.
+
+A Run without an output fails with its ID and status instead of returning a
+blank success or waiting for completion. Present null and empty outputs succeed.
+Use `inspect RUN/output` to inspect the output wrapper, or
+`inspect RUN/output/local/value --json` for the raw stored value, including
+unresolved references. Existing Pointer queries retain their original behavior.
+The `output` projector is available only for whole Runs, not Steps or collections.
+
 `call` on a model Step reconstructs the complete normalized call persisted for
 that Step, including instructions, messages, tool definitions, the
 structured-output schema, and continuation data:
@@ -541,10 +574,11 @@ selected value retains normal Pointer resolution and validation.
 Human projections have no trailing context footer. Direct scalar and
 specialized values print only their value. Strings have no JSON quotes, and
 nullable Human type labels use `T?`. Multiline Part content stays aligned
-inside the VALUE cell without a leading bullet. `--json` does not resolve
-Pointers and prints only the selected canonical JSON value. The two display
-modes are mutually exclusive, and `--type` is not an option. Inspection is
-read-only and historical and does not load a runnable.
+inside the VALUE cell without a leading bullet. Pointer queries with `--json`
+do not resolve Pointers and print only the selected canonical JSON value. The
+explicit Run `output` view instead returns the resolved result as described
+above. Display modes are mutually exclusive, and `--type` is not an option.
+Inspection is read-only and historical and does not load a runnable.
 
 ## Runtime Commands
 
@@ -1080,7 +1114,7 @@ State publication. PUT responses read the exact published root/home layer,
 including a cap shadowed by a higher scope or excluded by runtime allow policy.
 DELETE responses wait for publication too. If the source change is saved but
 State rejects the candidate, HTTP 409 reports that distinction; the last valid
-State remains active. Publication does not apply a reload to an existing run.
+State remains active. Publication does not rebind an existing run.
 
 Delete routes accept `scope=home|root` as a query parameter. Cap read
 items include:
@@ -1514,7 +1548,7 @@ the Part; signatures can also occur on normal text and tool-call Parts. Signatur
 fragments are not separate events. Deltas are live only; completed Parts are
 durable and available through existing output/inspection endpoints.
 
-The Part format requires execution-store schema **48**. Opening an incompatible
+The Part format requires execution-store schema **49**. Opening an incompatible
 store fails without modifying it; no migration or reset is performed. See the
 [model adapter contract](plugins.md#model-adapter) for the required indexed
 stream interface. Human output continues to omit reasoning and native fields.

{toolang-0.3.2 → toolang-0.3.4}/docs/execution-presentation.md

@@ -53,12 +53,41 @@ Script and Chat use the same projected ownership, content, aggregates, facts,
 and errors. Their presenters own terminal mechanics such as wrapping, lane
 truncation, scrollback, and live-area replacement.
 
-A Run has no standalone progress header. A root Run contains projected Steps
-followed by one footer. Child Runs are represented through the Steps they
+The shared projector emits no standalone Run header. Script adds the root
+context header described below; Chat retains its existing run control bar.
+A root Run contains projected Steps followed by one footer. Child Runs are represented through the Steps they
 execute rather than separate Run headers or closure rows. A model-produced
 dynamic Run Step owns its own opening and closing divider around that child
 content.
 
+## Script Run Context
+
+Script prints one persistent context header to stderr when the root Run begins:
+
+```text
+‣ agic:review                  deepseek/deepseek-chat · auto
+```
+
+The entire header is dim on the terminal's default background. `‣` marks the
+start, with the runnable at the left edge and model/reasoning at the right edge
+of the configured progress width, separated by at least two spaces. Narrow
+layouts put model/reasoning below the runnable, with two-cell indentation;
+long fields wrap without truncation. A one- or two-cell viewport drops the
+marker and indentation. Terminal controls are escaped as literal text.
+
+The runnable uses the resolved root identity, displaying an unnamed entry as
+`agic:_` or `flow:_`. The model is the resolved initial run-level setting;
+Flow steps and child Runs may select other models. Reasoning shows an explicit
+effort or token budget, or `auto` when unspecified. A missing model request
+shows `model unspecified` with no reasoning field.
+
+The header appears once, before Step output, separated by one blank line. It
+remains in scrollback after success, failure, or cancellation. Preparation and
+submission failures before `RunBegin` produce no header. Nested Runs do not
+repeat it. Non-TTY output retains the layout without ANSI; `-q` suppresses it.
+Result saving, stdout, and the existing root footer are unchanged. Chat TUI
+does not display this Script header.
+
 ## Width and Alignment
 
 Progress is at most 120 terminal cells wide by default and never wider than an
@@ -146,7 +175,7 @@ publication and adoption complete.
 ## Markers and Style
 
 `•` marks Model and Flow Steps; `›` marks ordinary tools; `✧` marks the `pick`,
-`reload`, `compact`, and `honor` runtime helpers. `---  ` opens and closes a
+`compact` and `honor` runtime helpers. `---  ` opens and closes a
 dynamic Run Step, and `∎` marks the root Run footer. The centered dot `·` is only
 an inline facts separator.
 
@@ -620,43 +649,54 @@ scrollback and retaining only replaceable fragments in its live container.
 
 Model and result Markdown leaves ordinary text on the terminal's default
 foreground and background. Semantic styles use named ANSI colors, so the
-terminal theme owns their actual RGB values. Inline code uses bold ANSI cyan
-text on the terminal's default background, distinguishing it from ordinary bold
-text without isolated background spans around short identifiers.
-In Script, fenced code uses ANSI slot 15 text on an ANSI slot 8 background with
-Rich's `ansi_dark` token palette. In interactive Chat, its base text inherits
-the terminal foreground and its background uses Code. Both paths retain the
-named ANSI syntax-token colors. Top and bottom padding, trailing background
-cells, and authored blank lines remain one rectangular surface.
+terminal theme owns their actual RGB values. Inline code retains Rich's
+Markdown text style (bold ANSI cyan by default) with an explicit background.
+Both Chat and Script derive a stronger inline background from the terminal
+background. Inline spans add no padding. In both modes, fenced-code base text
+inherits the terminal foreground and its background uses Code. Both retain
+Rich's `ansi_dark` named ANSI syntax-token colors. Top and bottom padding,
+trailing background cells, and authored blank lines remain one rectangular
+surface.
 
 Chat preserves terminal-default and 16-color ANSI identities through both its
-live prompt_toolkit path and stable scrollback path. Script uses the same
-identities on a TTY and continues to emit no color for non-TTY output.
+live prompt_toolkit path and stable scrollback path. Script uses the same ANSI
+identities and truecolor background fills on a TTY and continues to emit no
+color for non-TTY output.
 
 Interactive Chat resolves one concrete palette before prompt_toolkit begins
-reading keyboard input. The public backgrounds are Input, Queue, and Code, in
-that order. Input fills the input box and the non-accent cells of Run, Steer,
-and Quick Command bars. Queue fills the adjacent queue area; a focused queue
-selection uses Input. Code fills fenced-code rectangles. These surfaces assign
-no ordinary foreground: normal text inherits the terminal
-foreground, dim text adds only the dim attribute, and the input cursor uses
-reverse video.
+reading keyboard input. Script resolves the same palette before starting run
+output, including remote execution and retry/rerun. The public backgrounds are
+Input, Queue, and Code, in that order. Input fills the input box and the non-
+accent cells of Run, Steer, and Quick Command bars. Queue fills the adjacent
+queue area; a focused queue selection uses Input. Code fills fenced-code
+rectangles; inline code has a separate derived background. These surfaces
+assign no ordinary foreground: normal text inherits the terminal foreground,
+dim text adds only the dim attribute, and the input cursor uses reverse video.
 
 `TOOLANG_COLOR_SCHEME` accepts case-insensitive `dark` or `light`, or exactly
 three comma-separated `#RRGGBB` values in `input,queue,code` order. An explicit
-value is final and bypasses terminal discovery. Without one, Chat requests the
-terminal's default foreground and background through bounded OSC 10 and 11
-queries when stdin and stdout are the same TTY and no input is pending. A
-complete response derives subtle surfaces from those defaults; unsupported,
-incomplete, or failed queries always use the dark palette. `COLORFGBG` is not
-consulted. Script and non-interactive Chat never probe.
+value is final and bypasses terminal discovery. With three explicit colors, the
+third color fills both fenced and inline code. Without one, both modes request
+the terminal's default foreground and background through bounded OSC 10 and 11
+queries when stdin and the output stream (stdout for Chat, stderr for Script)
+are the same TTY and no input is pending. A complete response derives subtle
+surfaces from those defaults; unsupported, incomplete, or failed queries always
+use the dark palette. `COLORFGBG` is not consulted. Quiet Script execution and
+non-TTY output never probe; non-interactive Chat does not probe either.
 
 The fixed palettes are:
 
-| Scheme | Input | Queue | Code |
-| --- | --- | --- | --- |
-| Dark | `#1f1f1f` | `#121212` | `#0b0b0b` |
-| Light | `#e3e3e3` | `#f2f2f2` | `#f9f9f9` |
+| Scheme | Input | Queue | Code | Inline code |
+| --- | --- | --- | --- | --- |
+| Dark | `#1f1f1f` | `#121212` | `#0b0b0b` | `#151515` |
+| Light | `#e3e3e3` | `#f2f2f2` | `#f9f9f9` | `#efefef` |
+
+Detected code backgrounds mix the terminal background toward black or white
+(whichever offers greater contrast) in linear RGB. The block contrast target
+is 1.05, or 1.07 for near-black backgrounds with luminance at most 0.005; the
+inline target is 1.15. These targets describe contrast against the terminal
+background, not text readability. Neither code background depends on default
+foreground color. Input and Queue retain their foreground-based contrast cap.
 
 OSC reports RGB colors but not terminal opacity. All resolved surfaces paint
 RGB cells; they do not infer or preserve terminal transparency. A light

{toolang-0.3.2 → toolang-0.3.4}/docs/execution.md

@@ -122,7 +122,6 @@ start()                                             -> None
 run(RunSpec, run_id?, request_id?, tracer?)         -> LocalRunHandle
 cancel(run_id, timing, request_id?, reason?)         -> ControlRecord
 steer(run_id, message, timing, request_id?)          -> ControlRecord
-reload(run_id, state, request_id?)                   -> ControlRecord
 cancel_control(run_id, index)                        -> ControlRecord
 stop()                                               -> None
 ```
@@ -131,14 +130,13 @@ stop()                                               -> None
 creates the owner task, and immediately
 returns an awaitable `LocalRunHandle`. Awaiting the handle returns the terminal
 `RunRecord`; canceling one waiter does not cancel execution. The handle also
-provides same-process `cancel()`, `steer()`, `reload()`, and
+provides same-process `cancel()`, `steer()`, and
 `cancel_control()` conveniences.
 Cross-process callers address the run by ID through their local `RunExecutor`.
 
 `steer()` and `cancel()` only accept durable controls; `cancel_control()` changes
-one pending reload, steer, or cancel to `revoked`. Steer, cancel, and control
-revocation do not need the target run to be owned by the submitting process;
-reload does. Run execution remains local:
+one pending steer or cancel to `revoked`. These controls do not require the
+target run to be owned by the submitting process. Run execution remains local:
 the process that calls `run(spec)` accepts and executes that run. `stop()` is
 terminal and cancels the run tasks owned by that executor instance. The process
 owner closes the shared `RunStore` after the executor stops.
@@ -213,7 +211,7 @@ observe only higher-level events.
 ## Run Controls
 
 Preparation control kinds are `run`, `rerun`, and `retry`; runtime control
-kinds are `reload`, `steer`, and `cancel`. Control timing is:
+kinds include `execute`, `steer`, and `cancel`. Control timing is:
 
 ```text
 immediate | next_step | next_call
@@ -232,11 +230,6 @@ revoked   explicitly withdrawn before application
 A cancel control is therefore `applied` when it cancels a run. An unapplied steer
 left behind by a terminal run is `wontapply`.
 
-Reload always uses `immediate` timing. It is process-local: the accepting
-executor must own the active run tree and retain the concrete durable
-`AgentState`. A child run ID is normalized to its root. There is no HTTP, CLI,
-Chat, scheduler, or model-facing reload endpoint.
-
 Every Run entry control stores its concrete runnable and model bindings,
 limits, resources, and a flat `CallInput[Value | TypedRef]`. Optional
 `authored_input` records the corresponding `CallInput[str]` source snapshot.
@@ -244,9 +237,8 @@ Steer stores a primary `Part[]` value under `_`; cancel stores optional primary
 Text under `_`. Execute stores input references keyed by parameter name. Retry
 inherits input from the entry control and records its effective settings.
 
-Root Run entry controls store the State revision and accepted sandbox. Child
-entries refer to the inherited State and omit the redundant sandbox. Reload
-stores the new State revision. A durable run is a root exactly when
+Every Run entry stores its State revision. Root entries also store the accepted
+sandbox; child entries omit the redundant sandbox. A durable run is a root exactly when
 `parent is None`; callers derive its root by following parent-run ownership.
 
 Every run-control insert or status change receives a monotonically increasing
@@ -260,7 +252,7 @@ all pending controls for every active run.
 Local submissions update the same cache immediately after their durable write.
 Remote submissions and cancellations arrive through revision polling. An
 immediate cancel cancels the owning task after the owner observes the durable
-control. Before applying a reload, steer, or cancel, runtime atomically claims it in
+control. Before applying a steer or cancel, runtime atomically claims it in
 SQLite. Cancellation is allowed only while a control remains unclaimed, so a
 cross-process claim/cancel race has exactly one winner without adding another
 public control status.
@@ -320,8 +312,7 @@ Output coercion validates the final run value against the runnable's declared
 output type. Setup and State remain
 complete snapshots; the executor computes concrete `AgentResources` instead of
 receiving filtered copies. A root starts from the State supplied in `RunSpec`.
-An explicit reload changes the State/ref pair at a serialized execution
-boundary; each physical step captures that pair, and a child run inherits its
-calling step's pair. Independent roots remain isolated. Source changes have no
-effect until a caller starts a new root or explicitly reloads an owned active
-tree. Invalid later setup config does not replace the last valid snapshot.
+Each physical Step retains its executing Run's State reference. A newly accepted
+named child independently captures the latest published State and validates it
+against the caller's contract. Inline bodies retain their containing plan.
+Publication never rebinds accepted Runs. Invalid source is not published.

{toolang-0.3.2 → toolang-0.3.4}/docs/executor.md

@@ -66,14 +66,6 @@ class RunExecutor:
         request_id: str | None = None,
     ) -> ControlRecord: ...
 
-    def reload(
-        self,
-        *,
-        run_id: str,
-        state: AgentState,
-        request_id: str | None = None,
-    ) -> ControlRecord: ...
-
     def cancel_control(
         self,
         *,
@@ -146,7 +138,7 @@ omitted retry anchor uses the latest visible failed, canceled, or running Step.
 For a failed or canceled Run with no incomplete Step, it uses the latest visible
 Step. For a succeeded Run, it prefers the latest non-value Step and falls back
 to the latest value Step. The handle exposes its run ID, executor, and task, and
-delegates same-process `cancel()`, `steer()`, `reload()`, and
+delegates same-process `cancel()`, `steer()`, and
 `cancel_control()` operations.
 Its await path shields the owner task so
 canceling a waiting HTTP request or TUI action does not cancel the durable run.
@@ -185,8 +177,7 @@ root, resolves and records its anchor, physically deletes the invalid structural
 step suffix and its child Runs, fails stale pending controls, and reopens the
 root as pending. New steps reuse the trimmed indexes. Before mutation, retry
 rejects any root tree captured by a durable fork prefix, as well as applied
-reload and execute-control history
-because it cannot replay either prior execution timeline. It also requires the
+execute-control history because it cannot replay those prior execution timelines. It also requires the
 source preparation to have sandbox
 provenance and requires it to equal the current canonical sandbox. Accepted
 retry controls repeat that value. A flow retry restores typed locals from the
@@ -323,7 +314,7 @@ effective-resource, invocation, or tool-snapshot layer.
 
 The frame holds one selected tool mapping and effective Agic routes. Every
 ordinary tool-capable Agic call receives `_toolang__run`,
-`_toolang__execute`, `_toolang__reload`, and `_toolang__pick`. `hands` and `handoffs` authorize run and
+`_toolang__execute`, `_toolang__chdir`, and `_toolang__pick`. `hands` and `handoffs` authorize run and
 execute targets; they do not select definitions. All tools use plugin registration
 and the same Tool Step lifecycle. Every call includes `toolang:hands` and
 `toolang:handoffs` in messages, as siblings before `toolang:context`, even with
@@ -337,8 +328,11 @@ The limits are 64 unique targets and 32,768 UTF-8 bytes across both snapshots,
 including escaped framing. Overflow rejects preparation with an error asking
 the author to narrow hands/handoffs; lists are never silently truncated.
 Runtime calls in one model batch
-use that Model Call's captured routes, even if reload and ordinary tools adopt
-new State between calls. The next Model Call captures the new routes.
+use that Model Call's captured routes and prepared frame. Both advertisement
+and invocation resolve within the caller's module: main sees public exports,
+and a flow module sees its own declarations, including private helpers. Child acceptance
+selects latest State and checks the advertised contract. The next Model Call
+captures the latest published routes within the Run's bound authority.
 
 `AgentSetup.models_effective()` and `AgentSetup.tools()` provide the filtered
 runtime collections. They are lazily materialized and memoized in the pinned
@@ -349,8 +343,7 @@ stable model entry keys. A ceiling cannot expand the published base. Invalid
 queries are rejected before the run is durably accepted.
 Every child agic/flow inherits its immediate parent's effective resources,
 intersected with module visibility by stable identity. Public calls and execute
-transfers use the same boundary; reload reapplies it rather than resetting to
-agent resources. Immutable per-run configuration inherits separately and permits
+transfers use the same authority boundary. Immutable per-run configuration inherits separately and permits
 explicit overrides. Inherited instruct/context retain their declaring module.
 
 The root runtime owns one thread-history snapshot. Only root agics automatically
@@ -497,11 +490,6 @@ operations only mutate shared SQLite truth. `run(spec)` is also process-safe,
 but the process that calls it owns and executes that run; run is not a
 cross-process dispatch queue.
 
-`reload()` is intentionally different: only the owning executor accepts it.
-It requires a concrete durable State from the same `AgentLayout`, normalizes a
-child ID to the active root, retains the object, and writes a root-targeted
-`reload` control with `immediate` timing.
-
 Every inserted or changed control receives a global monotonic revision inside
 the same SQLite write transaction. The owner process polls only revisions
 newer than its cursor. An unchanged control table returns no rows. Changed
@@ -521,13 +509,10 @@ it. A cancellation updates only an unclaimed pending control, making
 application and cancellation linearizable without exposing an intermediate
 public status.
 
-Reload application and every physical `StepBegin` use the same root
-`asyncio.Lock`. Applying a reload claims and marks its control `applied`, then
-swaps the in-memory State/ref pair without awaiting. Beginning a step persists
-the current ref and captures the matching immutable object before releasing
-the lock. Parallel Flow branches serialize only this short boundary; their work
-remains concurrent. A started step never changes State, and a child accepted by
-that step uses the captured object and ref.
+Every physical `StepBegin` persists the executing Run's bound State reference
+under the root event lock. Named child acceptance independently captures the
+latest published State once, validates its contract and authority, and persists
+its own entry revision before execution. Accepted and queued Runs never rebind.
 
 
 ## Event Ordering

{toolang-0.3.2 → toolang-0.3.4}/docs/input-syntax.md

@@ -26,10 +26,11 @@ ChatInput = QuickCommand | RunOverrideHelp | RunOverride + CallInput[str]
   chat input.
 - `RunOverrideHelp` is the terminal-chat-only `:?` interaction. It describes
   colon syntax without creating a run.
-- The runnable branch is valid only when it contains primary or named input. A
-  colon override without runnable input is invalid and never changes the
-  session. Slash setting commands change `SessionSetting` without creating a
-  run.
+- The runnable branch requires primary or named input, or an explicit runnable
+  selection (`:agic`, `:flow`, or `:runnable`). An explicit selection may invoke
+  a runnable with no input; its signature still validates required parameters.
+  Other colon overrides alone are invalid and never change the session. Slash
+  setting commands change `SessionSetting` without creating a run.
 
 Script, task, and chore surfaces parse the run-only pair of `RunOverride` and
 `CallInput[str]`; they do not parse `QuickCommand`. Agic, flow, and prompt
@@ -92,6 +93,11 @@ resolvable unqualified ref. `agic` and `flow` are exact shorthand:
 `default` resets only the generic runnable form. Kind-specific commands treat it
 as a normal name. Colon runnable commands may carry named runnable input, such
 as `:agic review focus=security`; slash runnable commands may not.
+`:flow research` invokes `research` with an empty argument map. It may be
+combined with other overrides, such as `:model effort=high` on a preceding
+line. `:runnable default` invokes the surface default, even if the session has
+selected another runnable. These forms do not synthesize an empty primary
+input; `:flow research -` instead supplies `_` as an empty string.
 
 Allow and limit bodies accept one or more assignments:
 
@@ -227,8 +233,10 @@ inside Script input still support fenced capture. The capture form is
 parser-only state and is not stored in `CallInput[str]`.
 
 Plain run-only parsing permits an empty `CallInput[str]` when the selected
-runnable accepts no primary or named input. A colon override still requires
-primary or named runnable input. Parsing is atomic: any invalid run override,
+runnable accepts empty input. Colon overrides also permit an empty argument map
+when they explicitly select a runnable; missing required input is rejected
+against that runnable's signature. Overrides without an explicit runnable still
+require primary or named input. Parsing is atomic: any invalid run override,
 named input, include, prompt, or coerced value rejects the complete input.
 
 ## Content

{toolang-0.3.2 → toolang-0.3.4}/docs/plans/agic-runtime-calls.md

@@ -1,5 +1,10 @@
 # Define Agic Runtime Calls
 
+State switching and reload in this historical plan are superseded by
+[Latest-State Run Binding](revision-refresh-calls.md). The reload tool and
+control have been removed.
+
+
 ## Status
 
 Approved for implementation. Revised on 2026-08-28 to use one ordinary Run

toolang-0.3.4/docs/plans/background-derived-code-surfaces.md

@@ -0,0 +1,77 @@
+# Background-derived code surfaces
+
+Status: approved through the inline contrast 1.15 visual review and the request
+to implement it in a pull request, extended by the explicit request to make
+Script and Chat consistent. This supersedes the code-surface decisions in
+[terminal-adaptive-chat-surfaces.md](terminal-adaptive-chat-surfaces.md).
+
+## Goal and scope
+
+Make inline code distinguishable without adding spaces or changing wrapping.
+Chat and Script code backgrounds depend only on the terminal background,
+independently of its default foreground. Input/queue colors, text attributes, and ANSI syntax
+highlighting retain their existing behavior.
+
+## Design
+
+- Mix the original terminal background toward the black or white endpoint with
+  greater contrast headroom, in linear RGB.
+- Block contrast is 1.05, or 1.07 when background luminance is at most 0.005.
+  Inline contrast is 1.15. Do not clamp either using default text contrast.
+- Add a concrete `inline_code_background` to `TerminalSurfaces`. Fixed dark/light
+  schemes and the dark fallback use #151515/#efefef for inline backgrounds.
+- Preserve the three-color environment configuration: its explicit code color
+  controls both block and inline backgrounds, with no probe or derivation.
+- Carry both backgrounds through Chat live, committed, and durable `/output`
+  rendering. Rich retains ownership of Markdown text styling.
+- Shared render functions accept an optional inline override, falling back to
+  the block background for existing callers.
+- Script local/remote execution and retry/rerun resolve the same palette once
+  at command orchestration, before starting run output, using loaded runtime
+  environment and stderr as the output stream. Quiet execution does not probe.
+- Script's presenter and console receive concrete surfaces without probing
+  the terminal. All live and committed Markdown paths pass both backgrounds
+  and inherit the terminal foreground, matching Chat. TTY output uses truecolor;
+  non-TTY output remains uncolored. The shared resolver only probes when stdin
+  and stderr are the same TTY with no pending input.
+- Retain the existing input/queue derivation, including its historical weak
+  surface reference used for compression and quantization. Keep this helper
+  independent of the code-contrast constants so future code tuning cannot
+  change input/queue colors.
+
+## Touchpoints
+
+`terminal_surfaces.py` owns palette derivation and configuration. Script and
+thread command entry points resolve colors for the Script presenter/console.
+Chat's TUI,
+presenter, and blocks pass colors into `human_values.py` and shared execution
+progress rendering. Focused terminal-surface, Markdown, and Chat tests cover the
+policy and propagation. Update `docs/execution-presentation.md` to describe
+the code background policy. The local comparison script remains an experiment and
+is not part of the production change.
+
+## Acceptance checks
+
+- Equal backgrounds produce equal code colors with different foregrounds,
+  including low-contrast black and white themes.
+- Quantized colors approximate the contrast targets; inline is stronger than
+  block. Black produces #0b0b0b/#151515; white produces #f9f9f9/#efefef.
+- Input/queue outputs remain unchanged, including low-contrast/tinted themes
+  and when the code-contrast constants change.
+- Paragraph, list, quote, and table inline spans receive only the background
+  override. Fences use their separate background, wrapping/text are unchanged,
+  and the console theme is restored after rendering.
+- Live, committed, and durable slash outputs propagate the selected colors.
+- Script and Chat render identical Markdown colors with dark, light, custom,
+  and detected palettes, in both live and committed paths.
+- Script CLI wiring honors loaded environment, probes its stderr terminal once,
+  and avoids probing quiet/non-TTY output. Invalid configuration fails before
+  starting a run. Explicit three-color values still control both code colors.
+- Run all default repository checks before commit and PR handoff.
+
+## Risks and open questions
+
+Neutral mixing may reduce saturation. Code text contrast is not guaranteed by
+this background-only policy; terminal-owned ANSI colors still determine text
+readability. Code surfaces need not remain weaker than foreground-capped queue
+surfaces. HTML previews approximate the terminal ANSI palette. No open questions.