@cleocode/contracts 2026.6.12 → 2026.6.13

package/src/operations/llm.ts

@@ -10,6 +10,8 @@
  */
 
 import type { BuiltinProviderId, ProviderId } from '../llm/provider-id.js';
+import type { SealedCredential } from '../llm/sealed-credential.js';
+import type { SystemOfUseKind, SystemOfUsePickerEntry } from '../llm/system-of-use.js';
 
 /**
  * @deprecated since Phase 4 (ADR-072). Use {@link ProviderId} from
@@ -196,6 +198,33 @@ export interface CredentialResultWire {
   authType: AuthTypeWire;
 }
 
+/**
+ * Non-secret credential metadata — the E10 (T11753) redacted view of a resolved
+ * credential that {@link ResolvedLLM} carries inline.
+ *
+ * This is {@link CredentialResultWire} with the secret-bearing `apiKey` field
+ * **structurally removed**. The resolver returns this metadata so consumers can
+ * branch on `authType` / `source` / `provider` (e.g. choose OAuth-vs-api_key
+ * header style, surface `cleo llm whoami` diagnostics) WITHOUT any plaintext
+ * crossing the resolver boundary. The plaintext is reachable ONLY via
+ * {@link ResolvedLLM.sealedCredential}'s `fetch()` at the wire.
+ *
+ * @task T11753
+ * @epic T11746
+ */
+export interface CredentialMetadataWire {
+  /** Provider transport this credential is for. */
+  provider: ModelTransport;
+  /**
+   * Which tier produced this credential. `undefined` only when no credential
+   * was resolved (in which case both this and {@link ResolvedLLM.sealedCredential}
+   * are `null`).
+   */
+  source: CredentialSourceWire | undefined;
+  /** Scheme used to present the credential to the provider. */
+  authType: AuthTypeWire;
+}
+
 // ============================================================================
 // Role-based LLM resolution wire types (T9255 — Phase 2 T-llm-1)
 // ============================================================================
