dsh-hashline-edit 0.1.0 → 0.2.0

package/lib/types/dsh/contracts.d.ts

@@ -2,7 +2,7 @@
  * Shared host contracts for the dsh adapter.
  *
  * The `dsh/` tree is the DeepSeek Harness host layer over the host-agnostic
- * hashline core in `src/`. Every lane (host, read, edit, platform) compiles
+ * hashline core in `src/`. Every lane (host, read, apply-patch, platform) compiles
  * against this file; renaming or reshaping an export here is a cross-lane
  * breaking change.
  *
@@ -52,10 +52,11 @@ export interface FileStat {
  *
  * Paths crossing this interface are absolute and already validated by
  * `dsh/fs.ts`: implementations may assume no null byte and no relative path.
- * Reads return raw bytes so the platform lane owns BOM sniffing and encoding
- * governance without a second decode step; callers that want text decode the
- * bytes through `src/file-content/loader.ts`'s `decodeNormText` (which is
- * node:fs-bound today and therefore takes a path, not this interface).
+ * Reads return raw bytes so a byte-level refusal stays possible without a second
+ * decode step; callers that want text decode the bytes through
+ * `src/file-content/detection.ts`'s `decodeUtf8Strict` (the host's one admission:
+ * strict UTF-8, BOM stripped) or, for the anchor pipeline, through `decodeNormText`
+ * (which is node:fs-bound today and therefore takes a path, not this interface).
  */
 export interface FileIO {
     /** Read a whole regular file as raw bytes. */
@@ -66,6 +67,15 @@ export interface FileIO {
     stat(path: string, signal?: AbortSignal): Promise<FileStat | undefined>;
     /** Direct child names of a directory, sorted lexicographically. */
     readdir(path: string, signal?: AbortSignal): Promise<string[]>;
+    /**
+     * Delete one regular file. A lifecycle delete targets a file; a directory at the same path is
+     * a caller bug that must surface (never a recursive removal).
+     */
+    remove?(path: string, signal?: AbortSignal): Promise<void>;
+    /** Rename one regular file. The destination must not exist and its parent is created first. */
+    rename?(from: string, to: string, signal?: AbortSignal): Promise<void>;
+    /** Create one directory and missing parents. */
+    mkdir?(path: string, signal?: AbortSignal): Promise<void>;
 }
 /** The two sandbox-escalation arguments a mutating tool may carry. */
 export interface SandboxArgs {
@@ -118,6 +128,54 @@ export interface SandboxController {
      */
     mapError(error: unknown, decision: SandboxDecision): unknown;
 }
+/**
+ * The host observation channel one agent install publishes through.
+ *
+ * The host's observation policy fills its per-session state exclusively from
+ * `fs/observed`, and that state is what lets a built-in `write` replace an
+ * existing file. Shadowed `read`/`apply_patch` calls never touch the provider's own
+ * write path, so without this channel a file this plugin served stays
+ * "unobserved" and the built-in overwrite is refused forever.
+ *
+ * A mounted `ctx.fs` supplies the channel. Without one (`dsh/fs.ts`'s local
+ * `node:fs` fallback, and every test double that drives the tools directly)
+ * there is no channel at all: `FsTarget` and `FsVersion` are provider-owned
+ * values a consumer must never manufacture, so a local-only composition
+ * publishes nothing instead of publishing a fabricated identity.
+ */
+export interface FsObservationChannel {
+    /**
+     * Publish what a successful call observed or produced for one file.
+     *
+     * Reuses the version an in-flight `stat` already reported unless
+     * {@link FsObserveOptions.fresh} is set, which re-stats; a write must pass
+     * `fresh` because the pre-write version is stale by then. A target the
+     * provider confirms missing is published as `{ kind: "absent" }`.
+     *
+     * Never throws and never fails the tool call: a provider round-trip or
+     * listener failure is reported through the channel's diagnostic sink.
+     * At most one observation per call and file is published.
+     */
+    publish(absolutePath: string, exec?: object, options?: FsObserveOptions): Promise<void>;
+    /**
+     * Dispatch `fs/write-intent` for a file this plugin is about to write, so
+     * host listeners still see the change this plugin is making.
+     *
+     * The returned intent is deliberately not enforced: this plugin's mutations
+     * go straight to `node:fs`, so the provider's guarded-write semantics (which
+     * is where an intent is applied) do not run for them. A listener failure is
+     * reported and the write proceeds — this dispatch is bookkeeping, not a
+     * guard this plugin owns.
+     */
+    announceWrite(absolutePath: string, exec?: object, signal?: AbortSignal): Promise<void>;
+}
+/** Knobs for one {@link FsObservationChannel.publish} call. */
+export interface FsObserveOptions {
+    /** Re-stat through the provider instead of reusing the version this call already saw. */
+    readonly fresh?: boolean | undefined;
+    /** Caller cancellation, forwarded into the provider round-trip. */
+    readonly signal?: AbortSignal | undefined;
+}
 /** Host services one tool factory receives at agent-install time. */
 export interface ToolDependencies {
     /** Local filesystem seam; M1 is `dsh/fs.ts`'s node:fs implementation. */
@@ -126,6 +184,11 @@ export interface ToolDependencies {
     readonly sandbox: SandboxController;
     /** Read-only IO bridge; absent keeps the legacy node:fs read path. */
     readonly coreIo?: CoreReadIo;
+    /**
+     * Host observation channel; absent without a mounted `ctx.fs`, where a
+     * provider-owned target and version cannot be manufactured.
+     */
+    readonly observations?: FsObservationChannel;
     /** Optional telemetry recorder; undefined keeps the tool path emission-free. */
     readonly metrics?: ToolMetrics;
 }
@@ -136,7 +199,7 @@ export interface ToolDependencies {
  * factories at registration time. The fixed names are part of the lane
  * contract:
  * - `dsh/tools/read.ts` → `buildReadTool` (tool name `read`)
- * - `dsh/tools/edit.ts` → `buildEditTool` (tool name `edit`)
+ * - `dsh/tools/apply-patch.ts` → `buildApplyPatchTool` (tool name `apply_patch`)
  * - `dsh/tools/undo.ts` → `buildUndoTool` (tool name `undo_last_edit`)
  */
 export type ToolDefinitionFactory = (deps: ToolDependencies) => ToolDefinition;

package/lib/types/dsh/fs.d.ts

@@ -1,5 +1,6 @@
-import type { FileIO, FileStat } from "./contracts.js";
-import { type FileSystem } from "@deepseek-ai/dsh-fs";
+import type { FileIO, FileStat, FsObservationChannel } from "./contracts.js";
+import type { Context } from "@deepseek-ai/cordis";
+import { type FileSystem, type FsTarget, type FsVersion } from "@deepseek-ai/dsh-fs";
 import type { CoreReadIo } from "../src/io-port.js";
 /** Stable codes for request-shape failures raised before any OS call. */
 export type FileValidationCode = "E_PATH_EMPTY" | "E_PATH_NULL_BYTE" | "E_PATH_NOT_ABSOLUTE" | "E_ACCESS_MODE";
@@ -40,6 +41,9 @@ export declare class LocalFileIO implements FileIO {
     write(path: string, data: Uint8Array | string, signal?: AbortSignal): Promise<void>;
     stat(path: string, signal?: AbortSignal): Promise<FileStat | undefined>;
     readdir(path: string, signal?: AbortSignal): Promise<string[]>;
+    remove(path: string, signal?: AbortSignal): Promise<void>;
+    rename(from: string, to: string, signal?: AbortSignal): Promise<void>;
+    mkdir(path: string, signal?: AbortSignal): Promise<void>;
 }
 /** Create the M1 local filesystem seam. */
 export declare function createLocalFileIO(): FileIO;
@@ -48,6 +52,11 @@ export declare function createLocalFileIO(): FileIO;
  * fallback when no `ctx.fs` service is mounted; it reads through `node:fs`.
  */
 export declare function createCoreReadIo(io: FileIO): CoreReadIo;
+/**
+ * One successful `stat` through the `ctx.fs` bridge: the target it settled on
+ * and the provider's opaque version token for it.
+ */
+export type CtxFsStatObserver = (target: FsTarget, version: FsVersion) => void;
 /**
  * Adapt a mounted `ctx.fs` provider to the core read port. Targets are cached
  * by path and opaque `targetKey`; `resolve` returns the backend's absolute
@@ -56,5 +65,31 @@ export declare function createCoreReadIo(io: FileIO): CoreReadIo;
  * path round-trip. `FsInfo.version` stays opaque and is deliberately not turned
  * into a fake inode identity: ADR-0043 adoption is skipped for such targets and
  * the read path falls back to content hashing.
+ * @param fs - the mounted provider.
+ * @param onStat - receives the target and provider version of every successful
+ *   `stat`. `CoreFileStat` has no field for the version, so without this hook the
+ *   freshness token the observation channel needs would be dropped.
+ * @returns the read port the core consumes.
+ */
+export declare function createCtxFsCoreReadIo(fs: FileSystem, onStat?: CtxFsStatObserver): CoreReadIo;
+/** The read bridge plus the observation channel for one mounted `ctx.fs`. */
+export interface CtxFsBridge {
+    /** The read port the core consumes. */
+    readonly io: CoreReadIo;
+    /** The channel that publishes `fs/observed` and dispatches `fs/write-intent`. */
+    readonly observations: FsObservationChannel;
+}
+/**
+ * Build the read bridge and the observation channel over one `ctx.fs` provider.
+ *
+ * Both share one resolved-target cache, and the bridge reports every `stat` it
+ * performs, so a successful read publishes the exact version it saw instead of
+ * paying for a second provider round-trip.
+ *
+ * @param ctx - the context that owns the observed tool calls. Publishing from
+ *   the agent's own scope keeps a scope-filtered host listener on that agent.
+ * @param fs - the mounted provider.
+ * @param warn - host diagnostic sink for a publication that could not complete.
+ * @returns the bridge and its channel.
  */
-export declare function createCtxFsCoreReadIo(fs: FileSystem): CoreReadIo;
+export declare function createCtxFsBridge(ctx: Context, fs: FileSystem, warn: (message: string) => void): CtxFsBridge;

package/lib/types/dsh/guidance.d.ts

@@ -26,20 +26,20 @@ export declare function parseSectionFile(content: string): ParsedSection;
 export declare function isBlankOverride(content: string): boolean;
 /** One overridable tool section. */
 export interface GuidanceSection {
-    /** Registry section name, e.g. `tool:edit`. */
+    /** Registry section name, e.g. `tool:apply_patch`. */
     readonly name: string;
-    /** Override file name inside a preset directory, e.g. `edit.md`. */
+    /** Override file name inside a preset directory, e.g. `apply-patch.md`. */
     readonly file: string;
     /** Order used when the harness registry names no slot for this section. */
     readonly defaultOrder: number;
     /** The `systemPrompt.getSectionOrder` slot this section shadows, when one exists. */
-    readonly orderName?: "TOOL_READ" | "TOOL_EDIT";
+    readonly orderName?: "TOOL_READ" | "TOOL_EDIT" | "TOOL_APPLY_PATCH";
     /** The compiled default text. */
     renderDefault(): string;
 }
 /**
- * The three sections, in default-order sequence. Defaults are byte-identical to
- * the pi host's guidance because they come from the same prompt sources.
+ * The three sections, in default-order sequence. Read and undo reuse the pi
+ * host's prompt sources; apply_patch owns the v4 mutation guidance.
  */
 export declare const GUIDANCE_SECTIONS: readonly GuidanceSection[];
 /** Render the compiled default text for one section. */

package/lib/types/dsh/hide.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Hide the native edit-class tools so every precise text change goes through
+ * `apply_patch` — the one mutation entry point of the v4 surface.
+ *
+ * DSH 0.2.2-alpha.3 owns tool declarations in the tool registry, not in the
+ * `system-prompt/assemble` waterfall: the waterfall receives sections, contexts
+ * and variables only. The authoritative schema filter is therefore the
+ * per-agent registry restriction (`tools.restrict({ deny })`), which removes a
+ * global tool from both the native schema list and the PTC `tools:sdk` section
+ * because both are rendered from `tools.definitions(scope, toolSet)`.
+ *
+ * Three seams still back that up, because a restriction only governs the
+ * registry view and a stale session or a hand-rolled section could carry a
+ * residual binding:
+ *
+ * 1. `tools.restrict({ deny })` drops the hidden schemas for this agent;
+ * 2. `system-prompt/assemble` empties the `tool:edit` guidance section (its
+ *    text is prose, never a tool mention) and deletes the hidden tools' member
+ *    blocks from any rendered PTC `tools:sdk` section;
+ * 3. `tools.guard` is the monotonic execution backstop for a stale schema or
+ *    any residual binding.
+ *
+ * `write` stays visible on purpose: whole-file replacement has no operation in
+ * `apply_patch` (`*** Add File:` refuses to overwrite), so hiding it would leave
+ * a rewrite with nowhere to go. Callers that want it gone can list it in
+ * `hiddenToolNames`.
+ *
+ * The layer is installed only when `apply_patch` actually registered: hiding
+ * the native editors while owning no replacement would leave the profile with
+ * no way to change a file.
+ *
+ * @module dsh-hashline-edit/hide
+ */
+/** A boolean config value, or a live getter (used when a host exposes volatile config). */
+type BooleanSource = boolean | (() => boolean);
+/** The hide-layer configuration after the plugin-level defaults are applied. */
+export interface NativeHideConfig {
+    /** The registered replacement tool name, protected from `hiddenToolNames`. */
+    readonly toolName: string;
+    /** Hide `edit`/`str_replace_editor`; defaults to true. */
+    readonly hideNativeWriteTools?: BooleanSource;
+    /** Extra global tool names to hide alongside the native set. */
+    readonly hiddenToolNames?: readonly string[];
+    /** The Agent scope key used for the agent-view probe; absent keeps the global probe. */
+    readonly scope?: unknown;
+}
+/**
+ * Delete the hidden tools' member blocks from one rendered `tools:sdk` text.
+ *
+ * Structural, renderer-specific parsing — never a mention match:
+ * - TypeScript: a member starts at `  name: type` (2-space indent) inside
+ *   `ToolArgsMap`/`ToolOutputMap`, may open braces on the same line, and ends
+ *   at the first line that closes every opened brace and ends with `;`. Its
+ *   optional single-line JSDoc comment directly above goes with it.
+ * - Python: a `Tools` protocol member starts at an indented `async def` line
+ *   and spans until the next line at that member indent or shallower.
+ * @param text - the rendered SDK section text.
+ * @param hidden - the tool names to remove.
+ * @returns the text with every hidden member block removed.
+ */
+export declare function stripSdkMembers(text: string, hidden: ReadonlySet<string>): string;
+interface LoggerLike {
+    warn?(message: string): void;
+}
+declare function warn(rootCtx: {
+    logger?: LoggerLike;
+}, message: string): void;
+/**
+ * Install the hide layer for one agent. Only call this after `apply_patch`
+ * registered successfully.
+ *
+ * @param rootCtx - the plugin/root scope, used for the global-name probe and warnings.
+ * @param agentCtx - the agent scope whose tool view is restricted.
+ * @param config - the resolved hide configuration.
+ * @returns the exact disposer; disposing lifts the restriction and every listener.
+ */
+export declare function registerNativeToolHiding(rootCtx: Parameters<typeof warn>[0], agentCtx: unknown, config: NativeHideConfig): () => void;
+export {};

package/lib/types/dsh/host-compat.d.ts

@@ -1,82 +1,11 @@
-/** Retained line budget, matching pi's `DEFAULT_MAX_LINES`. */
-export declare const DEFAULT_MAX_LINES = 2000;
-/** Retained byte budget, matching pi's `DEFAULT_MAX_BYTES` (50KB). */
-export declare const DEFAULT_MAX_BYTES: number;
-/** The truncation report the core's read page renders. */
-export interface TruncationResult {
-    /** The truncated content. */
-    content: string;
-    /** Whether truncation occurred. */
-    truncated: boolean;
-    /** Which limit was hit: `"lines"`, `"bytes"`, or `null` when nothing was cut. */
-    truncatedBy: "lines" | "bytes" | null;
-    /** Total number of lines in the original content. */
-    totalLines: number;
-    /** Total number of bytes in the original content. */
-    totalBytes: number;
-    /** Number of complete lines in the truncated output. */
-    outputLines: number;
-    /** Number of bytes in the truncated output. */
-    outputBytes: number;
-    /** Whether the last line was partially truncated (tail truncation only). */
-    lastLinePartial: boolean;
-    /** Whether the first line exceeded the byte limit (head truncation only). */
-    firstLineExceedsLimit: boolean;
-    /** The line limit that was applied. */
-    maxLines: number;
-    /** The byte limit that was applied. */
-    maxBytes: number;
-}
-/** The two independent limits a truncation call applies. */
-export interface TruncationOptions {
-    /** Maximum number of lines; defaults to {@link DEFAULT_MAX_LINES}. */
-    maxLines?: number;
-    /** Maximum number of bytes; defaults to {@link DEFAULT_MAX_BYTES}. */
-    maxBytes?: number;
-}
 /**
- * Minimal structural stand-in for pi's extension-registry type.
+ * dsh host shim for the host-neutral utilities the core uses.
  *
- * WHY: `src/edit-undo.ts` keeps the pi registration (and its `ExtensionAPI` type) next to the
- * host-agnostic use case the dsh undo tool calls. The dsh build resolves the pi package to this
- * shim and never invokes that registration, so the build typecheck needs only the single method
- * the registration calls; the root tsconfig still checks the registration against the real pi API.
- */
-export interface ExtensionAPI {
-    /**
-     * Register one pi tool definition. The argument is intentionally structural and loose: the dsh
-     * program only needs the registration to compile, never to execute, and the loose `execute`
-     * signature keeps the pi adapter's untyped callback out of the dsh build's implicit-any checks.
-     */
-    registerTool(definition: {
-        execute: (...args: any[]) => unknown;
-        [key: string]: unknown;
-    }): void;
-}
-/**
- * Format bytes as a human-readable size (`512B`, `1.5KB`, `2.0MB`).
- * @param bytes - the byte count to render.
- * @returns the pi-compatible size label.
- */
-export declare function formatSize(bytes: number): string;
-/**
- * Truncate content from the head (keep the first N lines / bytes).
+ * WHY: the dsh bundle must not ship the pi agent package. The core's utility
+ * surface lives in `src/host-utils.ts`; this module keeps the historical
+ * `dsh/host-compat` import path (and the `@earendil-works/pi-coding-agent`
+ * esbuild/tsconfig alias) working for the dsh build.
  *
- * WHY: the read page's oversize and truncation warnings must agree with the pi
- * implementation the rest of the contract was written against, so this is a
- * faithful port including its two edge rules: complete lines only, and an
- * over-long first line yields empty content with `firstLineExceedsLimit`.
- * @param content - the text to truncate.
- * @param options - the line and byte limits.
- * @returns the truncation report.
- */
-export declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
-/**
- * Serialize file mutation operations that target the same file; different files still run
- * in parallel. A faithful port of pi's queue so the core's cut transaction keeps its
- * lock ordering guarantees under the dsh host.
- * @param filePath - the file the mutation targets.
- * @param run - the critical section to run once the path is free.
- * @returns the critical section's result.
+ * @module dsh-hashline-edit/host-compat
  */
-export declare function withFileMutationQueue<T>(filePath: string, run: () => Promise<T>): Promise<T>;
+export * from "../src/host-utils.js";

package/lib/types/dsh/index.d.ts

@@ -1,17 +1,16 @@
 /**
  * dsh-hashline-edit host plugin entry.
  *
- * On every `agent/created`, install the three hashline tools on the AGENT's
- * own scope layer so they shadow the preset's built-in `read`/`edit` for that
+ * On every `agent/created`, install the hashline tools on the AGENT's
+ * own scope layer so they shadow the preset's built-in `read` for that
  * agent (nearest layer wins in dsh's tool registry) and unwind automatically
  * when the agent is disposed. The built-in `write` stays in place; the
  * platform lane's write hook integrates with it.
  *
- * `inject` deliberately lists only `tools` and `systemPrompt`: M1 has no
  * `inject` deliberately lists only `tools` and `systemPrompt`: the read-path
  * `ctx.fs` bridge is optional and resolved with `ctx.get`, so a minimal
- * composition still loads with the local `node:fs` fallback. Edit/undo stay
- * local-only (the M5 bridge covers reads; M6 owns mutation).
+ * composition still loads with the local `node:fs` fallback. apply_patch and
+ * undo stay local-only (the M5 bridge covers reads; M6 owns mutation).
  * @module dsh-hashline-edit
  */
 import type { Context } from "@deepseek-ai/cordis";
@@ -24,6 +23,17 @@ export declare const name = "dsh-hashline-edit";
  * services are resolved with `ctx.get` inside `dsh/sandbox.ts` instead.
  */
 export declare const inject: string[];
+/** The plugin configuration the loader passes as the second `apply` argument. */
+export interface PluginConfig {
+    /**
+     * Hide the native `edit`/`str_replace_editor` tools so every precise text
+     * change goes through `apply_patch`. Defaults to true. `write` is not in
+     * that set on purpose: whole-file replacement has no apply_patch operation.
+     */
+    hideNativeWriteTools?: boolean;
+    /** Extra global tool names to hide alongside the native write set. */
+    hiddenToolNames?: readonly string[];
+}
 /**
  * Install the hashline toolset for one agent inside its own effect, so the
  * registrations are disposed in reverse order when the agent scope unwinds.
@@ -31,6 +41,6 @@ export declare const inject: string[];
  * Exported separately from {@link apply} so the host test can drive one fake
  * agent directly and integration probes can reuse the exact install path.
  */
-export declare function installAgentTools(rootCtx: Context, agent: Agent, metrics?: ToolMetrics): void;
+export declare function installAgentTools(rootCtx: Context, agent: Agent, metrics?: ToolMetrics, config?: PluginConfig): void;
 /** Mount the plugin: install the hashline toolset on every new agent. */
-export declare function apply(rootCtx: Context): void;
+export declare function apply(rootCtx: Context, config?: PluginConfig): void;

package/lib/types/dsh/metrics/events.d.ts

@@ -1,4 +1,11 @@
-type ToolName = "read" | "edit" | "undo_last_edit" | "write" | "shell_view";
+/**
+ * Every tool name this telemetry can carry.
+ *
+ * The named members are the tools this plugin measures itself; the open member
+ * lets the global observer record any other host tool — the built-in `write`,
+ * `pwsh`, `grep`, … — without widening this union once per tool.
+ */
+type ToolName = "read" | "apply_patch" | "undo_last_edit" | "write" | "shell_view" | (string & {});
 /** One tool call, as written to the JSONL file. Character counts are exact; the
  *  token estimate belongs to the summarizer so the ratio stays a reporting
  *  choice instead of being frozen into the event stream. */

package/lib/types/dsh/metrics/instrument.d.ts

@@ -1,19 +1,18 @@
+import type { MetricSink, ToolMetric } from "./events.js";
 /**
- * Shared emission helpers for the dsh tool-call telemetry.
- *
- * The tools and the shell hook call {@link createToolMetrics} at their boundary
- * with whatever counts they already hold; every extraction here is cheap
- * (string lengths, array lengths, one JSON stringify of the request). The
- * sink is optional: when no `DSH_HASHLINE_METRICS` file is configured the
- * callers skip the timer and this module is never reached, so the tool path
- * pays no allocation.
+ * The execution facts one measured call carries.
  *
- * Telemetry is observability only: a missing/disabled/throwing sink must
- * never fail or delay the call it measures.
- * @module dsh-hashline-edit/metrics/instrument
+ * Structural on purpose: a tool boundary hands over a `ToolRunContext` while the
+ * global observer sees the `tools/execute` view of the same call, and both expose
+ * the caller agent. Only the agent's id is read (the session key the event
+ * names), so neither caller has to manufacture a full `ToolExecution`.
  */
-import type { ToolExecution } from "@deepseek-ai/dsh-tools";
-import type { MetricSink, ToolMetric } from "./events.js";
+interface MetricExecution {
+    /** The agent on whose behalf the call ran. */
+    readonly agent?: {
+        readonly id?: unknown;
+    } | undefined;
+}
 /** One event's facts, as the tool boundary knows them. */
 interface MetricRecord {
     /** The metric tool key; `shell_view` is emitted only when the hook rewrites a result. */
@@ -23,7 +22,7 @@ interface MetricRecord {
     /** Wall time of the tool call (or of the shell hook's rewrite). */
     readonly durationMs: number;
     /** The dsh execution; supplies the session id. */
-    readonly exec: ToolExecution;
+    readonly exec: MetricExecution;
     /** The accepted tool arguments, used for the exact request-payload character count. */
     readonly args?: unknown;
     /** Explicit request character count; when omitted, `JSON.stringify(args).length`. */
@@ -32,6 +31,11 @@ interface MetricRecord {
     readonly charsOut: number;
     /** The request path, when the call names one. */
     readonly path?: string | undefined;
+    /**
+     * Retry-chain discriminator for a call that names no path: a shell call's
+     * command, so re-running the same command is one chain.
+     */
+    readonly chain?: string | undefined;
     /** First `E_*`/`W_*` code on a refusal or a warning. */
     readonly code?: string | undefined;
     /** Final file line count, when the tool already computed it. */
@@ -45,6 +49,8 @@ interface MetricRecord {
 export declare function pathOf(args: unknown): string | undefined;
 /** The first `W_*` code among the supplied warning strings, if any. */
 export declare function warningCodeOf(values: readonly (string | undefined)[]): string | undefined;
+/** The first `E_*`/`W_*` code carried by a settled result's content blocks. */
+export declare function resultCodeOf(result: unknown): string | undefined;
 /** The registry code carried by a caught failure, if it carries one. */
 export declare function errorCodeOf(error: unknown): string | undefined;
 /** Exact text length of `{ content: [{text}], … }` tool envelopes (edit/undo). */

package/lib/types/dsh/metrics/observer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Global tool-call telemetry for the dsh host layer.
+ *
+ * Before this observer the adapter measured only its own surface: `read`,
+ * `apply_patch` and `undo_last_edit` from the tool boundaries, plus `shell_view` from
+ * the shell hook when it rewrites a result. Every other call the host
+ * dispatched — the built-in `write` that sits next to this plugin's shadowed
+ * tools, `pwsh`, `grep`, … — left no event at all, so no baseline could say
+ * what those calls cost or how often they were retried. This listener closes
+ * that hole with the tool's own name as the event's `tool`.
+ *
+ * It hangs off `tools/execute`, the host's around-dispatch waterfall (the one
+ * the host documents for metrics), on the agent's own scope, so a
+ * scope-filtered dispatch sends it that agent's calls only. It is installed
+ * only when a sink exists: the unmeasured composition pays no listener and no
+ * allocation.
+ *
+ * @module dsh-hashline-edit/metrics/observer
+ */
+import type { Context } from "@deepseek-ai/cordis";
+import { type ToolMetrics } from "./instrument.js";
+/**
+ * Install the global observer for one agent.
+ * @param agentCtx - the agent's scoped context; the listener sees only its calls.
+ * @param metrics - the shared recorder; `undefined` installs nothing at all.
+ * @returns the exact disposer that unregisters the listener.
+ */
+export declare function registerToolObserver(agentCtx: Context, metrics: ToolMetrics | undefined): () => void;

package/lib/types/dsh/sandbox.d.ts

@@ -3,7 +3,7 @@
  *
  * Mirrors the built-in `@deepseek-ai/dsh-tool-fs` controller (same
  * vocabulary, same fail-closed approval sequence, shared
- * `@deepseek-ai/dsh-sandbox` pieces) so `edit`/`undo_last_edit` ask for wider
+ * `@deepseek-ai/dsh-sandbox` pieces) so `apply_patch`/`undo_last_edit` ask for wider
  * access exactly like the built-in `write`/`edit`. The differences are
  * deliberate M1 facts:
  *
@@ -21,7 +21,7 @@ import type { ToolExecution } from "@deepseek-ai/dsh-tools";
 import type { SandboxMode } from "@deepseek-ai/dsh-sandbox";
 import type { SandboxArgs, SandboxController, SandboxDecision } from "./contracts.js";
 /**
- * The filesystem escalation controller shared by `edit` and `undo_last_edit`
+ * The filesystem escalation controller shared by `apply_patch` and `undo_last_edit`
  * for one agent install.
  */
 export declare class FsSandboxController implements SandboxController {

package/lib/types/dsh/shell-hook.d.ts

@@ -7,7 +7,7 @@
  * foreground stdout channel, or a shell view that refuses (not whitelisted /
  * ambiguous alignment) all pass the decision through untouched. Only a
  * successful, uniquely aligned view is rewritten, and its rows are served
- * through the read tool's seam so a following `edit` resolves the anchors.
+ * through the read tool's seam so a following `apply_patch` hunk resolves the anchors.
  *
  * Both foreground value shapes the host may project are understood:
  * `{ kind: "foreground", stdout: { text, truncated } }` (the canonical
@@ -19,13 +19,20 @@
  */
 import type { Context } from "@deepseek-ai/cordis";
 import type { PostToolDecision, ToolExecution, ToolExecutionResult } from "@deepseek-ai/dsh-tools";
-import type { ToolDependencies } from "./contracts.js";
+import type { FsObservationChannel, ToolDependencies } from "./contracts.js";
 import type { ToolMetrics } from "./metrics/instrument.js";
-import { type ShellViewPlan, type ShellViewRequest } from "./shell-view.js";
+import { type GrepViewPlan, type GrepViewRequest, type ShellViewPlan, type ShellViewRequest } from "./shell-view.js";
 /** Host seams one shell hook needs; a product of `ctx`/`deps` at apply time. */
 export interface ShellHookDeps {
     /** Plan anchored rows for a whitelisted command; `undefined` means pass through. */
     plan(request: ShellViewRequest): Promise<ShellViewPlan | undefined>;
+    /** Plan anchored rows for a built-in `grep` result; `undefined` means pass through. */
+    planGrep(request: GrepViewRequest): Promise<GrepViewPlan | undefined>;
+    /**
+     * Optional host observation channel: a granted view is a read of that file, so
+     * the host's read-before-write guard must see it.
+     */
+    readonly observations?: FsObservationChannel;
     /** Host diagnostic sink; the hook must never throw through this. */
     warn(message: string): void;
     /** Optional telemetry recorder; emits `shell_view` only when a result is rewritten. */
@@ -36,18 +43,20 @@ export interface ShellHooks {
     postExecute(exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>;
 }
 /**
- * Compose the shell hook around one dependency set. The returned function is
- * the test surface; {@link registerShellHook} is a thin `agentCtx.on` binding.
+ * Compose the shell and built-in-grep hooks around one dependency set. Both listen on
+ * `tools/post-execute` and share the serve/lease seam; this single entry point keeps the
+ * registration one listener. The returned function is the test surface;
+ * {@link registerShellHook} is a thin `agentCtx.on` binding.
  */
 export declare function createShellHooks(deps: ShellHookDeps): ShellHooks;
 /** The production dependency set: the shell-view planner plus the host diagnostic sink. */
 export declare function defaultShellHookDeps(deps: ToolDependencies, warn: (message: string) => void): ShellHookDeps;
 /**
- * Register the shell integration for one agent on its own scope layer.
+ * Register the shell and built-in-grep integrations for one agent on its own scope layer.
  *
  * @param rootCtx - host context, used only for diagnostics.
- * @param agentCtx - the agent's scoped context; the listener sees only that agent's shell calls.
- * @param deps - the host seams the shell view plans and serves through.
+ * @param agentCtx - the agent's scoped context; the listener sees only that agent's calls.
+ * @param deps - the host seams the shell view and the grep view plan and serve through.
  * @returns the exact disposer that unregisters the listener.
  */
 export declare function registerShellHook(rootCtx: Context, agentCtx: Context, deps: ToolDependencies): () => void;