agent-shim 7.11.0 → 7.12.0

package/README.md

@@ -82,47 +82,47 @@ The full mechanics, including the credential block, the merge algorithm, conditi
 ```
 agent-shim <noun> <verb> [name] [options]      # nouns: identity, profile, pool, provider, rule
 
-agent-shim identity add <name>
+agent-shim identity add <name> [--json]
 agent-shim identity list [--json]
 agent-shim identity show <name> [--json]
-agent-shim identity set <name> [--default-profile <profile> | --no-default-profile] [--[no-]allow-ambient-credential]
-agent-shim identity set <name> [--credential <source>]... [--credential-target <bearer|apiKey|oauthToken>] [--no-credential]
-agent-shim identity remove <name> [--yes]
-agent-shim identity use <name>
+agent-shim identity set <name> [--default-profile <profile> | --no-default-profile] [--[no-]allow-ambient-credential] [--json]
+agent-shim identity set <name> [--credential <source>]... [--credential-target <bearer|apiKey|oauthToken>] [--no-credential] [--json]
+agent-shim identity remove <name> [--yes] [--json]
+agent-shim identity use <name> [--json]
 agent-shim @<name>                          # shorthand for `identity use <name>`
 agent-shim identity resolve-conflicts <name>  # interactively resolve a retained superseded farm's conflicts
 
-agent-shim profile add [name] [--extends <profile>]... [--description <text>]   # interactive with no options on a terminal
-agent-shim profile set <name> [--category <category>=<bool>]... [--entry <category>/<path>=<bool>]...
-agent-shim profile set <name> [--extends <profile>]... [--no-extends] [--description <text> | --no-description]
-agent-shim profile set <name> [--[no-]launch-skip-permissions] [--[no-]launch-remote-control] [--[no-]launch-headroom] [--[no-]launch-track-usage]
-agent-shim profile set <name> [--launch-provider <provider> | --no-launch-provider]
+agent-shim profile add [name] [--extends <profile>]... [--description <text>]   # interactive with no options on a terminal [--json]
+agent-shim profile set <name> [--category <category>=<bool>]... [--entry <category>/<path>=<bool>]... [--json]
+agent-shim profile set <name> [--extends <profile>]... [--no-extends] [--description <text> | --no-description] [--json]
+agent-shim profile set <name> [--[no-]launch-skip-permissions] [--[no-]launch-remote-control] [--[no-]launch-headroom] [--[no-]launch-track-usage] [--json]
+agent-shim profile set <name> [--launch-provider <provider> | --no-launch-provider] [--json]
 agent-shim profile list [--json]
 agent-shim profile show <name> [--json]
-agent-shim profile remove <name> [--yes]
-agent-shim profile use <name>               # the global default configuration profile
+agent-shim profile remove <name> [--yes] [--json]
+agent-shim profile use <name>               # the global default configuration profile [--json]
 
-agent-shim pool add <name> --identity <identity>...
-agent-shim pool set <name> --identity <identity>...
+agent-shim pool add <name> --identity <identity>... [--json]
+agent-shim pool set <name> --identity <identity>... [--json]
 agent-shim pool list [--json]
 agent-shim pool show <name> [--json]
-agent-shim pool remove <name> [--yes]
-agent-shim pool use <name>
+agent-shim pool remove <name> [--yes] [--json]
+agent-shim pool use <name> [--json]
 agent-shim pool pick <name> [--json]
 
-agent-shim provider add <name> --display-name <name> (--base-url <url> | --kind codex) (--credential <source>)... [--credential-target <bearer|apiKey>] [--env KEY=VALUE]...
+agent-shim provider add <name> --display-name <name> (--base-url <url> | --kind codex) (--credential <source>)... [--credential-target <bearer|apiKey>] [--env KEY=VALUE]... [--json]
                                               [--codex-default-model <model>] [--codex-model <tier=model>]... [--codex-effort <none|low|medium|high>]
-agent-shim provider set <name> [--display-name <name>] ([--base-url <url>] | --kind codex) [--credential <source>]... [--credential-target <bearer|apiKey>] [--env KEY=VALUE]... [--unset-env KEY]...
+agent-shim provider set <name> [--display-name <name>] ([--base-url <url>] | --kind codex) [--credential <source>]... [--credential-target <bearer|apiKey>] [--env KEY=VALUE]... [--unset-env KEY]... [--json]
                                               [--codex-default-model <model>] [--codex-model <tier=model>]... [--codex-effort <none|low|medium|high>]
 agent-shim provider list [--json]
 agent-shim provider show <name> [--json]
-agent-shim provider remove <name> [--yes]
+agent-shim provider remove <name> [--yes] [--json]
 
-agent-shim rule add <path> [--config-profile <profile>] [--identity <identity>]
-agent-shim rule set <path> [--config-profile <profile> | --no-config-profile] [--identity <identity> | --no-identity]
+agent-shim rule add <path> [--config-profile <profile>] [--identity <identity>] [--json]
+agent-shim rule set <path> [--config-profile <profile> | --no-config-profile] [--identity <identity> | --no-identity] [--json]
 agent-shim rule list [--json]
 agent-shim rule show <path> [--json]
-agent-shim rule remove <path> [--yes]
+agent-shim rule remove <path> [--yes] [--json]
 
 agent-shim configure [path] [--identity <identity>]
 agent-shim check [path] [--identity <identity>] [--json] [--strict]
@@ -144,7 +144,7 @@ agent-shim run [@<identity>] [launch flags] [claude arguments]
 claude @<identity> ...                      # the same, once `agent-shim shim enable` has run
 ```
 
