@zhijiewang/openharness 2.36.0 → 2.38.0

package/README.md

@@ -574,6 +574,8 @@ 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

@@ -574,6 +574,8 @@ 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/services/AgentDispatcher.d.ts

@@ -8,7 +8,7 @@
 import type { Provider } from "../providers/base.js";
 import type { Tools } from "../Tool.js";
 import type { StreamEvent, ToolCallComplete, ToolCallEnd, ToolCallStart, ToolOutputDelta } from "../types/events.js";
-import type { PermissionMode } from "../types/permissions.js";
+import { type PermissionMode } from "../types/permissions.js";
 /**
  * Forward inner-loop tool events to the outer stream, stamping parentCallId.
  * Exported for direct unit testing.
@@ -20,6 +20,15 @@ export type AgentTask = {
     description?: string;
     blockedBy?: string[];
     allowedTools?: string[];
+    /**
+     * Per-task permission mode override — narrowing-only, same contract as
+     * AgentTool's `permission_mode` (v2.36). When set, the task's effective
+     * mode is `clampSubagentPermissionMode(dispatcher.permissionMode, task.permissionMode)`,
+     * so a task can be the same strictness as the outer call or stricter,
+     * never looser. Use to mark specific tasks in a parallel batch as
+     * read-only review/audit while letting siblings keep full write access.
+     */
+    permissionMode?: PermissionMode;
 };
 export type AgentTaskResult = {
     id: string;

package/dist/services/AgentDispatcher.js

@@ -6,6 +6,7 @@
  * and triggers dependent tasks when their blockers complete.
  */
 import { createWorktree, isGitRepo, removeWorktree } from "../git/index.js";
+import { clampSubagentPermissionMode } from "../types/permissions.js";
 /**
  * Forward inner-loop tool events to the outer stream, stamping parentCallId.
  * Exported for direct unit testing.
@@ -168,11 +169,15 @@ export class AgentDispatcher {
             // matching `process.chdir(originalCwd)` in `finally` — but since
             // `process.cwd()` is process-wide, two concurrent tasks would clobber
             // each other's directory mid-execution.
+            // Per-task permission mode — narrowing-only clamp applied so a task
+            // can override only to a same-or-stricter mode than the dispatcher's
+            // outer mode (#115 contract).
+            const taskPermissionMode = clampSubagentPermissionMode(this.permissionMode, task.permissionMode);
             const config = {
                 provider: this.provider,
                 tools: taskTools,
                 systemPrompt: this.systemPrompt,
-                permissionMode: this.permissionMode,
+                permissionMode: taskPermissionMode,
                 model: this.model,
                 maxTurns: 20,
                 abortSignal: this.abortSignal,

package/dist/tools/AgentTool/index.js

@@ -109,8 +109,16 @@ export const AgentTool = {
         // 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 subagentMode = clampSubagentPermissionMode(parentMode, input.permission_mode);
+        const requestedMode = input.permission_mode ?? role?.permissionMode;
+        const subagentMode = clampSubagentPermissionMode(parentMode, requestedMode);
         const config = {
             provider: context.provider,
             tools: agentTools,

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

@@ -6,15 +6,21 @@ declare const inputSchema: z.ZodObject<{
         prompt: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
         blockedBy: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        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, {
         id: string;
         prompt: string;
         description?: string | undefined;
+        allowed_tools?: string[] | undefined;
+        permission_mode?: "ask" | "deny" | "trust" | "acceptEdits" | "plan" | "auto" | "bypassPermissions" | undefined;
         blockedBy?: string[] | undefined;
     }, {
         id: string;
         prompt: string;
         description?: string | undefined;
+        allowed_tools?: string[] | undefined;
+        permission_mode?: "ask" | "deny" | "trust" | "acceptEdits" | "plan" | "auto" | "bypassPermissions" | undefined;
         blockedBy?: string[] | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
@@ -22,6 +28,8 @@ declare const inputSchema: z.ZodObject<{
         id: string;
         prompt: string;
         description?: string | undefined;
+        allowed_tools?: string[] | undefined;
+        permission_mode?: "ask" | "deny" | "trust" | "acceptEdits" | "plan" | "auto" | "bypassPermissions" | undefined;
         blockedBy?: string[] | undefined;
     }[];
 }, {
@@ -29,6 +37,8 @@ declare const inputSchema: z.ZodObject<{
         id: string;
         prompt: string;
         description?: string | undefined;
+        allowed_tools?: string[] | undefined;
+        permission_mode?: "ask" | "deny" | "trust" | "acceptEdits" | "plan" | "auto" | "bypassPermissions" | undefined;
         blockedBy?: string[] | undefined;
     }[];
 }>;

package/dist/tools/ParallelAgentTool/index.js

@@ -5,6 +5,11 @@ const taskSchema = z.object({
     prompt: z.string(),
     description: z.string().optional(),
     blockedBy: z.array(z.string()).optional(),
+    allowed_tools: z.array(z.string()).optional(),
+    permission_mode: z
+        .enum(["ask", "trust", "deny", "acceptEdits", "plan", "auto", "bypassPermissions"])
+        .optional()
+        .describe("Restrict THIS task's permission mode. Narrowing-only — clamps to the outer mode if a less-restrictive value is requested. Use to mark a single task as read-only review/audit while sibling tasks keep full write access."),
 });
 const inputSchema = z.object({
     tasks: z.array(taskSchema).min(1),
@@ -27,7 +32,18 @@ export const ParallelAgentTool = {
         const systemPrompt = context.systemPrompt ?? "You are a sub-agent. Complete the delegated task concisely.";
         const dispatcher = new AgentDispatcher(context.provider, context.tools, systemPrompt, context.permissionMode ?? "trust", context.model, context.workingDir, context.abortSignal, 4, // maxConcurrency default
         context.callId, context.emitChildEvent);
-        dispatcher.addTasks(input.tasks);
+        // Map snake_case input fields to the AgentTask camelCase shape — the
+        // input schema uses `allowed_tools` / `permission_mode` to stay
+        // consistent with AgentTool, but the dispatcher's task type uses
+        // `allowedTools` / `permissionMode`.
+        dispatcher.addTasks(input.tasks.map((t) => ({
+            id: t.id,
+            prompt: t.prompt,
+            description: t.description,
+            blockedBy: t.blockedBy,
+            allowedTools: t.allowed_tools,
+            permissionMode: t.permission_mode,
+        })));
         const results = await dispatcher.execute();
         const output = results
             .map((r) => {
@@ -48,12 +64,13 @@ Parameters:
   - prompt (string): Instructions for the sub-agent
   - description (string, optional): Short label
   - blockedBy (string[], optional): IDs of tasks that must complete first
+  - allowed_tools (string[], optional): Restrict THIS task's agent to specific tools
+  - permission_mode (string, optional): Override THIS task's permission mode. Narrowing-only — a less-restrictive value clamps to the outer mode. Useful for marking review/audit tasks as "plan" or "deny" while sibling tasks keep full write access.
 
-Example: Run task A and B in parallel, then task C after both complete:
+Example: parallel test-write + read-only review:
 tasks: [
-  { id: "a", prompt: "..." },
-  { id: "b", prompt: "..." },
-  { id: "c", prompt: "...", blockedBy: ["a", "b"] }
+  { id: "tests", prompt: "Add tests for the new auth module" },
+  { id: "review", prompt: "Audit the new auth module for security issues", permission_mode: "plan" }
 ]`;
     },
 };

package/package.json

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