foldrun 2.4.0 → 2.6.0

package/bin/foldrun.mjs

@@ -183,6 +183,7 @@ const HELP = `foldrun — agents are just folders
   foldrun billing card      Stripe's page for saving a card for auto top-up (owner only)
   foldrun billing credit <usd>  put credit on the balance by hand (--note "…") — only on an install without Stripe (self-hosted, dev); refused once billing is live
   foldrun gallery           the platform's built-in tools (web) and whether you keep your own copy — also pull (a copy for offline runs), upgrade <tool>
+  foldrun identity          what your cloud must trust for keyless identities: the issuer and each agent's subject (--to <workspace>, --json)
   foldrun jobs              the four jobs — governance, guardrail, observability, evaluation — and what each has set (--to <workspace>, --json)
   foldrun account           the account's defaults — also set <key> <value>, clear <key> (timezone, notify, budget, concurrency, deploy_block none|secrets|security, network_enforce on|off, owner, alerts <threshold> <value>, judge model|effort <value>; or <job>.<field>, e.g. governance.owner), pause [--reason] [--stop] / resume (the kill switch), telemetry [set <url> --header name=\${SECRET} | clear | test] (runs as OpenTelemetry traces), providers (--check) (singular; accounts lists logins)
   foldrun account export    everything the platform holds about the account as one JSON file (owner only; --file <path>, --force)
@@ -202,7 +203,7 @@ const HELP = `foldrun — agents are just folders
   foldrun backups requests  every restore asked of the platform team, and where each stands (--json)
   foldrun secrets set NAME  store a secret (prompted, never echoed) — also ls, rm, status; --kind file|ssh|api|service-account|m2m for the other shapes; --site <domain> (repeatable) binds it as it is stored
   foldrun secrets sites NAME [site…]  bind a secret to sites: the egress proxy fills it for those alone and it never enters a sandbox; no sites lists them, --clear unbinds
-  foldrun secrets clients   the OAuth clients saved on the platform — also add <name> (--provider or --authorize-url/--token-url, --client-id, --scopes), rm <name>
+  foldrun secrets clients   the OAuth clients saved on the platform — also add <name> (--authorize-url/--token-url, --client-id, --scopes, --authorize-param name=value), rm <name>
   foldrun connect NAME      OAuth sign-in from the terminal, stored as an auto-refreshing secret — --client <saved> runs it from a saved client through the platform
   foldrun deploy [dir]      push the whole account, or deploy <workspace> for one of them
   foldrun pull [workspace]  bring the platform's account down here (refuses to clobber; --force overrides)
@@ -277,7 +278,7 @@ Options
   --on-fail <agent>         flow add: who takes the step over when it fails
   --off                     flow add: take the pattern off the step instead (fan-out, loop, approval, ask, wait, rescue)
   --schedule "<cron>"       flow trigger: the cron line a schedule fires on (5 fields, or @daily); --timezone <zone> the zone it is read in
-  --kind <k>                secrets set: file (--file <path>), ssh (--host, --user, --port, --key-file or a prompted password), api (--base-url, --header "Name: value" repeatable), service-account (--file <key.json>, --scopes), m2m (--token-url, --client-id, --scopes; secret prompted)
+  --kind <k>                secrets set: file (--file <path>), ssh (--host, --user, --port, --key-file or a prompted password), api (--base-url, --header "Name: value" repeatable, or --basic-user <u> with the password prompted or --basic-password), service-account (--file <key.json>, --scopes, --subject <user to act as>), client-cert (--cert-file, --key-file, --passphrase, --export to put it in the sandbox as files too), identity (--audience: keyless cloud access, no credential stored), m2m (--token-url, --client-id, --scopes; secret prompted)
   --client <name>           connect: run the consent from that OAuth client saved on the platform (secrets clients lists them)
   --subagent <name>         agent link, agent unlink: a worker it delegates to (subagents:)
   --consult <name>          agent link, agent unlink: a colleague it asks (agents:)
@@ -333,11 +334,14 @@ Options
   --print                   open: print the URL only
   --from <n>                invoke, flow run, rerun: start at step n; earlier steps are recorded as skipped (a bulk rerun defaults to 1)
   --no-browser              login, connect, billing top-up/card/plan: print the address instead of opening it
