zob-harness 0.16.0 → 0.17.0

package/.pi/capabilities/zob-public-runtime-capabilities.json

@@ -1129,6 +1129,46 @@
       ],
       "noShipNotes": "Readiness check only."
     },
+    {
+      "name": "zob_read_full",
+      "family": "files",
+      "modes": [
+        "explore",
+        "plan",
+        "implement",
+        "oracle",
+        "factory",
+        "orchestrator"
+      ],
+      "skillRefs": [
+        ".pi/skills/zob-file-read/SKILL.md"
+      ],
+      "docRefs": [
+        ".pi/extensions/zob-harness/src/AGENTS.md",
+        "README.md"
+      ],
+      "noShipNotes": "Whole-file read only; returns content iff path passes secret/generated-path safety, the file is a readable utf8 regular file under the hard byte ceiling, and (when the context window is known) estimated tokens fit the context headroom (allowedTokens = min(availableTokens*(1-safetyMargin/100), contextWindow*0.5)); otherwise blocks with pagination guidance and no content. Never reads .env/~/.ssh/~/.aws/*.pem/*.key (including via symlinks, blocked as symlink_resolves_to_zero_access after realpath canonicalization), node_modules, dist, build, .pi/sessions, .pi/agent-sessions; v1 utf8 only (non-utf8 -> binary_not_supported); telemetry is body-free (details carry hashes/counts only, bodyStored:false); does not bypass the file-tool preflight or other safety gates."
+    },
+    {
+      "name": "zob_receive_full",
+      "family": "files",
+      "modes": [
+        "explore",
+        "plan",
+        "implement",
+        "oracle",
+        "factory",
+        "orchestrator"
+      ],
+      "skillRefs": [
+        ".pi/skills/zob-file-read/SKILL.md"
+      ],
+      "docRefs": [
+        ".pi/extensions/zob-harness/src/AGENTS.md",
+        "README.md"
+      ],
+      "noShipNotes": "Long-response receive only; returns content iff exactly one source is provided (path or run_id) and the resolved target passes the shared file-tool preflight path/secret safety (lexical zero-access + realpath symlink check inherited from zob_read_full's runFullRead), is a readable utf8 regular file under the hard byte ceiling, and (when the context window is known) estimated tokens fit the context headroom (allowedTokens = min(availableTokens*(1-safetyMargin/100), contextWindow*0.5)); otherwise blocks with recovery guidance and no content. run_id resolves ONLY to a run's persisted report artifact under reports/factory-runs|orchestrations|chains/<runId>/ (default final-report.md, or a named single-basename artifact) — raw child output bodies are NOT persisted (body-free harness) and cannot be retrieved; run_id and artifact are validated path-safe (alphanumeric/.//- only, no slashes or ..) before any resolution, refusing run_id_unsafe/artifact_unsafe/run_not_found/artifact_not_found. max_bytes tightens the 2MB ceiling only (cannot enlarge). Telemetry is body-free (details carry hashes/counts/source metadata only, bodyStored:false); does not bypass the file-tool preflight or other safety gates."
+    },
     {
       "name": "zob_context_validate_scope",
       "family": "context",

package/.pi/extensions/zob-harness/index.ts

@@ -688,6 +688,52 @@ export type {
   FileToolPreflightVerdict,
 } from "./src/domains/governance/file-tool-preflight.js";
 
+export {
+  FULL_READ_DEFAULT_IO,
+  FULL_READ_DEFAULT_POLICY,
+  FULL_READ_SCHEMA,
+  classifyPathForbiddenGenerated,
+  classifyPathSecret,
+  evaluateFullRead,
+  fullReadBodyFreeViolations,
+  runFullRead,
+} from "./src/domains/files/full-read.js";
+export type {
+  FullReadContextUsage,
+  FullReadDecision,
+  FullReadDetails,
+  FullReadEncoding,
+  FullReadEvaluation,
+  FullReadFacts,
+  FullReadIo,
+  FullReadPolicy,
+  FullReadReasonCode,
+  FullReadRunInput,
+  FullReadRunResult,
+  FullReadStat,
+} from "./src/domains/files/full-read.js";
+
+export {
+  DEFAULT_RUN_ARTIFACT,
+  RESPONSE_RECEIVE_SCHEMA,
+  RUN_ARTIFACT_DIRS,
+  isPathSafeArtifactName,
+  isPathSafeRunId,
+  receiveFullResponse,
+  resolveRunArtifact,
+  responseReceiveBodyFreeViolations,
+  runDirRelative,
+} from "./src/domains/files/response-receive.js";
+export type {
+  ResponseReceiveDetails,
+  ResponseReceiveInput,
+  ResponseReceiveReasonCode,
+  ResponseReceiveResult,
+  ResponseReceiveRunType,
+  ResponseReceiveSource,
+  RunArtifactResolution,
+} from "./src/domains/files/response-receive.js";
+
 export {
   validateSandboxWritePlanInputs,
   runSandboxWritePlan,

package/.pi/extensions/zob-harness/src/core/constants.ts

@@ -59,6 +59,7 @@ export const ZOB_DELEGATION_READ_TOOLS = ["zob_delegation_catalog", "get_delegat
 export const ZOB_MISSION_CONTROL_READ_TOOLS = ["zob_coms_readiness", "zob_mission_control_snapshot"] as const;
 export const ZOB_MISSION_CONTROL_PROPOSAL_TOOLS = ["zob_mission_control_propose_command"] as const;
 export const ZOB_CONTEXT_READ_TOOLS = ["zob_context_search", "zob_context_readiness", "zob_context_validate_scope"] as const;
+export const ZOB_FILES_READ_TOOLS = ["zob_read_full", "zob_receive_full"] as const;
 export const ZOB_CONTEXT_PROPOSAL_TOOLS = ["zob_context_writeback_proposal"] as const;
 export const ZOB_COMPUTE_READ_TOOLS = ["zob_compute_preview", "zob_compute_resolve_profile", "zob_compute_plan_workflow", "zob_compute_validate_profile"] as const;
 export const ZOB_COMPUTE_REPORT_TOOLS = ["zob_compute_write_profile_reports"] as const;
@@ -70,12 +71,12 @@ export const ZOB_AUTONOMOUS_READ_TOOLS = ["zob_autonomous_validate_run", "zob_au
 export const ZOB_AUTONOMOUS_FACTORY_TOOLS = ["zob_autonomous_dry_run", "zob_autonomous_readonly_smoke"] as const;
 
 export const MODE_TOOLS: Record<ModeName, string[]> = {
-  explore: ["read", "grep", "find", "ls", "bash", "delegate_agent", "delegate_task", "zob_coms_list", "zob_coms_get", "zob_coms_await", "zpeer_ask", "zpeer_reply", "zob_goal_room_list", "zob_workspace_claims_list", "zob_worker_pool_status", "zob_merge_queue_list", ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_AUTONOMOUS_READ_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS],
-  plan: ["read", "grep", "find", "ls", "delegate_agent", "delegate_task", "orchestrate_run", "chain_run", ...ZOB_PLAN_LAUNCH_TOOLS, ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_ZAGENT_TOOLS, ...ZOB_COMS_TOOLS, ...ZOB_GOAL_ROOM_TOOLS, ...ZOB_GOVERNED_REQUEST_TOOLS, ...ZOB_WORKSPACE_CLAIM_TOOLS, ...ZOB_WORKER_POOL_TOOLS, ...ZOB_MERGE_QUEUE_TOOLS, ...ZOB_WORKLIST_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_MISSION_CONTROL_PROPOSAL_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_CONTEXT_PROPOSAL_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_COMPUTE_REPORT_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS, ...ZOB_PROJECT_DNA_PROPOSAL_TOOLS],
-  implement: ["read", "bash", "edit", "write", "grep", "find", "ls", "delegate_agent", "delegate_task", ...ZOB_PLAN_LAUNCH_TOOLS, ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_ZAGENT_TOOLS, ...ZOB_COMS_TOOLS, ...ZOB_GOAL_ROOM_TOOLS, ...ZOB_GOVERNED_REQUEST_TOOLS, ...ZOB_WORKSPACE_CLAIM_TOOLS, ...ZOB_WORKER_POOL_TOOLS, ...ZOB_MERGE_QUEUE_TOOLS, ...ZOB_WORKLIST_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_MISSION_CONTROL_PROPOSAL_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_CONTEXT_PROPOSAL_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_COMPUTE_REPORT_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS, ...ZOB_PROJECT_DNA_PROPOSAL_TOOLS],
-  oracle: ["read", "grep", "find", "ls", "bash", "delegate_agent", "delegate_task", "zob_coms_list", "zob_coms_get", "zob_coms_await", "zpeer_ask", "zpeer_reply", "zob_goal_room_list", "zob_workspace_claims_list", "zob_worker_pool_status", "zob_merge_queue_list", ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_AUTONOMOUS_READ_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS],
-  orchestrator: ["read", "grep", "find", "ls", "delegate_agent", "delegate_task", "orchestrate_run", "chain_run", ...ZOB_PLAN_LAUNCH_TOOLS, ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_ZAGENT_TOOLS, ...ZOB_COMS_TOOLS, ...ZOB_GOAL_ROOM_TOOLS, ...ZOB_GOVERNED_REQUEST_TOOLS, ...ZOB_WORKSPACE_CLAIM_TOOLS, ...ZOB_WORKER_POOL_TOOLS, ...ZOB_MERGE_QUEUE_TOOLS, ...ZOB_WORKLIST_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_MISSION_CONTROL_PROPOSAL_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_CONTEXT_PROPOSAL_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_COMPUTE_REPORT_TOOLS],
-  factory: ["read", "bash", "edit", "write", "grep", "find", "ls", "delegate_agent", "delegate_task", "orchestrate_run", "factory_run", "factory_quarantine_review", "factory_quarantine_activate", "factory_quarantine_verify_activation", "chain_run", ...ZOB_PLAN_LAUNCH_TOOLS, ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_ZAGENT_TOOLS, ...ZOB_AUTONOMOUS_READ_TOOLS, ...ZOB_AUTONOMOUS_FACTORY_TOOLS, ...ZOB_COMS_TOOLS, ...ZOB_GOAL_ROOM_TOOLS, ...ZOB_GOVERNED_REQUEST_TOOLS, ...ZOB_WORKSPACE_CLAIM_TOOLS, ...ZOB_WORKER_POOL_TOOLS, ...ZOB_MERGE_QUEUE_TOOLS, ...ZOB_WORKLIST_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_MISSION_CONTROL_PROPOSAL_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_CONTEXT_PROPOSAL_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_COMPUTE_REPORT_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS, ...ZOB_PROJECT_DNA_PROPOSAL_TOOLS],
+  explore: ["read", "grep", "find", "ls", "bash", "delegate_agent", "delegate_task", "zob_coms_list", "zob_coms_get", "zob_coms_await", "zpeer_ask", "zpeer_reply", "zob_goal_room_list", "zob_workspace_claims_list", "zob_worker_pool_status", "zob_merge_queue_list", ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_AUTONOMOUS_READ_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_FILES_READ_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS],
+  plan: ["read", "grep", "find", "ls", "delegate_agent", "delegate_task", "orchestrate_run", "chain_run", ...ZOB_PLAN_LAUNCH_TOOLS, ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_ZAGENT_TOOLS, ...ZOB_COMS_TOOLS, ...ZOB_GOAL_ROOM_TOOLS, ...ZOB_GOVERNED_REQUEST_TOOLS, ...ZOB_WORKSPACE_CLAIM_TOOLS, ...ZOB_WORKER_POOL_TOOLS, ...ZOB_MERGE_QUEUE_TOOLS, ...ZOB_WORKLIST_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_MISSION_CONTROL_PROPOSAL_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_FILES_READ_TOOLS, ...ZOB_CONTEXT_PROPOSAL_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_COMPUTE_REPORT_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS, ...ZOB_PROJECT_DNA_PROPOSAL_TOOLS],
+  implement: ["read", "bash", "edit", "write", "grep", "find", "ls", "delegate_agent", "delegate_task", ...ZOB_PLAN_LAUNCH_TOOLS, ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_ZAGENT_TOOLS, ...ZOB_COMS_TOOLS, ...ZOB_GOAL_ROOM_TOOLS, ...ZOB_GOVERNED_REQUEST_TOOLS, ...ZOB_WORKSPACE_CLAIM_TOOLS, ...ZOB_WORKER_POOL_TOOLS, ...ZOB_MERGE_QUEUE_TOOLS, ...ZOB_WORKLIST_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_MISSION_CONTROL_PROPOSAL_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_FILES_READ_TOOLS, ...ZOB_CONTEXT_PROPOSAL_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_COMPUTE_REPORT_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS, ...ZOB_PROJECT_DNA_PROPOSAL_TOOLS],
+  oracle: ["read", "grep", "find", "ls", "bash", "delegate_agent", "delegate_task", "zob_coms_list", "zob_coms_get", "zob_coms_await", "zpeer_ask", "zpeer_reply", "zob_goal_room_list", "zob_workspace_claims_list", "zob_worker_pool_status", "zob_merge_queue_list", ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_AUTONOMOUS_READ_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_FILES_READ_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS],
+  orchestrator: ["read", "grep", "find", "ls", "delegate_agent", "delegate_task", "orchestrate_run", "chain_run", ...ZOB_PLAN_LAUNCH_TOOLS, ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_ZAGENT_TOOLS, ...ZOB_COMS_TOOLS, ...ZOB_GOAL_ROOM_TOOLS, ...ZOB_GOVERNED_REQUEST_TOOLS, ...ZOB_WORKSPACE_CLAIM_TOOLS, ...ZOB_WORKER_POOL_TOOLS, ...ZOB_MERGE_QUEUE_TOOLS, ...ZOB_WORKLIST_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_MISSION_CONTROL_PROPOSAL_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_FILES_READ_TOOLS, ...ZOB_CONTEXT_PROPOSAL_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_COMPUTE_REPORT_TOOLS],
+  factory: ["read", "bash", "edit", "write", "grep", "find", "ls", "delegate_agent", "delegate_task", "orchestrate_run", "factory_run", "factory_quarantine_review", "factory_quarantine_activate", "factory_quarantine_verify_activation", "chain_run", ...ZOB_PLAN_LAUNCH_TOOLS, ...ZOB_RUNTIME_GOAL_TOOLS, ...ZOB_DELEGATION_READ_TOOLS, ...ZOB_ZCOMMIT_TOOLS, ...ZOB_ZAGENT_TOOLS, ...ZOB_AUTONOMOUS_READ_TOOLS, ...ZOB_AUTONOMOUS_FACTORY_TOOLS, ...ZOB_COMS_TOOLS, ...ZOB_GOAL_ROOM_TOOLS, ...ZOB_GOVERNED_REQUEST_TOOLS, ...ZOB_WORKSPACE_CLAIM_TOOLS, ...ZOB_WORKER_POOL_TOOLS, ...ZOB_MERGE_QUEUE_TOOLS, ...ZOB_WORKLIST_TOOLS, ...ZOB_MISSION_CONTROL_READ_TOOLS, ...ZOB_MISSION_CONTROL_PROPOSAL_TOOLS, ...ZOB_CONTEXT_READ_TOOLS, ...ZOB_FILES_READ_TOOLS, ...ZOB_CONTEXT_PROPOSAL_TOOLS, ...ZOB_COMPUTE_READ_TOOLS, ...ZOB_COMPUTE_REPORT_TOOLS, ...ZOB_PROJECT_DNA_READ_TOOLS, ...ZOB_PROJECT_DNA_PROPOSAL_TOOLS],
   // Vanilla is handled specially by applyMode: all currently available Pi tools are enabled.
   vanilla: [],
 };

package/.pi/extensions/zob-harness/src/domains/files/full-read.ts

@@ -0,0 +1,488 @@
+import { accessSync, constants as fsConstants, readFileSync, realpathSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { DEFAULT_RULES } from "../../core/constants.js";
+import { sha256Hex } from "../../core/utils/hashing.js";
+import { pathMatches } from "../../core/utils/paths.js";
+
+/**
+ * `full-read.ts` is the PURE context-window-aware decision module for the future
+ * `zob_read_full` tool. It decides whether an entire file may be returned in one
+ * call given the live model context window, refusing with pagination guidance
+ * (block `exceeds_context_budget` / `exceeds_hard_ceiling`) when there is not
+ * enough headroom. All decision logic is pure over an injected `io` + `usage`;
+ * the only `node:fs` use lives in `FULL_READ_DEFAULT_IO`.
+ *
+ * Telemetry is body-free: `FullReadDetails` never carries file content, only
+ * hashes, byte/token counts, and policy echoes (`bodyStored: false`).
+ */
+
+export type FullReadDecision = "pass" | "block" | "observe";
+
+export type FullReadReasonCode =
+  | "full_read_pass"
+  | "context_unknown_fallback_pass"
+  | "path_not_found"
+  | "path_not_file"
+  | "path_secret_rejected"
+  | "path_forbidden_generated"
+  | "path_not_readable"
+  | "inspection_failed"
+  | "binary_not_supported"
+  | "exceeds_context_budget"
+  | "exceeds_hard_ceiling"
+  | "symlink_resolves_to_zero_access";
+
+export type FullReadEncoding = "utf8";
+
+export const FULL_READ_SCHEMA = "zob.full-read.v1";
+
+export interface FullReadContextUsage {
+  tokens?: number;
+  contextWindow?: number;
+  percent?: number;
+}
+
+export interface FullReadPolicy {
+  zeroAccessPaths: string[];
+  forbiddenGeneratedPaths: string[];
+  safetyMarginPercent: number;
+  maxAllowedContextFraction: number;
+  hardCeilingBytesDefault: number;
+}
+
+export const FULL_READ_DEFAULT_POLICY: FullReadPolicy = {
+  zeroAccessPaths: [...DEFAULT_RULES.zeroAccessPaths],
+  forbiddenGeneratedPaths: ["node_modules/", "dist/", "build/", ".pi/sessions/", ".pi/agent-sessions/"],
+  safetyMarginPercent: 30,
+  maxAllowedContextFraction: 0.5,
+  hardCeilingBytesDefault: 2 * 1024 * 1024,
+};
+
+export interface FullReadStat {
+  size: number;
+  isFile(): boolean;
+  isDirectory(): boolean;
+}
+
+export interface FullReadIo {
+  stat(path: string): FullReadStat;
+  accessReadable(path: string): void;
+  readFile(path: string): string;
+  realpath(path: string): string;
+}
+
+export interface FullReadFacts {
+  pathKind: "file" | "directory" | "other" | "missing";
+  isSecret: boolean;
+  isForbiddenGenerated: boolean;
+  binaryRequested: boolean;
+  readable: boolean;
+  byteSize: number;
+  estimatedTokens: number;
+  usage: FullReadContextUsage;
+}
+
+export interface FullReadEvaluation {
+  decision: FullReadDecision;
+  reasonCode: FullReadReasonCode;
+  contextKnown: boolean;
+  availableTokens?: number;
+  allowedTokens?: number;
+  hardCeilingBytes: number;
+}
+
+export interface FullReadDetails {
+  schema: typeof FULL_READ_SCHEMA;
+  decision: FullReadDecision;
+  reasonCode: FullReadReasonCode;
+  pathHash: string;
+  byteSize: number;
+  lineCount: number;
+  estimatedTokens: number;
+  contextWindow?: number;
+  contextTokensBefore?: number;
+  availableTokens?: number;
+  allowedTokens?: number;
+  safetyMarginPercent: number;
+  maxAllowedContextFraction: number;
+  hardCeilingBytes: number;
+  maxBytesOverride?: number;
+  contextKnown: boolean;
+  encoding: FullReadEncoding;
+  bodyStored: false;
+}
+
+export interface FullReadRunInput {
+  cwd: string;
+  path: string;
+  encoding?: string;
+  maxBytesOverride?: number;
+  usage: FullReadContextUsage;
+  policy: FullReadPolicy;
+  io: FullReadIo;
+  estimateTokens: (text: string) => number;
+}
+
+export interface FullReadRunResult {
+  decision: FullReadDecision;
+  reasonCode: FullReadReasonCode;
+  content?: string;
+  details: FullReadDetails;
+}
+
+const BODY_LIKE_FIELDS = new Set([
+  "body",
+  "prompt",
+  "output",
+  "command",
+  "path",
+  "pattern",
+  "oldtext",
+  "newtext",
+  "stderr",
+  "diff",
+  "patch",
+  "content",
+  "text",
+  "secret",
+  "token",
+  "password",
+  "credential",
+]);
+
+function errCode(error: unknown): string | undefined {
+  return typeof error === "object" && error !== null && "code" in error && typeof (error as { code?: unknown }).code === "string"
+    ? (error as { code: string }).code
+    : undefined;
+}
+
+function contextWindowKnown(usage: FullReadContextUsage): boolean {
+  return (
+    typeof usage.contextWindow === "number" &&
+    Number.isFinite(usage.contextWindow) &&
+    usage.contextWindow > 0 &&
+    typeof usage.tokens === "number" &&
+    Number.isFinite(usage.tokens) &&
+    usage.tokens >= 0
+  );
+}
+
+function resolveHardCeiling(policy: FullReadPolicy, maxBytesOverride?: number): number {
+  const ceiling = typeof maxBytesOverride === "number" && Number.isFinite(maxBytesOverride) && maxBytesOverride > 0
+    ? Math.min(Math.floor(maxBytesOverride), policy.hardCeilingBytesDefault)
+    : policy.hardCeilingBytesDefault;
+  return ceiling;
+}
+
+export function classifyPathSecret(targetPath: string, cwd: string, policy: FullReadPolicy): boolean {
+  return policy.zeroAccessPaths.some((pattern) => pathMatches(targetPath, pattern, cwd, cwd));
+}
+
+export function classifyPathForbiddenGenerated(targetPath: string, cwd: string, policy: FullReadPolicy): boolean {
+  return policy.forbiddenGeneratedPaths.some((pattern) => pathMatches(targetPath, pattern, cwd, cwd));
+}
+
+export function evaluateFullRead(facts: FullReadFacts, policy: FullReadPolicy, maxBytesOverride?: number): FullReadEvaluation {
+  const hardCeilingBytes = resolveHardCeiling(policy, maxBytesOverride);
+  const contextKnown = contextWindowKnown(facts.usage);
+
+  if (facts.isSecret) {
+    return { decision: "block", reasonCode: "path_secret_rejected", contextKnown, hardCeilingBytes };
+  }
+  if (facts.isForbiddenGenerated) {
+    return { decision: "block", reasonCode: "path_forbidden_generated", contextKnown, hardCeilingBytes };
+  }
+  if (facts.pathKind === "missing") {
+    return { decision: "block", reasonCode: "path_not_found", contextKnown, hardCeilingBytes };
+  }
+  if (facts.pathKind !== "file") {
+    return { decision: "block", reasonCode: "path_not_file", contextKnown, hardCeilingBytes };
+  }
+  if (facts.binaryRequested) {
+    return { decision: "block", reasonCode: "binary_not_supported", contextKnown, hardCeilingBytes };
+  }
+  if (!facts.readable) {
+    return { decision: "block", reasonCode: "path_not_readable", contextKnown, hardCeilingBytes };
+  }
+  if (facts.byteSize > hardCeilingBytes) {
+    return { decision: "block", reasonCode: "exceeds_hard_ceiling", contextKnown, hardCeilingBytes };
+  }
+
+  if (!contextKnown) {
+    return { decision: "observe", reasonCode: "context_unknown_fallback_pass", contextKnown: false, hardCeilingBytes };
+  }
+
+  const availableTokens = Math.max(0, Math.floor((facts.usage.contextWindow as number) - (facts.usage.tokens as number)));
+  const marginAllowed = Math.floor(availableTokens * (1 - policy.safetyMarginPercent / 100));
+  const fractionCap = Math.floor((facts.usage.contextWindow as number) * policy.maxAllowedContextFraction);
+  const allowedTokens = Math.max(0, Math.min(marginAllowed, fractionCap));
+
+  if (facts.estimatedTokens <= allowedTokens) {
+    return { decision: "pass", reasonCode: "full_read_pass", contextKnown: true, availableTokens, allowedTokens, hardCeilingBytes };
+  }
+  return { decision: "block", reasonCode: "exceeds_context_budget", contextKnown: true, availableTokens, allowedTokens, hardCeilingBytes };
+}
+
+function bodyLikeField(field: string): boolean {
+  const normalized = field.replace(/[^a-zA-Z0-9]/g, "").toLowerCase();
+  if (normalized === "bodystored" || normalized.endsWith("hash")) return false;
+  return BODY_LIKE_FIELDS.has(normalized) || (normalized.startsWith("raw") && BODY_LIKE_FIELDS.has(normalized.slice(3)));
+}
+
+export function fullReadBodyFreeViolations(value: unknown): string[] {
+  const violations: string[] = [];
+  const seen = new WeakSet<object>();
+
+  function visit(candidate: unknown, path: string): void {
+    if (typeof candidate !== "object" || candidate === null || seen.has(candidate)) return;
+    seen.add(candidate);
+    if (Array.isArray(candidate)) {
+      candidate.forEach((entry, index) => {
+        visit(entry, `${path}[${index}]`);
+      });
+      return;
+    }
+    for (const [field, entry] of Object.entries(candidate)) {
+      const fieldPath = `${path}.${field}`;
+      if (bodyLikeField(field)) violations.push(fieldPath);
+      visit(entry, fieldPath);
+    }
+  }
+
+  visit(value, "$");
+  return violations.sort();
+}
+
+function buildDetails(input: {
+  decision: FullReadDecision;
+  reasonCode: FullReadReasonCode;
+  pathHash: string;
+  byteSize: number;
+  lineCount: number;
+  estimatedTokens: number;
+  usage: FullReadContextUsage;
+  evaluation: FullReadEvaluation;
+  policy: FullReadPolicy;
+  encoding: FullReadEncoding;
+  maxBytesOverride?: number;
+}): FullReadDetails {
+  const details: FullReadDetails = {
+    schema: FULL_READ_SCHEMA,
+    decision: input.decision,
+    reasonCode: input.reasonCode,
+    pathHash: input.pathHash,
+    byteSize: input.byteSize,
+    lineCount: input.lineCount,
+    estimatedTokens: input.estimatedTokens,
+    safetyMarginPercent: input.policy.safetyMarginPercent,
+    maxAllowedContextFraction: input.policy.maxAllowedContextFraction,
+    hardCeilingBytes: input.evaluation.hardCeilingBytes,
+    contextKnown: input.evaluation.contextKnown,
+    encoding: input.encoding,
+    bodyStored: false,
+  };
+  if (typeof input.usage.contextWindow === "number" && Number.isFinite(input.usage.contextWindow)) {
+    details.contextWindow = input.usage.contextWindow;
+  }
+  if (typeof input.usage.tokens === "number" && Number.isFinite(input.usage.tokens)) {
+    details.contextTokensBefore = input.usage.tokens;
+  }
+  if (typeof input.evaluation.availableTokens === "number") {
+    details.availableTokens = input.evaluation.availableTokens;
+  }
+  if (typeof input.evaluation.allowedTokens === "number") {
+    details.allowedTokens = input.evaluation.allowedTokens;
+  }
+  if (typeof input.maxBytesOverride === "number") {
+    details.maxBytesOverride = input.maxBytesOverride;
+  }
+  return details;
+}
+
+function inspectionFailedResult(input: FullReadRunInput, pathHash: string, byteSize: number): FullReadRunResult {
+  const evaluation: FullReadEvaluation = {
+    decision: "block",
+    reasonCode: "inspection_failed",
+    contextKnown: contextWindowKnown(input.usage),
+    hardCeilingBytes: resolveHardCeiling(input.policy, input.maxBytesOverride),
+  };
+  const details = buildDetails({
+    decision: "block",
+    reasonCode: "inspection_failed",
+    pathHash,
+    byteSize,
+    lineCount: 0,
+    estimatedTokens: 0,
+    usage: input.usage,
+    evaluation,
+    policy: input.policy,
+    encoding: "utf8",
+    maxBytesOverride: input.maxBytesOverride,
+  });
+  return { decision: "block", reasonCode: "inspection_failed", details };
+}
+
+export function runFullRead(input: FullReadRunInput): FullReadRunResult {
+  const targetPath = resolve(input.cwd, input.path);
+  const pathHash = sha256Hex(targetPath);
+  const binaryRequested = !(input.encoding === "utf8" || input.encoding === undefined);
+  const encoding: FullReadEncoding = "utf8";
+  const isSecret = classifyPathSecret(targetPath, input.cwd, input.policy);
+  let isForbiddenGenerated = classifyPathForbiddenGenerated(targetPath, input.cwd, input.policy);
+
+  let pathKind: FullReadFacts["pathKind"] = "missing";
+  let readable = false;
+  let byteSize = 0;
+  let inspectionFailed = false;
+
+  try {
+    const stat = input.io.stat(targetPath);
+    pathKind = stat.isFile() ? "file" : stat.isDirectory() ? "directory" : "other";
+    byteSize = stat.size;
+    try {
+      input.io.accessReadable(targetPath);
+      readable = true;
+    } catch {
+      readable = false;
+    }
+  } catch (error) {
+    if (errCode(error) === "ENOENT") {
+      pathKind = "missing";
+      byteSize = 0;
+      readable = false;
+    } else {
+      inspectionFailed = true;
+    }
+  }
+
+  if (inspectionFailed) {
+    return inspectionFailedResult(input, pathHash, 0);
+  }
+
+  // Canonical-path zero-access check: realpath the target (this follows symlinks,
+  // unlike resolve) and re-run classifyPathSecret on the canonical path. This
+  // closes the symlink bypass where an in-cwd symlink to ~/.ssh/id_rsa or a .env
+  // would otherwise evade the lexical targetPath check. Runs for every existing
+  // path kind and BEFORE any readFile, mirroring file-tool-preflight's
+  // zeroAccessRealpathFailure.
+  if (pathKind !== "missing") {
+    let canonicalPath: string;
+    try {
+      canonicalPath = input.io.realpath(targetPath);
+    } catch {
+      return inspectionFailedResult(input, pathHash, byteSize);
+    }
+    const canonicalSecret = classifyPathSecret(canonicalPath, input.cwd, input.policy);
+    if (canonicalSecret && !isSecret) {
+      const canonicalEvaluation: FullReadEvaluation = {
+        decision: "block",
+        reasonCode: "symlink_resolves_to_zero_access",
+        contextKnown: contextWindowKnown(input.usage),
+        hardCeilingBytes: resolveHardCeiling(input.policy, input.maxBytesOverride),
+      };
+      const canonicalDetails = buildDetails({
+        decision: "block",
+        reasonCode: "symlink_resolves_to_zero_access",
+        pathHash,
+        byteSize,
+        lineCount: 0,
+        estimatedTokens: 0,
+        usage: input.usage,
+        evaluation: canonicalEvaluation,
+        policy: input.policy,
+        encoding,
+        maxBytesOverride: input.maxBytesOverride,
+      });
+      return { decision: "block", reasonCode: "symlink_resolves_to_zero_access", details: canonicalDetails };
+    }
+    isForbiddenGenerated = isForbiddenGenerated || classifyPathForbiddenGenerated(canonicalPath, input.cwd, input.policy);
+  }
+
+  // Pre-evaluate WITHOUT reading content. estimatedTokens is 0 here, which only
+  // matters for the budget branches — so any "block" from this pass is one of
+  // the safety/path-kind/binary/readable/hard-ceiling branches and must return
+  // immediately without touching file content.
+  const preliminaryFacts: FullReadFacts = {
+    pathKind,
+    isSecret,
+    isForbiddenGenerated,
+    binaryRequested,
+    readable,
+    byteSize,
+    estimatedTokens: 0,
+    usage: input.usage,
+  };
+  const preliminaryEvaluation = evaluateFullRead(preliminaryFacts, input.policy, input.maxBytesOverride);
+  if (preliminaryEvaluation.decision === "block") {
+    const details = buildDetails({
+      decision: preliminaryEvaluation.decision,
+      reasonCode: preliminaryEvaluation.reasonCode,
+      pathHash,
+      byteSize,
+      lineCount: 0,
+      estimatedTokens: 0,
+      usage: input.usage,
+      evaluation: preliminaryEvaluation,
+      policy: input.policy,
+      encoding,
+      maxBytesOverride: input.maxBytesOverride,
+    });
+    return { decision: preliminaryEvaluation.decision, reasonCode: preliminaryEvaluation.reasonCode, details };
+  }
+
+  let content: string;
+  try {
+    content = input.io.readFile(targetPath);
+  } catch {
+    return inspectionFailedResult(input, pathHash, byteSize);
+  }
+
+  const estimatedTokens = input.estimateTokens(content);
+  const lineCount = content === "" ? 0 : content.split("\n").length;
+
+  const facts: FullReadFacts = {
+    pathKind,
+    isSecret,
+    isForbiddenGenerated,
+    binaryRequested,
+    readable,
+    byteSize,
+    estimatedTokens,
+    usage: input.usage,
+  };
+  const evaluation = evaluateFullRead(facts, input.policy, input.maxBytesOverride);
+
+  const details = buildDetails({
+    decision: evaluation.decision,
+    reasonCode: evaluation.reasonCode,
+    pathHash,
+    byteSize,
+    lineCount,
+    estimatedTokens,
+    usage: input.usage,
+    evaluation,
+    policy: input.policy,
+    encoding,
+    maxBytesOverride: input.maxBytesOverride,
+  });
+
+  const result: FullReadRunResult = { decision: evaluation.decision, reasonCode: evaluation.reasonCode, details };
+  if (evaluation.decision === "pass" || evaluation.decision === "observe") {
+    result.content = content;
+  }
+  return result;
+}
+
+/**
+ * Default IO backed by `node:fs` synchronous helpers. The runtime tool (later
+ * slice) injects this unless tests pass an in-memory `FullReadIo`.
+ */
+export const FULL_READ_DEFAULT_IO: FullReadIo = {
+  stat: (path: string): FullReadStat => statSync(path) as FullReadStat,
+  accessReadable: (path: string): void => {
+    accessSync(path, fsConstants.R_OK);
+  },
+  readFile: (path: string): string => readFileSync(path, "utf8"),
+  realpath: (path: string): string => realpathSync(path),
+};