Agent Forge CLI

Release history for the Agent Forge CLI. Commands, authentication, entity sync, simulation, and tool development updates.

Release history for the Agent Forge CLI (configuration management and deployment tooling). Latest release: v0.1.52 (July 2026).

Installation

Install the latest macOS release from the public release channel:

curl -fsSL https://forge.platform.amigo.ai/install.sh | sh

The public installer and built-in forge update command currently support macOS on Intel and Apple Silicon. For an overview of the CLI and its command groups, see the Agent Forge CLI reference.

Releases

Entries from v0.1.x onward track the current Agent Forge CLI release line. The earlier v0.2.x-v0.4.x entries below cover the previous CLI generation.

v0.1.51 - v0.1.52 - Agent Definition Management and Framework Guidance (July 2026)

Agent Definition Management and Framework Guidance

Forge can now validate, register, inspect, and archive customer-authored framework agent definitions from the command line.

What changed:

• forge platform agent-definition validate. Checks a framework-native definition without storing it. Supply the definition name and exactly one JSON source through --file or --body.
• forge platform agent-definition register. Registers a definition for claude-agent-sdk or openai-agents. Re-registering an identical body reports it as unchanged; registering a changed body creates an immutable version.
• Definition discovery and lifecycle commands. list retrieves all active definitions across paginated results, get <definition-id> returns one definition and its version metadata, and archive <definition-id> soft-archives it after confirmation so the name can be reused.
• OpenAI Realtime voice preset. forge platform service voice-config <service-id> --preset gpt_realtime selects the OpenAI Realtime speech-to-speech provider. The existing gpt_live preset remains available.
• Clearer agent-run help. The CLI now names claude-agent-sdk and openai-agents explicitly and explains which SDK each framework identifier selects.

What you need to do:

• No action required. Upgrade to v0.1.52 to manage native agent definitions or use the gpt_realtime preset.

v0.1.43 - v0.1.50 - Unified Runs, Background Reply Polling, and Command Cleanup (July 2026)

Unified Runs, Background Reply Polling, and Command Cleanup

Forge now mirrors the platform's unified Runs surface and provides a protocol-safe way to claim completed background replies.

What changed:

• forge platform run list|summary|get. Lists conversation and framework runs together, summarizes them, and opens a single run by its channel-neutral run ID. List filters cover live status, run kind, and channel.
• Inline conversation evaluation. conversation send-message accepts repeatable --must-contain, --must-not-contain, and --judge-criteria checks. LLM-judge checks require the explicit PII acknowledgement flag.
• forge platform conversation poll. Claims completed background work for a conversation. Forge prints the idempotency key needed to replay an ambiguous claim and acknowledges the result only after successful output.
• Retired commands removed. The review-queue command group and service escalation-policy subcommand are no longer registered because their Platform API endpoints were retired.

What you need to do:

• Use platform run for cross-channel run listings. Conversation-specific commands remain available for opening transcripts and sending turns.
• Update scripts that call retired commands. Remove service escalation-policy invocations. For workspaces enrolled in the private preview, replace legacy review-queue workflows with the platform's external-write proposal review flow.

v0.1.39 - v0.1.40 - Full-Duplex Voice Preset and Per-Model Judge Pricing (July 2026)

Full-Duplex Voice Preset and Per-Model Judge Pricing

Voice configuration and regression evaluation now recognize the latest runtime options.

What changed:

• gpt_live voice preset. Forge accepts the full-duplex gpt_live session-provider family when pushing voice configuration.
• Per-model judge pricing. Regression evaluation selects pricing for the configured judge model rather than applying a single shared estimate.

What you need to do:

• No action required. Upgrade to use the gpt_live preset or the updated regression cost reporting.

v0.1.38 - Conversation Close Command (July 2026)

Conversation Close Command

Text conversations are durable and stay open until explicitly closed, which previously meant a contact on a text channel could never start a fresh conversation from the CLI. A new command closes a conversation directly.

What changed:

• forge platform conversation close <conversation-id> closes a text conversation. The command asks for confirmation before closing; pass --yes / -y to skip the prompt. --json emits a structured receipt with the conversation ID. If the conversation does not exist or is already closed, the command reports that clearly instead of a raw error.
• sms and imessage accepted as channel values. The --channel option on forge platform use-case commands now accepts sms and imessage alongside the existing voice and email values.

What you need to do:

• No action required. These are additive changes.

v0.1.37 - Voice Settings Field Removal (July 2026)

Voice Settings Field Removal

The correction_categories field has been removed from workspace voice settings.

What changed:

• correction_categories removed. forge platform voice-settings get no longer displays a Correction Categories row, and the field is no longer part of the voice-settings payload.

What you need to do:

• Update any scripts that read this field. JSON output from voice-settings get no longer includes correction_categories.

v0.1.35 - Integration Endpoint Commands (July 2026)

Integration Endpoint Commands

Integration endpoints can now be created and listed from the CLI, and endpoints defined inline in an integration file are created together with the integration.

What changed:

• forge platform integration endpoint-create <integration-id> adds one endpoint (or a JSON list of endpoints) to an existing integration via --file / --body. A leading / on an endpoint path is stripped automatically, and failures are reported per endpoint without aborting the batch.
• Inline endpoints on integration create. When an integration definition includes endpoints, forge platform integration create now creates those endpoints too, so one file can define the integration and its endpoints together. Previously the inline endpoints were silently dropped and the created integration had no callable endpoints.
• forge platform integration endpoint-list <integration-id> lists an integration's endpoints, with --json output for scripting.
• forge platform integration test now resolves endpoint names, so you can refer to an endpoint by name when testing an integration.

What you need to do:

• Re-check integrations created with inline endpoints on older versions. If you previously ran integration create with endpoints in the body, those endpoints were not created. Use endpoint-list to verify and endpoint-create to add any that are missing.

