# Where Is the Permission Mode Implementation in Craft Agents?

> Find the permission mode implementation in Craft Agents within packages/shared/src/agent/mode-types.ts. Learn about canonical mode names and parsing helpers.

- Repository: [Craft Ai Agents/craft-agents-oss](https://github.com/craft-ai-agents/craft-agents-oss)
- Tags: internals
- Published: 2026-07-04

---

**The permission mode implementation in Craft Agents is located in [`packages/shared/src/agent/mode-types.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/mode-types.ts) defines the core logic, consuming modules implement the runtime behavior:

- **[`packages/shared/src/agent/mode-manager.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/agent/mode-manager.ts)** – Runtime state management and permission enforcement
- **[`packages/shared/src/workspaces/types.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/workspaces/types.ts)** – Workspace configuration interfaces referencing `permissionMode`
- **[`packages/shared/src/sessions/types.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/sessions/types.ts)** – Session-level permission overrides

## Practical Usage Example

```typescript
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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/mode-manager.ts)) and configuration storage ([`workspaces/types.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/workspaces/types.ts), [`sessions/types.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/agent/mode-manager.ts), which imports definitions from [`mode-types.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/workspaces/types.ts) and [`packages/shared/src/sessions/types.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/sessions/types.ts), allowing granular configuration at the workspace or individual session level according to the craft-agents-oss source code.