-Every `list`, `show`, `check`, `doctor` and `headroom status` prints text by default and JSON with `--json`. Prompts appear only when standard input is a terminal; without one, a command that needs input fails with the option that supplies it (a `remove` needs `--yes`). Failures print as `agent-shim: <message>` and exit 1, usage errors exit 2, a selected provider or identity whose credential block yields no token exits 64, and `AGENT_SHIM_DEBUG=1` adds stack traces to unexpected errors. `agent-shim completion <bash|zsh|fish>` prints a shell completion script.
+Every `list`, `show`, `check`, `doctor` and `headroom status` prints text by default and JSON with `--json`, and so do the mutating commands (`add`, `set`, `remove` and `use` on identities, profiles, providers, pools and rules), which print one object naming the `action`, the `kind`, the `name` and, for a creation or update, the stored `value`. Prompts appear only when standard input is a terminal; without one, a command that needs input fails with the option that supplies it (a `remove` needs `--yes`). Failures print as `agent-shim: <message>` and exit 1, usage errors exit 2, a selected provider or identity whose credential block yields no token exits 64, and `AGENT_SHIM_DEBUG=1` adds stack traces to unexpected errors. `agent-shim completion <bash|zsh|fish>` prints a shell completion script.
 
 `agent-shim check [path]` resolves the full cascade for a directory without touching the farm, and is the primary way to answer "why is X shared or hidden here". `agent-shim doctor` audits the whole `~/.agent-shim` config graph at once: every identity, profile, `extends` chain, provider (naming the exact replacement for a file still in the format before the credential block) and directory rule, plus whether the right `agent-shim` is the one actually on `PATH`.
 

package/dist/cli.cjs