v0.1.34 - CLI Self-Update on macOS (July 2026)

CLI Self-Update on macOS

forge update now updates the CLI in place on macOS (Intel and Apple Silicon). It downloads the requested release, verifies its SHA256 checksum, sanity-checks the new binary, and atomically swaps the running install.

What changed:

• forge update installs the latest release. --check reports whether an update is available without installing anything.
• --version <ver> pins an exact release and installs it even if it is older than the current install. Downgrades prompt for confirmation; --yes / -y skips the prompt for scripted use.
• --force reinstalls the current version and is required to overwrite a development build.
• Clear permission errors. If the install location is not writable, the command fails with guidance to re-run with elevated permissions instead of escalating on its own.
• Release notes after updating. After a successful update, forge update prints the release notes for every version the update spans (newest first), so a multi-version jump shows everything you skipped. Fetching notes is best effort and never fails the update.

What you need to do:

• No action required. Once on a version with this command, you can update with forge update instead of downloading a new build manually.

v0.1.30 - Platform Function Register and Test Fixes (July 2026)

Platform Function Register and Test Fixes

What changed:

• forge platform function register now upserts. Registering a function name that already exists updates it in place.
• Manifest input on register. The command accepts a complete function manifest via --file / --body (name, description, function type, parameters, body, timeout, examples). The existing individual flags still work for sql and ai functions; python and udtf functions require a manifest. With manifest input, an optional --name asserts that it matches the manifest's name.
• forge platform function test sends your input. The sample JSON passed with --input is now delivered to the function under test. Previously it was sent under a field the service ignored, so tests executed without the provided input.

What you need to do:

• No action required. Existing register invocations continue to work.

v0.1.28 - Agent Run Commands (July 2026)

Agent Run Commands

A new forge platform agent-run command group creates, monitors, and inspects agent runs.

What changed:

• forge platform agent-run create submits a run for a service with --service-id, --framework <claude-agent-sdk|openai-agents>, and --message, plus optional --version-set (default release) and --timeout-s. --wait polls until the run reaches a terminal status (succeeded, failed, or timed_out) and prints the final result. Framework values are validated before the request is sent.
• Native agent-definition runs. create can also run an agent definition directly: --definition-id (optionally --definition-version; latest when unpinned) runs a registered definition, and --native-config <file> runs an inline definition from a JSON file. Exactly one run source is allowed per invocation.
• forge platform agent-run get --run-id <id> fetches a single run.
• Cache token accounting. Run usage output now includes cached and cache_write token counts. input_tokens excludes cached tokens, so a cache-heavy run can legitimately report near-zero input tokens.
• forge platform agent-run harness-context --service-id <id> [--version-set] shows the context a service provides to an agent run: identity and instructions, world scope, tool descriptors, guardrails, the enforced write floor, and runtime details. The default output is a concise summary; --json prints the full payload.

What you need to do:

• No action required. These are additive commands; all support --json.

v0.1.24 - Session Fleet Status and Conversation Detail (July 2026)

Session Fleet Status and Conversation Detail

What changed:

• forge platform session fleet-status [--fleet voice|tool-runner] reports live session capacity: ready, allocated, and total counts, the maximum-replica ceiling and remaining headroom when configured (rendered - when not), and a per-state breakdown. Omitting --fleet uses the server default (voice).
• forge platform conversation get <conversation-id> fetches a single conversation: a metadata block and the turn transcript. --include-tool-calls adds per-turn tool calls (name, status, call ID), including background completion records. --json outputs the full conversation detail.

What you need to do:

• No action required. These are additive commands.

v0.1.23 - Platform Command Removals (June 2026)

Platform Command Removals

Two forge platform command groups have been removed.

What changed:

• forge platform persona removed. The persona command group (list, get, create, update, delete) is no longer available. The persona entity type used by forge validate and entity sync is unaffected and continues to work.
• forge platform ses-setup removed. The email SES setup command group is no longer available. The forge platform use-case commands (including email use cases and service bindings) and the conversation --channel-kind filter are unchanged.

What you need to do:

• Update scripts that call these commands. Invocations of forge platform persona ... or forge platform ses-setup ... now fail with an unknown-command error.

v0.1.20 - Tool Dispatch Validation (June 2026)

Tool Dispatch Validation

Pre-push validation of tool dispatch settings in a context graph's tool_call_specs is now aligned with what the platform accepts.

What changed:

• result_persistence accepted. Configurations that set result_persistence on a tool call spec no longer fail push validation. This is a live platform field that was previously rejected by mistake, so any configuration setting it could not be pushed.
• Dispatch axis values validated locally. Each axis is checked before the push: execution must be blocking or background, delivery must be interrupt or queue, and lifecycle must be coupled or independent. A typo now fails fast with a clear message instead of being sent to the server.
• execution=background with delivery=queue rejected. The platform does not accept this combination, and the CLI now rejects it locally for faster feedback.
• version_constraint still rejected. This field is not part of the API and remains invalid.
• Dispatch axes in function register output. forge platform function register now prints the optional dispatch axes and their defaults next to the tool_call_specs example.

What you need to do:

• Retry configurations that set result_persistence. If a push previously failed validation because of this field, it now succeeds.

v0.1.18 - Trigger Management, Voice Check, and Voice Config Push Fix (June 2026)

Trigger Management, Voice Check, and Voice Config Push Fix

What changed:

• Full forge platform triggers command group. create, update, pause, resume, fire, and delete join the existing read-only list, get, and runs commands. create, update, and fire accept JSON via --file / --body; delete asks for confirmation unless --yes is passed; pause and resume echo the trigger's is_active state so a no-op is visible rather than silent.
• forge platform voice-check run --spans <file> runs per-call voice-isolation checks over an exported call-trace span file and exits with code 5 on failure, so it can gate CI pipelines.
• Voice config push fix. The session_provider and tts_provider fields in a service voice config are now included when pushing. Previously they were silently dropped, so provider selections never reached the platform.

