@oh-my-pi-zen/pi-coding-agent 16.3.6-zen.1

package/dist/types/tools/output-meta.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Structured metadata for tool outputs.
+ *
+ * Tools populate details.meta using the fluent OutputMetaBuilder.
+ * The tool wrapper automatically formats and appends notices at message boundary.
+ */
+import type { AgentTool } from "@oh-my-pi-zen/pi-agent-core";
+import { type Settings } from "../config/settings";
+import type { Theme } from "../modes/theme/theme";
+import { type OutputSummary, type TruncationResult } from "../session/streaming-output";
+/**
+ * Truncation metadata for the output notice.
+ */
+export interface TruncationMeta {
+    direction: "head" | "tail" | "middle";
+    truncatedBy: "lines" | "bytes" | "middle";
+    totalLines: number;
+    totalBytes: number;
+    outputLines: number;
+    outputBytes: number;
+    maxBytes?: number;
+    /** Line range shown (1-indexed, inclusive). Omitted for middle elision. */
+    shownRange?: {
+        start: number;
+        end: number;
+    };
+    /** Head/tail line ranges shown when direction === "middle". */
+    headRange?: {
+        start: number;
+        end: number;
+    };
+    tailRange?: {
+        start: number;
+        end: number;
+    };
+    /** Bytes elided from the middle. */
+    elidedBytes?: number;
+    /** Lines elided from the middle. */
+    elidedLines?: number;
+    /** Artifact ID if full output was saved */
+    artifactId?: string;
+    /** Next offset for pagination (head truncation only) */
+    nextOffset?: number;
+}
+/**
+ * Source resolution info for the output.
+ */
+export type SourceMeta = {
+    type: "path";
+    value: string;
+} | {
+    type: "url";
+    value: string;
+} | {
+    type: "internal";
+    value: string;
+};
+/**
+ * LSP diagnostic info (for edit/write tools).
+ */
+export interface DiagnosticMeta {
+    summary: string;
+    messages: string[];
+}
+/**
+ * Limit-specific notices.
+ */
+export interface LimitsMeta {
+    matchLimit?: {
+        reached: number;
+        suggestion: number;
+    };
+    resultLimit?: {
+        reached: number;
+        suggestion: number;
+    };
+    headLimit?: {
+        reached: number;
+        suggestion: number;
+    };
+    columnTruncated?: {
+        maxColumn: number;
+    };
+}
+/**
+ * Structured metadata for tool outputs.
+ */
+export interface OutputMeta {
+    truncation?: TruncationMeta;
+    source?: SourceMeta;
+    diagnostics?: DiagnosticMeta;
+    limits?: LimitsMeta;
+}
+export interface TruncationOptions {
+    direction: "head" | "tail" | "middle";
+    startLine?: number;
+    totalFileLines?: number;
+    artifactId?: string;
+}
+export interface TruncationSummaryOptions {
+    direction: "head" | "tail" | "middle";
+    startLine?: number;
+    totalFileLines?: number;
+}
+export interface TruncationTextOptions {
+    direction: "head" | "tail" | "middle";
+    totalLines?: number;
+    totalBytes?: number;
+    maxBytes?: number;
+}
+/**
+ * Fluent builder for OutputMeta.
+ *
+ * @example
+ * ```ts
+ * details.meta = outputMeta()
+ *   .truncation(truncation, { direction: "head" })
+ *   .matchLimit(limitReached ? effectiveLimit : 0)
+ *   .columnTruncated(linesTruncated ? DEFAULT_MAX_COLUMN : 0)
+ *   .get();
+ * ```
+ */
+export declare class OutputMetaBuilder {
+    #private;
+    /** Add truncation info from TruncationResult. No-op if not truncated. */
+    truncation(result: TruncationResult, options: TruncationOptions): this;
+    /** Add truncation info from OutputSummary. No-op if not truncated. */
+    truncationFromSummary(summary: OutputSummary, options: TruncationSummaryOptions): this;
+    /** Add truncation info from truncated output text. No-op if truncation not detected. */
+    truncationFromText(text: string, options: TruncationTextOptions): this;
+    /** Add match limit notice. No-op if reached <= 0. */
+    matchLimit(reached: number, suggestion?: number): this;
+    /** Add limit notices in one call. */
+    limits(limits: {
+        matchLimit?: number;
+        resultLimit?: number;
+        headLimit?: number;
+        columnMax?: number;
+    }): this;
+    /** Add result limit notice. No-op if reached <= 0. */
+    resultLimit(reached: number, suggestion?: number): this;
+    /** Add limit notice for head truncation. No-op if reached <= 0. */
+    headLimit(reached: number, suggestion?: number): this;
+    /** Add column truncation notice. No-op if maxColumn <= 0. */
+    columnTruncated(maxColumn: number): this;
+    /** Add source path info. */
+    sourcePath(value: string): this;
+    /** Add source URL info. */
+    sourceUrl(value: string): this;
+    /** Add internal URL source info (skill://, agent://, artifact://). */
+    sourceInternal(value: string): this;
+    /** Add LSP diagnostics. No-op if no messages. */
+    diagnostics(summary: string, messages: string[]): this;
+    /** Get the built OutputMeta, or undefined if empty. */
+    get(): OutputMeta | undefined;
+}
+/** Create a new OutputMetaBuilder. */
+export declare function outputMeta(): OutputMetaBuilder;
+export declare function formatFullOutputReference(artifactId: string): string;
+/** Remove the trailing bash raw-output artifact footer while preserving its artifact id. */
+export declare function stripRawOutputArtifactNotice(text: string): {
+    text: string;
+    artifactId?: string;
+};
+/** Remove a trailing generated output notice when metadata is unavailable. */
+export declare function stripGeneratedOutputNotice(text: string): string;
+export declare function formatTruncationMetaNotice(truncation: TruncationMeta): string;
+/**
+ * Format styled artifact reference with warning color and brackets.
+ * For TUI rendering of truncation warnings.
+ */
+export declare function formatStyledArtifactReference(artifactId: string, theme: Theme): string;
+/**
+ * Format notices from OutputMeta for LLM consumption.
+ * Returns empty string if no notices needed.
+ */
+export declare function formatOutputNotice(meta: OutputMeta | undefined): string;
+/**
+ * Format a styled truncation warning message.
+ * Returns null if no truncation metadata present.
+ */
+export declare function formatStyledTruncationWarning(meta: OutputMeta | undefined, theme: Theme): string | null;
+/**
+ * Strip the trailing notice that {@link appendOutputNotice} bakes into the
+ * LLM-facing content body. Renderers should call this before printing
+ * `result.content` text in the TUI, because they emit a styled warning line of
+ * their own; without this, users see the same `[Showing lines …]` string twice
+ * (once verbatim from the body, once as the styled `⟨…⟩` warning).
+ *
+ * Safe to call eagerly: returns the input unchanged when no notice is present
+ * (e.g. during streaming, before {@link wrappedExecute} runs).
+ */
+export declare function stripOutputNotice(text: string, meta: OutputMeta | undefined): string;
+/**
+ * Resolve the OutputSink `headBytes` budget from session settings.
+ * Exposed so streaming executors (bash/python/ssh/eval) can opt into
+ * middle elision with the same per-user configuration.
+ */
+export declare function resolveOutputSinkHeadBytes(s: Settings | undefined): number;
+/**
+ * Resolve the per-line column cap from session settings. Shared by streaming
+ * executors (bash/python/ssh/eval via OutputSink) and the `read` tool's
+ * line-buffer post-processing, so one setting controls both surfaces.
+ */
+export declare function resolveOutputMaxColumns(s: Settings | undefined): number;
+/**
+ * Wrap a tool to:
+ * 1. Automatically append output notices based on details.meta
+ * 2. Handle ToolError rendering
+ */
+export declare function wrapToolWithMetaNotice<T extends AgentTool<any, any, any>>(tool: T): T;

