Cogitate runtime contract#

The canonical contract for cogitate talents — the LLM agents Cortex spawns to read and update the journal (chat, the entity / activity / import talents, and the rest). It is the single place a talent author can point at and say what a fresh cogitate run's working directory, context, tools, finalization, and persistence are — instead of reverse-engineering the runtime from solstone/think/talents.py, the providers, the policy, and the installed OpenHands SDK.

This contract names capabilities and access classes. It does not define the HTTP API shape (that is convey's — see docs/CONVEY.md and docs/SOLCLI.md) and it is not a per-talent prompt. Every talent prompt is written against this contract.

Source of truth for the in-context part: the short runtime preamble every cogitate talent receives is the constant COGITATE_RUNTIME_PREAMBLE in solstone/think/cogitate_contract.py. The locked access-tier and finalization vocabularies live in the same module (COGITATE_ACCESS_TIERS, FUTURE_ACCESS_TIERS, TALENT_FINALIZATION_MODES). Reference those by path; do not paraphrase them.

What a cogitate run is#

A cogitate run is not a coding agent (Claude / Codex / Gemini) launched in the journal. It is a Python talent subprocess spawned by Cortex, inside which the OpenHands SDK builds an Agent and a Conversation and runs the model against a small, explicit tool set.

Cortex (cortex/request)
   |- spawns: python -m solstone.think.talents      (cwd = journal root)
        |- prepare_config()                          (talents.py)
             |- run_cogitate()                        (providers/openhands.py)
                  |- assemble_prompt()                (providers/cli.py)
                  |- build the `sol` tool + CogitatePolicy
                  |- OpenHands Agent (system_prompt = preamble + instruction)
                  |- OpenHands Conversation -> model loop -> finalization

The model's initial context is solstone-assembled prompt material plus the OpenHands tool schemas — not a snapshot of the cwd. Files that merely sit in the working directory are not in context (see "What is not in a talent's context").

Working directory and OpenHands workspace#

These are two different things; conflating them is the most common debugging misread.

The journal-root cwd matters operationally because the sol tool inherits it, but cwd contents are never automatically loaded into the model's context.

The sol CLI is the authoritative talent-to-journal contract#

A talent reaches journal functionality by emitting sol / sol call ... command lines. The approved host command families journal identity ..., journal health ..., and journal talent ... also run directly and must not be prefixed with sol or sol call. The runtime parses each tool call as one command-line invocation and executes that argv directly; it is not an arbitrary shell. The CLI handlers are the single authoritative translation layer between a talent and the journal: they turn CLI syntax into journal operations. A talent therefore:

• never talks to the convey HTTP API directly, and
• never assumes a database, a socket, or any journal access other than the documented command forms and the bounded raw-read tools below.

The tool call shape is sol(command="sol call activities list"), or sol(command="journal identity partner") for an approved host command family. The command policy (below) constrains what may run and rejects shell composition such as pipes, redirects, chaining, and command substitution.

Reads: domain reads vs raw evidence reads#

Domain reads — the default. Indexed, normalized, or semantic reads go through sol call verbs (e.g. sol call activities list, sol call entities search, sol call transcripts read). Anything that needs authorization, derived state, normalization, or audit behavior is a domain read, not a raw read.

Raw evidence reads — bounded, for evidence with no sol verb. A normal talent may be given a small read tier (read_file, list_directory, glob, grep_search) for raw evidence (e.g. a per-span narrative file) that no domain command exposes. When that tier is present it defaults to broad journal-root read-only:

• reads resolve under the journal root by default;
• a denylist is always refused: .git, caches (.cache), credentials, virtualenvs, and node_modules;
• per-call and per-run caps bound output size and the number of read calls;
• traversal and symlink escape are refused; binary files, directories, sockets, devices, and FIFOs are refused by read_file.

The journal is the owner's own data, so a broad read default carries no data-use cost — the denylist and caps are the safety bound, not a permission gate. An optional per-talent read_scope is a narrowing hint only; it is not the default gate, and a talent never fails for reading an undeclared journal file.

The raw-read tools are built to this contract and registered per resolved access tier. Check the run's actual tool schema (journal talent show <name> --prompt) for what a specific talent receives.

Writes: only through approved journal commands#

A talent writes journal state only through approved journal commands (the sol call ... verbs for the domain it is updating, e.g. sol call entities update ..., plus approved direct host commands when a prompt names one). There is no general-purpose write tool and no raw-write tier — write-class tools are denied by policy. The mechanic is centralized in the owning command; a talent gets the capability to update a domain, never an arbitrary file-write path. Persistence that does not go through an approved journal command does not happen.

Access tiers#

A talent's access class is one of the following. The tier vocabulary is locked (COGITATE_ACCESS_TIERS / FUTURE_ACCESS_TIERS in solstone/think/cogitate_contract.py); the per-talent assignment and its enforcement are layered on top of it.

Policy denies support send verbs (create, reply, attach, feedback) for normal / system-read runs. outbound runs may use those verbs only when the launch config carries runtime owner send-approval. An agent cannot self-grant approval through prompt text, static frontmatter, templates, or scheduled injection.

There is no repair tier in cogitate. Health fact-gathering and repair run through the deterministic journal heartbeat workflow, explicitly launched and logged without an LLM. steward no longer runs as a cogitate talent at all: the owner-facing health.md body is rendered deterministically in its pre-hook, and a tiny lite generate talent writes only the human-friendly summaries (headline / summary_sentence / a closed-enum suggested_action) the home widget surfaces. No cogitate health surface remains.

code-agent is a documented future tier, not part of the current cogitate runtime. A code agent needs write access, broad tools (read / edit / write / shell / delegation), and a repo cwd — deliberately out of scope here. It gets its own clean contract if and when it is built; it is listed in FUTURE_ACCESS_TIERS so nothing keys enforcement off it today.

Finalization#

Every talent has exactly one finalization mode (TALENT_FINALIZATION_MODES in solstone/think/cogitate_contract.py):

A manual talent's prompt should state which of these it expects so the behavior is explicit rather than inferred.

What is not in a talent's context (disallowed assumptions)#

A talent prompt must not assume any of the following — they are named here so prompts can be checked against them:

• other bare journal ... families (e.g. journal search, journal facet, journal navigate) — reach the journal through the documented sol / sol call form;
• raw cat / ls / arbitrary shell file reads — use the raw-read tools when present, not shell file access;
• auto-loaded skills, AGENTS.md, CLAUDE.md, or GEMINI.md — these are normal journal files with no special status. They are not injected into a talent's context; this contract is the talent's source of truth. (They remain affordances for coding agents launched in the journal, not for cogitate.)
• browser / web tools, MCP tools, and sub-agent delegation — none are bound;
• cwd: repo / write: true modes — not cogitate modes; a normal talent runs with the journal cwd and no write tool.

The in-context preamble (named source constant)#

Every cogitate run receives the contract's essential preamble as the head of its system prompt. It is the constant COGITATE_RUNTIME_PREAMBLE in solstone/think/cogitate_contract.py, prepended in assemble_prompt (solstone/think/providers/cli.py) ahead of the talent's own instruction. The verbatim text:

You are a solstone cogitate talent running inside the live system. This runtime contract is authoritative; do not assume capabilities beyond it.

- Reach the journal through the `sol` command line: emit `sol` / `sol call ...` command lines, e.g. sol(command="sol call activities list"). The runtime runs each call as a single parsed command-line invocation, not an arbitrary shell. The `sol` CLI is the one authoritative path between you and the journal; never assume direct database, socket, or HTTP access.
- The approved host command families are identity, health, talent; run them directly as `journal <family> ...` through the same tool, never prefixed with `sol` or `sol call`.
- Write journal state only through approved journal commands (`sol call ...` verbs for the data you own, plus approved direct host commands when a prompt names one). There is no general-purpose write tool; persistence that does not go through an approved journal command will not happen.
- Raw evidence reads use the provided read tools (`read_file`, `list_directory`, `glob`, `grep_search`), bounded to the journal root: a denylist (`.git`, caches, credentials, virtualenvs, `node_modules`) and per-call / per-run caps apply. Prefer `sol call` reads; use raw reads only for evidence that has no `sol` command.
- Finalize as your run is configured: call `emit_final` when an `emit_final` tool is present; otherwise finish through the built-in finish tool; a side-effect-only talent that has already persisted its work finishes quietly with no output.
- Do not assume tools or context you were not given: no other bare `journal ...` family, no raw `cat` / `ls` / shell file reads, no shell composition (pipes, redirects, chaining, or command substitution; one command per call), no auto-loaded skills or AGENTS.md / CLAUDE.md, no browser or web access, no MCP tools, and no delegating to sub-agents. Any guidance file is a normal journal file with no special status; this contract is your source of truth.

Where this is wired (for maintainers)#