What you need to do:

• Re-push voice configs that set session_provider or tts_provider. If you pushed these fields with an earlier version, push again so they take effect.

v0.1.15 - Version Set Upsert JSON Body (June 2026)

Version Set Upsert JSON Body

forge platform version-set upsert now accepts a full JSON configuration body.

What changed:

• --body / -b and --file / -f on version-set upsert. The supplied JSON becomes the version-set configuration, which is how you set fields that have no dedicated flags, such as llm_model_preferences and turn_runtime. The existing -a / -g version-pinning flags still apply on top of the body.
• --copy-from and --body / --file are mutually exclusive. Passing both fails fast instead of silently dropping the body.
• Dry-run preview shows the body's effect. The dry-run output includes the llm_model_preferences and turn_runtime values the body sets.

What you need to do:

• No action required. Existing flag-only invocations are unchanged.

v0.1.13 - Surfaces, Audit, and Access Control Commands (June 2026)

Surfaces, Audit, and Access Control Commands

Several new forge platform command groups, plus an STT provider field in voice settings.

What changed:

• forge platform surface covers the full surface lifecycle: list (with --status, --channel, --entity-id, and --limit filters), get, create (--file / --body JSON), deliver (--channel-address), progress, approve, reject (--reason), reshape, and archive (confirmation prompt, --yes to skip).
• forge platform audit provides read-only access-audit commands: list, summary, phi-access, exports, and entity-log <id>.
• forge platform triggers provides read-only trigger commands: list, get <id>, and runs <id> for scheduled trigger configuration and run history.
• forge platform review-queue provides list, dashboard, stats, history, and my-queue for the human-review queue.
• External principals authoring commands. New forge platform external-role (list, get, create, delete), forge platform role-assignment (upsert, list, get, delete), and forge platform role-grant (list, get, create, delete) command groups.
• stt_provider in voice settings. forge platform voice-settings get now shows an STT Provider row (- when unset), and the field can be set with voice-settings update --body '{"stt_provider":"..."}'.

What you need to do:

• No action required. All new commands support --env and --json.

v0.1.5 - Email Channel Commands (June 2026)

Email Channel Commands

New command groups for enabling the email channel on a workspace from the CLI.

What changed:

• forge platform ses-setup: list, create, get, verify, and delete manage email sending setups. create and verify render the DNS records you must publish as a copy-friendly, untruncated table.
• forge platform use-case: list, create, get, and delete manage channel use cases, and bind, unbind, and binding manage a use case's service binding.
• Explicit email consent flags. Creating an email use case requires explicit --unsubscribable and --accepts-cold-inbound values (no silent defaults), and a marketing use case must be unsubscribable - validated before the request is sent.
• --setup-id list filter requires --channel, enforced client-side with a friendly error.

What you need to do:

• No action required. These are additive commands.

v0.1.3 - External Integrations and Workspace-Scoped Authentication (June 2026)

External Integrations and Workspace-Scoped Authentication

This release added external integration credential management and completed workspace scoping for Platform Identity device-code authentication.

What changed:

• forge platform external-integration list (with --search / -q, --sort-by, --limit / -n, and --continuation-token), get <integration-id>, and create (--file / --body JSON).
• Credential subcommands. credential list, credential create (--file / --body JSON), credential rotate, and credential delete (confirmation prompt, --yes to skip) manage an integration's credentials.
• One-time secrets. credential create and credential rotate print the client_secret once. It cannot be retrieved again, so store it securely when shown.
• Device code includes workspace scope. When you run forge auth login --platform, the CLI now sends the workspace ID (from PLATFORM_WORKSPACE_ID in your environment file) as part of the device code request. The identity service binds the device code to that workspace - the person approving in the browser must hold a session scoped to the same workspace, and the token issued to the CLI is scoped to it.
• No change to login flow. The user experience is identical - Forge displays a code, you approve in the browser, and the CLI receives tokens automatically. The workspace scoping happens behind the scenes.
• A workspace ID is always required. Platform authentication is always bound to a workspace: PLATFORM_WORKSPACE_ID must be set in your environment file (a per-command --workspace <id> can override it). There is no unscoped device code flow - platform commands fail with a configuration error when no workspace ID is available.
• workspace create works with workspace-pinned authentication. For forge platform workspace create, the configured workspace ID (or --workspace <id>) identifies the existing workspace you authenticate against as the creator - not the workspace being created. Cached tokens are keyed per workspace, so tokens for different workspaces never collide.

What you need to do:

• No action required. The external integration commands support --env and --json, and the device-code flow automatically uses the required PLATFORM_WORKSPACE_ID.

v0.1.1 - Workspace Command Fixes (May 2026)

Workspace Command Fixes

The forge platform workspace create command now sends workspace creation requests to the correct endpoint. Previously, the command targeted a workspace-creation route that had been removed from the API, so it always failed with 405 Method Not Allowed. The command now creates workspaces under the authenticated user's account scope, which matches the current API.

What changed:

• Correct endpoint for workspace creation. forge platform workspace create now creates workspaces under the authenticated user's account scope. Users who previously saw 405 Method Not Allowed when creating workspaces through the CLI should retry with this version.
• --region removed from workspace create. The workspace's region is determined server-side, so the flag is no longer accepted.
• workspace archive requires --slug <slug>. Archiving confirms the destructive operation with the workspace slug; the flag is validated before any network call.
• New --workspace <id> flag on workspace subcommands. Overrides the environment's workspace binding for a single command, so you can operate on a freshly created workspace without editing your environment file.
• workspace update help corrected. The help text now names connector_type as the accepted field (previously it listed ehr_type, which the API does not accept).

v0.4.14 - Text Conversation Smoke Commands (April 2026)

