@link-assistant/agent 0.23.0 → 0.24.0

package/README.md

@@ -293,6 +293,18 @@ Options:
   --append-system-message        Append to the default system message
   --append-system-message-file   Append to the default system message from file
 
+Permission Options:
+  --read-only                    Enforceable read-only / planning mode.
+                                 Disables all filesystem-mutating and shell
+                                 tools (bash, edit, write, multiedit, patch)
+                                 so the agent can only read, search and plan.
+                                 Env: LINK_ASSISTANT_AGENT_READ_ONLY=true
+  --disable-tools <list>         Comma-separated list of tool ids to disable
+                                 (e.g. "bash,write,edit"). Disabled tools are
+                                 never exposed to the model and are rejected if
+                                 invoked via batch.
+                                 Env: LINK_ASSISTANT_AGENT_DISABLE_TOOLS
+
 Stdin Mode Options:
   -p, --prompt                   Direct prompt (bypasses stdin reading)
   --disable-stdin                Disable stdin streaming (requires --prompt)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/agent",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "A minimal, public domain AI CLI agent compatible with OpenCode's JSON interface. Bun-only runtime.",
   "main": "src/index.js",
   "type": "module",

package/src/cli/continuous-mode.js

@@ -10,6 +10,7 @@ import { Session } from '../session/index.ts';
 import { SessionPrompt } from '../session/prompt.ts';
 import { createEventHandler, serializeOutput } from '../json-standard/index.ts';
 import { createContinuousStdinReader } from './input-queue.js';
+import { Permission } from '../permission/index.ts';
 import { Log } from '../util/log.ts';
 import { config } from '../config/config.ts';
 import { createVerboseFetch } from '../util/verbose-fetch.ts';
@@ -323,6 +324,19 @@ export async function runContinuousServerMode(
         return;
       }
 
