Crate forge_primitives 

forge-primitives - types-only crate shared across forge crates.

The workspace base crate. Holds every wire-shape type that crosses any forge-* crate boundary, with no logic, I/O, or async. Other crates depend on this; this depends on nothing forge-shaped.

Module map:

• command - Command enum (UI → agent channel envelope) + IDs.
• ids - SessionId, ToolUseId.
• image - ImageAttachment + clipboard validation helpers.
• messages - top-level stream-json shapes (Message, AssistantEnvelope, Usage, RateLimit*, StopReason, task-lifecycle variants).
• content - wire-side ContentBlock (Text, Thinking, ToolUse, ToolResult, server-tool, Image).
• public_types - public wire types: AccountInfo, McpServer*, McpStatusResponse, ContextUsage*, SDKSessionInfo, SessionMessage*, Sandbox*, StreamEvent.
• hooks - hook event data (HookKind, HookContext, all 12 *Input structs, the two *HookSpecificOutput wrappers).
• permissions - permission decision data (PermissionDecision, ToolPermissionContext, PermissionUpdate*, Permission*).
• options - option-config enums shared between the SDK’s Options builder and consumers (PermissionMode, SystemPromptKind, SdkPluginConfig).
• subagents - SubagentDefinition + nested types.
• runtime - live runtime state: mode/model state, available commands/agents/models, rate-limit views, retry classification, terminal reasons.
• session_update - wire-side support types for streaming session events (chunks, tool calls, tool-call updates, plan entries, output metadata).
• permission_interaction - the shapes one permission interaction is made of: the request the CLI raises, the options it offers, and the answer a person gives (distinct from the wire-side decisions in permissions).
• question - AskUserQuestion request/response shapes.
• mcp_ui_sync - MCP UI events (McpOperationError).
• session_meta - PromptChunk.
• project_key - ProjectKey, the canonical on-disk project identity.
• handoff - one session swap: the record the swap signal carries, the brief a successor is given, and the numbers kept for tuning the trigger.
• settings - the effective-config document a server pushes: the areas, every key’s value, and when an edit to it takes effect.
• wire - the socket’s binary frame tags shared by the server and the shell.
• biometric - one device’s enrolment as a view draws it, its purposes, and the opaque blob a release hands back.

Add a type here when 2+ forge crates need it. Never reach for cross-crate pub use chains as a substitute.

Re-exports

pub use call_output::CallOutput;

pub use client::ClientConfig;

pub use command::AgentCommand;

pub use content::ContentBlock;

pub use cron::CronEntry;

pub use cron::CronId;

pub use cron::CronKind;

pub use error::AppError;

pub use gotify::GotifyConfig;

pub use gotify::GotifyMessage;

pub use gotify::GotifySubscription;

pub use handoff::HandoffBrief;

pub use handoff::HandoffCycle;

pub use handoff::HandoffGitState;

pub use handoff::HandoffReason;

pub use handoff::HandoffRecord;

pub use handoff::HandoffSection;

pub use handoff::HandoffSuccessor;

pub use hooks::BaseHookInput;

pub use hooks::HookContext;

pub use hooks::HookKind;

pub use hooks::NotificationInput;

pub use hooks::PermissionRequestInput;

pub use hooks::PostToolUseFailureInput;

pub use hooks::PostToolUseInput;

pub use hooks::PreCompactInput;

pub use hooks::PreToolUseHookSpecificOutput;

pub use hooks::PreToolUseInput;

pub use hooks::StopInput;

pub use hooks::SubagentContext;

pub use hooks::SubagentStartInput;

pub use hooks::SubagentStopInput;

pub use hooks::UserPromptSubmitHookSpecificOutput;

pub use hooks::UserPromptSubmitInput;

pub use ids::SessionId;

pub use ids::ToolUseId;

pub use image::ImageAttachment;

pub use image::SUPPORTED_IMAGE_MIME_TYPES;

pub use image::display_blocks;

pub use image::is_supported_image_type;

pub use image::is_valid_base64;

pub use image::payload_bytes;

pub use image::validate_image;

pub use mcp_ui_sync::McpOperationError;

pub use messages::StopHookInfo;

pub use messages::WorkflowProgressEvent;

pub use messages::AssistantEnvelope;

pub use messages::AssistantMessageError;

pub use messages::Message;