Text Conversation Smoke Commands

Agent Forge now includes CLI commands for smoke-testing text conversation endpoints, covering both the REST interact path and the WebSocket streaming path.

New commands:

• forge platform conversation send-message - Send a single user message through the text conversation REST endpoint. Specify a service ID and message text; optionally pass a conversation ID to resume a durable conversation. The command displays the agent's response, conversation ID, and status. Use the returned conversation ID with subsequent calls to continue the same conversation.
• forge platform conversation text-ws-smoke - Open a WebSocket text-stream connection, wait for session initialization, send one message, and verify the agent responds. The command reports pass/fail, the conversation ID, and the agent's response text. Configurable timeouts control how long to wait for session start and agent response. An optional greeting drain window allows initial greeting events to arrive before the test message is sent.

Both commands support --json output for CI integration and --env for environment selection.

Usage examples:

Command	Key Options
forge platform conversation send-message	--service-id, --message, --conversation-id, --entity-id, --env, --json
forge platform conversation text-ws-smoke	--service-id, --message, --conversation-id, --entity-id, --ws-url, --timeout, --greeting-drain, --env, --json

No breaking changes. These are additive commands under the new forge platform conversation subgroup.

v0.4.13 - Platform Identity Authentication (April 2026)

Platform Identity Device Code Authentication

Agent Forge now supports Platform Identity authentication using the RFC 8628 device code flow. This is the recommended authentication method for interactive CLI use, replacing the need for static API keys during development.

What changed:

• Device code login - forge auth login now initiates a device code flow when the environment is configured with a Platform Identity URL. The CLI requests a device code, opens the browser to an approval page, and polls for authorization. Once approved, the access token and refresh token are cached in the system keyring.
• Silent token refresh - Subsequent CLI commands use the cached token. When the access token expires, the CLI silently refreshes it using the stored refresh token without requiring re-authentication.
• Auth status and logout - forge auth status shows the current authentication state (authenticated, expired, or not logged in). forge auth logout clears cached tokens from the keyring.
• Automatic method selection - The CLI automatically selects the authentication method based on the environment configuration: Platform Identity when an identity URL is configured, API key when a bearer token is present.

No breaking changes. Existing API key authentication continues to work. Environments without Platform Identity configuration are unaffected.

v0.4.12 - Canonical Value Lint for Context Graphs (May 2026)

Pre-Sync Validation for Inline Canonical Values

The sync-to-remote pipeline now detects canonical values - phone numbers, email addresses, and URLs - inlined directly into context graph state prose. Inline canonical values are a common authoring mistake that causes silent data drift: when a graph is cloned or updated, hardcoded values like phone numbers can be accidentally mutated, and the agent reads incorrect information to callers without any visible error.

The validator scans prose fields (descriptions, instructions, boundary constraints, exit conditions, and action descriptions) in every context graph state. When an inline canonical value is found, Forge emits a warning identifying the state, field, and matched value, along with guidance to move the value into structured context (such as world model entities or workspace settings) and reference it abstractly in the prose.

This check runs automatically during pre-sync validation alongside existing checks. No configuration is required. The validator catches:

• Phone numbers in digit form - patterns like 555-010-1234, [phone], or 555.010.1234
• Phone numbers in spelled-out form - sequences of seven or more number words (e.g., "five five five zero one zero one two three four"), which appear in TTS-optimized prose
• Email addresses - standard email patterns
• URLs - bare http and https links

Canonical values should live in structured context that the runtime injects at render time - for example, location or insurance entities in the world model, or workspace-level settings. State prose should reference these values abstractly (e.g., "provide the clinic's returning-patient line from your context") rather than hardcoding the digits.

v0.4.11 - Caller ID for Simulation Commands (May 2026)

Simulated Caller ID in Platform Simulation Commands

The forge platform sim session-create, forge platform sim smoke-test, and forge platform sim bridge commands now accept a --caller-id flag that sets a simulated caller phone number for the session. When provided, the agent resolves the number as a known caller, so the session starts with full patient context - useful for testing caller-specific flows like greeting a known patient by name or loading their clinical history.

The flag requires E.164 format: a + followed by 2-15 digits with the first digit 1-9 (e.g. [phone]). Invalid values are rejected before the request is sent.

Command	New Flag
forge platform sim session-create	--caller-id <E.164 number>
forge platform sim smoke-test	--caller-id <E.164 number>
forge platform sim bridge	--caller-id <E.164 number>

Omit the flag to simulate an unknown caller (the default behavior).

Examples:

v0.4.10 - Platform Insights and Call Trace Analysis (May 2026)

Platform Insights Commands

New forge platform insights command group for querying workspace data and discovering schema metadata through the platform insights service:

Command	Description
forge platform insights sql	Execute a read-only SQL query against the workspace data warehouse
forge platform insights schema	List available tables, columns, and functions in the workspace schema
forge platform insights digest	Get a cached workspace health digest with entity counts, data quality signals, and suggested questions
forge platform insights suggestions	Get contextual starter questions for exploring workspace data

The sql command accepts inline SQL or reads from a file with --sql-file. Results render as a formatted table by default, or as structured JSON with --json. Common SQL errors include targeted hints for discovering queryable objects.

Call Trace Analysis Commands

New forge platform trace command group for accessing deep call understanding from the intelligence pipeline:

Command	Description
forge platform trace list	List call trace analyses with optional outcome filtering and pagination
forge platform trace get	Get detailed trace analysis for a specific call

Trace analysis surfaces:

• Emotional arc - How caller sentiment evolved across the conversation
• Key decision moments - Critical points with causal attribution and quality assessment
• Coaching recommendations - Actionable improvements tied to specific moments in the call
• Counterfactuals - Alternative actions that could have changed the outcome
• Emotional shifts - State changes detected in the caller with trigger identification
• Signal-response alignment - Whether the agent responded appropriately to caller signals
• Interaction dynamics - Turn-taking quality, information density, rapport trajectory, and repair effectiveness
• Missed opportunities and emergent patterns - Behavioral patterns the agent could act on

