passcontrol 1.7.2 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -273,8 +273,15 @@ are separate from signature verification.
273
273
  and budget checks; it is not arbitrary API translation. Embeddings never fail over.
274
274
  - The injected provider key is removed from what comes back: if an upstream echoes it in
275
275
  an error body, a JSON answer or an event stream (even split across chunks), the agent
276
- receives `[REDACTED_PROVIDER_KEY]` instead. This covers the exact key, not a key an
277
- upstream has transformed.
276
+ receives `[REDACTED_PROVIDER_KEY]` instead. For keys of 16+ characters this also covers
277
+ base64 (including inside Basic auth), hex, percent-encoded and reversed copies, and any
278
+ run of 12+ characters of the key's secret part (a key cut in halves or truncated). A key
279
+ streamed back a few characters per event is caught too: for Anthropic Messages, OpenAI
280
+ Chat Completions and OpenAI Responses streams the text is followed the way the client's
281
+ SDK joins it. Ordinary events are not delayed; an event waits only while the text ends
282
+ with the first four or more characters of the key. Not followed: Ollama's native
283
+ (newline-delimited) stream and streamed fields other than text, tool input and thinking,
284
+ which keep the byte-level check.
278
285
 
279
286
  Passport scopes are snapshots in visas; scope edits can take up to the configured visa
280
287
  TTL to replace those snapshots. Other live controls have their own cache/invalidation
@@ -357,6 +364,8 @@ the provider credential. Upstream redirects are refused, never followed.
357
364
 
358
365
  ### Receipts, statements, and identity evidence
359
366
 
367
+ Receipt versions distinguish passport calls (v1), Direct Agent Key calls (v2), delegated worker calls (v3), and gateway endings on the owner's stop (v4, with no passport or agent key); older verifiers refuse v4.
368
+
360
369
  A signed call receipt records the issuer's decision, authentication method, reported
361
370
  usage/cost, and (when read) a digest of client request bytes. It does not include the
362
371
  provider response body. Verify it with an explicitly trusted issuer:
