@agentxm/client-core 0.16.2 → 0.18.0

package/dist/src/unstable/agent-capabilities/schema.js

@@ -1,6 +1,33 @@
 /**
  * Agent capability catalog schemas.
  *
+ * Sourcing namespaces:
+ *
+ * - `native` is the vendor-authoritative fact layer: whether the agent exposes
+ *   the surface, which standard or convention it follows, where config lives,
+ *   and the source URLs used to verify that claim.
+ * - `axm` is AXM integration state: whether AXM has modeled support, whether a
+ *   writer exists, the writer metadata needed by AXM, and AXM-owned backlog or
+ *   unsupported reasons. These fields are not vendor facts.
+ * - `canonical` is a derived, vendor-neutral vocabulary. Hook event/tool
+ *   mappings store canonical IDs beside native names, but the catalog does not
+ *   store a per-agent canonical capability block.
+ *
+ * Status axes:
+ *
+ * - `AgentLifecycle` describes the coding agent product itself.
+ * - `VendorStatus` describes the vendor or plugin surface named by
+ *   `Availability`.
+ * - `Availability` describes whether the surface is native, plugin-backed, or
+ *   absent.
+ * - AXM support/writer state lives under `axm.status` and `axm.writer`;
+ *   `axm.writer !== null` means AXM has verified write mechanics for that
+ *   capability.
+ *
+ * `permissions` lives beside `capabilities` because it models AXM grant/write
+ * mechanics for an agent's permission system. It is not a publishable leaf
+ * extension type and therefore is not keyed under the extension capability map.
+ *
  * @experimental This API is unstable and may change without notice.
  */
 import * as Schema from "effect/Schema";
@@ -56,7 +83,7 @@ export const AxmSupportSchema = Schema.Literals([
 ]).annotate({
     identifier: "AxmSupport",
     title: "AXM Support",
-    description: "AXM install behavior and verification state for an agent capability.",
+    description: "AXM-owned integration status for an agent capability. This is not a vendor fact.",
     examples: [SUPPORTED_AXM_SUPPORT, "unsupported", "unknown"],
 });
 /** @experimental This API is unstable and may change without notice. */
