@zhijiewang/openharness 2.35.0 → 2.37.0

package/README.md

@@ -563,6 +563,19 @@ Agent({ subagent_type: 'architect', prompt: 'Plan a migration from option A to o
 Agent({ subagent_type: 'editor', prompt: '<paste plan>' })
 ```
 
+### Sub-agent permission isolation
+
+Each `Agent` call accepts a `permission_mode` override that **narrows** the parent's permission mode (never loosens it). Useful when running in `trust` and you want a subagent's review/audit pass to stay strictly read-only:
+
+```
+Agent({ subagent_type: 'code-reviewer', prompt: '...', permission_mode: 'plan' })
+Agent({ subagent_type: 'security-auditor', prompt: '...', permission_mode: 'deny' })
+```
+
+If a less-restrictive mode is requested (e.g. parent is `ask`, subagent requests `trust`), the harness silently clamps to the parent — a model can never use a sub-agent to escape user-approval gates.
+
+**Read-only roles default to `plan` automatically.** `code-reviewer`, `evaluator`, `security-auditor`, `architect`, and `planner` ship with `permissionMode: 'plan'` — spawn them under any parent and they're statically read-only, no `permission_mode` override needed. Markdown-defined agents in `.oh/agents/*.md` can set their own default with `permissionMode: plan` (or `permission-mode: plan`) frontmatter.
+
 ## Headless Mode
 
 Run a single prompt without interactive UI — perfect for CI/CD and scripting:

package/README.zh-CN.md

@@ -563,6 +563,19 @@ Agent({ subagent_type: 'architect', prompt: 'Plan a migration from option A to o
 Agent({ subagent_type: 'editor', prompt: '<paste plan>' })
 ```
 
+### 子代理的权限隔离
+
+`Agent` 调用支持 `permission_mode` 参数，**只能收紧不能放宽**父级的权限模式。当父代理跑在 `trust` 但你希望某个评审/审计子代理保持只读时尤其有用：
+
+```
+Agent({ subagent_type: 'code-reviewer', prompt: '...', permission_mode: 'plan' })
+Agent({ subagent_type: 'security-auditor', prompt: '...', permission_mode: 'deny' })
+```
+
+如果请求的模式比父级更宽松（比如父级 `ask`、子代理请求 `trust`），harness 会静默回退到父级的模式 —— 模型永远不能借助子代理绕过用户的批准门。
+
+**只读角色自动默认 `plan` 模式。** `code-reviewer`、`evaluator`、`security-auditor`、`architect`、`planner` 内置 `permissionMode: 'plan'` —— 在任何父级权限下启动它们都是静态只读，无需在调用处再传 `permission_mode`。`.oh/agents/*.md` 里自定义的 markdown agent 也可以在 frontmatter 写 `permissionMode: plan`（或 `permission-mode: plan`）来设默认。
+
 ## 无头模式
 
 跑一次提示词，不走交互 UI —— 适合 CI/CD 和脚本化：

package/dist/agents/roles.d.ts

@@ -21,6 +21,20 @@ export type AgentRole = {
     model?: string;
     /** Isolation mode for sub-agent execution. Default: inherits parent. */
     isolation?: "none" | "worktree";
+    /**
+     * Default permission mode for this role. When the AgentTool caller doesn't
+     * pass `permission_mode`, this value is used. Always passes through the
+     * narrowing-only safety clamp (v2.36): a role marked `plan` can't loosen
+     * the parent's stricter mode, only set the floor when the parent is looser.
+     *
+     * Use cases:
+     *   - `plan` for read-only roles (code-reviewer, evaluator, security-auditor,
+     *     architect, planner) — locks them as read-only even when the parent
+     *     is in `trust`, so the review pass can't accidentally write anything.
+     *   - Leave undefined for roles that mutate (editor, migrator, refactorer,
+     *     test-writer, debugger) — they need the parent's mode to do their job.
+     */
+    permissionMode?: import("../types/permissions.js").PermissionMode;
     /** Per-agent MCP servers injected only when this agent runs (parsed via raw passthrough; dispatcher wiring is a future task). */
     mcpServers?: Record<string, unknown>;
     /** Per-agent hooks (parsed via raw passthrough; dispatcher wiring is a future task). */

package/dist/agents/roles.js

@@ -22,6 +22,7 @@ const roles = [
 
 Be specific: cite file paths, line numbers, and code snippets. Prioritize issues by severity (critical > major > minor). Don't mention things that look fine — focus on problems.`,
         suggestedTools: ["Read", "Glob", "Grep", "LS"],
+        permissionMode: "plan",
     },
     {
         id: "test-writer",
@@ -99,6 +100,7 @@ Do NOT add new features or change behavior. The refactored code must be function
 
 Report findings with severity (Critical/High/Medium/Low), affected file:line, and recommended fix.`,
         suggestedTools: ["Read", "Glob", "Grep", "Bash"],
+        permissionMode: "plan",
     },
     {
         id: "evaluator",
@@ -113,6 +115,7 @@ Report findings with severity (Critical/High/Medium/Low), affected file:line, an
 
 You CANNOT modify files. Only read, search, and run test/lint commands to evaluate.`,
         suggestedTools: ["Read", "Glob", "Grep", "LS", "Bash", "Diagnostics"],
+        permissionMode: "plan",
     },
     {
         id: "planner",
@@ -127,6 +130,7 @@ You CANNOT modify files. Only read, search, and run test/lint commands to evalua
 
 Do NOT implement anything. Your output is a plan document, not code. Read widely before planning.`,
         suggestedTools: ["Read", "Glob", "Grep", "LS", "Bash"],
+        permissionMode: "plan",
     },
     {
         id: "architect",
@@ -152,6 +156,7 @@ When you've finished planning, output a structured "Plan" the editor can apply m
 
 Keep each step small enough that an editor (a cheaper model) can apply it without re-deriving your reasoning. Group related edits together; surface dependencies between steps.`,
         suggestedTools: ["Read", "Glob", "Grep", "LS"],
+        permissionMode: "plan",
     },
     {
         id: "editor",
@@ -238,6 +243,7 @@ function parseAgentMarkdown(raw, filePath) {
     const disallowedMatch = fm.match(/^disallowedTools:\s*(.+)$/m) ?? fm.match(/^disallowed-tools:\s*(.+)$/m);
     const modelMatch = fm.match(/^model:\s*(.+)$/m);
     const isolationMatch = fm.match(/^isolation:\s*(.+)$/m);
+    const permModeMatch = fm.match(/^permissionMode:\s*(.+)$/m) ?? fm.match(/^permission-mode:\s*(.+)$/m);
     const fmEnd = raw.indexOf("---", raw.indexOf("---") + 3);
     const content = fmEnd > 0 ? raw.slice(fmEnd + 3).trim() : "";
     const id = basename(filePath, ".md")
@@ -245,6 +251,14 @@ function parseAgentMarkdown(raw, filePath) {
         .replace(/[^a-z0-9]+/g, "-");
     const isolation = isolationMatch?.[1]?.trim().replace(/^["']|["']$/g, "");
     const validIsolation = isolation === "worktree" || isolation === "none" ? isolation : undefined;
+    // permissionMode: only honor known values; silently drop typos. Same
+    // pattern as `isolation` above — we'd rather a misspelled mode produce
+    // "no override" than a runtime crash.
+    const permModeRaw = permModeMatch?.[1]?.trim().replace(/^["']|["']$/g, "");
+    const validModes = ["ask", "trust", "deny", "acceptEdits", "plan", "auto", "bypassPermissions"];
+    const validPermissionMode = validModes.includes(permModeRaw)
+        ? permModeRaw
+        : undefined;
     // Parse optional inline-JSON fields (mcpServers, hooks). These are block fields in
     // Anthropic's YAML but we support single-line JSON for lightweight frontmatter use.
     const mcpServersMatch = fm.match(/^mcpServers:\s*(\{[\s\S]*?\})\s*$/m);
@@ -258,6 +272,7 @@ function parseAgentMarkdown(raw, filePath) {
         disallowedTools: disallowedMatch ? parseAgentList(disallowedMatch[1]) : undefined,
         model: modelMatch?.[1]?.trim().replace(/^["']|["']$/g, ""),
         isolation: validIsolation,
+        permissionMode: validPermissionMode,
         mcpServers: mcpServersMatch ? tryParseJson(mcpServersMatch[1]) : undefined,
         hooks: hooksMatch ? tryParseJson(hooksMatch[1]) : undefined,
     };

package/dist/tools/AgentTool/index.d.ts

@@ -21,6 +21,7 @@ declare const inputSchema: z.ZodObject<{
     model: z.ZodOptional<z.ZodString>;
     subagent_type: z.ZodOptional<z.ZodString>;
     allowed_tools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    permission_mode: z.ZodOptional<z.ZodEnum<["ask", "trust", "deny", "acceptEdits", "plan", "auto", "bypassPermissions"]>>;
 }, "strip", z.ZodTypeAny, {
     prompt: string;
     model?: string | undefined;
@@ -30,6 +31,7 @@ declare const inputSchema: z.ZodObject<{
     run_in_background?: boolean | undefined;
     subagent_type?: string | undefined;
     allowed_tools?: string[] | undefined;
+    permission_mode?: "ask" | "deny" | "trust" | "acceptEdits" | "plan" | "auto" | "bypassPermissions" | undefined;
 }, {
     prompt: string;
     model?: string | undefined;
@@ -39,6 +41,7 @@ declare const inputSchema: z.ZodObject<{
     run_in_background?: boolean | undefined;
     subagent_type?: string | undefined;
     allowed_tools?: string[] | undefined;
+    permission_mode?: "ask" | "deny" | "trust" | "acceptEdits" | "plan" | "auto" | "bypassPermissions" | undefined;
 }>;
 export declare const AgentTool: Tool<typeof inputSchema>;
 export {};

package/dist/tools/AgentTool/index.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { createWorktree, hasWorktreeChanges, isGitRepo, removeWorktree } from "../../git/index.js";
 import { emitHook } from "../../harness/hooks.js";
 import { getMessageBus } from "../../services/agent-messaging.js";
+import { clampSubagentPermissionMode } from "../../types/permissions.js";
 /**
  * Forward a single inner-query event to the outer stream via `context.emitChildEvent`,
  * stamping it with `parentCallId = context.callId`.
@@ -36,6 +37,10 @@ const inputSchema = z.object({
     model: z.string().optional(),
     subagent_type: z.string().optional(),
     allowed_tools: z.array(z.string()).optional(),
+    permission_mode: z
+        .enum(["ask", "trust", "deny", "acceptEdits", "plan", "auto", "bypassPermissions"])
+        .optional()
+        .describe("Restrict the sub-agent's permission mode. Narrowing-only: the harness clamps to the parent's mode if a less-restrictive value is requested. Useful for spawning read-only review/audit agents while the parent runs in 'trust'."),
 });
 export const AgentTool = {
     name: "Agent",
@@ -101,11 +106,24 @@ export const AgentTool = {
         }
         // Model override for sub-agent
         const agentModel = input.model ?? context.model;
+        // Permission mode override — narrowing-only. Subagent can be same-or-stricter
+        // than parent; a less-restrictive request silently clamps to the parent so a
+        // model in `ask` can't spawn a `trust`-mode subagent to bypass user approval.
+        //
+        // Resolution order, most-specific-wins:
+        //   1. input.permission_mode (the call site's explicit choice)
+        //   2. role.permissionMode (the role's documented default — e.g.
+        //      code-reviewer / security-auditor / planner default to "plan")
+        //   3. parent's mode (no narrowing — current default)
+        // The clamp applies in all cases so #1 and #2 can only narrow, not loosen.
+        const parentMode = context.permissionMode ?? "trust";
+        const requestedMode = input.permission_mode ?? role?.permissionMode;
+        const subagentMode = clampSubagentPermissionMode(parentMode, requestedMode);
         const config = {
             provider: context.provider,
             tools: agentTools,
             systemPrompt,
-            permissionMode: context.permissionMode ?? "trust",
+            permissionMode: subagentMode,
             model: agentModel,
             maxTurns: 20,
             abortSignal: context.abortSignal,
@@ -225,7 +243,8 @@ export const AgentTool = {
 - run_in_background (boolean, optional): Run the agent in the background. Returns immediately; you will be notified when it completes.
 - model (string, optional): Override the model for this sub-agent (e.g., use a faster model for exploration).
 - subagent_type (string, optional): Specialize the agent behavior. Types: "Explore" (read-only codebase search), "Plan" (design implementation plans), "code-reviewer", "test-writer", "debugger", "refactorer", "security-auditor", "evaluator" (read-only evaluation), "planner" (implementation plans), "architect" (system design), "migrator" (codebase migrations).
-- allowed_tools (string[], optional): Restrict the sub-agent to only these tools by name. If omitted and a role has suggested tools, those are used.`;
+- allowed_tools (string[], optional): Restrict the sub-agent to only these tools by name. If omitted and a role has suggested tools, those are used.
+- permission_mode (string, optional): Override the sub-agent's permission mode (one of: ask, trust, deny, acceptEdits, plan, auto, bypassPermissions). Narrowing-only — a less-restrictive value silently clamps to the parent's mode. Use to spawn a read-only audit/review sub-agent in "plan" or "deny" while the parent runs in "trust".`;
     },
 };
 //# sourceMappingURL=index.js.map

package/dist/types/permissions.d.ts

@@ -4,6 +4,23 @@
 import type { ToolPermissionRule } from "../harness/config.js";
 export type PermissionMode = "ask" | "trust" | "deny" | "acceptEdits" | "plan" | "auto" | "bypassPermissions";
 export type RiskLevel = "low" | "medium" | "high";
+/**
+ * Resolve a subagent's effective permission mode given the parent's mode and
+ * an optionally-requested override. The contract: a subagent may be the same
+ * strictness as its parent or stricter, never looser.
+ *
+ * Why this asymmetry: the AgentTool input schema lets the model pick a
+ * subagent's mode. Allowing a less-restrictive choice would mean a model in
+ * `ask` mode could spawn a `trust`-mode subagent and quietly bypass user
+ * approval on its own tool calls — exactly the kind of escalation the
+ * permission system exists to prevent. The same pattern as `allowed_tools`,
+ * which is also narrowing-only.
+ *
+ * Returns the parent's mode if the requested override is undefined or would
+ * loosen the gate. Returns the requested override only when it's the same or
+ * stricter than the parent.
+ */
+export declare function clampSubagentPermissionMode(parentMode: PermissionMode, requestedMode: PermissionMode | undefined): PermissionMode;
 export type PermissionResult = {
     readonly allowed: boolean;
     readonly reason: string;

package/dist/types/permissions.js

@@ -2,6 +2,56 @@
  * Permission types — tool permission context and risk-based gating.
  */
 import { analyzeBashCommand, isReadOnlyBashCommand, splitCommands, stripProcessWrappers, } from "../utils/bash-safety.js";
+/**
+ * Strictness rank for permission modes. Lower = more permissive. Used by
+ * `clampSubagentPermissionMode` to enforce that a subagent can never run
+ * less restrictively than its parent — only the same or stricter.
+ *
+ * The ordering is deliberate, not lexical:
+ *   bypassPermissions (0) — approves everything unconditionally
+ *   trust             (1) — approves everything user-trusted
+ *   auto              (2) — approves except dangerous bash
+ *   acceptEdits       (3) — auto-approves edit-safe tool subset
+ *   plan              (4) — read-only allowed; writes blocked
+ *   ask               (5) — every non-trivial call prompts the user
+ *   deny              (6) — denies everything
+ *
+ * Why a rank instead of a Set: most-restrictive comparisons are easier when
+ * the dimension is total-ordered, and adding a new mode means adding one row
+ * to this table rather than re-deriving the partial order across call sites.
+ */
+const PERMISSION_STRICTNESS_RANK = {
+    bypassPermissions: 0,
+    trust: 1,
+    auto: 2,
+    acceptEdits: 3,
+    plan: 4,
+    ask: 5,
+    deny: 6,
+};
+/**
+ * Resolve a subagent's effective permission mode given the parent's mode and
+ * an optionally-requested override. The contract: a subagent may be the same
+ * strictness as its parent or stricter, never looser.
+ *
+ * Why this asymmetry: the AgentTool input schema lets the model pick a
+ * subagent's mode. Allowing a less-restrictive choice would mean a model in
+ * `ask` mode could spawn a `trust`-mode subagent and quietly bypass user
+ * approval on its own tool calls — exactly the kind of escalation the
+ * permission system exists to prevent. The same pattern as `allowed_tools`,
+ * which is also narrowing-only.
+ *
+ * Returns the parent's mode if the requested override is undefined or would
+ * loosen the gate. Returns the requested override only when it's the same or
+ * stricter than the parent.
+ */
+export function clampSubagentPermissionMode(parentMode, requestedMode) {
+    if (!requestedMode)
+        return parentMode;
+    return PERMISSION_STRICTNESS_RANK[requestedMode] >= PERMISSION_STRICTNESS_RANK[parentMode]
+        ? requestedMode
+        : parentMode;
+}
 /** Tools auto-approved in acceptEdits mode */
 const EDIT_SAFE_TOOLS = new Set([
     "FileRead",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhijiewang/openharness",
-  "version": "2.35.0",
+  "version": "2.37.0",
   "description": "Open-source terminal coding agent. Works with any LLM.",
   "type": "module",
   "bin": {