claude-opencode-mcp 1.0.0

package/docs/security-audit.md

@@ -0,0 +1,80 @@
+# Security audit
+
+- **Version audited:** 1.0.0
+- **Date:** 2026-09-24
+- **Scope:** the `claude-opencode-mcp` source tree, its configuration parsing,
+  process management, permission model, MCP tool surface, CI workflows, and
+  published package contents.
+
+## Method
+
+1. Manual review of every source module with attention to command execution,
+   path handling, credential flow, and permission construction.
+2. Pattern scan for unsafe primitives: `child_process.exec`, `execSync`,
+   `shell: true`, `eval`, `new Function`, non-local `http://` endpoints.
+3. Secret scan of the repository (API-key and private-key patterns) and a scan
+   for machine-specific paths in shipped files.
+4. Dependency audit: `npm audit` and `npm audit --omit=dev`.
+5. Review of the permission model against the documented threat model,
+   including how a model could bypass intended restrictions.
+6. Review of CI workflows for secret exposure and fork safety.
+7. Reproduction of security-relevant behavior with the automated test suite,
+   including real OpenCode/DeepSeek end-to-end tests.
+
+## Findings
+
+| # | Finding | Risk | Status |
+| --- | --- | --- | --- |
+| 1 | `opencode.binary` configuration was ignored; the bridge used a PATH-resolved binary instead. | A user explicitly selecting a trusted binary could unknowingly run another. | Fixed: resolver receives the configured path; regression test asserts the configured binary is used. |
+| 2 | Shutdown/startup race could orphan a spawned OpenCode process. | Local resource leak; a stale server keeps running after the bridge exits. | Fixed: children are tracked at spawn time, startup aborts during shutdown, and a synchronous `exit`-handler kills anything left. Tested with a fake binary. |
+| 3 | Session registry and log file were created with default permissions. | Other local users could read agent output summaries and workspace paths. | Fixed: state directory `0700`, files `0600`; log directory created with `0700`. |
+| 4 | Logger had no redaction. | A future code path logging credentials would leak them to disk. | Fixed: log field names matching password/secret/token/authorization/API-key/credential/private-key are redacted; unit-tested. |
+| 5 | MCP tool inputs were unbounded. | Oversized payloads could bloat prompts/logs. | Fixed: `.max()` limits on task, message, cwd, model, agent, title, session id, path array (200 items), and timeout (1 hour). |
+| 6 | CI E2E job could attempt to use secrets on fork pull requests. | Failed/unsafe runs on untrusted PRs. | Fixed: the E2E job runs only on `push` events, and checkouts disable credential persistence. |
+| 7 | `edit: deny` alone is bypassable by shell commands. | Read-only intent could be violated. | Mitigated: read-only profiles also deny `bash`; shell-enabled tester is documented as able to write via shell. Verified end-to-end that a read-only agent cannot create a file. |
+
+No unsafe command construction was found: all external processes use
+`execFile`/`spawn` with explicit argument arrays and no shell. Credentials for
+external OpenCode servers come only from explicit configuration or the URL,
+never from the ambient environment. Dependency audit reports zero known
+vulnerabilities.
+
+## Accepted risks
+
+These are intentional and documented in [security.md](security.md):
+
+- Shell-enabled agents (`deepseek-coder`, `deepseek-tester`) can write files
+  through shell commands; the tester's edit tools are denied but shell is
+  inherently powerful.
+- Sensitive-file protection applies to OpenCode's file tools, not to `bash`.
+- A delegated agent reads repository content, so prompt injection from a
+  hostile repository is possible; review diffs with `get_diff` and keep
+  `workspace.allowedRoots` narrow.
+- Explicitly configured/`OPENCODE_BIN` executables are trusted by definition.
+- Changing `opencode.hostname` from `127.0.0.1` exposes the OpenCode HTTP API
+  to the network; use a server password and firewall the port.
+
+## Security test coverage
+
+The suite includes assertions for: workspace canonicalization and traversal
+rejection, allowed-root enforcement, path-hint escape rejection, read-only
+agent file-creation denial, `.env` secret non-disclosure, `git commit` denial,
+unknown-session handling, timeout and abort without hanging, crashed-server
+handling, workspace routing mismatch detection, child-process cleanup, log
+redaction, and dependency freshness via CI.
+
+## Reproducing
+
+```bash
+npm audit --omit=dev
+npm audit
+grep -rEn "exec\(|execSync|shell: true|eval\(|new Function\(" src/
+grep -rEn "sk-[a-zA-Z0-9]{20,}|BEGIN (RSA|OPENSSH|EC) PRIVATE" .
+npm test
+npm run test:e2e        # real OpenCode + provider required
+```
+
+## Reporting
+
+Found something this audit missed? Please use the private process in
+[SECURITY.md](../SECURITY.md).

