@arnilo/prism-coding-agent 0.2.4 → 0.2.6

package/dist/review.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Bounded patch-review manifest binding review decisions to the exact
+ * repository/worktree/base/head identity plus patch digest and artifact
+ * revision. Pure helpers compose over the server ArtifactService (attach /
+ * approve / reject) — no second approval engine, no raw patch body persisted.
+ */
+export type CodingPatchReviewState = "pending" | "accepted" | "rejected" | "superseded";
+export type ReviewDiagnosticSeverity = "error" | "warning" | "info" | "hint";
+export interface CodingPatchReviewCheckSummary {
+    readonly name: string;
+    readonly exitCode: number;
+    readonly summary: string;
+}
+export interface CodingPatchReviewDiagnosticSummary {
+    readonly file: string;
+    readonly severity: ReviewDiagnosticSeverity;
+    readonly count: number;
+    readonly generation: number;
+}
+export interface CodingPatchReviewDiffstatEntry {
+    readonly file: string;
+    readonly additions: number;
+    readonly deletions: number;
+}
+export interface CodingPatchReviewIdentity {
+    readonly repositoryId: string;
+    /** Credential-free remote fingerprint (GitOperations.fingerprint). */
+    readonly remoteFingerprint: string;
+    readonly defaultBranch: string;
+    /** Relative worktree path inside the approved worktree roots; optional. */
+    readonly worktreePath?: string;
+}
+export interface CodingPatchReview {
+    readonly schemaVersion: 1;
+    readonly reviewId: string;
+    readonly state: CodingPatchReviewState;
+    readonly threadId: string;
+    readonly artifactId: string;
+    readonly identity: CodingPatchReviewIdentity;
+    readonly base: string;
+    readonly head: string;
+    readonly patch: {
+        readonly kind: "patch" | "bundle" | "diff" | "other";
+        readonly uri: string;
+        readonly sha256: string;
+        readonly bytes: number;
+    };
+    readonly changedPaths: readonly string[];
+    readonly diffstat: readonly CodingPatchReviewDiffstatEntry[];
+    readonly checks: readonly CodingPatchReviewCheckSummary[];
+    readonly diagnostics: readonly CodingPatchReviewDiagnosticSummary[];
+    /** SHA-256 over the canonical manifest JSON — the acceptance binding. */
+    readonly digest: string;
+    readonly createdAt: string;
+}
+export interface CreateCodingPatchReviewInput {
+    readonly threadId: string;
+    readonly artifactId: string;
+    readonly identity: CodingPatchReviewIdentity;
+    readonly base: string;
+    readonly head: string;
+    readonly patch: CodingPatchReview["patch"];
+    readonly changedPaths?: readonly string[];
+    readonly diffstat?: readonly CodingPatchReviewDiffstatEntry[];
+    readonly checks?: readonly CodingPatchReviewCheckSummary[];
+    readonly diagnostics?: readonly CodingPatchReviewDiagnosticSummary[];
+    readonly limits?: CodingReviewLimits;
+    /** Explicit review id; defaults to a deterministic id from the digest. */
+    readonly reviewId?: string;
+    /** Explicit ISO-8601 timestamp (deterministic manifests); defaults to now. */
+    readonly createdAt?: string;
+}
+export interface CodingReviewLimits {
+    readonly maxRevisions?: number;
+    readonly maxDiagnostics?: number;
+    readonly maxManifestBytes?: number;
+}
+export interface ResolvedCodingReviewLimits {
+    readonly maxRevisions: number;
+    readonly maxDiagnostics: number;
+    readonly maxManifestBytes: number;
+}
+export declare function resolveCodingReviewLimits(options?: CodingReviewLimits): ResolvedCodingReviewLimits;
+/** Structural subset of the server ArtifactAttachInput (thread/uri/hash/preview). */
+export interface CodingReviewArtifactInput {
+    readonly threadId: string;
+    readonly id: string;
+    readonly uri: string;
+    readonly mime: string;
+    readonly hash: string;
+    readonly size?: number;
+    readonly title?: string;
+    readonly changeNote?: string;
+    readonly producerRunId?: string;
+    readonly preview?: Readonly<Record<string, unknown>>;
+}
+/** Structural subset of the server ArtifactRecord for acceptance checks. */
+export interface CodingReviewArtifactRecord {
+    /** Server artifact id (ArtifactRecord.id); must equal review.artifactId. */
+    readonly id: string;
+    readonly threadId: string;
+    readonly revisions: readonly {
+        readonly version: number;
+        readonly hash: string;
+        readonly uri: string;
+        readonly preview?: Readonly<Record<string, unknown>>;
+    }[];
+    readonly approvals: readonly {
+        readonly version: number;
+        readonly state: "pending" | "approved" | "rejected";
+        readonly reviewer?: string;
+        readonly note?: string;
+    }[];
+}
+export type CodingPatchReviewErrorCode = "ERR_PRISM_REVIEW_INPUT" | "ERR_PRISM_REVIEW_LIMIT" | "ERR_PRISM_REVIEW_BINDING" | "ERR_PRISM_REVIEW_STATE" | "ERR_PRISM_REVIEW_OWNERSHIP";
+export declare class CodingPatchReviewError extends Error {
+    readonly code: CodingPatchReviewErrorCode;
+    constructor(code: CodingPatchReviewErrorCode, message: string);
+}
+/**
+ * Build the bounded review manifest. Validates every identity field, caps
+ * changed paths / diffstat / check summaries / diagnostic summaries, computes
+ * the digest over the canonical manifest JSON, and returns the structural
+ * artifact input whose `preview.review` embeds the manifest (digest binding).
+ * Never embeds a raw patch body, command, env, or secret.
+ */
+export declare function createCodingPatchReviewManifest(input: CreateCodingPatchReviewInput): {
+    review: CodingPatchReview;
+    artifactInput: CodingReviewArtifactInput;
+};
+export interface AssertCodingPatchAcceptedInput {
+    /** Fresh manifest whose state is being derived; must match the artifact binding. */
+    readonly review: CodingPatchReview;
+    /** Server ArtifactRecord (structurally compatible with @arnilo/prism-server ArtifactRecord). */
+    readonly artifact: CodingReviewArtifactRecord;
+}
+export interface AssertCodingPatchAcceptedResult {
+    readonly state: CodingPatchReviewState;
+    readonly version: number;
+    readonly reviewer?: string;
+    readonly reason?: string;
+}
+/**
+ * Derive the review state from the artifact record. The binding is exact:
+ * review digest + patch digest + artifact revision + workspace identity must
+ * all match the recorded preview; any patch/repository/worktree/base/head
+ * change since approval surfaces as `superseded` — never a silent accept.
+ * Acceptance never applies, commits, pushes, or merges.
+ */
+export declare function assertCodingPatchAccepted(input: AssertCodingPatchAcceptedInput): AssertCodingPatchAcceptedResult;

