@craftsamo/whatsapp-tools 0.1.0 → 0.1.2

package/.antigravity-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "whatsapp-tools",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "WhatsApp tools for coding agents: chats, contacts, history, received files, sends and actions.",
   "author": {
     "name": "craftsamo",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "whatsapp-tools",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "WhatsApp tools for coding agents: chats, contacts, history, received files, sends and actions.",
   "author": {
     "name": "craftsamo",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "whatsapp-tools",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "WhatsApp tools for coding agents: chats, contacts, history, received files, sends and actions.",
   "author": {
     "name": "craftsamo",
@@ -15,6 +15,7 @@
       "command": "node",
       "args": ["dist/mcp.js"],
       "cwd": ".",
+      "default_tools_approval_mode": "writes",
       "env_vars": [
         "WHATSAPP_TOOLS_TOOLSETS",
         "WHATSAPP_TOOLS_READ_ONLY",

package/README.md

@@ -79,7 +79,15 @@ codex plugin add whatsapp-tools@craft-agent
 
 Codex turns `-` into `_` in server names, so it shows the tools as
 `mcp__whatsapp_tools__whatsapp_*`. It starts the MCP server in the plugin's
-install directory, which is never the caller's working tree.
+install directory and passes no roots, so the server takes each call's directory
+from what Codex sends with the call: its sandbox state, which the server asks
+for, else the one workspace it names.
+
+The plugin declares `default_tools_approval_mode = "writes"`: Codex asks before
+every tool not marked read-only. A user's
+`[plugins."<plugin>".mcp_servers.<server>]` setting can only tighten it. Setting
+`auto` there yields `prompt` (reads asked too), since Codex treats `auto` and
+`writes` as incomparable.
 
 ### Grok Build
 
@@ -110,7 +118,10 @@ hermes plugins enable whatsapp-tools
 ```
 
 If a Hermes gateway is already running, restart it (`hermes gateway restart`) to
-load the plugin.
+load the plugin. While a gateway runs, `hermes chat` runs the plugin's tools in
+the gateway too, so they see the gateway's environment, not the shell's: the
+`PATH` that finds `wacli` and `node`, and any `WHATSAPP_TOOLS_*` variable, are
+the ones the gateway started with.
 
 The plugin runs the Node it found when Hermes started. If a version manager
 removes that version while Hermes runs, a call looks for Node again; when it
@@ -326,6 +337,26 @@ in Hermes.
 
 [`docs/conventions.md`](docs/conventions.md) has the rules each step follows.
 
+A package declares each option as `text`, `boolean`, `number`, `list`, `path`
+or `paths`, or as an object with `type` and optional bounds. For example, in
+`src/project.ts`:
+
+```ts
+options: {
+  notes_dir: "path",
+  note_limit: { type: "number", integer: true, min: 1, max: 50 },
+}
+```
+
+`integer: true` requires a whole number; `min` and `max` bound a number or
+count a `list` or `paths` value's items. An object with only `type` means the
+same as the type alone. Hermes's `OPTIONS` mirrors the declarations on one
+line, with double quotes and Python's `True` for `integer`:
+
+```python
+OPTIONS: dict[str, str | dict[str, object]] = {"notes_dir": "path", "note_limit": {"type": "number", "integer": True, "min": 1, "max": 50}}
+```
+
 ## Reads and writes
 
 Every read tool is named `<prefix>_<domain>_read`. Reads can run unasked;
@@ -344,8 +375,11 @@ Where a write is asked about, and where it is not:
 
 - **OpenCode** grants any action no rule names, so a write runs unasked unless
   a rule asks for it: add the `whatsapp_*` rule shown under [OpenCode](#opencode).
-- **Codex** under `codex exec`, and **Grok Build** under `grok -p`, refuse a
-  write they cannot ask about, unless it is allowed beforehand.
+- **Codex** asks before every write because of the plugin's approval mode.
+  Under `codex exec` it refuses with "MCP tool call requires approval, but
+  approval policy is never".
+- **Grok Build** under `grok -p` refuses a write it cannot ask about, unless it
+  is allowed beforehand.
 - **Grok Build** calls the plugin's tools through its `use_tool` tool, and the
   agent often names a tool without its server first. Grok checks the rules
   against the name as given, so the server-qualified rule alone does not match
@@ -372,13 +406,24 @@ Hermes, noted below.
 | `confirm`       | `--confirm`       | `WHATSAPP_TOOLS_CONFIRM`       | MCP server only: `harness` (default) or `elicitation`, as the conventions say     |
 | `language`      | `--language`      | `WHATSAPP_TOOLS_LANGUAGE`      | native plugins only: the approval prompt's language, such as `ja`                 |
 | `emoji`         | —                 | —                              | Hermes only: the emoji shown beside each toolset, by toolset name (`""` for none) |
-| `state_dir`     | `--state-dir`     | `WHATSAPP_TOOLS_STATE_DIR`     | where every label's state lives; default `$XDG_STATE_HOME/whatsapp-tools`         |
-| `download_dir`  | `--download-dir`  | `WHATSAPP_TOOLS_DOWNLOAD_DIR`  | where received files are saved; default `~/Downloads/whatsapp-tools`              |
-| `send_dirs`     | `--send-dirs`     | `WHATSAPP_TOOLS_SEND_DIRS`     | the directories files may be sent from, besides the working directory             |
-
-Lists are comma-separated in a flag or a variable. A package's own settings,
-listed in `options` in `src/project.ts`, take a row each here and are read the
-same way. Where each harness reads them:
+| `state_dir`     | `--state-dir`     | `WHATSAPP_TOOLS_STATE_DIR`     | `path`: where every label's state lives; default `$XDG_STATE_HOME/whatsapp-tools` |
+| `download_dir`  | `--download-dir`  | `WHATSAPP_TOOLS_DOWNLOAD_DIR`  | `path`: where received files are saved; default `~/Downloads/whatsapp-tools`      |
+| `send_dirs`     | `--send-dirs`     | `WHATSAPP_TOOLS_SEND_DIRS`     | `paths`: the directories files may be sent from, besides the working directory    |
+
+Lists are comma-separated in a flag or a variable. `state_dir`, `download_dir`
+and `send_dirs` are this package's own settings, listed in `options` in
+`src/project.ts` and read the same way. A `path` is trimmed; `~` and `~/…`
+(also with the platform separator) stand for the home directory (`HOME` when
+it is absolute, else the account's). It must then be absolute and reaches the
+tool normalized, without a filesystem check. A blank path counts as unset,
+so the default applies. `paths` is a list of such paths, comma-separated in a
+flag or variable and an array of strings in a plugin option. Blank items are
+dropped, and a list with none left counts as unset. Repeated send directories
+are dropped. Bounds check only a given value, not an unset option. Refused
+values are `invalid_argument`, naming the flag, variable or option and what it
+must be.
+Hermes passes paths and lists to the command line, which checks the paths and
+bounds. Where each harness reads them:
 
 - **OpenCode** takes the plugin `options` shown above, with lists as arrays,
   `read_only` as a boolean, `state_dir` and `download_dir` as paths and
@@ -407,7 +452,8 @@ same way. Where each harness reads them:
   `send_dirs: []`) passes nothing, so a variable set in that environment
   still applies: `WHATSAPP_TOOLS_READ_ONLY=true` keeps the plugin read-only
   whatever the setting says. A running gateway keeps the environment it
-  started with; restart it (`hermes gateway restart`) after changing one.
+  started with, and `hermes chat` runs the tools there while it runs; restart
+  it (`hermes gateway restart`) after changing one.
 
 - **Claude Code, Grok Build and Antigravity** start the plugin's server without
   flags and pass it the client's environment, so set the variables in the