@oscharko-dev/keiko-contracts 0.2.0

package/dist/relationships.js

@@ -0,0 +1,307 @@
+// Public type contracts for the Keiko relationship engine (Epic #532, Issue #538).
+//
+// Pure types and frozen constant tables only — no IO, no clock reads, no hashing, no
+// randomness, no filesystem access. Leaf-package rule (ADR-0019 direction 1): no
+// `@oscharko-dev/keiko-*` imports may appear in this module. The schemaVersion discriminant
+// follows the same evolution rule as MEMORY_AUDIT_EVENT_SCHEMA_VERSION and
+// LOCAL_KNOWLEDGE_SCHEMA_VERSION: a breaking change introduces a NEW literal member rather
+// than mutating "1".
+//
+// Foundations: docs/relationship-engine/taxonomy.md (object kinds, relationship types,
+// per-type metadata), docs/relationship-engine/compatibility-matrix.md (source × target
+// pairs), docs/relationship-engine/denial-reasons.md (the 18-code catalog and resolution
+// order), docs/relationship-engine/lifecycle.md (the 7-state machine), and
+// docs/relationship-engine/activity-state.md (the 9 transient activity states derived from
+// existing event streams — durable on the lifecycle column, never persisted on their own).
+//
+// The relationship record is BODY-FREE by construction (taxonomy.md §12, audit-events.md
+// §8.3). The `metadata` bag is a `Readonly<Record<string, unknown>>` so callers may attach
+// non-sensitive structural hints; the deterministic validator (relationships-validation.ts)
+// rejects forbidden keys outright so a client never accidentally smuggles a prompt or
+// document excerpt past the redactor.
+// ─── Schema version ───────────────────────────────────────────────────────────
+export const RELATIONSHIP_SCHEMA_VERSION = "1";
+// ─── Object kinds ─────────────────────────────────────────────────────────────
+// Closed enumeration of the 14 object kinds a relationship endpoint may carry. The order
+// of this tuple matches the column order of compatibility-matrix.md §2 (alphabetical,
+// ignoring the forward-looking suffix) so test fixtures can iterate deterministically.
+export const RELATIONSHIP_OBJECT_KINDS = [
+    "agent",
+    "capsule",
+    "capsule-set",
+    "chat",
+    "connector",
+    "data-source",
+    "evidence-run",
+    "mcp-tool",
+    "memory",
+    "patch-proposal",
+    "skill",
+    "tool",
+    "workflow-run",
+    "workspace-path",
+];
+// Kinds the relationship engine accepts TODAY. Forward-looking kinds (agent, connector,
+// data-source, skill, mcp-tool) are members of RELATIONSHIP_OBJECT_KINDS so the schema is
+// stable when their owning registries land (taxonomy.md §4.2), but the validator rejects
+// proposals naming them with `denied/object-kind-not-yet-supported`.
+export const RELATIONSHIP_SUPPORTED_OBJECT_KINDS = [
+    "capsule",
+    "capsule-set",
+    "chat",
+    "evidence-run",
+    "memory",
+    "patch-proposal",
+    "tool",
+    "workflow-run",
+    "workspace-path",
+];
+// ─── Relationship types ───────────────────────────────────────────────────────
+// Closed enumeration of the seven relationship types (taxonomy.md §5.8). Order matches
+// the taxonomy's section ordering so reviewers can cross-walk the table.
+export const RELATIONSHIP_TYPES = [
+    "reads-context",
+    "proposes-patch",
+    "uses-tool",
+    "starts-workflow",
+    "produces-evidence",
+    "references-document",
+    "depends-on",
+];
+// ─── Lifecycle states ─────────────────────────────────────────────────────────
+// Closed enumeration of durable lifecycle states (lifecycle.md §1; taxonomy.md §6.1).
+export const RELATIONSHIP_LIFECYCLE_STATES = [
+    "draft",
+    "active",
+    "archived",
+    "superseded",
+    "revoked",
+    "blocked",
+    "stale",
+];
+// ─── Activity states (transient, in-memory derived) ───────────────────────────
+// The nine transient activity states from activity-state.md §2. These are NOT persisted
+// on the relationship record; the lifecycle column is durable, this enumeration powers
+// the inspector / graph overlays only. Surfaced here so downstream UI code can pin
+// against a stable closed set in `@oscharko-dev/keiko-contracts`.
+export const RELATIONSHIP_ACTIVITY_STATES = [
+    "inactive",
+    "queued",
+    "active",
+    "processing",
+    "completed",
+    "failed",
+    "blocked",
+    "degraded",
+    "high-throughput",
+];
+// ─── Denial codes ─────────────────────────────────────────────────────────────
+// Closed enumeration of the 18 denial codes (denial-reasons.md §"Catalog"). Tuple order
+// matches the normative "Resolution order" so the validator and reviewers can keep the
+// two views in lock-step. Adding a new code follows the additive-evolution rule from
+// taxonomy.md §3.2 (append, document in denial-reasons.md, slot into resolution order).
+export const RELATIONSHIP_DENIAL_CODES = [
+    "denied/non-existent-source",
+    "denied/non-existent-target",
+    "denied/object-kind-not-yet-supported",
+    "denied/source-kind-not-allowed",
+    "denied/target-kind-not-allowed",
+    "denied/kind-incompatible",
+    "denied/cardinality-exceeded",
+    "denied/cycle-forbidden",
+    "denied/cross-workspace",
+    "denied/path-not-contained",
+    "denied/denied-by-deny-list",
+    "denied/lifecycle-illegal-transition",
+    "denied/endpoint-tombstoned",
+    "denied/endpoint-retired",
+    "denied/endpoint-unavailable",
+    "denied/payload-content-not-permitted",
+    "denied/authority-insufficient",
+    "denied/schema-version-unsupported",
+];
+// The seven definitions (taxonomy.md §5.1 — §5.7). Kept verbose so a future reader does
+// not need to round-trip through the markdown to understand the contract.
+export const RELATIONSHIP_TYPE_DEFINITIONS = {
+    "reads-context": {
+        id: "reads-context",
+        displayName: "reads context",
+        semantics: "A consumer endpoint reads the contextual content of the target at a specific point in time.",
+        validSourceKinds: ["workflow-run", "chat"],
+        validTargetKinds: [
+            "memory",
+            "capsule",
+            "capsule-set",
+            "evidence-run",
+            "workspace-path",
+            "connector",
+            "data-source",
+        ],
+        cardinality: "N:N",
+        direction: "directed",
+        lifecycle: {
+            creatable: true,
+            immutable: true,
+            reconnectable: false,
+            deletable: false,
+            archivable: true,
+        },
+        auditEventOnMutation: true,
+        evidenceRelevance: "reference",
+        ownerPackage: "@oscharko-dev/keiko-workflows",
+        trustBoundary: "per-endpoint",
+    },
+    "proposes-patch": {
+        id: "proposes-patch",
+        displayName: "proposes patch",
+        semantics: "A workflow run proposes a patch against one or more workspace paths. The relationship records the proposal; diff content stays in the harness PatchProposedEvent.",
+        validSourceKinds: ["workflow-run"],
+        validTargetKinds: ["workspace-path", "patch-proposal"],
+        cardinality: "1:N",
+        direction: "directed",
+        lifecycle: {
+            creatable: true,
+            immutable: true,
+            reconnectable: false,
+            deletable: true,
+            archivable: true,
+        },
+        auditEventOnMutation: true,
+        evidenceRelevance: "reference",
+        ownerPackage: "@oscharko-dev/keiko-workflows",
+        trustBoundary: "fs",
+    },
+    "uses-tool": {
+        id: "uses-tool",
+        displayName: "uses tool",
+        semantics: "A workflow run uses a registered tool. Per-call arguments and results remain in the harness ToolCallRequest / ToolCallResult envelopes.",
+        validSourceKinds: ["workflow-run"],
+        validTargetKinds: ["tool", "mcp-tool"],
+        cardinality: "N:N",
+        direction: "directed",
+        lifecycle: {
+            creatable: true,
+            immutable: true,
+            reconnectable: false,
+            deletable: false,
+            archivable: true,
+        },
+        auditEventOnMutation: true,
+        evidenceRelevance: "reference",
+        ownerPackage: "@oscharko-dev/keiko-workflows",
+        trustBoundary: "tool",
+    },
+    "starts-workflow": {
+        id: "starts-workflow",
+        displayName: "starts workflow",
+        semantics: "A chat or a parent workflow run initiates a workflow run. The relationship records the origin; run identity belongs to the workflow ledger.",
+        validSourceKinds: ["chat", "workflow-run"],
+        validTargetKinds: ["workflow-run"],
+        // The exported cardinality is source-centric for UI display and contract summaries:
+        // one chat / parent run may start many runs over time. The validator still enforces
+        // the target-side 1:1 invariant separately via startsWorkflowForTarget.
+        cardinality: "1:N",
+        direction: "directed",
+        lifecycle: {
+            creatable: true,
+            immutable: true,
+            reconnectable: false,
+            deletable: false,
+            archivable: true,
+        },
+        auditEventOnMutation: true,
+        evidenceRelevance: "reference",
+        ownerPackage: "@oscharko-dev/keiko-workflows",
+        trustBoundary: "per-endpoint",
+    },
+    "produces-evidence": {
+        id: "produces-evidence",
+        displayName: "produces evidence",
+        semantics: "A workflow run produces exactly one durable evidence-run record. If a run produces no evidence, no relationship is recorded.",
+        validSourceKinds: ["workflow-run"],
+        validTargetKinds: ["evidence-run"],
+        cardinality: "1:1",
+        direction: "directed",
+        lifecycle: {
+            creatable: true,
+            immutable: true,
+            reconnectable: false,
+            deletable: false,
+            archivable: true,
+        },
+        auditEventOnMutation: true,
+        evidenceRelevance: "produces",
+        ownerPackage: "@oscharko-dev/keiko-evidence",
+        trustBoundary: "evidence",
+    },
+    "references-document": {
+        id: "references-document",
+        displayName: "references document",
+        semantics: "A chat or workflow run holds a structural pointer to a document (workspace file or local-knowledge capsule). Distinct from reads-context: a reference is structural, a read is an event.",
+        validSourceKinds: ["chat", "workflow-run"],
+        validTargetKinds: ["workspace-path", "capsule", "capsule-set"],
+        cardinality: "N:N",
+        direction: "directed",
+        lifecycle: {
+            creatable: true,
+            immutable: false,
+            reconnectable: true,
+            deletable: true,
+            archivable: true,
+        },
+        auditEventOnMutation: true,
+        evidenceRelevance: "reference",
+        ownerPackage: "@oscharko-dev/keiko-workflows",
+        trustBoundary: "per-endpoint",
+    },
+    "depends-on": {
+        id: "depends-on",
+        displayName: "depends on",
+        semantics: "A capsule, capsule-set, workflow run, or memory depends on another. Used by impact analysis (#542). Self-loops and direct two-edge cycles are forbidden at validation time; transitive cycle detection is deferred to impact traversal.",
+        validSourceKinds: ["capsule", "capsule-set", "workflow-run", "memory"],
+        validTargetKinds: [
+            "capsule",
+            "capsule-set",
+            "workflow-run",
+            "memory",
+            "evidence-run",
+            "workspace-path",
+        ],
+        cardinality: "N:N",
+        direction: "directed",
+        lifecycle: {
+            creatable: true,
+            immutable: false,
+            reconnectable: true,
+            deletable: true,
+            archivable: true,
+        },
+        auditEventOnMutation: true,
+        evidenceRelevance: "reference",
+        ownerPackage: "@oscharko-dev/keiko-contracts",
+        trustBoundary: "per-endpoint",
+    },
+};
+// ─── Forbidden-payload key list ───────────────────────────────────────────────
+// The deterministic validator rejects any metadata key whose lowercase form contains
+// one of these substrings. The list mirrors audit-events.md §8.3 (raw prompts, model
+// output text, document content, tool stdout/stderr, patch bodies, secrets, credentials)
+// reduced to the smallest set of token-substrings a payload object would carry. The
+// redactor at `packages/keiko-security/src/redaction.ts` runs at the persist boundary;
+// this list lets the validator reject upstream so the operator sees the rejection
+// rather than a silent redaction (denial-reasons.md `denied/payload-content-not-permitted`).
+//
+// Case-insensitive substring match: e.g. "promptText" → matches "prompt", "ApiKey" →
+// matches "apikey", "rawDocumentContent" → matches "documentcontent".
+export const RELATIONSHIP_FORBIDDEN_METADATA_KEY_SUBSTRINGS = [
+    "prompt",
+    "documentcontent",
+    "filecontent",
+    "toolstdout",
+    "toolstderr",
+    "secret",
+    "credential",
+    "apikey",
+    "password",
+    "token",
+];

