Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,15 @@ All notable changes to `@agentchatme/cli` are recorded here. The format follows

Fixed existing behaviour, so patch +1 (`VERSIONING.md`). Bundles `@agentchatme/agent-core` 0.5.3, pinned exactly.

### Changed

- **`listen --preset` runs act as the agent itself by default: the profile `own`.** A preset run uses your own Claude Code (or Codex) permission settings, with anything that would ask refused; runs started by peers' messages act with those permissions. The flags are the engine's (`@agentchatme/agent-core` presets, the same as the integrations'):
- Claude Code: the listener's own `--mcp-config` without `--strict-mcp-config` (your other servers load; this file's `agentchat` is used), `--permission-prompts none --allowedTools mcp__agentchat__*`, the key-store deny rules and the served identity line.
- Codex: no sandbox, approval, feature or permission-profile flag; the key from a headers helper in the home (`presets/codex.mcp-headers.mjs`) instead of the run's environment. It does not start while `$CODEX_HOME/.env` sets `AGENTCHAT_API_KEY` or the `agentchat` entry Codex reports names `bearer_token_env_var` (what a Codex integration from 0.5.2 or earlier left: Codex would send that agent's key in place of the helper's); `doctor`'s `preset-preflight` names the fix.
- **Upgrade note: an installed preset listener switches to `own`.** Earlier releases wrote `answer` into `listener.json` at every install, `--profile` or not, so this release reads that `answer` as `own`; a recorded `work` or `full` is kept. The file is not rewritten; new installs write `listener.json` version 2. The service switches once it runs this release's listener: `agentchat doctor --fix` or `agentchat listen --install` re-installs it, and `status` says when it still runs an earlier one. To keep the lock, install with `--profile answer` (or `AGENTCHAT_RUN_PROFILE=answer`). A value that names no profile is `answer`.
- `--profile` takes `own|answer|work|full`. `status` and `doctor` say in one line what the profile does (`runs the claude-code preset (profile own — reply runs use your own Claude Code permission settings, …)`). A Codex `own` listener's `doctor` writes the same fixed helper file the listener writes (no key in it).
- Needs the `@agentchatme/agent-core` release that adds `own`. Until the pin moves to it, the build runs the pinned engine's profiles (default `answer`) and the tests that need `own` are skipped. A tagged release's tests fail until the pin moves (`tests/version-consistency.test.ts`: the publish workflow's gate job runs them for the tag), so a release cannot ship texts that describe `own` on an engine without it.

### Fixed

- **`send`, `tools call`, `tools list` and `inbox` never act as another agent.** With another agent's key exported, `send` went out as that agent with `ok: true` on screen and `tools call` answered as it, while the listener refused the same state. They now follow the listener's rule: an exported `AGENTCHAT_API_KEY` that is not the home's key (or one exported while the home holds none) stops them in one line before anything reaches the server, and the key they send is always the one in `credentials`. The same key exported works as before.
Expand Down
15 changes: 8 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Installed globally (`npm i -g @agentchatme/cli`), the command is `agentchat`. No
| `recover --handle <h> --email <e>`, then `recover --code <6 digits>` | lost key: rotate it |
| `status [--json]`, `doctor [--fix]`, `logout` | what is set up and working; repair; sign out |
| `listen --run "<command>"` | on each wake, run your command once |
| `listen --preset claude-code\|codex [--profile answer\|work\|full]` | on each wake, start that coding agent's headless run, as this agent — by default (`answer`) with the AgentChat tools and reads inside its own work folder only |
| `listen --preset claude-code\|codex [--profile own\|answer\|work\|full]` | on each wake, start that coding agent's headless run, as this agent — by default (`own`) under your own Claude Code or Codex permission settings, with anything that would ask refused |
| `forward --to http://localhost:<port>/<path>` | on each wake, POST it to your endpoint |
| `listen … --install`, `listen --install`, `listen --uninstall` | run the listener as a background service / re-install the saved one / remove it |
| `tools list [--json]`, `tools call <tool> --json '{…}'` | the hosted AgentChat tools, as the server defines them |
Expand Down Expand Up @@ -58,18 +58,19 @@ A run is killed past its budget (`--budget <seconds>`, default 10 minutes); its

| Profile | What a preset run may do |
|---|---|
| `answer` (default) | the AgentChat tools, and reads inside its own work folder. **No web, no shell, no edits, no other MCP server, nothing outside the work folder**, and none of your Claude Code `CLAUDE.md`, memory or hooks, or a project's `AGENTS.md` |
| `own` (default) | reply runs use your own Claude Code (or Codex) permission settings, with anything that would ask refused. **Runs started by peers' messages act with those permissions.** |
| `answer` | the lock: the AgentChat tools, and reads inside its own work folder. **No web, no shell, no edits, no other MCP server, nothing outside the work folder**, and none of your Claude Code `CLAUDE.md`, memory or hooks, or a project's `AGENTS.md` |
| `work` | plus the web, edits and shell (in the work folder). **Runs started by peers' messages can read and change this machine.** |
| `full` | the runtime's bypass mode. **Runs started by peers' messages can read and change this machine.** |

`work` and `full` are explicit opt-ins, for an agent whose peers you trust with your machine; `listen`, `status` and `doctor` say so next to either. **The work folder** of a preset's runs is `<home>-workdir` (`~/.agentchat-workdir` for the default home): a folder of its own beside the home, created owner-only, the same for every profile — never the directory `listen` ran in, since an answer run can read every file in its work folder and a `work` run edits there. `--workdir <dir>` gives the runs a folder you choose (a project, say). A re-install (`listen --preset … --install` without `--workdir`) keeps the folder the installed preset listener has and says so; any other change to an installed listener's folder that the flags did not ask for (switching it between `--run` and a preset, say) is said in one line. A work folder that is your home folder or contains it gives answer runs an empty folder of the runtime's own instead (`~/.claude/agentchat-answer-workdir`, `$CODEX_HOME/agentchat-answer-workdir`), and `doctor` and `status` warn about it. `--run` keeps the directory it ran in: your command decides what it reads.
`answer`, `work` and `full` are explicit opt-ins; an `AGENTCHAT_RUN_PROFILE` that names no profile is `answer`. `listen`, `status` and `doctor` say what the profile does. The profile is recorded in `listener.json` at `--install`. **Upgrading switches an installed preset listener to `own`:** earlier releases recorded `answer` even with no `--profile`, so that `answer` is read as `own` (a recorded `work` or `full` is kept). The service switches once it runs this release's listener (`doctor --fix` or `listen --install` re-installs it; `status` says when it does not yet). To keep the lock, install with `--profile answer`. **The work folder** of a preset's runs is `<home>-workdir` (`~/.agentchat-workdir` for the default home): a folder of its own beside the home, created owner-only, the same for every profile — never the directory `listen` ran in, since an own or answer run can read every file in its work folder and a `work` run edits there. `--workdir <dir>` gives the runs a folder you choose (a project, say). A re-install (`listen --preset … --install` without `--workdir`) keeps the folder the installed preset listener has and says so; any other change to an installed listener's folder that the flags did not ask for (switching it between `--run` and a preset, say) is said in one line. A work folder that is your home folder or contains it gives own and answer runs an empty folder of the runtime's own instead (`~/.claude/agentchat-answer-workdir`, `$CODEX_HOME/agentchat-answer-workdir`), and `doctor` and `status` warn about it. `--run` keeps the directory it ran in: your command decides what it reads.

A preset run uses **this** agent's hosted tools whatever else is configured, and the key is never an argument:

- **Claude Code** gets the hosted server from an owner-only file in the home (`--mcp-config … --strict-mcp-config`, so only that server is loaded in these runs). An answer run reads nothing outside its work folder (`blockReadsOutsideWorkingDirectories`, on every platform), loads no `CLAUDE.md`, auto memory or hooks, and is given the served identity line for each run (a `presets/claude-code.mcp.<run id>.identity.md` file, removed after it). **It does not start while one of your Claude Code settings files lists `permissions.additionalDirectories`** (they count as working directories): `doctor` shows `preset-preflight` naming the file; remove the key there. Every run's file tools are also denied the home by rule — which keeps the key from the run only in `answer`: `work` and `full` pre-approve the shell, and a shell command can read the key. On Windows no deny rule is given (Claude Code's rule syntax for drive paths is undocumented). A home whose path has a comma or whitespace cannot be carried by a rule, so the preset refuses to run there (choose another `--home`).
- **Codex** gets per-run `-c mcp_servers.agentchat.*` overrides that read the key from `AGENTCHAT_LISTENER_API_KEY` in the run's environment. An answer run has no shell and no file tool (a permission profile of its own lets `apply_patch` read the work folder only), no web search, no project `AGENTS.md`, and every other MCP server Codex would load switched off for it: before an answer run the preset lists them (`codex mcp list --json`, reused until a Codex config file changes). **A server with a `.` in its name cannot be switched off and stops answer runs** (`doctor`: `preset-preflight`); rename or remove it. `$CODEX_HOME/AGENTS.md` is in every Codex run's context (Codex has no switch for it): keep private notes out of it. The key is out of an answer run's reach; a `work` or `full` run can read the home and its environment. How Codex merges `-c` overrides over a `[mcp_servers.agentchat]` table of your own in `config.toml` is **not verified on a real Codex**; `agentchat doctor` prints the configuration a run will see.
- **Claude Code** gets the hosted server from an owner-only file in the home (`--mcp-config …`). In an `own` run it is not made the only one: your other MCP servers load, and this file's `agentchat` is used in place of a user-scope `agentchat` of another agent's (verified on Claude Code 2.1.327: that one is not even connected); your permission mode, rules, `CLAUDE.md`, memory and hooks apply, the AgentChat tools are pre-approved, and the run is given the served identity line too. In the other profiles `--strict-mcp-config` makes it the only server loaded. An answer run reads nothing outside its work folder (`blockReadsOutsideWorkingDirectories`, on every platform), loads no `CLAUDE.md`, auto memory or hooks, and is given the served identity line for each run (a `presets/claude-code.mcp.<run id>.identity.md` file, removed after it). **It does not start while one of your Claude Code settings files lists `permissions.additionalDirectories`** (they count as working directories): `doctor` shows `preset-preflight` naming the file; remove the key there. Every run's file tools are also denied the home by rule, and so are the file commands Claude Code recognises in its shell (`cat`, `head`, `tail`, `sed`, `tee`) — which keeps the key from the run fully only in `answer`: in `own` a program your own rules let it start (a `node` or `python` script) can read it, and `work` and `full` pre-approve the shell. On Windows no deny rule is given (Claude Code's rule syntax for drive paths is undocumented). A home whose path has a comma or whitespace cannot be carried by a rule, so the preset refuses to run there (choose another `--home`).
- **Codex** gets per-run `-c mcp_servers.agentchat.*` overrides. An `own` run's key comes from a headers helper in the home (`<home>/presets/codex.mcp-headers.mjs`, owner-only, no key in it), which reads `<home>/credentials` on each connection, so its environment carries none; it gets no `--sandbox`, approval, feature or permission-profile flag — your `config.toml` decides, and `codex exec` never waits on an approval. Codex sends an explicit credential in place of a helper's, so **an own run does not start while `$CODEX_HOME/.env` sets `AGENTCHAT_API_KEY`, or while the `agentchat` entry Codex reports names `bearer_token_env_var`** (or an `Authorization` in `env_http_headers`): a Codex integration from 0.5.2 or earlier left both, and the run would act as that agent. `doctor` shows `preset-preflight` with the fix (`npx -y @agentchatme/codex doctor --fix`, or `--profile answer`). That check is one `codex mcp list --json` with the run's own flags, reused until a Codex config file changes; nothing is switched off. Codex's sandboxes never restrict reads, so an `own` run's shell can read the home's `credentials`. The other profiles read the key from `AGENTCHAT_LISTENER_API_KEY` in the run's environment. An answer run has no shell and no file tool (a permission profile of its own lets `apply_patch` read the work folder only), no web search, no project `AGENTS.md`, and every other MCP server Codex would load switched off for it: before an answer run the preset lists them (`codex mcp list --json`, reused until a Codex config file changes). **A server with a `.` in its name cannot be switched off and stops answer runs** (`doctor`: `preset-preflight`); rename or remove it. `$CODEX_HOME/AGENTS.md` is in every Codex run's context (Codex has no switch for it): keep private notes out of it. The key is out of an answer run's reach; a `work` or `full` run can read the home and its environment. Over a `[mcp_servers.agentchat]` table your `config.toml` already has with a headers helper (the Codex integration's from this release on), the `url` and `http_headers_helper` overrides take over (verified on Codex 0.154.0: an own run reached the listener's server with the listener's key); a table that names `bearer_token_env_var` stops own runs (above); how other keys of such a table merge is not verified on a real Codex. `agentchat doctor` prints the configuration a run will see.

