@bluewombat/slots 0.6.0 → 0.8.0

package/README.md

@@ -95,7 +95,13 @@ or `--report`. A role slot after `--` is what names one:
 `cursor.mjs` needs `cursor-agent` on PATH. Without `--agent-home` it uses the
 CLI's own login (`cursor-agent login`). With `--agent-home DIR` and
 `--api-key-env NAME` the vendor process gets that directory as `HOME` and
-`CURSOR_API_KEY` from `NAME`; the value never appears on the argv. `claude.mjs`
+`CURSOR_API_KEY` from `NAME`; the value never appears on the argv. It also gets
+a short environment (`PATH`, locale, proxy and certificate variables and a few
+others, plus the names given with `--pass-env`), not the operator's whole
+shell; git's credential helpers are cleared for it; and `ssh`, `scp` plus the
+commands given with `--deny-shell` are denied in its own `cli-config.json`,
+rewritten every run. That
+lowers a risk and confines nothing (RESERVATIONS F32). `claude.mjs`
 needs `claude`, signed in once, and refuses those two flags: Claude is not
 isolated yet, and starting it would keep the operator's own config.
 
@@ -112,16 +118,62 @@ isolated yet, and starting it would keep the operator's own config.
 | `--agent-arg VALUE`                | Appended to the CLI argv, before the prompt. Repeatable                          |
 | `--agent-home DIR`                 | Isolate the vendor process: its `HOME` is this directory. Cursor only; Claude refuses |
 | `--api-key-env NAME`               | With `--agent-home`, read `process.env[NAME]` for the vendor key. Never the value itself |
+| `--pass-env NAME`                  | With `--agent-home`, also hand the vendor this environment variable. Repeatable |
+| `--deny-shell NAME`                | With `--agent-home`, also refuse this command to the vendor (`gh`, `vercel`…). `ssh` and `scp` always are. Repeatable |
+| `--plugin-dir DIR`                 | A plugin folder of the operator's (a Mason home's `ai-plugins/core/*`). Repeatable, loaded first |
+| `--profile NAME`                   | The project's deck profile for this role, read in the working directory. Cursor only; Claude refuses |
+| `--plugins-out DIR`                | Where `--profile` is built, one folder per profile. Required with `--profile`; never the workspace |
+| `--deck-bin PATH`                  | The deck CLI. Default: the `@pinkpuma/deck` this package depends on |
 | `--id` / `--attempt` / `--context` | How a transcript is filed. Forwarded by the role                                 |
 
+### Plugins
+
+An agent starts with plugin folders, each passed to the vendor as
+`--plugin-dir`: first the `--plugin-dir` folders, in order, then what the
+project's [deck](https://github.com/tilap/pinkpuma-deck) profile resolves to.
+
+`--profile builder` runs `deck materialize -C <cwd> --profile builder --out
+<plugins-out>/builder --json` before the vendor starts. The working directory
+is the checkout the agent works on, so a role gets what the project committed
+at that commit — the base `ai-plugin.json` and `.ai/profiles/builder/`, as their
+locks pin them — never what the operator has installed. deck refuses a request
+no committed lock pins, and the wrapper then refuses before the vendor starts
+(`Run deck install in the project and commit its locks`). Every Attempt of the
+role refuses the same way until the project is fixed; `mason doctor` says so
+first.
+
+| The project has                         | The agent gets                       |
+| --------------------------------------- | ------------------------------------ |
+| `.ai/profiles/<name>/ai-plugin.json`    | the base and that profile            |
+| only a base `ai-plugin.json`            | the base, and a note on stderr       |
+| no deck file at all                     | the `--plugin-dir` folders only      |
+
+A non-empty `.ai/profiles/<name>/prompt.md` is appended to the filled prompt
+under `## Project instructions for this role`: what the project wants from that
+role, next to what Mason asks.
+
+The plugins keep their hooks: deck writes a plugin's `hooks/hooks.json` as its
+author did. `cursor-agent` ran a Claude-format one (`${CLAUDE_PLUGIN_ROOT}`,
+`PostToolUse` on edits) on a real run; a hook that runs is part of the agent's
+time and of what it reads back.
+
+deck's cache (`~/.cache/pinkpuma-deck`, or `DECK_CACHE`) has no lock, and
+`--plugins-out` holds one folder per profile: both rely on a Mason run starting
+one agent at a time, which it does.
+
+`claude.mjs` takes `--plugin-dir` but refuses `--profile`: not isolated, Claude
+also loads the operator's plugins and the project's `.claude/settings.json`, so
+a role's profile would not be all it gets.
+
 The agent CLI prints **one JSON line** — a `SerializedRun` from
