@nanhara/hara 0.132.3 → 0.133.0

package/CHANGELOG.md

@@ -5,15 +5,59 @@ 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.132.3 — 2026-07-22 — immediate prompt-key routing and verified release carrier
+## 0.133.0 — 2026-07-22 — field-feedback closure: documents, web, recall, and setup
+
+- A new approval-gated `python` tool sends Python 3 source directly over stdin, so one-shot APIs such as
+  `python-docx` no longer require Hara to create and later execute a durable `.py` helper. Source size,
+  active-run cancellation, process-tree timeout, output redaction, workspace sandboxing, and protected-file
+  preflight remain enforced; the tool reports a focused prerequisite error when Python 3 is unavailable.
+- Existing user artifacts now keep their original path as the canonical output by default. Hara must not
+  invent “完整版”, “简版”, “new”, or similar copies unless the user explicitly requests a separate version.
+  Any temporary binary output used for atomic replacement must be removed on both success and failure.
+- Regression coverage executes Python through stdin, proves no `.py` file is left behind, verifies protected
+  files cannot be reached through the new input path, and pins the in-place/no-suffix/no-helper policy in the
+  agent system prompt. Upgrade with `npm i -g @nanhara/hara@0.133.0`.
+- The transitive `fast-uri` parser is pinned to 3.1.4, closing CVE-2026-16221/GHSA-v2hh-gcrm-f6hx's
+  backslash-authority host-confusion gap before URL policy and network consumers can disagree on a host.
+- `--proxy <url>` and `--lang <tag>` make the existing scoped web proxy and same-language behavior visible
+  at launch. Proxy credentials remain config/environment-only so they never enter the process list. A user
+  who explicitly refers to an older chat (for example “继续上次的任务”) now triggers bounded, audience-safe
+  `session_search` before the model turn; ordinary prompts and explicit opt-outs do not scan transcripts.
+- `web_fetch` identifies SPA shells and can retry with `render:true`. The render path requires computer-use
+  approval, launches an installed Chrome/Chromium/Edge with a fresh temporary profile, and forces every page,
+  redirect, and subresource request through a capped loopback proxy that re-applies public-IP/SSRF checks.
+  Browser cancellation, complete-DOM output, process-tree cleanup, and missing-browser failures are bounded.
+- Package installs can explicitly switch sources with `--registry npmmirror`, global `packageRegistry`, or
+  `bash.registry`. Registry values are injected as environment rather than shell text and reject credentials.
+  Hara does not silently replay an install against a public mirror, because private scopes and supply-chain
+  trust must be preserved; timeout guidance now points to the explicit public-dependency recovery.
+- A truly empty directory (including only `.DS_Store`/`.gitkeep`) no longer asks to generate `AGENTS.md`.
+  The Intel `--cwd` regression now disables update checks and uses a load-tolerant 30-second process ceiling;
+  product behavior remains checked by status/output rather than runner scheduling speed.
+- The TUI composer now keeps one stable Ink input subscription across renders. Rapid follow-up keys (including
+  Up/Down history navigation on slower terminals) can no longer land between paint and listener resubscription
+  and disappear; the handler still observes the latest draft through React 19 Effect Events.
+
+## 0.132.4 — 2026-07-22 — release-class Intel readiness handshakes
+
+- Non-Git `@path` completion now skips the bounded Git inventory subprocess when no repository marker
+  exists. Slow or contended machines keep the full synchronous budget for the actual filesystem walk instead
+  of occasionally returning an empty completion list.
+- TUI streaming and semantic-cancellation regressions now synchronize on concrete composer, render, provider,
+  and completion handshakes rather than fixed millisecond sleeps. Main-branch CI also runs the complete suite
+  on the same Intel macOS class used for native releases before any immutable version tag is created.
+- This patch carries the complete 0.132 feature set into the native and Desktop release train. Upgrade with
+  `npm i -g @nanhara/hara@0.132.4`.
+
+## 0.132.3 — 2026-07-22 — immediate prompt-key routing (npm published; native assets withheld)
 
 - TUI approval/select input now reads the live visible prompt and selection through stable refs. A key pressed
   immediately after the prompt paints can no longer hit the previous render's null-prompt closure and be
   swallowed; rapid arrow-plus-Enter input also uses the current selection before the next paint.
 - The confirmation regression waits for the visible prompt and then presses `y` without an arbitrary grace
   delay, covering the Node 24 CI failure directly. Remaining process-tree fixtures also wait for valid PID