package/dist/types/tools/output-schema-validator.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared output-schema validation for subagent yield + executor finalization.
+ *
+ * Both the in-process `yield` tool (subagent side) and the executor's post-mortem
+ * finalize path (parent side) need to validate yield payloads against the agent's
+ * declared output schema. This module is the single source of truth for that
+ * pipeline — keeping the two callsites in lockstep so a schema accepted in-tool
+ * cannot be rejected post-mortem (or vice versa).
+ */
+import { type JsonSchemaValidationIssue, type JsonSchemaValidationResult } from "@oh-my-pi-zen/pi-ai/utils/schema";
+/** A validator bound to a specific output schema. */
+export interface OutputValidator {
+    /** Run JSON Schema validation; returns the raw `success`/`issues` shape so callers may inspect every failure. */
+    validate(value: unknown): JsonSchemaValidationResult;
+    /** Top-level required property names. Empty if the schema has no `required` array at root. */
+    readonly requiredFields: readonly string[];
+    /**
+     * Per-label validators for incremental yields (`type: ["<label>"]`). Each entry validates the
+     * `data` payload of a single section against the matching top-level property's sub-schema —
+     * array-typed properties (e.g. `findings`) use the items schema since each yield contributes
+     * one element, while scalar properties use the property schema directly.
+     */
+    readonly validateSection: ReadonlyMap<string, (value: unknown) => JsonSchemaValidationResult>;
+    /** Whether top-level schema closure makes unknown incremental yield labels invalid. */
+    readonly rejectUnknownSections: boolean;
+    /** Finite top-level section labels declared directly by the schema. Pattern-backed labels are accepted via `isKnownSection`. */
+    readonly knownSectionLabels: readonly string[];
+    /** Whether an incremental yield label is accepted by the top-level schema declaration. */
+    isKnownSection(label: string): boolean;
+}
+export interface BuildOutputValidatorResult {
+    /** Present when the schema produced a usable validator (i.e. constraining schemas). Absent for missing/unconstrained schemas. */
+    validator?: OutputValidator;
+    /** Raw JSON Schema produced by `jtdToJsonSchema`. Available alongside the validator so callers can derive related artifacts (strict-mode probe, dereference, hint text). */
+    jsonSchema?: Record<string, unknown>;
+    /**
+     * Normalized schema (post-`normalizeSchema`). Surfaced so callers can distinguish
+     * "no schema provided" (`undefined`) from "intentionally unconstrained" (`true`)
+     * when both produce no validator.
+     */
+    normalized?: unknown;
+    /** Set when the schema cannot be used. Callers should treat this as a "no validation" case (loose acceptance) and surface the message in diagnostics. */
+    error?: string;
+}
+/**
+ * Build the canonical validator for a JTD-or-JSON-Schema output declaration.
+ *
+ * Returns:
+ * - `{ validator, jsonSchema, normalized }` for constraining schemas — both callers use this path.
+ * - `{ normalized: true }` for an intentionally unconstrained schema (the JSON Schema literal `true`).
+ *   No validator, but distinguishable from "no schema provided".
+ * - `{}` for an absent schema (`undefined`).
+ * - `{ error, normalized? }` when the schema cannot be honored (invalid syntax, `false`, malformed JTD).
+ */
+export declare function buildOutputValidator(schema: unknown): BuildOutputValidatorResult;
+/** Produce the executor's headline+missing-required summary from a failed validation. */
+export declare function summarizeValidationFailure(result: JsonSchemaValidationResult, value: unknown, requiredFields: readonly string[]): {
+    message: string;
+    missingRequired: string[];
+};
+export declare function extractRequiredFields(jsonSchema: unknown): string[];
+export declare function computeMissingRequired(required: readonly string[], value: unknown): string[];
+/**
+ * Format a single validation issue as `path.with.dots: message`.
+ *
+ * Used by the executor's post-mortem `schema_violation` headline — one line, dot-separated path,
+ * since the executor's error format already lists missing-required fields separately.
+ */
+export declare function formatValidationIssueHeadline(issue: JsonSchemaValidationIssue | undefined): string | undefined;
+/**
+ * Format every validation issue as `path/with/slashes: message; ...`.
+ *
+ * Used by the yield tool's model-facing retry feedback — the model gets every problem at once so it
+ * can fix the entire output in one retry instead of iterating issue-by-issue. The slash separator
+ * mirrors JSON Pointer convention and disambiguates against fields whose names contain dots.
+ */
+export declare function formatAllValidationIssues(issues: ReadonlyArray<JsonSchemaValidationIssue> | undefined): string;