@@ -54858,6 +54858,13 @@ function date4(params) {
 function printJson(value) {
   console.log(JSON.stringify(value, null, 2));
 }
+function reportMutation(json2, report, printText) {
+  if (json2 === true) {
+    printJson(report);
+  } else {
+    printText();
+  }
+}
 function withExamples(command, examples) {
   return command.addHelpText("after", `
 Examples:
@@ -60584,30 +60591,36 @@ function registerProfileCommand(program2, deps) {
   withExamples(
     profile.command("add [name]").description(
       "Create a new configuration profile. Fails if one with this name already exists. With no options on a terminal, walks through choosing its categories."
-    ).option("--extends <profile>", "A profile this one extends (repeatable, in order).", collectRepeated).option("--description <text>", "A free-text description stored in the profile.").action(async (name, options) => {
+    ).option("--extends <profile>", "A profile this one extends (repeatable, in order).", collectRepeated).option("--description <text>", "A free-text description stored in the profile.").option("--json", "Print the result as JSON.").action(async (name, allOptions) => {
+      const { json: json2, ...options } = allOptions;
       const hasOptions = options.extends !== void 0 || options.description !== void 0;
       if (!hasOptions && deps.isInteractive()) {
         const result = await runProfileWizard(deps.prompts, name === void 0 ? { paths } : { paths, createName: name });
         if (result === void 0) {
           throw new PromptCancelledError();
         }
-        console.log(`Created configuration profile "${result.name}".`);
+        reportMutation(json2, { action: "created", kind: "profile", name: result.name, value: readProfile(paths, result.name) }, () => {
+          console.log(`Created configuration profile "${result.name}".`);
+        });
         return;
       }
       if (name === void 0) {
         throw new UsageError("missing required argument 'name' (standard input is not a terminal, so there is nothing to prompt on).");
       }
-      createProfile(paths, name, options.extends, options.description);
-      console.log(`Created configuration profile "${name}".`);
+      const created = createProfile(paths, name, options.extends, options.description);
+      reportMutation(json2, { action: "created", kind: "profile", name, value: created }, () => {
+        console.log(`Created configuration profile "${name}".`);
+      });
     }),
     ["agent-shim profile add client-acme", "agent-shim profile add client-acme --extends work-default --extends strict"]
   );
   withExamples(
     profile.command("set <name>").description(
       "Update a configuration profile's categories, entries, extends list, description or launch settings. With no options on a terminal, walks through its categories."
-    ).option("--category <category=bool>", "Share (true) or hide (false) a whole category (repeatable).", collectBoolPair).option("--entry <path=bool>", "Share (true) or hide (false) one <category>/<path> entry (repeatable).", collectBoolPair).option("--extends <profile>", "Replace the extends list with these profiles (repeatable, in order).", collectRepeated).option("--no-extends", "Clear the extends list.").option("--description <text>", "Replace the description.").option("--no-description", "Clear the description.").option("--launch-skip-permissions", "Launches under this profile skip permission prompts.").option("--no-launch-skip-permissions", "Launches under this profile keep permission prompts.").option("--launch-remote-control", "Launches under this profile enable Remote Control.").option("--no-launch-remote-control", "Launches under this profile leave Remote Control off.").option("--launch-headroom", "Launches under this profile route through headroom.").option("--no-launch-headroom", "Launches under this profile route direct.").option("--launch-track-usage", "Launches under this profile route through the front door so their requests and quota are recorded, with no headroom needed.").option("--no-launch-track-usage", "Launches under this profile are not recorded unless a provider or headroom routes them anyway.").option("--launch-provider <provider>", "Launches under this profile route through this provider.").option("--no-launch-provider", "Clear this profile's provider selection.").action(async (name, options) => {
+    ).option("--category <category=bool>", "Share (true) or hide (false) a whole category (repeatable).", collectBoolPair).option("--entry <path=bool>", "Share (true) or hide (false) one <category>/<path> entry (repeatable).", collectBoolPair).option("--extends <profile>", "Replace the extends list with these profiles (repeatable, in order).", collectRepeated).option("--no-extends", "Clear the extends list.").option("--description <text>", "Replace the description.").option("--no-description", "Clear the description.").option("--launch-skip-permissions", "Launches under this profile skip permission prompts.").option("--no-launch-skip-permissions", "Launches under this profile keep permission prompts.").option("--launch-remote-control", "Launches under this profile enable Remote Control.").option("--no-launch-remote-control", "Launches under this profile leave Remote Control off.").option("--launch-headroom", "Launches under this profile route through headroom.").option("--no-launch-headroom", "Launches under this profile route direct.").option("--launch-track-usage", "Launches under this profile route through the front door so their requests and quota are recorded, with no headroom needed.").option("--no-launch-track-usage", "Launches under this profile are not recorded unless a provider or headroom routes them anyway.").option("--launch-provider <provider>", "Launches under this profile route through this provider.").option("--no-launch-provider", "Clear this profile's provider selection.").option("--json", "Print the result as JSON.").action(async (name, allOptions) => {
+      const { json: json2, ...options } = allOptions;
       requireProfileExists(paths, name);
-      if (Object.values(options).every((value) => value === void 0)) {
+      if (Object.entries(allOptions).every(([key, value]) => key === "json" || value === void 0)) {
         if (!deps.isInteractive()) {
           throw new UsageError(
             "Nothing to change: pass --category, --entry, --extends, --description or a --launch-* option (standard input is not a terminal, so there is nothing to prompt on)."
@@ -60619,7 +60632,9 @@ function registerProfileCommand(program2, deps) {
       } else {
         applyProfileSet(paths, name, options);
       }
-      console.log(`Updated configuration profile "${name}".`);
+      reportMutation(json2, { action: "updated", kind: "profile", name, value: readProfile(paths, name) }, () => {
+        console.log(`Updated configuration profile "${name}".`);
+      });
     }),
     [
       "agent-shim profile set client-acme --category history=false --category knowledge=true",
@@ -60675,19 +60690,23 @@ function registerProfileCommand(program2, deps) {
     ["agent-shim profile show client-acme", "agent-shim profile show client-acme --json"]
   );
   withExamples(
-    profile.command("remove <name>").description("Delete a configuration profile's file. References to it by name are left for `agent-shim doctor` to report.").option("--yes", "Remove without asking for confirmation (required when standard input is not a terminal).").action(async (name, options) => {
+    profile.command("remove <name>").description("Delete a configuration profile's file. References to it by name are left for `agent-shim doctor` to report.").option("--yes", "Remove without asking for confirmation (required when standard input is not a terminal).").option("--json", "Print the result as JSON.").action(async (name, options) => {
       requireProfileExists(paths, name);
       await confirmRemoval(deps, options.yes, `configuration profile "${name}"`);
       removeProfile(paths, name);
-      console.log(`Removed configuration profile "${name}".`);
+      reportMutation(options.json, { action: "removed", kind: "profile", name }, () => {
+        console.log(`Removed configuration profile "${name}".`);
+      });
     }),
     ["agent-shim profile remove client-acme --yes"]
   );
   withExamples(
-    profile.command("use <name>").description("Make a configuration profile the global default, used when no directory rule or identity selects one.").action(async (name) => {
+    profile.command("use <name>").description("Make a configuration profile the global default, used when no directory rule or identity selects one.").option("--json", "Print the result as JSON.").action(async (name, options) => {
       await ensureProfileExists(deps, name);
       setGlobalDefaultProfile(paths, name);
-      console.log(`Global default configuration profile is now "${name}".`);
+      reportMutation(options.json, { action: "selected", kind: "profile", name }, () => {
+        console.log(`Global default configuration profile is now "${name}".`);
+      });
     }),
     ["agent-shim profile use work-default"]
   );
@@ -60732,7 +60751,7 @@ async function runIdentityWizard(prompts, paths, name, options = {}) {
   prompts.outro(`Identity "${name}" is set up and active.`);
   return true;
 }
-async function selectIdentity(deps, name) {
+async function selectIdentity(deps, name, json2) {
   if (poolNameOf(name) !== void 0 || identityExists(deps.paths, name)) {
     useIdentity(deps.paths, name);
   } else if (deps.isInteractive()) {
@@ -60742,7 +60761,9 @@ async function selectIdentity(deps, name) {
   } else {
     throw new IdentityNotFoundError(name);
   }
-  console.log(`Active identity is now "${name}".`);
+  reportMutation(json2, { action: "selected", kind: "identity", name }, () => {
+    console.log(`Active identity is now "${name}".`);
+  });
 }
 async function tryRunAtIdentityShortcut(deps, argv) {
   if (argv.length !== 1) {
@@ -60784,9 +60805,11 @@ function registerIdentityCommand(program2, deps) {
     ["agent-shim identity add work", "agent-shim identity list"]
   );
   withExamples(
-    identity.command("add <name>").description("Create a new identity. Fails if one with this name already exists.").action((name) => {
-      addIdentity(paths, name);
-      console.log(`Created identity "${name}".`);
+    identity.command("add <name>").description("Create a new identity. Fails if one with this name already exists.").option("--json", "Print the result as JSON.").action((name, options) => {
+      const created = addIdentity(paths, name);
+      reportMutation(options.json, { action: "created", kind: "identity", name, value: created }, () => {
+        console.log(`Created identity "${name}".`);
+      });
     }),
     ["agent-shim identity add work"]
   );
@@ -60833,7 +60856,7 @@ function registerIdentityCommand(program2, deps) {
     }),
     ["agent-shim identity show work", "agent-shim identity show work --json"]
   );
-  const identitySet = identity.command("set <name>").description("Update an identity's settings.").option("--default-profile <profile>", "Configuration profile this identity uses when nothing more specific selects one.").option("--no-default-profile", "Clear this identity's default configuration profile.").option("--allow-ambient-credential", "Allow this identity to launch even with an ambient credential env var set.").option("--no-allow-ambient-credential", "Disallow ambient credential env vars for this identity (the default).").option(
+  const identitySet = identity.command("set <name>").description("Update an identity's settings.").option("--json", "Print the result as JSON.").option("--default-profile <profile>", "Configuration profile this identity uses when nothing more specific selects one.").option("--no-default-profile", "Clear this identity's default configuration profile.").option("--allow-ambient-credential", "Allow this identity to launch even with an ambient credential env var set.").option("--no-allow-ambient-credential", "Disallow ambient credential env vars for this identity (the default).").option(
     "--credential <source>",
     `Authenticate this identity from a token instead of its stored login, replacing any existing sources (repeatable, in the order tried): ${CREDENTIAL_SOURCE_SYNTAX}.`,
     collectCredentialSource
@@ -60845,8 +60868,9 @@ function registerIdentityCommand(program2, deps) {
   );
   addCredentialCacheOptions(identitySet);
   withExamples(
-    identitySet.action(async (name, options) => {
-      if (Object.values(options).every((value) => value === void 0)) {
+    identitySet.action(async (name, allOptions) => {
+      const { json: json2, ...options } = allOptions;
+      if (Object.entries(allOptions).every(([key, value]) => key === "json" || value === void 0)) {
         throw new UsageError(
           "Nothing to change: pass --default-profile, --no-default-profile, --allow-ambient-credential, --no-allow-ambient-credential, --credential, --no-credential, --credential-target or a --credential-cache option."
         );
@@ -60854,25 +60878,24 @@ function registerIdentityCommand(program2, deps) {
       if (!identityExists(paths, name)) {
         throw new IdentityNotFoundError(name);
       }
+      const messages = [];
       if (options.defaultProfile !== void 0) {
         const profileName = options.defaultProfile === false ? void 0 : options.defaultProfile;
         if (profileName !== void 0) {
           await ensureProfileExists(deps, profileName);
         }
         setDefaultConfigProfile(paths, name, profileName);
-        console.log(
+        messages.push(
           profileName === void 0 ? `Identity "${name}" no longer has a default configuration profile.` : `Identity "${name}" now defaults to configuration profile "${profileName}".`
         );
       }
       if (options.allowAmbientCredential !== void 0) {
         setAllowAmbientCredential(paths, name, options.allowAmbientCredential);
-        console.log(
-          `Identity "${name}" ${options.allowAmbientCredential ? "now allows" : "no longer allows"} an ambient credential.`
-        );
+        messages.push(`Identity "${name}" ${options.allowAmbientCredential ? "now allows" : "no longer allows"} an ambient credential.`);
       }
       if (options.credential === false) {
         setIdentityCredential(paths, name, false);
-        console.log(`Identity "${name}" no longer has a credential and uses its stored login.`);
+        messages.push(`Identity "${name}" no longer has a credential and uses its stored login.`);
       } else if (options.credential !== void 0 || options.credentialTarget !== void 0 || cacheChange(options, void 0) !== void 0) {
         const cache = cacheChange(options, readIdentity(paths, name)?.credential?.cache);
         const updated = setIdentityCredential(paths, name, {
@@ -60881,9 +60904,14 @@ function registerIdentityCommand(program2, deps) {
           ...cache === void 0 ? {} : { cache }
         });
         if (updated.credential !== void 0) {
-          console.log(`Identity "${name}" now authenticates with credential ${describeCredential(updated.credential)}.`);
+          messages.push(`Identity "${name}" now authenticates with credential ${describeCredential(updated.credential)}.`);
         }
       }
+      reportMutation(json2, { action: "updated", kind: "identity", name, value: readIdentity(paths, name) }, () => {
+        for (const message of messages) {
+          console.log(message);
+        }
+      });
     }),
     [
       "agent-shim identity set work --default-profile client-acme",
@@ -60895,19 +60923,21 @@ function registerIdentityCommand(program2, deps) {
   withExamples(
     identity.command("remove <name>").description(
       "Delete an identity and its directory, including its credentials and anything it does not share with ~/.claude. Shared data in ~/.claude is kept."
-    ).option("--yes", "Remove without asking for confirmation (required when standard input is not a terminal).").action(async (name, options) => {
+    ).option("--yes", "Remove without asking for confirmation (required when standard input is not a terminal).").option("--json", "Print the result as JSON.").action(async (name, options) => {
       if (!identityExists(paths, name)) {
         throw new IdentityNotFoundError(name);
       }
       await confirmRemoval(deps, options.yes, `identity "${name}" and its directory ${import_node_path20.default.join(paths.identitiesDir, name)}`);
       removeIdentity(paths, name);
-      console.log(`Removed identity "${name}".`);
+      reportMutation(options.json, { action: "removed", kind: "identity", name }, () => {
+        console.log(`Removed identity "${name}".`);
+      });
     }),
     ["agent-shim identity remove old-client --yes"]
   );
   withExamples(
-    identity.command("use <name>").description("Select the active identity, used by every launch that names none. Offers to create it on a terminal if it does not exist.").action(async (name) => {
-      await selectIdentity(deps, name);
+    identity.command("use <name>").description("Select the active identity, used by every launch that names none. Offers to create it on a terminal if it does not exist.").option("--json", "Print the result as JSON.").action(async (name, options) => {
+      await selectIdentity(deps, name, options.json);
     }),
     ["agent-shim identity use work", "agent-shim @work"]
   );
@@ -60955,7 +60985,7 @@ function registerIdentityCommand(program2, deps) {
 // package.json
 var package_default = {
   name: "agent-shim",
-  version: "7.11.0",
+  version: "7.12.0",
   description: "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
   license: "MIT",
   author: "Joseph Mearman <joseph@mearman.co.uk>",
@@ -68598,20 +68628,24 @@ function registerPoolCommand(program2, deps) {
     ["agent-shim pool add subs --identity work --identity personal", "agent-shim pool pick subs"]
   );
   withExamples(
-    pool.command("add <name>").description("Define a pool. Fails if one with this name already exists.").option("--identity <name>", "A member identity (repeatable).", collectRepeated).action((name, options) => {
+    pool.command("add <name>").description("Define a pool. Fails if one with this name already exists.").option("--identity <name>", "A member identity (repeatable).", collectRepeated).option("--json", "Print the result as JSON.").action((name, options) => {
       const members2 = membersOf(options);
       requireIdentities(paths, members2);
-      addPool(paths, name, members2);
-      console.log(`Created pool "${name}" with ${members2.join(", ")}.`);
+      const created = addPool(paths, name, members2);
+      reportMutation(options.json, { action: "created", kind: "pool", name, value: created }, () => {
+        console.log(`Created pool "${name}" with ${members2.join(", ")}.`);
+      });
     }),
     ["agent-shim pool add subs --identity work --identity personal"]
   );
   withExamples(
-    pool.command("set <name>").description("Replace a pool's members.").option("--identity <name>", "A member identity (repeatable); the full new list.", collectRepeated).action((name, options) => {
+    pool.command("set <name>").description("Replace a pool's members.").option("--identity <name>", "A member identity (repeatable); the full new list.", collectRepeated).option("--json", "Print the result as JSON.").action((name, options) => {
       const members2 = membersOf(options);
       requireIdentities(paths, members2);
-      setPool(paths, name, members2);
-      console.log(`Pool "${name}" now has ${members2.join(", ")}.`);
+      const updated = setPool(paths, name, members2);
+      reportMutation(options.json, { action: "updated", kind: "pool", name, value: updated }, () => {
+        console.log(`Pool "${name}" now has ${members2.join(", ")}.`);
+      });
     }),
     ["agent-shim pool set subs --identity work --identity personal --identity spare"]
   );
@@ -68647,18 +68681,22 @@ function registerPoolCommand(program2, deps) {
     ["agent-shim pool show subs"]
   );
   withExamples(
-    pool.command("remove <name>").description("Delete a pool. Its member identities are untouched.").option("--yes", "Skip the confirmation prompt.").action(async (name, options) => {
+    pool.command("remove <name>").description("Delete a pool. Its member identities are untouched.").option("--yes", "Skip the confirmation prompt.").option("--json", "Print the result as JSON.").action(async (name, options) => {
       requirePool(paths, name);
       await confirmRemoval(deps, options.yes, `pool "${name}"`);
       removePool(paths, name);
-      console.log(`Removed pool "${name}".`);
+      reportMutation(options.json, { action: "removed", kind: "pool", name }, () => {
+        console.log(`Removed pool "${name}".`);
+      });
     }),
     ["agent-shim pool remove subs --yes"]
   );
   withExamples(
-    pool.command("use <name>").description("Make launches with no other selection pick a member of this pool.").action((name) => {
+    pool.command("use <name>").description("Make launches with no other selection pick a member of this pool.").option("--json", "Print the result as JSON.").action((name, options) => {
       useIdentity(paths, `${POOL_SELECTOR_PREFIX}${name}`);
-      console.log(`Active selection is now pool "${name}".`);
+      reportMutation(options.json, { action: "selected", kind: "pool", name }, () => {
+        console.log(`Active selection is now pool "${name}".`);
+      });
     }),
     ["agent-shim pool use subs"]
   );
@@ -68719,7 +68757,7 @@ function registerProviderCommand(program2, deps) {
       new Option("--credential-target <target>", "Where the token goes: bearer sets ANTHROPIC_AUTH_TOKEN (default), apiKey sets ANTHROPIC_API_KEY.").choices(
         PROVIDER_CREDENTIAL_TARGETS
       )
-    ).option("--env <KEY=VALUE>", "Extra environment entry for the child (repeatable).", collectStringPair).option("--codex-default-model <model>", "Codex providers: the codex model a request maps to when no tier matches.").option("--codex-model <tier=model>", "Codex providers: the codex model one tier (fable, opus, sonnet or haiku) maps to (repeatable).", collectStringPair).addOption(new Option("--codex-effort <effort>", "Codex providers: the reasoning effort when a request asks for none the backend accepts.").choices(CODEX_EFFORTS)).action((name, options) => {
+    ).option("--env <KEY=VALUE>", "Extra environment entry for the child (repeatable).", collectStringPair).option("--codex-default-model <model>", "Codex providers: the codex model a request maps to when no tier matches.").option("--codex-model <tier=model>", "Codex providers: the codex model one tier (fable, opus, sonnet or haiku) maps to (repeatable).", collectStringPair).addOption(new Option("--codex-effort <effort>", "Codex providers: the reasoning effort when a request asks for none the backend accepts.").choices(CODEX_EFFORTS)).option("--json", "Print the result as JSON.").action((name, options) => {
       const codex = codexConfigFromOptions(options);
       const created = addProvider(paths, name, {
         ...options.kind === void 0 ? {} : { kind: options.kind },
@@ -68730,7 +68768,9 @@ function registerProviderCommand(program2, deps) {
         ...options.env === void 0 ? {} : { env: options.env },
         ...codex === void 0 ? {} : { codex }
       });
-      console.log(`Created provider "${name}" (${describeProviderEndpoint(created)}, credential ${describeCredential(created.credential)}).`);
+      reportMutation(options.json, { action: "created", kind: "provider", name, value: created }, () => {
+        console.log(`Created provider "${name}" (${describeProviderEndpoint(created)}, credential ${describeCredential(created.credential)}).`);
+      });
     }),
     [
       "agent-shim provider add z --display-name z.ai --base-url https://api.z.ai/api/anthropic --credential env:Z_API_TOKEN",
@@ -68752,8 +68792,9 @@ function registerProviderCommand(program2, deps) {
   ).option("--env <KEY=VALUE>", "Add or replace an environment entry for the child (repeatable).", collectStringPair).option("--unset-env <KEY>", "Remove an environment entry (repeatable).", collectRepeated).option("--codex-default-model <model>", "Codex providers: replace the model a request maps to when no tier matches.").option("--codex-model <tier=model>", "Codex providers: set the codex model one tier maps to (repeatable; other tiers are kept).", collectStringPair).addOption(new Option("--codex-effort <effort>", "Codex providers: replace the default reasoning effort.").choices(CODEX_EFFORTS));
   addCredentialCacheOptions(providerSet);
   withExamples(
-    providerSet.action((name, options) => {
-      if (Object.values(options).every((value) => value === void 0)) {
+    providerSet.option("--json", "Print the result as JSON.").action((name, allOptions) => {
+      const { json: json2, ...options } = allOptions;
+      if (Object.entries(allOptions).every(([key, value]) => key === "json" || value === void 0)) {
         throw new UsageError(
           "Nothing to change: pass --display-name, --base-url, --credential, --credential-target, a --credential-cache option, --env, --unset-env, --codex-default-model, --codex-model or --codex-effort."
         );
@@ -68770,7 +68811,9 @@ function registerProviderCommand(program2, deps) {
         ...options.env === void 0 ? {} : { env: options.env },
         ...options.unsetEnv === void 0 ? {} : { unsetEnv: options.unsetEnv }
       });
-      console.log(`Updated provider "${name}" (${describeProviderEndpoint(updated)}, credential ${describeCredential(updated.credential)}).`);
+      reportMutation(json2, { action: "updated", kind: "provider", name, value: updated }, () => {
+        console.log(`Updated provider "${name}" (${describeProviderEndpoint(updated)}, credential ${describeCredential(updated.credential)}).`);
+      });
     }),
     [
       "agent-shim provider set z --base-url https://api.z.ai/api/anthropic",
@@ -68824,13 +68867,15 @@ function registerProviderCommand(program2, deps) {
     ["agent-shim provider show z", "agent-shim provider show z --json"]
   );
   withExamples(
-    provider.command("remove <name>").description("Delete a provider definition.").option("--yes", "Remove without asking for confirmation (required when standard input is not a terminal).").action(async (name, options) => {
+    provider.command("remove <name>").description("Delete a provider definition.").option("--yes", "Remove without asking for confirmation (required when standard input is not a terminal).").option("--json", "Print the result as JSON.").action(async (name, options) => {
       if (!providerExists(paths, name)) {
         throw new ProviderNotFoundError(name);
       }
       await confirmRemoval(deps, options.yes, `provider "${name}"`);
       removeProvider(paths, name);
-      console.log(`Removed provider "${name}".`);
+      reportMutation(options.json, { action: "removed", kind: "provider", name }, () => {
+        console.log(`Removed provider "${name}".`);
+      });
     }),
     ["agent-shim provider remove z --yes"]
   );
@@ -68856,21 +68901,27 @@ function registerRuleCommand(program2, deps) {
     ["agent-shim rule add ~/work/acme --config-profile client-acme", "agent-shim rule list"]
   );
   withExamples(
-    rule.command("add <path>").description("Add a directory rule for a path. Fails if a rule for that exact path already exists.").option("--config-profile <profile>", "Configuration profile to select under this path.").option("--identity <identity>", "Identity to pin under this path.").action(async (rulePath, options) => {
+    rule.command("add <path>").description("Add a directory rule for a path. Fails if a rule for that exact path already exists.").option("--config-profile <profile>", "Configuration profile to select under this path.").option("--identity <identity>", "Identity to pin under this path.").option("--json", "Print the result as JSON.").action(async (rulePath, allOptions) => {
+      const { json: json2, ...options } = allOptions;
       await checkRuleTargets(deps, options);
-      addDirectoryRule(paths, rulePath, options);
-      console.log(`Added directory rule for "${rulePath}".`);
+      const created = addDirectoryRule(paths, rulePath, options);
+      reportMutation(json2, { action: "created", kind: "rule", name: rulePath, value: created }, () => {
+        console.log(`Added directory rule for "${rulePath}".`);
+      });
     }),
     ["agent-shim rule add ~/work/acme --config-profile client-acme", "agent-shim rule add ~/personal --identity personal"]
   );
   withExamples(
-    rule.command("set <path>").description("Update the directory rule for a path.").option("--config-profile <profile>", "Configuration profile to select under this path.").option("--no-config-profile", "Stop selecting a configuration profile under this path.").option("--identity <identity>", "Identity to pin under this path.").option("--no-identity", "Stop pinning an identity under this path.").action(async (rulePath, options) => {
+    rule.command("set <path>").description("Update the directory rule for a path.").option("--config-profile <profile>", "Configuration profile to select under this path.").option("--no-config-profile", "Stop selecting a configuration profile under this path.").option("--identity <identity>", "Identity to pin under this path.").option("--no-identity", "Stop pinning an identity under this path.").option("--json", "Print the result as JSON.").action(async (rulePath, allOptions) => {
+      const { json: json2, ...options } = allOptions;
       if (options.configProfile === void 0 && options.identity === void 0) {
         throw new UsageError("Nothing to change: pass --config-profile, --no-config-profile, --identity or --no-identity.");
       }
       await checkRuleTargets(deps, options);
-      updateDirectoryRule(paths, rulePath, options);
-      console.log(`Updated directory rule for "${rulePath}".`);
+      const updated = updateDirectoryRule(paths, rulePath, options);
+      reportMutation(json2, { action: "updated", kind: "rule", name: rulePath, value: updated }, () => {
+        console.log(`Updated directory rule for "${rulePath}".`);
+      });
     }),
     ["agent-shim rule set ~/work/acme --identity work", "agent-shim rule set ~/work/acme --no-config-profile"]
   );
@@ -68907,13 +68958,15 @@ function registerRuleCommand(program2, deps) {
     ["agent-shim rule show ~/work/acme"]
   );
   withExamples(
-    rule.command("remove <path>").description("Remove the directory rule for a path.").option("--yes", "Remove without asking for confirmation (required when standard input is not a terminal).").action(async (rulePath, options) => {
+    rule.command("remove <path>").description("Remove the directory rule for a path.").option("--yes", "Remove without asking for confirmation (required when standard input is not a terminal).").option("--json", "Print the result as JSON.").action(async (rulePath, options) => {
       if (!listDirectoryRules(paths).some((entry) => entry.path === rulePath)) {
         throw new DirectoryRuleNotFoundError(rulePath);
       }
       await confirmRemoval(deps, options.yes, `the directory rule for "${rulePath}"`);
       removeDirectoryRule(paths, rulePath);
-      console.log(`Removed directory rule for "${rulePath}".`);
+      reportMutation(options.json, { action: "removed", kind: "rule", name: rulePath }, () => {
+        console.log(`Removed directory rule for "${rulePath}".`);
+      });
     }),
     ["agent-shim rule remove ~/work/acme --yes"]
   );

package/dist/types/cli/commandDeps.d.ts

@@ -15,6 +15,17 @@ export interface CommandDeps {
 }
 /** Prints `value` as indented JSON on standard output: the one `--json` output format every `list`, `show`, `check`, `doctor` and `headroom status` command shares. */
 export declare function printJson(value: unknown): void;
+/** What a mutating command did, as the one object `--json` prints in place of its text output. */
+export interface MutationReport {
+    readonly action: "created" | "updated" | "removed" | "selected";
+    /** The noun the command works on: `identity`, `profile`, `provider`, `pool` or `rule`. */
+    readonly kind: string;
+    readonly name: string;
+    /** The stored object after the change; absent for a removal and for a selection. */
+    readonly value?: unknown;
+}
+/** Reports a mutating command's outcome: the `MutationReport` as JSON under `--json`, otherwise whatever `printText` prints. */
+export declare function reportMutation(json: boolean | undefined, report: MutationReport, printText: () => void): void;
 /**
  * Appends an `Examples:` block to `command`'s help output, one `$ agent-shim ...` line per entry. Every command registers at least one, so `--help` on any of them shows a runnable invocation, not just its option list.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-shim",
-  "version": "7.11.0",
+  "version": "7.12.0",
   "description": "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
   "license": "MIT",
   "author": "Joseph Mearman <joseph@mearman.co.uk>",