-  content rather than file creation alone. This patch carries the complete 0.132 feature set into the native
-  and Desktop release train. Upgrade with `npm i -g @nanhara/hara@0.132.3`.
+  content rather than file creation alone. The npm package is valid, but native assembly was withheld after
+  the release-class Intel lane exposed additional completion/render fixture races; upgrade to 0.132.4 instead.
 
 ## 0.132.2 — 2026-07-22 — complete bounded native release gates (npm published; native assets withheld)
 

package/README.md

@@ -130,6 +130,8 @@ hara config set model    ...
 **Proxy for web tools in mainland/restricted networks** — only `web_fetch` and `web_search` use it:
 ```bash
 export HTTPS_PROXY=http://127.0.0.1:7890
+# or for one Hara launch (do not put credentials in command-line arguments):
+hara --proxy http://127.0.0.1:7890
 # or persist the same endpoint privately:
 hara config set proxy http://127.0.0.1:7890
 ```
@@ -138,6 +140,24 @@ organization enrollment, and chat gateways are not silently redirected. Even thr
 pins each DNS-approved public IP and rechecks redirects; authenticated proxy URLs are masked by
 `hara config get`.
 
+When `web_fetch` receives only a JavaScript SPA shell, it tells the agent to retry with `render:true`.
+That path asks for computer-use approval, uses an installed Chrome/Chromium/Edge with a fresh temporary
+profile, and routes every browser request back through the same private-IP/redirect guard. Set
+`HARA_BROWSER_PATH` only when the browser executable is installed in a non-standard location.
+
+**Package registry for slow/restricted npm networks** — switching is explicit, so Hara never sends a
+private scope to a public mirror without your decision:
+```bash
+hara --registry npmmirror             # this launch
+hara config set packageRegistry npmmirror  # persist globally
+```
+The `bash` tool also accepts `registry:"npmmirror"` for one npm/pnpm/yarn/bun install. Use `npmjs`,
+`npmmirror`, or a credential-free HTTP(S) registry URL; keep private-registry authentication in the package
+manager's normal credential store. `HARA_PACKAGE_REGISTRY` is the environment equivalent.
+
+Replies follow the latest user message's language by default. Use `hara --lang zh-CN` (or `en`) to pin one
+launch, and `hara --lang auto` to restore per-message matching.
+
 **Vision** — hara **auto-detects** whether your main model can see images. A vision model (Claude, gpt-4o,
 qwen-vl, glm-4v…) gets pasted images **inline**. For a **text-only** model (DeepSeek, coding models), set a
 describer — the "eyes" — and hara OCRs/describes each pasted image into text first:
@@ -402,7 +422,8 @@ agent.
 ### What it can do
 
 A streaming agentic loop with built-in tools — `read_file`, `write_file`, **`edit_file`** /
-**`apply_patch`** (surgical edits — single file, or **atomic multi-file** changes), `bash`, and
+**`apply_patch`** (surgical edits — single file, or **atomic multi-file** changes), direct-stdin
+**`python`** (one-shot APIs without helper scripts), `bash`, and
 read-only **`grep`** / **`glob`** / **`ls`** / **`web_fetch`** — behind a human-in-the-loop confirmation gate on the
 dangerous ones unless `-y`. Read-only tools run in parallel within a turn, and edits print a
 **colored diff** of what changed. Shell output streams live; press **Esc** to interrupt a running

package/dist/agent/loop.js

@@ -63,9 +63,16 @@ export function needsConfirm(kind, mode) {
         return kind === "exec";
     return true; // suggest: confirm edits and exec
 }
