merakcode 0.3.0 → 0.3.1

package/README.md

@@ -144,27 +144,27 @@ cd your-project
 merak run "Explain how src/index.ts starts up"
 ```
 
-| Command                                         | What it does                                                                                                                                                                             |
-| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `merak run "<task>"`                            | Run one task and print the result. `-c` continues the last session, `-m` picks the model, `-f` attaches files, `--format json` prints the raw events; the task can also come from a pipe |
-| `merak run --auto "<task>"`                     | Run it in auto mode; see below                                                                                                                                                           |
-| `merak provider login`                          | Connect a model provider; `list` shows the connected ones, `logout` removes one, `relay` adds a relay                                                                                    |
-| `merak serve --port 4096`                       | Start only the engine, for the SDK or other programs                                                                                                                                     |
-| `merak upgrade` (or `update`)                   | Upgrade. `--check` only looks for a new version, `--yes` skips the question                                                                                                              |
-| `merak models`                                  | List the models you can use; `--refresh` fetches the model lists again                                                                                                                   |
-| `merak mcp list`                                | Show MCP server status                                                                                                                                                                   |
-| `merak skill`, `merak plugin`                   | Manage skills and plugins                                                                                                                                                                |
-| `merak session`, `merak export`, `merak import` | Manage, export and import sessions                                                                                                                                                       |
-| `merak stats`                                   | Token usage and cost                                                                                                                                                                     |
-| `merak sandbox status`                          | Is the sandbox on? `setup` sets it up (Windows only), `reset` undoes it                                                                                                                  |
-| `merak doctor`                                  | Check the install, config, models and sandbox, and say what is wrong                                                                                                                     |
-| `merak logs`                                    | Where the logs are and recent runs; `--tail` follows the newest log                                                                                                                      |
-| `merak bug-report`                              | Zip the checks, config and logs for an issue; keys and conversations are left out                                                                                                        |
-| `merak acp`                                     | Run as an [ACP](https://agentclientprotocol.com) agent for editors such as Zed                                                                                                           |
+| Command                                              | What it does                                                                                                                                                                             |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `merak run "<task>"`                                 | Run one task and print the result. `-c` continues the last session, `-m` picks the model, `-f` attaches files, `--format json` prints the raw events; the task can also come from a pipe |
+| `merak run --permission-level fullTakeover "<task>"` | Run at the Full takeover level; see below                                                                                                                                                |
+| `merak provider login`                               | Connect a model provider; `list` shows the connected ones, `logout` removes one, `relay` adds a relay                                                                                    |
+| `merak serve --port 4096`                            | Start only the engine, for the SDK or other programs                                                                                                                                     |
+| `merak upgrade` (or `update`)                        | Upgrade. `--check` only looks for a new version, `--yes` skips the question                                                                                                              |
+| `merak models`                                       | List the models you can use; `--refresh` fetches the model lists again                                                                                                                   |
+| `merak mcp list`                                     | Show MCP server status                                                                                                                                                                   |
+| `merak skill`, `merak plugin`                        | Manage skills and plugins                                                                                                                                                                |
+| `merak session`, `merak export`, `merak import`      | Manage, export and import sessions                                                                                                                                                       |
+| `merak stats`                                        | Token usage and cost                                                                                                                                                                     |
+| `merak sandbox status`                               | Is the sandbox on? `setup` sets it up (Windows only), `reset` undoes it                                                                                                                  |
+| `merak doctor`                                       | Check the install, config, models and sandbox, and say what is wrong                                                                                                                     |
+| `merak logs`                                         | Where the logs are and recent runs; `--tail` follows the newest log                                                                                                                      |
+| `merak bug-report`                                   | Zip the checks, config and logs for an issue; keys and conversations are left out                                                                                                        |
+| `merak acp`                                          | Run as an [ACP](https://agentclientprotocol.com) agent for editors such as Zed                                                                                                           |
 
 Add `--help` to any command for the full details.
 
-`merak run` has no one to approve anything: an action that would ask (in ask mode, `npm install` or `npm test`, say) is refused, and the agent is told why. To let such actions through, add `--auto`, or write allow rules in the project config (see [Configuration](#configuration)). Writes outside the workspace, risky commands, secret reads, hosts off the allowlist and leaving the sandbox are refused even with `--auto`, and so are commands that may change things before the Windows sandbox is set up.
+Without an approval handler, `merak run` refuses operations that need confirmation. `--permission-level autoApprove` allows only eligible safe operations. Explicit `--permission-level fullTakeover` skips safety approvals. The old `--auto` option was removed.
 
 `merak serve` listens only on `127.0.0.1` by default, but has no password, so any program on this computer can call it. When other programs connect, set the environment variable `MERAKCODE_SERVER_PASSWORD` (HTTP Basic auth; the user name is `merakcode` by default). See [SECURITY.md](SECURITY.md#the-engines-api).
 
@@ -182,32 +182,23 @@ Editors that speak [ACP](https://agentclientprotocol.com) can use MerakCode as t
 
 ## Permissions and the sandbox
 
-MerakCode edits files and runs commands on your computer, so every action goes through the permission mode first: do it, ask you, or refuse. There is no category called an ordinary file. The rules are:
+New conversations default to Ask every time. Child tasks, group members and background work follow the root conversation's latest permission level.
 
-- **Edits inside the workspace.** If no directory or file name on the path relative to the workspace starts with `.`, ask mode and auto mode edit it immediately. If any segment starts with `.` (`.git`, `.github`, `.env`, `src/.hidden/a.ts`), ask mode asks first and auto mode edits it immediately. MerakCode's own config files (`merakcode.json` and `merakcode.jsonc` anywhere, including the global config) are the exception: they hold the permission rules, so even auto mode asks first, and you can allow only once or for the session. Read-only mode never edits, and an allow rule in the config cannot override that.
-- **Reads.** A file inside the workspace that is not a secret is read immediately in every mode. A non-secret file outside the workspace asks in read-only and ask mode, and is read immediately in auto mode. Secrets always ask. A secret is a file named `.env`, or `.env.*` other than `.env.example`, `.env.sample`, `.env.template` and `.env.dist`; `id_rsa`, `id_dsa`, `id_ecdsa` or `id_ed25519`, with an optional extra suffix; `credentials` or `credentials.json`; an extension of `.pem`, `.key`, `.p12`, `.pfx`, `.keystore` or `.jks`; or `.npmrc`, `.pypirc`, `.netrc`, `.git-credentials` or `.pgpass`. Files under `.ssh`, `.aws`, `.azure`, `.kube`, `.gnupg`, `.docker`, `.config/gcloud` or `.config/gh` in your home directory count too, and so does `~/.merakcode/data/auth.json`, where MerakCode keeps your provider keys. A command argument naming one of these files asks too (`cat .env`, `cat ~/.ssh/id_rsa`), but paths read inside a script or built from variables are not seen. The OS sandbox blocks only the key folders in your home directory; it does not block `.env`, `~/.npmrc`, `~/.git-credentials` or `auth.json`.
-- **Commands.** Commands whose name is on a fixed read-only list (`ls`, `git status`, `git diff`, `rg` and so on) run in every mode; with an option that writes files or runs another program (`sort -o`, `rg --pre`, `git diff --output=`) they count as file-changing commands, and so does anything not on the list. File-changing commands, and `rm`, `rmdir`, `unlink`, `shred`, `git clean`, `git reset --hard` and `find -delete`, are refused in read-only mode, asked about in ask mode, and run immediately in auto mode. Risky commands are refused in read-only mode and asked about in ask and auto mode: `sudo`, `su`, `doas`, `pkexec`, `runas`, `dd` when it does not target a whole disk, `shutdown`, `reboot`, `chown`, and `git push`, `npm publish`, `npm unpublish`, `pnpm publish`, `yarn publish`, `bun publish`, `cargo publish`, `gem push`, `twine upload`, `docker push`, `gh release`, `gh pr`, `helm push`, and piping a `curl` or `wget` download straight into a shell (`curl … | sh`). `rm -rf /` (and the home directory), recursively chmodding those locations to `777`, `mkfs`, `dd` onto a whole disk, `format`, `diskpart` and a fork bomb are refused by default. In ask and auto mode they run only when the config explicitly allows them. In read-only mode an allow rule still does not. All of this is read from the command text: wrappers such as `env`, `sudo`, `nice`, `timeout` and `xargs` are judged by the command they run, commands inside `sh -c "…"` and `eval` are looked at too, and forms such as `git -C dir push` are recognised; but commands in a script file or built from variables are not seen. So these rules are not a security boundary; the OS sandbox below is what limits the damage.
-- **Websites.** The allowlist matches hostnames exactly; a subdomain does not count. These hosts are reached immediately: `registry.npmjs.org`, `registry.yarnpkg.com`, `registry.npmmirror.com`, `cdn.npmmirror.com`, `pypi.org`, `files.pythonhosted.org`, `pypi.tuna.tsinghua.edu.cn`, `crates.io`, `index.crates.io`, `static.crates.io`, `static.rust-lang.org`, `rsproxy.cn`, `proxy.golang.org`, `sum.golang.org`, `goproxy.cn`, `repo.maven.apache.org`, `repo1.maven.org`, `maven.aliyun.com`, `services.gradle.org`, `plugins.gradle.org`, `rubygems.org`, `github.com`, `codeload.github.com`, `objects.githubusercontent.com`, `raw.githubusercontent.com`, `gitlab.com`, `gitee.com`, `mirrors.aliyun.com`, `mirrors.tuna.tsinghua.edu.cn`. Every other host asks, in every mode. Local addresses (`localhost`, `127.0.0.1` and so on) do not ask, so commands can reach databases, dev servers and other services on this computer (except the engine's own port; see [SECURITY.md](SECURITY.md) for details).
-- **The rest.** Subagents, workflows, scheduled tasks, MCP and tools registered by plugins ask in read-only and ask mode, and run immediately in auto mode. Leaving the sandbox asks in ask and auto mode and is refused in read-only mode. While the sandbox is not ready, a command that may change things asks even in auto mode. In ask and auto mode, allow and deny rules in your config (global or project) override the defaults above. Read-only mode still cannot edit files or run anything except read-only commands.
-- **Collaboration members.** The leader hands a task to a member without asking. When a member (Claude Code, Codex, OpenCode, or a product with a member adapter) wants to edit files, run commands, reach a website or read files, the rules above decide it; what needs asking shows in the approval bar and a member's question in the question box, both naming the member. Members' commands do not run in MerakCode's OS sandbox (Codex runs them in its own sandbox), and a custom product added as a one-shot command never asks: its own settings decide.
+| Permission level                         | Required isolation is ready                                                                                                           | Required isolation is unavailable                          |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| Ask every time `ask`                     | Ask before each operation; scoped conversation grants may apply                                                                       | Ask each time; allow once or reject                        |
+| Ask only for risky actions `autoApprove` | Allow controlled project reads and edits, provably read-only commands and dedicated plan writes; ask for dangerous or unknown actions | Preserve the selection and ask each time                   |
+| Full takeover `fullTakeover`             | Skip safety approvals; isolate compatible controlled commands and use the current account when needed                                 | Skip safety approvals and report current-account execution |
 
-| Mode          | Good for                              | What happens                                                                                                                                                                                                                                               |
-| ------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Read-only     | Designs and plans                     | No edits, only commands on the read-only list. Still asks before a non-secret read outside the workspace, a secret, or a host off the allowlist                                                                                                            |
-| Ask (default) | Everyday work                         | Edits a workspace file immediately when no path segment starts with `.`. Asks before edits to dot paths, file-changing commands and deletes, reads or edits outside the workspace, secrets, or hosts off the allowlist                                     |
-| Auto          | Large projects, when you trust the AI | Edits inside the workspace (including dot paths), file-changing commands and deletes run immediately. Still asks before changes to MerakCode's config files, writes outside, risky commands, secret reads, hosts off the allowlist, or leaving the sandbox |
+Full takeover still respects the user's task scope, input validation and concurrency protection. A failed command is never automatically replayed with the current account.
 
-Switch modes next to the input in the desktop app, or press `Shift+Tab`. When it asks, you can allow once, allow for this session, always allow (saved to the project config) or deny. Subagents, workflows, sandbox permissions and changes to MerakCode's config files offer no "always allow".
+The product prepares isolation. On Windows, the first interactive desktop setup requests system administrator approval once. Cancellation leaves Ask every time and Ask only for risky actions on per-operation approval. Retry from sandbox status, or diagnose and repair with `merak sandbox status` and `merak sandbox setup`.
 
-Commands the agent runs also go into an **OS sandbox**: they can only write the workspace, temp folders and package manager caches; they cannot read key folders such as `~/.ssh` or `~/.aws`; they cannot change `.git/hooks`, `.git/config` or MerakCode's config files in the workspace (blocked outright where the OS allows it, otherwise rolled back when the command ends and reported to the model); and network traffic goes through a local proxy that asks you about hosts off the allowlist that you have not approved. The sandbox is our own code on top of what each OS provides:
+Every level supports official plans. The model saves Markdown with `plan_generate` and edits it with `plan_edit`. Draft-only requests do not authorize project changes. Human saves need no agent approval. The Plan tab renders full Markdown; Edit plan opens the existing editor.
 
-| System  | Built on                                                           | What you need to do                                                                                                                                |
-| ------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Windows | A separate low-rights account, NTFS permissions, the firewall      | Click "Set up" under Settings → Permissions & security in the desktop app (or run `merak sandbox setup` once) and approve one administrator prompt |
-| Linux   | Landlock (kernel 5.13 or newer with Landlock enabled; needs glibc) | Nothing. Network rules need kernel 6.7 or newer                                                                                                    |
-| macOS   | The built-in Seatbelt (sandbox-exec)                               | Nothing                                                                                                                                            |
+The button and explicit chat instructions share plan startup. Startup uses the latest saved document, records an immutable execution snapshot and preserves the selected permission level. Later edits do not change that snapshot. See [Permission levels and official plans](docs/session-modes.md).
 
-While the sandbox is not ready (for example before setup on Windows), commands that may change things ask first, even in auto mode. For what the sandbox does and does not protect against, see [SECURITY.md](SECURITY.md).
+External adapters use protocol 3. The host controls only operations the adapter actually reports; native restrictions remain in effect. Plan-dependent work requires declared full-input and capacity support.
 
 ## Collaboration groups
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "merakcode",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "MerakCode command line: run tasks, start the engine, ACP for editors",
   "license": "MIT",
   "repository": {
@@ -19,11 +19,11 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "merakcode-darwin-arm64": "0.3.0",
-    "merakcode-darwin-x64": "0.3.0",
-    "merakcode-linux-arm64": "0.3.0",
-    "merakcode-linux-x64": "0.3.0",
-    "merakcode-windows-arm64": "0.3.0",
-    "merakcode-windows-x64": "0.3.0"
+    "merakcode-darwin-arm64": "0.3.1",
+    "merakcode-darwin-x64": "0.3.1",
+    "merakcode-linux-arm64": "0.3.1",
+    "merakcode-linux-x64": "0.3.1",
+    "merakcode-windows-arm64": "0.3.1",
+    "merakcode-windows-x64": "0.3.1"
   }
 }