hilos-agent 0.11.1 → 0.11.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pablo Stanley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,13 +1,16 @@
 # hilos-agent
 
-Run **your own** coding agent — Claude Code, Codex, Cursor, opencode, Hermes, or any command — as
+Run **your own** coding agent — Claude Code, Codex, Cursor, opencode,
+Antigravity, Hermes, or any command — as
 an autonomous teammate inside a [hilos](https://hilos.sh) channel.
 
 It connects to hilos over MCP, watches for `@mentions` of your agent in a
 git-linked channel (including thread replies) and for **every message in a DM
 with your agent — no tag needed there**, runs your coding agent in a
-**local** checkout, and — by default — **opens a PR for review**. Your code and
-your git/`gh` credentials never leave your machine — hilos only relays messages.
+**local** checkout, and — by default — **opens a PR for review**. The checkout
+and your coding-provider/git credentials stay on your machine. Changes go to the
+configured Git remote; hilos receives bounded plans, progress, reports, and—when
+the pre-push gate is enabled—the proposal diff.
 
 ```
 hilos channel  ──MCP/HTTPS──▶  hilos-agent (your laptop)
@@ -19,13 +22,13 @@ hilos channel  ──MCP/HTTPS──▶  hilos-agent (your laptop)
          Changes  ▶  agent re-works with your note
 ```
 
-Prefer **approve-before-push**? Set `"gate": true` — the agent then posts the
-proposed diff as a card and pushes only after you Approve (nothing leaves your
-machine until then).
+Prefer **approve-before-push**? Set `"gate": true` — the agent posts a bounded
+proposed diff to hilos as a card, then pushes the change to the Git remote only
+after you Approve.
 
 ## Quick start
 
-In hilos: open your agent's profile → **Connect** → **Run in channel**. Copy the
+In hilos: open your agent's profile → **Connect agent** → **Run in channel**. Copy the
 terminal command and run it from inside your repo's folder. It waits at a hidden
 prompt; copy the private join code from Hilos and paste it there. The daemon
 matches the repo by its git remote, so no config is needed, and the reusable
@@ -39,30 +42,42 @@ npx hilos-agent@latest --join-stdin  # then paste the private join code when ask
 Previously copied `--join <blob>` commands remain compatible. New commands use
 stdin because the blob contains the agent token and should not live in argv.
 
-Running from elsewhere, or want to map several repos explicitly? Use a config:
+Running from elsewhere, or want to map several repos explicitly? Save this as
+`~/.hilos/agent.json` (or `./hilos-agent.json`). The file is strict JSON, so it
+cannot contain comments:
 
-```jsonc
-// ~/.hilos/agent.json  (or ./hilos-agent.json)
+```json
 {
   "url": "https://hilos.sh/api/mcp",
   "token": "mgo_…",
   "repos": { "your-org/your-repo": "/Users/you/code/your-repo" },
-  "codingCmd": "claude -p --permission-mode acceptEdits",  // safe default; see Permissions / autonomy. or "codex exec", "cursor-agent -p --output-format text --trust", "opencode run", "agy -p", any command
-  "codingModel": "",  // Codex tier ("most-capable" | "balanced" | "fastest"), resolved against this account's own model list; "" = the tool's default
-  "chatCmd": "",  // FAST command for chat replies + the plan-ack. Empty = derived from codingCmd's tool (codex daemons chat with codex, etc.); set to override
-  "webSearch": true,  // native public-web tools are on by default; false stops Hilos enablement/instructions
+  "codingCmd": "claude -p --permission-mode acceptEdits",
+  "codingModel": "",
+  "chatCmd": "",
+  "webSearch": true,
   "defaultBranch": "main",
-  "gate": false,               // default: open a PR directly. true = approve-before-push
-  "heartbeatMs": 180000,       // long runs post one "still working…" thread reply this often (0 = off, min 15s)
-  "chatTimeoutMs": 90000,      // cap a chat reply / plan-ack so a stalled model can't go silent
-  "longPollMs": 20000,         // ask the server to HOLD the mention poll and answer the moment work lands (0 = plain 5s polling; older servers fall back automatically)
-  "catchupMs": 86400000        // how far back a restart replays mentions from the persisted cursor (default 24h; 0 = restart at "now", the pre-0866 behavior)
+  "gate": false,
+  "heartbeatMs": 180000,
+  "chatTimeoutMs": 90000,
+  "longPollMs": 20000,
+  "catchupMs": 86400000
 }
 ```
 
+`codingCmd` above is the safe default; it can also be `codex exec`,
+`cursor-agent -p --output-format text --trust`, `opencode run`, `agy -p`, or a
+custom command. `codingModel` accepts the Codex tiers `most-capable`, `balanced`,
+or `fastest`; empty uses the tool's default. Empty `chatCmd` derives a fast chat
+command from `codingCmd`. `webSearch: false` disables hilos's web-search
+enablement, and `gate: true` switches to approve-before-push. `heartbeatMs: 0`
+disables the heartbeat (minimum nonzero value 15 seconds); `longPollMs: 0` uses
+plain five-second polling; `catchupMs: 0` restarts at now instead of replaying
+the default 24-hour window.
+
 **Staying responsive.** Every code task posts an **instant acknowledgement**
-(under a second), and — if your server exposes `edit_message` and a `chatCmd` is
-set — a quick **plan** ("On it — I'll do X, then open a PR") edits into it. On a
+(under a second), and — if your server exposes `edit_message` and a fast chat
+command can be resolved (explicit `chatCmd` or one derived from `codingCmd`) —
+a quick **plan** ("On it — I'll do X, then open a PR") edits into it. On a
 run longer than `heartbeatMs` (default 3 min; env `HILOS_HEARTBEAT_MS`, `0`
 disables, clamped to ≥15s) the agent posts **one progress reply** in the thread
 then edits it in place with elapsed time + the CLI's latest line — so the channel
@@ -98,7 +113,7 @@ The local daemon can give its coding and chat agents a narrow bridge to
 third-party WebMCP sites. It is off until you name exact origins and exact read
 tools in the machine's config:
 
-```jsonc
+```json
 {
   "webMcp": {
     "origins": {
@@ -113,8 +128,11 @@ tools in the machine's config:
 The site does not authorize itself: `readOnlyHint` is informational, while this
 person-owned list decides what may run. Site descriptions are omitted, schema
 prose is stripped, results are bounded and labeled untrusted, and cookies stay
-inside a separate browser profile. The bundled browser bridge currently needs
-Node.js 24 or newer; the rest of the daemon keeps its existing Node.js support.
+inside a separate browser profile. The optional browser bridge needs Node.js 24
+or newer. On Node.js 20 or 22 WebMCP stays unavailable, while the rest of the
+daemon keeps working regardless of whether that optional package was omitted by
+the installer. Run `hilos-agent webmcp doctor` after upgrading Node.js and
+reinstalling the package.
 
 ```sh
 hilos-agent webmcp doctor
@@ -128,7 +146,9 @@ hilos-agent webmcp close
 The daemon adds this capability and its citation rules to agent prompts only
 when the config is valid. Unlisted tools — including writes — are refused with
 `human_approval_required`; there is no approval flag the agent can set. WebMCP
-can never approve or merge hilos work. See the complete contract in
+can never approve or merge hilos work. This wrapper is a policy boundary for
+the bridge, not a sandbox around the coding CLI, which still has the machine
+access its operator granted. See the complete contract in
 [WebMCP in hilos](https://hilos.sh/docs/webmcp).
 
 ## How it works
@@ -147,8 +167,10 @@ can never approve or merge hilos work. See the complete contract in
   it", "approved", or "go for it" after a request, in any language → a code run.
 - **Repo resolution** — the channel's linked repo is mapped to a local path via
   `repos`. No mapping → the agent says so and stops.
-- **Run** — it branches off `defaultBranch` (refuses a dirty tree), runs
-  `codingCmd` with the task, and stages the result.
+- **Run** — it temporarily stashes a dirty checkout, branches off
+  `defaultBranch`, runs `codingCmd` with the task, stages the result, and attempts
+  to restore the person's pre-existing work on every exit path. If `stash pop`
+  conflicts, the stash stays intact and the room gets the recovery command.
 - **Continue the thread's PR** — when the mention lands in a thread hilos says is
   about a pull request, the daemon works on *that* PR instead of opening a second
   one: it fetches the PR's head branch, commits there, and the same PR updates.
@@ -187,8 +209,7 @@ to a plain **local folder** and the agent works in it **directly** — it edits
 files in place (no branch, no commit, no PR), then posts a report of what changed.
 It's your own machine, so this is the same trust as running the CLI yourself.
 
-```jsonc
-// hilos-agent.json
+```json
 {
   "folders": { "<channelId>": "/Users/you/notes-site" }
 }
@@ -222,7 +243,7 @@ It's your own machine, so this is the same trust as running the CLI yourself.
 
 Add an optional per-channel deploy target next to `folders`:
 
-```jsonc
+```json
 {
   "folders": { "<channelId>": "/Users/you/notes-site" },
   "deploy": { "<channelId>": { "provider": "vercel", "prod": false } }
@@ -277,30 +298,29 @@ touching the token.
 
 ## Permissions / autonomy
 
-`codingCmd` decides how much the coding agent can do on its own. Three levels,
-safest first:
-
-- **`opencode run` (runtime-gated).** When the connected hilos server advertises
-  runtime permissions, the daemon runs OpenCode through an authenticated
-  loopback server and becomes its sole permission responder. A tool ask pauses
-  mechanically, posts a card in the run thread, and resumes only after a channel
-  member chooses **Allow once**, an exact harness-suggested **Always** rule, or
-  **Deny**. Missing transport, expiry, and cancellation all reject the tool
-  call. `opencode run --auto` deliberately bypasses these cards and keeps
-  OpenCode's dangerous auto-approve behavior.
-- **`--permission-mode acceptEdits` (default).** The agent edits files without
-  prompting, but in headless `claude -p` a step that needs bash — run the tests,
-  install a dep — has no interactive prompt to grant, so the task can **stall**.
-  Good when the work is edit-only; frustrating for anything that needs to run
-  commands.
-- **`--dangerously-skip-permissions` (recommended for independent agents).** Full
-  autonomy: the agent can run the tests, install deps, and finish hands-off.
-  Caution: it can run **any** command in the repo you point it at — only use it
-  on a repo and machine where that's acceptable. This is the option to pick if
-  you want the agent to actually work on its own.
-
-  ```jsonc
-  "codingCmd": "claude -p --dangerously-skip-permissions"
+There are two separate gates:
+
+- **Room runtime permissions.** When the workspace has granted runtime
+  permissions, current daemons put Claude Code, Codex, Cursor, and OpenCode
+  behind the same server-authorized card flow. A tool ask pauses mechanically
+  and resumes only after an eligible channel member chooses **Allow once**, an
+  exact harness-suggested **Always** rule, or **Deny**. Cursor and OpenCode use
+  ACP; Claude Code uses its permission-prompt tool; Codex uses `codex
+  mcp-server` because `codex exec` has no approval transport. Once a relay is
+  active, authority loss, expiry, cancellation, and transport failure all fail
+  closed. A positively unavailable old-CLI transport is the compatibility
+  exception: the daemon warns the room, then starts the ungated fallback.
+  Explicit vendor bypass modes such as `opencode run --auto` or Claude Code's
+  `--dangerously-skip-permissions` deliberately opt out of the cards.
+- **The CLI's own mode.** Without a workspace runtime grant, `codingCmd` remains
+  authoritative. The default Claude Code command uses
+  `--permission-mode acceptEdits`: it may edit without prompting, but a headless
+  command that needs additional approval can stall. For a fully independent
+  local agent, `--dangerously-skip-permissions` can run any command in the repo
+  you point it at, so use it only where that trust is acceptable.
+
+  ```json
+  { "codingCmd": "claude -p --dangerously-skip-permissions" }
   ```
 
 - **Approve-before-push (`gate:true`), most cautious.** Independent of the two
@@ -309,10 +329,9 @@ safest first:
 
 The default stays `acceptEdits`. Reach for `--dangerously-skip-permissions` when
 you want a truly hands-off teammate, and keep `gate:true` if you'd rather review
-before anything is pushed. OpenCode is the first harness with the runtime-card
-bridge; Claude Code, Codex, Cursor, and other adapters still follow their own
-CLI permission modes until their native approval hooks join the same
-vendor-neutral hilos substrate.
+before anything is pushed. Runtime cards and the push gate are independent: one
+governs tools during the run, the other governs when the resulting code leaves
+the machine.
 
 ## Hooks — keep a raw Codex, Claude Code, or Cursor session in the room
 
@@ -361,8 +380,9 @@ npx hilos-agent@latest hooks print
   live card. The normal one-line `--join` flow does not need that file for
   replies: its token stays in daemon memory, and Hilos signs each session
   binding so the daemon can verify it before resuming local code.
-- Keep `hilos-agent` running to pick replies up. Hooks alone still stream live
-  steps, but MCP has no server-push channel that can wake an idle local client.
+- Keep `hilos-agent` running to pick replies up. Hooks only emit lifecycle
+  events; the daemon is the consumer that waits on the server's wake/long-poll
+  path and resumes the local session.
 
 **What you get:**
 - Team members see "Editing lib/x.ts" or "Running pnpm test" on the agent's live
@@ -418,8 +438,9 @@ An older server simply leaves it off.
 ### Run transcripts are opt-in
 
 The room gets what a teammate needs to see: a plan, live progress, a report, a
-PR. The coding tool's own stream is **not** part of that by default — the live
-card is an eight-step window and nothing keeps it after the run.
+PR. The coding tool's raw stream is **not** part of that by default. Current
+servers do keep a bounded, redacted set of structured activity facts through
+the runtime-neutral event protocol described above; that is not a transcript.
 
 Set `"uploadTranscripts": true` and the daemon, after posting its report, sends
 the tail of that run's stream to hilos, where it becomes the same transcript a
@@ -440,18 +461,35 @@ restart — and **deleting** the key counts as off, not as "leave it as it was".
 
 ## Flags
 
-`--join <blob>` · `--channel <id>` · `--config <path>` · `--coding-cmd <cmd>` ·
-`--chat-cmd <cmd>` · `--once` · `--backfill` · `--no-gate` · `--help`
+`--join <blob>` · `--join-stdin` · `--channel <id>` · `--config <path>` ·
+`--url <endpoint>` · `--token <token>` ·
+`--coding-cmd <cmd>` · `--coding-model <tier>` · `--chat-cmd <cmd>` ·
+`--web-search` · `--no-web-search` · `--once` · `--backfill` · `--gate` ·
+`--no-gate` · `--no-reply-bridge` · `--version` · `--help`. Hook installation
+also accepts `--global` or one of `--claude`, `--codex`, and `--cursor`.
+
+`--token` remains only for compatibility with older scripts. Command-line
+arguments can be visible to other processes on the machine, so use
+`--join-stdin`, `HILOS_TOKEN`, or the private config file for credentials.
+Likewise, prefer `--join-stdin` over the legacy `--join <blob>` form for a new
+connection.
+
+See `hilos-agent --help` for the `init`, `webmcp`, `web doctor`, and `hooks`
+subcommands.
 
-Env: `HILOS_TOKEN`, `HILOS_URL`, `HILOS_CHANNEL`, `CODING_CMD`, `HILOS_ONCE=1`,
-`HILOS_BACKFILL=1`, `HILOS_UPLOAD_TRANSCRIPTS=1|0`.
+Env: `HILOS_TOKEN`, `HILOS_URL`, `HILOS_CHANNEL`, `CODING_CMD`,
+`HILOS_CODING_MODEL`, `HILOS_CHAT_CMD`, `HILOS_WEB_SEARCH=1|0`,
+`HILOS_ACP=1|0`, `HILOS_HEARTBEAT_MS`, `HILOS_PROGRESS_MS`,
+`HILOS_CHAT_TIMEOUT_MS`, `HILOS_REPLY_BRIDGE=1|0`, `HILOS_ONCE=1`,
+`HILOS_BACKFILL=1`, and `HILOS_UPLOAD_TRANSCRIPTS=1|0`.
 
 ## Releasing
 
-Bump `version` in `package.json`, merge, then tag that commit
-`hilos-agent-v<version>` and push the tag. The `npm-publish` workflow checks
-the tag against the tree, parses every source file on Node 20, 22, and 24,
-and publishes to npm (without provenance while the repository is private:
-npm refuses a provenance bundle from a private source repository, 1182).
-`workflow_dispatch` runs the same pipeline as a dry run. Needs the
-`NPM_TOKEN` repository secret (1094).
+Bump `version` in `package.json`, merge, wait for main CI, then tag that commit
+`hilos-agent-v<version>` and push the tag. The `npm-publish` workflow requires
+that exact version, a commit contained in `main`, and a successful `verify`
+check. It packs and clean-installs the artifact on Node.js 20, 22, and 24 before
+publishing, then installs the registry copy and checks its version and help.
+A manual workflow dispatch is always a dry run and cannot publish. The current
+release path needs the `NPM_TOKEN` repository secret until npm trusted
+publishing is configured (1094, 1211).

package/bin/hilos-agent.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 // hilos-agent — run your coding agent as an autonomous teammate in a hilos
-// channel. Picks up @mentions, proposes a diff, pushes only after a human
-// approves in hilos. Your code + credentials never leave your machine.
+// channel. Picks up @mentions and opens a PR by default; an optional pre-push
+// gate waits for a person's approval. The checkout and credentials stay local;
+// changes go to the configured Git remote and bounded run state goes to hilos.
 //
 // Usage:
 //   hilos-agent --join <blob>      connect with a copy-paste link from hilos
@@ -35,43 +36,107 @@ function packageVersion() {
   return JSON.parse(readFileSync(pkgPath, "utf8")).version;
 }
 
+function requiredOptionValue(argv, index, option) {
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith("-")) {
+    throw new Error(`Option ${option} requires a value.`);
+  }
+  return value;
+}
+
+function validateCommand(cmd, positional, { skipShape = false } = {}) {
+  const commands = new Set(["run", "init", "hook", "hooks", "webmcp", "web", "help", "version"]);
+  if (!commands.has(cmd)) {
+    throw new Error(`Unknown command: ${cmd}. Try \`hilos-agent --help\`.`);
+  }
+  if (skipShape) return;
+
+  if (["run", "init", "hook", "help", "version"].includes(cmd) && positional.length > 1) {
+    throw new Error(`Unexpected argument for ${cmd}: ${positional[1]}. Try \`hilos-agent --help\`.`);
+  }
+
+  if (cmd === "hooks") {
+    const subcommand = positional[1];
+    if (!subcommand) throw new Error("A hooks command is required: install or print.");
+    if (!new Set(["install", "print"]).has(subcommand)) {
+      throw new Error(`Unknown hooks command: ${subcommand}. Use install or print.`);
+    }
+    if (positional.length > 2) {
+      throw new Error(`Unexpected argument for hooks ${subcommand}: ${positional[2]}.`);
+    }
+  }
+
+  if (cmd === "web") {
+    const subcommand = positional[1] || "doctor";
+    if (subcommand !== "doctor") {
+      throw new Error(`Unknown web command: ${subcommand}. Try \`hilos-agent web doctor\`.`);
+    }
+    if (positional.length > 2) {
+      throw new Error(`Unexpected argument for web doctor: ${positional[2]}.`);
+    }
+  }
+
+  if (cmd === "webmcp") {
+    const operation = positional[1] || "doctor";
+    const allowed = new Set(["doctor", "login", "open", "tools", "call", "close"]);
+    if (!allowed.has(operation)) {
+      throw new Error(`Unknown webmcp command: ${operation}. Use doctor, login, open, tools, call, or close.`);
+    }
+    const argumentCount = positional.length - 2;
+    const validCount = operation === "login" || operation === "open"
+      ? argumentCount === 1
+      : operation === "call"
+        ? argumentCount === 1 || argumentCount === 2
+        : argumentCount === 0;
+    if (!validCount) {
+      throw new Error(`Invalid arguments for webmcp ${operation}. Try \`hilos-agent --help\`.`);
+    }
+  }
+}
+
 function parseArgs(argv) {
   const flags = {};
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === "--join") flags.join = argv[++i];
+    if (a === "--join") flags.join = requiredOptionValue(argv, i++, a);
     else if (a === "--join-stdin") flags.joinStdin = true;
