passcontrol 1.4.0 → 1.5.1

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/LICENSE CHANGED
@@ -8,7 +8,9 @@ License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved.
8
8
  Parameters
9
9
 
10
10
  Licensor: Kristiyan Ivanov, operating under the Vertias name
11
- Licensed Work: PassControl
11
+ Licensed Work: PassControl, excluding the plugins/passcontrol/ directory,
12
+ which is licensed under the MIT License (see the
13
+ LICENSE file in that directory).
12
14
  The Licensed Work is © 2026 Kristiyan Ivanov.
13
15
  Additional Use Grant: You may make production use of the Licensed Work, provided
14
16
  that you do not offer the Licensed Work to third parties as
package/README.md CHANGED
@@ -19,7 +19,8 @@ not passport-signed. Both go through gateway controls.
19
19
 
20
20
  Built by one developer under [Vertias](https://vertias.eu). Early software, **not
21
21
  independently audited**. Start with a non-critical provider key. Source-available under
22
- [BSL 1.1](./LICENSE).
22
+ [BSL 1.1](./LICENSE), except the Claude Code plugin in
23
+ [`plugins/passcontrol/`](https://github.com/Vertias3u/PassControl/tree/main/plugins/passcontrol), which is MIT.
23
24
 
24
25
  ## Cloud
25
26
 
@@ -129,6 +130,7 @@ its scope and suitable budgets. Choose by what your client supports:
129
130
  | Your JS/TS code | `PassControl` from `passcontrol/sdk`; [SDK guide](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/passport-sdk.md) |
130
131
  | Static-key client needing Passport | `passcontrol sidecar`, then `passcontrol env <integration>` |
131
132
  | MCP client | `passcontrol mcp`; configure as below |
133
+ | Coding agent | [Claude Code](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/claude-code.md), [Codex](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/codex.md), [OpenRouter](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/openrouter.md), [Ollama](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/ollama.md) |
132
134
 
133
135
  Direct Agent Keys point the client at the PassControl gateway origin. Passport Sidecar clients
134
136
  point at loopback with a provider path (for example `http://127.0.0.1:8788/api/v1/anthropic`) and the sidecar forwards to the gateway.
@@ -161,6 +163,13 @@ API key. Treat access to that local listener as access to the configured agent.
161
163
  not a sandbox against other processes running as you. Its provider CONNECT requests are
162
164
  refused; use base URLs rather than TLS interception.
163
165
 
166
+ To see each call as it happens, run `passcontrol watch` beside the agent (`--port` for a
167
+ sidecar that is not on 8788). It is a read-only, full-screen board: one row per call the
168
+ sidecar relays, with its time, declared session and sub-agent, model, BOARDED or DENIED
169
+ (with the gateway's refusal code), and latency, under the agent's budget. It reads a feed
170
+ on the sidecar's own loopback port, held in memory and never written to disk. A call that
171
+ does not go through that sidecar is not on it, and the board cannot stop anything.
172
+
164
173
  Presets (from `cli/presets.mjs`): `generic`, `openhands`, `litellm`, `aider`, `hermes`, `cline`, `continue`, `chatbox`, `jan`, `msty`, `cherry-studio`, `open-webui`, `librechat`; service presets: `github`, `telegram`, `brave`, `notion`, `discord`; coding agent: `codex`; MCP presets: `claude-desktop`, `cursor`, `claude-code`. Compatibility still depends on the client using
165
174
  supported paths. [Hermes configuration](https://github.com/Vertias3u/PassControl/blob/main/docs/integrations/hermes.md).
166
175
 
@@ -90,13 +90,26 @@ import {
90
90
  import { isLocalGatewayOrigin, probeGatewayVersion, probeTimeoutMs } from "../cli/gateway-probe.mjs";
91
91
  import { dashboardOriginForOffset, portHolders, stackPortConflictMessage } from "../cli/local-stack.mjs";
92
92
  import { startSidecar } from "../cli/sidecar.mjs";
93
+ import { listProfiles, profilePath, readProfile, TOOL_PROFILE_PORTS, writeProfile } from "../cli/profiles.mjs";
93
94
  import {
94
95
  claudeCodeEnv,
95
96
  claudeCodeSettingsPath,
96
97
  removeClaudeCodeSettings,
98
+ removeClaudeCodeSubscription,
99
+ subscriptionEnv,
100
+ subscriptionHooks,
97
101
  writeClaudeCodeSettings,
102
+ writeClaudeCodeSubscription,
98
103
  } from "../cli/claude-code.mjs";
99
- import { statuslineText } from "../cli/statusline.mjs";
104
+ import {
105
+ notInPathText,
106
+ readStatusInput,
107
+ sidecarFromBaseUrl,
108
+ statusPanelText,
109
+ statuslineText,
110
+ statuslineWithWindow,
111
+ } from "../cli/statusline.mjs";
112
+ import { runWatch } from "../cli/watch.mjs";
100
113
  import { CODEX_PROFILE, codexProfilePath, codexProfileToml, codexStoresApiKey, removeCodexProfile, writeCodexProfile } from "../cli/codex.mjs";
101
114
  import { waitForGateway as awaitGateway } from "../cli/gateway-wait.mjs";
102
115
  import { loginCommand } from "../cli/login.mjs";
@@ -206,8 +219,10 @@ ${heading("Quick start")}
206
219
  ${cmd} login [--project] sign in through your browser and set this machine up
207
220
  ${cmd} call "hi" mint a visa and make a governed model call
208
221
  ${cmd} mcp passport identity for Claude Desktop, Cursor, Claude Code
209
- ${cmd} sidecar [--port 8788] [--allow-connect host[,host]] [--ollama-port 11435] [--no-journal]
222
+ ${cmd} sidecar [--port 8788] [--allow-connect host[,host]] [--ollama-port 11435] [--no-journal] [--no-report-calls]
210
223
  passport identity for any tool that takes an api_key
224
+ ${cmd} sidecar --profile <name> | --profiles a,b
225
+ run a coding tool's own sidecar (or several, one process)
211
226
 
212
227
  ${heading("Operate")}
213
228
  ${cmd} status [--no-network] [--json]
@@ -223,6 +238,7 @@ ${heading("Operate")}
223
238
 
224
239
  ${heading("Manage")}
225
240
  ${cmd} agent list [--json] list agents
241
+ ${cmd} profile list [--json] show the profiles: one identity per coding tool
226
242
  ${cmd} agent create <name> [--write]
227
243
  create an agent passport (--write saves it here)
228
244
  ${cmd} agent rotate <id> [--grace <seconds>]
@@ -230,6 +246,10 @@ ${heading("Manage")}
230
246
  ${cmd} agent suspend <id> suspend an agent
231
247
  ${cmd} agent resume <id> resume an agent
232
248
  ${cmd} agent revoke <id> permanently revoke an agent
249
+ ${cmd} agent delegations <id> [--json]
250
+ list the delegations its workers have used
251
+ ${cmd} agent revoke-delegation <id> <jti>|--all
252
+ permanently revoke one delegation, or all before now
233
253
  ${cmd} spend [--json] show fleet and per-agent spend
234
254
  ${cmd} audit [--limit 20] [--json]
235
255
  show operator audit history
@@ -240,8 +260,10 @@ ${heading("Manage")}
240
260
  ${cmd} sessions [--agent ID] [--limit 20] [--json]
241
261
  list Claude Code / Codex sessions (declared by the client)
242
262
  ${cmd} seal <session> --agent ID [--out FILE]
243
- ${cmd} statusline [--port 8788] one line for Claude Code's status line (configure claude-code --statusline)
244
263
  sign one session; save the seal and its receipts
264
+ ${cmd} statusline [--port 8788] one line for Claude Code's status line (configure claude-code --statusline)
265
+ ${cmd} statusline --panel [--session <id>] the longer view the Claude Code plugin's /passcontrol shows
266
+ ${cmd} watch [--port 8788] a live board of each call the sidecar relays (read-only)
245
267
  ${cmd} kill on|off toggle the tenant kill switch
246
268
  ${cmd} export [--out FILE] save a workspace configuration snapshot
247
269
  ${cmd} import <file> [--confirm IMPORT]
@@ -249,8 +271,10 @@ ${heading("Manage")}
249
271
 
250
272
  ${heading("Integrate")}
251
273
  ${cmd} env [integration] print settings without writing anything
252
- ${cmd} configure <integration> [--write] [--force]
274
+ ${cmd} configure <integration> [--write] [--force] [--dedicated]
253
275
  preview or write integration config
276
+ ${cmd} configure claude-code --subscription [--write|--remove]
277
+ a Pro/Max login: stops, calls, usage window
254
278
  integrations: ${integrationChoices()}
255
279
 
256
280
  ${heading("Trust")}
@@ -302,6 +326,8 @@ ${heading("Usage:")}
302
326
  ${cmd} agent suspend <id>
303
327
  ${cmd} agent resume <id>
304
328
  ${cmd} agent revoke <id>
329
+ ${cmd} agent delegations <id> [--json]
330
+ ${cmd} agent revoke-delegation <id> <jti>|--all
305
331
 
306
332
  ${heading("Examples")}
307
333
  ${cmd} agent create prod-summarizer --provider anthropic --scope 'claude-*'
@@ -373,6 +399,7 @@ async function printCockpit({ noNetwork = false, json = false } = {}) {
373
399
  app: { state: app },
374
400
  config: {
375
401
  source: configFile,
402
+ profile: config.profile,
376
403
  provider: config.provider,
377
404
  model: config.model,
378
405
  passport_configured: passportConfigured,
@@ -2273,9 +2300,66 @@ async function agentCommand(rest, opts) {
2273
2300
  step("passport instead, and leaves this one working everywhere it already runs.");
2274
2301
  break;
2275
2302
  }
2303
+ // An agent's signed delegations to its workers (Bet D). A delegation is made
2304
+ // offline, so the gateway knows a link only once a worker has exchanged it; the
2305
+ // listing says so, and --all is the tool that reaches the ones never seen.
2306
+ case "delegations": {
2307
+ if (!args[0]) throw new Error("Usage: passcontrol agent delegations <agent-id> [--json]");
2308
+ const rows = await api("GET", `/agents/${encodeURIComponent(args[0])}/delegations`);
2309
+ if (opts.json) {
2310
+ console.log(JSON.stringify(rows, null, 2));
2311
+ break;
2312
+ }
2313
+ step("Only delegations a worker has used appear here. A delegation is signed offline, so the");
2314
+ step("gateway learns of it at its first exchange; `revoke-delegation --all` also reaches unseen ones.");
2315
+ if (!Array.isArray(rows) || rows.length === 0) {
2316
+ step("No worker has used a delegation from this agent yet.");
2317
+ break;
2318
+ }
2319
+ // Server text reaches a terminal: keep it to printable ASCII.
2320
+ const printable = (v) => String(v ?? "").replace(/[^\x20-\x7e]/g, "?").slice(0, 64);
2321
+ const now = Date.now();
2322
+ console.table(
2323
+ rows.map((d) => ({
2324
+ jti: printable(d.jti),
2325
+ depth: d.depth,
2326
+ status: d.revoked ? "revoked" : Date.parse(d.expires_at) <= now ? "expired" : "active",
2327
+ worker: `${printable(d.worker_key).slice(0, 12)}…`,
2328
+ cap: usd(d.cap_microcents),
2329
+ models: Array.isArray(d.scope)
2330
+ ? d.scope.map((s) => `${printable(s?.provider)}:${(Array.isArray(s?.models) ? s.models : []).map(printable).join("|")}`).join(", ")
2331
+ : "",
2332
+ expires: printable(d.expires_at).slice(0, 19),
2333
+ "first used": printable(d.first_exchanged_at).slice(0, 19),
2334
+ }))
2335
+ );
2336
+ break;
2337
+ }
2338
+ case "revoke-delegation": {
2339
+ const usage = "Usage: passcontrol agent revoke-delegation <agent-id> <jti>|--all";
2340
+ const [agentId, jti] = args;
2341
+ const all = opts.all === true;
2342
+ if (!agentId || all === Boolean(jti)) throw new Error(usage);
2343
+ const result = await api(
2344
+ "POST",
2345
+ `/agents/${encodeURIComponent(agentId)}/delegations/revoke`,
2346
+ all ? { all: true } : { jti }
2347
+ );
2348
+ ok(
2349
+ all
2350
+ ? `revoked every delegation agent ${agentId} issued before now, seen or not`
2351
+ : `revoked delegation ${jti} and every delegation under it`
2352
+ );
2353
+ step("This is permanent. To let a worker go on, the agent delegates to it again.");
2354
+ if (result?.immediate === false) {
2355
+ step("Recorded, but the gateway's fast copy could not be written: a worker holding a current");
2356
+ step("visa can keep calling until that visa expires (5 minutes by default).");
2357
+ }
2358
+ break;
2359
+ }
2276
2360
  default:
2277
2361
  throw new Error(
2278
- "Usage: passcontrol agent list|create <name>|suspend <id>|resume <id>|revoke <id>|rotate <id> [--grace <seconds>]"
2362
+ "Usage: passcontrol agent list|create <name>|suspend <id>|resume <id>|revoke <id>|rotate <id> [--grace <seconds>]|delegations <id>|revoke-delegation <id> <jti>|--all"
2279
2363
  );
2280
2364
  }
2281
2365
  }
@@ -2368,6 +2452,32 @@ async function sidecarCommand(rest, opts) {
2368
2452
  // sidecar mints on demand for the lifetime of the process, so a bad
2369
2453
  // destination has to be refused at start, not at the first proxied request.
2370
2454
  const gateway = requirePassportGateway(config);
2455
+ if (opts.profiles) {
2456
+ // Several identities, one process: one listener per profile, each with its own
2457
+ // passport, visa and journal (candidate 4). One terminal, one Ctrl-C.
2458
+ const names = String(opts.profiles).split(",").map((n) => n.trim()).filter(Boolean);
2459
+ for (const name of names) {
2460
+ const values = readProfile(name);
2461
+ if (!values?.PASSPORT_ID || !values?.PASSPORT_SECRET) {
2462
+ throw new Error(`Profile ${name} has no passport. Create it with ${cliCommand(`configure ${name} --dedicated --write`)}.`);
2463
+ }
2464
+ step(`Profile ${name}:`);
2465
+ startSidecar({
2466
+ gateway,
2467
+ passportId: values.PASSPORT_ID,
2468
+ passportSecret: values.PASSPORT_SECRET,
2469
+ keyStorage: null,
2470
+ port: sidecarPort({ port: values.SIDECAR_PORT }),
2471
+ host: String(opts.host ?? process.env.SIDECAR_HOST ?? "127.0.0.1"),
2472
+ allowNonLoopback: Boolean(opts.allowNonLoopback),
2473
+ allowConnectHosts: [],
2474
+ refreshSkewSeconds: Number(opts.refreshSkewSeconds ?? process.env.REFRESH_SKEW_SECONDS ?? 30),
2475
+ noJournal: opts.journal === false || Boolean(opts.noJournal),
2476
+ reportCalls: !(opts.reportCalls === false || Boolean(opts.noReportCalls)),
2477
+ });
2478
+ }
2479
+ return;
2480
+ }
2371
2481
  const { passportId, passportSecret, keyStorage } = requirePassport(config);
2372
2482
  startSidecar({
2373
2483
  gateway,
@@ -2397,6 +2507,9 @@ async function sidecarCommand(rest, opts) {
2397
2507
  // A flag only, like --allow-non-loopback: whether this machine keeps a record
2398
2508
  // is the operator's to state, not a config file's.
2399
2509
  noJournal: opts.journal === false || Boolean(opts.noJournal),
2510
+ // Subscription mode: the calls Claude Code reports go to the agent's page. On
2511
+ // unless the flag says off, like the journal.
2512
+ reportCalls: !(opts.reportCalls === false || Boolean(opts.noReportCalls)),
2400
2513
  });
2401
2514
 
2402
2515
  if (opts.for) {
@@ -2427,8 +2540,26 @@ function sidecarPort(opts = {}) {
2427
2540
  async function statuslineCommand(opts) {
2428
2541
  try {
2429
2542
  const port = sidecarPort(opts);
2543
+ // `--panel`: the several-line view `/passcontrol` shows in Claude Code (F3).
2544
+ // Without --port, the sidecar Claude Code's own ANTHROPIC_BASE_URL names.
2545
+ if (opts.panel) {
2546
+ const route = opts.port === undefined ? sidecarFromBaseUrl(process.env.ANTHROPIC_BASE_URL) : null;
2547
+ if (route?.remote) return notInPathText(route.remote);
2548
+ // Subscription mode (cli/subscription-gate.mjs): no ANTHROPIC_BASE_URL, since
2549
+ // the calls go to Anthropic directly; `configure claude-code --subscription`
2550
+ // names the sidecar the hooks and telemetry use instead.
2551
+ const reported = !route && opts.port === undefined ? sidecarFromBaseUrl(process.env.PASSCONTROL_SIDECAR_URL) : null;
2552
+ return await statusPanelText({
2553
+ port: route?.port ?? reported?.port ?? port,
2554
+ gateway: config.gateway,
2555
+ session: typeof opts.session === "string" ? opts.session : null,
2556
+ subscription: Boolean(reported?.port),
2557
+ });
2558
+ }
2430
2559
  const cacheFile = path.join(path.dirname(globalConfigPath()), `statusline-${port}.json`);
2431
- return await statuslineText({ port, cacheFile });
2560
+ // On a Pro/Max login Claude Code adds the usage window to its input (cli/usage-window.mjs).
2561
+ const input = await readStatusInput();
2562
+ return await statuslineWithWindow({ input, port, budgetLine: () => statuslineText({ port, cacheFile }) });
2432
2563
  } catch (error) {
2433
2564
  return `PassControl · ${error instanceof Error && /--port/.test(error.message) ? "bad --port" : "unavailable"}`;
2434
2565
  }
@@ -2482,7 +2613,9 @@ function passControlMcpEntry() {
2482
2613
  }
2483
2614
 
2484
2615
  function printMcpPreset(integration, opts = {}) {
2485
- requireGlobalMcpPassport();
2616
+ // Claude Code's lines only point it at the sidecar, which holds the passport (as in
2617
+ // configureMcpClient); the MCP clients below launch `passcontrol mcp`, which needs it.
2618
+ if (integration !== "claude-code") requireGlobalMcpPassport();
2486
2619
  if (integration === "claude-code") {
2487
2620
  const { baseUrl } = sidecarBaseUrl({ ...opts, provider: "anthropic" });
2488
2621
  console.log("# Route Claude Code's model calls through the sidecar (start it first):");
@@ -2642,6 +2775,7 @@ function aiderConfig(opts = {}) {
2642
2775
  * Claude Code owns.
2643
2776
  */
2644
2777
  function configureClaudeCode(opts = {}) {
2778
+ if (opts.subscription) return configureClaudeCodeSubscription(opts);
2645
2779
  const scope = opts.global ? "user" : "project";
2646
2780
  const target = claudeCodeSettingsPath({ scope });
2647
2781
  if (opts.remove) {
@@ -2684,6 +2818,52 @@ function configureClaudeCode(opts = {}) {
2684
2818
  step(`To undo: ${cliCommand(`configure claude-code --remove${scope === "user" ? " --global" : ""}`)}`);
2685
2819
  }
2686
2820
 
2821
+ /**
2822
+ * Subscription mode (cli/claude-code.mjs): a Claude
2823
+ * Pro/Max login keeps talking to Anthropic directly. PassControl is told about each
2824
+ * call, asked before each prompt and tool, and shown the usage window. Always the
2825
+ * user settings: Claude Code ignores telemetry settings in a project's file.
2826
+ */
2827
+ function configureClaudeCodeSubscription(opts = {}) {
2828
+ const target = claudeCodeSettingsPath({ scope: "user" });
2829
+ const port = sidecarPort(opts);
2830
+ if (opts.remove) {
2831
+ const result = removeClaudeCodeSubscription({ target });
2832
+ if (result.changed) ok(`removed PassControl's subscription mode from ${target}`);
2833
+ else step(`${target} has no PassControl subscription settings; nothing to remove.`);
2834
+ return;
2835
+ }
2836
+ const preview = { env: subscriptionEnv(port), hooks: subscriptionHooks(port), statusLine: { type: "command", command: statusLineSettingsCommand(port) } };
2837
+ console.log(`Preview: ${target}\n\n${JSON.stringify(preview, null, 2)}`);
2838
+ if (!opts.write) {
2839
+ step("Dry run only. Re-run with `--write` to merge these into your Claude Code user settings (anything of yours is kept).");
2840
+ } else {
2841
+ const result = writeClaudeCodeSubscription({ target, port, statusLineCommand: statusLineSettingsCommand(port), force: Boolean(opts.force) });
2842
+ if (!result.changed) ok(`${target} already has PassControl's subscription mode`);
2843
+ else {
2844
+ if (result.backupPath) step(`backed up ${result.backupPath}`);
2845
+ ok(`wrote ${target}`);
2846
+ }
2847
+ if (result.statusLine?.existing) {
2848
+ warn(`${target} already has a status line (${result.statusLine.existing}); it was left as it is, so the usage window is not shown. To show it, have yours pipe its input to \`${statusLineSettingsCommand(port)}\`.`);
2849
+ }
2850
+ if (result.hookUrlsBlocked) {
2851
+ warn(`${target} sets allowedHttpHookUrls, which does not include http://127.0.0.1:${port}/_passcontrol/hook and its tool hook (…/_passcontrol/hook?t=600): Claude Code will not run them until you add both, for example http://127.0.0.1:${port}/_passcontrol/hook*.`);
2852
+ }
2853
+ if (result.routed) {
2854
+ warn(`${target} also routes Claude Code through the sidecar with PassControl's API key (ANTHROPIC_BASE_URL). Those sessions do not use your subscription. To use the subscription, run ${cliCommand("configure claude-code --remove --global")}.`);
2855
+ }
2856
+ }
2857
+ step(`Start the sidecar before Claude Code: ${cliCommand(port === 8788 ? "sidecar" : `sidecar --port ${port}`)}`);
2858
+ step("Your Pro/Max login stays between Claude Code and Anthropic. PassControl never sees it or sits in the path.");
2859
+ step("If the sidecar is not running, Claude Code still works: stops are not checked and calls are not shown until it is.");
2860
+ step(`Watch the calls: ${cliCommand("watch")}`);
2861
+ step(
2862
+ `The sidecar also uploads each reported call (model, session, tokens, time, API-equivalent cost; never your email or account ids) to the agent's dashboard page, marked as reported, not proxied. To keep them on this machine only: ${cliCommand("sidecar --no-report-calls")}`
2863
+ );
2864
+ step(`To undo: ${cliCommand("configure claude-code --subscription --remove")}`);
2865
+ }
2866
+
2687
2867
  /**
2688
2868
  * Codex speaks only OpenAI's Responses API, so its profile always points at the
2689
2869
  * sidecar's OpenAI route. A model is written only when one is named with
@@ -2709,6 +2889,68 @@ function printCodexPreset(opts = {}) {
2709
2889
  * Codex layers over its config when started with `--profile passcontrol`.
2710
2890
  * `--remove` deletes that file, and only when PassControl wrote it.
2711
2891
  */
2892
+ // ── One identity per coding tool (candidate 4, plans/one-identity-per-tool.md) ──
2893
+ //
2894
+ // `configure <tool> --dedicated` gives Claude Code or Codex its OWN agent: its own
2895
+ // passport, budget, scope and kill switch, served by its own sidecar port, kept in
2896
+ // a named profile (cli/profiles.mjs). Re-running reuses the profile; it never
2897
+ // creates a second agent.
2898
+ async function prepareDedicatedProfile(tool, opts) {
2899
+ const port = TOOL_PROFILE_PORTS[tool];
2900
+ opts.port = port;
2901
+ const existing = readProfile(tool);
2902
+ if (existing?.PASSPORT_ID && existing?.PASSPORT_SECRET) {
2903
+ opts.port = Number(existing.SIDECAR_PORT || port);
2904
+ step(`Using the ${tool} profile's own agent (passport …${existing.PASSPORT_ID.slice(-8)}), sidecar port ${opts.port}.`);
2905
+ return;
2906
+ }
2907
+ const label = tool === "claude-code" ? "Claude Code" : "Codex";
2908
+ const provider = tool === "claude-code" ? "anthropic" : "openai";
2909
+ const name = `${label} @ ${os.hostname().split(".")[0] || "this machine"}`;
2910
+ if (!opts.write) {
2911
+ step(`With --write: creates the agent "${name}" with its own passport, saved in the ${tool} profile, served on sidecar port ${port}.`);
2912
+ return;
2913
+ }
2914
+ requireControlApiKey(config);
2915
+ // The keypair is made here and only the public half leaves, as in `agent create`.
2916
+ // The profile is written FIRST, so a created agent never exists without its key on
2917
+ // this machine; if creating it fails, the profile is removed again.
2918
+ const priv = ed25519.utils.randomPrivateKey();
2919
+ const passportId = b64url(ed25519.getPublicKey(priv));
2920
+ writeProfile(tool, { PASSPORT_ID: passportId, PASSPORT_SECRET: b64url(priv), PASSPORT_KEY_STORAGE: "", SIDECAR_PORT: String(port) });
2921
+ let created;
2922
+ try {
2923
+ created = await api("POST", "/agents", {
2924
+ name,
2925
+ passportPubkey: passportId,
2926
+ scopes: [{ provider, models: [defaultAllowedModelForProvider(provider)] }],
2927
+ });
2928
+ } catch (error) {
2929
+ fs.rmSync(profilePath(tool), { force: true });
2930
+ throw error;
2931
+ }
2932
+ ok(`created agent ${created.id} (${created.name}); its passport is in the ${tool} profile and was not printed`);
2933
+ }
2934
+
2935
+ function dedicatedSidecarHint(tool) {
2936
+ step(`Run its own sidecar: ${cliCommand(`sidecar --profile ${tool}`)}`);
2937
+ step(`Both coding tools at once, each as its own agent: ${cliCommand("sidecar --profiles claude-code,codex")}`);
2938
+ }
2939
+
2940
+ function profileCommand(rest, opts) {
2941
+ if (rest[0] !== "list") throw new Error("Usage: passcontrol profile list");
2942
+ const rows = listProfiles().map((p) => ({ profile: p.name, passport: p.passportId ? `…${p.passportId.slice(-8)}` : "none", port: p.port || "-" }));
2943
+ if (opts.json) {
2944
+ console.log(JSON.stringify(rows, null, 2));
2945
+ return;
2946
+ }
2947
+ if (!rows.length) {
2948
+ step(`No profiles yet. Give a coding tool its own agent: ${cliCommand("configure claude-code --dedicated --write")}`);
2949
+ return;
2950
+ }
2951
+ for (const r of rows) console.log(`${r.profile.padEnd(20)} passport ${r.passport.padEnd(10)} port ${r.port}`);
2952
+ }
2953
+
2712
2954
  function configureCodex(opts = {}) {
2713
2955
  const target = codexProfilePath();
2714
2956
  if (opts.remove) {
@@ -2739,11 +2981,13 @@ function configureCodex(opts = {}) {
2739
2981
  }
2740
2982
 
2741
2983
  function configureMcpClient(integration, opts = {}) {
2742
- requireGlobalMcpPassport();
2984
+ // Claude Code's settings only point it at the sidecar, which holds the passport
2985
+ // itself; requiring one here also stopped `--remove` once the config was gone.
2743
2986
  if (integration === "claude-code") {
2744
2987
  configureClaudeCode(opts);
2745
2988
  return;
2746
2989
  }
2990
+ requireGlobalMcpPassport();
2747
2991
 
2748
2992
  const target = mcpClientConfigPath(integration);
2749
2993
  const entry = passControlMcpEntry();
@@ -2775,12 +3019,17 @@ async function configureCommand(rest, opts = {}) {
2775
3019
  `Unknown integration "${integration}". Use one of: ${integrationChoices()}.`
2776
3020
  );
2777
3021
  }
3022
+ if (opts.dedicated && (integration === "claude-code" || integration === "codex")) {
3023
+ await prepareDedicatedProfile(integration, opts);
3024
+ }
2778
3025
  if (integration === "codex") {
2779
3026
  configureCodex(opts);
3027
+ if (opts.dedicated) dedicatedSidecarHint(integration);
2780
3028
  return;
2781
3029
  }
2782
3030
  if (isMcpIntegration(integration)) {
2783
3031
  configureMcpClient(integration, opts);
3032
+ if (opts.dedicated && integration === "claude-code") dedicatedSidecarHint(integration);
2784
3033
  return;
2785
3034
  }
2786
3035
  if (!supportsWrite(integration)) {
@@ -4198,6 +4447,12 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
4198
4447
  return;
4199
4448
  }
4200
4449
 
4450
+ // Also before the update check: a full-screen board owns the terminal from its
4451
+ // first frame, and the check's cache would be the one file `watch` ever wrote.
4452
+ if (command === "watch" && !opts.help) {
4453
+ process.exit(await runWatch({ port: sidecarPort(opts) }));
4454
+ }
4455
+
4201
4456
  // Started here and awaited at the very end, so the registry lookup overlaps
4202
4457
  // the command instead of being tacked onto the exit. On anything that touches
4203
4458
  // the network — which is most of this CLI — it costs nothing measurable, and
@@ -4299,6 +4554,9 @@ async function main(argv = process.argv.slice(2), runtime = {}) {
4299
4554
  " `passcontrol login` now does the same thing with YOUR agent rather than a\n" +
4300
4555
  " shared demo one: a governed call and a signed receipt you can verify."
4301
4556
  );
4557
+ case "profile":
4558
+ profileCommand(commandRest, opts);
4559
+ break;
4302
4560
  case "sidecar":
4303
4561
  await sidecarCommand(commandRest, opts);
4304
4562
  break;
@@ -74,3 +74,40 @@ export function budgetLines(self) {
74
74
  if (lines.length === 0) lines.push("No spending or token limit is set for this agent.");
75
75
  return lines;
76
76
  }
77
+
78
+ /**
79
+ * Every limit as a [label, value] row, for the `/passcontrol` panel in Claude Code
80
+ * (`passcontrol statusline --panel`): "Today", "$0.42 of $10.00 · $9.58 left · resets in 7h".
81
+ */
82
+ export function panelRows(self) {
83
+ const b = self?.budget ?? {};
84
+ const rows = [];
85
+ if (b.period && b.period.unknown) {
86
+ rows.push(["Limit", "could not be read right now"]);
87
+ } else if (b.period) {
88
+ const reset = resetsIn(b.period.resets_in_seconds);
89
+ rows.push([
90
+ PERIOD_LABEL[b.period.kind] ?? "This period",
91
+ `${formatUsd(b.period.used_microcents)} of ${formatUsd(b.period.limit_microcents)} · ${formatUsd(b.period.remaining_microcents)} left${reset ? ` · resets in ${reset}` : ""}`,
92
+ ]);
93
+ }
94
+ if (b.cost) {
95
+ rows.push(["Lifetime", `${formatUsd(b.cost.used_microcents)} of ${formatUsd(b.cost.limit_microcents)} · ${formatUsd(b.cost.remaining_microcents)} left`]);
96
+ }
97
+ if (b.tokens) {
98
+ rows.push(["Tokens", `${formatTokens(b.tokens.used)} of ${formatTokens(b.tokens.limit)} · ${formatTokens(b.tokens.remaining)} left`]);
99
+ }
100
+ if (rows.length === 0) rows.push(["Limit", "none set"]);
101
+ return rows;
102
+ }
103
+
104
+ /** Whether a limit has nothing left, so the gateway refuses calls until it resets or is raised. */
105
+ export function limitReached(self) {
106
+ const b = self?.budget ?? {};
107
+ const spent = (left) => left !== null && left !== undefined && Number.isFinite(Number(left)) && Number(left) <= 0;
108
+ return Boolean(
109
+ (b.period && !b.period.unknown && spent(b.period.remaining_microcents)) ||
110
+ (b.cost && spent(b.cost.remaining_microcents)) ||
111
+ (b.tokens && spent(b.tokens.remaining))
112
+ );
113
+ }