@bookedsolid/reagent 0.12.0 → 0.12.2

package/README.md

@@ -48,8 +48,8 @@ Point your AI assistant's MCP configuration at the gateway:
 {
   "mcpServers": {
     "reagent": {
-      "command": "reagent",
-      "args": ["serve"]
+      "command": "npx",
+      "args": ["-y", "@bookedsolid/reagent", "serve"]
     }
   }
 }
@@ -78,12 +78,124 @@ npx @bookedsolid/reagent init --discord   # configure Discord notifications
 npx @bookedsolid/reagent init --dry-run
 ```
 
+## Installing Reagent in Your Project
+
+This section documents the end-to-end setup for a new project — including the nuances of MCP transport, token passing, and env var expansion that aren't obvious from first principles.
+
+### Step 1 — Run `reagent init`
+
+```bash
+cd /path/to/your-project
+npx @bookedsolid/reagent init --profile bst-internal
+```
+
+This installs hooks, policy, agent team, gateway config template, and Claude settings. It also writes a managed block into `CLAUDE.md` with agent behavioral rules.
+
+To pick up an updated hook suite after a reagent version bump:
+
+```bash
+npx @bookedsolid/reagent upgrade
+```
+
+`upgrade` re-syncs hooks that are already installed and bumps `installed_by` in `policy.yaml`. It never adds new hooks without consent.
+
+### Step 2 — Configure `.mcp.json`
+
+**Use stdio transport — not HTTP.** Claude Code's HTTP MCP transport requires OAuth 2.1, which the reagent server does not implement. The stdio transport is what works:
+
+```json
+{
+  "mcpServers": {
+    "reagent": {
+      "command": "npx",
+      "args": ["-y", "@bookedsolid/reagent", "serve"]
+    }
+  }
+}
+```
+
+> **Why `npx` instead of `reagent`?** Using the bare `reagent` command requires a global install. `npx` works from any project, always uses the registry version, and avoids "command not found" errors on machines where reagent isn't globally installed.
+
+> **Env vars in `.mcp.json`:** Claude Code does **not** expand `${VAR}` syntax in `.mcp.json` env values — the literal string `${MY_TOKEN}` is passed to the process, not the value. If reagent needs tokens to pass to downstream MCP servers (e.g., Discord bots), use the gateway proxy pattern instead (see Step 3). The gateway **does** expand `${VAR}` from the shell environment at startup.
+
+If you need to pass env vars to `reagent serve` itself (e.g., tokens used by native tools like `discord_notify`), set them in your shell environment rather than in `.mcp.json`:
+
+```bash
+# In your shell profile or .env (never committed):
+export BOOKED_DISCORD_BOT_TOKEN="..."
+```
+
+### Step 3 — Configure downstream MCP servers (gateway proxy)
+
+If your project uses other MCP servers that need secrets (API keys, bot tokens, etc.), proxy them through reagent's gateway rather than adding them directly to `.mcp.json`. This is the **only** way to pass env vars reliably from Claude Code.
+
+Edit `.reagent/gateway.yaml`:
+
+```yaml
+version: '1'
+
+servers:
+  discord-ops:
+    command: npx
+    args: ['-y', 'discord-ops@latest']
+    env:
+      BOOKED_DISCORD_BOT_TOKEN: '${BOOKED_DISCORD_BOT_TOKEN}'
+      CLARITY_DISCORD_BOT_TOKEN: '${CLARITY_DISCORD_BOT_TOKEN}'
+```
+
+The `${VAR}` syntax here is resolved by reagent from `process.env` at gateway startup — it works because reagent inherits the shell environment from Claude Code's process. The spawned child MCP server receives the resolved values.
+
+Do **not** add the same server to both `gateway.yaml` and `.mcp.json` directly — `reagent init` warns about this. Direct `.mcp.json` entries with `${VAR}` env values will pass the literal string, not the token.
+
+### Step 4 — Commit the config files
+
+`reagent init` generates files in two categories:
+
+| File                         | Commit?                                             |
+| ---------------------------- | --------------------------------------------------- |
+| `.reagent/policy.yaml`       | Yes — defines autonomy level for the team           |
+| `.reagent/gateway.yaml`      | Yes — documents which MCP servers this project uses |
+| `.claude/settings.json`      | Yes — permission gates for Claude Code              |
+| `.claude/hooks/`             | Yes — safety and quality hooks                      |
+| `.claude/agents/`            | Yes — agent team definitions                        |
+| `CLAUDE.md` (managed block)  | Yes — behavioral rules for AI agents                |
+| `.reagent/tasks.jsonl`       | No — gitignored, local task store                   |
+| `.reagent/audit/`            | No — gitignored, local audit log                    |
+| `.reagent/review-cache.json` | No — gitignored, local review cache                 |
+
+### Upgrading an existing install
+
+When a new version of reagent ships with updated hooks or agents:
+
+```bash
+npx @bookedsolid/reagent upgrade
+```
+
+This re-syncs all hooks in `.claude/hooks/` and `.husky/` that were installed by a previous `reagent init`. It will not add hooks that weren't installed originally.
+
+### How `reagent serve` runs in Claude Code
+
+When Claude Code reads `.mcp.json`, it spawns `npx -y @bookedsolid/reagent serve` as a child process. The MCP protocol runs over stdio between Claude Code and the reagent process. Reagent then spawns its own child processes for each entry in `gateway.yaml`, also over stdio.
+
+The resulting process tree:
+
+```
+Claude Code
+  └── reagent serve (stdio MCP to Claude Code)
+        └── discord-ops (stdio MCP, proxied through reagent)
+        └── other-server (stdio MCP, proxied through reagent)
+```
+
+All tool calls from Claude Code go through reagent's middleware chain before reaching downstream servers.
+
 ## Commands
 
 | Command                         | Description                                       |
 | ------------------------------- | ------------------------------------------------- |
 | `reagent serve`                 | Start the MCP gateway server (stdio transport)    |
+| `reagent serve`                 | Start the MCP gateway server (stdio transport)    |
 | `reagent init`                  | Install reagent config into the current directory |
+| `reagent upgrade`               | Re-sync hooks and bump installed_by in policy     |
 | `reagent catalyze`              | Analyze project stack and generate gap report     |
 | `reagent check`                 | Verify what reagent components are installed      |
 | `reagent freeze --reason "..."` | Create `.reagent/HALT` — suspends all tool calls  |
@@ -107,6 +219,14 @@ npx @bookedsolid/reagent init --dry-run
 | `--releases-channel <id>` | Discord channel for release events             | —                   |
 | `--dev-channel <id>`      | Discord channel for dev activity               | —                   |
 
+### `reagent upgrade` Options
+
+| Flag        | Description                                  | Default |
+| ----------- | -------------------------------------------- | ------- |
+| `--dry-run` | Preview what would be updated without writes | —       |
+
+Re-syncs hooks in `.claude/hooks/` and `.husky/` that were installed by a previous `reagent init`. Updates `installed_by` in `.reagent/policy.yaml`. Never adds hooks that weren't originally installed.
+
 ### `reagent catalyze` Options
 
 | Flag          | Description                                          | Default |

package/dist/cli/commands/init/policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/init/policy.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/D,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,OAAO,GACd,aAAa,EAAE,CAgFjB"}
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/init/policy.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/D,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,OAAO,GACd,aAAa,EAAE,CAkFjB"}

package/dist/cli/commands/init/policy.js

@@ -16,7 +16,9 @@ export function installPolicy(targetDir, profileName, profile, dryRun) {
         const coverageEnabled = profile.coverage?.enabled === true;
         const coverageThreshold = profile.coverage?.threshold ?? 80;
         const blockedPaths = profile.blockedPaths ?? [
-            '.reagent/',
+            '.reagent/policy.yaml',
+            '.reagent/HALT',
+            '.reagent/review-cache.json',
             '.github/workflows/',
             '.env',
             '.env.*',

package/dist/cli/commands/init/policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../../src/cli/commands/init/policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG/C,MAAM,UAAU,aAAa,CAC3B,SAAiB,EACjB,WAAmB,EACnB,OAAsB,EACtB,MAAe;IAEf,MAAM,WAAW,GAAG,aAAa,EAAE,CAAC;IACpC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACpD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;IAExD,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,EAAE,IAAI,EAAE,sBAAsB,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,KAAK,IAAI,CAAC;QAC7D,MAAM,cAAc,GAAG,OAAO,CAAC,QAAQ,EAAE,cAAc,IAAI,UAAU,CAAC;QACtE,MAAM,eAAe,GAAG,OAAO,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;QAC3D,MAAM,iBAAiB,GAAG,OAAO,CAAC,QAAQ,EAAE,SAAS,IAAI,EAAE,CAAC;QAC5D,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI;YAC3C,WAAW;YACX,oBAAoB;YACpB,MAAM;YACN,QAAQ;SACT,CAAC;QACF,MAAM,gBAAgB,GAAG,YAAY,CAAC,MAAM;YAC1C,CAAC,CAAC,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YACjE,CAAC,CAAC,KAAK,CAAC;QACV,MAAM,OAAO,GAAG,+DAA+D,WAAW;;;;;YAKlF,WAAW;yBACE,WAAW;iBACnB,GAAG;;;;;;;;;;;;;;;;;;wBAkBI,gBAAgB;;;gBAGxB,gBAAgB;;;;;;;;;;;;aAYnB,eAAe;eACb,iBAAiB;;;;;;;;sBAQV,cAAc;CACnC,CAAC;QACE,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,CAAC,EAAE,IAAI,EAAE,sBAAsB,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;AACjE,CAAC"}
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../../src/cli/commands/init/policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG/C,MAAM,UAAU,aAAa,CAC3B,SAAiB,EACjB,WAAmB,EACnB,OAAsB,EACtB,MAAe;IAEf,MAAM,WAAW,GAAG,aAAa,EAAE,CAAC;IACpC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACpD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;IAExD,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,EAAE,IAAI,EAAE,sBAAsB,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,KAAK,IAAI,CAAC;QAC7D,MAAM,cAAc,GAAG,OAAO,CAAC,QAAQ,EAAE,cAAc,IAAI,UAAU,CAAC;QACtE,MAAM,eAAe,GAAG,OAAO,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;QAC3D,MAAM,iBAAiB,GAAG,OAAO,CAAC,QAAQ,EAAE,SAAS,IAAI,EAAE,CAAC;QAC5D,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI;YAC3C,sBAAsB;YACtB,eAAe;YACf,4BAA4B;YAC5B,oBAAoB;YACpB,MAAM;YACN,QAAQ;SACT,CAAC;QACF,MAAM,gBAAgB,GAAG,YAAY,CAAC,MAAM;YAC1C,CAAC,CAAC,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YACjE,CAAC,CAAC,KAAK,CAAC;QACV,MAAM,OAAO,GAAG,+DAA+D,WAAW;;;;;YAKlF,WAAW;yBACE,WAAW;iBACnB,GAAG;;;;;;;;;;;;;;;;;;wBAkBI,gBAAgB;;;gBAGxB,gBAAgB;;;;;;;;;;;;aAYnB,eAAe;eACb,iBAAiB;;;;;;;;sBAQV,cAAc;CACnC,CAAC;QACE,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,CAAC,EAAE,IAAI,EAAE,sBAAsB,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;AACjE,CAAC"}

package/hooks/blocked-paths-enforcer.sh

@@ -90,28 +90,36 @@ if [[ ${#BLOCKED_PATHS[@]} -eq 0 ]]; then
   exit 0
 fi
 
-# ── 6. Normalize and match ────────────────────────────────────────────────────
+# ── 6. Agent-writable allowlist ───────────────────────────────────────────────
+# These paths under .reagent/ must always be writable by agents regardless of
+# what blocked_paths says. Blocking the whole .reagent/ directory in policy
+# is a common default, but tasks.jsonl is the PM data store — agents must
+# write there. Settings-protection.sh guards the sensitive files explicitly.
+AGENT_WRITABLE=(
+  '.reagent/tasks.jsonl'
+  '.reagent/audit/'
+)
 
-# Convert to relative path from project root
 normalize_path() {
   local p="$1"
   local root="$REAGENT_ROOT"
-
-  # Strip project root prefix if present
   if [[ "$p" == "$root"/* ]]; then
     p="${p#$root/}"
   fi
-
-  # URL decode common sequences
   p=$(printf '%s' "$p" | sed 's/%2[Ff]/\//g; s/%2[Ee]/./g; s/%20/ /g')
-
-  # Remove ./ prefix
   p="${p#./}"
-
   printf '%s' "$p"
 }
 
 NORMALIZED=$(normalize_path "$FILE_PATH")
+
+for writable in "${AGENT_WRITABLE[@]}"; do
+  if [[ "$NORMALIZED" == "$writable" ]] || [[ "$NORMALIZED" == "$writable"* && "$writable" == */ ]]; then
+    exit 0
+  fi
+done
+
+# ── 7. Match against blocked_paths ───────────────────────────────────────────
 LOWER_NORM=$(printf '%s' "$NORMALIZED" | tr '[:upper:]' '[:lower:]')
 
 for blocked in "${BLOCKED_PATHS[@]}"; do

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/reagent",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Zero-trust MCP gateway — policy enforcement, secret redaction, and audit logging for AI-assisted projects",
   "license": "MIT",
   "author": "Booked Solid Technology <oss@bookedsolid.tech> (https://bookedsolid.tech)",