Skip to content

Release v0.11.0

Latest

Choose a tag to compare

@github-actions github-actions released this 14 Nov 08:57
· 299 commits to develop since this release
52cd7bf

What's New in v0.11.0

Security

  • read_file withholds a file with more than one hard link (#703). A hard link to .env under another name (notes.txt) matched no name rule and was returned verbatim. On Unix a regular file whose nlink is above 1 is now refused, and the refusal points to read_file_raw (approval); a single-link file is unaffected, and nothing changes on other platforms. It reads only the nlink of the metadata it already has: no directory scan, so a legitimately linked file (a hard-linked build artifact) needs read_file_raw too. The git diff filter and cora_search hits stay name-based.

  • A known secret is now redacted in more of the forms it takes in a sink (#681). The matcher (SecretSet::redact) only knew the value alone, its JSON escape, base64 of the value alone and percent-encoding, so Authorization: Basic base64("user:" + token), a docker config.json auth, a base64'd .env, xxd -p hex, a JSON \/ or \uXXXX escape (Python ensure_ascii, PHP) and a value split by a zero-width character reached the provider, the log and the other sinks unredacted. A value now also matches as base64 (standard and URL-safe) at each of the three offsets inside a larger payload, keeping only the characters that do not depend on the neighbouring bytes, as lower- and uppercase hex, and with \/ and \uXXXX escapes (surrogate pairs included). Text holding a zero-width, bidi or soft-hyphen character is scanned a second time with those characters removed, and the matches are mapped back onto the original. At most 24 needles per value, the 8-character floor still applies (no needle is shorter), and a text without invisible characters is scanned once; redaction throughput on mixed text is about 350 MB/s (was about 660 MB/s). Residual, documented in the threat model: arbitrary transforms (line-wrapped base64, mixed-case hex, gzip, ROT13, a value cut in pieces) are not recognised; the shape detector (#597) cannot close that either.

  • A server the plugin lock refuses no longer reaches the model through resources or prompts, and an unapproved or revoked server is not started at all (#680). Before, a refused server's tools stayed out, but tole still connected to it, listed its prompts as /mcp: commands, offered it in mcp_read (ReadOnly, no approval) and rendered its prompts into the next message. Now register_server_tools records the admission decision on the session's own registry (ToolRegistry::mcp_admitted, per session, never process-wide), the roster probes extras and offers mcp_read only for admitted servers, tole chat lists and renders /mcp: prompts only for them, and the host skips a server with no lock entry, a revoked one, or every server under an unreadable lock before connecting (plugin_gate::Gate::refuse_unseen), with the same refusal note as before. A server whose manifest changed is still connected once, to detect the change. Prompts and resource templates stay outside the manifest hash; they are reachable only from an admitted server.

  • Live tool events no longer show secrets the session log hides (#677). The tool_started input, the tool_finished preview of an output or error, and the reasoning that serve SSE (GET /sessions/{id}/events), ACP tool_call_update and the TUI forward were the raw values, while the log of the same turn was redacted (#596). The turn loop now redacts every observer event with the session's own secret set (Storage::egress_secrets), before the 200-character preview cut, so a cut never leaves part of a secret. Streamed answer text is model output and is not redacted live (its committed entry is).

  • The advisor's context no longer lets a secret dodge redaction by being split with an invisible character (#587). advisor::clean redacted known secret values and only then stripped control characters, so a value split by a zero-width, bidi or control character (tok\u{200b}-...) was not redacted and re-formed once the character was removed. Control and invisible characters (newline and tab kept) are now stripped first, then secrets are redacted, then the fence markers are neutralized, then the text is capped. The multi-round discussion sanitizer (#588) uses the same order.

  • A session directory swapped for a symlink no longer redirects the session log (#639). JsonlStorage resolves its directory once, walks the canonical path from / with O_NOFOLLOW | O_DIRECTORY at every component, holds that directory handle, and opens the session file, its .lock sidecar and compaction's temp file relative to it (the rename and the directory sync too). Before, O_NOFOLLOW covered only the last component, so a job that swapped .tole or .tole/sessions for a link could have the .lock sidecar created elsewhere. Unix only; no new dependency; other targets keep the path-based open. Regression tests swap the directory after create and after open and assert nothing is created through the link.

  • Webhook routes on tole serve, part 1b of #582: the security gate. No job is fired yet; filters and the action come in part 2, and tole hook in part 3.

    • Each [hooks.<route>] table in the user config serves POST /hooks/<route>. A project config cannot define or change a route: its hooks table is ignored with a warning.
    • A route needs an HMAC-SHA256 key, named by hmac_key_env or hmac_key_file (a regular file, not a link or FIFO, at most 4 KiB, at least 16 bytes). A route that cannot load stops tole serve before it listens, naming the route. Only insecure_loopback = true skips the signature, and it loads on a loopback bind only, for loopback clients.
    • Deliveries are checked with tole_core::webhook (#643): native X-Tole-Timestamp and X-Tole-Signature within ±300 s, or GitHub X-Hub-Signature-256. The bearer token is not a webhook credential, and a failed signature counts toward the source IP's failed-auth limit.
    • Every delivery id is recorded as hook_seen in the cron ledger. A repeat gets 200 duplicate, after a restart too; an accepted delivery gets 202.
    • Limits per route:
      • rate_per_minute (default 30, at most 600), counted from the ledger so it survives a restart;
      • max_body_bytes (default 256 KiB, at most 1 MiB);
      • an unknown route (404) or an oversized body (413) is answered before the body is read.
    • The key never appears in errors, logs, responses, config check or the ledger.
    • Accepted limits, written in the threat model:
      • a GitHub delivery replayed after the 7-day retention verifies again, since GitHub signs no timestamp;
      • the ledger grows by one line per accepted delivery and is not rotated;
      • bad-signature limiting is per IP and in memory.
  • Agent-created cron jobs (#581 part 2). An agent creates a job only through the new cron_create tool (Risk::Write, so each call is approved or allowlisted). The tool exists in run, chat and serve sessions at depth 0 outside plan mode; a cron run, a child agent and the MCP server face do not have it. The host saves the job paused in the session workspace, with created_by = agent and creator_allow (the session's allow list). The tool input refuses an id, a script, skills, a profile, a pause state and every provenance field by name. Its allow may name only the creator's allow patterns, and the creator's deny patterns are always kept; a command: delivery is refused. tole cron resume is the human enable and now records enabled_by = cli.

    • Behavior change: every job not saved through tole cron create (a hand-written line without created_by included) is blocked unless it was enabled with tole cron resume (not_enabled), stays within its creator's allow list and deny patterns (allow_exceeds_creator), and is not a script (script_untrusted).
    • Behavior change: an agent run whose workdir holds the cron dir is blocked (ledger_in_workdir), because its file tools could write job records. Give such a job a workdir that does not contain $TOLE_CRON_DIR (by default <codecora home>/tole/cron).
    • tole cron edit keeps an agent job's creator, grant and enable, and refuses an --allow beyond the creator's.
    • The ledger fold keeps a live job's created_by and creator_allow from the line that created it (tole_core::ledger::PROVENANCE), so a later line cannot change them.
    • No config defines jobs, and a cron run reads no project config from its workdir. When jobs gain MCP servers, they go through the plugin lock (#636).

    Design: docs/automation-design.md §5.

  • Sensitive files are read redacted (#598 part b). read_file on .env*, *.pem, id_*, .npmrc, .netrc or *.key (file name, case-insensitive, by the requested name or the resolved real path, so a symlink to .env counts) returns KEY=«redacted» lines, a key file a single «redacted», and no content hash. The verbatim read is the new read_file_raw tool, Risk::Write: approve its call, or start with --allow read_file_raw. The git tool's diff hides every hunk line of a sensitive file, and cora_search hides the text of a hit in one. read_file now opens a file without blocking or following a final symlink and checks it on the handle, so a FIFO swapped in after the check cannot hang the read. tole doctor adds a secrets report: which secret names are set, which tools may receive each, what reaches the children of model commands and of a child session (never a value). Tool list and approval: docs/secrets-integrations-design.md §10.

  • Known-value secret redaction, part 1 of #595 (epic #594). New tole-core module secrets with SecretSet: it collects the values of every secret-named env var (the ENV-1 name rule, now secrets::is_secret_name, shared with the child-env scrub) plus explicitly named values (a provider key, URL userinfo passwords), and redact replaces each value and its base64 (standard and URL-safe), percent-encoded and JSON-escaped forms with «NAME»; overlapping matches merge, unmatched text is returned without a copy, and an empty set costs nothing. Values under 8 characters are not redacted and are reported by name only. The provider request body (system prompt, messages, tool arguments, tool results) and provider errors now redact every known secret of the process instead of only the provider key (E11): the marker changes from <redacted> to «NAME», and a provider key shorter than 8 characters is no longer redacted. tole-core API: new secrets module, OpenAiProvider::with_secrets, subprocess::scrub_env_for_child_keeping, child_env::PROVIDER_SECRETS.

  • Known-value secret redaction, part 2 of #595: the same SecretSet now covers every egress sink tole has today. MCP tool arguments (every string and key, JSON structure preserved), the web_search query, the systemone_decide request and uteke_document markdown are redacted before they leave the process; the memory-loop session summary is redacted before its length cap (so a cap can never cut a secret into an unrecognizable prefix). A web_fetch URL that carries a known secret, raw or percent-encoded, is refused (direct fetch and fetch backend) instead of being sent. Values a TOLE_WEB_SEARCH_HEADERS / TOLE_WEB_FETCH_HEADERS header expands from ${NAME} count as secrets whatever the variable is called, for every sink including the provider. tole-core API changes: mcp::register_server_tools and memory::remember_session take a &SecretSet; web::WebFetchTool is no longer a unit struct (use WebFetchTool::default()); new with_secrets on McpTool, WebFetchTool, WebSearchTool, WebBackendFetchTool, SystemOneTool and UtekeDocumentTool; new SecretSet::redact_value and web::header_secrets. The provider now redacts tool-call arguments and tool results structurally with redact_value (part 1 redacted their serialized text, which turned a secret that is a bare JSON number into invalid JSON; it now becomes the marker string).

  • tole is no longer dumpable on Linux (#675). Every tole process (serve, mission, cron, child agents included) calls prctl(PR_SET_DUMPABLE, 0) first thing in main. A child running as the same user can no longer read tole's /proc/<pid>/environ (which held every secret tole was started with, whatever the ENV-1 scrub removed from the child's own environment) or /proc/<pid>/mem, or attach with ptrace. Side effects: tole writes no core dump, and attaching a debugger to a running tole needs root. /proc/<pid>/stat stays readable, so delegation leases work as before. Residual: root, and other systems (macOS, Windows) that expose a same-user process's environment by other means; files the owner keeps readable are for the sandbox work (#601).

BREAKING

  • BREAKING: more files count as sensitive, so read_file, the git diff filter and cora_search hits redact them (#683). The name rule now also matches *.env and *.env.* (prod.env, config.env), credentials, .git-credentials, .pgpass, .htpasswd, .pypirc, .dockercfg, config.json directly under a .docker directory, *.p12, *.pfx, *.jks, *.keystore (shown as one marker, like *.pem), *.tfvars, kubeconfig and secrets.y*ml. Before, read_file (no approval) returned these verbatim, and their values are usually not in the secret set, so they reached the provider. A new sensitive_files list in the config adds name globs (* wildcards, no directory part), e.g. sensitive_files = ["*.secret", "vault-*.json"]; the project layer's list is added to the user's and can never remove a name. Migration: a tool that needs the verbatim content of such a file uses read_file_raw (approval) or --allow read_file_raw. A hard link to a sensitive file under another name is withheld since #703.
    • Migration: read a sensitive file verbatim with read_file_raw (approved) or start with --allow read_file_raw.
  • BREAKING: a session can no longer run the tole binary, and the owner-only subcommands refuse under a session (#684). Before, only a child agent was refused tole in run_command and job_start; a root session, or a cron agent run, could run tole cron create '@every 10m' --script ..., tole cron resume <id>, tole plugin approve X --hash H, tole skills approve or tole config trust, each saved as the owner's decision. Now, in every session kind, run_command and job_start refuse an argv whose program is the tole binary (by name, by resolving to the running executable, behind env/nohup/sh -c) and any argument naming TOLE_UNDER_SESSION; every process they start carries TOLE_UNDER_SESSION=1; and tole cron create|resume|edit, plugin approve, skills approve, skills drafts promote and config trust refuse to write when that marker or TOLE_AGENT_DEPTH >= 1 is set. A human at a terminal is unaffected; a mission that had the model run tole ... through run_command must be run by the owner instead. Defense in depth, not a boundary: a copied binary with a cleared environment, or an interpreter, can still write the files (docs/threat-model.md, sandbox in #601).
    • Migration: run the owner-only subcommands (cron create|resume|edit, plugin approve, skills approve, skills drafts promote, config trust) yourself in a terminal, not through a session or a mission.
  • BREAKING: no write_file, edit_file or delete_file when the workspace holds the tole data dir (#684). Started in ~, the file-tool jail contained ~/.codecora/tole (the cron ledger, plugins.lock, skill-approvals.json, trusted-configs.json, the user config), so the model could approve a server or a skill by writing the file. Every session kind now registers no mutating file tool when the workspace contains, or sits inside, the data dir, and tole warns at startup; start tole in a project directory. Cron agent runs already refused such a workdir.
    • Migration: start tole in a project directory, not in ~ or ~/.codecora/tole.
  • BREAKING: a plugin-lock approval binds the server's command line or URL and its program file, and its recorded secrets are its real grant (#679). Admission compared only the server-reported version and tool manifest, which any process can replay: the same server NAME re-pointed at another command or URL, or another binary at the approved path, was trusted and got the mcp secrets and every tool argument. Now plugin_lock::admit also compares the configured source with the approved one (Moved) and, when the approval recorded one, the SHA-256 of the stdio program with the recorded integrity (Rebuilt); either refuses the server before it is started, with a note naming the remedy, and the ledger records source_change / binary_change. The lock entry's secrets (the mcp grants held at approval) are now what the server's process receives, intersected with the current [secrets] release; a project lock that drops a name now takes effect. Existing version 2 locks keep working unchanged when the command line and binary are the ones approved. Migration: after upgrading an MCP server's binary (cargo install cora-code, a new gh extension, ...) or editing its command line, re-approve it once: start tole in a terminal, or run tole plugin approve <name>. A server that should receive a secret it did not hold at approval needs a re-approval too.
    • Migration: after changing an MCP server's binary or command line, re-approve it once (tole plugin approve <name>).
  • BREAKING: native webhook deliveries sign the delivery id and the event (scheme v2) (#678). X-Tole-Signature is now v2=<hex>, an HMAC-SHA256 over v2\n<timestamp>\n<delivery id>\n<event>\n<body> (the X-Tole-Event value, empty when absent). Before, the id and the event were outside the signature, so a captured delivery replayed as new under a fresh id within the 300 s window, or passed another route's events list. The v1 form (sha256= over <timestamp>.<body>) is refused with 401 and a reason naming v2. GitHub deliveries (which sign only the body) are now deduplicated on the signed body (gh: and its SHA-256) instead of the unsigned X-GitHub-Delivery, so a capture re-sent under a new id is duplicate for the 7-day retention; two GitHub deliveries with byte-identical bodies count as one. X-GitHub-Event stays unsigned: use filter on the payload for anything that must hold. Migration: update native senders to sign v2 (tole hook test --fire already does; tole_core::webhook::sign takes the delivery id and the event).
    • Migration: sign native webhook deliveries with scheme v2 (X-Tole-Signature: v2=<hex>); no release ever served v1, so only builds from develop are affected.
  • BREAKING: more variables count as secrets, by name and by value (#682). The ENV-1 name rule (secrets::is_secret_name, shared by the child scrub and the redactor) now also matches names ending in PASS, _KEY, _DSN, _SK, _COOKIE, _AUTH, _BEARER or DATABASE_URL, names starting with AUTH_ or BEARER_, and PASSPHRASE anywhere (DB_PASS, PGPASS, OPENAI_KEY, SENTRY_DSN, STRIPE_SK, NPM_AUTH, SESSION_COOKIE); SSH_AUTH_SOCK, GPG_KEY, public keys and *BYPASS stay ordinary. A variable is also a secret by its value: a URL with a password under any name (REDIS_URL=redis://:pw@host; its password is redacted, and the variable is scrubbed from children except proxy settings *_PROXY), and a value tole holds by role whatever the variable is called: every webhook route key (hmac_key_env or hmac_key_file), the serve token and the ${NAME} web header expansions. All of these are redacted on egress and removed from run_command, job_start, cron, hook and MCP children unless granted. Child agents keep their provider base URLs. Migration: a command that needs one of them gets it back with a [secrets] grant in the user config, e.g. DATABASE_URL = { tools = ["run_command"] }; [secrets] keys may now also be *_URL / *_URI names.
    • Migration: grant a variable a command needs back with [secrets], e.g. DATABASE_URL = { tools = ["run_command"] }.
  • BREAKING: the tole mission --verify command and the on_turnend stop gates get no secrets by default (#676). Both run unattended and usually execute code the agent just wrote (cargo test runs build scripts and tests, npm test runs package scripts). Before, the verify command inherited tole's whole environment (provider key, GITHUB_TOKEN, TOLE_SERVE_TOKEN, webhook keys) and the stop gates ran as the hook consumer, which keeps GITHUB_TOKEN by default. Each now has its own [secrets] consumer, verify and turnend, bound to nothing by default; the ENV-1 scrub removes every secret-shaped variable a binding does not grant them. Pre- and post-tool hooks keep the hook consumer and its default. Migration: if a verify command or a stop gate needs a token (for example gh in a check script), grant it in your user config, listing every consumer that should keep it: GITHUB_TOKEN = { tools = ["gh", "git", "hook", "mcp", "verify", "turnend"] } under [secrets].
    • Migration: grant the token to the verify and turnend consumers in [secrets], e.g. GITHUB_TOKEN = { tools = ["gh", "git", "hook", "mcp", "verify", "turnend"] }.
  • BREAKING: MCP servers need the owner's approval, pinned in a plugin lock (#599 part 1, design third-party-plugins-design.md §4.1–4.2), the auto-attached cora server included. On every connect tole hashes the server's live tool manifest (every name, description and input schema: SHA-256 over a canonical, length-prefixed encoding with sorted JSON keys) and its reported version, and registers its tools only when both match the approval in the user lock ($CODECORA_HOME/tole/plugins.lock). A server that is unapproved, changed since approval (a rug pull) or revoked is not registered, with a note naming the remedy; tole doctor lists each server's state. In an interactive terminal session (tole, tole chat, tole run, tole resume on a TTY) tole shows the FULL tool list of each unapproved or changed server before the session starts (control and invisible characters dropped, nothing summarized or cut) and asks; a yes writes the lock entry. Missions, cron, serve and child agents never approve: an unapproved server is unavailable there, so approve it once interactively first. A project lock (.tole/plugins.lock) can only narrow the user lock (pin the same manifest, drop granted secrets, revoke); it never trusts a server or grants a secret. Locks are versioned JSON, read without following a symlink or blocking, size-capped, and an unreadable lock trusts nothing. Approvals and manifest changes are appended to $CODECORA_HOME/tole/plugin-ledger.jsonl (names and hashes only). tole plugin list|approve|diff|revoke follows in part 2. Migration (cora once, missions, cron and CI): docs/third-party-plugins-design.md §8.
    • Migration: approve each MCP server once, cora included: accept the prompt in a terminal session or run tole plugin approve <name>.
  • BREAKING: run_command, job_start and cron scripts get no secrets by default, GITHUB_TOKEN included (owner decision 2026-11-11, #598 part a). A new [secrets] table binds each secret NAME to the tools whose child processes may receive it, e.g. GITHUB_TOKEN = { tools = ["gh", "git"] }; every secret-shaped variable a binding does not grant to the launching tool is scrubbed (ENV-1). The default keeps GITHUB_TOKEN for the gh and git tools and for your own hooks and MCP servers only. To restore it for commands: GITHUB_TOKEN = { tools = ["gh", "git", "hook", "mcp", "run_command"] } under [secrets] in your user config. A project config can only narrow a binding; a widening entry is ignored with a warning naming the remedy. A child session (classic or delegated) now gets only its parent's grant (the secrets it holds that its release binds to some tool), narrowed by a profile's grants. Redaction is unchanged and covers every secret, granted or not. Migration note: docs/secrets-integrations-design.md §9.
    • Migration: to give commands a token, add GITHUB_TOKEN = { tools = ["gh", "git", "hook", "mcp", "run_command"] } under [secrets] in the user config.
  • BREAKING: the session log stores the redacted form (owner decision 2026-11-11, #596; reverses E11's "the durable log keeps the original"). Every entry payload (user and assistant text, tool-call arguments, tool results, errors, every other field) and the pinned system prompt are redacted with the process SecretSet before the line is written, in every form it knows (as is, JSON-escaped, base64, percent-encoded; a secret that is a bare number becomes the marker string). An entry that hid a secret carries "redacted": ["NAME"], names only; the field is absent otherwise. The committed in-memory entry is the same redacted form, and the provider is fed from it, so the log stores exactly what the provider saw and a replay reproduces the request byte for byte. The host installs, as that set, every secret a provider request is redacted with (both providers' keys and URL passwords included); an embedder that installs none gets the process environment's set. Logs written before this load unchanged (append-only, never rewritten): their old lines stay raw, new lines are redacted. /export, the memory-loop summary, handoffs and forks of a new session therefore carry no known secret. A tool still runs with the arguments the model sent; a crash-resumed intent re-runs with the logged (redacted) arguments.
    • Migration: none for new logs; do not expect /export, handoffs or a replay to carry a known secret value, and keep originals outside the log.
  • BREAKING: skill approval is required by default (owner decision 2026-11-11, #591). Without TOLE_SKILL_APPROVAL set, a session loads a discovered skill (<workspace>/skills/, ~/.codecora/tole/skills/) only when its whole directory hashes to the owner's approval; every other skill is listed by name only, as unavailable, and load_skill refuses it. A session with unapproved skills prints one startup note (N skill(s) unavailable until approved (tole skills list; tole skills approve <name> --hash <h>)), and tole doctor reports the same count, or warns when the CodeCora home is unresolvable (then nothing can ever be approved). Cron jobs that name an unapproved skill are blocked (skill_not_approved) with the exact tole skills approve <name> --hash <h> in the recorded detail. --skill <file> and a profile's skills stay ungated (the owner named the file). Migration: run tole skills list, review each skill, then tole skills approve <name> --hash <hash> (scripts must pass --hash); or set TOLE_SKILL_APPROVAL=off in the environment to restore the old behaviour. Only the environment can opt out; no config file can.
    • Migration: tole skills list, review, then tole skills approve <name> --hash <hash>; or set TOLE_SKILL_APPROVAL=off in the environment.
  • BREAKING: child agents (agent_start) no longer inherit the parent's whole environment (#595). They get the ENV-1-scrubbed environment plus only their provider keys (TOLE_API_KEY, OPENAI_API_KEY, TOLE_FALLBACK_API_KEY); non-secret settings (TOLE_BASE_URL, TOLE_MODEL, TOLE_MEMORY*, ...) and GITHUB_TOKEN stay. A child therefore can no longer use an integration whose secret lives only in the parent's environment (TOLE_MCP_<NAME>_TOKEN, SYSTEMONE_API_KEY, web backend header keys). The remaining egress sinks (MCP tool arguments, web_search / web_fetch, systemone, memory loop, uteke_document) follow in part 2.
    • Migration: bind the secret a child needs to a tool in [secrets]; a child gets its parent's grant, narrowed by its profile.
  • BREAKING for embedders (Rust API): tole_core::mcp::register_server_tools takes a &SecretSet and an Admit (the plugin-lock decision); tole_core::memory::remember_session takes a &SecretSet; web::WebFetchTool is no longer a unit struct; tole_tui::TuiHost is footer, run_turn and apply(HostCmd) in place of its eleven methods, with App::on_input(Input) as the key entry point; tole_cli::session_host::{UpdatePlanTool, PlanEmitter, register_gitea, detect_github_repo, github_repo_from_remote_url} moved to tole_cli::tool_roster with no re-export (#525, #526, #595, #599).
    • Migration: pass the SecretSet and the Admit your host decides, use WebFetchTool::default(), implement TuiHost::apply, and import the moved items from tole_cli::tool_roster; docs/migrating-0.11.md has the details.

Added

  • Independent child-process participants for agent-started discussions (#704, follow-up of #701; the owner's tole discuss is unchanged). discuss takes an optional modes array, one entry per participant in order, each inline (the default: a voice with no tools and no process) or reviewer. A reviewer runs as its own consult child of the caller's goal, under exactly the rules of delegate: the profile must be one the caller may seat (its allow list covers the profile's), the budget is carved from the caller's remaining budget (at least 20000 tokens a turn, never added; the discussion also counts the child's spend, so it is charged twice, which only over-counts), and the depth cap, the live-process limit, the machine guard and the lease rules apply. A reviewer launches read-only: --plan-mode (no Write tool exists), an empty allow list (the profile's patterns are not carried over, so neither it nor the caller's allow list can approve anything) and TOLE_DISCUSSION_PARTICIPANT=1 in its environment, with delegate_report as its only Write tool (one capped file, the contribution). A Write a reviewer wants is denied, fail closed, until #714 routes it to the owner's approval surface; nothing goes to the caller's allowlist. A reviewer cannot start a discussion or delegate: a session with that marker gets no delegation host, so no discuss or delegate tool is registered, at any depth. modes is a closed enum (a bad value, a wrong length or any other spelling such as mode, reviewers or independent is refused before anything is carved or started); every other field is still refused, and no secret, allow pattern, profile or budget is added.

  • tole serve --token-file <path> (#682): the bearer token can come from a file (a regular file, no link or FIFO, at most 4 KiB) instead of the command line, where every local process can read it. --token <value> still works and prints a warning; TOLE_SERVE_TOKEN is unchanged.

  • tole doctor reports the process guard (#675): process guard: ✓ non-dumpable when same-user children cannot read tole's /proc/<pid>/environ or memory, ! dumpable otherwise. Linux only; the line names no secret.

  • The nginjen backend for web_search and web_fetch, and tole doctor web lines, part 2 of #625.

    • Configuration: set both NGINJEN_BASE_URL and NGINJEN_API_KEY to use a full nginjen service for both tools.
      • Search is POST {base}/search and fetch is POST {base}/scrape with {url, format}, each with the key as a bearer token.
      • The order per tool: a TOLE_WEB_* backend, then nginjen, then the built-in tools; without web-builtin, the direct fetcher and no search.
      • A base URL that is not http(s) fails startup, naming the variable.
    • The key is sent only to that backend. It is redacted with the process secrets, and no error, spec or doctor line shows it.
    • Fetch through the backend vets the target first and sends nothing if it fails: http(s), no credentials, no known secret, a public host. Formats are markdown (default), compact, text, html and links.
    • Jina: a result the backend produced through its Jina Reader fallback (engine_used: "jina") is discarded with an error. tole never asks for it.
    • tole doctor prints which lane web_search and web_fetch use: built-in, nginjen backend, generic backend, direct fetch or off. It shows names only.
    • Memory: none resident; one HTTP agent per call.
  • Built-in web_search and web_fetch (#625), on nginjen-lite 0.1.0 and tole's own HTTP client, behind the default web-builtin feature of tole-cli. A configured TOLE_WEB_* backend still wins, and a build without the feature keeps today's tools.

    • web_search works out of the box: DuckDuckGo Lite, then Bing, then Brave (keyless; a non-2xx answer moves to the next).
      • The query is redacted with the process secrets and capped at 512 characters.
      • 8 results, each field capped; the answer names the engine and whether it was a fallback.
      • The engines get nginjen-lite's browser-like User-Agent, because they block other agents.
    • web_fetch gains format: markdown (default), compact, text, html or links. compact is shortest but drops the text of inline bold, italic and code and image alt text, so it is not the default.
      • It honours robots.txt (fail-open when robots.txt cannot be read) and sends tole/<version> (+https://github.com/codecoradev/tole).
    • Guards, unchanged and now on every redirect hop: http(s) only, refusal of URLs carrying a known secret, the SSRF check (up front and in the pinned resolver), no https-to-http hop, the content-type allowlist, and the 512 KiB body and 20,000-character text caps.
    • Politeness: at most one request per second per host (robots.txt included).
    • Memory: the robots cache (64 origins) and the per-host pacer (64 hosts) are bounded per tool, with no threads.
    • Dependencies: tole-cli gains 30 crates (nginjen-lite's scraper HTML stack, 4 of them build-time proc-macros); tole-core is unchanged at 58 (--no-default-features). Release binary sizes are in docs/perf.md.
  • The model-facing discussion tools, part 3b of #588 (option (b) of automation-design.md "Entry point", the owner chose both entry points): discuss, discuss_status and discuss_stop, under exactly the rules of delegate. All three are Risk::Write (approved or allowlisted; the prompt shows the question, participants and budget) and are registered only where delegate is, so never at the goal's depth limit. discuss starts a discussion in the background and returns its id; its budget is carved from the caller's remaining budget in the delegation tree (budget_tokens, else half of what is left, never more), recorded as a running consult node, charged what the ledger counted when it ends (a crash is charged the whole carve); at most two run at once per process. Participants must be user-config profiles whose allow patterns the caller's allow list covers (a refusal, where delegate trims) and never a built-in role; they are inline voices with no tools, so none can start a discussion or write. The input has five fields (question, criteria, participants, budget, rounds): any other field is refused and the id is the host's. discuss_status and discuss_stop work only on discussions the same session started (a host-only tree node, not a task string), never the owner's; status text is fenced as data and redacted. A stop is the ledger's own stopped escalation (tole_core::discussion::Reason::Stopped, DiscussionLog::stop), so no participant text can start, prevent or delay it; a discussion whose process died is closed by a stop without a model call or continued by the owner with tole discuss resume. Independent child-process participants for agents are not part of this step.

  • tole discuss start|resume|list|show, part 3a of #588: the owner-only entry point (option (a) of automation-design.md "Entry point"). tole discuss start --question Q --criterion C... --participant P... --budget N [--max-rounds R] [--id ID] [--dry-run] runs a multi-round discussion from a shell. The contract is what you typed: nothing a model wrote. Participants are profiles from your user config, voiced inline and read-only (no tools, no process, depth 0), the budget is a hard cap reserved call by call in the ledger, and a stop at the budget or --max-rounds is an escalation to you, never a silent end. --dry-run validates the contract and shows what it may cost (participants, rounds, most model calls, the cap) without a provider or a write; a real run prints the same plan first and the tokens used at the end. tole discuss resume <ID> continues after a crash or a failed call from the ledger (a finished turn is never run again, the budget is the contract's own) and prints a finished discussion's outcome again; list and show [--json] are the tole audit --discussions view and need no provider or config. Errors are redacted. The model-facing entry point (option (b)) follows under the rules of delegate.

  • tole audit --discussions and tole audit --discussion <ID>, part 2d of #588: the multi-round discussions in the tole data dir, read-only. One discussion shows its goal (question, criteria, participants, budget, max rounds), each round's speakers, summary (a digest's lines, or that it was passed on as written and why), checklist, gate and tokens, and the outcome; never a raw contribution. The logs are read without a lock, without following a symlink and with the ledger's size cap, and nothing is written. Every string is redacted with the process secrets before it is capped (a secret across the cap leaves no prefix), then the whole output is redacted again; --json prints the same as JSON.

  • The discussion's built-in roles, part 2b of #588 (tole_cli::discussion_roles): the scribe and the claim-checker run on the light tier with no tools, no streaming and the fixed instructions of tole_core::discussion. Their model is the light tier of [router.tiers] in the user config, else the run's configured model. The owner may override a role only with [profiles.scribe] or [profiles.claim-checker] in the user config, and only its models: the tier is models.default, else light. An override that resolves to a missing or unknown tier, or that sets a persona, allow list, skills, grants, memory room or advisor, is a load error, never a fallback to the built-in. A project config cannot define profiles, so it can neither override nor widen a role. tole doctor names where each role's model comes from, never the model.

  • Multi-round discussion ledger, part 2a of #588: budget hard stops, crash-safe spend and caps. Still no model call and no command.

    • Every provider call is reserved before it runs (reserve, counted at its estimate) and settled after it (settle, the estimate replaced by what was spent). A call that does not fit what is left of the budget is not reserved: the budget escalation is recorded at once, wherever the round is, and the discussion goes to its closing step, so a spent budget is a hard stop with an escalation, never a silent end. A call a crash interrupted stays counted at its estimate, so a resumed discussion never spends past its budget; open_call and bind let a host find a call that runs elsewhere (a delegated child) and poll it instead of starting it again.
    • A refused digest falls back to the round as written (RoundSummary::Fallback, with a reason of at most 300 characters): only a round big enough for the scribe has one, it holds exactly the round's pass-1 contributions, and it never counts as a round without news.
    • Caps: one record at most 512 KiB, one discussion log at most 16 MiB, written as well as read; the last 128 KiB is kept for the gate and the closing record (its text capped at 16,000 characters), so a full log can still be stopped and closed. The log is read with O_NOFOLLOW | O_NONBLOCK and a size cap checked on the opened file, and neither the log nor its lock is opened through a symlink.
  • Independent participants and uteke round documents for the multi-round discussion, part 2e of #588 (tole_cli::discussion_host, still a library).

    • Independent participants (Driver::with_independent, for review and critique only): a named participant runs as a read-only delegated child (Delegator::consult: mode = consult, as its profile) through the existing delegation tree, so the carve, the depth and live-process caps, the leases and the machine resource guard apply. Its contribution is its completion report, read by the parent with the report caps (O_NOFOLLOW | O_NONBLOCK, size cap) and then passed through pass 1. Its reservation is at least 20,000 tokens, settled at the child's measured usage (its whole carve when unreadable). A child starts at most once: the reservation (the intent) is written before the child starts, the child's task is tagged with that call, and its node id is bound after. A resumed driver polls a bound child; for an unbound intent it looks for the tagged child (Delegator::find_child: direct children of a goal at the root, or of the session's own node in a delegated child, never deeper) and starts one only when there is none, under the same reservation. Delegator::poll_node settles an ended child and drains the queue.
    • uteke round documents (Driver::with_docs, UtekeDocs over uteke_document): flat slugs goal-<id> (contract, status, outcome and checklist) and goal-<id>-r<n> (the digest, or that the round was passed on as written and why), each round created with parent = goal-<id> and naming its parent in the body. Never a raw contribution. Each document is redacted, then capped at 16,000 characters (and redacted again by uteke_document). A document that cannot be written never stops the discussion; it is listed in Outcome::notes, redacted.
  • The multi-round discussion's host driver, part 2c of #588 (tole_cli::discussion_host), a library only: no command and no model-facing tool. How a discussion starts is an open question for the owner, laid out with its security consequences in docs/automation-design.md ("Entry point: open question").

    • Inline participants: the orchestrator voices each dormant profile from its persona file (redacted) with the fixed participant instructions, on the profile's default-tier model; no process, no tools, no streaming. Participants are user-config profiles only, never the scribe or the claim-checker.
    • Per round: every reply passes the pass-1 sanitizer before the ledger records it (a tool call in a reply runs nothing). A big round goes to the scribe, read only through the digest validator; a refused digest or a failed scribe falls back to the round's pass-1 text. The claim-checker's checklist is read only through its parser; an unreadable one meets nothing. The ledger computes the gate.
    • Budget: carve takes the discussion's budget from the goal's pot (never more than is left). Participants, scribe and checker are all reserved before and settled after each call, in the ledger and the pot; a call that does not fit, or max_rounds, ends with an escalation. The closing text is the host's: the outcome, the checklist and the last round fenced as data.
    • Resume: a new driver on the same log continues at the ledger's next step, so a finished turn or round never runs again and a crashed call stays counted.
  • Multi-round discussion ledger, part 1b of #588 (tole_core::discussion_log): the append-only file the discussion's state and its next step are folded from. Still no model call and no command.

    • The ledger ($CODECORA_HOME/tole/discussions/<id>.jsonl, append-only): the state, including what must happen next, is folded from it, so a crash resumes mid-discussion: a torn last line (a step that never completed, even torn inside a multi-byte character) is ignored on read and cut off before the next step is appended, so the next line is never glued onto it. The log is the referee: a contribution only from a participant who has not spoken, a summary only once everyone has, verdicts only after the summary, and the gate's result is computed from the ledger rather than supplied by the caller. The roster may change between rounds within the contract's participants. Every step takes the discussion's lock (a sidecar file) around reading the state and appending, so two writers on one discussion never take the same turn or the same entry id.
  • Multi-round discussion, the pure core, part 1a of #588 (tole_core::discussion, design profiles-collaboration-secrets.md A8.3). No model is called and there is no command yet; the ledger (1b) and the orchestration that calls the participants, the scribe and the checker are built on these parts.

    • Contract: question, 1 to 12 acceptance criteria (the gate checks them), 1 to 8 participants (profile names), a token budget and max rounds (default 4, at most 10).
    • Sanitizer pass 1, deterministic: secrets redacted, control and invisible characters removed, the <<< >>> fence markers neutralized, sizes capped. Applied to the question, the criteria, every contribution and every digest line.
    • Digest (pass 2) validator: a scribe's JSON is read against a fixed schema (decisions, claims, actions, disagreements, open questions, delta). Every line must name a participant of the round and a raw entry of that round written by that same participant; a disagreement needs positions from at least two participants; a participant whose contribution appears nowhere is an error, so dissent cannot be dropped. A round under 2400 characters is passed on verbatim, with no scribe call.
    • Claim-checker verdicts: one per criterion; a criterion called met needs evidence, and every cited entry must exist.
    • Gate, in a fixed order: a pending approval or an owner-only disagreement hands over at once, then a report only when every criterion is met on the checker's evidence, then the token budget, the round limit, two rounds with an empty delta (stalled), else continue.
    • Fixed prompts for the participant (contract, last digest and its own previous turn only), the scribe and the checker, everything between fence markers labelled as data.
  • Run outcomes for the skill curator, part 3b of #593 (closes it). When tole run (and resume) or tole mission ends, how it ended goes to the usage ledger: a success or failure line for each skill the run loaded (RunTracker, noted by load_skill), or one baseline line when it loaded none. The curator's underperformer proposals compare the two.

    • What counts: a settled turn (or a complete mission) is a success; a provider failure, an exhausted step, token or time budget, a blocked stop gate, a loop, an unknown tool, a storage error, verify_failed or an error mission is a failure. A run that stopped for an approval, was cancelled or detached, or a stopped mission is not recorded. chat, serve, ACP and cron agent runs record no outcomes yet.
    • Only where there is something to curate: usage, recalls and outcomes are written only when the user has made a skill draft or has curator state (skill-curator.json), so a plain tole run leaves no file behind. This also keeps test runs from writing into a developer's home.
  • Curator config, schedule and doctor line, part 3a of #593.

    • [curator] in the user config (user layer only; a project's table is ignored and shown as such in tole config check): enabled (default on), stale_days (14), archive_days (30) and grace_days (30), each at most 3650. The pair is validated with the defaults filled in, so stale_days = 30 alone is an error. With enabled = false, tole curator run and the weekly job report what they would do and change nothing; status says why. A user config that cannot be read is reported and the defaults apply.
    • tole curator schedule [--cron EXPR] saves one script job curator-weekly (tole curator run, default 0 4 * * 1, UTC) on the built-in scheduler, zero tokens; unschedule removes it. The scheduler refuses a path-qualified program, so the job runs the bare tole found on the scheduler's PATH, and schedule warns when tole is not on this PATH. It runs when the scheduler ticks (tole serve --cron, or cron(8) calling tole cron tick).
    • tole doctor gains a curator: line (off, or on with the schedule or a hint to run tole curator schedule), and tole curator status shows the schedule.
  • uteke_document takes an optional parent (#576): the slug of an existing uteke document to nest the new one under, passed as uteke doc create <slug> --parent <parent> --file -. It is checked like a slug ([a-zA-Z0-9-], not starting with a hyphen) before anything is spawned, shown in the approval line (uteke doc create <slug> under <parent> (linked to room <r>)), and a blank value means none. An unknown parent or a tree deeper than 10 is uteke's own error, shown unchanged. This is what the multi-round discussion's round digests (#588) nest under their goal.

  • tole curator, part 2 of #593: the owner's side of the skill curator, on top of the part 1 core.

    • tole curator run [--dry-run] assesses every skill the curator manages (promoted from a draft, or adopted) and archives those unused past the thresholds (stale after 14 days, archived after 30, 30 days of grace for a skill never used). The whole package moves into $CODECORA_HOME/tole/skill-archive/ with a mutation-ledger entry; a symlinked skill is refused and reported. Pinned skills, skills a live cron job names with --skill NAME and skills the curator does not manage are never touched. Skills whose success rate is 0.2 or more below the runs that loaded no skill are listed as proposals, never acted on. One sweep runs at a time (a lock file, taken over when 10 minutes old).
    • status, pause and resume (a paused curator changes nothing), restore <name>, pin/unpin, lock/unlock (a locked skill takes no skill_propose draft) and adopt/unadopt (put a hand-written skill under curation).
    • Usage is recorded: each successful load_skill is a loaded line in skill-usage.jsonl, and each skill the uteke index recalls for a task is a recalled line. A recall alone never keeps a skill alive. The ledger is host bookkeeping under the CodeCora home, not a workspace write.
    • Not in this part: outcomes per run, the [curator] config table and the weekly schedule (part 3).
  • Skill curator core, part 1 of #593 (tole_core::skill_curator, design skills-registry-design.md §4.5, §6.4): the deterministic, LLM-free part of keeping the library small. No command or config key yet (part 2).

    • Usage ledger skill-usage.jsonl (append-only): recalled, loaded, success and failure per skill, and a baseline for runs that loaded no skill. A recall alone is not use. A malformed line is skipped; past 8 MiB only the newest lines are read.
    • Lifecycle, derived and never stored: active to stale after 14 days without a load or outcome, to archived after 30 (Hermes' defaults), a 30-day grace for a skill never used, and no assessment at all for a pinned skill, a skill a cron job names, or a skill that is not agent-grown or adopted. archive_days must exceed stale_days.
    • Underperformers: a managed skill whose success rate is 0.2 or more below the baseline of skill-less runs, with at least 5 outcomes on each side, is listed for the owner. A proposal, not a verdict.
    • Package-aware archive and restore: the whole directory moves (references/, scripts/, assets/ with SKILL.md), with the package hash before and after in an append-only mutation ledger; a move and its ledger line go together (when the ledger cannot be written the move is undone); restore refuses a taken place or a copy that changed since. A symlink or bad name is refused. skill_approval::read_dir_package reads a package by directory.
    • Curator state (paused, pinned, locked, adopted) in skill-curator.json, written atomically.
  • tole skills drafts promote and revoke, part 3 of #592 (closes it): the owner turns a draft into a skill, and can take back what grew from a poisoned source.

    • promote <id> shows the draft, then asks (without a terminal, --hash with the content hash show printed is required). It refuses a decided draft, a draft whose SKILL.md no longer matches its proposed hash, a name already in use, a tainted draft without --accept-taint, and a draft close to an existing skill unless its verdict is new (verdict conflict is never promoted; patch and reference mean fold it into that skill by hand, then reject the draft). It writes SKILL.md exactly as proposed into <workspace>/skills/<name> (--workspace) or the user-global skills dir (refused when that dir is a symlink), approves the package hash only if the new directory holds that one file and nothing else, records where it went on the draft and indexes the skill when a uteke index is configured.
    • revoke <session-or-draft-id> rejects the source's pending drafts and withdraws the approval of each skill promoted from it, when that skill's approval is still the promoted one. A skill the owner re-approved since is left alone and reported. The skill stays on disk.
  • skill_propose and tole skills drafts, part 2 of #592 (design skills-registry-design.md §4.4): an agent grows the skill library only by writing a draft, and the owner reads it.

    • skill_propose (Write tier, so each call is approved; a session face's tool, never a child's, a cron run's or a plan-mode session's) takes name, skill_md, trigger (owner_correction, dead_end, repeated_workflow) and optional extra sources; any other field is refused. The host adds the session id (server faces), the model, the taint and the meaning dedup, so none of them can be set from the input. A blocking finding refuses the call and stores nothing; the refusal names the rules and never quotes a secret.
    • Taint is recorded at the turn loop's execute funnel (ToolRegistry::set_taint_tracker): a session that ran web_fetch, web_search, an mcp_* tool, gh, gitea, a child-agent or session tool (agent_*, delegate*, tole_session_*) or uteke_recall/uteke_document marks every draft it proposes as tainted, failed calls included. The tool taint is recomputed from the session's own entries at the start of every turn, so a resumed session keeps the taint of what it fetched before and a registry reused for another session (/new, /resume) never carries the wrong session's taint; marks the host sets directly are kept. read_file and run_command are not counted (every coding session uses them, and --accept-taint would become a reflex): a page fetched through curl in run_command does not taint.
    • Dedup asks the uteke skill index (TOLE_SKILL_INDEX=uteke) for the nearest skill and proposes patch (>= 0.92), reference (>= 0.80) or new; without that index the result says dedup did not run.
    • tole skills drafts [list|show|reject|verdict]: list shows the pending drafts (--all for the rest) and marks tainted ones, show prints provenance, taint, warnings and the proposed SKILL.md followed by the nearest skill, reject closes a draft, verdict patch|reference|new|conflict records a reviewer's call. Everything a model wrote is printed with control and invisible characters escaped. Nothing here makes a skill loadable; promotion is the next step.
    • Known gap: a CLI face (run, chat, mission) builds its tools before the session id exists, so its drafts record no session id yet; tole serve and ACP sessions do.
  • Skill drafts, part 1 of #592 (tole_core::skill_draft, design skills-registry-design.md §4.4, §6.3): the gate and the store that skill_propose will use. No tool or command yet.

    • Gate: a proposal is refused on a blocking finding and nothing blocking is ever stored: bad frontmatter or name, an empty description, a body over MAX_SKILL_CHARS, more than one top-level heading, more than 3 references/ scripts/ assets/ files, three or more dated lines (an incident log), a known secret value or a token-shaped string (the finding never quotes it), an instruction-override phrase, or invisible and bidi characters. Risky shapes (| sh, ~/.ssh, ...) are stored as warnings.
    • Drafts live in $CODECORA_HOME/tole/skill-drafts/<id>/ (draft.json + SKILL.md), outside every skills directory, so nothing can load one. A draft is never overwritten and is decided once (rejected or promoted).
    • Provenance on each draft: source session ids, trigger (owner_correction, dead_end, repeated_workflow) and model. Taint: a TaintTracker records the untrusted tools a session used (web_fetch, web_search, mcp_*) and a draft from such a session is marked tainted.
    • Dedup bands from a similarity score (0.92 patch, 0.80 reference, below that new); only a reviewer's verdict can say conflict, since similarity cannot see negation.
  • consult_advisor in runs, part 2b of #587: a run whose profile declares models.advisor can consult that model on a hard decision.

    • Where: tole mission, a delegated child (a mission, so only when its own profile declares an advisor) and cron agent runs. These are the faces with a token budget the advisor can share. run, chat, the TUI, serve and ACP have none, so the tool is not registered there; there is never an uncounted advisor. The tool is ReadOnly, so plan-mode runs keep it, under the same cap.
    • What it sees: the task contract (the profile and the mission goal or job prompt), the executor's question, and the last 12 transcript entries. The entries come from an in-memory copy of what the turn loop sends the run's provider, never from a file. Everything is redacted, neutralized and capped (tole_core::advisor::request).
    • The call: one request on the advisor model, on the run's provider connection with no fallback chain (a fallback would be another model). It sends no tools and does not stream.
    • What it returns: only the parsed verdict (plan, correction or stop, plus capped text), fenced as advisory data, with the use number and tokens. An advisor that answers with a tool call gets an error, and nothing runs.
    • Budget:
      • The run's token budget is shared: the mission's provider, or the cron job's meter, charges each step, and the advisor charges its call.
      • A consultation the budget cannot fit, or past advisor_max_uses, is refused before any call.
      • What a call spent is counted even when it fails, and written to the session as a usage record with "role": "advisor". A resumed mission and a cron job's reported tokens and daily cap therefore include it.
  • consult_advisor on the host side, part 2a of #587: the new module tole_cli::advisor_host. No run registers the tool yet; part 2b wires it into missions, delegated children and cron runs.

    • ConsultAdvisor (ReadOnly): one advisor call per consultation, with no tools, no streaming and no fallback chain.
      • The request is built from the task contract, the question and the window, redacted, neutralized and capped (tole_core::advisor::request).
      • It returns only the fenced verdict from parse_reply, the use number and the tokens. An advisor's own tool call is answered with an error, and nothing runs.
    • Window: Tap wraps the run's provider and keeps, in memory, the last 12 entries of each transcript the turn loop sends; no file is read. With charge, it also charges each step to the run's shared Budget.
    • Budget: a consultation that the budget cannot fit, or past the cap, is refused before any call and without spending a use. What a call spent is charged and queued even when it fails.
    • record_usage writes the queued usage to the session as usage records tagged "role": "advisor".
  • Advisor tier, part 1 of #587: the core seam, the profile key and doctor lines. No run consults an advisor yet; consult_advisor comes in part 2.

    • tole_core::advisor (no I/O, builds with --no-default-features):
      • request builds the advisor call: a fixed system prompt, then the task contract, the last 12 transcript entries and the executor's question. Each is redacted with the process secrets, neutralized and capped before it is fenced as data.
      • parse_reply reads only a verdict (plan, correction or stop) and capped text, so a reply cannot name a tool, grant or budget for the host to act on. A reply without a verdict word is a plan, never a stop. Verdict::fenced hands it back as advisory data.
      • Uses caps consultations per run. Budget is the run's token budget shared with the advisor, so advisor tokens come out of it. usage_value tags usage "role": "advisor".
    • profiles.<name>.advisor_max_uses (default 3, 1 to 20) is refused without models.advisor, and a blank models.advisor is refused.
    • tole doctor names the profiles with an advisor and their caps, never the model.
  • Model routing wired into runs, part 2 of #586. Off unless the user config says [router] enabled = true; with routing off nothing changes.

    • Where: a new tole run, tole chat, TUI session, tole mission, delegated child (a mission with TOLE_AGENT_DEPTH of 1 or more routes as delegate) and cron agent run is routed once, before its first provider call. Never per turn: a resumed session or a continued cron run keeps its model.
    • An explicit model wins: a session that already has a model (/model, ACP) and a cron job with a --model pin are not routed.
    • What changes: the routed model is stored as the session's fact/model, and the decision (tier, model, source, reason, redacted then capped) as fact/route. The run's budget, allow list, plan mode and secrets are untouched; the tools sent to the provider are the same.
    • The brief:
      • the task text: the prompt or goal; a cron run uses the job's own prompt, never a webhook payload;
      • the highest risk among the run's tools (new ToolRegistry::max_risk);
      • the profile, the job's name and the token budget.
    • A broken router (an undeclared tier, an unknown profile) stops run, chat, the TUI and mission before the session file exists, and fails a cron run with the remedy, before any provider call.
  • Model routing config, dry run and doctor, part 1b of #586. Nothing routes runs yet: part 2 wires the router into runs, cron runs and delegated children, off by default.

    • [router] in the user config:
      • enabled (off unless true), allow_tiers, [router.tiers] (the models of runs without a profile; a profile resolves through profiles.<name>.models) and [[router.rules]].
      • Rule conditions: kinds, min_chars / max_chars, min_risk / max_risk, profiles, jobs, budget_below and keywords.
      • A rule without profiles applies only to runs without a profile, and resolves its tier through [router.tiers]. A rule with profiles applies only to those profiles and resolves through profiles.<name>.models.
      • At most 64 rules and 32 keywords per rule; rule names are unique.
    • A matching rule replaces the configured model, whether it comes from TOLE_MODEL (or another provider variable), the config's model or the profile's default tier. Only an explicit choice is never routed: a session's own model (/model, ACP) and a cron job's --model pin. No match keeps the configured model.
    • Load-time errors with a remedy: an unknown tier, kind or risk, a rule whose tier is not declared where it resolves, or an unknown profile. There is never a fallback to another model.
    • A project config can only set enabled = false or narrow allow_tiers. Its tiers, rules and enabled = true are ignored with a warning.
    • tole route PROMPT [--kind K] [--risk R] [--job J] [--budget-left N] (with the global --profile) prints the tier, model and reason a run would get. It also prints the configured model and its source (for example from env TOLE_MODEL), which a matching rule replaces. It is a dry run that calls no provider, and its output is redacted.
    • Visibility: tole doctor shows the router's state, rule names and tier names, and fails on a broken router. config check shows names only, never models or keywords.
  • Model routing by task weight, part 1a of #586: the Router seam and the rule baseline in tole-core. Nothing routes yet. The [router] config, tole route and doctor lines come in part 1b; wiring into runs, cron runs and delegated children comes in part 2, off by default.

    • tole_core::router (platform-agnostic, no new dependency, builds with --no-default-features):
      • Router returns a Route with a tier (light, standard or heavy), its source and a reason. It never returns a model name, a budget, an allow list or a secret.
      • RuleRouter is deterministic. Every matching rule is a candidate, the cheapest tier wins, and among rules of that tier the first declared one names the route.
      • An allowed-tier set can only narrow the pick. No match keeps the configured model.
      • RuleRouter::check refuses, with a remedy, a rule whose tier is not declared where it resolves, or an unknown profile.
      • Route::model errors on an undeclared tier, never falling back to another model. Route::record redacts with the process secrets, then caps at 300 characters.

    Design: docs/profiles-collaboration-secrets.md A9.3.

  • tole hook add|list|remove|test, part 3 of #582 (built with the shell-tools feature, like tole cron).

    • add ROUTE appends one [hooks.ROUTE] section to the user config and never touches a project config. It keeps the rest of the file, comments included, and replaces it atomically. It refuses an existing route, and it checks the new route with the loader tole serve uses before writing.
    • Keys: add needs exactly one key source, --key-env NAME or --key-file /absolute/path. No flag takes the key itself, and no tole hook output shows a key. list does not show where a key comes from either.
    • Hand-edited only: allow_writes, insecure_loopback and [hooks.ROUTE.filter] have no flag. They stay a manual edit of the user config (design P8). The other keys have flags: --job, --event (repeatable), --template, --rate-per-minute and --max-body-bytes.
    • list shows each route's job, events, filter shape (paths and operators, not values), writes: yes|no and whether it is signed.
    • remove ROUTE cuts that route's sections, its filter included, and keeps everything else. A route written another way (an inline table) is refused with "edit by hand".
    • test ROUTE [--payload FILE] [--event E] is a local dry run. It signs the payload with the route's key and checks the signature. It applies the events allowlist and the filter, then prints the fenced, redacted and capped context the fired run would see. It fires nothing and records nothing.
    • --fire --url http://127.0.0.1:PORT sends the signed delivery to a running tole serve, which takes it through the real claim path. Only loopback http:// URLs are accepted.
  • Webhook routes fire cron jobs, part 2b of #582. tole hook comes in part 3.

    • New route keys: cron_job, events, [hooks.<route>.filter], template and allow_writes, compiled when the route loads. A bad value stops tole serve, naming the route.
    • Before any LLM work, for a verified, first-seen delivery: the events allowlist (X-GitHub-Event / X-Tole-Event), then the JSON body, then the filter. A miss is 200 ignored.
    • A match fires cron_job through the same claim path as tole cron run: the trust check from #640, delivery, provider, skills, the daily cap, and the job's model, budgets and allowlist. It answers 202 with the fire id once the run is claimed. A paused, running, blocked or out-of-budget job gets 409.
    • The fired run gets the rendered template as fenced untrusted data appended to its prompt, for that run only. It is ReadOnly by default (its Write tools are absent) unless the route says allow_writes = true.
    • Filters: contains is a substring match on a string and a whole-element match on an array.
    • tole-cli API: cron::claim_now, cron::tick::Trigger, Claimed::with_trigger / fire_id, and run_agent takes a trigger.
  • Webhook filters and templates, part 2a of #582: the new module tole_cli::hook_filter. Routes start using it in part 2b, where it runs before any LLM work.

    • Filters: equals, contains, in, regex and exists on a dot.path, joined by all, any and not. Each node has exactly one operator, and a tree is at most 8 deep and 64 nodes.
    • Regex uses regex-lite, which does not backtrack. A pattern is at most 256 bytes and its compiled program at most 32 KiB, and a string over 16 KiB is never scanned.
    • {dot.path} templates render scalar values only. Each value is neutralized (control characters and fence markers), redacted with the process secrets, then capped at 1024 characters; the whole rendering is capped at 8 KiB.
    • fenced wraps the rendering as untrusted data, and event_allowed applies a route's events allowlist.
    • New dependency: regex-lite 0.1, in tole-cli only. It has no dependencies of its own, so tole-cli goes from 207 to 208 unique crates, and tole-core stays at 50 (--no-default-features).
  • Webhook signature checks in tole-core, part 1a of #582. Nothing serves webhooks yet; POST /hooks/<route> on tole serve follows in the next part.

    • New module webhook: hmac_sha256 (RFC 2104, built on the sha2 crate already in the tree, so no new dependency), ct_eq, sign and verify.
    • verify accepts two schemes:
      • native: X-Tole-Timestamp and X-Tole-Signature: sha256=<hex> over <timestamp>.<body>, within ±300 s;
      • GitHub: X-Hub-Signature-256 over the body.
    • Every delivery needs an id (X-Tole-Delivery / X-GitHub-Delivery, 1 to 128 of [A-Za-z0-9._:-]). A refusal (Reject) gives a status and a reason, never a header value.
    • The ledger's hook_seen fold keeps seen deliveries for 7 days, so its memory is bounded. The new LedgerState::hooks_since(route, since) counts a route's deliveries from the log, so a rate limit built on it survives a restart. LedgerState::hooks_tracked reports how many are kept.
  • Per-job time zones for cron, part 2 of #580.

    • tole cron create|edit --timezone takes UTC, a fixed offset like +07:00 or an IANA name like Asia/Jakarta. The schedule then runs on that zone's wall clock: 0 9 * * * stays 09:00 local across DST changes.
    • A local time that DST skips runs once, right after the gap. A local time that happens twice runs once, the first time. @every is a plain duration and ignores the zone.
    • tole cron list shows each job's zone and its next run in local time and UTC, for example 2026-01-01 09:00 Asia/Jakarta (2026-01-01 02:00Z). create and edit print the next run the same way.
    • A run of a zoned job records its zone, its UTC offset and its DST case (gap or first_of_two) in the fire record.
    • Two new user-config keys (a project config cannot set either):
      • cron.timezone: the zone of a job created without --timezone. Existing jobs and edits never gain one.
      • cron.tz_source: where IANA names resolve. system is the default on unix: the host's zoneinfo, read at run time ($TZDIR honored), with no zone data in the binary. offset-only takes only UTC and fixed offsets.
    • A name the source cannot resolve, a malformed offset or a path-like name is refused on save with the remedy, never silently treated as UTC. A job without a zone keeps plain UTC and writes the same records as before.
    • tole-core API: cron::Zoned, Ledger::open_with_zones, ledger::{Zones, FireZone}, Fire::tz, and JobState::schedule is now a Result<Zoned, String>.
  • Time zones, part 1 of #580: the new tole-core module tz. Schedules do not use it yet; part 2 brings per-job time zones and tole cron --timezone.

    • A Zone is UTC, a fixed offset (+07:00, at most 14 hours) or zone rules read from TZif bytes (RFC 8536, versions 1 to 4, including the POSIX TZ footer that modern zoneinfo files use for future dates) or from a POSIX TZ string.
    • Zone::from_local maps a wall-clock time to one instant, to the first instant after a DST gap, or to both instants of a DST overlap.
    • Zone data comes from a replaceable ZoneSource: OffsetOnly (no data; every IANA name is refused with the remedy) or ZoneinfoDir, which reads the host's /usr/share/zoneinfo at run time. A ZoneinfoDir follows the directory's own alias links, but never one that leads out of it; it does not wait on a FIFO and caps a file at 512 KiB.
    • Nothing is embedded and there is no new dependency. Invalid names, offsets and TZif data are errors with a remedy, never a panic, and leap-second (right/) zones are refused.
  • Parked cron runs resume after an approval (#581). Under tole serve --cron, an allow on a cron run's parked Write (POST /approvals/{id}/decision) continues the run: a new resume ledger record claims the continuation (at most once per parked run, only for a run that settled awaiting_approval; the fold ignores any other resume line), the run's session is reopened and its parked turn resumed without a new prompt, and the approval lets exactly the approved call run once. An allow does not run the call by itself: the resumed model plans again from the denial, and the approved call runs only if the model makes that same call again (same tool, same input). If it does something else, the approved call never runs, and the run settles on whatever the model does instead. The continuation runs under the job's model pin, step budget, token budget and time limit (each counted for the continuation alone), settles and delivers like any run with its own done, and reports only its own tokens toward the daily cap; the parked done stays. JsonlStorage::open now opens a session file once and replays, repairs and appends through that one handle. On unix it no longer follows a symlink at the session file, its .lock sidecar or compaction's temp file, and it no longer waits on a FIFO. Every platform requires a regular file. The new JsonlStorage::open_bounded also caps the size on the handle, and a cron resume uses it. Nothing is auto-approved: a denied or expired approval parks the run again. Script jobs, runs parked by a standalone tole cron tick, approvals lost with a server restart and runs whose session already ended are not resumable (re-run the job). Design: docs/automation-design.md §5.

  • tole plugin list|diff|approve|revoke (#599 part 2), without starting a session. list shows every configured or locked MCP server with its state (approved, changed, unapproved, revoked), version, manifest hash, approval date and lock (user, project), --json too. diff <name> compares the approved manifest with the live one tool by tool (added, removed, changed description, changed schema). approve <name> shows the full live tool list and needs a terminal yes or a matching --hash (the refusal shows the text to review); --project also pins it in .tole/plugins.lock. revoke <name> marks it revoked (asks, or --hash with the locked hash), writes a revoke ledger line and names the granted secrets to rotate. Every printed string is redacted with the process secret set, then made terminal-safe. Lock format version 2: an approval stores a per-tool snapshot (exact description and schema hashes; text redacted, terminal-safe and capped, 8 KiB per field and 128 KiB per server, so the lock stays under its read cap); a version 1 entry has none, and diff then shows the live list in full and says so. list and diff flag a stdio server whose binary no longer matches the hash recorded at approval (reported, not enforced at connect). A lock that does not read safely is never written.

  • Plugin lock library, part 1a of #599 (design third-party-plugins-design.md §4.1–4.2; no behaviour change yet). New tole-core module plugin_lock: the versioned lock format (plugins.lock: source, exact version, integrity hash, tool-manifest hash, granted secrets, sandbox profile, approval date, revoked), read without following a symlink or blocking and size-capped, failing closed when unreadable, malformed or newer; manifest_hash, SHA-256 over a canonical, length-prefixed encoding of every tool's name, description and input schema (sorted tools, sorted JSON keys) so moving text between fields or tools always changes it; effective, where a project lock can only narrow the user lock (never trust a server or grant a secret); admit, the connect-time decision that only an exact manifest and version match passes; and the audit ledger_line. The MCP client now lists each server's version and full input schemas, and register_server_tools takes a guard that sees the whole live manifest before anything registers. The CLI passes an open guard until part 1b enforces the lock.

  • Delegation, part 5 of #585 (closes it): tole audit [goal] [--json] prints this workspace's delegation tree read-only: the goals, or one goal's nodes with profile, mode, status, depth, budget carve against measured and charged use, allow list with dropped patterns, lease paths, report summary and reason. It reads only the delegation log in the data dir (no lock, no repair, nothing written, no network) and nothing from the children's agent dirs; the task is one capped line, summaries and reasons are capped, control characters are dropped, and every string is redacted through the process SecretSet.

  • Delegation resource guard, part 2: delegate and delegate_poll now run the machine resource guard before every delegated launch (both spawn levels share the drain). A spawn the guard holds back is queued, never failed, and the queue stays strictly FIFO. A machine-wide registry (<data dir>/delegation/machine.jsonl) counts the live delegated children of every session and goal by lease, so a dead child frees its slot. Replies carry queued_reason and waited_secs for each queued spawn, delegated children start at child_nice, and tole doctor prints the headroom against each threshold and warns about a spawn queued longer than 10 minutes.

  • Delegation, part 4 of #585: the completion report. A delegated child gets the harness-owned delegate_report tool (added to its allow list like handoff_submit) and hands in ONE report (summary, files changed, diff ref, checks run, open risks; each field capped, control characters escaped, at most 64 KiB) to its agent dir, created new and never through a symlink. The parent reads it when it settles the child, on delegate_poll or, for a child whose process is gone, on the next delegate (no longer interrupted): through a plain agent dir only, size-capped before parsing, cleaned again, and records it in the delegation log itself. A complete report makes the run done; none, or an incomplete, oversized, symlinked or invalid one, leaves it incomplete with the reasons. delegate_poll shows the report fenced as untrusted data. Every file the parent reads from a child's agent dir (report, session files, and agent_poll's pid, meta, log and handoff) is opened non-blocking without following a symlink and must be a regular file, so a FIFO planted there cannot freeze the parent.

  • Delegation resource guard, part 1 (owner requirement: delegation must not overload or crash the server): new tole-core module resource_guard. Thresholds::admit answers Go or Wait { reason } (a queue decision, shown as queued: memory 612 MB free < 1536 MB needed) from a Probe and a machine-wide census: live delegated children across all goals and sessions (machine_max_live, default max(2, CPUs)), the gap since the last start (spawn_interval_secs, 2), free memory over a floor plus a reserve per child still ramping up (min_free_memory_mb 1024, child_memory_mb 512; cgroup v2 memory.max minus the working set (memory.current less inactive_file of memory.stat, so reclaimable page cache counts as free) when a limit is set, else MemAvailable, the smaller headroom wins), load per CPU (max_load_per_cpu, 1.5), free process ids (min_free_pids_percent, 10; cgroup pids.max else pid_max against the threads in /proc) and free disk for an unprivileged user on each checked path (min_free_disk_mb, 2048; statvfs f_bavail). An unreadable probe is skipped with one startup note. apply_child_nice starts a child at niceness child_nice (10). The eight thresholds are [delegation] keys of the user config only, bounded. The delegate tool, the machine-wide live registry and the tole doctor lines are wired in part 2.

  • Delegation, part 3 of #585: the CLI faces (run, chat, mission) get the delegate / delegate_poll tools over tole_core::delegation. delegate {task, profile?, mode?, budget?, allow?, role?, consumes?} carves the child's budget from the session's node and starts it as tole mission with that carve as --max-steps/--max-minutes/--max-tokens, optionally --profile, with --allow = parent ∩ profile; the child keeps its provider keys plus the parent grant ∩ the profile's grants. An execute child takes a write lease on the canonicalized directory it works in, checked before it spawns. A child gets the tool again only while above the goal's depth. delegate_poll charges a settled child its measured session usage (its whole carve when unreadable); until the completion report lands, an ok child settles incomplete. Past max_live_processes spawns queue and start on a later delegate or poll, strictly in log order (a queued writer waits for its workspace lease; an exited, unreaped child frees its slot). The delegation log and its queue live in the tole data dir (<codecora home>/tole/delegation/<workspace hash>/), outside every workspace, and the fold ignores any spawn record that breaks a cap (parent, depth, allow, budget, consult rule). agents::agent_dir now refuses ids that are not one plain path component, and child_env::delegation refuses node ids with a leading, trailing or doubled dot. Known limit: the root session's own usage is not measured, so it sits outside the goal budget.

  • Delegation, part 2 of #585: the launch contract and limits the delegate tool (next PR) builds on, inert until then. New user-config table [delegation]: max_depth (1–3, default 2), max_live_processes (default 8), goal_budget, goal_steps, goal_minutes (user layer only; a project config's is IGNORED, out-of-range values are config errors). The child launch contract carries a delegated child's real depth and its log and node id (TOLE_DELEGATION_LOG, TOLE_DELEGATION_NODE), and agent_start takes launch options (subcommand, depth, secret names to keep) for a delegating host. A delegated child takes its allow patterns and trust presets ONLY from its flags (the parent's parent ∩ profile); its profile's allow, the config's allow/trust and TOLE_TRUST are ignored. The ledger file store moved from cron::store to ledger_file (still reachable as cron::store) so non-cron hosts can use it.

  • tole cron closing part (#579): agent jobs take --skill (repeatable; a skill name found from the workdir or a SKILL.md file) and --profile NAME on create and edit, both validated on save and again before every run (a skill that is gone or a profile no longer in the user config records the run blocked, no tokens spent). Saving pins each skill's content hash (job and profile skills); a run whose skill changed since is blocked (skill_changed) until cron edit --skill/--profile re-pins it, and under TOLE_SKILL_APPROVAL=required a skill named by name must be owner-approved (skill_not_approved). A profiled run gets the profile's persona and skills in its system prompt, its model (below the job's --model pin), its memory room (when TOLE_MEMORY=uteke), Writes auto-approved only when both the job's and the profile's allow lists cover them, and no secret grants. New user-config key cron.max_concurrent (1 to 64, default 4) for tole cron tick and the tole serve --cron ticker; tole cron status shows it.

  • Delegation core, part 1 of #585 (epic #583): new tole-core module delegation, an append-only, auditable tree of one goal (the orchestrator at depth 0, delegated profiles below). A child's tokens and steps are carved from its parent's remaining budget (a running child keeps its whole carve reserved; a settled one is charged what its subtree spent) and its deadline never passes the parent's, so any number of children share one pot. Depth defaults to 2 and can never exceed 3. The child allowlist is parent ∩ profile plus every deny; a consult node cannot spawn an executor or write. An execute node takes a write lease per path (same path, ancestor or descendant conflict; the first in log order wins). max_live_processes only queues. An ok run settles done only with a completion report (summary; changed files need a diff ref and the checks run) and no unsettled children, else incomplete. Unknown usage is charged in full: a dead child is charged its whole carve unless the host measured less, a budget stop its whole carve, and a node's reported own spend can only grow; only a child that never started refunds everything. Recovery settles dead processes interrupted and queued orphans cancelled; render_tree prints the audit view. Not wired yet: the delegate tool, tole audit and the profile wiring follow.

  • Approved-hash skill loading (#591, epic #589): with TOLE_SKILL_APPROVAL=required a discovered skill loads only when its package (SKILL.md plus every other file of its directory) hashes to the owner's approval in $CODECORA_HOME/tole/skill-approvals.json; any other skill is listed by name only as unavailable, load_skill and skill_search never return its text, and the loaded body is parsed from the hashed bytes. New tole skills approve <name> [--hash], revoke and list (status, hash, approval time). New tole-core module skill_approval (Gate, Approvals, read_package); skill_index::select and SkillSearchTool take a Gate. The default off keeps today's behavior; --skill and profile skills are not gated.

  • Skill index seam, part 1 of #590 (epic #589): new tole-core module skill_index. The SkillIndex trait (search(query, filter, k), upsert, retire) has two adapters: LocalIndex (the skills directories, lexical match; the fallback without uteke) and UtekeDocIndex (uteke doc, slug skill-<name>, tag skill, metadata name / description / profiles / status / sha256: content hash; semantic search, so the similarity floor is a cosine; only approved entries in scope for the profile are returned). select builds a task's list: a pinned core of at most 5 plus the top K (default 5, at most 10) above the floor; fewer or zero is fine, and an index failure is a note, not an error. RecallQuery is built from the owner-written brief plus the profile role only. The ReadOnly skill_search tool searches on demand. The index only finds names: descriptions and bodies always come from the local skill files, and a name with no local skill is dropped. Also skills::skill_file, and a sha2 dependency (already in the tree via rmcp). Nothing uses the seam yet; the session wiring and tole skills follow in part 2.

  • Skill recall in sessions, part 2 of #590: opt-in with TOLE_SKILL_INDEX=uteke (TOLE_SKILLS_PINNED, TOLE_SKILL_RECALL_K, TOLE_SKILL_FLOOR; an invalid value fails startup). run lists the pinned core plus the skills recalled for its prompt; chat, resume and the TUI list the pinned core; all of them get skill_search. The default local keeps today's full listing unchanged, and uteke without the binary falls back to it with a note. New tole skills index|retire|search maintains and inspects the uteke index (index sends name, description, status and content hash, never the body). Not included: config / profile keys for these settings (after #584), one parent document per category (#576), recall per delegation and discussion participant (#585, #588), the mid-task note for new skills (#592), and the token-matched eval.

  • Dormant profiles (#584, epic #583): [profiles.<name>] tables in the user config (a project config's [profiles] is ignored with a warning and marked IGNORED in tole config check) carry a persona file (system_prompt_file), an allow list, skills, a memory_room (default profile-<name>), grants (secret NAMES only; a value-shaped entry is a config error) and [profiles.<name>.models] tiers light / standard / heavy / advisor with a default (standard unless set; it must name a set executing tier). The global --profile <name> selects one for any session command (run, chat, resume, mission, serve, acp, mcp, tui): its values form one layer between the per-key flags and the environment (per-key flag > profile > env > config > user config), the default tier's model replaces the provider triple's model (it beats TOLE_MODEL), the persona replaces the system prompt (for mission, the default base prompt), and the memory loop uses the profile's room unless a child agent's mailbox room is set. Dormant by construction: resolving a profile reads only its own persona file (64 KiB cap) and starts nothing. An unknown name fails startup and lists the defined ones. tole-cli API: new profile module (Profile::resolve, Profile::granted), config::{ProfileConfig, ModelTiers}, config_apply::Source::Profile, Flags::profile, Settings::memory_room, Settings::fill_with_profile, config_apply::profile_system_prompt; mission::MissionConfig gains persona. Not included: tole cron create --profile (the cron CLI landed separately), tole config check --profile, and the use of tiers other than default (routing #586, advisor #587) and of grants (#585, #598).

  • TUI keybinding config (#463, part 4 and last: closes the issue). [tui.keys] in the user config rebinds ten convenience actions (toggle_tools, toggle_reasoning, model_picker, cycle_model, cycle_thinking, newline, queue_follow_up, pop_queue, history_prev, history_next), each to one key spec or a list (ctrl+o, alt+enter, shift+tab, f5, case-insensitive); an action that is not listed keeps its default, and the default keymap is exactly the keys the TUI always had. Never rebindable: typing (every bare character), y / n at an approval prompt, Esc, Ctrl+C, Enter, Backspace and Tab; a binding needs Ctrl or Alt (or is a function key), and keys a terminal cannot tell apart (Ctrl+I/M/H/[, Ctrl+digit) or reserves (Ctrl+S/Q/Z/) are refused. At an approval prompt and in a picker the keymap is not consulted, and the dispatcher also refuses to map the protected keys whatever the table says. An unknown action, bad or protected key, or one key on two actions makes the TUI use the whole default keymap with one startup note (never an abort); tole config check shows the result or INVALID: ... (not validated: this build has no TUI without the tui feature). A project config cannot set keys (same single startup warning and IGNORED mark as the theme), and there is no env var. The footer hint and the [+n lines] marker show the effective binding. Behavior changes: at an approval prompt only plain y / n answer (before, Alt+Y / Ctrl+N did too); Shift+Enter and Alt+Enter never send even when unbound; Ctrl+Alt+ no longer acts as Ctrl+; the /model and /thinking menu descriptions no longer name a key. tole-tui API: new Keymap, KeyAction, KeySpec, App::with_keymap, defaulted TuiHost::keymap; Key gains Left, Right and F(u8) (they were Key::Other). tole-cli: Settings::{tui_keys, keymap}, TuiSession::with_keymap.

  • TUI /fork and /tree (#463, part 2 of the TUI polish; the issue stays open for export/copy, themes and keybindings), a UI over the session branching of #210. /fork [entry-id] forks the open session at a settled entry (default: the last one, like tole branch) into a new session and switches to it in place, as /new and /resume do; the new session is indexed (sessions --all, face branch) and its header says forkedFrom. The source is only replayed read-only (never locked or written), so forking while the TUI holds its writer lock is safe; an unknown or unsettled entry, or a session with nothing settled yet, is refused with the core error and leaves the session and the sessions directory as they were. /tree opens a picker over the family of the open session (its parent chain up to the root and every fork below it, siblings and grandchildren included), indented by depth with the open session marked and preselected; picking a row switches to it. It is built from the same forkedFrom data as sessions --tree. Like /new and /resume, both are ignored while a turn runs, and neither replays the old transcript on screen. tole-tui API: new HostCmd::{Fork(Option<String>), PickTree} (answered with HostReply::Session and HostReply::Sessions) and PickKind::Tree; a host that does not implement them refuses them like the other commands. tole-cli: session_index::{tree_nodes, tree_order, family} (sessions --tree now shares the scan). Not included: in-file branching (several branches inside one session file), transcript replay after a switch.

  • TUI /export [path] and /copy (#463, part 1; the issue stays open for fork/tree, themes and keybindings). /copy sends the last assistant answer to the terminal clipboard with an OSC 52 sequence written by the TUI process (ESC ] 52 ; c ; <base64> BEL): no native clipboard dependency, the payload is only base64 so answer text cannot inject escape bytes, answers over 64 KiB are refused with a pointer to /export, and since a terminal never confirms OSC 52 the note says what was sent (needs OSC 52 support; tmux needs set -g set-clipboard on), never that it worked. /export writes the session transcript as .html (self-contained: every text escaped, no script, no external resource, a default-src 'none' CSP meta, light and dark) or .jsonl (the entries exactly as stored); no argument writes <workspace>/.tole/exports/<session id>.html. The path is workspace-jailed (canonicalized, symlink-safe), an existing file or symlink is never overwritten or followed, the file is created owner-only on Unix, and an unknown extension is refused. Transcripts contain tool output and may contain secrets. Like the other commands, both are ignored while a turn runs. tole-tui API: new HostCmd::{LastAnswer, Export} and HostReply::{Answer, Path}; TuiSession::with_workspace, last_answer and export.

  • TUI paste and image attach (#560; epic #523): the TUI enables bracketed paste (and turns it off on exit and on panic), so a pasted block is inserted into the editor as one edit, with CRLF/CR normalized to LF and control characters other than newline and tab dropped, and is never sent before Enter. Before, a multi-line paste arrived as keys: the first line was sent at the first line break and the next one steered that turn. /image <path|data-url> queues an image for the next message (/image lists, /image clear empties; same jail, cap and sniffing as --image), shown as an image: … row above the editor; a paste that is exactly one image path or data:image/… URL is attached instead of inserted (inserted as text, with the host's reason, when it cannot be attached). Decision: no OS clipboard images in the TUI (GUI clients own them; no native dependency). tole-tui API: Input is now an enum, Input::Key(KeyPress) | Input::Paste(String) (the Input::new/ctrl/alt/shift constructors are unchanged; code reading input.key / input.mods matches Input::Key first); new HostCmd::{AttachImage, ClearImages, Images}, HostReply::Images, ImageItem, Action::PasteImage and term_input::input_from_event.

  • Images on any turn and ACP image blocks (#559; epic #523): tole chat takes /image <path|data-url> to queue an image for the next message (/image lists the queue, /image clear empties it), so images are no longer limited to the first message; a message that could not be recorded keeps its images queued. The TUI host (TuiSession) gets the same queue for #560 to drive: attach_image(spec), attach_image_ref, pending_images, clear_pending_images, taken by the next run_turn. tole acp now advertises promptCapabilities.image (when a spill dir exists) and maps ACP image content blocks onto the existing spill-and-reference path of CLI data: URLs: the declared mimeType is not trusted (bytes are sniffed), the optional uri is never read, a bad image refuses the prompt, an image-only prompt now runs instead of being refused as "missing prompt", and audio / embedded-resource blocks stay ignored. An image-only user message no longer sends an empty text part (tole-core). New shared-runner entry points turn_runner::{run_turn_on_with_images, run_turn_with_images, resolve_image, resolve_inline_image, inline_images_supported} and session_host::run_session_turn_with_images. Decision recorded: no model-callable image tool for now; images stay user-supplied (threat model).

  • Image input on tole serve (#558): POST /sessions/{id}/images takes one image as the raw request body, sniffs its type from the bytes (PNG, JPEG, GIF, WebP; the request's Content-Type is ignored), resolves it through the same core path as --image (jail, 10 MiB cap, FNV-1a 64) and stores it content-addressed under ~/.codecora/tole/images/serve/<session id>/; the answer is {id, mime, bytes, fnv1a64} (the id is the hash, no server path). POST /sessions/{id}/prompt accepts "images": [<id>] next to text; only that session's uploads resolve and the turn records the references exactly like --image (no blob in the log), so they are re-sent after a restart and resume. GET /sessions/{id}/images/{fnv1a64} serves only an image recorded in that session's log, re-checking the jail, size and hash of the bytes served, with the recorded Content-Type and X-Content-Type-Options: nosniff; a mismatch is a 409 (a recorded image outside the jail a 403), never a silent serve. The 10 MiB upload ceiling applies only once the headers carry the right token (otherwise the 1 MiB body cap stays; a declared body over the cap is authenticated first, so a wrong token gets 401 through the per-IP limiter and only the right token gets 413), and uploads count within the 32-connection cap. Quotas in bytes: TOLE_SERVE_IMAGE_SESSION_QUOTA (default 64 MiB) and TOLE_SERVE_IMAGE_TOTAL_QUOTA (default 512 MiB), 507 when exceeded; 415 for a non-image, 413 over the cap. No tole-core API change. Not included: garbage collection of unused uploads (they count against the quotas until removed by hand), inline data: URLs in the prompt JSON.

  • review_gate config key (#534 follow-up): off | warn | block in .tole/config.toml or the user config, with precedence flag > TOLE_REVIEW_GATE > config > user config > default block; an invalid value is a config error and tole config check shows the effective value and its source. A project file can only keep or tighten the gate: when both layers set it the STRICTER wins, so a cloned repository cannot loosen the gate a user chose (the one key that is not simply project-over-user). A project-only value is used as given, behind the project-config trust gate. No effect without the cora review tools.

  • Event stream on tole serve (#524, third and last part; epic #523): GET /sessions/{id}/events?after=<seq> is a Server-Sent Events stream for graphical clients. Durable entry frames carry the log's entries with their seq as the SSE id and replay losslessly after a dropped connection (after, or Last-Event-ID, which EventSource sends itself); ready marks the end of the replay. Ephemeral, best-effort frames carry streamed text and reasoning, tool start/finish and approval_requested / approval_resolved; they are never stored or replayed, and a slow client gets a resync marker instead of slowing the turn (bounded, non-blocking per-stream queue). A turn only gets live text/tool events when it starts while a stream is open on that session (with no stream open it runs exactly as before); the turn that resumes after an approval streams durable entries only. Heartbeat comment after 15 s without a write (TOLE_SERVE_HEARTBEAT_SECS, 1 to 3600, changes it); closed and a clean end when the session leaves the live map. At most 8 open streams per server (429 beyond that), counted within the 32-connection cap so they cannot starve /approvals and /prompt. Additive: no existing route or response changes. New events module (SSE framing, bus, limiter, log tail, approval diff). With this, #524 is complete; the next UI-epic items are #525 and #526. Not included: a stream token for browser EventSource (the web client, #529), a log index for very large sessions, an observer for the approvals-resume turn (a tole-core change).

  • Resume-by-id on tole serve (#524, second of three parts; epic #523): POST /sessions {"resume": "<id>"} makes an existing session live again, e.g. after a serve restart, so a UI client can reopen it (history via GET /sessions/{id}/entries). The id is validated and joined into the session directory only (no client-supplied path); cwd goes through the same jail check as a new session and a session is found only under the workspace it was created in (404 otherwise). An already-live session is returned as is (alreadyLive, with its busy flag), never reopened, so a running turn is not disturbed. 409 when another process holds the session's writer lock, 503 at the live-session cap with every session busy; a resumed session queues non-preauthorized Writes like a new one. POST /sessions for a new session now shares its open-and-admit code with resume, behavior unchanged. Next: the SSE event stream.

  • GET /sessions/{id}/entries?after=<seq>&limit=<n> on tole serve (#524, first of three parts; epic #523): a paginated transcript read for graphical clients. Returns the session log's entries with seq > after exactly as stored (nextAfter, hasMore, lastSeq for paging); limit defaults to 100, is clamped to 500 and a page stops near 1 MiB. It replays the session file read-only instead of taking the storage lock, so it works while a turn is running. New protocol module for the wire types (serde structs; schema export deferred until a client generator needs it). Additive: no existing route changes. Live sessions only for now; resume-by-id and the SSE event stream are the next two parts.

  • Optional fetch backend for web_fetch (#532): with TOLE_WEB_FETCH_URL set, web_fetch asks that backend (a scraping service with browser and reader fallbacks, say) for pages that need JavaScript or block direct fetches, and stays a ReadOnly tool with the same trust model as web_search. Default contract GET {url}?url=<target> → {"content": "…"}; TOLE_WEB_FETCH_METHOD=POST sends {"url"}; TOLE_WEB_FETCH_HEADERS (Name=${VAR} pairs, sent only to the backend) and TOLE_WEB_FETCH_FIELDS='content=<field>' work like the search settings; a malformed value fails startup. The target is vetted before anything is sent (https only, no credentials in the URL, public host; TOLE_WEB_ALLOW_PRIVATE=1 opts out). Backend only, no direct fallback. Unset: web_fetch is the unchanged direct fetcher. The target URL is disclosed to the backend operator (threat model). The response shape of a specific real backend is not verified here: the field mapping exists for that. Not included: a fallback order, a format hint to the backend.

  • evals/shell_usage.py (#531, step 1): a read-only report over session JSONL of how often run_command / job_start inputs use shell features (pipe, chain, redirect, substitution, leading cd, bash -c wrapper), how many failed and how many follow a failed call. No runtime change and no new logging; run_command behavior is unchanged. The repository's own traces are too small and too scripted to decide anything (9 calls); the decision waits for real sessions.

  • Review gate before git commit (#534): while both cora review tools are attached (mcp_cora_cora_review_prepare / _finalize), a git commit is refused until the staged diff has a validated review, and the refusal tells the model exactly how to get one. tole does not hash or record anything itself: it asks cora >= 0.20.0's own commit gate (cora hook verify: exit 0 validated or nothing to review, 10 reviewed but blocking, 11 not validated), whose marker is bound to the exact change set, so tole and cora cannot disagree about "this diff". It covers the git tool's commit op and run_command / job_start running git commit (behind env, VAR=x, a path to git and git's global options). git -C <dir> commit is verified in <dir>, the repository the commit really happens in; a commit that redirects git's git dir or work tree (--git-dir, --work-tree, GIT_DIR= / GIT_WORK_TREE= / GIT_INDEX_FILE=, -c core.worktree=) cannot be checked and is refused under block (noted under warn). TOLE_REVIEW_GATE=off|warn|block / --review-gate (default block; the flag wins; an invalid value fails startup; no config key yet, so a cloned project's config cannot weaken it); with no review tools attached there is no gate; a cora without hook verify, or one that cannot run, fails open with one warning; tole doctor reports the state. Child agents inherit the policy through the environment. Not included: sh -c, scripts, git aliases and merge / cherry-pick / am (see the threat model); a config key.

  • tole setup cora (#535): installs or upgrades the cora binary the review flow, mcp_cora_* and cora_search need. It runs cargo install cora-code --locked (the same constant tole doctor prints) after a [y/N] at a terminal or --yes; with neither it refuses (exit 2), a supported cora is left alone, --check only reports, no cargo prints the manual command (exit 1). The result is verified at $CARGO_HOME/bin/cora and a still-too-old result is an error; a note says when PATH resolves a different copy first. tole doctor now ends its cora lines with "(or run tole setup cora)". Same trust as tole upgrade (cargo verifies the registry checksum, tole downloads nothing). Not included: a prebuilt-archive download path (cora-code's release layout is unverified), embedding cora (a CLI-only crate), and uteke (the table is ready for one more variant).

  • Streamable HTTP MCP client (#530): --mcp-server name=https://host/path (and the mcp_server config key) connects to a remote MCP server next to the existing stdio form, inside the existing mcp feature of tole-core. The bearer token is read from TOLE_MCP_<NAME>_TOKEN only (name upper-cased, - becomes _), re-read on every reconnect and sent only to that endpoint; it and the url are scrubbed from every error. https is required (plain http only for loopback), a url with credentials is refused, and a redirect to another origin is not followed. Tools register as mcp_<name>_<tool> and stay Risk::Write (pre-authorize with --allow 'mcp_<name>_*'); results stay capped and fenced. Build without the mcp feature links no HTTP client. API change in tole-core: McpServerConfig now holds transport: McpTransport (Stdio { command, args } | Http { url }) instead of command / args; new mcp::{McpTransport, token_env_name}. Not included (deferred): server-initiated notifications and SSE resumption, OAuth.

Fixed

  • uteke_recall and uteke_document accept uteke 0.24 category:title room ids (#716). The room check allowed only [a-zA-Z0-9-_], so project:qa-check was refused before uteke was spawned. One shared validator now accepts today's ids unchanged and the category:title form (lowercase, exactly one colon, at most 64 characters, no leading hyphen); flag-shaped values, a second colon, uppercase in the new form and over-long colon ids are still refused, and the room is still passed as a positional value, never a flag. The built-in repo-*, profile-* and agent-* rooms keep their names (migration is a follow-up).
  • Discussion round documents now reach uteke (#717). UtekeDocs was only wired in tests, so tole discuss start and resume and the model-facing discuss tool wrote no goal or round document. Driver::from_config, the one builder every entry point uses, now wires it (secret-redacted, capped, slug and parent built by the host) when uteke is on PATH: goal-<id> and one digest per round. A document that cannot be written is a note: in the outcome (a risk on the delegate node for the tool) and does not stop the discussion or change its gate; without uteke one note says documents are off.
  • tole skills approve --workspace and tole skills list --workspace panicked ("Mismatch between definition and access of workspace"): the subcommand declared the argument as a path while the global --workspace is a string. They take a string now.
  • Skill review notes (#616, #617): tole skills approve now shows the package (files, sizes, hash) before it approves and asks for confirmation on a terminal; without a terminal it refuses unless --hash is given, so scripts must pass --hash <sha256:…> (the hash tole skills list shows). tole skills index redacts known secret values from each description before it reaches uteke (the content hash stays the real file's). A skill package walk counts directories too (at most 1024 entries), so a skill directory of countless empty subdirectories is refused quickly.
  • A huge SKILL.md can no longer exhaust memory at session start: every SKILL.md read (load_skill in every mode, the discovery listing, skill_search, the approved-hash gate, tole skills index) goes through one capped reader (1 MiB; the length is checked before reading and the read stops one byte past the cap). An oversized skill is left out of the listings with a startup note and refused by load_skill. A FIFO named SKILL.md is refused instead of blocking. The skill approvals file is capped at 1 MiB too. Found while fixing the same pattern in #617.
  • Reopening a session right after dropping its writer no longer fails with a spurious Locked naming our own pid (#552): an flock belongs to the open file description, so a child forked by another thread of the same process (a command, job or hook) briefly holds a duplicate of the lock descriptor until it execs, and a reopen in that window was refused. It showed as 409 ... open for writing by pid <our pid> on POST /sessions {"resume"}, in the TUI /resume and /new, and as two flaky tole-core tests. lock_writer now retries for up to 150 ms, only when the recorded holder is our own pid; a holder with another pid still fails at once, and a genuine second open in this process (#475) still fails after the bounded wait. Regression test: 6000 create/drop/reopen rounds against three threads spawning children (8 to 12 failures before, 0 after).
  • Missions now learn about cora's agent-as-reviewer flow (#536): tole mission builds its registry like run (including the auto-attached mcp_cora_* tools) but its pinned system prompt never named the review tools, so the unattended command was the one that did not know the flow existed. When both mcp_cora_cora_review_prepare and mcp_cora_cora_review_finalize are registered, a fresh mission's prompt now carries the same review section as run / chat / the TUI plus one sentence asking for a review (and its verdict in the final message) before the mission ends; without the tools nothing is added. Guidance only: a gate before git commit is tracked separately. serve, acp and mcp sessions are unchanged on purpose: they attach no external MCP servers, so they have no review tools. Resumed missions keep their pinned prompt.

Deprecated

  • agent_start / agent_poll (#585): in the CLI faces they are now aliases of delegate / delegate_poll (same tree, same caps; prompt is accepted for task) and will be removed in the next release. tole serve keeps the classic depth-1 tools for now.

Changed

  • tole-tui rendering split out of lib.rs (#526, fourth part): App::draw and its styling helpers (tail, styled, diff_style, inline_spans, wrap) now live in a new private render module that only reads App, so a second front end can replace or reuse drawing without touching the state machine. A pure move: no behavior change, no public API change.
  • tole-tui approvals as source-agnostic UI state (#526, third part): a pending approval is an ApprovalRequest (one sanitized line plus the Risk tier, with can_allow_always() encoding that a Destructive call is never allowed always) and a Pending whose reply is a one-shot closure instead of a Sender. Prompter::ask(request) blocks for an in-process turn as before; the new Prompter::post(request, reply) does not block, so a remote source (the /approvals queue of a server) can feed the same UI and receive the verdict. The verdict is delivered exactly once, and dropping a Pending unanswered still denies (fail closed), now through its Drop, so a cancelled turn, a replaced request or a vanished UI all deny. No behavior change for users. Breaking for code outside this repository that uses the removed API: Prompter::ask(text, destructive) is now ask(ApprovalRequest) and Pending's fields are private; new public items tole_tui::ApprovalRequest and Prompter::post.
  • tole-tui host seam (#526, second part): TuiHost shrinks from eleven methods to three (footer, run_turn, apply). apply(HostCmd) -> Result<HostReply, String> replaces models, set_model, set_effort, request_compaction, new_session, sessions, switch_session, status_lines and set_name; no slash command is lost. HostReply (Done, Session(id), Models, Sessions, Lines) carries data only, and the UI keeps the wording and the pickers, so a remote adapter has a small interface to implement. The default apply supports Status (no lines) and refuses the other commands as before. A reply of the wrong kind from a host is reported in the transcript instead of panicking. TuiSession keeps its session operations as plain methods and apply dispatches to them. No behavior change for users. Breaking for anyone implementing TuiHost outside this repository (override apply instead of the removed methods); new public item tole_tui::HostReply. Next: model a pending approval as source-agnostic UI state.
  • tole-tui input seam (#526, first part): App::on_input(Input) takes a UI-neutral Input (Key::{Char, Enter, Esc, Tab, BackTab, Backspace, Up, Down, Other} plus ctrl/alt/shift) so the key logic no longer depends on terminal types. The crossterm mapping is an adapter (term_input::input_from, and App::on_key(KeyEvent) as the terminal entry point, which drops key releases); keys the logic does not distinguish map to Key::Other, which still disarms a pending Ctrl+C exactly as before. No behavior change: the key table in docs/tui.md is unchanged and all existing tests pass without edits. New public items: tole_tui::{Input, Key, Mods}. Next: collapse TuiHost into one apply(HostCmd) path and model a pending approval as source-agnostic UI state.
  • Internal refactor, no behavior change (#525, first part): tool registration moved out of session_host.rs. UpdatePlanTool, PlanEmitter, register_gitea, detect_github_repo and github_repo_from_remote_url now live in tole_cli::tool_roster next to the rest of the roster; session_host keeps only session hosting (open, turn, resume, cancel, interrupt, detach, list). Library paths change accordingly (tole_cli::session_host::UpdatePlanTool is now tole_cli::tool_roster::UpdatePlanTool, and likewise for the other four); there is no re-export. Part 2a: new sessions are created through one helper, tole_cli::session_host::create_session, which creates the session file and registers it in the global session index in the same call. run, chat, tui, mission, the server faces and the TUI's /new all use it (they each created and indexed by hand before), so a face can no longer create a session and forget to index it. Error messages and index contents are unchanged. Part 2b: one turn runner. tole_cli::turn_runner::{TurnPlan, run_turn_on, run_turn_with, resume_turn_on} describe how a turn is run (build the session's provider, optionally settle a turn parked mid-flight, optionally compact, run), and run_session_turn / resume_session_turn (serve, ACP, MCP) and TuiSession::run_turn all go through it. The differences between faces are now explicit plan fields (resolve_parked, compaction: the TUI sets both, the server faces neither) instead of two copies of the sequence. Behavior is unchanged, including each face's error text (the TUI keeps its storage error: prefix); on a parked session the server faces still get the core's refusal ("resolve the session first"). Part 2c: a session's durable settings live in one module, tole_cli::session_settings: the register names (fact/model, fact/reasoning_effort, fact/session_name), the label validation, and the writers (set_model, set_effort, set_name, request_compaction, plus write_model for ACP, which validates against its own model list first). The TUI's /model, /effort, /name and /compact and ACP's model picker write through it, and the readers (session_model, session_effort, status) use the same constants instead of repeated string literals. Behavior and error text are unchanged. With this, #525's consolidation is done as shared primitives (create + index, one turn runner, settings); what is left is listed on the issue.

📦 Platforms

Platform File
Linux (x86_64) tole-x86_64-unknown-linux-gnu-v0.11.0.tar.gz
Linux (ARM64) tole-aarch64-unknown-linux-gnu-v0.11.0.tar.gz
macOS (Apple Silicon) tole-aarch64-apple-darwin-v0.11.0.tar.gz
Windows (x86_64) tole-x86_64-pc-windows-msvc-v0.11.0.zip

🚀 Install

# From crates.io (canonical — `tole upgrade` tracks it)
cargo install tole-cli

Or download a binary archive below, verify it against checksums-sha256.txt, and put tole on your PATH.

Full changelog: https://github.com/codecoradev/tole/blob/main/CHANGELOG.md