Approval as Data, Reach as Its Own Axis

// The approval layer: the app's own permission handler and the policy that
// decides which tools ask.
//
// Up to module 38 every session ran under permissionMode: 'dontAsk', a tool
// that was not pre-approved was denied and nobody was asked, because there was
// nobody to ask. This module builds the surface to ask, and the callback is
// here.
//
// The one new idea is that "can write" and "can reach the network" are two
// different axes. A read-only tool that fetches a web page has written nothing
//, and the page it read can tell it to go looking, so reading the network is
// egress-adjacent in a way reading a local file is not. That is why WebFetch
// and WebSearch are not on the silent list even though they only read.

import path from "node:path";
import { MAIL_TOOL_NAMES } from "./agent-mail.js";

// ... the secret-shaped content two-list (SECRET_DENY / SECRET_SAFE) omitted, 
//     record 0155: same two-list shape, one level down, flags but never blocks.

// The safe-list of path shapes that are legitimately outside the workspace.
//
// Empty, and that is the decision rather than an omission. In this module a
// model has no legitimate write outside the workspace, so nothing is exempt.
// The list is kept, empty, because the content guard above uses the same
// two-list shape with a populated safe-list, and a later module that let a
// model write its own notes would add this list's first entry rather than
// inventing the mechanism then. Record 0154.
const PATH_SAFE = Object.freeze([]);

// A write whose resolved path escapes the workspace is denied here, before any
// approval. The deny-list is "any write outside the workspace"; PATH_SAFE (the
// empty safe-list) would exempt a legitimate outside path if one existed.
export function guardWrite(toolName, input, workspaceDir) {
if (!PATH_WRITE_TOOLS.includes(toolName)) return { escapes: false };
// ... pull the first present path field off the input ...
const resolved = path.isAbsolute(raw)
  ? path.resolve(raw)
  : path.resolve(workspaceDir, raw);
if (isInside(workspaceDir, resolved)) return { escapes: false };
if (PATH_SAFE.some((exempt) => exempt(resolved))) return { escapes: false };
return {
  escapes: true,
  reason: `${toolName} to ${raw} escapes the workspace`,
};
}

// The word or recipient the person must type to confirm an outbound tool.
// WebFetch names a host to type; WebSearch has none, so the person types a
// fixed word instead. An unparseable URL falls back to the fixed word rather
// than throwing. Record 0153.
export function requiredTypedFor(toolName, input) {
if (toolName === "WebFetch") {
  try {
    const host = new URL(input.url).host;
    return host === "" ? CONFIRM_WORD : host;
  } catch {
    return CONFIRM_WORD;
  }
}
return CONFIRM_WORD;
}

// Build the canUseTool callback for one conversation. The SDK calls it before
// each tool runs, with the tool's name and input. Verified against
// @anthropic-ai/claude-agent-sdk 0.3.251, sdk.d.ts: canUseTool is
// (toolName, input, options) => Promise<PermissionResult | null>; returning
// null blocks the tool with no deadline, so this callback never does.
export function makeCanUseTool({ config, agent, emit, currentId, approvals }) {
return async function canUseTool(toolName, input) {
  try {
    const messageId = currentId();
    if (messageId === null) {
      return {
        behavior: "deny",
        message: `${toolName}: no message in flight`,
      };
    }

    // 1. The write guard, before any approval. Record 0154.
    const guard = guardWrite(toolName, input, config.workspaceDir);
    if (guard.escapes) return { behavior: "deny", message: guard.reason };

    // 2. The app's own mail tools. Cross-agent but not outbound: mail lands
    //    in another conversation on this same connection, so it never leaves
    //    the machine and never becomes a card. Record 0149.
    if (MAIL_TOOL_NAMES.includes(toolName)) {
      return { behavior: "allow", updatedInput: input };
    }

    // 3. The silent list. Read-shaped tools, allowed with no frame. WebFetch
    //    and WebSearch are NOT here even though they only read,
    //    because reading the network is egress-adjacent. Record 0148.
    if (config.silentTools.includes(toolName)) {
      return { behavior: "allow", updatedInput: input };
    }

    // 4. AskUserQuestion is a question, not an action. Record 0151.
    if (toolName === ASK_USER_QUESTION) {
      return await ask({ kind: "question", toolName, input, messageId });
    }

    // 5. Everything else asks a person. Outbound tools demand a typed word.
    return await ask({ kind: "approval", toolName, input, messageId });
  } catch (cause) {
    // Never null: a concrete deny refuses the one tool and lets the turn go
    // on, where a null would block it forever.
    return { behavior: "deny", message: `approval check failed: ${cause}` };
  }
};

// Emit the frame, park on the registry, and turn the answer into a result.
async function ask({ kind, toolName, input, messageId }) {
  // ... the AskUserQuestion branch omitted, record 0151: the answer rides
  //     back as a deny message the model reads as the person's reply ...

  const outbound = config.outboundTools.includes(toolName);
  const required = outbound ? requiredTypedFor(toolName, input) : null;
  const { askId, outcome } = approvals.open({
    kind: "approval",
    messageId,
    validate: (payload) =>
      payload.choice === "allow" || payload.choice === "deny"
        ? {
            ok: true,
            value: { choice: payload.choice, typed: payload.typed },
          }
        : { ok: false, message: 'choice must be "allow" or "deny"' },
  });
  emit({
    type: "approval",
    id: messageId,
    approvalId: askId,
    agentId: agent.agentId,
    tool: toolName,
    summary: approvalSummary(toolName, input, { outbound, required }),
    // The two-axis signal as explicit frame fields: a client renders the
    // typed-confirmation input off `outbound`, and compares nothing itself
    //, `confirm` is the word to type, and the server is what checks it.
    ...(outbound ? { outbound: true, confirm: required } : {}),
  });

  const answer = await outcome;
  if (answer.status !== "answered") {
    return { behavior: "deny", message: "denied: timed out or turn ended" };
  }
  if (answer.choice === "deny") {
    return { behavior: "deny", message: `${toolName} was denied` };
  }
  // An allow of an outbound tool is only an allow when the typed word matches.
  if (outbound && answer.typed !== required) {
    return {
      behavior: "deny",
      message:
        `${toolName} is outbound and the ` +
        `typed confirmation ${required} did not match; denied.`,
    };
  }
  return { behavior: "allow", updatedInput: input };
}
}

// The tools admitted with no approval card: the read-shaped ones.
//
// Data, not logic, because docs/PROTOCOL.md says so: "Which tools are silent
// and which are outbound is the server's policy, stated in its config as data,
// not scattered as rules." A frozen list canUseTool reads by membership.
//
// Three tools, and only three. Read, Glob and Grep observe the
// filesystem and change nothing. WebFetch and WebSearch are pointedly not here
// even though they only read: reading the network is egress-adjacent. That is
// this module's one new idea, and record 0148 is the argument.
export const SILENT_TOOLS = Object.freeze(["Read", "Glob", "Grep"]);

// The tools that can move something off this machine: the outbound ones.
//
// An outbound tool is not merely asked about, it demands a typed confirmation,
// because the harm it can do is exfiltration and a person clicking "allow" by
// reflex is exactly the failure typed confirmation exists to slow down.
//
// send_to_agent is not here. It is cross-agent, it writes into another agent's
// queue, but that queue is on this connection, in this process; mail cannot
// leave the machine, so it is not outbound in the exfiltration sense. Record 0149.
export const OUTBOUND_TOOLS = Object.freeze(["WebFetch", "WebSearch"]);