pub use messages::RateLimitInfo;

pub use messages::RateLimitStatus;

pub use messages::RateLimitType;

pub use messages::StopReason;

pub use messages::TaskNotificationStatus;

pub use messages::TaskUsage;

pub use messages::Usage;

pub use messages::UserEnvelope;

pub use messages::names_a_dispatch;

pub use options::SdkPluginConfig;

pub use options::SystemPromptKind;

pub use permission::PermissionMode;

pub use permission_interaction::PermissionDisplay;

pub use permission_interaction::PermissionOption;

pub use permission_interaction::PermissionOutcome;

pub use permission_interaction::PermissionRequest;

pub use permissions::PermissionBehavior;

pub use permissions::PermissionDecision;

pub use permissions::PermissionRuleValue;

pub use permissions::PermissionUpdate;

pub use permissions::PermissionUpdateDestination;

pub use permissions::ToolPermissionContext;

pub use project_key::ProjectKey;

pub use public_types::AccountInfo;

pub use public_types::ContextUsageResponse;

pub use public_types::ConversationHistory;

pub use public_types::ForgeAccountIdentity;

pub use public_types::McpServerConfig;

pub use public_types::McpServerConnectionStatus;

pub use public_types::McpServerInfo;

pub use public_types::McpServerStatus;

pub use public_types::McpSetServersResponse;

pub use public_types::McpStatusResponse;

pub use public_types::McpToolAnnotations;

pub use public_types::McpToolInfo;

pub use public_types::SDKSessionInfo;

pub use public_types::SessionHistory;

pub use public_types::SessionMessage;

pub use public_types::SessionMessageKind;

pub use public_types::StreamEvent;

pub use public_types::TranscriptAnchor;

pub use public_types::TranscriptSpan;

pub use question::QuestionAnnotation;

pub use question::QuestionOption;

pub use question::QuestionOutcome;

pub use question::QuestionPrompt;

pub use question::QuestionRequest;

pub use review::ReviewAnchor;

pub use review::ReviewAuthor;

pub use review::ReviewComment;

pub use review::ReviewSet;

pub use review::ReviewSide;

pub use review::ReviewStatus;

pub use review::ReviewThread;

pub use runtime::ApiRetryError;

pub use runtime::ApiRetryUpdate;

pub use runtime::AvailableAgent;

pub use runtime::AvailableCommand;

pub use runtime::AvailableModel;

pub use runtime::CurrentModel;

pub use runtime::EffortLevel;

pub use runtime::ModeInfo;

pub use runtime::ModeState;

pub use runtime::MonitorRecord;

pub use runtime::MonitorStatus;

pub use runtime::RateLimitUpdate;

pub use runtime::RuntimeSessionState;

pub use runtime::SessionLifecycleState;

pub use runtime::SessionTurnState;

pub use runtime::SettingsParseErrorUpdate;

pub use runtime::TerminalReason;

pub use server::DEFAULT_SERVER_PORT;

pub use server::ServerConfig;

pub use session_meta::PromptChunk;

pub use session_slot::SessionSlot;

pub use session_update::BashOutputMetadata;

pub use session_update::ChunkContent;

pub use session_update::TaskMetadata;

pub use session_update::ToolCall;

pub use session_update::ToolCallContent;

pub use session_update::ToolCallLocation;

pub use session_update::ToolCallStatus;

pub use session_update::ToolCallUpdate;

pub use session_update::ToolCallUpdateFields;

pub use session_update::ToolKind;

pub use session_update::ToolOutputMetadata;

pub use settings::EditKind;

pub use settings::EffectClass;

pub use settings::SettingKind;

pub use settings::SettingsArea;

pub use settings::SettingsDocument;

pub use settings::SettingsEdit;

pub use settings::SettingsEditOp;

pub use settings::SettingsEditRequest;

pub use settings::SettingsKey;

pub use settings::SettingsTotals;

pub use subagents::EffortPreset;

pub use subagents::SubagentDefinition;

pub use subagents::SubagentMcpServerRef;

pub use subagents::SubagentMemory;

pub use tasks::Task;

pub use tasks::TaskId;

pub use tasks::TaskStatus;

pub use turn_error::TurnErrorClass;

pub use workers::FORGE_WORKER_TAG_PREFIX;

pub use workers::LEAD_LABEL;

pub use workers::WorkerLiveness;