package/dist/text-safety.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Remove Unicode bidi/zero-width/BOM/format spoofing code points and C0/C1/DEL control
+ * characters from `value`, preserving TAB/LF/CR. Pure; returns the input unchanged (a no-op,
+ * byte-identical) when it contains no unsafe code points.
+ */
+export declare function stripUnsafeFormatChars(value: string): string;
+//# sourceMappingURL=text-safety.d.ts.map

package/dist/text-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-safety.d.ts","sourceRoot":"","sources":["../src/text-safety.ts"],"names":[],"mappings":"AAoCA;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAkB5D"}

package/dist/text-safety.js

@@ -0,0 +1,58 @@
+// Shared text-safety primitive (Epic #177/#189 grounding hardening, GRD-001).
+//
+// Removes Unicode code points that are invisible or that can reorder a display surface's
+// reading order ("Trojan-source" class) plus C0/C1/DEL control characters. Untrusted
+// repository / document evidence flows into (a) the LLM prompt — where reordered or hidden
+// instructions can subvert the answer — and (b) the browser-rendered answer/citation wire —
+// where React escapes HTML but NOT bidi reordering. Stripping at the surface chokepoints
+// (excerpt → prompt/wire) neutralises both without touching persisted offsets.
+//
+// Whitespace policy: TAB (U+0009), LF (U+000A), and CR (U+000D) are preserved so legitimate
+// formatting of evidence survives; every other control code point is removed.
+//
+// This lives in keiko-contracts (the base layer) so both keiko-local-knowledge and
+// keiko-server can compose it; it mirrors the QI-domain `stripUnsafeFormatChars` without
+// creating a dependency on the QI package.
+// True for an invisible / text-reordering code point: bidi override/embedding/isolate,
+// zero-width joiners, BOM, LRM/RLM, and the Arabic letter mark. Numeric scan keeps the set
+// auditable and avoids embedding invisible literals in the source.
+function isBidiOrZeroWidthCodePoint(cp) {
+    return (cp === 0x061c ||
+        (cp >= 0x200b && cp <= 0x200f) ||
+        (cp >= 0x202a && cp <= 0x202e) ||
+        (cp >= 0x2066 && cp <= 0x2069) ||
+        cp === 0xfeff);
+}
+// True for a C0 control (0x00–0x1F) or DEL/C1 control (0x7F–0x9F), EXCEPT TAB/LF/CR which
+// are legitimate whitespace and preserved.
+function isStrippableControlCodePoint(cp) {
+    if (cp === 0x09 || cp === 0x0a || cp === 0x0d)
+        return false;
+    return cp <= 0x1f || (cp >= 0x7f && cp <= 0x9f);
+}
+/**
+ * Remove Unicode bidi/zero-width/BOM/format spoofing code points and C0/C1/DEL control
+ * characters from `value`, preserving TAB/LF/CR. Pure; returns the input unchanged (a no-op,
+ * byte-identical) when it contains no unsafe code points.
+ */
+export function stripUnsafeFormatChars(value) {
+    // Fast path: scan once; only allocate a rebuilt string if something must be removed.
+    let needsStrip = false;
+    for (const ch of value) {
+        const cp = ch.codePointAt(0) ?? 0;
+        if (isBidiOrZeroWidthCodePoint(cp) || isStrippableControlCodePoint(cp)) {
+            needsStrip = true;
+            break;
+        }
+    }
+    if (!needsStrip)
+        return value;
+    let out = "";
+    for (const ch of value) {
+        const cp = ch.codePointAt(0) ?? 0;
+        if (isBidiOrZeroWidthCodePoint(cp) || isStrippableControlCodePoint(cp))
+            continue;
+        out += ch;
+    }
+    return out;
+}