-    else if (a === "--config") flags.config = argv[++i];
-    else if (a === "--channel") flags.channelId = argv[++i];
-    else if (a === "--url") flags.url = argv[++i];
-    else if (a === "--token") flags.token = argv[++i];
-    else if (a === "--coding-cmd") flags.codingCmd = argv[++i];
-    else if (a === "--coding-model") flags.codingModel = argv[++i];
-    else if (a === "--chat-cmd") flags.chatCmd = argv[++i];
+    else if (a === "--config") flags.config = requiredOptionValue(argv, i++, a);
+    else if (a === "--channel") flags.channelId = requiredOptionValue(argv, i++, a);
+    else if (a === "--url") flags.url = requiredOptionValue(argv, i++, a);
+    else if (a === "--token") flags.token = requiredOptionValue(argv, i++, a);
+    else if (a === "--coding-cmd") flags.codingCmd = requiredOptionValue(argv, i++, a);
+    else if (a === "--coding-model") flags.codingModel = requiredOptionValue(argv, i++, a);
+    else if (a === "--chat-cmd") flags.chatCmd = requiredOptionValue(argv, i++, a);
     else if (a === "--no-web-search") flags.webSearch = false;
     else if (a === "--web-search") flags.webSearch = true;
     else if (a === "--once") flags.once = true;
     else if (a === "--backfill") flags.backfill = true;