The list command supports filtering by outcome (succeeded, partially, failed, abandoned), lookback window (--days), and pagination (--limit, --continuation-token).

All commands support --json for structured output and --env for environment selection.

Improved API Error Messages

Platform API error responses (401, 403, 422) now include the specific error detail returned by the server, making authentication and permission issues easier to diagnose.

v0.4.9 - Simulation Run Tracking, Schema Validation (April 16, 2026)

Simulation Runs Now Tracked and Preserved

All simulation conversations created by forge platform sim commands are now tagged with simulation at creation time, so they show up in the Agent Performance dashboard's simulation filter and remain queryable by tag after the run completes. Platform simulation sessions are no longer deleted once a smoke test or bridge run finishes. Sessions persist so tagged analytics and post-hoc inspection keep working.

The Classic API equivalent (forge sim simulate, simulate-step, simulate-batch, bridge runs) now emits the same simulation=true tag on the underlying conversation, giving both API surfaces consistent tracking.

Platform Command Schema Validation

Query parameters on every forge platform ... command are now validated against the live Platform API OpenAPI spec before the request is sent, and JSON responses are validated against the published response schema after the request returns. Schema drift surfaces as a clear error rather than a silent mismatch.

Platform CLI Parity Close-Out

Remaining gaps in Platform API coverage were closed. Every endpoint exposed under api.platform.amigo.ai now has a corresponding forge platform ... command, bringing the CLI to parity with the API surface.

v0.4.8 - Trigger Management (April 14, 2026)

Trigger CLI Commands

New forge platform trigger command group for managing scheduled action triggers:

Command	Description
forge platform trigger create	Create a trigger with cron schedule and action binding
forge platform trigger list	List triggers with active/inactive filtering
forge platform trigger get	Get trigger details including next fire time
forge platform trigger update	Update trigger configuration
forge platform trigger delete	Delete a trigger
forge platform trigger pause	Pause a trigger's schedule
forge platform trigger resume	Resume a paused trigger
forge platform trigger fire	Manually fire a trigger for testing
forge platform trigger runs	View trigger execution history

All commands support --json for structured output and --env for environment selection.

v0.4.6 - Simulation Bridge Persistence & CLI Alignment (April 13, 2026)

Simulation Bridge Persistence & Reports

The simulation bridge now persists test results across runs, enabling trend analysis and regression detection. New capabilities:

• Run reports - Generate summary reports after simulation runs with pass/fail counts, score distributions, and failure breakdowns
• Tag-based test library - Tag simulation scenarios for selective execution (e.g., forge sim run --tag scheduling to run only scheduling-related tests)
• Result persistence - Test outcomes are stored locally, so you can compare current results against previous runs

CLI Alignment with Live API

Seven schema and path fixes verified against the staging API:

• Voice settings URL path corrected to include workspace segment
• Billing, simulation, and world model schemas updated to match current API responses
• Phone number schema field alignment

v0.4.5 - Platform Functions & Simulation Coverage (April 8, 2026)

Platform Function Commands

New forge platform function command group for managing platform functions: declarative SQL, Python, and AI functions that agents call mid-conversation.

Command	Description
forge platform function register	Register a new platform function
forge platform function list	List all registered functions
forge platform function test	Execute a function with test parameters
forge platform function delete	Remove a function registration
forge platform function query	Run an open-scope SQL query against workspace data
forge platform function catalog	Display the full function catalog offline
forge platform function sync	Sync function definitions between local files and the platform

Simulation Coverage Commands

New forge platform simulation command group for branch-and-bound simulation coverage runs.

Command	Description
forge platform simulation create	Create a new coverage run for a service
forge platform simulation session	Create a session within a coverage run
forge platform simulation step	Step a session forward with a simulated user message
forge platform simulation fork	Fork a session into N children at a decision point
forge platform simulation score	Score a session against configured metrics
forge platform simulation graph	Retrieve the coverage knowledge graph
forge platform simulation complete	Complete a run and clean up ephemeral branches

Vendor-Neutral Function Naming

Platform function identifiers renamed from uc_ prefix to fn_ prefix for vendor-neutral naming. Existing references are automatically migrated.

Platform CLI Parity

New command groups closing remaining CLI-to-API coverage gaps:

• forge platform persona - CRUD for cross-channel agent identities
• forge platform billing - Workspace billing and usage information
• forge platform settings - Workspace configuration (environments, workflows, branding)
• forge platform network - Egress IP listing for firewall allowlisting

All commands support --json for structured output and --env for environment selection.

v0.4.4 - Surface E2E Testing (April 6, 2026)

Surface End-to-End Testing

New forge platform surface e2e command for testing the full surface lifecycle from the CLI: create a surface, deliver it, render the patient-facing form, and submit data, all in one command.

The command exercises the complete flow: surface creation via Platform API, spec retrieval, form rendering, and submission. It validates that branding settings are applied correctly and that submitted data flows through to the world model. Useful for verifying surface configuration changes before deploying to production.

Uses Pydantic models for request/response validation, matching the Platform API schemas.

v0.4.3 - Context Graph Rename & Voice Configuration (April 5, 2026)

HSM → Context Graph Rename

All CLI commands and API paths now use the "context graph" terminology consistently:

• API paths renamed: hsms/ → context-graphs/, sims/ → simulations/
• CLI flags renamed: --hsm-id → --context-graph-id
• Entity type selector: -e hsm → -e context-graph
• All user-facing output now says "Context Graph" instead of "HSM"

Voice Configuration Command

New forge platform service voice-config command for per-service voice tuning:

