@link-assistant/agent 0.23.0 → 0.24.1

package/README.md

@@ -286,6 +286,10 @@ Options:
                                  Default: opencode/minimax-m2.5-free
   --json-standard                JSON output format standard
                                  Choices: "opencode" (default), "claude" (experimental)
+  --output-format                Alias for JSON output format
+                                 Choices: "json" (OpenCode), "stream-json" (Claude NDJSON)
+  --input-format                 Input format
+                                 Choices: "text" (default), "stream-json" (Claude JSONL)
   --use-existing-claude-oauth    Use existing Claude OAuth credentials
                                  from ~/.claude/.credentials.json
   --system-message               Full override of the system message
@@ -293,6 +297,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)
@@ -378,6 +394,21 @@ echo "your message here" | agent
 }
 ```
 
+**Live `stream-json`:**
+
+For bidirectional drivers, use:
+
+```bash
+agent --input-format stream-json --output-format stream-json
+```
+
+The live contract supports `user_prompt`, `system`, `interrupt`, and
+`permission_response` frames on stdin. It emits replay acknowledgements for
+consumed user frames and an explicit idle/turn-boundary event
+(`session_idle` in OpenCode output, `idle` in Claude output). See
+[docs/stdin-mode.md](../docs/stdin-mode.md#live-stream-json-contract) for the
+session resume and steering semantics.
+
 ## Supported Tools
 
 All 13 tools are **enabled by default** with **no configuration required**. See [TOOLS.md](../TOOLS.md) for complete documentation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/agent",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "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,8 @@ 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 { outputBusEvent } from './event-handler.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 +325,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;
@@ -386,62 +401,14 @@ export async function runContinuousServerMode(
 
     // Subscribe to all bus events and output in selected format
     unsub = Bus.subscribeAll((event) => {
-      if (event.type === 'message.part.updated') {
-        const part = event.properties.part;
-        if (part.sessionID !== sessionID) {
-          return;
-        }
-
-        if (part.type === 'step-start') {
-          eventHandler.output({
-            type: 'step_start',
-            timestamp: Date.now(),
-            sessionID,
-            part,
-          });
-        }
-
-        if (part.type === 'step-finish') {
-          eventHandler.output({
-            type: 'step_finish',
-            timestamp: Date.now(),
-            sessionID,
-            part,
-          });
-        }
-
-        if (part.type === 'text' && part.time?.end) {
-          eventHandler.output({
-            type: 'text',
-            timestamp: Date.now(),
-            sessionID,
-            part,
-          });
-        }
-
-        if (part.type === 'tool') {
-          eventHandler.output({
-            type: 'tool_use',
-            timestamp: Date.now(),
-            sessionID,
-            part,
-          });
-        }
-      }
-
-      if (event.type === 'session.error') {
-        const props = event.properties;
-        if (props.sessionID !== sessionID || !props.error) {
-          return;
-        }
-        hasError = true;
-        eventHandler.output({
-          type: 'error',
-          timestamp: Date.now(),
-          sessionID,
-          error: props.error,
-        });
-      }
+      outputBusEvent({
+        event,
+        sessionID,
+        eventHandler,
+        onError: () => {
+          hasError = true;
+        },
+      });
     });
 
     // Create continuous stdin reader
@@ -577,6 +544,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;
@@ -634,62 +614,14 @@ export async function runContinuousDirectMode(
 
     // Subscribe to all bus events and output in selected format
     unsub = Bus.subscribeAll((event) => {
-      if (event.type === 'message.part.updated') {
-        const part = event.properties.part;
-        if (part.sessionID !== sessionID) {
-          return;
-        }
-
-        if (part.type === 'step-start') {
-          eventHandler.output({
-            type: 'step_start',
-            timestamp: Date.now(),
-            sessionID,
-            part,
-          });
-        }
-
-        if (part.type === 'step-finish') {
-          eventHandler.output({
-            type: 'step_finish',
-            timestamp: Date.now(),
-            sessionID,
-            part,
-          });
-        }
-
-        if (part.type === 'text' && part.time?.end) {
-          eventHandler.output({
-            type: 'text',
-            timestamp: Date.now(),
-            sessionID,
-            part,
-          });
-        }
-
-        if (part.type === 'tool') {
-          eventHandler.output({
-            type: 'tool_use',
-            timestamp: Date.now(),
-            sessionID,
-            part,
-          });
-        }
-      }
-
-      if (event.type === 'session.error') {
-        const props = event.properties;
-        if (props.sessionID !== sessionID || !props.error) {
-          return;
-        }
-        hasError = true;
-        eventHandler.output({
-          type: 'error',
-          timestamp: Date.now(),
-          sessionID,
-          error: props.error,
-        });
-      }
+      outputBusEvent({
+        event,
+        sessionID,
+        eventHandler,
+        onError: () => {
+          hasError = true;
+        },
+      });
     });
 
     // Create continuous stdin reader

package/src/cli/event-handler.js

@@ -26,84 +26,126 @@ export function createBusEventSubscription({
   });
 
   const unsub = Bus.subscribeAll((event) => {
-    // Output events in selected JSON format
-    if (event.type === 'message.part.updated') {
-      const part = event.properties.part;
-      if (part.sessionID !== sessionID) {
-        return;
-      }
-
-      // Output different event types
-      if (part.type === 'step-start') {
-        eventHandler.output({
-          type: 'step_start',
-          timestamp: Date.now(),
-          sessionID,
-          part,
-        });
-      }
+    outputBusEvent({
+      event,
+      sessionID,
+      eventHandler,
+      onError,
+      onIdle: idleResolve,
+    });
+  });
 
-      if (part.type === 'step-finish') {
-        eventHandler.output({
-          type: 'step_finish',
-          timestamp: Date.now(),
-          sessionID,
-          part,
-        });
-      }
+  return { unsub, idlePromise };
+}
 
-      if (part.type === 'text' && part.time?.end) {
-        eventHandler.output({
-          type: 'text',
-          timestamp: Date.now(),
-          sessionID,
-          part,
-        });
-      }
+export function outputBusEvent({
+  event,
+  sessionID,
+  eventHandler,
+  onError,
+  onIdle,
+}) {
+  // Output events in selected JSON format
+  if (event.type === 'message.part.updated') {
+    const part = event.properties.part;
+    if (part.sessionID !== sessionID) {
+      return;
+    }
 
-      if (part.type === 'tool') {
-        eventHandler.output({
-          type: 'tool_use',
-          timestamp: Date.now(),
-          sessionID,
-          part,
-        });
+    // Output different event types
+    if (part.type === 'step-start') {
+      eventHandler.output({
+        type: 'step_start',
+        timestamp: Date.now(),
+        sessionID,
+        part,
+      });
+    }
 
-        // If tool failed, also output an error event
-        if (part.state?.status === 'error') {
-          eventHandler.output({
-            type: 'error',
-            timestamp: Date.now(),
-            sessionID,
-            error: part.state.error || 'Tool execution failed',
-          });
-        }
-      }
+    if (part.type === 'step-finish') {
+      eventHandler.output({
+        type: 'step_finish',
+        timestamp: Date.now(),
+        sessionID,
+        part,
+      });
     }
 
-    // Handle session idle to know when to stop
-    if (
-      event.type === 'session.idle' &&
-      event.properties.sessionID === sessionID
-    ) {
-      idleResolve();
+    if (part.type === 'text' && part.time?.end) {
+      eventHandler.output({
+        type: 'text',
+        timestamp: Date.now(),
+        sessionID,
+        part,
+      });
     }
 
-    // Handle errors
-    if (event.type === 'session.error') {
-      const props = event.properties;
-      if (props.sessionID !== sessionID || !props.error) {
-        return;
-      }
-      onError();
+    if (part.type === 'tool') {
       eventHandler.output({
-        type: 'error',
+        type: 'tool_use',
         timestamp: Date.now(),
         sessionID,
-        error: props.error,
+        part,
       });
+
+      // If tool failed, also output an error event
+      if (part.state?.status === 'error') {
+        eventHandler.output({
+          type: 'error',
+          timestamp: Date.now(),
+          sessionID,
+          error: part.state.error || 'Tool execution failed',
+        });
+      }
     }
-  });
+  }
 
-  return { unsub, idlePromise };
+  // 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' &&
+    event.properties.sessionID === sessionID
+  ) {
+    eventHandler.output({
+      type: 'session_idle',
+      timestamp: Date.now(),
+      sessionID,
+    });
+    onIdle?.();
+  }
+
+  // Handle errors
+  if (event.type === 'session.error') {
+    const props = event.properties;
+    if (props.sessionID !== sessionID || !props.error) {
+      return;
+    }
+    onError();
+    eventHandler.output({
+      type: 'error',
+      timestamp: Date.now(),
+      sessionID,
+      error: props.error,
+    });
+  }
 }

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/json-standard/index.ts

@@ -18,7 +18,13 @@ export type JsonStandard = 'opencode' | 'claude';
  * OpenCode JSON event types
  */
 export interface OpenCodeEvent {
-  type: 'step_start' | 'step_finish' | 'text' | 'tool_use' | 'error';
+  type:
+    | 'step_start'
+    | 'step_finish'
+    | 'text'
+    | 'tool_use'
+    | 'error'
+    | 'session_idle';
   timestamp: number;
   sessionID: string;
   part?: Record<string, unknown>;
@@ -29,7 +35,7 @@ export interface OpenCodeEvent {
  * Claude JSON event types (stream-json format)
  */
 export interface ClaudeEvent {
-  type: 'init' | 'message' | 'tool_use' | 'tool_result' | 'result';
+  type: 'init' | 'message' | 'tool_use' | 'tool_result' | 'result' | 'idle';
   timestamp?: string;
   session_id?: string;
   role?: 'assistant' | 'user';
@@ -126,6 +132,13 @@ export function convertOpenCodeToClaude(
         duration_ms: event.timestamp - startTime,
       };
 
+    case 'session_idle':
+      return {
+        type: 'idle',
+        timestamp,
+        session_id,
+      };
+
     case 'error':
       return {
         type: 'result',