package/dist/tools.d.ts

@@ -0,0 +1,153 @@
+import type { ToolDefinition } from "./gateway.js";
+export type NetworkPolicy = "inherit" | "none";
+export type FilesystemPolicy = "inherit" | "execution-root";
+export interface SandboxPolicy {
+    readonly envAllowlist: readonly string[];
+    readonly network: NetworkPolicy;
+    readonly filesystem?: FilesystemPolicy | undefined;
+    readonly maxOutputBytes: number;
+    readonly defaultTimeoutMs: number;
+    readonly terminationGraceMs: number;
+}
+export declare const DEFAULT_ENV_ALLOWLIST: readonly string[];
+export declare const DEFAULT_SANDBOX_POLICY: SandboxPolicy;
+export type SandboxBackend = "bubblewrap" | "unshare" | "seatbelt" | "container-docker" | "container-podman" | "none";
+export declare const SANDBOX_BACKENDS: readonly SandboxBackend[];
+export interface SandboxAttestation {
+    readonly backend: SandboxBackend;
+    readonly networkEnforced: boolean;
+    readonly filesystemEnforced: boolean;
+    readonly platform: string;
+}
+export interface CommandRule {
+    readonly executable: string;
+    readonly allowedSubcommands?: readonly string[] | undefined;
+    readonly deniedSubcommands?: readonly string[] | undefined;
+    readonly valueFlags?: readonly string[] | undefined;
+    readonly requiredLeadingFlags?: readonly string[] | undefined;
+    readonly denyFlags?: readonly string[] | undefined;
+    readonly knownSubcommands?: readonly string[] | undefined;
+}
+export declare const DEFAULT_COMMAND_RULES: readonly CommandRule[];
+export interface CommandRunInput {
+    readonly command: string;
+    readonly args?: readonly string[] | undefined;
+    readonly cwd?: string | undefined;
+    readonly timeoutMs?: number | undefined;
+    readonly signal: AbortSignal;
+}
+export interface CommandResult {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly durationMs: number;
+    readonly timedOut: boolean;
+    readonly truncated: boolean;
+    readonly attestation?: SandboxAttestation | undefined;
+}
+export type PatchChangeKind = "create" | "modify" | "delete";
+export interface PatchHunk {
+    readonly oldStart: number;
+    readonly oldLines: number;
+    readonly newStart: number;
+    readonly newLines: number;
+    readonly lines: readonly string[];
+}
+export interface PatchFileChange {
+    readonly path: string;
+    readonly kind: PatchChangeKind;
+    readonly hunks: readonly PatchHunk[];
+    readonly addedLines: number;
+    readonly removedLines: number;
+}
+export type PatchRejectionCode = "size-limit" | "binary" | "path-unsafe" | "path-denied" | "line-limit" | "file-limit" | "malformed";
+export interface PatchRejection {
+    readonly code: PatchRejectionCode;
+    readonly message: string;
+    readonly path?: string | undefined;
+}
+export interface PatchConflict {
+    readonly path: string;
+    readonly hunkIndex: number;
+    readonly reason: string;
+}
+export interface PatchValidation {
+    readonly ok: boolean;
+    readonly files: readonly PatchFileChange[];
+    readonly totalChangedLines: number;
+    readonly totalBytes: number;
+    readonly normalizedDiff?: string | undefined;
+    readonly reasons: readonly PatchRejection[];
+    readonly conflicts: readonly PatchConflict[];
+}
+export interface PatchLimits {
+    readonly maxPatchBytes: number;
+    readonly maxChangedLines: number;
+    readonly maxFilesChanged: number;
+}
+export declare const DEFAULT_PATCH_LIMITS: PatchLimits;
+export interface PatchApplyResult {
+    readonly changedFiles: readonly string[];
+    readonly created: readonly string[];
+    readonly deleted: readonly string[];
+}
+export interface ToolHostConfig {
+    readonly sandbox: SandboxPolicy;
+    readonly commandRules: readonly CommandRule[];
+    readonly patchLimits: PatchLimits;
+    readonly applyEnabled: boolean;
+    readonly maxReadBytes: number;
+}
+export declare const DEFAULT_TOOL_HOST_CONFIG: ToolHostConfig;
+export interface ToolHostConfigInput {
+    readonly sandbox?: Partial<SandboxPolicy> | undefined;
+    readonly commandRules?: readonly CommandRule[] | undefined;
+    readonly patchLimits?: Partial<PatchLimits> | undefined;
+    readonly applyEnabled?: boolean | undefined;
+    readonly maxReadBytes?: number | undefined;
+}
+export interface ToolCallRequest {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly arguments: Record<string, unknown>;
+    readonly signal: AbortSignal;
+}
+export type ToolCallMetadata = {
+    readonly kind: "command";
+    readonly executable: string;
+    readonly argCount: number;
+    readonly exitCode: number | null;
+    readonly timedOut: boolean;
+    readonly sandbox: {
+        readonly envAllowlist: readonly string[];
+        readonly network: "inherit" | "none";
+        readonly maxOutputBytes: number;
+        readonly timeoutMs: number;
+        readonly terminationGraceMs: number;
+        readonly cwdRequested: boolean;
+        readonly filesystem?: FilesystemPolicy | undefined;
+        readonly networkEnforced?: boolean | undefined;
+        readonly filesystemEnforced?: boolean | undefined;
+        readonly backend?: SandboxBackend | undefined;
+    };
+} | {
+    readonly kind: "patch-apply";
+    readonly changedFiles: number;
+    readonly created: number;
+    readonly deleted: number;
+};
+export interface ToolCallResult {
+    readonly toolCallId: string;
+    readonly output: string;
+    readonly durationMs: number;
+    readonly commandExecuted?: boolean | undefined;
+    readonly metadata?: ToolCallMetadata | undefined;
+}
+export interface ToolPort {
+    readonly execute: (request: ToolCallRequest) => Promise<ToolCallResult>;
+    readonly listTools: () => readonly ToolDefinition[];
+}
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/tools.js