Three presets available: ultra_low_latency (demos, coaching), balanced (default), quality (complex healthcare). Configures filler style, barge-in sensitivity, response limits, and TTS model selection.

Bug Fixes

• Service list now correctly shows Context Graph ID (was blank due to field rename)
• Version set commands now read context_graph_version_number (was silently reading None)
• apply-policy limit corrected from 50 → 20 (matches API constraint)

v0.4.2 - Conversation Quality Check (April 3, 2026)

Quality Check Command

New forge quality check command for scanning workspace conversations against 5 behavioral detectors:

Detector	What It Finds
Character degeneration	Repeated characters, low entropy output, stuttering patterns
Stuck agent loops	Agent repeats the same response while the caller changes topics
Repetitive patterns	High similarity across sliding message windows
Word salad	Incoherent output patterns like or-chains and excessive word repetition
Phantom success	Agent claims a tool call succeeded when the tool actually returned an error

Queries production conversation data directly. Supports configurable lookback windows, verbose mode with message excerpts, and JSON output for scripting.

v0.4.1 - VoiceSim CLI & Tool Testing Commands (April 2, 2026)

Voice Simulation Commands

New forge platform sim commands for managing VoiceSim runs from the CLI:

Command	Description
forge platform sim create	Create a new simulation run
forge platform sim list	List simulation runs for the workspace
forge platform sim sample	Sample and evaluate N configuration points
forge platform sim evaluate	Evaluate a specific configuration point against a scenario
forge platform sim get	Get run status and best results
forge platform sim summary	Get aggregated summary with best-per-scenario and penalty frequency
forge platform sim points	List scored points (by score or chronologically)
forge platform sim complete	Mark a run as finished

Tool Testing Commands

New forge platform tool-test commands for testing HSM tools without phone calls:

Command	Description
forge platform tool-test resolve	List available tools for a service with schemas
forge platform tool-test execute	Execute a tool with custom parameters and dry run mode

v0.4.0 - Platform API CLI, Simulation Engine & Changelog (April 1, 2026)

Major release. Agent Forge now provides full CLI coverage for the Platform API, a dedicated simulation engine, cross-entity change traceability, and bulk sync from local files.

Platform API CLI (73 Endpoints)

forge platform commands now cover all Platform API resources: agents, services, skills, context graphs, integrations, phone numbers, data sources, FHIR, pipeline, operators, surfaces, analytics, safety, and workspaces. Every read, create, update, and delete operation available through the Platform API can be performed from the CLI.

Simulation Engine

New forge simulation command group for coverage-optimized testing against context graphs:

Command	Description
forge simulation run	Execute a simulation run against a target context graph with configurable personas and scenarios
forge simulation plan	Generate a test plan that maximizes state and transition coverage across the context graph
forge simulation evaluate	Score simulation results against quality metrics and expected outcomes
forge simulation cleanup	Remove simulation artifacts (test users, conversations, recordings) from a workspace

The simulation engine analyzes context graph structure to generate test plans that exercise every reachable state and transition, identifying untested paths and edge cases. Key capabilities include parallel execution with ephemeral test users, atomic budget enforcement across concurrent sessions, a batched classifier for state transition prediction, and composable pipelines (plan --json | run -t -).

Simulation Bridge

forge simulation bridge provides a higher-level simulation workflow that generates scenario variations from a natural-language objective and runs them against a service. Unlike simulation run (which requires explicit state targets), the bridge uses an LLM to create realistic test scenarios and runs them with platform interaction insights for state and tool coverage tracking. Supports pass^k consistency testing (--runs flag) to measure scenario reliability across repeated runs.

Interaction Insights on simulate-step

forge conversation simulate-step now returns an interaction_insights object in its JSON output: current state, action, objective, behaviors triggered, tools called, and state transitions. Gives coding agents (Claude Code, Cursor) visibility into what the agent did internally at each turn.

Cross-Environment Permissions Fix

Simulation test users are now created with DemoProspectRole instead of DefaultUserRole, fixing permission errors when running simulations in non-dogfood environments. Provision with forge role provision --role DemoProspectRole --env [ORG_ID].

Changelog Command

forge changelog provides cross-entity change traceability: view a chronological log of all configuration changes (agent updates, context graph versions, service deploys, integration edits) across a workspace. Filterable by entity type, date range, and actor.

Text Agent & Outbound Triggers

New CLI commands for managing text (SMS) agent sessions and scheduling automated outbound messages:

Command	Description
forge platform session list-text	List active and recent text sessions, filterable by service, channel, and status
forge platform session create-outbound	Create an outbound text session that sends a greeting and conducts a multi-turn SMS conversation
forge platform outbound-trigger list	List outbound triggers (appointment-based SMS scheduling rules)
forge platform outbound-trigger get	Get details for a specific trigger
forge platform outbound-trigger create	Create a new trigger with cron schedule, appointment window, consent checks, and daily send limits

Platform Push

forge platform push enables bulk sync from local configuration files to a workspace. Define agents, context graphs, services, and skills as local files and push them in a single operation. Useful for promoting configurations across environments (staging to production) or restoring from version-controlled snapshots.

v0.3.25 - GWS CLI & Linear Integration Skills (March 9, 2026)

New skill documentation added:

• GWS CLI: Google Workspace CLI skill covering auth, multi-account, MCP setup, and operations for Drive/Sheets/Gmail/Calendar/Tasks (brew install googleworkspace/tap/gws)
• Linear Ticket Workflow: Documented Linear ticket lifecycle for customer workspace work
• Linear Ticket Script: New scripts/create_linear_tickets.py for creating parent Linear tickets

v0.3.24 - Tool Developer Breaking Changes (March 6, 2026)

Breaking change: run_tool() signature now requires a 6th parameter user_variables: UserVariables. Invocation mode conversation renamed to regular, and conversation-test removed.

Impact: High | Action Required: Yes, for all tool developers

