hoomanjs 1.46.0 → 1.55.0

package/dist/core/skills/built-in/hooman-design/craft/spacing-density.md

@@ -0,0 +1,46 @@
+# Spacing and density craft rules
+
+Spacing is a system, not one-off margins.
+
+## Scale
+
+Prefer a 4 px base. Expose tokens in `:root`:
+
+| Token       | Default | Use                           |
+| ----------- | ------- | ----------------------------- |
+| `--space-1` | 4px     | Hairline tweaks               |
+| `--space-2` | 8px     | Icon gaps, compact stacks     |
+| `--space-3` | 12px    | Related control groups        |
+| `--space-4` | 16px    | Default component padding     |
+| `--space-5` | 24px    | Section padding (compact)     |
+| `--space-6` | 32px    | Section padding (comfortable) |
+| `--space-7` | 48px    | Major section breaks          |
+| `--space-8` | 64px    | Hero / slide outer padding    |
+
+## Density postures
+
+| Posture         | When                        | Notes                                               |
+| --------------- | --------------------------- | --------------------------------------------------- |
+| **Comfortable** | Marketing, editorial, decks | Larger type, `--space-6`+ section gaps              |
+| **Standard**    | Product UI, settings        | `--space-4` / `--space-5`                           |
+| **Dense**       | Tables, consoles, ops       | `--space-2` / `--space-3`; never starve hit targets |
+
+Pick one posture per artifact. Do not mix hero-airy with table-cramped in the same view without a clear region boundary.
+
+## Stacking
+
+- Vertical rhythm: consistent gap between siblings (`gap` on flex/grid > random margins)
+- Related items closer than unrelated (proximity)
+- Separate regions with space **or** a hairline — not both stacked heavily
+
+## Cards and lists
+
+- Internal padding ≥ `--space-4` on all sides unless dense table cells
+- Gap between cards ≥ internal padding (avoid “tile wallpaper”)
+- List rows: align baselines; meta column must not collide with primary text
+
+## Anti-patterns
+
+- `margin: 10px 15px 8px 12px` snowflake values
+- Huge hero padding + cramped footer on the same slide
+- Nested cards each adding full padding until content is a postage stamp

package/dist/core/skills/built-in/hooman-design/craft/state-coverage.md

@@ -0,0 +1,21 @@
+# State coverage craft rules
+
+Every interactive surface that fetches or accepts data must render these states.
+
+| State         | Must contain                                                        |
+| ------------- | ------------------------------------------------------------------- |
+| **Loading**   | Skeleton/spinner + long-wait fallback                               |
+| **Empty**     | Headline, explanation, primary CTA                                  |
+| **Error**     | Plain-language cause, recovery action, preserved input              |
+| **Populated** | The primary designed case                                           |
+| **Edge**      | Long strings, missing optionals, dense data — layout must not break |
+
+## Forms
+
+- Validate on blur (not first keystroke)
+- Untouched / dirty-valid / submitted-pending states
+- Lock submit while pending; never wipe user input on error
+
+## Check
+
+Before shipping, mentally walk each list, table, card, form, and panel through all five states. Missing empty/error is the most common silent AI-UI failure.

package/dist/core/skills/built-in/hooman-design/craft/typography.md

