genaicode 2.11.0 → 2.13.2

package/docs/agents.md

@@ -119,19 +119,19 @@ session.send('Now cover it with a test'); // resumes the same agent session
 
 ## Drivers
 
-| Driver                | Command        | Mode                                     | Notes                                                                                  |
-| --------------------- | -------------- | ---------------------------------------- | -------------------------------------------------------------------------------------- |
-| `claude(options?)`    | `claude`       | `-p --output-format stream-json`         | `permissionMode` defaults to `acceptEdits`; `allowedTools` / `disallowedTools`         |
-| `codex(options?)`     | `codex`        | `exec --json`                            | `sandbox` defaults to `workspace-write`; effort via `model_reasoning_effort`           |
-| `muse(options?)`      | `muse`         | `exec --json --trust-workspace`          | `maxTurns` maps to `--max-model-steps`                                                 |
-| `codexLive(options?)` | `codex`        | `app-server` (JSON-RPC)                  | `steer()`, approvals, MCP. See [Live sessions](#live-sessions-steering-and-approvals)  |
-| `museLive(options?)`  | `muse`         | `serve` (JSON-RPC)                       | `steer()`, approvals. See [Live sessions](#live-sessions-steering-and-approvals)       |
-| `gemini(options?)`    | `gemini`       | `--output-format stream-json --prompt=…` | `approvalMode` defaults to `auto_edit`; `--skip-trust` unless `trustWorkspace: false`  |
-| `cursor(options?)`    | `cursor-agent` | `-p --output-format stream-json`         | `--force --approve-mcps` by default (`--trust` if `force: false`); `partialOutput`     |
-| `opencode(options?)`  | `opencode`     | `run --format json`                      | `model` is `provider/model`; `effort` maps to `--variant`; `autoApprove` adds `--auto` |
-| `copilot(options?)`   | `copilot`      | `--output-format json --prompt=…`        | `--allow-all-tools --no-ask-user` by default; `allowTools` / `denyTools` patterns      |
-| `vibe(options?)`      | `vibe`         | `--output streaming --prompt=…`          | `agent` defaults to `accept-edits`; `--trust`; `model` via `VIBE_ACTIVE_MODEL`         |
-| `antigravity(opts?)`  | `agy`          | `--output-format stream-json --print`    | `mode` defaults to `accept-edits`; `--sandbox` unless `sandbox: false`                 |
+| Driver                | Command        | Mode                                     | Notes                                                                                     |
+| --------------------- | -------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `claude(options?)`    | `claude`       | `-p --output-format stream-json`         | `permissionMode` defaults to `acceptEdits`; `allowedTools` / `disallowedTools`; approvals |
+| `codex(options?)`     | `codex`        | `exec --json`                            | `sandbox` defaults to `workspace-write`; effort via `model_reasoning_effort`              |
+| `muse(options?)`      | `muse`         | `exec --json --trust-workspace`          | `maxTurns` maps to `--max-model-steps`                                                    |
+| `codexLive(options?)` | `codex`        | `app-server` (JSON-RPC)                  | `steer()`, approvals, MCP. See [Live sessions](#live-sessions-steering-and-approvals)     |
+| `museLive(options?)`  | `muse`         | `serve` (JSON-RPC)                       | `steer()`, approvals. See [Live sessions](#live-sessions-steering-and-approvals)          |
+| `gemini(options?)`    | `gemini`       | `--output-format stream-json --prompt=…` | `approvalMode` defaults to `auto_edit`; `--skip-trust` unless `trustWorkspace: false`     |
+| `cursor(options?)`    | `cursor-agent` | `-p --output-format stream-json`         | `--force --approve-mcps` by default (`--trust` if `force: false`); `partialOutput`        |
+| `opencode(options?)`  | `opencode`     | `run --format json`                      | `model` is `provider/model`; `effort` maps to `--variant`; `autoApprove` adds `--auto`    |
+| `copilot(options?)`   | `copilot`      | `--output-format json --prompt=…`        | `--allow-all-tools --no-ask-user` by default; `allowTools` / `denyTools` patterns         |
+| `vibe(options?)`      | `vibe`         | `--output streaming --prompt=…`          | `agent` defaults to `accept-edits`; `--trust`; `model` via `VIBE_ACTIVE_MODEL`            |
+| `antigravity(opts?)`  | `agy`          | `--output-format stream-json --print`    | `mode` defaults to `accept-edits`; `--sandbox` unless `sandbox: false`                    |
 
 Every driver accepts `command` to point at a specific executable. `task.extraArgs` is
 inserted before the prompt for flags that have no portable field.
@@ -160,15 +160,125 @@ const result = await run.result;
 
 - `steer(text)` resolves once the agent acknowledges the input. It rejects after the task has
   ended, and when no acknowledgement arrives (the input may or may not have reached the agent).
-- `onApproval` is asked for each permission request. It gets a `command`, `file-change` or
-  `other` request and returns `'approve'` or `'deny'`. If `onApproval` is missing or throws, the
-  request is denied. Codex runs with approval policy `never` when no `onApproval` is set.
-- `museLive()` answers each approval with one of the choices Muse offers: the `once`
-  approve or deny choice where there is one. A multi-stage approval asks `onApproval` once
-  per stage; later stages get ids like `ap-1/2`.
+- `onApproval` answers permission requests; see [Approvals](#approvals).
 - The task ends when the agent reports its turn complete. The server is then stopped. An exit
   before that point is a failure, even with exit code 0.
 
+## Approvals
+
+`onApproval(request, signal)` answers the agent's permission prompts on drivers with
+`capabilities.approvals`: `claude`, `codexLive`, `museLive`. It returns `'approve'` or
+`'deny'`.
+
+```ts
+const run = claude().run({
+  prompt: 'Run the tests and fix what fails',
+  cwd: '/work/repo',
+  onApproval: (request, signal) => askUser(request, signal), // your UI
+});
+```
+
+- `request.kind` is `command`, `file-change` or `other`; `summary` is one line to show;
+  `detail` is the vendor's whole request (the command with its working directory, the tool
+  input, the requested permissions). Show `detail` before asking for a decision.
+- `request.scope` says what approving grants. `once` (or absent): this one call. `turn`: the
+  permissions in `detail` until the agent's current turn ends (Codex permission profiles).
+- `signal` aborts when the answer is no longer needed: the agent withdrew the request, the
+  turn ended, the process exited, or the task was stopped. Close the question then. A late
+  answer counts as `deny`.
+- No handler, a handler that throws, and an aborted signal all deny. Nothing is approved
+  automatically unless `permissions.approval` says so (see [Permissions](#permissions)).
+  `approval-request` and `approval-resolved` events record each question.
+
+Per agent:
+
+- `claude()`: with `onApproval`, the driver serves Claude Code's `--permission-prompt-tool`
+  from a private MCP endpoint on 127.0.0.1 (random port, random bearer token), next to the
+  task's own `mcpServers`, and raises `MCP_TOOL_TIMEOUT` to a day unless `env` sets it. The
+  permission mode still applies first (`acceptEdits` by default): only what it does not allow
+  is asked. Approving allows exactly the input Claude asked about (`updatedInput` unchanged).
+- `codexLive()`: runs with approval policy `on-request` when `onApproval` is set (`never`
+  otherwise). Commands and file changes are answered `accept` / `decline`. A permission
+  profile request (`item/permissions/requestApproval`) is asked with `scope: 'turn'`; approving
+  grants the requested categories (those that are not null) for the turn, denying grants none.
+  Requests from another thread or turn are rejected; `serverRequest/resolved` withdraws one.
+- `museLive()`: answers with one of the choices Muse offers and the stage's requirement id.
+  Approving picks the `once` choice; a request that only offers session-wide approval is
+  denied. A multi-stage approval asks once per stage (later stages get ids like `ap-1/2`),
+  however often a stage is delivered. `approval/resolved` withdraws an open question.
+
+The protocol handlers are exported for apps that run their own driver or MCP server:
+
+- `codexApprovals(session, ids)` and `museApprovals(session, ids, options?)` take a
+  `LiveSession` and a function returning the current `{ session, turn }` ids. Hand them each
+  request and notification first (`request()` returns `undefined`, `notification()` false,
+  for methods they do not own) and call `close()` when the turn ends.
+- `claudeApprovalTool(onApproval)` is the permission prompt tool as an MCP tool (`name`,
+  `description`, `inputSchema`, `call(args, signal)`) to serve from the app's own MCP server;
+  pass `claudeApprovalArgs(serverName)` to Claude and `claudeApprovalEnv(env)` in its env.
+  Abort `signal` when the MCP caller disconnects. `startClaudeApprovalServer(onApproval)`
+  serves the tool on its own endpoint instead.
+
+## Permissions
+
+`task.permissions` picks the approval policy and the sandbox in one place, and each driver
+translates it into the agent's own options. An omitted field keeps the driver's default (the
+behavior described above); `'yolo'` is `{ approval: 'auto-approve', sandbox: 'unrestricted' }`.
+
+```ts
+claude().run({ prompt, cwd, permissions: { approval: 'auto-approve', sandbox: 'workspace-write' } });
+codexLive().run({ prompt, cwd, permissions: 'yolo' });
+```
+
+- `approval`: `ask` sends prompts to `onApproval` (required then). `auto-approve` approves each
+  prompt without asking, for exactly the scope the agent asked for (one call, or a Codex
+  profile for the turn; never a session-wide grant). `deny` refuses whatever would need a
+  prompt and does not call `onApproval`.
+- `sandbox`: `workspace-write` turns on the agent's own sandbox (writes limited to `cwd`;
+  network rules are the vendor's), `read-only` its read-only mode, `unrestricted` no sandbox,
+  even when the agent's settings enable one. `auto-approve` never grants a step outside the
+  sandbox. With `ask`, Claude refuses such steps before asking and Codex permission profiles
+  (which widen the sandbox) are denied; a Codex command or file-change approval stays the
+  person's call, as in Codex itself, so approving it may let that one step leave the sandbox.
+- `capabilities.permissions` lists the values a driver accepts. Anything else, and any
+  combination the agent cannot honor, fails the run with `status: 'failed'` and an `error`
+  naming the value before the agent starts. Setting both a permissions field and the driver
+  option it replaces (`permissionMode`, `sandbox`, `approvalMode`, `force`...) is an error too.
+- Where genaicode sees the prompt (Claude's prompt tool, Muse), `auto-approve` and policy
+  denials still emit `approval-request` and `approval-resolved` with `automatic: true`, and
+  `createAgentSession` shows them as transcript entries. Agents that approve by themselves
+  (Codex with policy `never`, Gemini `yolo`, Cursor `--force`...) report nothing to show.
+
+| Driver          | approval                | sandbox                                  | Translation                                                                                                                                                                                                    |
+| --------------- | ----------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `claude()`      | ask, auto-approve, deny | workspace-write, read-only, unrestricted | `ask` / `auto-approve`: the prompt tool; `deny`: none. `workspace-write`: Claude's sandbox via `--settings` (required, no per-command escape), `acceptEdits`; `read-only`: `plan`; `unrestricted`: sandbox off |
+| `codex()`       | auto-approve, deny      | workspace-write, read-only, unrestricted | `approval_policy="never"` (exec never asks); `--sandbox` read-only / workspace-write / danger-full-access                                                                                                      |
+| `codexLive()`   | ask, auto-approve, deny | workspace-write, read-only, unrestricted | `ask`: policy `on-request`, otherwise `never`; `thread/start` sandbox as above                                                                                                                                 |
+| `museLive()`    | ask, auto-approve, deny | unrestricted                             | `ask` / `auto-approve`: approval mode `onRequest` (the `once` choice); `deny`: `denyUnmatched`. Muse has no sandbox                                                                                            |
+| `gemini()`      | auto-approve, deny      | workspace-write, read-only, unrestricted | `--approval-mode yolo` / `auto_edit`; `read-only`: `plan` (not with `auto-approve`); `--sandbox` / `--no-sandbox` plus `GEMINI_SANDBOX`, which overrides the flag in Gemini                                    |
+| `cursor()`      | auto-approve, deny      | workspace-write, read-only, unrestricted | `auto-approve`: `--force`, which runs commands unsandboxed, so only with `unrestricted`; `deny`: `--trust`; `--sandbox enabled` / `disabled`; `read-only`: `--mode ask`                                        |
+| `copilot()`     | auto-approve            | unrestricted                             | `--allow-all-tools` (prompt mode needs it); `--allow-all-paths --allow-all-urls`. Copilot's `--sandbox` lets a command opt out of it, so `workspace-write` is not offered                                      |
+| `opencode()`    | auto-approve, deny      | unrestricted                             | `--auto`; opencode has no sandbox                                                                                                                                                                              |
+| `vibe()`        | auto-approve, deny      | read-only, unrestricted                  | `--auto-approve`; `read-only`: `--agent plan` (not with `auto-approve`); no sandbox                                                                                                                            |
+| `antigravity()` | none                    | workspace-write, unrestricted            | `--sandbox` on or off                                                                                                                                                                                          |
+| `muse()`        | none                    | none                                     |                                                                                                                                                                                                                |
+
+Claude in `read-only` writes nothing in the workspace, but plan mode may still save its plan
+under `~/.claude/plans`. In `workspace-write`, Claude's sandbox covers Bash; edits through its
+file tools are accepted inside `cwd` and denied outside it.
+
+For apps that keep their own argument lists (an adapters file, say),
+`applyPermissionArgs(agent, args, permissions)` returns `{ args, env }` with the flags the
+translation owns replaced, using the same per-agent functions (`claudePermissionFlags`,
+`codexPermissionFlags`, `geminiPermissionFlags`, `cursorPermissionFlags`,
+`copilotPermissionFlags`, `opencodePermissionFlags`, `vibePermissionFlags`,
+`antigravityPermissionFlags`; `codexThreadPolicy` for the app server). For Claude, `ask` and
+`auto-approve` also need the prompt tool: `claudeApprovalTool(handler, { sandbox, cwd })`
+denies requests outside the sandbox before asking, and `decideApproval(task, request, signal)`
+applies the approval policy the way the drivers do.
+
+## Custom live agents
+
 For other JSON-RPC agents, `liveAgent({ name, command, args, drive })` provides the process,
 an `RpcPeer`, event emission, the approval flow, and `setSteer()`. `drive(session)` runs the
 protocol and resolves with `{ ok, error? }` when the turn ends.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genaicode",
-  "version": "2.11.0",
+  "version": "2.13.2",
   "description": "A small, provider-neutral TypeScript toolkit for calling LLMs from backend code.",
   "author": "Grzegorz Tańczyk",
   "repository": {
@@ -86,8 +86,8 @@
     "@types/node": "^20.0.0",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
-    "@typescript-eslint/eslint-plugin": "^7.17.0",
-    "@typescript-eslint/parser": "^7.17.0",
+    "@typescript-eslint/eslint-plugin": "^8.71.1",
+    "@typescript-eslint/parser": "^8.71.1",
     "esbuild": "^0.28.2",
     "eslint": "^8.54.0",
     "eslint-config-prettier": "^9.0.0",
@@ -95,14 +95,14 @@
     "husky": "^9.1.1",
     "ink": "^6.8.0",
     "ink-testing-library": "^4.0.0",
-    "lint-staged": "^15.2.7",
+    "lint-staged": "^16.4.0",
     "playwright": "^1.56.1",
     "prettier": "^3.1.0",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
     "typescript": "^5.0.0",
     "vite": "^6.4.3",
-    "vitest": "^3.0.7"
+    "vitest": "^4.1.11"
   },
   "lint-staged": {
     "*.{js,ts,md}": "prettier --write"