The tool scaffold signature and project configuration have been updated.

run_tool() Signature Change

Invocation Mode Rename

Before	After
conversation	regular
conversation-test	(removed)

Only two modes remain: regular and conversation-simulation.

Updated pyproject.toml Requirements

Setting	Before	After
pyright	>=1.1.403,<2	>=1.1.407,<2
ruff	>=0.12.10,<0.15	>=0.14.6,<0.15
amigo-tool-scaffold source	path = "../amigo_tool_scaffold", editable = true	path = "../amigo_tool_scaffold.tar.gz"
extend-select	["I"]	["I", "SLF001"]

v0.3.22 - Temporary Conversation Access & AgentEngineerRole Removal (March 3, 2026)

Agent Forge v0.3.22 replaces the overly-permissive AgentEngineerRole with per-conversation, time-limited access grants. Engineers now request temporary access to specific conversations instead of having blanket org-wide visibility.

Why This Matters: The AgentEngineerRole granted full conversation visibility across the entire organization - far more access than needed for debugging a single conversation. The new temporary access system enforces least-privilege: engineers request access to a specific conversation with a justification, and the grant expires automatically (default: 2 hours).

New Commands

Command	Description
forge conversation request-access	Request time-limited access to a specific conversation
forge conversation list-access	List active and expired temporary access grants

Example: Request Conversation Access

Example: List Active Grants

Command Options: forge conversation request-access

Option	Required	Default	Description
CONVERSATION	Yes	--	Conversation URL or 24-char ID
--env / -e	Conditional	From URL	Environment name
--justification / -j	Yes	--	Reason for access (min 10 chars)
--duration / -d	No	PT2H	ISO 8601 duration (e.g., PT2H, PT30M, P1D)
--user-email	No	Self	Grant access to another user by email
--json	No	false	JSON output

Command Options: forge conversation list-access

Option	Required	Default	Description
--env / -e	Yes	--	Environment name
--all	No	false	Show grants for all users
--show-expired	No	false	Include expired grants
--json	No	false	JSON output

Breaking change: AgentEngineerRole has been removed. Use forge conversation request-access for per-conversation temporary access instead.

Breaking Change: AgentEngineerRole Removed

The AgentEngineerRole predefined role has been removed from forge role list and forge role provision. If you were using this role:

1. Use forge conversation request-access to get per-conversation access as needed
2. The underlying platform admin role (DefaultAmigoAdministratorRole) remains unchanged
3. Existing AgentEngineerRole assignments in organizations are not affected (the role still exists remotely if previously provisioned)

Key Behaviors

• Each request-access call creates 3 permission grants: GetConversation, GetMessage, GetInteractionInsights
• Grants are scoped to the specific conversation's owner and organization
• Grants auto-expire after the specified duration
• All grants are tagged with source: forge-cli and the conversation ID for auditability
• Partial failures are reported (e.g., if 2 of 3 grants succeed)

v0.3.21 - User Management & Impersonation (February 20, 2026)

Agent Forge v0.3.21 adds a full forge user command group for user CRUD operations and a --user impersonation flag on conversation commands, so developers can run conversations as any existing user without creating ephemeral test accounts.

Why This Matters: Testing user-specific agent behaviors (personalized context, memory, conversation history) previously required either creating disposable test users or manually calling the API. The new forge user commands provide first-class user management, and the --user flag lets you run smoke tests or simulations as any real user via API key impersonation.

New Command Group: forge user

Command	Description
forge user list	List users with search, email filter, and pagination
forge user get	Get user details by ID or email (shows conversation and memory counts)
forge user create	Create a new user with optional initial context
forge user update	Update user context entries
forge user delete	Remove a user from the organization

New Flag: --user / -u on Conversation Commands

Command	Description
forge conversation smoke-test --user	Run smoke test as an existing user
forge conversation simulate --user	Run simulation as an existing user
forge conversation simulate-step --user	Run step-by-step simulation as an existing user

Example: User Management

Example: Impersonation

Command Options: forge user list

Option	Description
--env / -e	Environment name (required)
--search / -q	Search by name or email
--email	Filter by exact email
--limit	Maximum results to show
--json	JSON output for scripting

Command Options: forge user create

Option	Description
--env / -e	Environment name (required)
--first-name	User's first name (required)
--last-name	User's last name (required)
--email	User's email (required)
--role	Role to assign (default: DefaultUserRole)
--context / -c	Context string to add (repeatable)
--file / -f	File containing context entries

Key Behaviors

• --user accepts either a user ID or email address (auto-resolves email to ID)
• Impersonation requires API key authentication (Firebase auth does not support impersonation)
• When --user is combined with --additional-context, the user's original context is saved, temporarily replaced, and restored after the test
• forge test-user set-context is deprecated in favor of forge user update -c
• forge user manages real accounts; forge test-user manages ephemeral simtest_* accounts for parallel testing

v0.3.20 - Version List Pagination & Sorting (February 20, 2026)

Agent Forge v0.3.20 adds a --newest-first flag and automatic pagination to all version-list commands, overcoming the API's 10-item-per-page limit and so developers can quickly find recent versions.

Why This Matters: When agents or context graphs have many versions, the default oldest-first ordering buries the latest versions at the end. The API also returns at most 10 items per page, requiring manual pagination. This release adds descending sort and transparent multi-page fetching so --limit 50 actually returns 50 results.

Enhanced Commands

Command	Change
forge asset agent version-list	Added --newest-first / -d flag and pagination
forge asset context-graph version-list	Added --newest-first / -d flag and pagination
forge asset behavior version-list	Added --newest-first / -d flag and pagination

Example: Find Recent Versions

New Options

Option	Description
--newest-first / -d	Sort by version descending (newest first). Default: ascending
--limit	Maximum results to return (pagination fetches up to this count automatically)

Key Behaviors

