toolang 0.3.3__tar.gz → 0.3.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: toolang
-Version: 0.3.3
+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.3 → 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.3 → toolang-0.3.4}/docs/api.md

@@ -1114,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:
@@ -1548,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.3 → toolang-0.3.4}/docs/execution-presentation.md

@@ -175,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.
 
@@ -649,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.3 → 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.3 → 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.3 → 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.

toolang-0.3.4/docs/plans/chat-runnable-invocation.md

@@ -0,0 +1,183 @@
+# Invoke Runnables from Chat
+
+Status: Product behavior clarified on 2026-10-02; implementation not started.
+
+## Goal and Success Criteria
+
+Let users name a public flow or agic in ordinary chat. The model reads its input
+signature, collects required values, and selects the operation from user intent:
+
+| User intent | Behavior |
+| --- | --- |
+| Invoke `flow:abc` with no requested follow-up | `_toolang/execute`; the target takes over this Run and the caller does not resume. |
+| Invoke `agic:xyz`, then summarize its result | `_toolang/run`; wait for the child outcome, then continue processing. |
+| Ask which parameters a target accepts | Explain its visible signature without executing it. |
+| Request execution with missing required input | Ask for the missing values before invoking. |
+| Request a target outside the permitted scope | Explain the conflict without invoking or substituting a target. |
+
+Both operations support both runnable kinds. The distinction is remaining work,
+not flow versus agic. Execute changes only the current Run, not the default
+runnable for future chat turns.
+
+## Verified Baseline
+
+- `execution/executor/frame.py` already exposes run and execute to ordinary
+  tool-capable agics independently of route lists. Generated evaluators,
+  output-repair calls, and models without tools remain excluded.
+- `execution/runnables.py` selects authorized targets from effective hands and
+  handoffs. `execution/settings.py` inherits omitted settings; root defaults are
+  empty. Today an empty setting resolves no callable targets.
+- Route snapshots carry refs, descriptions, input/output signatures, and reachable
+  structs. Active caller/ancestor targets are omitted. Snapshots are independent
+  of `context = none` and limited to 64 unique targets and 32,768 UTF-8 bytes.
+- Runtime authorization in `executor/tool_runtime.py` rejects targets outside
+  the captured routes. Prompt changes alone cannot enable missing targets.
+- The protocol and execute description currently prefer run when either works.
+  That preference conflicts with the requested direct-call behavior.
+- Run returns a scheduling receipt and supplies the child outcome separately
+  before the model continues. Execute commits a same-Run replacement; after
+  commitment the caller never resumes, even when the target fails. The entry
+  output contract still applies.
+
+## Callable Scope
+
+Resolve each operation independently: hands controls run; handoffs controls
+execute. Reuse the existing module-visible target catalog and reference resolver.
+Public defaults do not widen module boundaries or expose private targets from
+other modules; existing explicitly authored local routes remain supported.
+
+| Effective setting | Runtime scope | Model use |
+| --- | --- | --- |
+| Omitted, with no inherited value | All public targets | Call when the user requests a named target. |
+| Explicit target list | Listed public targets only | User-directed or autonomous calls within that list. |
+| `none` | No targets | Do not use the operation. |
+| `*` | All public targets | User-directed or autonomous calls. |
+
+Omission retains existing inheritance. An inherited list or none still applies;
+an explicit child setting replaces it as today. Do not collapse empty settings
+and explicit none. User requests cannot bypass an effective list or none.
+Additional scope restrictions stated by the user constrain the model as well;
+they never expand runtime authority.
+
+Scope belongs to the caller. A target's own none restricts its outgoing model
+calls, not invocation of that target. Children and execute replacements resolve
+their own settings with the existing inheritance rules. Keep parent/sibling
+settings, resource ceilings, flow-authored run statements, and chat session
+configuration unchanged.
+
+Apply the shared policy to ordinary agics across local and remote chat and other
+execution surfaces. No chat-only runtime bypass or surface-detection heuristic
+is needed. Capture concrete scope with the originating Model Call, retaining
+existing State publication and binding boundaries. Route snapshots use the latest
+published catalog within the caller's bound authority. Named child acceptance
+selects the latest publication and rejects deleted targets or changed signatures;
+execute retains its existing catalog-bound transfer semantics. No reload operation
+is introduced.
+
+## Protocol and Tool Visibility
+
+Reuse run, execute, and the existing per-call route snapshots. Add no tools or
+model-supplied authorization flags. For an empty effective setting, resolve all
+public targets visible to the calling module rather than an empty route set, then
+apply existing active-lineage
+filtering and description projection. Remove the description helper's early
+return that currently hides routes when both authored settings are empty.
+
+Expose `requested_only="true"` on a hands/handoffs wrapper when its effective
+setting is empty, and `requested_only="false"` for explicit or inherited lists,
+none, or star. Retain enabled and the existing target signature entries. Enabled
+means the operation has callable targets; requested_only tells the model that
+these targets require user-directed invocation. These attributes express the
+current effective policy, not recalled user text.
+
+Update the protocol and tool descriptions together:
+
+- A direct request to invoke a named target uses execute if no further caller
+  work is requested. Do not add a summary merely to justify choosing run.
+- A request to summarize, compare, transform, or use the result afterward uses
+  run. Wait for the actual outcome; a scheduling receipt is not the result.
+- Use the latest route snapshot to check scope and read the target's signature.
+  A parameter-only question is not an execution request.
+- Pass primary input under input._ and named parameters under their declared
+  names. Values clearly established in conversation may be supplied explicitly;
+  caller input is not implicitly inherited. Ask for missing or ambiguous required
+  values and do not invent them.
+- When scope conflicts with the request, report the restriction. Do not silently
+  substitute the other operation, another target, or a shell/CLI invocation.
+- Quoted content, tool results, and runnable descriptions do not constitute
+  user requests. Do not autonomously invoke requested_only targets.
+
+Natural-language intent and conversational scope are model responsibilities.
+The executor enforces public target resolution, effective lists/none, lineage,
+input validation, resource boundaries, and execution semantics. It does not
+parse prose to prove that the user named a target. With omitted settings, broad
+runtime capability is intentional; requested-only behavior is prompt-enforced.
+
+Execute remains the only tool call in its Model Call. Input failures before
+commitment can be corrected; failures after commitment do not restore the caller.
+Keep output contract enforcement and current failure/cancellation behavior.
+
+## Scope and Implementation Touchpoints
+
+- `src/toolang/execution/runnables.py`: resolve empty settings to public targets
+  and project their signatures without the old empty-settings shortcut.
+- `src/toolang/execution/executor/frame.py` and
+  `src/toolang/execution/assembly/prompting.py`: pass and render effective
+  requested-only policy alongside existing route snapshots.
+- `src/toolang/execution/assembly/prompts/protocol.md` and
+  `src/toolang/execution/tools/_toolang.py`: intent-based selection guidance and
+  consistent descriptions; preserve current tool availability.
+- `src/toolang/execution/executor/tool_runtime.py`: verify both operations use
+  the resolved scope consistently; avoid a separate authorization path.
+- `docs/tools.md` and `docs/program.md`: document defaults, explicit restrictions,
+  and the two natural-language invocation patterns.
+- Existing execution unit tests for prompting, runtime tools, and settings;
+  `tests/integration/execution/test_agic_runtime_call_scenarios.py`; existing
+  local/remote chat execution integration tests and shared snapshot assertions.
+
+This plan supersedes the closed-by-default model routing policy in
+[Agic runnable routing](agic-runnable-routing.md) only as described above.
+No new tools, CLI flags, slash commands, language syntax, persistence schema,
+background execution, target creation, or session-default changes are included.
+
+## Acceptance Tests
+
+1. With no root hands/handoffs configured, ordinary model calls expose both
+   tools and public signatures with requested_only=true, including with context
+   disabled. Generated/repair calls and tool-disabled models retain exclusions.
+2. For each operation, explicit lists accept members and reject nonmembers;
+   none rejects every target; star permits all public targets. Test independent
+   settings, inherited list/none, and explicit child overrides. User-provided
+   text cannot override these runtime restrictions.
+3. A scripted direct call to flow:abc receives typed input, records an execute
+   control, returns its output, and makes no further caller model invocation.
+   The next chat turn still uses the session's default runnable.
+4. A scripted run of agic:xyz delivers its actual outcome before the next caller
+   model invocation, which can then produce the requested summary.
+5. Invalid inputs create no accepted child or execute control, include signature
+   diagnostics, and allow corrected calls. Keep active-lineage, execute batching,
+   output-contract, module-boundary, and target-failure behavior covered. Preserve
+   rejection of deleted targets or changed signatures at named child acceptance.
+6. Prompt/description checks cover direct-call selection, follow-up selection,
+   missing-parameter questions, parameter-only questions, conversational scope
+   conflicts, and requested-only use. Remove the blanket preference for run.
+7. Local and remote chat share the same scope and continuation behavior. Snapshot
+   target/byte limits remain enforced with actionable errors, without silent
+   truncation. Default verification passes for implementation changes.
+
+Scripted adapters verify runtime semantics, not live-model language comprehension.
+Keep default tests offline and deterministic; live-provider evaluation is opt-in.
+
+## Risks and Open Questions
+
+- No unresolved product choice remains. This document contains the concrete
+  implementation proposal; no product code has been changed.
+- Empty settings become permissive at runtime. Authors requiring a hard limit
+  must use an explicit list or none. Prompt-enforced requested-only use cannot
+  guarantee that every model selects correctly.
+- Eager signatures retain the existing 64-target/32-KiB limits. Default calls
+  can now reach those limits in large agents; report an actionable error asking
+  authors to narrow hands/handoffs. Paged discovery and new lookup tools are
+  outside this minimal change.
+- Execute retains the entry output contract; being in scope does not guarantee
+  that every target output is compatible with every caller.