refactor: parse permissions example flags

examples/permissions/package.json

@@ -7,6 +7,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "commander": "^12.1.0",
     "sandbox-agent": "workspace:*"
   },
   "devDependencies": {

examples/permissions/src/index.ts

@@ -1,16 +1,18 @@
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
+import { Command } from "commander";
 import {
   SandboxAgent,
   type PermissionReply,
   type SessionPermissionRequest,
 } from "sandbox-agent";
 
-const agent = (process.env.PERMISSIONS_AGENT?.trim() || "claude").toLowerCase();
-const requestedPermissionMode = process.env.PERMISSION_MODE?.trim();
-const autoReply = parsePermissionReply(process.env.PERMISSION_REPLY);
+const options = parseOptions();
+const agent = options.agent.trim().toLowerCase();
+const permissionMode = options.permissionMode.trim();
+const autoReply = parsePermissionReply(options.reply);
 const promptText =
-  process.env.PERMISSION_PROMPT?.trim() ||
+  options.prompt?.trim() ||
   `Create ./permission-example.txt with the text 'hello from the ${agent} permissions example'.`;
 
 const sdk = await SandboxAgent.start({
@@ -30,7 +32,6 @@ try {
     : [];
   const modeOption = configOptions.find((option) => option.category === "mode");
   const availableModes = extractOptionValues(modeOption);
-  const permissionMode = requestedPermissionMode || modeOption?.currentValue || availableModes[0] || "default";
 
   console.log(`Agent: ${agent}`);
   console.log(`Permission mode: ${permissionMode}`);
@@ -159,3 +160,29 @@ function parsePermissionReply(value: string | undefined): PermissionReply | null
       return null;
   }
 }
+
+function parseOptions(): {
+  agent: string;
+  permissionMode: string;
+  prompt?: string;
+  reply?: string;
+} {
+  const argv = process.argv.slice(2);
+  const normalizedArgv = argv[0] === "--" ? argv.slice(1) : argv;
+  const program = new Command();
+  program
+    .name("permissions")
+    .description("Run a permissions example against an ACP agent session.")
+    .requiredOption("--agent <agent>", "Agent to run, for example 'claude' or 'codex'")
+    .requiredOption("--permission-mode <mode>", "Permission mode to configure for the session")
+    .option("--prompt <text>", "Prompt to send after the session starts")
+    .option("--reply <reply>", "Automatically answer permission prompts with once, always, or reject");
+
+  program.parse(normalizedArgv, { from: "user" });
+  return program.opts<{
+    agent: string;
+    permissionMode: string;
+    prompt?: string;
+    reply?: string;
+  }>();
+}

pnpm-lock.yaml

@@ -47,22 +47,6 @@ importers:
         specifier: latest
         version: 5.9.3
 
-  examples/claude-permissions:
-    dependencies:
-      sandbox-agent:
-        specifier: workspace:*
-        version: link:../../sdks/typescript
-    devDependencies:
-      '@types/node':
-        specifier: latest
-        version: 25.4.0
-      tsx:
-        specifier: latest
-        version: 4.21.0
-      typescript:
-        specifier: latest
-        version: 5.9.3
-
   examples/cloudflare:
     dependencies:
       '@cloudflare/sandbox':
@@ -287,6 +271,25 @@ importers:
         specifier: latest
         version: 5.9.3
 
+  examples/permissions:
+    dependencies:
+      commander:
+        specifier: ^12.1.0
+        version: 12.1.0
+      sandbox-agent:
+        specifier: workspace:*
+        version: link:../../sdks/typescript
+    devDependencies:
+      '@types/node':
+        specifier: latest
+        version: 25.4.0
+      tsx:
+        specifier: latest
+        version: 4.21.0
+      typescript:
+        specifier: latest
+        version: 5.9.3
+
   examples/persist-memory:
     dependencies:
       '@sandbox-agent/example-shared':