export type WorkDirErrorReason = "not_found" | "not_dir" | "subpath_escape";
/**
 * Thrown when a workspace directory is missing, is not a directory, or the
 * requested sub_path escapes the workspace root.
 * Callers can catch by `instanceof WorkDirError` and branch on `.reason`.
 */
export declare class WorkDirError extends Error {
    readonly reason: WorkDirErrorReason;
    readonly path: string;
    readonly detail?: string;
    constructor(resolvedPath: string, reason: WorkDirErrorReason, options?: {
        cause?: unknown;
        detail?: string;
    });
}
/**
 * Assert that a directory exists and is a directory.
 *
 * Graders that inspect files or run commands in the workspace should call
 * this before attempting any filesystem access.  Non-workspace graders
 * (output-contains, output-matches, tool-calls) do not need this check.
 *
 * @param detail - Optional context appended to the error message and stored on the error.
 */
export declare function assertWorkDirAccessible(workDir: string, detail?: string): Promise<void>;
/**
 * Resolve a grader's workdir. Allows for an optional subPath.
 *
 * @param subPath - a path underneath the workspace. Can use either / or \ as the path separator.
 */
export declare function resolveGraderWorkDir(workspace: string, subPath?: string): string;
/**
 * Resolve a relative destination under a managed base directory (e.g. the
 * per-trial assets dir), confined to that base. Accepts either slash style.
 * Rejects absolute paths and `..` traversal so a staged file can never escape
 * the managed base. Returns an absolute path.
 */
export declare function resolveAssetPath(baseAbs: string, ref: string): string;
/**
 * Where a file-reading grader should look for `relPath`, preferring an
 * out-of-workspace read root (e.g. `artifactDir`) over the graded `workDir`.
 *
 * Generalizes the `custom-metrics` lookup so any grader can honor the
 * `artifactDir`-first, `workDir`-fallback contract consistently:
 * - When `readRoot` is set and `strict`, the read root is authoritative — its
 *   path is returned unconditionally, so a missing file fails there instead of
 *   silently reading a stale workspace copy.
 * - When `readRoot` is set and not strict, the read-root path is used only if it
 *   is present; otherwise the lookup falls back to `workDir`.
 * - When `readRoot` is unset, `workDir` is used.
 *
 * `source` is a stable, non-path label for evidence messages.
 */
export declare function resolveGraderReadRoot(workDir: string, readRoot: string | undefined, strict: boolean, relPath: string): Promise<{
    path: string;
    root: string;
    source: "artifact dir" | "workspace";
}>;
/**
 * Validate the configured grader working directory and return its resolved path.
 * @param workspaceRoot - The absolute path to the root of the grader workspace.
 * @param subPath - Optional subpath within {@link workspaceRoot}.
 */
export declare function getAccessibleGraderWorkDir(workspaceRoot: string, subPath?: string): Promise<string>;
//# sourceMappingURL=workspace-guard.d.ts.map