@@ -28,6 +28,7 @@ import {
28
28
  assertConfigLoaded,
29
29
  bareGatewayOrigin,
30
30
  config,
31
+ configInjectedKeys,
31
32
  configPathLabel,
32
33
  defaultModelForProvider,
33
34
  fail,
@@ -71,6 +72,7 @@ import {
71
72
  SERVICE_ENV,
72
73
  supportsWrite,
73
74
  } from "../cli/presets.mjs";
75
+ import { plantTripwires, removeTripwires, tripwirePlacementChoices } from "../cli/tripwires.mjs";
74
76
  import { importCompletionMessage, noAgentCreateMessage } from "../cli/workspace-import-report.mjs";
75
77
  import { announcesAfter, checkForUpdate, fetchLatest, REGISTRY_URL } from "../cli/update-check.mjs";
76
78
  import {
@@ -123,6 +125,9 @@ import {
123
125
  } from "../cli/codex-hooks.mjs";
124
126
  import { waitForGateway as awaitGateway } from "../cli/gateway-wait.mjs";
125
127
  import { loginCommand } from "../cli/login.mjs";
128
+ import { commandLabel, heldWriteKey, obtainWriteKey, releaseWriteKey } from "../cli/write-approval.mjs";
129
+ import { loweredKeysFile, lowerStoredKeyOnce } from "../cli/lowered-keys.mjs";
130
+ import { isSidecarKey, sidecarKey } from "../cli/sidecar-token.mjs";
126
131
  import { logoutCommand } from "../cli/logout.mjs";
127
132
  import { proveItWorks } from "../cli/selftest.mjs";
128
133
  import {
@@ -131,8 +136,9 @@ import {
131
136
  instanceKidFromSeed,
132
137
  retiredKeyEntry,
133
138
  } from "../cli/instance-key.mjs";
134
- import { FAILURE_REASONS, verifyAgentToken, verifyReceipt, verifySession, verifyStatement } from "../cli/verify.mjs";
139
+ import { describeGatewayEnding, FAILURE_REASONS, verifyAgentToken, verifyReceipt, verifySession, verifyStatement } from "../cli/verify.mjs";
135
140
  import { compareProtocolSets } from "../cli/protocols.mjs";
141
+ import { memoryReviewCommand } from "../cli/memory-review.mjs";
136
142
  import { defaultAllowedModelForProvider } from "../cli/integration-defaults.mjs";
137
143
  import {
138
144
  PASSPORT_KEY_STORAGE_OS,
@@ -274,6 +280,8 @@ ${heading("Manage")}
274
280
  ${cmd} statusline [--port 8788] one line for Claude Code's status line (configure claude-code --statusline)
275
281
  ${cmd} statusline --panel [--session <id>] the longer view the Claude Code plugin's /passcontrol shows
276
282
  ${cmd} watch [--port 8788] a live board of each call the sidecar relays (read-only)
283
+ ${cmd} memory review [--port 8788] [--codex]
284
+ show the memory entries waiting at customs, with their text from this machine
277
285
  ${cmd} kill on|off toggle the tenant kill switch
278
286
  ${cmd} export [--out FILE] save a workspace configuration snapshot
279
287
  ${cmd} import <file> [--confirm IMPORT]
@@ -291,6 +299,8 @@ ${heading("Integrate")}
291
299
  a ChatGPT plan in Codex: stops and tool rules
292
300
  ${cmd} configure claude-code --write --agent-note
293
301
  tell the agent its own limits, only when they change
302
+ ${cmd} configure tripwires --agent <id> [--places ${tripwirePlacementChoices()}] [--dry-run] [--remove]
303
+ plant decoy keys for one agent outside any repo (rerun rotates)
294
304
  integrations: ${integrationChoices()}
295
305
 
296
306
  ${heading("Trust")}
@@ -2131,13 +2141,31 @@ async function callCommand(rest, opts) {
2131
2141
  ok("done - check the dashboard audit log + spend for this call.");
2132
2142
  }
2133
2143
 
2144
+ /** What api() needs to know about the command running (review C-01). */
2145
+ const writeContext = { command: "a command", storedKeyChecked: false };
2146
+
2134
2147
  async function api(method, pathPart, body, { timeoutMs } = {}) {
2135
2148
  // Destination first, key second — same order and same reason as the SDK's
2136
2149
  // ControlClient. `config.gateway` is whatever PASSCONTROL_GATEWAY said, and
2137
2150
  // this is the one place a long-lived fleet-wide `pc_` key goes on the wire, so
2138
2151
  // the URL is built from the validated origin rather than from that string.
2139
2152
  const origin = requireControlGateway(config);
2140
- const apiKey = requireControlApiKey(config);
2153
+ const storedKey = requireControlApiKey(config);
2154
+ // Review C-01: the stored key is read-only since login lowers it. A change asks for a
2155
+ // one-command key approved in the browser (cli/write-approval.mjs), and keeps using
2156
+ // it for the rest of this command.
2157
+ const held = heldWriteKey(origin);
2158
+ // A key saved by an older login still has write scope: lowered before its first use
2159
+ // (owner 2026-11-15). Only a key that came from a config file, never one from the shell.
2160
+ if (!held && !writeContext.storedKeyChecked && configInjectedKeys.has("PASSCONTROL_API_KEY")) {
2161
+ writeContext.storedKeyChecked = true;
2162
+ const lowered = await lowerStoredKeyOnce({ origin, key: storedKey, stateFile: loweredKeysFile(globalConfigPath()) });
2163
+ if (lowered.lowered) {
2164
+ warn("This machine's saved control key could change things, so it is read-only now (an agent can read that file).");
2165
+ step("A command that changes something asks you to approve it in the browser.");
2166
+ }
2167
+ }
2168
+ const apiKey = held ?? storedKey;
2141
2169
  // Unbounded by default, deliberately: a fleet mutation must not be abandoned
2142
2170
  // halfway because a caller guessed a duration. `timeoutMs` is opt-in, for the
2143
2171
  // one kind of caller that is a REPORT — where a gateway that never answers is
@@ -2166,6 +2194,10 @@ async function api(method, pathPart, body, { timeoutMs } = {}) {
2166
2194
  } catch {
2167
2195
  json = { error: { message: text || "non-JSON response" } };
2168
2196
  }
2197
+ if (!res.ok && res.status === 403 && json.error?.code === "insufficient_scope" && !held) {
2198
+ await obtainWriteKey(origin, { command: writeContext.command, openUrl });
2199
+ return api(method, pathPart, body, { timeoutMs });
2200
+ }
2169
2201
  if (!res.ok) {
2170
2202
  const e = json.error ?? {};
2171
2203
  throw new Error(`${res.status} ${e.code ?? ""} ${e.message ?? ""} (req ${e.request_id ?? "?"})`);
@@ -2565,8 +2597,10 @@ async function statuslineCommand(opts) {
2565
2597
  // the calls go to Anthropic directly; `configure claude-code --subscription`
2566
2598
  // names the sidecar the hooks and telemetry use instead.
2567
2599
  const reported = !route && opts.port === undefined ? sidecarFromBaseUrl(process.env.PASSCONTROL_SIDECAR_URL) : null;
2600
+ const panelPort = route?.port ?? reported?.port ?? port;
2568
2601
  return await statusPanelText({
2569
- port: route?.port ?? reported?.port ?? port,
2602
+ port: panelPort,
2603
+ sidecarKey: sidecarKeyForPort(panelPort),
2570
2604
  gateway: config.gateway,
2571
2605
  session: typeof opts.session === "string" ? opts.session : null,
2572
2606
  subscription: Boolean(reported?.port),
@@ -2575,7 +2609,8 @@ async function statuslineCommand(opts) {
2575
2609
  const cacheFile = path.join(path.dirname(globalConfigPath()), `statusline-${port}.json`);
2576
2610
  // On a Pro/Max login Claude Code adds the usage window to its input (cli/usage-window.mjs).
2577
2611
  const input = await readStatusInput();
2578
- return await statuslineWithWindow({ input, port, budgetLine: () => statuslineText({ port, cacheFile }) });
2612
+ const statusKey = sidecarKeyForPort(port);
2613
+ return await statuslineWithWindow({ input, port, sidecarKey: statusKey, budgetLine: () => statuslineText({ port, cacheFile, sidecarKey: statusKey }) });
2579
2614
  } catch (error) {
2580
2615
  return `PassControl · ${error instanceof Error && /--port/.test(error.message) ? "bad --port" : "unavailable"}`;
2581
2616
  }
@@ -2588,6 +2623,35 @@ function statusLineSettingsCommand(port) {
2588
2623
  return `node ${JSON.stringify(CLI_ENTRY)} ${args}`;
2589
2624
  }
2590
2625
 
2626
+ /** Shown where the sidecar's key would be when this machine has no passport yet. */
2627
+ const NO_SIDECAR_KEY = "run-passcontrol-login-first";
2628
+
2629
+ /**
2630
+ * The key the sidecar on `port` asks its callers for (review C-03, cli/sidecar-token.mjs):
2631
+ * derived from the passport that sidecar runs with. A dedicated tool profile that serves
2632
+ * this port has its own passport (cli/profiles.mjs); otherwise it is this config's.
2633
+ */
2634
+ function sidecarKeyForPort(port) {
2635
+ for (const profile of listProfiles()) {
2636
+ if (!profile.port || Number(profile.port) !== Number(port)) continue;
2637
+ const secret = readProfile(profile.name)?.PASSPORT_SECRET;
2638
+ if (secret) return sidecarKey(secret);
2639
+ }
2640
+ return sidecarKey(config.passportSecret);
2641
+ }
2642
+
2643
+ /** A preview prints the key's first characters only: it lands in terminals and logs. */
2644
+ function maskSidecarKey(text, key) {
2645
+ return isSidecarKey(key) ? String(text).split(key).join(`${key.slice(0, 8)}…`) : String(text);
2646
+ }
2647
+
2648
+ function sidecarApiKey(port) {
2649
+ const key = sidecarKeyForPort(port);
2650
+ if (key) return key;
2651
+ warn("No passport on this machine yet, so there is no sidecar key to print. Run `passcontrol login`, then this again.");
2652
+ return NO_SIDECAR_KEY;
2653
+ }
2654
+
2591
2655
  function sidecarBaseUrl(opts = {}) {
2592
2656
  const provider = String(opts.provider || config.provider);
2593
2657
  assertProvider(provider);
@@ -2596,7 +2660,11 @@ function sidecarBaseUrl(opts = {}) {
2596
2660
  return {
2597
2661
  provider,
2598
2662
  model: activeModel(provider, opts),
2599
- apiKey: "passcontrol",
2663
+ // Review C-03: the sidecar's own key, not a placeholder. It opens the sidecar on
2664
+ // this machine and nothing else; the sidecar strips it before forwarding.
2665
+ get apiKey() {
2666
+ return sidecarApiKey(port);
2667
+ },
2600
2668
  baseUrl: `http://${host}:${port}/api/v1/${provider}`,
2601
2669
  port,
2602
2670
  };
@@ -2633,9 +2701,9 @@ function printMcpPreset(integration, opts = {}) {
2633
2701
  // configureMcpClient); the MCP clients below launch `passcontrol mcp`, which needs it.
2634
2702
  if (integration !== "claude-code") requireGlobalMcpPassport();
2635
2703
  if (integration === "claude-code") {
2636
- const { baseUrl } = sidecarBaseUrl({ ...opts, provider: "anthropic" });
2704
+ const { baseUrl, apiKey } = sidecarBaseUrl({ ...opts, provider: "anthropic" });
2637
2705
  console.log("# Route Claude Code's model calls through the sidecar (start it first):");
2638
- printExports(Object.entries(claudeCodeEnv(baseUrl)));
2706
+ printExports(Object.entries(claudeCodeEnv(baseUrl, apiKey)));
2639
2707
  console.log("# Optional: also add PassControl's chat tool to Claude Code:");
2640
2708
  console.log(`# ${CLAUDE_CODE_ADD_COMMAND}`);
2641
2709
  return;
@@ -2697,8 +2765,8 @@ function printAgentPreset(name = "generic", opts = {}) {
2697
2765
  console.log(`# Start the bridge first: ${sidecarStart}`);
2698
2766
 
2699
2767
  // Desktop / GUI clients: there is nothing to export, you type these into a
2700
- // settings form. The API-key field is required by the UI but ignored by the
2701
- // sidecar — that is the point. It is where your real provider key used to go.
2768
+ // settings form. The API-key field takes the sidecar's own key (review C-03),
2769
+ // where your real provider key used to go. It opens the sidecar, nothing else.
2702
2770
  if (isGuiPreset(preset)) {
2703
2771
  console.log(`# ${GUI_PRESET_LABELS[preset]} settings:`);
2704
2772
  console.log(`Base URL: ${baseUrl}`);
@@ -2716,7 +2784,7 @@ function printAgentPreset(name = "generic", opts = {}) {
2716
2784
  console.log(" provider: custom");
2717
2785
  console.log(` base_url: ${JSON.stringify(`${baseUrl}/v1`)}`);
2718
2786
  console.log(` api_key: ${JSON.stringify(apiKey)}`);
2719
- console.log("# The placeholder key is stripped by the sidecar. Keep `passcontrol sidecar` running.");
2787
+ console.log("# That key only opens the sidecar on this machine; it is not a provider key. Keep `passcontrol sidecar` running.");
2720
2788
  break;
2721
2789
  case "openhands":
2722
2790
  console.log("# OpenHands / LiteLLM-compatible starting point:");
@@ -2757,7 +2825,8 @@ function printAgentPreset(name = "generic", opts = {}) {
2757
2825
 
2758
2826
  // A service preset has no provider and no model: the client is pointed at the
2759
2827
  // governed service route and sends no service token at all — the gateway
2760
- // injects the workspace's, and only for calls the agent's rules admit.
2828
+ // injects the workspace's, and only for calls the agent's rules admit. It does
2829
+ // send the sidecar's own key (review C-03), which opens the sidecar and nothing else.
2761
2830
  function printServicePreset(service, opts = {}) {
2762
2831
  const host = String(opts.host ?? process.env.SIDECAR_HOST ?? "127.0.0.1");
2763
2832
  const port = sidecarPort(opts);
@@ -2768,7 +2837,10 @@ function printServicePreset(service, opts = {}) {
2768
2837
  const entry = Object.hasOwn(SERVICE_ENV, service) ? SERVICE_ENV[service] : null;
2769
2838
  if (!entry) throw new Error(`Usage: passcontrol env <${integrationChoices()}>`);
2770
2839
  for (const line of entry.about) console.log(line);
2771
- printExports([[entry.envVar, `http://${host}:${port}/api/v1/svc/${service}`]]);
2840
+ printExports([
2841
+ [entry.envVar, `http://${host}:${port}/api/v1/svc/${service}`],
2842
+ ["PASSCONTROL_SIDECAR_KEY", sidecarApiKey(port)],
2843
+ ]);
2772
2844
  console.log(entry.usage);
2773
2845
  }
2774
2846
 
@@ -2801,16 +2873,19 @@ function configureClaudeCode(opts = {}) {
2801
2873
  return;
2802
2874
  }
2803
2875
  const { baseUrl, port } = sidecarBaseUrl({ ...opts, provider: "anthropic" });
2876
+ const sidecarKeyValue = sidecarApiKey(port);
2804
2877
  const note = Boolean(opts.agentNote);
2805
- const preview = { env: claudeCodeEnv(baseUrl), hooks: apiToolHooks(port) };
2806
- if (note) preview.hooks = { ...preview.hooks, UserPromptSubmit: [{ hooks: [{ type: "http", url: `http://127.0.0.1:${port}/_passcontrol/hook?note=only`, timeout: 5 }] }] };
2807
- console.log(`Preview: ${target}\n\n${JSON.stringify(preview, null, 2)}`);
2878
+ // The preview prints the key's first characters only: it lands in terminals and logs.
2879
+ const preview = { env: claudeCodeEnv(baseUrl, sidecarKeyValue), hooks: apiToolHooks(port, sidecarKeyValue) };
2880
+ if (note) preview.hooks = { ...preview.hooks, UserPromptSubmit: [{ hooks: [{ type: "http", url: `http://127.0.0.1:${port}/_passcontrol/hook?note=only`, ...(isSidecarKey(sidecarKeyValue) ? { headers: { Authorization: `Bearer ${sidecarKeyValue}` } } : {}), timeout: 5 }] }] };
2881
+ console.log(`Preview: ${target}\n\n${maskSidecarKey(JSON.stringify(preview, null, 2), sidecarKeyValue)}`);
2808
2882
  if (!opts.write) {
2809
2883
  step(`Dry run only. Re-run with \`--write\` to merge these env keys and the tool hook${scope === "project" ? " (or --write --global for every session)" : ""}.`);
2810
2884
  } else {
2811
2885
  const result = writeClaudeCodeSettings({
2812
2886
  target,
2813
2887
  baseUrl,
2888
+ sidecarKey: sidecarKeyValue,
2814
2889
  force: Boolean(opts.force),
2815
2890
  statusLineCommand: opts.statusline ? statusLineSettingsCommand(port) : null,
2816
2891
  noteHookPort: note ? port : null,
@@ -2861,12 +2936,14 @@ function configureClaudeCodeSubscription(opts = {}) {
2861
2936
  return;
2862
2937
  }
2863
2938
  const note = Boolean(opts.agentNote);
2864
- const preview = { env: subscriptionEnv(port), hooks: subscriptionHooks(port, { note }), statusLine: { type: "command", command: statusLineSettingsCommand(port) } };
2865
- console.log(`Preview: ${target}\n\n${JSON.stringify(preview, null, 2)}`);
2939
+ // Review C-03 follow-up: the hooks and the logs export carry the sidecar's key.
2940
+ const subscriptionKey = opts.write ? sidecarApiKey(port) : sidecarKeyForPort(port);
2941
+ const preview = { env: subscriptionEnv(port, subscriptionKey), hooks: subscriptionHooks(port, { note, key: subscriptionKey }), statusLine: { type: "command", command: statusLineSettingsCommand(port) } };
2942
+ console.log(`Preview: ${target}\n\n${maskSidecarKey(JSON.stringify(preview, null, 2), subscriptionKey)}`);
2866
2943
  if (!opts.write) {
2867
2944
  step("Dry run only. Re-run with `--write` to merge these into your Claude Code user settings (anything of yours is kept).");
2868
2945
  } else {
2869
- const result = writeClaudeCodeSubscription({ target, port, statusLineCommand: statusLineSettingsCommand(port), force: Boolean(opts.force), note });
2946
+ const result = writeClaudeCodeSubscription({ target, port, sidecarKey: subscriptionKey, statusLineCommand: statusLineSettingsCommand(port), force: Boolean(opts.force), note });
2870
2947
  if (!result.changed) ok(`${target} already has PassControl's subscription mode`);
2871
2948
  else {
2872
2949
  if (result.backupPath) step(`backed up ${result.backupPath}`);
@@ -2908,13 +2985,13 @@ function codexSettings(opts = {}) {
2908
2985
  }
2909
2986
  const { baseUrl, port } = sidecarBaseUrl({ ...opts, provider: "openai" });
2910
2987
  const model = typeof opts.model === "string" && opts.model ? opts.model : undefined;
2911
- return { baseUrl, port, model };
2988
+ return { baseUrl, port, model, sidecarKey: sidecarApiKey(port) };
2912
2989
  }
2913
2990
 
2914
2991
  function printCodexPreset(opts = {}) {
2915
- const { baseUrl, model } = codexSettings(opts);
2992
+ const { baseUrl, model, sidecarKey: key } = codexSettings(opts);
2916
2993
  console.log(`# Save as ${codexProfilePath()} (or run: ${cliCommand("configure codex --write")}):`);
2917
- console.log(codexProfileToml({ baseUrl, model }).trimEnd());
2994
+ console.log(codexProfileToml({ baseUrl, model, sidecarKey: key }).trimEnd());
2918
2995
  }
2919
2996
 
2920
2997
  /**
@@ -3037,12 +3114,13 @@ function configureCodex(opts = {}) {
3037
3114
  else step(`${target} is not a profile PassControl wrote; nothing to remove.`);
3038
3115
  return;
3039
3116
  }
3040
- const { baseUrl, port, model } = codexSettings(opts);
3041
- console.log(`Preview: ${target}\n\n${codexProfileToml({ baseUrl, model })}`);
3117
+ const { baseUrl, port, model, sidecarKey: key } = codexSettings(opts);
3118
+ // The preview shows the key's first characters only: it lands in terminals and logs.
3119
+ console.log(`Preview: ${target}\n\n${codexProfileToml({ baseUrl, model, sidecarKey: `${key.slice(0, 8)}…` })}`);
3042
3120
  if (!opts.write) {
3043
3121
  step("Dry run only. Re-run with `--write` to create this profile. Codex's config.toml is not touched.");
3044
3122
  } else {
3045
- const result = writeCodexProfile({ target, baseUrl, model, force: Boolean(opts.force) });
3123
+ const result = writeCodexProfile({ target, baseUrl, model, sidecarKey: key, force: Boolean(opts.force) });
3046
3124
  if (!result.changed) ok(`${target} already routes Codex through PassControl`);
3047
3125
  else {
3048
3126
  if (result.backupPath) step(`backed up ${result.backupPath}`);
@@ -3085,8 +3163,46 @@ function configureMcpClient(integration, opts = {}) {
3085
3163
  ok(`wrote ${target}`);
3086
3164
  }
3087
3165
 
3166
+ // ── Tripwire decoys (idea 12) ───────────────────────────────────────────────
3167
+ //
3168
+ // `configure tripwires` plants decoy Direct Agent Keys for ONE agent outside any repo,
3169
+ // registers only their digests with the gateway, and keeps a digest manifest the sidecar
3170
+ // reads. Re-running rotates; --remove retires them and deletes the files this wrote. The
3171
+ // placements and their order come from cli/tripwires.mjs, never typed here.
3172
+ async function tripwiresCommand(opts = {}) {
3173
+ const agentId = typeof opts.agent === "string" ? opts.agent : "";
3174
+ if (!/^[0-9a-f-]{36}$/i.test(agentId)) {
3175
+ throw new Error(`Usage: passcontrol configure tripwires --agent <agent-id> [--places ${tripwirePlacementChoices()}] [--dry-run] [--remove]`);
3176
+ }
3177
+ if (opts.remove) {
3178
+ const r = await removeTripwires({ agentId, retire: () => api("DELETE", `/agents/${agentId}/tripwires`) });
3179
+ ok(`retired this agent's decoys at the gateway (they stay armed 30 days in case a copy is still out there)`);
3180
+ for (const file of r.removed) step(`removed ${file}`);
3181
+ for (const file of r.kept) warn(`kept ${file}: it no longer holds the decoy this tool wrote`);
3182
+ return;
3183
+ }
3184
+ const origin = requireControlGateway(config);
3185
+ const placements = typeof opts.places === "string" ? opts.places.split(",").map((p) => p.trim()).filter(Boolean) : undefined;
3186
+ const r = await plantTripwires({
3187
+ agentId,
3188
+ origin,
3189
+ placements,
3190
+ dryRun: Boolean(opts.dryRun),
3191
+ register: (decoys, replace, retireDigests) =>
3192
+ api("POST", `/agents/${agentId}/tripwires`, replace ? { decoys, replace, retire_digests: retireDigests } : { decoys, replace }),
3193
+ });
3194
+ for (const p of r.planted) step(`${r.dryRun ? "would plant" : "planted"} ${p.placement}: ${p.path}`);
3195
+ if (r.dryRun) return;
3196
+ ok(r.rotated ? "rotated this agent's tripwire decoys" : "planted tripwire decoys for this agent");
3197
+ // Plain about what this is and is not (research/idea-12-tripwire/VERDICT.md).
3198
+ step("A decoy presented to PassControl suspends the agent it names at once. A decoy seen in an agent's");
3199
+ step("traffic is an alert. Silence proves nothing: an agent can avoid, encode or exfiltrate a decoy unobserved.");
3200
+ step("Your own scanners may flag these files; that is expected. Do not copy them into a repository.");
3201
+ }
3202
+
3088
3203
  async function configureCommand(rest, opts = {}) {
3089
3204
  const integration = String(rest[0] ?? "").toLowerCase();
3205
+ if (integration === "tripwires") return tripwiresCommand(opts);
3090
3206
  if (!integration) {
3091
3207
  throw new Error(
3092
3208
  `Usage: passcontrol configure <${integrationChoices()}> [--write] [--force]`
@@ -3469,7 +3585,11 @@ async function verifyCommand(rest, opts) {
3469
3585
  step("would need every receipt in the window.");
3470
3586
  return;
3471
3587
  }
3472
- step(`Passport: ${c.sub}`);
3588
+ if (what === "receipt" && c.auth?.kind === "gateway_ending") {
3589
+ step(describeGatewayEnding(c.end));
3590
+ } else {
3591
+ step(`Passport: ${c.sub}`);
3592
+ }
3473
3593
  if (what === "token") {
3474
3594
  step(`Audience: ${c.aud}`);
3475
3595
  step(`Expires: ${new Date(c.exp * 1000).toISOString()}`);
@@ -4513,6 +4633,9 @@ async function settingsCommand() {
4513
4633
  } catch (error) {
4514
4634
  if (!chosen.returnToMenu) throw error;
4515
4635
  fail(error.message);
4636
+ } finally {
4637
+ // One approval covers one command, not the rest of the menu session (review C-01).
4638
+ await releaseWriteKey();
4516
4639
  }
4517
4640
  recentIds = updateRecents(recentIds, chosen);
4518
4641
  if (!chosen.returnToMenu || !(await pauseForSettings())) return;
@@ -4522,6 +4645,7 @@ async function settingsCommand() {
4522
4645
  async function main(argv = process.argv.slice(2), runtime = {}) {
4523
4646
  const { opts, rest } = parseArgv(argv);
4524
4647
  const [command, ...commandRest] = rest;
4648
+ writeContext.command = commandLabel(rest);
4525
4649
 
4526
4650
  // First, before the update check or anything else that could print or wait:
4527
4651
  // Claude Code shows this command's whole stdout as its status line, runs it
@@ -4539,7 +4663,7 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
4539
4663
  try {
4540
4664
  for await (const chunk of process.stdin) input += chunk;
4541
4665
  const port = sidecarPort(opts);
4542
- const out = await runCodexHook({ input, port });
4666
+ const out = await runCodexHook({ input, port, sidecarKey: sidecarKeyForPort(port) });
4543
4667
  if (out) process.stdout.write(`${out}\n`);
4544
4668
  } catch {
4545
4669
  // Nothing: a hook that cannot run lets Codex go ahead, as a failed hook would.
@@ -4550,7 +4674,7 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
4550
4674
  // Also before the update check: a full-screen board owns the terminal from its
4551
4675
  // first frame, and the check's cache would be the one file `watch` ever wrote.
4552
4676
  if (command === "watch" && !opts.help) {
4553
- process.exit(await runWatch({ port: sidecarPort(opts) }));
4677
+ process.exit(await runWatch({ port: sidecarPort(opts), sidecarKey: sidecarKeyForPort(sidecarPort(opts)) }));
4554
4678
  }
4555
4679
 
4556
4680
  // Started here and awaited at the very end, so the registry lookup overlaps
@@ -4691,6 +4815,13 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
4691
4815
  case "seal":
4692
4816
  await sealCommand(commandRest, opts);
4693
4817
  break;
4818
+ case "memory": {
4819
+ // Idea 13. Shows only; the decision is the owner's, on the agent's page.
4820
+ if (commandRest[0] !== "review") throw new Error("Usage: passcontrol memory review [--port 8788] [--codex]");
4821
+ const port = Number(opts.port ?? process.env.SIDECAR_PORT ?? 8788);
4822
+ await memoryReviewCommand({ sidecarUrl: process.env.PASSCONTROL_SIDECAR_URL || `http://127.0.0.1:${port}`, sidecarKey: sidecarKeyForPort(port), client: opts.codex ? "codex" : "claude-code" });
4823
+ break;
4824
+ }
4694
4825
  case "kill":
4695
4826
  await killCommand(commandRest);
4696
4827
  break;
@@ -4722,7 +4853,17 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
4722
4853
  await announceUpdate();
4723
4854
  }
4724
4855
 
4725
- main().catch((error) => {
4856
+ /**
4857
+ * After every command, whatever its outcome (review C-01): give back a one-command
4858
+ * write key if one was approved, and say so once if the key stored in a config file
4859
+ * turned out to have write scope (a login from before this release).
4860
+ */
4861
+ async function afterCommand() {
4862
+ await releaseWriteKey();
4863
+ }
4864
+
4865
+ main().then(afterCommand, async (error) => {
4866
+ await afterCommand().catch(() => undefined);
4726
4867
  fail(error.message);
4727
4868
  process.exit(1);
4728
4869
  });