agent-shim 7.7.0 → 7.8.0

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

@@ -0,0 +1,8 @@
+/**
+ * The one boolean vocabulary every agent-shim input shares, CLI flag values and environment variables alike: `true` and `1` mean true, `false` and `0` mean false, and nothing else is a boolean (no case folding, no `yes`/`no`).
+ *
+ * Lives in a module with no imports so both `src/cli/parsers.ts` (which raises on anything else) and `src/cliError.ts` (which must never raise while reporting another failure) can share it without an import cycle.
+ * @param input - The raw text.
+ * @returns The boolean it spells, or undefined when it spells none.
+ */
+export declare function parseBoolWord(input: string): boolean | undefined;

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

@@ -0,0 +1,40 @@
+import { UsageError } from "../cliError";
+/** One `<key>=<value>` pair, as parsed by `parsePair`. */
+export interface ParsedPair {
+    readonly key: string;
+    readonly value: string;
+}
+/**
+ * Splits `input` on its *first* `=` into a key and a value. The value may itself contain further `=` characters (they stay part of the value); only the first `=` is treated as the separator.
+ *
+ * Throws when there is no `=` at all, or when the key half is empty (`=true`, or a leading `=`).
+ */
+export declare function parsePair(input: string): ParsedPair;
+/** Parses `input` as a boolean in the shared vocabulary (`true`/`1`, `false`/`0`); throws on anything else. */
+export declare function parseBool(input: string): boolean;
+/** Raised when a boolean environment variable holds something outside the shared vocabulary. */
+export declare class InvalidEnvBoolError extends UsageError {
+    readonly variable: string;
+    readonly value: string;
+    constructor(variable: string, value: string);
+}
+/**
+ * Reads a boolean environment variable with the same vocabulary a CLI flag value uses. Unset and the empty string both mean "not given" (undefined), consistent with how every other agent-shim environment variable treats the empty string; anything outside the vocabulary throws `InvalidEnvBoolError` rather than silently reading as false.
+ */
+export declare function parseEnvBool(variable: string, value: string | undefined): boolean | undefined;
+/**
+ * Parses a comma-separated list of `<key>=<bool>` pairs into a plain object, e.g. `"history=true,knowledge=false"` becomes `{ history: true, knowledge: false }`. Used only for the list-valued environment variables; flags repeat instead.
+ *
+ * An empty string parses to `{}`. A key repeated within the same list is not an error: the later occurrence wins, matching how a plain object literal with a repeated key behaves.
+ */
+export declare function parseBoolPairList(input: string): Record<string, boolean>;
+/**
+ * Commander repeatable-option collector for one `--flag <key>=<bool>` occurrence: parses `value` and merges it over `previous`, so `--category history=true --category knowledge=false` accumulates into one object, the later occurrence winning on key collision.
+ */
+export declare function collectBoolPair(value: string, previous?: Readonly<Record<string, boolean>>): Record<string, boolean>;
+/** Commander repeatable-option collector for one `--flag <KEY>=<VALUE>` occurrence with a free-text value, merged over `previous` the same way `collectBoolPair` merges. */
+export declare function collectStringPair(value: string, previous?: Readonly<Record<string, string>>): Record<string, string>;
+/** Commander repeatable-option collector for a plain repeated value (`--extends a --extends b`), preserving the order given. */
+export declare function collectRepeated(value: string, previous?: readonly string[]): string[];
+/** Commander option parser for a duration such as `30m`, `5h` or `7d` (a count followed by ms, s, m, h, d or w), returning milliseconds. A malformed value is a usage error naming the option. */
+export declare function parseDurationOption(value: string): number;

package/dist/types/configProfilesStore.d.ts

