squad-kit 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,140 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] — 2026-08-24
+
+### What's new
+
+- **Plan on your Claude subscription.** The Anthropic planner can authenticate
+  with the Claude login you already have (Pro, Max, or Team/Enterprise) instead
+  of an API key. `squad new-plan --api` and the console Generate page both run
+  on it. No per-token API bill. OpenAI and Google are unchanged and remain
+  API-key only.
+- **`squad auth login | status | logout`.** `login` runs the Anthropic browser
+  authorization flow and stores the resulting token in `.squad/secrets.yaml`;
+  `--token <value>` consumes a `claude setup-token` value on a headless machine,
+  and `--print-only` runs the flow, prints the token, and stores nothing.
+  `status` reports the resolved mode, the credential behind it, and the
+  signed-in account (`--json` for a stable scripting shape, `--offline` to skip
+  the live check). `logout` removes only the token squad-kit stored.
+- **`planner.auth.anthropic`** in `.squad/config.yaml` — `subscription`,
+  `api-key`, or `auto`. The merged default is **`auto`**: prefer a detected
+  Claude login, fall back to a resolvable API key, otherwise fail naming both
+  recovery paths. `squad init` offers the subscription as the first and default
+  choice for new workspaces and writes it explicitly.
+- **`planner.anthropicOauthToken`** is a new secrets-only key. `.squad/config.yaml`
+  rejects it by name at load time.
+- **Subscription runs withhold the API key.** In subscription mode
+  `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` are removed (case-insensitively)
+  from the planner subprocess environment. Both outrank the login credential
+  inside Claude Code, so an inherited one would silently bill API credits. The
+  parent shell is untouched.
+- **No new runtime dependency.** `squad auth login` shells out to the `claude`
+  binary that `@anthropic-ai/claude-agent-sdk` already ships through
+  `optionalDependencies`. A separate Claude Code install is never required.
+- **Auth-aware `squad doctor`.** New `planner auth mode` (resolved mode, why,
+  and the credential — naming any API key it is ignoring) and
+  `planner auth vs. runtime` (subscription auth requires the Agent SDK runtime)
+  checks. `planner model resolves at provider` and `planner tier vs. model` now
+  **skip** on subscription auth: there is no API key to list models with and no
+  API rate tier to warn about.
+- **Console auth surface.** An Authentication control on Config (with a
+  hard-conflict callout that disables Save), a Claude Account card on Secrets
+  with a live "Check again" probe and a masked stored token, an auth badge and
+  branched billing copy on Generate, a dedicated recovery callout for
+  `auth_unavailable` failures, and an Auth column on the runs index. The console
+  guides the login and never performs it — it cannot complete an OAuth callback
+  on your behalf.
+- **Run records carry `authMode`**, and the planner stream gained one additive
+  `auth_info` event. Older clients ignore unknown event kinds.
+- **Cost copy branches on auth mode.** `printPlannerApiCostNotice()` and the
+  limit explanations no longer describe per-token billing on a subscription run.
+
+### Bug fixes
+
+- Planner model-list probe (`src/core/probes.ts`): a network-level `fetch`
+  rejection (offline, DNS failure, proxy refusal) or a non-JSON response body
+  threw out of `fetchProviderModelIds` instead of returning a failure result, so
+  `squad doctor`'s `planner model resolves at provider` check surfaced an
+  unexpected error rather than a clean diagnosis. Both are now caught and
+  reported as `status: 0` with the message, and long error bodies are truncated.
+  Shipped to GitHub after v0.11.0 (`d2d67a1`) and missed the 0.11.0 changelog.
+
+### Upgrade notes
+
+Zero-config. A `config.yaml` with no `planner.auth` block merges to `auto` and
+keeps loading; every existing `planner.*` key, including `maxOutputTokens`, is
+unaffected. An untouched 0.11.0 API-key workspace resolves to `api-key` and
+behaves identically — **provided the machine has no Claude login**.
+
+Under `auto`, a detected Claude login **outranks** a stored API key. So on a
+machine that has both, an upgraded workspace switches to subscription billing.
+Nothing errors, and the change is announced rather than silent: `squad doctor`'s
+`planner auth mode` row reads `subscription (auto — Claude login detected) → …
+· ignoring the API key from .squad/secrets.yaml`. Set
+`planner.auth.anthropic: api-key` to pin the previous behaviour.
+
+`squad doctor --fix` deliberately does **not** pin an implicit `auto` to
+`api-key`. `auto` exists so that a Claude login takes over once one appears;
+pinning would silently prevent that forever.
+
+### Notes / limitations
+
+- **Usage draws on your Claude plan's limits.** Per Anthropic's
+  [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan),
+  Agent SDK, `claude -p`, and third-party usage consumes the subscription's
+  usage limits, and the separately announced monthly SDK credit is not currently
+  available. The claim this release makes is **"no per-token API bill"** — not
+  free, and not unlimited. Opus planning against a **Pro** plan consumes a usage
+  window noticeably faster than against **Max**. Hitting the ceiling means
+  waiting for the reset window or switching to an API key.
+- **Enterprise managed-settings `apiKeyHelper` still wins.** squad-kit runs the
+  Agent SDK with `settingSources: []`, so user, project, and local settings are
+  not read and an ordinary user-level `apiKeyHelper` cannot hijack a
+  subscription run. **Policy settings are always merged regardless**, so a
+  managed-settings `apiKeyHelper` deployed by MDM is still honoured and still
+  outranks the login credential — on a managed device, `auth: subscription` may
+  resolve through the organization's helper. This was established by reading the
+  credential resolver in the bundled `claude` binary, **not** on a live managed
+  device. `squad auth status` reports the `apiKeySource` the SDK actually
+  resolved.
+- **`auth: subscription` requires the Agent SDK runtime.** `@ai-sdk/anthropic`
+  authenticates with `x-api-key`, and an OAuth credential is not an API key.
+  `auth: subscription` with `planner.runtime.anthropic: vercel`, or with a
+  non-Anthropic provider, is a hard failure before any network call — never a
+  silent downgrade to API billing.
+- **Account details are never persisted.** Email, organization, and plan are
+  fetched live for display in `squad auth status`, `squad doctor`, and the
+  console. `.squad/runs/` records the resolved **mode** and `apiKeySource` only —
+  no token, key, email, or organization. Asserted by a test.
+- **A successful SDK handshake does not prove the credential works.**
+  `accountInfo()` resolves from the subprocess's `initialize` response, which
+  succeeds whether or not the credential is valid. Subscription auth that
+  reports no account **and** no `apiKeySource` is therefore treated as
+  unverified rather than signed in.
+- `docs/auth.md` is not shipped inside the npm tarball. It is served at
+  <https://squad-kit.com/docs/auth> and lives in the repo under `docs/`.
+
+## [0.11.0] — 2026-05-04
+
+### What's new
+
+- API `new-plan` can append planner events to `.squad/runs/<id>.events.jsonl`
+  (thinking text redacted on disk; retention rotates old files).
+- Agent SDK runs emit richer events (tool lifecycle, thinking deltas, caps,
+  runtime metadata) for the CLI and console.
+- API-mode `new-plan` prints stage pipeline, budget meters, and thinking
+  activity; the plan summary cites the events file path.
+- `squad console` HTTP API lists persisted runs and serves stored event streams.
+- Console UI adds a runs index, run report page, and a reworked Generate view
+  with live panels and navigation.
+
+### Bug fixes
+
+- `squad doctor` skips live external probes when `CI` is set and surfaces
+  planner probe errors cleanly.
+- Vitest timeouts increased for slow config loads and console API tests.
+
 ## [0.10.0] — 2026-05-04
 
 ### What's new

