Harn ACP/MCP extensions v1

Canonical URL: https://harnlang.com/spec/harn-extensions/v1

This page defines Harn-owned protocol extension fields for clients that consume Harn over Agent Client Protocol (ACP) or Model Context Protocol (MCP). Harn uses _meta.harn for fields that extend an upstream protocol object. Standard ACP and MCP fields stay at their standard locations.

Compatibility

The ACP adapter advertises this contract during initialize:

{
  "agentCapabilities": {
    "_meta": {
      "harn": {
        "schemaCompatibility": "agentclientprotocol/agent-client-protocol schema v0.12.2",
        "extensionContract": "https://harnlang.com/spec/harn-extensions/v1",
        "sessionUpdateExtensions": [
          "fs_watch",
          "handoff",
          "hitl_request",
          "hitl_resolved",
          "log",
          "progress",
          "skill_activated",
          "skill_deactivated",
          "skill_narrow",
          "skill_scope_tools",
          "tool_search_query",
          "tool_search_result",
          "transcript_compacted",
          "worker_update"
        ],
        "toolLifecycleExtensionFields": [
          "audit",
          "durationMs",
          "error",
          "errorCategory",
          "executionDurationMs",
          "executor",
          "parsing",
          "rawInputPartial"
        ],
        "contentExtensionFields": ["visible_delta", "visible_text"],
        "extensionMethods": {
          "_harn/agentEvent": {
            "description": "Pipeline-loop milestones that have no canonical ACP session/update mapping.",
            "schema": "https://harnlang.com/spec/harn-extensions/agent-event/v1"
          },
          "_harn/providerCatalog": {
            "description": "Return the normalized provider/model catalog used by this runtime.",
            "schema": "https://harnlang.com/schemas/provider-catalog.v2.json",
            "schemaVersion": 2
          }
        },
        "hostCapabilityOperations": {
          "process": [
            "exec",
            "list_shells",
            "get_default_shell",
            "set_default_shell",
            "shell_invocation"
          ]
        }
      }
    }
  }
}

Field stability means the field name and location are part of this v1 contract. Consumers must still ignore unknown sibling fields and tolerate missing optional fields.

Field	Location	Stability	Meaning
`schemaCompatibility`	`agentCapabilities._meta.harn`	Stable v1	Upstream ACP schema version Harn pins its ACP wire shape against.
`extensionContract`	`agentCapabilities._meta.harn`	Stable v1	Public spec URL for Harn-owned extension fields.
`sessionUpdateExtensions`	`agentCapabilities._meta.harn`	Stable v1	Harn `session/update` discriminators a client may receive in addition to upstream ACP values.
`toolLifecycleExtensionFields`	`agentCapabilities._meta.harn`	Stable v1	Harn fields that can appear below `tool_call._meta.harn` or `tool_call_update._meta.harn`.
`contentExtensionFields`	`agentCapabilities._meta.harn`	Stable v1	Harn fields that can appear below ACP content-block `_meta.harn`.
`extensionMethods`	`agentCapabilities._meta.harn`	Stable v1	Harn-owned JSON-RPC methods beyond canonical ACP methods. Unknown keys must be ignored.
`hostCapabilityOperations`	`agentCapabilities._meta.harn`	Experimental	Host bridge operation names Harn may request through ACP host calls.

ACP extension methods

`_harn/providerCatalog`

Request:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "_harn/providerCatalog",
  "params": {}
}

Response result is the provider catalog v2 artifact identified by https://harnlang.com/schemas/provider-catalog.v2.json. It is the same shape as harn providers export, with the serving runtime's effective provider and capability overlays already applied.

Clients should use this method for provider/model pickers and avoid maintaining parallel hard-coded provider lists. The catalog includes provider auth requirements and env var names, aliases, context windows, tool-support hints, local/cloud classification, availability, and pricing where known.

ACP session updates

Harn extension session updates keep the sessionUpdate discriminator at params.update.sessionUpdate; all Harn-owned payload fields are under params.update._meta.harn.

{
  "method": "session/update",
  "params": {
    "sessionId": "session_123",
    "update": {
      "sessionUpdate": "progress",
      "_meta": {
        "harn": {
          "phase": "ingest",
          "message": "loading",
          "progress": 3,
          "total": 10
        }
      }
    }
  }
}

