indusagi-coding-agent 0.1.62 → 0.2.1

package/dist/types/boot/runners/session.d.ts

@@ -8,8 +8,12 @@
  * {@link ModelMatcher}; the conductor itself is built lazily so no framework agent
  * is constructed until the first turn runs.
  */
-import { type SessionConductor } from "../../conductor";
-import type { BootContext } from "../contract";
+import { type AgentTool, type SessionConductor } from "../../conductor";
+import { type MemoryStore } from "../../capability-deck";
+import { type DelegateRunner } from "../../capability-deck/cards/task-card";
+import { type CheckpointStore } from "./checkpoint";
+import { type ContextDoc, type SkillCard } from "../../briefing";
+import type { BootContext, Invocation } from "../contract";
 /**
  * Resolve the model id for this run.
  *
@@ -21,6 +25,37 @@ import type { BootContext } from "../contract";
  * @returns the canonical model id to bind the session to
  */
 export declare function resolveModelId(ctx: BootContext): string;
+/**
+ * Gather the on-disk skill cards the model may invoke this run: walk the project
+ * and user `.indusagi/skills` roots and drop any card flagged
+ * `disable-model-invocation` (those stay loadable explicitly, but the model is
+ * not told about them). A filesystem walk error degrades to an empty list so a
+ * bad/unreadable skills dir never sinks the session.
+ */
+export declare function gatherModelSkills(cwd: string): SkillCard[];
+/**
+ * Select the tool deck for the run, honouring `--no-tools` (empty) and `--tools`
+ * (allow-list). Tool ids are matched case-insensitively with `_`/`-` stripped, so
+ * a `--tools web_fetch,todo_read` request lines up with the deck's `webfetch` /
+ * `todoread` ids.
+ */
+/**
+ * @param runner an optional live sub-agent {@link DelegateRunner}; when present it
+ *   is injected under {@link DELEGATE_HANDLE_KEY} so the `task` card delegates for
+ *   real instead of returning its `STUB_NOTE`. Omitted by callers that only need
+ *   a deck (the card then degrades gracefully).
+ * @param checkpoint an optional per-session {@link CheckpointStore}; when present
+ *   it is injected under {@link CHECKPOINT_HANDLE_KEY} so the framework's
+ *   write/edit tools snapshot a file's pre-mutation content (rewind, #24). Omitted
+ *   callers get no checkpointing (the tools no-op the snapshot).
+ */
+export declare function selectTools(cwd: string, inv: Invocation, runner?: DelegateRunner, memoryStore?: MemoryStore, checkpoint?: CheckpointStore): AgentTool[];
+/**
+ * Compose the run's system prompt: `--system` replaces the built-in briefing,
+ * `--append-system` adds a trailing block, and both compose (override then
+ * append). With neither, it is the tool-aware built-in briefing.
+ */
+export declare function composeSystem(tools: AgentTool[], inv: Invocation, cwd: string, skills?: readonly SkillCard[], memoryDoc?: ContextDoc): string;
 /**
  * The cwd-scoped session directory under the workspace `sessions/` root.
  *

package/dist/types/boot/runners/session.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Skills-surface wiring (#7 / fixes #11).
+ *
+ * Proves the chain that makes on-disk `SKILL.md` cards visible to the model:
+ * `gatherModelSkills` walks `cwd/.indusagi/skills`, drops any card flagged
+ * `disable-model-invocation`, and the survivors render into the briefing's
+ * `<available_skills>` block via `composeSystem`. A `--system` override must NOT
+ * carry the skills block (it replaces the whole prompt).
+ */
+export {};

