@nanhara/hara 0.122.0 → 0.122.1

package/CHANGELOG.md

@@ -5,6 +5,60 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.122.1 — 2026-07-14 — protected files and explicit extension trust
+
+- **The npm CLI now requires Node.js 22.12+.** Node 20 is end-of-life, so Hara no longer makes a security or
+  compatibility promise for it. npm metadata, `hara doctor`, and startup diagnostics now agree; an older
+  runtime exits with a direct `nvm install 22 && nvm use 22` upgrade hint. Standalone binaries and Desktop
+  sidecars remain self-contained and do not require a host Node installation.
+- **Built-in file access fails closed before ordinary approval/dispatch.** Canonical and real-path checks
+  reject `.env`/`.env.*`, credential stores, private keys, and private Hara runtime state in file reads,
+  edit/patch pre-reads, grep/glob/ls, `@file`/completion, codebase and stale semantic indexes, checkpoints,
+  gateway file delivery, and cron command admission. Safe templates such as `.env.example`, `.env.sample`,
+  and `.env.template` remain readable. `HARA_ALLOW_SENSITIVE_FILES=1` is an explicit launch-time exposure
+  switch for one process; it removes both these built-in denies and that process's shell protected-read mask.
+- **Shell protection now reflects the host's guarantees.** Tool subprocesses receive a scrubbed environment;
+  inherited variables can be explicitly retained with the launch-time `HARA_SUBPROCESS_ENV_ALLOW` list, and
+  output is redacted by secret pattern and exact inherited value. Under the default protected-file policy,
+  shell admission blocks literal protected paths and environment dump commands on every platform. macOS
+  additionally applies a Seatbelt read mask to existing protected
+  files/directories, even when the general write sandbox is off. Linux and Windows do not have that kernel
+  read mask: their arbitrary shell code is not a security sandbox and static preflight can be bypassed.
+- **MCP servers and external coding agents are explicit trusted extensions.** They execute outside Hara's
+  protected-file boundary, require confirmation on every interactive tool call (including `full-auto`), and
+  are disabled in non-interactive runs by default. Reviewed automation may opt in before launch with
+  `HARA_ALLOW_TRUSTED_EXTENSIONS=1`; inherited credentials are still scrubbed.
+- **Repositories no longer silently control Hara's privileged configuration.** Project config is limited by
+  default to validated presentation/model preferences; provider routes, credentials, hooks, MCP, sandbox,
+  guardian, approval, and automation settings require the launch-time `HARA_TRUST_PROJECT_CONFIG=1` opt-in.
+  Project permissions may tighten global policy but cannot grant new access, and Git-tracked `.hara-profile`
+  pins are ignored unless that same trust decision was made before startup. Symlink, hard-link, size, identity,
+  and concurrent-change checks protect each of these inputs, while diagnostics reveal key names but no values.
+- **Coding and project-state writes are transactional.** Edit, patch, undo, memory, skills, plans, profiles,
+  indexes, and gateway state use no-follow descriptors, inode checks, bounded reads, atomic replace or
+  compare-and-swap semantics, and private modes where appropriate. Protected search uses the same verified
+  descriptor path instead of handing sensitive-path decisions to `rg`, closing replacement and hard-link
+  races. `AGENTS.md`, subdirectory hints, mentions, and touched-file recall are bounded and reject protected
+  aliases before adding repository content to model context.
+- **Semantic search and review automation distrust stale or historical content.** Semantic indexes carry a
+  versioned manifest with content hashes and are rebuilt when source identity or bytes change. Review-chain
+  prompts receive bounded status/path metadata rather than Git patches; an auto-commit proceeds only when the
+  staged blob still matches the verified worktree descriptor, including deletion and SHA-256 repository edge
+  cases. Read-only auto-run Git policy excludes commands that can expose historical blobs, credentials, remote
+  URLs, or patch bodies.
+- **Old private state is tightened and stale checkpoint history is rotated.** Startup repairs `~/.hara` and
+  sensitive runtime trees to owner-only modes on POSIX systems. The protected checkpoint format rebuilds old
+  derived shadow repositories, filters protected paths independently of the launch-time exposure switch, and
+  purges a checkpoint repository if a protected blob ever reaches its index.
+- **Long-running work has bounded ownership and shutdown.** Shell jobs, external agents, gateway children,
+  approved organization flows, and cron commands terminate the whole process tree with TERM-to-KILL escalation
+  and stop accepting output after cancellation. Background job counts, cron run time/log size, lock takeover,
+  and context fan-out are capped; Windows shell aliases and environment-dump variants are denied consistently.
+- **Gateway outbound files are immutable after admission.** Telegram, Feishu, Slack, Discord, Mattermost,
+  Matrix, WeCom, and Weixin upload verified in-memory bytes plus a safe filename, so a queued path cannot be
+  swapped for a secret before delivery. Counts and bytes are bounded at queue and consume time, cleanup checks
+  inode identity, and Signal outbound files fail closed because its RPC accepts only reopenable filesystem paths.
+
 ## 0.122.0 — 2026-07-13 — structured runs, durable work, and a fail-closed gateway
 
 - **Machine-safe headless runs.** `hara -p … --schema <json|file>` installs a run-scoped

package/README.md

@@ -12,11 +12,11 @@
 
 **Highlights**
 - **An org, not just an agent** — `hara org "<task>"` routes work to the role that *owns* it; `hara plan "<task>"` decomposes a task into a verified DAG of atoms (frame → atomize → sequence → execute → **verify gate**), and `hara plan --parallel` runs independent atoms concurrently.
