@koalaauto/agentchannel 0.0.0-stage → 3.0.0-rc.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# agentchannel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Hand work between your team's agents (Claude Code, Codex) and follow it in one
+panel. This package is the `ach` command: the CLI, the MCP server your
+interactive agent talks to (`ach mcp`), and the runner that picks up tasks in
+the background (`ach run`).
+
+You need a team hub. Your admin runs it and sends you one line.
+
+## Join in one line
+
+Your admin sends you a short paragraph. Paste it into your Claude Code or
+Codex and it does the setup for you (it asks before installing the background
+helper). Or paste just the line in it into a terminal (Node.js 20 or later):
+
+```sh
+npx -y @koalaauto/agentchannel@3 join ach2.eyJodWIiOi...
+```
+
+The line works once: it holds a one-time join token that `join` exchanges with
+the hub for your agent's key. Running the same line again on the same machine keeps the key it
+saved; on another machine, ask your admin for a new invite.
+
+`join` shows the hub address in the line (a plain `http://` address is refused
+unless it is this machine or a `*.localhost` / `*.test` name), stores the key in
+your OS keychain, and adds AgentChannel to **the agent's own tool only**:
+
+| Agent runtime | What it runs |
+|---|---|
+| `claude` | `claude mcp add --scope user ach -- <ach> mcp` (changes `~/.claude.json`, or `$CLAUDE_CONFIG_DIR/.claude.json`) |
+| `codex` | `codex mcp add ach -- <ach> mcp` (changes `~/.codex/config.toml`, or `$CODEX_HOME/config.toml`) |
+| `other` | both, for the ones you installed yourself |
+
+`<ach>` is `npx -y @koalaauto/agentchannel@<version>` when you ran the line through npx
+(nothing is installed globally), else the `ach` you ran. Nothing else is
+installed or changed.
+
+- In a terminal it asks once (the hub, then the command above); Enter accepts.
+- Run by an agent (pasted into Claude Code / Codex), there is no one to ask:
+  pasting the line was the consent, so it does the same and says what it ran.
+- `--service` also installs the background helper (`ach run --install-service
+  --interactive-first` for the current directory; `--notify` only on a machine
+  with a desktop). Through npx it first installs this version globally, since a
+  service cannot run from the npx cache.
+- `--dry-run` prints the plan; the invite is not used and nothing is written.
+- `--yes` skips the question.
+
+If another program called `ach` comes first on your PATH, `join` and `doctor` say so.
+
+When it says **Done**, open the tool it names and say:
+
+> check my AgentChannel inbox
+
+## Check your setup
+
+```sh
+ach doctor
+```
+
+It reports three things, each problem with a one-line fix:
+
+- **Hub**: the hub answers over HTTPS at its public address, and your clock matches it.
+- **Front door**: if the hub sits behind a sign-in page, this machine has a valid pass for it. The pass comes in the join line only when your admin opted in (`ach admin invite <agent> --cf-token`); otherwise use your own sign-in or a pass your admin gives you (`ACH_CF_ID` / `ACH_CF_SECRET`). If it expired, ask your admin for a new line.
+- **Hub** also warns when the hub address is plain `http://` to anything but this machine.
+- **MCP entries**: read back from `claude mcp get ach` / `codex mcp get ach`: the exact command each one runs, whether that is this CLI, and its AgentChannel home.
+- **Key**: the hub accepts your agent's key.
+
+It also checks this machine: which `ach` runs first on PATH, Claude Code and
+Codex login, and the `ach` MCP entry.
+
+## Who decides
+
+`ach ask-human` asks your own agent's owner by default. When the call belongs
+to someone else in the task's channel (an ops decision to the ops owner), add
+`--to <name or email>`: they decide and you are cc'd. Someone outside the
+channel is refused (`小林 is not a member of #ops-data`). `--to both` asks
+both sides' owners.
+
+## Reminders, never content
+
+When something needs you (a question, a decision, a mention), AgentChannel
+reminds you with one line, never the message itself:
+
+> AgentChannel: 2 items need you (1 question, 1 decision) — say 'check my inbox'
+
+- **Inside an open Claude Code session**: `ach mcp` sends the line as a Claude
+  Code channel event. Claude Code shows channel events only when started with
+  channels enabled for the `ach` server, for example
+  `claude --dangerously-load-development-channels server:ach` (research
+  preview). Without that the event is dropped silently and nothing breaks.
+- **Inside an open Codex session**: `ach mcp` runs
+  `codex queue --thread <session> --message "<the line>"` when Codex tells it
+  the session id (`CODEX_THREAD_ID`; or set `ACH_CODEX_THREAD_ID`). Otherwise
+  it does nothing and the desktop notification covers it.
+- **Desktop** (`ach run --notify`, on by default with `--install-service`):
+  an OS notification. Decision requests show their options as buttons where
+  the OS can report the click: macOS with
+  [`alerter`](https://github.com/vjeantet/alerter) installed (else
+  terminal-notifier / osascript without buttons), Linux `notify-send` with
+  `--action` (libnotify 0.7.9+), Windows toast buttons. A click never answers for you:
+  it opens the panel at the decision with that option preselected
+  (`#/t/T-12/m/<id>?pick=<i>`), and you press Send there. The helper runs with
+  your agent's key, which must not stand in for your own reply.
+
+At most one reminder per 10 minutes; changes inside the window become one
+reminder at its end. The content is fetched only when you ask ("check my
+inbox"). `ACH_SESSION_NOTICES=0` turns the session reminders off. The helper
+follows the hub's change stream (a 25 s long poll) and falls back to polling
+every 15 s.
+
+```sh
+ach notify --test     # shows a test desktop notification
+```
+
+## Everyday commands
+
+```sh
+ach inbox                     # what is waiting for you
+ach send --to <agent> ...     # hand a task to another agent
+ach open                      # open the panel in your browser, logged in
+ach run --dir <repo>          # work tasks on this machine (foreground)
+ach help                      # everything else
+```
+
+## For admins
+
+```sh
+ach admin invite <agent>              # a paragraph for the owner to paste into Claude/Codex (zh if the hub's language is zh)
+ach admin invite <agent> --line       # only the join line: npx -y @koalaauto/agentchannel@3 join ach2....
+ach admin invite <person> [--feishu]  # a one-time login link for the panel (--feishu sends it on Feishu)
+ach admin avatars priority upload,feishu,github,gravatar
+```
+
+Every link and line works once or expires, and a new one replaces the old.
+Send them privately until they are used.
+
+## Background runs are isolated
+
+Tasks the helper runs in the background never load your personal agent setup:
+Claude runs with no user/project settings and no MCP servers
+(`settingSources: []`, `strictMcpConfig`); Codex runs with its own
+`CODEX_HOME` holding a generated `config.toml` (no `mcp_servers`, profiles,
+hooks or global `AGENTS.md`) and a link to the login file of your Codex home
+(placed by path; the file is never read or copied by AgentChannel).
+
+## Where things are kept
+
+- Settings: `~/.config/agentchannel/config.json` (set `AGENTCHANNEL_HOME` to move it).
+- Secrets (agent key, front-door pass, admin session): the OS keychain, or files
+  with mode 0600 in the same folder when no keychain is available.
+
+## License
+
+Apache-2.0. Contributor notes and the security model are in `DEVELOPMENT.md`
+in the source repository.

package/dist/src/adapters/claude.d.ts

@@ -0,0 +1,65 @@
+import type { CanUseTool, HookCallbackMatcher, Options } from '@anthropic-ai/claude-agent-sdk';
+import type { Perm } from '../perm.js';
+import { type PathPolicy } from './paths.js';
+import type { AdapterResult, AdapterRunOptions, RuntimeAdapter } from './types.js';
+/** Best-effort Bash deny list for `workdir` (the SDK sandbox is the real boundary). */
+export declare const BASH_DENY: RegExp[];
+/** S3: the only `ach` subcommands a spawned agent is pre-approved to run. */
+export declare const WORK_ACH_TOOLS: string[];
+export declare const ANSWER_ACH_TOOLS: string[];
+/** §16 mention runs: read the thread and channel, reply in the thread (with evidence, or --escalate). */
+export declare const MENTION_ACH_TOOLS: string[];
+/** canUseTool for workdir: path policy (reads under $HOME, writes outside cwd) plus the Bash deny list. */
+export declare function workdirCanUseTool(pol: PathPolicy): CanUseTool;
+/**
+ * PreToolUse hook with the same path policy. Hooks run even for tools that
+ * allowedTools pre-approves (Read/Glob/Grep), which canUseTool never sees.
+ */
+export declare function pathPolicyHook(pol: PathPolicy): HookCallbackMatcher;
+export declare function hostOf(url?: string): string | undefined;
+export interface ClaudePermInput {
+    cwd: string;
+    hub?: string;
+    mode?: 'work' | 'answer' | 'mention';
+    /** Readable roots under $HOME besides cwd (toolchain, git common dir). */
+    readRoots?: string[];
+    denyReadPaths?: string[];
+    home?: string;
+    /** B1: the AgentChannel home, denied to sandboxed commands (allowRead re-allows cwd and read roots). */
+    achHome?: string;
+    /** P2: hub `net_allow` of the agent; see sandboxNetwork(). */
+    netAllow?: string[];
+}
+/**
+ * P2: sandbox network policy. The hub host is always reachable (the agent's
+ * `ach` needs it). A concrete list is a strict allowlist; "*" lifts the domain
+ * restriction (admin-only on the hub).
+ */
+export declare function sandboxNetwork(hubHost: string | undefined, netAllow?: string[]): NonNullable<Options['sandbox']>['network'];
+/**
+ * Permission-related query options (§14.4 as amended by round 1). Pure, unit-tested.
+ * - settingSources: [] (S1): no user/project/local settings, hooks, MCP servers
+ *   or CLAUDE.md from the (sender-influenced) worktree.
+ * - allowedTools: only the `ach` subcommands of the run's mode (S3).
+ * - read/workdir: the SDK sandbox denies reads under $HOME except cwd and the
+ *   read roots; a PreToolUse hook applies the same policy to file tools (S4).
+ * - workdir writes: cwd only. The git common dir is NOT writable (S10); the
+ *   runner commits after the run.
+ */
+export declare function claudePermOptions(perm: Perm, o: ClaudePermInput): Partial<Options>;
+/** Error text of a result message (C9): never the word "success" for a failed run. */
+export declare function resultError(m: {
+    subtype?: string;
+    is_error?: boolean;
+    errors?: string[];
+    result?: string;
+}): string;
+export interface ClaudeAdapterOptions {
+    model?: string;
+}
+export declare class ClaudeAdapter implements RuntimeAdapter {
+    private o;
+    readonly name = "claude";
+    constructor(o?: ClaudeAdapterOptions);
+    run(opts: AdapterRunOptions): Promise<AdapterResult>;
+}

package/dist/src/adapters/claude.js

@@ -0,0 +1,243 @@
+import { homedir } from 'node:os';
+import { toolDenied } from './paths.js';
+import { spawnGroup } from './procgroup.js';
+/** Best-effort Bash deny list for `workdir` (the SDK sandbox is the real boundary). */
+export const BASH_DENY = [
+    /\brm\s+-[a-z]*r[a-z]*f?[a-z]*\s+(\/|~|\$HOME)(\s|$)/i,
+    /\bgit\s+push\b.*(--force\b|-f\b|--force-with-lease\b)/,
+    /\b(curl|wget)\b[^|]*\|\s*(ba|z)?sh\b/,
+    /\bsudo\b/,
+    /\bchmod\s+-R\s+777\s+\//,
+];
+/** S3: the only `ach` subcommands a spawned agent is pre-approved to run. */
+export const WORK_ACH_TOOLS = [
+    'Bash(ach progress:*)',
+    'Bash(ach ask:*)',
+    'Bash(ach decide-request:*)',
+    'Bash(ach ask-human:*)',
+    'Bash(ach decide:*)',
+    'Bash(ach complete:*)',
+    'Bash(ach fail:*)',
+    'Bash(ach task:*)',
+    'Bash(ach channel:*)',
+    'Bash(ach thread:*)',
+    'Bash(ach reply:*)',
+];
+export const ANSWER_ACH_TOOLS = ['Bash(ach answer:*)', 'Bash(ach decide-request:*)', 'Bash(ach ask-human:*)', 'Bash(ach task:*)'];
+/** §16 mention runs: read the thread and channel, reply in the thread (with evidence, or --escalate). */
+export const MENTION_ACH_TOOLS = ['Bash(ach reply:*)', 'Bash(ach thread:*)', 'Bash(ach channel:*)'];
+/** canUseTool for workdir: path policy (reads under $HOME, writes outside cwd) plus the Bash deny list. */
+export function workdirCanUseTool(pol) {
+    return async (toolName, input) => {
+        const why = toolDenied(pol, toolName, input);
+        if (why)
+            return { behavior: 'deny', message: why };
+        if (toolName === 'Bash') {
+            const cmd = String(input.command ?? '');
+            if (BASH_DENY.some((re) => re.test(cmd))) {
+                return { behavior: 'deny', message: 'Command is on the AgentChannel deny list' };
+            }
+        }
+        return { behavior: 'allow', updatedInput: input };
+    };
+}
+/**
+ * PreToolUse hook with the same path policy. Hooks run even for tools that
+ * allowedTools pre-approves (Read/Glob/Grep), which canUseTool never sees.
+ */
+export function pathPolicyHook(pol) {
+    return {
+        hooks: [
+            async (input) => {
+                if (input.hook_event_name !== 'PreToolUse')
+                    return {};
+                const why = toolDenied(pol, input.tool_name, (input.tool_input ?? {}));
+                if (!why)
+                    return {};
+                return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: why } };
+            },
+        ],
+    };
+}
+export function hostOf(url) {
+    if (!url)
+        return undefined;
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * P2: sandbox network policy. The hub host is always reachable (the agent's
+ * `ach` needs it). A concrete list is a strict allowlist; "*" lifts the domain
+ * restriction (admin-only on the hub).
+ */
+export function sandboxNetwork(hubHost, netAllow) {
+    const list = netAllow ?? ['api.anthropic.com'];
+    const domains = Array.from(new Set([...(hubHost ? [hubHost] : []), ...list.map((d) => d.toLowerCase())]));
+    if (domains.includes('*'))
+        return { allowedDomains: ['*'] };
+    return netAllow ? { allowedDomains: domains, strictAllowlist: true } : { allowedDomains: domains };
+}
+/**
+ * Permission-related query options (§14.4 as amended by round 1). Pure, unit-tested.
+ * - settingSources: [] (S1): no user/project/local settings, hooks, MCP servers
+ *   or CLAUDE.md from the (sender-influenced) worktree.
+ * - allowedTools: only the `ach` subcommands of the run's mode (S3).
+ * - read/workdir: the SDK sandbox denies reads under $HOME except cwd and the
+ *   read roots; a PreToolUse hook applies the same policy to file tools (S4).
+ * - workdir writes: cwd only. The git common dir is NOT writable (S10); the
+ *   runner commits after the run.
+ */
+export function claudePermOptions(perm, o) {
+    const home = o.home ?? homedir();
+    const denyRead = o.denyReadPaths ?? [];
+    // Permission-rule paths: `//abs/path/**` means an absolute path.
+    const disallowedTools = denyRead.flatMap((p) => [`Read(/${p})`, `Read(/${p}/**)`, `Edit(/${p})`, `Edit(/${p}/**)`]);
+    const achTools = o.mode === 'answer' ? ANSWER_ACH_TOOLS : o.mode === 'mention' ? MENTION_ACH_TOOLS : WORK_ACH_TOOLS;
+    // strictMcpConfig: no MCP servers from ~/.claude.json or .mcp.json either (only ones passed here: none)
+    const base = { settingSources: [], strictMcpConfig: true, disallowedTools };
+    if (perm === 'full') {
+        return { ...base, permissionMode: 'bypassPermissions', allowDangerouslySkipPermissions: true };
+    }
+    const pol = {
+        home,
+        cwd: o.cwd,
+        readRoots: o.readRoots ?? [],
+        writeRoots: perm === 'workdir' ? [o.cwd] : [],
+        deny: denyRead,
+    };
+    const hubHost = hostOf(o.hub);
+    const sandbox = {
+        enabled: true,
+        // read: only the pre-approved `ach` commands may run, sandboxed or not.
+        autoAllowBashIfSandboxed: perm === 'workdir',
+        allowUnsandboxedCommands: false,
+        filesystem: {
+            allowWrite: perm === 'workdir' ? [o.cwd] : [],
+            denyRead: [home, ...(o.achHome ? [o.achHome] : []), ...denyRead],
+            allowRead: [o.cwd, ...(o.readRoots ?? [])],
+        },
+        network: sandboxNetwork(hubHost, o.netAllow),
+    };
+    const common = {
+        ...base,
+        allowedTools: ['Read', 'Glob', 'Grep', ...achTools],
+        sandbox,
+        hooks: { PreToolUse: [pathPolicyHook(pol)] },
+    };
+    if (perm === 'read')
+        return { ...common, permissionMode: 'dontAsk' };
+    return { ...common, permissionMode: 'acceptEdits', canUseTool: workdirCanUseTool(pol) };
+}
+/** Error text of a result message (C9): never the word "success" for a failed run. */
+export function resultError(m) {
+    const errs = (m.errors ?? []).filter(Boolean).join('; ');
+    if (errs)
+        return errs;
+    if (m.is_error && typeof m.result === 'string' && m.result.trim())
+        return m.result.trim();
+    if (m.subtype && m.subtype !== 'success')
+        return m.subtype;
+    return 'the run ended with an error';
+}
+export class ClaudeAdapter {
+    o;
+    name = 'claude';
+    constructor(o = {}) {
+        this.o = o;
+    }
+    async run(opts) {
+        const { query } = await import('@anthropic-ai/claude-agent-sdk');
+        const abortController = new AbortController();
+        const onAbort = () => abortController.abort();
+        if (opts.signal.aborted)
+            abortController.abort();
+        else
+            opts.signal.addEventListener('abort', onAbort, { once: true });
+        const options = {
+            cwd: opts.cwd,
+            env: opts.env,
+            abortController,
+            ...(opts.resume ? { resume: opts.resume } : {}),
+            ...(this.o.model ? { model: this.o.model } : {}),
+            ...claudePermOptions(opts.perm, {
+                cwd: opts.cwd,
+                hub: opts.hub,
+                mode: opts.mode,
+                readRoots: opts.readRoots,
+                denyReadPaths: opts.denyReadPaths,
+                home: opts.realHome ?? opts.env.HOME,
+                achHome: opts.achHome,
+                netAllow: opts.netAllow,
+            }),
+            spawnClaudeCodeProcess: (s) => spawnGroup(s.command, s.args, {
+                cwd: s.cwd,
+                env: s.env,
+                signal: s.signal,
+                onStderr: (t) => opts.onEvent({ type: 'error', data: t }),
+            }),
+        };
+        let sessionId;
+        let finalText = '';
+        let costUsd;
+        let ok = false;
+        let error;
+        const lastText = [];
+        try {
+            for await (const m of query({ prompt: opts.prompt, options })) {
+                const anyM = m;
+                if (anyM.session_id && anyM.session_id !== sessionId) {
+                    sessionId = anyM.session_id;
+                    opts.onEvent({ type: 'session', data: sessionId });
+                }
+                if (m.type === 'assistant') {
+                    for (const b of (anyM.message?.content ?? [])) {
+                        if (b.type === 'text' && b.text) {
+                            lastText.push(b.text);
+                            opts.onEvent({ type: 'text', data: b.text });
+                        }
+                        else if (b.type === 'tool_use') {
+                            opts.onEvent({ type: 'tool_start', data: { id: b.id, name: b.name, input: b.input } });
+                        }
+                    }
+                }
+                else if (m.type === 'user') {
+                    const content = anyM.message?.content;
+                    for (const b of (Array.isArray(content) ? content : [])) {
+                        if (b?.type === 'tool_result')
+                            opts.onEvent({ type: 'tool_end', data: { id: b.tool_use_id } });
+                    }
+                }
+                else if (m.type === 'result') {
+                    costUsd = anyM.total_cost_usd;
+                    opts.onEvent({ type: 'usage', data: { costUsd, usage: anyM.usage } });
+                    if (anyM.subtype === 'success' && !anyM.is_error) {
+                        ok = true;
+                        finalText = anyM.result ?? '';
+                    }
+                    else {
+                        error = resultError(anyM);
+                        finalText = lastText.join('\n');
+                    }
+                }
+                else {
+                    opts.onEvent({ type: 'tool', data: { type: m.type, subtype: anyM.subtype } });
+                }
+            }
+        }
+        catch (e) {
+            ok = false;
+            error = opts.signal.aborted ? 'aborted' : String(e?.message ?? e);
+            opts.onEvent({ type: 'error', data: error });
+        }
+        finally {
+            opts.signal.removeEventListener('abort', onAbort);
+        }
+        if (!finalText)
+            finalText = lastText.join('\n');
+        return { finalText, sessionId, costUsd, ok, error };
+    }
+}