@falkenslab/agent-kit 0.10.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francisco Vargas Ruiz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# agent-kit
+
+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 (human oversight, safety, memory and a good terminal interface), so each concrete agent only has to write what belongs to its own domain: what it knows how to do, with which tools, and how it talks.
+
+> **Status:** version `0.x`, still evolving. MIT license.
+
+## What an agent built with it can do
+
+- **Work at different levels of oversight.** Autonomous, guided (it asks for permission before anything that can't be undone or that other people will see) or step by step (it asks before every action). Within the same conversation you can switch from guided to step by step and back.
+- **Ask a person for help.** It asks for approvals, or stops so someone can do something by hand, such as signing in to a website. It can be answered from the keyboard or from another program driving it, for example a desktop app.
+- **Remember between sessions.** It keeps its own knowledge base, a small wiki of notes that grows with every session, and keeps the original documents you give it or that it downloads untouched.
+- **Delegate to subagents safely.** Only to the ones it declares, always waiting for their result, and without the main agent being able to slip past its own limits through them.
+- **Stay within limits.** It only reads and writes in the folders that belong to it, and never in protected files, such as one holding passwords.
+- **Use external tools.** MCP servers of its own or of the project, and skills and commands organized in plugins.
+- **Leave a trail.** It records every action and the whole conversation, with secrets hidden.
+- **Chat in a terminal the way Claude Code does.** Full screen, with the reply written live and its markdown already formatted, the tools it uses summed up in one line (Ctrl+O unfolds it), panels for approvals, history and search, a suggestion for the next message, pasted blocks, file mentions with `@`, mouse selection (right-click to copy), and the agent's status in the tab and in the Windows taskbar.
+- **Also work without a terminal.** The same foundation runs inside a desktop app or a server, which bring their own interface.
+
+## Examples
+
+### Captain Whiskers
+
+[Captain Whiskers](./examples/captain-whiskers) is a toy agent to see the kit in action: a retired pirate cat who tells jokes in the terminal, in Spanish. It starts full screen with its logo and has a small crew of subagents: one looks for new jokes on the web, another rates them before they're told, and a third, optional one tells the time. It lets you try the different levels of oversight and is the best starting point for an agent of your own. Its README explains how to run it.
+
+![Captain Whiskers in Windows Terminal: its logo at the top, the conversation in the middle and the framed prompt at the bottom, with a suggestion for the next message](docs/assets/captain-whiskers.png)
+
+### teacher-agent
+
+[teacher-agent](https://github.com/falkenslab/teacher-agent) is a real assistant for Moodle teachers. It signs in with your account in a Chrome window and works as you would: it grades submissions, answers in the forum, creates or reviews content and sums up how the class is going. It asks for your permission before publishing anything students will see, and takes notes about the course to remember everything in the next session.
+
+Oversight, memory, safety and the chat come from the kit; teacher-agent brings what it knows about Moodle and driving the browser.
+
+## Installation
+
+```
+npm install @falkenslab/agent-kit
+```
+
+To try changes to the kit without publishing them, point to a local clone with `"file:../agent-kit"` in your `package.json` and build it with `npm run build` after each change.
+
+Requires Node.js 20 or later.
+
+## A minimal agent
+
+An agent only describes what belongs to it (who it is, which MCP servers, skills and subagents it has) and picks a level of oversight; the kit sets up the session and the chat:
+
+```ts
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { buildSessionOptions, ensureClaudeAuth, runChatInk, type AgentSpec, type BaseSessionConfig } from "@falkenslab/agent-kit";
+
+// The only part specific to the agent: who it is and what it has.
+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
+
+// Each session keeps its logs in a folder of its own.
+const runDir = path.resolve(".run", new Date().toISOString().replace(/[:.]/g, "-"));
+await mkdir(runDir, { recursive: true });
+
+const config: BaseSessionConfig = { mode: "guided", projectDir: process.cwd() };
+const { options, modeControl } = await buildSessionOptions(config, runDir, spec);
+
+await runChatInk(options, {
+  header: { title: "My agent" },
+  mode: config.mode,
+  modeControl, // Shift+Tab switches between guided and step by step
+  fullscreen: true,
+  sessionLogPath: path.join(runDir, "session.log"),
+});
+```
+
+Save it as `agent.ts` in a project with the kit and `tsx` installed and `"type": "module"` in its `package.json`, and run it with `npx tsx agent.ts`. Captain Whiskers is this same skeleton with more pieces: skills, subagents and its logo.
+
+## More details
+
+The specification in [`.minispec/`](./.minispec/README.md) explains how each part is built and why, including the SDK behaviors checked by hand that motivate several of its safeguards. Captain Whiskers' code is the quickest way to see how an agent is put together.
+
+## Development
+
+| 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 |
+
+To run a single test file:
+
+```
+npx tsx --test test/tui/promptErrors.test.ts
+```

package/assets/knowledge-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,4 @@
+{
+  "name": "knowledge",
+  "description": "Built-in knowledge base workflows (an LLM wiki): page templates, ingesting sources, querying the knowledge base and health-checking it."
+}

package/assets/knowledge-plugin/commands/ingest.md

@@ -0,0 +1,7 @@
+---
+description: Ingest material into the knowledge base right now - the files or topic given, or everything in sources/ not ingested yet
+---
+
+Apply the `knowledge-ingest` skill right now to: $ARGUMENTS
+
+If nothing is given above, find every file in the sources folder that has no summary page in the knowledge base yet (check `index.md` and `summaries/`) and ingest them all. When you're done, summarize which pages you created and updated, and anything you couldn't read.

package/assets/knowledge-plugin/commands/lint.md

@@ -0,0 +1,5 @@
+---
+description: Health-check the knowledge base right now - broken links, orphans, duplicates, contradictions, gaps
+---
+
+Apply the `knowledge-lint` skill right now over the whole knowledge base. Fix what's mechanical (links, index, missing back-links) and report the rest: what needs the human's decision, and the gaps worth filling next.

package/assets/knowledge-plugin/commands/query.md

@@ -0,0 +1,5 @@
+---
+description: Answer a question from the knowledge base, and file the answer back if it is worth keeping
+---
+
+Apply the `knowledge-query` skill right now to answer: $ARGUMENTS

package/assets/knowledge-plugin/skills/knowledge-ingest/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: knowledge-ingest
+description: Ingest one source into the knowledge base - a file in sources/, a document, a page - creating its summary page, creating or updating the concept and entity pages it touches, linking everything both ways, and updating index.md and log.md.
+---
+
+# Ingesting a source into the knowledge base
+
+A source is ingested once, and from then on the knowledge base holds what it taught: later sessions read the pages, not the original again. Ingesting is not summarizing a file in isolation - its value is in how it connects to what the knowledge base already knows. Load the `knowledge-pages` skill first for the page templates.
+
+## 1. Check it isn't already ingested
+
+Look for it in `index.md` (Summaries) or `Grep` its file name or URL inside the knowledge base. If it already has a page:
+- unchanged source: nothing to do;
+- the source changed or the page is thin: update that page instead of creating another.
+
+## 2. Read it for real
+
+Read the whole source, not its first page. If it exists only outside the sources folder (a downloaded document, a remote file), save it with `save_to_sources` first, so the original is kept as obtained.
+
+## 3. Write the summary page
+
+Create `summaries/<slug>.md` with the template: summary, key points (literal wording where exactness matters), frontmatter `file`/`url` pointing to the original.
+
+## 4. Update concepts and entities
+
+For every concept or entity the source explains or relies on:
+- no page yet: create it;
+- page exists: add what is new (a better definition, an example, a nuance, a fact) with `Edit`, and link the summary under "Sources".
+
+Check first whether it exists under another name (`Grep` the knowledge base for the term and look at `aliases`): a duplicate page is worse than none.
+
+## 5. Link both ways and look for conflicts
+
+Every link you added from page A to page B needs its counterpart in B. If the source contradicts an existing page, record both versions with attribution in both pages - don't overwrite.
+
+## 6. Close
+
+- `index.md`: new pages, and one-line descriptions that changed.
+- `log.md`: `## [date] ingest | <source title>` with the pages created and updated.
+- `overview.md`: only if the source changes the big picture.
+
+When ingesting several sources in a row, do steps 1-5 for each and close once at the end.

package/assets/knowledge-plugin/skills/knowledge-lint/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: knowledge-lint
+description: Health-check the knowledge base - broken links, pages missing from index.md, orphan pages, one-way links, duplicated concepts, mentioned-but-missing concepts, contradictions, gaps - fix what's mechanical and report the rest.
+---
+
+# Linting the knowledge base
+
+A knowledge base maintained across sessions drifts: links break, pages go unlisted, the same concept appears under two names. Lint it when asked and after a large ingest. Load `knowledge-pages` first for the templates.
+
+## Checks
+
+Use `Glob` to list pages and `Grep` (always with `path` inside the knowledge base) to find links, instead of reading every page in full.
+
+1. **Broken links**: a relative link whose target file doesn't exist. Fix it if the right target is obvious (a typo, a page under a close name); otherwise report it.
+2. **Index**: every page is listed in `index.md` and every entry there points to an existing page. Fix it.
+3. **Orphans**: pages nothing links to (`Grep` for the file name). Link them from where they belong, or report why they don't belong anywhere.
+4. **One-way links**: a summary that feeds a concept which doesn't list it back... Add the missing side.
+5. **Duplicates**: two pages for the same idea under different names. Merge the content into one, mark the other as superseded (never delete it) and repoint links.
+6. **Missing pages**: terms that several pages treat as concepts or entities but have no page. Create them if the material is there; otherwise list them.
+7. **Contradictions**: claims that disagree across pages without being recorded as such. Record both sides, attributed.
+8. **Provenance**: claims with no traceable source. Add the link, or mark them as unsourced.
+9. **Gaps**: files in the sources folder with no summary page yet, concepts mentioned but never explained by any source. Report them - they are what to ingest or find next.
+
+## Close
+
+Append `## [date] lint | <summary>` to `log.md` listing what was fixed. Then report to the human: what you fixed, and what needs their decision or more material. Don't make judgement calls silently - merging pages that are only similar, or choosing between contradictory sources, goes in the report.

package/assets/knowledge-plugin/skills/knowledge-pages/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: knowledge-pages
+description: Exact templates and conventions for every page of the knowledge base (index, log, overview, summary, concept, entity and synthesis pages) - load it before creating a knowledge base page or restructuring one, so every page keeps the same shape and links.
+---
+
+# Knowledge base page templates
+
+The knowledge base's layout and rules are in the system prompt ("Knowledge base"). This skill only adds the exact shape of each page. Headings and frontmatter keys stay in English (they are structure); the text under them is in the human's language. Dates are `YYYY-MM-DD`. Links are relative markdown links (from `concepts/x.md`, a summary is `../summaries/y.md`; an original file is `../../sources/...`, adjusted to where the folders really are).
+
+Every page starts with YAML frontmatter; `updated` changes whenever you edit the page.
+
+## index.md
+
+The catalog and entry point. One line per page, grouped by section: Summaries, Concepts, Entities, Syntheses (plus any section the domain adds).
+
+```markdown
+# Index
+
+## Summaries
+- [Q3 architecture review](summaries/q3-architecture-review.md) - decisions taken on the billing service
+## Concepts
+- [Idempotency](concepts/idempotency.md) - safe retries of a request
+```
+
+## log.md
+
+Append-only; never edit past entries. Newest at the bottom.
+
+```markdown
+## [2026-10-03] ingest | Q3 architecture review
+- created: summaries/q3-architecture-review.md, concepts/idempotency.md
+- updated: entities/billing-service.md, index.md
+```
+
+## overview.md
+
+A living synthesis of the whole knowledge base, rewritten (not appended) as understanding grows: what it covers, its main blocks and how they connect (with links), what is still unknown.
+
+## Summary page (`summaries/<slug>.md`)
+
+One per ingested source.
+
+```markdown
+---
+type: summary
+title: "<Title>"
+file: <relative link to the original in sources/, if any>
+url: <original URL, if any>
+ingested: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# <Title>
+
+## Summary
+<Two to four paragraphs: what it actually says.>
+
+## Key points
+- Claims, definitions or figures likely to be needed later, quoted literally when exact wording matters.
+
+## Pages it feeds
+- [Concept or entity](../concepts/<slug>.md)
+
+## New or surprising
+- What this source adds to what the knowledge base already had.
+
+## Contradictions
+- Conflicts with other pages, linked.
+```
+
+## Concept page (`concepts/<slug>.md`)
+
+One idea per page.
+
+```markdown
+---
+type: concept
+aliases: []
+updated: YYYY-MM-DD
+---
+
+# <Concept>
+
+<Definition in one or two sentences.>
+
+## Explanation
+<How it works, at the depth the sources give.>
+
+## Connections
+- Requires: [Concept](<slug>.md)
+- Related: [Concept](<slug>.md) - how
+
+## Sources
+- [Summary](../summaries/<slug>.md) - what it says about this
+
+## Contradictions and open questions
+- "<Source A> says X; <source B> says Y" - both attributed.
+```
+
+## Entity page (`entities/<slug>.md`)
+
+A concrete thing: a system, a component, an organization, a document, a person only when they are a public role rather than private individual details.
+
+```markdown
+---
+type: entity
+kind: <system | component | organization | document | other>
+aliases: []
+updated: YYYY-MM-DD
+---
+
+# <Name>
+
+<What it is, one or two sentences.>
+
+## Facts
+- Attributed facts, each linking the summary or source it comes from.
+
+## Connections
+- [Concept or entity](../concepts/<slug>.md) - how
+```
+
+## Synthesis page (`syntheses/<slug>.md`)
+
+An answer worth keeping: a comparison, an analysis, a report.
+
+```markdown
+---
+type: synthesis
+question: "<The question it answers>"
+updated: YYYY-MM-DD
+---
+
+# <Title>
+
+<The answer, with links to every page it draws on.>
+```

package/assets/knowledge-plugin/skills/knowledge-query/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: knowledge-query
+description: Answer a question from the knowledge base - find the relevant pages through the index, read them, answer with links to them, and file the answer back as a synthesis page when it is worth keeping.
+---
+
+# Querying the knowledge base
+
+The knowledge base exists so a question doesn't start from zero. Answer from it first; go back to the originals or the web only for what it doesn't hold.
+
+1. **Start from the index.** Read `index.md`, pick the pages that can matter, read those (not the whole knowledge base). `Grep` inside the knowledge base for terms and aliases the index doesn't reveal.
+2. **Answer from the pages**, linking each one you drew on. Say what comes from the knowledge base, what comes from an original in the sources folder (read it if the knowledge base is thin or contradictory) and what comes from outside (label it as such).
+3. **Say what is missing.** If the knowledge base can't answer part of the question, say so and name the source that would fill it, instead of filling the gap from memory silently.
+4. **File it back.** If the answer is a comparison, an analysis or a report that will be asked again, save it as `syntheses/<slug>.md` (template in `knowledge-pages`) with links to its inputs, add it to `index.md`, and log it: `## [date] query | <question>`. A quick factual answer needs no page.
+5. **Feed the knowledge base.** If answering revealed a concept or fact that has no page, or a contradiction, fix that in the knowledge base too and log it.

package/dist/core/agentSpec.d.ts

@@ -0,0 +1,132 @@
+import type { AgentDefinition as SdkSubagentDefinition, McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * The human-supervision spectrum every agent built on this kit shares, independent of
+ * domain: "interactive" pauses before every single action, "guided" only pauses before a
+ * hard-to-undo/visible-to-others action, "autonomous" has no human-in-the-loop channel at
+ * all. See session.ts's buildSessionOptions() for exactly what each mode changes.
+ *
+ * Deliberately orthogonal to whether the session is a one-shot run or a multi-turn chat
+ * (that's a matter of which entry point the caller uses — a single `query()` call vs.
+ * `runChatTui()`/`createInputQueue()` — not a supervision level): a concrete agent that
+ * wants to know "is this session chat-shaped" for its own purposes (e.g. picking a
+ * different system-prompt template) should track that as its own domain field on its
+ * config type, not conflate it with `Mode`.
+ */
+export type Mode = "interactive" | "guided" | "autonomous";
+/**
+ * The minimum a config object needs to drive `buildSessionOptions()` — a concrete agent's
+ * own config type (e.g. a `Config`) extends this with whatever domain fields
+ * it needs (a course URL, credentials, ...), which `buildSessionOptions()` itself never
+ * looks at directly: only `AgentSpec`'s methods receive the full concrete config.
+ */
+export interface BaseSessionConfig {
+    mode: Mode;
+    /** Project root (the session's cwd): the folder under which the agent's notes, sources and runs live. */
+    projectDir: string;
+    /**
+     * Where the agent writes its own notes (the "wiki"). Setting this or `sourcesDir` is what
+     * gives the session the file tools (Read/Write/Edit/Glob/Grep, scoped — see
+     * hooks/fileScopeGate.ts); without either, the agent has no file access at all.
+     */
+    knowledgeDir?: string;
+    /**
+     * Original files, kept as obtained and apart from the notes in `knowledgeDir`: material
+     * the user drops in, plus whatever the agent saves with `save_to_sources` (downloaded
+     * documents, transcripts...). The agent can read and search it but never edit it — Write/
+     * Edit are scoped to `knowledgeDir` — and `save_to_sources` never overwrites.
+     */
+    sourcesDir?: string;
+    /** Directories besides `knowledgeDir`/`sourcesDir` where Write/Edit are allowed (see hooks/fileScopeGate.ts). */
+    extraWritableDirs?: string[];
+    /** Files or directories the agent must never read, search or write, e.g. a config file holding a password (see hooks/fileScopeGate.ts). */
+    deniedPaths?: string[];
+    /** Extra values (e.g. a password) to scrub out of the transcript log — see hooks/transcriptLogger.ts. */
+    secrets?: string[];
+}
+/**
+ * Everything actually *about the domain* that `buildSessionOptions()` needs but doesn't
+ * decide itself: which system prompt to build, which MCP servers to talk to besides the
+ * generic human-in-the-loop/knowledge ones this kit already wires up, which local plugin
+ * roots (skills/commands) to load, and which opt-in subagents (if any) to register.
+ *
+ * Deliberately not named `AgentDefinition`: the SDK already uses that name for a single
+ * subagent's own definition (`Options.agents: Record<string, AgentDefinition>`), and this
+ * is a level above that — it's what decides *which* subagents get registered, among other
+ * things.
+ */
+export interface AgentSpec<TConfig extends BaseSessionConfig> {
+    /** The system prompt for this run — everything role/mode/domain-specific lives behind this call. */
+    buildSystemPrompt(config: TConfig): string;
+    /**
+     * MCP servers this agent always registers (e.g. Playwright for a browser-driving
+     * agent), on top of the generic ones `buildSessionOptions()` wires up itself when
+     * applicable (human approval, manual intervention, save-to-knowledge) — those aren't
+     * part of the spec because they're driven by `mode` plus this spec's own
+     * `manualInterventionTexts`/`knowledgeDir`/`sourcesDir`, not by anything else
+     * domain-specific.
+     */
+    buildMcpServers(config: TConfig, runDir: string): Record<string, McpServerConfig>;
+    /**
+     * Local plugin roots (skills/commands, SDK "local" plugin type) to load, in the order
+     * given, when the session has file tools (`config.knowledgeDir`/`config.sourcesDir`). Absolute paths; `buildSessionOptions()`
+     * doesn't know or care where they live on disk.
+     */
+    pluginRoots(config: TConfig): string[];
+    /**
+     * Opt-in subagents (the SDK's `Options.agents`) this spec wants registered for this
+     * config, plus which `subagent_type` values are therefore allowed to be spawned via the
+     * `Agent` tool (see hooks/subagentTypeGate.ts — the SDK's own built-in
+     * "general-purpose" type is always spawnable regardless of this list, which is exactly
+     * why that gate exists). Returns `undefined` when this config needs no subagents at
+     * all, so `buildSessionOptions()` knows not to grant `Agent`/`Bash` in the first place.
+     */
+    buildSubagents(config: TConfig): {
+        agents: Record<string, SdkSubagentDefinition>;
+        allowedSubagentTypes: string[];
+    } | undefined;
+    /**
+     * Tool names to explicitly block regardless of what `canUseTool`/`allowAnyMcpTool`
+     * would otherwise allow (e.g. a browser-automation agent blocking
+     * "mcp__playwright__browser_run_code_unsafe", which Microsoft's own description calls
+     * RCE-equivalent). Confirmed empirically that `disallowedTools` takes full precedence
+     * over a permissive `canUseTool` — a disallowed tool never even reaches that callback.
+     */
+    disallowedTools?: string[];
+    /** Overrides this kit's generic `save_to_sources` tool description (registered whenever `config.sourcesDir` is set) with domain-specific wording. */
+    saveToSourcesDescription?: string;
+    /**
+     * The built-in knowledge base (see knowledge.ts): when `config.knowledgeDir` is set, the kit
+     * appends its "Knowledge base" rules to the system prompt and loads its plugin (skills
+     * knowledge-pages/knowledge-ingest/knowledge-query/knowledge-lint, commands /knowledge:ingest, /knowledge:query,
+     * /knowledge:lint), so the agent maintains its notes as an interlinked wiki. On by default;
+     * set `false` for an agent that writes its own rules for `knowledgeDir` (or wants plain
+     * notes) — `knowledgePromptSection()`/`knowledgePluginRoot()` are exported to reuse the pieces.
+     */
+    knowledgeBase?: boolean;
+    /**
+     * Text for the generic human-approval checkpoint (see tools/humanApproval.ts) — what
+     * counts as "publishing something visible to others" is entirely domain-specific.
+     * Omit to use this kit's own generic, domain-neutral defaults.
+     */
+    humanApprovalTexts?: {
+        description: string;
+        approved: string;
+        rejected: string;
+    };
+    /**
+     * Text for the generic manual-intervention checkpoint (see tools/manualLogin.ts), AND
+     * this domain's opt-in signal for offering that checkpoint at all: `buildSessionOptions()`
+     * only registers `request_manual_login` when this is set (and `mode !== "autonomous"`).
+     * Manual intervention only makes sense for a domain that drives some live UI a human could
+     * actually step into by hand (a browser window, say) — there's no generic default to fall
+     * back to the way there is for `humanApprovalTexts` above, because this kit can't assume
+     * every agent built on it has such a UI at all. Leave unset for a domain that doesn't.
+     */
+    manualInterventionTexts?: {
+        toolDescription: string;
+        confirmedMessage: string;
+        checkpointTitle: string;
+        checkpointLines: string[];
+        checkpointQuestion?: string;
+    };
+}

package/dist/core/agentSpec.js

@@ -0,0 +1 @@
+export {};

package/dist/core/claudeAuth.d.ts

@@ -0,0 +1,24 @@
+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;
+}
+/**
+ * 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`.
+ */
+export declare function resolveClaudeAuth(config?: ClaudeAuthConfig): boolean;

package/dist/core/claudeAuth.js

@@ -0,0 +1,27 @@
+/**
+ * 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`.
+ */
+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;
+        return true;
+    }
+    return false;
+}

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

