# How the Status System Enables Workflow Customization in Craft Agents

> Discover how the Craft Agents status system customizes workflows. Learn how configurable states and automations manage sessions effectively with SessionStatus and statuses/config.json.

- Repository: [Craft Docs/craft-agents-oss](https://github.com/lukilabs/craft-agents-oss)
- Tags: deep-dive
- Published: 2026-04-18

---

**The status system in Craft Agents treats each session as a work item that moves through configurable states, triggering automations and UI updates via the `SessionStatus` type and workspace-level [`statuses/config.json`](https://github.com/lukilabs/craft-agents-oss/blob/main/statuses/config.json) configuration.**

The status system for workflow customization in Craft Agents (lukilabs/craft-agents-oss) provides a declarative mechanism for defining how conversations progress through business workflows. By mapping session states to automation triggers, developers can build complex approval processes, notification pipelines, and agent handoffs without modifying core application logic.

## Core Concepts of the Status System

### SessionStatus Type Definition

The foundation of the status system resides in [`packages/core/src/types/session.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/core/src/types/session.ts), which defines the `SessionStatus` enum and extends the `Session` interface with an optional `status` field. This type-safe definition ensures that all workspace states conform to a consistent schema across the application.

### Workspace Configuration Storage

Status configurations are stored in the workspace file **[`statuses/config.json`](https://github.com/lukilabs/craft-agents-oss/blob/main/statuses/config.json)**. This file acts as the source of truth for which statuses are valid within a specific workspace, allowing different teams to define custom workflows such as "Backlog," "In Review," and "Deployed" without code changes.

### Validation and Error Handling

The [`packages/shared/src/statuses/validation.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/shared/src/statuses/validation.ts) module provides runtime validation against the workspace configuration. When a status change is requested, the system checks [`packages/shared/src/statuses/types.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/shared/src/statuses/types.ts) to verify that the target status exists in [`statuses/config.json`](https://github.com/lukilabs/craft-agents-oss/blob/main/statuses/config.json), throwing a descriptive error if an undeclared status is used.

## Programmatic Status Changes

### The set_session_status Tool

Agents interact with the status system through the `set_session_status` tool defined in [`packages/session-tools-core/src/tool-defs.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/session-tools-core/src/tool-defs.ts). This tool accepts a `sessionId` (optional, defaults to current session) and a `status` parameter, allowing agents to advance workflows based on conversation outcomes.

### Handler Implementation

The tool handler in [`packages/session-tools-core/src/handlers/set-session-status.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/session-tools-core/src/handlers/set-session-status.ts) processes agent requests by invoking `ctx.setSessionStatus`. This abstraction layer ensures that agents cannot directly manipulate workspace files, maintaining security boundaries while enabling workflow automation.

### Server-Side Persistence

The `SessionManager` class in [`packages/server-core/src/sessions/SessionManager.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/server-core/src/sessions/SessionManager.ts) implements the actual status mutation. When `setSessionStatus` is called, the method persists the change to [`statuses/config.json`](https://github.com/lukilabs/craft-agents-oss/blob/main/statuses/config.json) and emits a `SessionStatusChange` event through the automation system, triggering any configured downstream actions.

## Workflow Automation Integration

### Event Emission and Listening

The [`packages/shared/src/automations/event-bus.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/shared/src/automations/event-bus.ts) module defines the `SessionStatusChangePayload` interface, which carries the `sessionId`, `newState`, and optional metadata such as previous state and timestamp. This event bus decouples status changes from automation execution, enabling asynchronous workflow processing.

### Automation Configuration Examples

Automations are configured in workspace files (typically under `.craft/automations`) and listen for `SessionStatusChange` events. For example, when a session transitions to `done`, an automation might invoke the `close_session` tool and send an email notification:

```json
{
  "SessionStatusChange": [
    {
      "if": {
        "newState": "done"
      },
      "then": [
        { "tool": "close_session", "args": {} },
        { "tool": "send_email", "args": { "to": "owner@example.com", "subject": "Session completed" } }
      ]
    }
  ]
}

```

### Legacy Event Mapping

The [`packages/shared/src/automations/schemas.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/shared/src/automations/schemas.ts) file maintains backward compatibility by mapping legacy `TodoStateChange` events to the modern `SessionStatusChange` type. This ensures that existing automations continue functioning while migrating to the current status system.

## UI and Prompt Integration

### Rendering Status Activities

The UI layer in [`packages/ui/src/components/chat/turn-utils.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/ui/src/components/chat/turn-utils.ts) handles status visualization by checking activity objects with `type: 'status'`. The component renders a spinner emoji (⏳) while `status` equals `running`, a checkmark (✅) when `completed`, and an error icon (❌) for failures, providing immediate visual feedback on workflow state.

### System Prompt Documentation

System prompts defined in [`packages/shared/src/prompts/system.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/shared/src/prompts/system.ts) explicitly document the `set_session_status` tool, instructing agents that status changes can trigger automations via `SessionStatusChange` events. This documentation ensures that AI agents understand the workflow implications of status updates without requiring hardcoded logic.

## Summary

- The **status system** in Craft Agents uses `SessionStatus` (defined in [`packages/core/src/types/session.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/core/src/types/session.ts)) and workspace-specific [`statuses/config.json`](https://github.com/lukilabs/craft-agents-oss/blob/main/statuses/config.json) to create configurable workflows.
- **Programmatic control** flows through the `set_session_status` tool → handler → `SessionManager.setSessionStatus`, which persists changes and emits events.
- **Automation integration** occurs via `SessionStatusChange` events (defined in [`packages/shared/src/automations/event-bus.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/shared/src/automations/event-bus.ts)), allowing user-defined automations to trigger on status transitions.
- **Legacy compatibility** is maintained through schema mappings in [`packages/shared/src/automations/schemas.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/shared/src/automations/schemas.ts).
- **UI reflection** and **agent prompts** ensure that status changes are visible to users and understood by AI agents as workflow triggers.

## Frequently Asked Questions

### How do I define custom statuses for my workspace?

Create or edit the [`statuses/config.json`](https://github.com/lukilabs/craft-agents-oss/blob/main/statuses/config.json) file in your workspace root. This JSON file declares the valid status strings (e.g., `["backlog", "in_progress", "needs_review", "done"]`) that the validation logic in [`packages/shared/src/statuses/validation.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/shared/src/statuses/validation.ts) will enforce. Any status not listed in this configuration will be rejected when an agent or script attempts to apply it.

### What happens when an agent calls set_session_status?

When an agent invokes the `set_session_status` tool, the request flows through the handler in [`packages/session-tools-core/src/handlers/set-session-status.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/session-tools-core/src/handlers/set-session-status.ts) to `SessionManager.setSessionStatus` in [`packages/server-core/src/sessions/SessionManager.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/server-core/src/sessions/SessionManager.ts). The manager validates the status against the workspace configuration, persists the change to [`statuses/config.json`](https://github.com/lukilabs/craft-agents-oss/blob/main/statuses/config.json), and emits a `SessionStatusChange` event via the automation event bus, potentially triggering user-defined automations before returning success to the agent.

### Can I trigger external integrations when a status changes?

Yes, by configuring automations that listen for `SessionStatusChange` events in your workspace automation files (typically under `.craft/automations`). According to the schema in [`packages/shared/src/automations/schemas.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/shared/src/automations/schemas.ts), you can define conditional logic that invokes tool calls such as `send_email`, `slack_notification`, or custom webhooks when a session enters specific states like `done` or `needs_review`, enabling seamless integration with external CI/CD pipelines or notification systems.

### How does the UI reflect status changes in real-time?

The UI components in [`packages/ui/src/components/chat/turn-utils.ts`](https://github.com/lukilabs/craft-agents-oss/blob/main/packages/ui/src/components/chat/turn-utils.ts) monitor activity objects with `type: 'status'`. When a status activity is `running`, the interface displays a spinner (⏳); when `completed`, it shows a checkmark (✅); and when `error`, it displays a failure icon (❌). Because the `SessionManager` emits events immediately upon persistence, the UI receives real-time updates through the application's event stream, providing immediate visual feedback on workflow progression without requiring page refreshes.