Where Is the Permission Mode Implementation in Craft Agents?

The permission mode implementation in Craft Agents is located in packages/shared/src/agent/mode-types.ts, which defines the canonical mode names, conversion helpers, and the parsePermissionMode parser.

In the craft-ai-agents/craft-agents-oss repository, permission modes control how agents interact with system resources and execute operations. Understanding where this logic lives is essential for developers customizing agent behavior or integrating the framework into existing workflows.

Core Implementation File

The canonical source of truth for permission mode logic resides in packages/shared/src/agent/mode-types.ts. This file exports the TypeScript definitions, ordered mode lists, and bidirectional mapping tables that translate between internal system identifiers and user-facing canonical names.

Type Definitions and Constants

The file defines the PermissionMode union type representing valid operational states. It also declares ordered arrays that establish priority hierarchies and readonly mappings that enforce immutability across the application lifecycle.

Internal vs. Canonical Name Mapping

Two critical conversion utilities bridge the gap between storage representations and UI displays:

• parsePermissionMode() – Resolves legacy aliases to standardized internal values and validates user input
• toCanonicalPermissionMode() – Converts internal identifiers back to user-facing strings like 'execute'

Parsing and Validation Functions

The parsePermissionMode() function serves as the primary entry point for normalizing user input. It accepts string values, resolves legacy aliases to modern canonical names, and returns a validated PermissionMode or null for invalid inputs.

Related Files and Integration

While mode-types.ts defines the core logic, consuming modules implement the runtime behavior:

• packages/shared/src/agent/mode-manager.ts – Runtime state management and permission enforcement
• packages/shared/src/workspaces/types.ts – Workspace configuration interfaces referencing permissionMode
• packages/shared/src/sessions/types.ts – Session-level permission overrides

Practical Usage Example

import { parsePermissionMode, PermissionMode } from '@craft-agent/shared/agent/mode-types';

// Parse a user-provided mode name
const mode: PermissionMode | null = parsePermissionMode('execute');
// → 'allow-all'

if (mode) {
  // Convert internal mode to the UI-facing canonical name
  const canonical = toCanonicalPermissionMode(mode);
  // → 'execute'
}

Summary

• The permission mode implementation lives in packages/shared/src/agent/mode-types.ts
• parsePermissionMode() normalizes legacy aliases and validates input strings
• toCanonicalPermissionMode() translates internal values to user-facing names
• Related files handle runtime enforcement (mode-manager.ts) and configuration storage (workspaces/types.ts, sessions/types.ts)

Frequently Asked Questions

What is the main file for permission mode logic in Craft Agents?

The core implementation is in packages/shared/src/agent/mode-types.ts, which contains type definitions, conversion mappings, and the parsePermissionMode validation function used throughout the codebase.

How does Craft Agents handle legacy permission mode aliases?

The parsePermissionMode function in mode-types.ts normalizes legacy aliases to their canonical internal values, ensuring backward compatibility while maintaining strict type safety through the PermissionMode union type.

Where is permission mode state managed at runtime?

Runtime state management occurs in packages/shared/src/agent/mode-manager.ts, which imports definitions from mode-types.ts to enforce permissions during agent execution and handle state transitions between modes.

Can I configure permission modes per workspace or session?

Yes. The permissionMode field appears in both packages/shared/src/workspaces/types.ts and packages/shared/src/sessions/types.ts, allowing granular configuration at the workspace or individual session level according to the craft-agents-oss source code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}