package/dist/review.js

@@ -0,0 +1,222 @@
+/**
+ * Bounded patch-review manifest binding review decisions to the exact
+ * repository/worktree/base/head identity plus patch digest and artifact
+ * revision. Pure helpers compose over the server ArtifactService (attach /
+ * approve / reject) — no second approval engine, no raw patch body persisted.
+ */
+import { createHash } from "node:crypto";
+import { DEFAULT_MAX_REVIEW_DIAGNOSTICS, DEFAULT_MAX_REVIEW_MANIFEST_BYTES, DEFAULT_MAX_REVIEW_REVISIONS, HARD_MAX_REVIEW_DIAGNOSTICS, HARD_MAX_REVIEW_MANIFEST_BYTES, HARD_MAX_REVIEW_REVISIONS, validateCodingLimit, } from "./limits.js";
+export function resolveCodingReviewLimits(options) {
+    return {
+        maxRevisions: validateCodingLimit("maxRevisions", options?.maxRevisions ?? DEFAULT_MAX_REVIEW_REVISIONS, HARD_MAX_REVIEW_REVISIONS),
+        maxDiagnostics: validateCodingLimit("maxDiagnostics", options?.maxDiagnostics ?? DEFAULT_MAX_REVIEW_DIAGNOSTICS, HARD_MAX_REVIEW_DIAGNOSTICS),
+        maxManifestBytes: validateCodingLimit("maxManifestBytes", options?.maxManifestBytes ?? DEFAULT_MAX_REVIEW_MANIFEST_BYTES, HARD_MAX_REVIEW_MANIFEST_BYTES),
+    };
+}
+export class CodingPatchReviewError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "CodingPatchReviewError";
+        this.code = code;
+    }
+}
+const HEX64 = /^[0-9a-f]{64}$/;
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+const REF_PATTERN = /^[^\s]{1,255}$/;
+const CONTROL_PATTERN = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g;
+/**
+ * Build the bounded review manifest. Validates every identity field, caps
+ * changed paths / diffstat / check summaries / diagnostic summaries, computes
+ * the digest over the canonical manifest JSON, and returns the structural
+ * artifact input whose `preview.review` embeds the manifest (digest binding).
+ * Never embeds a raw patch body, command, env, or secret.
+ */
+export function createCodingPatchReviewManifest(input) {
+    const limits = resolveCodingReviewLimits(input.limits);
+    if (!ID_PATTERN.test(input.threadId)) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", "threadId must match [A-Za-z0-9][A-Za-z0-9._:-]*");
+    }
+    if (!ID_PATTERN.test(input.artifactId)) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", "artifactId must match [A-Za-z0-9][A-Za-z0-9._:-]*");
+    }
+    if (!ID_PATTERN.test(input.identity.repositoryId)) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", "repositoryId must match [A-Za-z0-9][A-Za-z0-9._:-]*");
+    }
+    if (!HEX64.test(input.identity.remoteFingerprint)) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", "remoteFingerprint must be a 64-hex sha256");
+    }
+    if (!REF_PATTERN.test(input.identity.defaultBranch) || input.identity.defaultBranch.includes("..")) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", "defaultBranch is invalid");
+    }
+    if (input.identity.worktreePath !== undefined) {
+        assertRelativePath(input.identity.worktreePath, "worktreePath");
+    }
+    if (!REF_PATTERN.test(input.base) || input.base.includes("..")) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", "base is invalid");
+    }
+    if (!REF_PATTERN.test(input.head) || input.head.includes("..")) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", "head is invalid");
+    }
+    if (!HEX64.test(input.patch.sha256)) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", "patch.sha256 must be a 64-hex sha256");
+    }
+    if (!Number.isSafeInteger(input.patch.bytes) || input.patch.bytes < 0) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", "patch.bytes must be a non-negative safe integer");
+    }
+    if (input.patch.uri.length > 2_048 || CONTROL_PATTERN.test(input.patch.uri)) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", "patch.uri exceeds 2048 bytes or contains control characters");
+    }
+    const changedPaths = (input.changedPaths ?? []).map((path) => assertRelativePath(path, "changedPaths"));
+    const diffstat = (input.diffstat ?? []).map((entry) => {
+        const file = assertRelativePath(entry.file, "diffstat");
+        if (!Number.isSafeInteger(entry.additions) || entry.additions < 0 || !Number.isSafeInteger(entry.deletions) || entry.deletions < 0) {
+            throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", "diffstat counts must be non-negative safe integers");
+        }
+        return { file, additions: entry.additions, deletions: entry.deletions };
+    });
+    const checks = (input.checks ?? []).map((check) => {
+        if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(check.name)) {
+            throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", `check name is invalid: ${check.name}`);
+        }
+        if (!Number.isInteger(check.exitCode)) {
+            throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", `check ${check.name} exitCode must be an integer`);
+        }
+        const summary = String(check.summary).replace(CONTROL_PATTERN, "");
+        if (Buffer.byteLength(summary, "utf8") > 8_192) {
+            throw new CodingPatchReviewError("ERR_PRISM_REVIEW_LIMIT", `check ${check.name} summary exceeds 8192 bytes`);
+        }
+        return { name: check.name, exitCode: check.exitCode, summary };
+    });
+    const diagnostics = (input.diagnostics ?? []).map((diag) => {
+        const file = assertRelativePath(diag.file, "diagnostics");
+        if (diag.severity !== "error" && diag.severity !== "warning" && diag.severity !== "info" && diag.severity !== "hint") {
+            throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", `diagnostic severity is invalid: ${String(diag.severity)}`);
+        }
+        if (!Number.isSafeInteger(diag.count) || diag.count < 0 || !Number.isSafeInteger(diag.generation) || diag.generation < 0) {
+            throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", "diagnostic count/generation must be non-negative safe integers");
+        }
+        return { file, severity: diag.severity, count: diag.count, generation: diag.generation };
+    });
+    if (changedPaths.length > limits.maxRevisions * 250) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_LIMIT", `changedPaths exceed the bounded manifest budget (${limits.maxRevisions * 250})`);
+    }
+    if (checks.length > limits.maxRevisions) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_LIMIT", `checks exceed ${limits.maxRevisions}`);
+    }
+    if (diffstat.length > limits.maxRevisions * 250) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_LIMIT", `diffstat exceeds the bounded manifest budget (${limits.maxRevisions * 250})`);
+    }
+    if (diagnostics.length > limits.maxDiagnostics) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_LIMIT", `diagnostic summaries exceed ${limits.maxDiagnostics}`);
+    }
+    if (input.reviewId !== undefined && !ID_PATTERN.test(input.reviewId)) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", "reviewId must match [A-Za-z0-9][A-Za-z0-9._:-]*");
+    }
+    const body = {
+        schemaVersion: 1,
+        reviewId: "",
+        state: "pending",
+        threadId: input.threadId,
+        artifactId: input.artifactId,
+        identity: input.identity,
+        base: input.base,
+        head: input.head,
+        patch: input.patch,
+        changedPaths,
+        diffstat,
+        checks,
+        diagnostics,
+    };
+    const createdAt = input.createdAt ?? new Date().toISOString();
+    if (typeof createdAt !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(createdAt)) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", "createdAt must be an ISO-8601 UTC timestamp");
+    }
+    const digest = sha256Hex(Buffer.from(JSON.stringify({ ...body, createdAt }), "utf8"));
+    const reviewId = input.reviewId ?? `review-${digest.slice(0, 24)}`;
+    const review = { ...body, reviewId, digest, createdAt };
+    const manifestJson = JSON.stringify(review);
+    if (Buffer.byteLength(manifestJson, "utf8") > limits.maxManifestBytes) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_LIMIT", `review manifest exceeds ${limits.maxManifestBytes} bytes`);
+    }
+    const artifactInput = {
+        threadId: input.threadId,
+        id: input.artifactId,
+        uri: input.patch.uri,
+        mime: `application/x-${input.patch.kind}`,
+        hash: input.patch.sha256,
+        size: input.patch.bytes,
+        title: `Coding patch review ${reviewId}`,
+        changeNote: `head ${input.head} over base ${input.base}`,
+        preview: {
+            review,
+        },
+    };
+    return { review, artifactInput };
+}
+/**
+ * Derive the review state from the artifact record. The binding is exact:
+ * review digest + patch digest + artifact revision + workspace identity must
+ * all match the recorded preview; any patch/repository/worktree/base/head
+ * change since approval surfaces as `superseded` — never a silent accept.
+ * Acceptance never applies, commits, pushes, or merges.
+ */
+export function assertCodingPatchAccepted(input) {
+    const { review, artifact } = input;
+    if (artifact.threadId !== review.threadId || artifact.id !== review.artifactId) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_OWNERSHIP", "artifact does not belong to this review thread");
+    }
+    const bound = artifact.revisions.find((revision) => revision.hash === review.patch.sha256);
+    if (!bound) {
+        return { state: "superseded", version: 0, reason: "no artifact revision matches the patch digest" };
+    }
+    const latestVersion = artifact.revisions.reduce((max, revision) => Math.max(max, revision.version), 0);
+    if (bound.version < latestVersion) {
+        return { state: "superseded", version: bound.version, reason: "a newer patch revision supersedes this acceptance" };
+    }
+    const preview = bound.preview?.review;
+    if (!preview || typeof preview !== "object") {
+        return { state: "superseded", version: bound.version, reason: "artifact revision carries no review binding" };
+    }
+    if (preview.digest !== review.digest) {
+        return {
+            state: "superseded",
+            version: bound.version,
+            reason: "review digest changed after the decision (patch, identity, base, or head changed)",
+        };
+    }
+    if (preview.identity?.repositoryId !== review.identity.repositoryId ||
+        preview.identity?.remoteFingerprint !== review.identity.remoteFingerprint ||
+        preview.identity?.defaultBranch !== review.identity.defaultBranch ||
+        preview.base !== review.base ||
+        preview.head !== review.head) {
+        return { state: "superseded", version: bound.version, reason: "repository/worktree/base/head identity changed after the decision" };
+    }
+    const decision = artifact.approvals.find((approval) => approval.version === bound.version);
+    if (!decision) {
+        return { state: "pending", version: bound.version, reason: "no decision recorded for the bound revision" };
+    }
+    if (decision.state === "rejected") {
+        return { state: "rejected", version: bound.version, reviewer: decision.reviewer, reason: decision.note };
+    }
+    if (decision.state !== "approved") {
+        return { state: "pending", version: bound.version, reason: "decision for the bound revision is not approved" };
+    }
+    return { state: "accepted", version: bound.version, reviewer: decision.reviewer };
+}
+function assertRelativePath(path, field) {
+    if (typeof path !== "string" || path.length === 0) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", `${field} must be a non-empty string`);
+    }
+    if (path.includes("\0") || path.startsWith("/") || path.startsWith("\\") || /^[A-Za-z]:/.test(path)) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", `${field} must be workspace-relative: ${path}`);
+    }
+    if (path === ".." || path.startsWith("../") || path.split("/").includes("..")) {
+        throw new CodingPatchReviewError("ERR_PRISM_REVIEW_INPUT", `${field} escapes the workspace: ${path}`);
+    }
+    return path;
+}
+function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+//# sourceMappingURL=review.js.map