+      // Permission approval reply (issue #271). Resolve a pending tool
+      // permission request without interrupting the in-flight turn — this must
+      // bypass the `isProcessing` queue, since the turn is blocked waiting for it.
+      if (message.kind === 'permission_response') {
+        Permission.respond({
+          sessionID,
+          permissionID: message.permissionID,
+          response: message.response,
+        });
+        outputConsumedInput({ message, jsonStandard, sessionID, compactJson });
+        return;
+      }
+
       if (isProcessing) {
         pendingMessages.push(message);
         return;
@@ -577,6 +591,19 @@ export async function runContinuousDirectMode(
         return;
       }
 
+      // Permission approval reply (issue #271). Resolve a pending tool
+      // permission request without interrupting the in-flight turn — this must
+      // bypass the `isProcessing` queue, since the turn is blocked waiting for it.
+      if (message.kind === 'permission_response') {
+        Permission.respond({
+          sessionID,
+          permissionID: message.permissionID,
+          response: message.response,
+        });
+        outputConsumedInput({ message, jsonStandard, sessionID, compactJson });
+        return;
+      }
+
       if (isProcessing) {
         pendingMessages.push(message);
         return;

package/src/cli/event-handler.js

@@ -81,6 +81,27 @@ export function createBusEventSubscription({
       }
     }
 
+    // Emit a JSON permission request when a tool needs approval (issue #271).
+    // The consumer replies with a `permission_response` frame over stdin which
+    // is routed to Permission.respond. No TUI is involved.
+    if (event.type === 'permission.updated') {
+      const permission = event.properties;
+      if (permission.sessionID !== sessionID) {
+        return;
+      }
+      eventHandler.output({
+        type: 'permission_request',
+        timestamp: Date.now(),
+        sessionID,
+        permissionID: permission.id,
+        callID: permission.callID,
+        tool: permission.type,
+        pattern: permission.pattern,
+        title: permission.title,
+        metadata: permission.metadata,
+      });
+    }
+
     // Handle session idle to know when to stop
     if (
       event.type === 'session.idle' &&

package/src/cli/input-queue.js

@@ -30,18 +30,47 @@ export class InputQueue {
       return parseStreamJsonInput(trimmed);
     }
 
+    let parsed;
     try {
-      const parsed = JSON.parse(trimmed);
-      // If it has a message field, use it directly
-      if (typeof parsed === 'object' && parsed !== null) {
-        return parsed;
-      }
-      // Otherwise wrap it
-      return { message: JSON.stringify(parsed) };
+      parsed = JSON.parse(trimmed);
     } catch (_e) {
       // Not JSON, treat as plain text message
       return { message: trimmed };
     }
+
+    // If it has a message field, use it directly
+    if (typeof parsed === 'object' && parsed !== null) {
+      // Permission approval reply (issue #271) — normalize to a `kind` frame
+      // so it is routed to Permission.respond, mirroring stream-json mode.
+      if (parsed.type === 'permission_response') {
+        const permissionID = parsed.permissionID ?? parsed.permission_id;
+        const response = parsed.response;
+        if (typeof permissionID !== 'string' || !permissionID) {
+          throw new Error(
+            'Invalid permission_response: expected string "permissionID"'
+          );
+        }
+        if (
+          response !== 'once' &&
+          response !== 'always' &&
+          response !== 'reject'
+        ) {
+          throw new Error(
+            'Invalid permission_response: "response" must be "once", "always" or "reject"'
+          );
+        }
+        return {
+          kind: 'permission_response',
+          permissionID,
+          response,
+          raw: trimmed,
+          parsed,
+        };
+      }
+      return parsed;
+    }
+    // Otherwise wrap it
+    return { message: JSON.stringify(parsed) };
   }
 
   /**
@@ -283,6 +312,33 @@ export function parseStreamJsonInput(input) {
     };
   }
 
+  // Permission approval reply (issue #271). Resolves a pending
+  // `permission_request` emitted by the agent. `response` is one of
+  // `once` | `always` | `reject`.
+  if (type === 'permission_response') {
+    const permissionID = frame.permissionID ?? frame.permission_id;
+    const response = frame.response;
+    if (typeof permissionID !== 'string' || !permissionID) {
+      throw new Error(
+        'Invalid permission_response frame: expected string "permissionID"'
+      );
+    }
+    if (response !== 'once' && response !== 'always' && response !== 'reject') {
+      throw new Error(
+        'Invalid permission_response frame: "response" must be "once", "always" or "reject"'
+      );
+    }
+    return {
+      kind: 'permission_response',
+      permissionID,
+      response,
+      raw: input,
+      parsed: frame,
+      format: 'stream-json',
+      inputType: type,
+    };
+  }
+
   if (type === 'user' || type === 'user_prompt' || type === undefined) {
     const message = extractFrameText(frame);
     if (message === null) {

package/src/cli/run-options.js

@@ -211,5 +211,28 @@ export function buildRunOptions(yargs, defaultOptions = {}) {
       type: 'number',
       description:
         'Override the temperature for model completions. When not set, the default per-model temperature is used.',
+    })
+    .option('read-only', {
+      type: 'boolean',
+      description:
+        'Enforceable read-only / planning mode. Disables all filesystem-mutating and shell tools (bash, edit, write, multiedit, patch) so the agent can only read, search and plan. Maps to agent-commander --read-only.',
+      default: false,
+    })
+    .option('disable-tools', {
+      type: 'string',
+      description:
+        'Comma-separated list of tool ids to disable (e.g. "bash,write,edit"). Disabled tools are never exposed to the model and are rejected if invoked via batch.',
+    })
+    .option('permission-mode', {
+      type: 'string',
+      choices: ['auto', 'plan', 'readonly', 'ask'],
+      description:
+        'Permission policy for mutating tools. "auto" (default) allows everything; "plan" allows read-only shell and asks before mutations; "readonly" denies all mutations; "ask" asks before every mutating tool. Approvals are driven over JSON (permission_request / permission_response).',
+      default: 'auto',
+    })
+    .option('permission', {
+      type: 'string',
+      description:
+        'OpenCode-compatible permission override as JSON, merged on top of --permission-mode. Example: \'{"edit":"ask","bash":{"git push*":"ask","*":"allow"},"webfetch":"allow"}\'.',
     });
 }

package/src/config/config.ts

@@ -52,6 +52,10 @@ export interface AgentConfig {
   mcpDefaultToolCallTimeout: number;
   mcpMaxToolCallTimeout: number;
   verifyImagesAtReadTool: boolean;
+  readOnly: boolean;
+  disableTools: string;
+  permissionMode: string;
+  permission: string;
 }
 
 // Fallback helpers for when config is not yet initialized (early imports/tests)
@@ -132,6 +136,10 @@ function defaultConfig(): AgentConfig {
     })(),
     verifyImagesAtReadTool:
       getEnvStr('LINK_ASSISTANT_AGENT_VERIFY_IMAGES_AT_READ_TOOL') !== 'false',
+    readOnly: truthyEnv('LINK_ASSISTANT_AGENT_READ_ONLY'),
+    disableTools: getEnvStr('LINK_ASSISTANT_AGENT_DISABLE_TOOLS') ?? '',
+    permissionMode: getEnvStr('LINK_ASSISTANT_AGENT_PERMISSION_MODE') ?? 'auto',
+    permission: getEnvStr('LINK_ASSISTANT_AGENT_PERMISSION') ?? '',
   };
 }
 
@@ -240,6 +248,31 @@ function buildAgentConfigOptions({
       type: 'boolean',
       description: 'Verify images when using the read tool',
       default: getenv('LINK_ASSISTANT_AGENT_VERIFY_IMAGES_AT_READ_TOOL', true),
+    })
+    .option('read-only', {
+      type: 'boolean',
+      description:
+        'Enforceable read-only / planning mode. Disables all filesystem-mutating and shell tools (bash, edit, write, multiedit, patch).',
+      default: getenv('LINK_ASSISTANT_AGENT_READ_ONLY', false),
+    })
+    .option('disable-tools', {
+      type: 'string',
+      description:
+        'Comma-separated list of tool ids to disable (e.g. "bash,write,edit"). Disabled tools are never exposed to the model and are rejected if invoked via batch.',
+      default: getenv('LINK_ASSISTANT_AGENT_DISABLE_TOOLS', ''),
+    })
+    .option('permission-mode', {
+      type: 'string',
+      choices: ['auto', 'plan', 'readonly', 'ask'],
+      description:
+        'Permission policy for mutating tools. "auto" (default) allows everything; "plan" allows read-only shell and asks before mutations; "readonly" denies all mutations; "ask" asks before every mutating tool. Approvals are driven over JSON (permission_request / permission_response).',
+      default: getenv('LINK_ASSISTANT_AGENT_PERMISSION_MODE', 'auto'),
+    })
+    .option('permission', {
+      type: 'string',
+      description:
+        'OpenCode-compatible permission override as JSON, merged on top of --permission-mode. Example: \'{"edit":"ask","bash":{"git push*":"ask","*":"allow"},"webfetch":"allow"}\'.',
+      default: getenv('LINK_ASSISTANT_AGENT_PERMISSION', ''),
     });
 }
 
@@ -292,6 +325,10 @@ export function initConfig(argv?: string[]): AgentConfig {
     mcpDefaultToolCallTimeout: parsed.mcpDefaultToolCallTimeout ?? 120000,
     mcpMaxToolCallTimeout: parsed.mcpMaxToolCallTimeout ?? 600000,
     verifyImagesAtReadTool: parsed.verifyImagesAtReadTool ?? true,
+    readOnly: parsed.readOnly ?? false,
+    disableTools: parsed.disableTools ?? '',
+    permissionMode: parsed.permissionMode ?? 'auto',
+    permission: parsed.permission ?? '',
   });
 
   // Propagate verbose to env var for subprocess resilience (issue #227).

package/src/permission/index.ts

@@ -0,0 +1,564 @@
+/**
+ * Permission system (issue #271).
+ *
+ * Re-adds an OpenCode-style permission system to @link-assistant/agent that is
+ * fully controllable from JSON (input and output), with no TUI.
+ *
+ * By default the agent runs in **full auto mode** (every action is `allow`), so
+ * nothing changes for existing consumers. Opt-in CLI options switch the policy:
+ *
+ *   --permission-mode auto      (default) allow everything, never ask
+ *   --permission-mode plan      read-only planning: deny edits, allow read-only
+ *                               shell commands, ask before anything else
+ *   --permission-mode readonly  hard read-only: deny edits and any non
+ *                               read-only shell command (never asks)
+ *   --permission-mode ask       ask before every mutating tool (per-command
+ *                               approval driven over JSON)
+ *   --permission '<json>'       explicit OpenCode-compatible override merged on
+ *                               top of the mode, e.g.
+ *                               '{"bash":{"git push*":"ask","*":"allow"},"edit":"ask"}'
+ *
+ * When a tool needs approval it publishes a `permission.updated` event (emitted
+ * to stdout as a `permission_request` JSON event) and waits. The consumer sends
+ * back a `permission_response` JSON frame which resolves `Permission.respond`.
+ *
+ * This is the native, enforceable counterpart of agent-commander's `--read-only`
+ * flag and of its (future) per-command approval UX.
+ */
+import z from 'zod';
+import { Bus } from '../bus';
+import { Log } from '../util/log';
+import { Identifier } from '../id/id';
+import { Instance } from '../project/instance';
+import { Wildcard } from '../util/wildcard';
+import { config } from '../config/config';
+
+export namespace Permission {
+  const log = Log.create({ service: 'permission' });
+
+  // ─── Policy types ─────────────────────────────────────────────────────────
+
+  export const Action = z.enum(['ask', 'allow', 'deny']);
+  export type Action = z.infer<typeof Action>;
+
+  export const Mode = z.enum(['auto', 'plan', 'readonly', 'ask']);
+  export type Mode = z.infer<typeof Mode>;
+
+  /** Resolved permission policy. `bash` is a pattern map (OpenCode-compatible). */
+  export interface Policy {
+    edit: Action;
+    bash: Record<string, Action>;
+    webfetch: Action;
+  }
+
+  /**
+   * Read-only shell allowlist. Commands matching one of these patterns are safe
+   * to run in plan/readonly mode; everything else falls back to `fallback`
+   * (`ask` for plan, `deny` for readonly).
+   */
+  function readonlyBash(fallback: Action): Record<string, Action> {
+    return {
+      'cat*': 'allow',
+      'cd*': 'allow',
+      'cut*': 'allow',
+      'date*': 'allow',
+      'df*': 'allow',
+      'diff*': 'allow',
+      'dirname*': 'allow',
+      'du*': 'allow',
+      'echo*': 'allow',
+      env: 'allow',
+      'file *': 'allow',
+      'find *': 'allow',
+      'git diff*': 'allow',
+      'git log*': 'allow',
+      'git show*': 'allow',
+      'git status*': 'allow',
+      'git branch': 'allow',
+      'git branch -v': 'allow',
+      'grep*': 'allow',
+      'head*': 'allow',
+      'hostname*': 'allow',
+      'less*': 'allow',
+      'ls*': 'allow',
+      'more*': 'allow',
+      'printenv*': 'allow',
+      'pwd*': 'allow',
+      'readlink*': 'allow',
+      'realpath*': 'allow',
+      'rg*': 'allow',
+      'sort*': 'allow',
+      'stat*': 'allow',
+      'tail*': 'allow',
+      'tree*': 'allow',
+      'uname*': 'allow',
+      'uniq*': 'allow',
+      'wc*': 'allow',
+      'whereis*': 'allow',
+      'which*': 'allow',
+      'whoami*': 'allow',
+      // Read-only command families that have destructive variants:
+      'find * -delete*': fallback,
+      'find * -exec*': fallback,
+      'find * -execdir*': fallback,
+      'find * -fprint*': fallback,
+      'find * -fls*': fallback,
+      'find * -fprintf*': fallback,
+      'find * -ok*': fallback,
+      'sort -o*': fallback,
+      'sort --output*': fallback,
+      'tree -o*': fallback,
+      // Catch-all:
+      '*': fallback,
+    };
+  }
+
+  /** Base policy for a mode, before any explicit `--permission` override. */
+  export function modePolicy(mode: Mode): Policy {
+    switch (mode) {
+      case 'plan':
+        return { edit: 'deny', bash: readonlyBash('ask'), webfetch: 'allow' };
+      case 'readonly':
+        return { edit: 'deny', bash: readonlyBash('deny'), webfetch: 'allow' };
+      case 'ask':
+        return { edit: 'ask', bash: { '*': 'ask' }, webfetch: 'ask' };
+      case 'auto':
+      default:
+        return { edit: 'allow', bash: { '*': 'allow' }, webfetch: 'allow' };
+    }
+  }
+
+  /** Parse the raw `--permission` JSON string into a partial policy. */
+  export function parseOverride(raw: string | undefined): Partial<Policy> {
+    if (!raw || !raw.trim()) return {};
+    let parsed: any;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (error) {
+      throw new Error(
+        `Invalid --permission JSON: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('Invalid --permission JSON: expected an object');
+    }
+    const out: Partial<Policy> = {};
+    if (parsed.edit !== undefined) out.edit = Action.parse(parsed.edit);
+    if (parsed.webfetch !== undefined)
+      out.webfetch = Action.parse(parsed.webfetch);
+    if (parsed.bash !== undefined) {
+      if (typeof parsed.bash === 'string') {
+        out.bash = { '*': Action.parse(parsed.bash) };
+      } else if (
+        typeof parsed.bash === 'object' &&
+        !Array.isArray(parsed.bash)
+      ) {
+        const bash: Record<string, Action> = {};
+        for (const [pattern, value] of Object.entries(parsed.bash)) {
+          bash[pattern] = Action.parse(value);
+        }
+        out.bash = bash;
+      } else {
+        throw new Error(
+          'Invalid --permission JSON: "bash" must be a string or object'
+        );
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Resolve the active policy from the global config. Mode defines the base
+   * policy and `--permission` JSON is merged on top (override wins; bash maps
+   * are merged key-by-key).
+   */
+  export function policy(): Policy {
+    const mode = Mode.parse(config.permissionMode ?? 'auto');
+    const base = modePolicy(mode);
+    const override = parseOverride(config.permission);
+    return {
+      edit: override.edit ?? base.edit,
+      webfetch: override.webfetch ?? base.webfetch,
+      bash: { ...base.bash, ...(override.bash ?? {}) },
+    };
+  }
+
+  const RESTRICTIVENESS: Record<Action, number> = {
+    allow: 0,
+    ask: 1,
+    deny: 2,
+  };
+
+  function moreRestrictive(a: Action, b: Action): Action {
+    return RESTRICTIVENESS[b] > RESTRICTIVENESS[a] ? b : a;
+  }
+
+  function tokenize(segment: string): string[] {
+    return segment.trim().split(/\s+/).filter(Boolean);
+  }
+
+  /**
+   * Evaluate a shell command against a bash pattern map.
+   *
+   * Faithful-enough port of OpenCode's structured matching, hardened for
+   * non-interactive enforcement: a command is only `allow`ed when *every*
+   * segment (split on `;`, `&&`, `||`, `|`) matches an allow pattern and the
+   * command contains no command substitution or output redirection. Otherwise
+   * it falls back to the catch-all action (`*`). The strongest enforcement
+   * remains tool removal via `--read-only` / `--disable-tools`.
+   */
+  export function evaluateBash(
+    command: string,
+    patterns: Record<string, Action>
+  ): { action: Action; askPatterns: string[] } {
+    const fallback = patterns['*'] ?? 'allow';
+    const askPatterns = new Set<string>();
+
+    // Command substitution or output redirection can hide arbitrary writes.
+    const hasSubstitution = /\$\(|`/.test(command);
+    const hasRedirection = />>?/.test(command);
+    if (hasSubstitution || hasRedirection) {
+      if (fallback === 'ask') askPatterns.add(command);
+      return { action: fallback, askPatterns: Array.from(askPatterns) };
+    }
+
+    const segments = command
+      .split(/&&|\|\||;|\|/g)
+      .map((s) => s.trim())
+      .filter(Boolean);
+    if (segments.length === 0) {
+      return { action: fallback, askPatterns: [] };
+    }
+
+    let action: Action = 'allow';
+    for (const segment of segments) {
+      const tokens = tokenize(segment);
+      if (tokens.length === 0) continue;
+      const matched = Wildcard.allStructured(
+        { head: tokens[0], tail: tokens.slice(1) },
+        patterns
+      ) as Action | undefined;
+      const segAction = matched ?? fallback;
+      action = moreRestrictive(action, segAction);
+      if (segAction === 'ask') {
+        const sub = tokens.slice(1).find((arg) => !arg.startsWith('-'));
+        askPatterns.add(sub ? `${tokens[0]} ${sub} *` : `${tokens[0]} *`);
+      }
+    }
+    return { action, askPatterns: Array.from(askPatterns) };
+  }
+
+  // ─── Ask / respond machinery (ported from OpenCode) ───────────────────────
+
+  function toKeys(pattern: Info['pattern'], type: string): string[] {
+    return pattern === undefined
+      ? [type]
+      : Array.isArray(pattern)
+        ? pattern
+        : [pattern];
+  }
+
+  function covered(keys: string[], approved: Record<string, boolean>): boolean {
+    const pats = Object.keys(approved);
+    return keys.every((k) => pats.some((p) => Wildcard.match(k, p)));
+  }
+
+  export const Info = z
+    .object({
+      id: z.string(),
+      type: z.string(),
+      pattern: z.union([z.string(), z.array(z.string())]).optional(),
+      sessionID: z.string(),
+      messageID: z.string(),
+      callID: z.string().optional(),
+      title: z.string(),
+      metadata: z.record(z.string(), z.any()),
+      time: z.object({
+        created: z.number(),
+      }),
+    })
+    .meta({
+      ref: 'Permission',
+    });
+  export type Info = z.infer<typeof Info>;
+
+  export const Event = {
+    Updated: Bus.event('permission.updated', Info),
+    Replied: Bus.event(
+      'permission.replied',
+      z.object({
+        sessionID: z.string(),
+        permissionID: z.string(),
+        response: z.string(),
+      })
+    ),
+  };
+
+  const state = Instance.state(
+    () => {
+      const pending: {
+        [sessionID: string]: {
+          [permissionID: string]: {
+            info: Info;
+            resolve: () => void;
+            reject: (e: any) => void;
+          };
+        };
+      } = {};
+
+      const approved: {
+        [sessionID: string]: {
+          [permissionID: string]: boolean;
+        };
+      } = {};
+
+      return {
+        pending,
+        approved,
+      };
+    },
+    async (state) => {
+      for (const pending of Object.values(state.pending)) {
+        for (const item of Object.values(pending)) {
+          item.reject(
+            new RejectedError(
+              item.info.sessionID,
+              item.info.id,
+              item.info.callID,
+              item.info.metadata
+            )
+          );
+        }
+      }
+    }
+  );
+
+  export function pending() {
+    return state().pending;
+  }
+
+  export const Response = z.enum(['once', 'always', 'reject']);
+  export type Response = z.infer<typeof Response>;
+
+  /**
+   * Ask for permission. Resolves immediately when already approved; rejects
+   * (throws via the caller) when denied. Otherwise registers a pending request,
+   * publishes `permission.updated`, and returns a promise resolved by
+   * `respond()`.
+   */
+  export async function ask(input: {
+    type: Info['type'];
+    title: Info['title'];
+    pattern?: Info['pattern'];
+    callID?: Info['callID'];
+    sessionID: Info['sessionID'];
+    messageID: Info['messageID'];
+    metadata: Info['metadata'];
+  }) {
+    const { pending, approved } = state();
+    log.info(() => ({
+      message: 'asking',
+      sessionID: input.sessionID,
+      pattern: input.pattern,
+    }));
+    const approvedForSession = approved[input.sessionID] || {};
+    const keys = toKeys(input.pattern, input.type);
+    if (covered(keys, approvedForSession)) return;
+    const info: Info = {
+      id: Identifier.ascending('permission'),
+      type: input.type,
+      pattern: input.pattern,
+      sessionID: input.sessionID,
+      messageID: input.messageID,
+      callID: input.callID,
+      title: input.title,
+      metadata: input.metadata,
+      time: {
+        created: Date.now(),
+      },
+    };
+
+    pending[input.sessionID] = pending[input.sessionID] || {};
+    return new Promise<void>((resolve, reject) => {
+      pending[input.sessionID][info.id] = {
+        info,
+        resolve,
+        reject,
+      };
+      Bus.publish(Event.Updated, info);
+    });
+  }
+
+  export function respond(input: {
+    sessionID: Info['sessionID'];
+    permissionID: Info['id'];
+    response: Response;
+  }) {
+    log.info(() => ({ message: 'response', ...input }));
+    const { pending, approved } = state();
+    const match = pending[input.sessionID]?.[input.permissionID];
+    if (!match) return;
+    delete pending[input.sessionID][input.permissionID];
+    Bus.publish(Event.Replied, {
+      sessionID: input.sessionID,
+      permissionID: input.permissionID,
+      response: input.response,
+    });
+    if (input.response === 'reject') {
+      match.reject(
+        new RejectedError(
+          input.sessionID,
+          input.permissionID,
+          match.info.callID,
+          match.info.metadata
+        )
+      );
+      return;
+    }
+    match.resolve();
+    if (input.response === 'always') {
+      approved[input.sessionID] = approved[input.sessionID] || {};
+      const approveKeys = toKeys(match.info.pattern, match.info.type);
+      for (const k of approveKeys) {
+        approved[input.sessionID][k] = true;
+      }
+      const items = pending[input.sessionID];
+      if (!items) return;
+      for (const item of Object.values(items)) {
+        const itemKeys = toKeys(item.info.pattern, item.info.type);
+        if (covered(itemKeys, approved[input.sessionID])) {
+          respond({
+            sessionID: item.info.sessionID,
+            permissionID: item.info.id,
+            response: input.response,
+          });
+        }
+      }
+    }
+  }
+
+  export class RejectedError extends Error {
+    constructor(
+      public readonly sessionID: string,
+      public readonly permissionID: string,
+      public readonly toolCallID?: string,
+      public readonly metadata?: Record<string, any>,
+      public readonly reason?: string
+    ) {
+      super(
+        reason !== undefined
+          ? reason
+          : `The user rejected permission to use this specific tool call. You may try again with different parameters.`
+      );
+    }
+  }
+
+  // ─── High-level helpers used by tools ─────────────────────────────────────
+
+  /**
+   * Enforce the policy for a simple (non-bash) tool type (`edit`/`webfetch`).
+   * Throws RejectedError on deny, asks (and may throw) on ask, returns on allow.
+   */
+  export async function check(input: {
+    type: 'edit' | 'webfetch';
+    title: string;
+    sessionID: string;
+    messageID: string;
+    callID?: string;
+    metadata?: Record<string, any>;
+  }) {
+    const p = policy();
+    const action: Action = input.type === 'edit' ? p.edit : p.webfetch;
+    if (action === 'allow') return;
+    if (action === 'deny') {
+      throw new RejectedError(
+        input.sessionID,
+        input.callID ?? input.messageID,
+        input.callID,
+        input.metadata,
+        `The ${input.type} tool is disabled in the current permission mode (${config.permissionMode ?? 'auto'}).`
+      );
+    }
+    await ask({
+      type: input.type,
+      title: input.title,
+      sessionID: input.sessionID,
+      messageID: input.messageID,
+      callID: input.callID,
+      metadata: input.metadata ?? {},
+    });
+  }
+
+  /**
+   * Whether bash enforcement is active. In the default `auto` mode every
+   * pattern maps to `allow`, so callers can skip the (non-trivial) tree-sitter
+   * parse entirely — preserving zero overhead for the full-auto default.
+   */
+  export function bashEnforced(): boolean {
+    const patterns = policy().bash;
+    return Object.values(patterns).some((a) => a !== 'allow');
+  }
+
+  /** Resolve the ask-pattern for a single command's token array. */
+  function askPattern(command: string[]): string {
+    const head = command[0];
+    const sub = command.slice(1).find((arg) => !arg.startsWith('-'));
+    return sub ? `${head} ${sub} *` : `${head} *`;
+  }
+
+  /**
+   * Enforce the bash policy for the extracted command nodes of a shell line.
+   *
+   * `commands` is the list of token arrays for every `command` node parsed out
+   * of the shell line (e.g. via tree-sitter), so command substitutions and
+   * chained commands are each evaluated independently — faithful to OpenCode's
+   * bash tool. `cd` is always allowed. A `deny` match throws `RejectedError`; any
+   * `ask` matches are batched into a single `Permission.ask`.
+   */
+  export async function checkBashTokens(input: {
+    commands: string[][];
+    command: string;
+    sessionID: string;
+    messageID: string;
+    callID?: string;
+  }) {
+    const patterns = policy().bash;
+    const askPatterns = new Set<string>();
+    for (const command of input.commands) {
+      if (command.length === 0) continue;
+      if (command[0] === 'cd') continue;
+      const action = Wildcard.allStructured(
+        { head: command[0], tail: command.slice(1) },
+        patterns
+      ) as Action | undefined;
+      if (action === 'deny') {
+        throw new RejectedError(
+          input.sessionID,
+          input.callID ?? input.messageID,
+          input.callID,
+          { command: input.command },
+          `The command "${command[0]}" is not allowed in the current permission mode (${config.permissionMode ?? 'auto'}). Configuration: ${JSON.stringify(
+            patterns
+          )}`
+        );
+      }
+      if (action === 'ask') {
+        askPatterns.add(askPattern(command));
+      }
+    }
+    if (askPatterns.size > 0) {
+      const list = Array.from(askPatterns);
+      await ask({
+        type: 'bash',
+        pattern: list,
+        sessionID: input.sessionID,
+        messageID: input.messageID,
+        callID: input.callID,
+        title: input.command,
+        metadata: { command: input.command, patterns: list },
+      });
+    }
+  }
+}

package/src/session/prompt.ts

@@ -1128,6 +1128,12 @@ export namespace SessionPrompt {
       ),
       mergeDeep(input.tools ?? {})
     );
+    // Enforce read-only / planning mode and explicit --disable-tools. These
+    // denials are applied last so they always win over agent and per-message
+    // tool overrides (issue #271).
+    for (const id of ToolRegistry.deniedTools()) {
+      enabledTools[id] = false;
+    }
     for (const item of await ToolRegistry.tools(
       input.model.providerID,
       input.model.modelID

package/src/session/system.ts

@@ -2,6 +2,7 @@ import { Ripgrep } from '../file/ripgrep';
 import { Global } from '../global';
 import { Filesystem } from '../util/filesystem';
 import { Config } from '../config/file-config';
+import { config as runtimeConfig } from '../config/config';
 
 import { Instance } from '../project/instance';
 import path from 'path';
@@ -42,6 +43,18 @@ export namespace SystemPrompt {
 
   export async function environment() {
     const project = Instance.project;
+    const readOnlyNote = runtimeConfig.readOnly
+      ? [
+          ``,
+          `<read_only_mode>`,
+          `  You are running in read-only / planning mode. Tools that modify the`,
+          `  filesystem or execute shell commands (bash, edit, write, multiedit,`,
+          `  patch) are disabled and will be rejected if attempted. You may only`,
+          `  read, search, and plan. Describe the changes you would make instead`,
+          `  of attempting to apply them.`,
+          `</read_only_mode>`,
+        ].join('\n')
+      : '';
     return [
       [
         `Here is some useful information about the environment you are running in:`,
@@ -51,6 +64,7 @@ export namespace SystemPrompt {
         `  Platform: ${process.platform}`,
         `  Today's date: ${new Date().toDateString()}`,
         `</env>`,
+        readOnlyNote,
         `<files>`,
         `  ${
           project.vcs === 'git'

package/src/tool/bash.ts

@@ -8,6 +8,7 @@ import { lazy } from '../util/lazy';
 import { Language } from 'web-tree-sitter';
 import { $ } from 'bun';
 import { Filesystem } from '../util/filesystem';
+import { Permission } from '../permission';
 import { fileURLToPath } from 'url';
 
 const MAX_OUTPUT_LENGTH = 30_000;
@@ -71,7 +72,46 @@ export const BashTool = Tool.define('bash', {
     }
     const timeout = Math.min(params.timeout ?? DEFAULT_TIMEOUT, MAX_TIMEOUT);
 
-    // No restrictions - unrestricted command execution
+    // Permission enforcement (issue #271). In the default `auto` mode every
+    // bash pattern resolves to `allow`, so we skip the tree-sitter parse
+    // entirely and keep zero overhead. In plan/readonly/ask modes (or with a
+    // `--permission` override) we parse the shell line into its individual
+    // command nodes and evaluate each against the bash policy: a `deny` match
+    // throws, `ask` matches are batched into a single JSON permission request.
+    if (Permission.bashEnforced()) {
+      const tree = await parser().then((p) => p.parse(params.command));
+      if (!tree) {
+        throw new Error('Failed to parse command');
+      }
+      const commands: string[][] = [];
+      for (const node of tree.rootNode.descendantsOfType('command')) {
+        if (!node) continue;
+        const command: string[] = [];
+        for (let i = 0; i < node.childCount; i++) {
+          const child = node.child(i);
+          if (!child) continue;
+          if (
+            child.type !== 'command_name' &&
+            child.type !== 'word' &&
+            child.type !== 'string' &&
+            child.type !== 'raw_string' &&
+            child.type !== 'concatenation'
+          ) {
+            continue;
+          }
+          command.push(child.text);
+        }
+        commands.push(command);
+      }
+      await Permission.checkBashTokens({
+        commands,
+        command: params.command,
+        sessionID: ctx.sessionID,
+        messageID: ctx.messageID,
+        callID: ctx.callID,
+      });
+    }
+
     const proc = spawn(params.command, {
       shell: true,
       cwd: Instance.directory,

package/src/tool/batch.ts

@@ -54,6 +54,14 @@ export const BatchTool = Tool.define('batch', async () => {
             );
           }
 
+          // Enforce read-only / planning mode and --disable-tools even when a
+          // tool is invoked indirectly through batch (issue #271).
+          if (ToolRegistry.deniedTools().has(call.tool)) {
+            throw new Error(
+              `Tool '${call.tool}' is disabled in read-only / planning mode and cannot be executed.`
+            );
+          }
+
           const tool = toolMap.get(call.tool);
           if (!tool) {
             const availableToolsList = Array.from(toolMap.keys()).filter(

package/src/tool/edit.ts

@@ -13,6 +13,7 @@ import { Bus } from '../bus';
 import { FileTime } from '../file/time';
 import { Instance } from '../project/instance';
 import { Snapshot } from '../snapshot';
+import { Permission } from '../permission';
 
 function normalizeLineEndings(text: string): string {
   return text.replaceAll('\r\n', '\n');
@@ -42,11 +43,21 @@ export const EditTool = Tool.define('edit', {
       throw new Error('oldString and newString must be different');
     }
 
-    // No restrictions - unrestricted file editing
     const filePath = path.isAbsolute(params.filePath)
       ? params.filePath
       : path.join(Instance.directory, params.filePath);
 
+    // Permission enforcement (issue #271). `auto` mode allows immediately;
+    // plan/readonly modes deny; `ask` mode emits a JSON permission request.
+    await Permission.check({
+      type: 'edit',
+      title: filePath,
+      sessionID: ctx.sessionID,
+      messageID: ctx.messageID,
+      callID: ctx.callID,
+      metadata: { filePath },
+    });
+
     let diff = '';
     let contentOld = '';
     let contentNew = '';

package/src/tool/patch.ts

@@ -8,6 +8,7 @@ import { FileWatcher } from '../file/watcher';
 import { Instance } from '../project/instance';
 import { Patch } from '../patch';
 import { Filesystem } from '../util/filesystem';
+import { Permission } from '../permission';
 import { createTwoFilesPatch } from 'diff';
 
 const PatchParams = z.object({
@@ -141,7 +142,24 @@ export const PatchTool = Tool.define('patch', {
       }
     }
 
-    // No restrictions - apply changes directly
+    // Permission enforcement (issue #271). Patching mutates the filesystem and
+    // is governed by the `edit` policy. `auto` allows; plan/readonly deny;
+    // `ask` emits a JSON permission request per affected file.
+    for (const change of fileChanges) {
+      await Permission.check({
+        type: 'edit',
+        title: change.movePath ?? change.filePath,
+        sessionID: ctx.sessionID,
+        messageID: ctx.messageID,
+        callID: ctx.callID,
+        metadata: {
+          filePath: change.filePath,
+          movePath: change.movePath,
+          changeType: change.type,
+        },
+      });
+    }
+
     // Apply the changes
     const changedFiles: string[] = [];
 

package/src/tool/registry.ts

@@ -16,8 +16,44 @@ import { Instance } from '../project/instance';
 import { Config } from '../config/file-config';
 import { WebSearchTool } from './websearch';
 import { CodeSearchTool } from './codesearch';
+import { config } from '../config/config';
 
 export namespace ToolRegistry {
+  /**
+   * Tools that can mutate the filesystem or execute shell commands.
+   * These are disabled when read-only / planning mode is active so that the
+   * agent can only read, search and plan. This is the native, enforceable
+   * counterpart of agent-commander's `--read-only` flag (issue #271).
+   */
+  export const READ_ONLY_DENIED_TOOLS = [
+    'bash',
+    'edit',
+    'write',
+    'multiedit',
+    'patch',
+  ] as const;
+
+  /**
+   * Resolve the set of tool ids that must be denied for the current run.
+   *
+   * Combines the read-only/planning preset (`config.readOnly`) with any
+   * explicit `--disable-tools a,b,c` list. The result is enforced both when
+   * exposing tools to the model and when tools are invoked indirectly via the
+   * `batch` tool, so the restriction cannot be bypassed.
+   */
+  export function deniedTools(): Set<string> {
+    const denied = new Set<string>();
+    if (config.readOnly) {
+      for (const id of READ_ONLY_DENIED_TOOLS) denied.add(id);
+    }
+    const list = config.disableTools ?? '';
+    for (const raw of list.split(',')) {
+      const id = raw.trim().toLowerCase();
+      if (id) denied.add(id);
+    }
+    return denied;
+  }
+
   export const state = Instance.state(async () => {
     const custom = [] as Tool.Info[];
     return { custom };

package/src/tool/webfetch.ts

@@ -3,6 +3,7 @@ import { Tool } from './tool';
 import TurndownService from 'turndown';
 import DESCRIPTION from './webfetch.txt';
 import { createVerboseFetch } from '../util/verbose-fetch';
+import { Permission } from '../permission';
 
 const verboseFetch = createVerboseFetch(fetch, { caller: 'webfetch' });
 
@@ -33,7 +34,17 @@ export const WebFetchTool = Tool.define('webfetch', {
       throw new Error('URL must start with http:// or https://');
     }
 
-    // No restrictions - unrestricted web fetch
+    // Permission enforcement (issue #271). `auto` allows; plan/readonly allow
+    // (webfetch is read-only); `ask` emits a JSON permission request.
+    await Permission.check({
+      type: 'webfetch',
+      title: params.url,
+      sessionID: ctx.sessionID,
+      messageID: ctx.messageID,
+      callID: ctx.callID,
+      metadata: { url: params.url },
+    });
+
     const timeout = Math.min(
       (params.timeout ?? DEFAULT_TIMEOUT / 1000) * 1000,
       MAX_TIMEOUT

package/src/tool/write.ts

@@ -3,6 +3,7 @@ import * as path from 'path';
 import { Tool } from './tool';
 import DESCRIPTION from './write.txt';
 import { Instance } from '../project/instance';
+import { Permission } from '../permission';
 
 export const WriteTool = Tool.define('write', {
   description: DESCRIPTION,
@@ -15,11 +16,22 @@ export const WriteTool = Tool.define('write', {
       ),
   }),
   async execute(params, ctx) {
-    // No restrictions - unrestricted file system access
     const filepath = path.isAbsolute(params.filePath)
       ? params.filePath
       : path.join(Instance.directory, params.filePath);
 
+    // Permission enforcement (issue #271). Writing is governed by the same
+    // `edit` policy as the edit tool: `auto` allows, plan/readonly deny,
+    // `ask` emits a JSON permission request.
+    await Permission.check({
+      type: 'edit',
+      title: filepath,
+      sessionID: ctx.sessionID,
+      messageID: ctx.messageID,
+      callID: ctx.callID,
+      metadata: { filePath: filepath },
+    });
+
     const file = Bun.file(filepath);
     const exists = await file.exists();