+export function replyLanguageInstruction(env = process.env) {
+    const requested = String(env.HARA_REPLY_LANGUAGE ?? "").trim();
+    if (/^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8}){0,3}$/u.test(requested)) {
+        return `Reply in ${requested} unless the user explicitly asks for another language;`;
+    }
+    return "Reply in the same language as the user's latest message unless they explicitly ask for another language;";
+}
 const HARA_SYSTEM = () => `You are hara, a coding agent running in the user's terminal.
-Be concise and direct. Reply in the same language as the user's latest message unless they explicitly
-ask for another language; keep code, commands, paths, and technical identifiers unchanged. Use the
+Be concise and direct. ${replyLanguageInstruction()} keep code, commands, paths, and technical identifiers
+unchanged. Use the
 provided tools to read files, edit/write files, and run shell
 commands. Prefer small, verifiable steps; edit existing files with edit_file rather than rewriting
 them whole. Batch INDEPENDENT tool calls in a single response — especially reads (read_file / grep /
@@ -76,6 +83,12 @@ grep/glob; don't read whole large files when a targeted search answers the quest
 grep to locate then read_file just that region with offset/limit — not the whole file. After a successful
 edit_file/write_file do NOT re-read the file to verify — the tool already applied and diffed the change;
 re-reading a big file after every edit is the slowest habit an agent can have.
+When editing an existing user artifact, including a DOCX, keep its original path as the canonical output
+and replace it in place by default. Do not invent suffix copies such as "完整版", "简版", or "new" unless
+the user explicitly asks to save a separate version. For one-shot Python library work such as python-docx,
+call the python tool with source directly; never write a durable helper .py file and then run it. If an
+atomic binary save needs a temporary output, remove it in finally/on failure and leave only the requested
+document when the task completes.
 When an attempt FAILS, never repeat it unchanged — read the error, form a hypothesis about the cause, and
 change something (arguments / approach / tool) before trying again. After two failed variants of the same
 approach, stop: re-plan from what you learned, or ask the user, stating concisely what you tried and what

package/dist/config.js

@@ -76,7 +76,7 @@ export function providerCatalog() {
         ...(PROVIDER_DEFAULTS[id].baseURL ? { defaultBaseURL: PROVIDER_DEFAULTS[id].baseURL } : {}),
     }));
 }
-export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "routeModel", "routeBaseURL", "routeApiKey", "guardian", "notify", "runTimeoutMs", "maxAgentRounds", "vimMode", "autoCompact", "fileCheckpoints", "updateCheck", "proxy", "fallbackModel", "fallbackProvider", "fallbackBaseURL", "fallbackApiKey", "reasoningEffort"];
+export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "routeModel", "routeBaseURL", "routeApiKey", "guardian", "notify", "runTimeoutMs", "maxAgentRounds", "vimMode", "autoCompact", "fileCheckpoints", "updateCheck", "proxy", "packageRegistry", "fallbackModel", "fallbackProvider", "fallbackBaseURL", "fallbackApiKey", "reasoningEffort"];
 export const REASONING_EFFORTS = ["off", "low", "medium", "high", "max"];
 export const APPROVAL_MODES = ["suggest", "auto-edit", "full-auto"];
 export const SANDBOX_MODES = ["off", "workspace-write", "read-only"];
@@ -493,6 +493,8 @@ export function loadConfig(opts = {}) {
     const fileCheckpoints = !(process.env.HARA_CHECKPOINTS === "0" || merged.fileCheckpoints === false || merged.fileCheckpoints === "false"); // default ON
     const updateCheck = !(process.env.HARA_UPDATE_CHECK === "0" || merged.updateCheck === false || merged.updateCheck === "false"); // default ON
     const proxy = typeof merged.proxy === "string" && merged.proxy.trim() ? merged.proxy.trim() : undefined;
+    const packageRegistry = nonBlankEnv(process.env.HARA_PACKAGE_REGISTRY)
+        ?? (typeof merged.packageRegistry === "string" && merged.packageRegistry.trim() ? merged.packageRegistry.trim() : undefined);
     const fallbackModel = nonBlankEnv(process.env.HARA_FALLBACK_MODEL) ?? merged.fallbackModel;
     const requestedFallbackProvider = nonBlankEnv(process.env.HARA_FALLBACK_PROVIDER) ?? merged.fallbackProvider;
     const fallbackProvider = isProviderId(requestedFallbackProvider) ? requestedFallbackProvider : undefined;
@@ -502,7 +504,7 @@ export function loadConfig(opts = {}) {
     const reasoningEffort = reasoningRaw && ["off", "low", "medium", "high", "max"].includes(reasoningRaw)
         ? reasoningRaw
         : undefined;
-    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, guardian, hooks, notify, runTimeoutMs, maxAgentRounds, vimMode, autoCompact, fileCheckpoints, updateCheck, proxy, fallbackModel, fallbackProvider, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: effectiveCwd };
+    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, guardian, hooks, notify, runTimeoutMs, maxAgentRounds, vimMode, autoCompact, fileCheckpoints, updateCheck, proxy, packageRegistry, fallbackModel, fallbackProvider, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: effectiveCwd };
 }
 export function providerEnvKey(provider) {
     return (PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic).envKey;

package/dist/context/agents-md.js

@@ -1,6 +1,6 @@
 // Project-context loading (AGENTS.md) — the cross-tool standard read by Codex/Claude Code/OpenClaw.
 // Walks up from cwd to the project root, concatenates AGENTS.md files, caps total size.
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { readModelContextBytePrefixSync } from "../fs-read.js";
 import { homeWorkspaceGuidance, isHomeWorkspace } from "./workspace-scope.js";
@@ -110,6 +110,23 @@ export function hasAgentsMd(cwd) {
     const root = findProjectRoot(cwd);
     return FILENAMES.some((n) => existsSync(join(root, n)));
 }
+/** An empty directory has nothing useful for the init agent to analyze. Do not interrupt first launch with
+ * an AGENTS.md offer until the user has created a project marker or at least one visible project file. */
+export function hasProjectContent(cwd) {
+    const root = findProjectRoot(cwd);
+    try {
+        return readdirSync(root, { withFileTypes: true }).some((entry) => {
+            if (ROOT_MARKERS.includes(entry.name))
+                return true;
+            if (entry.name === ".DS_Store" || entry.name === ".gitkeep")
+                return false;
+            return !entry.name.startsWith(".");
+        });
+    }
+    catch {
+        return false;
+    }
+}
 /** Prompt hara runs against itself to analyze the repo and write AGENTS.md. */
 export const INIT_PROMPT = "Explore this repository to understand it, then write a concise AGENTS.md at the project root.\n" +
     "Use read_file, bash (e.g. `ls`, `git ls-files`, `cat`), and write_file.\n" +

package/dist/exec/jobs.js

@@ -50,7 +50,7 @@ function ensureExitCleanup() {
     process.on("exit", killAllJobs); // sync; runs on normal quit so background jobs don't orphan
 }
 /** Start a background shell job; returns its id immediately. Output is captured to a capped tail buffer. */
-export function startJob(command, cwd, mode) {
+export function startJob(command, cwd, mode, env = {}) {
     ensureExitCleanup();
     const running = [...jobs.values()].filter((job) => job.status === "running" || job.terminationPending).length;
     if (running >= MAX_RUNNING_JOBS) {
@@ -59,7 +59,7 @@ export function startJob(command, cwd, mode) {
     pruneFinishedJobs(1);
     const { cmd, args } = shellCommand(command, cwd, mode);
     const processGroup = platform() !== "win32";
-    const child = spawn(cmd, args, { cwd, env: toolSubprocessEnv(), detached: processGroup });
+    const child = spawn(cmd, args, { cwd, env: toolSubprocessEnv(process.env, env), detached: processGroup });
     const job = {
         id: "j" + ++seq,
         // The raw command may contain an inline --token/KEY=value. It is used only for spawning above; every

package/dist/fs-walk.js

@@ -1,8 +1,8 @@
 // Shared filesystem walker — powers @file completion and the grep/glob tools.
 // Walks a directory tree, skipping noise dirs, capped so huge trees stay responsive.
-import { readdirSync, statSync } from "node:fs";
+import { lstatSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { opendir } from "node:fs/promises";
-import { join, relative, sep } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { execFile, execSync } from "node:child_process";
 import { fuzzyRank } from "./fuzzy.js";
 import { isSensitiveFilePath } from "./security/sensitive-files.js";
@@ -22,6 +22,37 @@ const DEFAULT_ASYNC_TIMEOUT_MS = 2_000;
 // interruptible. Keep them on a much tighter wall budget; agent/tool paths use the async APIs below.
 const DEFAULT_SYNC_TIMEOUT_MS = 250;
 const DEFAULT_YIELD_EVERY = 128;
+function gitMarkerOnPath(start) {
+    let dir = resolve(start);
+    for (let depth = 0; depth < 128; depth++) {
+        try {
+            lstatSync(join(dir, ".git"));
+            return true;
+        }
+        catch (error) {
+            // An unreadable or otherwise suspicious marker must still take the Git path. Only a definite
+            // absence permits the filesystem fallback to skip spawning Git.
+            if (error?.code !== "ENOENT")
+                return true;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+    return true;
+}
+function gitMarkerAbove(start) {
+    if (gitMarkerOnPath(start))
+        return true;
+    // Preserve worktree semantics when callers reach a repository through a symlinked project path.
+    try {
+        return gitMarkerOnPath(realpathSync.native(start));
+    }
+    catch {
+        return false;
+    }
+}
 function finiteLimit(value, fallback) {
     return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : fallback;
 }
@@ -228,6 +259,12 @@ export function listProjectFiles(root, cap = 8000) {
     if (recursiveRootContainsHome(root))
         return [];
     const startedAt = Date.now();
+    // On a non-repository directory, a contended `git ls-files` can consume the entire synchronous
+    // completion budget before the real filesystem walk starts. A bounded marker scan is sufficient to
+    // prove that Git cannot be authoritative here, leaving the budget for the user's actual files.
+    if (!gitMarkerAbove(root)) {
+        return walkFiles(root, cap, { timeoutMs: Math.max(0, DEFAULT_SYNC_TIMEOUT_MS - (Date.now() - startedAt)) });
+    }
     try {
         const out = execSync("git ls-files --cached --others --exclude-standard", {
             cwd: root,
@@ -288,6 +325,19 @@ export async function listProjectFilesAsync(root, options = {}) {
     if (cfg.maxEntries === 0)
         return result([], 0, 0, "entry_limit");
     const remaining = () => cfg.timeoutMs - (Date.now() - startedAt);
+    if (!gitMarkerAbove(root)) {
+        const timeoutMs = remaining();
+        if (timeoutMs <= 0)
+            return result([], 0, 0, "time_limit");
+        return walkFilesAsync(root, {
+            maxFiles: cfg.maxFiles,
+            maxDirectories: cfg.maxDirectories,
+            maxEntries: cfg.maxEntries,
+            timeoutMs,
+            signal: cfg.signal,
+            yieldEvery: cfg.yieldEvery,
+        });
+    }
     try {
         if (remaining() <= 0)
             return result([], 0, 0, "time_limit");

package/dist/index.js

@@ -56,6 +56,7 @@ import { listJobs, tailJob, killJob } from "./exec/jobs.js";
 import { readModelContextFileSync } from "./fs-read.js";
 import { MIN_NODE_VERSION, unsupportedNodeMessage } from "./runtime.js";
 import { redactKnownSecrets } from "./security/secrets.js";
+import { normalizePackageRegistry } from "./package-registry.js";
 /** Render the background-job list for /jobs (user-facing view of what the agent has running in the
  *  background — dev servers, watchers, long tasks). Mirrors codex/Claude-Code process visibility. */
 function renderBgJobs() {
@@ -71,7 +72,7 @@ function renderBgJobs() {
     return `Background jobs — /jobs tail <id> · /jobs kill <id>:\n${rows.join("\n")}`;
 }
 import { qwenDeviceLogin, loadQwenToken } from "./providers/qwen-oauth.js";
-import { loadAgentContext, hasAgentsMd, INIT_PROMPT, findProjectRoot } from "./context/agents-md.js";
+import { loadAgentContext, hasAgentsMd, hasProjectContent, INIT_PROMPT, findProjectRoot } from "./context/agents-md.js";
 import { homeWorkspaceActionError, discoverProjectWorkspaces, isUnsafeProjectWorkspace, resolveWorkspaceSwitch, suggestedProjectWorkspace, } from "./context/workspace-scope.js";
 import { getEmbedder } from "./search/embed.js";
 import { collectRepoChunksAsync, collectDirChunksAsync, buildIndex, indexPath, indexExists } from "./search/semindex.js";
@@ -96,7 +97,7 @@ import { scaffoldAssets, assetsDir, assetSearchRoots } from "./recall.js";
 import { c, out, statusLine } from "./ui.js";
 import * as bar from "./statusbar.js";
 import { nearest } from "./fuzzy.js";
-import "./tools/builtin.js"; // register read_file/write_file/bash
+import "./tools/builtin.js"; // register read_file/write_file/python/bash/job
 import "./tools/runtime.js"; // register tool_search/tool_result_read
 import "./tools/edit.js"; // register edit_file
 import "./tools/search.js"; // register grep/glob/ls
@@ -104,7 +105,7 @@ import "./tools/patch.js"; // register apply_patch
 import "./tools/web.js"; // register web_fetch
 import "./tools/agent.js"; // register agent (subagent spawn)
 import "./tools/memory.js"; // register memory_search/get/write/forget/skill_create
-import "./tools/session-search.js"; // register bounded cross-session transcript recall
+import { automaticSessionRecall } from "./tools/session-search.js"; // register + deterministic explicit-cue recall
 import "./tools/skill.js"; // register the skill loader tool
 import "./tools/codebase.js"; // register codebase_search (repo as a knowledge base)
 import "./tools/todo.js"; // register todo_write (inline task checklist)
@@ -1396,6 +1397,9 @@ program
     .option("--profile <id>", "use this identity profile for this run (personal / org id) — see `hara profile list`")
     .option("--overlay <name>", "apply a named config overlay from ~/.hara/config.json (legacy: --profile)")
     .option("--cwd <dir>", "run from this explicit project directory (alternative to cd)")
+    .option("--proxy <url>", "HTTP(S) proxy for web_fetch/web_search in this run (credentials belong in config/env)")
+    .option("--registry <url>", "package registry for installs in this run: npmjs, npmmirror, or an HTTP(S) URL")
+    .option("--lang <tag>", "reply language for this run, for example zh-CN or en (default: follow latest message)")
     .option("-c, --continue", "resume the most recent session in this directory")
     .option("--resume <id>", "resume a specific session by id")
     .option("--sandbox <mode>", "sandbox the shell: off | workspace-write | read-only");
@@ -1419,6 +1423,46 @@ program.hook("preAction", (thisCmd) => {
             process.exit(2);
         }
     }
+    const proxyFlag = thisCmd.opts().proxy;
+    if (proxyFlag) {
+        try {
+            const parsed = new URL(proxyFlag);
+            if (!(parsed.protocol === "http:" || parsed.protocol === "https:")
+                || parsed.pathname !== "/"
+                || parsed.search
+                || parsed.hash
+                || parsed.username
+                || parsed.password)
+                throw new Error("invalid or credential-bearing proxy URL");
+            process.env.HARA_WEB_PROXY = parsed.origin;
+        }
+        catch {
+            out(c.red("Cannot use --proxy: provide an HTTP(S) origin such as http://127.0.0.1:7890. Put authenticated proxy URLs in `hara config set proxy …` or HTTPS_PROXY so credentials do not enter the process list.\n"));
+            process.exit(2);
+        }
+    }
+    const languageFlag = thisCmd.opts().lang;
+    if (languageFlag) {
+        if (languageFlag === "auto")
+            delete process.env.HARA_REPLY_LANGUAGE;
+        else if (/^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8}){0,3}$/u.test(languageFlag)) {
+            process.env.HARA_REPLY_LANGUAGE = languageFlag;
+        }
+        else {
+            out(c.red("Cannot use --lang: provide a language tag such as zh-CN or en, or use auto.\n"));
+            process.exit(2);
+        }
+    }
+    const registryFlag = thisCmd.opts().registry;
+    if (registryFlag) {
+        try {
+            process.env.HARA_PACKAGE_REGISTRY = normalizePackageRegistry(registryFlag);
+        }
+        catch {
+            out(c.red("Cannot use --registry: provide npmjs, npmmirror, or an HTTP(S) registry URL without credentials/query/fragment.\n"));
+            process.exit(2);
+        }
+    }
     const flag = thisCmd.opts().profile;
     if (!flag)
         return;
@@ -3173,6 +3217,17 @@ config
             process.exit(1);
         }
     }
+    if (key === "packageRegistry") {
+        try {
+            value = normalizePackageRegistry(value) ?? "";
+            if (!value)
+                throw new Error("empty registry");
+        }
+        catch {
+            out(c.red("Invalid package registry. Use npmjs, npmmirror, or an HTTP(S) URL without credentials, query parameters, or a fragment.\n"));
+            process.exit(1);
+        }
+    }
     if (key === "runTimeoutMs") {
         const parsed = parseAgentRunTimeoutMs(value);
         if (parsed === undefined || parsed < MIN_AGENT_RUN_TIMEOUT_MS || parsed > MAX_AGENT_RUN_TIMEOUT_MS) {
@@ -3667,7 +3722,13 @@ program.action(async (opts) => {
             // Inbound images (gateway): the platform downloaded the user's photo(s) and passed their paths via env.
             // Let the agent actually SEE them — attached inline for a vision-capable main model, else described via the
             // visionModel sidecar and folded into the message (text-only models can't take image blocks).
-            const userText = await expandMentionsAsync(String(opts.print), cwd) + (schemaObj ? STRUCTURED_INSTRUCTION : "");
+            const printText = String(opts.print);
+            const automaticRecall = meta
+                ? await automaticSessionRecall(printText, { cwd, sessionId: meta.id })
+                : "";
+            const userText = (automaticRecall ? `${automaticRecall}\n\n---\n\n` : "")
+                + await expandMentionsAsync(printText, cwd)
+                + (schemaObj ? STRUCTURED_INSTRUCTION : "");
             const inboundImgs = (process.env.HARA_GATEWAY_IMAGES ?? "")
                 .split("\n")
                 .map((s) => s.trim())
@@ -3910,7 +3971,7 @@ program.action(async (opts) => {
     // First-run AGENTS.md offer — classic REPL only. In TUI mode we must NOT call rl.question before ink
     // mounts: a readline question puts stdin in a state ink can't read from, leaving the input box dead
     // (the TUI shows a `/init` tip instead, below). See the `tip` in the runTui header.
-    if (!homeWorkspace && !hasAgentsMd(cwd) && !useTui) {
+    if (!homeWorkspace && !hasAgentsMd(cwd) && hasProjectContent(cwd) && !useTui) {
         const ans = (await rl.question(`${c.dim("No AGENTS.md here — analyze this project and create one?")} ${c.dim("[Y/n]")} `)).trim().toLowerCase();
         if (ans === "" || ans.startsWith("y")) {
             out(c.dim("Analyzing project…\n"));
@@ -4565,7 +4626,7 @@ program.action(async (opts) => {
         // First-run AGENTS.md offer — via a tiny ink prompt, NOT readline. A readline question before the
         // main TUI leaves stdin unreadable by ink (dead input box); ink cleans up on unmount, so the TUI
         // mounted right after gets working input. Runs before mount, like the classic path.
-        if (!homeWorkspace && !hasAgentsMd(cwd)) {
+        if (!homeWorkspace && !hasAgentsMd(cwd) && hasProjectContent(cwd)) {
             if (await askConfirm("No AGENTS.md here — analyze this project and create one?")) {
                 out(c.dim("Analyzing project…\n"));
                 try {
@@ -5183,7 +5244,9 @@ program.action(async (opts) => {
                     const planImg = await resolveImages(images, h);
                     if (planImg.skip)
                         return;
-                    const planContent = (recalledContext ? `${recalledContext}\n\n---\n\n` : "") + await expandMentionsAsync(line, cwd, { signal: h.signal }) + (planImg.extraText ?? "");
+                    const automaticRecall = await automaticSessionRecall(line, { cwd, sessionId: meta.id, signal: h.signal });
+                    const recallPrefix = [recalledContext, automaticRecall].filter(Boolean).join("\n\n");
+                    const planContent = (recallPrefix ? `${recallPrefix}\n\n---\n\n` : "") + await expandMentionsAsync(line, cwd, { signal: h.signal }) + (planImg.extraText ?? "");
                     const executionContext = beginExecution(line);
                     if (!executionContext)
                         return;
@@ -5299,7 +5362,9 @@ program.action(async (opts) => {
                 const ri = await resolveImages(images, h);
                 if (ri.skip)
                     return;
-                const userContent = (recalledContext ? `${recalledContext}\n\n---\n\n` : "") + await expandMentionsAsync(line, cwd, { signal: h.signal }) + (ri.extraText ?? "");
+                const automaticRecall = await automaticSessionRecall(line, { cwd, sessionId: meta.id, signal: h.signal });
+                const recallPrefix = [recalledContext, automaticRecall].filter(Boolean).join("\n\n");
+                const userContent = (recallPrefix ? `${recallPrefix}\n\n---\n\n` : "") + await expandMentionsAsync(line, cwd, { signal: h.signal }) + (ri.extraText ?? "");
                 recalledContext = "";
                 const executionContext = beginExecution(line);
                 if (!executionContext)
@@ -5440,7 +5505,9 @@ program.action(async (opts) => {
             continue;
         }
         line = inlineLeadingPath(line, existsSync); // leading dropped file path → @-mention so it's read in
-        const userContent = (recalledContext ? `${recalledContext}\n\n---\n\n` : "") + await expandMentionsAsync(line, cwd);
+        const automaticRecall = await automaticSessionRecall(line, { cwd, sessionId: meta.id });
+        const recallPrefix = [recalledContext, automaticRecall].filter(Boolean).join("\n\n");
+        const userContent = (recallPrefix ? `${recallPrefix}\n\n---\n\n` : "") + await expandMentionsAsync(line, cwd);
         recalledContext = "";
         const recoveredClassicSteering = consumePendingTaskSteering(task);
         if (recoveredClassicSteering) {

package/dist/package-registry.js

@@ -0,0 +1,43 @@
+/** Explicit package-registry routing for npm/pnpm/yarn/bun installs. Registry switching is user-selected:
+ * silently replaying an install against a public mirror can break private scopes and changes the software
+ * supply-chain trust boundary. */
+export function normalizePackageRegistry(value) {
+    const raw = String(value ?? "").trim();
+    if (!raw)
+        return undefined;
+    const expanded = raw === "npmjs"
+        ? "https://registry.npmjs.org/"
+        : raw === "npmmirror"
+            ? "https://registry.npmmirror.com/"
+            : raw;
+    let url;
+    try {
+        url = new URL(expanded);
+    }
+    catch {
+        throw new Error("package registry must be npmjs, npmmirror, or an absolute HTTP(S) URL");
+    }
+    if ((url.protocol !== "http:" && url.protocol !== "https:")
+        || !url.hostname
+        || url.username
+        || url.password
+        || url.search
+        || url.hash) {
+        throw new Error("package registry must be an HTTP(S) URL without credentials, query parameters, or a fragment");
+    }
+    if (!url.pathname.endsWith("/"))
+        url.pathname += "/";
+    return url.href;
+}
+export function commandHasPackageRegistry(command) {
+    return /(?:^|\s)--registry(?:=|\s|$)/iu.test(command);
+}
+/** The common npm config variable is honored by npm and pnpm; explicit Yarn/Bun variables cover their
+ * modern clients too. Values are injected as environment, never interpolated into a shell command. */
+export function packageRegistryEnv(registry) {
+    return {
+        NPM_CONFIG_REGISTRY: registry,
+        YARN_NPM_REGISTRY_SERVER: registry,
+        BUN_CONFIG_REGISTRY: registry,
+    };
+}

package/dist/tools/all.js

@@ -2,7 +2,7 @@
 // imports itself; library entries (serve/server.ts, future embedders) import THIS so the registry is
 // never empty when runAgent plans a turn — an unregistered tool is silently unplannable, which shows up
 // as "the model called write_file and nothing happened".
-import "./builtin.js"; // read_file / write_file / bash / job
+import "./builtin.js"; // read_file / write_file / python / bash / job
 import "./runtime.js"; // tool_search / tool_result_read
 import "./edit.js"; // edit_file
 import "./search.js"; // grep / glob / ls