package/dist/search.d.ts

@@ -2,7 +2,7 @@
  * `repo_search` tool: bounded native literal repository text search.
  */
 import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
-import { type RepositoryLimitOptions, type RepositoryOperations } from "./repository.js";
+import { type RepoSearchMode, type RepositoryLimitOptions, type RepositoryOperations } from "./repository.js";
 export interface SearchToolOptions {
     executionPolicy?: ExecutionPolicy;
     operations?: RepositoryOperations;
@@ -10,5 +10,7 @@ export interface SearchToolOptions {
     maxMatches?: number;
     maxContextLines?: number;
     exclude?: readonly string[];
+    /** Modes the tool exposes (default `["literal"]`); indexed modes require a host index via `operations`. */
+    modes?: readonly RepoSearchMode[];
 }
 export declare function createRepoSearchTool(cwd: string, options?: SearchToolOptions): ToolDefinition;

package/dist/search.js

@@ -3,6 +3,11 @@ import { enforceExecutionPolicy } from "./execution-policy.js";
 import { HARD_MAX_SEARCH_CONTEXT_LINES, HARD_MAX_SEARCH_MATCHES, validateCodingLimit, validateCodingLimitAllowZero } from "./limits.js";
 import { createLocalRepositoryOperations, RepositoryError, resolveRepositoryLimits, } from "./repository.js";
 import { truncateLine } from "./truncate.js";
+const ALL_MODES = ["literal", "indexed_literal", "semantic"];
+const INDEX_MODE_LABEL = {
+    indexed_literal: "host-indexed literal match with relevance scores",
+    semantic: "host semantic search (requires a semantic-capable index backend)",
+};
 function errorResult(toolCallId, message) {
     return {
         toolCallId,
@@ -18,7 +23,8 @@ function formatMatch(match) {
         lines.push(`${match.path}-${text}`);
     }
     const { text } = truncateLine(match.text, 500);
-    lines.push(`${match.path}:${match.line}:${match.column}:${text}`);
+    const score = match.score !== undefined ? ` [score ${match.score.toFixed(3)}]` : "";
+    lines.push(`${match.path}:${match.line}:${match.column}:${text}${score}`);
     for (const after of match.after) {
         const truncated = truncateLine(after, 500);
         lines.push(`${match.path}+${truncated.text}`);
@@ -87,11 +93,35 @@ function buildSearchMetadata(result, outputMode) {
         filesSkippedBinary: result.filesSkippedBinary,
         filesSkippedOversize: result.filesSkippedOversize,
     };
+    if (result.indexed !== undefined) {
+        base.untrusted_index = result.untrusted_index === true;
+        base.indexMode = result.indexed.mode;
+        base.indexState = result.indexed.state;
+        if (result.indexed.sourceRevision !== undefined)
+            base.indexRevision = result.indexed.sourceRevision;
+        if (result.indexed.updatedAt !== undefined)
+            base.indexUpdatedAt = result.indexed.updatedAt;
+    }
     if (outputMode === "content") {
         return { ...base, matches: result.matches };
     }
     return { ...base, fileCount: uniqueMatchPaths(result.matches).length };
 }
+function validateModes(modes) {
+    if (modes === undefined)
+        return ["literal"];
+    if (!Array.isArray(modes) || modes.length === 0)
+        return ["literal"];
+    const seen = new Set();
+    for (const mode of modes) {
+        if (!ALL_MODES.includes(mode)) {
+            throw new Error(`unsupported search mode in options.modes: ${String(mode)}`);
+        }
+        seen.add(mode);
+    }
+    seen.add("literal"); // literal always stays available
+    return [...seen].sort((a, b) => ALL_MODES.indexOf(a) - ALL_MODES.indexOf(b));
+}
 export function createRepoSearchTool(cwd, options) {
     const limits = resolveRepositoryLimits({
         ...options?.repository,
@@ -100,10 +130,15 @@ export function createRepoSearchTool(cwd, options) {
         exclude: options?.exclude ?? options?.repository?.exclude,
     });
     const ops = options?.operations ?? createLocalRepositoryOperations(limits);
+    const modes = validateModes(options?.modes);
+    const modeDescriptions = modes.map((m) => (m === "literal" ? "literal substring match only" : INDEX_MODE_LABEL[m])).join("; ");
+    const indexedEnabled = modes.some((m) => m !== "literal");
     return {
         name: "repo_search",
         effect: CODING_OBSERVATION_EFFECT,
-        description: `Search text files under the workspace using literal substring match. Use outputMode "files_with_matches" for paths only or "count" for totals without line bodies. Skips binary files, excluded basenames (default: ${limits.exclude.join(", ")}), and hidden names unless includeHidden is true. Does not follow symlinks. Caps matches/scanned bytes/time.`,
+        description: indexedEnabled
+            ? `Search text files under the workspace. Modes: ${modeDescriptions}. Index results are untrusted host index output and may be stale; verify before mutation. Skips binary files and excluded basenames (default: ${limits.exclude.join(", ")}). Caps matches/scanned bytes/time.`
+            : `Search text files under the workspace using literal substring match. Use outputMode "files_with_matches" for paths only or "count" for totals without line bodies. Skips binary files, excluded basenames (default: ${limits.exclude.join(", ")}), and hidden names unless includeHidden is true. Does not follow symlinks. Caps matches/scanned bytes/time.`,
         parameters: {
             type: "object",
             properties: {
@@ -114,8 +149,8 @@ export function createRepoSearchTool(cwd, options) {
                 },
                 mode: {
                     type: "string",
-                    description: "Search mode: literal substring match only",
-                    enum: ["literal"],
+                    description: `Search mode: ${modeDescriptions}`,
+                    enum: [...modes],
                 },
                 caseSensitive: {
                     type: "boolean",
@@ -153,10 +188,10 @@ export function createRepoSearchTool(cwd, options) {
             if (args.mode === "regex") {
                 return errorResult(toolCallId, 'repo_search no longer supports mode "regex"; use literal substring search.');
             }
-            if (args.mode !== undefined && args.mode !== "literal") {
-                return errorResult(toolCallId, `unsupported search mode: ${String(args.mode)}`);
+            if (args.mode !== undefined && !modes.includes(args.mode)) {
+                return errorResult(toolCallId, `unsupported search mode: ${String(args.mode)} (enabled: ${modes.join(", ")})`);
             }
-            const mode = "literal";
+            const mode = (args.mode ?? "literal");
             let outputMode;
             try {
                 outputMode = parseOutputMode(args.outputMode);

package/dist/workspace-lifecycle.d.ts

@@ -0,0 +1,153 @@
+import type { ArtifactReference, GitOperations } from "./git.js";
+/** Separate versioned namespace: never collides with coding checkpoint v1 keys. */
+export declare const WORKSPACE_NAMESPACE: "prism.coding-agent.workspace.v1";
+export declare const WORKSPACE_SCHEMA_VERSION: 1;
+export declare const WORKSPACE_LOCK_REASON_PREFIX: "prism-workspace:";
+/** Frozen workspace state machine: active | cleaning | closed | unknown. */
+export type WorkspaceState = "active" | "cleaning" | "closed" | "unknown";
+export declare const WORKSPACE_STATES: readonly WorkspaceState[];
+export type WorkspaceRepositoryState = "active" | "removed" | "unknown";
+export type WorkspaceErrorCode = "ERR_PRISM_WORKSPACE_UNKNOWN" | "ERR_PRISM_WORKSPACE_LIMIT" | "ERR_PRISM_WORKSPACE_OWNERSHIP" | "ERR_PRISM_WORKSPACE_FENCE" | "ERR_PRISM_WORKSPACE_DIRTY" | "ERR_PRISM_WORKSPACE_LOCKED" | "ERR_PRISM_WORKSPACE_MAIN" | "ERR_PRISM_WORKSPACE_PATH_ESCAPE" | "ERR_PRISM_WORKSPACE_FINGERPRINT";
+export declare class WorkspaceError extends Error {
+    readonly code: WorkspaceErrorCode;
+    constructor(code: WorkspaceErrorCode, message: string);
+}
+/** Host-approved repository registration; `git` must be cwd-bound to `root`. */
+export interface WorkspaceRepositoryRegistration {
+    readonly root: string;
+    readonly git: GitOperations;
+}
+/** Durable per-repository leg of a workspace record. */
+export interface WorkspaceRepositoryRecord {
+    readonly repositoryId: string;
+    /** Canonical absolute root; the main worktree is immutable. */
+    readonly root: string;
+    /** Credential-free remote fingerprint (sha256 hex), never a URL. */
+    readonly remoteFingerprint: string;
+    readonly defaultBranch?: string;
+    readonly branch: string;
+    /** Branch base at create time. */
+    readonly base: string;
+    /** Verified head at create/last verify. */
+    readonly head: string;
+    readonly worktreeId: string;
+    readonly worktreePath: string;
+    readonly state: WorkspaceRepositoryState;
+    readonly createdAt: string;
+}
+/** Durable workspace record (schemaVersion 1, namespace WORKSPACE_NAMESPACE). */
+export interface CodingWorkspaceRecord {
+    readonly schemaVersion: typeof WORKSPACE_SCHEMA_VERSION;
+    readonly workspaceId: string;
+    readonly taskId: string;
+    readonly ownerId: string;
+    readonly state: WorkspaceState;
+    readonly repositories: readonly WorkspaceRepositoryRecord[];
+    /** Artifact references only; never artifact contents or credentials. */
+    readonly artifactRefs: readonly ArtifactReference[];
+    /** Lease fencing token at last mutation; monotonic per record. */
+    readonly fencingToken: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly cleanupAt?: string;
+}
+export interface WorkspaceCreateRequest {
+    readonly taskId: string;
+    readonly repositories: readonly {
+        readonly repositoryId: string;
+        readonly branch: string;
+    }[];
+    readonly artifactRefs?: readonly ArtifactReference[];
+    readonly signal?: AbortSignal;
+}
+/** Host policy gates the documented cleanup refusals; all default to refuse. */
+export interface WorkspaceCleanupPolicy {
+    /** Allow forced removal of dirty worktrees (potential data loss). */
+    readonly allowDirtyCleanup?: boolean;
+    /** Allow unlocking worktrees locked by an external actor. */
+    readonly allowLockedCleanup?: boolean;
+    /** Allow claiming a missing worktree as removed. */
+    readonly allowMissingCleanup?: boolean;
+    /** Allow unclaiming a path that exists but is not a registered worktree. */
+    readonly allowUnownedCleanup?: boolean;
+    /** Allow forced removal when the worktree head no longer matches the record. */
+    readonly allowMismatchedCleanup?: boolean;
+}
+export interface WorkspaceLimitOptions {
+    readonly maxRepositories?: number;
+    readonly maxWorktrees?: number;
+    readonly maxRecordBytes?: number;
+    readonly leaseTtlMs?: number;
+    readonly maxCleanupOperations?: number;
+}
+export interface ResolvedWorkspaceLimits {
+    readonly maxRepositories: number;
+    readonly maxWorktrees: number;
+    readonly maxRecordBytes: number;
+    readonly leaseTtlMs: number;
+    readonly maxCleanupOperations: number;
+}
+export declare function resolveWorkspaceLimits(options?: WorkspaceLimitOptions): ResolvedWorkspaceLimits;
+export interface CreateCodingWorkspaceLifecycleOptions {
+    readonly checkpoints: import("@arnilo/prism").CheckpointStore;
+    readonly leases: import("@arnilo/prism").LeaseStore;
+    /** Replica/worker identity; part of the fencing trust boundary. */
+    readonly ownerId: string;
+    readonly ownership?: import("@arnilo/prism").OwnershipScope;
+    /** Host-approved repositories keyed by repositoryId. */
+    readonly repositories: Readonly<Record<string, WorkspaceRepositoryRegistration>>;
+    /** Host-approved linked-worktree destination roots (canonicalized). */
+    readonly worktreeRoots: readonly string[];
+    readonly policy?: WorkspaceCleanupPolicy;
+    readonly limits?: WorkspaceLimitOptions;
+}
+export interface CodingWorkspaceLifecycle {
+    /**
+     * Create linked worktrees for a task and persist the workspace record.
+     * Idempotent: an identical active record returns as-is (no Git mutation).
+     * Stale or conflicting workers fail with ERR_PRISM_WORKSPACE_FENCE.
+     */
+    create(request: WorkspaceCreateRequest): Promise<CodingWorkspaceRecord>;
+    get(input: {
+        readonly taskId: string;
+        readonly signal?: AbortSignal;
+    }): Promise<CodingWorkspaceRecord | null>;
+    list(input?: {
+        readonly cursor?: string;
+        readonly limit?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<{
+        readonly items: readonly CodingWorkspaceRecord[];
+        readonly nextCursor?: string;
+    }>;
+    /**
+     * Resume gate: revalidates repository/worktree identity and fingerprints
+     * (root containment, worktree presence, head, remote/default-branch) before
+     * tools, processes, index results, patches, or artifacts are reused.
+     */
+    verify(input: {
+        readonly taskId: string;
+        readonly signal?: AbortSignal;
+    }): Promise<CodingWorkspaceRecord>;
+    attachArtifacts(input: {
+        readonly taskId: string;
+        readonly artifactRefs: readonly ArtifactReference[];
+        readonly signal?: AbortSignal;
+    }): Promise<CodingWorkspaceRecord>;
+    /**
+     * Remove owned linked worktrees and close the record. Refuses dirty, locked,
+     * unowned, missing, or mismatched trees unless the host policy allows the
+     * documented action; partial failure persists state `unknown` and remains
+     * reconcilable by retrying.
+     */
+    cleanup(input: {
+        readonly taskId: string;
+        readonly signal?: AbortSignal;
+    }): Promise<CodingWorkspaceRecord>;
+    /** Delete the durable record (no Git mutation); false when absent. */
+    remove(input: {
+        readonly taskId: string;
+        readonly signal?: AbortSignal;
+    }): Promise<boolean>;
+}
+export declare function createCodingWorkspaceLifecycle(options: CreateCodingWorkspaceLifecycleOptions): CodingWorkspaceLifecycle;