@@ -0,0 +1,61 @@
+import { type ConfigProfile, type GlobalConfig, type LaunchFlags } from "./config/schema";
+import { CliError } from "./cliError";
+import type { LayoutPaths } from "./paths";
+/** Raised by any operation that requires a configuration profile to already exist, when it does not. */
+export declare class ProfileNotFoundError extends CliError {
+    readonly profileName: string;
+    constructor(profileName: string);
+}
+/** Raised by `createProfile` (`profile add`) when a profile with the given name already has a file. */
+export declare class ProfileAlreadyExistsError extends CliError {
+    readonly profileName: string;
+    constructor(profileName: string);
+}
+/** Raised when a `--category` patch names something other than one of the four overridable categories (e.g. `secret`, or a typo). */
+export declare class InvalidCategoryNameError extends CliError {
+    readonly categoryName: string;
+    constructor(categoryName: string);
+}
+/** True when a profile file exists for `name`, regardless of whether it validates. */
+export declare function profileExists(paths: LayoutPaths, name: string): boolean;
+export declare function requireProfileExists(paths: LayoutPaths, name: string): void;
+/** Reads and validates one configuration profile, or undefined when it does not exist. */
+export declare function readProfile(paths: LayoutPaths, name: string): ConfigProfile | undefined;
+/**
+ * Creates a new configuration profile, empty apart from the optional `extends` list and description. Throws `ProfileAlreadyExistsError` if a profile with this name already has a file, and `ConfigValidationError` when the result fails `ConfigProfileSchema` (e.g. an empty `--extends ""` name), rather than letting the underlying `ZodError` escape as an unhandled crash.
+ */
+export declare function createProfile(paths: LayoutPaths, name: string, extendsList?: readonly string[], description?: string): ConfigProfile;
+/** One profile as reported by `listProfiles`. */
+export interface ProfileListEntry {
+    readonly name: string;
+    readonly profile: ConfigProfile;
+}
+/** Lists every configuration profile under `configProfilesDir` that has a valid `<name>.json`. */
+export declare function listProfiles(paths: LayoutPaths): readonly ProfileListEntry[];
+/** Reads the user-global `~/.agent-shim/config.json`, or undefined when it does not exist. */
+export declare function readGlobalConfig(paths: LayoutPaths): GlobalConfig | undefined;
+/** Sets the user-global default configuration profile in `~/.agent-shim/config.json`, creating the file if it doesn't exist yet. Whether the profile exists is the caller's concern: `profile use` checks it first. */
+export declare function setGlobalDefaultProfile(paths: LayoutPaths, name: string): GlobalConfig;
+/**
+ * Merges `patch` (from one or more `--category cat=bool` flags) into `profile`'s own `categories` object and writes it back.
+ *
+ * Throws `InvalidCategoryNameError` for any key that isn't one of the four overridable categories — `secret` can never be toggled by any configuration layer, this included.
+ */
+export declare function setProfileCategories(paths: LayoutPaths, name: string, patch: Readonly<Record<string, boolean>>): ConfigProfile;
+/**
+ * Merges `patch` (from one or more `--entry "path"=bool` flags) into `profile`'s own `entries` object and writes it back.
+ *
+ * Key validity (the `<category>/<real-relative-path>` prefix requirement) is enforced by `ConfigProfileSchema`'s own `EntriesSchema` at write time — an invalid key surfaces as the usual `ConfigValidationError`.
+ */
+export declare function setProfileEntries(paths: LayoutPaths, name: string, patch: Readonly<Record<string, boolean>>): ConfigProfile;
+/**
+ * Merges `patch` into `profile`'s own `launch` object and writes it back. A key present in `patch` with the value `undefined` removes that setting outright (a `--no-launch-provider`, say) rather than overwriting it, and a `launch` object left with no settings is removed too.
+ */
+export declare function setProfileLaunchFlags(paths: LayoutPaths, name: string, patch: Readonly<LaunchFlags>): ConfigProfile;
+/** Replaces `profile`'s own `extends` list and/or description; an empty list or an undefined description removes the field. */
+export declare function setProfileMetadata(paths: LayoutPaths, name: string, patch: Readonly<{
+    extends?: readonly string[];
+    description?: string | false;
+}>): ConfigProfile;
+/** Deletes a configuration profile's file. Throws `ProfileNotFoundError` when it does not exist. Nothing that references it by name is rewritten; `agent-shim doctor` reports any identity default, directory rule or `extends` left pointing at it. */
+export declare function removeProfile(paths: LayoutPaths, name: string): void;

package/dist/types/credential.d.ts