@@ -268,14 +295,26 @@ export const LastVerifiedDateSchema = Schema.NonEmptyString.pipe(Schema.check(Sc
 const CapabilityNotesSchema = Schema.NullOr(Schema.NonEmptyString);
 const CapabilityDocsSchema = Schema.Array(DocLinkSchema);
 const CapabilitySourcesSchema = Schema.Array(UrlSchema);
-const UnavailableCanonicalCapabilityFields = {
+const provenanceFields = (sources, lastVerified) => ({
+    sources,
+    lastVerified,
+});
+const NullableProvenanceFields = provenanceFields(CapabilitySourcesSchema, Schema.NullOr(LastVerifiedDateSchema));
+const VerifiedProvenanceFields = provenanceFields(Schema.NonEmptyArray(UrlSchema), LastVerifiedDateSchema);
+/** @experimental This API is unstable and may change without notice. */
+export const ProvenanceSchema = Schema.Struct(NullableProvenanceFields).annotate({
+    identifier: "Provenance",
+    title: "Provenance",
+    description: "Source URLs and verification date for a catalog capability claim.",
+});
+const UnavailableNativeCapabilityFields = {
     availability: NoneAvailabilitySchema,
     vendorStatus: VendorStatusSchema,
     notes: CapabilityNotesSchema,
     docs: CapabilityDocsSchema,
     sources: CapabilitySourcesSchema,
 };
-const AvailableCanonicalCapabilityBaseFields = {
+const AvailableNativeCapabilityBaseFields = {
     availability: AvailableCapabilityAvailabilitySchema,
     vendorStatus: VendorStatusSchema,
     notes: CapabilityNotesSchema,
@@ -287,48 +326,49 @@ const SpecTrackedCapabilityFields = {
     standardsCompliance: StandardsComplianceSchema,
     convention: ConventionSchema,
 };
-const AvailableSpecTrackedCanonicalCapabilityFields = {
-    ...AvailableCanonicalCapabilityBaseFields,
+const AvailableSpecTrackedNativeCapabilityFields = {
+    ...AvailableNativeCapabilityBaseFields,
     ...SpecTrackedCapabilityFields,
 };
-const NoWriterAxmCapabilityStateSchema = Schema.Union([
-    Schema.Struct({
-        support: ActiveAxmSupportSchema,
-        lastVerified: LastVerifiedDateSchema,
-        writer: Schema.Null,
-    }),
-    Schema.Struct({
-        support: InactiveAxmSupportSchema,
-        writer: Schema.Null,
-    }),
-]);
+const axmCapabilityStateDescription = "AXM integration state for this capability: AXM support status, AXM verification date, optional writer metadata, and AXM-owned rationale. This is not a vendor fact.";
+const axmCapabilityStateSchema = (writerSchema, identifier) => Schema.Struct({
+    status: AxmSupportSchema,
+    lastVerified: Schema.NullOr(LastVerifiedDateSchema),
+    reason: Schema.optionalKey(Schema.NonEmptyString),
+    writer: Schema.NullOr(writerSchema),
+}).annotate({
+    identifier,
+    title: "AXM Capability State",
+    description: axmCapabilityStateDescription,
+});
+const NoWriterAxmCapabilityStateSchema = axmCapabilityStateSchema(Schema.Never, "NoWriterAxmCapabilityState");
 const requireSourcesForActiveAxmSupport = (capability) => {
-    if ((capability.axm.support === SUPPORTED_AXM_SUPPORT || capability.axm.support === "planned") &&
-        capability.canonical.sources.length === 0) {
+    if ((capability.axm.status === SUPPORTED_AXM_SUPPORT || capability.axm.status === "planned") &&
+        capability.native.sources.length === 0) {
         return {
-            path: ["canonical", "sources"],
-            issue: "Active AXM support claims require at least one canonical source.",
+            path: ["native", "sources"],
+            issue: "Active AXM support claims require at least one native source.",
         };
     }
     return undefined;
 };
 /** @experimental This API is unstable and may change without notice. */
-export const CanonicalCapabilityBaseSchema = Schema.Union([
-    Schema.Struct(AvailableCanonicalCapabilityBaseFields),
-    Schema.Struct(UnavailableCanonicalCapabilityFields),
+export const NativeCapabilityBaseSchema = Schema.Union([
+    Schema.Struct(AvailableNativeCapabilityBaseFields),
+    Schema.Struct(UnavailableNativeCapabilityFields),
 ]).annotate({
-    identifier: "CanonicalCapabilityBase",
-    title: "Canonical Capability Base",
+    identifier: "NativeCapabilityBase",
+    title: "Native Capability Base",
     description: "Vendor-sourced fields shared by all agent capabilities.",
 });
 /** @experimental This API is unstable and may change without notice. */
 export const SkillsExtensionCapabilitySchema = Schema.Struct({
-    canonical: Schema.Union([
+    native: Schema.Union([
         Schema.Struct({
-            ...AvailableSpecTrackedCanonicalCapabilityFields,
+            ...AvailableSpecTrackedNativeCapabilityFields,
             directory: Schema.NonEmptyString,
         }),
-        Schema.Struct(UnavailableCanonicalCapabilityFields),
+        Schema.Struct(UnavailableNativeCapabilityFields),
     ]),
     axm: NoWriterAxmCapabilityStateSchema,
 })
@@ -340,12 +380,12 @@ export const SkillsExtensionCapabilitySchema = Schema.Struct({
 });
 /** @experimental This API is unstable and may change without notice. */
 export const CommandsExtensionCapabilitySchema = Schema.Struct({
-    canonical: Schema.Union([
+    native: Schema.Union([
         Schema.Struct({
-            ...AvailableCanonicalCapabilityBaseFields,
+            ...AvailableNativeCapabilityBaseFields,
             directory: Schema.NonEmptyString,
         }),
-        Schema.Struct(UnavailableCanonicalCapabilityFields),
+        Schema.Struct(UnavailableNativeCapabilityFields),
     ]),
     axm: NoWriterAxmCapabilityStateSchema,
 })
@@ -362,21 +402,21 @@ export const SubagentsLayoutSchema = Schema.Literals(["file", "directory"]).anno
     description: "Whether subagents live in a directory or a single opaque file path.",
     examples: ["directory", "file"],
 });
-const PluginSubagentsCanonicalCapabilitySchema = Schema.Struct({
-    ...AvailableCanonicalCapabilityBaseFields,
+const PluginSubagentsNativeCapabilitySchema = Schema.Struct({
+    ...AvailableNativeCapabilityBaseFields,
     availability: PluginAvailabilitySchema,
 });
 /** @experimental This API is unstable and may change without notice. */
 export const SubagentsExtensionCapabilitySchema = Schema.Struct({
-    canonical: Schema.Union([
+    native: Schema.Union([
         Schema.Struct({
-            ...AvailableCanonicalCapabilityBaseFields,
+            ...AvailableNativeCapabilityBaseFields,
             availability: NativeAvailabilitySchema,
             directory: Schema.NonEmptyString,
             layout: SubagentsLayoutSchema,
         }),
-        PluginSubagentsCanonicalCapabilitySchema,
-        Schema.Struct(UnavailableCanonicalCapabilityFields),
+        PluginSubagentsNativeCapabilitySchema,
+        Schema.Struct(UnavailableNativeCapabilityFields),
     ]),
     axm: NoWriterAxmCapabilityStateSchema,
 })
@@ -408,7 +448,7 @@ const OptionalRuleDirectoryField = {
     directory: Schema.optionalKey(Schema.NonEmptyString),
 };
 const AgentsMdRulesExtensionCapabilitySchema = Schema.Struct({
-    ...AvailableSpecTrackedCanonicalCapabilityFields,
+    ...AvailableSpecTrackedNativeCapabilityFields,
     ...OptionalRuleDirectoryField,
     kind: Schema.Literal("agents-md"),
     files: Schema.Tuple([Schema.Literal("AGENTS.md")]),
@@ -416,7 +456,7 @@ const AgentsMdRulesExtensionCapabilitySchema = Schema.Struct({
     importSyntax: Schema.NullOr(RuleInstructionsImportSyntaxSchema),
 });
 const OwnFileRulesExtensionCapabilitySchema = Schema.Struct({
-    ...AvailableSpecTrackedCanonicalCapabilityFields,
+    ...AvailableSpecTrackedNativeCapabilityFields,
     ...OptionalRuleDirectoryField,
     kind: Schema.Literal("own-file"),
     files: Schema.Tuple([Schema.NonEmptyString]),
@@ -424,7 +464,7 @@ const OwnFileRulesExtensionCapabilitySchema = Schema.Struct({
     importSyntax: Schema.NullOr(RuleInstructionsImportSyntaxSchema),
 });
 const RulesDirRulesExtensionCapabilitySchema = Schema.Struct({
-    ...AvailableSpecTrackedCanonicalCapabilityFields,
+    ...AvailableSpecTrackedNativeCapabilityFields,
     kind: Schema.Literal("rules-dir"),
     files: Schema.Array(Schema.NonEmptyString).pipe(Schema.check(Schema.isUnique())),
     nestedDiscovery: Schema.Boolean,
@@ -433,11 +473,11 @@ const RulesDirRulesExtensionCapabilitySchema = Schema.Struct({
 });
 /** @experimental This API is unstable and may change without notice. */
 export const RulesExtensionCapabilitySchema = Schema.Struct({
-    canonical: Schema.Union([
+    native: Schema.Union([
         AgentsMdRulesExtensionCapabilitySchema,
         OwnFileRulesExtensionCapabilitySchema,
         RulesDirRulesExtensionCapabilitySchema,
-        Schema.Struct(UnavailableCanonicalCapabilityFields),
+        Schema.Struct(UnavailableNativeCapabilityFields),
     ]),
     axm: NoWriterAxmCapabilityStateSchema,
 })
@@ -449,14 +489,14 @@ export const RulesExtensionCapabilitySchema = Schema.Struct({
 });
 /** @experimental This API is unstable and may change without notice. */
 export const FilesExtensionCapabilitySchema = Schema.Struct({
-    canonical: Schema.Union([
+    native: Schema.Union([
         Schema.Struct({
-            ...AvailableCanonicalCapabilityBaseFields,
+            ...AvailableNativeCapabilityBaseFields,
             directory: Schema.NonEmptyString,
             files: Schema.Array(Schema.NonEmptyString).pipe(Schema.check(Schema.isUnique())),
             naming: Schema.NullOr(Schema.NonEmptyString),
         }),
-        Schema.Struct(UnavailableCanonicalCapabilityFields),
+        Schema.Struct(UnavailableNativeCapabilityFields),
     ]),
     axm: NoWriterAxmCapabilityStateSchema,
 })
@@ -471,13 +511,14 @@ export const ConfigFileFormatSchema = Schema.Literals([
     "json",
     "jsonc",
     "toml",
+    "yaml",
     "starlark",
     "vscode-settings",
 ]).annotate({
     identifier: "ConfigFileFormat",
     title: "Config File Format",
     description: "Serialization format used by an agent's permission config file.",
-    examples: ["json", "toml", "vscode-settings"],
+    examples: ["json", "toml", "yaml", "vscode-settings"],
 });
 /** @experimental This API is unstable and may change without notice. */
 export const McpServersKeySchema = Schema.Literals([
@@ -572,37 +613,17 @@ export const McpEnvExpansionSchema = Schema.Struct({
     description: "Whether an agent expands MCP config environment references.",
 });
 const McpUnavailableCapabilityStruct = Schema.Struct({
-    canonical: Schema.Struct(UnavailableCanonicalCapabilityFields),
-    axm: Schema.Union([
-        Schema.Struct({
-            support: ActiveAxmSupportSchema,
-            lastVerified: LastVerifiedDateSchema,
-            writer: Schema.NullOr(Schema.Struct({ config: McpConfigSchema })),
-        }),
-        Schema.Struct({
-            support: InactiveAxmSupportSchema,
-            writer: Schema.NullOr(Schema.Struct({ config: McpConfigSchema })),
-        }),
-    ]),
+    native: Schema.Struct(UnavailableNativeCapabilityFields),
+    axm: axmCapabilityStateSchema(Schema.Struct({ config: McpConfigSchema }), "McpAxmState"),
 });
-const McpCanonicalWithTransportsSchema = Schema.Struct({
-    ...AvailableSpecTrackedCanonicalCapabilityFields,
+const McpNativeWithTransportsSchema = Schema.Struct({
+    ...AvailableSpecTrackedNativeCapabilityFields,
     transports: NonEmptyMcpTransportsSchema,
     mcpEnvExpansion: Schema.optionalKey(McpEnvExpansionSchema),
 });
 const McpAvailableCapabilityStruct = Schema.Struct({
-    canonical: McpCanonicalWithTransportsSchema,
-    axm: Schema.Union([
-        Schema.Struct({
-            support: ActiveAxmSupportSchema,
-            lastVerified: LastVerifiedDateSchema,
-            writer: Schema.NullOr(Schema.Struct({ config: McpConfigSchema })),
-        }),
-        Schema.Struct({
-            support: InactiveAxmSupportSchema,
-            writer: Schema.NullOr(Schema.Struct({ config: McpConfigSchema })),
-        }),
-    ]),
+    native: McpNativeWithTransportsSchema,
+    axm: axmCapabilityStateSchema(Schema.Struct({ config: McpConfigSchema }), "McpAxmState"),
 });
 const McpExtensionCapabilityStruct = Schema.Union([
     McpAvailableCapabilityStruct,
@@ -614,17 +635,17 @@ const McpExtensionCapabilitySchemaWithChecks = McpExtensionCapabilityStruct.pipe
     if (activeSourcesIssue !== undefined)
         issues.push(activeSourcesIssue);
     const writer = capability.axm.writer;
-    if (writer === null || !("transports" in capability.canonical))
+    if (writer === null || !("transports" in capability.native))
         return issues;
     const config = writer.config;
-    if (capability.canonical.transports.includes("stdio") && config.stdio === null) {
+    if (capability.native.transports.includes("stdio") && config.stdio === null) {
         issues.push({
             path: ["axm", "writer", "config", "stdio"],
             issue: "MCP stdio config is required when stdio transport is supported.",
         });
     }
-    if ((capability.canonical.transports.includes("http") ||
-        capability.canonical.transports.includes("sse")) &&
+    if ((capability.native.transports.includes("http") ||
+        capability.native.transports.includes("sse")) &&
         config.remote === null) {
         issues.push({
             path: ["axm", "writer", "config", "remote"],
@@ -676,35 +697,237 @@ export const ConfigFileLocationSchema = Schema.Struct({
     description: "A configuration file where an agent's permission rules can live.",
 });
 /** @experimental This API is unstable and may change without notice. */
-export const HooksSerializerSchema = Schema.Literals(["claude-code-settings"]).annotate({
+export const CANONICAL_HOOK_EVENT_IDS = [
+    "session.start",
+    "prompt.submit",
+    "turn.end",
+    "tool.pre",
+    "tool.post",
+    "subagent.stop",
+    "compaction.pre",
+];
+/** @experimental This API is unstable and may change without notice. */
+export const CanonicalHookEventIdSchema = Schema.Literals(CANONICAL_HOOK_EVENT_IDS).annotate({
+    identifier: "CanonicalHookEventId",
+    title: "Canonical Hook Event ID",
+    description: "Vendor-neutral hook lifecycle event identifier.",
+    examples: ["tool.pre", "tool.post", "prompt.submit"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookEventTierSchema = Schema.Literals(["core", "extended"]).annotate({
+    identifier: "HookEventTier",
+    title: "Hook Event Tier",
+    description: "Whether a canonical hook event belongs to the stable core or extended tail.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const CanonicalHookEventSchema = Schema.Struct({
+    id: CanonicalHookEventIdSchema,
+    tier: HookEventTierSchema,
+}).annotate({
+    identifier: "CanonicalHookEvent",
+    title: "Canonical Hook Event",
+    description: "Registered AXM hook event concept.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const CANONICAL_HOOK_EVENTS = [
+    { id: "session.start", tier: "core" },
+    { id: "prompt.submit", tier: "core" },
+    { id: "turn.end", tier: "core" },
+    { id: "tool.pre", tier: "core" },
+    { id: "tool.post", tier: "core" },
+    { id: "subagent.stop", tier: "extended" },
+    { id: "compaction.pre", tier: "extended" },
+];
+/** @experimental This API is unstable and may change without notice. */
+export const CANONICAL_HOOK_TOOL_IDS = [
+    "file.read",
+    "file.write",
+    "file.edit",
+    "shell.exec",
+    "web.fetch",
+    "mcp.call",
+];
+/** @experimental This API is unstable and may change without notice. */
+export const CanonicalHookToolIdSchema = Schema.Literals(CANONICAL_HOOK_TOOL_IDS).annotate({
+    identifier: "CanonicalHookToolId",
+    title: "Canonical Hook Tool ID",
+    description: "Vendor-neutral tool identity used by portable hook matchers.",
+    examples: ["file.write", "file.edit", "shell.exec"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookToolMappingSchema = Schema.Struct({
+    nativeName: Schema.NonEmptyString,
+    canonical: CanonicalHookToolIdSchema,
+    ...VerifiedProvenanceFields,
+}).annotate({
+    identifier: "HookToolMapping",
+    title: "Hook Tool Mapping",
+    description: "Native tool name with its canonical AXM tool identity and provenance.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookMechanismFamilySchema = Schema.Literals(["command-stdin", "raw"]).annotate({
+    identifier: "HookMechanismFamily",
+    title: "Hook Mechanism Family",
+    description: "How a native hook system invokes a hook.",
+    examples: ["command-stdin", "raw"],
+});
+const NonEmptyHookMechanismFamiliesSchema = Schema.NonEmptyArray(HookMechanismFamilySchema).pipe(Schema.check(Schema.isUnique()));
+/** @experimental This API is unstable and may change without notice. */
+export const HookMatcherKindSchema = Schema.Literals([
+    "regex",
+    "literal-list",
+    "glob",
+    "tool-category",
+    "exact-substring",
+    "none-imperative",
+]).annotate({
+    identifier: "HookMatcherKind",
+    title: "Hook Matcher Kind",
+    description: "Native matcher syntax used to scope hook invocation.",
+    examples: ["regex", "glob", "none-imperative"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookMatcherSchema = Schema.Struct({
+    kind: HookMatcherKindSchema,
+    example: Schema.NullOr(Schema.NonEmptyString),
+    notes: Schema.NullOr(Schema.NonEmptyString),
+}).annotate({
+    identifier: "HookMatcher",
+    title: "Hook Matcher",
+    description: "Matcher model for a native hook event.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookBlockOutcomeSchema = Schema.Literals(["allow", "deny", "ask"]).annotate({
+    identifier: "HookBlockOutcome",
+    title: "Hook Block Outcome",
+    description: "Decision outcome available to blocking hook systems.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookModifyOperationSchema = Schema.Literals([
+    "modify-input",
+    "inject-context",
+    "modify-output",
+    "synthesize",
+    "redact",
+]).annotate({
+    identifier: "HookModifyOperation",
+    title: "Hook Modify Operation",
+    description: "Transform operation available to modifying hook systems.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookDecisionCapabilitySchema = Schema.Union([
+    Schema.Struct({ kind: Schema.Literal("observe") }),
+    Schema.Struct({
+        kind: Schema.Literal("block"),
+        outcomes: Schema.NonEmptyArray(HookBlockOutcomeSchema).pipe(Schema.check(Schema.isUnique())),
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("modify"),
+        operations: Schema.NonEmptyArray(HookModifyOperationSchema).pipe(Schema.check(Schema.isUnique())),
+    }),
+]).annotate({
+    identifier: "HookDecisionCapability",
+    title: "Hook Decision Capability",
+    description: "Whether a hook event can observe, block, or modify lifecycle behavior.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookEventMappingSchema = Schema.Struct({
+    nativeName: Schema.NonEmptyString,
+    canonical: CanonicalHookEventIdSchema,
+    matcher: HookMatcherSchema,
+    decision: Schema.NonEmptyArray(HookDecisionCapabilitySchema),
+    ...VerifiedProvenanceFields,
+}).annotate({
+    identifier: "HookEventMapping",
+    title: "Hook Event Mapping",
+    description: "Native hook event name with its canonical AXM event pointer and provenance.",
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HooksSerializerSchema = Schema.Literals(["command-stdin"]).annotate({
     identifier: "HooksSerializer",
     title: "Hooks Serializer",
     description: "Native settings serializer AXM uses for managed hook declarations.",
-    examples: ["claude-code-settings"],
+    examples: ["command-stdin"],
 });
 /** @experimental This API is unstable and may change without notice. */
-export const HooksExtensionCapabilitySchema = Schema.Struct({
-    canonical: Schema.Union([
-        Schema.Struct({
-            ...AvailableCanonicalCapabilityBaseFields,
-            configFiles: Schema.Array(ConfigFileLocationSchema),
-        }),
-        Schema.Struct(UnavailableCanonicalCapabilityFields),
-    ]),
-    axm: Schema.Union([
-        Schema.Struct({
-            support: ActiveAxmSupportSchema,
-            lastVerified: LastVerifiedDateSchema,
-            writer: Schema.NullOr(Schema.Struct({ serializer: HooksSerializerSchema })),
-        }),
-        Schema.Struct({
-            support: InactiveAxmSupportSchema,
-            writer: Schema.NullOr(Schema.Struct({ serializer: HooksSerializerSchema })),
-        }),
+export const HookMatcherSerializationSchema = Schema.Literals([
+    "bare",
+    "slash-delimited",
+    "glob",
+]).annotate({
+    identifier: "HookMatcherSerialization",
+    title: "Hook Matcher Serialization",
+    description: "How AXM serializes manifest matcher strings into an agent-native hook group.",
+    examples: ["bare", "slash-delimited", "glob"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookTimeoutSerializationSchema = Schema.Literals(["seconds", "milliseconds"]).annotate({
+    identifier: "HookTimeoutSerialization",
+    title: "Hook Timeout Serialization",
+    description: "Unit AXM uses when serializing hook timeout fields into native settings.",
+    examples: ["seconds", "milliseconds"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HookCommandNameSerializationSchema = Schema.Literals(["omit", "manifest"]).annotate({
+    identifier: "HookCommandNameSerialization",
+    title: "Hook Command Name Serialization",
+    description: "Whether native command hook entries need an explicit name field.",
+    examples: ["omit", "manifest"],
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HooksWriterSchema = Schema.Struct({
+    serializer: HooksSerializerSchema,
+    configFiles: Schema.NonEmptyArray(ConfigFileLocationSchema),
+    settingsKey: Schema.NonEmptyString,
+    eventMap: Schema.Literal("native.events"),
+    matcherKind: HookMatcherKindSchema,
+    matcherSerialization: HookMatcherSerializationSchema,
+    timeoutSerialization: HookTimeoutSerializationSchema,
+    commandNameSerialization: HookCommandNameSerializationSchema,
+}).annotate({
+    identifier: "HooksWriter",
+    title: "Hooks Writer",
+    description: "Parameterized AXM hook writer metadata derived from native hook catalog data.",
+});
+const HooksAvailableNativeCapabilitySchema = Schema.Struct({
+    ...AvailableNativeCapabilityBaseFields,
+    mechanism: NonEmptyHookMechanismFamiliesSchema,
+    configFiles: Schema.Array(ConfigFileLocationSchema),
+    events: Schema.NonEmptyArray(HookEventMappingSchema),
+    tools: Schema.Array(HookToolMappingSchema),
+});
+const HooksUnmodeledNativeCapabilitySchema = Schema.Struct({
+    ...AvailableNativeCapabilityBaseFields,
+    modeling: Schema.Literal("native-unmodeled"),
+});
+const HooksExtensionCapabilityStruct = Schema.Struct({
+    native: Schema.Union([
+        HooksAvailableNativeCapabilitySchema,
+        HooksUnmodeledNativeCapabilitySchema,
+        Schema.Struct(UnavailableNativeCapabilityFields),
     ]),
-})
-    .pipe(Schema.check(Schema.makeFilter(requireSourcesForActiveAxmSupport)))
-    .annotate({
+    axm: axmCapabilityStateSchema(HooksWriterSchema, "HooksAxmState"),
+});
+/** @experimental This API is unstable and may change without notice. */
+export const HooksExtensionCapabilitySchema = HooksExtensionCapabilityStruct.pipe(Schema.check(Schema.makeFilter((capability) => {
+    const issues = [];
+    if (capability.axm.writer !== null && capability.native.sources.length === 0) {
+        issues.push({
+            path: ["native", "sources"],
+            issue: "Hook writer claims require at least one native source.",
+        });
+    }
+    if ("events" in capability.native) {
+        const nativeToolNames = new Set(capability.native.tools.map((tool) => tool.nativeName));
+        if (nativeToolNames.size !== capability.native.tools.length) {
+            issues.push({
+                path: ["native", "tools"],
+                issue: "Hook native tool mappings require unique nativeName values.",
+            });
+        }
+    }
+    return issues;
+}))).annotate({
     identifier: "HooksExtensionCapability",
     title: "Hooks Capability",
     description: "Agent support for lifecycle hook extensions.",
@@ -754,28 +977,18 @@ export const PermissionGrantSchema = PermissionGrantStruct.pipe(Schema.check(Sch
 });
 /** @experimental This API is unstable and may change without notice. */
 export const PermissionsExtensionCapabilitySchema = Schema.Struct({
-    canonical: Schema.Union([
+    native: Schema.Union([
         Schema.Struct({
-            ...AvailableCanonicalCapabilityBaseFields,
+            ...AvailableNativeCapabilityBaseFields,
             mechanism: NonEmptyPermissionMechanismsSchema,
             configFiles: Schema.Array(ConfigFileLocationSchema),
             grammar: Schema.NullOr(PermissionGrammarSchema),
             prerequisites: Schema.Array(PermissionPrerequisiteSchema),
             cliFlags: Schema.Array(PermissionCliFlagSchema),
         }),
-        Schema.Struct(UnavailableCanonicalCapabilityFields),
-    ]),
-    axm: Schema.Union([
-        Schema.Struct({
-            support: ActiveAxmSupportSchema,
-            lastVerified: LastVerifiedDateSchema,
-            writer: Schema.NullOr(Schema.Struct({ grants: Schema.Record(Schema.String, PermissionGrantSchema) })),
-        }),
-        Schema.Struct({
-            support: InactiveAxmSupportSchema,
-            writer: Schema.NullOr(Schema.Struct({ grants: Schema.Record(Schema.String, PermissionGrantSchema) })),
-        }),
+        Schema.Struct(UnavailableNativeCapabilityFields),
     ]),
+    axm: axmCapabilityStateSchema(Schema.Struct({ grants: Schema.Record(Schema.String, PermissionGrantSchema) }), "PermissionsAxmState"),
 })
     .pipe(Schema.check(Schema.makeFilter(requireSourcesForActiveAxmSupport)))
     .annotate({
@@ -852,11 +1065,11 @@ const AgentStruct = Schema.Struct({
 });
 /** @experimental This API is unstable and may change without notice. */
 export const AgentSchema = AgentStruct.pipe(Schema.check(Schema.makeFilter((agent) => {
-    if ("kind" in agent.capabilities.rule.canonical &&
-        agent.capabilities.rule.canonical.kind === "agents-md" &&
-        agent.capabilities.rule.canonical.files[0] !== "AGENTS.md") {
+    if ("kind" in agent.capabilities.rule.native &&
+        agent.capabilities.rule.native.kind === "agents-md" &&
+        agent.capabilities.rule.native.files[0] !== "AGENTS.md") {
         return {
-            path: ["capabilities", "rule", "canonical", "files"],
+            path: ["capabilities", "rule", "native", "files"],
             issue: 'capabilities.rule.kind "agents-md" requires AGENTS.md.',
         };
     }