-`@bluewombat/slot-kit` — with the vendor's raw streams plus three extras the
+`@bluewombat/slot-kit` — with the vendor's raw streams plus the extras the
 wrapper fills when it can:
 
 | Field    | Meaning                                                                                                                                              |
 | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `skills` | `null` = unknown (not stream-json, or unparseable). `[]` = looked, none used. Otherwise skill names in order                                         |
 | `usage`  | `null` = unknown. Otherwise token counts (`input`, `output`, `cacheRead`, `cacheWrite`) and `costUsd` (`null` when the vendor did not report a cost) |
+| `plugins` | Absent when no plugin folder was loaded. Otherwise each folder: `id`, `path`, `from` (`local` or `deck`), and `integrity` (deck's, `null` for a local one) |
 | `tools`  | `null` = unknown (not stream-json, or unparseable). Otherwise what the agent did with its tools: `calls` per tool name, `busyMs` (time with a tool running; `null` when the stream has no times, as Claude's), and the lists `web` (pages fetched, searches, URLs a shell command named), `mcp` (`server/tool`, plus `getMcpTools` when the agent only listed a server's tools), `subagents` (by description), `outside` (paths named outside the working directory, skill files excepted) |
 
 Cursor extracts skills from `stream-json` `readToolCall` paths ending in
@@ -134,8 +186,8 @@ Claude's `tool_use` blocks (`WebFetch`, `WebSearch`, `Bash`, `Task`,
 future vendor agent (`codex.mjs`, …) uses the same fields: leave them `null`
 when it cannot tell.
 
-When `--transcript-dir` is set, the transcript header repeats `skills`,
-`usage` and the tools — `tools`, `web`, `mcp`, `subagents`, `outside the
+When `--transcript-dir` is set, the transcript header lists the `plugins` and
+repeats `skills`, `usage` and the tools — `tools`, `web`, `mcp`, `subagents`, `outside the
 workspace` — each `unknown`, `(none)`, or the values. "Did it read the page I
 linked?" is answered there, without reading the stream.
 
@@ -195,14 +247,32 @@ assembly, so `assembly/fix` does not fill it at all.
 
 | Role                | Required                              | Also fills                                                 |
 | ------------------- | ------------------------------------- | ---------------------------------------------------------- |
-| `builders/producer` | `{{task}}`, `{{rules}}`               | `{{done_when}}`, `{{id}}`, `{{attempt}}`                   |
-| `builders/repair`   | `{{task}}`, `{{report}}`, `{{rules}}` | `{{refused_by}}`, `{{done_when}}`, `{{id}}`, `{{attempt}}` |
-| `assembly/fix`      | `{{task}}`, `{{report}}`, `{{rules}}` | `{{refused_by}}`, `{{id}}`, `{{attempt}}`                  |
+| `builders/producer` | `{{task}}`, `{{rules}}`               | `{{history}}`, `{{done_when}}`, `{{id}}`, `{{attempt}}`    |
+| `builders/repair`   | `{{task}}`, `{{report}}`, `{{rules}}` | `{{history}}`, `{{refused_by}}`, `{{done_when}}`, `{{id}}`, `{{attempt}}` |
+| `assembly/fix`      | `{{task}}`, `{{report}}`, `{{rules}}` | `{{history}}`, `{{refused_by}}`, `{{id}}`, `{{attempt}}`   |
 | `assembly/validate` | `{{task}}`, `{{rules}}`               | `{{id}}`, `{{attempt}}`                                    |
 
 A first-pass command that receives `--report` is `fail-blocking`: that report
 belongs to the repair command. A repair or fix command without `--report` is the same.
 
+`{{history}}` is what the Task went through before this Attempt, oldest first (the
+refusal it came with, each Attempt, each Gate's answer; see Implementer's SPECS §
+History). It is empty on a first Attempt and vanishes whole then, so a template
+that does not place it works as before.
+
+### The way out
+
+Every shipped producer prompt ends with the same exit: when what the agent was
+given is not enough to act on, it changes nothing and ends its final message with
+one line, `MASON_BLOCKED: <what is missing>`. The slot reads the last such line
+in the agent's final message, and answers `fail-blocking` with that reason, so the
+Task stops as `escalated` and a person reads it instead of another Attempt
+inventing a change. This is the same kind of signal as `assembly/validate`'s
+`MASON_VERDICT:` line, and it is not tied to any refuser. A clean exit prints
+`{ "said": "<the agent's final message, clipped>" }` on stdout, which the Task
+keeps for its History. A Project's own template should keep a paragraph that
+tells the agent about the line, or the agent has no way to use it.
+
 ### The repair prompt
 
 A pass a Gate refused is a different job from a first pass: not "do this" but
@@ -376,7 +446,7 @@ the work in front of the checks did that before the Gate ran; a workspace
 with nothing published is `fail-blocking`, because no Attempt of that Task
 can change it.
 
-It waits while checks are running, so give it a ceiling of its own. On a red
+It waits while checks are running, so give it a ceiling of its own (the Gate's `timeoutMs`, which Implementer passes to it as `--timeout-ms`). A CI that does not answer is not a refusal of the work: a Gate killed by its clock reads as one, and a refusal sends the work to a producer with nothing to fix. So a few seconds before the ceiling, with no check yet or checks still running, `ci-green` answers `fail-blocking` itself, saying what it was waiting for and for how long, and a person reads it. A check that failed still refuses at once, with its reason. On a red
 check the report carries the failing job's log, cut at the error the runner
 marked — a check name and the word "failure" tell the next Attempt nothing it
 can act on. Right after a push the checks may not be created yet, and an empty

package/agents/agent-plugins.mjs

@@ -0,0 +1,231 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, join, resolve } from "node:path";
+import { listOption, textOption } from "@bluewombat/slot-kit";
+
+// The plugin folders an agent starts with, shared by every vendor wrapper.
+//
+//   --plugin-dir DIR      a folder of the operator's own (the Mason home's
+//                         core plugins). Repeatable, loaded first, in order
+//   --profile NAME        the project's deck profile for this role: the base
+//                         and that profile, as the project's locks pin them
+//   --plugins-out DIR     where the profile is materialized, one folder per
+//                         profile. Required with --profile: never the
+//                         workspace, whose tree the Gates read
+//   --deck-bin PATH       the deck CLI. Default: the @pinkpuma/deck this
+//                         package depends on
+//
+// The profile is read from the working directory — the checkout the agent
+// works on — so a role gets what the project committed at that commit, not
+// what the operator has installed. Agents of one Mason run one at a time,
+// which is why one folder per profile is enough.
+
+const PROFILE_NAME = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
+
+/**
+ * @typedef {import("@bluewombat/slot-kit").AgentPlugin} AgentPlugin
+ * @typedef {{ ok: true, plugins: AgentPlugin[], prompt: string | undefined, notes: string[] }
+ *   | { ok: false, reason: string }} LoadedPlugins
+ */
+
+/**
+ * @param {import("@bluewombat/slot-kit").OptionValues} options
+ * @param {string} cwd
+ * @returns {LoadedPlugins}
+ */
+export function loadPlugins(options, cwd) {
+  /** @type {AgentPlugin[]} */
+  const plugins = [];
+  for (const dir of listOption(options, "pluginDir")) {
+    const path = resolve(cwd, dir);
+    if (!isDirectory(path)) {
+      return { ok: false, reason: `The --plugin-dir ${dir} is not a folder.` };
+    }
+    plugins.push({ id: pluginId(path), path, from: "local", integrity: null });
+  }
+  const profile = textOption(options, "profile");
+  if (profile === undefined) {
+    return { ok: true, plugins, prompt: undefined, notes: [] };
+  }
+  if (!PROFILE_NAME.test(profile) || profile === "current") {
+    return { ok: false, reason: `The --profile "${profile}" is not a deck profile name.` };
+  }
+  const out = textOption(options, "pluginsOut");
+  if (out === undefined) {
+    return {
+      ok: false,
+      reason: "--profile needs --plugins-out: the profile is built outside the workspace.",
+    };
+  }
+  const hasBase = existsSync(join(cwd, "ai-plugin.json"));
+  // deck's own rule: a profile is a folder of .ai/profiles that holds a request.
+  const hasProfile = existsSync(join(cwd, ".ai", "profiles", profile, "ai-plugin.json"));
+  if (!hasBase && !hasProfile) {
+    return {
+      ok: true,
+      plugins,
+      prompt: undefined,
+      notes: [`The project has no deck setup: no plugin for profile ${profile}.`],
+    };
+  }
+  const deck = deckBin(options);
+  if (!deck.ok) {
+    return deck;
+  }
+  const args = [
+    deck.path,
+    "materialize",
+    "-C",
+    cwd,
+    "--out",
+    resolve(cwd, out, profile),
+    "--json",
+    ...(hasProfile ? ["--profile", profile] : []),
+  ];
+  // No timeout: this runs inside the agent wrapper's own process group, so
+  // the slot's deadline ends deck with it.
+  const run = spawnSync(process.execPath, args, { cwd, encoding: "utf8" });
+  if (run.error !== undefined || run.status !== 0) {
+    const said = (run.stderr || run.error?.message || `exit ${run.status}`).trim();
+    return {
+      ok: false,
+      reason: `deck materialize refused profile ${profile}: ${said} Run deck install in the project and commit its locks.`,
+    };
+  }
+  const result = parseMaterialized(run.stdout);
+  if (result === undefined) {
+    return { ok: false, reason: `deck materialize answered no JSON for profile ${profile}.` };
+  }
+  for (const plugin of result.plugins) {
+    plugins.push({ ...plugin, from: "deck" });
+  }
+  return {
+    ok: true,
+    plugins,
+    prompt: profilePrompt(result.prompt),
+    notes: hasProfile ? [] : [`The project has no deck profile ${profile}: base plugins only.`],
+  };
+}
+
+/**
+ * The filled prompt, then the project's own words for this role.
+ *
+ * @param {string} prompt
+ * @param {string | undefined} profilePromptText
+ * @returns {string}
+ */
+export function withProfilePrompt(prompt, profilePromptText) {
+  if (profilePromptText === undefined) {
+    return prompt;
+  }
+  return `${prompt.trimEnd()}\n\n## Project instructions for this role\n\n${profilePromptText}\n`;
+}
+
+/**
+ * `--plugin-dir` once per plugin folder: what both Cursor and Claude read.
+ *
+ * @param {readonly AgentPlugin[]} plugins
+ * @returns {string[]}
+ */
+export function pluginDirArgs(plugins) {
+  return plugins.flatMap((plugin) => ["--plugin-dir", plugin.path]);
+}
+
+/**
+ * @param {import("@bluewombat/slot-kit").OptionValues} options
+ * @returns {{ ok: true, path: string } | { ok: false, reason: string }}
+ */
+function deckBin(options) {
+  const given = textOption(options, "deckBin");
+  if (given !== undefined) {
+    return { ok: true, path: resolve(given) };
+  }
+  try {
+    const manifest = createRequire(import.meta.url).resolve("@pinkpuma/deck/package.json");
+    return { ok: true, path: join(dirname(manifest), "bin", "deck.js") };
+  } catch {
+    return {
+      ok: false,
+      reason:
+        "@pinkpuma/deck is not installed next to @bluewombat/slots. Install it, or pass --deck-bin.",
+    };
+  }
+}
+
+/**
+ * @param {string} stdout
+ * @returns {{ prompt: string | null, plugins: { id: string, path: string, integrity: string | null }[] } | undefined}
+ */
+function parseMaterialized(stdout) {
+  let raw;
+  try {
+    raw = JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+  if (raw === null || typeof raw !== "object" || !Array.isArray(raw.plugins)) {
+    return undefined;
+  }
+  const plugins = [];
+  for (const entry of raw.plugins) {
+    if (typeof entry?.id !== "string" || typeof entry?.path !== "string") {
+      return undefined;
+    }
+    plugins.push({
+      id: entry.id,
+      path: entry.path,
+      integrity: typeof entry.integrity === "string" ? entry.integrity : null,
+    });
+  }
+  return { prompt: typeof raw.prompt === "string" ? raw.prompt : null, plugins };
+}
+
+/**
+ * @param {string | null} path
+ * @returns {string | undefined}
+ */
+function profilePrompt(path) {
+  if (path === null) {
+    return undefined;
+  }
+  try {
+    const text = readFileSync(path, "utf8").trim();
+    return text.length === 0 ? undefined : text;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The name the plugin's manifest gives, else its folder's.
+ *
+ * @param {string} dir
+ * @returns {string}
+ */
+function pluginId(dir) {
+  for (const manifest of [
+    "plugin.json",
+    ".cursor-plugin/plugin.json",
+    ".claude-plugin/plugin.json",
+  ]) {
+    try {
+      const name = JSON.parse(readFileSync(join(dir, manifest), "utf8")).name;
+      if (typeof name === "string" && name.length > 0) {
+        return name;
+      }
+    } catch {
+      // try the next manifest
+    }
+  }
+  return basename(dir);
+}
+
+/** @param {string} path */
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/agents/claude.mjs

@@ -13,6 +13,7 @@ import {
   transcriptFor,
   writeContract,
 } from "@bluewombat/slot-kit";
+import { loadPlugins, pluginDirArgs } from "./agent-plugins.mjs";
 import { extrasFromClaude } from "./claude-extras.mjs";
 
 // Claude Code as a vendor agent. The prompt is already filled: this command
@@ -28,6 +29,11 @@ import { extrasFromClaude } from "./claude-extras.mjs";
 //   --agent-arg VALUE      appended before the prompt. Repeatable
 //   --agent-home / --api-key-env   recognised, then refused. Claude is not
 //                         isolated yet; starting would keep the operator's config
+//   --plugin-dir DIR      a plugin folder, repeatable (see agent-plugins.mjs)
+//   --profile / --plugins-out / --deck-bin   recognised, then refused for the
+//                         same reason: Claude would also load the operator's
+//                         and the project's own plugins, so a role's profile
+//                         would not be what it gets
 //   --id / --attempt / --context   how a transcript is filed
 
 const NAME = "Claude Code";
@@ -57,6 +63,15 @@ if (
     "Claude Code does not isolate the operator home yet. Remove --agent-home and --api-key-env; the vendor was not started.",
   );
 }
+if (
+  textOption(options, "profile") !== undefined ||
+  textOption(options, "pluginsOut") !== undefined ||
+  textOption(options, "deckBin") !== undefined
+) {
+  refuse(
+    "Claude Code does not isolate the operator home yet, so a deck profile would not be all it loads. Remove --profile; the vendor was not started.",
+  );
+}
 
 const loaded = readAgentPrompt(options);
 if (!loaded.ok) {
@@ -64,6 +79,12 @@ if (!loaded.ok) {
 }
 const prompt = loaded.prompt;
 
+const loadedPlugins = loadPlugins(options, cwd);
+if (!loadedPlugins.ok) {
+  refuse(loadedPlugins.reason);
+}
+const plugins = loadedPlugins.plugins;
+
 const bin = textOption(options, "bin") ?? findExecutable(CLI_NAMES, INSTALL_DIRS);
 if (bin === undefined) {
   refuse(
@@ -83,6 +104,7 @@ const args = [
   // Claude's stream-json only emits tool events with --verbose (headless docs).
   ...(outputFormat === "stream-json" ? ["--verbose"] : []),
   ...(model === undefined ? [] : ["--model", model]),
+  ...pluginDirArgs(plugins),
   ...listOption(options, "agentArg"),
   prompt,
 ];
@@ -92,6 +114,7 @@ const transcript = transcriptFor(process.argv, options, {
   bin,
   args,
   prompt,
+  plugins,
 });
 const run = await runAgent({ file: bin, args, cwd });
 const extras = extrasFromClaude(run.stdout, outputFormat, cwd);
@@ -119,6 +142,7 @@ function answer(run, binPath, extras) {
         skills: extras.skills,
         usage: extras.usage,
         tools: extras.tools,
+        plugins,
       }),
     )}\n`,
   );

package/agents/cursor.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import {
   AGENT_OPTIONS,
   findExecutable,
@@ -14,6 +14,7 @@ import {
   transcriptFor,
   writeContract,
 } from "@bluewombat/slot-kit";
+import { loadPlugins, pluginDirArgs, withProfilePrompt } from "./agent-plugins.mjs";
 import { extrasFromCursor } from "./cursor-extras.mjs";
 
 // Cursor CLI as a vendor agent. The prompt is already filled: this command
@@ -29,12 +30,59 @@ import { extrasFromCursor } from "./cursor-extras.mjs";
 //   --agent-home DIR      isolate this process: HOME is DIR, not the operator's
 //   --api-key-env NAME    required with --agent-home. Read process.env[NAME];
 //                         the value is never put on the argv
+//   --pass-env NAME       with --agent-home: also hand the vendor this variable
+//                         of the operator. Repeatable. The vendor otherwise
+//                         gets a short list (KEPT_ENV), not the whole environment
+//   --deny-shell NAME     with --agent-home: also refuse this command to the
+//                         vendor (`gh`, `vercel`…). Repeatable. ssh and scp are
+//                         always refused
+//   --plugin-dir / --profile / --plugins-out / --deck-bin   plugin folders,
+//                         see agent-plugins.mjs
 //   --id / --attempt / --context   how a transcript is filed
 
 const NAME = "Cursor CLI";
 const CLI_NAMES = ["cursor-agent", "agent"];
 const INSTALL_DIRS = [join(homedir(), ".local/bin"), join(homedir(), ".cursor/bin")];
 
+/**
+ * What the vendor gets of the operator's environment, besides what this file
+ * sets itself: enough to find tools, name the locale and reach the network.
+ * Tokens, agent sockets and the rest of an interactive shell stay with the
+ * operator; a Project that needs one more names it with `--pass-env`.
+ */
+const KEPT_ENV = [
+  "PATH",
+  "TERM",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "TZ",
+  "TMPDIR",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "PNPM_HOME",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "NO_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "no_proxy",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+  "NODE_EXTRA_CA_CERTS",
+];
+
+/**
+ * Commands refused to the vendor whatever the Project says: the ones that
+ * reach for the operator's own logins through a socket or a key. A Project adds
+ * its own with `--deny-shell` (the GitHub CLI reads a keychain whatever HOME
+ * is; `security` is macOS only; each machine has its own). The vendor's
+ * permission list refuses a command even under `--force`. It is a list of
+ * names, not a sandbox: `python -c` goes round it.
+ */
+const DENIED_SHELL = ["ssh", "scp"];
+
 const cwd = process.cwd();
 
 const parsed = parseOptions(process.argv.slice(2), AGENT_OPTIONS, NAME);
@@ -47,7 +95,15 @@ const loaded = readAgentPrompt(options);
 if (!loaded.ok) {
   refuse(loaded.reason);
 }
-const prompt = loaded.prompt;
+const loadedPlugins = loadPlugins(options, cwd);
+if (!loadedPlugins.ok) {
+  refuse(loadedPlugins.reason);
+}
+for (const note of loadedPlugins.notes) {
+  process.stderr.write(`${note}\n`);
+}
+const plugins = loadedPlugins.plugins;
+const prompt = withProfilePrompt(loaded.prompt, loadedPlugins.prompt);
 
 const bin = textOption(options, "bin") ?? findExecutable(CLI_NAMES, INSTALL_DIRS);
 if (bin === undefined) {
@@ -70,6 +126,7 @@ const args = [
   "--output-format",
   outputFormat,
   ...(model === undefined ? [] : ["--model", model]),
+  ...pluginDirArgs(plugins),
   ...listOption(options, "agentArg"),
   prompt,
 ];
@@ -84,6 +141,7 @@ const transcript = transcriptFor(process.argv, options, {
   bin,
   args,
   prompt,
+  plugins,
 });
 const run = await runAgent({
   file: bin,
@@ -129,42 +187,93 @@ function cursorIsolation(options, dir) {
       reason: `The environment variable ${keyEnv} is empty. An isolated Cursor agent needs it, or the CLI tries to store credentials in the login keychain.`,
     };
   }
-  return { ok: true, env: isolatedVendorEnv(resolve(dir, home), apiKey) };
+  const passEnv = listOption(options, "passEnv");
+  const bad = passEnv.find((name) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name));
+  if (bad !== undefined) {
+    return { ok: false, reason: `--pass-env must name an environment variable, not "${bad}".` };
+  }
+  const denyShell = listOption(options, "denyShell");
+  const badCommand = denyShell.find((name) => !/^[A-Za-z0-9._+-]+$/.test(name));
+  if (badCommand !== undefined) {
+    return {
+      ok: false,
+      reason: `--deny-shell must name a command, not "${badCommand}".`,
+    };
+  }
+  const agentHome = resolve(dir, home);
+  const env = isolatedVendorEnv(agentHome, apiKey, passEnv);
+  denyShellCommands(agentHome, denyShell);
+  return { ok: true, env };
 }
 
 /**
  * @param {string} agentHome
  * @param {string} apiKey
+ * @param {readonly string[]} passEnv
  * @returns {NodeJS.ProcessEnv}
  */
-function isolatedVendorEnv(agentHome, apiKey) {
+function isolatedVendorEnv(agentHome, apiKey, passEnv) {
   mkdirSync(agentHome, { recursive: true });
   const parentHome = homedir();
   /** @type {NodeJS.ProcessEnv} */
-  const env = { ...process.env, HOME: agentHome };
-  if (process.env.PATH !== undefined) {
-    env.PATH = process.env.PATH;
+  const env = { HOME: agentHome };
+  for (const name of [...KEPT_ENV, ...passEnv]) {
+    if (process.env[name] !== undefined) {
+      env[name] = process.env[name];
+    }
   }
   env.CURSOR_API_KEY = apiKey;
   env.AGENT_CLI_CREDENTIAL_STORE = "memory";
+  // The operator's git config may name a credential helper (a keychain with
+  // their account). An empty helper first clears that list for the vendor's
+  // git, and a missing credential fails instead of prompting.
+  env.GIT_CONFIG_COUNT = "1";
+  env.GIT_CONFIG_KEY_0 = "credential.helper";
+  env.GIT_CONFIG_VALUE_0 = "";
+  env.GIT_TERMINAL_PROMPT = "0";
   const gitConfig = parentGitConfig(parentHome);
-  if (gitConfig === undefined) {
-    delete env.GIT_CONFIG_GLOBAL;
-  } else {
+  if (gitConfig !== undefined) {
     env.GIT_CONFIG_GLOBAL = gitConfig;
   }
   const npmCache = process.env.npm_config_cache;
   env.npm_config_cache =
     npmCache !== undefined && npmCache.length > 0 ? npmCache : join(parentHome, ".npm");
   const corepack = parentCorepack(parentHome);
-  if (corepack === undefined) {
-    delete env.COREPACK_HOME;
-  } else {
+  if (corepack !== undefined) {
     env.COREPACK_HOME = corepack;
   }
   return env;
 }
 
+/**
+ * Write the denials into the vendor's own config in `agentHome`, keeping what
+ * else is in it. Every pass, because the vendor can edit that file.
+ *
+ * @param {string} agentHome
+ * @param {readonly string[]} extra  commands the Project also refuses
+ */
+function denyShellCommands(agentHome, extra) {
+  const file = join(agentHome, ".cursor", "cli-config.json");
+  /** @type {Record<string, any>} */
+  let config = {};
+  try {
+    config = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    // none yet, or unreadable: start from nothing rather than refuse to run
+  }
+  const permissions = config.permissions ?? {};
+  const deny = Array.isArray(permissions.deny) ? permissions.deny : [];
+  config.permissions = {
+    ...permissions,
+    allow: Array.isArray(permissions.allow) ? permissions.allow : [],
+    deny: [...new Set([...deny, ...[...DENIED_SHELL, ...extra].map((name) => `Shell(${name})`)])],
+  };
+  mkdirSync(dirname(file), { recursive: true });
+  const next = `${file}.${process.pid}.tmp`;
+  writeFileSync(next, `${JSON.stringify(config, null, 2)}\n`);
+  renameSync(next, file);
+}
+
 /**
  * The global git file the parent already resolves. `~/.gitconfig` wins over
  * the XDG file, which is git's own order when both exist.
@@ -224,6 +333,7 @@ function answer(run, binPath, extras) {
         skills: extras.skills,
         usage: extras.usage,
         tools: extras.tools,
+        plugins,
       }),
     )}\n`,
   );

package/assembly/fix.mjs

@@ -40,6 +40,19 @@ This was asked in the first place, and still holds:
 
 {{task}}
 
+{{history}}
+
+## When you cannot act
+
+If what you were given is not enough to act on (the refusal names nothing you
+can read or run here, the request contradicts the rules of this run, or the
+cause is outside this directory), do not invent a change. Change nothing and
+end your final message with exactly one line:
+
+MASON_BLOCKED: <what is missing, in one line>
+
+A person reads that line and decides. It is a correct answer, not a failure.
+
 ## Rules of this run
 
 {{rules}}
@@ -79,6 +92,7 @@ const rendered = fillPrompt(
   template.value,
   {
     task: intention,
+    history: (take(process.argv, "--history") ?? "").trim(),
     report,
     refused_by:
       refusedBy.length > 0 ? refusedBy : "the producer of the last attempt, which did not finish",

package/builders/producer.mjs

@@ -28,6 +28,19 @@ This checkout already includes any earlier subtasks that were folded into the
 feature. Do not rewrite that work. Add or change only what this task names, and
 leave the project's own checks green on the whole tree.
 
+{{history}}
+
+## When you cannot act
+
+If what you were given is not enough to act on (the refusal names nothing you
+can read or run here, the request contradicts the rules of this run, or the
+cause is outside this directory), do not invent a change. Change nothing and
+end your final message with exactly one line:
+
+MASON_BLOCKED: <what is missing, in one line>
+
+A person reads that line and decides. It is a correct answer, not a failure.
+
 Rules of this run:
 {{rules}}
 `;
@@ -68,6 +81,7 @@ const rendered = fillPrompt(
   template.value,
   {
     task: intention,
+    history: (take(process.argv, "--history") ?? "").trim(),
     done_when: doneWhen(take(process.argv, "--definition-of-done")),
     rules: rules.value.trim(),
     id: take(process.argv, "--id") ?? "",

package/builders/repair.mjs

@@ -40,6 +40,19 @@ This was asked in the first place, and still holds:
 
 {{done_when}}
 
+{{history}}
+
+## When you cannot act
+
+If what you were given is not enough to act on (the refusal names nothing you
+can read or run here, the request contradicts the rules of this run, or the
+cause is outside this directory), do not invent a change. Change nothing and
+end your final message with exactly one line:
+
+MASON_BLOCKED: <what is missing, in one line>
+
+A person reads that line and decides. It is a correct answer, not a failure.
+
 ## Rules of this run
 
 {{rules}}
@@ -79,6 +92,7 @@ const rendered = fillPrompt(
   template.value,
   {
     task: intention,
+    history: (take(process.argv, "--history") ?? "").trim(),
     report,
     refused_by:
       refusedBy.length > 0 ? refusedBy : "the producer of the last attempt, which did not finish",

package/gates/ci-green.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
-import { emitVerdict, GATE_FLAGS, ownArgv } from "@bluewombat/slot-kit";
+import { emitVerdict, GATE_FLAGS, ownArgv, take } from "@bluewombat/slot-kit";
 
 // The work line's own checks, on the work this workspace published: GitHub
 // Actions' check runs, and the commit statuses CI outside Actions reports
@@ -20,6 +20,12 @@ import { emitVerdict, GATE_FLAGS, ownArgv } from "@bluewombat/slot-kit";
 //                        to it failed only at the first assembly of a real run
 //   --require-checks     wait for a check to appear; without it, a commit with no
 //                        check at all passes
+//
+// It also receives `--timeout-ms` from Implementer: the ceiling it will be
+// killed at. A Gate that waits on a CI it does not run must not wait to be cut
+// off: a kill reads as "refused", and a refusal sends the work to an agent that
+// has nothing to fix. Near that ceiling it says so itself, `fail-blocking`, with
+// what it was waiting for.
 
 // What the runner writes at the top of every step it runs.
 const STEP_OPEN = "##[group]Run ";
@@ -63,8 +69,10 @@ if (pull === undefined) {
   process.exit(0);
 }
 
-// Ask again until the answer settles. The ceiling is this Gate's own timeout:
-// reaching it ends the Attempt, and the next one asks from scratch.
+// Ask again until the answer settles, or until just before Implementer would
+// kill this Gate (`--timeout-ms`); without that flag, until it does.
+const startedAt = Date.now();
+const stopAt = stopTime(startedAt, take(process.argv, "--timeout-ms"));
 for (;;) {
   const checks = await readChecks(pull.sha);
   if (checks === undefined) {
@@ -77,16 +85,61 @@ for (;;) {
   }
   if (checks.total === 0 && options.requireChecks) {
     // Just after a push there is a window where the checks are not created
-    // yet, and an empty list then says nothing. Ask again; the Gate's timeout
-    // is what ends the wait on a commit no check ever picks up.
-    await sleep(options.pollMs);
+    // yet, and an empty list then says nothing. Ask again, until the wait
+    // runs out: a commit no check ever picks up is not a refusal of the work.
+    if (Date.now() >= stopAt) {
+      stopWaiting(pull, "no check has appeared");
+    }
+    await sleep(Math.min(options.pollMs, Math.max(0, stopAt - Date.now())));
     continue;
   }
   if (checks.running === 0) {
     emitVerdict("pass");
     process.exit(0);
   }
-  await sleep(options.pollMs);
+  if (Date.now() >= stopAt) {
+    stopWaiting(
+      pull,
+      `${checks.running} check${checks.running === 1 ? " was" : "s were"} still running`,
+    );
+  }
+  await sleep(Math.min(options.pollMs, Math.max(0, stopAt - Date.now())));
+}
+
+/**
+ * The moment to stop waiting: a margin before Implementer's ceiling (5 %, between
+ * 2 and 30 seconds, and at most half of it), so the verdict is out before the
+ * kill. `Infinity` when Implementer gave no ceiling.
+ *
+ * @param {number} from
+ * @param {string | undefined} raw
+ */
+function stopTime(from, raw) {
+  const ceiling = Number.parseInt(raw ?? "", 10);
+  if (!Number.isInteger(ceiling) || ceiling <= 0) {
+    return Number.POSITIVE_INFINITY;
+  }
+  const margin = Math.min(Math.max(2_000, ceiling * 0.05), 30_000, ceiling / 2);
+  return from + ceiling - margin;
+}
+
+/**
+ * The CI did not answer. That says nothing of the work, and nothing the work
+ * could change: blocking, so a person reads it instead of an agent being sent
+ * to repair what was never judged.
+ *
+ * @param {{ number: number; sha: string }} pr
+ * @param {string} what
+ * @returns {never}
+ */
+function stopWaiting(pr, what) {
+  const seconds = Math.round((Date.now() - startedAt) / 1000);
+  const lasted = seconds >= 120 ? `${Math.round(seconds / 60)} min` : `${seconds} s`;
+  emitVerdict(
+    "fail-blocking",
+    `ci-green stopped waiting after ${lasted}: ${what} on ${pr.sha.slice(0, 7)} (pull request #${pr.number}). The CI did not answer in time; this is not a refusal of the work, and no change to it can make the CI answer.`,
+  );
+  process.exit(0);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluewombat/slots",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Shipped mason slots: Planners, Builders, Gates, publishers, and refreshers a Project names in its config.",
   "keywords": [
@@ -53,6 +53,7 @@
     "test": "tsx --test $(find test -name '*.test.ts')"
   },
   "dependencies": {
-    "@bluewombat/slot-kit": "^0.6.0"
+    "@bluewombat/slot-kit": "^0.8.0",
+    "@pinkpuma/deck": "1.0.0"
   }
 }