package/README.md

@@ -23,6 +23,36 @@
 └── plans/<feature>/         # NN-story-<id>.md (one per executable plan)
 ```
 
+## What's new in 0.12.0
+
+- **Plan on your Claude subscription.** `squad auth login` signs in with your Anthropic account and `squad new-plan --api` runs on your Claude plan — no API key, no per-token API bill. Usage draws on the same limits as Claude and Claude Code. Full guide: [`docs/auth.md`](docs/auth.md) · [on the site](https://squad-kit.com/docs/auth).
+- **`planner.auth.anthropic`** — `subscription` | `api-key` | `auto` (default `auto`). Existing API-key workspaces keep working; `squad doctor` gained `planner auth mode` and `planner auth vs. runtime` so the resolved mode is never a mystery.
+- **Console auth surface** — an Authentication control on Config, a Claude Account card on Secrets, an auth badge on Generate and on every run record.
+
+## What's new in 0.11.0
+
+- **Persisted run history** — `--api` runs append to `.squad/runs/<id>.events.jsonl` (thinking text redacted on disk, old files rotated), and the console gained a runs index plus a full run report page.
+- **Richer live telemetry** — tool lifecycle, thinking deltas, and runtime metadata stream to both the CLI and the console; the CLI prints a stage pipeline and budget meters.
+
+## What's new in 0.10.0
+
+- **Anthropic planning moved to the Claude Agent SDK** by default so Opus 4.7 can use adaptive thinking and effort. OpenAI and Google stay on the Vercel AI SDK.
+- **Thinking, effort, and runtime are configurable** — `planner.runtime.anthropic`, `planner.providerOptions.anthropic`, and the `--anthropic-runtime` / `--effort` / `--scout-effort` / `--no-thinking` flags.
+- **`squad doctor` checks runtime wiring**, model-vs-runtime fit, and the Agent SDK binary.
+
+## What's new in 0.9.0
+
+- **Scout stage** — a cheap-tier model picks the files worth preloading before your plan model drafts, cutting the expensive model's read loop.
+- **LLM-free validation pass** flags missing paths, line ranges past EOF, and simple symbol problems; `--strict-validation` writes `*.partial.md` when it finds something.
+
+## What's new in 0.8.0
+
+- **Rate-limit handling you can watch** — the Generate page shows a countdown, auto-retry banner, and rerun control; the planner emits `rate_limit` events distinguishing "retrying" from "aborted".
+
+## What's new in 0.7.0
+
+- **GitHub Issues as a tracker** — owner/repo in config, PAT (or `GITHUB_TOKEN`) in secrets, search and import like Jira or Azure. **Linear was removed** as a tracker type in the same release.
+
 ## What's new in 0.6.0
 
 - **Console redesign** — Geist-style flat dark UI, Cmd+K command palette, global keyboard shortcuts, portal dialogs, density toggle. Same CLI and `.squad/` on disk; no migration. See [`docs/console.md`](docs/console.md).
@@ -66,7 +96,7 @@ Full list in [`CHANGELOG.md`](CHANGELOG.md).
 Existing squad-kit users should run two commands, once per repo:
 
 ```bash