@@ -0,0 +1,136 @@
+import type { Credential, CredentialSource, CredentialTarget, CredentialTargetVar } from "./config/schema";
+import { type CredentialCachePort } from "./credentialCache";
+/** The exit status for a launch whose selected provider or identity has a credential block none of whose sources yields a token: 64, the conventional `EX_USAGE`, because the invocation asked for a credential the environment cannot supply. */
+export declare const CREDENTIAL_UNAVAILABLE_EXIT = 64;
+/** How long a non-interactive credential command may run. Secret-store CLIs answer from a local cache or agent well within a second, so this leaves a wide margin while still failing a wedged command quickly instead of stalling the launch. */
+export declare const CREDENTIAL_COMMAND_TIMEOUT_MS = 10000;
+/** How long an interactive credential command may run: long enough for a person to notice and approve a biometric or password prompt, short enough that a prompt nobody is watching fails the launch rather than hanging it. */
+export declare const CREDENTIAL_INTERACTIVE_TIMEOUT_MS = 120000;
+/** What reading one `file` source found: nothing at that path, or its contents and permission bits. `mode` is undefined on a platform with no POSIX permission bits (Windows), where the looseness check cannot apply. */
+type SecretFileRead = {
+    readonly found: false;
+} | {
+    readonly found: true;
+    readonly content: string;
+    readonly mode: number | undefined;
+};
+/** The outcome of one credential command. `stderr` is empty for an interactive run, whose stderr goes to the terminal so a person sees any prompt. */
+export interface CredentialCommandResult {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+}
+/**
+ * Everything resolving a credential needs from the outside world, injected so the resolver (and every launcher test) runs without `op`, the Keychain, real secret files or a terminal. `src/realPorts.ts` wires the real one; tests wire a fake.
+ */
+export interface CredentialPort {
+    /** Reads a `file` source's path (absolute or `~`-rooted). */
+    readonly readSecretFile: (filePath: string) => SecretFileRead;
+    /** Runs a command source's argv directly (no shell) under a timeout, capturing stdout. An interactive run inherits the terminal's stdin and stderr so a person can answer a prompt. */
+    readonly runCommand: (argv: readonly [string, ...string[]], options: {
+        readonly timeoutMs: number;
+        readonly interactive: boolean;
+    }) => CredentialCommandResult;
+    /** Whether a person can answer a prompt now: standard input is a terminal, or there is a desktop session to show a dialog in. */
+    readonly personPresent: () => boolean;
+    /** Where cached credentials live, used only for a credential block that asks for caching. Omit to resolve every launch from the sources. */
+    readonly cache?: CredentialCacheEnv;
+}
+/** The sources that run a command: `command` itself and the two presets that compile to one. */
+type CommandBackedSource = Extract<CredentialSource, {
+    readonly command: unknown;
+} | {
+    readonly op: unknown;
+} | {
+    readonly keychain: unknown;
+}>;
+/**
+ * The argv a command-backed source runs, with the `op` and `keychain` presets compiled to theirs: `op read <ref>` and `security find-generic-password -s <service> [-a <account>] -w`.
+ */
+export declare function commandArgv(source: CommandBackedSource): readonly [string, ...string[]];
+/**
+ * Whether a source needs a person present. An explicit `interactive` always wins. Otherwise only `op` defaults to interactive, because the desktop app's integration asks for approval, unless `OP_SERVICE_ACCOUNT_TOKEN` is set, in which case `op` authenticates as the service account with nobody asked. A plain `command` and a `keychain` read default to non-interactive: a Keychain item whose access list already trusts `security` reads silently, and one that does not fails at once with "User interaction is not allowed" rather than hanging.
+ */
+export declare function isInteractiveSource(source: CredentialSource, env: Readonly<Record<string, string | undefined>>): boolean;
+/** One source as `check`, `doctor` and every `--json` output report it: its kind plus the same non-secret identifying detail `describeSource` prints. */
+type CredentialSourceSummary = {
+    readonly kind: "env";
+    readonly variable: string;
+} | {
+    readonly kind: "file";
+    readonly path: string;
+} | {
+    readonly kind: "command";
+    readonly program: string;
+} | {
+    readonly kind: "op";
+    readonly reference: string;
+} | {
+    readonly kind: "keychain";
+    readonly service: string;
+    readonly account?: string;
+} | {
+    readonly kind: "literal";
+};
+/** A credential block as it is reported: its effective target and each source's summary, in order. */
+export interface CredentialSummary {
+    readonly target: CredentialTarget;
+    readonly sources: readonly CredentialSourceSummary[];
+    /** The block's cache setting when it asks for caching: how long a token is kept (absent for no expiry) and where. */
+    readonly cache?: {
+        readonly ttl?: string;
+        readonly store?: string;
+    };
+}
+/** Summarises a credential block for reporting, with `target` resolved to its default. */
+export declare function summariseCredential(credential: Credential): CredentialSummary;
+/** Renders a source for a message, as `formatSourceSummary` does its summary. */
+export declare function describeSource(source: CredentialSource): string;
+/** Renders a credential summary on one line for human-readable output: `bearer from env Z_API_TOKEN, then op op://...`. */
+export declare function formatCredentialSummary(summary: CredentialSummary): string;
+/** Renders a credential block on one line, as `formatCredentialSummary` does its summary. */
+export declare function describeCredential(credential: Credential): string;
+/** Inputs to `resolveCredential`. */
+export interface ResolveCredentialParams {
+    readonly credential: Credential;
+    /** The launching environment: where `env` sources are read, and what decides whether `op` is interactive. */
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly port: CredentialPort;
+    /** What the credential belongs to, for messages and as its cache key: `provider z` or `identity work`. */
+    readonly subject: string;
+    /** True to skip a cached token and fetch from the sources, replacing the cached copy: what `credential warm` does. */
+    readonly refresh?: boolean;
+}
+/** What caching a credential needs beyond the block's own `cache` setting: the port holding entries, the platform that picks the default store, and the clock the TTL is measured on. */
+export interface CredentialCacheEnv {
+    readonly port: CredentialCachePort;
+    readonly platform: NodeJS.Platform;
+    readonly now: () => number;
+}
+/** A resolved credential: the token, where it goes, and which source produced it. `warnings` carries any source refused on the way for a reason worth reporting (a secret file with loose permissions). */
+export interface ResolvedCredential {
+    readonly target: CredentialTarget;
+    readonly token: string;
+    readonly source: CredentialSource;
+    readonly warnings: readonly string[];
+    /** When the token was fetched, if it came from the cache rather than a source; undefined for a live fetch. */
+    readonly cachedAt?: number;
+}
+/** The outcome of `resolveCredential`: a resolved credential, or a message naming every source and why none yielded a token. */
+export type CredentialResolution = {
+    readonly ok: true;
+    readonly credential: ResolvedCredential;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Resolves a credential block: a fresh cached token if the block caches one, else tries each source in order and returns the first non-empty token, with the block's target, storing it when the block caches. When none yields one, the message names every source and why, and never a value; for a caching block it also names the command that fills the cache from a terminal. Pure over its injected ports.
+ */
+export declare function resolveCredential(params: ResolveCredentialParams): CredentialResolution;
+/**
+ * The credential variables a child environment gets for a resolved token: the target's variable set to the token, and the other two set to undefined so that merging this over an environment removes them, and an ambient one inherited from the parent can neither outrank nor sit alongside the credential agent-shim chose. Removing a variable (rather than setting it to the empty string) leaves nothing for Claude Code to interpret.
+ */
+export declare function credentialVariables(target: CredentialTarget, token: string): Record<CredentialTargetVar, string | undefined>;
+export {};

package/dist/types/credentialCache.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { type CredentialCache, type CredentialCacheStore } from "./config/schema";
+/** What a cache stores for one credential: the token, when it was fetched, and the source that produced it (a non-secret descriptor, kept so `check` and the launch log can still say where the token came from). */
+export declare const CachedCredentialSchema: z.ZodObject<{
+    token: z.ZodString;
+    fetchedAt: z.ZodNumber;
+    source: z.ZodUnion<readonly [z.ZodObject<{
+        env: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        file: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        interactive: z.ZodOptional<z.ZodBoolean>;
+        timeoutMs: z.ZodOptional<z.ZodInt>;
+        command: z.ZodTuple<[z.ZodString], z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        interactive: z.ZodOptional<z.ZodBoolean>;
+        timeoutMs: z.ZodOptional<z.ZodInt>;
+        op: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        interactive: z.ZodOptional<z.ZodBoolean>;
+        timeoutMs: z.ZodOptional<z.ZodInt>;
+        keychain: z.ZodObject<{
+            service: z.ZodString;
+            account: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        literal: z.ZodString;
+    }, z.core.$strict>]>;
+}, z.core.$strict>;
+export type CachedCredential = z.infer<typeof CachedCredentialSchema>;
+/**
+ * Where cached credentials live, injected so resolution and its tests need neither the Keychain nor a real directory. `owner` names what the credential belongs to (`identity work`, `provider z`) and is the entry's key; `store` picks the backing store. `read` returns undefined for a missing or unreadable entry, since an entry that cannot be used is the same as no entry.
+ */
+export interface CredentialCachePort {
+    readonly read: (store: CredentialCacheStore, owner: string) => CachedCredential | undefined;
+    readonly write: (store: CredentialCacheStore, owner: string, entry: CachedCredential) => void;
+    readonly remove: (store: CredentialCacheStore, owner: string) => void;
+}
+/** The store a block uses: its own choice, else the Keychain on macOS and a file elsewhere. */
+export declare function effectiveStore(cache: Readonly<CredentialCache>, platform: NodeJS.Platform): CredentialCacheStore;
+/** A `ttl` such as `12h` in milliseconds, or undefined for no expiry. */
+export declare function ttlMs(cache: Readonly<CredentialCache>): number | undefined;
+/** Whether a cached entry is still within its TTL at `now`. A cache with no TTL never expires; an entry stamped in the future (a clock that moved back) is treated as expired. */
+export declare function isFresh(entry: CachedCredential, cache: Readonly<CredentialCache>, now: number): boolean;
+/** How old a cached entry is, for `check` and `doctor` to report without the value. */
+export declare function cacheAgeMs(entry: CachedCredential, now: number): number;

package/dist/types/directoryRulesStore.d.ts

@@ -0,0 +1,43 @@
+import { type DirectoryRule, type DirectoryRules } from "./config/schema";
+import { CliError } from "./cliError";
+import type { LayoutPaths } from "./paths";
+/** Raised by `removeDirectoryRule`, `updateDirectoryRule` and `rule show` when no rule matches the given path exactly. */
+export declare class DirectoryRuleNotFoundError extends CliError {
+    readonly rulePath: string;
+    constructor(rulePath: string);
+}
+/** Raised by `addDirectoryRule` when neither `--config-profile` nor `--identity` is given, and by `updateDirectoryRule` when an update would leave a rule that sets nothing at all: a rule that pins and overrides nothing would do nothing. */
+export declare class DirectoryRuleMissingTargetError extends CliError {
+    constructor();
+}
+/** Raised by `addDirectoryRule` when a rule for the exact path already exists: `rule add` creates, `rule set` updates. */
+export declare class DirectoryRuleAlreadyExistsError extends CliError {
+    readonly rulePath: string;
+    constructor(rulePath: string);
+}
+/** Reads `~/.agent-shim/directory-rules.json`, or an empty rule set when the file does not exist yet. */
+export declare function readDirectoryRules(paths: LayoutPaths): DirectoryRules;
+/** Validates and writes the whole `~/.agent-shim/directory-rules.json` file. Exported so `src/configure.ts` can update a single rule's `categories`/`entries` in place without duplicating this validate-then-write step. Throws `ConfigValidationError` when `rules` fails `DirectoryRulesSchema`, rather than letting the underlying `ZodError` escape as an unhandled crash. */
+export declare function writeDirectoryRules(paths: LayoutPaths, rules: DirectoryRules): void;
+/** Lists every directory rule, in file order. */
+export declare function listDirectoryRules(paths: LayoutPaths): readonly DirectoryRule[];
+/** Inputs to `addDirectoryRule` beyond the path itself. */
+export interface AddDirectoryRuleOptions {
+    readonly configProfile?: string;
+    readonly identity?: string;
+}
+/**
+ * Adds a new directory rule for `rulePath`. Throws `DirectoryRuleAlreadyExistsError` when a rule for that exact path already exists (`updateDirectoryRule` changes one), and `DirectoryRuleMissingTargetError` when neither `configProfile` nor `identity` is given, since a rule that pins neither would do nothing.
+ */
+export declare function addDirectoryRule(paths: LayoutPaths, rulePath: string, options: AddDirectoryRuleOptions): DirectoryRule;
+/** The fields `updateDirectoryRule` changes. A value of `false` removes that field from the rule. */
+export interface UpdateDirectoryRuleOptions {
+    readonly configProfile?: string | false;
+    readonly identity?: string | false;
+}
+/**
+ * Updates the existing directory rule for `rulePath` in place, keeping its position in the file and every field not named. Throws `DirectoryRuleNotFoundError` when no rule matches that exact path, and `DirectoryRuleMissingTargetError` when the update would leave a rule that does nothing (remove it with `removeDirectoryRule` instead).
+ */
+export declare function updateDirectoryRule(paths: LayoutPaths, rulePath: string, options: UpdateDirectoryRuleOptions): DirectoryRule;
+/** Removes the directory rule for `rulePath`. Throws `DirectoryRuleNotFoundError` when no rule matches that exact path. */
+export declare function removeDirectoryRule(paths: LayoutPaths, rulePath: string): void;

package/dist/types/headroom/headers.d.ts

@@ -0,0 +1,11 @@
+/** One `ANTHROPIC_CUSTOM_HEADERS` entry as the child environment carries it. */
+export interface CustomHeaderEntry {
+    readonly name: string;
+    readonly value: string;
+}
+/**
+ * Merges `ANTHROPIC_CUSTOM_HEADERS` blocks: every string in `existing` (as Claude Code writes them, `Name: Value` entries separated by newlines) parsed in order, then every entry of `additions` set on top, so a later block replaces an earlier block's value for the same header name while leaving every other entry untouched. The result is re-serialised in first-seen order with additions updated in place.
+ *
+ * Blank lines are skipped on parse; a header name keeps its own case exactly as written, since header names are case-insensitive on the wire but a statusline or log reading this value back should see what was set.
+ */
+export declare function mergeAnthropicCustomHeaders(existing: readonly (string | undefined)[], additions: readonly CustomHeaderEntry[]): string;

package/dist/types/identityStore.d.ts

@@ -0,0 +1,85 @@
+import { type CredentialCache, type CredentialSource, type CredentialTarget, type Identity } from "./config/schema";
+import { CliError } from "./cliError";
+import type { LayoutPaths } from "./paths";
+/** Raised by any operation that requires an identity to already exist, when it does not. */
+export declare class IdentityNotFoundError extends CliError {
+    readonly name: string;
+    constructor(name: string);
+}
+/** Raised by `addIdentity` when an identity with the given name already has an `identity.json`. */
+export declare class IdentityAlreadyExistsError extends CliError {
+    readonly identityName: string;
+    constructor(identityName: string);
+}
+/** Raised by `addIdentity` when `name` fails `IdentitySchema`'s own naming rule — it must start with a letter or number and may then contain letters, numbers, dots, hyphens, underscores, and at signs, so an email address names an identity directly while a *leading* `@` stays invalid (it would collide with the `@name` selector syntax's first-`@` split). */
+export declare class InvalidIdentityNameError extends CliError {
+    readonly attemptedName: string;
+    constructor(attemptedName: string);
+}
+export declare function identityExists(paths: LayoutPaths, name: string): boolean;
+/** Reads and validates one identity's `identity.json`, or undefined when it does not exist. */
+export declare function readIdentity(paths: LayoutPaths, name: string): Identity | undefined;
+/**
+ * Creates a new identity: validates `name` against `IdentitySchema`'s own naming rule and writes a fresh `identity.json` with `allowAmbientCredential: false` and no `defaultConfigProfile`.
+ *
+ * Throws `IdentityAlreadyExistsError` if an identity with this name already has an `identity.json` — `add` never silently overwrites an existing identity. Throws `InvalidIdentityNameError` when `name` fails `IdentitySchema`'s naming rule, rather than letting the underlying `ZodError` escape as an unhandled crash.
+ */
+export declare function addIdentity(paths: LayoutPaths, name: string): Identity;
+/**
+ * Persists `name` as the active identity, written atomically as plain text (not JSON — this file is read by `decideIdentity` in `src/launcher/identity.ts` via a simple UTF-8 read-and-trim, matching the README's documented `~/.agent-shim/active-identity` file).
+ *
+ * `name` may be a `pool:<name>` selector, which makes launches pick a member of that pool. Throws `IdentityNotFoundError` when no identity with this name exists yet, and `PoolNotFoundError` for a pool that is not defined: selecting either would silently persist a name nothing else can ever load.
+ */
+export declare function useIdentity(paths: LayoutPaths, name: string): void;
+/** Reads the persisted active-identity file, or undefined when none is set. */
+export declare function readActiveIdentity(paths: LayoutPaths): string | undefined;
+/**
+ * Whether a directory name directly under `identitiesDir` names an actual identity, rather than one of agent-shim's own farm directories.
+ *
+ * `IdentitySchema` requires an identity name to start with a letter or digit, so a leading `.` can only be a resync's own bookkeeping: a `.<identity>.scratch.<suffix>` tree still being built, or a `.<identity>.previous.<suffix>` superseded farm retained for `agent-shim identity resolve-conflicts`. Neither is an identity, and neither should be reported as a broken one for lacking an `identity.json` a resync never put there.
+ */
+export declare function isIdentityDirectoryName(name: string): boolean;
+/** One identity as reported by `listIdentities`, whose `identity.json` parsed and validated cleanly. */
+export interface IdentityListEntry {
+    readonly name: string;
+    readonly identity: Identity;
+    readonly isActive: boolean;
+    readonly problem?: never;
+}
+/** One identity whose `identity.json` is present but unreadable — malformed JSON, or valid JSON this version's `IdentitySchema` rejects. `problem` carries the reason, already flattened onto a single line. */
+export interface UnreadableIdentityListEntry {
+    readonly name: string;
+    readonly identity?: never;
+    readonly isActive: boolean;
+    readonly problem: string;
+}
+/** Either shape `listIdentities` can report, discriminated by which of `identity`/`problem` is present rather than by a tag field — the two are never simultaneously satisfiable. */
+export type IdentityListing = IdentityListEntry | UnreadableIdentityListEntry;
+/**
+ * Lists every identity under `identitiesDir`, marking which one (if any) is currently active.
+ *
+ * One identity whose `identity.json` cannot be read is reported as its own `UnreadableIdentityListEntry` rather than aborting the whole listing. A single bad file blocking `identity list` outright is exactly the failure mode that hides every *other* identity from view at the moment the user most needs to see them — and the file need not even be corrupt to land here, since a name written by a newer agent-shim whose naming rule has since widened is rejected outright by an older binary's own copy of `IdentitySchema`.
+ */
+export declare function listIdentities(paths: LayoutPaths): readonly IdentityListing[];
+/**
+ * Sets `identity`'s `defaultConfigProfile` field, or clears it when `profileName` is undefined. Throws `IdentityNotFoundError` when the identity does not exist. Whether the profile exists is the caller's concern: `identity set --default-profile` checks it first.
+ */
+export declare function setDefaultConfigProfile(paths: LayoutPaths, identityName: string, profileName: string | undefined): Identity;
+/**
+ * Patches `identity`'s `allowAmbientCredential` field. Throws `IdentityNotFoundError` when the identity does not exist.
+ */
+export declare function setAllowAmbientCredential(paths: LayoutPaths, identityName: string, allow: boolean): Identity;
+/** The change `setIdentityCredential` makes: new sources and/or a new target for the credential block, or `false` to remove the block and return the identity to its stored login. */
+export type IdentityCredentialChange = {
+    readonly sources?: readonly CredentialSource[];
+    readonly target?: CredentialTarget;
+    readonly cache?: CredentialCache | false;
+} | false;
+/**
+ * Sets, changes or removes `identityName`'s credential block. New `sources` replace the whole ordered list (the order is the meaning); a `target` alone keeps the existing sources, and so needs a credential block to exist already. Throws `IdentityNotFoundError` when the identity does not exist, and `UsageError` when only a target is given for an identity with no credential yet.
+ */
+export declare function setIdentityCredential(paths: LayoutPaths, identityName: string, change: IdentityCredentialChange): Identity;
+/**
+ * Deletes identity `name` entirely: its directory under `identitiesDir` (the farm, its `identity.json`, and whatever that farm holds unshared, credentials included), its resync lock, any scratch or superseded farm a resync left behind, and the active-identity selection when it names this identity. Data shared into `~/.claude` stays there, since the farm only ever symlinks to it. Throws `IdentityNotFoundError` when the identity does not exist.
+ */
+export declare function removeIdentity(paths: LayoutPaths, name: string): void;

package/dist/types/index.d.ts

@@ -7,6 +7,8 @@
  * - the per-identity usage snapshot a statusline or launcher reads: its schema and the reader over an injected filesystem;
  * - the state root's layout (`resolveAgentShimHome`, `resolveLayoutPaths`, `buildLayoutPaths`), which includes adopting an existing `~/.claude-use` in place, and the Zod schema and inferred type of every configuration file (identity, configuration profile, provider, pool, directory rules, global config, credential), so a tool can validate or generate them with the same definitions the CLI uses.
  *
+ * Creating and changing identities, configuration profiles, providers, pools and directory rules: the `*Store` modules, which take the state root's `LayoutPaths`, return typed values and throw `CliError` subclasses.
+ *
  * Everything the CLI alone needs (commander wiring, prompts, `doctor`, `check`) is deliberately not exported here.
  */
 export { resolveDecisions, topLevelNames, type ResolveDecisionsInput, type ResolvedState } from "./resolve/pipeline";
@@ -24,3 +26,8 @@ export { AMBIENT_CREDENTIAL_VARS, detectAmbientCredential, evaluateAmbientCreden
 export { buildLayoutPaths, resolveAgentShimHome, resolveClaudeHome, resolveLayoutPaths, type LayoutPaths } from "./paths";
 export { CliError, EXIT_FAILURE, EXIT_USAGE, UsageError } from "./cliError";
 export { CategoryClassificationOverlaySchema, CategoryClassificationSchema, CategoryMapSchema, ConfigProfileSchema, CredentialCacheSchema, CredentialSchema, CredentialSourceSchema, DirectoryRuleSchema, DirectoryRulesSchema, EntryValueSchema, GlobalConfigSchema, IdentitySchema, PoolNameSchema, PoolSchema, PortableConfigSchema, ProviderSchema, WhenSchema, type CategoryMap, type ConfigProfile, type Credential, type CredentialSource, type DirectoryRule, type DirectoryRules, type EntryValue, type GlobalConfig, type Identity, type Pool, type PortableConfig, type Provider, type WhenCondition, } from "./config/schema";
+export { addIdentity, IdentityAlreadyExistsError, IdentityNotFoundError, identityExists, InvalidIdentityNameError, isIdentityDirectoryName, listIdentities, readActiveIdentity, readIdentity, removeIdentity, setAllowAmbientCredential, setDefaultConfigProfile, setIdentityCredential, useIdentity, type IdentityCredentialChange, type IdentityListEntry, type IdentityListing, type UnreadableIdentityListEntry, } from "./identityStore";
+export { createProfile, InvalidCategoryNameError, listProfiles, ProfileAlreadyExistsError, ProfileNotFoundError, profileExists, readGlobalConfig, readProfile, removeProfile, setGlobalDefaultProfile, setProfileCategories, setProfileEntries, setProfileLaunchFlags, setProfileMetadata, type ProfileListEntry, } from "./configProfilesStore";
+export { addProvider, describeProviderEndpoint, InvalidProviderNameError, LegacyProviderFileError, listProviders, ProviderAlreadyExistsError, ProviderKindMismatchError, ProviderNotFoundError, providerExists, readProvider, removeProvider, updateProvider, type AddProviderInput, type ProviderListEntry, type UpdateProviderInput, } from "./providersStore";
+export { addPool, PoolNotFoundError, readPools, removePool, requirePool, setPool } from "./poolStore";
+export { addDirectoryRule, DirectoryRuleAlreadyExistsError, DirectoryRuleMissingTargetError, DirectoryRuleNotFoundError, listDirectoryRules, readDirectoryRules, removeDirectoryRule, updateDirectoryRule, writeDirectoryRules, type AddDirectoryRuleOptions, type UpdateDirectoryRuleOptions, } from "./directoryRulesStore";

package/dist/types/launcher/flags.d.ts

@@ -0,0 +1,96 @@
+import type { LaunchFlags, Provider } from "../config/schema";
+import { type ResolvedCredential } from "../credential";
+import type { FrontDoorUp, HeadroomUp } from "./ports";
+/** The fully resolved launch flags for one launch. */
+export interface ResolvedLaunchFlags {
+    readonly skipPermissions: boolean;
+    readonly remoteControl: boolean;
+    readonly headroom: boolean;
+    /** Whether the launch routes through the front door so its requests are recorded, even with no provider and no headroom. */
+    readonly trackUsage: boolean;
+}
+/** The one-off command-line forms of the four boolean launch flags, each undefined when neither its positive nor its `--no-` form was given. */
+interface LaunchFlagOverrides {
+    readonly skipPermissions?: boolean;
+    readonly remoteControl?: boolean;
+    readonly headroom?: boolean;
+    readonly trackUsage?: boolean;
+}
+/** Inputs to `resolveLaunchFlags`. */
+export interface ResolveLaunchFlagsParams {
+    /** The cascade's resolved `launch` block, when a cascade was loaded for this launch. */
+    readonly cascade?: LaunchFlags;
+    /** The launch's own `--[no-]skip-permissions`, `--[no-]remote-control`, `--[no-]headroom` and `--[no-]track-usage` flags. */
+    readonly flags?: LaunchFlagOverrides;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** What `trackUsage` is when no flag, environment variable or cascade setting says: off, except for a pool launch, whose pick reads the usage the front door records. */
+    readonly trackUsageDefault?: boolean;
+}
+/**
+ * Resolves `skipPermissions`/`remoteControl`/`headroom`/`trackUsage` for one launch. Each setting has the same three forms, decided in the same order: an explicit command-line flag outright, then its environment variable (`AGENT_SHIM_SKIP_PERMISSIONS`, `AGENT_SHIM_REMOTE_CONTROL`, `AGENT_SHIM_HEADROOM`, `AGENT_SHIM_TRACK_USAGE`), then the cascade, and OFF when none of them says otherwise (`trackUsageDefault` changes that one fallback). The flag outranks the environment variable because it is the more deliberate of the two one-off forms (typed on this very command line, not inherited from a shell profile), and both outrank the cascade because they are one-off overrides of it.
+ *
+ * Environment variables read with the shared boolean vocabulary (`true`/`1`, `false`/`0`), so `AGENT_SHIM_SKIP_PERMISSIONS=0` switches off a cascade's `skipPermissions: true` for one launch; any other value throws `InvalidEnvBoolError`.
+ *
+ * This default-off posture is a deliberate change from the legacy bash tool, which passed `--dangerously-skip-permissions` unconditionally on every launch.
+ */
+export declare function resolveLaunchFlags(params: ResolveLaunchFlagsParams): ResolvedLaunchFlags;
+/**
+ * Builds the tool's own flag arguments from resolved launch flags.
+ *
+ * `--remote-control=` always carries a literal trailing `=` with an empty value — never bare `--remote-control` — confirmed as a deliberate fix in the legacy script's own git history to stop the flag from consuming the next positional argument as its value.
+ */
+export declare function buildFlagArgs(flags: ResolvedLaunchFlags): string[];
+/** Inputs to `buildArgv`. */
+export interface BuildArgvParams {
+    readonly toolFlags: readonly string[];
+    readonly extraFlags: readonly string[];
+    readonly passthrough: readonly string[];
+}
+/**
+ * Assembles the final argv passed to the real `claude` binary: tool flags, then `$CLAUDE_EXTRA_FLAGS`, then the user's own forwarded arguments, in that exact order.
+ *
+ * Extra flags must land BEFORE the passthrough args — confirmed load-bearing against real wrapper scripts (`cpl`, `mp`, `zpl`) that set `CLAUDE_EXTRA_FLAGS="--print"` and then pass a positional prompt afterwards; reversing this order would feed the prompt to `--print` as if it were a flag value instead of a trailing positional.
+ */
+export declare function buildArgv(params: BuildArgvParams): string[];
+/** The provider resolved for this launch, with its credential already resolved from the provider's credential block. */
+export interface ResolvedProvider {
+    readonly name: string;
+    readonly definition: Provider;
+    readonly credential: ResolvedCredential;
+}
+/** A resolved provider with the base URL its sessions are sent to: the front door's provider-scoped address, which exists only once the door is up and is the same shape for both kinds (the door is what decides where the request goes from there). */
+export interface RoutedProvider extends ResolvedProvider {
+    readonly baseUrl: string;
+}
+/** Inputs to `buildEnv`. */
+export interface BuildEnvParams {
+    readonly baseEnv: Readonly<Record<string, string | undefined>>;
+    /** True when `CLAUDE_CONFIG_DIR` was already set and the escape hatch applied — `buildEnv` must leave it untouched in that case. */
+    readonly configDirEscapeHatch: boolean;
+    /** The identity name resolved for this launch, when one was resolved. */
+    readonly resolvedIdentityName?: string;
+    readonly identitiesDir: string;
+    /** The provider resolved for this launch, when one was resolved, with the base URL it routes to. Its credential is resolved by the caller because refusing an unusable one needs the caller's log/exit ports. */
+    readonly provider?: RoutedProvider;
+    /** The launching identity's own resolved credential, when it has a credential block and no provider was selected. A provider's credential authenticates against the provider's endpoint, so the identity's is never applied alongside one. */
+    readonly identityCredential?: ResolvedCredential;
+    /** The front door this launch routes through, when one is engaged (a provider is selected, or headroom resolved on). It is what the child talks to: its provider listener for a provider session, its CONNECT surface for an OAuth one. */
+    readonly frontdoor?: FrontDoorUp;
+    /** The headroom daemon this launch's requests must pass through (as the door's headroom hop), when headroom resolved on. The child never talks to it directly. */
+    readonly headroom?: HeadroomUp;
+    /** The per-launch session id, stamped into the session header the door identifies this launch's requests by. */
+    readonly sessionId: string;
+}
+/**
+ * Builds the environment the real `claude` binary is spawned with.
+ *
+ * When the `CLAUDE_CONFIG_DIR`-already-set escape hatch applied, or no identity was resolved at all (a bare launch with no active identity, matching the legacy script's own "no profile means plain `~/.claude`" behaviour), `CLAUDE_CONFIG_DIR` is left untouched. Otherwise `CLAUDE_CONFIG_DIR` is set to the resolved identity's own directory under `identitiesDir` — farm population into that directory is Phase 5's job, not this function's.
+ *
+ * A resolved provider is applied regardless of the identity outcome, because it selects which API endpoint the child talks to, not which login's data it sees: `ANTHROPIC_BASE_URL` points at the provider's routed base URL (always the front door's provider-scoped address), `AGENT_SHIM_PROVIDER` names the provider for the statusline, the provider's own `env` entries land verbatim, and its resolved credential is exported as its target's variable (`credentialVariables`), with the other credential variables removed so an ambient one inherited from the parent cannot outrank it. Without a provider, an identity's own resolved credential is exported the same way. The token only ever reaches this environment, never the child's argv or a log line.
+ *
+ * A resolved front door is the whole of the child's routing, on top of the provider: `ANTHROPIC_CUSTOM_HEADERS` gains the launcher-injected session headers (identity, session id, the launch's capability token, and, when headroom resolved on, the headroom flag and the project identity headroom scopes memory to), merged with any headers the provider's own `env` or the parent environment already set. The door strips every one of them before anything leaves the machine; the token is what authorises the session's requests at the door in the first place. `NODE_EXTRA_CA_CERTS` points at the door's trust bundle in both modes, because the child reaches the door over TLS signed by agent-shim's CA either way. With a provider, the child's HTTPS base URL already names the door's provider listener, so a process that merely binds that port cannot present a certificate the child accepts. Without one (an OAuth launch), the base URL is left exactly as the parent environment had it, because Claude Code enables Remote Control and connectors only against the real `api.anthropic.com`; routing happens one layer down instead, with `HTTPS_PROXY` pointing the child at the door's CONNECT surface and carrying the launch's capability as its proxy credential (the surface refuses any CONNECT without a live one), so the child still believes it is talking to the real `api.anthropic.com` while the surface's terminated TLS feeds the routed paths to the same pipeline. `HEADROOM_PROXY_URL` names the headroom daemon for anything else that wants it; the child never talks to that daemon directly, the door's hop does.
+ *
+ * `$CLAUDE_EXTRA_FLAGS` is never stripped from the child's environment: some wrappers set it two process-levels up and rely on inheritance through a `claude` invoked from inside a running session.
+ */
+export declare function buildEnv(params: BuildEnvParams): Record<string, string | undefined>;
+export {};