@zhijiewang/openharness 2.31.0 → 2.33.0

package/README.md

@@ -773,6 +773,14 @@ Create `.oh/RULES.md` in any repo (or run `oh init`):
 
 Rules load automatically into every session.
 
+openHarness also reads any of the following project-instruction files if present (additive, parent-first):
+
+- `CLAUDE.md` (Anthropic convention) — and hierarchical `CLAUDE.md` from parent dirs, plus `~/.claude/CLAUDE.md` for user-global
+- `AGENTS.md` ([agents.md cross-tool standard](https://agents.md/), used by Codex / Cursor / Copilot / Cline / Aider) — same parent-first walk
+- `CLAUDE.local.md` (gitignored personal overrides)
+
+If a repo has `AGENTS.md` already configured for another agent, openHarness picks it up unchanged — no migration step needed.
+
 ## Skills & Plugins
 
 ### Skills

package/README.zh-CN.md

@@ -772,6 +772,14 @@ description: 专注的代码审查模式
 
 规则会自动加载到每次会话中。
 
+openHarness 还会自动读取以下项目指令文件（如果存在，按父目录优先合并加载）：
+
+- `CLAUDE.md`（Anthropic 约定）—— 含从父目录到项目根的层级 `CLAUDE.md` 文件，以及全局 `~/.claude/CLAUDE.md`
+- `AGENTS.md`（[agents.md 跨工具标准](https://agents.md/)，被 Codex / Cursor / Copilot / Cline / Aider 共同采用）—— 同样的父目录优先扫描
+- `CLAUDE.local.md`（gitignore 的个人覆盖）
+
+如果仓库已为其他 agent 配置了 `AGENTS.md`，openHarness 直接读取，无需迁移。
+
 ## 技能与插件
 
 ### 技能

package/dist/harness/config.d.ts

@@ -214,6 +214,34 @@ export type OhConfig = {
         rateLimit?: number;
         allowedTools?: string[];
     };
+    /**
+     * Opt-in OS-level sandbox via `@anthropic-ai/sandbox-runtime` (an optional
+     * dependency). When `enabled: true`, BashTool wraps every command in
+     * bubblewrap (Linux) or sandbox-exec (macOS) plus a domain-allowlist
+     * network proxy. Windows isn't supported by the package — the wrap is a
+     * silent passthrough there. Off by default; users opt in via config or the
+     * `--sandbox` CLI flag.
+     *
+     * `network.allowedDomains` is the proxy allowlist (e.g. `["github.com",
+     * "registry.npmjs.org"]`); `deniedDomains` blocks specific hosts before
+     * the allowlist applies. `filesystem.allowWrite` defaults to `[cwd]` —
+     * the sandbox can write to the project tree but nowhere else.
+     *
+     * See `src/harness/sandbox-runtime.ts` and SECURITY.md for the full
+     * threat-model boundary.
+     */
+    sandbox?: {
+        enabled?: boolean;
+        network?: {
+            allowedDomains?: string[];
+            deniedDomains?: string[];
+        };
+        filesystem?: {
+            allowWrite?: string[];
+            denyWrite?: string[];
+            denyRead?: string[];
+        };
+    };
     /**
      * Environment variables injected into child processes spawned by the harness —
      * Bash/Monitor/PowerShell tool executions and MCP server subprocesses. Useful

package/dist/harness/memory.d.ts

@@ -31,10 +31,10 @@ export type MemoryEntry = {
 export declare function loadMemories(): MemoryEntry[];
 /** Build a system prompt section from loaded memories (capped at MEMORY_PROMPT_MAX_CHARS) */
 export declare function memoriesToPrompt(memories: MemoryEntry[]): string;
-/** A single CLAUDE.md source with its resolved content (imports inlined). */
+/** A single project-instructions source with its resolved content (imports inlined). */
 export type ClaudeMdEntry = {
     path: string;
-    source: "project" | "project-local" | "user" | "claude-dir";
+    source: "project" | "project-local" | "user" | "claude-dir" | "agents-md";
     content: string;
 };
 /**
@@ -47,11 +47,17 @@ export type ClaudeMdEntry = {
  */
 export declare function resolveClaudeMdImports(content: string, baseDir: string, hopsLeft?: number): string;
 /**
- * Load the hierarchical CLAUDE.md set in the order Anthropic documents:
- *   1. `./.claude/CLAUDE.md` (project, checked in)
+ * Load hierarchical project-instruction files. Order:
+ *   1. `./.claude/CLAUDE.md` (project, Anthropic convention)
  *   2. `./CLAUDE.md` (project, checked in)
- *   3. `./CLAUDE.local.md` (project, gitignored)
- *   4. `~/.claude/CLAUDE.md` (user-global)
+ *   3. `./AGENTS.md` (project, AGENTS.md cross-tool standard — agents.md)
+ *   4. `./CLAUDE.local.md` (project, gitignored)
+ *   5. `~/.claude/CLAUDE.md` (user-global)
+ *
+ * AGENTS.md is read alongside CLAUDE.md so OH "just works" in the 60k+ repos
+ * already configured for cross-agent compatibility (Codex / Cursor / Copilot
+ * / Cline / Aider all read AGENTS.md). Both layers concatenate into the
+ * system prompt; if both files exist, both contribute.
  *
  * Each file is read, `@imports` are resolved, and the results are returned in
  * load order. Missing files are skipped. The caller can format these into the
@@ -61,8 +67,11 @@ export declare function resolveClaudeMdImports(content: string, baseDir: string,
  */
 export declare function loadClaudeMdHierarchy(root?: string): ClaudeMdEntry[];
 /**
- * Render loaded CLAUDE.md entries as a system-prompt block. Empty when no
- * CLAUDE.md files exist — caller should concatenate alongside `memoriesToPrompt`.
+ * Render loaded project-instruction entries as a system-prompt block. Empty
+ * when no source files exist — caller should concatenate alongside
+ * `memoriesToPrompt`. Header is generic ("Project instructions") since both
+ * CLAUDE.md and AGENTS.md feed in; the per-entry `source:` comment
+ * disambiguates which file each section came from.
  */
 export declare function claudeMdToPrompt(entries: ClaudeMdEntry[]): string;
 /** Save a memory entry to the project memory directory */

package/dist/harness/memory.js

@@ -130,11 +130,17 @@ function readClaudeMdIfExists(path, source) {
     }
 }
 /**
- * Load the hierarchical CLAUDE.md set in the order Anthropic documents:
- *   1. `./.claude/CLAUDE.md` (project, checked in)
+ * Load hierarchical project-instruction files. Order:
+ *   1. `./.claude/CLAUDE.md` (project, Anthropic convention)
  *   2. `./CLAUDE.md` (project, checked in)
- *   3. `./CLAUDE.local.md` (project, gitignored)
- *   4. `~/.claude/CLAUDE.md` (user-global)
+ *   3. `./AGENTS.md` (project, AGENTS.md cross-tool standard — agents.md)
+ *   4. `./CLAUDE.local.md` (project, gitignored)
+ *   5. `~/.claude/CLAUDE.md` (user-global)
+ *
+ * AGENTS.md is read alongside CLAUDE.md so OH "just works" in the 60k+ repos
+ * already configured for cross-agent compatibility (Codex / Cursor / Copilot
+ * / Cline / Aider all read AGENTS.md). Both layers concatenate into the
+ * system prompt; if both files exist, both contribute.
  *
  * Each file is read, `@imports` are resolved, and the results are returned in
  * load order. Missing files are skipped. The caller can format these into the
@@ -146,6 +152,7 @@ export function loadClaudeMdHierarchy(root = ".") {
     const candidates = [
         [join(root, ".claude", "CLAUDE.md"), "claude-dir"],
         [join(root, "CLAUDE.md"), "project"],
+        [join(root, "AGENTS.md"), "agents-md"],
         [join(root, "CLAUDE.local.md"), "project-local"],
         [join(homedir(), ".claude", "CLAUDE.md"), "user"],
     ];
@@ -162,13 +169,16 @@ export function loadClaudeMdHierarchy(root = ".") {
     return entries;
 }
 /**
- * Render loaded CLAUDE.md entries as a system-prompt block. Empty when no
- * CLAUDE.md files exist — caller should concatenate alongside `memoriesToPrompt`.
+ * Render loaded project-instruction entries as a system-prompt block. Empty
+ * when no source files exist — caller should concatenate alongside
+ * `memoriesToPrompt`. Header is generic ("Project instructions") since both
+ * CLAUDE.md and AGENTS.md feed in; the per-entry `source:` comment
+ * disambiguates which file each section came from.
  */
 export function claudeMdToPrompt(entries) {
     if (entries.length === 0)
         return "";
-    const parts = ["# Project instructions (CLAUDE.md)"];
+    const parts = ["# Project instructions"];
     for (const e of entries) {
         parts.push(`<!-- source: ${e.source} (${e.path}) -->`);
         parts.push(e.content.trim());

package/dist/harness/rules.d.ts

@@ -2,10 +2,14 @@
  * Rules system — load project and global rules into agent context.
  * Discovery order:
  *   1. ~/.oh/global-rules/*.md
- *   2. CLAUDE.md files from parent directories down to project root (hierarchical)
+ *   2. CLAUDE.md / AGENTS.md files from parent directories down to project root (hierarchical)
  *   3. .oh/RULES.md
  *   4. .oh/rules/*.md
  *   5. CLAUDE.local.md (gitignored personal overrides)
+ *
+ * AGENTS.md (https://agents.md/) is read alongside CLAUDE.md at every level
+ * of the hierarchy so OH "just works" in repos already configured for the
+ * cross-tool standard (Codex, Cursor, Copilot, Cline, Aider all read it).
  */
 export declare function loadRules(projectPath?: string): string[];
 export declare function loadRulesAsPrompt(projectPath?: string): string;

package/dist/harness/rules.js

@@ -2,10 +2,14 @@
  * Rules system — load project and global rules into agent context.
  * Discovery order:
  *   1. ~/.oh/global-rules/*.md
- *   2. CLAUDE.md files from parent directories down to project root (hierarchical)
+ *   2. CLAUDE.md / AGENTS.md files from parent directories down to project root (hierarchical)
  *   3. .oh/RULES.md
  *   4. .oh/rules/*.md
  *   5. CLAUDE.local.md (gitignored personal overrides)
+ *
+ * AGENTS.md (https://agents.md/) is read alongside CLAUDE.md at every level
+ * of the hierarchy so OH "just works" in repos already configured for the
+ * cross-tool standard (Codex, Cursor, Copilot, Cline, Aider all read it).
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -13,10 +17,13 @@ import { dirname, join, parse as parsePath, resolve } from "node:path";
 import { gitRoot as getGitRoot } from "../git/index.js";
 const OH_HOME = join(homedir(), ".oh");
 /**
- * Walk from git root (or home) down to `projectRoot`, collecting CLAUDE.md files.
- * Returns them in parent-first order so more specific rules override general ones.
+ * Walk from git root (or home) down to `projectRoot`, collecting CLAUDE.md
+ * and AGENTS.md files at every level. Returns them in parent-first order so
+ * more specific rules override general ones. Within a single directory,
+ * CLAUDE.md is read before AGENTS.md (Anthropic-specific guidance first,
+ * then the cross-tool standard layer).
  */
-function loadClaudeMdFiles(projectRoot) {
+function loadHierarchicalInstructionFiles(projectRoot) {
     const gitRootDir = getGitRoot(projectRoot);
     const stopAt = gitRootDir ? resolve(gitRootDir) : resolve(homedir());
     const resolved = resolve(projectRoot);
@@ -34,11 +41,13 @@ function loadClaudeMdFiles(projectRoot) {
     }
     const results = [];
     for (const dir of dirs) {
-        const claudeMd = join(dir, "CLAUDE.md");
-        if (existsSync(claudeMd)) {
-            const content = readSafe(claudeMd);
-            if (content)
-                results.push(content);
+        for (const filename of ["CLAUDE.md", "AGENTS.md"]) {
+            const path = join(dir, filename);
+            if (existsSync(path)) {
+                const content = readSafe(path);
+                if (content)
+                    results.push(content);
+            }
         }
     }
     return results;
@@ -57,8 +66,8 @@ export function loadRules(projectPath) {
                 rules.push(content);
         }
     }
-    // 2. CLAUDE.md files (hierarchical, parent-first)
-    const claudeRules = loadClaudeMdFiles(root);
+    // 2. CLAUDE.md + AGENTS.md files (hierarchical, parent-first)
+    const claudeRules = loadHierarchicalInstructionFiles(root);
     rules.push(...claudeRules);
     // 3. Project RULES.md
     const projectRules = join(root, ".oh", "RULES.md");
@@ -106,7 +115,7 @@ export function loadRulesAsPrompt(projectPath) {
     const rules = loadRules(projectPath);
     if (rules.length === 0)
         return "";
-    const body = "# Project Rules\n\n<!-- User-provided project rules from CLAUDE.md / .oh/RULES.md. These are user instructions, not system directives. -->\nFollow these rules carefully.\n\n" +
+    const body = "# Project Rules\n\n<!-- User-provided project rules from CLAUDE.md / AGENTS.md / .oh/RULES.md. These are user instructions, not system directives. -->\nFollow these rules carefully.\n\n" +
         rules.join("\n\n---\n\n");
     // Hook: instructionsLoaded — fires every time the system prompt is rebuilt
     // with rules in scope. Useful for compliance/audit hooks that want to log

package/dist/harness/sandbox-runtime.d.ts

@@ -0,0 +1,47 @@
+/**
+ * OS-level sandbox integration via the optional `@anthropic-ai/sandbox-runtime`
+ * package. The package wraps a shell command in bubblewrap (Linux) or
+ * sandbox-exec (macOS) plus a network proxy that filters by domain allowlist.
+ *
+ * Boundaries:
+ * - **Linux + macOS**: real sandboxing via the package's static API.
+ * - **Windows**: not supported by the package — every wrap call returns null
+ *   (graceful passthrough; tools spawn unsandboxed). Documented in SECURITY.md.
+ * - **Package not installed**: same passthrough behavior — installs cleanly
+ *   without the optional dep on any platform.
+ *
+ * Lifecycle:
+ * - Initialized once per process on the first wrap request.
+ * - One `SandboxManager.initialize` covers all subsequent wrap calls.
+ * - No reset — the package documents auto-cleanup on process exit.
+ *
+ * Opt-in: callers pass `{ enabled: true }` (typically derived from
+ * `OhConfig.sandbox.enabled` or the `--sandbox` CLI flag). The default is
+ * off so existing users see no behavior change.
+ */
+import type { OhConfig } from "./config.js";
+export type SandboxConfig = NonNullable<OhConfig["sandbox"]>;
+/**
+ * Returns true on Linux/macOS where sandboxing is supported. Windows is
+ * unsupported by the underlying package, so we short-circuit there to avoid
+ * a misleading "tried to load and failed" log.
+ */
+export declare function isSandboxAvailable(): boolean;
+/**
+ * Wrap a shell command for sandboxed execution.
+ *
+ * Returns the wrapped command (a single shell string suitable for
+ * `spawn(cmd, { shell: "/bin/bash" })`) when sandboxing is enabled and
+ * available. Returns null in every other case — Windows, missing package,
+ * disabled config, init failure — so the caller falls through to the
+ * unsandboxed code path unchanged.
+ */
+export declare function wrapForSandbox(command: string, config: SandboxConfig): Promise<string | null>;
+/**
+ * Test-only: reset the cached init promise so unit tests can re-init with
+ * different configs.
+ *
+ * @internal
+ */
+export declare function _resetSandboxForTest(): void;
+//# sourceMappingURL=sandbox-runtime.d.ts.map

package/dist/harness/sandbox-runtime.js

@@ -0,0 +1,100 @@
+/**
+ * OS-level sandbox integration via the optional `@anthropic-ai/sandbox-runtime`
+ * package. The package wraps a shell command in bubblewrap (Linux) or
+ * sandbox-exec (macOS) plus a network proxy that filters by domain allowlist.
+ *
+ * Boundaries:
+ * - **Linux + macOS**: real sandboxing via the package's static API.
+ * - **Windows**: not supported by the package — every wrap call returns null
+ *   (graceful passthrough; tools spawn unsandboxed). Documented in SECURITY.md.
+ * - **Package not installed**: same passthrough behavior — installs cleanly
+ *   without the optional dep on any platform.
+ *
+ * Lifecycle:
+ * - Initialized once per process on the first wrap request.
+ * - One `SandboxManager.initialize` covers all subsequent wrap calls.
+ * - No reset — the package documents auto-cleanup on process exit.
+ *
+ * Opt-in: callers pass `{ enabled: true }` (typically derived from
+ * `OhConfig.sandbox.enabled` or the `--sandbox` CLI flag). The default is
+ * off so existing users see no behavior change.
+ */
+// Cached, lazy-initialized handle. We deliberately don't expose this — callers
+// only see `wrapForSandbox` / `isSandboxAvailable` / `resetSandboxForTest`.
+let _initPromise = null;
+/**
+ * Returns true on Linux/macOS where sandboxing is supported. Windows is
+ * unsupported by the underlying package, so we short-circuit there to avoid
+ * a misleading "tried to load and failed" log.
+ */
+export function isSandboxAvailable() {
+    return process.platform === "linux" || process.platform === "darwin";
+}
+async function loadAndInitialize(config) {
+    if (!isSandboxAvailable())
+        return null;
+    let mod;
+    try {
+        mod = (await import("@anthropic-ai/sandbox-runtime"));
+    }
+    catch {
+        // Optional dep not installed — graceful passthrough.
+        return null;
+    }
+    try {
+        await mod.SandboxManager.initialize({
+            network: {
+                allowedDomains: config.network?.allowedDomains ?? [],
+                deniedDomains: config.network?.deniedDomains ?? [],
+            },
+            filesystem: {
+                allowWrite: config.filesystem?.allowWrite ?? [process.cwd()],
+                denyWrite: config.filesystem?.denyWrite ?? [],
+                denyRead: config.filesystem?.denyRead ?? [],
+            },
+        });
+    }
+    catch {
+        // Init can fail when bubblewrap / sandbox-exec aren't installed, or when
+        // the user's profile rejects the proxy ports. Falling back to passthrough
+        // is correct — opting in promised "use sandbox if you can," not "fail
+        // closed" — that's a separate `requireSandbox` mode for a future revision.
+        return null;
+    }
+    return mod;
+}
+/**
+ * Wrap a shell command for sandboxed execution.
+ *
+ * Returns the wrapped command (a single shell string suitable for
+ * `spawn(cmd, { shell: "/bin/bash" })`) when sandboxing is enabled and
+ * available. Returns null in every other case — Windows, missing package,
+ * disabled config, init failure — so the caller falls through to the
+ * unsandboxed code path unchanged.
+ */
+export async function wrapForSandbox(command, config) {
+    if (!config.enabled)
+        return null;
+    if (!_initPromise) {
+        _initPromise = loadAndInitialize(config);
+    }
+    const mod = await _initPromise;
+    if (!mod)
+        return null;
+    try {
+        return await mod.SandboxManager.wrapWithSandbox(command);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Test-only: reset the cached init promise so unit tests can re-init with
+ * different configs.
+ *
+ * @internal
+ */
+export function _resetSandboxForTest() {
+    _initPromise = null;
+}
+//# sourceMappingURL=sandbox-runtime.js.map

package/dist/tools/BashTool/index.js

@@ -1,5 +1,7 @@
 import { spawn } from "node:child_process";
 import { z } from "zod";
+import { readOhConfig } from "../../harness/config.js";
+import { wrapForSandbox } from "../../harness/sandbox-runtime.js";
 import { safeEnv } from "../../utils/safe-env.js";
 const inputSchema = z.object({
     command: z.string(),
@@ -21,12 +23,30 @@ export const BashTool = {
     isConcurrencySafe() {
         return false;
     },
-    call(input, context) {
+    async call(input, context) {
         // input.timeout is in seconds; convert to ms. Default 120s.
         const timeoutMs = Math.min((input.timeout ?? 120) * 1000, MAX_TIMEOUT);
         const isWin = process.platform === "win32";
-        const shell = isWin ? "cmd.exe" : "/bin/bash";
-        const shellArgs = isWin ? ["/c", input.command] : ["-c", input.command];
+        // Optional OS-level sandbox via @anthropic-ai/sandbox-runtime. Returns null
+        // when disabled / on Windows / when the optional dep isn't installed —
+        // caller falls back to the existing unsandboxed spawn unchanged.
+        const sandboxCfg = readOhConfig()?.sandbox;
+        const wrappedCommand = sandboxCfg ? await wrapForSandbox(input.command, sandboxCfg) : null;
+        let shell;
+        let shellArgs;
+        let extraSpawnOpts = {};
+        if (wrappedCommand) {
+            // sandbox-runtime returns a shell-string. Pin the shell to /bin/bash so
+            // the surrounding command syntax (heredocs, $((...)) etc.) keeps working
+            // — `shell: true` would default to /bin/sh on Linux.
+            shell = wrappedCommand;
+            shellArgs = [];
+            extraSpawnOpts = { shell: "/bin/bash" };
+        }
+        else {
+            shell = isWin ? "cmd.exe" : "/bin/bash";
+            shellArgs = isWin ? ["/c", input.command] : ["-c", input.command];
+        }
         // Background execution: spawn and return immediately
         if (input.run_in_background) {
             const bgId = Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
@@ -35,9 +55,13 @@ export const BashTool = {
                 env: safeEnv(),
                 stdio: ["ignore", "pipe", "pipe"],
                 detached: false,
+                ...extraSpawnOpts,
             });
             let stdout = "";
             let stderr = "";
+            // stdio is fixed to ["ignore", "pipe", "pipe"] above, so stdout/stderr
+            // are always streams. Adding `...extraSpawnOpts` widens the spawn
+            // overload's return type to potentially-null pipes; assert non-null.
             proc.stdout.on("data", (chunk) => {
                 stdout += chunk.toString();
             });
@@ -76,11 +100,15 @@ export const BashTool = {
                 cwd: context.workingDir,
                 env: safeEnv(),
                 stdio: ["ignore", "pipe", "pipe"],
+                ...extraSpawnOpts,
             });
             const timer = setTimeout(() => {
                 killed = true;
                 proc.kill("SIGTERM");
             }, timeoutMs);
+            // stdio: ["ignore", "pipe", "pipe"] is set above — pipes are always
+            // present here; the spread of extraSpawnOpts just widens the return
+            // type. Non-null asserts are safe.
             proc.stdout.on("data", (chunk) => {
                 const text = chunk.toString();
                 stdout += text;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhijiewang/openharness",
-  "version": "2.31.0",
+  "version": "2.33.0",
   "description": "Open-source terminal coding agent. Works with any LLM.",
   "type": "module",
   "bin": {
@@ -91,6 +91,7 @@
   },
   "homepage": "https://github.com/zhijiewong/openharness#readme",
   "optionalDependencies": {
+    "@anthropic-ai/sandbox-runtime": "^0.0.49",
     "@napi-rs/keyring": "^1.2.0",
     "sharp": "^0.34.5"
   }