package/docs/security.md

@@ -0,0 +1,128 @@
+# Security
+
+Security in this bridge comes from four places: workspace validation in the
+bridge, permission rules enforced by OpenCode, the absence of interactive
+`ask` rules (headless safety), and honest documentation of the remaining
+limits.
+
+## Workspace boundaries
+
+- The workspace must exist, be a directory, and be readable.
+- Paths are canonicalized (`realpath`); `..` and symlinks cannot escape.
+- `workspace.allowedRoots` (when non-empty) restricts every workspace to those
+  canonical roots.
+- `paths` hints cannot escape the workspace (`INVALID_PATH`).
+- `workspace.defaultCwd` is only a fallback; explicit `cwd` and
+  `CLAUDE_PROJECT_DIR` fail loudly when invalid.
+- The bridge probes the OpenCode server's `directory` before the first run and
+  aborts on mismatch (`WORKSPACE_MISMATCH`).
+
+## File protection
+
+When `security.protectEnvFiles` is `true` (default), the read and edit
+permission rules deny:
+
+```text
+*.env, *.env.*, *.pem, *.key, *.p12, *.pfx,
+id_rsa*, id_ed25519*, id_ecdsa*, credentials, credentials.*, .ssh/*, *.npmrc
+```
+
+while keeping `*.env.example`, `*.env.sample` and `*.env.template` readable.
+Add your own patterns with `security.extraProtectedPatterns`.
+
+## Git safety
+
+For agents that can run shell commands (`coder`, `tester`), bash rules deny:
+
+```text
+git push*     git -C * push*     git -c * push*
+git commit*   git -C * commit*   git -c * commit*
+```
+
+All other commands are allowed for those profiles. Read-only profiles have
+`bash: deny` outright, so they cannot mutate anything through the shell.
+
+The bridge never commits, pushes, stages or reverts anything itself. There is
+no automatic commit or push anywhere in the codebase.
+
+## Permission matrix
+
+| Permission | read | review | code | test |
+| --- | --- | --- | --- | --- |
+| `read` | allow (+ sensitive denies) | same | same | same |
+| `edit` | deny | deny | allow (+ sensitive denies) | deny |
+| `bash` | deny | deny | allow (git commit/push denied) | allow (git commit/push denied) |
+| `glob`, `grep`, `list`, `lsp` | allow | allow | allow | allow |
+| `webfetch`, `websearch`, `skill`, `todowrite` | allow | allow | allow | allow |
+| `task` (subagents) | deny | deny | deny | deny |
+| `external_directory` | deny | deny | deny | deny |
+| `question`, `doom_loop` | deny | deny | deny | deny |
+
+`externalDirectory` can be set to `allow`, `ask` or `deny`. `ask` is
+discouraged: nothing answers the prompt in headless mode, although the bridge
+auto-rejects permission events it sees.
+
+## Headless safety
+
+- No `ask` rules are emitted by the bridge.
+- The bridge subscribes to OpenCode's event stream and rejects any permission
+  request for an active delegated session, logging a warning. A run cannot hang
+  waiting for a human.
+- Every run has a timeout; on timeout the bridge aborts the OpenCode session
+  and returns `AGENT_TIMEOUT`.
+- Cancellation via MCP (`extra.signal`) aborts the session and returns
+  `AGENT_ABORTED`.
+
+## Local data protection
+
+- Session registry: `~/.local/state/claude-opencode-mcp/sessions.json`, written
+  with mode `0600` inside a `0700` directory. It contains workspace paths and
+  agent output summaries, so treat it as private.
+- Log file: `~/.local/state/claude-opencode-mcp/bridge.log`, mode `0600`,
+  rotated at 5 MB. Log fields whose names look like credentials (password,
+  secret, token, authorization, API key, credential, private key) are redacted
+  before writing.
+- Provider credentials are never stored by the bridge; they stay in OpenCode's
+  auth store or environment variables.
+
+## Network exposure
+
+The started OpenCode server binds to `127.0.0.1` by default and uses a
+configurable port (`0` lets OpenCode pick). If you change `opencode.hostname`
+to a routable address, the OpenCode HTTP API becomes reachable from your
+network: set `OPENCODE_SERVER_PASSWORD` (or `opencode.password`) and firewall
+the port. The bridge only sends credentials to the server you configured.
+
+## External OpenCode servers
+
+When `opencode.url` is set, the bridge cannot inject agent definitions or
+permissions. It verifies the required agents exist and refuses to delegate
+otherwise. The permissions of those agents are whatever the external server's
+configuration says — review it yourself.
+
+Provider credentials are never sent to external URLs from the environment;
+only explicit `username`/`password` or credentials embedded in the URL are
+used.
+
+## Known limits
+
+State these plainly when deciding what to delegate:
+
+1. **Shell access implies write access.** A coder or tester can write files via
+   `bash` (`printf > file`, `sed -i`, …). The bridge denies edit tools for the
+   tester and forbids git history changes, but shell is powerful. Only delegate
+   to shell-enabled agents in repositories you trust.
+2. **`.env` protection covers file tools.** A shell-enabled agent could `cat`
+   a protected file through `bash`. This matches OpenCode's own permission
+   model, which gates the `read` tool, not `bash`.
+3. **Prompt injection.** Agents read repository content; a hostile repository
+   can attempt to influence them. Keep `allowedRoots` tight and review diffs
+   with `get_diff` before accepting changes.
+4. **An agent can read anything inside the workspace.** That is intentional:
+   hints are not boundaries. Use workspace separation, not hints, to isolate
+   code.
+
+## Reporting
+
+If you find a security issue, please open an issue with a minimal reproduction
+and avoid sharing live credentials.