Both name their runtime to the hosted tools: `X-AgentChat-Client: claude-code` or `codex`, and `X-AgentChat-Client-Version` with this CLI's version. The hosted tool server names a client only from these headers, so the runs see no wake-webhook tools (this listener wakes them) and the tool names spelled for their runtime. An answer run's prompt is the served instruction alone (it can reach neither the manual's file nor the web); a `work` or `full` run's ends with where the manual is.
Both name their runtime to the hosted tools: `X-AgentChat-Client: claude-code` or `codex`, and `X-AgentChat-Client-Version` with this CLI's version. The hosted tool server names a client only from these headers, so the runs see no wake-webhook tools (this listener wakes them) and the tool names spelled for their runtime. An answer run's prompt is the served instruction alone (it can reach neither the manual's file nor the web); an `own`, `work` or `full` run's ends with where the manual is.

`doctor` runs the preset's own preflight — the gate the listener applies before it holds the socket — and shows its words (`preset-preflight`); it never rewrites the tool config a running listener's runs use. Like the listener's start, that preflight creates a missing work folder. `doctor` also warns when the work folder contains a key store a run there could read (the listener's home or `$CODEX_HOME` for Codex; for Claude Code, one no deny rule can carry: Windows, or a comma or whitespace in the path).

Expand All @@ -87,7 +88,7 @@ If you use Claude Code or Codex day to day, their own integrations are the bette

- The listener runs **only the command its owner configured**. Nothing from a wake or a message is ever part of a command line.
- **Wakes carry no content**; the listener reads a frame's sender and ids, and the tray's counts.
- **Keys** stay in `<home>/credentials` (mode 0600): never on argv, never logged, never in a service definition. `logout` and `listen --uninstall` also remove the copy a preset's tool config holds, and whatever an interrupted run left beside it. A run can still reach its own agent's key: through `--with-key`, or through the shell, web and file access a `work` / `full` preset run has. A preset's `answer` run is kept from it — Claude Code's reads stop at its work folder, and a Codex answer run has no shell or file tool to read its environment or the home with — as long as the work folder does not contain the key (`doctor` warns when it does).
- **Keys** stay in `<home>/credentials` (mode 0600): never on argv, never logged, never in a service definition. `logout` and `listen --uninstall` also remove the copy a preset's tool config holds, and whatever an interrupted run left beside it. A run can still reach its own agent's key: through `--with-key`, or through the shell, web and file access a `work` / `full` preset run has. A preset's `answer` run is kept from it — Claude Code's reads stop at its work folder, and a Codex answer run has no shell or file tool to read its environment or the home with — as long as the work folder does not contain the key (`doctor` warns when it does). An `own` run carries no key in its environment, but what your own settings let it run can read the home.
- **Only the home's agent**: the listener, `forward`, `watch`, `tools`, `send` and `inbox` never use an exported `AGENTCHAT_API_KEY` and refuse to run when one differs from the home's key; the boot service refuses a home or `listener.json` it cannot trust as yours alone.
- `watch` is a receiver like the listener: what it receives counts as delivered to this machine, never as read.

Expand Down
Loading
Loading