package/dist/types/briefing/context-docs.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Project-context document loader — gathers repository convention files
+ * (CLAUDE.md / AGENTS.md and brand variants) into {@link ContextDoc}s that the
+ * briefing's `PROJECT_CONTEXT_SECTION` inlines under `# Project context`.
+ *
+ * The walk runs the ancestor chain from the filesystem root down to the cwd, so
+ * the cwd's own files land LAST in the returned array — and since the renderer
+ * treats array order as priority order, the closest (most specific) file wins.
+ * The home directory is scanned after the chain as a global fallback. Each file
+ * may pull additional files inline via `@import` references (bounded to a depth
+ * of {@link DEFAULT_MAX_IMPORT_DEPTH} with a per-walk realpath guard so cycles
+ * and symlink loops cannot recurse or hang).
+ *
+ * The whole body is wrapped so that a permissions error on one ancestor, a
+ * binary file, or a malformed tree degrades to `[]` rather than crashing boot —
+ * repo conventions are a best-effort enrichment, never a hard dependency.
+ */
+import type { ContextDoc } from "./contract";
+/** Options for {@link gatherContextDocs}. Every field is optional. */
+export interface GatherContextDocsOptions {
+    /** Maximum `@import` recursion depth. Defaults to {@link DEFAULT_MAX_IMPORT_DEPTH}. */
+    readonly maxImportDepth?: number;
+    /** Maximum bytes retained per document body (post-trim). Defaults to {@link DEFAULT_MAX_BYTES_PER_DOC}. */
+    readonly maxBytesPerDoc?: number;
+}
+/**
+ * Gather the repository's project-context documents into an ordered
+ * {@link ContextDoc} array for the briefing.
+ *
+ * Order: the ancestor chain from root → cwd (so cwd's files land last = highest
+ * priority), then the home directory as a global fallback. Within each directory
+ * the {@link CANDIDATE_FILES} are read in their listed order. Each file may pull
+ * `@import` children inline (depth-bounded, cycle-guarded). De-duplication is by
+ * realpath, so a file reachable through two roots is inlined once.
+ *
+ * Never throws: any failure in the walk yields the docs gathered so far (or `[]`).
+ */
+export declare function gatherContextDocs(cwd: string, home: string, opts?: GatherContextDocsOptions): readonly ContextDoc[];

package/dist/types/briefing/context-docs.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Project-context loader — colocated unit tests.
+ *
+ * Every test runs against a fresh tmpdir tree (the `src/boot/boot.test.ts`
+ * sandbox pattern): no real home directory, no network. The realpath of the
+ * tmpdir base is taken up front because macOS resolves `/var/folders` → a
+ * `/private/...` symlink, which the loader's realpath de-dup would otherwise
+ * surface in path assertions.
+ *
+ * Pinned behaviors:
+ *   - a cwd CLAUDE.md body is inlined;
+ *   - an ancestor AGENTS.md orders BEFORE the cwd doc (cwd = highest priority);
+ *   - an `@import` pulls a sibling file inline;
+ *   - a cyclic import terminates (does not hang) and inlines each file once;
+ *   - missing files and binary (non-text-extension) imports are skipped;
+ *   - a home-root CLAUDE.md is included exactly once even when cwd is under home.
+ */
+export {};

package/dist/types/briefing/index.d.ts

