@falkenslab/agent-kit 0.31.0 → 0.32.0

package/README.md

@@ -1,175 +1,175 @@
-<div align="center">
-
-<img src="https://raw.githubusercontent.com/falkenslab/agent-kit/main/docs/static/img/logo.svg" alt="agent-kit logo: three blue building blocks and a coral one being set in place" width="112"/>
-
-# agent-kit
-
-**Build an AI agent on Claude that asks before it acts, remembers, and chats like Claude Code.**<br/>
-You write what your agent knows and does; the kit brings oversight, safety, memory and the interface.
-
-[![npm](https://img.shields.io/npm/v/@falkenslab/agent-kit?color=cb3837&logo=npm)](https://www.npmjs.com/package/@falkenslab/agent-kit)
-![Node.js 20+](https://img.shields.io/badge/node-20%2B-339933?logo=node.js&logoColor=white)
-![Claude Agent SDK](https://img.shields.io/badge/Claude-Agent%20SDK-d97757?logo=anthropic&logoColor=white)
-![TypeScript](https://img.shields.io/badge/types-included-3178c6?logo=typescript&logoColor=white)
-[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](LICENSE)
-
-**[📖 Documentation](https://falkenslab.github.io/agent-kit/)** · [📖 Documentación en español](https://falkenslab.github.io/agent-kit/es/)
-
-</div>
-
-agent-kit is a foundation for building AI agents on top of the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk). It isn't an agent itself: it solves once what every agent needs (levels of oversight, approvals, safe limits, memory across sessions, extensions, and a terminal chat as good as Claude Code's), so each agent writes only what belongs to its own domain: what it knows how to do, with which tools, and how it talks. A teacher's assistant for Moodle and a pirate cat who tells jokes are built the same way.
-
-## ✨ Why agent-kit
-
-- 🎚️ **You choose how much it acts alone.** Autonomous, guided (it asks before what others will see or can't be undone), step by step, or a plan mode where it only reads and plans; switch among them in the same conversation.
-- ✋ **It asks a person, and the kit makes sure.** Approvals, choices, a file, a sign-in by hand; an installed extension's tool that changes things waits for a yes whatever the model decided, and answers can last for the session or for good.
-- 🧠 **It remembers.** A knowledge base that grows with every session, the original documents it learns from kept untouched, a memory of the person, and every conversation to pick up again with `--continue` or `/resume`.
-- 🛡️ **It stays within limits.** Only its own folders, never protected files, subagents that can't slip past the main agent's limits, secrets hidden from the logs, remote servers allowed, asked about or denied.
-- 🧩 **It grows with extensions.** Claude Code plugins with MCP servers, skills and commands, installed from a marketplace or a folder, with their own options, sign-in and a catalog in the chat; no Git needed.
-- 🌐 **It speaks your language.** Its interface in English, Spanish, French or German, and it answers in that language unless you write in another.
-- 🖥️ **A terminal chat like Claude Code's, or none at all.** Full screen, live markdown, folded tool calls, panels, history, themes; or the same agent inside a desktop app or a web page with its own interface.
-
-## 🚀 Quick start
-
-You need [Node.js](https://nodejs.org) 20 or later and a Claude account. In a project with `"type": "module"` in its `package.json`:
-
-```bash
-npm install @falkenslab/agent-kit tsx
-```
-
-Save this as `agent.ts`: the only part that's your agent's is the spec at the top.
-
-```ts
-import path from "node:path";
-import { buildSessionOptions, ensureClaudeAuth, runChatInk, type AgentSpec, type BaseSessionConfig } from "@falkenslab/agent-kit";
-
-const spec: AgentSpec<BaseSessionConfig> = {
-  buildSystemPrompt: () => "You are a pirate cat who tells jokes. Always answer in character.",
-  buildMcpServers: () => ({}), // its own MCP servers, if any
-  pluginRoots: () => [], // folders with skills and commands
-  buildSubagents: () => undefined, // subagents, if it delegates to any
-};
-
-await ensureClaudeAuth(); // offers to create a Claude token if it finds none
-const config: BaseSessionConfig = { mode: "guided", projectDir: process.cwd() };
-
-// Each run gets a folder under .run/ (keep it out of git): its log, transcript and conversation.
-await runChatInk((run) => buildSessionOptions(config, run.dir, spec, { run }), {
-  runsDir: path.resolve(".run"),
-  header: { title: "My agent" },
-  mode: config.mode, // Shift+Tab cycles through guided, step by step and plan
-  fullscreen: true,
-});
-```
-
-Run it with `npx tsx agent.ts`: a full-screen chat opens, in your system's language, and the agent asks before anything it shouldn't do alone. The [tutorial](https://falkenslab.github.io/agent-kit/docs/getting-started/first-agent) takes it from there.
-
-## 🧪 A taste of the code
-
-Give it a memory and a folder of sources, with the kit's own extensions:
-
-```ts
-import { knowledge, memory, sources } from "@falkenslab/agent-kit";
-
-const spec: AgentSpec<BaseSessionConfig> = {
-  // …
-  extensions: [sources({ dir: "sources" }), knowledge({ dir: "knowledge" }), memory({ dir: "memory" })],
-};
-```
-
-Let it install extensions from your marketplace, and keep its data from leaving the computer without asking:
-
-```ts
-const config: BaseSessionConfig = {
-  mode: "guided",
-  projectDir: process.cwd(),
-  extensionDirs: { agent: path.join(os.homedir(), ".my-agent", "extensions") },
-  officialMarketplace: "falkenslab/agent-extensions",
-  remoteServers: "ask",
-};
-```
-
-Make a tool always wait for the person's yes, on every call:
-
-```ts
-const spec: AgentSpec<BaseSessionConfig> = {
-  // …
-  extensionGate: { confirmTools: { canva: ["create-design", "publish-design"] } },
-};
-```
-
-## 📸 See it at work
-
-[Captain Whiskers](./examples/captain-whiskers), the kit's example agent: a retired pirate cat who tells jokes in your language, with a crew of subagents (one looks for new jokes on the web, one rates them, one tells the time), a logbook and an extension of his own. He runs in the terminal, in a browser and as a Windows app.
-
-<div align="center">
-
-<img src="https://raw.githubusercontent.com/falkenslab/agent-kit/main/docs/assets/captain-whiskers.png" alt="Captain Whiskers in Windows Terminal: his logo with the mode and the agent-kit version at the top, his crew at work in the middle, a task list under the spinner, and the framed prompt and status bar at the bottom" width="760"/>
-
-</div>
-
-See [everything he can do](https://falkenslab.github.io/agent-kit/docs/examples/captain-whiskers#what-he-can-do), with screenshots. For a real one, [miyagi](https://github.com/falkenslab/miyagi) is an assistant for Moodle teachers: it grades, answers the forum, builds content and sums up how the class is going, asking before publishing anything students will see. Oversight, memory, safety and the chat come from the kit; miyagi brings what it knows about Moodle.
-
-## 🧰 What's inside
-
-| Area | For example |
-| --- | --- |
-| 🎚️ Modes and gates | Autonomous, guided, step by step and plan; the guided gate for extensions' tools, the plan gate, the step gate |
-| ✋ Human in the loop | Approvals, choices, free text, files, manual steps, MCP elicitation forms, a response file for hosts without a keyboard |
-| 🧠 Memory | A knowledge base (an LLM wiki), sources kept as obtained, a memory of the person, runs resumed with `--continue` and `/resume` |
-| 🧩 Extensions | Claude Code plugins with MCP servers (local, npm, remote with OAuth), skills, commands and subagents; scopes, a lock, workspace trust, options, marketplaces and a catalog |
-| 🛡️ Security | A file scope gate, denied paths, subagent gates, a remote-servers gate, isolation from the runner's own Claude Code, redacted transcripts |
-| 🤖 Subagents | Declared types only, in the foreground, without Bash for the main agent |
-| 🖥️ Interfaces | A full-screen Ink chat, a plain readline chat, a progress view, a wizard, themes; a chat controller for desktop apps and web pages |
-| 🌐 Languages | English, Spanish, French and German, for the interface, the replies and the extensions' servers |
-
-Every export, with what it takes and what it gives, is in the [API reference](https://falkenslab.github.io/agent-kit/docs/api).
-
-## 📚 Documentation
-
-- **[Getting started](https://falkenslab.github.io/agent-kit/docs/getting-started/installation)**: installation and a first agent, step by step.
-- **[Modes](https://falkenslab.github.io/agent-kit/docs/core-concepts/modes)** and **[human in the loop](https://falkenslab.github.io/agent-kit/docs/human-in-the-loop/overview)**: how much the agent does alone, and how it asks.
-- **[Extensions](https://falkenslab.github.io/agent-kit/docs/extensions/overview)**: installing, writing and publishing them.
-- **[Security](https://falkenslab.github.io/agent-kit/docs/security/overview)**: every guardrail, and what the kit doesn't protect.
-- **[The terminal chat](https://falkenslab.github.io/agent-kit/docs/terminal-ui/ink-chat)**: its keys, panels, options and themes.
-- **[Captain Whiskers](https://falkenslab.github.io/agent-kit/docs/examples/captain-whiskers)**: the example agent, piece by piece.
-
-## 🛠️ Developing
-
-The design decisions, and the SDK behaviors checked by hand behind several safeguards, are in [`.minispec/`](./.minispec/README.md).
-
-| Command | What it does |
-| --- | --- |
-| `npm run build` | Builds the kit into `dist/` |
-| `npm run typecheck` | Checks the types without building |
-| `npm run lint` | Checks the code style |
-| `npm test` | Runs all the tests (one file: `npx tsx --test test/tui/promptErrors.test.ts`) |
-| `npm run docs:install` | Installs the documentation site's dependencies (once) |
-| `npm run docs:start` | Serves the documentation site locally, reloading on changes |
-| `npm run docs:build` | Builds the documentation site (fails on broken links) |
-
-To try changes to the kit in an agent without publishing them, point its `package.json` to a local clone (`"file:../agent-kit"`) and run `npm run build` after each change.
-
-Working on the kit with Claude Code goes through Falken's Lab's own skills (commit, verify, update-docs, release, sync-issues, and the house style for READMEs, sites and Markdown), from the [falkenslab/falkenslab-plugins](https://github.com/falkenslab/falkenslab-plugins) marketplace. Install them once, for all of Falken's Lab's repositories:
-
-```bash
-claude plugin marketplace add falkenslab/falkenslab-plugins
-claude plugin install falkenslab-dev@falkenslab-plugins
-claude plugin install falkenslab-style@falkenslab-plugins
-```
-
-<details>
-<summary>What each plugin brings, and what stays in this repository</summary>
-
-- 🔧 **falkenslab-dev**: `commit`, `verify`, `update-docs`, `release`, `sync-issues`, `upgrade-deps` and `add-tool`.
-- 🎨 **falkenslab-style**: `falkenslab-docs`, `falkenslab-site-style`, `falkenslab-terminal-screenshots` and `markdown-writing`.
-
-Inside Claude Code, the same with `/plugin marketplace add falkenslab/falkenslab-plugins` and `/plugin install falkenslab-dev@falkenslab-plugins`; `/plugin marketplace update falkenslab-plugins` brings their latest version. This repository keeps only the skills that are agent-kit's own, in `.claude/skills/` (`add-export`, the MiniSpec ones and `upgrade-sdk`), and what its release adds to the general one is in [`CLAUDE.md`](./CLAUDE.md#releasing).
-
-</details>
-
-<div align="center">
-
-Made with 💖 by Falken's Lab Team
-
-</div>
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/falkenslab/agent-kit/main/docs/static/img/logo.svg" alt="agent-kit logo: three blue building blocks and a coral one being set in place" width="112"/>
+
+# agent-kit
+
+**Build an AI agent on Claude that asks before it acts, remembers, and chats like Claude Code.**<br/>
+You write what your agent knows and does; the kit brings oversight, safety, memory and the interface.
+
+[![npm](https://img.shields.io/npm/v/@falkenslab/agent-kit?color=cb3837&logo=npm)](https://www.npmjs.com/package/@falkenslab/agent-kit)
+![Node.js 20+](https://img.shields.io/badge/node-20%2B-339933?logo=node.js&logoColor=white)
+![Claude Agent SDK](https://img.shields.io/badge/Claude-Agent%20SDK-d97757?logo=anthropic&logoColor=white)
+![TypeScript](https://img.shields.io/badge/types-included-3178c6?logo=typescript&logoColor=white)
+[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](LICENSE)
+
+**[📖 Documentation](https://falkenslab.github.io/agent-kit/)** · [📖 Documentación en español](https://falkenslab.github.io/agent-kit/es/)
+
+</div>
+
+agent-kit is a foundation for building AI agents on top of the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk). It isn't an agent itself: it solves once what every agent needs (levels of oversight, approvals, safe limits, memory across sessions, extensions, and a terminal chat as good as Claude Code's), so each agent writes only what belongs to its own domain: what it knows how to do, with which tools, and how it talks. A teacher's assistant for Moodle and a pirate cat who tells jokes are built the same way.
+
+## ✨ Why agent-kit
+
+- 🎚️ **You choose how much it acts alone.** Autonomous, guided (it asks before what others will see or can't be undone), step by step, or a plan mode where it only reads and plans; switch among them in the same conversation.
+- ✋ **It asks a person, and the kit makes sure.** Approvals, choices, a file, a sign-in by hand; an installed extension's tool that changes things waits for a yes whatever the model decided, and answers can last for the session or for good.
+- 🧠 **It remembers.** A knowledge base that grows with every session, the original documents it learns from kept untouched, a memory of the person, and every conversation to pick up again with `--continue` or `/resume`.
+- 🛡️ **It stays within limits.** Only its own folders, never protected files, subagents that can't slip past the main agent's limits, secrets hidden from the logs, remote servers allowed, asked about or denied.
+- 🧩 **It grows with extensions.** Claude Code plugins with MCP servers, skills and commands, installed from a marketplace or a folder, with their own options, sign-in and a catalog in the chat; no Git needed.
+- 🌐 **It speaks your language.** Its interface in English, Spanish, French or German, and it answers in that language unless you write in another.
+- 🖥️ **A terminal chat like Claude Code's, or none at all.** Full screen, live markdown, folded tool calls, panels, history, themes; or the same agent inside a desktop app or a web page with its own interface.
+
+## 🚀 Quick start
+
+You need [Node.js](https://nodejs.org) 20 or later and a Claude account. In a project with `"type": "module"` in its `package.json`:
+
+```bash
+npm install @falkenslab/agent-kit tsx
+```
+
+Save this as `agent.ts`: the only part that's your agent's is the spec at the top.
+
+```ts
+import path from "node:path";
+import { buildSessionOptions, ensureClaudeAuth, runChatInk, type AgentSpec, type BaseSessionConfig } from "@falkenslab/agent-kit";
+
+const spec: AgentSpec<BaseSessionConfig> = {
+  buildSystemPrompt: () => "You are a pirate cat who tells jokes. Always answer in character.",
+  buildMcpServers: () => ({}), // its own MCP servers, if any
+  pluginRoots: () => [], // folders with skills and commands
+  buildSubagents: () => undefined, // subagents, if it delegates to any
+};
+
+await ensureClaudeAuth(); // offers to sign in with your Claude account, on Anthropic's page, if it isn't
+const config: BaseSessionConfig = { mode: "guided", projectDir: process.cwd() };
+
+// Each run gets a folder under .run/ (keep it out of git): its log, transcript and conversation.
+await runChatInk((run) => buildSessionOptions(config, run.dir, spec, { run }), {
+  runsDir: path.resolve(".run"),
+  header: { title: "My agent" },
+  mode: config.mode, // Shift+Tab cycles through guided, step by step and plan
+  fullscreen: true,
+});
+```
+
+Run it with `npx tsx agent.ts`: a full-screen chat opens, in your system's language, and the agent asks before anything it shouldn't do alone. The [tutorial](https://falkenslab.github.io/agent-kit/docs/getting-started/first-agent) takes it from there.
+
+## 🧪 A taste of the code
+
+Give it a memory and a folder of sources, with the kit's own extensions:
+
+```ts
+import { knowledge, memory, sources } from "@falkenslab/agent-kit";
+
+const spec: AgentSpec<BaseSessionConfig> = {
+  // …
+  extensions: [sources({ dir: "sources" }), knowledge({ dir: "knowledge" }), memory({ dir: "memory" })],
+};
+```
+
+Let it install extensions from your marketplace, and keep its data from leaving the computer without asking:
+
+```ts
+const config: BaseSessionConfig = {
+  mode: "guided",
+  projectDir: process.cwd(),
+  extensionDirs: { agent: path.join(os.homedir(), ".my-agent", "extensions") },
+  officialMarketplace: "falkenslab/agent-extensions",
+  remoteServers: "ask",
+};
+```
+
+Make a tool always wait for the person's yes, on every call:
+
+```ts
+const spec: AgentSpec<BaseSessionConfig> = {
+  // …
+  extensionGate: { confirmTools: { canva: ["create-design", "publish-design"] } },
+};
+```
+
+## 📸 See it at work
+
+[Captain Whiskers](./examples/captain-whiskers), the kit's example agent: a retired pirate cat who tells jokes in your language, with a crew of subagents (one looks for new jokes on the web, one rates them, one tells the time), a logbook and an extension of his own. He runs in the terminal, in a browser and as a Windows app.
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/falkenslab/agent-kit/main/docs/assets/captain-whiskers.png" alt="Captain Whiskers in Windows Terminal: his logo with the mode and the agent-kit version at the top, his crew at work in the middle, a task list under the spinner, and the framed prompt and status bar at the bottom" width="760"/>
+
+</div>
+
+See [everything he can do](https://falkenslab.github.io/agent-kit/docs/examples/captain-whiskers#what-he-can-do), with screenshots. For a real one, [miyagi](https://github.com/falkenslab/miyagi) is an assistant for Moodle teachers: it grades, answers the forum, builds content and sums up how the class is going, asking before publishing anything students will see. Oversight, memory, safety and the chat come from the kit; miyagi brings what it knows about Moodle.
+
+## 🧰 What's inside
+
+| Area | For example |
+| --- | --- |
+| 🎚️ Modes and gates | Autonomous, guided, step by step and plan; the guided gate for extensions' tools, the plan gate, the step gate |
+| ✋ Human in the loop | Approvals, choices, free text, files, manual steps, MCP elicitation forms, a response file for hosts without a keyboard |
+| 🧠 Memory | A knowledge base (an LLM wiki), sources kept as obtained, a memory of the person, runs resumed with `--continue` and `/resume` |
+| 🧩 Extensions | Claude Code plugins with MCP servers (local, npm, remote with OAuth), skills, commands and subagents; scopes, a lock, workspace trust, options, marketplaces and a catalog |
+| 🛡️ Security | A file scope gate, denied paths, subagent gates, a remote-servers gate, isolation from the runner's own Claude Code, redacted transcripts |
+| 🤖 Subagents | Declared types only, in the foreground, without Bash for the main agent |
+| 🖥️ Interfaces | A full-screen Ink chat, a plain readline chat, a progress view, a wizard, themes; a chat controller for desktop apps and web pages |
+| 🌐 Languages | English, Spanish, French and German, for the interface, the replies and the extensions' servers |
+
+Every export, with what it takes and what it gives, is in the [API reference](https://falkenslab.github.io/agent-kit/docs/api).
+
+## 📚 Documentation
+
+- **[Getting started](https://falkenslab.github.io/agent-kit/docs/getting-started/installation)**: installation and a first agent, step by step.
+- **[Modes](https://falkenslab.github.io/agent-kit/docs/core-concepts/modes)** and **[human in the loop](https://falkenslab.github.io/agent-kit/docs/human-in-the-loop/overview)**: how much the agent does alone, and how it asks.
+- **[Extensions](https://falkenslab.github.io/agent-kit/docs/extensions/overview)**: installing, writing and publishing them.
+- **[Security](https://falkenslab.github.io/agent-kit/docs/security/overview)**: every guardrail, and what the kit doesn't protect.
+- **[The terminal chat](https://falkenslab.github.io/agent-kit/docs/terminal-ui/ink-chat)**: its keys, panels, options and themes.
+- **[Captain Whiskers](https://falkenslab.github.io/agent-kit/docs/examples/captain-whiskers)**: the example agent, piece by piece.
+
+## 🛠️ Developing
+
+The design decisions, and the SDK behaviors checked by hand behind several safeguards, are in [`.minispec/`](./.minispec/README.md).
+
+| Command | What it does |
+| --- | --- |
+| `npm run build` | Builds the kit into `dist/` |
+| `npm run typecheck` | Checks the types without building |
+| `npm run lint` | Checks the code style |
+| `npm test` | Runs all the tests (one file: `npx tsx --test test/tui/promptErrors.test.ts`) |
+| `npm run docs:install` | Installs the documentation site's dependencies (once) |
+| `npm run docs:start` | Serves the documentation site locally, reloading on changes |
+| `npm run docs:build` | Builds the documentation site (fails on broken links) |
+
+To try changes to the kit in an agent without publishing them, point its `package.json` to a local clone (`"file:../agent-kit"`) and run `npm run build` after each change.
+
+Working on the kit with Claude Code goes through Falken's Lab's own skills (commit, verify, update-docs, release, sync-issues, and the house style for READMEs, sites and Markdown), from the [falkenslab/falkenslab-plugins](https://github.com/falkenslab/falkenslab-plugins) marketplace. Install them once, for all of Falken's Lab's repositories:
+
+```bash
+claude plugin marketplace add falkenslab/falkenslab-plugins
+claude plugin install falkenslab-dev@falkenslab-plugins
+claude plugin install falkenslab-style@falkenslab-plugins
+```
+
+<details>
+<summary>What each plugin brings, and what stays in this repository</summary>
+
+- 🔧 **falkenslab-dev**: `commit`, `verify`, `update-docs`, `release`, `sync-issues`, `upgrade-deps` and `add-tool`.
+- 🎨 **falkenslab-style**: `falkenslab-docs`, `falkenslab-site-style`, `falkenslab-terminal-screenshots` and `markdown-writing`.
+
+Inside Claude Code, the same with `/plugin marketplace add falkenslab/falkenslab-plugins` and `/plugin install falkenslab-dev@falkenslab-plugins`; `/plugin marketplace update falkenslab-plugins` brings their latest version. This repository keeps only the skills that are agent-kit's own, in `.claude/skills/` (`add-export`, the MiniSpec ones and `upgrade-sdk`), and what its release adds to the general one is in [`CLAUDE.md`](./CLAUDE.md#releasing).
+
+</details>
+
+<div align="center">
+
+Made with 💖 by Falken's Lab Team
+
+</div>

package/dist/core/claudeAuth.d.ts

@@ -1,25 +1,57 @@
-/** What `resolveClaudeAuth()` and `ensureClaudeAuth()` accept besides the environment. */
-export interface ClaudeAuthConfig {
-    /** A previously-resolved token the caller already has (from wherever it stores one, if
-     * anywhere) — this module owns no persistence of its own, unlike an earlier version
-     * that read/wrote `~/.<appName>/config.json` itself (see git history). Sourcing this
-     * value across runs, if a concrete agent wants that at all, is entirely its own concern. */
-    claudeCodeOAuthToken?: string;
+/**
+ * The Claude Code binary the Agent SDK ships (`@anthropic-ai/claude-agent-sdk-<platform>-<arch>`),
+ * unmodified: the copy unpacked next to the archive when the agent runs packaged, or else the
+ * one resolved from `node_modules` as the SDK resolves it. `undefined` when it isn't installed.
+ * `resolve` and the platform are replaceable for tests.
+ */
+export declare function claudeExecutable(resolve?: (request: string) => string, platform?: NodeJS.Platform, arch?: string): string | undefined;
+/** What `claudeSignedIn()` and `startClaudeSignIn()` accept. */
+export interface ClaudeAuthOptions {
+    /** The binary to run instead of the SDK's own (`claudeExecutable()`); a `.js`/`.mjs` file runs with Node, as the SDK runs one. */
+    executable?: string;
 }
+/** The binary and its arguments as a process to spawn: a JavaScript file runs with this Node. */
+export declare function claudeCommand(executable: string, args: string[]): {
+    file: string;
+    args: string[];
+};
 /**
- * Pure lookup, no I/O and no console output of any kind — safe to call from a
- * headless/non-interactive consumer (a server, an Electron main process) as much as from a
- * terminal one.
+ * Whether the agent can reach Claude: true when the person's environment has `ANTHROPIC_API_KEY`
+ * or `CLAUDE_CODE_OAUTH_TOKEN` (their own setting); otherwise what the Claude Code binary says
+ * (`claude auth status --json`, its `loggedIn`). Never reads the credentials file, and prints
+ * nothing: safe from a server or an Electron main process. False when there is no binary.
+ */
+export declare function claudeSignedIn(options?: ClaudeAuthOptions): Promise<boolean>;
+/** A sign-in in progress (`startClaudeSignIn()`): Claude Code's own `auth login`, which keeps the credentials itself. */
+export interface ClaudeSignIn {
+    /** Anthropic's sign-in page, to show as a link in case the browser didn't open; `undefined` if the binary ended without printing one. */
+    url: Promise<string | undefined>;
+    /** The code Anthropic's page shows after signing in, when it shows one: handed to the binary, which waits for it. */
+    sendCode(code: string): void;
+    /** Once the binary has ended: whether the person is signed in (`claudeSignedIn()`). */
+    done: Promise<boolean>;
+    /** Stops the sign-in; `done` then resolves with whether the person is signed in anyway. */
+    cancel(): void;
+}
+/**
+ * Signs the person in to their Claude account through Anthropic's own flow, for a host without a
+ * terminal (a web page, a desktop app): runs `claude auth login` (`console: true` for an
+ * Anthropic Console account, billed by API usage) with plain pipes. The binary opens the browser
+ * itself; the host shows `url` as a link in case it didn't, and a box for the code Anthropic's
+ * page shows (`sendCode`). The binary keeps the credentials: the kit never sees a token. Throws
+ * when the binary isn't installed.
  *
- * Checks, in order: `ANTHROPIC_API_KEY` (a complete authentication path on its own — API
- * billing instead of subscription, so nothing else is checked when it's set),
- * `CLAUDE_CODE_OAUTH_TOKEN`, then `config.claudeCodeOAuthToken` if the caller passed one.
- * Returns `true` and (for the `config` case) sets `CLAUDE_CODE_OAUTH_TOKEN` on the process
- * as a side effect once a token is found — the SDK's own subprocess reads that env var
- * directly, never anything this kit passes it explicitly; `false` when none of the three
- * has one. Getting a token in that case (e.g. by walking the user through
- * `claude setup-token`) is a terminal-UX concern, not this function's — see
- * `ensureClaudeAuth()` in tui/claudeAuth.ts, which calls this first and only falls back to
- * that interactive flow when it returns `false`.
+ * Confirmed empirically (Claude Code 2.1.310): without a TTY, `auth login` prints "If the browser
+ * didn't open, visit: <url>" (the URL may come wrapped in OSC 8 hyperlink escapes) and then waits
+ * at "Paste code here if prompted >".
+ */
+export declare function startClaudeSignIn(options?: ClaudeAuthOptions & {
+    console?: boolean;
+}): ClaudeSignIn;
+/**
+ * The sign-in URL in what `claude auth login` printed so far: an OSC 8 hyperlink's target, or a
+ * URL in the text with its escapes removed, Anthropic's authorize page (`/oauth/authorize`)
+ * first. A URL in the text counts only once whitespace follows it (the rest may still be on its
+ * way), unless `complete` says the output is all there is.
  */
-export declare function resolveClaudeAuth(config?: ClaudeAuthConfig): boolean;
+export declare function signInUrl(output: string, complete?: boolean): string | undefined;

package/dist/core/claudeAuth.js

@@ -1,27 +1,140 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { claudeBinaryRequests, unpackedClaudeExecutable } from "./packaged.js";
+/*
+ * Signing in to Claude without ever touching a credential (ADR-009, #90). Anthropic's terms
+ * (https://code.claude.com/docs/en/legal-and-compliance, "Authentication and credential use")
+ * say an Agent SDK developer may not collect, store or intermediate Claude.ai credentials or
+ * session tokens: a Claude account signs in through Anthropic's own flow, in the unmodified
+ * Claude Code binary. The SDK ships that binary, so the kit runs its `auth status` and
+ * `auth login` and nothing else: the binary opens Anthropic's page and keeps the credentials
+ * itself (`~/.claude/.credentials.json`, the Keychain on macOS), where the SDK's sessions find
+ * them. The kit never reads, returns or stores a token. An API key (`ANTHROPIC_API_KEY`) is
+ * allowed, and so is a person's own `CLAUDE_CODE_OAUTH_TOKEN`: both are their setting, not
+ * something the kit collects.
+ */
 /**
- * Pure lookup, no I/O and no console output of any kind — safe to call from a
- * headless/non-interactive consumer (a server, an Electron main process) as much as from a
- * terminal one.
- *
- * Checks, in order: `ANTHROPIC_API_KEY` (a complete authentication path on its own — API
- * billing instead of subscription, so nothing else is checked when it's set),
- * `CLAUDE_CODE_OAUTH_TOKEN`, then `config.claudeCodeOAuthToken` if the caller passed one.
- * Returns `true` and (for the `config` case) sets `CLAUDE_CODE_OAUTH_TOKEN` on the process
- * as a side effect once a token is found — the SDK's own subprocess reads that env var
- * directly, never anything this kit passes it explicitly; `false` when none of the three
- * has one. Getting a token in that case (e.g. by walking the user through
- * `claude setup-token`) is a terminal-UX concern, not this function's — see
- * `ensureClaudeAuth()` in tui/claudeAuth.ts, which calls this first and only falls back to
- * that interactive flow when it returns `false`.
+ * The Claude Code binary the Agent SDK ships (`@anthropic-ai/claude-agent-sdk-<platform>-<arch>`),
+ * unmodified: the copy unpacked next to the archive when the agent runs packaged, or else the
+ * one resolved from `node_modules` as the SDK resolves it. `undefined` when it isn't installed.
+ * `resolve` and the platform are replaceable for tests.
  */
-export function resolveClaudeAuth(config = {}) {
-    if (process.env.ANTHROPIC_API_KEY)
-        return true;
-    if (process.env.CLAUDE_CODE_OAUTH_TOKEN)
-        return true;
-    if (config.claudeCodeOAuthToken) {
-        process.env.CLAUDE_CODE_OAUTH_TOKEN = config.claudeCodeOAuthToken;
+export function claudeExecutable(resolve = createRequire(import.meta.url).resolve, platform = process.platform, arch = process.arch) {
+    const unpacked = unpackedClaudeExecutable(resolve, platform, arch);
+    if (unpacked)
+        return unpacked;
+    for (const request of claudeBinaryRequests(platform, arch)) {
+        try {
+            const file = resolve(request);
+            if (existsSync(file))
+                return file;
+        }
+        catch {
+            // That package isn't installed: the next one.
+        }
+    }
+    return undefined;
+}
+/** The binary and its arguments as a process to spawn: a JavaScript file runs with this Node. */
+export function claudeCommand(executable, args) {
+    return /\.(c|m)?js$/i.test(executable) ? { file: process.execPath, args: [executable, ...args] } : { file: executable, args };
+}
+/**
+ * Whether the agent can reach Claude: true when the person's environment has `ANTHROPIC_API_KEY`
+ * or `CLAUDE_CODE_OAUTH_TOKEN` (their own setting); otherwise what the Claude Code binary says
+ * (`claude auth status --json`, its `loggedIn`). Never reads the credentials file, and prints
+ * nothing: safe from a server or an Electron main process. False when there is no binary.
+ */
+export async function claudeSignedIn(options = {}) {
+    if (process.env.ANTHROPIC_API_KEY || process.env.CLAUDE_CODE_OAUTH_TOKEN)
         return true;
+    const executable = options.executable ?? claudeExecutable();
+    if (!executable)
+        return false;
+    const command = claudeCommand(executable, ["auth", "status", "--json"]);
+    // Exit code 1 when signed out, with the same JSON (confirmed empirically): read it either way.
+    const output = await new Promise((resolve) => {
+        execFile(command.file, command.args, { timeout: 30_000, windowsHide: true }, (_error, stdout) => resolve(String(stdout ?? "")));
+    });
+    try {
+        return JSON.parse(output).loggedIn === true;
     }
-    return false;
+    catch {
+        return false;
+    }
+}
+/**
+ * Signs the person in to their Claude account through Anthropic's own flow, for a host without a
+ * terminal (a web page, a desktop app): runs `claude auth login` (`console: true` for an
+ * Anthropic Console account, billed by API usage) with plain pipes. The binary opens the browser
+ * itself; the host shows `url` as a link in case it didn't, and a box for the code Anthropic's
+ * page shows (`sendCode`). The binary keeps the credentials: the kit never sees a token. Throws
+ * when the binary isn't installed.
+ *
+ * Confirmed empirically (Claude Code 2.1.310): without a TTY, `auth login` prints "If the browser
+ * didn't open, visit: <url>" (the URL may come wrapped in OSC 8 hyperlink escapes) and then waits
+ * at "Paste code here if prompted >".
+ */
+export function startClaudeSignIn(options = {}) {
+    const executable = options.executable ?? claudeExecutable();
+    if (!executable)
+        throw new Error("Claude Code's binary, which the Agent SDK ships (@anthropic-ai/claude-agent-sdk-<platform>-<arch>), isn't installed.");
+    const command = claudeCommand(executable, ["auth", "login", ...(options.console ? ["--console"] : [])]);
+    const child = spawn(command.file, command.args, { stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+    let output = "";
+    let resolveUrl;
+    const url = new Promise((resolve) => (resolveUrl = resolve));
+    const read = (chunk) => {
+        output += chunk.toString("utf8");
+        // Anthropic's page as soon as it's all there; any other URL only once the binary has ended.
+        const found = signInUrl(output);
+        if (found?.includes("/oauth/authorize"))
+            resolveUrl(found);
+    };
+    child.stdout?.on("data", read);
+    child.stderr?.on("data", read);
+    // A write after the binary ended fails on the stream: nothing to tell then.
+    child.stdin?.on("error", () => { });
+    const ended = new Promise((resolve) => {
+        child.on("error", () => resolve());
+        child.on("close", () => resolve());
+    });
+    const done = ended.then(() => {
+        resolveUrl(signInUrl(output, true));
+        return claudeSignedIn(options);
+    });
+    return {
+        url,
+        sendCode(code) {
+            if (child.stdin?.writable)
+                child.stdin.write(`${code.trim()}\n`);
+        },
+        done,
+        cancel() {
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill();
+        },
+    };
+}
+// An OSC sequence (a hyperlink's `ESC ] 8 ; ; URL ESC \`, a title), ended by BEL or ST.
+// eslint-disable-next-line no-control-regex -- ESC and BEL delimit terminal escapes, on purpose
+const OSC = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+// A CSI sequence (colors, cursor moves).
+// eslint-disable-next-line no-control-regex -- ESC starts the sequence
+const CSI = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+// eslint-disable-next-line no-control-regex -- an OSC 8 hyperlink's target, between ESC/BEL delimiters
+const HYPERLINK_TARGET = /\x1b\]8;[^;\x07\x1b]*;(https:\/\/[^\x07\x1b]+)(?:\x07|\x1b\\)/g;
+/**
+ * The sign-in URL in what `claude auth login` printed so far: an OSC 8 hyperlink's target, or a
+ * URL in the text with its escapes removed, Anthropic's authorize page (`/oauth/authorize`)
+ * first. A URL in the text counts only once whitespace follows it (the rest may still be on its
+ * way), unless `complete` says the output is all there is.
+ */
+export function signInUrl(output, complete = false) {
+    const targets = [...output.matchAll(HYPERLINK_TARGET)].map((match) => match[1]);
+    const text = output.replace(OSC, " ").replace(CSI, "");
+    const inText = [...text.matchAll(complete ? /https:\/\/\S+/g : /https:\/\/\S+(?=\s)/g)].map((match) => match[0]);
+    const urls = [...targets, ...inText];
+    return urls.find((url) => url.includes("/oauth/authorize")) ?? urls[0];
 }

package/dist/core/hooks/transcriptLogger.d.ts

@@ -9,8 +9,8 @@ export interface TranscriptLogger {
 /**
  * Logs every tool call (request + result) as one JSON line, redacting `secrets` (e.g. a
  * domain-specific password — see `BaseSessionConfig.secrets`) plus
- * `CLAUDE_CODE_OAUTH_TOKEN`, which this kit always scrubs regardless of domain since it
- * owns the auth-token concept (see claudeAuth.ts).
+ * `CLAUDE_CODE_OAUTH_TOKEN` when the person's environment sets one, which this kit always
+ * scrubs regardless of domain (it never handles a token itself: see claudeAuth.ts).
  */
 export declare function createTranscriptLogger(transcriptPath: string, secrets?: readonly string[]): TranscriptLogger;
 /** Avoids bloating the transcript with large payloads (browser-tool screenshots/base64). */

package/dist/core/hooks/transcriptLogger.js

@@ -10,8 +10,8 @@ function redact(text, secrets) {
 /**
  * Logs every tool call (request + result) as one JSON line, redacting `secrets` (e.g. a
  * domain-specific password — see `BaseSessionConfig.secrets`) plus
- * `CLAUDE_CODE_OAUTH_TOKEN`, which this kit always scrubs regardless of domain since it
- * owns the auth-token concept (see claudeAuth.ts).
+ * `CLAUDE_CODE_OAUTH_TOKEN` when the person's environment sets one, which this kit always
+ * scrubs regardless of domain (it never handles a token itself: see claudeAuth.ts).
  */
 export function createTranscriptLogger(transcriptPath, secrets = []) {
     const allSecrets = [...secrets, process.env.CLAUDE_CODE_OAUTH_TOKEN].filter((s) => Boolean(s));

package/dist/core/messages/de.js

@@ -194,12 +194,14 @@ export const de = {
         presentingPlan: "Plan vorlegen",
     },
     auth: {
-        noToken: "Es wurde kein Claude-Authentifizierungstoken gefunden",
-        noTokenDetail: "(weder die Umgebungsvariable CLAUDE_CODE_OAUTH_TOKEN noch ein im Code übergebenes).",
-        generateQuestion: 'Jetzt eines mit "claude setup-token" erzeugen? (erfordert ein Claude-Pro/Max-Abonnement)',
-        cantStart: "Der Agent kann ohne Token nicht starten. Setze CLAUDE_CODE_OAUTH_TOKEN von Hand (oder starte erneut und lass es erzeugen) und versuche es noch einmal.",
-        generatingHeading: "=== Claude-Authentifizierungstoken wird erzeugt ===",
-        browserWillOpen: "Zum Anmelden öffnet sich ein Browser; folge den Anweisungen, die der Befehl unten ausgibt.",
-        generated: "Token für diese Ausführung erzeugt. Speichere es selbst (z. B. CLAUDE_CODE_OAUTH_TOKEN im Profil deiner Shell), um diesen Schritt beim nächsten Mal zu überspringen.",
+        notSignedIn: "Du bist nicht bei Claude angemeldet",
+        notSignedInDetail: "Melde dich mit deinem Claude-Konto auf Anthropics eigener Seite an: Das übernimmt Claude Code, das mit diesem Agenten kommt, und es speichert die Anmeldung selbst. Oder setze ANTHROPIC_API_KEY, um einen API-Schlüssel zu verwenden.",
+        signInQuestion: "Jetzt mit deinem Claude-Konto anmelden?",
+        cantStart: "Der Agent kann ohne Claude nicht starten. Starte ihn erneut und melde dich an, oder setze ANTHROPIC_API_KEY.",
+        signingInHeading: "=== Anmeldung bei Claude ===",
+        browserWillOpen: "Ein Browser öffnet sich mit Anthropics Anmeldeseite. Zeigt die Seite einen Code, füge ihn hier ein.",
+        signedIn: "Angemeldet. Claude Code speichert die Anmeldung, du wirst nicht erneut gefragt.",
+        notCompleted: "Die Anmeldung wurde nicht abgeschlossen. Starte den Agenten erneut, um es noch einmal zu versuchen, oder setze ANTHROPIC_API_KEY.",
+        noClaude: "Das Claude-Code-Programm, das mit dem Agent SDK kommt (@anthropic-ai/claude-agent-sdk-<Plattform>-<Architektur>), ist nicht installiert, daher ist keine Anmeldung möglich. Installiere den Agenten neu, oder setze ANTHROPIC_API_KEY.",
     },
 };

package/dist/core/messages/en.d.ts

@@ -203,13 +203,15 @@ export interface Messages {
         presentingPlan: string;
     };
     auth: {
-        noToken: string;
-        noTokenDetail: string;
-        generateQuestion: string;
+        notSignedIn: string;
+        notSignedInDetail: string;
+        signInQuestion: string;
         cantStart: string;
-        generatingHeading: string;
+        signingInHeading: string;
         browserWillOpen: string;
-        generated: string;
+        signedIn: string;
+        notCompleted: string;
+        noClaude: string;
     };
 }
 export declare const en: Messages;

package/dist/core/messages/en.js

@@ -193,12 +193,14 @@ export const en = {
         presentingPlan: "Presenting the plan",
     },
     auth: {
-        noToken: "No Claude authentication token was found",
-        noTokenDetail: "(neither the CLAUDE_CODE_OAUTH_TOKEN environment variable, nor one passed in).",
-        generateQuestion: 'Generate one now with "claude setup-token" (requires a Claude Pro/Max subscription)?',
-        cantStart: "The agent can't start without a token. Set CLAUDE_CODE_OAUTH_TOKEN by hand (or run this again and accept generating it) and try again.",
-        generatingHeading: "=== Generating a Claude authentication token ===",
-        browserWillOpen: "A browser will open to log in; follow the instructions the command itself prints below.",
-        generated: "Token generated for this run. Save it yourself (e.g. CLAUDE_CODE_OAUTH_TOKEN in your shell profile) to skip this next time.",
+        notSignedIn: "You aren't signed in to Claude",
+        notSignedInDetail: "Sign in with your Claude account on Anthropic's own page: Claude Code, which comes with this agent, does it and keeps the sign-in itself. Or set ANTHROPIC_API_KEY to use an API key.",
+        signInQuestion: "Sign in with your Claude account now?",
+        cantStart: "The agent can't start without Claude. Run it again and sign in, or set ANTHROPIC_API_KEY.",
+        signingInHeading: "=== Signing in to Claude ===",
+        browserWillOpen: "A browser will open on Anthropic's sign-in page. If the page shows a code, paste it here.",
+        signedIn: "Signed in. Claude Code keeps the sign-in, so this won't be asked again.",
+        notCompleted: "The sign-in didn't complete. Run the agent again to retry, or set ANTHROPIC_API_KEY.",
+        noClaude: "Claude Code's binary, which comes with the Agent SDK (@anthropic-ai/claude-agent-sdk-<platform>-<arch>), isn't installed, so there's no way to sign in. Reinstall the agent, or set ANTHROPIC_API_KEY.",
     },
 };

package/dist/core/messages/es.js

@@ -194,12 +194,14 @@ export const es = {
         presentingPlan: "Presentando el plan",
     },
     auth: {
-        noToken: "No se ha encontrado ningún token de autenticación de Claude",
-        noTokenDetail: "(ni la variable de entorno CLAUDE_CODE_OAUTH_TOKEN ni uno pasado por código).",
-        generateQuestion: '¿Generar uno ahora con "claude setup-token"? (requiere una suscripción Claude Pro/Max)',
-        cantStart: "El agente no puede arrancar sin un token. Define CLAUDE_CODE_OAUTH_TOKEN a mano (o vuelve a ejecutarlo y acepta generarlo) e inténtalo de nuevo.",
-        generatingHeading: "=== Generando un token de autenticación de Claude ===",
-        browserWillOpen: "Se abrirá un navegador para iniciar sesión; sigue las instrucciones que el propio comando muestra abajo.",
-        generated: "Token generado para esta ejecución. Guárdalo tú (p. ej. CLAUDE_CODE_OAUTH_TOKEN en el perfil de tu shell) para no repetir esto la próxima vez.",
+        notSignedIn: "No has iniciado sesión en Claude",
+        notSignedInDetail: "Inicia sesión con tu cuenta de Claude en la propia página de Anthropic: lo hace Claude Code, que viene con este agente, y guarda él mismo la sesión. O define ANTHROPIC_API_KEY para usar una API key.",
+        signInQuestion: "¿Iniciar sesión ahora con tu cuenta de Claude?",
+        cantStart: "El agente no puede arrancar sin Claude. Vuelve a ejecutarlo e inicia sesión, o define ANTHROPIC_API_KEY.",
+        signingInHeading: "=== Iniciando sesión en Claude ===",
+        browserWillOpen: "Se abrirá un navegador en la página de inicio de sesión de Anthropic. Si la página muestra un código, pégalo aquí.",
+        signedIn: "Sesión iniciada. Claude Code la guarda, así que no se volverá a pedir.",
+        notCompleted: "El inicio de sesión no se completó. Vuelve a ejecutar el agente para reintentarlo, o define ANTHROPIC_API_KEY.",
+        noClaude: "No está instalado el binario de Claude Code que trae el Agent SDK (@anthropic-ai/claude-agent-sdk-<plataforma>-<arquitectura>), así que no hay cómo iniciar sesión. Reinstala el agente, o define ANTHROPIC_API_KEY.",
     },
 };

package/dist/core/messages/fr.js

@@ -194,12 +194,14 @@ export const fr = {
         presentingPlan: "Présentation du plan",
     },
     auth: {
-        noToken: "Aucun jeton d'authentification Claude n'a été trouvé",
-        noTokenDetail: "(ni la variable d'environnement CLAUDE_CODE_OAUTH_TOKEN, ni un jeton passé par le code).",
-        generateQuestion: 'En générer un maintenant avec "claude setup-token" ? (nécessite un abonnement Claude Pro/Max)',
-        cantStart: "L'agent ne peut pas démarrer sans jeton. Définissez CLAUDE_CODE_OAUTH_TOKEN à la main (ou relancez et acceptez de le générer), puis réessayez.",
-        generatingHeading: "=== Génération d'un jeton d'authentification Claude ===",
-        browserWillOpen: "Un navigateur va s'ouvrir pour vous connecter ; suivez les instructions que la commande affiche ci-dessous.",
-        generated: "Jeton généré pour cette exécution. Enregistrez-le vous-même (par ex. CLAUDE_CODE_OAUTH_TOKEN dans le profil de votre shell) pour éviter cette étape la prochaine fois.",
+        notSignedIn: "Tu n'es pas connecté à Claude",
+        notSignedInDetail: "Connecte-toi avec ton compte Claude sur la page d'Anthropic : c'est Claude Code, fourni avec cet agent, qui s'en charge et garde lui-même la connexion. Ou définis ANTHROPIC_API_KEY pour utiliser une clé d'API.",
+        signInQuestion: "Se connecter maintenant avec ton compte Claude ?",
+        cantStart: "L'agent ne peut pas démarrer sans Claude. Relance-le et connecte-toi, ou définis ANTHROPIC_API_KEY.",
+        signingInHeading: "=== Connexion à Claude ===",
+        browserWillOpen: "Un navigateur va s'ouvrir sur la page de connexion d'Anthropic. Si la page affiche un code, colle-le ici.",
+        signedIn: "Connecté. Claude Code garde la connexion : on ne te la redemandera pas.",
+        notCompleted: "La connexion n'a pas abouti. Relance l'agent pour réessayer, ou définis ANTHROPIC_API_KEY.",
+        noClaude: "Le binaire de Claude Code fourni avec l'Agent SDK (@anthropic-ai/claude-agent-sdk-<plateforme>-<architecture>) n'est pas installé : impossible de se connecter. Réinstalle l'agent, ou définis ANTHROPIC_API_KEY.",
     },
 };

package/dist/core/packaged.d.ts

@@ -1,5 +1,11 @@
 /** A path inside `…/app.asar/…`, as the unpacked copy next to it (`…/app.asar.unpacked/…`); any other path as it is. */
 export declare function outsideArchive(file: string): string;
+/**
+ * The module requests that name the SDK's CLI binary on this platform, in the SDK's order:
+ * `@anthropic-ai/claude-agent-sdk-<platform>-<arch>/claude[.exe]`, both libcs on Linux (musl
+ * first when the system runs on it, as the SDK decides).
+ */
+export declare function claudeBinaryRequests(platform?: NodeJS.Platform, arch?: string, musl?: boolean): string[];
 /**
  * The SDK's CLI binary unpacked next to the archive, when the kit runs packaged: the SDK would
  * resolve it inside `app.asar`, where it can't be executed, and its first turn would hang with

package/dist/core/packaged.js

@@ -11,6 +11,22 @@ const ARCHIVE = /([\\/])app\.asar([\\/])/;
 export function outsideArchive(file) {
     return file.replace(ARCHIVE, "$1app.asar.unpacked$2");
 }
+/**
+ * The module requests that name the SDK's CLI binary on this platform, in the SDK's order:
+ * `@anthropic-ai/claude-agent-sdk-<platform>-<arch>/claude[.exe]`, both libcs on Linux (musl
+ * first when the system runs on it, as the SDK decides).
+ */
+export function claudeBinaryRequests(platform = process.platform, arch = process.arch, musl = platform === "linux" && runsOnMusl()) {
+    const packages = platform === "linux" ? (musl ? [`linux-${arch}-musl`, `linux-${arch}`] : [`linux-${arch}`, `linux-${arch}-musl`]) : [`${platform}-${arch}`];
+    return packages.map((suffix) => `@anthropic-ai/claude-agent-sdk-${suffix}/claude${platform === "win32" ? ".exe" : ""}`);
+}
+/** A Linux whose C library is musl (Alpine): Node's report names no glibc version there. */
+function runsOnMusl() {
+    if (process.platform !== "linux")
+        return false;
+    const report = process.report?.getReport();
+    return Boolean(report?.header) && report?.header?.glibcVersionRuntime === undefined;
+}
 /**
  * The SDK's CLI binary unpacked next to the archive, when the kit runs packaged: the SDK would
  * resolve it inside `app.asar`, where it can't be executed, and its first turn would hang with
@@ -19,11 +35,10 @@ export function outsideArchive(file) {
  * when not packaged, or when the build didn't unpack it: then the SDK finds its own.
  */
 export function unpackedClaudeExecutable(resolve = createRequire(import.meta.url).resolve, platform = process.platform, arch = process.arch) {
-    const packages = platform === "linux" ? [`linux-${arch}`, `linux-${arch}-musl`] : [`${platform}-${arch}`];
-    for (const suffix of packages) {
+    for (const request of claudeBinaryRequests(platform, arch)) {
         let file;
         try {
-            file = resolve(`@anthropic-ai/claude-agent-sdk-${suffix}/claude${platform === "win32" ? ".exe" : ""}`);
+            file = resolve(request);
         }
         catch {
             continue;

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { setTheme, getTheme, DEFAULT_THEME, type Theme, type ThemeColor } from "
 export { isExitPromptError } from "./tui/promptErrors.js";
 export { allowAnyMcpTool } from "./core/mcpPermissions.js";
 export { createPromptLoader } from "./core/promptTemplate.js";
-export { resolveClaudeAuth, type ClaudeAuthConfig } from "./core/claudeAuth.js";
+export { claudeExecutable, claudeSignedIn, startClaudeSignIn, type ClaudeAuthOptions, type ClaudeSignIn } from "./core/claudeAuth.js";
 export { ensureClaudeAuth } from "./tui/claudeAuth.js";
 export { createFriendlyToolLabel, truncate, truncatePath, withToolLabels, withToolPhrases, withToolResults, quietResults, type ToolResult, type ToolDescriber, type ToolLabel, type ToolLabels, } from "./core/toolLabels.js";
 export type { Mode, BaseSessionConfig, AgentSpec, AgentIdentity, PlanModeSpec, ExtensionGateSpec } from "./core/agentSpec.js";

package/dist/index.js

@@ -5,7 +5,7 @@ export { setTheme, getTheme, DEFAULT_THEME } from "./tui/theme.js";
 export { isExitPromptError } from "./tui/promptErrors.js";
 export { allowAnyMcpTool } from "./core/mcpPermissions.js";
 export { createPromptLoader } from "./core/promptTemplate.js";
-export { resolveClaudeAuth } from "./core/claudeAuth.js";
+export { claudeExecutable, claudeSignedIn, startClaudeSignIn } from "./core/claudeAuth.js";
 export { ensureClaudeAuth } from "./tui/claudeAuth.js";
 export { createFriendlyToolLabel, truncate, truncatePath, withToolLabels, withToolPhrases, withToolResults, quietResults, } from "./core/toolLabels.js";
 export { buildSessionOptions, createInputQueue, createDeferred, createModeControl, togglePlanMode } from "./core/session.js";

package/dist/tui/claudeAuth.d.ts

@@ -1,21 +1,16 @@
-import { type ClaudeAuthConfig } from "../core/claudeAuth.js";
 /**
- * The terminal-facing counterpart to `resolveClaudeAuth()` (core/claudeAuth.ts), which only
- * *looks up* a token. This one also gets you one: if `resolveClaudeAuth(config)` comes back
- * empty, it prints why, offers to run "claude setup-token" interactively, and sets the
- * result on `process.env.CLAUDE_CODE_OAUTH_TOKEN` for this run. Exits the process if the
- * user declines or cancels — there's no agent to run without a token.
+ * Makes sure the agent can reach Claude before a terminal chat starts: returns at once when
+ * `claudeSignedIn()` says so (an API key or the person's own token in the environment, or a
+ * Claude Code sign-in). Otherwise it says why, asks whether to sign in, and runs Claude Code's
+ * own `claude auth login` (the binary the Agent SDK ships) on this terminal: Anthropic's page in
+ * the browser, the code it shows pasted here. The binary keeps the credentials; nothing is
+ * returned or stored (ADR-009: Anthropic's terms forbid an agent collecting them). Exits the
+ * process when the person declines or the sign-in doesn't complete: there's no agent to run
+ * without Claude.
  *
- * Persisting a freshly-generated token across runs is *not* this function's job — unlike an
- * earlier version, this kit owns no config-file storage of its own (see git history). When
- * the interactive flow does generate one, it's returned so the caller can save it wherever
- * it wants (a file, an OS keychain, ...) and pass it back in as `config.claudeCodeOAuthToken`
- * next time; returns `undefined` when auth was already resolved (an env var, or the `config`
- * passed in) and nothing new was generated.
- *
- * Only makes sense with a real terminal in front of a human (a `runWizard()` confirm, colored console
- * output), which is why it lives here rather than in the non-interactive core.
+ * Only makes sense with a terminal in front of a person (a `runWizard()` confirm, colored
+ * output); a host without one uses `startClaudeSignIn()` from the core.
  */
-export declare function ensureClaudeAuth(config?: ClaudeAuthConfig, options?: {
+export declare function ensureClaudeAuth(options?: {
     language?: string;
-}): Promise<string | undefined>;
+}): Promise<void>;

package/dist/tui/claudeAuth.js

@@ -1,78 +1,47 @@
 import { spawn } from "node:child_process";
-import { resolveClaudeAuth } from "../core/claudeAuth.js";
+import { claudeCommand, claudeExecutable, claudeSignedIn } from "../core/claudeAuth.js";
 import { isExitPromptError } from "./promptErrors.js";
 import * as ui from "./ui.js";
 import { runWizard } from "./ink/wizard.js";
 import { applyLanguage } from "./language.js";
 import { t } from "../core/messages/index.js";
-// The real format of "claude setup-token" tokens ("sk-ant-oat01-...", seen in the
-// installed @anthropic-ai/claude-code binary) — used to extract the token from its output.
-const TOKEN_PATTERN = /sk-ant-oat\d{2}-[A-Za-z0-9_-]+/;
-/**
- * Launches "claude setup-token" as an interactive child process: it opens a browser and
- * asks the user to authenticate, with instructions it prints itself. stdin/stderr are
- * inherited as-is so the interaction (pasting the authorization code, etc.) is identical
- * to running the command by hand; stdout is duplicated live and also buffered to extract
- * the token it prints at the end ("Your OAuth token (...): sk-ant-oat01-...").
- */
-function runSetupToken() {
-    return new Promise((resolve, reject) => {
-        // On Windows npx is npx.cmd, which only runs through a shell. The command is passed as
-        // one fixed string there (nothing user-supplied in it): an args array with
-        // `shell: true` triggers Node's DEP0190 warning, since args are concatenated unescaped.
-        const stdio = ["inherit", "pipe", "inherit"];
-        const child = process.platform === "win32"
-            ? spawn("npx @anthropic-ai/claude-code setup-token", { stdio, shell: true })
-            : spawn("npx", ["@anthropic-ai/claude-code", "setup-token"], { stdio });
-        let output = "";
-        child.stdout.on("data", (chunk) => {
-            const text = chunk.toString("utf-8");
-            output += text;
-            process.stdout.write(text);
-        });
-        child.on("error", reject);
-        child.on("exit", (code) => {
-            if (code !== 0) {
-                reject(new Error(`"claude setup-token" exited with code ${code}.`));
-                return;
-            }
-            const match = output.match(TOKEN_PATTERN);
-            if (!match) {
-                reject(new Error('"claude setup-token" exited without errors, but no token was found in its ' +
-                    "output (sk-ant-oat...). Copy it by hand into CLAUDE_CODE_OAUTH_TOKEN if you see it above."));
-                return;
-            }
-            resolve(match[0]);
-        });
+/** Runs Claude Code's own `auth login` on this terminal: it opens the browser, and the person pastes the code here. */
+function runLogin(executable) {
+    const command = claudeCommand(executable, ["auth", "login"]);
+    return new Promise((resolve) => {
+        const child = spawn(command.file, command.args, { stdio: "inherit" });
+        child.on("error", () => resolve());
+        child.on("close", () => resolve());
     });
 }
 /**
- * The terminal-facing counterpart to `resolveClaudeAuth()` (core/claudeAuth.ts), which only
- * *looks up* a token. This one also gets you one: if `resolveClaudeAuth(config)` comes back
- * empty, it prints why, offers to run "claude setup-token" interactively, and sets the
- * result on `process.env.CLAUDE_CODE_OAUTH_TOKEN` for this run. Exits the process if the
- * user declines or cancels — there's no agent to run without a token.
- *
- * Persisting a freshly-generated token across runs is *not* this function's job — unlike an
- * earlier version, this kit owns no config-file storage of its own (see git history). When
- * the interactive flow does generate one, it's returned so the caller can save it wherever
- * it wants (a file, an OS keychain, ...) and pass it back in as `config.claudeCodeOAuthToken`
- * next time; returns `undefined` when auth was already resolved (an env var, or the `config`
- * passed in) and nothing new was generated.
+ * Makes sure the agent can reach Claude before a terminal chat starts: returns at once when
+ * `claudeSignedIn()` says so (an API key or the person's own token in the environment, or a
+ * Claude Code sign-in). Otherwise it says why, asks whether to sign in, and runs Claude Code's
+ * own `claude auth login` (the binary the Agent SDK ships) on this terminal: Anthropic's page in
+ * the browser, the code it shows pasted here. The binary keeps the credentials; nothing is
+ * returned or stored (ADR-009: Anthropic's terms forbid an agent collecting them). Exits the
+ * process when the person declines or the sign-in doesn't complete: there's no agent to run
+ * without Claude.
  *
- * Only makes sense with a real terminal in front of a human (a `runWizard()` confirm, colored console
- * output), which is why it lives here rather than in the non-interactive core.
+ * Only makes sense with a terminal in front of a person (a `runWizard()` confirm, colored
+ * output); a host without one uses `startClaudeSignIn()` from the core.
  */
-export async function ensureClaudeAuth(config = {}, options = {}) {
-    if (resolveClaudeAuth(config))
-        return undefined;
+export async function ensureClaudeAuth(options = {}) {
+    if (await claudeSignedIn())
+        return;
     applyLanguage(options.language);
     const texts = t().auth;
-    console.log(ui.warn(`\n${texts.noToken}`));
-    console.log(ui.dim(texts.noTokenDetail));
+    const executable = claudeExecutable();
+    if (!executable) {
+        console.log(ui.error(`\n${texts.noClaude}`));
+        process.exit(1);
+    }
+    console.log(ui.warn(`\n${texts.notSignedIn}`));
+    console.log(ui.dim(texts.notSignedInDetail));
     try {
-        const { generate } = await runWizard([{ type: "confirm", name: "generate", message: texts.generateQuestion, default: true }]);
-        if (!generate) {
+        const { signIn } = await runWizard([{ type: "confirm", name: "signIn", message: texts.signInQuestion, default: true }]);
+        if (!signIn) {
             console.log(ui.error(`\n${texts.cantStart}`));
             process.exit(0);
         }
@@ -82,10 +51,12 @@ export async function ensureClaudeAuth(config = {}, options = {}) {
             process.exit(0);
         throw error;
     }
-    console.log(ui.heading(`\n${texts.generatingHeading}`));
+    console.log(ui.heading(`\n${texts.signingInHeading}`));
     console.log(ui.dim(`${texts.browserWillOpen}\n`));
-    const token = await runSetupToken();
-    process.env.CLAUDE_CODE_OAUTH_TOKEN = token;
-    console.log(ui.success(`\n${texts.generated}\n`));
-    return token;
+    await runLogin(executable);
+    if (!(await claudeSignedIn())) {
+        console.log(ui.error(`\n${texts.notCompleted}`));
+        process.exit(1);
+    }
+    console.log(ui.success(`\n${texts.signedIn}\n`));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falkenslab/agent-kit",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Library for building an agent on top of the Claude Agent SDK",
   "author": "Francisco Vargas Ruiz",
   "license": "MIT",