• Pagination is transparent: the CLI automatically follows continuation_token to fetch subsequent pages up to the requested --limit
• Safety limit of 100 API pages prevents infinite loops
• Page size is optimized on the last page to fetch only remaining items
• Default sort order (ascending) is unchanged for backward compatibility

v0.3.19 - Ergonomic Update Diffs (February 19, 2026)

Agent Forge v0.3.19 introduces type-aware diff formatting for entity updates, making it much easier to review what actually changed when syncing entities.

Why This Matters: Entity updates often involve nested JSON structures (agent backgrounds, context graph states, behavior triggers). Previously, diffs showed raw before/after values that were difficult to parse. The new system adapts formatting based on value type - simple strings stay inline, long text uses unified diffs, and complex objects show semantic change summaries.

Improved Diff Display

The diff system now uses three tiers:

Value Type	Display Style	Example
Simple values (<=100 chars)	Inline in summary table	"old value" -> "new value"
Long strings (>100 chars)	Unified text diff (---/+++)	Like git diff output
Dicts/lists	Semantic DeepDiff summary	~ ['expertise'][2]: "old" -> "new"

Example: Semantic Diff Output

Key Behaviors

• Inline values truncated to 120 characters for readability
• Up to 20 changes displayed per field before showing ... and N more change(s)
• Works across all entity types (agents, behaviors, context graphs, services)
• Applies to forge str and any command that shows update diffs

v0.3.18 - Tool Scaffold Install (February 12, 2026)

Agent Forge v0.3.18 adds a forge tool-scaffold install command that automates installation of the amigo_tool_scaffold package into tool directories using uv, reducing tool development setup to a single command.

Why This Matters: Tool developers previously had to manually configure package manager authentication and run uv add commands in each tool directory. This command handles authentication, uv version validation, and package installation in a single step.

New Command

Command	Description
forge tool-scaffold install	Install amigo_tool_scaffold in tool directories

Example: Install Tool Scaffold

Command Options

Option	Required	Description
--env / -e	Yes	Environment name
--tool / -t	No	Install in a specific tool directory
--all	No	Install in all tool directories
--verbose / -v	No	Enable verbose output

Key Behaviors

• Requires uv >= 0.10.2 (validated at startup with a clear error message if missing)
• Discovers tools by scanning local/{env}/tools-{org_id}/ for pyproject.toml files
• Authenticates via the configured auth method (API key or Firebase)
• Runs uv auth login followed by uv add amigo_tool_scaffold for each target tool
• If neither --tool nor --all is specified, presents an interactive selection menu

v0.3.17 - Firebase Authentication (February 12, 2026)

Agent Forge v0.3.17 migrates authentication from API keys to Firebase-based Google Sign-In using the OAuth 2.0 device authorization flow (RFC 8628). Existing API key authentication remains fully supported for backward compatibility.

Why This Matters: API key management creates operational overhead - keys must be generated, distributed securely, and rotated periodically. Firebase authentication provides a more ergonomic flow: developers sign in with their Google account once, and tokens refresh automatically. This also aligns Forge CLI authentication with the web platform's auth model.

New Authentication Method

Method	When Used	Setup
API Key (existing)	API_KEY, API_KEY_ID, API_KEY_USER_ID all present in .env	No changes needed
Firebase (new default)	API key fields absent, GOOGLE_TENANT_ID present	One-time forge auth login

New Command

Command	Description
forge auth login	Authenticate via Google Sign-In device code flow

Example: Firebase Authentication

Environment Configuration

Key Behaviors

• Auth method is selected automatically based on which environment variables are present
• Firebase tokens are cached in the system keyring for persistent, secure credentials
• Tokens refresh silently on subsequent commands (no repeated login prompts)
• Keyring save failures are non-fatal - commands continue to work even if the system keyring is unavailable
• The --user impersonation flag (v0.3.21) requires API key auth; Firebase does not support impersonation

Setup

1. Add GOOGLE_TENANT_ID to your .env.{env} file (get the tenant ID from your org admin).
2. Run forge auth login -e <env> to authenticate.

v0.3.16 - Auto-Finish for Simulations (February 11, 2026)

Agent Forge v0.3.16 adds smart conversation lifecycle management: conversations auto-finish when the agent marks them complete, and the simulate command always finishes conversations in its cleanup path to prevent orphaned sessions.

Why This Matters: Open conversations that are never finished don't trigger post-processing (memory extraction, metric evaluation). Previously, simulate-step users had to manually finish conversations, and error paths in simulate could leave conversations dangling. This release ensures conversations are always properly closed.

Enhanced Commands

Command	Change
forge conversation simulate-step	Auto-finishes when agent marks is_finished=true; new --finish flag
forge conversation simulate	Always finishes conversations in finally block; new --stop-on-finished flag

Example: Auto-Finish in Step Mode

Example: Stop-on-Finished in Simulate

New Options

Command	Option	Description
simulate-step	--finish	Explicitly finish the conversation
simulate	--stop-on-finished	Stop when agent marks conversation as finished

Key Behaviors

• simulate-step: Checks is_finished in the API response; auto-finishes and includes "finished": true in JSON output
• simulate: Finishes conversations in the finally block regardless of success/error (not just for --test-user + --analyze-wait)
• Keyring save failures are now non-fatal (graceful degradation on broken macOS keychains)

v0.3.15 - Additional Context for Test Users (February 10, 2026)

Agent Forge v0.3.15 adds first-class support for setting additional_context on test users during CLI-based agent testing. This lets you test agents that depend on user context (care recipient profiles, ages, person IDs) without manually configuring test users.

Why This Matters: Many agents rely on additional_context to personalize conversations - for example, knowing a care recipient's name, age, or medical profile. Previously, testing these agents required manually creating users and setting context through the API. Now, smoke-test handles the full lifecycle automatically: create an ephemeral test user, set context, run the test, and clean up.