From 44d4a4bb0cfa79c8d827ea48ee29f307e0c09c49 Mon Sep 17 00:00:00 2001
From: Nishad <nishu.builder@gmail.com>
Date: Tue, 18 Aug 2026 17:48:43 -0700
Subject: [PATCH 1/4] Use secrets in conversations

---
 README.md                     | 18 +++++++++++
 SPEC.md                       | 19 +++---------
 crates/caos-cli/src/lib.rs    | 58 +++++++++++++++++++++--------------
 crates/caos/src/eval.rs       | 16 ++++++++--
 crates/caos/src/lib.rs        | 34 ++++++++++++++++++--
 design/agent-harness.md       | 10 ++++--
 std/llm-call/src/main.rs      |  7 +++--
 std/llm-step/src/main.rs      |  7 +++--
 std/llm-test/common.sh        | 10 +++++-
 tests/caos-tools/cli.sh       | 10 +++++-
 tests/chat-offline/cli.sh     | 37 +++++++++++++++++++---
 tests/chat-online/cli.sh      |  9 ++++++
 tests/chat-tools-grep/cli.sh  |  1 -
 tests/chat-tools-mixed/cli.sh |  1 -
 tests/chat-tools/cli.sh       |  1 -
 tests/llm-call/cli.sh         | 10 +++++-
 tests/max-tokens/cli.sh       | 10 +++++-
 tests/merge-harness/cli.sh    | 10 +++++-
 18 files changed, 203 insertions(+), 65 deletions(-)

diff --git a/README.md b/README.md
index 3d0b5407..ef695159 100644
--- a/README.md
+++ b/README.md
@@ -319,6 +319,24 @@ the object machinery through a one-way dependency. Their difference is the
     missing `entropy=`, warn on a weak one (`--check` reports only and exits
     non-zero, for CI). Offline — no server (design/secrets.md).
 
+Conversations read their model credential from that local store rather than
+putting it in a curried worker. A minimal per-device setup is:
+
+```text
+# .gitignore
+.caos-secrets/
+
+# .caos-secrets/anthropic-api-key
+name=anthropic-api-key
+value:@=/absolute/path/to/anthropic-api-key
+reader=DEEP-DEPS/llm-step
+reader=DEEP-DEPS/llm-call
+```
+
+Run `caos-cli secrets` once to add the random `entropy=` used for cache
+isolation. The file and value path stay local; only the entropy-derived identity
+enters an ArgTree, while the value is carried out of band for the run.
+
 `caos-cli` must run inside a git working tree with the server as its `caos`
 remote — the remote's URL is also where compute is triggered and results are
 fetched, so there is nothing else to configure:
diff --git a/SPEC.md b/SPEC.md
index 63323bf7..b9281f6a 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -125,8 +125,11 @@ credential's destination or permitted repository belong beside the credential;
 requiring a wrapper would make that policy repository-owned and needlessly
 proliferate expression directories.
 
-What remains is not about the eval path: the agent harness carries no store,
-and `value:@=` is UTF-8 only. See "Remaining work".
+The agent harness carries the same store: conversation preparation resolves
+`llm-step` with it, the admitted request includes the resulting isolation
+identity, and foreground or recovery dispatches send the store out of band.
+Both conversation LLM workers read `anthropic-api-key` from `/secret`, never
+from a curried arg. `value:@=` remains UTF-8 only; see "Remaining work".
 
 ## Problem
 
@@ -198,18 +201,6 @@ Note that this means that the server sees all secrets. We can revisit if this be
 
 ## Remaining work
 
-- **The agent harness carries no store.** `caos talk`/`chat` (`chat.rs`'s
-  `turn` and `generate_conversation_title`) pass an empty store and an empty
-  header, so an agent turn — and every tool it invokes as a sub-run — is granted
-  nothing. This is where the note's own motivating example lives (an agent
-  reaching for github-push), so it is a hole, not a boundary. It was never
-  decided: the `&[]` is what the parameter-threading left behind. Filling it is
-  one call (`build_secret_store` before `prepare_request`, its header on
-  `request_compute`), but it is a **policy** choice first: a store-carrying turn
-  is per-user keyed via `secret-hash`, so every chat that matches a reader stops
-  sharing cache with other users. Worth deciding explicitly rather than by
-  default.
-
 - **Binary `value:@=`.** Read but kept UTF-8 (binary/multiline later).
 
 - **Shared-server exposure.** Carrying the whole store means a shared server
diff --git a/crates/caos-cli/src/lib.rs b/crates/caos-cli/src/lib.rs
index 806f6d5b..95d877ca 100644
--- a/crates/caos-cli/src/lib.rs
+++ b/crates/caos-cli/src/lib.rs
@@ -16,15 +16,16 @@ use std::time::{Duration, Instant};
 use serde_json::{json, Value};
 
 use caos::{
-    compute_client_request, curry_client_object, eval_workspace_dep, prepare_client_request,
-    GitTransport, Transport, CAOS_REMOTE,
+    build_secret_store, compute_client_request_with_store, curry_client_object,
+    eval_workspace_dep_with_store, prepare_client_request_with_store, ClientSecret, GitTransport,
+    Transport, CAOS_REMOTE,
 };
 
 const CONVERSATION_PREFIX: &str = "refs/caos/v2/conversations/";
 const HEAD_SUFFIX: &str = "/head";
 const MAX_CONVERSATION_ID_BYTES: usize = 124;
 const MAX_APPEND_ATTEMPTS: usize = 32;
-const API_KEY_ENV: &str = "ANTHROPIC_API_KEY";
+const MODEL_API_SECRET: &str = "anthropic-api-key";
 const AUTO_NAME_PREFIX: &str = "talk-";
 const MERGE_REF_CANDIDATES: &[&str] = &["main", "master", "origin/main", "origin/master"];
 pub const DEFAULT_MODEL: &str = "claude-opus-4-8";
@@ -962,8 +963,10 @@ pub fn prepare_queued_request(
     queued_head: &str,
 ) -> Result<String, String> {
     validate_hash(queued_head, "queued conversation head")?;
-    let llm = resolve_llm(t, options, id)?;
-    prepare_client_request(t, &llm, &[format!("--head:commit={queued_head}")])
+    let store = build_secret_store(t)?;
+    require_model_secret(&store)?;
+    let llm = resolve_llm(t, options, id, &store)?;
+    prepare_client_request_with_store(t, &llm, &[format!("--head:commit={queued_head}")], &store)
 }
 
 /// Resolve the human-facing identity once per client. `author` remains
@@ -1044,9 +1047,12 @@ fn unsafe_username_character(character: char) -> bool {
         )
 }
 
-fn resolve_llm(t: &GitTransport, options: &TurnOptions, id: &str) -> Result<String, String> {
-    let api_key = std::env::var(API_KEY_ENV)
-        .map_err(|_| format!("{API_KEY_ENV} must be set to start a conversation request"))?;
+fn resolve_llm(
+    t: &GitTransport,
+    options: &TurnOptions,
+    id: &str,
+    store: &[ClientSecret],
+) -> Result<String, String> {
     let system = match (&options.system, &options.system_file) {
         (Some(system), None) => system.clone(),
         (None, Some(path)) => std::fs::read_to_string(path)
@@ -1057,11 +1063,7 @@ fn resolve_llm(t: &GitTransport, options: &TurnOptions, id: &str) -> Result<Stri
         }
     };
     let merge_refs = snapshot_merge_refs(t)?;
-    let mut config = vec![
-        format!("--api-key={api_key}"),
-        format!("--system={system}"),
-        format!("--conversation={id}"),
-    ];
+    let mut config = vec![format!("--system={system}"), format!("--conversation={id}")];
     if !merge_refs.is_empty() {
         config.push(format!("--merge-refs={merge_refs}"));
     }
@@ -1072,10 +1074,19 @@ fn resolve_llm(t: &GitTransport, options: &TurnOptions, id: &str) -> Result<Stri
     if let Some(base_url) = &options.base_url {
         config.push(format!("--base-url={base_url}"));
     }
-    let llm_base = eval_workspace_dep(t, "llm-step")?;
+    let llm_base = eval_workspace_dep_with_store(t, "llm-step", store)?;
     curry_client_object(t, &llm_base, &config).map(|hash| hash.to_string())
 }
 
+fn require_model_secret(store: &[ClientSecret]) -> Result<(), String> {
+    if store.iter().any(|secret| secret.name() == MODEL_API_SECRET) {
+        return Ok(());
+    }
+    Err(format!(
+        "conversation needs a {MODEL_API_SECRET:?} secret in .caos-secrets"
+    ))
+}
+
 fn request_is_active(status: &str) -> bool {
     matches!(status, "queued" | "running")
 }
@@ -1084,8 +1095,9 @@ fn request_is_active(status: &str) -> bool {
 /// conversation state; `llm-step` advances the canonical head itself.
 pub fn resume_request(t: &GitTransport, request: &str) -> Result<(), String> {
     validate_hash(request, "request")?;
+    let store = build_secret_store(t)?;
     let server = t.server_url()?;
-    compute_client_request(&server, request).map(|_| ())
+    compute_client_request_with_store(&server, request, &store).map(|_| ())
 }
 
 /// Reissue the exact request recorded by a nonterminal conversation. Repeated
@@ -1959,10 +1971,11 @@ pub fn run_chat_turn(
         });
         emit(TurnEvent::PhaseStarted(TurnPhase::Model));
         emit(TurnEvent::Status("waiting for agent".to_string()));
+        let store = build_secret_store(t)?;
         let server = t.server_url()?;
         let (tx, rx) = std::sync::mpsc::channel();
         std::thread::spawn(move || {
-            let result = compute_client_request(&server, &request).map(|_| ());
+            let result = compute_client_request_with_store(&server, &request, &store).map(|_| ());
             let _ = tx.send(result);
         });
         request_result = Some(rx);
@@ -2022,14 +2035,13 @@ pub fn generate_conversation_title(
     options: &TurnOptions,
     first_message: &str,
 ) -> Result<String, String> {
-    let api_key = std::env::var(API_KEY_ENV).map_err(|_| {
-        format!("{API_KEY_ENV} must be set (it rides, curried, into the title run)")
-    })?;
-    let mut kvs = vec![format!("--api-key={api_key}")];
+    let store = build_secret_store(t)?;
+    require_model_secret(&store)?;
+    let mut kvs = Vec::new();
     if let Some(url) = &options.base_url {
         kvs.push(format!("--base-url={url}"));
     }
-    let llm_base = eval_workspace_dep(t, "llm-call")?;
+    let llm_base = eval_workspace_dep_with_store(t, "llm-call", &store)?;
     let llm = curry_client_object(t, &llm_base, &kvs)?.to_string();
     let messages = serde_json::to_string(&title_messages(first_message))
         .map_err(|error| format!("encoding title context: {error}"))?;
@@ -2042,8 +2054,8 @@ pub fn generate_conversation_title(
         "--model={}",
         options.model.as_deref().unwrap_or(DEFAULT_MODEL)
     ));