+    else if (a === "--gate") flags.gate = true;
     else if (a === "--no-gate") flags.gate = false;
     else if (a === "--no-reply-bridge") flags.replyBridge = false;
     else if (a === "--global") flags.global = true;
     else if (a === "--claude") flags.hookClient = "claude";
     else if (a === "--codex") flags.hookClient = "codex";
     else if (a === "--cursor") flags.hookClient = "cursor";
-    else if (a === "--vendor") flags.vendor = argv[++i];
+    else if (a === "--vendor") flags.vendor = requiredOptionValue(argv, i++, a);
     else if (a === "--scope-managed") flags.scopeManaged = true;
+    // Marker embedded in self-contained hook commands. It is intentionally
+    // internal: hook.mjs uses it to recognize and replace managed installs.
     else if (a === "--managed-runtime") flags.managedRuntime = true;
     else if (a === "-h" || a === "--help") flags.help = true;
     else if (a === "-v" || a === "--version") flags.version = true;
+    else if (a.startsWith("-")) throw new Error(`Unknown option: ${a}. Try \`hilos-agent --help\`.`);
     else positional.push(a);
   }
-  return { cmd: positional[0] || "run", flags, positional };
+  const cmd = positional[0] || "run";
+  validateCommand(cmd, positional, { skipShape: flags.help || flags.version });
+  return { cmd, flags, positional };
 }
 
 const HELP = `hilos-agent — your coding agent as a teammate in hilos
 
-  hilos-agent --join <blob>      connect using a link copied from hilos
+  hilos-agent --join <blob>      legacy argv-compatible connect link
   hilos-agent --join-stdin       paste the private link at a no-echo prompt
   hilos-agent init               write a starter config to ~/.hilos/agent.json
   hilos-agent webmcp doctor      verify the local WebMCP browser bridge
@@ -82,16 +147,21 @@ const HELP = `hilos-agent — your coding agent as a teammate in hilos
   hilos-agent webmcp close       close the isolated browser session
   hilos-agent web doctor         report this CLI's native public-web capability
   hilos-agent                    run the daemon (watch @mentions, propose diffs)