@@ -0,0 +1,33 @@
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * Where the built-in file tools may act. Without this, the only boundary is the SDK's own
+ * working-directory scope — the whole project directory — so keeping the agent out of the
+ * user's own files (a config file holding a password, the originals in sources/) would rest on the system
+ * prompt alone.
+ */
+export interface FileScope {
+    /** Base for relative paths: the session's cwd. */
+    projectDir: string;
+    /** Write/Edit are only allowed inside these. */
+    writableDirs: string[];
+    /** Readable and searchable but never writable; only affects the wording of the denial. */
+    readOnlyDirs?: string[];
+    /** Grep is only allowed inside these — it prints file contents, so it isn't let loose on the whole project. */
+    searchableDirs: string[];
+    /** Never readable, searchable or writable. */
+    deniedPaths: string[];
+}
+/** Whether `candidate` is `base` itself or somewhere inside it (case-insensitive on Windows, like path.relative). */
+export declare function isWithin(base: string, candidate: string): boolean;
+/**
+ * The reason to deny `toolName` with `input` under `scope`, or `undefined` to let it
+ * through. Tools other than Read/Write/Edit/Grep are never judged here, and a call
+ * without a path is left for the tool itself to reject.
+ */
+export declare function checkFileScope(scope: FileScope, toolName: string, input: Record<string, unknown>): string | undefined;
+/**
+ * PreToolUse hook enforcing `scope` on Read/Write/Edit/Grep, for the main agent and its
+ * subagents alike. Bash, when a subagent has it, is not covered: it can reach any path,
+ * which is why Bash-granting features stay opt-in.
+ */
+export declare function createFileScopeGate(scope: FileScope): HookCallback;