@herjarsa/omo-meta-governor 0.40.0 → 0.43.0

package/dist/config.d.ts

@@ -130,6 +130,69 @@ export interface MetaGovernorPluginConfig {
         };
     };
     /** Sisyphus protocol enforcement config. */
+    /**
+     * v0.41.0: Tier 1 governance - active policy enforcement via OpenCode hooks.
+     *
+     * Before v0.41.0 the plugin could only OBSERVE tool calls. This block adds
+     * the ability to BLOCK and REWRITE: permission.ask denies dangerous ops,
+     * tool.definition rewrites tool descriptions, command.execute.before filters
+     * destructive shell commands, and experimental.provider.small_model forces
+     * cheap models on subagents.
+     *
+     * All sub-blocks default to no-op (no behavior change vs v0.40.0) - features
+     * require explicit opt-in via the respective flags.
+     */
+    governance?: {
+        /** permission.ask policy. Default "allow" + empty patterns = no-op (preserves v0.40.0). */
+        permissionPolicy?: {
+            /**
+             * @default "allow"
+             * - "allow": plugin only denies when a pattern matches (default).
+             * - "deny-on-match": same as "allow" - kept for future semantic.
+             * - "ask-on-match": only escalate to user prompt on pattern match.
+             */
+            mode?: "allow" | "deny-on-match" | "ask-on-match";
+            /** Bash command regex patterns to deny (matched anywhere in command). */
+            bashDenyPatterns?: string[];
+            /** Bash command patterns that require user confirmation. */
+            bashAskPatterns?: string[];
+            /** Edit path glob patterns to deny (matched against file path). */
+            editDenyPaths?: string[];
+            /** Edit path patterns that require user confirmation. */
+            editAskPaths?: string[];
+            /** webfetch URL host patterns to deny (matched against host). */
+            webfetchDenyHosts?: string[];
+        };
+        /** tool.definition policy. Default disabled (no behavior change). */
+        toolRewrite?: {
+            /** @default false */
+            enabled?: boolean;
+            /** Suffix to append to every tool description visible to LLM. */
+            descriptionSuffix?: string;
+            /** Hide specific tools entirely from LLM by clearing description. */
+            hideToolIDs?: string[];
+            /** Override parameter descriptions per tool. */
+            parameterOverrides?: Record<string, Record<string, string>>;
+        };
+        /** command.execute.before policy. Default disabled. */
+        commandFilter?: {
+            /** @default false */
+            enabled?: boolean;
+            /** Dangerous command regex patterns - throw on match to block execution. */
+            denyPatterns?: string[];
+            /** Prefix injected as warning text part (does not block, only warns). */
+            replacementPrefix?: string;
+        };
+        /** experimental.provider.small_model override for subagent cost control. Default disabled. */
+        smallModelOverride?: {
+            /** @default false */
+            enabled?: boolean;
+            /** Force this model ID for subagents (e.g. "claude-3-5-haiku-20241022"). */
+            modelID?: string;
+            /** Provider ID (e.g. "anthropic"). */
+            providerID?: string;
+        };
+    };
     protocolEnforcement?: {
         enabled?: boolean;
         path?: string;

package/dist/governance/command-filter.d.ts

@@ -0,0 +1,34 @@
+/**
+ * v0.41.0: command.execute.before hook handler.
+ *
+ * Blocks destructive shell commands (the `!`-prefixed palette). When enabled,
+ * every command is checked against the denyPatterns list (regex). On match,
+ * the handler throws — OpenCode surfaces the error to the agent.
+ *
+ * The optional replacementPrefix is appended as a warning text part; it is
+ * informative only (does not block).
+ */
+import type { MetricsCollector } from "../metrics";
+export interface GovernanceCommandFilterPolicy {
+    readonly enabled?: boolean;
+    readonly denyPatterns?: readonly string[];
+    readonly replacementPrefix?: string;
+}
+export interface CommandInput {
+    command: string;
+    sessionID: string;
+    arguments: string;
+}
+export interface CommandOutput {
+    parts: Array<{
+        type: string;
+        text: string;
+        synthetic?: boolean;
+    }>;
+}
+/**
+ * v0.41.0: Handle a command.execute.before invocation.
+ * - If not enabled or no patterns: pass through.
+ * - If a deny pattern matches: increment counter, throw (blocks execution).
+ */
+export declare function handleCommandFilter(input: CommandInput, _output: CommandOutput, policy: GovernanceCommandFilterPolicy, metrics: MetricsCollector): Promise<void>;

package/dist/governance/permission-gate.d.ts

@@ -0,0 +1,42 @@
+/**
+ * v0.41.0: permission.ask hook handler.
+ *
+ * Routes permission requests through the governance policy. When the policy
+ * matches a deny/ask pattern, the handler mutates output.status to block or
+ * prompt the user, and increments the appropriate counter.
+ *
+ * SAFETY: policy.mode === undefined or empty patterns = pure pass-through
+ * (preserves v0.40.0 behavior - OpenCode prompts user by default).
+ */
+import type { MetricsCollector } from "../metrics";
+import { type GovernancePermissionPolicySubset } from "./permission-rules";
+/**
+ * OpenCode Permission shape (subset we care about - the SDK defines more types).
+ * Discriminated by `type`.
+ */
+export type Permission = {
+    type: "bash";
+    command: string;
+    [k: string]: unknown;
+} | {
+    type: "edit";
+    pattern: string;
+    [k: string]: unknown;
+} | {
+    type: "webfetch";
+    url: string;
+    [k: string]: unknown;
+} | {
+    type: string;
+    [k: string]: unknown;
+};
+export interface PermissionOutput {
+    status: "ask" | "deny" | "allow";
+}
+/**
+ * v0.41.0: Handle a permission.ask invocation.
+ * - If policy is undefined/empty: pass through (no override of status).
+ * - If a deny pattern matches: set status="deny" + increment governance_blocks.
+ * - If an ask pattern matches: set status="ask" + increment governance_asks.
+ */
+export declare function handlePermissionAsk(input: Permission, output: PermissionOutput, policy: GovernancePermissionPolicySubset, metrics: MetricsCollector): Promise<void>;

package/dist/governance/permission-rules.d.ts

@@ -0,0 +1,42 @@
+/**
+ * v0.41.0: Pure-function regex matchers for permission.ask policy.
+ *
+ * No I/O, no plugin deps - these are the building blocks the permission-gate
+ * handler calls. Each function returns a PermissionMatchResult with the
+ * governance decision ("deny" / "ask") and a human-readable reason
+ * for the audit log.
+ *
+ * SAFETY: callers MUST treat null as "do nothing" (preserve OpenCode's
+ * default permission flow). "deny" blocks silently, "ask" prompts the user.
+ */
+export type PermissionDecision = "allow" | "deny" | "ask";
+export interface PermissionMatchResult {
+    decision: Exclude<PermissionDecision, "allow">;
+    reason: string;
+}
+/**
+ * v0.41.0: Governance policy shape - subset of MetaGovernorPluginConfig that
+ * the matchers care about. Defined here so this file has no dependency on
+ * the full config schema.
+ */
+export interface GovernancePermissionPolicySubset {
+    mode?: "allow" | "deny-on-match" | "ask-on-match";
+    bashDenyPatterns?: string[];
+    bashAskPatterns?: string[];
+    editDenyPaths?: string[];
+    editAskPaths?: string[];
+    webfetchDenyHosts?: string[];
+}
+/**
+ * Evaluate bash permission: returns the FIRST matching rule (deny beats ask).
+ * If no match: returns null - caller should treat as "allow" (no override).
+ */
+export declare function evaluateBashPolicy(command: string, policy: GovernancePermissionPolicySubset): PermissionMatchResult | null;
+/**
+ * Evaluate edit permission against file path patterns.
+ */
+export declare function evaluateEditPolicy(filepath: string, policy: GovernancePermissionPolicySubset): PermissionMatchResult | null;
+/**
+ * Evaluate webfetch permission against URL host patterns.
+ */
+export declare function evaluateWebfetchPolicy(url: string, policy: GovernancePermissionPolicySubset): PermissionMatchResult | null;

package/dist/governance/small-model.d.ts

@@ -0,0 +1,36 @@
+/**
+ * v0.41.0: experimental.provider.small_model hook handler — subagent cost control.
+ *
+ * When enabled, the plugin overrides which model OpenCode uses for the
+ * cheap/fast path (TaskTool/Oracle subagents). The provider hook receives the
+ * provider context with the provider's bundled model list; if the configured
+ * modelID exists in that list, the handler replaces output.model so OpenCode
+ * will schedule the subagent on the cheaper model.
+ *
+ * Graceful degradation: the handler is a pure no-op if the policy is empty
+ * or the model cannot be found — OpenCode keeps its default choice.
+ */
+export interface GovernanceSmallModelPolicy {
+    readonly enabled?: boolean;
+    readonly modelID?: string;
+    readonly providerID?: string;
+}
+export interface SmallModelInput {
+    provider: {
+        models?: Record<string, unknown>;
+        [k: string]: unknown;
+    };
+}
+export interface SmallModelOutput {
+    model?: {
+        id?: string;
+        providerID?: string;
+        [k: string]: unknown;
+    };
+}
+/**
+ * v0.41.0: Handle a provider.small_model invocation.
+ * - If not enabled or modelID/providerID missing: pass through.
+ * - Finds the configured model in the provider's model list and assigns it.
+ */
+export declare function handleSmallModel(input: SmallModelInput, output: SmallModelOutput, policy: GovernanceSmallModelPolicy): Promise<void>;

package/dist/governance/tool-rewriter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * v0.41.0: tool.definition hook handler.
+ *
+ * Routes tool definition output through the governance policy. When enabled,
+ * the handler can hide specific tools or suffix every tool description with a
+ * governance marker. Parameter description overrides are per-tool and per-param.
+ *
+ * SAFETY: when policy.enabled is falsy, this is a pure pass-through.
+ */
+import type { MetricsCollector } from "../metrics";
+export interface GovernanceToolRewritePolicy {
+    readonly enabled?: boolean;
+    readonly descriptionSuffix?: string;
+    readonly hideToolIDs?: readonly string[];
+    readonly parameterOverrides?: Record<string, Record<string, string>>;
+}
+export interface ToolDefinitionInput {
+    toolID: string;
+}
+export interface ToolDefinitionOutput {
+    description: string;
+    parameters: {
+        properties?: Record<string, {
+            description?: string;
+            [k: string]: unknown;
+        }>;
+    };
+}
+/**
+ * v0.41.0: Handle a tool.definition invocation.
+ * - If not enabled: pass through.
+ * - If tool is in hideToolIDs: set description to empty string (hidden from LLM).
+ * - Otherwise: append descriptionSuffix if set, and apply parameterOverrides.
+ */
+export declare function handleToolDefinition(input: ToolDefinitionInput, output: ToolDefinitionOutput, policy: GovernanceToolRewritePolicy, metrics: MetricsCollector): Promise<void>;