-- **Drive it from chat** — `hara gateway` runs your local hara from **Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk · WeCom · Signal** (10 platforms), with **two-way images**, resumable per-chat sessions, project/agent roaming, bounded per-thread queues, and approval-gated group automations. Connects out — no public webhook. See **[docs/gateway.md](docs/gateway.md)**.
+- **Drive it from chat** — `hara gateway` runs your local hara from **Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk · WeCom · Signal** (10 platforms), with **two-way images where the platform has a byte-upload API**, resumable per-chat sessions, project/agent roaming, bounded per-thread queues, and approval-gated group automations. Connects out — no public webhook. See **[docs/gateway.md](docs/gateway.md)**.
 - **Real terminal UX** — an **ink TUI**: bottom-pinned input box, **plan mode** (read-only investigation → the model submits its plan via `exit_plan` → approve → execute), selectable approvals with "don't ask again", windowed reasoning, **paste images** (Ctrl+V) for vision models, light/dark theme.
 - **Persistent memory + self-evolution** — `memory_*` tools over global/project `MEMORY.md`; the agent recalls before acting, **proactively saves** durable facts, and grows its own playbooks (a lexical guard screens what it writes). Inspect/consolidate it with **`hara memory show`** and **`hara memory distill`** (promote recent daily logs → durable memory). Lexical-first by design — semantic search is opt-in, never required.
 - **Multi-provider, all streamed** — Anthropic (Claude) or any OpenAI-compatible endpoint (Qwen/DashScope, GLM, Kimi, OpenAI) with live Markdown + visible reasoning.
-- **Delegate to other agents** — the **`external_agent`** tool hands a self-contained task to **Claude Code** or **Codex** running headless, and returns the result — so you pick the best engine per task. Gated by approval, trust-tiered, and never exposed to read-only sub-agents.
+- **Delegate to other agents** — the **`external_agent`** tool hands a self-contained task to **Claude Code** or **Codex** running headless, and returns the result — so you pick the best engine per task. It is a trusted extension outside Hara's protected-file boundary: every interactive call requires confirmation, and non-interactive use is disabled by default.
 - **Honest under a slow network** — a live "waiting for the model… Ns" status, a stall watchdog that
   auto-fails-over instead of hanging, big pastes folding to a token, and a startup update notice — the
   terminal never feels dead.
@@ -26,6 +26,9 @@ Track it: https://github.com/hara-cli/hara · https://hara.run
 
 ## Install
 
+The npm package requires **Node.js 22.12 or newer**. If needed, upgrade first with
+`nvm install 22 && nvm use 22`. Node.js 20 is end-of-life and is not a supported Hara runtime.
+
 ```bash
 npm i -g @nanhara/hara
 ```
@@ -135,9 +138,14 @@ hara expresses it the way each endpoint wants (OpenAI `reasoning_effort`, Anthro
 DashScope `enable_thinking`, **DeepSeek** V4 `thinking` + `reasoning_effort` where `max` genuinely raises the
 effort). In the TUI, bare `/model` opens a picker — ↑↓ pick a model, **←→ set the thinking level**.
 
-Config lives in `~/.hara/config.json`; the nearest project `.hara/config.json` can specialize it. Effective
-precedence is **environment > project > selected overlay > global**. Empty routing values are ignored, so an
-empty project/env value cannot hide a working global credential or endpoint. Env overrides include
+Config lives in `~/.hara/config.json`; the nearest project `.hara/config.json` may set the explicitly safe
+project preferences `model`, `theme`, `vimMode`, `autoCompact`, and `reasoningEffort`. Repository config is
+untrusted by default: routing/credential, hook/MCP, approval/sandbox, computer-control, and other privileged
+keys are ignored with a key-name-only warning. For a repository you have reviewed, launch with
+`HARA_TRUST_PROJECT_CONFIG=1` to enable all of its project keys for that process. The opt-in is captured at
+startup, and project config itself must be a bounded regular file under a real (non-symlink) `.hara` directory.
+Effective precedence for enabled keys is **environment > project > selected overlay > global**. Empty routing
+values are ignored, so an empty project/env value cannot hide a working global credential or endpoint. Env overrides include
 `HARA_PROVIDER`, `HARA_MODEL`, `HARA_BASE_URL`, `HARA_API_KEY`, and the provider key
 (`ANTHROPIC_API_KEY` / `DASHSCOPE_API_KEY`).
 
@@ -220,14 +228,14 @@ vector DB needed, and lexical still works when there's no index. Re-running `har
 only changed files re-embed (a full repo rebuild that takes ~a minute re-runs in well under a second).
 
 **Approval modes**: `suggest` confirms edits & shell · `auto-edit` auto-applies file edits but confirms shell · `full-auto` runs everything.