@@ -0,0 +1,118 @@
+// Tool-layer contract types and frozen default tables (env allowlist, command rules,
+// sandbox policy, limits, host config). No runtime logic lives here — the
+// `resolveToolHostConfig` helper stays in src/tools/types.ts because it is layer logic, not a
+// contract. `readonly` everywhere; optional props are `| undefined` because
+// exactOptionalPropertyTypes is on. Imports end `.js`, double quotes, `type` keyword.
+// Cross-platform name allowlist. Only names that are PRESENT in the parent are copied, so an
+// absent Windows var on POSIX (or vice versa) is simply skipped.
+//
+// HOME and USERPROFILE are deliberately ABSENT (C5). Forwarding the developer's real home would let
+// a subprocess read ~/.npmrc (npm tokens), ~/.git-credentials, and ~/.aws/… by standard home-dir
+// lookup. runCommand instead injects an ephemeral, EMPTY per-run dir as HOME/USERPROFILE so those
+// lookups resolve to nothing (ADR-0006 D2 Dimension 1).
+export const DEFAULT_ENV_ALLOWLIST = Object.freeze([
+    "PATH",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TZ",
+    "TERM",
+    "TMPDIR",
+    // Windows essentials so spawned tools resolve the shell-less executable correctly.
+    "SystemRoot",
+    "SystemDrive",
+    "PATHEXT",
+    "COMSPEC",
+    "NUMBER_OF_PROCESSORS",
+    "WINDIR",
+]);
+export const DEFAULT_SANDBOX_POLICY = {
+    envAllowlist: DEFAULT_ENV_ALLOWLIST,
+    // `"inherit"` stays the default for the read-only command tools. A caller that executes UNTRUSTED
+    // code (e.g. the #1202 assured pre-filter) passes `network: "none"` explicitly; keiko-sandbox then
+    // wraps the spawn in an OS/container egress boundary, so `"none"` is now HONOURED, not merely
+    // documented (ADR-0043). Leaving the default at `"inherit"` keeps the blast radius minimal.
+    network: "inherit",
+    maxOutputBytes: 262_144,
+    defaultTimeoutMs: 30_000,
+    terminationGraceMs: 2_000,
+};
+export const SANDBOX_BACKENDS = Object.freeze([
+    "bubblewrap",
+    "unshare",
+    "seatbelt",
+    "container-docker",
+    "container-podman",
+    "none",
+]);
+// Minimal, justified default rules. Everything not listed is denied (deny-by-default).
+export const DEFAULT_COMMAND_RULES = Object.freeze([
+    {
+        executable: "npm",
+        // Read-only npm only. Mutating/package-installing subcommands are excluded by omission.
+        allowedSubcommands: Object.freeze([
+            "audit",
+            "ls",
+            "list",
+            "outdated",
+            "view",
+            "info",
+            "help",
+            "ping",
+        ]),
+        // `-c`/`--call` execute a command string in a shell; deny outright (S-H2).
+        denyFlags: Object.freeze(["-c", "--call"]),
+    },
+    {
+        executable: "git",
+        // READ-ONLY git only; push/reset/checkout/commit/merge/rebase/clean/config/remote denied.
+        allowedSubcommands: Object.freeze([
+            "status",
+            "diff",
+            "log",
+            "show",
+            "rev-parse",
+            "ls-files",
+            "describe",
+            "blame",
+            "cat-file",
+        ]),
+        // Global value flags that precede the subcommand (`git -C DIR <sub>`). Skipping them prevents
+        // the value (DIR) from being read as the subcommand (S-H2).
+        valueFlags: Object.freeze([
+            "-C",
+            "-c",
+            "--git-dir",
+            "--work-tree",
+            "--namespace",
+            "--exec-path",
+        ]),
+        // Deny git's code-execution / external-driver flags. `git -c diff.external=<cmd> diff` (and
+        // --config-env/--ext-diff/--textconv) make git spawn an arbitrary command via its OWN shell,
+        // defeating the Node spawn's shell:false; --exec-path redirects git to attacker-supplied sub-binaries.
+        // hasDeniedFlag runs BEFORE subcommand resolution and matches both `--flag value` and
+        // `--flag=value`. `-C`/--git-dir/--work-tree stay value-flags (location only, not execution).
+        denyFlags: Object.freeze([
+            "-c",
+            "--config-env",
+            "--exec-path",
+            "--ext-diff",
+            "--textconv",
+            "--no-index",
+            "--output",
+            "--contents",
+        ]),
+    },
+]);
+export const DEFAULT_PATCH_LIMITS = {
+    maxPatchBytes: 65_536,
+    maxChangedLines: 2_000,
+    maxFilesChanged: 50,
+};
+export const DEFAULT_TOOL_HOST_CONFIG = {
+    sandbox: DEFAULT_SANDBOX_POLICY,
+    commandRules: DEFAULT_COMMAND_RULES,
+    patchLimits: DEFAULT_PATCH_LIMITS,
+    applyEnabled: false,
+    maxReadBytes: 262_144,
+};