@@ -25,3 +25,5 @@ export { scanMacroBody, resolveTokens, applyMacros, buildMacroScope, expandInvoc
 export type { LoadMacrosOptions, FrontmatterSplit } from "./macros";
 export { loadSkillCards, gatherSkillCards, modelInvocableCards, } from "./skills";
 export type { SkillRoot } from "./skills";
+export { gatherContextDocs } from "./context-docs";
+export type { GatherContextDocsOptions } from "./context-docs";

package/dist/types/capability-deck/cards/index.d.ts

@@ -23,8 +23,14 @@ export { daemonCard, buildDaemonCapability, DaemonTable, type DaemonState, type
 export { taskCard, buildTaskCapability, DELEGATE_HANDLE_KEY, type DelegateRunner, type DelegateRequest, type DelegateResult, type TaskParamsType, type TaskDetails, } from "./task-card";
 export { saasCard, buildSaasCapability, SAAS_GATEWAY_KEY, type SaasGatewayPort, type RemoteToolSummary, type RemoteExecution, type SaasParamsType, type SaasDetails, } from "./saas-card";
 export { memoryCard, buildMemoryCapability, InMemoryStore, MEMORY_HANDLE_KEY, type MemoryStore, type MemoryParamsType, type MemoryDetails, } from "./memory-card";
+export { enterPlanModeCard, exitPlanModeCard, buildEnterPlanModeCapability, buildExitPlanModeCapability, PLAN_HANDLE_KEY, type PlanController, type EnterPlanParamsType, type EnterPlanDetails, type ExitPlanParamsType, type ExitPlanDetails, } from "./plan-tools";
+export { planSlug, planFilePath, writePlan, readPlan, PLANS_DIRNAME } from "./plan-file";
 /**
  * The app-novel cards, in catalog order. The manifest module concatenates these
  * with the builtin-bridge cards to build the full `CAPABILITY_CARDS` array.
+ *
+ * The plan-mode tools live here (the broadest `all` profile only): plan mode is a
+ * gate over mutating work, so the tools are only meaningful in a full-access deck —
+ * never the read-only `authoring` subset.
  */
 export declare const APP_NOVEL_CARDS: readonly CapabilityCard[];

package/dist/types/capability-deck/cards/memory-card.d.ts

@@ -5,16 +5,15 @@
  * Status: minimal in-memory implementation + clearly-typed seam for the
  * framework memory subsystem.
  *
- * The framework's `indusagi/memory` facade is not yet populated with a public
- * working-memory store, so this card ships a self-contained, framework-agnostic
- * implementation: a single mutable text buffer the agent overwrites or appends
- * to, scoped to one built capability (one session). When the framework exposes a
- * persistent memory store, swap the {@link MemoryStore} default for an adapter
- * over it via {@link DeckContext.framework} — the {@link Capability} surface and
- * the tool's wire contract do not change.
- *
- * TODO(framework-memory): adapt `indusagi/memory` once it exports a public
- * working-memory store; read it from `ctx.framework[MEMORY_HANDLE_KEY]`.
+ * This card ships a self-contained, framework-agnostic default: a single mutable
+ * text buffer the agent overwrites or appends to, scoped to one built capability
+ * (one session). A host that wants persistence injects a durable store under
+ * {@link MEMORY_HANDLE_KEY} via {@link DeckContext.framework} — the boot layer's
+ * `DiskMemoryStore` (`boot/runners/memdir.ts`) does exactly this, persisting the
+ * note to a per-cwd `MEMORY.md` so it survives across sessions. The
+ * {@link Capability} surface and the tool's wire contract do not change either
+ * way; {@link readStore} validates the injected store's three methods and falls
+ * back to {@link InMemoryStore} when none is wired.
  *
  * The single tool keys behavior on an `action` discriminant:
  *   - `read`    — return the current working-memory note.

package/dist/types/capability-deck/cards/plan-file.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Plan-file persistence — write and read the approved plan a plan-mode session
+ * produces, as a slug-named markdown file under a per-session plans directory.
+ *
+ * Plan mode is a read-only "research first, act second" stance: the agent
+ * explores under {@link EnterPlanMode}, drafts a plan, and proposes leaving plan
+ * mode with {@link ExitPlanMode}. When the user approves the exit, the plan text
+ * the model authored is durable — saved here so it survives the session and can
+ * be reviewed, diffed, or fed back later. The conductor owns the approval
+ * handshake; this module owns only the bytes-on-disk concern.
+ *
+ * The filename is derived from a stable slug of the plan's first line (its de
+ * facto title), prefixed with a short timestamp so successive plans in one
+ * session never collide. Writing is best-effort from the caller's perspective —
+ * a write failure surfaces as a thrown error the conductor swallows into a
+ * non-fatal note rather than faulting the turn.
+ */
+/** The directory plans are written under (relative to the session scope dir). */
+export declare const PLANS_DIRNAME: "plans";
+/**
+ * Derive a filesystem-safe slug from a plan's text — its first non-empty line,
+ * lower-cased, with every run of non-alphanumeric characters collapsed to a
+ * single dash and the result trimmed and length-capped. Falls back to `"plan"`
+ * when the text yields nothing usable (empty, or punctuation-only).
+ *
+ * @param plan the plan body whose first line seeds the slug
+ */
+export declare function planSlug(plan: string): string;
+/**
+ * Resolve the absolute path a plan with `slug` is written to under `sessionDir`.
+ * The `plans/` sub-directory is implied; callers pass the session scope dir and
+ * get back `<sessionDir>/plans/<slug>.md`.
+ *
+ * @param sessionDir the per-session directory plans live beneath
+ * @param slug       the derived slug (see {@link planSlug})
+ */
+export declare function planFilePath(sessionDir: string, slug: string): string;
+/**
+ * Write the plan body to a slug-named markdown file under `sessionDir/plans`,
+ * creating the directory as needed, and return the absolute path written. The
+ * filename is `<short-timestamp>-<slug>.md` so repeated plans in one session do
+ * not overwrite each other.
+ *
+ * Throws on an I/O failure (the conductor swallows it into a non-fatal note).
+ *
+ * @param sessionDir the per-session directory plans live beneath
+ * @param plan       the plan body to persist
+ */
+export declare function writePlan(sessionDir: string, plan: string): string;
+/**
+ * Read a previously-written plan file back, or `undefined` when it is missing or
+ * unreadable. Used by tests and by any review surface that wants the saved plan.
+ *
+ * @param path the absolute plan-file path (see {@link planFilePath} / {@link writePlan})
+ */
+export declare function readPlan(path: string): string | undefined;

package/dist/types/capability-deck/cards/plan-tools.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Plan-mode capabilities — the two tools that bracket a read-only planning phase.
+ *
+ *   - {@link enterPlanModeTool} (`enter_plan_mode`) is a **read-only** tool: when
+ *     invoked it returns a structured detail `{ enterPlanMode: true }` plus
+ *     explore-only prose. It carries no side effect of its own — the **conductor**
+ *     watches the tool-result seam for `enterPlanMode` and switches the session
+ *     into the `plan` permission mode (research-only — every mutating tool is
+ *     blocked at the permission gate), capturing the pre-plan mode so it can be
+ *     restored on exit. It is marked `readOnly: true` so it is itself always
+ *     permitted, even inside plan mode.
+ *
+ *   - {@link exitPlanModeTool} (`exit_plan_mode`) likewise does NOT flip the mode
+ *     itself — a tool cannot drive the interactive approval dialog. It returns a
+ *     structured detail `{ exitPlan: true, plan }` that the conductor intercepts:
+ *     the conductor raises the user-approval prompt, and on approval restores the
+ *     pre-plan mode + injects the approved plan as context for the next turn,
+ *     persisting it to a plan file. On reject the session stays in plan mode.
+ *
+ * Keeping every side effect (mode flip, approval, persistence) in the conductor
+ * rather than the tool keeps the tools pure, side-effect-light, and assemblable in
+ * any environment, including tests — and lets the conductor own the single
+ * permission-mode source of truth.
+ */
+import { type Static } from "@sinclair/typebox";
+import type { Capability, CapabilityCard, DeckContext } from "../contract";
+/**
+ * Reserved key under which a host MAY wire a plan-mode controller into the deck
+ * context. The conductor-driven design intercepts the plan tools' result details
+ * directly (no handle required), so this is exported only for forward-compat /
+ * an alternate host that wants the tool to drive the flip itself.
+ */
+export declare const PLAN_HANDLE_KEY: "planController";
+/**
+ * The narrow port a host may wire to flip the live session into plan mode. Unused
+ * by the default (conductor-intercept) wiring; kept for hosts that prefer the tool
+ * to signal directly rather than via the tool-result seam.
+ */
+export interface PlanController {
+    /** Switch the session into read-only plan mode for subsequent tool calls. */
+    enterPlanMode(): void;
+}
+declare const EnterPlanParams: import("@sinclair/typebox").TObject<{}>;
+/** Statically-inferred parameter type EnterPlanMode's `execute` receives. */
+export type EnterPlanParamsType = Static<typeof EnterPlanParams>;
+/** Structured detail returned by EnterPlanMode. */
+export interface EnterPlanDetails {
+    /**
+     * The marker the conductor intercepts on the tool-result seam to switch the
+     * session into plan mode (and capture the pre-plan mode for a later restore).
+     */
+    readonly enterPlanMode: true;
+    /** Whether an optional in-context controller also applied the switch directly. */
+    readonly applied: boolean;
+}
+/**
+ * Build the EnterPlanMode capability. On invoke it asks the wired
+ * {@link PlanController} to switch the session into plan mode, then returns
+ * explore-only prose. It is `readOnly: true`, so the permission gate always
+ * permits it (including inside plan mode itself).
+ *
+ * @param ctx the deck context; an optional controller is read from
+ *            `ctx.framework[PLAN_HANDLE_KEY]`.
+ */
+export declare function buildEnterPlanModeCapability(ctx: DeckContext): Capability<typeof EnterPlanParams, EnterPlanDetails>;
+declare const ExitPlanParams: import("@sinclair/typebox").TObject<{
+    plan: import("@sinclair/typebox").TString;
+}>;
+/** Statically-inferred parameter type ExitPlanMode's `execute` receives. */
+export type ExitPlanParamsType = Static<typeof ExitPlanParams>;
+/**
+ * Structured detail returned by ExitPlanMode. The conductor watches the
+ * tool-result seam for `exitPlan === true`, captures the {@link plan}, and runs
+ * the approval handshake (the tool itself does not flip the mode or prompt).
+ */
+export interface ExitPlanDetails {
+    /** The marker the conductor intercepts to start the exit-plan handshake. */
+    readonly exitPlan: true;
+    /** The plan text the model authored, surfaced to the user for approval. */
+    readonly plan: string;
+}
+/**
+ * Build the ExitPlanMode capability. It performs no mode flip and no prompt of
+ * its own — it returns the `{ exitPlan: true, plan }` detail the conductor
+ * intercepts. The model-facing content echoes the proposed plan so a transcript
+ * reader sees what was put up for approval.
+ *
+ * Not marked read-only: it represents the request to RESUME mutating work, so in
+ * plan mode it must still be permitted explicitly (the gate special-cases the
+ * plan tools alongside read-only tools — see the conductor wiring).
+ */
+export declare function buildExitPlanModeCapability(_ctx: DeckContext): Capability<typeof ExitPlanParams, ExitPlanDetails>;
+/** Catalog row for the EnterPlanMode capability. */
+export declare const enterPlanModeCard: CapabilityCard;
+/** Catalog row for the ExitPlanMode capability. */
+export declare const exitPlanModeCard: CapabilityCard;
+export {};

package/dist/types/capability-deck/cards/plan-tools.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Plan-mode cards + plan-file helpers — focused unit tests.
+ *
+ * The cards are pure capability builders: EnterPlanMode is read-only and returns
+ * the `{ enterPlanMode: true }` marker the conductor intercepts; ExitPlanMode
+ * returns the `{ exitPlan: true, plan }` detail the conductor's handshake reads.
+ * The plan-file helpers slug a title and round-trip the bytes on disk.
+ */
+export {};

package/dist/types/capability-deck/checkpoint.int.test.d.ts

@@ -0,0 +1,25 @@
+/**
+ * File checkpoint / code rewind — PRODUCT integration test (rewind, #24).
+ *
+ * This proves the checkpoint records through the ACTUAL wired path the product
+ * uses, NOT a hand-rolled harness:
+ *
+ *   1. We provision a real deck via {@link provisionDeck} with a `framework` bag
+ *      carrying a real per-session {@link CheckpointStore} under the SAME
+ *      `checkpoint` handle key `session.ts` injects (`CHECKPOINT_HANDLE_KEY`).
+ *   2. We pull the WIRED `edit` capability out of that deck — the same `AgentTool`
+ *      object the conductor would run — and edit a file through it.
+ *
+ * The framework's edit tool calls `ctx.framework['checkpoint'].record(absPath,
+ * previous)` immediately before the write lands, with the file's OLD on-disk
+ * content. If the bridge failed to thread the store into `createEditTool`, the
+ * handle would be `undefined` and nothing would be recorded — so the assertions
+ * below only pass when the store reaches the tool through the real wiring.
+ *
+ * We then call `store.restore(nodeId)` and assert the on-disk content reverts to
+ * the pre-edit bytes, closing the loop end-to-end.
+ *
+ * Note: no `readState` handle is wired here, so the read-before-edit gate is OFF
+ * and the edit proceeds without a prior read — isolating the checkpoint behavior.
+ */
+export {};

package/dist/types/capability-deck/index.d.ts

@@ -31,7 +31,7 @@ export { CAPABILITY_CARDS, CAPABILITY_INDEX, CARD_PROFILES, capabilityIds, hasCa
  * (checklist, background-process proxy, delegate/sub-agent, SaaS connector,
  * working memory) plus their builders, stores, and injection-handle types.
  */
-export { APP_NOVEL_CARDS, todoCard, buildTodoCapability, TodoLedger, type TodoItem, type TodoState, type TodoWeight, type TodoParamsType, type TodoDetails, daemonCard, buildDaemonCapability, DaemonTable, type DaemonState, type DaemonParamsType, type DaemonDetails, taskCard, buildTaskCapability, DELEGATE_HANDLE_KEY, type DelegateRunner, type DelegateRequest, type DelegateResult, type TaskParamsType, type TaskDetails, saasCard, buildSaasCapability, SAAS_GATEWAY_KEY, type SaasGatewayPort, type RemoteToolSummary, type RemoteExecution, type SaasParamsType, type SaasDetails, memoryCard, buildMemoryCapability, InMemoryStore, MEMORY_HANDLE_KEY, type MemoryStore, type MemoryParamsType, type MemoryDetails, } from "./cards/index";
+export { APP_NOVEL_CARDS, todoCard, buildTodoCapability, TodoLedger, type TodoItem, type TodoState, type TodoWeight, type TodoParamsType, type TodoDetails, daemonCard, buildDaemonCapability, DaemonTable, type DaemonState, type DaemonParamsType, type DaemonDetails, taskCard, buildTaskCapability, DELEGATE_HANDLE_KEY, type DelegateRunner, type DelegateRequest, type DelegateResult, type TaskParamsType, type TaskDetails, saasCard, buildSaasCapability, SAAS_GATEWAY_KEY, type SaasGatewayPort, type RemoteToolSummary, type RemoteExecution, type SaasParamsType, type SaasDetails, memoryCard, buildMemoryCapability, InMemoryStore, MEMORY_HANDLE_KEY, type MemoryStore, type MemoryParamsType, type MemoryDetails, enterPlanModeCard, exitPlanModeCard, buildEnterPlanModeCapability, buildExitPlanModeCapability, PLAN_HANDLE_KEY, planSlug, planFilePath, writePlan, readPlan, PLANS_DIRNAME, type PlanController, type EnterPlanParamsType, type EnterPlanDetails, type ExitPlanParamsType, type ExitPlanDetails, } from "./cards/index";
 /**
  * Bridge ledger — event-sourced enrollment of dynamically grafted MCP tools:
  * content-hash / ULID key minting, the immutable {@link BridgeLedger} value with

package/dist/types/capability-deck/read-edit-gate.int.test.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Read-before-edit gate — PRODUCT integration test (read-edit-gate, #11).
+ *
+ * This proves the gate fires through the ACTUAL wired path the product uses:
+ *
+ *   1. We provision a real deck via {@link provisionDeck} with a `framework` bag
+ *      that carries a real per-session {@link ReadStateStore} under the same
+ *      `readState` handle key `session.ts` injects (`READ_STATE_HANDLE_KEY`).
+ *   2. We pull the WIRED `read` and `edit` capabilities out of that deck — the
+ *      same `AgentTool` objects the conductor would run — and exercise them.
+ *
+ * The framework's edit tool consults `ctx.framework['readState']` to enforce the
+ * gate. If the bridge failed to thread the store into `createEditTool`, the
+ * handle would be `undefined` and the gate would no-op — so an edit of an unread
+ * file would succeed instead of being refused. These assertions therefore only
+ * pass when the store reaches the tool through the real wiring.
+ *
+ * The refusal message is byte-stable (the framework's `READ_BEFORE_EDIT_MESSAGE`)
+ * and asserted verbatim, so a wording drift on either side is caught.
+ */
+export {};

package/dist/types/conductor/bash-guard.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Bash command parser/classifier + catastrophic-command blocklist.
+ *
+ * The permission engine ({@link "./permissions"}) matches a tool call against
+ * induscode-style `Bash(...)` allow/ask/deny rules. For most tools the call is a
+ * single atomic action, so a rule's argument specifier matches against one
+ * subject string. The shell tool is different: `a && b; c | d` is FOUR commands
+ * in one call, and a coarse "match the whole command string" check is trivially
+ * bypassed — a benign-looking prefix can smuggle a destructive tail past an
+ * allow rule (`npm test && rm -rf /`), or hide a blocked binary behind a wrapper
+ * (`env X=1 rm -rf /`, `sudo rm -rf /`) or quoting.
+ *
+ * This module makes bash matching real. It is split in two concerns:
+ *
+ *   1. **A parser/classifier** — {@link parseBashCommand} splits a shell command
+ *      string into its constituent *simple* commands across the control
+ *      operators (`;`, `&&`, `||`, `|`, newlines) and `( … )` subshells /
+ *      `$( … )` / `` ` … ` `` command substitutions, strips benign leading
+ *      wrappers (`env VAR=x`, `nice`, `nohup`, `timeout N`, `xargs`, `command`,
+ *      `builtin`, and `sudo`/`doas` — the last recorded as an *elevation* flag),
+ *      and returns each base command + its raw argument string. Quoting is
+ *      handled well enough that `"rm -rf /"` cannot hide behind quotes or a
+ *      wrapper. The split is quote-aware so an operator *inside* a quoted string
+ *      (`echo "a && b"`) is NOT treated as a command boundary.
+ *
+ *   2. **A catastrophic blocklist** — {@link isCatastrophicCommand} matches a
+ *      single parsed sub-command against a conservative set of always-deny
+ *      patterns (root-targeting `rm -rf`, fork bombs, `curl … | sh` of remote
+ *      scripts, `dd of=/dev/…`, `mkfs`, `chmod -R 777 /`, redirect-to-raw-disk).
+ *      It is deliberately narrow so normal dev commands (`rm -rf node_modules`,
+ *      `rm -rf ./dist`, `curl … -o file`) are NOT blocked. This is
+ *      defense-in-depth, NOT a hard security boundary — the OS sandbox and the
+ *      permission gate are the real boundary.
+ *
+ * Everything here is pure, synchronous, and side-effect free so the classifier
+ * and the blocklist are exhaustively unit-testable, and the permission engine
+ * can fold them into its decision without any I/O.
+ */
+/**
+ * One simple command extracted from a (possibly compound) shell string.
+ *
+ * `rm -rf /tmp` parses to `{ name: "rm", args: ["-rf", "/tmp"], elevated: false,
+ * raw: "rm -rf /tmp" }`. The `name` is the base binary AFTER benign wrappers are
+ * stripped; `args` are its tokens (quotes removed); `raw` is the original
+ * sub-command slice (wrappers included) so a caller can echo exactly what the
+ * model asked for; `elevated` is true when a `sudo`/`doas` wrapper was stripped.
+ */
+export interface ParsedCommand {
+    /** The base binary, lower-cased for stable comparison (e.g. `"rm"`). */
+    readonly name: string;
+    /** The argument tokens after the binary, with surrounding quotes removed. */
+    readonly args: readonly string[];
+    /** Whether a `sudo`/`doas` elevation wrapper preceded this command. */
+    readonly elevated: boolean;
+    /** The original sub-command slice (wrappers included), trimmed. */
+    readonly raw: string;
+}
+/**
+ * Parse a (possibly compound) shell command string into the flat list of every
+ * simple command it runs — across operators, subshells, and command
+ * substitutions, with benign wrappers stripped.
+ *
+ * The result is order-preserving and exhaustive enough that the permission
+ * engine can evaluate a `Bash(...)` rule (and the catastrophic blocklist)
+ * against EACH sub-command independently: a deny on any sub-command denies the
+ * whole call, and an allow must cover every sub-command to auto-allow.
+ *
+ * @returns one {@link ParsedCommand} per simple command; an empty array for an
+ * empty/whitespace command string.
+ */
+export declare function parseBashCommand(command: string): ParsedCommand[];
+/**
+ * Classify a SINGLE parsed sub-command against the catastrophic blocklist.
+ *
+ * @returns the byte-stable deny reason when the command is catastrophic, else
+ * `undefined`. Use {@link evaluateCatastrophic} for a whole compound call (it
+ * also runs the cross-sub-command `curl | sh` correlation).
+ */
+export declare function catastrophicReason(cmd: ParsedCommand): string | undefined;
+/** Convenience boolean form of {@link catastrophicReason}. */
+export declare function isCatastrophicCommand(cmd: ParsedCommand): boolean;
+/**
+ * Evaluate the catastrophic blocklist over a WHOLE bash command string.
+ *
+ * Parses the (possibly compound) command, runs the per-sub-command blocklist on
+ * each leaf, AND runs the cross-sub-command `curl | sh` correlation. Returns a
+ * byte-stable deny message when ANY check fires, else `undefined`.
+ *
+ * This is what the permission engine calls for the bash tool: a catastrophic
+ * command is denied REGARDLESS of allow/ask/deny rules or mode (it is not even
+ * `bypass`-able, mirroring the original always-block guard).
+ */
+export declare function evaluateCatastrophic(command: string): string | undefined;
+/**
+ * Render the rule-matching SUBJECT for each sub-command of a bash call: the base
+ * command joined with its argument tokens (wrappers stripped). The permission
+ * engine matches an induscode `Bash(...)` specifier against EACH of these — an
+ * allow rule must cover them all to auto-allow, a deny on any one denies the
+ * whole call.
+ *
+ * For `npm test && rm important.txt` this yields `["npm test", "rm
+ * important.txt"]`, so `Bash(npm test)` allows the first but not the second.
+ * Returns the original command (single element) when nothing parses, so a tool
+ * call always has at least one subject to match against.
+ */
+export declare function bashSubcommandSubjects(command: string): string[];

package/dist/types/conductor/bash-guard.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Bash command parser/classifier + catastrophic blocklist — unit tests.
+ *
+ * Pins the parser ({@link parseBashCommand}) across the four concerns that make
+ * coarse whole-string matching trivially bypassable:
+ *   - **compound** splitting on `;`, `&&`, `||`, `|`, `&`, newlines,
+ *   - benign **wrapper** stripping (`env VAR=x`, `nohup`, `timeout N`, `nice -n
+ *     N`, `xargs`, `command`, and `sudo`/`doas` as elevation),
+ *   - **subshell / command-substitution** descent (`( … )`, `$( … )`, `` ` … ` ``),
+ *   - **quote-aware** tokenization so an operator inside a quote is not a
+ *     boundary and a quoted/escaped binary cannot hide from the classifier,
+ * plus the documented bypass cases. Then the catastrophic blocklist
+ * ({@link evaluateCatastrophic}) — `rm -rf /` and root-ish targets, fork bombs,
+ * `curl | sh`, raw-disk writes, `mkfs`, `chmod -R 777 /` — alongside the
+ * negative cases proving normal dev commands are NOT blocked. No I/O.
+ */
+export {};

package/dist/types/conductor/conductor.d.ts

@@ -36,6 +36,7 @@ import { type ConductorFault, type ConductorPhase, type ConductorState, type Ses
 import { ModelMatcher } from "./catalog";
 import { SignalHub } from "./signal-hub";
 import { TranscriptStore } from "./transcript-store";
+import { DiagnosticsEngine, type DiagnosticsConfig } from "./diagnostics";
 /**
  * The slice of the framework `Agent` the conductor drives.
  *
@@ -73,12 +74,30 @@ export interface AgentLike {
     setThinkingLevel?(level: ThinkingLevel): void;
 }
 /**
- * The pluggable condense hook. Given the active branch's messages, it returns the
- * (smaller) message list to replace it with. The real window-budget engine arrives
- * in Phase 3; the {@link noopCondense} default is an identity transform.
+ * Options handed to a {@link CondenseFn} on each invocation.
+ *
+ * Every field is optional so a scripted/no-op hook can ignore the bag entirely:
+ *   - `force`         — a manual `/compact` (fold to the last user turn) vs the
+ *                       budget-gated auto path.
+ *   - `model`         — the model bound to the live session, forwarded so the
+ *                       summarizer can write a *real* digest instead of the
+ *                       no-model local stub. Omitted when no model is bound.
+ *   - `contextTokens` — the conductor's latest provider-reported context
+ *                       occupancy, an optional anchor for the slice planner.
+ */
+export interface CondenseOpts {
+    readonly force?: boolean;
+    readonly model?: Model<any>;
+    readonly contextTokens?: number;
+}
+/**
+ * The pluggable condense hook. Given the active branch's messages (and an options
+ * bag), it returns the (smaller) message list to replace it with. The live
+ * window-budget engine is wired in `boot/runners/session.ts`; the
+ * {@link noopCondense} default is an identity transform that ignores the opts.
  */
-export type CondenseFn = (messages: AgentMessage[], force?: boolean) => AgentMessage[] | Promise<AgentMessage[]>;
-/** The default condense hook: returns the input unchanged (no-op). */
+export type CondenseFn = (messages: AgentMessage[], opts?: CondenseOpts) => AgentMessage[] | Promise<AgentMessage[]>;
+/** The default condense hook: returns the input unchanged (no-op), ignoring opts. */
 export declare const noopCondense: CondenseFn;
 /** Tuning for the transient-fault auto-retry. */
 export interface RetryPolicy {
@@ -105,10 +124,22 @@ export interface ConductorDeps {
     readonly condense?: CondenseFn;
     /** Auto-retry tuning. */
     readonly retry?: RetryPolicy;
-    /** Branch length past which auto-compaction fires (default 200). */
+    /**
+     * Legacy branch-length condense threshold. The auto path is now token-gated
+     * ({@link isOverBudget}), so this field is accepted but no longer governs when
+     * auto-compaction fires; kept for back-compat with callers that pass it.
+     */
     readonly compactAt?: number;
     /** Sleep primitive (injected so tests don't actually wait). */
     readonly sleep?: (ms: number) => Promise<void>;
+    /**
+     * Post-edit live-diagnostics control. Pass a ready {@link DiagnosticsEngine} to
+     * inject one directly (tests), a {@link DiagnosticsConfig} to tune the default
+     * engine, or omit it to get the default: ON when `workspace` has a
+     * `tsconfig.json` (eslint runner added when an eslint config is present),
+     * otherwise inert. Set `{ enabled: false }` to opt out entirely.
+     */
+    readonly diagnostics?: DiagnosticsEngine | DiagnosticsConfig;
 }
 /** The transitions the reducer understands — fresh vocabulary, all typed. */
 type StateAction = {