package/docs/troubleshooting.md

@@ -0,0 +1,126 @@
+# Troubleshooting
+
+Start with the log file:
+
+```bash
+tail -f ~/.local/state/claude-opencode-mcp/bridge.log
+```
+
+and raise the level:
+
+```bash
+CLAUDE_OPENCODE_LOG=debug claude
+```
+
+## Error codes
+
+| Code | Meaning | Typical fix |
+| --- | --- | --- |
+| `WORKSPACE_NOT_FOUND` | No usable workspace could be resolved. | Pass `cwd` explicitly or start Claude Code inside the project. |
+| `WORKSPACE_NOT_ALLOWED` | Canonical workspace is outside `workspace.allowedRoots`. | Add the root or clear the list. |
+| `WORKSPACE_NOT_READABLE` | Permission problem accessing the workspace. | Fix directory permissions. |
+| `WORKSPACE_MISMATCH` | OpenCode reported a different directory than requested. | Restart Claude Code; report a bug if it persists. |
+| `INVALID_PATH` | A path hint escaped the workspace, a path had a null byte, or `cwd` was not a directory. | Fix the hint. |
+| `OPENCODE_NOT_AVAILABLE` | Executable not found or not executable. | `npm install -g opencode-ai` or set `OPENCODE_BIN`/`opencode.binary`. |
+| `OPENCODE_START_TIMEOUT` | Server did not print its listening URL in time. | Run `opencode serve` manually; raise `opencode.startupTimeout`; check auth env vars. |
+| `OPENCODE_UNAVAILABLE` | Server died or refused a request. | Retry; check `bridge.log` and `opencode serve` output. |
+| `OPENCODE_SESSION_NOT_FOUND` | Unknown or deleted session id. | Create a new session. |
+| `OPENCODE_ERROR` | OpenCode returned an error (includes provider auth failures). | Read the message; for auth re-run `opencode auth login`. |
+| `AGENT_NOT_FOUND` | Unknown agent, or the external server lacks required agents. | Check `list_agents`; install agents on the external server. |
+| `AGENT_TIMEOUT` | Run exceeded the timeout and was aborted. | Raise `timeouts.execution`/`timeout`, or split the task. |
+| `AGENT_ABORTED` | Run was cancelled. | Expected after `abort_session` or MCP cancellation. |
+| `AGENT_EXECUTION_FAILED` | Provider/API error during the run. | Inspect `details.statusCode`/`responseBody`; retry on `429`. |
+| `MODEL_NOT_AVAILABLE` | No model could be resolved. | `opencode auth login` or set `defaults.model`. |
+| `DIFF_UNAVAILABLE` | No changes were reported and the workspace is not a git repo. | Initialize git for reliable diffs. |
+| `NOT_GIT_REPOSITORY` | A git-only operation was requested outside a repo. | Initialize git. |
+| `CONFIG_INVALID` | Configuration file has wrong types or bad JSON. | Fix the file named in `details.file`. |
+| `INTERNAL_ERROR` | Unexpected bridge error. | Report with the `request_id` from the log. |
+
+## The tool call times out in Claude Code
+
+- Set `"timeout": 600000` in the `.mcp.json` server entry (per-tool wall clock).
+- `MCP_TOOL_TIMEOUT` raises the default for all servers.
+- Claude Code backgrounds calls after two minutes; this is normal and the
+  result still arrives.
+- The stdio idle timeout is 30 minutes with no response *and no progress*; the
+  bridge emits progress notifications while polling, so long runs are safe.
+
+## OpenCode server fails to start
+
+Run the same command the bridge runs, in the workspace:
+
+```bash
+cd /path/to/project
+opencode serve --hostname=127.0.0.1 --port=0
+```
+
+Common causes:
+
+- Port/hostname conflicts: leave `opencode.port` at `0` (choose a free port).
+- `OPENCODE_SERVER_PASSWORD` set in the environment: the server requires basic
+  auth. The bridge handles it; if you connect manually, pass credentials.
+- Stale `OPENCODE_CONFIG_CONTENT` with invalid JSON: the bridge ignores
+  malformed inherited content and merges its own agents on top.
+- A broken global OpenCode config: run `opencode debug config`.
+
+## DeepSeek is not detected by `init`
+
+`claude-opencode init` runs `opencode models` and looks for `deepseek/*`. If the
+list is empty:
+
+```bash
+opencode auth login
+opencode models | grep deepseek
+```
+
+## Agents are missing on an external server
+
+`AGENT_NOT_FOUND` with `opencode.url` set means the server has no definitions
+for `deepseek-*`. Either:
+
+```bash
+claude-opencode init
+mkdir -p .opencode/agents
+cp .claude-opencode/agents/*.md .opencode/agents/
+```
+
+then restart the external server, or remove `opencode.url` and let the bridge
+manage the server.
+
+## A run seems stuck
+
+- Check `/tasks` in Claude Code for a backgrounded call.
+- `get_session` returns live `opencode.status` (`busy`, `idle`, `retry`).
+- `abort_session` stops it.
+- The bridge auto-rejects permission prompts it observes, and every run has a
+  timeout, so a run cannot wait forever.
+
+## Provider errors during runs
+
+Results include `error.details` from OpenCode, for example:
+
+```json
+{
+  "status": "failed",
+  "error": {
+    "code": "AGENT_EXECUTION_FAILED",
+    "message": "rate limited",
+    "details": { "statusCode": 429, "isRetryable": true }
+  }
+}
+```
+
+Retry by sending a follow-up (`send_message`) on the same session or delegating
+again.
+
+## Diagnostics
+
+```bash
+claude-opencode-mcp --version
+claude-opencode init          # validates binary, provider, workspace, MCP config
+claude mcp list               # shows connection health
+node dist/index.js --version
+```
+
+When reporting a bug, include the `request_id` from the error payload and the
+matching lines from `bridge.log`.