@@ -204,22 +233,28 @@ export interface CredentialResultWire {
  * Which configuration tier produced a {@link ResolvedLLM}.
  *
  * Resolution chain order:
- *   1. `role`               — `config.llm.roles[role]` (explicit override)
- *   2. `profile`            — `config.llm.profiles[roles[role].profile]`
- *   3. `default`            — `config.llm.default` (canonical default)
- *   4. `default-profile`    — `config.llm.profiles[config.llm.defaultProfile]`
- *   5. `implicit-fallback`  — hard-coded fallback inside the resolver
+ *   1. `role`                — `config.llm.roles[role]` (explicit override)
+ *   2. `profile`             — `config.llm.profiles[roles[role].profile]`
+ *   3. `system`              — `config.llm.systems[systemKey]` (granular override)
+ *   4. `default`             — `config.llm.default` (canonical default)
+ *   5. `default-profile`     — `config.llm.profiles[config.llm.defaultProfile]`
+ *   6. `registered-default`  — `registerSystemOfUse()` default (below user config)
+ *   7. `implicit-fallback`   — hard-coded fallback inside the resolver
  *
  * Useful for `cleo llm whoami` diagnostics.
  *
  * @task T9306
  * @task T11617 (`profile`, `default-profile`)
+ * @task T11748 (`system`)
+ * @task T11751 (`registered-default`)
  */
 export type ResolutionSource =
   | 'role'
   | 'profile'
+  | 'system'
   | 'default'
   | 'default-profile'
+  | 'registered-default'
   | 'implicit-fallback';
 
 /**
@@ -256,10 +291,33 @@ export interface ResolvedLLM {
    */
   client: unknown;
   /**
-   * Resolved credential. `null` when no tier produced a token. Callers
-   * MUST handle this case.
+   * Resolved credential **metadata** — provider / source / authType only.
+   * `null` when no tier produced a credential (in which case
+   * {@link sealedCredential} is also `null`). Callers MUST handle this case.
+   *
+   * E10 (T11753): the secret-bearing `apiKey` field has been **removed** — this
+   * is now a {@link CredentialMetadataWire}, NOT the old
+   * {@link CredentialResultWire}. The plaintext token never rides on this
+   * envelope; obtain it ONLY via {@link sealedCredential}'s `fetch()` at the
+   * wire. Branch on `authType` / `source` here for header-style / diagnostics.
+   */
+  credential: CredentialMetadataWire | null;
+  /**
+   * Sealed credential handle — the E10 on-demand-decrypt credential surface
+   * (T11752 · T11753 · T11746). `null` when no tier produced a credential
+   * (paired with `credential === null`); non-null exactly when a usable
+   * credential was resolved.
+   *
+   * The plaintext token is materialized ONLY by calling
+   * {@link SealedCredential.fetch} at the wire (`transportForProvider` /
+   * `session-factory.ts`) or daemon worker-injection — never returned up this
+   * envelope. This is the canonical credential surface; the old inline
+   * `credential.apiKey` plaintext is gone.
+   *
+   * @task T11752
+   * @task T11753
    */
-  credential: CredentialResultWire | null;
+  sealedCredential: SealedCredential | null;
   /** Which config path produced this resolution. */
   source: ResolutionSource;
   /** When `roles[role].credentialLabel` was set, the label that was used. */
@@ -278,6 +336,19 @@ export interface ResolveLLMForRoleOptions {
    * Defaults to `process.cwd()`.
    */
   projectRoot?: string;
+  /**
+   * Optional encoded system-of-use key (e.g. `'sentient'`, `'tool:web-search'`)
+   * that activates the `llm.systems[key]` override tier in the resolution chain
+   * (E9 · T11748).
+   *
+   * When set, `llm.systems[systemKey]` is consulted AFTER any explicit
+   * role/argument override but BEFORE the global `llm.defaultProfile`. Threaded
+   * down by `resolveLLMForSystem`; direct role callers leave it unset and the
+   * system tier is skipped — preserving role-resolution behaviour unchanged.
+   *
+   * @task T11748
+   */
+  systemKey?: string;
 }
 
 // ============================================================================
@@ -570,6 +641,32 @@ export interface LlmWhoamiResult {
   entries: LlmWhoamiEntry[];
 }
 
+/**
+ * Parameters for `llm.systems-of-use` (query — the profile-picker enumeration).
+ *
+ * Reserved for future filters (e.g. by {@link SystemOfUsePickerEntry.kind}).
+ *
+ * @task T11751
+ */
+export interface LlmSystemsOfUseParams {
+  /** Optional kind filter — when set, only that axis is enumerated. */
+  kind?: SystemOfUseKind;
+}
+
+/**
+ * Result envelope for `llm.systems-of-use` (query · T11751 · AC2).
+ *
+ * The merged picker surface: every builtin {@link SystemOfUse} plus every
+ * runtime-registered system (`registerSystemOfUse`), so the TUI / Studio
+ * profile picker can enumerate them from ONE op.
+ *
+ * @task T11751
+ */
+export interface LlmSystemsOfUseResult {
+  /** One entry per builtin or registered system-of-use. */
+  entries: SystemOfUsePickerEntry[];
+}
+
 // ProviderProfile interface lives in ./llm/provider-profile.ts (T9262).
 // The generated catalog (packages/core/src/llm/generated/provider-profiles.ts)
 // imports the canonical type from the contracts package and emits each

package/src/operations/validate.ts

@@ -2,11 +2,9 @@
  * Validate / Check Domain Operations
  *
  * T982 extension: Added new types for gate, archive, coherence, compliance-sync,
- * chain, grade, canon, workflow-compliance, verify-explain, and all protocol subtypes.
+ * grade, canon, workflow-compliance, verify-explain, and all protocol subtypes.
  */
 
-import type { WarpChain } from '../warp-chain.js';
-
 export type ValidationSeverity = 'error' | 'warning' | 'info';
 
 export interface ValidationViolation {
@@ -242,16 +240,6 @@ export interface ValidateArchiveStatsParams {
 }
 export type ValidateArchiveStatsResult = Record<string, unknown>;
 
-export interface ValidateChainParams {
-  chain: WarpChain;
-}
-export interface ValidateChainResult {
-  wellFormed: boolean;
-  gateSatisfiable: boolean;
-  errors: string[];
-  warnings: string[];
-}
-
 export interface ValidateGradeParams {
   sessionId: string;
 }
@@ -379,7 +367,6 @@ export type CheckOps = {
   readonly 'gate.set': readonly [ValidateGateParams, ValidateGateResult];
   readonly 'verify.explain': readonly [ValidateVerifyExplainParams, ValidateVerifyExplainResult];
   readonly 'archive.stats': readonly [ValidateArchiveStatsParams, ValidateArchiveStatsResult];
-  readonly 'chain.validate': readonly [ValidateChainParams, ValidateChainResult];
   readonly grade: readonly [ValidateGradeParams, ValidateGradeResult];
   readonly 'grade.list': readonly [ValidateGradeListParams, ValidateGradeListResult];
   readonly canon: readonly [ValidateCanonParams, ValidateCanonResult];

package/src/playbook.ts

@@ -77,6 +77,55 @@ export interface PlaybookApprovalNode extends PlaybookNodeBase {
 
 export type PlaybookNode = PlaybookAgenticNode | PlaybookDeterministicNode | PlaybookApprovalNode;
 
+/**
+ * Declarative, eval-free predicate over the playbook run `context` used to
+ * guard a conditional branch edge (T11806).
+ *
+ * The predicate is intentionally a *pure data* description — never an
+ * arbitrary expression — so the runtime stays deterministic and sandbox-safe.
+ * The named `field` is resolved against the accumulated run context
+ * (`context[field]`) and compared by exactly one of the optional operators
+ * below. When a `PlaybookEdge` carries a `when` predicate, the runtime only
+ * traverses that edge if the predicate evaluates to `true`.
+ *
+ * Exactly one comparison operator (`equals`, `notEquals`, `exists`, `in`, or
+ * `truthy`) should be supplied; the parser enforces this so an ambiguous
+ * predicate is rejected at parse time rather than mis-routing at runtime.
+ *
+ * @example
+ * ```yaml
+ * edges:
+ *   - from: classify
+ *     to: deep-research        # taken when context.needsResearch === true
+ *     when: { field: needsResearch, equals: true }
+ *   - from: classify
+ *     to: skip-research        # taken when context.needsResearch !== true
+ *     when: { field: needsResearch, notEquals: true }
+ * ```
+ *
+ * @task T11806 — cantbook runtime branching
+ */
+export interface PlaybookEdgeCondition {
+  /** Context key whose value the predicate is evaluated against. */
+  field: string;
+  /** Edge is satisfied when `context[field]` strictly equals this value. */
+  equals?: unknown;
+  /** Edge is satisfied when `context[field]` strictly does NOT equal this value. */
+  notEquals?: unknown;
+  /**
+   * When `true`, edge is satisfied iff `field` is present in context;
+   * when `false`, satisfied iff `field` is absent from context.
+   */
+  exists?: boolean;
+  /** Edge is satisfied when `context[field]` is one of these values. */
+  in?: unknown[];
+  /**
+   * When `true`, edge is satisfied iff `context[field]` is truthy;
+   * when `false`, satisfied iff `context[field]` is falsy.
+   */
+  truthy?: boolean;
+}
+
 export interface PlaybookEdge {
   from: string;
   to: string;
@@ -84,6 +133,18 @@ export interface PlaybookEdge {
     requires?: string[];
     ensures?: string[];
   };
+  /**
+   * Optional declarative branch guard (T11806). When present, the edge is
+   * only traversed if the {@link PlaybookEdgeCondition} predicate over the
+   * run `context` is satisfied. Edges without `when` are unconditional.
+   *
+   * A node may have multiple outgoing edges as long as every additional
+   * edge carries a `when` guard — the runtime evaluates them against the
+   * current context and routes to the single satisfied successor. More than
+   * one *unconditional* successor remains a fail-closed error (genuine
+   * ambiguity).
+   */
+  when?: PlaybookEdgeCondition;
 }
 
 export interface PlaybookErrorHandler {

package/src/session.ts

@@ -121,6 +121,17 @@ export interface Session {
   previousSessionId?: string | null;
   /** ID of the session that follows this one. @defaultValue undefined */
   nextSessionId?: string | null;
+  /**
+   * ID of the fork-tree PARENT session that spawned this one (T11639).
+   *
+   * Sourced from `CLEO_PARENT_SESSION_ID` (stamped by the supervisor — T11629).
+   * Distinct from {@link Session.previousSessionId} (the linear resume chain):
+   * `parentSessionId` is the orchestrator→worker spawn edge. NULL/undefined for a
+   * root session with no spawning parent.
+   *
+   * @defaultValue undefined
+   */
+  parentSessionId?: string | null;
   /** Provider-specific agent identifier string. @defaultValue undefined */
   agentIdentifier?: string | null;
   /** ISO 8601 timestamp of when the handoff was consumed. @defaultValue undefined */

package/src/tools/agent-tools.ts

@@ -0,0 +1,270 @@
+/**
+ * Agent-facing tool family I/O contracts (T1741 · epic T11456 · SG-TOOLS).
+ *
+ * The shared, types-only I/O shapes for the six CORE agent-tool families wired
+ * into the {@link ./atomic.js | atomic} primitive layer and surfaced through the
+ * `AgentToolRegistry` (`packages/core/src/tools/agent-registry.ts`):
+ *
+ *   - **terminal** — `run_shell` with PTY + non-PTY modes ({@link RunShellInput}).
+ *   - **file/read** — `read_file` with pagination ({@link ReadFilePagedInput}).
+ *   - **file/patch** — `apply_patch` with fuzzy hunk matching ({@link ApplyPatchInput}).
+ *   - **search** — `search_files` over ripgrep ({@link SearchFilesInput}).
+ *   - **git** — status / diff / log / commit ({@link GitStatusInput} …).
+ *
+ * These compose OVER the atomic `fs`/`shell`/`search` primitives — they never
+ * introduce a new side-effect surface. The implementations
+ * (`packages/core/src/tools/builtin/*`) perform ALL work through the injected
+ * `GuardedToolSurface` (deny-first chokepoint), so the same guardrail policy
+ * applies. Types-only — no runtime logic (Gate 10 `contracts-purity`).
+ *
+ * @epic T11456
+ * @task T1741
+ * @see ./atomic.js — the raw primitive I/O shapes these compose over
+ */
+
+// ---------------------------------------------------------------------------
+// terminal — run_shell (PTY + non-PTY)
+// ---------------------------------------------------------------------------
+
+/**
+ * Execution mode for {@link RunShellInput}.
+ *
+ * - `pty` — allocate a pseudo-terminal (line-discipline, colour, interactive
+ *   programs). Requires the OPTIONAL `node-pty` native dep; when it cannot be
+ *   loaded the implementation transparently falls back to `spawn`.
+ * - `spawn` — plain `child_process.spawn` (no TTY). Always available.
+ * - `auto` — prefer `pty` when `node-pty` is loadable, else `spawn`.
+ */
+export type ShellRunMode = 'pty' | 'spawn' | 'auto';
+
+/** Input for the `run_shell` terminal tool. */
+export interface RunShellInput {
+  /** Executable to run (argv form — NOT a shell string; no shell interpolation). */
+  readonly command: string;
+  /** Arguments for {@link RunShellInput.command}. */
+  readonly args?: readonly string[];
+  /** Working directory. */
+  readonly cwd?: string;
+  /** Extra environment variables (scrubbed at the guard chokepoint). */
+  readonly env?: Readonly<Record<string, string>>;
+  /** Hard timeout in milliseconds; the process is killed when exceeded. */
+  readonly timeoutMs?: number;
+  /** Execution mode. Defaults to `auto`. */
+  readonly mode?: ShellRunMode;
+  /** PTY column count (PTY mode only). Defaults to 80. */
+  readonly cols?: number;
+  /** PTY row count (PTY mode only). Defaults to 24. */
+  readonly rows?: number;
+}
+
+/** Result of the `run_shell` terminal tool. */
+export interface RunShellResult {
+  /**
+   * Combined output. In `spawn` mode this is stdout; in `pty` mode stdout and
+   * stderr are interleaved on the single PTY stream (as a real terminal does).
+   */
+  readonly stdout: string;
+  /** Captured standard error. Empty in PTY mode (merged into {@link RunShellResult.stdout}). */
+  readonly stderr: string;
+  /** Process exit code (0 = success). `null` when killed by signal/timeout. */
+  readonly code: number | null;
+  /** The mode that actually ran (`pty` downgrades to `spawn` when unavailable). */
+  readonly mode: 'pty' | 'spawn';
+  /** Whether a PTY was requested but unavailable, so `spawn` was used instead. */
+  readonly ptyFellBack: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// file — read_file (pagination)
+// ---------------------------------------------------------------------------
+
+/** Input for the paginated `read_file` tool. */
+export interface ReadFilePagedInput {
+  /** Absolute path to read. */
+  readonly path: string;
+  /** 0-based line offset to start from. Defaults to 0. */
+  readonly offset?: number;
+  /** Maximum number of lines to return. Omit for "to end of file". */
+  readonly limit?: number;
+}
+
+/** Result of a paginated read. */
+export interface ReadFilePagedResult {
+  /** Absolute path that was read. */
+  readonly path: string;
+  /** The selected slice of lines (joined with `\n`). */
+  readonly content: string;
+  /** 0-based line offset the slice began at. */
+  readonly offset: number;
+  /** Number of lines returned. */
+  readonly lineCount: number;
+  /** Total number of lines in the file. */
+  readonly totalLines: number;
+  /** Whether more lines exist after the returned slice. */
+  readonly hasMore: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// file — apply_patch (fuzzy)
+// ---------------------------------------------------------------------------
+
+/** Input for the `apply_patch` tool (fuzzy, whitespace-tolerant replacement). */
+export interface ApplyPatchInput {
+  /** Absolute path of the file to patch. */
+  readonly path: string;
+  /** Exact-or-fuzzy block of original text to locate. */
+  readonly oldText: string;
+  /** Replacement text. */
+  readonly newText: string;
+  /**
+   * Permit fuzzy (leading/trailing whitespace-insensitive) matching when an
+   * exact match is not found. Defaults to `true`.
+   */
+  readonly fuzzy?: boolean;
+}
+
+/** Result of an `apply_patch`. */
+export interface ApplyPatchResult {
+  /** Absolute path that was patched. */
+  readonly path: string;
+  /** Whether the replacement was applied. */
+  readonly applied: boolean;
+  /** How the match was located: exact, fuzzy (whitespace-normalised), or none. */
+  readonly matchKind: 'exact' | 'fuzzy' | 'none';
+  /** 0-based line where the replacement began (when applied). */
+  readonly startLine?: number;
+}
+
+// ---------------------------------------------------------------------------
+// search — search_files (ripgrep)
+// ---------------------------------------------------------------------------
+
+/** Input for the ripgrep-backed `search_files` tool. */
+export interface SearchFilesInput {
+  /** Pattern to search for (regex by default — see {@link SearchFilesInput.fixedStrings}). */
+  readonly pattern: string;
+  /** Root directory to search under. */
+  readonly root: string;
+  /** Treat {@link SearchFilesInput.pattern} as a literal string, not a regex. */
+  readonly fixedStrings?: boolean;
+  /** Case-insensitive matching. */
+  readonly ignoreCase?: boolean;
+  /** Restrict to files matching this ripgrep glob (e.g. `*.ts`). */
+  readonly glob?: string;
+  /** Cap on returned matches. Defaults to 1000. */
+  readonly maxResults?: number;
+}
+
+/** A single `search_files` match. */
+export interface SearchFilesMatch {
+  /** Absolute (or root-relative) path of the matching file. */
+  readonly path: string;
+  /** 1-based line number of the match. */
+  readonly line: number;
+  /** The matching line's text (trailing newline stripped). */
+  readonly text: string;
+}
+
+/** Result of `search_files`. */
+export interface SearchFilesResult {
+  /** Matches in ripgrep order. */
+  readonly matches: readonly SearchFilesMatch[];
+  /** Whether {@link SearchFilesInput.maxResults} truncated the results. */
+  readonly truncated: boolean;
+  /**
+   * `true` when ripgrep (`rg`) was unavailable and the search degraded to a
+   * built-in scan, so callers can surface reduced fidelity.
+   */
+  readonly degraded: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// git — status / diff / log / commit
+// ---------------------------------------------------------------------------
+
+/** Common options for the git tools. */
+export interface GitToolBase {
+  /** Repository working directory. Defaults to `process.cwd()`. */
+  readonly cwd?: string;
+  /** Hard timeout in milliseconds. */
+  readonly timeoutMs?: number;
+}
+
+/** Input for `git_status`. */
+export interface GitStatusInput extends GitToolBase {}
+
+/** One porcelain-v1 status entry. */
+export interface GitStatusEntry {
+  /** Two-char XY porcelain status code (e.g. ` M`, `A `, `??`). */
+  readonly status: string;
+  /** Path the status applies to. */
+  readonly path: string;
+}
+
+/** Result of `git_status`. */
+export interface GitStatusResult {
+  /** The current branch name (`HEAD` when detached/unknown). */
+  readonly branch: string;
+  /** Parsed porcelain entries. */
+  readonly entries: readonly GitStatusEntry[];
+  /** Whether the working tree has any uncommitted changes. */
+  readonly clean: boolean;
+}
+
+/** Input for `git_diff`. */
+export interface GitDiffInput extends GitToolBase {
+  /** Show staged (`--cached`) changes instead of the working tree. */
+  readonly staged?: boolean;
+  /** Restrict the diff to these paths. */
+  readonly paths?: readonly string[];
+}
+
+/** Result of `git_diff`. */
+export interface GitDiffResult {
+  /** The unified diff text (empty when there are no changes). */
+  readonly diff: string;
+}
+
+/** Input for `git_log`. */
+export interface GitLogInput extends GitToolBase {
+  /** Maximum number of commits to return. Defaults to 20. */
+  readonly maxCount?: number;
+}
+
+/** One commit in a `git_log` result. */
+export interface GitLogEntry {
+  /** Full commit SHA. */
+  readonly sha: string;
+  /** Author name. */
+  readonly author: string;
+  /** ISO-8601 author date. */
+  readonly date: string;
+  /** Commit subject (first line). */
+  readonly subject: string;
+}
+
+/** Result of `git_log`. */
+export interface GitLogResult {
+  /** Commits newest-first. */
+  readonly commits: readonly GitLogEntry[];
+}
+
+/** Input for `git_commit`. */
+export interface GitCommitInput extends GitToolBase {
+  /** Commit message. */
+  readonly message: string;
+  /** Stage all tracked modifications first (`-a`). Defaults to `false`. */
+  readonly all?: boolean;
+  /** Explicit paths to stage before committing. */
+  readonly paths?: readonly string[];
+}
+
+/** Result of `git_commit`. */
+export interface GitCommitResult {
+  /** Whether the commit was created. */
+  readonly committed: boolean;
+  /** The new commit SHA (when created). */
+  readonly sha?: string;
+  /** Git's stdout/stderr summary (e.g. "nothing to commit"). */
+  readonly summary: string;
+}

package/src/tools/atomic.ts

@@ -36,6 +36,27 @@ export const TOOL_CLASSES = ['fs', 'shell', 'search', 'net', 'notebook'] as cons
 /** One of the canonical {@link TOOL_CLASSES}. */
 export type ToolClass = (typeof TOOL_CLASSES)[number];
 
+/**
+ * Agent-facing **toolset** groups (T1739 · AC4 · epic T11456).
+ *
+ * Where {@link TOOL_CLASSES} groups primitives by their SIDE-EFFECT surface (and
+ * therefore by guardrail policy), a {@link Toolset} groups tools by the
+ * AGENT-FACING CAPABILITY a model selects when reasoning — the dimension Hermes'
+ * `tools/registry.py` exposes to the loop. The two axes are orthogonal: an `fs`
+ * class primitive belongs to the `file` toolset, a `shell` class primitive to the
+ * `terminal` toolset, a `net` class primitive to the `web` toolset, etc.
+ *
+ * - `terminal` — shell / process execution (`executeShell`, `runGit`).
+ * - `file` — filesystem read/write/search (`readFileText`, `writeFileAtomic`, …).
+ * - `web` — outbound network / fetch (`fetch`).
+ * - `agent` — sub-agent / delegation / task orchestration tools.
+ * - `media` — image / audio / notebook authoring (`notebookEdit`, …).
+ */
+export const AGENT_TOOLSETS = ['terminal', 'file', 'web', 'agent', 'media'] as const;
+
+/** One of the canonical {@link AGENT_TOOLSETS}. */
+export type Toolset = (typeof AGENT_TOOLSETS)[number];
+
 /**
  * Descriptor for a single registered tool primitive. The registry of these is
  * the SoT for "what atomic tools exist", consumed by the guardrail chokepoint

package/src/tools/index.ts

@@ -7,6 +7,30 @@
  * @epic T9835
  */
 
+// === Agent-facing tool families (T1741 / T11456) ===
+export type {
+  ApplyPatchInput,
+  ApplyPatchResult,
+  GitCommitInput,
+  GitCommitResult,
+  GitDiffInput,
+  GitDiffResult,
+  GitLogEntry,
+  GitLogInput,
+  GitLogResult,
+  GitStatusEntry,
+  GitStatusInput,
+  GitStatusResult,
+  GitToolBase,
+  ReadFilePagedInput,
+  ReadFilePagedResult,
+  RunShellInput,
+  RunShellResult,
+  SearchFilesInput,
+  SearchFilesMatch,
+  SearchFilesResult,
+  ShellRunMode,
+} from './agent-tools.js';
 export type { FetchBrainEntriesInput, FetchBrainEntriesOutput } from './brain-fetch.js';
 export type { ObserveBrainInput, ObserveBrainOutput } from './brain-observe.js';
 // === BrainTools (T10070 / T9835c) ===
@@ -41,3 +65,25 @@ export type {
   ScoreTaskInput,
   ScoreTaskResult,
 } from './score-task-priority.js';
+// === Web + browser agent tools (T1742 / T11456) ===
+export type {
+  AccessibilityNode,
+  BrowserActionResult,
+  BrowserClickInput,
+  BrowserNavigateInput,
+  BrowserPageState,
+  BrowserPressInput,
+  BrowserScrollDirection,
+  BrowserScrollInput,
+  BrowserScrollResult,
+  BrowserSnapshotResult,
+  BrowserTypeInput,
+  BrowserVisionInput,
+  BrowserVisionResult,
+  WebExtractInput,
+  WebExtractResult,
+  WebSearchBackendId,
+  WebSearchHit,
+  WebSearchInput,
+  WebSearchResult,
+} from './web-tools.js';

package/src/tools/skill-executor.ts

@@ -44,6 +44,7 @@
  * @see ./atomic.js — the tool I/O shapes this seam composes over
  */
 
+import type { RunShellInput, RunShellResult } from './agent-tools.js';
 import type {
   ExecuteShellInput,
   ExecuteShellResult,
@@ -86,6 +87,12 @@ export interface GuardedToolSurface {
   pathExists(input: PathExistsInput): Promise<PathExistsResult>;
   /** Run a command with explicit cwd/env/timeout through the guard. */
   executeShell(input: ExecuteShellInput): Promise<ExecuteShellResult>;
+  /**
+   * Run a command under a pseudo-terminal (PTY) through the guard, falling back
+   * to a non-PTY spawn when a PTY backend is unavailable. Subject to the same
+   * deny-first command policy + env scrubbing as {@link GuardedToolSurface.executeShell}.
+   */
+  executePty(input: RunShellInput): Promise<RunShellResult>;
   /** Run a git subcommand through the guard. */
   runGit(input: RunGitInput): Promise<ExecuteShellResult>;
 }