`sessionUpdate` value	`_meta.harn` fields	Stability
`progress`	`phase`, `message`, `progress`, `total`, `data`	Stable v1
`log`	`level`, `message`, `fields`	Stable v1
`fs_watch`	`subscriptionId`, `events`	Stable v1
`worker_update`	`workerId`, `workerName`, `workerTask`, `workerMode`, `event`, `status`, `terminal`, `metadata`, `audit`	Stable v1
`transcript_compacted`	`mode`, `reason`, `strategy`, `archivedMessages`, `estimatedTokensBefore`, `estimatedTokensAfter`, `snapshotAssetId`, `instructionMode`, `instructionSource`, `compactionPolicy`	Stable v1
`transcript_projected`	`policy`, `reason`, `prefixHash`, `keptCount`, `droppedCount`, `providerSafetyBlocked`, `redactedCount`, `reclaimedTokens`, `rootsConsulted`, `redactionPointers`	Stable v1
`handoff`	`handoffId`, `artifactId`, `handoff`	Stable v1
`skill_activated`	`skillName`, `iteration`, `reason`	Stable v1
`skill_deactivated`	`skillName`, `iteration`	Stable v1
`skill_narrow`	`reason`, `removedTools`, `remainingTools`, `policy`, `removedToolDetails`, `keptToolDetails`	Stable v1
`skill_scope_tools`	`skillName`, `allowedTools`	Stable v1
`tool_search_query`	`toolUseId`, `name`, `query`, `strategy`, `mode`	Stable v1
`tool_search_result`	`toolUseId`, `promoted`, `strategy`, `mode`	Stable v1
`hitl_request`	`requestId`, `kind`, `payload`	Experimental
`hitl_resolved`	`requestId`, `kind`, `outcome`	Experimental

The audit field on worker_update is the same mutation-session record shape used by tool lifecycle audit.

agent_progress task-list entries are not encoded as the Harn progress extension. ACP adapters emit them as canonical sessionUpdate: "plan" updates with full-replacement entries; message-only agent_progress reports use the Harn progress extension with phase: "narration".

Standard ACP updates such as agent_message_chunk, tool_call, tool_call_update, and plan keep their standard payload fields at the root of params.update.

ACP tool lifecycle

tool_call and tool_call_update use canonical ACP root fields for toolCallId, title, kind, status, rawInput, rawOutput, and content. Harn-owned lifecycle fields appear under params.update._meta.harn.

{
  "sessionUpdate": "tool_call_update",
  "toolCallId": "call_123",
  "title": "edit_file",
  "status": "completed",
  "rawOutput": "ok",
  "_meta": {
    "harn": {
      "executor": "host_bridge",
      "durationMs": 25,
      "executionDurationMs": 18,
      "audit": {
        "session_id": "session_123",
        "run_id": "run_123",
        "mutation_scope": "apply_workspace"
      }
    }
  }
}

Field	Applies to	Stability	Meaning
`audit`	`tool_call`, `tool_call_update`	Stable v1	Mutation-session record for grouping writes, approvals, undo/redo, and audit logs.
`executor`	`tool_call_update`	Stable v1	Execution backend: `"harn_builtin"`, `"host_bridge"`, `"provider_native"`, or `{"kind":"mcp_server","serverName":"..."}`.
`durationMs`	`tool_call_update`	Stable v1	End-to-end duration from Harn's lifecycle observation.
`executionDurationMs`	`tool_call_update`	Stable v1	Backend execution duration when Harn can separate it from parsing or routing overhead.
`error`	`tool_call_update`	Stable v1	Human-readable execution or validation error.
`errorCategory`	`tool_call_update`	Stable v1	Machine-readable error category such as `schema_validation` or `parse_aborted`.
`parsing`	`tool_call`, `tool_call_update`	Experimental	Whether the event represents an in-progress structured input parsing state.
`rawInputPartial`	`tool_call_update`	Experimental	Unparseable partial tool input bytes captured during streaming tool-call parsing.

audit is omitted when no mutation session is installed.

ACP content extensions

Harn can add visibility metadata to ACP text content blocks. These fields live under the content block's _meta.harn, not under the surrounding update.

{
  "sessionUpdate": "agent_message_chunk",
  "content": {
    "type": "text",
    "text": "hello",
    "_meta": {
      "harn": {
        "visible_text": "hello",
        "visible_delta": "hello"
      }
    }
  }
}

Field	Location	Stability	Meaning
`visible_text`	`content._meta.harn`	Experimental	Assistant-visible text after Harn visibility filtering.
`visible_delta`	`content._meta.harn`	Experimental	Newly visible text in this content chunk.

MCP extension boundary

Harn does not currently emit Harn-owned _meta.harn fields on MCP tool annotations, capabilities, or notifications. MCP consumers should treat the following as standard MCP fields, not Harn namespace extensions:

MCP surface	Fields Harn emits or consumes	Namespace
Tool list entries	`annotations.title`, `annotations.readOnlyHint`, `annotations.destructiveHint`, `annotations.idempotentHint`, `annotations.openWorldHint`	MCP standard
Tool list entries	`execution.taskSupport`	MCP task execution extension
Server capabilities	`tools.listChanged`, `resources.listChanged`, `prompts.listChanged`, `logging`, `tasks`, `elicitation`	MCP standard or latest-spec MCP extension
Tool-call requests	`_meta.progressToken`	MCP standard
Notifications	`notifications/progress` with `progressToken`, `progress`, `message`	MCP standard
Task correlation metadata	`_meta["io.modelcontextprotocol/related-task"].taskId`	MCP namespace

If Harn introduces MCP-specific Harn metadata in a future revision, those fields will be added below _meta.harn and advertised by a new version of this page.