@@ -0,0 +1,73 @@
+# Typography craft rules
+
+`DESIGN.md` / directions choose fonts; this file governs behavior.
+
+## Prefer Google Fonts (webfonts)
+
+For HTML artifacts that will export to **Sketch** (and for consistent preview across machines), load display/body faces from [Google Fonts](https://fonts.google.com/) instead of relying on system-only stacks:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link
+  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&family=Source+Serif+4:opsz,wght@8..60,600;8..60,700&display=swap"
+  rel="stylesheet"
+/>
+<style>
+  :root {
+    --font-display: "Source Serif 4", Georgia, ui-serif, serif;
+    --font-body: Inter, system-ui, sans-serif;
+  }
+</style>
+```
+
+Why:
+
+- Preview and Playwright measure use the same faces
+- `export_design` `format: "sketch"` **embeds** document `@font-face` / Google Fonts TTFs into the `.sketch` (`fontReferences`) so collaborators see correct type without installing fonts
+- System fonts (Georgia, SF Pro, …) are **not** scraped from disk — keep them only as fallbacks after a webfont
+
+Rules:
+
+- Max 2 families; load only weights you use (400/600/700 typical)
+- Self-host under `assets/fonts/` is fine if you ship `@font-face` with `.ttf` / `.otf` (WOFF2 alone will not embed in Sketch)
+- Do not invent proprietary font names without a real `@font-face` or Google link
+
+## Type scale
+
+Use a multiplicative scale (1.2–1.25). Cap at 6–8 sizes.
+
+| Role    | Range    |
+| ------- | -------- |
+| Display | 48–72 px |
+| H1      | 32–48 px |
+| H2      | 24–32 px |
+| H3      | 20–24 px |
+| Body    | 15–18 px |
+| Small   | 13–14 px |
+| Caption | 11–12 px |
+
+## Line height
+
+| Text size             | Line height |
+| --------------------- | ----------- |
+| Display / H1 (≥32 px) | `1.0`–`1.2` |
+| Body (15–18 px)       | `1.5`–`1.6` |
+| Small (≤14 px)        | `1.5`       |
+
+## Letter-spacing
+
+| Context             | Letter-spacing                  |
+| ------------------- | ------------------------------- |
+| Body 14–18 px       | `0`                             |
+| Small 11–13 px      | `0.01em`–`0.02em`               |
+| UI labels / buttons | `0.02em`                        |
+| **ALL CAPS**        | **`0.06em`–`0.1em` (required)** |
+| Headings 32 px+     | `-0.01em`–`-0.02em`             |
+| Display 48 px+      | `-0.02em`–`-0.03em`             |
+
+## Pairing
+
+- Max 2 typefaces per artifact
+- Do not set body below 15 px for long reading
+- Prefer `clamp()` for display on responsive prototypes

package/dist/core/skills/built-in/hooman-design/directions.md

@@ -0,0 +1,115 @@
+# Directions (when no DESIGN.md)
+
+Pick **one** direction and stick to it for the artifact — but only after the user chooses it via `ask_user` (see `references/workflow.md` phase 4). When ranking options, offer the **5 best-fit** ids for the brief (recommended first) plus **Other / custom**. State the chosen id in chat. Do not invent an indigo-on-white theme outside these packs.
+
+Copy matching tokens from `assets/tokens/<id>.css` into the artifact `:root`.
+
+**Fonts:** Prefer [Google Fonts](https://fonts.google.com/) for `--font-display` / `--font-body` (see `craft/typography.md`) so preview, measure, and Sketch embed share the same faces. Keep Georgia / system-ui only as fallbacks after a webfont link.
+
+## `editorial-ink`
+
+- Posture: calm editorial product marketing
+- Surfaces: near-white `#f7f5f2`, ink `#1a1a1a`
+- Accent: deep teal `#0f6b6b` (max 2 visible uses per screen)
+- Display: Georgia / `ui-serif`; body: system UI sans
+- Avoid: gradients, purple accents, emoji icons
+- Good shells: `landing-shell`, `prototype-shell`, `email-shell`, `invite-shell`, `resume-shell`
+
+## `swiss-grid`
+
+- Posture: dense, precise, high-contrast utility
+- Surfaces: pure white `#ffffff`, black `#0a0a0a`
+- Accent: signal red `#c8102e`
+- Type: Inter / system sans only; tight tracking on caps (`0.08em`)
+- Avoid: soft shadows, rounded mega-cards, decorative blobs
+- Good shells: `settings-shell`, `pricing-shell`, `deck-shell` (light variant)
+
+## `night-console`
+
+- Posture: dark operational / dashboard
+- Surfaces: `#0d1117`, elevated `#161b22`
+- Accent: `#58a6ff`; success `#3fb950`; warning `#d29922`
+- Type: system UI sans; monospace for metrics
+- Avoid: neon purple, glassmorphism stacks, fake sparklines
+- Good shells: `dashboard-shell`, `deck-shell` (default dark)
+
+## `warm-atelier`
+
+- Posture: craft / studio / portfolio
+- Surfaces: warm paper `#f4efe6`, charcoal `#2c241b`
+- Accent: burnt orange `#c45c26`
+- Display: serif; body: humanist sans
+- Avoid: cool gray chrome, stock Unsplash heroes
+- Good shells: `landing-shell`, `prototype-shell`, `flyer-shell`, `invite-shell`
+
+## `fintech-clear`
+
+- Posture: trustworthy finance / B2B SaaS
+- Surfaces: `#f8fafc`, `#ffffff`, border `#e2e8f0`
+- Accent: `#0f766e` (teal); text `#0f172a`
+- Type: system sans; generous body leading `1.55`
+- Avoid: crypto neon, indigo Tailwind defaults, invented ROI metrics
+- Good shells: `pricing-shell`, `auth-shell`, `contact-shell`, `settings-shell`
+
+## `signal-mono`
+
+- Posture: brutalist / launch / manifesto
+- Surfaces: `#111111`, type `#fafafa`, rules `#333333`
+- Accent: single electric `#ffe600` (one use per view)
+- Type: condensed system sans or IBM Plex Sans; heavy weight on display
+- Avoid: soft radii, pastels, illustration filler
+- Good shells: `landing-shell`, `deck-shell`, `flyer-shell`, `business-card-shell`
+
+## `soft-product`
+
+- Posture: friendly consumer / productivity app
+- Surfaces: `#fafafa`, cards `#ffffff`, border `#ececec`
+- Accent: `#2563eb` only if brand requires blue — prefer a brand-specific hue from the brief; never default indigo stack
+- Type: system UI sans; slightly larger body (16–17 px)
+- Avoid: skeuomorphism, heavy gradients, emoji icon grids
+- Good shells: `auth-shell`, `newsletter-shell`, `waitlist-shell`, `settings-shell`, `dashboard-shell` (lighten tokens)
+
+## `harbor-navy`
+
+- Posture: institutional / classic B2B / professional services
+- Surfaces: cool gray `#f3f5f8`, ink `#0b1f33`
+- Accent: deep navy `#1e3a5f` (sparse; prefer type hierarchy over color)
+- Display: serif for titles; body: system sans
+- Avoid: neon accents, playful illustration, soft-product blues
+- Good shells: `landing-shell`, `pricing-shell`, `article-shell`, `resume-shell`, `business-card-shell`
+
+## `paper-mono`
+
+- Posture: print / CV / quiet documentation
+- Surfaces: stone `#f5f5f4`, paper white, ink `#171717`
+- Accent: ink itself (near-monochrome; status colors only when needed)
+- Display: transitional serif; body: system sans; tight small type OK
+- Avoid: colored hero washes, large radii, decorative shadows
+- Good shells: `resume-shell`, `article-shell`, `email-shell`, `flyer-shell`
+
+## `botanical-calm`
+
+- Posture: wellness / nature / quiet consumer product
+- Surfaces: sage wash `#f4f6f1`, soft paper `#fbfcf8`
+- Accent: leaf green `#3f6b4e` (max 2 uses per screen)
+- Display: serif; body: system sans; generous leading
+- Avoid: neon fitness gradients, emoji icon grids, purple wellness clichés
+- Good shells: `landing-shell`, `onboarding-shell`, `newsletter-shell`, `invite-shell`
+
+## `midnight-editorial`
+
+- Posture: dark magazine / portfolio / cultural brand
+- Surfaces: near-black `#121212`, warm paper ink `#f3efe6`
+- Accent: copper `#d4a574` (one strong moment per view)
+- Display: Georgia / serif; body: system sans
+- Avoid: neon cyberpunk, glassmorphism, signal-yellow
+- Good shells: `landing-shell`, `article-shell`, `deck-shell`, `business-card-shell`
+
+## `copper-ledger`
+
+- Posture: warm utility / docs / ops with craft feel
+- Surfaces: warm gray `#f7f3ee`, paper `#fffdf9`
+- Accent: saddle copper `#8b4513`
+- Type: system sans throughout; monospace for IDs / codes
+- Avoid: cool slate-only chrome, fintech teal defaults, soft blue CTAs
+- Good shells: `settings-shell`, `data-table-shell`, `dashboard-shell`, `article-shell`

package/dist/core/skills/built-in/hooman-design/references/artifact-layout.md

@@ -0,0 +1,15 @@
+# Artifact layout
+
+Write design artifacts only under:
+
+```
+.hooman/design/<slug>/
+  index.html     # required entry
+  assets/        # optional images, fonts, copied tokens
+  reviews/       # screenshots from export_design format:images (visual QA)
+  export/        # optional PDF / PPTX / screenshot-backed .fig / .deck / .sketch
+```
+
+- `<slug>` is kebab-case from the brief (reuse the same slug when refining).
+- Do not invent parallel trees outside `.hooman/design/<slug>/`.
+- Delivery exports (`pdf` / `images-to-pdf` / `pptx` / `figma` / `figma-deck` / `sketch`) land under `export/` by default.

package/dist/core/skills/built-in/hooman-design/references/export.md

@@ -0,0 +1,47 @@
+# Export
+
+Use the built-in tool (do not hand-roll PDF/PPTX/Figma/Sketch with shell):
+
+- `export_design` with `format`:
+  - `images` — page screenshots under `reviews/` by default (visual QA; then `launch_subagent` with `kind: "design-review"`)
+  - `pdf` — Chromium print PDF under `export/`
+  - `images-to-pdf` — screenshot pages stitched into a PDF under `export/`
+  - `pptx` — screenshot-backed PPTX under `export/`
+  - `figma` — screenshot-backed Figma Design `.fig` under `export/` (one image frame per page)
+  - `figma-deck` — screenshot-backed Figma Slides `.deck` under `export/` (one image slide per page)
+  - `sketch` — screenshot-backed Sketch `.sketch` under `export/` (one image artboard per page)
+
+## Gate: visual QA + human go-ahead first
+
+Do **not** call delivery formats (`pdf` / `images-to-pdf` / `pptx` / `figma` / `figma-deck` / `sketch`) until:
+
+1. `export_design` with `format: "images"` has written current `reviews/` shots, and
+2. `launch_subagent` with `kind: "design-review"` has run with those shot paths (binary reads), and
+3. Must-fix is empty — or you hit the 2–3 round cap and will report remaining Must-fix to the user, and
+4. The user has accepted the live preview (or explicitly asked to export anyway) and chosen a delivery format via `ask_user` (see `workflow.md` phases 7–8).
+
+Keep `preview_design` running until after delivery export, then `stop_design_preview`.
+
+Capturing screenshots and then delivering without review is a process failure.
+
+## When
+
+- User asks for PDF/PPTX, Figma (`.fig` / `.deck`), Sketch (`.sketch`), or
+- Delivering a deck / printable one-pager / design-tool handoff as the deliverable
+- **and** the gate above is satisfied
+
+## Deck convention
+
+Mark each slide root with `data-slide` so export paginates correctly:
+
+```html
+<section data-slide>...</section>
+```
+
+Without `data-slide`, export treats the document as a long page (PDF multipage / single PPTX slide or paginated viewports). For `figma` / `figma-deck` / `sketch` / `pptx`, each `[data-slide]` becomes one screenshot page/slide/frame/artboard.
+
+## Notes
+
+- First PDF/PPTX/`images` / Figma / Sketch export may need Playwright Chromium (`npx playwright install chromium`).
+- `pptx`, `images-to-pdf`, `images`, `figma`, `figma-deck`, and `sketch` are all **screenshot-backed** (visual fidelity). They are not native editable layer trees — open them in the target app as flat image frames/slides/artboards, like a PPTX built from screenshots.
+- Prefer `figma-deck` for `[data-slide]` decks when the handoff is Figma Slides; prefer `figma` for multi-frame Design files; prefer `sketch` when the handoff is Sketch; prefer `pptx` for PowerPoint.

package/dist/core/skills/built-in/hooman-design/references/workflow.md

@@ -0,0 +1,80 @@
+# Design workflow (strict)
+
+Follow these phases **in order** for every new brief. Do not skip ahead to writing HTML. Use `ask_user` for each decision (one question per call). Users can always type a free-form answer; still offer concrete choices.
+
+## Phase 0 — Activate
+
+If `hooman-design` is not active, activate it before any design write.
+
+## Phase 1 — Intake (what they already have)
+
+Ask what starting material they have. Recommended options (adapt labels; keep ≤6):
+
+1. Brand / `DESIGN.md` notes only
+2. Nothing — start fresh from a template
+3. Reference images / screenshots to recreate in HTML
+4. Mix / other (I'll describe)
+
+**`DESIGN.md`:** If a `DESIGN.md` is already injected in the system prompt, say so and do **not** ask whether one exists — ask only whether to honor it as-is or override for this artifact. If none is injected, include an option or follow-up to capture brand tokens / write guidance into the brief (do not invent a parallel brand file unless the user asks).
+
+## Phase 2 — Clarify the brief
+
+Ask focused follow-ups until you can name: audience, surface (landing / deck / dashboard / form / …), must-have sections or slides, tone, and hard constraints (print size, dark-only, no stock photos, …). Prefer 1–3 `ask_user` rounds over guessing. Do **not** write HTML until this is clear enough to pick a shell.
+
+## Phase 3 — Template (shell)
+
+From the shells table in `SKILL.md`, pick the **5 best-fit** shells for this brief (recommended first). Offer them via `ask_user` plus a 6th option: **Other / custom (I'll describe)**.
+
+Read the chosen shell HTML under `assets/` before building. Only invent structure from scratch when they choose Other / custom.
+
+## Phase 4 — Color theme (direction)
+
+- If `DESIGN.md` is in force: skip picking a library direction; bind to those tokens.
+- Otherwise: from `directions.md`, offer the **5 best-fit** direction ids (recommended first) plus **Other / custom (I'll describe)**. Copy matching `assets/tokens/<id>.css` into the artifact `:root` when they pick a library direction.
+
+State the chosen shell + direction (or DESIGN.md) in chat in one short line, then build.
+
+## Phase 5 — Build
+
+Write only under `.hooman/design/<slug>/` (`index.html` + optional `assets/`). Prefer the shell + tokens.
+
+## Phase 6 — Preview + internal visual QA
+
+After the first meaningful HTML write (and after each Must-fix round):
+
+1. `preview_design` on the entry (keep this running — do **not** stop yet)
+2. `export_design` `format: "images"`
+3. `launch_subagent` `kind: "design-review"` (binary-read every shot)
+4. Fix Must-fix → re-capture → re-review (max 2–3 rounds)
+
+Do **not** call delivery export formats until Must-fix is empty or you hit the round cap and report remaining issues honestly.
+
+## Phase 7 — Human review
+
+When internal QA is clear (or capped), **ask the user** to look at the live preview and give feedback. Options like: Looks good — export / Needs changes (I'll describe) / Start over.
+
+Iterate Phases 5–7 on feedback. Keep the preview open across iterations (hot reload).
+
+## Phase 8 — Export format
+
+Only after the user confirms the design is good enough, ask which delivery format(s) they want. Offer the best-fit set for the surface, e.g.:
+
+1. Figma Design (`.fig`) — screenshot-backed
+2. Figma Slides (`.deck`) — prefer for `[data-slide]` decks; screenshot-backed
+3. Sketch (`.sketch`) — screenshot-backed
+4. PDF
+5. PowerPoint (`.pptx`)
+6. Other / multiple (I'll describe)
+
+Then call `export_design` with the chosen delivery `format`(s). See `export.md`.
+
+## Phase 9 — Stop preview
+
+Call `stop_design_preview` with the same HTML path **only after** delivery export finishes (or the user explicitly declines export / ends the session without exporting). Never stop preview before export when the user asked to ship a file.
+
+## Shortcuts that are forbidden
+
+- Writing HTML before intake + clarify + template (+ theme when no DESIGN.md)
+- Auto-picking a direction without asking when no DESIGN.md applies
+- Capturing screenshots then exporting / finishing without `launch_subagent` (`kind: "design-review"`)
+- Stopping preview before delivery export when export was requested

package/dist/core/skills/built-in/hooman-mcp/SKILL.md

@@ -90,11 +90,11 @@ hooman mcp logout <server> --scope all # Clear discovery, client registration, a
 hooman mcp logout <server> --scope client # Clear only the registered OAuth client
 hooman mcp logout <server> --scope tokens # Clear only the stored access/refresh tokens
 hooman mcp logout <server> --scope discovery # Clear only cached OAuth server metadata
-hooman mcp auth-status # Show OAuth status for all configured MCP servers
+hooman mcp status # Show OAuth status for all configured MCP servers
 ```
 
 - `<server>` must match a key under `mcpServers` in `mcp.json`.
 - `hooman mcp auth` starts the OAuth flow (opening a local callback server as needed) and stores credentials in `~/.hooman/mcp-oauth.json`.
 - `hooman mcp logout` clears stored OAuth state without touching `mcp.json`; use it before re-authenticating with different credentials or when decommissioning a server.
-- `hooman mcp auth-status` reports each server's OAuth state (e.g. authenticated, expired, not authenticated) without making network calls to the server itself beyond what's needed to read stored state.
+- `hooman mcp status` reports each server's OAuth state (e.g. authenticated, expired, not authenticated) without making network calls to the server itself beyond what's needed to read stored state.
 - These commands operate on the home config (`~/.hooman/mcp.json`) only, not repo-local `.hooman/mcp.json` overlays.

package/dist/core/state/llm-modality.d.ts

@@ -0,0 +1,13 @@
+import type { ResolvedLlmInputModality } from "../utils/model-metadata.js";
+/** Strands appState key for the active LLM's resolved input modalities. */
+export declare const LLM_MODALITY_STATE_KEY = "hooman.llmModality";
+type AppStateLike = {
+    get(key: string): unknown;
+    set(key: string, value: unknown): void;
+};
+type AgentLike = {
+    appState: AppStateLike;
+};
+export declare function getLlmModality(agent: AgentLike | undefined): ResolvedLlmInputModality | null;
+export declare function setLlmModality(agent: AgentLike, modality: ResolvedLlmInputModality | null | undefined): void;
+export {};

package/dist/core/state/llm-modality.js

@@ -0,0 +1,19 @@
+/** Strands appState key for the active LLM's resolved input modalities. */
+export const LLM_MODALITY_STATE_KEY = "hooman.llmModality";
+function isModality(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        typeof value.text === "boolean");
+}
+export function getLlmModality(agent) {
+    if (!agent) {
+        return null;
+    }
+    const raw = agent.appState.get(LLM_MODALITY_STATE_KEY);
+    return isModality(raw) ? raw : null;
+}
+export function setLlmModality(agent, modality) {
+    agent.appState.set(LLM_MODALITY_STATE_KEY, modality ?? null);
+}
+//# sourceMappingURL=llm-modality.js.map

package/dist/core/state/llm-modality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-modality.js","sourceRoot":"","sources":["../../../src/core/state/llm-modality.ts"],"names":[],"mappings":"AAEA,2EAA2E;AAC3E,MAAM,CAAC,MAAM,sBAAsB,GAAG,oBAAoB,CAAC;AAW3D,SAAS,UAAU,CAAC,KAAc;IAChC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACrB,OAAQ,KAA4B,CAAC,IAAI,KAAK,SAAS,CACxD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,KAA4B;IAE5B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;IACvD,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,KAAgB,EAChB,QAAqD;IAErD,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,sBAAsB,EAAE,QAAQ,IAAI,IAAI,CAAC,CAAC;AAC/D,CAAC"}

package/dist/core/state/plan.d.ts

@@ -3,7 +3,7 @@ export declare const PLAN_ENTER_REASON_STATE_KEY = "hooman.enterReason";
 export declare const PLAN_ENTERED_AT_STATE_KEY = "hooman.enteredAt";
 /**
  * Last plan file used in this session. Survives {@link clearPlanState} so a
- * later `enter_plan_mode` can reopen the same document instead of minting a new
+ * later `switch_mode` into plan can reopen the same document instead of minting a new
  * one. Only cleared when a fresh plan is explicitly requested.
  */
 export declare const PLAN_LAST_FILE_STATE_KEY = "hooman.lastPlanFile";

package/dist/core/state/plan.js

@@ -3,7 +3,7 @@ export const PLAN_ENTER_REASON_STATE_KEY = "hooman.enterReason";
 export const PLAN_ENTERED_AT_STATE_KEY = "hooman.enteredAt";
 /**
  * Last plan file used in this session. Survives {@link clearPlanState} so a
- * later `enter_plan_mode` can reopen the same document instead of minting a new
+ * later `switch_mode` into plan can reopen the same document instead of minting a new
  * one. Only cleared when a fresh plan is explicitly requested.
  */
 export const PLAN_LAST_FILE_STATE_KEY = "hooman.lastPlanFile";

package/dist/core/state/shell-jobs.d.ts

@@ -0,0 +1,9 @@
+import type { ShellJobInfo } from "../shell/types.js";
+export type ShellJobViewState = {
+    visible: boolean;
+    jobs: ShellJobInfo[];
+    active: number;
+};
+type AgentLike = object;
+export declare function getShellJobViewState(agent: AgentLike): ShellJobViewState;
+export {};

package/dist/core/state/shell-jobs.js

@@ -0,0 +1,20 @@
+import { peekShellJobManager } from "../shell/registry.js";
+const ACTIVE = new Set([
+    "starting",
+    "running",
+    "ready",
+]);
+export function getShellJobViewState(agent) {
+    const manager = peekShellJobManager(agent);
+    if (!manager) {
+        return { visible: false, jobs: [], active: 0 };
+    }
+    const jobs = manager.list();
+    const activeJobs = jobs.filter((j) => ACTIVE.has(j.status));
+    return {
+        visible: activeJobs.length > 0,
+        jobs: activeJobs,
+        active: activeJobs.length,
+    };
+}
+//# sourceMappingURL=shell-jobs.js.map

package/dist/core/state/shell-jobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-jobs.js","sourceRoot":"","sources":["../../../src/core/state/shell-jobs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAQ3D,MAAM,MAAM,GAAgC,IAAI,GAAG,CAAC;IAClD,UAAU;IACV,SAAS;IACT,OAAO;CACR,CAAC,CAAC;AAIH,MAAM,UAAU,oBAAoB,CAAC,KAAgB;IACnD,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IACjD,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAC5B,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5D,OAAO;QACL,OAAO,EAAE,UAAU,CAAC,MAAM,GAAG,CAAC;QAC9B,IAAI,EAAE,UAAU;QAChB,MAAM,EAAE,UAAU,CAAC,MAAM;KAC1B,CAAC;AACJ,CAAC"}

package/dist/core/state/tool-approvals.d.ts

@@ -6,21 +6,24 @@ type AppStateLike = {
 type AgentLike = {
     appState: AppStateLike;
 };
-export declare const ENTER_PLAN_MODE_TOOL = "enter_plan_mode";
-export declare const EXIT_PLAN_MODE_TOOL = "exit_plan_mode";
+/** Session mode switch; always requires explicit approval (never yolo / always-allow). */
+export declare const SWITCH_MODE_TOOL = "switch_mode";
 export declare const INTERNAL_ALWAYS_ALLOWED: Set<string>;
 /**
- * In session mode `plan`, block `write_file` / `edit_file` unless the target path resolves
- * under the app plans directory. Runs before any “always allow” grant so plan boundaries
- * cannot be overridden by tooling preferences.
+ * In plan mode, reject `write_file` / `edit_file` unless the destination path
+ * is under the plans directory, and reject `fetch` with `save_as` entirely.
+ * Runs before any “always allow” grant.
  */
 export declare function planModeWriteEditRejectionMessage(agent: AgentLike, toolName: string, toolInput: unknown): string | null;
 /**
  * Implicit, always-on allow for filesystem tools whose targets stay inside
- * trusted roots: reads under attachments or plans in every mode, plus reads
- * under the session cwd in ask/plan mode; writes/edits remain limited to the
- * plans directory. Persistent "always allow" grants are handled separately by
- * the on-disk {@link Allowlist} (see `../approvals/allowlist.ts`).
+ * trusted roots: reads under attachments, plans, or bundled skills in every
+ * mode, plus reads under the session cwd in ask/plan/design; writes/edits under
+ * the plans directory in every mode, and under `.hooman/design/` in design mode.
+ * Design tools (`preview_design`, `stop_design_preview`, `export_design`) are
+ * also auto-allowed when `path` is under `.hooman/design/`. Persistent "always
+ * allow" grants are handled separately by the on-disk {@link Allowlist}
+ * (see `../approvals/allowlist.ts`).
  */
 export declare function isImplicitlyAllowed(toolName: string, toolInput?: unknown, mode?: SessionMode): boolean;
 export declare function isToolVisible(mode: SessionMode, toolName: string, options?: {