@vellumai/assistant 0.12.2-staging.1 → 0.12.2-staging.2

package/src/acp/acp-claude-oauth.ts

@@ -8,18 +8,29 @@
  * builds one against the manual redirect page and parses the `code#state`
  * string the user copies back. Both converge on `storeAcpClaudeToken`, which
  * writes the `acp/claude_oauth_token` vault field the ACP broker reads at
- * spawn time and provisions the `acp_spawn` read policy.
+ * spawn time, persists any refresh token and expiry the exchange returned,
+ * and provisions the `acp_spawn` read policy.
+ *
+ * Refresh, expiry, and the bound-access digest are stored without credential
+ * metadata so the broker cannot hand them to a spawned agent. The policy for
+ * when to spend the refresh token lives in `claude-token-refresh.ts`.
  */
 
+import { computeExpiresAt, isTokenExpired } from "@vellumai/credential-storage";
+
 import { credentialKey } from "../security/credential-key.js";
 import type { OAuth2Config } from "../security/oauth2.js";
 import {
+  deleteSecureKeyAsync,
   getSecureKeyAsync,
   setSecureKeyAsync,
 } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";
 import { claudeTokenDigest } from "./acp-auth-marker-store.js";
 import {
+  ACP_OAUTH_ACCESS_DIGEST_FIELD,
+  ACP_OAUTH_EXPIRES_AT_FIELD,
+  ACP_OAUTH_REFRESH_TOKEN_FIELD,
   ACP_OAUTH_TOKEN_FIELD,
   ACP_SERVICE,
   classifyAnthropicToken,
@@ -32,6 +43,22 @@ import {
 
 const log = getLogger("acp:claude-oauth");
 
+/**
+ * Serializes every Claude OAuth token-set write (Connect, renewal persist,
+ * companion clear) so a compare-and-write cannot interleave with another
+ * writer. The network refresh itself stays outside this queue.
+ */
+let tokenWriteQueue: Promise<unknown> = Promise.resolve();
+
+function withAcpClaudeTokenWrite<T>(fn: () => Promise<T>): Promise<T> {
+  const run = tokenWriteQueue.then(fn, fn);
+  tokenWriteQueue = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  return run;
+}
+
 /**
  * Verified Claude Code public OAuth client. PKCE-only (no client secret);
  * the single `user:inference` scope is what the ACP adapter's
@@ -137,20 +164,103 @@ export async function storedClaudeTokenDigest(): Promise<string | undefined> {
   return token ? claudeTokenDigest(token) : undefined;
 }
 
+/** Tokens as returned by an authorization-code exchange or a refresh. */
+export interface AcpClaudeTokens {
+  accessToken: string;
+  refreshToken?: string;
+  /** Lifetime in seconds, as the provider reports it. */
+  expiresIn?: number;
+}
+
+function vaultKey(field: string): string {
+  return credentialKey(ACP_SERVICE, field);
+}
+
+/**
+ * Write a companion field, or delete it when there is no value.
+ *
+ * Both outcomes are checked. The store signals failure by return value rather
+ * than by throwing (`setSecureKeyAsync` returns false, `deleteSecureKeyAsync`
+ * returns `"error"` on timeout), so ignoring them would let a backend hiccup
+ * report success while leaving the token-set fields out of sync: an access
+ * token with no way to renew it, or a new access token still paired with a
+ * previous connect's refresh token.
+ */
+async function writeOrClear(
+  field: string,
+  value: string | undefined,
+): Promise<void> {
+  if (value) {
+    const stored = await setSecureKeyAsync(vaultKey(field), value);
+    if (!stored) {
+      throw new Error(
+        `Failed to store Claude OAuth ${field} in secure storage.`,
+      );
+    }
+    return;
+  }
+  const result = await deleteSecureKeyAsync(vaultKey(field));
+  if (result === "error") {
+    throw new Error(
+      `Failed to clear Claude OAuth ${field} from secure storage.`,
+    );
+  }
+}
+
+/**
+ * Write a Claude OAuth token set to the `acp/claude_oauth_*` vault fields.
+ * Throws when the backing store rejects any of the writes.
+ *
+ * The refresh token and expiry are written as a set with the access token:
+ * when the provider returns neither, any previously stored values are cleared
+ * rather than left behind. A stale refresh token paired with a newly connected
+ * access token would otherwise renew into the credential from a previous
+ * connect.
+ *
+ * Only the access-token field gets credential metadata. `serverUse` refuses
+ * any field without metadata, so the refresh token and expiry stay
+ * unreachable through the broker and cannot be injected into a spawned
+ * agent's env.
+ */
+async function writeConnectedTokenSet(tokens: AcpClaudeTokens): Promise<void> {
+  await withAcpClaudeTokenWrite(async () => {
+    const stored = await setSecureKeyAsync(
+      vaultKey(ACP_OAUTH_TOKEN_FIELD),
+      tokens.accessToken,
+    );
+    if (!stored) {
+      throw new Error("Failed to store Claude OAuth token in secure storage.");
+    }
+
+    await writeOrClear(ACP_OAUTH_REFRESH_TOKEN_FIELD, tokens.refreshToken);
+    const expiresAt = computeExpiresAt(tokens.expiresIn);
+    await writeOrClear(
+      ACP_OAUTH_EXPIRES_AT_FIELD,
+      expiresAt == null ? undefined : String(expiresAt),
+    );
+    const hasRenewal = Boolean(tokens.refreshToken) || expiresAt != null;
+    await writeOrClear(
+      ACP_OAUTH_ACCESS_DIGEST_FIELD,
+      hasRenewal ? claudeTokenDigest(tokens.accessToken) : undefined,
+    );
+  });
+}
+
 /**
- * Store a captured Claude OAuth token in the `acp/claude_oauth_token` vault
- * field and provision the policy the broker applies at spawn time: grant the
+ * Store a captured Claude OAuth token set in the `acp/claude_oauth_*` vault
+ * fields and provision the policy the broker applies at spawn time: grant the
  * `acp_spawn` read and lift any domain restriction. Throws when the backing
  * store rejects the write.
+ *
+ * A string argument is treated as an access-token-only write and clears any
+ * companion refresh or expiry fields so they cannot describe a previous token.
  */
-export async function storeAcpClaudeToken(token: string): Promise<void> {
-  const stored = await setSecureKeyAsync(
-    credentialKey(ACP_SERVICE, ACP_OAUTH_TOKEN_FIELD),
-    token,
-  );
-  if (!stored) {
-    throw new Error("Failed to store Claude OAuth token in secure storage.");
-  }
+export async function storeAcpClaudeToken(
+  tokens: string | AcpClaudeTokens,
+): Promise<void> {
+  const tokenSet: AcpClaudeTokens =
+    typeof tokens === "string" ? { accessToken: tokens } : tokens;
+  await writeConnectedTokenSet(tokenSet);
   // Repair rather than merely ensure the policy: an explicit Connect is a
   // deliberate opt-in to ACP, so this widens a credential the broker would
   // otherwise keep denying the spawn read on, which would dead-loop the Connect
@@ -241,6 +351,11 @@ export async function notifyAcpConnectRetired(): Promise<void> {
  * spawn-time broker read applies, so "connected" means precisely "the spawn
  * would get this token". The token-shape guard stays here instead: the broker
  * knows nothing about Anthropic token formats.
+ *
+ * An expired token with no refresh token is the same shape of problem, and is
+ * likewise NOT connected: the card has to stay up so the user can reconnect.
+ * An expired token that still has a refresh token IS connected, because
+ * `ensureFreshAcpClaudeToken` renews it on the next spawn.
  */
 export async function hasAcpClaudeToken(): Promise<boolean> {
   return (await usableStoredClaudeToken()) !== undefined;
@@ -257,9 +372,7 @@ export async function hasAcpClaudeToken(): Promise<boolean> {
  * card and no working token.
  */
 async function usableStoredClaudeToken(): Promise<string | undefined> {
-  const token = await getSecureKeyAsync(
-    credentialKey(ACP_SERVICE, ACP_OAUTH_TOKEN_FIELD),
-  );
+  const token = await getSecureKeyAsync(vaultKey(ACP_OAUTH_TOKEN_FIELD));
   if (token == null || token.length === 0) {
     return undefined;
   }
@@ -274,6 +387,15 @@ async function usableStoredClaudeToken(): Promise<string | undefined> {
     );
     return undefined;
   }
+  if (await isAcpClaudeTokenExpiring()) {
+    const boundDigest = await readBoundAccessDigest();
+    if (boundDigest && boundDigest !== claudeTokenDigest(token)) {
+      return token;
+    }
+    if (!(await hasAcpClaudeRefreshToken())) {
+      return undefined;
+    }
+  }
   return token;
 }
 
@@ -326,3 +448,195 @@ export async function acpConnectCardStillWarranted(
     await import("./acp-auth-marker-store.js");
   return claudeCredentialRefused(resolved);
 }
+
+/**
+ * Persist a token set obtained by renewing an existing credential, leaving
+ * the read policy exactly as it was.
+ *
+ * A renewal happens on a passive spawn with no user in the loop, so it must
+ * not widen what the credential is allowed to do. Granting `acp_spawn` here
+ * would let a background refresh restore a permission a user or admin had
+ * removed from `allowedTools`.
+ *
+ * A rotated refresh token is written when the provider returns one. When the
+ * response omits a refresh token, the stored refresh token is kept so a
+ * non-rotating grant does not lose its renewal material. A missing or
+ * non-positive `expiresIn` clears the recorded expiry so a stale past expiry
+ * cannot condemn the new access token.
+ *
+ * `expectedRefreshToken` is the refresh token this request spent. If the
+ * vault no longer holds that value, the access-token field is gone, or the
+ * stored access token is not the one this refresh material was written
+ * with, the persist is skipped so a newer token set is not overwritten and
+ * a deleted or pasted credential is not replaced. Returns whether the write
+ * happened.
+ */
+export async function persistRefreshedAcpClaudeTokens(
+  tokens: AcpClaudeTokens,
+  expectedRefreshToken: string,
+): Promise<boolean> {
+  if (!tokens.accessToken) {
+    throw new Error("Refreshed Claude OAuth response had no access token.");
+  }
+  return withAcpClaudeTokenWrite(async () => {
+    const current = await readAcpClaudeRefreshToken();
+    if (current !== expectedRefreshToken) {
+      log.info(
+        "Skipping Claude OAuth refresh persist because the stored refresh token changed while the request was in flight",
+      );
+      return false;
+    }
+    const access = await getSecureKeyAsync(vaultKey(ACP_OAUTH_TOKEN_FIELD));
+    if (access == null || access.length === 0) {
+      log.info(
+        "Skipping Claude OAuth refresh persist because the access token is no longer stored",
+      );
+      return false;
+    }
+    if (!(await renewalIsBoundTo(access))) {
+      log.info(
+        "Skipping Claude OAuth refresh persist because the stored access token is not the one this refresh material was written with",
+      );
+      return false;
+    }
+    const stored = await setSecureKeyAsync(
+      vaultKey(ACP_OAUTH_TOKEN_FIELD),
+      tokens.accessToken,
+    );
+    if (!stored) {
+      throw new Error("Failed to store Claude OAuth token in secure storage.");
+    }
+    if (tokens.refreshToken) {
+      await writeOrClear(ACP_OAUTH_REFRESH_TOKEN_FIELD, tokens.refreshToken);
+    }
+    const expiresAt = computeExpiresAt(tokens.expiresIn);
+    await writeOrClear(
+      ACP_OAUTH_EXPIRES_AT_FIELD,
+      expiresAt == null ? undefined : String(expiresAt),
+    );
+    await writeOrClear(
+      ACP_OAUTH_ACCESS_DIGEST_FIELD,
+      claudeTokenDigest(tokens.accessToken),
+    );
+    return true;
+  });
+}
+
+/**
+ * The stored absolute expiry in epoch milliseconds, or null when unknown.
+ *
+ * Unknown is the norm for tokens connected before expiry was recorded, and is
+ * treated as "assume usable": we cannot tell fresh from expired, and guessing
+ * expired would refresh or discard a perfectly good token.
+ */
+async function readExpiresAt(): Promise<number | null> {
+  const raw = await getSecureKeyAsync(vaultKey(ACP_OAUTH_EXPIRES_AT_FIELD));
+  if (!raw) {
+    return null;
+  }
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+/**
+ * Whether the stored access token is past its recorded expiry, or close
+ * enough that it should be renewed before use. False when no expiry was
+ * recorded.
+ */
+export async function isAcpClaudeTokenExpiring(): Promise<boolean> {
+  return isTokenExpired(await readExpiresAt());
+}
+
+/** The stored refresh token, or null when none was captured. */
+export async function readAcpClaudeRefreshToken(): Promise<string | null> {
+  const token = await getSecureKeyAsync(vaultKey(ACP_OAUTH_REFRESH_TOKEN_FIELD));
+  return token != null && token.length > 0 ? token : null;
+}
+
+/** Whether renewal material is on hand, without revealing it. */
+export async function hasAcpClaudeRefreshToken(): Promise<boolean> {
+  return (await readAcpClaudeRefreshToken()) != null;
+}
+
+/**
+ * Whether the access-token vault field is present. Presence only: not
+ * whether the value is usable, expired, or readable by the spawn broker.
+ *
+ * Renewal spends a refresh token to replace this field. If the field is
+ * gone, there is no credential to renew.
+ */
+export async function hasStoredAcpClaudeAccessToken(): Promise<boolean> {
+  const token = await getSecureKeyAsync(vaultKey(ACP_OAUTH_TOKEN_FIELD));
+  return token != null && token.length > 0;
+}
+
+async function readBoundAccessDigest(): Promise<string | null> {
+  const digest = await getSecureKeyAsync(
+    vaultKey(ACP_OAUTH_ACCESS_DIGEST_FIELD),
+  );
+  return digest != null && digest.length > 0 ? digest : null;
+}
+
+async function renewalIsBoundTo(accessToken: string): Promise<boolean> {
+  const digest = await readBoundAccessDigest();
+  return digest != null && digest === claudeTokenDigest(accessToken);
+}
+
+async function clearRenewalFields(): Promise<void> {
+  await writeOrClear(ACP_OAUTH_REFRESH_TOKEN_FIELD, undefined);
+  await writeOrClear(ACP_OAUTH_EXPIRES_AT_FIELD, undefined);
+  await writeOrClear(ACP_OAUTH_ACCESS_DIGEST_FIELD, undefined);
+}
+
+/**
+ * Drop the refresh token, keeping the recorded expiry and the access token.
+ * Called when the provider rejects the refresh token.
+ *
+ * The expiry has to survive. `hasAcpClaudeToken()` reads "not connected" from
+ * the combination of an expired token and no refresh token. Clearing the
+ * expiry as well would make `readExpiresAt()` return null, which
+ * {@link isAcpClaudeTokenExpiring} treats as "assume usable", and the dead
+ * credential would report itself connected.
+ */
+export async function clearAcpClaudeRefreshToken(
+  expectedRefreshToken?: string,
+): Promise<void> {
+  await withAcpClaudeTokenWrite(async () => {
+    if (expectedRefreshToken !== undefined) {
+      const current = await readAcpClaudeRefreshToken();
+      if (current !== expectedRefreshToken) {
+        log.info(
+          "Skipping Claude OAuth refresh-token clear because the stored refresh token changed while the request was in flight",
+        );
+        return;
+      }
+    }
+    await writeOrClear(ACP_OAUTH_REFRESH_TOKEN_FIELD, undefined);
+  });
+}
+
+/**
+ * Drop refresh, expiry, and the bound-access digest when they do not describe
+ * the access token currently stored.
+ *
+ * Connect and persist write those fields as a set with the access token. A
+ * later paste or CLI write replaces only the access-token field. Spending the
+ * leftover refresh token would overwrite that replacement.
+ */
+export async function forgetAcpClaudeRenewalStateIfUnbound(): Promise<void> {
+  await withAcpClaudeTokenWrite(async () => {
+    const access = await getSecureKeyAsync(vaultKey(ACP_OAUTH_TOKEN_FIELD));
+    const refresh = await readAcpClaudeRefreshToken();
+    const expiresAt = await readExpiresAt();
+    const digest = await readBoundAccessDigest();
+    const hasRenewal = refresh != null || expiresAt != null || digest != null;
+    if (!hasRenewal) {
+      return;
+    }
+    if (access && digest && digest === claudeTokenDigest(access)) {
+      return;
+    }
+    await clearRenewalFields();
+  });
+}
+

package/src/acp/acp-credentials.ts

@@ -14,6 +14,25 @@
 export const ACP_SERVICE = "acp";
 export const ACP_OAUTH_TOKEN_FIELD = "claude_oauth_token";
 
+/**
+ * Refresh and expiry for {@link ACP_OAUTH_TOKEN_FIELD}, written by the Connect
+ * Claude exchange that stored that access token. Expiry is epoch milliseconds,
+ * matching `computeExpiresAt` and `isTokenExpired` in
+ * `@vellumai/credential-storage`.
+ *
+ * {@link ACP_OAUTH_ACCESS_DIGEST_FIELD} is a digest of the access token those
+ * fields were written with, so a later paste of a different access token cannot
+ * spend leftover refresh material.
+ *
+ * These fields are given no credential metadata. `credentialBroker.serverUse`
+ * refuses any field without metadata, so they stay unreachable through the
+ * broker and cannot be injected into a spawned agent's env. Only the access
+ * token crosses into the child process.
+ */
+export const ACP_OAUTH_REFRESH_TOKEN_FIELD = "claude_oauth_refresh_token";
+export const ACP_OAUTH_EXPIRES_AT_FIELD = "claude_oauth_expires_at";
+export const ACP_OAUTH_ACCESS_DIGEST_FIELD = "claude_oauth_access_digest";
+
 /**
  * True for the ACP vault field the "Connect Claude" flow owns
  * (`acp/claude_oauth_token`). Used to route this credential to the inline

package/src/acp/claude-token-refresh.ts

@@ -0,0 +1,150 @@
+/**
+ * Renewal policy for the Claude OAuth credential the ACP spawn path injects as
+ * `CLAUDE_CODE_OAUTH_TOKEN`. Storage lives in `acp-claude-oauth.ts`; this
+ * module owns only the decision to refresh and the handling of what comes back.
+ *
+ * Setting `CLAUDE_CODE_OAUTH_TOKEN` tells the Claude Agent SDK to treat the
+ * value as a static bearer token: its own credential store and refresh
+ * machinery are skipped entirely. The SDK does expose a host-refresh hook,
+ * `getOAuthToken`, but `claude-agent-acp` never passes it through and it is
+ * absent from the SDK's public typings. With the env-var contract the adapter
+ * gives us, the daemon is the only thing that can renew this token.
+ *
+ * Every failure mode here returns without throwing and lets the spawn proceed
+ * with whatever token is stored. A dead token then fails at the adapter as a
+ * structured ACP `auth_required`, which raises the Connect card. Renewal is
+ * the fast path, not the error path, so it must never be the thing that fails
+ * a spawn.
+ *
+ * When the provider rejects the refresh token itself (revoked, or rotated out
+ * from under us), the stored refresh token is dropped. The recorded expiry is
+ * kept, because that pair (expired, no way to renew) is what makes
+ * `hasAcpClaudeToken()` answer "not connected" and keep the inline Connect
+ * card on screen.
+ */
+
+import {
+  isCredentialError,
+  RefreshDeduplicator,
+} from "@vellumai/credential-storage";
+
+import { refreshOAuth2Token } from "../security/oauth2.js";
+import { getLogger } from "../util/logger.js";
+import {
+  CLAUDE_OAUTH_CONFIG,
+  clearAcpClaudeRefreshToken,
+  forgetAcpClaudeRenewalStateIfUnbound,
+  hasStoredAcpClaudeAccessToken,
+  isAcpClaudeTokenExpiring,
+  persistRefreshedAcpClaudeTokens,
+  readAcpClaudeRefreshToken,
+} from "./acp-claude-oauth.js";
+import { ACP_OAUTH_TOKEN_FIELD } from "./acp-credentials.js";
+import { acpSpawnCredentialDenialReason } from "./prepare-agent-env.js";
+
+const log = getLogger("acp:claude-token-refresh");
+
+/**
+ * Single in-flight refresh across concurrent spawns. Anthropic rotates the
+ * refresh token on use, so two parallel refreshes would race and one would
+ * invalidate the other's token.
+ */
+const deduplicator = new RefreshDeduplicator();
+const REFRESH_KEY = "acp:claude";
+
+/**
+ * Renew the stored Claude access token if it is expiring and a refresh token
+ * is available. Returns without throwing in every failure mode. Never returns
+ * the token: the plaintext read boundary stays with the credential broker, so
+ * callers re-read through it as usual.
+ */
+export async function ensureFreshAcpClaudeToken(): Promise<void> {
+  // An explicit `allowedTools` that omits `acp_spawn` means the broker will
+  // deny the read this renewal exists to feed, so there is nothing to gain by
+  // spending a refresh token here. Checking first also keeps a passive spawn
+  // from touching a credential the workspace has fenced off.
+  if (acpSpawnCredentialDenialReason(ACP_OAUTH_TOKEN_FIELD) !== undefined) {
+    return;
+  }
+  // Companions can outlive a deleted access token. Renewal exists to replace
+  // that field, not to mint a new credential after the user removed it.
+  if (!(await hasStoredAcpClaudeAccessToken())) {
+    return;
+  }
+  try {
+    await forgetAcpClaudeRenewalStateIfUnbound();
+  } catch (err) {
+    log.debug(
+      { err },
+      "Could not drop unbound Claude OAuth renewal state before refresh",
+    );
+  }
+  if (!(await isAcpClaudeTokenExpiring())) {
+    return;
+  }
+
+  const refreshToken = await readAcpClaudeRefreshToken();
+  if (!refreshToken) {
+    log.info(
+      "Claude OAuth token is expiring and no refresh token is stored; " +
+        "the spawn will surface auth_required so the user can reconnect",
+    );
+    return;
+  }
+
+  try {
+    await deduplicator.deduplicate(REFRESH_KEY, () => doRefresh(refreshToken));
+  } catch (err) {
+    log.debug({ err }, "Claude OAuth token refresh did not complete");
+  }
+}
+
+async function doRefresh(refreshToken: string): Promise<string> {
+  log.info("Refreshing the Claude OAuth token for ACP");
+
+  let result;
+  try {
+    result = await refreshOAuth2Token(
+      CLAUDE_OAUTH_CONFIG.tokenExchangeUrl,
+      CLAUDE_OAUTH_CONFIG.clientId,
+      refreshToken,
+      // PKCE public client, so no secret. Anthropic's token endpoint takes a
+      // JSON body, matching the authorization-code exchange.
+      undefined,
+      undefined,
+      CLAUDE_OAUTH_CONFIG.tokenExchangeBodyFormat,
+    );
+  } catch (err) {
+    if (isCredentialError(err)) {
+      log.warn(
+        { err },
+        "Claude OAuth refresh token was rejected; dropping it so the account reads as needing a reconnect",
+      );
+      await clearAcpClaudeRefreshToken(refreshToken);
+    } else {
+      log.warn({ err }, "Claude OAuth token refresh failed transiently");
+    }
+    throw err;
+  }
+
+  if (!result.accessToken) {
+    log.warn(
+      "Claude OAuth refresh returned no usable access token; dropping the refresh token so the account reads as needing a reconnect",
+    );
+    await clearAcpClaudeRefreshToken(refreshToken);
+    throw new Error("Claude OAuth refresh returned no access token");
+  }
+
+  const persisted = await persistRefreshedAcpClaudeTokens(
+    {
+      accessToken: result.accessToken,
+      refreshToken: result.refreshToken,
+      expiresIn: result.expiresIn,
+    },
+    refreshToken,
+  );
+  if (persisted) {
+    log.info("Claude OAuth token refreshed");
+  }
+  return result.accessToken;
+}

package/src/acp/prepare-agent-env.ts

@@ -199,6 +199,26 @@ export function acpSpawnCredentialDenialReason(
  * mode, including a simply-absent credential, as `{ success: false,
  * reason }`, so callers choose whether a miss is fatal.
  */
+/**
+ * Vault path for `CLAUDE_CODE_OAUTH_TOKEN`. Renews first so a near-expired
+ * stored token is replaced before the broker read. Config overrides never
+ * reach here, so this does not spend the vault refresh token on a spawn
+ * that will not use it.
+ */
+async function injectClaudeOauthFromVault(
+  env: Record<string, string>,
+): Promise<string | undefined> {
+  const { ensureFreshAcpClaudeToken } =
+    await import("./claude-token-refresh.js");
+  await ensureFreshAcpClaudeToken();
+  return injectCredential(
+    env,
+    ACP_OAUTH_TOKEN_FIELD,
+    "CLAUDE_CODE_OAUTH_TOKEN",
+    ACP_CLAUDE_OAUTH_USAGE_DESCRIPTION,
+  );
+}
+
 async function injectCredential(
   env: Record<string, string>,
   field: string,
@@ -371,12 +391,7 @@ export async function prepareAgentEnv(
     }
     let missReason: string | undefined;
     if (!env.CLAUDE_CODE_OAUTH_TOKEN) {
-      missReason = await injectCredential(
-        env,
-        ACP_OAUTH_TOKEN_FIELD,
-        "CLAUDE_CODE_OAUTH_TOKEN",
-        ACP_CLAUDE_OAUTH_USAGE_DESCRIPTION,
-      );
+      missReason = await injectClaudeOauthFromVault(env);
     }
     // Any api-key-shaped value still standing here came from the vault read:
     // the config override was already dropped above, and the read only runs

package/src/calls/__tests__/voice-control-protocol.test.ts

@@ -6,7 +6,10 @@ import {
   HOLD_VERDICT_TOKEN,
   isIncompleteControlMarkerTail,
   MINIMIZE_ROOM_MARKER,
+  parseTerminalSessionControl,
+  type SessionControlRequest,
   stripInternalSpeechMarkers,
+  terminalControlMarkerLength,
 } from "../voice-control-protocol.js";
 
 describe("front-door verdict tokens", () => {
@@ -136,3 +139,62 @@ describe("createControlMarkerHoldback", () => {
     expect(chunks).toEqual([]);
   });
 });
+
+describe("session control markers", () => {
+  test("strips untimed and timed mute markers", () => {
+    expect(stripInternalSpeechMarkers("Muted. [MUTE]").trim()).toBe("Muted.");
+    expect(stripInternalSpeechMarkers("Muted. [MUTE:30]").trim()).toBe(
+      "Muted.",
+    );
+  });
+
+  test("holds a streaming timed mute until its bracket arrives", () => {
+    expect(isIncompleteControlMarkerTail("[MU")).toBe(true);
+    expect(isIncompleteControlMarkerTail("[MUTE:3")).toBe(true);
+    expect(isIncompleteControlMarkerTail("[MUTE:30]")).toBe(false);
+    expect(isIncompleteControlMarkerTail("[UPDATES:FEW")).toBe(true);
+    expect(isIncompleteControlMarkerTail("[UPDATES:FEWER]")).toBe(false);
+  });
+
+  test.each([
+    ["Okay, talk soon. [END_CALL]", { action: "end" }],
+    ["Muted. [MUTE]", { action: "mute" }],
+    [
+      "I'll check in less. [UPDATES:FEWER]",
+      { action: "updates", cadence: "fewer" },
+    ],
+    [
+      "Updates are back on. [UPDATES:NORMAL]",
+      { action: "updates", cadence: "normal" },
+    ],
+    [
+      "Muting for half a minute. [MUTE:30]  ",
+      { action: "mute", durationMs: 30_000 },
+    ],
+    ["Muted. [MUTE: 1.5]", { action: "mute", durationMs: 1_500 }],
+    // A garbled or oversized duration still mutes, just until unmuted.
+    ["Muted. [MUTE:soon]", { action: "mute" }],
+    ["Muted. [MUTE:0]", { action: "mute" }],
+    ["Muted. [MUTE:99999]", { action: "mute" }],
+  ] as Array<[string, SessionControlRequest]>)(
+    "parses the terminal control in %j",
+    (text, expected) => {
+      expect(parseTerminalSessionControl(text)).toEqual(expected);
+    },
+  );
+
+  test("a marker anywhere but the end controls nothing", () => {
+    expect(
+      parseTerminalSessionControl("Say [END_CALL] and I would hang up."),
+    ).toBeNull();
+    expect(parseTerminalSessionControl("No markers here.")).toBeNull();
+  });
+
+  test("measures the terminal marker the transcript pass strips", () => {
+    expect(terminalControlMarkerLength("Done [-1]")).toBe(4);
+    expect(terminalControlMarkerLength("Bye [END_CALL] ")).toBe(10);
+    expect(terminalControlMarkerLength("Muted [MUTE:30]")).toBe(9);
+    expect(terminalControlMarkerLength("Okay [UPDATES:FEWER]")).toBe(15);
+    expect(terminalControlMarkerLength("The array [-1] sorts")).toBe(0);
+  });
+});