@praxis-ai/praxis 0.1.0

package/dist/storagePool/baseToolStorage/gitBase/stash/git.cleanUntrackedFiles/core.js

@@ -0,0 +1,417 @@
+/*
+ * git.cleanUntrackedFiles storage core.
+ * Owns the fixed git clean workspace deletion contract and delegates host execution to BaseToolExecutorPort.git.runGit.
+ */
+export const gitCleanUntrackedFilesDescriptor = {
+    toolId: "git.cleanUntrackedFiles",
+    toolKind: "git.cleanUntrackedFiles",
+    capability: "clean-untracked-files",
+    route: "agent_executionEngine.basic_toolLayer.baseTools.gitBase.stash",
+    defaultDryRun: true,
+    defaultDispatch: "dry-run",
+    tapOwnsApproval: true,
+    requiresTapApproval: true,
+    runtimeEntryPort: "BaseToolExecutorPort.git.runGit",
+    operationRisk: "destructive",
+    permissionsRequired: ["git:read", "git:write", "filesystem:read", "filesystem:write"],
+    defaultTimeoutMs: 30_000,
+    maxTimeoutMs: 600_000,
+    unsafeSideEffects: true,
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function booleanValue(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+function stringArrayValue(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string"))
+        return undefined;
+    return value;
+}
+function cleanList(values) {
+    if (!Array.isArray(values))
+        return [];
+    return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+function dryRunEnabled(context) {
+    return context?.dryRun !== false;
+}
+function invocationId(context) {
+    return stringValue(context?.invocationId)?.trim() || "git.cleanUntrackedFiles:dry-run";
+}
+function runtimeId(context) {
+    return stringValue(context?.runtimeId)?.trim() || "runtime.unspecified";
+}
+function auditEvent(type, context, repositoryPath, metadata) {
+    return {
+        type,
+        toolId: gitCleanUntrackedFilesDescriptor.toolId,
+        invocationId: invocationId(context),
+        dryRun: dryRunEnabled(context),
+        repositoryPath,
+        metadata: {
+            ...(context?.auditMetadata ?? {}),
+            ...(metadata ?? {}),
+        },
+    };
+}
+function failure(code, message, boundary, context, repositoryPath) {
+    return {
+        ok: false,
+        toolId: gitCleanUntrackedFilesDescriptor.toolId,
+        error: {
+            code,
+            message,
+            boundary,
+            publicSafe: true,
+            safeForRuntimeInspection: true,
+            internalDetailExposed: false,
+        },
+        audit: [auditEvent("agentCore.basicTool.git.cleanUntrackedFiles.rejected", context, repositoryPath, { code })],
+        events: ["basicTool.git.cleanUntrackedFiles.rejected"],
+    };
+}
+function normalizeContext(rawContext, legacyRequest) {
+    const contextRecord = rawContext === undefined ? {} : rawContext;
+    if (!isRecord(contextRecord)) {
+        return failure("INVALID_CONTEXT", "git.cleanUntrackedFiles context must be an object", "input", undefined);
+    }
+    const guard = contextRecord.guard;
+    if (guard !== undefined && !isRecord(guard)) {
+        return failure("INVALID_CONTEXT", "git.cleanUntrackedFiles context.guard must be an object", "input", undefined);
+    }
+    const allowedRepositoryRoots = stringArrayValue(contextRecord.allowedRepositoryRoots);
+    if (contextRecord.allowedRepositoryRoots !== undefined && allowedRepositoryRoots === undefined) {
+        return failure("INVALID_CONTEXT", "git.cleanUntrackedFiles context.allowedRepositoryRoots must be a string array", "input", undefined);
+    }
+    const grantedPermissions = stringArrayValue(contextRecord.grantedPermissions);
+    if (contextRecord.grantedPermissions !== undefined && grantedPermissions === undefined) {
+        return failure("INVALID_CONTEXT", "git.cleanUntrackedFiles context.grantedPermissions must be a string array", "input", undefined);
+    }
+    const auditMetadata = isRecord(contextRecord.auditMetadata) ? contextRecord.auditMetadata : undefined;
+    if (contextRecord.auditMetadata !== undefined && auditMetadata === undefined) {
+        return failure("INVALID_CONTEXT", "git.cleanUntrackedFiles context.auditMetadata must be an object", "input", undefined);
+    }
+    return {
+        runtimeId: stringValue(contextRecord.runtimeId) ?? stringValue(legacyRequest.runtimeId),
+        sessionId: stringValue(contextRecord.sessionId),
+        invocationId: stringValue(contextRecord.invocationId) ?? stringValue(legacyRequest.invocationId),
+        dryRun: booleanValue(contextRecord.dryRun) ?? booleanValue(legacyRequest.dryRun),
+        guard: guard === undefined
+            ? undefined
+            : {
+                allowed: booleanValue(guard.allowed),
+                accepted: booleanValue(guard.accepted),
+                reason: stringValue(guard.reason),
+            },
+        allowedRepositoryRoots,
+        grantedPermissions: grantedPermissions,
+        auditMetadata,
+    };
+}
+function normalizeRepositoryPath(value, context) {
+    const normalized = stringValue(value)?.trim() ?? "";
+    if (normalized.length === 0) {
+        return failure("MISSING_REPOSITORY_PATH", "git.cleanUntrackedFiles requires target.repositoryPath", "input", context);
+    }
+    if (normalized.includes("\0")) {
+        return failure("INVALID_ARGUMENT", "git.cleanUntrackedFiles repositoryPath cannot contain NUL bytes", "input", context, normalized);
+    }
+    return normalized;
+}
+function normalizePath(value, context, repositoryPath) {
+    const normalized = value.trim().replaceAll("\\", "/");
+    if (normalized.length === 0)
+        return "";
+    if (normalized.includes("\0") || normalized.startsWith("/") || /^[A-Za-z]:\//u.test(normalized)) {
+        return failure("PATH_OUTSIDE_SCOPE", "git.cleanUntrackedFiles target.paths must be repository-relative paths", "scope", context, repositoryPath);
+    }
+    const parts = normalized.split("/").filter(Boolean);
+    if (parts.includes("..")) {
+        return failure("PATH_OUTSIDE_SCOPE", "git.cleanUntrackedFiles target.paths must stay inside the repository", "scope", context, repositoryPath);
+    }
+    return normalized.replace(/\/+$/u, "");
+}
+function normalizePaths(value, context, repositoryPath) {
+    const raw = stringArrayValue(value);
+    if (value !== undefined && raw === undefined) {
+        return failure("INVALID_PATH", "git.cleanUntrackedFiles target.paths must be a string array", "input", context, repositoryPath);
+    }
+    const normalized = [];
+    for (const item of cleanList(raw)) {
+        const path = normalizePath(item, context, repositoryPath);
+        if (typeof path !== "string")
+            return path;
+        if (path.length > 0)
+            normalized.push(path);
+    }
+    return [...new Set(normalized)];
+}
+function normalizeIgnoredMode(value, context, repositoryPath) {
+    if (value === undefined || value === "none")
+        return "none";
+    if (value === "tracked-ignored" || value === "ignored-only")
+        return value;
+    return failure("INVALID_IGNORED_MODE", "git.cleanUntrackedFiles target.ignoredMode must be tracked-ignored, ignored-only, or none", "input", context, repositoryPath);
+}
+function normalizeTimeout(value, context, repositoryPath) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > gitCleanUntrackedFilesDescriptor.maxTimeoutMs) {
+        return failure("INVALID_TIMEOUT", `git.cleanUntrackedFiles timeoutMs must be an integer from 1 to ${gitCleanUntrackedFilesDescriptor.maxTimeoutMs}`, "input", context, repositoryPath);
+    }
+    return value;
+}
+function normalizeRequest(request) {
+    if (request !== undefined && !isRecord(request)) {
+        return failure("INVALID_ARGUMENT", "git.cleanUntrackedFiles request must be an object", "input", undefined);
+    }
+    const requestRecord = isRecord(request) ? request : {};
+    const context = normalizeContext(requestRecord.context, requestRecord);
+    if ("ok" in context)
+        return context;
+    const targetRecord = isRecord(requestRecord.target) ? requestRecord.target : requestRecord;
+    if (requestRecord.target !== undefined && !isRecord(requestRecord.target)) {
+        return failure("INVALID_ARGUMENT", "git.cleanUntrackedFiles target must be an object", "input", context);
+    }
+    const repositoryPath = normalizeRepositoryPath(targetRecord.repositoryPath, context);
+    if (typeof repositoryPath !== "string")
+        return repositoryPath;
+    const paths = normalizePaths(targetRecord.paths, context, repositoryPath);
+    if ("ok" in paths)
+        return paths;
+    const ignoredMode = normalizeIgnoredMode(targetRecord.ignoredMode, context, repositoryPath);
+    if (typeof ignoredMode !== "string")
+        return ignoredMode;
+    const timeoutMs = normalizeTimeout(requestRecord.timeoutMs, context, repositoryPath);
+    if (timeoutMs !== undefined && typeof timeoutMs !== "number")
+        return timeoutMs;
+    return {
+        target: {
+            repositoryPath,
+            paths,
+            includeDirectories: targetRecord.includeDirectories !== false,
+            ignoredMode,
+        },
+        context,
+        timeoutMs,
+    };
+}
+function normalizeAllowedRoot(root) {
+    const trimmed = root.trim();
+    return trimmed === "/" ? trimmed : trimmed.replace(/\/+$/u, "");
+}
+function ensureScope(repositoryPath, context) {
+    const allowedRoots = cleanList(context?.allowedRepositoryRoots).map(normalizeAllowedRoot);
+    if (allowedRoots.length === 0)
+        return undefined;
+    const allowed = allowedRoots.some((root) => repositoryPath === root || repositoryPath.startsWith(`${root}/`));
+    return allowed
+        ? undefined
+        : failure("SCOPE_REJECTED", "git.cleanUntrackedFiles target repository is outside the allowed repository roots", "scope", context, repositoryPath);
+}
+function ensurePermissions(repositoryPath, context) {
+    const granted = cleanList(context?.grantedPermissions);
+    if (granted.length === 0)
+        return undefined;
+    const missing = gitCleanUntrackedFilesDescriptor.permissionsRequired.filter((permission) => !granted.includes(permission));
+    return missing.length === 0
+        ? undefined
+        : failure("PERMISSION_DENIED", `git.cleanUntrackedFiles is missing permissions: ${missing.join(", ")}`, "permission", context, repositoryPath);
+}
+function ensureGovernance(repositoryPath, context) {
+    if (dryRunEnabled(context))
+        return undefined;
+    if (context.guard?.allowed === true || context.guard?.accepted === true)
+        return undefined;
+    return failure("GOVERNANCE_REJECTED", context.guard?.reason ?? "git.cleanUntrackedFiles requires an affirmative runtime guard for real execution", "governance", context, repositoryPath);
+}
+function providerArgs(target, dryRun) {
+    return [
+        "clean",
+        ...(dryRun ? ["--dry-run"] : []),
+        "-f",
+        ...(target.includeDirectories ? ["-d"] : []),
+        ...(target.ignoredMode === "tracked-ignored" ? ["-x"] : []),
+        ...(target.ignoredMode === "ignored-only" ? ["-X"] : []),
+        ...(target.paths.length === 0 ? [] : ["--", ...target.paths]),
+    ];
+}
+function commandPreview(target, dryRun) {
+    return ["git", "-C", target.repositoryPath, ...providerArgs(target, dryRun)];
+}
+const runtimeEntry = {
+    owner: "runtime",
+    port: "BaseToolExecutorPort.git.runGit",
+    method: "runGit",
+    binary: "git",
+    argvMode: "fixed-clean-untracked-workspace-deletion",
+    allowedSubcommand: "clean",
+};
+function riskFor(target) {
+    return {
+        category: "destructive",
+        riskLevel: "destructive",
+        mutatesRepository: true,
+        mutatesWorkingTree: true,
+        mutatesIndex: false,
+        deletesUntrackedFiles: true,
+        mayDeleteIgnoredFiles: target.ignoredMode !== "none",
+        repositoryWide: target.paths.length === 0,
+        spawnsProcess: true,
+        requiresTapApproval: true,
+        runtimeOwnsExecution: true,
+    };
+}
+function plan(normalized, dispatch, dryRun) {
+    const risk = riskFor(normalized.target);
+    return {
+        toolId: "git.cleanUntrackedFiles",
+        toolKind: "git.cleanUntrackedFiles",
+        capability: "clean-untracked-files",
+        runtimeId: runtimeId(normalized.context),
+        invocationId: invocationId(normalized.context),
+        repositoryPath: normalized.target.repositoryPath,
+        paths: normalized.target.paths,
+        includeDirectories: normalized.target.includeDirectories,
+        ignoredMode: normalized.target.ignoredMode,
+        gitArgs: providerArgs(normalized.target, dryRun),
+        commandPreview: commandPreview(normalized.target, dryRun),
+        requiredPermissions: gitCleanUntrackedFilesDescriptor.permissionsRequired,
+        runtimeEntry,
+        risk,
+        dispatch,
+        dryRun,
+        wouldMutateWorkingTree: true,
+        wouldMutateIndex: false,
+        unsafeSideEffects: true,
+        outputEnvelope: { stdoutPreview: "", stderrPreview: "", parsed: false },
+        audit: {
+            guard: "git-clean-untracked-runtime-guard",
+            event: "basicTool.git.cleanUntrackedFiles.planned",
+            governanceRequired: true,
+            tapCanWrap: true,
+            metadata: normalized.context.auditMetadata ?? {},
+        },
+    };
+}
+function lineCount(text) {
+    if (text.length === 0)
+        return 0;
+    return text.split(/\r?\n/u).length;
+}
+function cleanOutputLines(stdout, stderr) {
+    return `${stdout}\n${stderr}`
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+function parseCleanPaths(lines, prefix) {
+    return lines
+        .filter((line) => line.startsWith(prefix))
+        .map((line) => line.slice(prefix.length).trim())
+        .filter(Boolean);
+}
+export function parseGitCleanUntrackedFilesResult(providerResult, target) {
+    const lines = providerResult === undefined ? [] : cleanOutputLines(providerResult.stdout, providerResult.stderr);
+    const removedPaths = parseCleanPaths(lines, "Removing ");
+    const previewPaths = parseCleanPaths(lines, "Would remove ");
+    return {
+        parser: "git-clean-output-v1",
+        paths: target.paths,
+        includeDirectories: target.includeDirectories,
+        ignoredMode: target.ignoredMode,
+        repositoryWide: target.paths.length === 0,
+        exitCode: providerResult?.exitCode,
+        stdoutLineCount: lineCount(providerResult?.stdout ?? ""),
+        stderrLineCount: lineCount(providerResult?.stderr ?? ""),
+        removedPaths,
+        previewPaths,
+        unparsedLineCount: lines.filter((line) => !line.startsWith("Removing ") && !line.startsWith("Would remove ")).length,
+        truncated: false,
+    };
+}
+function success(normalized, dryRun, providerResult) {
+    const executionPlan = plan(normalized, dryRun ? "dry-run" : "runtime-git-executor", dryRun);
+    return {
+        ok: true,
+        toolId: "git.cleanUntrackedFiles",
+        plan: executionPlan,
+        output: {
+            kind: "agentCore.basicTool.git.cleanUntrackedFiles",
+            target: normalized.target,
+            runtimeEntry,
+            risk: executionPlan.risk,
+            gitArgs: executionPlan.gitArgs,
+            commandPreview: executionPlan.commandPreview,
+            timeoutMs: normalized.timeoutMs ?? gitCleanUntrackedFilesDescriptor.defaultTimeoutMs,
+            dryRun,
+            executionBlocked: dryRun,
+            providerCalled: providerResult !== undefined,
+            exitCode: providerResult?.exitCode,
+            stdout: providerResult?.stdout,
+            stderr: providerResult?.stderr,
+            permissionsRequired: gitCleanUntrackedFilesDescriptor.permissionsRequired,
+            unsafeSideEffects: true,
+            deletesUntrackedFiles: true,
+            resultEnvelope: parseGitCleanUntrackedFilesResult(providerResult, normalized.target),
+        },
+        audit: [
+            auditEvent(dryRun ? "agentCore.basicTool.git.cleanUntrackedFiles.dryRun" : "agentCore.basicTool.git.cleanUntrackedFiles.executed", normalized.context, normalized.target.repositoryPath, {
+                pathCount: normalized.target.paths.length,
+                includeDirectories: normalized.target.includeDirectories,
+                ignoredMode: normalized.target.ignoredMode,
+                exitCode: providerResult?.exitCode,
+            }),
+        ],
+        events: [dryRun ? "basicTool.git.cleanUntrackedFiles.dryRun" : "basicTool.git.cleanUntrackedFiles.executed"],
+    };
+}
+export function planGitCleanUntrackedFiles(request = {}) {
+    const normalized = normalizeRequest(request);
+    if ("ok" in normalized)
+        return normalized;
+    const scopeFailure = ensureScope(normalized.target.repositoryPath, normalized.context);
+    if (scopeFailure !== undefined)
+        return scopeFailure;
+    const permissionFailure = ensurePermissions(normalized.target.repositoryPath, normalized.context);
+    if (permissionFailure !== undefined)
+        return permissionFailure;
+    return success(normalized, true);
+}
+export async function executeGitCleanUntrackedFiles(request = {}) {
+    const normalized = normalizeRequest(request);
+    if ("ok" in normalized)
+        return normalized;
+    const scopeFailure = ensureScope(normalized.target.repositoryPath, normalized.context);
+    if (scopeFailure !== undefined)
+        return scopeFailure;
+    const permissionFailure = ensurePermissions(normalized.target.repositoryPath, normalized.context);
+    if (permissionFailure !== undefined)
+        return permissionFailure;
+    const governanceFailure = ensureGovernance(normalized.target.repositoryPath, normalized.context);
+    if (governanceFailure !== undefined)
+        return governanceFailure;
+    if (dryRunEnabled(normalized.context))
+        return success(normalized, true);
+    if (request.provider === undefined) {
+        return failure("PROVIDER_UNAVAILABLE", "git.cleanUntrackedFiles requires runtime.execEngine.git.runGit for real execution", "provider", normalized.context, normalized.target.repositoryPath);
+    }
+    try {
+        const providerResult = await request.provider({
+            repositoryPath: normalized.target.repositoryPath,
+            args: providerArgs(normalized.target, false),
+            timeoutMs: normalized.timeoutMs,
+        }, normalized.context);
+        return success(normalized, false, providerResult);
+    }
+    catch {
+        return failure("PROVIDER_REJECTED", "git.cleanUntrackedFiles provider rejected the request or failed safely", "provider", normalized.context, normalized.target.repositoryPath);
+    }
+}

package/dist/storagePool/baseToolStorage/gitBase/stash/git.cleanUntrackedFiles/deepmind.d.ts

@@ -0,0 +1,2 @@
+import type { GitCleanUntrackedFilesProviderPractice } from "./dependencies.js";
+export declare const deepmindGitCleanUntrackedFilesPractice: GitCleanUntrackedFilesProviderPractice;

package/dist/storagePool/baseToolStorage/gitBase/stash/git.cleanUntrackedFiles/deepmind.js

@@ -0,0 +1,15 @@
+import { createHostExecutorGitCleanUntrackedFilesProvider } from "./dependencies.js";
+export const deepmindGitCleanUntrackedFilesPractice = {
+    providerName: "deepmind",
+    source: {
+        kind: "cli",
+        label: "Gemini CLI GitService-style ownership for git clean untracked",
+    },
+    directCliSupport: true,
+    sideEffectPolicy: "destructive",
+    notes: [
+        "Gemini-style practice separates Git service/runtime ownership from model-facing intent.",
+        "Praxis maps that boundary to BaseToolExecutorPort.git.runGit while preserving fixed-action tool semantics.",
+    ],
+    createProvider: ({ provider, executor }) => provider ?? createHostExecutorGitCleanUntrackedFilesProvider(executor),
+};

package/dist/storagePool/baseToolStorage/gitBase/stash/git.cleanUntrackedFiles/dependencies.d.ts

@@ -0,0 +1,36 @@
+import type { BaseToolExecutorPort } from "../../../../../agentCore/agent_executionEngine/basic_toolLayer/baseTools/baseToolExecutorPort.js";
+import type { GitCleanUntrackedFilesProvider } from "./core.js";
+export type GitCleanUntrackedFilesPracticeProviderName = "anthropic" | "openai" | "deepmind" | "praxis-native";
+export type GitCleanUntrackedFilesDependencies = {
+    executor?: BaseToolExecutorPort;
+    provider?: GitCleanUntrackedFilesProvider;
+};
+export type GitCleanUntrackedFilesProviderPractice = {
+    providerName: GitCleanUntrackedFilesPracticeProviderName;
+    source: {
+        kind: "cli" | "agent-sdk" | "api-sdk" | "praxis-native";
+        label: string;
+        path?: string;
+    };
+    directCliSupport: boolean;
+    sideEffectPolicy: "destructive" | "workspace-mutation" | "runtime-governed";
+    notes: readonly string[];
+    createProvider(dependencies: GitCleanUntrackedFilesDependencies): GitCleanUntrackedFilesProvider | undefined;
+};
+export declare const gitCleanUntrackedFilesDependencyDeclarations: ({
+    dependencyId: string;
+    kind: "runtime";
+    required: true;
+    description: string;
+} | {
+    dependencyId: string;
+    kind: "permission";
+    required: true;
+    description: string;
+} | {
+    dependencyId: string;
+    kind: "binary";
+    required: true;
+    description: string;
+})[];
+export declare function createHostExecutorGitCleanUntrackedFilesProvider(executor: BaseToolExecutorPort | undefined): GitCleanUntrackedFilesProvider | undefined;

package/dist/storagePool/baseToolStorage/gitBase/stash/git.cleanUntrackedFiles/dependencies.js

@@ -0,0 +1,37 @@
+export const gitCleanUntrackedFilesDependencyDeclarations = [
+    {
+        dependencyId: "runtime.execEngine.git.runGit",
+        kind: "runtime",
+        required: true,
+        description: "Runtime-provided git executor exposed through BaseToolExecutorPort.git.runGit",
+    },
+    {
+        dependencyId: "runtime.governancePlane.toolInvocationGrant",
+        kind: "permission",
+        required: true,
+        description: "dryRun:false requires an affirmative runtime guard before provider dispatch.",
+    },
+    {
+        dependencyId: "git",
+        kind: "binary",
+        required: true,
+        description: "Host git binary used by the runtime-owned git executor.",
+    },
+];
+export function createHostExecutorGitCleanUntrackedFilesProvider(executor) {
+    const runGit = executor?.git?.runGit;
+    if (runGit === undefined) {
+        return undefined;
+    }
+    return async (request, _context) => {
+        const result = await runGit({
+            repositoryPath: request.repositoryPath,
+            args: request.args,
+            timeoutMs: request.timeoutMs,
+        });
+        if (!result.ok) {
+            throw new Error(result.error.message);
+        }
+        return result.output;
+    };
+}

package/dist/storagePool/baseToolStorage/gitBase/stash/git.cleanUntrackedFiles/git.cleanUntrackedFiles.md

@@ -0,0 +1,119 @@
+---
+description: "Delete untracked files through fixed git clean semantics."
+argument-hint: '{"target":{"repositoryPath":"/repo/project","paths":["tmp/a.log","build"],"includeDirectories":true,"ignoredMode":"tracked-ignored"},"context":{"dryRun":false,"guard":{"allowed":true,"accepted":true},"allowedRepositoryRoots":["/repo"],"grantedPermissions":["git:read","git:write","filesystem:read","filesystem:write"]}}'
+---
+
+# git.cleanUntrackedFiles
+
+## Use This Tool
+
+Use `git.cleanUntrackedFiles` to delete untracked files through fixed git clean semantics. It is a fixed-action gitBase tool exposed through the unified `BaseToolHandler.invoke()` surface. The model must call this narrow tool rather than `shell.commandExecution`, `git.execute`, or a made-up `gitBase.*` tool id.
+
+Risk class: `destructive`. Runtime contact is owned by `BaseToolExecutorPort.git.runGit`; storage owns validation, fixed-action planning, result parsing, and public-safe errors.
+
+## Call Shape
+
+```json
+{
+  "target": {
+    "repositoryPath": "/repo/project",
+    "paths": [
+      "tmp/a.log",
+      "build"
+    ],
+    "includeDirectories": true,
+    "ignoredMode": "tracked-ignored"
+  },
+  "context": {
+    "dryRun": false,
+    "guard": {
+      "allowed": true,
+      "accepted": true
+    },
+    "allowedRepositoryRoots": [
+      "/repo"
+    ],
+    "grantedPermissions": [
+      "git:read",
+      "git:write",
+      "filesystem:read",
+      "filesystem:write"
+    ]
+  }
+}
+```
+
+## Required Inputs
+
+- `target.repositoryPath`.
+- `context.dryRun`: use `false` only when the runtime/TAP layer has approved real execution.
+- `context.guard`: real execution requires `allowed === true` or `accepted === true`.
+- `context.allowedRepositoryRoots`: runtime-approved repository roots; never widen this from model-provided paths.
+
+## Optional Inputs
+
+- `target.paths`.
+- `target.includeDirectories`.
+- `target.ignoredMode`: none, tracked-ignored, or ignored-only.
+- `timeoutMs`.
+- `context.grantedPermissions`: permission hints such as `git:read`, `git:write`, `filesystem:read`, `filesystem:write`, or `network:egress` according to the action.
+
+## Runtime Behavior
+
+Storage validates unknown JSON before reading nested fields, trims and validates refs or paths, checks repository scope and permissions, and then builds only the fixed action for this tool.
+
+Allowed fixed argv or fixed action:
+
+- `clean -f [-d] [-x|-X] -- <paths>`
+
+If `context.dryRun !== false`, the tool returns a command plan and does not call a provider. If `context.dryRun === false`, storage requires an affirmative guard before dispatch. Missing runtime support returns `PROVIDER_UNAVAILABLE`; provider failures are mapped to public-safe errors such as `PROVIDER_REJECTED`. Runtime/TAP owns process execution, sandboxing, timeout, cancellation, host Git availability, and user-facing approval.
+
+## Returns
+
+Returns a normalized `BaseToolInvokeResult`. The public output includes `runtimeEntry`, `risk`, fixed `gitArgs`, `commandPreview`, `providerCalled`, `executionBlocked`, raw public-safe provider fields when executed, and a parsed `resultEnvelope`.
+
+The result is safe for runtime inspection: no raw stack traces, hidden shell commands, credentials, or private provider internals should be exposed.
+
+## Example
+
+```json
+{
+  "tool": "git.cleanUntrackedFiles",
+  "arguments": {
+    "target": {
+      "repositoryPath": "/repo/project",
+      "paths": [
+        "tmp/a.log",
+        "build"
+      ],
+      "includeDirectories": true,
+      "ignoredMode": "tracked-ignored"
+    },
+    "context": {
+      "dryRun": false,
+      "guard": {
+        "allowed": true,
+        "accepted": true
+      },
+      "allowedRepositoryRoots": [
+        "/repo"
+      ],
+      "grantedPermissions": [
+        "git:read",
+        "git:write",
+        "filesystem:read",
+        "filesystem:write"
+      ]
+    }
+  }
+}
+```
+
+## Avoid
+
+- Do not expose or simulate a generic `git.execute`.
+- Do not let the model provide arbitrary git subcommands or flags.
+- Do not bypass `createBaseToolRegistry().lookupHandler("git.cleanUntrackedFiles")` and `handler.invoke(...)` in integration tests.
+- Do not call shell tools for this Git intent when the fixed-action gitBase tool exists.
+- Do not auto-allow repository roots, destructive actions, network access, or history mutation from model text alone.
+- Do not move approval, sandbox, or live process ownership into storage; runtime and TAP own those boundaries.

package/dist/storagePool/baseToolStorage/gitBase/stash/git.cleanUntrackedFiles/openai.d.ts

@@ -0,0 +1,2 @@
+import type { GitCleanUntrackedFilesProviderPractice } from "./dependencies.js";
+export declare const openaiGitCleanUntrackedFilesPractice: GitCleanUntrackedFilesProviderPractice;

package/dist/storagePool/baseToolStorage/gitBase/stash/git.cleanUntrackedFiles/openai.js

@@ -0,0 +1,15 @@
+import { createHostExecutorGitCleanUntrackedFilesProvider } from "./dependencies.js";
+export const openaiGitCleanUntrackedFilesPractice = {
+    providerName: "openai",
+    source: {
+        kind: "cli",
+        label: "Codex sandbox/runtime executor pattern for git clean untracked",
+    },
+    directCliSupport: true,
+    sideEffectPolicy: "destructive",
+    notes: [
+        "Codex-style practice keeps host process execution behind sandbox/runtime ownership.",
+        "Praxis storage builds fixed argv and delegates only BaseToolExecutorPort.git.runGit to runtime.",
+    ],
+    createProvider: ({ provider, executor }) => provider ?? createHostExecutorGitCleanUntrackedFilesProvider(executor),
+};

package/dist/storagePool/baseToolStorage/gitBase/stash/git.popStashChanges/anthropic.d.ts

@@ -0,0 +1,2 @@
+import type { GitPopStashChangesProviderPractice } from "./dependencies.js";
+export declare const anthropicGitPopStashChangesPractice: GitPopStashChangesProviderPractice;

package/dist/storagePool/baseToolStorage/gitBase/stash/git.popStashChanges/anthropic.js

@@ -0,0 +1,15 @@
+import { createHostExecutorGitPopStashChangesProvider } from "./dependencies.js";
+export const anthropicGitPopStashChangesPractice = {
+    providerName: "anthropic",
+    source: {
+        kind: "cli",
+        label: "Claude Code git stash pop practice through permissioned shell/tool execution",
+    },
+    directCliSupport: true,
+    sideEffectPolicy: "workspace-mutation",
+    notes: [
+        "Claude-style practice treats stash pop as a write action behind explicit tool permission boundaries.",
+        "Praxis narrows that surface to fixed git stash pop argv for one stash ref.",
+    ],
+    createProvider: ({ provider, executor }) => provider ?? createHostExecutorGitPopStashChangesProvider(executor),
+};