-    let arg_tree = prepare_client_request(t, &llm, &call)?;
-    let (kind, hash) = compute_client_request(&t.server_url()?, &arg_tree)?;
+    let arg_tree = prepare_client_request_with_store(t, &llm, &call, &store)?;
+    let (kind, hash) = compute_client_request_with_store(&t.server_url()?, &arg_tree, &store)?;
     if kind != "blob" {
         return Err(format!(
             "conversation title run returned a {kind}, expected a blob"
diff --git a/crates/caos/src/eval.rs b/crates/caos/src/eval.rs
index 8a4b863a..0a04cfaa 100644
--- a/crates/caos/src/eval.rs
+++ b/crates/caos/src/eval.rs
@@ -132,12 +132,22 @@ static EVAL_NODE_MEMO: Memo<(String, String)> = Memo::new();
 /// the DEEPENED tree — so resolving the raw `std/llm-step` directory out of the
 /// worktree cannot work, whatever the path is spelled.
 pub fn eval_workspace_dep(t: &dyn Transport, name: &str) -> Result<String, String> {
+    eval_workspace_dep_with_store(t, name, &[])
+}
+
+/// Resolve a workspace entry point while carrying the caller's secret store
+/// through expression evaluation. Conversation setup uses this form so a tool
+/// embedded by the llm-step expression keeps its secret-dependent identity in
+/// the enclosing turn request.
+pub fn eval_workspace_dep_with_store(
+    t: &dyn Transport,
+    name: &str,
+    store: &[ClientSecret],
+) -> Result<String, String> {
     let (_, oid) = t
         .ingest_path(".")?
         .ok_or_else(|| "this client cannot ingest the workspace tree".to_string())?;
-    // Entry-point resolution feeds `assemble_arg_tree` (which marks the run) or
-    // a reader match, so it carries no store of its own — no marking here.
-    eval_path(t, &oid.to_string(), &format!("DEEP-DEPS/{name}"), &[])
+    eval_path(t, &oid.to_string(), &format!("DEEP-DEPS/{name}"), store)
         .map(|(_kind, hash)| hash)
         .map_err(|error| workspace_dep_error(name, &error))
 }
diff --git a/crates/caos/src/lib.rs b/crates/caos/src/lib.rs
index bc434efc..3b48444a 100644
--- a/crates/caos/src/lib.rs
+++ b/crates/caos/src/lib.rs
@@ -32,7 +32,7 @@ use std::time::{Duration, SystemTime, UNIX_EPOCH};
 use gix::objs::WriteTo;
 
 mod eval;
-pub use eval::{cli_eval_path, eval_workspace_dep};
+pub use eval::{cli_eval_path, eval_workspace_dep, eval_workspace_dep_with_store};
 
 /// `run-tool <script | name> [--name=value ...]` — run a caos-tool by hand: fire
 /// the tool script as a caos job over this repo's tree, exactly what an
@@ -3109,6 +3109,17 @@ pub fn prepare_client_request(
     prepare_request(t, image, None, kvs, &[])
 }
 
+/// Build and push a host-side request while folding the supplied local secret
+/// store's identities into the ArgTree. Secret values remain out of band.
+pub fn prepare_client_request_with_store(
+    t: &dyn Transport,
+    image: &str,
+    kvs: &[String],
+    store: &[ClientSecret],
+) -> Result<String, String> {
+    prepare_request(t, image, None, kvs, store)
+}
+
 /// `prepare-request --base:<type>=<image-or-arg-tree> [--name=value | --name:@=path ...]`
 /// — construct the exact flat runnable ArgTree and print its hash without
 /// executing it. This is the worker-side half: CAS paths use `/cas` semantics.
@@ -4126,18 +4137,25 @@ pub fn cli_secrets(check: bool) -> Result<(), String> {
 
 /// A resolved secret from the caller's store: its value, its entropy (the
 /// cache-isolation capability), and each reader resolved to a partial arg tree.
-pub(crate) struct ClientSecret {
+pub struct ClientSecret {
     name: String,
     value: String,
     entropy: String,
     readers: Vec<std::collections::BTreeMap<String, String>>,
 }
 
+impl ClientSecret {
+    /// Worker-visible name used for `/secret/<name>`.
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+}
+
 /// Read and resolve the caller's `.caos-secrets` store (SPEC.md, Secrets): each
 /// constrained reader is assembled HERE through the curry/expression grammar,
 /// against the store's pinned tree, into a partial name → oid ArgTree. The
 /// server only subset-matches and never evals. Empty when there is no store.
-pub(crate) fn build_secret_store(t: &dyn Transport) -> Result<Vec<ClientSecret>, String> {
+pub fn build_secret_store(t: &dyn Transport) -> Result<Vec<ClientSecret>, String> {
     let dir = Path::new(SECRETS_DIR);
     if !dir.is_dir() {
         return Ok(Vec::new());
@@ -4413,6 +4431,16 @@ pub fn compute_client_request(base: &str, arg_tree: &str) -> Result<(String, Str
     request_compute(base, arg_tree, "")
 }
 
+/// Run an already-prepared request with the supplied local secret store carried
+/// in ephemeral request context.
+pub fn compute_client_request_with_store(
+    base: &str,
+    arg_tree: &str,
+    store: &[ClientSecret],
+) -> Result<(String, String), String> {
+    request_compute(base, arg_tree, &secret_store_header(store))
+}
+
 fn request_compute_traced(
     base: &str,
     arg_tree: &str,
diff --git a/design/agent-harness.md b/design/agent-harness.md
index e595cdb1..fcbb608e 100644
--- a/design/agent-harness.md
+++ b/design/agent-harness.md
@@ -97,7 +97,8 @@ already contains one.
 own image):
 
 - `head:commit=` — the human-turn commit to answer (the conversation head);
-- curried config: `api-key`, `system` (the system prompt), `bash-image` (the
+- secret: `anthropic-api-key`, injected at `/secret/anthropic-api-key`;
+- curried config: `system` (the system prompt), `bash-image` (the
   tool registry — just bash for now, an image ref), `model`, `base-url` (default
   `https://api.anthropic.com`; tests point it at a stub), `conversation`
   (names the progress ref);
@@ -237,8 +238,11 @@ commit). Hand-rolled retry on 429/5xx honoring `retry-after`. Top-level
 `cache_control: {"type": "ephemeral"}` on every request — each step replays
 an identical prefix, so steps after the first read the prompt cache.
 
-Secrets: API key curried into the llm-step worker's args. It lives in CAS
-and rides in job payloads; the runner-token auth is the fence.
+Secrets: the client reads its git-ignored `.caos-secrets` store when preparing
+and dispatching a turn. `llm-step` reads `anthropic-api-key` from
+`/secret/anthropic-api-key`; the value never enters its args or CAS. Reader
+expressions and `secret-hash` give the request its per-secret cache identity,
+and the server carries the store to entitled tool sub-runs.
 
 ## Progress
 
diff --git a/std/llm-call/src/main.rs b/std/llm-call/src/main.rs
index 59c4cd36..ba008709 100644
--- a/std/llm-call/src/main.rs
+++ b/std/llm-call/src/main.rs
@@ -1,6 +1,7 @@
 //! A stateless, tool-free LLM call for small auxiliary jobs.
 //!
-//! Curried configuration: `api-key`, and optionally `base-url`. Call inputs:
+//! The API key is injected as the `anthropic-api-key` secret. Optional curried
+//! configuration: `base-url`. Call inputs:
 //! `system`, a JSON `messages` array, and optionally `model` and `max-tokens`.
 //! The result is the response's text blocks as a plain blob. This worker owns
 //! no conversation commits, tools, status refs, or presentation-specific
@@ -10,14 +11,14 @@ use std::fs;
 
 use llm_client::{post_messages, DEFAULT_BASE_URL, DEFAULT_MODEL};
 use serde_json::{json, Value};
-use worker_common::{caos, path, read_arg, read_arg_opt, run_worker, scratch};
+use worker_common::{caos, path, read_arg, read_arg_opt, run_worker, scratch, secret};
 
 fn main() -> std::process::ExitCode {
     run_worker("llm-call", run)
 }
 
 fn run() -> Result<(), String> {
-    let api_key = read_arg("api-key")?;
+    let api_key = secret("anthropic-api-key")?;
     let base_url = read_arg_opt("base-url")?.unwrap_or_else(|| DEFAULT_BASE_URL.to_string());
     let model = read_arg_opt("model")?.unwrap_or_else(|| DEFAULT_MODEL.to_string());
     let system = read_arg("system")?;
diff --git a/std/llm-step/src/main.rs b/std/llm-step/src/main.rs
index a97189d9..d824481a 100644
--- a/std/llm-step/src/main.rs
+++ b/std/llm-step/src/main.rs
@@ -24,7 +24,8 @@ use llm_client::{post_messages, DEFAULT_BASE_URL};
 use serde_json::{json, Value};
 use worker_common::{
     arg, caos, caos_curry, caos_recurry, cas_hash, forward, link, own_args_tree, path, read_arg,
-    read_arg_opt, read_commit, run_then_catching, run_worker, scratch, write_commit_as, Arg,
+    read_arg_opt, read_commit, run_then_catching, run_worker, scratch, secret, write_commit_as,
+    Arg,
 };
 
 const AGENT_AUTHOR: &str = "caos-agent";
@@ -86,7 +87,7 @@ fn image_arg(name: &str) -> Result<Option<String>, String> {
 impl Config {
     fn read() -> Result<Config, String> {
         Ok(Config {
-            api_key: read_arg("api-key")?,
+            api_key: secret("anthropic-api-key")?,
             system: read_arg("system")?,
             bash_image: image_arg("bash-image")?.ok_or("--bash-image is required")?,
             grep_image: image_arg("grep-image")?,
@@ -924,7 +925,7 @@ fn launch_githist(
 }
 
 /// Rebuild ourselves as the callback for one compute tool. We carry our WHOLE current ArgTree
-/// forward with [`own_args_tree`] (so the static config — `api-key`, `system`,
+/// forward with [`own_args_tree`] (so the static config — `system`,
 /// `bash-image`, `head`, `worker1`, and the optional
 /// `model`/`base-url`/`conversation`/`grep-image`/`tools-image`/`merge-image`/`merge-refs`
 /// — rides along and a NEW config arg needs no edit here) and manage only the
diff --git a/std/llm-test/common.sh b/std/llm-test/common.sh
index da15662f..6ab9a013 100644
--- a/std/llm-test/common.sh
+++ b/std/llm-test/common.sh
@@ -63,6 +63,14 @@ llm_test_setup() {
   stub_bin=/tmp/llm-stub-bin
   install -m 755 /tmp/llm-stub-entry/bin/llm-stub "$stub_bin"
   stub_host=${CAOS_STUB_HOST:-host.containers.internal}
+  mkdir -p .caos-secrets
+  printf '.caos-secrets/\n' >> .git/info/exclude
+  printf '%s\n' \
+    'name=anthropic-api-key' \
+    'value=test-key' \
+    'entropy=0123456789abcdef0123456789abcdef' \
+    'reader=DEEP-DEPS/llm-step' \
+    > .caos-secrets/anthropic-api-key
 }
 
 start_stub() { # <fixture-dir> <pid-variable> <port-variable>
@@ -106,7 +114,7 @@ new_llm_conversation() { # <suffix> <port>
   conversation_ref="refs/caos/v2/conversations/$conv/head"
   # shellcheck disable=SC2034
   llm=$("$CAOS_CLI" curry --base:@=DEEP-DEPS/llm-step \
-    --api-key=test-key --system:@=system.txt \
+    --system:@=system.txt \
     --model=test-model --base-url="http://$stub_host:$stub_port" \
     --conversation="$conv")
 }
diff --git a/tests/caos-tools/cli.sh b/tests/caos-tools/cli.sh
index dbc5f1c0..b2d00e91 100755
--- a/tests/caos-tools/cli.sh
+++ b/tests/caos-tools/cli.sh
@@ -110,12 +110,20 @@ done
 trap 'kill "$stub_pid" 2>/dev/null || true' EXIT
 
 echo "== run the turn ==" >&2
+mkdir -p .caos-secrets
+printf '.caos-secrets/\n' >> .git/info/exclude
+printf '%s\n' \
+  'name=anthropic-api-key' \
+  'value=test-key' \
+  'entropy=0123456789abcdef0123456789abcdef' \
+  'reader=DEEP-DEPS/llm-step' \
+  > .caos-secrets/anthropic-api-key
 test_run_id="$(date +%s%N)-$$-$RANDOM"
 conv="${test_run_id}-ct"
 conversation_ref="refs/caos/v2/conversations/$conv/head"
 stub_host=${CAOS_STUB_HOST:-host.containers.internal}
 llm=$("$CAOS_CLI" curry --base:@=DEEP-DEPS/llm-step \
-  --api-key=test-key --system:@=system.txt \
+  --system:@=system.txt \
   --model=test-model \
   --base-url="http://$stub_host:$port" --conversation="$conv")
 request=$("$CAOS_CLI" prepare-request --base:hash="$llm" --head:commit="$human1")
diff --git a/tests/chat-offline/cli.sh b/tests/chat-offline/cli.sh
index cba6ae03..ad4c21cb 100755
--- a/tests/chat-offline/cli.sh
+++ b/tests/chat-offline/cli.sh
@@ -103,18 +103,24 @@ stub_host=${CAOS_STUB_HOST:-host.containers.internal}
 opts=(--model test-model --base-url "http://$stub_host:$port")
 
 echo "== request preparation fails before admission ==" >&2
-if env -u ANTHROPIC_API_KEY \
-    "$CAOS_CLI" chat "$queued_conv" -m "hello" --base "$base" "${opts[@]}" 2>key.err; then
-  fail "chat succeeded without ANTHROPIC_API_KEY"
+if "$CAOS_CLI" chat "$queued_conv" -m "hello" --base "$base" "${opts[@]}" 2>key.err; then
+  fail "chat succeeded without its model secret"
 fi
-grep -q "ANTHROPIC_API_KEY" key.err || fail "missing-key error is unclear"
+grep -q "anthropic-api-key" key.err || fail "missing-key error is unclear"
 if remote_tip "$queued_ref" >/dev/null; then
   fail "request-preparation failure partially admitted a conversation"
 fi
 [ ! -e stub/request-1.json ] || fail "missing-key failure reached the LLM"
 
 echo "== invalid bases publish no conversation ==" >&2
-export ANTHROPIC_API_KEY=test-key
+mkdir -p .caos-secrets
+printf '.caos-secrets/\n' >> .git/info/exclude
+printf '%s\n' \
+  'name=anthropic-api-key' \
+  'value=test-key' \
+  'entropy=0123456789abcdef0123456789abcdef' \
+  'reader=DEEP-DEPS/llm-step' \
+  > .caos-secrets/anthropic-api-key
 mkdir -p bad/.caos
 echo reserved > bad/.caos/marker
 git add bad
@@ -177,6 +183,27 @@ grep -qF "$TALK_TEXT" talk.events || fail "post-disconnect assistant event is mi
 [ "$(git show "$tip:notes/todo.txt")" = "hello notes" ] \
   || fail "completed conversation lost its base workspace"
 
+admission=""
+current=$tip
+while [ "$current" != "$base" ]; do
+  event=$(git show -s --format=%B "$current" | tr -d '\n')
+  if jq -e '.status == "queued" and (.request | type == "string") and (.request_head | type == "string")' \
+      <<<"$event" >/dev/null; then
+    admission=$current
+    break
+  fi
+  current=$(git rev-parse "$current^1")
+done
+[ -n "$admission" ] || fail "atomic request admission event is missing"
+admission_event=$(git show -s --format=%B "$admission" | tr -d '\n')
+request=$(jq -r '.request' <<<"$admission_event")
+request_args=$(git ls-tree --name-only "$request")
+grep -qx 'secret-hash' <<<"$request_args" \
+  || fail "conversation request is not isolated by its model secret"
+if grep -qx 'api-key' <<<"$request_args"; then
+  fail "conversation request still contains a curried API key"
+fi
+
 title_ref="refs/caos/v2/conversations/$conv/title"
 title=$(remote_tip "$title_ref") || fail "conversation has no title ref"
 git fetch -q caos "$title"
diff --git a/tests/chat-online/cli.sh b/tests/chat-online/cli.sh
index fdfe0168..cad9aab1 100644
--- a/tests/chat-online/cli.sh
+++ b/tests/chat-online/cli.sh
@@ -19,6 +19,15 @@ if [ -z "${ANTHROPIC_API_KEY:-}" ]; then
   exit 0
 fi
 
+mkdir -p .caos-secrets
+printf '.caos-secrets/\n' >> .git/info/exclude
+printf '%s\n' \
+  'name=anthropic-api-key' \
+  "value=$ANTHROPIC_API_KEY" \
+  'entropy=0123456789abcdef0123456789abcdef' \
+  'reader=DEEP-DEPS/llm-step' \
+  > .caos-secrets/anthropic-api-key
+
 # The human commit carries the client's git identity; pin one so the test
 # doesn't depend on host-global config.
 git config user.name chat-online-test
diff --git a/tests/chat-tools-grep/cli.sh b/tests/chat-tools-grep/cli.sh
index 8e55db24..7569aea6 100755
--- a/tests/chat-tools-grep/cli.sh
+++ b/tests/chat-tools-grep/cli.sh
@@ -15,7 +15,6 @@ echo "goodbye world" > ws/notes/new.txt
 commit "search fixture"
 git config user.name tester
 git config user.email tester@example.com
-export ANTHROPIC_API_KEY=test-key
 base=$(mkcommit "HEAD:ws" base)
 
 GREP_CALLS='[
diff --git a/tests/chat-tools-mixed/cli.sh b/tests/chat-tools-mixed/cli.sh
index 5b468a6f..a65b483f 100755
--- a/tests/chat-tools-mixed/cli.sh
+++ b/tests/chat-tools-mixed/cli.sh
@@ -14,7 +14,6 @@ echo "fixture" > ws/original.txt
 commit "workspace"
 git config user.name tester
 git config user.email tester@example.com
-export ANTHROPIC_API_KEY=test-key
 base=$(mkcommit "HEAD:ws" base)
 
 MIXED_CALLS='[
diff --git a/tests/chat-tools/cli.sh b/tests/chat-tools/cli.sh
index c4005a1e..c0f99668 100755
--- a/tests/chat-tools/cli.sh
+++ b/tests/chat-tools/cli.sh
@@ -15,7 +15,6 @@ echo "hello notes" > ws/notes/todo.txt
 commit "workspace"
 git config user.name tester
 git config user.email tester@example.com
-export ANTHROPIC_API_KEY=test-key
 base=$(mkcommit "HEAD:ws" base)
 
 INLINE_CALLS='[
diff --git a/tests/llm-call/cli.sh b/tests/llm-call/cli.sh
index 928e7b90..011d9151 100755
--- a/tests/llm-call/cli.sh
+++ b/tests/llm-call/cli.sh
@@ -43,9 +43,17 @@ done
 trap 'kill "$stub_pid" 2>/dev/null || true' EXIT
 
 stub_host=${CAOS_STUB_HOST:-host.containers.internal}
+mkdir -p .caos-secrets
+printf '.caos-secrets/\n' >> .git/info/exclude
+printf '%s\n' \
+  'name=anthropic-api-key' \
+  'value=test-key' \
+  'entropy=0123456789abcdef0123456789abcdef' \
+  'reader=DEEP-DEPS/llm-call' \
+  > .caos-secrets/anthropic-api-key
 call=$(
   "$CAOS_CLI" curry --base:@=DEEP-DEPS/llm-call \
-    --api-key=test-key --base-url="http://$stub_host:$port"
+    --base-url="http://$stub_host:$port"
 )
 messages='[{"role":"user","content":"Name the sidebar task"}]'
 result=$(
diff --git a/tests/max-tokens/cli.sh b/tests/max-tokens/cli.sh
index b0ea88f4..6007c162 100644
--- a/tests/max-tokens/cli.sh
+++ b/tests/max-tokens/cli.sh
@@ -68,6 +68,14 @@ done
 trap 'kill "$stub_pid" 2>/dev/null || true' EXIT
 
 echo "== curry llm-step and run the turn ==" >&2
+mkdir -p .caos-secrets
+printf '.caos-secrets/\n' >> .git/info/exclude
+printf '%s\n' \
+  'name=anthropic-api-key' \
+  'value=test-key' \
+  'entropy=0123456789abcdef0123456789abcdef' \
+  'reader=DEEP-DEPS/llm-step' \
+  > .caos-secrets/anthropic-api-key
 test_run_id="$(date +%s%N)-$$-$RANDOM"
 conv="${test_run_id}-max-tokens"
 conversation_ref="refs/caos/v2/conversations/$conv/head"
@@ -77,7 +85,7 @@ stub_host=${CAOS_STUB_HOST:-host.containers.internal}
 # NO TOOL IMAGES: llm-step's `.caos-expr` binds its own (std/llm-step/DEPS), so
 # a caller says what the turn is, never which shell the agent greps with.
 llm=$("$CAOS_CLI" curry --base:@=DEEP-DEPS/llm-step \
-  --api-key=test-key --system:@=system.txt \
+  --system:@=system.txt \
   --model=test-model --base-url="http://$stub_host:$port" \
   --conversation="$conv")
 
diff --git a/tests/merge-harness/cli.sh b/tests/merge-harness/cli.sh
index e4f0083f..fc4c9593 100755
--- a/tests/merge-harness/cli.sh
+++ b/tests/merge-harness/cli.sh
@@ -54,12 +54,20 @@ done
 trap 'kill "$stub_pid" 2>/dev/null || true' EXIT
 
 echo "== dispatch merge turn ==" >&2
+mkdir -p .caos-secrets
+printf '.caos-secrets/\n' >> .git/info/exclude
+printf '%s\n' \
+  'name=anthropic-api-key' \
+  'value=test-key' \
+  'entropy=0123456789abcdef0123456789abcdef' \
+  'reader=DEEP-DEPS/llm-step' \
+  > .caos-secrets/anthropic-api-key
 test_run_id="$(date +%s%N)-$$-$RANDOM"
 conv="${test_run_id}-merge"
 conversation_ref="refs/caos/v2/conversations/$conv/head"
 stub_host=${CAOS_STUB_HOST:-host.containers.internal}
 llm=$("$CAOS_CLI" curry --base:@=DEEP-DEPS/llm-step \
-  --api-key=test-key --system:@=system.txt \
+  --system:@=system.txt \
   --merge-refs="feature $feature" \
   --model=test-model --base-url="http://$stub_host:$port" \
   --conversation="$conv")

From 50b824a0a239ffeeeb2f74b91529557ed668903d Mon Sep 17 00:00:00 2001
From: Nishad <nishu.builder@gmail.com>
Date: Tue, 18 Aug 2026 22:04:08 -0700
Subject: [PATCH 2/4] Carry secrets into detached conversation work

---
 crates/caos/src/bin/caos.rs    | 30 ++++++++++++++++++
 crates/caos/src/lib.rs         | 35 ++++++++++++++++----
 crates/server/src/compute.rs   | 11 ++++++-
 crates/server/src/runner.rs    | 10 ++++++
 crates/server/src/secrets.rs   | 58 +++++++++++++++++++++++++++++++---
 std/llm-step/src/async_work.rs |  2 +-
 std/llm-step/src/main.rs       | 10 +++++-
 std/llm-step/src/subagents.rs  |  2 +-
 8 files changed, 144 insertions(+), 14 deletions(-)

diff --git a/crates/caos/src/bin/caos.rs b/crates/caos/src/bin/caos.rs
index 0fc61ba2..d0601f80 100644
--- a/crates/caos/src/bin/caos.rs
+++ b/crates/caos/src/bin/caos.rs
@@ -155,6 +155,9 @@ struct RunnerJob {
     /// Secrets the server granted this job (design/secrets.md): name → value.
     /// Dropped at `/secret/<name>` for the worker, out of band from its args.
     secrets: Vec<(String, String)>,
+    /// Grants this job was already entitled to, serialized for an explicit
+    /// detached `run-async` launched by the worker.
+    delegated_secrets: String,
 }
 
 impl RunnerJob {
@@ -188,6 +191,7 @@ impl RunnerJob {
             nonce,
             token: field("token").map(str::to_string),
             secrets,
+            delegated_secrets: field("delegated_secrets").unwrap_or_default().to_string(),
         })
     }
 }
@@ -243,10 +247,12 @@ fn run_runner_job(
     // first, so a warm runner never leaks a secret into a later job that wasn't
     // granted it.
     write_secrets(&job.secrets)?;
+    write_delegated_secrets(&job.delegated_secrets)?;
     let ran = run_worker(&envs, &job.secrets);
     // Remove the secrets whether the worker passed or failed; the next job's
     // `write_secrets` also wipes, but don't leave plaintext around meanwhile.
     remove_secrets();
+    remove_delegated_secrets();
     ran?;
     let result = read_result(&cas)?;
     remove_cas(&cas)?;
@@ -288,6 +294,30 @@ fn remove_secrets() {
     let _ = std::fs::remove_dir_all(SECRET_DIR);
 }
 
+/// Write the serialized grants where only the root runner and the setuid
+/// `caos run-async` client can read them. The ordinary worker already receives
+/// each granted value through `/secret/<name>`; it does not need this metadata.
+fn write_delegated_secrets(secrets: &str) -> Result<(), String> {
+    remove_delegated_secrets();
+    if secrets.is_empty() {
+        return Ok(());
+    }
+    let path = std::path::Path::new(caos::DELEGATED_SECRETS_PATH);
+    let parent = path
+        .parent()
+        .ok_or("delegated secrets path has no parent")?;
+    std::fs::create_dir_all(parent)
+        .map_err(|error| format!("creating {}: {error}", parent.display()))?;
+    std::fs::write(path, secrets)
+        .map_err(|error| format!("writing {}: {error}", path.display()))?;
+    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o400))
+        .map_err(|error| format!("chmod {}: {error}", path.display()))
+}
+
+fn remove_delegated_secrets() {
+    let _ = std::fs::remove_file(caos::DELEGATED_SECRETS_PATH);
+}
+
 /// Unpack an ArgTree: its hash (returned back for `/cas/args`) and the salt
 /// (its reserved `salt` entry, empty if absent). `base`/`salt` are entries of
 /// this one tree, per SPEC's ArgTree.
diff --git a/crates/caos/src/lib.rs b/crates/caos/src/lib.rs
index 3b48444a..1b4cdab7 100644
--- a/crates/caos/src/lib.rs
+++ b/crates/caos/src/lib.rs
@@ -2093,6 +2093,11 @@ fn send(t: &dyn Transport, h: &Hashed) -> Result<(), String> {
 /// (`bin/caos.rs`), which writes it.
 pub const SECRET_DIR: &str = "/secret";
 
+/// Root-only runtime file holding serialized grants a secret-reading worker
+/// may carry into a detached `run-async`. Written and removed per job by the
+/// container runner; never stored in an ArgTree, curry, image, or Git object.
+pub const DELEGATED_SECRETS_PATH: &str = "/run/caos/delegated-secrets";
+
 /// The raw values of every secret injected into this run, read once from
 /// [`SECRET_DIR`]. Empty off-worker (no such dir) — so the leak scan costs
 /// nothing for the host CLI. Empty values are dropped (nothing to match).
@@ -3335,9 +3340,10 @@ pub fn caos_run_request_then(
 /// thread, so closing our side after sending the request does not cancel it.
 ///
 /// This starts a new top-level run: it does not inherit the caller's run stack,
-/// secrets, credentials, model settings, or other ephemeral execution context.
-/// Callers must use it only for independent work whose complete context is in
-/// the ArgTree.
+/// credentials, model settings, or other ambient execution context. A worker
+/// that was itself granted secrets explicitly delegates that ephemeral store;
+/// the detached run still grants each secret only to matching readers whose
+/// ArgTree carries the corresponding `secret-hash`.
 pub fn caos_run_async(t: &dyn Transport, arg_tree: &str) -> Result<(), String> {
     if !is_hex_hash(arg_tree) || arg_tree.bytes().any(|byte| byte.is_ascii_uppercase()) {
         return Err(format!(
@@ -3368,7 +3374,16 @@ pub fn caos_run_async(t: &dyn Transport, arg_tree: &str) -> Result<(), String> {
     }
     t.ensure_pushed(arg_tree)?;
     let url = run_url(&t.server_url()?, arg_tree, None);
-    dispatch_compute_url(&url)?;
+    let delegated_secrets = match std::fs::read_to_string(DELEGATED_SECRETS_PATH) {
+        Ok(secrets) => secrets,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => String::new(),
+        Err(error) => {
+            return Err(format!(
+                "reading delegated secrets from {DELEGATED_SECRETS_PATH}: {error}"
+            ))
+        }
+    };
+    dispatch_compute_url(&url, &delegated_secrets)?;
     println!("request {arg_tree}");
     Ok(())
 }
@@ -4465,7 +4480,7 @@ fn run_url(base: &str, arg_tree: &str, trace_id: Option<&str>) -> String {
 /// already outlives a disconnected caller, while the conversation's durable
 /// `pending` entry makes a dispatch that dies before reaching the server safe to
 /// retry. Waiting for response headers here would wait for the run itself.
-fn dispatch_compute_url(url: &str) -> Result<(), String> {
+fn dispatch_compute_url(url: &str, secrets: &str) -> Result<(), String> {
     let rest = url
         .strip_prefix("http://")
         .ok_or_else(|| format!("run-async only supports plain HTTP server URLs: {url}"))?;
@@ -4524,9 +4539,17 @@ fn dispatch_compute_url(url: &str) -> Result<(), String> {
     stream
         .set_write_timeout(Some(DISPATCH_TIMEOUT))
         .map_err(|error| format!("setting write timeout for {authority}: {error}"))?;
+    if secrets.contains(['\r', '\n']) {
+        return Err("delegated secrets contain a newline".to_string());
+    }
+    let secrets_header = if secrets.is_empty() {
+        String::new()
+    } else {
+        format!("{SECRETS_HEADER}: {secrets}\r\n")
+    };
     write!(
         stream,
-        "GET {path} HTTP/1.1\r\nHost: {authority}\r\n{}: {}\r\nConnection: close\r\n\r\n",
+        "GET {path} HTTP/1.1\r\nHost: {authority}\r\n{}: {}\r\n{secrets_header}Connection: close\r\n\r\n",
         caos_world::WORLD_HEADER,
         caos_world::WORLD,
     )
diff --git a/crates/server/src/compute.rs b/crates/server/src/compute.rs
index cb02bb14..5c760c3b 100644
--- a/crates/server/src/compute.rs
+++ b/crates/server/src/compute.rs
@@ -351,7 +351,16 @@ fn run_dispatch(
         // cache key — and the container runner drops them at `/secret/<name>`.
         // Read from `arg_entries` before dispatch takes ownership of it.
         let granted = crate::secrets::grant(secrets, &arg_entries);
-        crate::runner::dispatch(arg_tree, arg_entries, &image_ref, seeded, granted).map_err(fail)?
+        let delegated_secrets = crate::secrets::delegated_header(secrets, &arg_entries);
+        crate::runner::dispatch(
+            arg_tree,
+            arg_entries,
+            &image_ref,
+            seeded,
+            granted,
+            delegated_secrets,
+        )
+        .map_err(fail)?
     };
 
     if result_hash(&result).is_empty() {
diff --git a/crates/server/src/runner.rs b/crates/server/src/runner.rs
index e5762698..1a6c14b2 100644
--- a/crates/server/src/runner.rs
+++ b/crates/server/src/runner.rs
@@ -143,6 +143,11 @@ struct Job {
     /// never in the ArgTree — so out of the cache key. Recomputed per dispatch,
     /// so a warm runner's follow-up jobs each carry their own.
     secrets: Vec<(String, String)>,
+    /// Serialized grants this worker was already entitled to. The runner
+    /// exposes them ephemerally so `caos run-async` can preserve the store
+    /// across a detached-run boundary; the new run still reader-matches before
+    /// injecting anything.
+    delegated_secrets: String,
     /// Current rendezvous nonce; refreshed on requeue (first post per nonce wins).
     nonce: String,
     phase: Phase,
@@ -301,6 +306,9 @@ fn payload(job: &Job) -> String {
                 .collect(),
         );
     }
+    if !job.delegated_secrets.is_empty() {
+        body["delegated_secrets"] = serde_json::Value::String(job.delegated_secrets.clone());
+    }
     body.to_string()
 }
 
@@ -313,6 +321,7 @@ pub(crate) fn dispatch(
     image_ref: &str,
     seeded: bool,
     secrets: Vec<(String, String)>,
+    delegated_secrets: String,
 ) -> Result<String, HttpError> {
     let (outcome_tx, outcome_rx) = mpsc::channel();
     let id = {
@@ -344,6 +353,7 @@ pub(crate) fn dispatch(
                 image_ref: image_ref.to_string(),
                 arg_entries,
                 secrets,
+                delegated_secrets,
                 nonce,
                 phase: Phase::Pending {
                     deadline,
diff --git a/crates/server/src/secrets.rs b/crates/server/src/secrets.rs
index baf484af..2e62cfdc 100644
--- a/crates/server/src/secrets.rs
+++ b/crates/server/src/secrets.rs
@@ -14,17 +14,21 @@
 //! The server parses the maps into [`Grant`]s, threads them through
 //! promise resolution to every sub-run's dispatch, and at each dispatch does
 //! the cheap subset-match + injection. So a sub-worker is entitled by matching
-//! *its own* arg tree, never by inheritance (the no-delegation invariant).
+//! *its own* arg tree, never merely by inheritance. A secret-reading worker may
+//! explicitly carry its already-matched grants across `run-async`; the new run
+//! repeats this same reader and `secret-hash` check before every injection.
 
 use std::collections::{BTreeMap, HashSet};
 
+use serde::Serialize;
+
 /// The header carrying the serialized store from client to server.
 pub(crate) const HEADER: &str = "X-Caos-Secrets";
 
 /// One secret the run carries: its value, its entropy (the cache-isolation
 /// capability — hashed into `secret-hash`, never stored raw), and the readers
 /// (each a partial arg tree, already resolved client-side to name → oid).
-#[derive(Clone)]
+#[derive(Clone, Serialize)]
 pub(crate) struct Grant {
     name: String,
     value: String,
@@ -100,6 +104,34 @@ pub(crate) fn grant(
     grants: &[Grant],
     arg_entries: &BTreeMap<String, String>,
 ) -> Vec<(String, String)> {
+    matching_grants(grants, arg_entries)
+        .into_iter()
+        .map(|grant| {
+            eprintln!("secret {}: granted to this job", grant.name);
+            (grant.name.clone(), grant.value.clone())
+        })
+        .collect()
+}
+
+/// Serialize the grants this job was already entitled to so a detached
+/// `run-async` it launches can carry them into its own top-level run. The
+/// detached run still subset-matches each eventual worker and verifies its
+/// `secret-hash`; this only preserves the ephemeral store across the one
+/// boundary that server-side promise resolution cannot span.
+pub(crate) fn delegated_header(grants: &[Grant], arg_entries: &BTreeMap<String, String>) -> String {
+    let matching = matching_grants(grants, arg_entries);
+    if matching.is_empty() {
+        return String::new();
+    }
+    serde_json::to_string(&matching).unwrap_or_default()
+}
+
+/// Grants whose reader and cache-isolation capability both match this job,
+/// deduplicated by name in store order.
+fn matching_grants<'a>(
+    grants: &'a [Grant],
+    arg_entries: &BTreeMap<String, String>,
+) -> Vec<&'a Grant> {
     // The hash this job's matched grants require. None ⇒ nothing matches.
     let Some(digest) = secret_hash(grants, arg_entries) else {
         return Vec::new();
@@ -126,8 +158,7 @@ pub(crate) fn grant(
             .iter()
             .any(|reader| is_subset(reader, arg_entries));
         if visible && seen.insert(grant.name.clone()) {
-            eprintln!("secret {}: granted to this job", grant.name);
-            out.push((grant.name.clone(), grant.value.clone()));
+            out.push(grant);
         }
     }
     out
@@ -238,6 +269,25 @@ mod tests {
         assert!(grant(&grants, &map(&[("base", "xx")])).is_empty());
     }
 
+    #[test]
+    fn delegated_header_contains_only_grants_the_worker_can_read() {
+        let grants = parse_header(
+            r#"[{"name":"yes","value":"one","entropy":"E1","readers":[{"base":"aa"}]},
+                 {"name":"no","value":"two","entropy":"E2","readers":[{"base":"bb"}]}]"#,
+        );
+        let mut job = map(&[("base", "aa")]);
+        let digest = secret_hash(&grants, &job).unwrap();
+        job.insert(
+            caos_world::SECRET_HASH_ARG.to_string(),
+            blob_oid(digest.as_bytes()),
+        );
+        let carried = parse_header(&delegated_header(&grants, &job));
+        assert_eq!(
+            grant(&carried, &job),
+            vec![("yes".to_string(), "one".to_string())]
+        );
+    }
+
     #[test]
     fn empty_or_malformed_header_grants_nothing() {
         assert!(parse_header("").is_empty());
diff --git a/std/llm-step/src/async_work.rs b/std/llm-step/src/async_work.rs
index 3deb4ed5..e273c722 100644
--- a/std/llm-step/src/async_work.rs
+++ b/std/llm-step/src/async_work.rs
@@ -24,7 +24,7 @@ pub const TOOL_NAME: &str = "run_async";
 pub fn declaration() -> Value {
     json!({
         "name": TOOL_NAME,
-        "description": "Start or inspect an already-constructed CAOS request in the background. The request must be a complete 40-character ArgTree hash already stored in CAOS. Repeating the same request reads the same durable task; once complete, the result includes its result hash. Use this only for independent work whose complete context is in the request: detached work does not inherit secrets, credentials, model settings, or other ambient execution context.",
+        "description": "Start or inspect an already-constructed CAOS request in the background. The request must be a complete 40-character ArgTree hash already stored in CAOS. Repeating the same request reads the same durable task; once complete, the result includes its result hash. Use this only for independent work whose complete context is in the request: detached work does not inherit credentials, model settings, or other ambient execution context. Secrets explicitly granted to this worker remain available only to matching readers in the detached run.",
         "input_schema": {
             "type": "object",
             "properties": {
diff --git a/std/llm-step/src/main.rs b/std/llm-step/src/main.rs
index d824481a..26fbdaff 100644
--- a/std/llm-step/src/main.rs
+++ b/std/llm-step/src/main.rs
@@ -86,6 +86,14 @@ fn image_arg(name: &str) -> Result<Option<String>, String> {
 
 impl Config {
     fn read() -> Result<Config, String> {
+        // A child keeps this image in its ArgTree so it remains a superset of
+        // the configured llm-step secret reader, but the marker preserves the
+        // existing rule that a subagent cannot launch more detached agents.
+        let run_and_update_ref_image = if read_arg_opt("subagent")?.is_some() {
+            None
+        } else {
+            image_arg("run-and-update-ref-image")?
+        };
         Ok(Config {
             api_key: secret("anthropic-api-key")?,
             system: read_arg("system")?,
@@ -93,7 +101,7 @@ impl Config {
             grep_image: image_arg("grep-image")?,
             tools_image: image_arg("tools-image")?,
             merge_image: image_arg("merge-image")?,
-            run_and_update_ref_image: image_arg("run-and-update-ref-image")?,
+            run_and_update_ref_image,
             merge_refs: read_arg_opt("merge-refs")?,
             model: read_arg("model")?,
             base_url: read_arg_opt("base-url")?.unwrap_or_else(|| DEFAULT_BASE_URL.to_string()),
diff --git a/std/llm-step/src/subagents.rs b/std/llm-step/src/subagents.rs
index 2a0d3f7c..1a37db15 100644
--- a/std/llm-step/src/subagents.rs
+++ b/std/llm-step/src/subagents.rs
@@ -148,7 +148,6 @@ fn child_request(agent: &str, root: &str, system: &str) -> Result<String, String
         "head",
         "system",
         "merge-refs",
-        "run-and-update-ref-image",
         "wc",
         "run",
         "round",
@@ -172,6 +171,7 @@ fn child_request(agent: &str, root: &str, system: &str) -> Result<String, String
         &[
             ("conversation", Arg::Lit(agent)),
             ("head", Arg::Path(&root_path)),
+            ("subagent", Arg::Lit("true")),
             ("system", Arg::Lit(&child_system)),
         ],
     )?;

From 12db5099c5e20af582afa701c1365ef1a533a30c Mon Sep 17 00:00:00 2001
From: Nishad <nishu.builder@gmail.com>
Date: Wed, 19 Aug 2026 15:36:32 -0700
Subject: [PATCH 3/4] Pin LLM secret readers to their base URL

---
 README.md                     |  9 ++++++---
 crates/caos-cli/src/lib.rs    | 16 +++++++++-------
 design/agent-harness.md       | 18 ++++++++++--------
 std/llm-call/src/main.rs      |  9 +++++----
 std/llm-step/src/main.rs      |  4 ++--
 std/llm-test/common.sh        |  7 ++++++-
 tests/caos-tools/cli.sh       |  4 ++--
 tests/chat-offline/cli.sh     |  9 ++++++++-
 tests/chat-online/cli.sh      |  2 +-
 tests/chat-tools-grep/cli.sh  |  1 +
 tests/chat-tools-mixed/cli.sh |  1 +
 tests/chat-tools/cli.sh       |  1 +
 tests/llm-call/cli.sh         |  2 +-
 tests/max-tokens/cli.sh       |  4 ++--
 tests/merge-harness/cli.sh    |  4 ++--
 15 files changed, 57 insertions(+), 34 deletions(-)

diff --git a/README.md b/README.md
index ef695159..b3603362 100644
--- a/README.md
+++ b/README.md
@@ -329,13 +329,16 @@ putting it in a curried worker. A minimal per-device setup is:
 # .caos-secrets/anthropic-api-key
 name=anthropic-api-key
 value:@=/absolute/path/to/anthropic-api-key
-reader=DEEP-DEPS/llm-step
-reader=DEEP-DEPS/llm-call
+reader=--base:@=DEEP-DEPS/llm-step --base-url=https://api.anthropic.com
+reader=--base:@=DEEP-DEPS/llm-call --base-url=https://api.anthropic.com
 ```
 
 Run `caos-cli secrets` once to add the random `entropy=` used for cache
 isolation. The file and value path stay local; only the entropy-derived identity
-enters an ArgTree, while the value is carried out of band for the run.
+enters an ArgTree, while the value is carried out of band for the run. Pinning
+`base-url` beside the model credential prevents a worker configured for another
+destination from receiving that credential; a custom endpoint remains supported
+when the local reader pins that exact URL.
 
 `caos-cli` must run inside a git working tree with the server as its `caos`
 remote — the remote's URL is also where compute is triggered and results are
diff --git a/crates/caos-cli/src/lib.rs b/crates/caos-cli/src/lib.rs
index 95d877ca..fb61efda 100644
--- a/crates/caos-cli/src/lib.rs
+++ b/crates/caos-cli/src/lib.rs
@@ -29,6 +29,7 @@ const MODEL_API_SECRET: &str = "anthropic-api-key";
 const AUTO_NAME_PREFIX: &str = "talk-";
 const MERGE_REF_CANDIDATES: &[&str] = &["main", "master", "origin/main", "origin/master"];
 pub const DEFAULT_MODEL: &str = "claude-opus-4-8";
+const DEFAULT_BASE_URL: &str = "https://api.anthropic.com";
 const DEFAULT_SYSTEM: &str = "You are a coding agent operating on a git workspace. Use the \
     available tools for file access, builds, tests, and edits. Keep responses concise.";
 
@@ -1071,9 +1072,10 @@ fn resolve_llm(
         "--model={}",
         options.model.as_deref().unwrap_or(DEFAULT_MODEL)
     ));
-    if let Some(base_url) = &options.base_url {
-        config.push(format!("--base-url={base_url}"));
-    }
+    config.push(format!(
+        "--base-url={}",
+        options.base_url.as_deref().unwrap_or(DEFAULT_BASE_URL)
+    ));
     let llm_base = eval_workspace_dep_with_store(t, "llm-step", store)?;
     curry_client_object(t, &llm_base, &config).map(|hash| hash.to_string())
 }
@@ -2037,10 +2039,10 @@ pub fn generate_conversation_title(
 ) -> Result<String, String> {
     let store = build_secret_store(t)?;
     require_model_secret(&store)?;
-    let mut kvs = Vec::new();
-    if let Some(url) = &options.base_url {
-        kvs.push(format!("--base-url={url}"));
-    }
+    let kvs = vec![format!(
+        "--base-url={}",
+        options.base_url.as_deref().unwrap_or(DEFAULT_BASE_URL)
+    )];
     let llm_base = eval_workspace_dep_with_store(t, "llm-call", &store)?;
     let llm = curry_client_object(t, &llm_base, &kvs)?.to_string();
     let messages = serde_json::to_string(&title_messages(first_message))
diff --git a/design/agent-harness.md b/design/agent-harness.md
index fcbb608e..3f680070 100644
--- a/design/agent-harness.md
+++ b/design/agent-harness.md
@@ -99,8 +99,9 @@ own image):
 - `head:commit=` — the human-turn commit to answer (the conversation head);
 - secret: `anthropic-api-key`, injected at `/secret/anthropic-api-key`;
 - curried config: `system` (the system prompt), `bash-image` (the
-  tool registry — just bash for now, an image ref), `model`, `base-url` (default
-  `https://api.anthropic.com`; tests point it at a stub), `conversation`
+  tool registry — just bash for now, an image ref), `model`, `base-url` (always
+  explicit in the ArgTree; the client binds `https://api.anthropic.com` unless
+  overridden, and tests bind their exact stub URL), `conversation`
   (names the progress ref);
 - continuation state, curried by the worker itself between tool calls:
   `step:commit=` (the newest step commit), `pending` / `results` (JSON arrays
@@ -240,9 +241,10 @@ an identical prefix, so steps after the first read the prompt cache.
 
 Secrets: the client reads its git-ignored `.caos-secrets` store when preparing
 and dispatching a turn. `llm-step` reads `anthropic-api-key` from
-`/secret/anthropic-api-key`; the value never enters its args or CAS. Reader
-expressions and `secret-hash` give the request its per-secret cache identity,
-and the server carries the store to entitled tool sub-runs.
+`/secret/anthropic-api-key`; the value never enters its args or CAS. Its reader
+pins the allowed `base-url` as local, per-device policy. The explicit URL and
+entropy-derived `secret-hash` enter the request, while the API-key value does
+not, and the server carries the store to entitled tool sub-runs.
 
 ## Progress
 
@@ -351,14 +353,14 @@ flags: `--base <revspec>` (a new conversation's base commit, default `HEAD` —
 refused if its tree carries a top-level `.caos`), `--system <text>` /
 `--system-file <path>` (default: a short coding-agent prompt), `--model`,
 `--base-url`, and `--log` (print the conversation so far — the first-parent
-walk — and run nothing). The API key comes only from `$ANTHROPIC_API_KEY`
-(checked before anything is minted).
+walk — and run nothing). The API key comes only from the local
+`.caos-secrets/anthropic-api-key` grant (checked before anything is minted).
 
 The workers are resolved from the WORKSPACE, which declares them in its own
 `DEPS` (`./std/llm-step llm-step`); the root `.caos-expr` expands that into a
 `DEEP-DEPS/` mount and the client descends it (design/caos-expr.md). Each
 resolves to a `curry(runner, bin=<static binary>)` node, so the per-turn state
-(key, system, model…) is curried onto the llm-step curry and layers flatten.
+(system, model, base URL…) is curried onto the llm-step curry and layers flatten.
 
 The tools a turn drives — bash-tool, rgrep, bash, merge — are NOT named by the
 caller. They are llm-step's dependencies, so `std/llm-step/DEPS` declares them
diff --git a/std/llm-call/src/main.rs b/std/llm-call/src/main.rs
index ba008709..4c60aae1 100644
--- a/std/llm-call/src/main.rs
+++ b/std/llm-call/src/main.rs
@@ -1,7 +1,8 @@
 //! A stateless, tool-free LLM call for small auxiliary jobs.
 //!
-//! The API key is injected as the `anthropic-api-key` secret. Optional curried
-//! configuration: `base-url`. Call inputs:
+//! The API key is injected as the `anthropic-api-key` secret. Required curried
+//! configuration: `base-url`, so the credential destination is part of the
+//! ArgTree. Call inputs:
 //! `system`, a JSON `messages` array, and optionally `model` and `max-tokens`.
 //! The result is the response's text blocks as a plain blob. This worker owns
 //! no conversation commits, tools, status refs, or presentation-specific
@@ -9,7 +10,7 @@
 
 use std::fs;
 
-use llm_client::{post_messages, DEFAULT_BASE_URL, DEFAULT_MODEL};
+use llm_client::{post_messages, DEFAULT_MODEL};
 use serde_json::{json, Value};
 use worker_common::{caos, path, read_arg, read_arg_opt, run_worker, scratch, secret};
 
@@ -19,7 +20,7 @@ fn main() -> std::process::ExitCode {
 
 fn run() -> Result<(), String> {
     let api_key = secret("anthropic-api-key")?;
-    let base_url = read_arg_opt("base-url")?.unwrap_or_else(|| DEFAULT_BASE_URL.to_string());
+    let base_url = read_arg("base-url")?;
     let model = read_arg_opt("model")?.unwrap_or_else(|| DEFAULT_MODEL.to_string());
     let system = read_arg("system")?;
     let messages = parse_messages(&read_arg("messages")?)?;
diff --git a/std/llm-step/src/main.rs b/std/llm-step/src/main.rs
index 26fbdaff..4af8218d 100644
--- a/std/llm-step/src/main.rs
+++ b/std/llm-step/src/main.rs
@@ -20,7 +20,7 @@ use std::fs;
 use std::path::Path;
 use std::sync::atomic::{AtomicU32, Ordering};
 
-use llm_client::{post_messages, DEFAULT_BASE_URL};
+use llm_client::post_messages;
 use serde_json::{json, Value};
 use worker_common::{
     arg, caos, caos_curry, caos_recurry, cas_hash, forward, link, own_args_tree, path, read_arg,
@@ -104,7 +104,7 @@ impl Config {
             run_and_update_ref_image,
             merge_refs: read_arg_opt("merge-refs")?,
             model: read_arg("model")?,
-            base_url: read_arg_opt("base-url")?.unwrap_or_else(|| DEFAULT_BASE_URL.to_string()),
+            base_url: read_arg("base-url")?,
             conversation: read_arg_opt("conversation")?,
         })
     }
diff --git a/std/llm-test/common.sh b/std/llm-test/common.sh
index 6ab9a013..4d9d2ba4 100644
--- a/std/llm-test/common.sh
+++ b/std/llm-test/common.sh
@@ -65,11 +65,15 @@ llm_test_setup() {
   stub_host=${CAOS_STUB_HOST:-host.containers.internal}
   mkdir -p .caos-secrets
   printf '.caos-secrets/\n' >> .git/info/exclude
+}
+
+pin_llm_step_secret() { # <port>
+  local stub_port=$1
   printf '%s\n' \
     'name=anthropic-api-key' \
     'value=test-key' \
     'entropy=0123456789abcdef0123456789abcdef' \
-    'reader=DEEP-DEPS/llm-step' \
+    "reader=--base:@=DEEP-DEPS/llm-step --base-url=http://$stub_host:$stub_port" \
     > .caos-secrets/anthropic-api-key
 }
 
@@ -106,6 +110,7 @@ start_stub() { # <fixture-dir> <pid-variable> <port-variable>
 
 new_llm_conversation() { # <suffix> <port>
   local suffix=$1 stub_port=$2 test_run_id
+  pin_llm_step_secret "$stub_port"
   test_run_id="$(date +%s%N)-$$-$RANDOM"
   # Globals are the function's interface to the sourcing test.
   # shellcheck disable=SC2034
diff --git a/tests/caos-tools/cli.sh b/tests/caos-tools/cli.sh
index b2d00e91..6e701afb 100755
--- a/tests/caos-tools/cli.sh
+++ b/tests/caos-tools/cli.sh
@@ -108,6 +108,7 @@ for _ in 1 2 3 4 5; do
 done
 [ -n "$stub_pid" ] || fail "could not start llm-stub: $(cat stub/log)"
 trap 'kill "$stub_pid" 2>/dev/null || true' EXIT
+stub_host=${CAOS_STUB_HOST:-host.containers.internal}
 
 echo "== run the turn ==" >&2
 mkdir -p .caos-secrets
@@ -116,12 +117,11 @@ printf '%s\n' \
   'name=anthropic-api-key' \
   'value=test-key' \
   'entropy=0123456789abcdef0123456789abcdef' \
-  'reader=DEEP-DEPS/llm-step' \
+  "reader=--base:@=DEEP-DEPS/llm-step --base-url=http://$stub_host:$port" \
   > .caos-secrets/anthropic-api-key
 test_run_id="$(date +%s%N)-$$-$RANDOM"
 conv="${test_run_id}-ct"
 conversation_ref="refs/caos/v2/conversations/$conv/head"
-stub_host=${CAOS_STUB_HOST:-host.containers.internal}
 llm=$("$CAOS_CLI" curry --base:@=DEEP-DEPS/llm-step \
   --system:@=system.txt \
   --model=test-model \
diff --git a/tests/chat-offline/cli.sh b/tests/chat-offline/cli.sh
index ad4c21cb..d75a0ada 100755
--- a/tests/chat-offline/cli.sh
+++ b/tests/chat-offline/cli.sh
@@ -119,7 +119,7 @@ printf '%s\n' \
   'name=anthropic-api-key' \
   'value=test-key' \
   'entropy=0123456789abcdef0123456789abcdef' \
-  'reader=DEEP-DEPS/llm-step' \
+  "reader=--base:@=DEEP-DEPS/llm-step --base-url=http://$stub_host:$port" \
   > .caos-secrets/anthropic-api-key
 mkdir -p bad/.caos
 echo reserved > bad/.caos/marker
@@ -200,9 +200,16 @@ request=$(jq -r '.request' <<<"$admission_event")
 request_args=$(git ls-tree --name-only "$request")
 grep -qx 'secret-hash' <<<"$request_args" \
   || fail "conversation request is not isolated by its model secret"
+request_base_url=$(git cat-file blob "$request:base-url") \
+  || fail "conversation request has no explicit base-url"
+[ "$request_base_url" = "http://$stub_host:$port" ] \
+  || fail "conversation request has the wrong base-url: $request_base_url"
 if grep -qx 'api-key' <<<"$request_args"; then
   fail "conversation request still contains a curried API key"
 fi
+if git grep -F 'test-key' "$request" -- >/dev/null 2>&1; then
+  fail "conversation ArgTree contains the API-key value"
+fi
 
 title_ref="refs/caos/v2/conversations/$conv/title"
 title=$(remote_tip "$title_ref") || fail "conversation has no title ref"
diff --git a/tests/chat-online/cli.sh b/tests/chat-online/cli.sh
index cad9aab1..08d587b0 100644
--- a/tests/chat-online/cli.sh
+++ b/tests/chat-online/cli.sh
@@ -25,7 +25,7 @@ printf '%s\n' \
   'name=anthropic-api-key' \
   "value=$ANTHROPIC_API_KEY" \
   'entropy=0123456789abcdef0123456789abcdef' \
-  'reader=DEEP-DEPS/llm-step' \
+  'reader=--base:@=DEEP-DEPS/llm-step --base-url=https://api.anthropic.com' \
   > .caos-secrets/anthropic-api-key
 
 # The human commit carries the client's git identity; pin one so the test
diff --git a/tests/chat-tools-grep/cli.sh b/tests/chat-tools-grep/cli.sh
index 7569aea6..228c221d 100755
--- a/tests/chat-tools-grep/cli.sh
+++ b/tests/chat-tools-grep/cli.sh
@@ -31,6 +31,7 @@ stub_pid=""
 port=""
 start_stub stub stub_pid port
 stub_pid="${stub_pid:?start_stub did not set stub_pid}"
+pin_llm_step_secret "$port"
 
 test_run_id="$(date +%s%N)-$$-$RANDOM"
 conv="${test_run_id}-tools-grep"
diff --git a/tests/chat-tools-mixed/cli.sh b/tests/chat-tools-mixed/cli.sh
index a65b483f..ac7aeecb 100755
--- a/tests/chat-tools-mixed/cli.sh
+++ b/tests/chat-tools-mixed/cli.sh
@@ -30,6 +30,7 @@ stub_pid=""
 port=""
 start_stub stub stub_pid port
 stub_pid="${stub_pid:?start_stub did not set stub_pid}"
+pin_llm_step_secret "$port"
 
 test_run_id="$(date +%s%N)-$$-$RANDOM"
 conv="${test_run_id}-tools-mixed"
diff --git a/tests/chat-tools/cli.sh b/tests/chat-tools/cli.sh
index c0f99668..aec13fc7 100755
--- a/tests/chat-tools/cli.sh
+++ b/tests/chat-tools/cli.sh
@@ -33,6 +33,7 @@ stub_pid=""
 port=""
 start_stub stub stub_pid port
 stub_pid="${stub_pid:?start_stub did not set stub_pid}"
+pin_llm_step_secret "$port"
 
 test_run_id="$(date +%s%N)-$$-$RANDOM"
 conv="${test_run_id}-tools-inline"
diff --git a/tests/llm-call/cli.sh b/tests/llm-call/cli.sh
index 011d9151..25b3a129 100755
--- a/tests/llm-call/cli.sh
+++ b/tests/llm-call/cli.sh
@@ -49,7 +49,7 @@ printf '%s\n' \
   'name=anthropic-api-key' \
   'value=test-key' \
   'entropy=0123456789abcdef0123456789abcdef' \
-  'reader=DEEP-DEPS/llm-call' \
+  "reader=--base:@=DEEP-DEPS/llm-call --base-url=http://$stub_host:$port" \
   > .caos-secrets/anthropic-api-key
 call=$(
   "$CAOS_CLI" curry --base:@=DEEP-DEPS/llm-call \
diff --git a/tests/max-tokens/cli.sh b/tests/max-tokens/cli.sh
index 6007c162..ca8c8946 100644
--- a/tests/max-tokens/cli.sh
+++ b/tests/max-tokens/cli.sh
@@ -66,6 +66,7 @@ for _ in 1 2 3 4 5; do
 done
 [ -n "$stub_pid" ] || fail "could not start llm-stub: $(cat stub/log)"
 trap 'kill "$stub_pid" 2>/dev/null || true' EXIT
+stub_host=${CAOS_STUB_HOST:-host.containers.internal}
 
 echo "== curry llm-step and run the turn ==" >&2
 mkdir -p .caos-secrets
@@ -74,14 +75,13 @@ printf '%s\n' \
   'name=anthropic-api-key' \
   'value=test-key' \
   'entropy=0123456789abcdef0123456789abcdef' \
-  'reader=DEEP-DEPS/llm-step' \
+  "reader=--base:@=DEEP-DEPS/llm-step --base-url=http://$stub_host:$port" \
   > .caos-secrets/anthropic-api-key
 test_run_id="$(date +%s%N)-$$-$RANDOM"
 conv="${test_run_id}-max-tokens"
 conversation_ref="refs/caos/v2/conversations/$conv/head"
 # Workers reach the stub as host.containers.internal from the outer engine's
 # container network; nested siblings share this job's netns (CAOS_STUB_HOST).
-stub_host=${CAOS_STUB_HOST:-host.containers.internal}
 # NO TOOL IMAGES: llm-step's `.caos-expr` binds its own (std/llm-step/DEPS), so
 # a caller says what the turn is, never which shell the agent greps with.
 llm=$("$CAOS_CLI" curry --base:@=DEEP-DEPS/llm-step \
diff --git a/tests/merge-harness/cli.sh b/tests/merge-harness/cli.sh
index fc4c9593..2cef9530 100755
--- a/tests/merge-harness/cli.sh
+++ b/tests/merge-harness/cli.sh
@@ -52,6 +52,7 @@ for _ in 1 2 3 4 5; do
 done
 [ -n "$stub_pid" ] || fail "could not start llm-stub: $(cat stub/log)"
 trap 'kill "$stub_pid" 2>/dev/null || true' EXIT
+stub_host=${CAOS_STUB_HOST:-host.containers.internal}
 
 echo "== dispatch merge turn ==" >&2
 mkdir -p .caos-secrets
@@ -60,12 +61,11 @@ printf '%s\n' \
   'name=anthropic-api-key' \
   'value=test-key' \
   'entropy=0123456789abcdef0123456789abcdef' \
-  'reader=DEEP-DEPS/llm-step' \
+  "reader=--base:@=DEEP-DEPS/llm-step --base-url=http://$stub_host:$port" \
   > .caos-secrets/anthropic-api-key
 test_run_id="$(date +%s%N)-$$-$RANDOM"
 conv="${test_run_id}-merge"
 conversation_ref="refs/caos/v2/conversations/$conv/head"
-stub_host=${CAOS_STUB_HOST:-host.containers.internal}
 llm=$("$CAOS_CLI" curry --base:@=DEEP-DEPS/llm-step \
   --system:@=system.txt \
   --merge-refs="feature $feature" \

From cc41fd096273c25c8f7c56c9ac340c419963e4f4 Mon Sep 17 00:00:00 2001
From: Nishad <nishu.builder@gmail.com>
Date: Wed, 19 Aug 2026 15:40:31 -0700
Subject: [PATCH 4/4] Share secret parsing and request execution

---
 crates/caos-cli/src/lib.rs |   7 +-
 crates/caos/src/lib.rs     | 194 +++++++++++++++++++++++++------------
 2 files changed, 133 insertions(+), 68 deletions(-)

diff --git a/crates/caos-cli/src/lib.rs b/crates/caos-cli/src/lib.rs
index fb61efda..9df3bcb5 100644
--- a/crates/caos-cli/src/lib.rs
+++ b/crates/caos-cli/src/lib.rs
@@ -17,8 +17,8 @@ use serde_json::{json, Value};
 
 use caos::{
     build_secret_store, compute_client_request_with_store, curry_client_object,
-    eval_workspace_dep_with_store, prepare_client_request_with_store, ClientSecret, GitTransport,
-    Transport, CAOS_REMOTE,
+    eval_workspace_dep_with_store, prepare_client_request_with_store,
+    run_client_request_with_store, ClientSecret, GitTransport, Transport, CAOS_REMOTE,
 };
 
 const CONVERSATION_PREFIX: &str = "refs/caos/v2/conversations/";
@@ -2056,8 +2056,7 @@ pub fn generate_conversation_title(
         "--model={}",
         options.model.as_deref().unwrap_or(DEFAULT_MODEL)
     ));
-    let arg_tree = prepare_client_request_with_store(t, &llm, &call, &store)?;
-    let (kind, hash) = compute_client_request_with_store(&t.server_url()?, &arg_tree, &store)?;
+    let (kind, hash) = run_client_request_with_store(t, &llm, &call, &store)?;
     if kind != "blob" {
         return Err(format!(
             "conversation title run returned a {kind}, expected a blob"
diff --git a/crates/caos/src/lib.rs b/crates/caos/src/lib.rs
index 1b4cdab7..cc209ff6 100644
--- a/crates/caos/src/lib.rs
+++ b/crates/caos/src/lib.rs
@@ -3125,6 +3125,20 @@ pub fn prepare_client_request_with_store(
     prepare_request(t, image, None, kvs, store)
 }
 
+/// Prepare and synchronously run one host-side request with an already-resolved
+/// local secret store. This is the non-streaming client equivalent of
+/// [`cli_run`], for callers that need the result identity rather than CLI output
+/// handling. Durable conversation turns deliberately use the split prepare and
+/// compute APIs instead so they can record the request before dispatching it.
+pub fn run_client_request_with_store(
+    t: &dyn Transport,
+    image: &str,
+    kvs: &[String],
+    store: &[ClientSecret],
+) -> Result<(String, String), String> {
+    run_request(t, image, None, None, kvs, store)
+}
+
 /// `prepare-request --base:<type>=<image-or-arg-tree> [--name=value | --name:@=path ...]`
 /// — construct the exact flat runnable ArgTree and print its hash without
 /// executing it. This is the worker-side half: CAS paths use `/cas` semantics.
@@ -4092,28 +4106,12 @@ pub fn cli_secrets(check: bool) -> Result<(), String> {
         println!("no {SECRETS_DIR} directory — nothing to do");
         return Ok(());
     }
-    let mut paths: Vec<PathBuf> = std::fs::read_dir(dir)
-        .map_err(|e| format!("reading {SECRETS_DIR}: {e}"))?
-        .filter_map(Result::ok)
-        .map(|e| e.path())
-        .collect();
-    paths.sort();
 
     let mut issues = 0;
-    for path in paths {
-        let name = path
-            .file_name()
-            .and_then(|n| n.to_str())
-            .unwrap_or_default()
-            .to_string();
-        if name.starts_with('.') || !path.is_file() {
-            continue;
-        }
+    for (name, path) in local_secret_files(dir)? {
         let text = std::fs::read_to_string(&path).map_err(|e| format!("reading {name}: {e}"))?;
-        let entropy = text
-            .lines()
-            .find_map(|l| l.trim().strip_prefix("entropy=").map(str::trim));
-        match entropy {
+        let spec = parse_local_secret_spec(&name, &text)?;
+        match spec.entropy.as_deref() {
             None => {
                 if check {
                     eprintln!("{name}: missing entropy");
@@ -4176,25 +4174,14 @@ pub fn build_secret_store(t: &dyn Transport) -> Result<Vec<ClientSecret>, String
         return Ok(Vec::new());
     }
     let pinned = secrets_pinned_tree(t, dir)?;
-    let mut paths: Vec<PathBuf> = std::fs::read_dir(dir)
-        .map_err(|e| format!("reading {SECRETS_DIR}: {e}"))?
-        .filter_map(Result::ok)
-        .map(|e| e.path())
-        .collect();
-    paths.sort();
     let mut store = Vec::new();
-    for path in paths {
-        let file_name = path
-            .file_name()
-            .and_then(|n| n.to_str())
-            .unwrap_or_default()
-            .to_string();
-        // Skip dotfiles (`.tree`, editor backups) and non-files.
-        if file_name.starts_with('.') || !path.is_file() {
-            continue;
-        }
-        let (name, value, entropy, readers) = parse_local_secret(&file_name, &path)?;
-        let readers = readers
+    for (file_name, path) in local_secret_files(dir)? {
+        let text = std::fs::read_to_string(&path)
+            .map_err(|e| format!("reading secret {file_name}: {e}"))?;
+        let spec = parse_local_secret_spec(&file_name, &text)?;
+        let value = resolve_local_secret_value(&file_name, &path, spec.value)?;
+        let readers = spec
+            .readers
             .iter()
             .map(|reader| {
                 resolve_reader_client(t, &pinned, reader)
@@ -4202,9 +4189,9 @@ pub fn build_secret_store(t: &dyn Transport) -> Result<Vec<ClientSecret>, String
             })
             .collect::<Result<_, _>>()?;
         store.push(ClientSecret {
-            name,
+            name: spec.name,
             value,
-            entropy,
+            entropy: spec.entropy.unwrap_or_default(),
             readers,
         });
     }
@@ -4353,19 +4340,47 @@ fn secrets_pinned_tree(t: &dyn Transport, dir: &Path) -> Result<String, String>
     Ok(oid.to_string())
 }
 
-/// Parse one `.caos-secrets` file (repeated-key form) into `(name, value,
-/// entropy, readers)`. `name` defaults to the filename; `value=`/`value:@=` set
-/// the value; `reader=` accumulates; `entropy=` keys cache isolation (empty if
-/// absent — the `caos secrets` tool fills it).
-fn parse_local_secret(
-    file_name: &str,
-    path: &Path,
-) -> Result<(String, String, String, Vec<String>), String> {
-    let text =
-        std::fs::read_to_string(path).map_err(|e| format!("reading secret {file_name}: {e}"))?;
+/// Sorted, visible secret files shared by the offline `secrets` command and the
+/// runtime loader. Dotfiles (`.tree`, editor backups) and non-files are metadata,
+/// not secrets.
+fn local_secret_files(dir: &Path) -> Result<Vec<(String, PathBuf)>, String> {
+    let mut files = Vec::new();
+    for entry in std::fs::read_dir(dir).map_err(|e| format!("reading {SECRETS_DIR}: {e}"))? {
+        let path = entry
+            .map_err(|e| format!("reading {SECRETS_DIR}: {e}"))?
+            .path();
+        let name = path
+            .file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or_default()
+            .to_string();
+        if !name.starts_with('.') && path.is_file() {
+            files.push((name, path));
+        }
+    }
+    files.sort_by(|a, b| a.0.cmp(&b.0));
+    Ok(files)
+}
+
+enum LocalSecretValue {
+    Inline(String),
+    File(String),
+}
+
+struct LocalSecretSpec {
+    name: String,
+    value: Option<LocalSecretValue>,
+    entropy: Option<String>,
+    readers: Vec<String>,
+}
+
+/// Parse the repeated-key secret-file format once for both `caos-cli secrets`
+/// and runtime loading. Value files remain unresolved here so the offline
+/// entropy command does not need to read secret material.
+fn parse_local_secret_spec(file_name: &str, text: &str) -> Result<LocalSecretSpec, String> {
     let mut name = file_name.to_string();
-    let mut value: Option<String> = None;
-    let mut entropy = String::new();
+    let mut value = None;
+    let mut entropy = None;
     let mut readers = Vec::new();
     for raw in text.lines() {
         let line = raw.trim();
@@ -4377,23 +4392,38 @@ fn parse_local_secret(
             .ok_or_else(|| format!("secret {file_name}: line {line:?} is not key=value"))?;
         match key {
             "name" => name = val.trim().to_string(),
-            "entropy" => entropy = val.trim().to_string(),
-            "value" => value = Some(val.to_string()),
-            "value:@" => {
-                let file = path.parent().unwrap_or_else(|| Path::new(".")).join(val);
-                let bytes = std::fs::read(&file)
-                    .map_err(|e| format!("secret {file_name} value:@={val}: {e}"))?;
-                value = Some(
-                    String::from_utf8(bytes)
-                        .map_err(|e| format!("secret {file_name} value not UTF-8: {e}"))?,
-                );
-            }
+            "entropy" => entropy = Some(val.trim().to_string()),
+            "value" => value = Some(LocalSecretValue::Inline(val.to_string())),
+            "value:@" => value = Some(LocalSecretValue::File(val.to_string())),
             "reader" => readers.push(val.trim().to_string()),
             other => return Err(format!("secret {file_name}: unknown key {other:?}")),
         }
     }
-    let value = value.ok_or_else(|| format!("secret {file_name}: no value= line"))?;
-    Ok((name, value, entropy, readers))
+    Ok(LocalSecretSpec {
+        name,
+        value,
+        entropy,
+        readers,
+    })
+}
+
+fn resolve_local_secret_value(
+    file_name: &str,
+    path: &Path,
+    value: Option<LocalSecretValue>,
+) -> Result<String, String> {
+    match value.ok_or_else(|| format!("secret {file_name}: no value= line"))? {
+        LocalSecretValue::Inline(value) => Ok(value),
+        LocalSecretValue::File(value_path) => {
+            let file = path
+                .parent()
+                .unwrap_or_else(|| Path::new("."))
+                .join(&value_path);
+            let bytes = std::fs::read(&file)
+                .map_err(|e| format!("secret {file_name} value:@={value_path}: {e}"))?;
+            String::from_utf8(bytes).map_err(|e| format!("secret {file_name} value not UTF-8: {e}"))
+        }
+    }
 }
 
 /// Assemble one `reader=` line into the partial name -> oid ArgTree used by the
@@ -4892,6 +4922,42 @@ mod git_transport_tests {
     }
 }
 
+#[cfg(test)]
+mod local_secret_tests {
+    use super::{parse_local_secret_spec, LocalSecretValue};
+
+    #[test]
+    fn one_parser_serves_entropy_maintenance_and_runtime_loading() {
+        let spec = parse_local_secret_spec(
+            "token",
+            "name=api-key\nvalue:@=../key\nentropy=abc123\nreader=--base:@=DEEP-DEPS/tool\n",
+        )
+        .unwrap();
+        assert_eq!(spec.name, "api-key");
+        assert_eq!(spec.entropy.as_deref(), Some("abc123"));
+        assert_eq!(spec.readers, ["--base:@=DEEP-DEPS/tool"]);
+        match spec.value {
+            Some(LocalSecretValue::File(path)) => assert_eq!(path, "../key"),
+            _ => panic!("value:@ was not preserved as an unresolved file value"),
+        }
+    }
+
+    #[test]
+    fn entropy_maintenance_can_parse_a_spec_before_its_value_is_complete() {
+        let spec = parse_local_secret_spec("token", "reader=--base:@=DEEP-DEPS/tool\n").unwrap();
+        assert!(spec.value.is_none());
+        assert!(spec.entropy.is_none());
+    }
+
+    #[test]
+    fn shared_parser_rejects_unknown_fields() {
+        let error = parse_local_secret_spec("token", "wat=nope\n")
+            .err()
+            .expect("unknown field was accepted");
+        assert!(error.contains("unknown key \"wat\""), "{error}");
+    }
+}
+
 #[cfg(test)]
 mod memo_tests {
     use super::{eval::Memo, store_key, ClientSecret};