package/docs/workspace-model.md

@@ -0,0 +1,126 @@
+# Workspace model
+
+The core invariant: **a delegated agent operates against the same intended
+workspace as Claude Code, and can inspect it directly through OpenCode's
+tools.** No repository copying, no temporary clones for normal operation.
+
+## Resolution
+
+For every tool call the workspace is resolved in this order:
+
+1. explicit `cwd` argument
+2. `CLAUDE_PROJECT_DIR` (set by Claude Code for stdio MCP servers)
+3. the MCP server process working directory
+4. `workspace.defaultCwd` from configuration
+
+Candidates 1 and 2 are *required*: if one of them is present but invalid
+(`WORKSPACE_NOT_FOUND`, `WORKSPACE_NOT_READABLE`, `WORKSPACE_NOT_ALLOWED`,
+`INVALID_PATH`), the call fails immediately. The bridge never silently falls
+back to a different directory for an explicitly requested workspace. Only the
+process directory and `defaultCwd` are best-effort fallbacks.
+
+If no candidate can be validated, the error is:
+
+```
+WORKSPACE_NOT_FOUND: Unable to determine project workspace. Provide cwd explicitly.
+```
+
+## Validation
+
+Before a session is created:
+
+- the path must exist, be a directory, and be readable/executable;
+- it is canonicalized with `realpath` (symlinks and `..` are resolved);
+- when `workspace.allowedRoots` is configured, the canonical path must live
+  inside one of the canonical roots — anything else is rejected with
+  `WORKSPACE_NOT_ALLOWED`;
+- the git root is detected (`git rev-parse --show-toplevel`) for diff
+  baselines and reported as `gitRoot`.
+
+Path traversal (for example `cwd: "../../etc"` or a `paths` hint escaping the
+workspace) is rejected with `INVALID_PATH`.
+
+## Path hints
+
+`delegate_task` accepts `paths`:
+
+```json
+{
+  "task": "Review authentication",
+  "paths": ["src/auth", "src/middleware/auth.ts", "tests/auth"]
+}
+```
+
+Hints are turned into absolute paths, must stay inside the workspace, and are
+inserted into the task message as starting points. They are **not** a
+filesystem boundary: the agent is explicitly told to inspect additional files
+and to not assume everything relevant lives under the hints.
+
+## One server per workspace
+
+The bridge starts one OpenCode server per workspace directory and runs it with
+that directory as its working directory. Sessions for that workspace reuse it.
+`opencode.maxServers` (default 4) bounds how many idle servers are kept; the
+least recently used idle server is stopped when the limit is exceeded.
+
+During the first call for a workspace the bridge asks the server
+(`GET /path`) which directory it is serving and compares it with the requested
+canonical path. A mismatch aborts with `WORKSPACE_MISMATCH` rather than
+delegating into the wrong repository.
+
+## The workspace contract
+
+Internally every run carries:
+
+```ts
+interface AgentWorkspace {
+  cwd: string;          // canonical absolute directory
+  requestedPath: string;
+  allowedPaths?: string[];  // reserved; hints are not restrictions
+  deniedPaths?: string[];   // reserved; sensitive patterns are enforced via permissions
+  gitRoot?: string;
+  readOnly: boolean;    // derived from the agent profile
+}
+```
+
+and the agent message always contains:
+
+```text
+Workspace:
+/abs/path
+
+Task:
+...
+
+Relevant paths (starting points only, not a boundary):
+- /abs/path/src/auth
+
+Permissions:
+- file edits: denied
+- shell commands: denied
+- read-only agent: yes
+
+Instructions:
+- Work inside the specified workspace; do not read or write outside it.
+- Inspect additional files and directories whenever that helps the task.
+- Do not assume relevant code exists only under the supplied path hints.
+...
+```
+
+## Demo: two repositories
+
+```text
+repo-a/
+  ONLY_A.txt
+repo-b/
+  ONLY_B.txt
+```
+
+Delegating to each with the same task ("list the root .txt file and report its
+contents") returns `alpha-42` for repo-a and `beta-99` for repo-b. This scenario
+is covered by the end-to-end test suite (`tests/e2e/real-opencode.test.ts`).
+
+## Choosing a workspace without Claude Code
+
+Any MCP client can pass `cwd` explicitly. Claude Code additionally provides
+`CLAUDE_PROJECT_DIR`, which makes the common case zero-configuration.

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "claude-opencode-mcp",
+  "version": "1.0.0",
+  "description": "MCP bridge that lets Claude Code delegate software-engineering tasks to OpenCode agents (DeepSeek by default) inside the same workspace.",
+  "type": "module",
+  "license": "MIT",
+  "author": "claude-opencode-mcp contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/putuandy/claude-opencode-mcp.git"
+  },
+  "homepage": "https://github.com/putuandy/claude-opencode-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/putuandy/claude-opencode-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "opencode",
+    "deepseek",
+    "coding-agent"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "claude-opencode-mcp": "./dist/index.js",
+    "claude-opencode": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "agents",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "npm run build && cross-env CLAUDE_OPENCODE_E2E=1 vitest run --config vitest.e2e.config.ts",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "@opencode-ai/sdk": "^1.18.32",
+    "commander": "^14.0.3",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
+  },
+  "optionalDependencies": {
+    "opencode-ai": "^1.18.32"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.14",
+    "@types/node": "^26.6.2",
+    "cross-env": "^10.1.0",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  }
+}