+  hilos-agent run                same as above, explicit
   hilos-agent hooks install      stream this repo's Codex, Claude, and Cursor
                                  sessions to hilos and continue replies in the same
                                  local session. Installs all three hook formats;
                                  use --codex, --claude, or --cursor to choose, and
                                  --global for every repo. HILOS_HOOKS=off pauses
                                  streaming; HILOS_REPLY_BRIDGE=off pauses pickup.
+  hilos-agent hooks print        preview the hook configuration without writing
 
 Options:
   --channel <id>     watch only one channel (per-channel override)
   --config <path>    use a specific config file
+  --url <endpoint>   override the MCP endpoint (or use HILOS_URL/config)
+  --token <token>    legacy token override; argv may be visible to other local
+                     processes. Prefer --join-stdin or HILOS_TOKEN.
   --coding-cmd <cmd> the coding agent to run — claude -p, codex exec,
                      cursor-agent -p --trust, opencode run, agy -p, hermes -z,
                      or any command
@@ -104,10 +174,12 @@ Options:
   --chat-cmd <cmd>   fast command for chat replies + the plan-ack (default:
                      derived from the coding command, so a Codex or Cursor
                      daemon chats with its own tool)
+  --web-search       allow hilos to request native public web tools (default)
   --no-web-search    stop hilos from enabling/requesting native public web
   --once             one poll then exit (cron-friendly)
   --backfill         also act on mentions that predate startup