package/dist/types/tools/path-utils.d.ts

@@ -0,0 +1,267 @@
+import type { Skill } from "../extensibility/skills";
+import { type LocalProtocolOptions } from "../internal-urls";
+export declare function expandTilde(filePath: string, home?: string): string;
+export declare function expandPath(filePath: string): string;
+export declare function normalizeWindowsDriveAliasPath(filePath: string, platform?: NodeJS.Platform): string;
+/**
+ * Inclusive line range describing one selector segment (e.g. `50-100`,
+ * `301-`, or `50+10`). `endLine` is `undefined` for open-ended ranges.
+ */
+export interface LineRange {
+    startLine: number;
+    endLine: number | undefined;
+}
+/** Parse a single `N`, `N-M`, `N-`, `N+K`, or `..`-aliased (`N..M`, `N..`) chunk. Throws via {@link ToolError} on invalid bounds. */
+export declare function parseLineRangeChunk(sel: string): LineRange | null;
+/**
+ * Parse a comma-separated list of line ranges (e.g. `5-16,960-973`). Returns
+ * the ranges in ascending order with overlapping/adjacent ranges merged so
+ * downstream consumers can stream the file in a single forward pass per range.
+ */
+export declare function parseLineRanges(sel: string): [LineRange, ...LineRange[]] | null;
+/**
+ * Extract the line-range component from a read-tool selector that may also
+ * carry a verbatim/index display mode (`raw`, `conflicts`) — alone or compounded
+ * with a range (`raw:50-100`, `50-100:raw`). Returns the parsed ranges when the
+ * selector names any, otherwise `undefined` (pure `raw`/`conflicts`/none).
+ *
+ * Used by content search, which honors line ranges as a match filter but has no
+ * use for verbatim/conflict display modes — so those selectors are accepted and
+ * treated as an unfiltered, whole-resource search rather than rejected.
+ */
+export declare function selectorLineRanges(sel: string | undefined): [LineRange, ...LineRange[]] | undefined;
+/** Return `true` when `lineNumber` (1-indexed) falls in any of the supplied ranges. */
+export declare function isLineInRanges(lineNumber: number, ranges: readonly LineRange[]): boolean;
+export declare function splitPathAndSel(rawPath: string): {
+    path: string;
+    sel?: string;
+};
+/**
+ * Variant of {@link splitPathAndSel} for internal URLs (`scheme://...`).
+ *
+ * The filesystem-path splitter is intentionally conservative: it refuses to
+ * peel a trailing `:<chunk>` unless that chunk matches the strict selector
+ * grammar. That rule is right for filesystem paths (a file named `a:1-50` is
+ * legal) but wrong for internal URLs, where any trailing `:<chunk>` after the
+ * scheme is unambiguously a read-tool selector — even if malformed (e.g.
+ * `artifact://3:raw:-100`).
+ *
+ * This function iteratively peels selector-shaped chunks (well-formed plus
+ * common malformed shapes like `:-N`) so the rest of the read tool can pass a
+ * clean URL to the protocol handler and surface selector errors via parseSel
+ * instead of as misleading "host invalid" errors from the handler. Schemes
+ * whose resource URIs may legitimately contain colons (`mcp://`) are skipped.
+ *
+ * Falls back to the input unchanged when nothing matches.
+ */
+export declare function splitInternalUrlSel(rawPath: string): {
+    path: string;
+    sel?: string;
+};
+/**
+ * Peel a read-tool selector off an internal-URL write target so `write` resolves
+ * the same file `read` does (e.g. `ssh://h/f:raw` -> `ssh://h/f`). Only the
+ * whole-file display modes `raw`/`conflicts` are accepted (they do not change
+ * which bytes are written); any other selector-shaped tail `splitInternalUrlSel`
+ * peels — a line range, a compound like `raw:1-20`, or a malformed `:-N` — throws,
+ * because `write` addresses a whole file, not a partial range, and silently
+ * stripping it would write to a path the caller never named. Non-URL paths and
+ * URLs without a selector pass through unchanged.
+ */
+export declare function peelWriteUrlSelector(rawPath: string): string;
+export declare function normalizeLocalScheme(filePath: string): string;
+export declare function isInternalUrlPath(filePath: string): boolean;
+/**
+ * True when a tool path argument references the `ssh://` scheme anywhere.
+ *
+ * Substring (not anchored) on purpose: it feeds the read/search/write approval
+ * tier, which runs synchronously on the raw args. `search` only flattens a
+ * delimited `paths: "a,ssh://h/x"` into separate entries *after* approval, so an
+ * anchored check would let an embedded `ssh://` slip through at the read tier.
+ * Matching the literal `ssh://` substring also tracks exactly what routes to the
+ * SSH handler; over-matching only over-prompts (fail-closed).
+ */
+export declare function pathTargetsSsh(path: string): boolean;
+/**
+ * True when a path is specifically an `ssh://` URL (anchored scheme match).
+ * Unlike {@link pathTargetsSsh} (substring, for the pre-expansion approval
+ * scan), this is the exact per-entry check used to reject `ssh://` *before* a
+ * side-effecting `InternalUrlRouter.resolve` in tools that need a local file.
+ */
+export declare function isSshUrl(path: string): boolean;
+/**
+ * True when the read tool's URL parser (`parseReadUrlTarget` in fetch.ts) would
+ * recognize this path as a readable external URL: a strict `http(s)://`, a
+ * collapsed `http(s):/host` (Node path normalization folds `//` → `/`), or a
+ * scheme-less `www.` spelling. Keep in sync with `parseReadUrlTarget`.
+ */
+export declare function isReadableUrlPath(value: string): boolean;
+/**
+ * Resolve a path relative to the given cwd.
+ * Handles ~ expansion and absolute paths.
+ *
+ * A bare root slash is treated as a workspace-root alias for tool inputs. Users
+ * often pass `/` to mean “search from here”, and letting tools escape to the
+ * filesystem root is almost never what they intended.
+ */
+export declare function resolveToCwd(filePath: string, cwd: string): string;
+export declare function formatPathRelativeToCwd(filePath: string, cwd: string, options?: {
+    trailingSlash?: boolean;
+}): string;
+/**
+ * Strip matching surrounding double quotes from a path string.
+ * Common when users paste quoted paths from Windows Explorer or shell copy-paste.
+ * Only double quotes — single quotes are valid POSIX filename characters.
+ * Tradeoff: a POSIX path literally starting AND ending with " would also be unquoted.
+ * Accepted because such names are virtually nonexistent in practice.
+ */
+export declare function stripOuterDoubleQuotes(input: string): string;
+export declare function normalizePathLikeInput(input: string): string;
+/**
+ * Normalize a path argument that may arrive as a single string, a JSON-encoded
+ * string array (`'["a.ts"]'`), or an actual array into a flat `string[]`.
+ * Delimited single strings (`"a.ts b.ts"`) are left for
+ * {@link expandDelimitedPathEntries} to split.
+ */
+export declare function toPathList(input: string | string[] | undefined): string[];
+export declare function hasGlobPathChars(filePath: string): boolean;
+type PathEntrySplitter = (item: string) => {
+    basePath: string;
+};
+/**
+ * Split one path-like entry whose multiple targets were flattened into one
+ * string. Existing paths are kept intact, so real filenames containing spaces,
+ * commas, or semicolons win over delimiter recovery.
+ */
+export declare function splitDelimitedPathEntry(entry: string, cwd: string, options?: {
+    splitter?: PathEntrySplitter;
+}): Promise<string[] | null>;
+/** Expand delimited entries in-place while preserving unsplit entries. */
+export declare function expandDelimitedPathEntries(entries: readonly string[], cwd: string, options?: {
+    splitter?: PathEntrySplitter;
+}): Promise<string[]>;
+export interface ParsedSearchPath {
+    basePath: string;
+    glob?: string;
+}
+export interface ParsedFindPattern {
+    basePath: string;
+    globPattern: string;
+    hasGlob: boolean;
+}
+export interface ResolvedSearchTarget {
+    basePath: string;
+    glob?: string;
+}
+export interface ResolvedMultiSearchPath {
+    basePath: string;
+    glob?: string;
+    scopePath: string;
+    exactFilePaths?: string[];
+    targets?: ResolvedSearchTarget[];
+}
+export interface ResolvedFindTarget {
+    basePath: string;
+    globPattern: string;
+    hasGlob: boolean;
+}
+export interface ResolvedMultiFindPattern {
+    targets: ResolvedFindTarget[];
+    scopePath: string;
+}
+export declare function parseSearchPath(filePath: string): ParsedSearchPath;
+/**
+ * Async sibling of {@link parseSearchPath} that prefers literal interpretation
+ * when a path containing glob metacharacters resolves to an existing entry on
+ * disk. Disambiguates Next.js/SvelteKit routes like `apps/[id]/page.tsx` —
+ * without this, `[id]` is parsed as a glob character class and silently
+ * matches nothing.
+ */
+export declare function parseSearchPathPreferringLiteral(filePath: string, cwd: string): Promise<ParsedSearchPath>;
+export declare function parseFindPattern(pattern: string): ParsedFindPattern;
+export declare function combineSearchGlobs(prefixGlob?: string, suffixGlob?: string): string | undefined;
+export declare function resolveExplicitSearchPaths(pathItems: string[], cwd: string, suffixGlob?: string, fanOutFileItems?: boolean): Promise<ResolvedMultiSearchPath | undefined>;
+export declare function resolveExplicitFindPatterns(patternItems: string[], cwd: string): Promise<ResolvedMultiFindPattern | undefined>;
+/**
+ * Result of partitioning a list of user-supplied paths/globs into entries whose
+ * base directory currently exists on disk versus those that do not.
+ *
+ * Used by multi-path tools (search, find, ast_grep, ast_edit) to tolerate one
+ * or more missing entries in a multi-path call: the surviving entries should
+ * still be searched, with the missing entries surfaced as a non-fatal warning.
+ */
+export interface PartitionedPaths {
+    /** Raw input strings whose resolved base path exists. */
+    valid: string[];
+    /** Raw input strings whose resolved base path is missing (ENOENT). */
+    missing: string[];
+}
+/**
+ * Stat each input's base path concurrently; return entries split by existence.
+ *
+ * `splitter` is expected to be {@link parseFindPattern} or
+ * {@link parseSearchPath}: both return a `basePath` field that this helper
+ * resolves against `cwd` and stats. ENOENT is the only swallowed error — every
+ * other stat failure (permission, IO, etc.) propagates so callers do not silently
+ * skip paths that exist but are unreadable.
+ *
+ * Order of `valid` and `missing` follows the input order, so callers can rely
+ * on `valid[0]` matching the first surviving user-supplied entry.
+ */
+export declare function partitionExistingPaths(items: string[], cwd: string, splitter: (item: string) => {
+    basePath: string;
+}): Promise<PartitionedPaths>;
+export declare function resolveReadPath(filePath: string, cwd: string): string;
+/** Local file materialized from a readable external URL for shared tool-scope resolution. */
+export interface ResolvedExternalSearchUrl {
+    /** Absolute or cwd-relative file path to search. */
+    sourcePath: string;
+    /** True when the materialized file must not mint editable anchors. */
+    immutable?: boolean;
+}
+export interface ToolScopeOptions {
+    rawPaths: string[];
+    cwd: string;
+    /** Verb used in the "Cannot {action} internal URL without a backing file: …" message. */
+    internalUrlAction: string;
+    /** Collect absolute paths flagged immutable by their internal-URL handler. */
+    trackImmutableSources?: boolean;
+    /** Honor `exactFilePaths` from {@link resolveExplicitSearchPaths} (search-only). */
+    surfaceExactFilePaths?: boolean;
+    /** Fan plain-file entries out into per-target scans instead of folding them
+     * into a directory walk's glob union (search-only: the caller must dedupe
+     * matches from overlapping targets). */
+    fanOutFileTargets?: boolean;
+    /** Extra hint appended to "Path not found" when stat fails and the user supplied multiple paths. */
+    multipathStatHint?: string;
+    /** Calling session's settings — forwarded to the internal-URL router so caller-aware handlers (issue://, pr://) honor it. */
+    settings?: unknown;
+    /** Caller's abort signal — forwarded to the internal-URL router. */
+    signal?: AbortSignal;
+    /** Calling session's `local://` root mapping — pins resolutions to the calling session. */
+    localProtocolOptions?: LocalProtocolOptions;
+    /** Calling session's loaded skills — lets skill:// resolve without process-global state. */
+    skills?: readonly Skill[];
+    /** Materialize readable external URLs to local text files before scope derivation. */
+    resolveExternalUrl?: (rawPath: string) => Promise<ResolvedExternalSearchUrl | undefined>;
+}
+export interface ToolScopeResolution {
+    searchPath: string;
+    scopePath: string;
+    globFilter: string | undefined;
+    isDirectory: boolean;
+    multiTargets?: ResolvedSearchTarget[];
+    exactFilePaths?: string[];
+    missingPaths: string[];
+    immutableSourcePaths: Set<string>;
+}
+/**
+ * Shared path-input pipeline for `search`, `ast_grep`, and `ast_edit`:
+ *  1. normalize + reject empty paths,
+ *  2. resolve internal URLs through {@link InternalUrlRouter} to backing files,
+ *  3. partition existing vs missing when multiple paths are supplied,
+ *  4. derive a single search base path / glob, or a multi-target list,
+ *  5. stat the resolved base path so callers can branch on directory vs file scope.
+ */
+export declare function resolveToolSearchScope(opts: ToolScopeOptions): Promise<ToolScopeResolution>;
+export {};