-**Sandbox** (macOS): `--sandbox workspace-write|read-only` runs the `bash` tool under Seatbelt — **file-write confinement** (writes confined to the project / blocked). It does not restrict reads, network, or process exec; on non-macOS the shell runs unsandboxed (with a warning).
+**Protected files and shell sandboxing**: built-in file, search, and context paths hard-reject `.env`/credential/private-key/private-Hara-state files before the ordinary approval/dispatch path can authorize them. Safe templates (`.env.example`, `.env.sample`, `.env.template`) remain readable. `HARA_ALLOW_SENSITIVE_FILES=1` is an explicit one-process exposure switch: it removes these built-in denies and that process's shell protected-read mask. Shell subprocesses receive a scrubbed environment; explicitly retain a named inherited variable with `HARA_SUBPROCESS_ENV_ALLOW=NAME[,NAME]` (output is still redacted). With the protected-file policy enabled, shell preflight rejects literal protected paths and environment-dump commands on every OS. On macOS, Seatbelt also masks existing protected files/directories from the shell and `--sandbox workspace-write|read-only` provides **file-write confinement**. Linux/Windows have no equivalent kernel read mask: static shell preflight is a useful guardrail, not a security sandbox, and arbitrary code can bypass it.
 **Screen control** (opt-in): the `computer` tool drives desktop software (screenshot → click/type), native per OS
 (mac `screencapture`+`cliclick` · Windows PowerShell · Linux `scrot`+`xdotool`). Off by default — enable a tier with
 `hara config set computerUse read|click|full` and allowlist apps with `hara config set computerApps "App, …"`. Guarded
 by the tier, the frontmost-app allowlist, a dangerous-key blocklist, and a once-per-session grant. Screenshots are read via your
 vision model into **actionable** output — interactive elements + positions (pass `focus` to target what you're after) — so even a text-only main model can click.
 **Sessions**: conversations are saved automatically — `-c` / `--resume <id>` to continue, `hara sessions` to list, `hara export [id] [--out file]` to render one as a Markdown transcript.
-**MCP**: add an `mcpServers` map to config (global or project `.hara/config.json`); their tools appear to the agent as `mcp__<server>__<tool>`. hara can also **be** an MCP server — `hara mcp` exposes its read/search tools (esp. **`codebase_search`**) over stdio so other clients (Claude Desktop, Cursor, another hara) can use them; read-only by default (`HARA_MCP_TOOLS` to override).
+**MCP**: add an `mcpServers` map to global config (a reviewed project config additionally needs `HARA_TRUST_PROJECT_CONFIG=1` at launch); their tools appear to the agent as `mcp__<server>__<tool>`. Configured MCP servers, like `external_agent`, are trusted host extensions outside Hara's protected-file boundary. Every interactive tool call requires confirmation (even in `full-auto`), and non-interactive runs disable them by default; reviewed automation can explicitly opt in before launch with `HARA_ALLOW_TRUSTED_EXTENSIONS=1`. hara can also **be** an MCP server — `hara mcp` exposes its read/search tools (esp. **`codebase_search`**) over stdio so other clients (Claude Desktop, Cursor, another hara) can use them; read-only by default (`HARA_MCP_TOOLS` to override).
 **Vim mode**: `hara config set vimMode true` makes the prompt modal — Esc → normal, `i/a/A/I` insert, `h l 0 $ w b e` motions, `x D C dd cw p` edits. Off by default.
 **Scheduled tasks**: `hara cron add "0 9 * * 1-5" "<task>"` (or `"every 30m"`, `"in 2h"`) runs a task on a schedule — each run is a fresh hara session. `hara cron install` wires a per-minute tick into launchd/crontab (no daemon); `--org` routes through the role org. Manage with `hara cron list/run/enable/disable/remove/logs`.
 **Work coordination**: `todo_write` is the agent's short, session-scoped checklist; it persists with that
@@ -236,13 +244,18 @@ for work that outlives a conversation: add/update/list/remove items with `pendin
 owner, and `blockedBy` dependencies. The private, atomic store is shared by concurrent hara processes for the
 same project and rejects missing/self/cyclic dependencies.
 **Notifications**: `hara config set notify bell` (terminal bell) or `notify system` (OS notification) pings you when a turn finishes — handy for long runs you've stepped away from. Gated on elapsed time so quick turns stay quiet; off by default.
-**Hooks**: run your own shell commands around tool calls via a `"hooks"` map in config. A **`PreToolUse`** hook can **veto** a call (non-zero exit blocks it; its output becomes the reason the model sees) — gate `bash`, forbid edits outside a path, require a clean tree. A **`PostToolUse`** hook observes (format/lint a file the agent just wrote, log, notify). Each has a `matcher` (regex/literal on the tool name, `*` = all) and gets `{tool, payload}` on stdin + `HARA_TOOL_NAME` in env. Plugins can contribute hooks too.
+**Hooks**: run your own shell commands around tool calls via a `"hooks"` map in global config; hooks from a reviewed project config require the launch-time `HARA_TRUST_PROJECT_CONFIG=1` opt-in. A **`PreToolUse`** hook can **veto** a call (non-zero exit blocks it; its output becomes the reason the model sees) — gate `bash`, forbid edits outside a path, require a clean tree. A **`PostToolUse`** hook observes (format/lint a file the agent just wrote, log, notify). Each has a `matcher` (regex/literal on the tool name, `*` = all) and gets `{tool, payload}` on stdin + `HARA_TOOL_NAME` in env. Plugins can contribute hooks too.
 Reviewer/read-only/plan runs and parallel read-only sub-agents suppress both hook phases: PreToolUse and
 PostToolUse commands are arbitrary shell, so either could otherwise bypass their read-only contract indirectly.
 They also skip configured and plugin-provided MCP server processes, so starting an external tool server cannot
 bypass the same contract before the first model turn.
 **Profiles and live config**: select an identity with `--profile <name>`; use `overlays` in
-`~/.hara/config.json` for named config overlays, and a project `.hara/config.json` for project-specific routing.
+`~/.hara/config.json` for named config overlays. Project `.hara/config.json` files get the safe preference
+allowlist above; project-specific routing requires `HARA_TRUST_PROJECT_CONFIG=1` before launch.
+`.hara-profile` identity pins are read no-follow with size, single-inode, and hard-link checks; pin updates use
+an atomic compare-and-swap, and invalid-pin warnings never echo file contents or paths. A Git-tracked pin is
+repository-controlled and ignored by default; local untracked pins created with `hara profile pin` work
+normally. The same launch-time `HARA_TRUST_PROJECT_CONFIG=1` opt-in enables a reviewed tracked pin.
 Long-lived `hara serve` processes reload provider credentials/routes and guardian settings for the target cwd on
 new sessions and turns. `models.list` and new sessions see current defaults; a resumed session keeps its explicit
 model pin while using the live provider route. No server restart is required after a credential rotation.
@@ -289,11 +302,11 @@ turn, or **`/undo`** to revert the last edit. In-session **`/diff`**, **`/review
 - **Project context**: auto-loads `AGENTS.md` (the cross-tool standard) walking up to the repo root; `hara init` writes one by analyzing the repo.
 - **`@file` mentions**: attach file contents to a message (`@path`); Tab-completes with a **fuzzy** matcher over the project (subdirs, git-tracked + untracked) — `@idx` → `src/index.ts`. `@<dir>` loads a directory listing, `@src/`+Tab drills into a folder, and mistyped tool/file paths get a "did you mean" suggestion.
 - **Multi-provider**: Anthropic (Claude) or any OpenAI-compatible endpoint (Qwen/DashScope, GLM, Kimi, OpenAI) — **all streamed live**.
-- **Chat gateway**: drive your local hara from **Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk · WeCom · Signal**. The daemon connects out (no public webhook), with per-chat sessions, project roaming (`/cd`), agent switching (`/agent`), and **two-way images** (send a photo → it sees it; ask for a file → it sends one). Setup and the group-flow security model: **[docs/gateway.md](docs/gateway.md)**.
+- **Chat gateway**: drive your local hara from **Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk · WeCom · Signal**. The daemon connects out (no public webhook), with per-chat sessions, project roaming (`/cd`), agent switching (`/agent`), and **two-way images on byte-upload-capable platforms**. Setup, platform capability details, and the group-flow security model: **[docs/gateway.md](docs/gateway.md)**.
 
 ### Roadmap
 
-**Shipped:** ink TUI · plan mode · persistent memory + self-evolution · atomization planner · parallel plan atoms · **multi-role review chains** · global project-agent index · durable project tasks · parallel sub-agents · MCP client *and* server · **scheduled tasks (`hara cron`)** · **chat gateway (10 platforms, two-way images)** · **single-binary distribution** · **Docker image** · `/compact` context management.
+**Shipped:** ink TUI · plan mode · persistent memory + self-evolution · atomization planner · parallel plan atoms · **multi-role review chains** · global project-agent index · durable project tasks · parallel sub-agents · MCP client *and* server · **scheduled tasks (`hara cron`)** · **chat gateway (10 platforms, capability-aware media)** · **single-binary distribution** · **Docker image** · `/compact` context management.
 **Next:** SSOT data authority · an enterprise control-plane (fleet + central token management).
 
 ## Security

package/SECURITY.md

@@ -29,9 +29,45 @@ local user (who already has your shell).
 - **`web_fetch` SSRF guard.** Refuses to fetch private / loopback / link-local / CGNAT addresses (resolving
   the hostname first), re-checks on every redirect hop, and reads the body under a byte ceiling — so the
   model can't reach cloud-metadata endpoints or internal services.
-- **Secrets.** `~/.hara/config.json` (API keys) and `~/.hara/qwen-oauth.json` (tokens) are written `0600`.
-  The optional semantic index respects `.gitignore` and skips secret-named files, so keys aren't embedded or
-  sent to an embedding provider. The memory guard screens secret-shaped strings out of what the agent saves.
+- **Protected reads in built-in paths.** `.env`, `.env.*` (except explicit templates such as
+  `.env.example`), credential stores, private keys, and private Hara state are rejected before the ordinary
+  approval/dispatch path can authorize them. The same canonical/real-path check covers built-in file reads,
+  edit/patch pre-reads, grep/glob/ls, `@file`, completion, semantic/lexical indexes, checkpoints, gateway file
+  delivery, cron command admission, and symlink aliases. Headless, gateway, sub-agent, cron, and `full-auto`
+  execution cannot approve those built-in paths past the check. `HARA_ALLOW_SENSITIVE_FILES=1` is an explicit
+  launch-time exposure switch for one process: it removes the built-in denies and that process's shell
+  protected-read preflight/Seatbelt mask.
+- **Shell guardrails differ by platform.** With the protected-file policy enabled, shell admission statically
+  rejects literal protected paths and environment-dump commands on every OS. On macOS, Hara additionally
+  applies a Seatbelt read mask to existing
+  protected files/directories even when the general write sandbox is off. Linux and Windows have no equivalent
+  kernel-enforced read mask: their arbitrary shell code is outside the protected-file boundary, and static
+  preflight can be bypassed by indirection or generated code.
+- **Subprocess credentials.** Model-controlled Bash/background jobs, hooks, external agents, and MCP servers
+  inherit an environment with secret-shaped and code-injection variables removed. MCP `env` entries are an
+  explicit per-server grant; other commands can receive named variables only when the user launches Hara with
+  `HARA_SUBPROCESS_ENV_ALLOW=NAME,OTHER`. Tool output is pattern- and exact-value-redacted. Hara's own provider
+  process retains its keys.
+- **Secrets at rest.** `~/.hara/config.json` (API keys) and `~/.hara/qwen-oauth.json` (tokens) are written
+  `0600`. The optional semantic index skips secret-named files and filters old indexes at query time, so keys
+  aren't embedded or sent to an embedding provider. The memory guard screens secret-shaped strings out of
+  what the agent saves.
+- **Repository config is untrusted by default.** A project `.hara/config.json` can set only `model`, `theme`,
+  `vimMode`, `autoCompact`, and `reasoningEffort`. Endpoint/credential routing, hooks/MCP commands, approval,
+  sandbox, guardian, computer control, and all other keys remain global unless the user launches Hara with
+  `HARA_TRUST_PROJECT_CONFIG=1` after reviewing that repository. Warnings name ignored/enabled keys but never
+  their values. Project config reads reject a symlink `.hara`, final symlinks, hard links, oversized files,
+  and files/directories that change identity during the read.
+- **Identity pins are bound, not followed.** `.hara-profile` reads reject symlink/hard-link aliases and
+  oversized or changing files. Writes use a canonical-parent, no-follow snapshot plus atomic compare-and-swap;
+  invalid pin warnings never include the pin's raw content or untrusted path. Git-tracked pins are ignored by
+  default so a cloned repository cannot silently switch to an existing personal/org identity; untracked local
+  pins remain usable, and the reviewed-repository `HARA_TRUST_PROJECT_CONFIG=1` launch opt-in enables tracked pins.
+- **MCP/external agents are trusted extensions.** They execute outside Hara's protected-file boundary. Every
+  interactive tool call requires confirmation, including in `full-auto`; non-interactive runs disable them by
+  default. Reviewed automation can explicitly enable them before launch with
+  `HARA_ALLOW_TRUSTED_EXTENSIONS=1`. Their inherited environment is still scrubbed, but the extension may use
+  its own credentials or access anything its host process permits.
 - **Plugins are code you trust.** Installing a plugin (`hara plugin add`) grants its author code execution:
   its MCP servers and hooks run shell commands on launch. `hara plugin add` **prints the exact commands** a
   plugin will run so you can review them; disable with `hara plugin disable <name>`.
@@ -39,13 +75,16 @@ local user (who already has your shell).
 
 ## What is *not* a security boundary
 
-- **The sandbox confines file writes only** — not reads, not network, not process exec; `/private/tmp`
-  stays writable. It stops a stray `rm`/overwrite escaping the project, not a determined exfiltration. Treat
-  a `full-auto` + network-capable shell as able to read and send anything your account can.
-- **`@file` mentions** read any file *you* name (including outside the project) — that's you attaching
-  context, not the model exfiltrating; mentions are expanded on your typed input only, never on model output.
+- **The general sandbox confines file writes only** — not arbitrary reads, network, or process exec;
+  `/private/tmp` stays writable. The protected-file policy is a narrow boundary for Hara's built-in paths,
+  plus an OS-enforced shell read mask on macOS only; it is not a complete hostile-code jail. On Linux and
+  Windows, treat any allowed network-capable shell as able to read and send anything the Hara process account
+  can access. On macOS, the protected-path mask still does not confine ordinary files, network, or process exec.
+- **`@file` mentions** can read ordinary files *you* name (including outside the project), but protected
+  files are refused unless you made the launch-time opt-in. Mentions are expanded on user input only.
 - **`full-auto` / `-y`** removes the human gate by your explicit choice. Use it on code and in directories
-  you trust.
+  you trust. It does not remove built-in protected-path checks or subprocess environment scrubbing, but it
+  does not turn Linux/Windows shell preflight into a security boundary.
 
 ## Reporting a vulnerability
 

package/dist/agent/loop.js

@@ -17,6 +17,7 @@ import { setTurnPhase } from "./phase.js";
 import { recordTouch } from "./touched.js";
 import { resolve as resolvePath } from "node:path";
 import { redactSensitiveText } from "../security/secrets.js";
+import { redactToolSubprocessOutput } from "../security/subprocess-env.js";
 /** File tools whose `path` input marks the file as "recently worked with" (post-compaction restore). */
 const FILE_TOUCH_TOOLS = new Set(["read_file", "edit_file", "write_file"]);
 /** Stall watchdog ceiling: a model attempt that streams NOTHING for this long is treated as a dead /
@@ -72,7 +73,17 @@ source file or shell command. Reference an environment variable instead (for exa
 $API_KEY). Keep real values in the user's environment or an approved secret store; do not create/populate a
 .env file with a real secret unless the user explicitly asks and it is excluded from version control. Never
 echo credentials back. Session persistence redacts likely secrets as a last line of defense, but that does
-not make embedding credentials acceptable.
+not make embedding credentials acceptable. Built-in file, search, and context paths hard-reject protected
+files (.env/.env.*, credential stores, private keys, and private Hara state) before ordinary approval/dispatch;
+do not try to bypass that policy through shell indirection, another tool, a sub-agent, or full-auto. Safe
+templates such as .env.example may be read. Only a user who restarts Hara with
+HARA_ALLOW_SENSITIVE_FILES=1 explicitly removes the built-in deny and shell protected-read mask for that
+process. Shell subprocesses have credentials removed from their environment. macOS also applies an OS read
+mask to existing protected paths; Linux/Windows shell checks are
+static guardrails, not a kernel sandbox. MCP and external coding agents run outside this boundary: use them
+only as reviewed trusted extensions. Their tool calls require confirmation every time in interactive use and
+are disabled without an interactive approval channel unless the user launched with
+HARA_ALLOW_TRUSTED_EXTENSIONS=1.
 For broad,
 open-ended exploration (more than ~3 searches), spawn \`agent\` sub-agents — several in one response for
 independent questions (role "explore") — each returns conclusions, not dumps. Messages the user sends
@@ -461,11 +472,21 @@ export async function runAgent(history, opts) {
                 continue;
             }
             const input = tu.input;
-            const preview = String(input.path ?? input.command ?? input.pattern ?? input.url ?? input.task ?? "")
+            const preview = redactToolSubprocessOutput(String(input.path ?? input.command ?? input.pattern ?? input.url ?? input.task ?? "")
                 .replace(/\s+/g, " ")
-                .trim();
-            // Screen control is gated on EVERY action — a prior "don't ask again" must never satisfy it.
-            const alwaysGate = tool.kind === "computer";
+                .trim());
+            // Screen control and opaque host extensions are gated on EVERY action — a prior "don't ask again"
+            // and even full-auto must never silently turn them into a side channel.
+            const alwaysGate = tool.kind === "computer" || tool.trustBoundary === "external";
+            if (tool.trustBoundary === "external" && !ctx.ask && process.env.HARA_ALLOW_TRUSTED_EXTENSIONS !== "1") {
+                plans.push({
+                    tu,
+                    tool,
+                    denied: "Trusted extension blocked in this non-interactive run. MCP and external coding agents run outside Hara's file boundary; " +
+                        "restart with HARA_ALLOW_TRUSTED_EXTENSIONS=1 only after reviewing that extension.",
+                });
+                continue;
+            }
             // Command-level policy for shell commands: a deny rule blocks even in full-auto; an allow rule (or a
             // read-only command) auto-runs even in suggest mode. Composes with, doesn't replace, the approval mode.
             const cmdDecision = tool.kind === "exec" && typeof input.command === "string" ? decideCommand(input.command, permRules) : null;
@@ -480,8 +501,9 @@ export async function runAgent(history, opts) {
             if (guardianOn && !breakerHalt) {
                 const risk = classifyRisk(tu.name, tool.kind, input, ctx.cwd);
                 if (risk.level === "high") {
-                    const detail = String(input.command ?? input.path ?? "").replace(/\s+/g, " ").trim().slice(0, 400);
-                    const verdict = await guardianVeto(opts.guardian.provider, { tool: tu.name, detail, classifierReason: risk.reason }, history, { signal: opts.signal });
+                    const safeRiskReason = redactToolSubprocessOutput(risk.reason);
+                    const detail = redactToolSubprocessOutput(String(input.command ?? input.path ?? "").replace(/\s+/g, " ").trim().slice(0, 400));
+                    const verdict = await guardianVeto(opts.guardian.provider, { tool: tu.name, detail, classifierReason: safeRiskReason }, history, { signal: opts.signal });
                     if (opts.signal?.aborted)
                         return finalizeInterruptedToolRound();
                     if (verdict.decision === "block") {
@@ -489,10 +511,10 @@ export async function runAgent(history, opts) {
                         plans.push({
                             tu,
                             tool,
-                            denied: `Guardian blocked this high-risk action: ${verdict.reason || risk.reason}. Reconsider — take a safer, in-scope step, or ask the user before doing this.`,
+                            denied: `Guardian blocked this high-risk action: ${verdict.reason || safeRiskReason}. Reconsider — take a safer, in-scope step, or ask the user before doing this.`,
                         });
                         if (!opts.quiet) {
-                            const note = `⛔ guardian blocked ${tu.name} — ${verdict.reason || risk.reason}`;
+                            const note = `⛔ guardian blocked ${tu.name} — ${verdict.reason || safeRiskReason}`;
                             if (sink)
                                 sink.notice(note);
                             else
@@ -521,7 +543,8 @@ export async function runAgent(history, opts) {
                     }
                 }
             }
-            if (cmdDecision !== "allow" && needsConfirm(tool.kind, opts.approval) && (alwaysGate || !opts.autoApprove?.has(tu.name))) {
+            const shouldConfirm = alwaysGate || (cmdDecision !== "allow" && needsConfirm(tool.kind, opts.approval) && !opts.autoApprove?.has(tu.name));
+            if (shouldConfirm) {
                 const reply = await opts.confirm(`${c.yellow("⚠")}  ${c.bold(tu.name)} ${c.dim(preview)} — run?`);
                 if (opts.signal?.aborted)
                     return finalizeInterruptedToolRound();

package/dist/agent/touched.js

@@ -2,6 +2,7 @@
 // The loop records every file the MAIN conversation reads/edits; when the history is compacted to a
 // summary, the top-N most-recent files get their CURRENT on-disk content re-attached — so the model
 // doesn't lose the very files it was working on and re-read them all next turn.
+import { isSensitiveFilePath } from "../security/sensitive-files.js";
 const DEFAULT_SCOPE = "default";
 const touchedByScope = new Map(); // scope → absolute path → last-touch timestamp
 function scopedTouched(scope) {
@@ -11,6 +12,8 @@ function scopedTouched(scope) {
     return touched;
 }
 export function recordTouch(path, scope) {
+    if (isSensitiveFilePath(path))
+        return;
     const touched = scopedTouched(scope);
     touched.delete(path);
     touched.set(path, Date.now());
@@ -20,6 +23,7 @@ export function recordTouch(path, scope) {
 /** Most-recently-touched first. */
 export function recentTouched(n = 5, scope) {
     return [...scopedTouched(scope).entries()]
+        .filter(([path]) => !isSensitiveFilePath(path))
         .sort((a, b) => b[1] - a[1])
         .slice(0, n)
         .map(([p]) => p);

package/dist/checkpoints.js

@@ -5,22 +5,39 @@
 // snapshot-then-checkout: SAFE — it reverts changed/deleted files to the checkpoint and never deletes files
 // created since (so a stray restore can't nuke new work; it's also itself undoable via the auto-snapshot).
 import { execFileSync } from "node:child_process";
-import { mkdirSync, writeFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { chmodSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { findProjectRoot } from "./context/agents-md.js";
+import { toolSubprocessEnv } from "./security/subprocess-env.js";
+import { sensitiveFileReason } from "./security/sensitive-files.js";
+import { redactSensitiveText } from "./security/secrets.js";
 // Heavy/derived dirs the shadow repo must never snapshot (in addition to the project's own .gitignore).
-const EXCLUDES = ["node_modules/", ".git/", "dist/", "build/", "out/", ".next/", "target/", ".venv/", "venv/", "__pycache__/", ".hara/", ".cache/", ".turbo/", "coverage/", "*.log", ".DS_Store"];
+const PRIVATE_DATA_EXCLUDES = ["credentials", "credential", "secrets", "secret", "service-account", "service_account"]
+    .flatMap((stem) => ["json", "yaml", "yml", "toml", "ini", "cfg", "conf"].map((ext) => `**/${stem}.${ext}`));
+const EXCLUDES = [
+    "node_modules/", ".git/", "dist/", "build/", "out/", ".next/", "target/", ".venv/", "venv/",
+    "__pycache__/", ".hara/", ".cache/", ".turbo/", "coverage/", "*.log", ".DS_Store",
+    "**/.env", "**/.env.*", "!**/.env.example", "!**/.env.*.example", "!**/.env.sample", "!**/.env.*.sample",
+    "!**/.env.template", "!**/.env.*.template", "!**/.env.dist", "!**/.env.*.dist", "!**/.env.defaults", "!**/.env.*.defaults",
+    "**/.envrc", "**/.direnv/", "**/.netrc", "**/.npmrc", "**/.pypirc", "**/.git-credentials",
+    "**/credentials", "**/credential", "**/secrets", "**/secret", "**/service-account", "**/service_account",
+    ...PRIVATE_DATA_EXCLUDES,
+    "**/application_default_credentials.json", "**/.aws/credentials", "**/.docker/config.json", "**/.kube/config",
+    "**/id_rsa", "**/id_ed25519", "**/id_ecdsa", "**/*.pem", "**/*.key", "**/*.p12", "**/*.pfx", "**/*.keystore",
+];
+const CHECKPOINT_FORMAT = "protected-files-v2";
 function shadowGitDir(root) {
     return join(homedir(), ".hara", "checkpoints", createHash("sha256").update(root).digest("hex").slice(0, 16), "git");
 }
-function git(root, gitDir, args) {
+function git(root, gitDir, args, input) {
     return execFileSync("git", args, {
         cwd: root,
-        env: { ...process.env, GIT_DIR: gitDir, GIT_WORK_TREE: root, GIT_AUTHOR_NAME: "hara", GIT_AUTHOR_EMAIL: "hara@local", GIT_COMMITTER_NAME: "hara", GIT_COMMITTER_EMAIL: "hara@local" },
+        env: toolSubprocessEnv(process.env, { GIT_DIR: gitDir, GIT_WORK_TREE: root, GIT_AUTHOR_NAME: "hara", GIT_AUTHOR_EMAIL: "hara@local", GIT_COMMITTER_NAME: "hara", GIT_COMMITTER_EMAIL: "hara@local" }),
         encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
+        stdio: [input === undefined ? "ignore" : "pipe", "pipe", "ignore"],
+        ...(input === undefined ? {} : { input }),
         maxBuffer: 64 * 1024 * 1024,
         // Bound it: the per-turn shadow `git add -A` over a large tree (or a hung git) must never freeze a
         // turn. On timeout execFileSync throws → checkpoint()/ensureRepo() catch it → the snapshot is just
@@ -30,18 +47,61 @@ function git(root, gitDir, args) {
 }
 function ensureRepo(root, gitDir) {
     try {
+        const stateDir = dirname(gitDir);
+        const checkpointRoot = dirname(stateDir);
+        const marker = join(stateDir, "format");
+        mkdirSync(checkpointRoot, { recursive: true, mode: 0o700 });
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        try {
+            chmodSync(checkpointRoot, 0o700);
+            chmodSync(stateDir, 0o700);
+        }
+        catch { /* best effort */ }
+        // Older shadow repositories may contain secret blobs even after the path leaves the index. Checkpoints
+        // are a derived undo cache, so rotate the repository instead of pretending git-rm purged its history.
+        let format = "";
+        try {
+            format = readFileSync(marker, "utf8").trim();
+        }
+        catch { /* first protected open */ }
+        if (existsSync(gitDir) && format !== CHECKPOINT_FORMAT)
+            rmSync(gitDir, { recursive: true, force: true });
         if (!existsSync(join(gitDir, "HEAD"))) {
-            mkdirSync(gitDir, { recursive: true });
+            mkdirSync(gitDir, { recursive: true, mode: 0o700 });
             git(root, gitDir, ["init", "-q"]);
             mkdirSync(join(gitDir, "info"), { recursive: true });
-            writeFileSync(join(gitDir, "info", "exclude"), EXCLUDES.join("\n") + "\n");
         }
+        try {
+            chmodSync(gitDir, 0o700);
+        }
+        catch { /* best effort */ }
+        writeFileSync(marker, CHECKPOINT_FORMAT + "\n", { mode: 0o600 });
+        try {
+            chmodSync(marker, 0o600);
+        }
+        catch { /* best effort on non-POSIX filesystems */ }
+        mkdirSync(join(gitDir, "info"), { recursive: true });
+        const excludeFile = join(gitDir, "info", "exclude");
+        writeFileSync(excludeFile, EXCLUDES.join("\n") + "\n", { mode: 0o600 });
+        try {
+            chmodSync(excludeFile, 0o600);
+        }
+        catch { /* best effort on non-POSIX filesystems */ }
         return true;
     }
     catch {
         return false;
     }
 }
+function dropSensitiveIndexEntries(root, gitDir) {
+    const indexed = git(root, gitDir, ["ls-files", "-z"]).split("\0").filter(Boolean);
+    const protectedPaths = indexed.filter((path) => sensitiveFileReason(join(root, path)) !== null);
+    if (protectedPaths.length) {
+        // stdin pathspecs avoid ARG_MAX and preserve arbitrary filenames (including whitespace/newlines).
+        git(root, gitDir, ["update-index", "--force-remove", "-z", "--stdin"], protectedPaths.join("\0") + "\0");
+    }
+    return protectedPaths.length;
+}
 /** Snapshot the current working tree into the shadow repo. Returns the short sha, or null on failure. */
 export function checkpoint(cwd, label) {
     const root = findProjectRoot(cwd);
@@ -49,8 +109,22 @@ export function checkpoint(cwd, label) {
     if (!ensureRepo(root, gitDir))
         return null;
     try {
+        // If a path became protected after this format was introduced, merely unstaging it would leave its
+        // historical blobs reachable. Rotate the derived repository before taking another snapshot.
+        if (dropSensitiveIndexEntries(root, gitDir) > 0) {
+            rmSync(gitDir, { recursive: true, force: true });
+            if (!ensureRepo(root, gitDir))
+                return null;
+        }
         git(root, gitDir, ["add", "-A"]);
-        git(root, gitDir, ["commit", "-q", "--allow-empty", "--no-gpg-sign", "-m", (label || "checkpoint").slice(0, 120)]);
+        // Defense against a future exclude-list regression. Once git-add saw a protected path its blob may exist
+        // even if we unstage it, so fail closed and purge the derived repository instead of retaining that object.
+        if (dropSensitiveIndexEntries(root, gitDir) > 0) {
+            rmSync(gitDir, { recursive: true, force: true });
+            return null;
+        }
+        const safeLabel = redactSensitiveText(label || "checkpoint").text.slice(0, 120);
+        git(root, gitDir, ["commit", "-q", "--allow-empty", "--no-gpg-sign", "-m", safeLabel]);
         return git(root, gitDir, ["rev-parse", "--short", "HEAD"]).trim();
     }
     catch {
@@ -59,11 +133,12 @@ export function checkpoint(cwd, label) {
 }
 /** Recent checkpoints, newest first. */
 export function listCheckpoints(cwd, n = 15) {
-    const gitDir = shadowGitDir(findProjectRoot(cwd));
-    if (!existsSync(join(gitDir, "HEAD")))
+    const root = findProjectRoot(cwd);
+    const gitDir = shadowGitDir(root);
+    if (!ensureRepo(root, gitDir) || !existsSync(join(gitDir, "HEAD")))
         return [];
     try {
-        const out = git(findProjectRoot(cwd), gitDir, ["log", `-n${n}`, "--format=%h\x1f%ct\x1f%s"]).trim();
+        const out = git(root, gitDir, ["log", `-n${n}`, "--format=%h\x1f%ct\x1f%s"]).trim();
         if (!out)
             return [];
         return out.split("\n").map((l) => {
@@ -79,15 +154,26 @@ export function listCheckpoints(cwd, n = 15) {
  *  undoable). Files created AFTER the checkpoint are left in place — nothing is deleted. Returns the count of
  *  files restored, or null on failure. */
 export function restoreCheckpoint(cwd, ref) {
+    if (!/^[0-9a-f]{4,64}$/i.test(ref))
+        return null; // checkpoint refs are hashes; reject option/ref injection
     const root = findProjectRoot(cwd);
     const gitDir = shadowGitDir(root);
-    if (!existsSync(join(gitDir, "HEAD")))
+    if (!ensureRepo(root, gitDir) || !existsSync(join(gitDir, "HEAD")))
         return null;
     try {
-        checkpoint(cwd, `before restore to ${ref}`); // make the restore itself undoable
-        const changed = git(root, gitDir, ["diff", "--name-only", ref, "--"]).trim(); // files differing now vs ref
-        git(root, gitDir, ["checkout", ref, "--", "."]);
-        return changed ? changed.split("\n").length : 0;
+        // Restoring without a durable pre-restore snapshot can destroy the user's newest work. Checkpointing is
+        // best-effort during ordinary turns, but it is a hard prerequisite for this destructive operation.
+        if (!checkpoint(cwd, `before restore to ${ref}`))
+            return null;
+        const changed = new Set(git(root, gitDir, ["diff", "--name-only", "-z", ref, "--"]).split("\0").filter(Boolean));
+        // A pre-restore snapshot tracks files created after `ref`; `git checkout ref -- new-file` would make
+        // the whole checkout fail. Restore only paths that actually existed at the requested checkpoint.
+        const atRef = git(root, gitDir, ["ls-tree", "-r", "-z", "--name-only", ref]).split("\0").filter(Boolean);
+        const safe = atRef.filter((path) => changed.has(path) && sensitiveFileReason(join(root, path)) === null);
+        if (safe.length) {
+            git(root, gitDir, ["checkout", ref, "--pathspec-from-file=-", "--pathspec-file-nul"], safe.join("\0") + "\0");
+        }
+        return safe.length;
     }
     catch {
         return null;

package/dist/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Keep the runtime gate dependency-free and ahead of the main CLI import. Older Node releases must see an
+// actionable upgrade message even if a future dependency starts using syntax or APIs they cannot load.
+import { unsupportedNodeMessage } from "./runtime.js";
+const runtimeError = unsupportedNodeMessage();
+if (runtimeError) {
+    process.stderr.write(`${runtimeError}\n`);
+    process.exitCode = 1;
+}
+else {
+    void import("./index.js").catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`hara: failed to start: ${message}\n`);
+        process.exitCode = 1;
+    });
+}