pub use workers::WorkerStatus;

pub use workers::worker_tag;

Modules

account

Account identity shapes shared across the forge crates.

background

The seat’s live tasks, as a view reads it.

biometric

The biometric proxy’s shapes: one device’s enrolment, the purposes it carries, and the blob a release hands back.

browser

What a browser tool call hands back from the server’s browser.

call_output

A call’s own output, as the read answers it.

client

The [client] section of forge.toml.

cloud

Cloud-side wire shape types.

command

Command - the UI → agent channel envelope.

content

Content blocks inside assistant and user messages.

cron

Durable forge-cron wire types.

document

The document hand-off’s types: what a hand-off names, and what a read answers with.

error

App-level error enum used across forge crates. forge_workspace::SessionUpdate::FatalError carries this type.

git

Git introspection data shapes.

git_diff

Git diff snapshot types.

gotify

Gotify inbound-integration wire types.

handoff

The handoff record: what one session swap carries, and the numbers it leaves behind for tuning the trigger.

hooks

Hook callback wire-data - input payloads, output decisions, and the lifecycle plumbing.

ids

Identity newtypes used across forge crates.

image

Image-attachment wire-shape types + validation, shared between forge-agent and a view.

mcp_ui_sync

MCP-side UI events - operation-error envelopes that surface failures from the MCP orchestrator.

messages

Top-level stream-json message shapes.

options

Pure-data option enums shared across forge-* crates.

permission

Canonical PermissionMode enum, used by:

permission_interaction

The shapes one permission interaction is made of - PermissionRequest (what the agent surfaces when the CLI asks for tool approval), the options it offers, and PermissionOutcome (what a person picks).

permissions

Permission decision wire-data - ToolPermissionContext, PermissionDecision, PermissionUpdate, PermissionUpdateDestination, PermissionBehavior, PermissionRuleValue. The matching CanUseToolCallback trait stays SDK-side because it owns function-pointer dispatch.

plugins

Plugin inventory + CLI-action wire shapes. SessionUpdate variants carry these directly; loaders (refresh_inventory, the claude plugin shell-out, etc.) live in forge_agent::userdata::plugins.

project_key

ProjectKey - the canonical on-disk project identity.

public_types

Public types that don’t yet participate in any wire-path in forge-sdk but are useful for callers that build or inspect configuration values. The serde impls match the CLI’s wire shape exactly.

question

UI-side AskUserQuestion request/response shapes - what the agent surfaces to the UI when a tool wants structured user input, and what the user picks.

review

Durable local-review wire types.

runtime

Runtime status - mode/model state, available models/commands/agents, rate-limit views, retry classification, session status, terminal reason, monitor records. Wire-shape state the agent ↔ UI channel passes around to describe “what’s the live session doing right now”.

server

The [server] section of forge.toml.

session_meta

Session-level metadata - the prompt-chunk envelope.

session_slot

SessionSlot - the (org, project, label) triple that names a session, and the routing key the view <-> workspace boundary addresses one session task by.

session_update

Wire-side support types for streaming session events: content chunks, tool-call envelopes, tool-output metadata, plan entries.

settings

The effective-config document a server pushes to every client.

slack

Slack connector shapes that cross a crate boundary: the [[slack]] config entry an operator writes, the conversation shape users.conversations reports, and the subscription record a session creates.

subagents

Subagent declaration shapes. Pure data - no callbacks.

tasks

Task records: the shape a declared piece of live work takes as it crosses crate boundaries.

terminal

The terminal’s wire shapes: what a client draws, what a hand-off parks, and what the agent’s tools answer.

token_usage

Token/cost accounting shapes for the usage subject.

turn_error

Turn-error classification used by both forge-agent (the classifier lives there next to the matching regex helpers) and forge-workspace (re-emitted via SessionUpdate::TurnError). The enum itself lives here so neither crate has to re-state it.

usage

Anthropic plan-usage snapshot data shapes.

vault

The vault family’s ask shape: the draft one vault call parks for the reader’s approval, the answer a person gives it, and the tools those calls name.

wire

The socket’s binary frame tags, shared by every Rust half that speaks it.

workers

Worker-session shared types: tag constants, status snapshot, and the worker_tag() helper used by every crate that needs to format a worker’s {"type":"tag","tag":"forge:worker:<label>"} JSONL row consistently.