package/dist/types/tools/plan-mode-guard.d.ts

@@ -0,0 +1,33 @@
+import type { ToolSession } from ".";
+/** Strip the hashline `[path#TAG]` wrapper from a write/edit target so the inner
+ *  filesystem path drives both authorization and resolution. Only unwraps inputs
+ *  that match the strict hashline header shape (`[path]` or `[path#XXXX]` with a
+ *  4-hex tag); anything else returns the original string so the downstream
+ *  resolver surfaces the real error. Exported for callers (e.g. `write`) that
+ *  make scheme/bridge-routing decisions before {@link resolvePlanPath} runs. */
+export declare function unwrapHashlineHeaderPath(targetPath: string): string;
+/** True when `targetPath` resolves into the session-local artifact sandbox.
+ *  Routes through {@link resolvePlanPath} so the guard and the eventual write
+ *  always agree on the absolute target (including bracketed hashline headers,
+ *  `local://` URLs, and bare absolute paths). Files inside the sandbox are not
+ *  part of the working tree, so plan mode treats them as freely writable
+ *  scratch/plan space — and tag-based path recovery may rebind onto them. */
+export declare function targetsLocalSandbox(session: ToolSession, targetPath: string): boolean;
+/**
+ * Resolve a write/edit target to its absolute filesystem path, honoring the
+ * `local://` and `vault://` schemes. Plain paths resolve against the session cwd.
+ * Bracketed hashline headers (`[path#TAG]`) are unwrapped first so the inner
+ * filesystem path drives resolution — keeping the plan-mode guard and the
+ * eventual write in lockstep.
+ */
+export declare function resolvePlanPath(session: ToolSession, targetPath: string): string;
+/**
+ * Plan mode keeps the working tree read-only while letting the agent draft its
+ * plan. Writes and edits to the `local://` artifact sandbox are allowed (that is
+ * where the plan and any scratch notes live); anything that would touch the
+ * working tree — or rename/delete a file — is rejected.
+ */
+export declare function enforcePlanModeWrite(session: ToolSession, targetPath: string, options?: {
+    move?: string;
+    op?: "create" | "update" | "delete";
+}): void;

