@theokit/sdk-tools 0.21.0 → 0.22.0

package/dist/index.d.cts

@@ -119,6 +119,17 @@ declare function createCurrentTimeTool(opts?: CreateCurrentTimeToolOptions): Cus
  */
 
 interface CreateEditFileToolOptions {
+    /**
+     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     *
+     * Existe porque, no Codex, o nome NASCE na definição da tool e é a chave de decisão de approval —
+     * três consumidores (modelo, approval, telemetry) de uma string decidida num lugar só. Renomear
+     * depois da construção é mudar a identidade de algo já publicado ao modelo. `withName` continua
+     * para o caso genuinamente dinâmico.
+     */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Absolute path to the project root. Every edit is gated against this boundary. */
     projectRoot: string;
     /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the read + `.bak` backup +
@@ -175,6 +186,40 @@ interface CreateGitDiffToolOptions {
 }
 declare function createGitDiffTool(opts: CreateGitDiffToolOptions): CustomTool;
 
+/**
+ * `git_status` — built-in tool for coding agents.
+ *
+ * Returns the working-tree status in porcelain v1 format (`git status --porcelain`), which is the
+ * stable machine-readable form — the human format is explicitly not guaranteed across git versions.
+ *
+ * M76 — nasce ao lado de `git_diff` e compartilha o motor de execução (`internal/git-exec.ts`): teto
+ * de stdout, kill do grupo de processos no timeout e mapeamento para erro tipado são a MESMA regra
+ * para qualquer subcomando do git. O consumidor (agent-builder) tinha isto local em 62 LoC; nada ali
+ * era específico dele.
+ *
+ * Result shape (always a JSON string):
+ *   - `{ ok: true, diff: string, truncated?: boolean }` — `diff` carrega a saída porcelain
+ *   - `{ ok: false, error: 'not_a_repo' | 'path_traversal' | 'timeout' | 'git_failed' }`
+ */
+
+interface CreateGitStatusToolOptions {
+    /** Absolute path to the project root. Every invocation is gated against this boundary. */
+    projectRoot: string;
+    /** Wall-clock cap; the process group is killed on expiry. Default 30_000. */
+    timeoutMs?: number;
+    /** Cap on captured stdout; excess sets `truncated: true`. Default 5 MB. */
+    maxStdoutBytes?: number;
+    /**
+     * M76 — nome exposto ao modelo. Omitido ⇒ `"git_status"` (aditivo).
+     *
+     * O nome é contrato: chave de approval, o que o modelo vê e o que o telemetry registra.
+     */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal abaixo (aditivo). */
+    description?: string;
+}
+declare function createGitStatusTool(opts: CreateGitStatusToolOptions): CustomTool;
+
 /**
  * `glob_files` — built-in tool for coding agents.
  *
@@ -528,6 +573,26 @@ declare function withShellExitGuidance(tool: CustomTool): CustomTool;
  */
 
 interface CreateListDirToolOptions {
+    /**
+     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     *
+     * Existe porque, no Codex, o nome NASCE na definição da tool e é a chave de decisão de approval —
+     * três consumidores (modelo, approval, telemetry) de uma string decidida num lugar só. Renomear
+     * depois da construção é mudar a identidade de algo já publicado ao modelo. `withName` continua
+     * para o caso genuinamente dinâmico.
+     */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
+    /**
+     * M76 — opt-in "lista-em-qualquer-lugar": honra um `path` ABSOLUTO fora de `projectRoot`
+     * (paridade com `createReadFileTool`/`createSearchTextTool`, sandbox read-only do Codex).
+     *
+     * O guard de segredo por QUALQUER segmento continua valendo, e não é separável: `isForbiddenPath`
+     * só bloqueia o item sensível quando ele é o PRIMEIRO segmento, então um `/home/u/proj/.env/sub`
+     * passaria. Ligar o flag sem o guard é abrir exfiltração. Default `false` ⇒ absoluto rejeitado.
+     */
+    allowAbsolute?: boolean;
     /** Absolute path to the project root. Every listing is gated against this boundary. */
     projectRoot: string;
     /** Maximum number of entries returned per call. Default 500. */
@@ -605,17 +670,37 @@ declare function createPlanModeTool(options: PlanModeToolOptions): PlanModeToolW
  *   - `{ ok: false, error: "timeout" }`
  */
 interface QuestionToolOptions {
-    /** Callback that presents a question to the user and resolves with their answer. */
-    askUser: (question: string) => Promise<string>;
+    /**
+     * Callback que apresenta a pergunta ao usuário e resolve com a resposta.
+     *
+     * M76 — passou a ser OPCIONAL: o asker preferencial vem do contexto da run
+     * (`ctx.context.askUser`), porque um valor fixado aqui é o "baked into each factory" que a doc do
+     * `CustomTool.handler` aponta como o problema que `ctx.context` existe para resolver. Este campo
+     * permanece como fallback, para quem constrói a tool com um asker fixo (retrocompatível).
+     */
+    askUser?: (question: string) => Promise<string>;
     /** Maximum time to wait for user response in ms. Default: 300_000 (5 min). */
     timeoutMs?: number;
 }
+/**
+ * M76 — alinhado ao `CustomTool` do SDK. Era uma interface própria com `inputSchema: unknown`, o que
+ * obrigava todo consumidor a escrever um cast para registrar a tool — e cast não conserta contrato,
+ * só silencia o compilador, transformando uma futura mudança de assinatura em erro de RUNTIME.
+ *
+ * Estreitar foi aditivo: o valor sempre foi um objeto (`{ type: "object", properties, required }`
+ * logo abaixo); só o tipo declarado estava frouxo. O handler aceita o 2º argumento opcional do
+ * contrato (`ctx`), por onde o M76 passa a resolver o asker por sessão.
+ */
 interface QuestionTool {
     name: string;
     description: string;
-    inputSchema: unknown;
+    inputSchema: Record<string, unknown>;
     handler: (input: {
         question: string;
+    }, ctx?: {
+        signal?: AbortSignal;
+        context?: unknown;
+        threadId?: string;
     }) => Promise<string>;
 }
 declare function createQuestionTool(opts: QuestionToolOptions): QuestionTool;
@@ -782,6 +867,17 @@ declare function createRunVitestTool(opts: CreateRunVitestToolOptions): CustomTo
  */
 
 interface CreateSearchTextToolOptions {
+    /**
+     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     *
+     * Existe porque, no Codex, o nome NASCE na definição da tool e é a chave de decisão de approval —
+     * três consumidores (modelo, approval, telemetry) de uma string decidida num lugar só. Renomear
+     * depois da construção é mudar a identidade de algo já publicado ao modelo. `withName` continua
+     * para o caso genuinamente dinâmico.
+     */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     projectRoot: string;
     /** Cap on total matches returned. Default 100. */
     maxMatches?: number;
@@ -811,6 +907,17 @@ declare function createSearchTextTool(opts: CreateSearchTextToolOptions): Custom
  */
 
 interface CreateShellToolOptions {
+    /**
+     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     *
+     * Existe porque, no Codex, o nome NASCE na definição da tool e é a chave de decisão de approval —
+     * três consumidores (modelo, approval, telemetry) de uma string decidida num lugar só. Renomear
+     * depois da construção é mudar a identidade de algo já publicado ao modelo. `withName` continua
+     * para o caso genuinamente dinâmico.
+     */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Absolute path to the project root. Commands execute in this cwd. */
     projectRoot: string;
     /** Default timeout in ms. Capped at 300s. */
@@ -1117,4 +1224,4 @@ interface CreateWriteFileToolOptions {
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateCurrentTimeToolOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, ReadTracker, ReasoningTools, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateCurrentTimeToolOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGitStatusToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, ReadTracker, ReasoningTools, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };

package/dist/index.d.ts

@@ -119,6 +119,17 @@ declare function createCurrentTimeTool(opts?: CreateCurrentTimeToolOptions): Cus
  */
 
 interface CreateEditFileToolOptions {
+    /**
+     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     *
+     * Existe porque, no Codex, o nome NASCE na definição da tool e é a chave de decisão de approval —
+     * três consumidores (modelo, approval, telemetry) de uma string decidida num lugar só. Renomear
+     * depois da construção é mudar a identidade de algo já publicado ao modelo. `withName` continua
+     * para o caso genuinamente dinâmico.
+     */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Absolute path to the project root. Every edit is gated against this boundary. */
     projectRoot: string;
     /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the read + `.bak` backup +
@@ -175,6 +186,40 @@ interface CreateGitDiffToolOptions {
 }
 declare function createGitDiffTool(opts: CreateGitDiffToolOptions): CustomTool;
 
+/**
+ * `git_status` — built-in tool for coding agents.
+ *
+ * Returns the working-tree status in porcelain v1 format (`git status --porcelain`), which is the
+ * stable machine-readable form — the human format is explicitly not guaranteed across git versions.
+ *
+ * M76 — nasce ao lado de `git_diff` e compartilha o motor de execução (`internal/git-exec.ts`): teto
+ * de stdout, kill do grupo de processos no timeout e mapeamento para erro tipado são a MESMA regra
+ * para qualquer subcomando do git. O consumidor (agent-builder) tinha isto local em 62 LoC; nada ali
+ * era específico dele.
+ *
+ * Result shape (always a JSON string):
+ *   - `{ ok: true, diff: string, truncated?: boolean }` — `diff` carrega a saída porcelain
+ *   - `{ ok: false, error: 'not_a_repo' | 'path_traversal' | 'timeout' | 'git_failed' }`
+ */
+
+interface CreateGitStatusToolOptions {
+    /** Absolute path to the project root. Every invocation is gated against this boundary. */
+    projectRoot: string;
+    /** Wall-clock cap; the process group is killed on expiry. Default 30_000. */
+    timeoutMs?: number;
+    /** Cap on captured stdout; excess sets `truncated: true`. Default 5 MB. */
+    maxStdoutBytes?: number;
+    /**
+     * M76 — nome exposto ao modelo. Omitido ⇒ `"git_status"` (aditivo).
+     *
+     * O nome é contrato: chave de approval, o que o modelo vê e o que o telemetry registra.
+     */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal abaixo (aditivo). */
+    description?: string;
+}
+declare function createGitStatusTool(opts: CreateGitStatusToolOptions): CustomTool;
+
 /**
  * `glob_files` — built-in tool for coding agents.
  *
@@ -528,6 +573,26 @@ declare function withShellExitGuidance(tool: CustomTool): CustomTool;
  */
 
 interface CreateListDirToolOptions {
+    /**
+     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     *
+     * Existe porque, no Codex, o nome NASCE na definição da tool e é a chave de decisão de approval —
+     * três consumidores (modelo, approval, telemetry) de uma string decidida num lugar só. Renomear
+     * depois da construção é mudar a identidade de algo já publicado ao modelo. `withName` continua
+     * para o caso genuinamente dinâmico.
+     */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
+    /**
+     * M76 — opt-in "lista-em-qualquer-lugar": honra um `path` ABSOLUTO fora de `projectRoot`
+     * (paridade com `createReadFileTool`/`createSearchTextTool`, sandbox read-only do Codex).
+     *
+     * O guard de segredo por QUALQUER segmento continua valendo, e não é separável: `isForbiddenPath`
+     * só bloqueia o item sensível quando ele é o PRIMEIRO segmento, então um `/home/u/proj/.env/sub`
+     * passaria. Ligar o flag sem o guard é abrir exfiltração. Default `false` ⇒ absoluto rejeitado.
+     */
+    allowAbsolute?: boolean;
     /** Absolute path to the project root. Every listing is gated against this boundary. */
     projectRoot: string;
     /** Maximum number of entries returned per call. Default 500. */
@@ -605,17 +670,37 @@ declare function createPlanModeTool(options: PlanModeToolOptions): PlanModeToolW
  *   - `{ ok: false, error: "timeout" }`
  */
 interface QuestionToolOptions {
-    /** Callback that presents a question to the user and resolves with their answer. */
-    askUser: (question: string) => Promise<string>;
+    /**
+     * Callback que apresenta a pergunta ao usuário e resolve com a resposta.
+     *
+     * M76 — passou a ser OPCIONAL: o asker preferencial vem do contexto da run
+     * (`ctx.context.askUser`), porque um valor fixado aqui é o "baked into each factory" que a doc do
+     * `CustomTool.handler` aponta como o problema que `ctx.context` existe para resolver. Este campo
+     * permanece como fallback, para quem constrói a tool com um asker fixo (retrocompatível).
+     */
+    askUser?: (question: string) => Promise<string>;
     /** Maximum time to wait for user response in ms. Default: 300_000 (5 min). */
     timeoutMs?: number;
 }
+/**
+ * M76 — alinhado ao `CustomTool` do SDK. Era uma interface própria com `inputSchema: unknown`, o que
+ * obrigava todo consumidor a escrever um cast para registrar a tool — e cast não conserta contrato,
+ * só silencia o compilador, transformando uma futura mudança de assinatura em erro de RUNTIME.
+ *
+ * Estreitar foi aditivo: o valor sempre foi um objeto (`{ type: "object", properties, required }`
+ * logo abaixo); só o tipo declarado estava frouxo. O handler aceita o 2º argumento opcional do
+ * contrato (`ctx`), por onde o M76 passa a resolver o asker por sessão.
+ */
 interface QuestionTool {
     name: string;
     description: string;
-    inputSchema: unknown;
+    inputSchema: Record<string, unknown>;
     handler: (input: {
         question: string;
+    }, ctx?: {
+        signal?: AbortSignal;
+        context?: unknown;
+        threadId?: string;
     }) => Promise<string>;
 }
 declare function createQuestionTool(opts: QuestionToolOptions): QuestionTool;
@@ -782,6 +867,17 @@ declare function createRunVitestTool(opts: CreateRunVitestToolOptions): CustomTo
  */
 
 interface CreateSearchTextToolOptions {
+    /**
+     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     *
+     * Existe porque, no Codex, o nome NASCE na definição da tool e é a chave de decisão de approval —
+     * três consumidores (modelo, approval, telemetry) de uma string decidida num lugar só. Renomear
+     * depois da construção é mudar a identidade de algo já publicado ao modelo. `withName` continua
+     * para o caso genuinamente dinâmico.
+     */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     projectRoot: string;
     /** Cap on total matches returned. Default 100. */
     maxMatches?: number;
@@ -811,6 +907,17 @@ declare function createSearchTextTool(opts: CreateSearchTextToolOptions): Custom
  */
 
 interface CreateShellToolOptions {
+    /**
+     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     *
+     * Existe porque, no Codex, o nome NASCE na definição da tool e é a chave de decisão de approval —
+     * três consumidores (modelo, approval, telemetry) de uma string decidida num lugar só. Renomear
+     * depois da construção é mudar a identidade de algo já publicado ao modelo. `withName` continua
+     * para o caso genuinamente dinâmico.
+     */
+    name?: string;
+    /** M76 — descrição exposta ao modelo. Omitida ⇒ o literal de hoje (aditivo). */
+    description?: string;
     /** Absolute path to the project root. Commands execute in this cwd. */
     projectRoot: string;
     /** Default timeout in ms. Capped at 300s. */
@@ -1117,4 +1224,4 @@ interface CreateWriteFileToolOptions {
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateCurrentTimeToolOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, ReadTracker, ReasoningTools, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateCurrentTimeToolOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGitStatusToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, ReadTracker, ReasoningTools, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };

package/dist/index.js

@@ -5,9 +5,9 @@ import { z } from 'zod';
 import { safePathJoin, assertNoSymlinkEscape, PathTraversalError, ForbiddenPathError, isForbiddenPath, safeFilenameForId } from '@theokit/sdk/path-safety';
 import { replaceFileAtomic } from '@theokit/sdk/persistence';
 import { resolveFilesystem, FileNotFoundError, FilesystemSecurityError, FilesystemReadOnlyError, StaleFileError, FilesystemError } from '@theokit/sdk/filesystem';
-import { spawn } from 'child_process';
 import { existsSync, statSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from 'fs';
 import { resolveSandbox } from '@theokit/sdk/sandbox';
+import { spawn } from 'child_process';
 import { resolveInteractive, InteractiveUnavailableError, NoSuchSessionError } from '@theokit/sdk/interactive';
 import { lookup } from 'dns/promises';
 import { isIP } from 'net';
@@ -609,8 +609,8 @@ function editScopeError(path, projectRoot) {
 function createEditFileTool(opts) {
   const { projectRoot, filesystem } = opts;
   return Tool.create({
-    name: "edit_file",
-    description: "Make an exact string replacement in a project-relative file. Replaces the FIRST occurrence of old_string with new_string (a whitespace-normalized fallback is attempted if the exact match fails) and writes a .bak backup first. Read the file first so old_string matches the on-disk text exactly; include enough surrounding context to make it unique \u2014 only the first match is replaced, so a too-short old_string can edit the wrong location. old_string must be non-empty and differ from new_string; to change every occurrence, call edit_file repeatedly. Returns { ok, replacements } or { ok: false, error }.",
+    name: opts.name ?? "edit_file",
+    description: opts.description ?? "Make an exact string replacement in a project-relative file. Replaces the FIRST occurrence of old_string with new_string (a whitespace-normalized fallback is attempted if the exact match fails) and writes a .bak backup first. Read the file first so old_string matches the on-disk text exactly; include enough surrounding context to make it unique \u2014 only the first match is replaced, so a too-short old_string can edit the wrong location. old_string must be non-empty and differ from new_string; to change every occurrence, call edit_file repeatedly. Returns { ok, replacements } or { ok: false, error }.",
     inputSchema: z.object({
       path: z.string().min(1).describe("Project-relative file path."),
       old_string: z.string().min(1).describe("String to find in the file."),
@@ -682,21 +682,6 @@ function formatError(message, code) {
   return `> **Error:** ${prefix}${message}`;
 }
 
-// src/path-scope.ts
-function checkPathScope(path, projectRoot) {
-  if (path === void 0 || path === "") return null;
-  try {
-    const abs = safePathJoin(projectRoot, path);
-    assertNoSymlinkEscape(abs, projectRoot);
-    return null;
-  } catch (err) {
-    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
-      return JSON.stringify({ ok: false, error: "path_traversal", path });
-    }
-    throw err;
-  }
-}
-
 // src/subprocess.ts
 function createSettleGate(timer) {
   let done = false;
@@ -732,6 +717,85 @@ function attachChildSettlers(child, gate, onClose, onError, resolve) {
   });
 }
 
+// src/internal/git-exec.ts
+function formatGitResult(result, timeoutMs) {
+  if (result.kind === "timeout") {
+    return JSON.stringify({ ok: false, error: "timeout", timeoutMs });
+  }
+  if (result.kind === "error") {
+    return JSON.stringify({ ok: false, error: "git_failed", stderr: result.stderr });
+  }
+  return JSON.stringify({ ok: true, diff: result.stdout, truncated: result.truncated });
+}
+function runGitProcess(cwd, args, timeoutMs, maxStdoutBytes) {
+  return new Promise((resolve) => {
+    const child = spawn("git", args, { cwd, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let stdoutBytes = 0;
+    let truncated = false;
+    const gate = armTimeoutKill(
+      child,
+      timeoutMs,
+      () => ({ kind: "timeout" }),
+      resolve
+    );
+    child.stdout.on("data", (chunk) => {
+      if (gate.settled()) return;
+      if (stdoutBytes >= maxStdoutBytes) {
+        truncated = true;
+        return;
+      }
+      const remaining = maxStdoutBytes - stdoutBytes;
+      if (chunk.length > remaining) {
+        stdoutChunks.push(chunk.subarray(0, remaining));
+        stdoutBytes = maxStdoutBytes;
+        truncated = true;
+      } else {
+        stdoutChunks.push(chunk);
+        stdoutBytes += chunk.length;
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      stderrChunks.push(chunk);
+    });
+    attachChildSettlers(
+      child,
+      gate,
+      (code) => {
+        const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
+        const stderr = Buffer.concat(stderrChunks).toString("utf-8");
+        return code === 0 ? { kind: "ok", stdout, truncated } : { kind: "error", stderr };
+      },
+      (err) => ({ kind: "error", stderr: err.message }),
+      resolve
+    );
+  });
+}
+
+// src/path-scope.ts
+function checkPathScope(path, projectRoot) {
+  if (path === void 0 || path === "") return null;
+  try {
+    const abs = safePathJoin(projectRoot, path);
+    assertNoSymlinkEscape(abs, projectRoot);
+    return null;
+  } catch (err) {
+    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+      return JSON.stringify({ ok: false, error: "path_traversal", path });
+    }
+    throw err;
+  }
+}
+var SEGMENTOS_SENSIVEIS = /* @__PURE__ */ new Set([".env", ".git", "node_modules", ".theo"]);
+function ehProibidoEmQualquerProfundidade(path) {
+  const segs = path.replace(/\\/g, "/").split("/").filter(Boolean);
+  return segs.some((s) => {
+    if (s === ".env.example") return false;
+    return SEGMENTOS_SENSIVEIS.has(s) || /^\.env\./.test(s);
+  });
+}
+
 // src/git-diff.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_STDOUT_BYTES = 5 * 1024 * 1024;
@@ -785,58 +849,25 @@ function buildDiffArgs(cached, path) {
   if (path !== void 0 && path !== "") args.push("--", path);
   return args;
 }
-function formatGitResult(result, timeoutMs) {
-  if (result.kind === "timeout") {
-    return JSON.stringify({ ok: false, error: "timeout", timeoutMs });
-  }
-  if (result.kind === "error") {
-    return JSON.stringify({ ok: false, error: "git_failed", stderr: result.stderr });
-  }
-  return JSON.stringify({ ok: true, diff: result.stdout, truncated: result.truncated });
-}
-function runGitProcess(cwd, args, timeoutMs, maxStdoutBytes) {
-  return new Promise((resolve) => {
-    const child = spawn("git", args, { cwd, detached: true, stdio: ["ignore", "pipe", "pipe"] });
-    const stdoutChunks = [];
-    const stderrChunks = [];
-    let stdoutBytes = 0;
-    let truncated = false;
-    const gate = armTimeoutKill(
-      child,
-      timeoutMs,
-      () => ({ kind: "timeout" }),
-      resolve
-    );
-    child.stdout.on("data", (chunk) => {
-      if (gate.settled()) return;
-      if (stdoutBytes >= maxStdoutBytes) {
-        truncated = true;
-        return;
-      }
-      const remaining = maxStdoutBytes - stdoutBytes;
-      if (chunk.length > remaining) {
-        stdoutChunks.push(chunk.subarray(0, remaining));
-        stdoutBytes = maxStdoutBytes;
-        truncated = true;
-      } else {
-        stdoutChunks.push(chunk);
-        stdoutBytes += chunk.length;
+function createGitStatusTool(opts) {
+  const { projectRoot, timeoutMs = 3e4, maxStdoutBytes = 5 * 1024 * 1024 } = opts;
+  return Tool.create({
+    name: opts.name ?? "git_status",
+    description: opts.description ?? "Show the working-tree status in porcelain format: staged, unstaged and untracked paths, one per line with a two-character status code. Use before committing, or to see what changed without reading the full diff. Optional 'path' scopes the report to a subdirectory.",
+    inputSchema: z.object({
+      path: z.string().optional().describe("Optional project-relative path to scope the status report.")
+    }),
+    handler: async ({ path }) => {
+      if (!existsSync(join(projectRoot, ".git"))) {
+        return JSON.stringify({ ok: false, error: "not_a_repo" });
       }
-    });
-    child.stderr.on("data", (chunk) => {
-      stderrChunks.push(chunk);
-    });
-    attachChildSettlers(
-      child,
-      gate,
-      (code) => {
-        const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
-        const stderr = Buffer.concat(stderrChunks).toString("utf-8");
-        return code === 0 ? { kind: "ok", stdout, truncated } : { kind: "error", stderr };
-      },
-      (err) => ({ kind: "error", stderr: err.message }),
-      resolve
-    );
+      const scopeCheck = checkPathScope(path, projectRoot);
+      if (scopeCheck !== null) return scopeCheck;
+      const args = ["status", "--porcelain"];
+      if (path !== void 0 && path !== "") args.push("--", path);
+      const result = await runGitProcess(projectRoot, args, timeoutMs, maxStdoutBytes);
+      return formatGitResult(result, timeoutMs);
+    }
   });
 }
 var DEFAULT_EXCLUDES = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".theo"]);
@@ -1508,15 +1539,17 @@ var DEFAULT_MAX_ENTRIES = 500;
 function createListDirTool(opts) {
   const { projectRoot, max = DEFAULT_MAX_ENTRIES, filesystem } = opts;
   return Tool.create({
-    name: "list_dir",
-    description: `Return the direct entries of a project-relative directory. Refuses paths outside the project root or in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files). Caps at ${String(max)} entries by default; result carries truncated + totalCount.`,
+    name: opts.name ?? "list_dir",
+    description: opts.description ?? `Return the direct entries of a project-relative directory. Refuses paths outside the project root or in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files). Caps at ${String(max)} entries by default; result carries truncated + totalCount.`,
     inputSchema: z.object({
       path: z.string().min(1).describe("Project-relative directory path. Use '.' for root.")
     }),
     handler: async ({ path }, ctx) => {
       const relative3 = path === "" || path === "." ? "." : path;
-      if (relative3 !== "." && isForbiddenPath(relative3)) {
-        return JSON.stringify({ ok: false, error: "forbidden_path", path });
+      const veredito = decidirEscopo(relative3, path, opts.allowAbsolute === true);
+      if (veredito.erro !== void 0) return veredito.erro;
+      if (veredito.raizAbsoluta !== void 0) {
+        return listViaLocalFs(veredito.raizAbsoluta, ".", path, max);
       }
       if (filesystem) {
         const backend = await resolveFilesystem(filesystem, ctx ?? {});
@@ -1526,6 +1559,16 @@ function createListDirTool(opts) {
     }
   });
 }
+function decidirEscopo(relative3, original, allowAbsolute) {
+  const recusa = (error) => ({
+    erro: JSON.stringify({ ok: false, error, path: original })
+  });
+  if (relative3 !== "." && isForbiddenPath(relative3)) return recusa("forbidden_path");
+  if (!isAbsolute(relative3)) return {};
+  if (!allowAbsolute) return recusa("path_traversal");
+  if (ehProibidoEmQualquerProfundidade(relative3)) return recusa("forbidden_path");
+  return { raizAbsoluta: relative3 };
+}
 async function listViaLocalFs(projectRoot, relative3, originalPath, max) {
   const boundary = resolveDirBoundary(relative3, projectRoot, originalPath);
   if ("error" in boundary) return boundary.error;
@@ -1686,6 +1729,11 @@ function createPlanModeTool(options) {
 }
 
 // src/question.ts
+function askerDoContexto(context) {
+  if (typeof context !== "object" || context === null) return void 0;
+  const candidato = context.askUser;
+  return typeof candidato === "function" ? candidato : void 0;
+}
 function createQuestionTool(opts) {
   const timeoutMs = opts.timeoutMs ?? 3e5;
   return {
@@ -1698,12 +1746,20 @@ function createQuestionTool(opts) {
       },
       required: ["question"]
     },
-    handler: async (input) => {
+    handler: async (input, ctx) => {
+      const askUser = askerDoContexto(ctx?.context) ?? opts.askUser;
+      if (askUser === void 0) {
+        return JSON.stringify({
+          ok: false,
+          error: "no_asker",
+          message: "No asker available: pass `askUser` to createQuestionTool, or provide `context.askUser` via SendOptions.context."
+        });
+      }
       const timeout = new Promise((_, reject) => {
         setTimeout(() => reject(new Error("timeout")), timeoutMs);
       });
       try {
-        const answer = await Promise.race([opts.askUser(input.question), timeout]);
+        const answer = await Promise.race([askUser(input.question), timeout]);
         return JSON.stringify({ ok: true, answer });
       } catch (err) {
         if (err instanceof Error && err.message === "timeout") {
@@ -2041,8 +2097,8 @@ function createSearchTextTool(opts) {
   const queryKind = regex ? "a JavaScript REGULAR EXPRESSION" : "LITERAL, CASE-SENSITIVE text";
   const queryMatch = regex ? "matched as a regex" : "matched as a substring, not a regex";
   return Tool.create({
-    name: "search_text",
-    description: `Search file CONTENTS for ${queryKind} across the project tree (the query is ${queryMatch}). Use search_text when you know the content; use glob_files when you know the filename shape; use read_file when you know the exact path. Skips sensitive dirs (.env/.git/node_modules/.theo), binary files, and files over 1 MB; 'path' scopes the search to a subdirectory. Returns up to ${String(maxMatches)} matches as { file, line, preview } \u2014 cite locations to the user as file:line. Returns { ok, matches } or { ok: false, error }.`,
+    name: opts.name ?? "search_text",
+    description: opts.description ?? `Search file CONTENTS for ${queryKind} across the project tree (the query is ${queryMatch}). Use search_text when you know the content; use glob_files when you know the filename shape; use read_file when you know the exact path. Skips sensitive dirs (.env/.git/node_modules/.theo), binary files, and files over 1 MB; 'path' scopes the search to a subdirectory. Returns up to ${String(maxMatches)} matches as { file, line, preview } \u2014 cite locations to the user as file:line. Returns { ok, matches } or { ok: false, error }.`,
     inputSchema: z.object({
       query: regex ? z.string().min(1).describe("A JavaScript regular expression, e.g. 'function\\\\s+main'.") : z.string().min(1).describe("Literal text to search for. Case-sensitive."),
       path: z.string().optional().describe(
@@ -2250,8 +2306,8 @@ function createShellTool(opts) {
     sandbox
   } = opts;
   return Tool.create({
-    name: "shell_exec",
-    description: "Execute a shell command in the project directory. Use this for terminal operations \u2014 running tests, git, package managers, build tools. Do NOT use it for file operations (reading, writing, editing, finding files): prefer the specialized read_file/write_file/edit_file/glob_files/search_text tools, which are path-checked and safer. Only commit, push, or change git state when the user explicitly asks. timeout_ms defaults to 30000 (max 300000); stdout/stderr are capped (~5 MB). Returns { ok, stdout, stderr, exit_code } or { ok: false, error }.",
+    name: opts.name ?? "shell_exec",
+    description: opts.description ?? "Execute a shell command in the project directory. Use this for terminal operations \u2014 running tests, git, package managers, build tools. Do NOT use it for file operations (reading, writing, editing, finding files): prefer the specialized read_file/write_file/edit_file/glob_files/search_text tools, which are path-checked and safer. Only commit, push, or change git state when the user explicitly asks. timeout_ms defaults to 30000 (max 300000); stdout/stderr are capped (~5 MB). Returns { ok, stdout, stderr, exit_code } or { ok: false, error }.",
     inputSchema: z.object({
       command: z.string().min(1).describe("Shell command to execute."),
       timeout_ms: z.number().int().positive().optional().describe("Timeout in milliseconds (default 30000, max 300000).")
@@ -2817,6 +2873,6 @@ async function isBinaryFile(absolutePath) {
   }
 }
 
-export { CatastrophicCommandError, ContextMatchError, DEFAULT_TOOL_GUIDANCE, ReadTracker, ReasoningTools, RedirectBlockedError, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, ContextMatchError, DEFAULT_TOOL_GUIDANCE, ReadTracker, ReasoningTools, RedirectBlockedError, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map