pi-roundtable 0.32.1 → 0.33.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.33.0] - 2026-11-04
+
+This is a minor release with breaking defaults: the agents' shell and the coding plugin's workers no longer inherit the host's environment, and more shell commands are held. See the migration notes below.
+
+### Changed
+
+- The agents' `bash` gets only the names in `SHELL_ENV_NAMES` (`PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `LANG`, `LANGUAGE`, `LC_*`, `TZ`, `TERM`, `TMPDIR`, the proxy variables, `SSL_CERT_FILE`, `SSL_CERT_DIR`, and Pi's `PI_*` session names) instead of the whole host environment, so `env` no longer prints the bot tokens, model logins, `GH_TOKEN`, `DATABASE_URL` and keys the host holds. The new config key and `HostEnvironment` field `shellEnv: { pass?, set? }` (types `ShellEnv` and `ShellEnvConfig`, main entry) names more host variables to pass and fixed values to set; plugins read it as `context.env.shellEnv`. Without `pass` the shell keeps `GH_TOKEN` (`DEFAULT_SHELL_PASS`), so `gh` and a `git push` through `gh auth git-credential` keep working; `pass: []` drops it. A session without a scratch dir now gets the same whitelisted `bash`.
+- The shell rule holds reading secrets as the new class `shell.secret-read`, which `YOLO_CARDED_SHELL_CLASSES` includes, so yolo mode cards it: `env` or `printenv` with no command to run, `export`/`export -p`, `declare -p`, `declare -x` and `typeset` with no names, `set` alone, `compgen -e`; a file reader (`cat`, `less`, `head`, `tail`, `grep`, `sed`, `awk`, `base64`, `xxd`, `cp`, `tar`, `zip`, `curl -d @`/`-F @`/`--data-binary @`/`-T`, and the like) or a `<` redirect of a secret file; Pi's `read` tool on one; `gh auth token`, `gh auth status -t`/`--show-token`; `git credential`; and `git config` reading `credential.*` or listing everything. Secret files are `DEFAULT_SECRET_PATHS` (`/proc/*/environ`, `*.env`, `.env*` except `.env.example`, `.env.sample`, `.env.template`, `~/.ssh/**`, `~/.config/gh/**`, `.git-credentials`, `.netrc`, `.pgpass`, Pi's `auth.json`) plus the globs of the new `shellHoldRuleFor` option `secretPaths` (its options are now the type `ShellPolicy`, which extends `PushPolicy`). `env FOO=1 cmd` is still judged as `cmd`.
+- `docker run`, `exec`, `create` and `cp`, also under `docker container` and as `docker compose run`, `exec` and `cp`, are held as `shell.docker`: they run commands or copy files as the daemon's root.
+- Tool output is masked before it enters the model's context: each value of a host variable whose name matches `SECRET_NAME` (`TOKEN`, `SECRET`, `KEY`, `PASS`, `PASSWORD`, `DATABASE_URL`, `JWT`, `CREDENTIAL`) and that is at least 8 characters becomes `****`, in every tool's result, by the core's `secretMaskExtension()`.
+
+### Added
+
+- In `pi-roundtable/kit`, for a plugin that spawns a child process or runs a session of its own: `childEnv` (`childEnv(source, { pass?, set? })`, the environment of a child process), `shellChildEnv` (the same for an agent's shell, `pass` defaulting to `DEFAULT_SHELL_PASS`), `DEFAULT_SHELL_PASS`, `SHELL_ENV_NAMES`, `ShellPolicy`, `DEFAULT_SECRET_PATHS`, `maskSecrets`, `SECRET_NAME` and `secretMaskExtension`. `ShellEnv` and `ShellEnvConfig` are exported from the main entry.
+- README and site: a threat model of the host shell. It runs as the host's user; holds are not a sandbox; the whitelist, the secret-read hold and the mask stop casual and accidental leaks, not a determined read by the same user. Run agent shells under a dedicated account without the `docker` group, which equals root, or use pi-roundtable-sandbox.
+
+### Migration
+
+- A command in the agents' shell that relied on a host variable other than `GH_TOKEN` now misses it. A CLI that reads an API key needs it named: `shellEnv: { pass: ["GH_TOKEN", "SOME_API_KEY"] }` (a given `pass` replaces the default, so keep `GH_TOKEN` in it if the shell pushes). To keep `GH_TOKEN` out of the shell too, set `shellEnv: { pass: [] }`. Prefer a fixed, narrower value in `set`, or a credential the tool reads from its own config, to passing a host secret.
+- A yolo conversation now asks on a card for `env`, `printenv`, reading `.env` files and the other `shell.secret-read` commands, and for `docker run`/`exec`/`create`/`cp`; list the class in `autonomy.yolo.allow` to approve it without a card. A hold rule built with `shellHoldRuleFor` takes `secretPaths` to add files.
+- An exhaustive switch over the shell classes gains `shell.secret-read`.
+
 ## [0.32.1] - 2026-11-04
 
 - Release in lockstep with pi-roundtable-web 0.32.1 (optimistic mark-as-read, a Home button at the foot of the room drawer, Discord's -# subtext and line breaks in messages, the shared prompt's description in zh-TW, and the push device list centred); no core behavior changes.

package/README.md

@@ -274,6 +274,7 @@ pi-roundtable runs one assistant for one owner.
 - **Approvals.** A held call is approved only by the speaker whose turn held it, at a tier that still holds the call, or, in a shared conversation, by an owner, on its card or by a confirming message. In a private conversation nobody else may, and a call above the speaker's tier is not approved there.
 - **Conversations.** In Discord an agent's channel and a group room are shared: everyone who writes there adds to one conversation the agent reads. A web chat conversation belongs to the person who opened it: in the web chat only they may read it, write in it, or answer its prompts, but the owner can read it through the owner console ([pi-roundtable-web](packages/web)), and the operator through the database and the data directory.
 - **Memory isolation.** Memory follows the principal, not owner tier: a private conversation's person, or the current speaker in a shared room. Link accounts to share one person's memory across Discord and web. In shared requests and summaries, memory-tool and memory-loaded-worker exchanges (arguments and results together) are hidden from other speakers, and earlier reasoning is removed with provider-aware handling. Other tools' arguments and public assistant replies remain public, even if the model repeats private memory there; this is not general secret-flow prevention. Third-party compactors must use `privateCompaction` before summarizing shared history. `claude-bridge` shared turns refuse when raw reader records, including compacted turns, show another reader's private memory (even prompt-only memory and its reasoning), or an exchange is hidden from the current reader. A turn with no private memory does not block other readers, and disabling future memory does not bypass prior private history; admitting other people only warns at boot and in doctor. SYSTEM counts as primary owner for this core guard alone, so it can read and publicly repeat the owner's retained exchanges/reasoning; pre-0.9 untagged built-in memory results before the first scope record retain owner attribution. Sandbox party-wide prompt blocks must explicitly use `memory.visibility: "shared"`, and private turns require worker capabilities. Bridge replays unfiltered history outside these projections; see the [exact rule and remaining risk](docs/migration-0.9.md#claude-bridge-guard).
+- **The host shell.** An agent's shell runs as the host's user. Holds keep risky commands behind a card; they are not a sandbox. The shell gets only part of the host's environment (the paths, user, locale, terminal, `TMPDIR` and proxies, plus `GH_TOKEN` and what `shellEnv` adds), so the bot tokens, model logins, `DATABASE_URL` and keys the host holds stay in the host process; printing the environment, reading a secret file such as `.env` or `~/.ssh/*`, and `gh auth token` are held as `shell.secret-read`, which yolo mode always cards; a secret's value in a tool's output is replaced with `****`. This stops casual and accidental leaks, not a determined command run as the same user, which can read `/proc/<host pid>/environ` and any file that user can. To keep secrets from the agents, run their shells under a dedicated account without the `docker` group (membership in it equals root), or use [pi-roundtable-sandbox](packages/sandbox).
 - **Model credentials.** Every turn, whoever speaks, runs on the host's model login and is billed to it. Per-person credentials are planned for a later release.
 - **Data.** Conversations, memory, and schedules sit unencrypted in PostgreSQL and the data directory.
 

package/README.zh-TW.md

@@ -264,6 +264,7 @@ pi-roundtable 為一位擁有者執行騎士。
 - **核准。** 暫緩的呼叫只由當輪暫緩它的發言者核准，而且當下 tier 仍要足夠；在共用對話裡，擁有者也可以在卡片上或用確認訊息核准。私人對話裡別人都不能核准，高於發言者 tier 的呼叫在那裡也不會被核准。
 - **對話。** Discord 裡智慧體的頻道和群組房間是共用的：在那裡發言的每個人，都會寫進智慧體讀取的同一段對話。網頁聊天的對話屬於開啟它的人：在網頁聊天裡只有開啟者本人能讀、能發言、能回答它的提問，但擁有者可以透過擁有者主控台（[pi-roundtable-web](packages/web)）讀取，營運者也能從資料庫和資料目錄讀到。
 - **記憶隔離。** 記憶依 principal 分開，不依擁有者 tier 判斷。私人對話讀本人的，共用對話讀當輪發言者的；連結 Discord 與網頁身分後，同一個人共用一份記憶。在共用對話送給模型的請求和摘要裡，記憶工具與載入記憶的 worker 的呼叫（參數和結果成對）會對其他發言者隱藏，先前回合的 reasoning 則依 provider 清除。其他工具的參數和公開的騎士回覆仍是公開內容，即使模型在裡面重述私人記憶；這不是一般的秘密流向防護。第三方摘要器必須先使用 `privateCompaction`，才能摘要共用歷史。`claude-bridge` 的共用回合只在原始讀者紀錄（含已壓縮的回合）顯示另一位讀者的私人記憶（連只放進 prompt 的記憶與其 reasoning 也算），或某個呼叫已對當前讀者隱藏時才被拒絕。沒有私人記憶的回合不會擋其他讀者，關掉之後的記憶也繞不過先前的私人歷史；開放其他人進來只會在開機和 doctor 裡警告。SYSTEM 只在這項核心防護裡算作主要擁有者，所以它能讀取並公開重述擁有者保留的呼叫與 reasoning；0.9 之前、第一筆範圍紀錄之前未標記的內建記憶結果，仍歸屬擁有者。沙盒的全場共用 prompt 區塊必須明確使用 `memory.visibility: "shared"`，私人回合需要 worker 能力。Bridge 會在這些投影之外重播未過濾的歷史；見[確切規則與剩餘風險](docs/migration-0.9.md#claude-bridge-guard)。
+- **主機上的 shell。** 智慧體的 shell 以主機的使用者身分執行。暫緩只是把有風險的指令擋在卡片後面，不是沙箱。shell 只拿到主機環境變數的一部分（路徑、使用者、語系、終端機、`TMPDIR`、proxy，加上 `GH_TOKEN` 與 `shellEnv` 額外給的），所以主機持有的 bot token、模型登入、`DATABASE_URL` 和金鑰都留在主機行程裡；印出環境變數、讀取 `.env` 或 `~/.ssh/*` 這類秘密檔案、`gh auth token` 會以 `shell.secret-read` 暫緩，yolo 模式一律出卡片；工具輸出裡的秘密值會換成 `****`。這擋得住隨手和意外的外洩，擋不住以同一個使用者刻意執行的指令：它讀得到 `/proc/<主機 pid>/environ`，也讀得到那個使用者能讀的任何檔案。要讓智慧體碰不到秘密，請讓它們的 shell 以不在 `docker` 群組裡的專用帳號執行（加入這個群組等同 root），或改用 [pi-roundtable-sandbox](packages/sandbox)。
 - **模型憑證。** 每一輪不論誰發言，都用主機的模型登入執行、由它計費。每個人自己的憑證預計在之後的版本加入。
 - **資料。** 對話、記憶和排程以未加密的形式存在 PostgreSQL 和資料目錄裡。
 

package/docs/plugins.md

@@ -169,7 +169,7 @@ A plugin that replaces `IDENTITY` replaces this too: the declarations are the bu
 | Field | What it is |
 |---|---|
 | `logger` | The host's logger with `plugin: <your name>` on every line; each line is JSON on stdout. Its type is `Logger` (`debug`, `info`, `warn`, `error`, `fatal`, `child(fields)`), which a pino logger satisfies |
-| `env` | The host's own environment for the run: `locale`, `timeZone` (an IANA zone), `now()`, `scratchDir` when the host has one, `characterSkins`, the six skin tones the host draws its agents with ([host skins](#host-skins-the-charactersskins-option)), and `agentTools`, `"full"` or `"chat-only"` ([chat-only agents](#chat-only-agents-no-shell-file-or-workspace-tools)); read the zone from here rather than from the process, give `scratchDir` to a shell the plugin runs itself, and pass `characterSkins` to `composeSvg` when the plugin draws a character |
+| `env` | The host's own environment for the run: `locale`, `timeZone` (an IANA zone), `now()`, `scratchDir` when the host has one, `characterSkins`, the six skin tones the host draws its agents with ([host skins](#host-skins-the-charactersskins-option)), `agentTools`, `"full"` or `"chat-only"` ([chat-only agents](#chat-only-agents-no-shell-file-or-workspace-tools)), and `shellEnv` when the host sets one ([the agents' shell environment](#the-agents-shell-environment)); read the zone from here rather than from the process, give `scratchDir` to a shell the plugin runs itself, and pass `characterSkins` to `composeSvg` when the plugin draws a character |
 | `database()` | The host's one PostgreSQL connection (a Bun `SQL`), already migrated |
 | `toolTiers` | What each tool needs; ask it when a tool is used, not during setup |
 | `events` | Where the core reports turns and team changes to every plugin's handlers |
@@ -1135,7 +1135,7 @@ The mode is read when the card is asked for, so a toggle applies to the next car
 
 #### The shell rule
 
-`shellHoldRule` in `pi-roundtable/kit` judges the agents' `bash`, `write` and `edit` calls; the agent server links it, and a session without a workspace has no shell.
+`shellHoldRule` in `pi-roundtable/kit` judges the agents' `bash`, `write`, `edit` and `read` calls (a `read` only for a secret file); the agent server links it, and a session without a workspace has no shell.
 Its scratch roots are the shared workspace (`HoldContext.workspace`) and the scratch dir (`HoldContext.scratchDir`).
 The scratch dir is the config's `scratchDir`, by default `<os temp dir>/<discord.rootCommand>-scratch` (such as `/tmp/roundtable-scratch`); the agent server creates it with mode 0700 at startup and refuses one that is a symlink or another user's, and the agents' `bash` runs with `TMPDIR` pointing to it, so tools that read `TMPDIR` and GNU `mktemp` write there. macOS's BSD `mktemp` ignores `TMPDIR` for a bare `mktemp`; `mktemp -p "$TMPDIR"` works with both, and the agents' prompt tells them to use it.
 `AgentSessions.scratchDir` carries it to a runtime, and the agents' prompt tells them to write temporary files there, and to show a file with `attach_file` or a `discord_send_message` file `path` rather than reading an image or base64-encoding it.
@@ -1156,7 +1156,7 @@ The rule reports the class of **every** held command in the line, including thos
 | `shell.rm` | an `rm` outside the scratch roots, or one the line cannot resolve |
 | `shell.write` | a redirect, `tee`, `write` or `edit` outside the scratch roots |
 | `shell.service` | `systemctl` and `service` changes |
-| `shell.docker` | stopping, removing or pruning containers, images and volumes; `docker compose down` |
+| `shell.docker` | stopping, removing or pruning containers, images and volumes; `docker compose down`; `docker run`, `exec`, `create` and `cp` (also under `docker container` and `docker compose run`, `exec`, `cp`), which run commands or copy files as the daemon's root |
 | `shell.firewall` | `ufw`, `iptables`, `ip6tables`, `nft` changes |
 | `shell.packages` | `apt`, `apt-get`, `snap`, `dpkg` installs and removals |
 | `shell.push` | a plain `git push` the push policy holds |
@@ -1164,6 +1164,7 @@ The rule reports the class of **every** held command in the line, including thos
 | `shell.reset-hard` | `git reset --hard` |
 | `shell.gh` | `gh` writes |
 | `shell.crontab` | `crontab -r` |
+| `shell.secret-read` | printing the environment (`env` or `printenv` with no command to run, `export` or `export -p`, `declare -p`, `declare -x` and `typeset` with no names, `set` alone, `compgen -e`), a file reader (`cat`, `less`, `head`, `tail`, `grep`, `sed`, `awk`, `base64`, `xxd`, `cp`, `tar`, `zip`, `curl -d @`/`-F @`/`--data-binary @`/`-T`, and the like) or a `<` redirect of a secret file (`DEFAULT_SECRET_PATHS` and the rule's `secretPaths`), Pi's `read` tool on one, `gh auth token`, `gh auth status -t`/`--show-token`, `git credential`, and `git config` reading `credential.*` or listing everything |
 | `shell.unreadable` | a line the rule cannot read to the end, so it cannot rule out a destructive command: longer than 200,000 characters, nested deeper than 48 levels, a here-document or `case` it cannot place, a script built at run time (`eval`, `bash -c` of a variable or a substitution), a shell that reads a script the line does not show as a word (`echo x \| bash`, a here-document or here-string for a shell, `source <(…)`, `. /dev/stdin`, a file the line wrote earlier and then runs, anything `xargs` fills in), `env -S`, a builtin's subscript that runs a substitution (`declare 'a[$(x)]=1'`), `PS4`, `PROMPT_COMMAND` and the other variables that run a command, or a rule that failed while judging |
 
 The rule reads a line the way bash does, so text that only looks like a command stays unheld and text that runs is judged: quotes (`'…'`, `"…"`, `$'…'`, where a backslash escapes the next character), `$(…)` and backticks at any depth, `${…}`, comments (a `)` or a quote in one means nothing), here-document bodies up to their delimiter line (an unquoted body is still searched for substitutions, a quoted one is not), `case` patterns, arithmetic (`$((1<<2))` is a shift), line continuations, leading keywords (`then sudo ls`, `do rm -rf /x`), a descriptor before the command (`3>&1 sudo ls`), `eval`, `bash -c` (also `-ec`), and `find -exec`. Where it cannot tell, it holds the whole line as `shell.unreadable` instead of guessing; an error inside the rule also holds the call. So does a command whose name is a brace expansion, a pattern or a variable the line did not set to a literal (`{sudo,ls}`, `/usr/bin/su*`, `$cmd args`). The rule names programs it knows; a wrapper it does not list (`flock`, `chroot`, `ssh host`) runs its command unjudged. Known gaps: words in arithmetic (`$(( ))`, `(( ))`) are not commands, but a `$(` or backtick inside them is judged. A `bash -c` script is held whole only when the outer shell expands a substitution in it; a single-quoted script is judged like a line. `trap` scripts are judged. `alias NAME=…`, an assignment to `PROMPT_COMMAND`, `PS0`–`PS4`, `BASH_ENV`, `ENV` or `SHELLOPTS`, and `${x@P}` are held as `shell.unreadable`, because bash runs their value later. A line that evaluates arithmetic and also holds a literal `$(` or backtick (`x='a[$(cmd)]'; echo $((x))`) is held as `shell.unreadable`, so `echo '$(date)'; echo $((1 + 2))` is held too. Not followed: array subscripts and `printf -v` that evaluate a value, `source` of a file that defines aliases or traps, and a command run by a program the rule does not list.
@@ -1183,9 +1184,11 @@ ROUNDTABLE_SHELL_FUZZ=1 ROUNDTABLE_SHELL_FUZZ_BASE=<seed> bun test src/core/modu
 
 `ROUNDTABLE_SHELL_FUZZ` is the number of lines, `ROUNDTABLE_SHELL_FUZZ_BASE` the first seed (the others follow it) and `ROUNDTABLE_SHELL_FUZZ_JOBS` how many bash processes run at once (up to six by default; use `1` on a busy machine); a line is a function of its seed alone. Each line runs in a process group of its own, killed as a whole after 5 seconds or when the line ends, with a cap on the user's processes. A line the fuzz finds goes into the hand corpus, minimized, so the fix stays tested without the generator.
 
-Yolo mode never approves these unless `autonomy.yolo.allow` lists them: `YOLO_CARDED_SHELL_CLASSES` is every class above except `shell.write` and `shell.push`; that includes `shell.unreadable`.
+Yolo mode never approves these unless `autonomy.yolo.allow` lists them: `YOLO_CARDED_SHELL_CLASSES` is every class above except `shell.write` and `shell.push`; that includes `shell.unreadable` and `shell.secret-read`.
 
-`shellHoldRuleFor({ ownPushOwners?, heldPushRepos? })` (its options are the type `PushPolicy`) is the same rule with plain pushes to the owner's own repositories let through; `shellHoldRule` is `shellHoldRuleFor()`, which holds every push.
+`shellHoldRuleFor({ ownPushOwners?, heldPushRepos?, secretPaths? })` (its options are the type `ShellPolicy`, which extends `PushPolicy`) is the same rule with plain pushes to the owner's own repositories let through; `shellHoldRule` is `shellHoldRuleFor()`, which holds every push.
+`secretPaths` adds globs to `DEFAULT_SECRET_PATHS` (`/proc/*/environ`, `*.env`, `.env*` but `.env.example`, `.env.sample` and `.env.template`, `~/.ssh/**`, `~/.config/gh/**`, `.git-credentials`, `.netrc`, `.pgpass`, `~/.pi/**/auth.json`, and `auth.json` in `PI_CODING_AGENT_DIR`): a glob with no `/` matches a file name anywhere, `~/` is the home directory, `*` stays within a directory, `**` crosses them, a trailing `/**` takes the directory too, and a leading `!` lets a match run.
+The rule matches the paths a command line names; a program it does not list as a reader (`python3 -c 'open(".env")'`), a variable it cannot follow, or a glob in a directory part is not caught. See [the agents' shell environment](#the-agents-shell-environment) for what keeps secrets out of the shell in the first place.
 A push runs without a hold when all of these hold:
 
 - it does not force (`-f`, `--force*`, a `+` refspec), delete (`--delete`, `-d`, a `:ref` refspec), or push tags or more than its refs (`--tags`, `--follow-tags`, `--mirror`, `--all`, `--prune`), takes no other option than `-u`, `-q`, `-v`, `-n`, `--no-verify`, `--atomic`, `--porcelain`, `--progress` and `-o`, and names no `refs/tags/…` ref or local tag;
@@ -1203,6 +1206,27 @@ const shell = shellHoldRuleFor({
 });
 ```
 
+#### The agents' shell environment
+
+The agents' `bash` does not inherit the host process's environment.
+It gets the names in `SHELL_ENV_NAMES` (`PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `LANG`, `LANGUAGE`, `LC_*`, `TZ`, `TERM`, `TMPDIR`, the proxy variables in both cases, `SSL_CERT_FILE`, `SSL_CERT_DIR`, and Pi's `PI_*` session names), and what the host's `shellEnv` adds: `pass`, more host variables by name (a trailing `*` matches a prefix), and `set`, fixed values that win.
+Without `pass` it is `DEFAULT_SHELL_PASS`, `["GH_TOKEN"]`, so `gh` and a `git push` through `gh auth git-credential` work in the shell; `pass: []` keeps it out.
+Any other secret the host needs (a bot token, a model login, `DATABASE_URL`) stays in the host process; give a shell one only by naming it:
+
+```ts
+export default {
+	// ...
+	shellEnv: { pass: ["GH_TOKEN", "SOME_CLI_KEY"], set: { GIT_PAGER: "cat" } },
+} satisfies RoundtableConfig;
+```
+
+A host composed by hand sets the same object as `RoundtableOptions.environment.shellEnv` (type `ShellEnvConfig`); plugins read it as `context.env.shellEnv` and give it to the shells they run, as the coding plugin's workers do.
+`childEnv(source, { pass?, set? })` (`pi-roundtable/kit`) builds such an environment for any child process: a plugin that spawns a tool needing a secret passes that one secret, to that tool only.
+
+Before a tool's result enters the model's context, `maskSecrets` replaces each value of a host variable whose name `SECRET_NAME` matches (`TOKEN`, `SECRET`, `KEY`, `PASS`, `PASSWORD`, `DATABASE_URL`, `JWT`, `CREDENTIAL`, any case) and that is at least 8 characters with `****`; every session runs `secretMaskExtension()` after the other extensions' `tool_result` handlers.
+
+None of this is a sandbox. The shell runs as the host's user, so a determined command reads what that user can: `/proc/<host pid>/environ`, a file the rule does not know, a token in a program's memory. The whitelist, the `shell.secret-read` hold and the mask stop casual and accidental leaks. To keep secrets from the agents, run their shells under a dedicated account without the `docker` group (membership in it equals root), or use the sandbox package.
+
 ### `PROMPTS`: prompt texts the owner edits
 
 A prompt that comes from a file or the configuration can be made editable by the owner without touching the file.
@@ -4519,6 +4543,8 @@ Import from the entries listed below; source area files are internal.
 | `HoldRule` | `pi-roundtable` | type |
 | `HostEnv` | `pi-roundtable` | type |
 | `HostEnvironment` | `pi-roundtable` | type |
+| `ShellEnv` | `pi-roundtable` | type |
+| `ShellEnvConfig` | `pi-roundtable` | type |
 | `HostStoppingError` | `pi-roundtable` | value |
 | `HttpRoute` | `pi-roundtable` | type |
 | `IDENTITY` | `pi-roundtable` | value |
@@ -4857,6 +4883,11 @@ Import from the entries listed below; source area files are internal.
 | `PushPolicy` | `pi-roundtable/kit` | type |
 | `SCHEDULE_TOOLS` | `pi-roundtable/kit` | value |
 | `SHELL_TOOLS` | `pi-roundtable/kit` | value |
+| `SHELL_ENV_NAMES` | `pi-roundtable/kit` | value |
+| `DEFAULT_SHELL_PASS` | `pi-roundtable/kit` | value |
+| `DEFAULT_SECRET_PATHS` | `pi-roundtable/kit` | value |
+| `SECRET_NAME` | `pi-roundtable/kit` | value |
+| `ShellPolicy` | `pi-roundtable/kit` | type |
 | `SKILL_LIST_TOOL` | `pi-roundtable/kit` | value |
 | `createCodexImages` | `pi-roundtable/kit` | value |
 | `drawCodexImage` | `pi-roundtable/kit` | value |
@@ -4955,6 +4986,10 @@ Import from the entries listed below; source area files are internal.
 | `settleTurn` | `pi-roundtable/kit` | value |
 | `shellHoldRule` | `pi-roundtable/kit` | value |
 | `shellHoldRuleFor` | `pi-roundtable/kit` | value |
+| `childEnv` | `pi-roundtable/kit` | value |
+| `shellChildEnv` | `pi-roundtable/kit` | value |
+| `maskSecrets` | `pi-roundtable/kit` | value |
+| `secretMaskExtension` | `pi-roundtable/kit` | value |
 | `skillListExtension` | `pi-roundtable/kit` | value |
 | `splitReply` | `pi-roundtable/kit` | value |
 | `stringList` | `pi-roundtable/kit` | value |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.32.1",
+	"version": "0.33.0",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",

package/src/core/config/config-schema.ts

@@ -141,6 +141,9 @@ export const configSchema = shape({
 	avatar: optional(text),
 	workDir: optional(text),
 	scratchDir: optional(text),
+	shellEnv: optional(
+		shape({ pass: optional(list(text)), set: optional(record(text)) }),
+	),
 	skills: optional(skillsField),
 	memory: optional(bool),
 	ops: optional(shape({ agent: optional(text), conversation: optional(text) })),

package/src/core/config/config.ts

@@ -18,6 +18,7 @@ import {
 import type { PerPrincipalLimits } from "../modules/background/personal-target.ts";
 import type { AgentTools, RoundtablePlugin } from "../plugin.ts";
 import { PRIMARY_CHARS } from "../runtime/interim-text.ts";
+import type { ShellEnvConfig } from "../shared/child-env.ts";
 import type { Tier, TierMembers } from "../speakers.ts";
 import { type AccessConfig, accessOf } from "./access.ts";
 import {
@@ -77,7 +78,7 @@ export interface BackgroundConfig {
 }
 
 /** What `roundtable.config.ts` gives `defineRoundtable`. */
-export interface RoundtableConfig extends LimitsConfig {
+export interface RoundtableConfig extends LimitsConfig, ShellEnvConfig {
 	/** The assistant's display name; default "Roundtable". */
 	name?: string;
 	/**

package/src/core/define-roundtable.ts

@@ -326,6 +326,7 @@ export async function defineRoundtable(
 				rootCommand: config.slug,
 				agentDir: config.agentDir,
 				scratchDir: config.scratchDir,
+				...(input.shellEnv ? { shellEnv: input.shellEnv } : {}),
 				characterSkins: config.characters.skins,
 				agentTools: config.agentTools,
 			},

package/src/core/host-registration.ts

@@ -44,6 +44,7 @@ import { PeerBots } from "./routing/peer-bots.ts";
 import { surfacePort } from "./routing/surface-port.ts";
 import { refuseHostAccess } from "./runtime/chat-only.ts";
 import { CONVERSATIONS, IDENTITY, RUNTIME } from "./services.ts";
+import { frozenShellEnv } from "./shared/child-env.ts";
 import { setTimeZone } from "./time.ts";
 import { type ToolTierTable, toolTiers } from "./tool-tiers.ts";
 
@@ -133,6 +134,7 @@ export class Linkage {
 			scratchDir,
 			characterSkins,
 			agentTools = "full",
+			shellEnv,
 		} = this.#options.environment ?? {};
 		// Checked before anything is applied, so a bad set stops the start with the process untouched.
 		const skins = characterSkinsOf(characterSkins);
@@ -147,6 +149,7 @@ export class Linkage {
 			...(scratchDir !== undefined ? { scratchDir } : {}),
 			characterSkins: skins,
 			agentTools,
+			...(shellEnv ? { shellEnv: frozenShellEnv(shellEnv) } : {}),
 		};
 	}
 

package/src/core/host.ts

@@ -15,6 +15,7 @@ import type { AgentTools, RoundtablePlugin, Service } from "./plugin.ts";
 import type { PeerBotsConfig } from "./routing/peer-bots.ts";
 import { RUNTIME } from "./services.ts";
 import type { ChannelKey } from "./sessions.ts";
+import type { ShellEnvConfig } from "./shared/child-env.ts";
 import type { ToolTierTable } from "./tool-tiers.ts";
 
 /**
@@ -22,7 +23,7 @@ import type { ToolTierTable } from "./tool-tiers.ts";
  * directory its packages read. `run()` applies them to the process when the host starts, and
  * plugins read the locale and zone from `PluginContext.env`.
  */
-export interface HostEnvironment {
+export interface HostEnvironment extends ShellEnvConfig {
 	/** The language of the Discord text; default en. */
 	locale?: Locale;
 	/** An IANA time zone; default UTC. */

package/src/core/modules/host-shell/shell-policy.ts

@@ -1,6 +1,5 @@
 import { basename } from "node:path";
 import type { HoldContext, HoldRule } from "../../holds.ts";
-import type { PushPolicy } from "./git-push.ts";
 import { COMMAND_PREFIX_WORDS, EXPANDED, lexShell } from "./shell-lexer.ts";
 import {
 	bindingCounts,
@@ -22,6 +21,14 @@ import {
 	shellScript,
 	teeOperands,
 } from "./shell-scripts.ts";
+import {
+	ENV_PRINTED,
+	type ShellPolicy,
+	secretFileRead,
+	secretPrinted,
+	secretReadHeld,
+	secretRedirect,
+} from "./shell-secrets.ts";
 import {
 	ASSIGNMENT_WORD,
 	program,
@@ -32,6 +39,7 @@ import {
 export type { PushPolicy } from "./git-push.ts";
 export { simpleCommands } from "./shell-lexer.ts";
 export { YOLO_CARDED_SHELL_CLASSES } from "./shell-programs.ts";
+export { DEFAULT_SECRET_PATHS, type ShellPolicy } from "./shell-secrets.ts";
 
 const MAX_SHOWN_COMMAND = 120;
 
@@ -173,7 +181,7 @@ const ALWAYS_HELD_CLASS: ReadonlyMap<string, ShellClass> = new Map([
 function heldReasons(
 	words: string[],
 	state: LineState,
-	policy: PushPolicy,
+	policy: ShellPolicy,
 ): Held[] {
 	const found: Held[] = [];
 	for (let i = 0; i < words.length; i++) {
@@ -186,6 +194,9 @@ function heldReasons(
 					class: deviceTarget(target, state) ? "shell.disk" : "shell.write",
 				});
 		}
+		const secret =
+			op === "<" ? secretRedirect(words[i + 1], state, policy) : undefined;
+		if (secret) found.push(secret);
 	}
 	return [...found, ...programHeld(words, state, policy)];
 }
@@ -194,7 +205,7 @@ function heldReasons(
 function programHeld(
 	words: string[],
 	state: LineState,
-	policy: PushPolicy,
+	policy: ShellPolicy,
 ): Held[] {
 	const prefix: string[] = [];
 	// A redirection is no part of the command: not its operator nor its target.
@@ -207,11 +218,12 @@ function programHeld(
 	if (setsSelfRunningVariable(own) || prefix.includes("env -S"))
 		return [DYNAMIC_SCRIPT];
 	const [word, ...args] = argv;
-	// `xargs env` runs what its input says.
-	if (!word)
-		return prefix.includes("xargs") && prefix.at(-1) !== "xargs"
-			? [DYNAMIC_SCRIPT]
-			: [];
+	// `xargs env` runs what its input says, and an `env` with no command prints the environment.
+	if (!word) {
+		if (prefix.includes("xargs") && prefix.at(-1) !== "xargs")
+			return [DYNAMIC_SCRIPT];
+		return prefix.includes("env") ? [ENV_PRINTED] : [];
+	}
 	const head = commandName(word, state);
 	if (head === undefined) {
 		// A variable the line binds may be empty when bash gets there, so the name is unknown; what
@@ -277,6 +289,9 @@ function programHeld(
 		const exec = findExec(args);
 		if (exec) return programHeld(exec, state, policy);
 	}
+	const secret =
+		secretPrinted(name, args) ?? secretFileRead(name, args, state, policy);
+	if (secret) return [secret];
 	const held = verbHeld(name, args, prefix, state, policy);
 	return held ? [held] : [];
 }
@@ -307,7 +322,7 @@ const UNREADABLE: Held = {
 function scriptHeld(
 	script: string,
 	state: LineState,
-	policy: PushPolicy,
+	policy: ShellPolicy,
 ): Held[] {
 	if (script.includes(EXPANDED)) return [DYNAMIC_SCRIPT];
 	if (script.trimStart().startsWith("$")) {
@@ -328,7 +343,7 @@ const DYNAMIC_SCRIPT: Held = {
 function commandHeld(
 	command: string,
 	outer: LineState,
-	policy: PushPolicy,
+	policy: ShellPolicy,
 ): Held[] {
 	const state: LineState = {
 		...lineState(command, outer.workspace, undefined),
@@ -368,13 +383,13 @@ function commandHeld(
 /**
  * Pi's shell and file tools: a bash command that is destructive or reaches outside the scratch
  * roots (the shared workspace and the scratch dir), and a write or edit outside them, wait for the
- * owner. Reading always runs.
+ * owner. Reading runs, but for a file that holds a secret (`shell.secret-read`).
  */
 export function shellActionNeedingConfirmation(
 	toolName: string,
 	input: Record<string, unknown>,
 	context: HoldContext & { workspace: string },
-	policy: PushPolicy = {},
+	policy: ShellPolicy = {},
 ): string | undefined {
 	return shellHold(toolName, input, context, policy)?.action;
 }
@@ -387,7 +402,7 @@ function shellHold(
 	toolName: string,
 	input: Record<string, unknown>,
 	context: HoldContext & { workspace: string },
-	policy: PushPolicy,
+	policy: ShellPolicy,
 ): { action: string; classes: ShellClass[] } | undefined {
 	try {
 		return judge(toolName, input, context, policy);
@@ -412,7 +427,7 @@ function judge(
 	toolName: string,
 	input: Record<string, unknown>,
 	context: HoldContext & { workspace: string },
-	policy: PushPolicy,
+	policy: ShellPolicy,
 ): { action: string; classes: ShellClass[] } | undefined {
 	const state = lineState(
 		typeof input.command === "string" ? input.command : "",
@@ -439,17 +454,18 @@ function judge(
 					classes: ["shell.write"],
 				};
 	}
-	return undefined;
+	return toolName === "read" ? secretReadHeld(input, state, policy) : undefined;
 }
 
 /**
  * The shell rule with a push policy: a plain push to a repository of `ownPushOwners`, other than
- * `heldPushRepos`, runs without a hold. Shell calls of a session without a workspace have no shell.
+ * `heldPushRepos`, runs without a hold; `secretPaths` adds files whose reading is held. Shell calls of a session without a workspace have no shell.
  */
-export function shellHoldRuleFor(policy: PushPolicy = {}): Readonly<HoldRule> {
-	const frozen: PushPolicy = {
+export function shellHoldRuleFor(policy: ShellPolicy = {}): Readonly<HoldRule> {
+	const frozen: ShellPolicy = {
 		ownPushOwners: [...(policy.ownPushOwners ?? [])],
 		heldPushRepos: [...(policy.heldPushRepos ?? [])],
+		...(policy.secretPaths ? { secretPaths: [...policy.secretPaths] } : {}),
 	};
 	return Object.freeze<HoldRule>({
 		name: "shell",

package/src/core/modules/host-shell/shell-programs.ts

@@ -1,13 +1,19 @@
 import { assistantName } from "../../i18n/index.ts";
-import { ownPush, type PushPolicy } from "./git-push.ts";
+import { ownPush } from "./git-push.ts";
 import { deviceTarget, type LineState, writable } from "./shell-paths.ts";
+import {
+	ghTokenPrinted,
+	gitCredentialRead,
+	type ShellPolicy,
+} from "./shell-secrets.ts";
 
 /**
  * The hold classes of the shell rule, as `shell.<class>` ids that `HoldRule.holdClasses` lists for
  * every command a call holds. Yolo mode approves `shell.write` (a write outside the scratch roots)
  * and `shell.push` (a plain `git push` the push policy holds), and cards the rest unless
  * `autonomy.yolo.allow` lists them. `shell.unreadable` is a line the rule could not read to the
- * end, so it holds what it cannot tell apart from a destructive command.
+ * end, so it holds what it cannot tell apart from a destructive command. `shell.secret-read` prints
+ * the environment or reads a file that holds a secret.
  */
 export const SHELL_CLASSES = Object.freeze([
 	"shell.privilege",
@@ -25,6 +31,7 @@ export const SHELL_CLASSES = Object.freeze([
 	"shell.reset-hard",
 	"shell.gh",
 	"shell.crontab",
+	"shell.secret-read",
 	"shell.unreadable",
 ] as const);
 
@@ -59,7 +66,19 @@ const SYSTEMD_VERBS = new Set([
 	"kill",
 	"isolate",
 ]);
-const DOCKER_VERBS = new Set(["stop", "kill", "restart", "rm", "rmi", "prune"]);
+/** Docker verbs that stop or remove, and those that run a command or copy files as the daemon's root. */
+const DOCKER_VERBS = new Set([
+	"stop",
+	"kill",
+	"restart",
+	"rm",
+	"rmi",
+	"prune",
+	"run",
+	"exec",
+	"create",
+	"cp",
+]);
 const DOCKER_OBJECTS = new Set([
 	"container",
 	"image",
@@ -68,7 +87,16 @@ const DOCKER_OBJECTS = new Set([
 	"system",
 	"builder",
 ]);
-const COMPOSE_VERBS = new Set(["down", "stop", "kill", "restart", "rm"]);
+const COMPOSE_VERBS = new Set([
+	"down",
+	"stop",
+	"kill",
+	"restart",
+	"rm",
+	"run",
+	"exec",
+	"cp",
+]);
 const PACKAGE_VERBS = new Set([
 	"install",
 	"reinstall",
@@ -98,7 +126,7 @@ export function verbHeld(
 	args: string[],
 	prefix: string[],
 	state: LineState,
-	policy: PushPolicy,
+	policy: ShellPolicy,
 ): Held | undefined {
 	const verbs = args.filter((a) => !a.startsWith("-"));
 	const because = (
@@ -177,6 +205,8 @@ export function verbHeld(
 		case "git":
 			return gitHeld(args, prefix, state, policy);
 		case "gh": {
+			const token = ghTokenPrinted(args);
+			if (token) return token;
 			const reason = ghHeld(args);
 			return reason ? { reason, class: "shell.gh" } : undefined;
 		}
@@ -203,9 +233,11 @@ function gitHeld(
 	args: string[],
 	prefix: string[],
 	state: LineState,
-	policy: PushPolicy,
+	policy: ShellPolicy,
 ): Held | undefined {
 	const [globals, [verb, ...rest]] = gitCommand(args);
+	const credential = gitCredentialRead(verb, rest);
+	if (credential) return credential;
 	if (verb === "push") {
 		const plain = !prefix.some((w) => w.startsWith("GIT_"));
 		if (plain && ownPush(globals, rest, state, policy)) return undefined;

package/src/core/modules/host-shell/shell-secrets.ts

@@ -0,0 +1,306 @@
+import { homedir } from "node:os";
+import { basename } from "node:path";
+import type { PushPolicy } from "./git-push.ts";
+import { type LineState, resolvePath } from "./shell-paths.ts";
+import type { Held, ShellClass } from "./shell-programs.ts";
+
+/** What the shell rule lets run: its push policy, and the files that hold secrets. */
+export interface ShellPolicy extends PushPolicy {
+	/**
+	 * More files whose reading is held as `shell.secret-read`, on top of `DEFAULT_SECRET_PATHS`, as
+	 * the same globs: a pattern with no `/` matches a file name anywhere, `~/` is the home
+	 * directory, `**` crosses directories, and a leading `!` lets a match run.
+	 */
+	secretPaths?: readonly string[];
+}
+
+/**
+ * The files whose reading is held as `shell.secret-read`: environment files, ssh and gh logins, git,
+ * curl and PostgreSQL credentials, Pi's model logins, and a process's environment. Example env
+ * files (`.env.example`) run.
+ */
+export const DEFAULT_SECRET_PATHS: readonly string[] = Object.freeze([
+	"/proc/*/environ",
+	"/proc/self/environ",
+	"*.env",
+	".env*",
+	"!.env.example",
+	"!.env.sample",
+	"!.env.template",
+	"~/.ssh/**",
+	"~/.config/gh/**",
+	".git-credentials",
+	".netrc",
+	".pgpass",
+	"~/.pi/**/auth.json",
+]);
+
+const SECRET_READ: ShellClass = "shell.secret-read";
+
+/** A glob as a regular expression over a whole path, or over a file name when it has no `/`. */
+function globPattern(glob: string): { name: boolean; pattern: RegExp } {
+	const name = !glob.includes("/");
+	const path = glob.startsWith("~/")
+		? `${homedir()}${glob.slice(1)}`
+		: name || glob.startsWith("/")
+			? glob
+			: `**/${glob}`;
+	let source = "";
+	for (let i = 0; i < path.length; i++) {
+		const ch = path[i] as string;
+		// A trailing `/**` takes the directory itself too, as `tar ~/.ssh` reads all of it.
+		if (i === path.length - 3 && path.endsWith("/**")) {
+			source += "(?:/.*)?";
+			break;
+		}
+		if (path.startsWith("**/", i)) {
+			source += "(?:.*/)?";
+			i += 2;
+		} else if (path.startsWith("**", i)) {
+			source += ".*";
+			i += 1;
+		} else if (ch === "*") source += "[^/]*";
+		else if (ch === "?") source += "[^/]";
+		else source += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+	}
+	return { name, pattern: new RegExp(`^${source}$`) };
+}
+
+interface SecretGlobs {
+	held: { name: boolean; pattern: RegExp }[];
+	allowed: { name: boolean; pattern: RegExp }[];
+}
+
+const compiled = new WeakMap<readonly string[], SecretGlobs>();
+
+function secretGlobs(extra: readonly string[] | undefined): SecretGlobs {
+	const key = extra ?? DEFAULT_SECRET_PATHS;
+	const known = compiled.get(key);
+	if (known) return known;
+	const agentDir = process.env.PI_CODING_AGENT_DIR;
+	const globs = [
+		...DEFAULT_SECRET_PATHS,
+		...(agentDir ? [`${agentDir.replace(/\/+$/, "")}/auth.json`] : []),
+		...(extra ?? []),
+	];
+	const made: SecretGlobs = {
+		held: globs.filter((g) => !g.startsWith("!")).map(globPattern),
+		allowed: globs
+			.filter((g) => g.startsWith("!"))
+			.map((g) => globPattern(g.slice(1))),
+	};
+	compiled.set(key, made);
+	return made;
+}
+
+/** Whether a path matches one of the globs. */
+function matchesAny(
+	path: string,
+	globs: readonly { name: boolean; pattern: RegExp }[],
+): boolean {
+	return globs.some(({ name, pattern }) =>
+		pattern.test(name ? basename(path) : path),
+	);
+}
+
+/** The paths an argument may name: itself, the value of `--opt=value`, and a curl `@file` or `field=@file`. */
+function candidates(arg: string): string[] {
+	const found = [arg];
+	const eq = arg.indexOf("=");
+	if (arg.startsWith("-") && eq !== -1) found.push(arg.slice(eq + 1));
+	const at = arg.indexOf("@");
+	if (at !== -1 && (at === 0 || arg[at - 1] === "=" || arg.startsWith("-")))
+		found.push(arg.slice(at + 1).replace(/;.*$/, ""));
+	return found.filter((path) => path !== "");
+}
+
+/** The secret file an argument names, or undefined. */
+export function secretFile(
+	arg: string,
+	state: LineState,
+	policy: ShellPolicy,
+): string | undefined {
+	const globs = secretGlobs(policy.secretPaths);
+	for (const word of candidates(arg)) {
+		const path = resolvePath(word, state);
+		if (path === undefined) continue;
+		if (matchesAny(path, globs.held) && !matchesAny(path, globs.allowed))
+			return word;
+	}
+	return undefined;
+}
+
+/** Why a redirect from `source` (`< file`) is held: it reads a secret file. */
+export function secretRedirect(
+	source: string | undefined,
+	state: LineState,
+	policy: ShellPolicy,
+): Held | undefined {
+	const file =
+		source === undefined ? undefined : secretFile(source, state, policy);
+	return file === undefined
+		? undefined
+		: { reason: `reads the secret file ${file}`, class: SECRET_READ };
+}
+
+/** What a call of Pi's read tool is held for: a file that holds a secret. */
+export function secretReadHeld(
+	input: Record<string, unknown>,
+	state: LineState,
+	policy: ShellPolicy,
+): { action: string; classes: ShellClass[] } | undefined {
+	const path = typeof input.path === "string" ? input.path : "";
+	return secretFile(path.replace(/^@/, ""), state, policy) === undefined
+		? undefined
+		: {
+				action: `read the secret file ${path} on the host`,
+				classes: [SECRET_READ],
+			};
+}
+
+/** Why an `env` with no command is held: it prints the environment. */
+export const ENV_PRINTED: Held = Object.freeze({
+	reason: "prints the environment",
+	class: SECRET_READ,
+});
+
+/** Programs that read the files they are given, or send them on: their path arguments are checked. */
+const READERS = new Set([
+	"cat",
+	"tac",
+	"less",
+	"more",
+	"most",
+	"bat",
+	"batcat",
+	"head",
+	"tail",
+	"nl",
+	"grep",
+	"egrep",
+	"fgrep",
+	"rg",
+	"ag",
+	"sed",
+	"awk",
+	"gawk",
+	"mawk",
+	"cut",
+	"sort",
+	"uniq",
+	"paste",
+	"diff",
+	"cmp",
+	"od",
+	"xxd",
+	"hexdump",
+	"strings",
+	"base64",
+	"base32",
+	"cp",
+	"mv",
+	"rsync",
+	"scp",
+	"tar",
+	"zip",
+	"gzip",
+	"bzip2",
+	"xz",
+	"zstd",
+	"7z",
+	"curl",
+	"wget",
+	"jq",
+	"yq",
+	"source",
+	".",
+	"vi",
+	"vim",
+	"view",
+	"nano",
+	"openssl",
+	"gpg",
+	"split",
+]);
+
+/** Why a read of a secret file by `name` with `args` is held, or undefined. */
+export function secretFileRead(
+	name: string,
+	args: readonly string[],
+	state: LineState,
+	policy: ShellPolicy,
+): Held | undefined {
+	if (!READERS.has(name)) return undefined;
+	for (const arg of args) {
+		const file = secretFile(arg, state, policy);
+		if (file !== undefined)
+			return { reason: `reads the secret file ${file}`, class: SECRET_READ };
+	}
+	return undefined;
+}
+
+/** Why a command that prints the environment, or a stored credential, is held; undefined when it does not. */
+export function secretPrinted(
+	name: string,
+	args: readonly string[],
+): Held | undefined {
+	const flags = args.filter((a) => a.startsWith("-"));
+	const operands = args.filter((a) => !a.startsWith("-"));
+	const prints = (reason: string): Held => ({ reason, class: SECRET_READ });
+	switch (name) {
+		case "printenv":
+			return prints("prints the environment");
+		case "export":
+			return operands.length === 0 || flags.includes("-p")
+				? prints("prints the environment")
+				: undefined;
+		case "declare":
+		case "typeset":
+			return flags.some((f) => /^-[A-Za-z]*p/.test(f)) ||
+				(operands.length === 0 && !flags.some((f) => /^-[A-Za-z]*[fF]/.test(f)))
+				? prints("prints the variables")
+				: undefined;
+		case "set":
+			return args.length === 0 ? prints("prints the variables") : undefined;
+		case "compgen":
+			return args.some(
+				(a, i) =>
+					a === "-e" ||
+					a === "-v" ||
+					(args[i - 1] === "-A" && (a === "variable" || a === "export")),
+			)
+				? prints("lists the environment")
+				: undefined;
+		default:
+			return undefined;
+	}
+}
+
+/** Why a `gh` command that prints its token is held. */
+export function ghTokenPrinted(args: readonly string[]): Held | undefined {
+	const [group, verb] = args.filter((a) => !a.startsWith("-"));
+	if (group !== "auth") return undefined;
+	if (verb === "token")
+		return { reason: "prints the GitHub token", class: SECRET_READ };
+	if (
+		verb === "status" &&
+		args.some((a) => a === "--show-token" || /^-[A-Za-z]*t/.test(a))
+	)
+		return { reason: "prints the GitHub token", class: SECRET_READ };
+	return undefined;
+}
+
+/** Why a git subcommand that reads stored credentials is held: `git credential`, a credential helper, `git config` of `credential.*`. */
+export function gitCredentialRead(
+	verb: string | undefined,
+	rest: readonly string[],
+): Held | undefined {
+	if (verb?.startsWith("credential"))
+		return { reason: "reads git credentials", class: SECRET_READ };
+	if (
+		verb === "config" &&
+		rest.some((a) => /credential/i.test(a) || a === "-l" || a === "--list")
+	)
+		return { reason: "reads git credentials", class: SECRET_READ };
+	return undefined;
+}

package/src/core/plugin.ts

@@ -35,6 +35,7 @@ import type {
 	SessionTool,
 	ToolSelection,
 } from "./sessions.ts";
+import type { ShellEnv } from "./shared/child-env.ts";
 import type { Speaker, Tier } from "./speakers.ts";
 import type { ToolTiers } from "./tool-tiers.ts";
 
@@ -323,6 +324,8 @@ export interface HostEnv {
 	 * plugin that declares `hostAccess`.
 	 */
 	readonly agentTools: AgentTools;
+	/** What the agents' shell gets of the host's environment besides `SHELL_ENV_NAMES`; plugins that run shells of their own (coding workers) give them the same. */
+	readonly shellEnv?: ShellEnv;
 }
 
 /** What the host gives every plugin. */

package/src/core/runtime/runtime-plugin.ts

@@ -200,6 +200,7 @@ export function runtimePlugin(
 						...turnPolicy(options),
 						sessions: context.sessions,
 						agentTools: context.env.agentTools,
+						...(context.env.shellEnv ? { shellEnv: context.env.shellEnv } : {}),
 						agentDir: options.agentDir,
 						modelRuntime: options.modelRuntime,
 						dataDir: options.dataDir,

package/src/core/runtime/runtime-types.ts

@@ -24,6 +24,8 @@ import {
 	type SessionPlan,
 	type SessionTool,
 } from "../sessions.ts";
+import type { ShellEnv } from "../shared/child-env.ts";
+import { secretMaskExtension } from "../shared/secret-mask.ts";
 import type { ToolTiers } from "../tool-tiers.ts";
 import type { MemoryDraws } from "./extensions/private-memory.ts";
 import type { PendingConfirmationStore } from "./pending-confirmation-store.ts";
@@ -77,6 +79,8 @@ export interface PiAgentRuntimeOptions {
 	agents?: AgentSessions;
 	/** "chat-only": no turn carries the shell and file tools, and agent sessions have no workspace; default "full". */
 	agentTools?: AgentTools;
+	/** What the sessions' shell gets of the host's environment besides `SHELL_ENV_NAMES`; see `HostEnvironment.shellEnv`. */
+	shellEnv?: ShellEnv;
 	/**
 	 * The prompts of a channel for an interactive turn's scope, made from its speaker and its
 	 * conversation's visibility; undefined for a channel that cannot show them. Without it every
@@ -171,7 +175,7 @@ export interface CoreExtensions {
  * A session's extensions in load order: the tools phase, the core's attachment, gate, ask-user,
  * and compact guard, the compactor, the MCP phase, the memory projection, so each request is
  * projected after every other extension changed it, the surface's formatting guidance, so it follows
- * the persona and everything appended before it, and active-tools last, so its
+ * the persona and everything appended before it, the secret mask, and active-tools last, so its
  * before_agent_start handler runs after every other extension's.
  */
 export function sessionExtensions(
@@ -202,6 +206,8 @@ export function sessionExtensions(
 		...contributed(plan.mcp),
 		{ name: "private-memory", factory: core.privateMemory },
 		{ name: "surface-formatting", factory: core.surfaceFormatting },
+		// After every other tool_result handler, so what they add is masked too.
+		{ name: "secret-mask", factory: secretMaskExtension() },
 		{ name: "active-tools", factory: core.activeTools },
 	];
 }

package/src/core/runtime/session-factory.ts

@@ -462,10 +462,10 @@ export class SessionFactory {
 		const { session } = await createAgentSession({
 			cwd,
 			agentDir,
-			// Pi's bash under its own name, run with TMPDIR at the agents' scratch dir.
-			...(agents?.scratchDir && !this.chatOnly
-				? { customTools: [scratchBash(cwd, agents.scratchDir)] }
-				: {}),
+			// Pi's bash under its own name, with the shell's environment and TMPDIR at the agents' scratch dir.
+			customTools: this.chatOnly
+				? []
+				: [scratchBash(cwd, agents?.scratchDir, this.#options.shellEnv)],
 			thinkingLevel: thinking,
 			modelRuntime: this.#modelRuntime,
 			resourceLoader,

package/src/core/runtime/session-helpers.ts

@@ -3,6 +3,7 @@ import {
 	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import type { ImageDrawer } from "../contract/providers.ts";
+import { type ShellEnv, shellChildEnv } from "../shared/child-env.ts";
 import { generateImageExtension } from "../shared/generate-image-tool.ts";
 import type { WorkspaceRoots } from "../shared/workspace-files.ts";
 import type { CoreExtensions } from "./runtime-types.ts";
@@ -15,13 +16,24 @@ export function imageTools(
 	return images ? { generateImage: generateImageExtension(images, roots) } : {};
 }
 
-/** Pi's bash tool with TMPDIR set to `scratchDir`, so tools that read TMPDIR and GNU `mktemp` write there (BSD `mktemp` needs `-p "$TMPDIR"`). */
-export function scratchBash(cwd: string, scratchDir: string): ToolDefinition {
+/**
+ * Pi's bash tool with the host's environment cut to `SHELL_ENV_NAMES` and `shellEnv` (see `shellChildEnv`), and TMPDIR
+ * set to `scratchDir` when there is one, so tools that read TMPDIR and GNU `mktemp` write there
+ * (BSD `mktemp` needs `-p "$TMPDIR"`).
+ */
+export function scratchBash(
+	cwd: string,
+	scratchDir: string | undefined,
+	shellEnv: ShellEnv = {},
+): ToolDefinition {
 	// SAFETY: Pi's bash definition is a ToolDefinition typed by its own parameter schema, which the session takes as any custom tool.
 	return createBashToolDefinition(cwd, {
 		spawnHook: (context) => ({
 			...context,
-			env: { ...context.env, TMPDIR: scratchDir },
+			env: {
+				...shellChildEnv(context.env, shellEnv),
+				...(scratchDir === undefined ? {} : { TMPDIR: scratchDir }),
+			},
 		}),
 	}) as unknown as ToolDefinition;
 }

package/src/core/shared/child-env.ts

@@ -0,0 +1,115 @@
+import { ConfigError } from "../domain/errors.ts";
+
+/**
+ * What an agent's shell and the host's other child processes get of the host's environment: the
+ * names on a whitelist, and nothing else. Secrets the host needs stay in the host process; a child
+ * that needs one gets it from code, through `pass` or `set`, for that child only.
+ */
+
+/** Extra names and fixed values for the agents' shells, on top of `SHELL_ENV_NAMES`. */
+export interface ShellEnv {
+	/** Host variables the shell gets too, by exact name (`LC_*`-style trailing `*` matches a prefix). */
+	pass?: readonly string[];
+	/** Fixed values the shell gets, set after the passed names, so they win. */
+	set?: Readonly<Record<string, string>>;
+}
+
+/** The `shellEnv` option of the host's environment and of `roundtable.config.ts`. */
+export interface ShellEnvConfig {
+	/**
+	 * What the agents' shell gets of the host's environment besides `SHELL_ENV_NAMES` (the user,
+	 * locale, terminal, paths and proxies): host variables to `pass` by name and fixed values to
+	 * `set`. Plugins read it as `env.shellEnv` for shells of their own. Default: `pass` is
+	 * `DEFAULT_SHELL_PASS` (GH_TOKEN, so gh and git in the shell keep working); give `pass` to
+	 * replace it, `pass: []` for no host secret in the shell at all.
+	 */
+	shellEnv?: ShellEnv;
+}
+
+/**
+ * The host variables every child gets: the user, the locale and the terminal, the paths, proxies
+ * and certificates; `LC_*` is every locale category. Pi's own `PI_*` session names (the model and
+ * session the shell runs in) carry no secret, so the shell keeps them.
+ */
+export const SHELL_ENV_NAMES: readonly string[] = Object.freeze([
+	"PATH",
+	"HOME",
+	"USER",
+	"LOGNAME",
+	"SHELL",
+	"LANG",
+	"LANGUAGE",
+	"LC_*",
+	"TZ",
+	"TERM",
+	"TMPDIR",
+	"HTTP_PROXY",
+	"HTTPS_PROXY",
+	"NO_PROXY",
+	"http_proxy",
+	"https_proxy",
+	"no_proxy",
+	"SSL_CERT_FILE",
+	"SSL_CERT_DIR",
+	"PI_SESSION_ID",
+	"PI_SESSION_FILE",
+	"PI_PROVIDER",
+	"PI_MODEL",
+	"PI_REASONING_LEVEL",
+]);
+
+function matches(name: string, pattern: string): boolean {
+	return pattern.endsWith("*")
+		? name.startsWith(pattern.slice(0, -1))
+		: name === pattern;
+}
+
+/**
+ * The environment of a child process: the variables of `source` that `SHELL_ENV_NAMES` or `pass`
+ * names, then `set`.
+ */
+export function childEnv(
+	source: Readonly<Record<string, string | undefined>>,
+	options: ShellEnv = {},
+): Record<string, string> {
+	const names = [...SHELL_ENV_NAMES, ...(options.pass ?? [])];
+	const env: Record<string, string> = {};
+	for (const [name, value] of Object.entries(source))
+		if (value !== undefined && names.some((pattern) => matches(name, pattern)))
+			env[name] = value;
+	return { ...env, ...options.set };
+}
+
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** A copy of `shellEnv` that later changes to the caller's object do not reach; a name that is not a variable name stops the start. */
+export function frozenShellEnv(shellEnv: ShellEnv): Readonly<ShellEnv> {
+	for (const name of shellEnv.pass ?? [])
+		if (!ENV_NAME.test(name.endsWith("*") ? name.slice(0, -1) : name))
+			throw new ConfigError(`shellEnv.pass: "${name}" is not a variable name`);
+	for (const [name, value] of Object.entries(shellEnv.set ?? {}))
+		if (!ENV_NAME.test(name) || typeof value !== "string")
+			throw new ConfigError(
+				`shellEnv.set: "${name}" needs a variable name and a string value`,
+			);
+	return Object.freeze({
+		...(shellEnv.pass ? { pass: Object.freeze([...shellEnv.pass]) } : {}),
+		...(shellEnv.set ? { set: Object.freeze({ ...shellEnv.set }) } : {}),
+	});
+}
+
+/** The host variables an agent's shell gets beyond `SHELL_ENV_NAMES` when `shellEnv.pass` is not given. */
+export const DEFAULT_SHELL_PASS: readonly string[] = Object.freeze([
+	"GH_TOKEN",
+]);
+
+/** The environment of an agent's shell: `childEnv` with `shellEnv`, whose `pass` defaults to `DEFAULT_SHELL_PASS`. */
+export function shellChildEnv(
+	source: Readonly<Record<string, string | undefined>>,
+	shellEnv: ShellEnv = {},
+): Record<string, string> {
+	return childEnv(source, {
+		...shellEnv,
+		pass: shellEnv.pass ?? DEFAULT_SHELL_PASS,
+	});
+}

package/src/core/shared/secret-mask.ts

@@ -0,0 +1,64 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+
+/** The names of host variables whose values are masked in tool output. */
+export const SECRET_NAME: RegExp = Object.freeze(
+	/(TOKEN|SECRET|KEY|PASS(WORD)?|DATABASE_URL|JWT|CREDENTIAL)/i,
+);
+
+/** Shorter values are too likely to be ordinary words to mask. */
+const MIN_SECRET_CHARS = 8;
+
+/** What a masked value is replaced with. */
+export const MASK = "****";
+
+/** The values of the variables `SECRET_NAME` matches, longest first, so a value inside another is masked as part of it. */
+function secretValues(
+	env: Readonly<Record<string, string | undefined>>,
+): string[] {
+	const values = new Set<string>();
+	for (const [name, value] of Object.entries(env))
+		if (
+			value !== undefined &&
+			value.length >= MIN_SECRET_CHARS &&
+			SECRET_NAME.test(name)
+		)
+			values.add(value);
+	return [...values].sort((a, b) => b.length - a.length);
+}
+
+/**
+ * The text with every value of a secret variable of `env` replaced with `****`: a variable whose
+ * name `SECRET_NAME` matches and whose value is at least 8 characters.
+ */
+export function maskSecrets(
+	text: string,
+	env: Readonly<Record<string, string | undefined>> = process.env,
+): string {
+	let masked = text;
+	for (const value of secretValues(env))
+		masked = masked.replaceAll(value, MASK);
+	return masked;
+}
+
+/**
+ * Masks secret values of `env` in the text of every tool result before it enters the model's
+ * context; read again at each result, so a variable set later is masked too.
+ */
+export function secretMaskExtension(
+	env: () => Readonly<Record<string, string | undefined>> = () => process.env,
+): ExtensionFactory {
+	return (pi) => {
+		pi.on("tool_result", (event) => {
+			const source = env();
+			let changed = false;
+			const content = event.content.map((part) => {
+				if (part.type !== "text") return part;
+				const text = maskSecrets(part.text, source);
+				if (text === part.text) return part;
+				changed = true;
+				return { ...part, text };
+			});
+			return changed ? { content } : undefined;
+		});
+	};
+}

package/src/index.ts

@@ -433,6 +433,7 @@ export type {
 	TransientTask,
 	TurnSelection,
 } from "./core/sessions.ts";
+export type { ShellEnv, ShellEnvConfig } from "./core/shared/child-env.ts";
 export type { Speaker, Tier } from "./core/speakers.ts";
 export { THE_SPEAKER, TIERS } from "./core/speakers.ts";
 export type { ToolTiers, ToolTierTable } from "./core/tool-tiers.ts";

package/src/kit/index.ts

@@ -137,8 +137,17 @@ export {
 } from "./presentation.ts";
 export { packageDir, serveUnix } from "./process.ts";
 export {
+	childEnv,
+	DEFAULT_SECRET_PATHS,
+	DEFAULT_SHELL_PASS,
+	maskSecrets,
 	type PushPolicy,
+	SECRET_NAME,
+	SHELL_ENV_NAMES,
 	SHELL_TOOLS,
+	type ShellPolicy,
+	secretMaskExtension,
+	shellChildEnv,
 	shellHoldRule,
 	shellHoldRuleFor,
 	YOLO_CARDED_SHELL_CLASSES,

package/src/kit/shell.ts

@@ -2,9 +2,23 @@
 // The host-shell tools and the hold rule that keeps risky commands behind the owner's approval.
 
 export {
+	DEFAULT_SECRET_PATHS,
 	type PushPolicy,
 	SHELL_TOOLS,
+	type ShellPolicy,
 	shellHoldRule,
 	shellHoldRuleFor,
 	YOLO_CARDED_SHELL_CLASSES,
 } from "../core/modules/host-shell/shell-policy.ts";
+// What child processes get of the host's environment, and the mask of secret values in tool output.
+export {
+	childEnv,
+	DEFAULT_SHELL_PASS,
+	SHELL_ENV_NAMES,
+	shellChildEnv,
+} from "../core/shared/child-env.ts";
+export {
+	maskSecrets,
+	SECRET_NAME,
+	secretMaskExtension,
+} from "../core/shared/secret-mask.ts";