package/dist/types/tools/read.d.ts

@@ -0,0 +1,87 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback, ToolTier } from "@oh-my-pi-zen/pi-agent-core";
+import type { Component } from "@oh-my-pi-zen/pi-tui";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { type Theme } from "../modes/theme/theme";
+import type { ToolSession } from "../sdk";
+import { type TruncationResult } from "../session/streaming-output";
+import { type OutputMeta } from "./output-meta";
+declare const readSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    path: string;
+}, {}>;
+export type ReadToolInput = typeof readSchema.infer;
+export interface ReadToolDetails {
+    kind?: "file" | "url";
+    truncation?: TruncationResult;
+    isDirectory?: boolean;
+    resolvedPath?: string;
+    suffixResolution?: {
+        from: string;
+        to: string;
+    };
+    url?: string;
+    finalUrl?: string;
+    contentType?: string;
+    method?: string;
+    notes?: string[];
+    meta?: OutputMeta;
+    /** Raw text + start line for user-visible TUI rendering, set when content is text-like.
+     * Mirrors the same lines the model receives but without hashline/line-number prefixes,
+     * so the TUI can render the file content with its own gutter without re-parsing the formatted text. */
+    displayContent?: {
+        text: string;
+        startLine: number;
+        lineNumbers?: Array<number | null>;
+    };
+    summary?: {
+        lines: number;
+        elidedSpans: number;
+        elidedLines: number;
+    };
+    /** Number of unresolved git conflicts surfaced by this read (TUI uses for inline `⚠ N` badge). */
+    conflictCount?: number;
+    /** Paths recovered from a delimited read argument; used only by the TUI to render one call as multiple read rows. */
+    displayReadTargets?: string[];
+}
+type ReadParams = ReadToolInput;
+/**
+ * Read tool implementation.
+ *
+ * Reads files with support for images, converted documents (via markit), and text.
+ * Directories return a formatted listing with modification times.
+ */
+export declare class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
+    #private;
+    private readonly session;
+    readonly name = "read";
+    readonly approval: (args: unknown) => ToolTier;
+    readonly label = "Read";
+    readonly loadMode = "essential";
+    readonly description: string;
+    readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
+        path: string;
+    }, {}>;
+    readonly strict = true;
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: ReadParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<ReadToolDetails>, _toolContext?: AgentToolContext): Promise<AgentToolResult<ReadToolDetails>>;
+}
+interface ReadRenderArgs {
+    path?: string;
+    file_path?: string;
+    sel?: string;
+    offset?: number;
+    limit?: number;
+    raw?: boolean;
+}
+export declare const readToolRenderer: {
+    renderCall(args: ReadRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: ReadToolDetails;
+        isError?: boolean;
+    }, options: RenderResultOptions, uiTheme: Theme, args?: ReadRenderArgs): Component;
+    mergeCallAndResult: boolean;
+};
+export {};