@sema-agent/core 7.7.0 → 7.9.0

package/dist/core/write-protect.js

@@ -1,5 +1,5 @@
 import { isWinFormPath, writeTargetPath, isUncPath } from "../tools/fs/safety.js";
-import { PATH_CONFINABLE_WRITE_TOOLS } from "./runner/session-rule-policy.js";
+import { isProtectedWrite } from "./tool-registry.js";
 import { dataRootSpellings } from "./sensitive-path-policy.js";
 const freezeTable = (rows) => Object.freeze(rows.map((r) => Object.freeze(r)));
 export const WRITE_PROTECTED_DEFAULT_TABLE = freezeTable([
@@ -213,10 +213,11 @@ export function createWriteProtectionCheck(entries, opts) {
     const matcher = compileWriteProtection(entries, opts);
     if (matcher === undefined)
         return undefined;
-    return (toolName, args) => {
-        if (!PATH_CONFINABLE_WRITE_TOOLS.has(toolName))
+    return (toolName, args, face) => {
+        const call = { toolName, args, ...(face !== undefined ? { face } : {}) };
+        if (!isProtectedWrite(call))
             return null;
-        const path = writeTargetPath(toolName, args);
+        const path = writeTargetPath(call);
         if (typeof path !== "string" || path.length === 0)
             return null;
         return matcher.matchPath(path);

package/dist/engine/compaction/utils.d.ts

@@ -1,5 +1,11 @@
 import type { Message } from "../llm/index.js";
 import type { AgentMessage } from "../loop/types.js";
+/**
+ * design/388 A-18 — the FROZEN history table: tool names a persisted pre-rename transcript may still carry
+ * (the upstream trio and the pre-CC-name core trio), mapped to the path access the live definition declares.
+ * Never grows: a new name declares its access on the catalog instead. Registered with the name-table gate.
+ */
+export declare const DURABLE_HISTORY_NAMES: ReadonlyMap<string, "read" | "create" | "edit">;
 /** File paths touched by a session branch or compaction range. */
 export interface FileOperations {
     /** Files read but not necessarily modified. */

package/dist/engine/compaction/utils.js

@@ -2,6 +2,15 @@ import { normalizeLlmMessageContent } from "../harness/messages.js";
 import { sliceHeadSafe } from "../../core/surrogate-safe-slice.js";
 import { cutEnginePrefix, cutEngineSegments, flattenableUserText } from "../../core/untrusted-text.js";
 import { fileArgPath } from "../../tools/fs/safety.js";
+import { fileOpAccessOf } from "../../core/tool-registry.js";
+export const DURABLE_HISTORY_NAMES = new Map([
+    ["read", "read"],
+    ["write", "create"],
+    ["edit", "edit"],
+    ["read_file", "read"],
+    ["write_file", "create"],
+    ["edit_file", "edit"],
+]);
 export function createFileOps() {
     return {
         read: new Set(),
@@ -35,25 +44,16 @@ export function extractFileOpsFromMessage(message, fileOps) {
         if (!path) {
             continue;
         }
-        switch (block.name) {
-            case "read":
-            case "Read":
-            case "read_file":
-                fileOps.read.add(path);
-                break;
-            case "write":
-            case "Write":
-            case "write_file":
-                fileOps.written.add(path);
-                touchModified(fileOps, path);
-                break;
-            case "edit":
-            case "Edit":
-            case "edit_file":
-            case "MultiEdit":
-                fileOps.edited.add(path);
-                touchModified(fileOps, path);
-                break;
+        const access = fileOpAccessOf(block.name) ?? DURABLE_HISTORY_NAMES.get(block.name);
+        if (access === "read")
+            fileOps.read.add(path);
+        else if (access === "create") {
+            fileOps.written.add(path);
+            touchModified(fileOps, path);
+        }
+        else if (access === "edit") {
+            fileOps.edited.add(path);
+            touchModified(fileOps, path);
         }
     }
 }

package/dist/engine/loop/types.d.ts

@@ -750,6 +750,12 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = unk
      * server's own channel for keeping one tool's full schema inlined. Absent on non-MCP tools.
      */
     mcpAlwaysLoad?: boolean;
+    /**
+     * design/388 — the server's RAW tool name this mounted MCP tool was accepted under (byte-exact, the `tools/call`
+     * spelling). The `toolFaces` overlay binds to it: two raw names can fold onto one minted wire name, and an overlay
+     * keyed by the folded-away spelling must stay inert rather than land on the other tool. Absent on non-MCP tools.
+     */
+    mcpRemoteName?: string;
     /**
      * design/120 P1.5 (CC `isConcurrencySafe(parsedInput)` parity): INPUT-level concurrency refinement
      * for a tool whose safety depends on its arguments — CC's only real consumer is

package/dist/index.d.ts

@@ -24,9 +24,9 @@ export { createTodoWriteTool } from "./tools/todo.js";
 export { createTaskListTools, createMemoryTaskListStore, assertJsonMetadata, type TaskListItem, type TaskListStore } from "./tools/task-list.js";
 export { assembleCodeTools, type CodeToolsConfig, CODE_ROLE } from "./scenarios/full-body.js";
 export { TOOL_MODEL_GATE_CLASSES, isModelGatedForClass, type ToolModelGateRule } from "./core/tool-model-gate.js";
-export { capAggregateToolResults, AGGREGATE_TOOL_RESULT_BUDGET_CHARS, DEFAULT_BUDGET_EXEMPT_TOOLS, type AggregateBudgetOptions, } from "./core/tool-result-budget.js";
+export { capAggregateToolResults, AGGREGATE_TOOL_RESULT_BUDGET_CHARS, type AggregateBudgetOptions, } from "./core/tool-result-budget.js";
 export { capAggregateMediaBytes, AGGREGATE_MEDIA_BUDGET_BYTES, type MediaStripInfo } from "./core/media-byte-cap.js";
-export { createAskUserQuestionTool, createDurableQuestionPolicy, QUESTION_AWAITS_RESUME, isQuestionUnavailable, type OnQuestionOutcome, type QuestionUnavailable, type OnQuestion, type AskQuestion, type AskQuestionOption, type AskQuestionRequest, type QuestionAnswer, type QuestionAnswerItem, type AskQuestionCardDetails, type AskUserQuestionToolOptions, type AskAnswerContinuationSource, type SyntheticContinuationReason, } from "./core/ask-question.js";
+export { createAskUserQuestionTool, createDurableQuestionPolicy, QUESTION_AWAITS_RESUME, isQuestionUnavailable, type OnQuestionOutcome, type QuestionUnavailable, type OnQuestion, type AskQuestion, type AskQuestionOption, type AskQuestionRequest, type QuestionAnswer, type QuestionAnswerItem, type AskQuestionCardDetails, type AskUserQuestionToolOptions, type AskAnswerContinuationSource, type SyntheticContinuationReason, ASK_USER_QUESTION_TOOL_NAME, } from "./core/ask-question.js";
 export { createLspTool, gitCheckIgnoreFilter, LSP_OPERATIONS, LSP_FAILURE_BRAND, brandLspFailure, lspFailureOf, SharedAbortScope, settleOnAbort, type LspNoneReason, type LspOperation, type LspServerManager, type LspSession, type LspResult, type LspLocation, type LspSymbolInfo, type LspRequestParams, type LspToolOptions, type LspTransport, type LspReadText, } from "./core/lsp.js";
 export { buildRequest, parseResult, callHierarchyMethod, pathToUri } from "./core/lsp-protocol.js";
 export { TransportLspSession, type SessionWarmup } from "./core/lsp-session.js";
@@ -91,7 +91,7 @@ export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted } from "./core
 export { mintReminderMark, isValidReminderMark, openSystemReminder, mintSystemReminder, reminderMarkDeclaration } from "./core/reminder-mint.js";
 export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
 export type { InvariantKind, FunctionContract, Invariant, InvariantViolation, CheckResult, } from "./core/property-harness.js";
-export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
+export { bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, type BashReadonlyRootBoundary, type CompoundReadonlyVerdict, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, resolveReadDenyBuiltins, compileReadDeny, type ReadDenyEntry, type ReadDenyMatcher, type NormalizedReadDenyEntry, type ReadDenyBuiltinTier, type ReadDenyBuiltinRow, type ReadDenyBuiltinConfig, } from "./tools/fs/index.js";
@@ -124,6 +124,17 @@ export { createFsWriteGatePolicy, type FsWriteGatePolicyOptions } from "./core/f
 export { RETIRED_TOOL_NAMES } from "./core/tool-name-aliases.js";
 export { DEFAULT_SUBAGENT_TOOL_NAME } from "./agents/subagent.js";
 export { renderTaskNotificationXml, taskNotificationDedupKey, isDelegatedAgentTerminal, isTerminalTaskNotification, SystemInjectionQueue, type TaskNotificationPayload, type TaskNotificationStatus, type ExternalNotificationInput, type SystemInjection, type SystemInjectionPriority, SYSTEM_INJECTION_PRIORITIES, isSystemInjectionPriority, AGENT_MESSAGE_TAG, renderAgentMessageFrame, type SemaProvenance, } from "./core/task-notification.js";
+export { TOOL_FAMILIES, TOOL_MOUNT_TAGS, TOOL_APPROVAL_CARDS, TOOL_PATH_ACCESSES, TOOL_WIRE_NAME_MAX_CHARS, TOOL_CONTRACT_MAX_CHARS, TOOL_KEY_MAX_CHARS, TOOL_KEYS_MAX, RENDER_HINT_MAX_CHARS, RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_LIST, type ToolFamily, type ToolMountTag, type ToolApprovalCard, type ToolPathAccess, type ToolPathTarget, type ToolRuleFace, type ToolRenderHints, type ToolFaceDeclaration, type ToolCatalogEntry, } from "./core/tool-face.js";
+export { describeToolCatalog, catalogEntriesNamed, catalogToolNames, catalogRuleFaceOf, pathTargetOf, pathTargetValue, protectivePathTargetOf, declaredPathTargetOf, isProtectedWrite, isDeclaredWrite, fileOpAccessOf, type ToolCallLike, pathConfinableWriteToolNames, skillScopeWriteToolNames, pathTargetingToolNames, compactableToolNames, budgetExemptToolNames, handBandEffects, engineCardTypes, predictMountedToolNames, HANDS_BAND_TAGS, MOUNT_TAG_IN_HANDS_BAND, } from "./core/tool-registry.js";
+export { ToolRosterEntry, ToolRoster, ToolRosterDelta, ToolRosterRenderHints, ROSTER_SOURCES, type RosterSource, type ToolIdentity, toolIdentityOf, mintCapabilityId, diffToolRoster, judgeParkedToolIdentity, ruleFacesFromRoster, toolCallFaceOf, inputKeysOf, ruleFaceOfInstance, ToolRosterDeltaSeat, } from "./core/tool-roster.js";
+export { type ToolCallFace } from "./core/tool-policy.js";
+export { TOOL_CONFORMANCE_VECTORS, describeToolConformanceVectors, type ToolConformanceVector } from "./core/tool-conformance.js";
+export { applyMcpToolFaces, toolFaceProblem, APPROVAL_CARD_REQUIRED_KEYS, type McpToolFace } from "./core/runner/tool-face-overlay.js";
+export { createStructuredProjector } from "./core/runner/tool-output-projection.js";
+export { parkedToolIdentity } from "./core/tool-roster.js";
+export { type ToolCallIdentity } from "./core/fs-write-gate-policy.js";
+export { type RuleFaceView, catalogRuleFaceView } from "./core/permission-rules.js";
+export { DURABLE_HISTORY_NAMES } from "./engine/compaction/utils.js";
 export { describeStaticWiring, deriveWiringManifest, deriveAskEffective, resolveDeclaredDurability, resolveSubagentTranscriptTier, type SubagentTranscriptTier, resolveAskSeamForm, resolveQuestionSeam, countElicitOptIns, AUTO_MODE_ARM_REASONS, type AutoModeArmReason, type WiringManifest, type WiringManifestMcpEntry, type WiringFacts, type WiringLegKind, type AskSeamForm, type AskEffective, type QuestionChannelState, type SeamProvenance, type ParkLaneReason, type ManifestDurability, type StaticWiringDeps, type StaticWiringSpec, } from "./core/wiring-manifest.js";
 export { probeParkRoundTrip, durableParkGapOf, durableParkGapFor, PARK_SELFCHECK_SCOPE_PREFIX, type ParkSelfCheckResult, type ParkProbeFinding, type ParkProbeFindingCode, } from "./core/park-selfcheck.js";
 export { type StoreDurability } from "./core/checkpoint-store.js";
@@ -175,8 +186,8 @@ export { createPermissionRulePolicy, validatePermissionRules, parsePermissionRul
  * and nothing more. Removal is exported without ceremony, because narrowing on a user's behalf is
  * allowed and widening is not.
  */
-export { parseAllowRuleText, formatAllowRuleText, ruleAdmitsCommand, findAdmittingRule, suggestRulesForCommand, scopeCoversCwd, pathWithinRoot, isRuleLive, renderUntrustedCommandText, stripFormatCharacters, UNCOVERED_SEGMENT_REASON_BASELINE, RULE_OFFERS_ABSENCE_BASELINE, type UncoveredSegmentDetail, type EditedRuleBreadthWarning, directoryRuleAdmits, BARE_INTERPRETER_NAMES, MAX_RULE_TEXT_CHARS, type PersistedAllowRule, type RuleTombstone, type RuleScope, type RuleDot, type RuleAdd, type RuleAddOrigin, type RuleOffer, type RuleOfferBatchMember, type SegmentRuleSuggestion, type SegmentCoverage, type RuleReject, type RuleRejectCode, type ParsedAllowRule, type PersistedRuleTool, type PersistedRuleMatch, } from "./core/permission-rule-model.js";
-export { removePersistedRule, applyTombstones, sameScope, isValidConsentScope, isValidDurableScope, InMemoryDurableRulePartition, EMPTY_DURABLE_RULE_PARTITION, type DurableRulePartition, type DurableRulePartitionProvider, type RuleWriteOutcome, type StoredAllowRules, type RemoveResult, type PutResult, joinRuleStates, screenRuleSyncState, collectBelowFrontier, ruleSyncVector, joinFrontiers, dotAtOrBelowFrontier, sameRuleOwner, type RuleSyncState, type RuleSyncFrontier, type RuleSyncDrop, type RuleSyncLandingReport, type RuleOwner, type QuarantinedRuleAdd, PERMISSION_RULE_WRITER, writerOf, foldDelta, addDotsOf, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, type PermissionRuleWriter, type WritableDurableRulePartition, type RuleWriteDelta, type RuleAddDelta, type RuleDeleteDelta, type RuleSyncJoinDelta, type RawRuleSyncState, type RedemptionAuthorization, } from "./core/permission-rule-store.js";
+export { RULE_BEHAVIORS, RULE_BEHAVIOR_PRECEDENCE, RULE_BEHAVIORS_BY_PRECEDENCE, isRuleBehavior, readRowBehavior, adjudicatePersistedRules, adjudicatePersistedPathRules, ruleReachesProgramRun, pathRuleReaches, ruleToolGrammarOf, COMMAND_RULE_TOOL, READ_RULE_TOOL, type PathRuleBases, type RuleBehavior, type PersistedRuleVerdict, parseRuleText, formatRuleText, ruleAdmitsCommand, findAdmittingRule, suggestRulesForCommand, scopeCoversCwd, pathWithinRoot, isRuleLive, renderUntrustedCommandText, stripFormatCharacters, UNCOVERED_SEGMENT_REASON_BASELINE, RULE_OFFERS_ABSENCE_BASELINE, type UncoveredSegmentDetail, type EditedRuleBreadthWarning, directoryRuleAdmits, BARE_INTERPRETER_NAMES, MAX_RULE_TEXT_CHARS, type PersistedRule, type RuleTombstone, type RuleScope, type RuleDot, type RuleAdd, type RuleAddOrigin, type RuleOffer, type RuleOfferBatchMember, type SegmentRuleSuggestion, type SegmentCoverage, type RuleReject, type RuleRejectCode, type ParsedRule, type PersistedRuleTool, type PersistedRuleMatch, } from "./core/permission-rule-model.js";
+export { removePersistedRule, applyTombstones, sameScope, sameRuleIdentity, isValidConsentScope, isValidDurableScope, InMemoryDurableRulePartition, EMPTY_DURABLE_RULE_PARTITION, type DurableRulePartition, type DurableRulePartitionProvider, type RuleWriteOutcome, type StoredRules, type RemoveResult, type PutResult, joinRuleStates, screenRuleSyncState, collectBelowFrontier, ruleSyncVector, joinFrontiers, dotAtOrBelowFrontier, sameRuleOwner, type RuleSyncState, type RuleSyncFrontier, type RuleSyncDrop, type RuleSyncLandingReport, type RuleOwner, type QuarantinedRuleAdd, PERMISSION_RULE_WRITER, writerOf, foldDelta, addDotsOf, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, type PermissionRuleWriter, type WritableDurableRulePartition, type RuleWriteDelta, type RuleAddDelta, type RuleDeleteDelta, type RuleSyncJoinDelta, type RawRuleSyncState, type RedemptionAuthorization, } from "./core/permission-rule-store.js";
 export { syncPermissionRules, parseRuleSyncResponse, PERMISSION_RULE_SYNC_PATH, LOCAL_OWNER_UNSYNCABLE_CODE, type PermissionRuleSyncTransport, type PermissionRuleSyncResult, type RuleSyncRequestBody, type RuleSyncResponseBody, } from "./core/permission-rule-sync.js";
 export { createPermissionRuleStoreProvider, effectivePermissionRules, effectiveOrThrow, ruleSourceOf, type PermissionRuleStore, type PermissionRuleStoreProvider, type PermissionRuleStoreConfig, type EffectivePermissionRules, type EffectivePermissionRule, type RemovedPermissionRule, type RuleSource, } from "./core/permission-rule-provider.js";
 export { InMemorySessionRulePartition, type SessionRulePartition, type SessionRuleAdd, type SessionRuleApplyResult, } from "./core/permission-rule-session.js";
@@ -280,7 +291,7 @@ export { defineAgent } from "./agents/agent-definition.js";
 export { builtinAgentDefinitions, BUILTIN_READONLY_DENY_TOOLS, EXPLORE_WHEN_TO_USE, EXPLORE_WHEN_TO_USE_LEAN, PLAN_WHEN_TO_USE, EXPLORE_SYSTEM_PROMPT, PLAN_SYSTEM_PROMPT, } from "./agents/builtin-agents.js";
 export { runTeamDiscussion, type TeamDiscussionOptions, type TeamMember, type TeamResult, type TeamTurn, type TeamEvent, } from "./agents/team.js";
 export { createTaskServer, type TaskServerOptions, type TaskRequestBody, } from "./server/http.js";
-export { clearStaleToolResults, COMPACTABLE_TOOLS, editBudget, type ContextEditOptions, } from "./core/context-edit.js";
+export { clearStaleToolResults, editBudget, type ContextEditOptions, } from "./core/context-edit.js";
 export { createOpenAIBrain, type OpenAIBrainConfig } from "./brain/openai.js";
 export { createAnthropicBrain, type AnthropicBrainConfig } from "./brain/anthropic.js";
 export { createOpenResponsesBrain, type OpenResponsesBrainConfig } from "./brain/open-responses.js";

package/dist/index.js

@@ -12,9 +12,9 @@ export { createTodoWriteTool } from "./tools/todo.js";
 export { createTaskListTools, createMemoryTaskListStore, assertJsonMetadata } from "./tools/task-list.js";
 export { assembleCodeTools, CODE_ROLE } from "./scenarios/full-body.js";
 export { TOOL_MODEL_GATE_CLASSES, isModelGatedForClass } from "./core/tool-model-gate.js";
-export { capAggregateToolResults, AGGREGATE_TOOL_RESULT_BUDGET_CHARS, DEFAULT_BUDGET_EXEMPT_TOOLS, } from "./core/tool-result-budget.js";
+export { capAggregateToolResults, AGGREGATE_TOOL_RESULT_BUDGET_CHARS, } from "./core/tool-result-budget.js";
 export { capAggregateMediaBytes, AGGREGATE_MEDIA_BUDGET_BYTES } from "./core/media-byte-cap.js";
-export { createAskUserQuestionTool, createDurableQuestionPolicy, QUESTION_AWAITS_RESUME, isQuestionUnavailable, } from "./core/ask-question.js";
+export { createAskUserQuestionTool, createDurableQuestionPolicy, QUESTION_AWAITS_RESUME, isQuestionUnavailable, ASK_USER_QUESTION_TOOL_NAME, } from "./core/ask-question.js";
 export { createLspTool, gitCheckIgnoreFilter, LSP_OPERATIONS, LSP_FAILURE_BRAND, brandLspFailure, lspFailureOf, SharedAbortScope, settleOnAbort, } from "./core/lsp.js";
 export { buildRequest, parseResult, callHierarchyMethod, pathToUri } from "./core/lsp-protocol.js";
 export { TransportLspSession } from "./core/lsp-session.js";
@@ -70,7 +70,7 @@ export { runExecGate } from "./core/exec-gate.js";
 export { sanitizeUntrustedText, delimitUntrusted, inlineUntrusted } from "./core/untrusted-text.js";
 export { mintReminderMark, isValidReminderMark, openSystemReminder, mintSystemReminder, reminderMarkDeclaration } from "./core/reminder-mint.js";
 export { deriveInvariants, checkInvariants } from "./core/property-harness.js";
-export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
+export { bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, resolveReadDenyBuiltins, compileReadDeny, } from "./tools/fs/index.js";
@@ -100,6 +100,17 @@ export { createFsWriteGatePolicy } from "./core/fs-write-gate-policy.js";
 export { RETIRED_TOOL_NAMES } from "./core/tool-name-aliases.js";
 export { DEFAULT_SUBAGENT_TOOL_NAME } from "./agents/subagent.js";
 export { renderTaskNotificationXml, taskNotificationDedupKey, isDelegatedAgentTerminal, isTerminalTaskNotification, SystemInjectionQueue, SYSTEM_INJECTION_PRIORITIES, isSystemInjectionPriority, AGENT_MESSAGE_TAG, renderAgentMessageFrame, } from "./core/task-notification.js";
+export { TOOL_FAMILIES, TOOL_MOUNT_TAGS, TOOL_APPROVAL_CARDS, TOOL_PATH_ACCESSES, TOOL_WIRE_NAME_MAX_CHARS, TOOL_CONTRACT_MAX_CHARS, TOOL_KEY_MAX_CHARS, TOOL_KEYS_MAX, RENDER_HINT_MAX_CHARS, RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_LIST, } from "./core/tool-face.js";
+export { describeToolCatalog, catalogEntriesNamed, catalogToolNames, catalogRuleFaceOf, pathTargetOf, pathTargetValue, protectivePathTargetOf, declaredPathTargetOf, isProtectedWrite, isDeclaredWrite, fileOpAccessOf, pathConfinableWriteToolNames, skillScopeWriteToolNames, pathTargetingToolNames, compactableToolNames, budgetExemptToolNames, handBandEffects, engineCardTypes, predictMountedToolNames, HANDS_BAND_TAGS, MOUNT_TAG_IN_HANDS_BAND, } from "./core/tool-registry.js";
+export { ToolRosterEntry, ToolRoster, ToolRosterDelta, ToolRosterRenderHints, ROSTER_SOURCES, toolIdentityOf, mintCapabilityId, diffToolRoster, judgeParkedToolIdentity, ruleFacesFromRoster, toolCallFaceOf, inputKeysOf, ruleFaceOfInstance, ToolRosterDeltaSeat, } from "./core/tool-roster.js";
+export {} from "./core/tool-policy.js";
+export { TOOL_CONFORMANCE_VECTORS, describeToolConformanceVectors } from "./core/tool-conformance.js";
+export { applyMcpToolFaces, toolFaceProblem, APPROVAL_CARD_REQUIRED_KEYS } from "./core/runner/tool-face-overlay.js";
+export { createStructuredProjector } from "./core/runner/tool-output-projection.js";
+export { parkedToolIdentity } from "./core/tool-roster.js";
+export {} from "./core/fs-write-gate-policy.js";
+export { catalogRuleFaceView } from "./core/permission-rules.js";
+export { DURABLE_HISTORY_NAMES } from "./engine/compaction/utils.js";
 export { describeStaticWiring, deriveWiringManifest, deriveAskEffective, resolveDeclaredDurability, resolveSubagentTranscriptTier, resolveAskSeamForm, resolveQuestionSeam, countElicitOptIns, AUTO_MODE_ARM_REASONS, } from "./core/wiring-manifest.js";
 export { probeParkRoundTrip, durableParkGapOf, durableParkGapFor, PARK_SELFCHECK_SCOPE_PREFIX, } from "./core/park-selfcheck.js";
 export {} from "./core/checkpoint-store.js";
@@ -134,8 +145,8 @@ export { AUTO_MODE_BASE_PROMPT, AUTO_MODE_PERMISSIONS_EXTERNAL } from "./core/au
 export { AUTO_MODE_ARMING_RECIPE_VERSION, autoModeArmingRecipeOf, sanitizeAutoModeArmingRecipe, foldAutoModeArming, } from "./core/auto-mode-arming.js";
 export { rebuildAutoModeDecider, } from "./core/auto-mode-rebuild.js";
 export { createPermissionRulePolicy, validatePermissionRules, parsePermissionRule, wildcardMatch, isNamespacedCoveringRuleName, namespacedRuleNameCovers, } from "./core/permission-rules.js";
-export { parseAllowRuleText, formatAllowRuleText, ruleAdmitsCommand, findAdmittingRule, suggestRulesForCommand, scopeCoversCwd, pathWithinRoot, isRuleLive, renderUntrustedCommandText, stripFormatCharacters, UNCOVERED_SEGMENT_REASON_BASELINE, RULE_OFFERS_ABSENCE_BASELINE, directoryRuleAdmits, BARE_INTERPRETER_NAMES, MAX_RULE_TEXT_CHARS, } from "./core/permission-rule-model.js";
-export { removePersistedRule, applyTombstones, sameScope, isValidConsentScope, isValidDurableScope, InMemoryDurableRulePartition, EMPTY_DURABLE_RULE_PARTITION, joinRuleStates, screenRuleSyncState, collectBelowFrontier, ruleSyncVector, joinFrontiers, dotAtOrBelowFrontier, sameRuleOwner, PERMISSION_RULE_WRITER, writerOf, foldDelta, addDotsOf, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, } from "./core/permission-rule-store.js";
+export { RULE_BEHAVIORS, RULE_BEHAVIOR_PRECEDENCE, RULE_BEHAVIORS_BY_PRECEDENCE, isRuleBehavior, readRowBehavior, adjudicatePersistedRules, adjudicatePersistedPathRules, ruleReachesProgramRun, pathRuleReaches, ruleToolGrammarOf, COMMAND_RULE_TOOL, READ_RULE_TOOL, parseRuleText, formatRuleText, ruleAdmitsCommand, findAdmittingRule, suggestRulesForCommand, scopeCoversCwd, pathWithinRoot, isRuleLive, renderUntrustedCommandText, stripFormatCharacters, UNCOVERED_SEGMENT_REASON_BASELINE, RULE_OFFERS_ABSENCE_BASELINE, directoryRuleAdmits, BARE_INTERPRETER_NAMES, MAX_RULE_TEXT_CHARS, } from "./core/permission-rule-model.js";
+export { removePersistedRule, applyTombstones, sameScope, sameRuleIdentity, isValidConsentScope, isValidDurableScope, InMemoryDurableRulePartition, EMPTY_DURABLE_RULE_PARTITION, joinRuleStates, screenRuleSyncState, collectBelowFrontier, ruleSyncVector, joinFrontiers, dotAtOrBelowFrontier, sameRuleOwner, PERMISSION_RULE_WRITER, writerOf, foldDelta, addDotsOf, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, } from "./core/permission-rule-store.js";
 export { syncPermissionRules, parseRuleSyncResponse, PERMISSION_RULE_SYNC_PATH, LOCAL_OWNER_UNSYNCABLE_CODE, } from "./core/permission-rule-sync.js";
 export { createPermissionRuleStoreProvider, effectivePermissionRules, effectiveOrThrow, ruleSourceOf, } from "./core/permission-rule-provider.js";
 export { InMemorySessionRulePartition, } from "./core/permission-rule-session.js";
@@ -236,7 +247,7 @@ export { defineAgent } from "./agents/agent-definition.js";
 export { builtinAgentDefinitions, BUILTIN_READONLY_DENY_TOOLS, EXPLORE_WHEN_TO_USE, EXPLORE_WHEN_TO_USE_LEAN, PLAN_WHEN_TO_USE, EXPLORE_SYSTEM_PROMPT, PLAN_SYSTEM_PROMPT, } from "./agents/builtin-agents.js";
 export { runTeamDiscussion, } from "./agents/team.js";
 export { createTaskServer, } from "./server/http.js";
-export { clearStaleToolResults, COMPACTABLE_TOOLS, editBudget, } from "./core/context-edit.js";
+export { clearStaleToolResults, editBudget, } from "./core/context-edit.js";
 export { createOpenAIBrain } from "./brain/openai.js";
 export { createAnthropicBrain } from "./brain/anthropic.js";
 export { createOpenResponsesBrain } from "./brain/open-responses.js";

package/dist/orchestration/goal.js

@@ -3,16 +3,17 @@ import { Type } from "typebox";
 import { delimitUntrusted } from "../core/untrusted-text.js";
 import { OUTPUT_TOOL_NAME } from "../core/runner/synthetic-tools.js";
 import { isDurablePause, pauseFamily } from "../agents/suspend-guard.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 export const DECLARE_DONE_TOOL_NAME = "DeclareDone";
 function createDeclareDoneTool(ref) {
     return {
         name: DECLARE_DONE_TOOL_NAME,
+        ...toolFace("declare-done"),
         description: "Call this ONLY when you believe the goal is FULLY achieved — verified against evidence, not just " +
             "attempted. Provide a concise summary of what was achieved and how you verified it. Calling this " +
             "declares completion; a verification check then runs. If it passes, the goal stops and surfaces for " +
             "human review. If it does NOT pass, you will be asked to keep working with the verification feedback.",
         parameters: Type.Object({ summary: Type.String() }),
-        effect: "read",
         execute: (args) => {
             ref.declared = true;
             ref.summary = String(args.summary ?? "").trim();

package/dist/orchestration/run-spec.js

@@ -7,7 +7,7 @@ import { isDurablePause } from "../agents/suspend-guard.js";
 import { terminalProjection } from "../core/runner/terminal-projection.js";
 import { isAbsolutePathForm, writeTargetPath } from "../tools/fs/safety.js";
 import { captureBaseline, resolveFrozenPaths, restoreFrozenPaths, runOracle, snapshotFrozenPaths, specError, } from "../core/spec-contract.js";
-const WRITE_TOOLS = new Set(["Write", "Edit", "NotebookEdit"]);
+import { isProtectedWrite } from "../core/tool-registry.js";
 const CASE_INSENSITIVE_FS = process.platform === "darwin" || process.platform === "win32";
 const pathKey = (p) => {
     let n = p.replace(/\\/g, "/");
@@ -19,11 +19,9 @@ function frozenDenyPolicy(rootDir, frozenResolved) {
     const frozen = new Set(frozenResolved.map(pathKey));
     return {
         check(req) {
-            const toolName = req.toolName;
-            if (!WRITE_TOOLS.has(toolName))
+            if (!isProtectedWrite(req))
                 return { action: "allow" };
-            const args = req.args;
-            const raw = writeTargetPath(toolName, args);
+            const raw = writeTargetPath(req);
             if (typeof raw !== "string" || raw.length === 0)
                 return { action: "allow" };
             const absForm = isAbsolutePathForm(raw);

package/dist/orchestration/run-workflow-tool.js

@@ -10,6 +10,7 @@ import { parseWorkflowMeta, splitWorkflowMeta, workflowScriptReadsClockOrRandom
 import { mergeWorkflowArgs, normalizeStringArg } from "./workflow-script-store.js";
 import { builtinWorkflowListings, canonicalWorkflowName, resolveBuiltinWorkflow, workflowNameProbeOrder } from "./builtin-workflows.js";
 import { workflowSizeGuidelineSection } from "./workflow-size-guideline.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 export const RUN_WORKFLOW_TOOL_NAME = "Workflow";
 function stripCodeFences(s) {
     const t = s.trim();
@@ -244,7 +245,7 @@ export async function createRunWorkflowTool(d) {
     const structuredError = (message) => errorResult(JSON.stringify({ error: message }));
     return defineTool({
         name: RUN_WORKFLOW_TOOL_NAME,
-        contract: { contractId: "core.workflow@1", implementationRevision: "1" },
+        ...toolFace("workflow"),
         approvalPreview: (raw) => {
             const a = (raw ?? {});
             if (typeof a.name === "string" && a.name)
@@ -374,7 +375,6 @@ export async function createRunWorkflowTool(d) {
                     "Requires a journal-backed deployment; omit for a fresh run.",
             })),
         }),
-        effect: "write",
         execute: async (rawArgs, ctx) => {
             const rawScript = rawArgs.script;
             const rawName = rawArgs.name;

package/dist/prompt-assembly/event-registry.js

@@ -6,7 +6,7 @@ export const EVENT_PROMPT_REGISTRY = new Map([
     { kind: "plan_mode", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "off", rendererRef: "turn-attachments.ts#PLAN_MODE_FULL_BODY" },
     { kind: "date_change", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "always", rendererRef: "turn-attachments.ts#renderDateChange" },
     { kind: "instructions_change", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", maxBytes: 512, defaultPolicy: "always", rendererRef: "turn-attachments.ts#collectInstructionsChange" },
-    { kind: "workflow_size_guideline_change", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "always", rendererRef: "runtask.ts#workflowSizeGuidelineChangeNotice" },
+    { kind: "workflow_size_guideline_change", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "always", rendererRef: "run-turn-boundary.ts#workflowSizeGuidelineChangeNotice" },
     { kind: "budget_usd", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "off", rendererRef: "turn-attachments.ts#renderBudgetUsd" },
     { kind: "total_tokens_reminder", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "on", rendererRef: "turn-attachments.ts#renderTotalTokensReminder" },
     { kind: "background_tasks", carrier: "message.user-prefix", trust: "operator", dedupe: "replace-by-key", defaultPolicy: "on", rendererRef: "turn-attachments.ts#renderBackgroundTasks" },
@@ -16,8 +16,8 @@ export const EVENT_PROMPT_REGISTRY = new Map([
     { kind: "mcp_instructions", carrier: "message.user-prefix", trust: "external", dedupe: "replace-by-key", defaultPolicy: "off", rendererRef: "turn-attachments.ts#renderMcpInstructionsDelta" },
     { kind: "mcp_dropped_tools", carrier: "message.user-prefix", trust: "external", dedupe: "replace-by-key", defaultPolicy: "off", rendererRef: "turn-attachments.ts#renderMcpDroppedTools" },
     { kind: "git_status", carrier: "message.user-prefix", trust: "external", dedupe: "replace-by-key", defaultPolicy: "always", rendererRef: "git-status-frame.ts#renderGitStatusFrameBody" },
-    { kind: "limit_approach_converge", carrier: "message.user-prefix", trust: "operator", dedupe: "once-per-run", defaultPolicy: "always", rendererRef: "runtask.ts#limitApproachFrames" },
-    { kind: "limit_approach_deliver", carrier: "message.user-prefix", trust: "operator", dedupe: "once-per-run", defaultPolicy: "always", rendererRef: "runtask.ts#limitApproachFrames" },
+    { kind: "limit_approach_converge", carrier: "message.user-prefix", trust: "operator", dedupe: "once-per-run", defaultPolicy: "always", rendererRef: "run-turn-boundary.ts#limitApproachFrames" },
+    { kind: "limit_approach_deliver", carrier: "message.user-prefix", trust: "operator", dedupe: "once-per-run", defaultPolicy: "always", rendererRef: "run-turn-boundary.ts#limitApproachFrames" },
     { kind: "final_verification", carrier: "message.user-prefix", trust: "operator", dedupe: "once-per-run", defaultPolicy: "always", rendererRef: "runtask.ts#final-verification" },
 ].map((e) => [e.kind, e]));
 export function eventDefaultOn(kind) {

package/dist/prompt-assembly/tool-catalog.d.ts

@@ -61,7 +61,7 @@ export declare function attachToolContract(tool: AgentTool, input: AttachContrac
 export declare function getToolContract(tool: AgentTool, fallbackOrigin?: ToolOrigin): ToolContractDescriptor;
 export declare function hasToolContract(tool: AgentTool): boolean;
 /** Manifest projection for the final mounted tool set (manifest v2 `tools`, protocol §5.4). */
-export declare function projectToolManifest(tools: AgentTool[], originOf?: (tool: AgentTool) => ToolOrigin): ToolManifestRow[];
+export declare function projectToolManifest(tools: readonly AgentTool[], originOf?: (tool: AgentTool) => ToolOrigin): ToolManifestRow[];
 /**
  * RB-15: wire-identity collision audit over the FINAL mounted tool set.
  * Rules (plan §6.2 tool row):
@@ -71,7 +71,7 @@ export declare function projectToolManifest(tools: AgentTool[], originOf?: (tool
  *     a built-in; the harness Map keeps the later mount) — NOT fatal, but returned as an explicit
  *     exemption record so the mount site can surface it (observable, never silent).
  */
-export declare function auditToolCollisions(tools: AgentTool[]): {
+export declare function auditToolCollisions(tools: readonly AgentTool[]): {
     yields: Array<{
         name: string;
     }>;

package/dist/stores/file/checkpoint-store.js

@@ -16,7 +16,7 @@ const KNOWN_CHECKPOINT_LEDGER_EVENTS = new Set(Object.keys(CHECKPOINT_LEDGER_EVE
 function applyCheckpointEvent(cps, ev) {
     if (!KNOWN_CHECKPOINT_LEDGER_EVENTS.has(ev.t)) {
         throw new CheckpointError("checkpoint.unsupported_version", `file checkpoint ledger: unrecognised event kind "${String(ev.t)}" — ` +
-            `it was written by a newer worker; refusing the replay rather than serving an incomplete authority`);
+            `it was written by a newer worker; refusing the replay rather than serving an incomplete authority`, { reason: "ledger_event_unknown" });
     }
     if (ev.t === "put") {
         cps.set(ev.token, ev.cp);

package/dist/stores/file/permission-rule-store.d.ts

@@ -2,17 +2,21 @@
  * design/179 §5/§8 / design/389 — the file backend of the permission-rule store's DURABLE partition (one
  * bucket file per owner), plus the file home of the ORG partition's durable state (`org.json`).
  *
- * ## Schema 3 and the one-time migration
+ * ## Schema 4 and the one-time migration
  *
  * Pre-389 files (schema 1/2) kept the org last-known-good snapshot as an `org` block INSIDE each
- * principal's bucket file — deployment-wide policy stored per person. Schema 3 drops that block; the org
- * state lives in one `org.json` beside the buckets. `FileDurableRulePartitionProvider` migrates every
- * legacy bucket file ONCE at construction (under the writer lock: the migration is a write, and a live
- * older writer over the same directory is refused rather than raced), folding each file's `org` block
- * into `org.json` by the anti-rollback rule (the highest high-water wins; an equal revision with
- * different content keeps what is already installed and discloses). After that the reader accepts
- * schema 3 ONLY — a 1/2/4 file is refused whole, loudly (zero rules + disclosure). There is no second
- * read path for the old shapes: the migrator is the only code that reads them, and it runs once.
+ * principal's bucket file — deployment-wide policy stored per person. Schema 3 dropped that block; the org
+ * state lives in one `org.json` beside the buckets. Schema 4 adds the `behavior` member to every rule row,
+ * tombstone and quarantine row (the rule identity is the (behavior, text, scope) triple): a schema-3 row has
+ * none, and every row a schema-3 engine wrote was an allow, so the migration stamps `"allow"` on each — the
+ * ONE reading of the pre-field row (`readRowBehavior`), applied once, here, never at a read face.
+ * `FileDurableRulePartitionProvider` migrates every legacy bucket file (1, 2 or 3) ONCE at construction
+ * (under the writer lock: the migration is a write, and a live older writer over the same directory is
+ * refused rather than raced), folding a 1/2 file's `org` block into `org.json` by the anti-rollback rule
+ * (the highest high-water wins; an equal revision with different content keeps what is already installed
+ * and discloses). After that the reader accepts schema 4 ONLY — a 1/2/3/5 file is refused whole, loudly
+ * (zero rules + disclosure). There is no second read path for the old shapes: the migrator is the only
+ * code that reads them, and it runs once.
  *
  * ## Why this store builds its own symlink refusal
  *
@@ -55,23 +59,23 @@
  * and is not: it detects corruption, and it does not detect an editor, because an editor recomputes it.
  * For this backend the trust is host = user, exactly as for the settings file it mirrors.
  */
-import type { PersistedAllowRule, RuleTombstone } from "../../core/permission-rule-model.js";
-import type { DurableRulePartition, DurableRulePartitionProvider, PermissionRuleWriter, QuarantinedRuleAdd, RuleOwner, RuleSyncFrontier, StoredAllowRules, WritableDurableRulePartition } from "../../core/permission-rule-store.js";
+import type { PersistedRule, RuleTombstone } from "../../core/permission-rule-model.js";
+import type { DurableRulePartition, DurableRulePartitionProvider, PermissionRuleWriter, QuarantinedRuleAdd, RuleOwner, RuleSyncFrontier, StoredRules, WritableDurableRulePartition } from "../../core/permission-rule-store.js";
 import { PERMISSION_RULE_WRITER } from "../../core/permission-rule-store.js";
 import type { OrgRuleStatePersistence, PersistedOrgRuleState } from "../../core/permission-rule-org.js";
 import type { StoreDurability, StoreFidelity } from "../../core/checkpoint-store.js";
 /**
  * The on-disk shape of one bucket. `schemaVersion` is the only field a future reader may rely on before
- * validating. Schema 3 (design/389): the five core fields plus the OPTIONAL `sync` block (observation
- * vector + round timestamp) and `quarantined` area (rows moved out of the live view, bytes preserved).
- * The org state is NOT here — see {@link OrgStateFile}.
+ * validating. Schema 4: the five core fields plus the OPTIONAL `sync` block (observation vector + round
+ * timestamp) and `quarantined` area (rows moved out of the live view, bytes preserved); every rule,
+ * tombstone and quarantine row carries its `behavior`. The org state is NOT here — see {@link OrgStateFile}.
  */
 interface RuleFile {
-    schemaVersion: 3;
+    schemaVersion: 4;
     actor: string;
     counter: number;
     rev: number;
-    rules: PersistedAllowRule[];
+    rules: PersistedRule[];
     tombstones: RuleTombstone[];
     sync?: {
         observedVector?: RuleSyncFrontier;
@@ -88,10 +92,10 @@ interface OrgStateFile {
 }
 /** The org partition's durable home in a rule directory. */
 export declare const ORG_STATE_FILE = "org.json";
-/** Written once the directory is known to hold only schema-3 buckets. Its presence ends the legacy
- *  scan for good: a schema 1/2 bucket that appears AFTERWARDS (an older engine writing after the
+/** Written once the directory is known to hold only schema-4 buckets. Its presence ends the legacy
+ *  scan for good: a schema 1/2/3 bucket that appears AFTERWARDS (an older engine writing after the
  *  cutover) is refused by the reader on every later construction too, never re-admitted by a restart. */
-export declare const SCHEMA3_MARKER_FILE = ".rule-schema-3";
+export declare const SCHEMA_MARKER_FILE = ".rule-schema-4";
 /** The anti-rollback contract's DESIGNED refusal (a lower high-water mark, or different content under
  *  the same revision) — distinguished by class from every other install failure, because the two are
  *  handled in opposite directions by the migration: a refusal means the block is superseded and may be
@@ -148,7 +152,7 @@ declare class FileDurableRulePartition implements WritableDurableRulePartition {
      */
     private screenDurableRows;
     private write;
-    list(): Promise<StoredAllowRules>;
+    list(): Promise<StoredRules>;
     /** The quarantine area (design/182 §5.2/§8.3): introspection only — never part of `list()`. */
     quarantined(): Promise<QuarantinedRuleAdd[]>;
     /**
@@ -209,7 +213,8 @@ export declare class FileDurableRulePartitionProvider implements DurableRulePart
         dataRoot?: string;
     });
     /**
-     * Fold every legacy bucket file in `dir` into schema 3 and its `org` block into `org.json`. A no-op on a
+     * Fold every legacy bucket file in `dir` into schema 4 (stamping `behavior: "allow"` on every pre-field
+     * row — the one pre-field reading) and a 1/2 file's `org` block into `org.json`. A no-op on a
      * directory with no legacy file (zero writes, the lock untouched — the second construction over a
      * migrated directory is byte-silent). A legacy file whose checksum or shape does not hold is NOT
      * migrated: its bytes stay where they are for a person to look at, and the reader keeps refusing it
@@ -220,10 +225,10 @@ export declare class FileDurableRulePartitionProvider implements DurableRulePart
      * shape — the old engine's buckets are refused whole until they are migrated.
      */
     private migrateLegacyBuckets;
-    /** Publish the schema-3 completion marker (idempotent, atomic, no lock: its content never changes and
+    /** Publish the schema-4 completion marker (idempotent, atomic, no lock: its content never changes and
      *  a concurrent writer of the same bytes is harmless). A failure to write it is disclosed, not thrown —
      *  the next construction simply scans again, which is the safe direction. */
-    private writeSchema3Marker;
+    private writeSchemaMarker;
     /** The org partition's durable home in this directory (design/182 §7.4 contract; `org.json`). Shares
      *  this provider's writer lock — an install is a write. */
     orgStatePersistence(): OrgRuleStatePersistence;