-  --provider <name>         connect: google, github, microsoft or linkedin (fills the URLs)
-  --scopes "<a b c>"        connect: space-separated scopes (default: the provider's example)
+  --provider <name>         (deprecated — use --authorize-url, --token-url and --authorize-param) connect: google, github, microsoft or linkedin
+  --no-pkce                 connect, secrets clients add: leave PKCE off (only for an app with a secret whose provider refuses it)
+  --issuer <url>            secrets clients add: the provider's issuer, checked against the iss it sends back (RFC 9207)
+  --scopes "<a b c>"        connect: space-separated scopes (default: the provider's example; with --client, the saved client's default — the connection keeps the ones asked for)
   --client-id / --client-secret  connect: the OAuth app (prompted if omitted; secret never echoed)
   --port <n>                connect: loopback port for the redirect (default 8642 — register http://localhost:8642/callback on the app)
-  --authorize-url / --token-url  connect: a provider with no preset
+  --authorize-url / --token-url  connect, secrets clients add: the provider's own OAuth addresses
+  --authorize-param name=value   connect, secrets clients add: an extra authorize-URL parameter the provider documents (repeatable — e.g. access_type=offline)
   --role <r>                keys create: viewer, editor (default) or admin
   --expires <span>          keys create: when it stops working — 30d, 90d, 365d or never (default never)
   --grace <span>            keys rotate: keep the old key working for 1h or 24h while you swap the new one in (default 0: revoked now)
@@ -381,9 +385,9 @@ if (!command || command === "--help" || command === "-h") {
 // `--value` as the account's argument and stored an empty secret; `--force
 // ./dir` swallowed the directory. A flag followed by another flag is also
 // boolean, so an unlisted switch at least does not eat its neighbour.
-const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last"]);
+const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test", "flat", "yes", "platform", "json", "forever", "all", "check", "new-client", "quiet", "off", "can-ask", "preview", "csv", "failed", "starter", "history", "list", "library", "clear", "security", "changed", "write-baseline", "no-baseline", "rules", "calls", "tree", "tool-error", "stop", "last", "no-pkce", "export", "isolated"]);
 // Flags said more than once collect into a list: `--tag a --tag b`.
-const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule"]);
+const REPEATABLE = new Set(["tag", "expect", "header", "site", "add", "remove", "rule", "authorize-param"]);
 // `--wait` is a switch everywhere but `flow add <flow> wait`, where it takes
 // a span: `--wait 30m`, `--wait event`. Only a value that reads as one is
 // taken, so `invoke x --wait` and friends are as they were.

package/docs/agents.md

@@ -91,6 +91,7 @@ the point of the week; a step that weighs two arguments and picks one is not.
 | `skills` | an allowlist. **Absent inherits every skill in scope**; `[]` withholds all of them |
 | `agents` | colleagues it may consult mid-run — an answer, no tools |
 | `subagents` | colleagues it may delegate a whole job to — own context, own tools, never more than its own ([below](#delegating-to-a-sub-agent)) |
+| `sandbox` | `own` \| `parent` (default) — delegated to as a sub-agent, run each job in a sandbox of its own, with its own tools, secrets and network ([below](#isolated-sub-agents-sandbox-own)) |
 | `scripts` | programs in `scripts/`, each becoming a callable tool |
 | `hooks` | your own code at every tool call, step start and step end — refuse, rewrite, add context — the same on every model ([Hooks](hooks)). Also in a workspace's or the account's `AGENTS.md` for every agent under it |
 | `apis` | an HTTP API declared inline, as one tool |
@@ -267,6 +268,73 @@ platform alike. `foldrun check` errors on a name that is not an agent and on a
 sub-agent with no description, and warns when a sub-agent would hold none of
 its tools inside the delegating agent's.
 
+### Isolated sub-agents: `sandbox: own`
+
+A sub-agent shares its parent's sandbox: whatever it reads, it reads where the
+parent's secrets are. For a sub-agent that reads untrusted content — web
+pages, mail, uploads — put it in a sandbox of its own instead. The sub-agent
+says so in its own file:
+
+```yaml
+---
+name: reader
+description: Reads the pages it is given and summarises them.
+tools: [web]
+sandbox: own
+---
+```
+
+The parent is unchanged (`subagents: [reader]`). Its model gets a
+`delegate_reader(job)` tool in place of the SDK's `Agent` tool for this one.
+
+| | `subagents:` | `subagents:` + `sandbox: own` |
+|---|---|---|
+| where it runs | inside the parent's sandbox | a sandbox of its own, started for the job |
+| tools | its own, cut to the parent's | its own — the parent may hold less |
+| secrets, network, size, runtime | the parent's | its own file's |
+| gives back | its reply | its reply, and the paths of files it changed |
+| on the run | lines in the parent's trace | a step of its own after the parent's, marked `subagentOf` |
+| cost | on the parent's step | on its own step, in the run's total |
+
+What holds:
+
+- **Its file decides what it holds.** Its `tools:`, `secrets:`, `network:`,
+  `limits:`, `hooks:`, `runtime:`, `size:` and `model:` are read exactly as
+  for a step of its own. So a reader with `tools: [web]` and no secrets can
+  serve a writer with secrets and no web: a page that tells the reader to
+  send something finds nothing to send, and the writer never read the page.
+  `foldrun check` names what it holds that the parent does not
+  ([`security/subagent-own-sandbox`](checks#securitysubagent-own-sandbox)).
+- **Only the reply comes back.** The reply is still text the parent reads —
+  it can carry an instruction — but it reaches a model whose sandbox never
+  held the page.
+- **Files.** What it writes reaches the workspace when its job ends, so the
+  next step sees it. The parent's own sandbox does not: it was copied in when
+  the parent started. The reply lists the paths. If both write one path, the
+  parent, finishing later, wins — as between two steps of a parallel group.
+- **One level deep.** Its own `subagents:` are not offered to it.
+- **Bounded by its parent.** A job runs within the parent step's `timeout:`
+  and under two budgets. The sub-agent's own `budget:`: a job holds what is
+  left of it while it runs, so a second job for the same agent at the same
+  moment, or one after the budget is spent, is not started and comes back as
+  failed. The flow's `budget:`: a job gets only what is neither spent nor held
+  by the steps and jobs running now — and a running step holds its whole
+  share, so in a flow with a `budget:` a job usually finds nothing left and is
+  not started. Give the sub-agent its own `budget:` and leave the flow's off,
+  or expect the job to be refused. The parent's step ends only when its jobs have. A stopped run
+  stops them.
+- **Needs a run.** On the platform each job starts a sandbox of its own.
+  With `foldrun run` on your machine no step has a sandbox, so a job runs in
+  the same process: its own context, tools and secrets, but the same files
+  and network as the step that asked — the step's trace says so. Where
+  nothing can start a job from inside a step (an install without the egress
+  proxy), or nothing can stop one job's sandbox on its own (the local docker
+  executor), the tool is not offered and the step says so: a job whose parent
+  stopped waiting must not run on.
+
+`foldrun agent link <parent> --subagent <reader> --isolated` writes
+`sandbox: own` on the reader along with the link.
+
 ## Where it runs
 
 | field | |

package/docs/api.md

@@ -173,7 +173,7 @@ history with each message.
 | Route | Methods | |
 |---|---|---|
 | `/api/workspaces/<ws>/agents` | GET, POST | list — each agent's frontmatter as read, `owner` and `ownerFrom` (its own `owner:`, else the workspace's, else the account's), `lastRunAt` (when its latest step that ran started, from the runs kept; null for none) and `stale` (past `alerts: stale_days`); create (`name`) |
-| `/api/workspaces/<ws>/agents/<agent>` | PATCH | edit one line of an agent's frontmatter in place, as the flow canvas does: `{ list: { key, name, action } }` — `key` one of `subagents`, `agents`, `tools`; `action` `add` or `remove` — or `{ set: { key: "description", value } }`, or `{ network }` — the sites its sandbox may reach: `"open"`, `"trusted"`, `"none"`, a list of sites, or `{ level, allow, defaults }`; `null` removes the line so it inherits ([Network](network)). A `network` nobody could read is a 400 that says why. Only that key's lines change — comments, key order and prose stay. Answers `{ ok, changed }`; 404 for an unknown agent. `workspace:write` |
+| `/api/workspaces/<ws>/agents/<agent>` | PATCH | edit one line of an agent's frontmatter in place, as the flow canvas does: `{ list: { key, name, action } }` — `key` one of `subagents`, `agents`, `tools`; `action` `add` or `remove` — or `{ set: { key: "description" | "sandbox", value } }` (`sandbox` takes `own` or `parent`, else 400), or `{ network }` — the sites its sandbox may reach: `"open"`, `"trusted"`, `"none"`, a list of sites, or `{ level, allow, defaults }`; `null` removes the line so it inherits ([Network](network)). A `network` nobody could read is a 400 that says why. Only that key's lines change — comments, key order and prose stay. Answers `{ ok, changed }`; 404 for an unknown agent. `workspace:write` |
 | `/api/workspaces/<ws>/agents/<agent>/run` | POST | run one agent alone (`task`; `test: true` for a test run) |
 | `/api/workspaces/<ws>/agents/import` | GET, POST | copy an agent in from another workspace of the account. GET lists what could be imported (every other workspace you can read, with its agents). POST `{ from, agent, as? }` copies `agents/<agent>/` — its agent.md and own skills/, scripts/, knowledge/; never memory/, outputs/, state/ — and answers `{ name, files, warnings }`; `warnings` names tools, skills, scripts and secrets the copy uses that this workspace lacks. 409 on a name clash (pass `as`), 404 for an unknown workspace or agent, 403 when `from` is outside your key's scope. Idempotent |
 | `/api/workspaces/<ws>/export` | GET | this workspace, one flow or one agent as a `.zip` — `?kind=flow&name=<flow>` (the flow, every flow it runs as a step, every agent those steps and their colleagues name, and the workspace tools, skills and scripts they grant), `?kind=agent&name=<agent>` (its folder and what it grants), or neither for the whole authored tree. Never memory/, state/, outputs/, storage, runs or a secret's value; `foldrun-package.json` inside says what it is. Any role that can read the workspace |
@@ -192,7 +192,7 @@ paying for the steps around it.
 | Route | Methods | |
 |---|---|---|
 | `/api/workspaces/<ws>/runs?limit=` | GET | `{ runs: [{ id, flow, status, verdict, outcome, startedAt, finishedAt, ... }] }`; search (see [Runs](runs#searching-runs)) with `tool` (a step called a tool whose name contains it), `tool_error=1`, `agent`, `model` (contains), `min_tokens` (`50k`), `min_secs` — `limit` counts the matches — `verdict` is the word the summary leads with (`GOOD`, `QUIET`, `BLOCKED`, `BAD` or null) and `outcome` the one word every page shows (`running`, `queued`, `waiting`, `good`, `done`, `quiet`, `blocked`, `bad`, `failed`, `stopped`); `failure` is `{ agent, reason }` for a run that failed (null otherwise), `chargedUsd` is what the account was charged for the run (one credit is one cent), null until the ledger settles it, while `costUsd` is the provider's token cost — off the run index (see [Runs](runs#the-runs-list)); a finished run's steps carry `agent`, `status`, `costUsd` and `tokens` (`{ input, output, cacheRead, cacheWrite }`, see [Runs](runs#the-record)), and the run its summed `tokens` — not their reply or trace |
-| `/api/workspaces/<ws>/runs/<id>/calls/<call>` | GET | one tool call's recorded content (see [Runs](runs#what-a-run-records)): `{ call: { id, tool, input, output, inputChars, outputChars, truncated, inputCut, outputCut } }` — what it was given and what it gave back, secrets masked, each at most 65,536 characters; `inputChars`/`outputChars` are the whole length, `inputCut`/`outputCut` say which part was cut (`truncated`: either). `<call>` is the tool event's `call`; an event with `captured: true` has content here. 404 when nothing was recorded: the workspace says `capture: metadata`, or the run is from before 19 Oct 2026. A run's steps also carry `calls`, each model call (`n`, `at`, `ms`, `model`, `stop`, `tokens`, `tools`, and `subagent` / `attempt` when a sub-agent or a later attempt made it), and the run its `revision` (the workspace's latest revision when a worker picked it up — a deploy's commit, or the id an edit through `/source` was saved as) and `drivenAt` (when that was) |
+| `/api/workspaces/<ws>/runs/<id>/calls/<call>` | GET | one tool call's recorded content (see [Runs](runs#what-a-run-records)): `{ call: { id, tool, input, output, inputChars, outputChars, truncated, inputCut, outputCut } }` — what it was given and what it gave back, secrets masked, each at most 65,536 characters; `inputChars`/`outputChars` are the whole length, `inputCut`/`outputCut` say which part was cut (`truncated`: either). `<call>` is the tool event's `call`; an event with `captured: true` has content here. 404 when nothing was recorded: the workspace says `capture: metadata`, or the run is from before 19 Oct 2026. A run's steps also carry `calls`, each model call (`n`, `at`, `ms`, `model`, `stop`, `tokens`, `tools`, and `subagent` / `attempt` when a sub-agent or a later attempt made it); a step that handed jobs to `sandbox: own` sub-agents carries `delegations` (`id`, `agent`, `status`, `costUsd`, `ms`), and each job is a step of its own with `subagentOf` (the delegating agent), `delegation` (that `id`) and `wrote` (the workspace paths it changed); and the run its `revision` (the workspace's latest revision when a worker picked it up — a deploy's commit, or the id an edit through `/source` was saved as) and `drivenAt` (when that was) |
 | `/api/workspaces/<ws>/runs/<id>/trace` | GET | the run as one tree (see [Runs](runs#the-trace-tree)): `{ tree, failure }`. Each span is `{ id, kind, label, start, end, status, children, … }`, where `kind` is `run`, `step`, `model` (one model call: `model`, `stop`, `tokens`), `tool` (`call`, `captured` when its input and output were recorded) or `error` (`text`); `start`/`end` are epoch milliseconds and `status` is `ok`, `error`, `running`, `waiting`, `skipped` or `pending`. A tool call sits under the model call that asked for it. `failure` is the ids from the root to the first thing that went wrong, which the run page opens on; `[]` when nothing did |
 | `/api/workspaces/<ws>/runs/<id>/compare?with=` | GET | this run beside another of the same flow (see [Runs](runs#compare-with-the-last-good-run)): `{ comparison: { base, run, revisionChanged, changedFiles, steps }, chosen }`. Each step is `{ step, agent, base, run, changes }`: both sides' status, instruction, model, seconds, tokens, model calls, tool counts, tool errors, first errors and first line said, and `changes` in words (`status: completed → failed`, `new error: …`, `instruction changed`, `tools: +web ×3`, `took 12s → 48s`, …). `changedFiles` lists the files changed between the revisions the two ran (null when one is unknown). `with` names the other run; unasked it is the newest earlier run of the flow that finished well, else the run this one re-ran (`chosen` says which) |
 | `/api/workspaces/<ws>/runs/<id>` | GET, DELETE | the whole run: every step, its output, cost, timing, the runner `image` it ran on and — for a step that browsed through the account's pod from slim — its `browserPod` reconnects and fallback ([runs](runs#the-record)). `?wait=true&timeout=<s>` instead blocks until the run stops (or `timeout`, default 300, max 900) and answers the verdict the run routes give — `200` completed, `500` failed with the record, `202` still going (`timedOut`) or parked on a person (`awaitingApproval`). Ask in short pieces: whatever sits in front of the platform cuts a request that stays silent too long (Cloudflare at 100 s, an AWS ALB at 60 s), and a flow can run for many minutes — the CLI's `--wait` asks 25 s at a time and comes back here on every `202` |
@@ -319,7 +319,7 @@ its header and requires a URL it can GET for itself.
 | `/api/secrets?workspace=` | GET, PUT, PATCH, DELETE | the vault: list which secrets exist (never a value), each with the `sites` it is bound to; set one (`name` plus one shape, below, and optionally `sites`); bind one to sites with PATCH `{ name, sites }` — `sites` a list like `["api.example.com", "*.example.com"]`, `[]` unbinds, the value untouched, 404 for a secret that is not there, 400 for a site with a scheme, path or port and for a file, ssh or api secret ([bound to sites](secrets#bound-to-sites)); delete one (`name`). `workspace` names a workspace's own store; unsaid is the account's, which a key scoped to some workspaces may not touch. PUT is idempotent; PATCH and a PUT with `sites` are audited as `secret.sites` / `secret.set` |
 
 `PUT` takes `name` plus exactly one shape: `value` (a string), `file` (a PEM,
-a cert), `oauth2`, `service_account`, `ssh`, or `api`. They go to the vault;
+a cert), `oauth2`, `service_account`, `ssh`, `api`, `client_cert` (`{ cert, key, passphrase?, export? }` — mutual TLS, presented by the egress proxy to the exact sites the secret is bound to), or `identity` (`{ audience }` — keyless cloud access). They go to the vault;
 agents name them in `secrets:` and never see them in a file.
 
 Reads return which secrets exist, never their values.
@@ -462,10 +462,12 @@ signed-in person, never by a key — mints an ordinary API key at their role.
 
 | Route | Methods | |
 |---|---|---|
-| `/api/oauth/clients` | GET, POST, DELETE | registered providers (`name`, `client`, `config`) |
-| `/api/oauth/start` | POST | begin a connection (`client`, `secret`, `workspace`) |
-| `/api/oauth/callback` | GET | where the provider returns |
-| `/api/oauth/reconnect` | POST | reconnect a secret with the client it was connected with — no client id (`secret`, `workspace`, `provider`) → `{ url }` |
+| `/api/oauth/clients` | GET, POST, DELETE | saved OAuth apps (`name`, `client`, `config`). `config`: `authorize_url`, `token_url`, `client_id`, `client_secret` (empty for a public app), `scopes`, optional `authorize_extra` (`{ name: value }` added to the authorize URL — the flow's own parameters are refused), `pkce` (false to turn it off), `issuer` |
+| `/api/oauth/start` | POST | begin a connection (`client`, `secret`, `workspace`, optional `scopes`). From a signed-in browser: `{ url }` is the provider's consent, bound to that browser by a cookie the callback checks, with PKCE. With an API key: `{ url, handoff: true }` is a dashboard page where a signed-in person accepts first (`foldrun connect --client` opens it). `scopes` (space-separated, as the provider spells them) is what this connection asks for instead of the client's default, and the connection keeps it for its reconnects — one saved app serves any number of connections at different scopes |
+| `/api/oauth/callback` | GET | where the provider returns — refuses a consent that comes back to another browser, and an `iss` that is not the app's issuer |
+| `/api/identity?workspace=` | GET | keyless cloud identity: `{ enabled, issuer, subject, tokenSeconds }` — the issuer a cloud must trust and the subject pattern each agent's tokens carry (`account:<a>:workspace:<w>:agent:<agent>`). Open (no key), outside `/api`: `/.well-known/openid-configuration` and `/.well-known/jwks.json`, 404 when the install does not issue tokens |
+| `/api/oauth/handoff/<id>` | POST | accept a connection started from a terminal: a signed-in person only, never a key; answers `{ url }`, the provider's consent bound to this browser. Used once, ten minutes |
+| `/api/oauth/reconnect` | POST | reconnect a secret with the client it was connected with — no client id (`secret`, `workspace`, `provider`, optional `scopes`) → `{ url }`; it asks for `scopes` when given, else the scopes the secret was connected with, else the client's default |
 | `/api/oauth/connections` | GET | each oauth2 secret's grant: saved client, `status` (ok, expiring, expired, failed, no-client), days left, last error |
 
 ## Triggers

package/docs/checks.md

@@ -261,6 +261,16 @@ is the other answer, though this rule looks at the agent, not the flow.
 *info · ASI03.* A sub-agent declares tools its parent does not have. A
 sub-agent never gets more than its parent, so they are dropped inside the
 delegation. Grant them to the parent, or remove them from the sub-agent.
+A sub-agent with `sandbox: own` is not this rule's: its tools are its own
+([below](#securitysubagent-own-sandbox)).
+
+### security/subagent-own-sandbox
+
+*info · ASI03.* A sub-agent with `sandbox: own` holds tools its parent does
+not. That is what `sandbox: own` is for: each job it is handed runs in a
+sandbox of its own, with its own tools, secrets and network, and only its
+reply reaches the parent. The finding says what it holds, so the choice
+stays visible ([agents](agents#isolated-sub-agents-sandbox-own)).
 
 ### flow/outward-ungated
 

package/docs/cli.md

@@ -44,7 +44,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `foldrun extract [dir]` | move each single-file script tool — a `tools/<name>.md` with its program in a fenced block — into a folder: `tools/<name>/tool.md` with `run:` pointing at `run.js`, `run.py` or `run.sh` beside it. Frontmatter is edited as text, never re-serialised, so the diff is only what moved. A tool that already has a folder is left for you; `--dry-run` lists what it would do |
 | `foldrun check --to <ws>` | validate the copy that is DEPLOYED, rather than the folder in front of you — a workspace edited through the API, by an agent or by `foldrun source put`, has had no way to be checked short of spending a run. The files are fetched into a temporary folder and the ordinary check runs over them, so there is one copy of the rules; the output names the workspace and the platform it checked. `--online` adds the network checks the platform runs: known vulnerabilities for exact runtime pins and remote MCP servers' tool text, and what could not be checked |
 | `foldrun agent run <name>` | run one agent once on a platform, with no flow file: a flow of one step. `--task "…"` is the instruction and is required. Prints the run id and how to follow it; `--wait` holds on (in 25-second pieces, as `invoke` does) and then prints the same report `foldrun report` would; `--test` makes it a [test run](runs#test-runs) |
-| `foldrun agent link <agent>` | add to an agent's team, in its own frontmatter — `--subagent <worker>` (`subagents:`, a worker it delegates to), `--consult <agent>` (`agents:`, a colleague it asks) or `--can-ask` (`ask` in `tools:`, so it may ask you mid-step). The edit is core's, the one the canvas's docks make: only the lines of that one list change, flow style stays flow style, comments and the prose stay byte for byte. A sub-agent without a `description:` needs one, because the model picks a sub-agent by it — asked for at a terminal, `--description "…"` otherwise, and written into the worker's file first. Says which flows use the agent ("used by 3 flows"), since the change reaches all of them. Prints the diff, and refuses an edit `foldrun check` would call an error; `--dry-run` writes nothing. In this folder by default (`--workspace <name>` in an account with several); `--to <workspace>` edits the deployed copy through `PATCH /api/workspaces/<ws>/agents/<name>`. In this folder it re-reads each file just before writing — after the description prompt, after `check` — and refuses, writing nothing to either file, when one changed since it was read |
+| `foldrun agent link <agent>` | add to an agent's team, in its own frontmatter — `--subagent <worker>` (`subagents:`, a worker it delegates to), `--consult <agent>` (`agents:`, a colleague it asks) or `--can-ask` (`ask` in `tools:`, so it may ask you mid-step). The edit is core's, the one the canvas's docks make: only the lines of that one list change, flow style stays flow style, comments and the prose stay byte for byte. A sub-agent without a `description:` needs one, because the model picks a sub-agent by it — asked for at a terminal, `--description "…"` otherwise, and written into the worker's file first. `--isolated` also writes `sandbox: own` on the worker: each job it is handed runs in its own sandbox, with its own tools, secrets and network, not cut to the delegating agent's, and only its reply comes back (`foldrun docs agents`). Says which flows use the agent ("used by 3 flows"), since the change reaches all of them. Prints the diff, and refuses an edit `foldrun check` would call an error; `--dry-run` writes nothing. In this folder by default (`--workspace <name>` in an account with several); `--to <workspace>` edits the deployed copy through `PATCH /api/workspaces/<ws>/agents/<name>`. In this folder it re-reads each file just before writing — after the description prompt, after `check` — and refuses, writing nothing to either file, when one changed since it was read |
 | `foldrun agent import <workspace>/<agent>` | copy an agent you already have in another workspace into this one: its `agent.md` and own `skills/`, `scripts/`, `knowledge/` — never `memory/`, `outputs/` or `state/`. Into the workspace you stand in, or `--workspace <name>`; `--as <name>` imports it under another name (and rewrites `name:`), which a name clash requires. `--to <workspace>` does it on the platform (`POST /api/workspaces/<ws>/agents/import`) and lists the tools, skills, scripts and secrets the copy uses that the workspace lacks. See [Importing an agent](workspaces#importing-an-agent-you-already-have) |
 | `foldrun agent import --list` | what could be imported into a deployed workspace: every other workspace this key may read, and each one's agents with their descriptions (`GET …/agents/import`). Imports nothing. `--to <workspace>`, `--json` |
 | `foldrun agent unlink <agent>` | take one away: `--subagent <name>`, `--consult <name>` or `--can-ask`. An emptied list is written `key: []`, not deleted. In this folder, refused the same way, nothing written, when the file changed since it was read |
@@ -96,10 +96,10 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `foldrun message <run-id> "…"` | say something to a running agent. It reaches the model after its next tool call, as context — it changes none of the step's tools. `--step <n>` picks one when a parallel group has several running. Platform only |
 | `foldrun secrets set NAME` | store a secret — also `ls`, `rm`, and `status` (OAuth grant health). `--site <domain>` (repeatable, or `a,b`) binds it as it is stored |
 | `foldrun secrets sites NAME [site…]` | bind a secret to the sites it is for: the egress proxy fills it in requests to those sites alone, and it never enters a sandbox ([bound to sites](secrets#bound-to-sites)). No sites prints what it is bound to; `--clear` unbinds. On the platform, or this machine's vault with `--local` |
-| `foldrun secrets set NAME --kind <k>` | the other shapes the Connections form stores: `file` (`--file <path>`), `ssh` (`--host`, `--user`, `--port`, `--key-file <path>` or a prompted password), `api` (`--base-url`, `--header "Name: value"` repeatable), `service-account` (`--file <key.json>`, `--scopes`), `m2m` (a client-credentials app: `--token-url`, `--client-id`, `--scopes`, the secret prompted). On the platform, or this machine's vault with `--local` |
-| `foldrun secrets clients` | the OAuth clients saved on the platform — what a consent runs from without typing the client again; the client secret is never shown. `clients add <name> --provider google\|github\|microsoft\|linkedin` (or `--authorize-url` / `--token-url`) `--client-id … --scopes …` saves one (secret prompted), `clients rm <name>` removes it |
-| `foldrun connect NAME` | OAuth sign-in from the terminal, stored as an auto-refreshing secret — `--provider google\|github\|microsoft\|linkedin`; reconnecting a secret whose client is saved asks for nothing (`--new-client` to enter one) |
-| `foldrun connect NAME --client <saved>` | the Connections page's **Connect**: a consent from a client saved on the platform, returning to the platform's own callback, which stores the grant as NAME (`--to <workspace>` for a workspace's). Opens the browser (`--no-browser` prints the address) and waits for it to land |
+| `foldrun secrets set NAME --kind <k>` | the other shapes the Connections form stores: `file` (`--file <path>`), `ssh` (`--host`, `--user`, `--port`, `--key-file <path>` or a prompted password), `api` (`--base-url`, `--header "Name: value"` repeatable, or `--basic-user <u>` with the password prompted or `--basic-password`), `service-account` (`--file <key.json>`, `--scopes`, `--subject <user>` to act as a user where the provider allows it), `client-cert` (`--cert-file`, `--key-file`, `--passphrase`, `--export` to put it in the sandbox as files too; bind it with `secrets sites`), `identity` (`--audience`: keyless cloud access — nothing secret is stored), `m2m` (a client-credentials app: `--token-url`, `--client-id`, `--scopes`, the secret prompted). On the platform, or this machine's vault with `--local` |
+| `foldrun secrets clients` | the OAuth clients saved on the platform — what a consent runs from without typing the client again; the client secret is never shown. `clients add <name> --authorize-url … --token-url … --client-id … --scopes …` saves one (secret prompted), with `--authorize-param name=value` for anything else the provider's authorize URL takes, `clients rm <name>` removes it |
+| `foldrun connect NAME` | OAuth sign-in from the terminal, stored as an auto-refreshing secret — `--authorize-url` and `--token-url` from the provider's OAuth docs, `--authorize-param name=value` for its extras; PKCE is on (`--no-pkce` only for an app with a secret whose provider refuses it), and an app with no client secret is a public app; reconnecting a secret whose client is saved asks for nothing (`--new-client` to enter one) |
+| `foldrun connect NAME --client <saved>` | the Connections page's **Connect**: a consent from a client saved on the platform (`--scopes "<a b>"` asks for this connection's own scopes instead of the client's default; the connection keeps them). It opens a page in the dashboard where you, signed in, accept the connection before the provider is asked, returning to the platform's own callback, which stores the grant as NAME (`--to <workspace>` for a workspace's). Opens the browser (`--no-browser` prints the address) and waits for it to land |
 | `foldrun deploy [dir]` | push this account into an installation — every workspace and the shared library. `foldrun deploy <workspace>` pushes one. Never removes a workspace the platform has and the folder does not. It first prints where it is going and as whom (`deploying to <url> as <profile> (<email>)`); a deploy that would delete files the folder no longer has lists them and asks — what runs wrote (`storage/`, `state/`, the trigger log) is never deleted, so never listed. The confirmed list goes with the deploy; if the platform would now remove anything else it refuses and the CLI asks again. With no terminal (a script, a CI job, a coding agent) it refuses unless `--yes`. A deploy that only adds or changes files asks nothing |
 | `foldrun help <command>` | that command's usage and options. `foldrun <command> --help` and `-h` print the same and never run the command |
 | `foldrun pull [workspace]` | bring the platform's account down into this folder — refuses to overwrite a locally edited file, and names every one it would have taken (`--force` takes them) |
@@ -142,6 +142,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `foldrun billing top-up <usd>` | the Payment page's top-up: Stripe's checkout page for that amount, opened in the browser (`--no-browser`, or no terminal, prints it). The credit lands when Stripe confirms the payment. `billing card` is the same for saving a card for auto top-up. Both need `billing:manage` |
 | `foldrun billing credit <usd>` | put credit on the balance by hand (`POST /api/billing { usd, note }`, `--note "…"` on the ledger line) — only on an install without Stripe, a self-hosted or dev platform; once billing is live the platform refuses it and top-ups go through `billing top-up`. The dashboard's Billing → Add credit does the same while billing is off. Needs `billing:manage` |
 | `foldrun gallery` | the tools the platform ships to every account (`web`), and for each whether this account keeps its own copy and whether that copy still matches. `pull` lays the shelf down under `~/.foldrun/gallery/<host>/` for offline runs (`foldrun run` and `foldrun eval` refresh it themselves before each run); `upgrade <tool>` replaces the account's copy with the current gallery version, the old one a revision back |
+| `foldrun identity` | keyless cloud identity: the issuer your cloud must trust and the subject each agent's tokens carry (`GET /api/identity`); `--to <workspace>` fills the workspace in, `--json` |
 | `foldrun jobs` | the four jobs — governance, guardrail, observability, evaluation — and every `AGENTS.md` field of each, with what is set (`GET /api/account/jobs`). `--to <workspace>` shows the workspace's value beside the account's and how the two combine; `--json` the document. `account set <job>.<field>` and `workspace set <job>.<field>` refuse a field that scope cannot set and name the `AGENTS.md` to write it in. See [The four jobs](four-jobs) |
 | `foldrun account` | the account's own defaults — the AGENTS.md frontmatter every workspace under it inherits: `timezone`, `notify`, `budget`, `concurrency`, `deploy_block`, `network_enforce`. `foldrun account set timezone Australia/Sydney`, `set notify email you@example.com` (`--events failed,awaiting-approval,completed`), `set notify url https://…`, `set budget 60/month`, `set concurrency 4`, `set deploy_block secrets` (`none`, `secrets` or `security` — what the scanner's findings do to a deploy), `set network_enforce on` (every workspace refuses a site off an agent's `network:` list; `off` reports only), `set owner <email or name>`, `set alerts <threshold> <value>` (merged into what is set; `off` removes one), `set judge model|effort <value>`. Any setting may be named by its job — `set governance.deploy_block secrets`, `set observability.alerts stale_days 30` — and one named under the wrong job is refused with the right one, `pause` (`--reason "…"`, `--stop` to also stop every run going now — asks, or `--yes`) and `resume`: the kill switch, no new run starts in any workspace while paused, `telemetry` — where each finished run goes as an OpenTelemetry trace: bare shows it, `set <url> --header authorization='${OTEL_TOKEN}'` (repeatable; a value is a vault secret's name), `clear`, `test` (one made-up run, and what the collector answered; exit 1 when not delivered), and `clear <key>` to unset one. `set notify` merges against what is there, because the platform replaces the whole block. `providers` lists the model providers the account's files use and the last daily key check — `--check` asks now, and a dead key is a non-zero exit. `model` is the account's own model key, what every step runs on unless a `provider:` block names another: `foldrun account model` shows it (never the key, only its last four; exit 1 when there is none and runs are refused), `model set <provider> --key <api key>` sets it — a preset name (anthropic, openrouter, openai, groq, …) or `custom --base-url https://… --format anthropic|openai`, `--key -` reads the key from stdin — and `model remove` removes it; a Claude login token is refused for any account not allowed the platform's own credential. `export` downloads everything the platform holds about the account — workspaces, runs, members and the whole ledger — as one JSON file (owner only; `--file <path>`, `--force`). Singular — `accounts` below is the list of logins on this machine |
 | `foldrun workspace` | one deployed workspace's own settings (`--to <workspace>`): description, timezone, budget and notify, read from its `AGENTS.md` — unset means the account's. `set timezone <tz>`, `set budget 20/week`, `set notify email <address>` / `set notify url <https://…>` (`--events`; merged with what the file says), `set network_enforce on` (refuse a site off an agent's `network:` list here; `off` or `clear` goes back to the account's), `set owner`, `set alerts <threshold> <value>`, `set judge model|effort <value>`, and `<job>.<field>` as on `account`, `pause` (`--reason`, `--stop`) and `resume` — this workspace's kill switch, `set description "…"`, `set name <new>` — a rename changes every webhook URL, so it asks first and names the flows whose URLs changed — and `clear <key>`. Singular — `workspaces` is the list |
@@ -187,7 +188,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `--schedule "<cron>"`, `--timezone <zone>` | `flow trigger schedule`: the cron line (5 fields, or `@daily`) and the zone it is read in |
 | `--kind <k>` | `secrets set`: `file`, `ssh`, `api`, `service-account` or `m2m` — each with its own flags, in the `secrets set NAME --kind` row above |
 | `--client <name>` | `connect`: run the consent from that OAuth client saved on the platform (`secrets clients` lists them) |
-| `--subagent`, `--consult`, `--can-ask`, `--description` | `agent link`, `agent unlink`: which list to edit, and a worker's description when it has none |
+| `--subagent`, `--consult`, `--can-ask`, `--description`, `--isolated` | `agent link`, `agent unlink`: which list to edit, a worker's description when it has none, and (`link --subagent` only) `sandbox: own` on the worker |
 | `--eval <name>`, `--expect "<line>"`, `--case <name>` | `promote`: the eval file, an assertion (repeatable), the case's name |
 | `--tag <t>` | `invoke`, `flow run`: a label on the run — repeatable |
 | `--inputs <name>` | `invoke`, `flow run`: the task is that saved input set; not with `--task` |
@@ -216,7 +217,9 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
 | `--wait` | `invoke`, `agent run`: hold on and print the result. Asked in 25-second pieces, so a flow that runs for many minutes is never cut by whatever sits in front of the platform; a run parked on a person prints its page and exits 2 |
 | `--from <n>` | `invoke`, `flow run`, `rerun`: start at step n; earlier steps are recorded as skipped. A bulk `rerun` defaults to 1. (One flag, two meanings: a template on `init`, a step everywhere else) |
 | `--no-browser` | `login`, `connect`: print the address instead of opening it |
-| `--provider <name>` | `connect`: fills the authorize and token URLs and an example scope string; `--authorize-url` / `--token-url` for a provider with no preset |
+| `--authorize-url` / `--token-url` | `connect`, `secrets clients add`: the provider's own OAuth addresses |
+| `--authorize-param name=value` | `connect`, `secrets clients add`: an extra authorize-URL parameter the provider documents, repeatable — Google wants `access_type=offline` and `prompt=consent` before it issues a refresh token. The flow's own parameters (`client_id`, `redirect_uri`, `state`, `scope`, PKCE) cannot be set this way |
+| `--provider <name>` | (deprecated — use `--authorize-url`, `--token-url` and `--authorize-param`) `connect`, `secrets clients add`: filled the URLs for google, github, microsoft or linkedin |
 | `--scopes "<a b c>"` | `connect`: space-separated, as OAuth defines it |
 | `--client-id` / `--client-secret` | `connect`: the OAuth app; prompted when omitted, the secret never echoed |
 | `--port <n>` | `connect`: the loopback port (default 8642) |

package/docs/four-jobs.md

@@ -38,7 +38,7 @@ top. Either way works, and the two can be mixed in one file.
 | File | `governance:` | `guardrail:` | `observability:` | `evaluation:` |
 |---|---|---|---|---|
 | `AGENTS.md` | `owner`, `budget`, `priority`, `concurrency`, `deploy_block` | `limits`, `network`, `network_enforce`, `hooks` | `alerts`, `telemetry`, `notify`, `capture` | `judge` |
-| an agent | `owner`, `budget` | `limits`, `network`, `hooks`, `disallowedTools`, `permissionMode`, `secrets` | — | — |
+| an agent | `owner`, `budget` | `limits`, `network`, `hooks`, `disallowedTools`, `permissionMode`, `secrets`, `sandbox` | — | — |
 | a flow | `owner`, `approvers`, `approve_within`, `budget`, `priority` | `throttle`, `debounce`, `overlap`, `disable_after`, `live` | `issues`, `sla` | — |
 
 A field that does none of the four, such as `name`, `model`, `tools`,

package/docs/secrets.md

@@ -30,9 +30,36 @@ PUT /api/secrets   { "name": "STRIPE_KEY", "value": "sk_live_…" }
 | `file` | a PEM, a certificate, a service-account JSON |
 | `oauth2` | a connected third-party account (see below) |
 | `service_account`, `ssh`, `api` | structured credentials the platform knows how to present |
+| `client_cert` | a certificate and key for mutual TLS, presented by the egress proxy |
+| `identity` | keyless cloud access: an audience, and tokens the platform signs (below) |
 
 Reads return which secrets exist, never their values.
 
+A **service account** is a key file that signs its own token request. It
+acts as itself, or — with **Act as** (`subject`) — as a user the provider
+lets it act for (RFC 7523's grant subject; for Google, domain-wide
+delegation, which a Workspace admin grants in their own console). Each
+subject gets its own token.
+
+An **`api`** connection is a base URL and the headers that go with it. For
+an old system that wants **HTTP Basic**, give a username and password
+instead of an `Authorization` header: the platform builds the header (RFC
+7617, UTF-8), refuses a colon in the username, needs an https base URL, and
+masks the password and the encoded header in every trace — as it does every
+header value of an `api` connection.
+
+A **client certificate** (mutual TLS) is a PEM certificate, its key and an
+optional passphrase; the key must belong to the certificate or it is
+refused. Bind it to the **exact hosts** it is for (`foldrun secrets sites
+NAME api.bank.example` — no wildcards): the egress proxy presents it on its
+own connection to those hosts, and the sandbox never holds the key. Two
+certificates bound to one host is refused, not guessed. A redirect to
+another site never carries it. Unbound, it stays out of the sandbox; save it
+with **export** only for a step that runs without the egress proxy, and it
+arrives as files (`$NAME_CERT`, `$NAME_KEY`, `$NAME_PASSPHRASE_FILE`). This
+is client authentication with a certificate — not OAuth's certificate-bound
+tokens (RFC 8705), which foldrun does not do.
+
 ## Scopes
 
 A secret lives at the **account** or in one **workspace**. An agent looks in
@@ -173,6 +200,85 @@ anything OAuth. Settings → Connections walks the consent flow once and stores
 the result as an `oauth2` secret; the platform refreshes it. An agent names
 it in `secrets:` like any other.
 
+You bring the OAuth app: register it once with the provider (its client id
+and secret, and the redirect URL the form shows), save it, and connect. The
+form asks for the provider's own authorize and token URLs — foldrun keeps no
+list of providers — and **Extra authorize parameters**, one `name=value` per
+line, for whatever else the provider's docs say its authorize URL takes:
+Google issues a refresh token only with `access_type=offline` and
+`prompt=consent`, and without one the connection stops when the first access
+token expires. The flow's own parameters (`client_id`, `redirect_uri`,
+`state`, `scope`, PKCE) cannot be set there. Every
+later connection can use the same saved app — choose it under **App** and
+type the scopes this connection needs, as the provider spells them. Each
+connection keeps its own scopes, so one app serves any number of APIs from
+the same provider (an ads API in one secret, a search API in another), and
+**Reconnect** asks for that connection's scopes again. The provider decides
+what the app may ask for; foldrun only carries the words. From a terminal:
+`foldrun connect NAME --client <saved app> --scopes "<scopes>" --to <workspace>`.
+
+How a connection is kept safe, whatever the provider:
+
+- **PKCE** (S256) is on for every connection: a code stolen on its way back
+  is useless without the verifier only foldrun holds. An app with no client
+  secret (a *public* app) is allowed — PKCE is then what protects it, and
+  its refreshes send no secret. Turn PKCE off only for an app with a secret
+  whose provider refuses the parameters.
+- **The browser that starts a connection is the one it must come back to.**
+  The consent link carries a cookie the callback checks; a link opened in
+  someone else's browser connects nothing.
+- **From a terminal**, `foldrun connect --client` opens a page in the
+  dashboard where you, signed in, see the secret, the app, the scopes and
+  where it will be stored, and accept before the provider is asked.
+- **Issuer.** Give a saved app its provider's issuer and the `iss` the
+  provider sends back (RFC 9207) must match it; without one, a returned
+  `iss` must at least be the authorize URL's own site.
+- The flow's own parameters (`client_id`, `redirect_uri`, `scope`, `state`,
+  the PKCE pair) cannot be overridden by extra parameters or by a query
+  string in the authorize URL.
+- A provider that **rotates refresh tokens** sends a new one with each
+  refresh; it replaces the old one in the vault, where that secret is kept.
+
+## Keyless cloud identity
+
+The safest credential is none at all. A cloud that supports workload
+identity federation — AWS (`AssumeRoleWithWebIdentity`), Google Cloud
+(Workload Identity Federation), Microsoft Entra (federated credentials) —
+can trust **foldrun's signature** instead of a key you store: a step proves
+which account, workspace and agent it is, and the cloud gives it a
+short-lived credential of its own.
+
+1. In your cloud, trust this install as an OIDC provider: its issuer is
+   shown by `foldrun identity` (and in the Connections form). Pin the
+   subject — `account:<account>:workspace:<workspace>:agent:<agent>` — at
+   least to your account, and the audience you choose.
+2. `foldrun secrets set AWS_ID --kind identity --audience sts.amazonaws.com`
+   (or Connections → Identity). Nothing secret is stored: only the audience.
+3. Name it in an agent's `secrets:`. The step gets **`$AWS_ID_FILE`**: a
+   token signed RS256, valid ten minutes, renewed while the step runs. Point
+   your cloud's SDK at it — for AWS, `AWS_ROLE_ARN` and
+   `AWS_WEB_IDENTITY_TOKEN_FILE=$AWS_ID_FILE`; for Google, an
+   `external_account` credential file whose `credential_source.file` is it;
+   for Entra, the token as the client assertion.
+
+What it is and is not:
+
+- A **workload-federation issuer**, not a sign-in provider: discovery
+  publishes what federation reads (issuer, JWKS, RS256, public subjects),
+  and nothing more.
+- The subject and claims come from the platform's own record of the run,
+  never from the sandbox. A token is issued only to the step the identity
+  was granted to, only while its driver checks in, and never after the step
+  stops or ends.
+- Stopping a step stops renewal; it cannot recall a token already issued,
+  which expires within ten minutes on its own.
+- Within an account, a workspace or agent recreated under the same name
+  is the same subject: pin your trust policy to the account at least.
+- Who may run or edit an agent that names the identity may use it — as
+  with every secret.
+- Not on a laptop: only a sandboxed step on a platform whose operator set
+  `FOLDRUN_OIDC_ISSUER` gets a token.
+
 ## How they are kept
 
 Every account has its own encryption key. Secrets are sealed under it, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldrun",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Agents are just folders. Write them, check them, run them — on your machine.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -11,7 +11,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@foldrun/core": "^2.6.0"
+    "@foldrun/core": "^2.8.0"
   },
   "files": [
     "bin",
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "e2e": "FOLDRUN_E2E=1 FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-e2e-XXXXXX) node --test --test-timeout=300000 tests/e2e.test.ts",
-    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts",
+    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-agent-link-isolated.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts",
     "release": "node scripts/release.mjs",
     "typecheck": "tsc -p tsconfig.json",
     "docs:sync": "node scripts/sync-docs.mjs",

package/src/commands.mjs

@@ -1340,7 +1340,8 @@ async function checkProblems(workspace, flags = {}) {
           note("warn", `agents/${a.name}`, `subagents: [${s}] — an agent delegating to itself; it is skipped at run time`);
         } else if (!sub.description?.trim()) {
           note("error", `agents/${s}`, `no description — ${a.name} delegates to it (subagents:), and the model picks a sub-agent by its description`);
-        } else if (sub.tools.length && !checkOverlap(a.tools, sub.tools).length) {
+        } else if (!ownSandboxOf(sub) && sub.tools.length && !checkOverlap(a.tools, sub.tools).length) {
+          // sandbox: own — its tools are its own, not cut to the parent's.
           note("warn", `agents/${a.name}`, `subagents: [${s}] — none of ${s}'s tools are in ${a.name}'s, and a sub-agent never gets more than its parent: it would have no tools`);
         }
       }
@@ -3609,13 +3610,38 @@ const CONNECT_PORT = 8642;
  * a provider that issues none (GitHub, most LinkedIn apps) gets its access
  * token stored as a static value and the expiry is said out loud.
  */
+/**
+ * `--authorize-param name=value`, repeatable: extra query parameters on the
+ * provider's authorize URL — what a provider wants beyond OAuth's own
+ * (Google's access_type=offline and prompt=consent, for a refresh token).
+ * foldrun knows no provider; the person types what theirs documents.
+ */
+function authorizeParams(flags) {
+  const out = {};
+  for (const p of [flags["authorize-param"]].flat().filter((x) => x !== undefined)) {
+    const i = typeof p === "string" ? p.indexOf("=") : -1;
+    if (i < 1) throw new Error(`--authorize-param takes name=value, got "${p}"`);
+    out[p.slice(0, i).trim()] = p.slice(i + 1).trim();
+  }
+  return out;
+}
+
+/** --provider is deprecated: a runner keeps no provider list. Said once,
+ *  on stderr, so a script reading stdout is not disturbed. */
+function warnProviderDeprecated(flags) {
+  if (flags.provider !== undefined) {
+    console.error(c.dim("  --provider is deprecated — pass the provider's own --authorize-url and --token-url, and any --authorize-param it documents"));
+  }
+}
+
 async function connect(positional, flags) {
   const name = positional[0];
-  if (!name) throw new Error("usage: foldrun connect NAME [--provider <google|github|microsoft|linkedin>] [--workspace <name>] [--new-client]");
+  if (!name) throw new Error("usage: foldrun connect NAME --authorize-url <url> --token-url <url> [--authorize-param name=value …] [--scopes …] [--workspace <name>] [--new-client]");
   if (!/^[A-Z][A-Z0-9_]*$/.test(name)) throw new Error(`secret name "${name}" must be UPPER_SNAKE_CASE`);
   const { OAUTH_PRESETS } = await core();
 
   const providerName = flags.provider;
+  warnProviderDeprecated(flags);
   const preset = providerName ? OAUTH_PRESETS[providerName] : undefined;
   if (providerName && !preset) {
     throw new Error(`unknown provider "${providerName}" — one of ${Object.keys(OAUTH_PRESETS).join(", ")}, or pass --authorize-url and --token-url`);
@@ -3668,14 +3694,18 @@ async function connect(positional, flags) {
     }
   }
 
-  if (!authorizeUrl || !tokenUrl) throw new Error("--provider, or both --authorize-url and --token-url");
+  if (!authorizeUrl || !tokenUrl) throw new Error("--authorize-url and --token-url — the provider's own addresses, from its OAuth docs");
+  const extra = { ...(preset?.authorize_extra ?? {}), ...authorizeParams(flags) };
   if (!/^https:\/\//.test(tokenUrl) && !/^http:\/\/(127\.0\.0\.1|localhost)[:/]/.test(tokenUrl)) {
     throw new Error("token URL must be https — a refresh token over http is a leaked one");
   }
 
   const clientId = flags["client-id"] ?? env("OAUTH_CLIENT_ID") ?? (await promptVisible("  client_id: "));
-  const clientSecret = flags["client-secret"] ?? env("OAUTH_CLIENT_SECRET") ?? (await promptHidden("  client_secret: "));
-  if (!clientId || !clientSecret) throw new Error("client_id and client_secret are required");
+  const pkce = flags["no-pkce"] !== true;
+  const clientSecret = flags["client-secret"] ?? env("OAUTH_CLIENT_SECRET") ?? (await promptHidden(`  client_secret${pkce ? " (empty for a public app)" : ""}: `));
+  if (!clientId) throw new Error("client_id is required");
+  // No secret is a public app, which PKCE alone protects (RFC 9700 §2.1.1).
+  if (!clientSecret && !pkce) throw new Error("an app with no client_secret needs PKCE — drop --no-pkce");
   const scopes = flags.scopes ?? preset?.scopes_example ?? "";
 
   // One fixed loopback address, the same on every developer's machine, so an
@@ -3691,13 +3721,21 @@ async function connect(positional, flags) {
   const crypto = await import("node:crypto");
   const http = await import("node:http");
   const state = crypto.randomBytes(24).toString("hex");
+  // PKCE (RFC 7636, S256): 32 random bytes as the verifier, its hash as the challenge.
+  const verifier = pkce ? crypto.randomBytes(32).toString("base64url") : null;
   const authorize = new URL(authorizeUrl);
+  // Extras first: the flow's own parameters are set after, and win.
+  for (const [k, v] of Object.entries(extra)) authorize.searchParams.set(k, v);
+  for (const k of ["client_id", "redirect_uri", "response_type", "scope", "state", "code_challenge", "code_challenge_method"]) authorize.searchParams.delete(k);
   authorize.searchParams.set("response_type", "code");
   authorize.searchParams.set("client_id", clientId);
   authorize.searchParams.set("redirect_uri", redirectUri);
   authorize.searchParams.set("state", state);
   if (scopes) authorize.searchParams.set("scope", scopes);
-  for (const [k, v] of Object.entries(preset?.authorize_extra ?? {})) authorize.searchParams.set(k, v);
+  if (verifier) {
+    authorize.searchParams.set("code_challenge", crypto.createHash("sha256").update(verifier).digest("base64url"));
+    authorize.searchParams.set("code_challenge_method", "S256");
+  }
 
   // One request, then the listener closes. The state is the whole authority:
   // a callback with any other value is answered and ignored.
@@ -3733,7 +3771,11 @@ async function connect(positional, flags) {
   const exchange = await fetch(tokenUrl, {
     method: "POST",
     headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
-    body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: redirectUri, client_id: clientId, client_secret: clientSecret }).toString(),
+    body: new URLSearchParams({
+      grant_type: "authorization_code", code, redirect_uri: redirectUri, client_id: clientId,
+      ...(clientSecret ? { client_secret: clientSecret } : {}),
+      ...(verifier ? { code_verifier: verifier } : {}),
+    }).toString(),
   });
   const payload = /** @type {any} */ (await exchange.json().catch(() => ({})));
   if (!exchange.ok || (!payload.refresh_token && !payload.access_token)) {
@@ -3743,7 +3785,7 @@ async function connect(positional, flags) {
   // Store: the refresh recipe when there is one, the bare token otherwise.
   /** @type {any} */
   const body = payload.refresh_token
-    ? { name, oauth2: { token_url: tokenUrl, client_id: clientId, client_secret: clientSecret, refresh_token: payload.refresh_token }, workspace: workspaceName, scopes, ...(payload.refresh_token_expires_in ? { refresh_token_expires_in: payload.refresh_token_expires_in } : {}) }
+    ? { name, oauth2: { token_url: tokenUrl, client_id: clientId, ...(clientSecret ? { client_secret: clientSecret } : {}), refresh_token: payload.refresh_token }, workspace: workspaceName, scopes, ...(payload.refresh_token_expires_in ? { refresh_token_expires_in: payload.refresh_token_expires_in } : {}) }
     : { name, value: payload.access_token, workspace: workspaceName };
   if (url) {
     // The same PUT `secrets set` makes. A store that fails here has spent the
@@ -5738,6 +5780,30 @@ function shortValue(v) {
   return typeof v === "object" ? JSON.stringify(v).replace(/"([a-z_]+)":/g, "$1: ").replace(/,/g, ", ") : String(v);
 }
 
+/**
+ * `foldrun identity [--to <workspace>]` — what a cloud must trust to accept
+ * this account's keyless identities: the issuer, and each agent's subject.
+ */
+async function identityCmd(flags) {
+  const url = platformFor(flags, "identity");
+  const ws = typeof flags.to === "string" ? flags.to : null;
+  const info = await remoteCall(url, flags, `/api/identity${ws ? `?workspace=${enc(ws)}` : ""}`);
+  if (flags.json === true) {
+    console.log(JSON.stringify(info, null, 2));
+    return 0;
+  }
+  if (!info.enabled) {
+    console.log(`\n  ${c.yellow("This install does not issue identity tokens")} ${c.dim("— its operator sets FOLDRUN_OIDC_ISSUER")}\n`);
+    return 1;
+  }
+  console.log(`\n  ${c.bold("Keyless cloud identity")}\n`);
+  console.log(`  issuer   ${info.issuer}`);
+  console.log(`  subject  ${info.subject}`);
+  console.log(`  tokens   ${Math.round(info.tokenSeconds / 60)} minutes, renewed while a step runs`);
+  console.log(`\n  ${c.dim("Trust the issuer in your cloud and pin at least the account in the subject; then `foldrun secrets set NAME --kind identity --audience <aud>` and name it in an agent's secrets:")}\n`);
+  return 0;
+}
+
 /**
  * `foldrun jobs [--to <workspace>]` — the four jobs and every AGENTS.md
  * field of each: the account's value, the workspace's, and how the two
@@ -8117,6 +8183,27 @@ async function flowRmStepCmd(positional, flags, layout) {
 }
 
 /** Whether an agent file says what the agent is for. */
+/** `sandbox: own` on an agent as core's listAgents reports it — from core
+ *  2.8 on; an older core does not say, and the agent reads as not own. */
+function ownSandboxOf(agent) {
+  return /** @type {{ sandbox?: string } | undefined} */ (agent)?.sandbox === "own";
+}
+
+/** An agent file's frontmatter as a run reads it (core's configMatter, which
+ *  folds the job blocks), from its text. {} when it does not parse. */
+async function effectiveFront(raw) {
+  const { readFrontmatter } = await core();
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-front-"));
+  try {
+    fs.writeFileSync(path.join(dir, "agent.md"), raw);
+    return readFrontmatter(path.join(dir, "agent.md")) ?? {};
+  } catch {
+    return {};
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
 function hasDescription(raw) {
   const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw)?.[1] ?? "";
   const lines = front.split(/\r?\n/);
@@ -8228,7 +8315,7 @@ async function agentImportCmd(positional, flags, layout) {
 }
 
 /**
- * `foldrun agent link <agent> --subagent <worker> | --consult <agent> |
+ * `foldrun agent link <agent> --subagent <worker> [--isolated] | --consult <agent> |
  * --can-ask`, and `unlink` — an agent's team, edited in its frontmatter
  * list and nowhere else: `subagents:`, `agents:`, `ask` in `tools:`.
  */
@@ -8236,7 +8323,7 @@ async function agentLinkCmd(positional, flags, layout) {
   const verb = positional[0];
   const add = verb === "link";
   const name = positional[1];
-  const usage = `\`foldrun agent ${verb} <agent> --subagent <worker> | --consult <agent> | --can-ask\``;
+  const usage = `\`foldrun agent ${verb} <agent> --subagent <worker> [--isolated] | --consult <agent> | --can-ask\``;
   if (!name) throw new Error(usage);
   const picked = [
     typeof flags.subagent === "string" ? ["subagents", flags.subagent] : null,
@@ -8245,6 +8332,10 @@ async function agentLinkCmd(positional, flags, layout) {
   ].filter(Boolean);
   if (picked.length !== 1) throw new Error(`${usage} — exactly one of them`);
   const [key, member] = /** @type {[string, string]} */ (picked[0]);
+  // --isolated: the worker runs each job in its own sandbox (sandbox: own on
+  // its file) — its own tools, secrets and network, not cut to the parent's.
+  const isolated = flags.isolated === true;
+  if (isolated && (key !== "subagents" || !add)) throw new Error("--isolated goes with `agent link <agent> --subagent <worker>`");
 
   const desk = await openDesk(flags, layout, `agent ${verb} ${name}`);
   const { editFrontmatterList, setFrontmatterScalar } = await patterns();
@@ -8258,8 +8349,11 @@ async function agentLinkCmd(positional, flags, layout) {
 
   const raw = desk.files.get(fileOf(name));
   const next = editFrontmatterList(raw, key, member, add ? "add" : "remove");
-  const said = key === "subagents" ? `${member} as a sub-agent` : key === "agents" ? `${member} as a consult` : "asking you mid-step";
-  if (next === raw) {
+  const said = key === "subagents" ? `${member} as a sub-agent${isolated ? " in its own sandbox" : ""}` : key === "agents" ? `${member} as a consult` : "asking you mid-step";
+  // What a run reads, through core's parser: a `guardrail:` block counts,
+  // and "sandbox: own" inside a description does not.
+  const workerOwn = isolated && (await effectiveFront(desk.files.get(fileOf(member)) ?? "")).sandbox === "own";
+  if (next === raw && (!isolated || workerOwn)) {
     console.log(`\n  ${c.dim(add ? `${name} already has ${said}` : `${name} does not have ${said} — nothing to remove`)}\n`);
     return 0;
   }
@@ -8277,9 +8371,22 @@ async function agentLinkCmd(positional, flags, layout) {
       if (!description) throw new Error("no description given — nothing written");
     }
     const w = desk.files.get(fileOf(member));
-    edits.push({ agent: member, rel: fileOf(member), before: w, after: setFrontmatterScalar(w, "description", description), body: { set: { key: "description", value: description } } });
+    edits.push({ agent: member, rel: fileOf(member), before: w, after: setFrontmatterScalar(w, "description", description), bodies: [{ set: { key: "description", value: description } }] });
+  }
+  if (isolated && !workerOwn) {
+    // The worker's file once, whatever is set on it: one diff, one write,
+    // one PATCH per key on the platform.
+    const prior = edits.find((e) => e.agent === member);
+    const set = { set: { key: "sandbox", value: "own" } };
+    if (prior) {
+      prior.after = setFrontmatterScalar(prior.after, "sandbox", "own");
+      prior.bodies.push(set);
+    } else {
+      const w = desk.files.get(fileOf(member));
+      edits.push({ agent: member, rel: fileOf(member), before: w, after: setFrontmatterScalar(w, "sandbox", "own"), bodies: [set] });
+    }
   }
-  edits.push({ agent: name, rel: fileOf(name), before: raw, after: next, body: { list: { key, name: member, action: add ? "add" : "remove" } } });
+  if (next !== raw) edits.push({ agent: name, rel: fileOf(name), before: raw, after: next, bodies: [{ list: { key, name: member, action: add ? "add" : "remove" } }] });
 
   console.log(`\n  ${c.bold(name)} ${c.dim(`· ${add ? "add" : "remove"} ${said} · ${desk.label}`)}\n`);
   for (const e of edits) {
@@ -8302,7 +8409,9 @@ async function agentLinkCmd(positional, flags, layout) {
   if (!desk.platform) for (const e of edits) assertUnchanged(desk, e.rel, e.before);
   for (const e of edits) {
     if (desk.platform) {
-      await remoteCall(desk.url, flags, `/api/workspaces/${enc(desk.ws)}/agents/${enc(e.agent)}`, { method: "PATCH", body: JSON.stringify(e.body) });
+      for (const body of e.bodies) {
+        await remoteCall(desk.url, flags, `/api/workspaces/${enc(desk.ws)}/agents/${enc(e.agent)}`, { method: "PATCH", body: JSON.stringify(body) });
+      }
     } else {
       writeIfUnchanged(desk, e.rel, e.before, e.after);
     }
@@ -8487,7 +8596,7 @@ async function flowShowCmd(positional, flags, layout) {
       const a = byAgent.get(s.agent);
       if (!a) return;
       if (a.model) console.log(`${under}${p.dim(`model ${a.model}${a.tools?.length ? ` · ${a.tools.length} tool${a.tools.length === 1 ? "" : "s"}` : ""}`)}`);
-      for (const w of a.subagents ?? []) console.log(`${under}↳ sub-agent ${w}`);
+      for (const w of a.subagents ?? []) console.log(`${under}↳ sub-agent ${w}${ownSandboxOf(byAgent.get(w)) ? p.dim(" (own sandbox)") : ""}`);
       for (const w of a.consults ?? []) console.log(`${under}· consults ${w}`);
       if ((a.tools ?? []).includes("ask")) console.log(`${under}${p.amber("may ask you")}`);
       for (const x of ofAgent(s.agent)) console.log(`${under}${mark(x)}`);
@@ -10485,17 +10594,27 @@ async function oauthClientsCmd(positional, flags) {
     return 0;
   }
   if (verb === "add") {
-    if (!name || !/^[a-z0-9][a-z0-9-]*$/.test(name)) throw new Error("`foldrun secrets clients add <name> --provider google|github|microsoft|linkedin --client-id … [--scopes …]` — the name in kebab-case");
+    if (!name || !/^[a-z0-9][a-z0-9-]*$/.test(name)) throw new Error("`foldrun secrets clients add <name> --authorize-url … --token-url … --client-id … [--authorize-param name=value …] [--scopes …]` — the name in kebab-case");
+    warnProviderDeprecated(flags);
     const { OAUTH_PRESETS } = await core();
     const preset = flags.provider ? OAUTH_PRESETS[flags.provider] : undefined;
     if (flags.provider && !preset) throw new Error(`unknown provider "${flags.provider}" — one of ${Object.keys(OAUTH_PRESETS).join(", ")}, or pass --authorize-url and --token-url`);
     const authorize_url = flags["authorize-url"] ?? preset?.authorize_url;
     const token_url = flags["token-url"] ?? preset?.token_url;
-    if (!authorize_url || !token_url) throw new Error("--provider, or both --authorize-url and --token-url");
+    if (!authorize_url || !token_url) throw new Error("--authorize-url and --token-url — the provider's own addresses, from its OAuth docs");
+    const authorize_extra = { ...(preset?.authorize_extra ?? {}), ...authorizeParams(flags) };
     const client_id = flags["client-id"] ?? env("OAUTH_CLIENT_ID") ?? (await promptVisible("  client_id: "));
-    const client_secret = flags["client-secret"] ?? env("OAUTH_CLIENT_SECRET") ?? (await promptHidden("  client_secret: "));
-    if (!client_id || !client_secret) throw new Error("client_id and client_secret are required");
-    const config = { authorize_url, token_url, client_id, client_secret, scopes: flags.scopes ?? preset?.scopes_example ?? "", ...(preset?.authorize_extra ? { authorize_extra: preset.authorize_extra } : {}) };
+    const pkce = flags["no-pkce"] !== true;
+    const client_secret = flags["client-secret"] ?? env("OAUTH_CLIENT_SECRET") ?? (await promptHidden(`  client_secret${pkce ? " (empty for a public app)" : ""}: `));
+    if (!client_id) throw new Error("client_id is required");
+    if (!client_secret && !pkce) throw new Error("an app with no client_secret needs PKCE — drop --no-pkce");
+    if (flags.issuer !== undefined && (typeof flags.issuer !== "string" || !/^https:\/\/[^?#]+$/.test(flags.issuer))) throw new Error("--issuer is the provider's https issuer URL, no query or fragment");
+    const config = {
+      authorize_url, token_url, client_id, client_secret: client_secret ?? "", scopes: flags.scopes ?? preset?.scopes_example ?? "",
+      ...(Object.keys(authorize_extra).length ? { authorize_extra } : {}),
+      ...(pkce ? {} : { pkce: false }),
+      ...(typeof flags.issuer === "string" ? { issuer: flags.issuer } : {}),
+    };
     await remoteCall(url, flags, "/api/oauth/clients", { method: "POST", body: JSON.stringify({ name, config }) });
     console.log(`\n  ${c.green("✓")} saved ${name} ${c.dim(`— \`foldrun connect NAME --client ${name}\` runs a consent from it`)}\n`);
     return 0;
@@ -10512,9 +10631,15 @@ async function connectFromClient(name, flags) {
   const url = platformFor(flags, "connect --client");
   const workspace = typeof flags.to === "string" ? flags.to : undefined;
   const before = (await remoteCall(url, flags, "/api/oauth/connections")).connections?.find((s) => s.name === name && (s.workspace ?? undefined) === workspace)?.connectedAt ?? null;
-  const started = await remoteCall(url, flags, "/api/oauth/start", { method: "POST", body: JSON.stringify({ client: flags.client, secret: name, ...(workspace ? { workspace } : {}) }) });
+  // --scopes: this connection's own, instead of the saved client's default;
+  // the platform keeps them with the connection for its reconnects.
+  const scopes = typeof flags.scopes === "string" && flags.scopes.trim() ? { scopes: flags.scopes } : {};
+  const started = await remoteCall(url, flags, "/api/oauth/start", { method: "POST", body: JSON.stringify({ client: flags.client, secret: name, ...(workspace ? { workspace } : {}), ...scopes }) });
   const opened = flags["no-browser"] === true || !process.stdout.isTTY ? false : await openInBrowser(started.url);
-  console.log(opened ? `\n  Opened your browser to consent with the saved ${c.bold(flags.client)} client.\n` : `\n  Open this address in your browser:\n\n    ${started.url}\n`);
+  // The platform answers a hand-off page: a signed-in person accepts the
+  // connection there, then the provider's consent runs in that browser.
+  const what = started.handoff ? "accept the connection, then consent" : "consent";
+  console.log(opened ? `\n  Opened your browser to ${what} with the saved ${c.bold(flags.client)} app.\n` : `\n  Open this address in your browser to ${what}:\n\n    ${started.url}\n`);
   console.log(`  ${c.dim("Waiting for the platform to store it…")}`);
   const deadline = Date.now() + 10 * 60 * 1000;
   while (Date.now() < deadline) {
@@ -10549,7 +10674,11 @@ async function secretOfKind(kind, flags) {
     }
     case "api": {
       const lines = [].concat(flags.header ?? []);
-      if (!lines.length) lines.push(await promptHidden("  header (Name: value): "));
+      // --basic-user: HTTP Basic from a username and password (prompted, or
+      // --basic-password); the platform builds the Authorization header.
+      const basicUser = typeof flags["basic-user"] === "string" ? flags["basic-user"] : null;
+      const basic = basicUser ? { basic: { username: basicUser, password: typeof flags["basic-password"] === "string" ? flags["basic-password"] : await promptHidden("  password: ") } } : {};
+      if (!lines.length && !basicUser) lines.push(await promptHidden("  header (Name: value): "));
       const headers = Object.fromEntries(
         lines.filter(Boolean).map((l) => {
           const i = String(l).indexOf(":");
@@ -10558,7 +10687,23 @@ async function secretOfKind(kind, flags) {
         }),
       );
       const base = typeof flags["base-url"] === "string" ? { base_url: flags["base-url"] } : {};
-      return { body: { api: { ...base, headers } }, local: (k, n, b, s) => k.setApiSecret("default", n, b.api, s) };
+      return { body: { api: { ...base, headers, ...basic } }, local: (k, n, b, s) => k.setApiSecret("default", n, b.api, s) };
+    }
+    case "identity": {
+      // A keyless cloud identity: only the audience; the platform signs the
+      // tokens (`foldrun identity` prints what the cloud must trust).
+      if (typeof flags.audience !== "string" || !flags.audience.trim()) throw new Error("--kind identity needs --audience <value your cloud's trust expects in aud>");
+      return { body: { identity: { audience: flags.audience } }, local: (k, n, b, s) => k.setIdentitySecret("default", n, b.identity, s) };
+    }
+    case "client-cert": {
+      // A client certificate for mutual TLS. Bind it to the exact hosts it is
+      // for with `foldrun secrets sites NAME host`; the egress proxy presents
+      // it there. --export also puts it in the sandbox as files.
+      const cert = read(flags["cert-file"], "--cert-file <cert.pem> — the certificate, chain included");
+      const key = read(flags["key-file"], "--key-file <key.pem> — its private key");
+      const passphrase = typeof flags.passphrase === "string" ? flags.passphrase : undefined;
+      const client_cert = { cert, key, ...(passphrase ? { passphrase } : {}), ...(flags.export === true ? { export: true } : {}) };
+      return { body: { client_cert }, local: (k, n, b, s) => k.setClientCertSecret("default", n, b.client_cert, s) };
     }
     case "service-account": {
       let j;
@@ -10568,7 +10713,9 @@ async function secretOfKind(kind, flags) {
         if (err instanceof SyntaxError) throw new Error(`${flags.file} is not JSON — the key file Google gives you`);
         throw err;
       }
-      const sa = { token_url: j.token_uri ?? "https://oauth2.googleapis.com/token", issuer: j.client_email, private_key: j.private_key, scope: flags.scopes ?? "" };
+      // --subject: the user it acts as (domain-wide delegation, granted by the
+      // provider's admin); without it the account acts as itself.
+      const sa = { token_url: j.token_uri ?? "https://oauth2.googleapis.com/token", issuer: j.client_email, private_key: j.private_key, scope: flags.scopes ?? "", ...(typeof flags.subject === "string" ? { subject: flags.subject } : {}) };
       return { body: { service_account: sa }, local: (k, n, b, s) => k.setServiceAccountSecret("default", n, b.service_account, s) };
     }
     case "m2m": {
@@ -10579,7 +10726,7 @@ async function secretOfKind(kind, flags) {
       return { body: { oauth2 }, local: (k, n, b, s) => k.setOAuth2Secret("default", n, b.oauth2, s) };
     }
     default:
-      throw new Error(`unknown --kind "${kind}" — file, ssh, api, service-account or m2m (a plain value needs no --kind; --oauth2 a refresh token; \`foldrun connect\` a browser sign-in)`);
+      throw new Error(`unknown --kind "${kind}" — file, ssh, api, service-account, m2m, client-cert or identity (a plain value needs no --kind; --oauth2 a refresh token; \`foldrun connect\` a browser sign-in)`);
   }
 }
 
@@ -11235,6 +11382,8 @@ export async function run(command, positional, flags, workspace, layout) {
       return rerunCmd(positional[0], flags, layout);
     case "account":
       return accountCmd(positional, flags);
+    case "identity":
+      return identityCmd(flags);
     case "jobs":
       return jobsCmd(flags, layout);
     case "schedule":

package/src/guide.mjs

@@ -30,7 +30,7 @@ export function agentRulesBlock() {
 
 # Read foldrun's docs before you edit this folder
 
-This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls; it is also the security scanner (a key written into a file, hidden text, an agent that can leak), and \`foldrun check --security\` fails on what it finds. Never paste a credential into a file: \`foldrun secrets set NAME\` and write \`\${NAME}\`. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). An agent with \`tools: [peers]\` can message the steps running beside it in its parallel group (\`peers_message\`) and ask for what they have instead of guessing or failing (\`foldrun docs agents\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling. Which sites a step's sandbox may reach is \`network:\` — open for an agent that may fetch or browse the web, the trusted list plus what it declares for every other; add a site with \`foldrun agent network <agent> --add <site>\` (\`foldrun docs network\`). Bind a secret to the sites it is for (\`foldrun secrets sites NAME <site>\`) and no sandbox ever holds its value.
+This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls; it is also the security scanner (a key written into a file, hidden text, an agent that can leak), and \`foldrun check --security\` fails on what it finds. Never paste a credential into a file: \`foldrun secrets set NAME\` and write \`\${NAME}\`. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). An agent with \`tools: [peers]\` can message the steps running beside it in its parallel group (\`peers_message\`) and ask for what they have instead of guessing or failing (\`foldrun docs agents\`). A sub-agent that reads untrusted content (web pages, mail, uploads) gets \`sandbox: own\` in its own file: each job then runs in a sandbox of its own with its own tools, secrets and network, and only its reply reaches the agent that delegated (\`foldrun agent link <agent> --subagent <worker> --isolated\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling. Which sites a step's sandbox may reach is \`network:\` — open for an agent that may fetch or browse the web, the trusted list plus what it declares for every other; add a site with \`foldrun agent network <agent> --add <site>\` (\`foldrun docs network\`). Bind a secret to the sites it is for (\`foldrun secrets sites NAME <site>\`) and no sandbox ever holds its value.
 
 This block is for coding tools. It is written and re-added by the foldrun CLI, and the runtime strips it, so the agents that run here never see it; the rest of this file is the account's own context, which they do read. Committing the block with your work keeps the tree clean.