-  --no-gate          propose only; don't wait for approval / push
+  --gate             wait for approval in hilos before pushing a branch
+  --no-gate          open a PR directly without pre-push approval (default)
   --no-reply-bridge  don't resume local sessions from replies in bound threads
   -v, --version      print the installed version
   -h, --help         this help
@@ -158,6 +230,7 @@ async function main() {
     const starter = { ...(joinPayload || {}) };
     if (flags.codingCmd) starter.codingCmd = flags.codingCmd;
     if (flags.codingModel) starter.codingModel = flags.codingModel;
+    if (flags.gate !== undefined) starter.gate = flags.gate;
     const path = writeStarterConfig(joinPayload ? GLOBAL_CONFIG : flags.config, starter);
     console.log(`Wrote ${path}.`);
     console.log(joinPayload ? "Token + endpoint set from your link." : "Fill in token + repos, then run `hilos-agent`.");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hilos-agent",
-  "version": "0.11.1",
-  "description": "Run your own coding agent (Claude Code / Codex / Cursor) as an autonomous teammate in a hilos channel. Picks up @mentions in channels and threads, makes the change, and opens a PR for review — your code and credentials never leave your machine. (Approve-before-push is available via gate:true.)",
+  "version": "0.11.3",
+  "description": "Run your own coding agent (Claude Code, Codex, Cursor, OpenCode, Hermes, or any command) as a teammate in a hilos room. The checkout and credentials stay local; changes go to your configured Git remote as a PR for human review, and bounded progress and reports go to hilos.",
   "type": "module",
   "bin": {
     "hilos-agent": "bin/hilos-agent.mjs"
@@ -30,10 +30,12 @@
     "claude-code",
     "codex",
     "cursor",
+    "opencode",
+    "hermes-agent",
     "coding-agent"
   ],
   "license": "MIT",
-  "dependencies": {
-    "agent-browser": "^0.35.0"
+  "optionalDependencies": {
+    "agent-browser": "^0.36.0"
   }
 }

package/src/acp-session.mjs

@@ -191,6 +191,7 @@ export function createNdjsonParser() {
  *   requestPermission?: (request: object, context: object) => Promise<unknown>,
  *   getPermissionDecision?: (handle: unknown, context: object) => Promise<unknown>,
  *   mcpServers?: object[],
+ *   beforeSpawn?: () => boolean | Promise<boolean>,
  *   spawnImpl?: (cmd: string, args: string[], options: object) => import("node:child_process").ChildProcess,
  *   setTimer?: typeof setTimeout,
  *   clearTimer?: typeof clearTimeout,
@@ -217,6 +218,7 @@ export async function runAcpSession({
   /** Session to continue (0778); null starts a fresh one. */
   resumeSessionId = null,
   mcpServers = [],
+  beforeSpawn,
   spawnImpl = spawn,
   setTimer = setTimeout,
   clearTimer = clearTimeout,
@@ -264,6 +266,7 @@ export async function runAcpSession({
   let currentMessageId = null;
   let messageBuffer = "";
   const eventMapper = createAcpEventMapper();
+  let authorityLost = false;
 
   const emitOutput = (text) => {
     try {
@@ -411,6 +414,17 @@ export async function runAcpSession({
   }
 
   try {
+    if (typeof beforeSpawn === "function") {
+      try {
+        if ((await beforeSpawn()) === false) {
+          authorityLost = true;
+          throw new Error("execution authority lost before ACP spawn");
+        }
+      } catch (error) {
+        authorityLost = true;
+        throw error;
+      }
+    }
     child = spawnImpl(cmd, acpArgs, { cwd, env, stdio: ["pipe", "pipe", "pipe"] });
     const spawned = new Promise((resolve, reject) => {
       child.once("spawn", resolve);
@@ -508,13 +522,14 @@ export async function runAcpSession({
     };
   } catch (error) {
     flushMessage();
-    const aborted = abortKind === "cancelled";
+    const aborted = abortKind === "cancelled" || authorityLost;
     const timedOut = abortKind === "timeout";
     return {
       status: null,
       stdout: stdout.trimEnd(),
       stderr: stderr.trimEnd(),
       ...(aborted ? { aborted: true } : {}),
+      ...(authorityLost ? { authorityLost: true } : {}),
       ...(sessionId ? { sessionId } : {}),
       error:
         error instanceof Error && !timedOut

package/src/cli.mjs

@@ -179,6 +179,9 @@ const MAX_CAPTURE_BYTES = 50 * 1024 * 1024;
  *   BEFORE the ungated compat retry is spawned when a CLI rejects the 0777
  *   permission flags (0785), so the caller can warn its room while the run can
  *   still be stopped. A throw here never fails the run.
+ * @property {() => (boolean | Promise<boolean>)} [beforeSpawn] - fail-closed
+ *   authority check, awaited immediately before each child-process attempt.
+ *   Returning false or throwing prevents that spawn and marks the run aborted.
  */
 
 /**
@@ -191,7 +194,7 @@ const MAX_CAPTURE_BYTES = 50 * 1024 * 1024;
  *
  * @param {RunCliOptions} opts
  */
-function runCliOnce(opts) {
+async function runCliOnce(opts) {
   const {
     cmd,
     args = [],
@@ -204,7 +207,37 @@ function runCliOnce(opts) {
     signal,
     onData,
     env,
+    beforeSpawn,
   } = opts || {};
+  // This guard belongs at the process boundary, after all potentially-slow
+  // caller setup and once per compatibility retry. Checking in runCli's caller
+  // leaves a race before the first child and lets its internal retries escape.
+  if (signal?.aborted) {
+    return { status: null, stdout: "", stderr: "", aborted: true, error: new Error("cancelled") };
+  }
+  if (typeof beforeSpawn === "function") {
+    try {
+      if ((await beforeSpawn()) === false) {
+        return {
+          status: null,
+          stdout: "",
+          stderr: "",
+          aborted: true,
+          authorityLost: true,
+          error: new Error("execution authority lost before spawn"),
+        };
+      }
+    } catch (error) {
+      return {
+        status: null,
+        stdout: "",
+        stderr: "",
+        aborted: true,
+        authorityLost: true,
+        error: error instanceof Error ? error : new Error(String(error)),
+      };
+    }
+  }
   return new Promise((resolve) => {
     // Already cancelled before we even start.
     if (signal?.aborted) {