-pnpm add -g squad-kit@0.2.0       # or: npm install -g squad-kit@0.2.0 — or: squad upgrade
+pnpm add -g squad-kit             # or: npm install -g squad-kit — or: squad upgrade
 cd your-project && squad migrate
 ```
 
@@ -77,9 +107,9 @@ Full upgrade walkthrough, including what-if scenarios and how to recover customi
 ## Install
 
 ```bash
-npm install -g squad-kit@0.2.0
+npm install -g squad-kit
 # or
-pnpm add -g squad-kit@0.2.0
+pnpm add -g squad-kit
 ```
 
 Requires Node 18+.
@@ -104,6 +134,20 @@ No slash commands in your agent? Skip the meta-prompt copy-paste entirely:
 squad new-plan --api   # interactive picker, direct provider call, writes the plan file
 ```
 
+### Plan on your Claude subscription
+
+If you already pay for **Claude Pro or Max**, you do not need an Anthropic API key to use the direct planner:
+
+```bash
+squad init             # choose Anthropic, then "Use my Claude subscription (browser login)"
+squad auth login       # browser sign-in; or just run `claude` and use /login
+squad new-plan --api   # plans on your Claude plan
+```
+
+**No API key is needed** on this path. Planning usage draws on your **Claude plan's usage limits** — the same limits Claude and Claude Code consume — so there is no per-token API bill, but a long planning run does consume part of your window. Opus planning against a **Pro** plan drains that window noticeably faster than against **Max**.
+
+Already signed in to Claude Code? squad-kit picks that login up automatically. Prefer an API key? Nothing changed — set `planner.auth.anthropic: api-key`. Details, CI setup, precedence, and troubleshooting: [`docs/auth.md`](docs/auth.md) · [on the site](https://squad-kit.com/docs/auth).
+
 Configuration, credential edits, and non-interactive flags: see [`docs/customization.md`](docs/customization.md) and `squad config show`. Full walkthrough: [`docs/getting-started.md`](docs/getting-started.md).
 
 ## Commands
@@ -116,6 +160,7 @@ Configuration, credential edits, and non-interactive flags: see [`docs/customiza
 | `squad status` | Counts, next `NN`, planner and tracker rows (including credential source). |
 | `squad list [--feature <slug>]` | Table of stories and plan state. |
 | `squad tracker link [story] [id]` | Attach or update a tracker id on an intake. |
+| `squad auth <login\|status\|logout>` | Sign in to Anthropic with your Claude subscription, inspect the resolved auth, or clear the stored token. `login` takes `--token <v>` (CI) and `--print-only`; `status` takes `--json` and `--offline`. See [`docs/auth.md`](docs/auth.md) · [site](https://squad-kit.com/docs/auth). |
 | `squad config <show\|set\|unset\|remove-credential> …` | View and edit `.squad/config.yaml` and `.squad/secrets.yaml` interactively. See [`docs/customization.md`](docs/customization.md). |
 | `squad rm <story\|plan\|feature> [target] [--dry-run] [--trash] [-y]` | Safely delete with cascading overview updates. |
 | `squad doctor [--fix] [--json]` | Full health check; `--fix` applies non-destructive repairs. |
@@ -129,26 +174,44 @@ Deeper option lists: `squad <command> --help` and the `docs/` pages above.
 
 Off by default. Enable during `squad init` (answer **yes** to *Enable automatic plan generation?*) or later with `squad config set planner`. Supported providers: Anthropic, OpenAI, Google.
 
-Credential resolution order:
+### Credential resolution order
+
+**Anthropic — default: your Claude subscription**
 
-1. Provider env var (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`).
-2. `.squad/secrets.yaml` under `planner.<provider>.apiKey` (or cross-provider `SQUAD_PLANNER_API_KEY`).
+1. **`planner.auth.anthropic`** in `.squad/config.yaml` — `subscription` | `api-key` | `auto` (merged default: **`auto`**).
+2. **`subscription`** — the login created by `squad auth login` (or `claude` → `/login`), resolved in this order:
+   `CLAUDE_CODE_OAUTH_TOKEN` → `planner.anthropicOauthToken` in `.squad/secrets.yaml` → the OS credential store (macOS Keychain / `~/.claude/.credentials.json`).
+3. **`api-key`** — `ANTHROPIC_API_KEY` → `SQUAD_PLANNER_API_KEY` → `.squad/secrets.yaml`.
+4. **`auto`** — a detected Claude login first, otherwise the API key chain, otherwise fail naming both recovery paths.
+
+In subscription mode squad-kit **clears `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` from the planner subprocess** (your shell is untouched): both outrank the login credential inside Claude Code, so an inherited one would silently bill API credits instead. If you have a key exported and it is being ignored, that is why.
+
+`auth: subscription` requires the Agent SDK runtime — `planner.runtime.anthropic: vercel` is a hard, early failure, never a silent downgrade.
+
+**OpenAI / Google — API key only, unchanged**
+
+1. Provider env var (`OPENAI_API_KEY`, `GOOGLE_API_KEY`).
+2. `.squad/secrets.yaml` under `planner.<provider>` (or cross-provider `SQUAD_PLANNER_API_KEY`).
 3. Interactive prompt (TTY only).
 4. Fail with a recovery hint.
 
+The deep page — both login paths, per-platform credential storage, CI, usage limits, and a troubleshooting table — is [`docs/auth.md`](docs/auth.md), also served at [squad-kit.com/docs/auth](https://squad-kit.com/docs/auth).
+
 Override the default plan-phase model without editing squad-kit:
 
 ```yaml
 planner:
   enabled: true
   provider: anthropic
+  auth:
+    anthropic: subscription   # or api-key, or auto (default)
   cache:
     enabled: true   # default; turn off via squad config set planner
   modelOverride:
     anthropic: claude-opus-5-0      # riding a newer provider release early
 ```
 
-`squad status` marks the planner row `(override)` when a `modelOverride` is active. `squad doctor` probes the provider's `/v1/models` endpoint (no paid completion) and tells you what to do if the id is no longer served.
+`squad status` marks the planner row `(override)` when a `modelOverride` is active, and shows a **planner auth** row with the resolved mode. `squad doctor` probes the provider's `/v1/models` endpoint (no paid completion) and tells you what to do if the id is no longer served — that probe and the API rate-tier check both **skip on subscription auth**, since there is no API key to list models with and no API rate tier to warn about.
 
 Slash commands inside your agent (`/squad-plan`) continue to work unchanged — the agent already has your repo in scope. The direct planner is an alternative path, not a replacement. For where keys live, see [Secrets](#secrets) below and [`docs/customization.md`](docs/customization.md).
 
@@ -174,9 +237,11 @@ squad-kit stores settings in two files:
 | File | Purpose | Git-tracked? | Editable by hand? |
 | --- | --- | --- | --- |
 | `.squad/config.yaml` | Project name, tracker, naming, agents, planner shape. | yes — commit it | yes, but `squad config set` is safer |
-| `.squad/secrets.yaml` | Planner + tracker API tokens. | **no** — auto-ignored, `0600` on POSIX | no — use `squad config set` / `squad init` |
+| `.squad/secrets.yaml` | Planner + tracker API tokens, and the Claude OAuth token (`planner.anthropicOauthToken`). | **no** — auto-ignored, `0600` on POSIX | no — use `squad auth login` / `squad config set` / `squad init` |
+
+`config.yaml` rejects credential-shaped key names at load time — `apiKey`, `api_key`, `token`, `oauthToken`, `anthropicOauthToken`, `secret`, `credential`, `credentials` — so accidental commits fail loud. Matching is on the **exact lowercased key name**, not a substring: a substring rule would reject the legitimate `planner.maxOutputTokens`. Any future credential-shaped key has to be added to that list by name.
 
-`config.yaml` rejects any key matching `apiKey`, `token`, `secret`, or `credential` at load time, so accidental commits fail loud. Rotate a credential with `squad config set planner` or `squad config set tracker`; remove one with `squad config remove-credential <section>`.
+Rotate a credential with `squad config set planner` or `squad config set tracker`; remove one with `squad config remove-credential <section>`. `squad auth logout` removes only the Claude OAuth token squad-kit stored and never touches your global Claude Code login.
 
 ## Why not Spec-Kit?
 
@@ -184,7 +249,7 @@ Both aim at spec-driven development. They make different bets.
 
 | | squad-kit | Spec-Kit |
 | --- | --- | --- |
-| Commands | `init`, `new-story`, `new-plan`, `status`, `doctor`, `migrate`, `upgrade`, `list`, `rm`, `tracker link`, `config` | `constitution`, `specify`, `clarify`, `plan`, `tasks`, `analyze`, `checklist`, `implement` |
+| Commands | `init`, `new-story`, `new-plan`, `status`, `doctor`, `migrate`, `upgrade`, `list`, `rm`, `tracker link`, `auth`, `config` | `constitution`, `specify`, `clarify`, `plan`, `tasks`, `analyze`, `checklist`, `implement` |
 | `/implement` turn starts with | one plan file (~5–15 KB) | 5–7 command templates + cross-artifact reads (~15–25 KB) |
 | Model-tier awareness | Built into the philosophy (planner ≠ executor) | Not prescribed |
 | Generated artifacts per story | `intake.md`, `NN-story-<id>.md`, overview row | `spec.md`, `plan.md`, `data-model.md`, `contracts/`, `research.md`, `quickstart.md`, `tasks.md` |
@@ -202,6 +267,7 @@ See [`docs/philosophy.md`](docs/philosophy.md) for the token math and [`docs/vs-
 - **Plans are project-coupled.** They reference real file paths. That is the point — do not expect portability between projects.
 - **Global `NN` can collide on parallel branches.** Rebase-and-renumber is the resolution. Documented in [`docs/customization.md`](docs/customization.md).
 - **Anthropic Tier 1 + Opus** shares a tight input-token-per-minute bucket. **0.3.0** added prompt caching (on by default) so typical multi-turn plans stay viable; see [Prompt caching](docs/customization.md#prompt-caching) in the customization docs.
+- **Subscription planning is not free planning.** It removes the per-token API bill, not the cost: Agent SDK usage draws on your Claude plan's usage limits. Opus planning on **Pro** will exhaust a window much faster than on **Max**. See [`docs/auth.md`](docs/auth.md).
 
 ## Non-goals for 0.2
 

package/SECURITY.md

@@ -37,12 +37,26 @@ squad-kit reads API tokens from (in order):
 2. **`.squad/secrets.yaml`** — created with mode `0600` on POSIX; always included in `.gitignore` by `squad init`.
 3. **Interactive prompt** — when the terminal is a TTY and the command needs a credential that is missing.
 
+### Anthropic subscription credentials (0.12.0+)
+
+The Anthropic planner can authenticate with a Claude subscription instead of an API key. That path resolves, in order: **`CLAUDE_CODE_OAUTH_TOKEN`** → **`planner.anthropicOauthToken` in `.squad/secrets.yaml`** → the **OS credential store** managed by Claude Code.
+
+- The OAuth token is a credential and is treated as one: it lives in `.squad/secrets.yaml` only (git-ignored, `0600` on POSIX), is masked everywhere it is displayed, and is rejected by name if it appears in `.squad/config.yaml`.
+- squad-kit **never reads** the OS credential store. It checks only whether an entry **exists** (on macOS via `security find-generic-password -s "Claude Code-credentials"`, never `-w` / `-g`) and leaves the reading to the Claude Agent SDK.
+- In subscription mode, `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` are **removed from the planner subprocess environment** (case-insensitively). Both outrank the subscription credential inside Claude Code, so an inherited one would silently redirect usage to API billing. The parent shell is not modified.
+- `squad auth logout` removes **only** the token squad-kit stored. It never deletes the user's global Claude Code credential.
+- Persisted run records (`.squad/runs/*.json`, `*.events.jsonl`) carry the resolved auth **mode** and `apiKeySource` only — never a token, key, email, or organization. Account details are fetched live for display and never written to disk.
+
 ### Non-goals
 
-- `.squad/config.yaml` must never contain secrets. Loading it with a key matching `apiKey`, `api_key`, `token`, `secret`, `credential`, or `credentials` raises a loud error.
-- squad-kit does not integrate with OS keychains in 0.2.0. The secrets file model is intentional: it is inspectable, excluded by ignore rules, and portable.
+- `.squad/config.yaml` must never contain secrets. Loading it with a key whose lowercased name is exactly `apikey`, `api_key`, `token`, `oauthtoken`, `anthropicoauthtoken`, `secret`, `credential`, or `credentials` raises a loud error. Matching is exact rather than substring so that legitimate keys such as `planner.maxOutputTokens` keep loading; new credential-shaped keys must be added to that list by name.
+- squad-kit does not **store** credentials in an OS keychain. It will detect and use a Claude Code login held in one (see above), but its own secrets model remains the `.squad/secrets.yaml` file: inspectable, excluded by ignore rules, and portable.
 - Credentials are never logged. Tracker error messages redact tokens; planner provider errors do the same.
 
+### Known limitation — enterprise managed settings
+
+squad-kit runs the Agent SDK with `settingSources: []`, which prevents it from reading user, project, and local settings files. An ordinary user-level `apiKeyHelper` therefore cannot redirect a subscription run. **Policy settings are always merged regardless**, so an enterprise **managed-settings** `apiKeyHelper` deployed by MDM is still honoured and still outranks the login credential. On a managed device, `planner.auth.anthropic: subscription` may resolve through the organization's helper. This was established by reading the credential resolver in the bundled `claude` binary, not by testing on a live managed device. `squad auth status` reports the `apiKeySource` the SDK actually resolved.
+
 ## Scope
 
 squad-kit is a local-only CLI. It can call **optional** network APIs (tracker fetch, direct planner) when the user enables those flows and provides credentials. It does not execute user code. Reports in scope include: