opencode-matrixx 2.6.6 → 2.6.8

package/dist/matrixx.schema.json

@@ -4063,6 +4063,27 @@
                   "turns": 4
                 }
               }
+            },
+            "brutal": {
+              "pruneNotification": "off",
+              "compress": {
+                "maxContextLimit": "20%",
+                "minContextLimit": "10%",
+                "nudgeFrequency": 1,
+                "nudgeForce": "strong",
+                "iterationNudgeThreshold": 1
+              },
+              "turnProtection": {
+                "enabled": false
+              },
+              "experimental": {
+                "allowSubAgents": false
+              },
+              "strategies": {
+                "purgeErrors": {
+                  "turns": 1
+                }
+              }
             }
           },
           "type": "object",
@@ -4184,6 +4205,46 @@
         "default_profile": {
           "type": "string"
         },
+        "handoffCompression": {
+          "default": {
+            "enabled": true,
+            "maxMessages": 6,
+            "keepFirst": 2,
+            "keepLast": 3
+          },
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "default": true,
+              "type": "boolean"
+            },
+            "maxMessages": {
+              "default": 6,
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 9007199254740991
+            },
+            "keepFirst": {
+              "default": 2,
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991
+            },
+            "keepLast": {
+              "default": 3,
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991
+            }
+          },
+          "required": [
+            "enabled",
+            "maxMessages",
+            "keepFirst",
+            "keepLast"
+          ],
+          "additionalProperties": false
+        },
         "base": {
           "default": {
             "autoUpdate": false,
@@ -4217,7 +4278,10 @@
               "enabled": false,
               "automaticStrategies": true
             },
-            "protectedFilePatterns": []
+            "protectedFilePatterns": [],
+            "experimental": {
+              "allowSubAgents": true
+            }
           },
           "type": "object",
           "properties": {
@@ -4436,6 +4500,18 @@
               "items": {
                 "type": "string"
               }
+            },
+            "experimental": {
+              "default": {
+                "allowSubAgents": true
+              },
+              "type": "object",
+              "properties": {
+                "allowSubAgents": {
+                  "type": "boolean"
+                }
+              },
+              "additionalProperties": false
             }
           },
           "required": [
@@ -4446,7 +4522,8 @@
             "strategies",
             "commands",
             "manualMode",
-            "protectedFilePatterns"
+            "protectedFilePatterns",
+            "experimental"
           ],
           "additionalProperties": false
         }
@@ -4454,6 +4531,7 @@
       "required": [
         "enabled",
         "profiles",
+        "handoffCompression",
         "base"
       ],
       "additionalProperties": false
@@ -4678,6 +4756,91 @@
             }
           },
           "additionalProperties": false
+        },
+        "admissionTimeoutMs": {
+          "anyOf": [
+            {
+              "type": "number",
+              "const": 0
+            },
+            {
+              "type": "number",
+              "minimum": 60000
+            }
+          ]
+        },
+        "nestedAdmission": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "mode": {
+              "type": "string",
+              "enum": [
+                "bypass",
+                "reserve"
+              ]
+            },
+            "maxDepth": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 5
+            }
+          },
+          "additionalProperties": false
+        },
+        "wakeScheduler": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "intervalMs": {
+              "type": "number",
+              "minimum": 60000
+            }
+          },
+          "additionalProperties": false
+        },
+        "jobBoard": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "strategy": {
+              "type": "string",
+              "enum": [
+                "latest",
+                "checkpoint-compatible"
+              ]
+            },
+            "maxRetainedSnapshots": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100
+            }
+          },
+          "additionalProperties": false
+        },
+        "wallClockTimeoutMs": {
+          "anyOf": [
+            {
+              "type": "number",
+              "const": 0
+            },
+            {
+              "type": "integer",
+              "minimum": 60000,
+              "maximum": 2147483647
+            }
+          ]
+        },
+        "wallClockAbortGraceMs": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 60000
         }
       },
       "additionalProperties": false
@@ -5206,7 +5369,6 @@
         },
         "blocked_tools": {
           "default": [
-            "read",
             "grep",
             "glob"
           ],

package/dist/plugin-handlers/agent-config-handler.d.ts

@@ -1,8 +1,9 @@
 import type { MatrixxConfig } from "../config";
+import { type ContextModeConfigInput } from "../shared/context-mode-enforcement";
 import type { PluginComponents } from "./plugin-components-loader";
 export declare function setAvailableToolNames(names: string[]): void;
 export declare function getAvailableToolNames(): string[];
-export declare function injectContextDiscipline(availableToolNames: string[], agents: Record<string, Record<string, unknown>>): void;
+export declare function injectContextDiscipline(availableToolNames: string[], agents: Record<string, Record<string, unknown>>, contextMode?: ContextModeConfigInput): void;
 export declare function applyAgentConfig(params: {
     config: Record<string, unknown>;
     pluginConfig: MatrixxConfig;

package/dist/shared/context-mode-enforcement.d.ts

@@ -0,0 +1,35 @@
+/** Canonical default — hook, constants, and schema must all agree on this. */
+export declare const CONTEXT_MODE_DEFAULT_BLOCKED_TOOLS: readonly ["grep", "glob"];
+export interface ContextModeEnforcement {
+    enabled: boolean;
+    enforce: boolean;
+    blockedTools: string[];
+}
+export interface ContextModeConfigInput {
+    enabled?: boolean;
+    enforce?: boolean;
+    blocked_tools?: string[];
+}
+/**
+ * Single source of truth for context-mode enforcement state.
+ * Both the context-mode-enforcer hook (block decision) and the agent prompt
+ * builders (guidance text) derive from this — prompt and hook can never
+ * disagree because they read the same resolved flags.
+ */
+export declare function resolveContextModeEnforcement(contextMode: ContextModeConfigInput | undefined): ContextModeEnforcement;
+/** Exact tool-name match for the raw search tools (mirrors the hook's check). */
+export declare function hasGrepGlobToolNames(toolNames: readonly string[]): boolean;
+/**
+ * Whether agent prompts may advertise a grep/glob fallback.
+ * Usable = registered AND not blocked. Under enforce:true the hook throws on
+ * grep/glob, so the prompt must never offer them — it must name the working
+ * substitute (ctx_batch_execute / ctx_execute running `rg`) instead.
+ */
+export declare function resolveGrepGlobUsable(toolNames: readonly string[], contextMode?: ContextModeConfigInput): boolean;
+export declare function _setDisciplinePathForTesting(p: string | null | undefined): void;
+export declare function setContextModeForPrompts(contextMode: ContextModeConfigInput | undefined): void;
+export declare function getContextModeForPrompts(): ContextModeConfigInput | undefined;
+export declare function _resetContextModeEnforcementForTesting(): void;
+export declare function willBlockGrepGlob(contextMode: ContextModeConfigInput | undefined): boolean;
+export declare function resolveContextModeDisciplinePath(): string | null;
+export declare function hasWorkingSubstitute(): boolean;

package/dist/shared/index.d.ts

@@ -4,7 +4,7 @@ export * from "./binary-downloader";
 export * from "./command-executor";
 export * from "./config-errors";
 export * from "./connected-providers-cache";
-export * from "./context-mode-prompt";
+export * from "./context-mode-enforcement";
 export * from "./data-path";
 export * from "./deep-merge";
 export * from "./delay";

package/dist/shared/poll-timeout-outcome.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Poll-timeout outcome helper shared by the sync session poller.
+ *
+ * When `pollSyncSession` exhausts `maxPollTimeMs` without observing
+ * completion, the session is still running server-side. This helper turns
+ * that state into a machine-readable, non-throwing outcome string.
+ *
+ * Mirrors the shape of `src/shared/saturated-outcome.ts`
+ * (`formatSaturatedOutcome`): human-readable block plus a trailing
+ * `<task_metadata>{JSON}</task_metadata>` line for programmatic parsing.
+ */
+export declare const POLL_TIMEOUT_PREFIX = "Poll timeout reached";
+export declare const LAST_ASSISTANT_TEXT_CAP = 2000;
+export interface PollTimeoutOutcomeArgs {
+    sessionID: string;
+    agentToUse: string;
+    maxPollTimeMs: number;
+    lastAssistantText?: string;
+}
+export declare function formatPollTimeoutOutcome(args: PollTimeoutOutcomeArgs): string;
+export declare function isPollTimeoutOutcome(text: string): boolean;

package/dist/shared/revive-outcome.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Revive-outcome helpers shared by the background task revive tools.
+ *
+ * A revive either produces a fresh session for a terminal task or is refused
+ * with a machine-readable reason. These helpers turn either case into a
+ * human-readable, non-throwing outcome for the revive tools.
+ *
+ * The status and reason are typed as `string` on purpose: this module lives
+ * in `src/shared` and must not depend on `BackgroundTaskStatus`
+ * or `ReviveBlockReason` from the background-agent feature.
+ */
+export declare const UNREVIVABLE_REASONS: readonly ["active", "uncertain", "no-session", "unknown-task", "expired"];
+export declare function isUnrevivableReason(reason: string): boolean;
+export declare function formatReviveOutcome(taskId: string, sessionID: string, status: string): string;
+export declare function formatUnrevivable(taskId: string, reason: string, detail?: string): string;

package/dist/shared/saturated-outcome.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Launch-outcome helpers shared by the background task launch tools.
+ *
+ * A launch can terminate without ever producing a session. T7 made a saturated
+ * queue admission produce a terminal `stopped` task with
+ * `terminalReason: "queue-saturated"` (nested depth-exceeded produces
+ * `terminalReason: "nested-depth-exceeded"`). These helpers turn that terminal
+ * state into a machine-readable, non-throwing outcome for the launch tools.
+ *
+ * The status is typed as `string` on purpose: this module must not import from
+ * `src/features/**`, so it cannot depend on `BackgroundTaskStatus`.
+ */
+export declare const LAUNCH_TERMINAL_STATUSES: readonly ["error", "cancelled", "interrupt", "stopped", "statusUncertain"];
+export type LaunchTerminalStatus = (typeof LAUNCH_TERMINAL_STATUSES)[number];
+export declare function isLaunchTerminalStatus(status: string): status is LaunchTerminalStatus;
+export declare function isQueueSaturated(status: string, terminalReason: string | undefined): boolean;
+export declare function formatSaturatedOutcome(taskId: string): string;
+export declare function formatLaunchFailure(taskId: string, status: string): string;

package/dist/shared/wallclock-outcome.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Wall-clock outcome helpers shared by the background agent wall-clock supervisor.
+ *
+ * A wall-clock timeout terminates a running task that exceeds its elapsed-time bound
+ * measured from `startedAt`. This module formats the human-readable + machine-readable
+ * outcome payload (mirroring saturated-outcome.ts / revive-outcome.ts).
+ *
+ * The status and reason are typed as `string` on purpose: this module lives in
+ * `src/shared` and must not depend on `BackgroundTaskStatus` or any type from
+ * `src/features/**`.
+ */
+export declare function formatWallclockTimeout(taskId: string, elapsedMs: number, limitMs: number): string;
+/**
+ * Checks whether the given status and terminal reason pair indicates a
+ * wall-clock timeout. Uses raw strings so this module never imports
+ * from src/features/**.
+ */
+export declare function isWallclockTimeout(status: string, terminalReason: string | undefined): boolean;

package/dist/tools/background-task/constants.d.ts

@@ -1,2 +1,3 @@
 export declare const BACKGROUND_OUTPUT_DESCRIPTION = "Get output from background task. Use full_session=true to fetch session messages with filters. System notifies on completion, so block=true rarely needed.";
 export declare const BACKGROUND_CANCEL_DESCRIPTION = "Cancel running background task(s). Use all=true to cancel ALL before final answer.";
+export declare const BACKGROUND_REVIVE_DESCRIPTION = "Revive a retained terminal background task with a NEW instruction.\n\nCall with no arguments (or list=true) to DISCOVER revivable tasks.\n\nRevivable: cancelled, stopped, interrupt, error, completed \u2014 provided the task still has a session ID.\nNot revivable: pending/running (still active \u2014 use background_output), statusUncertain (unknown liveness \u2014 pass force=true to acknowledge), and tasks that never produced a session (e.g. queue-saturated).\n\nHandles are retained for 30 minutes, so revive works after a task was pruned or the plugin restarted.";

package/dist/tools/background-task/create-background-revive.d.ts

@@ -0,0 +1,3 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { BackgroundReviveManager } from "./types";
+export declare function createBackgroundRevive(manager: BackgroundReviveManager, directory: string): ToolDefinition;

package/dist/tools/background-task/index.d.ts

@@ -1,3 +1,3 @@
 export * from "./constants";
-export { createBackgroundCancel, createBackgroundOutput, } from "./tools";
+export { createBackgroundCancel, createBackgroundOutput, createBackgroundRevive, } from "./tools";
 export type * from "./types";

package/dist/tools/background-task/tools.d.ts

@@ -1,3 +1,4 @@
 export type { BackgroundCancelClient, BackgroundOutputClient, BackgroundOutputManager, BackgroundOutputMessage, BackgroundOutputMessagesResult, } from "./clients";
 export { createBackgroundCancel } from "./create-background-cancel";
 export { createBackgroundOutput } from "./create-background-output";
+export { createBackgroundRevive } from "./create-background-revive";

package/dist/tools/background-task/types.d.ts

@@ -13,6 +13,14 @@ export interface BackgroundCancelArgs {
     taskId?: string;
     all?: boolean;
 }
+export interface BackgroundReviveArgs {
+    taskId?: string;
+    session_id?: string;
+    prompt?: string;
+    list?: boolean;
+    force?: boolean;
+    parentSessionID?: string;
+}
 export type BackgroundOutputMessage = {
     info?: {
         role?: string;
@@ -54,6 +62,7 @@ export type BackgroundCancelClient = {
     };
 };
 export type BackgroundOutputManager = Pick<import("../../features/background-agent").BackgroundManager, "getTask">;
+export type BackgroundReviveManager = Pick<import("../../features/background-agent").BackgroundManager, "revive" | "listRevivable">;
 export type ToolContextWithMetadata = {
     sessionID: string;
     messageID: string;

package/dist/tools/dcp-switch-profile/tools.d.ts

@@ -5,4 +5,11 @@ export interface DcpSwitchProfileOptions {
         dcp?: DcpConfig;
     };
 }
+export declare function deepMergeProfile(builtin: Record<string, unknown>, override: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Switch the active DCP profile.
+ * Reads profile parameters from the Matrixx plugin configuration and writes
+ * a full inline DCP config to ~/.config/opencode/dcp.jsonc.
+ */
+export declare function switchProfile(profile: string, options?: DcpSwitchProfileOptions): string;
 export declare function createDcpSwitchProfileTool(options?: DcpSwitchProfileOptions): Record<string, ToolDefinition>;

package/dist/tools/delegate-task/constants.d.ts

@@ -3,6 +3,7 @@ import type { CategoryConfig } from "../../config/schema";
 export declare const DEFAULT_CATEGORIES: Record<string, CategoryConfig>;
 export declare const CATEGORY_PROMPT_APPENDS: Record<string, string>;
 export declare const CATEGORY_DESCRIPTIONS: Record<string, string>;
+export declare const SHORT_CATEGORY_HINTS: Record<string, string>;
 export declare function buildPlanAgentSystemPrepend(categories?: AvailableCategory[], skills?: AvailableSkill[]): string;
 /**
  * List of agent names that should be treated as plan agents (receive plan system prompt).

package/dist/tools/index.d.ts

@@ -25,10 +25,9 @@ import type { BackgroundManager } from "../features/background-agent";
 type OpencodeClient = PluginInput["client"];
 export { createAssemblyTool } from "./assembly";
 export { createDcpSwitchProfileTool } from "./dcp-switch-profile";
-export { createDelegateAgent } from "./delegate-agent";
 export { createDelegateTask } from "./delegate-task";
 export { createHashlineEditTool } from "./hashline-edit";
 export { createLookAt } from "./look-at";
 export { createTaskCleanupTool, createTaskCreateTool, createTaskGetTool, createTaskList, createTaskUpdateTool, } from "./task";
-export declare function createBackgroundTools(manager: BackgroundManager, client: OpencodeClient): Record<string, ToolDefinition>;
+export declare function createBackgroundTools(manager: BackgroundManager, client: OpencodeClient, directory: string): Record<string, ToolDefinition>;
 export declare const builtinTools: Record<string, ToolDefinition>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-matrixx",
-  "version": "2.6.6",
+  "version": "2.6.8",
   "description": "The Best AI Agent Harness - Batteries-Included OpenCode Plugin with Multi-Model Orchestration, Parallel Background Agents, and Crafted LSP/AST Tools",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/shared/context-mode-prompt.d.ts

@@ -1,12 +0,0 @@
-export interface ContextModeToolGuidance {
-    searchGuidance: string;
-    readGuidance: string;
-    analysisGuidance: string;
-}
-/**
- * Returns context-mode-aware tool guidance for subagent prompts.
- * When `enforce` is true, raw grep/glob/read/bash-cat are blocked by the
- * context-mode-enforcer hook, so guidance routes to ctx_* tools instead.
- * When `enforce` is false, legacy tool guidance is preserved.
- */
-export declare function getContextModeToolGuidance(enforce: boolean): ContextModeToolGuidance;

package/dist/tools/delegate-agent/background-executor.d.ts

@@ -1,13 +0,0 @@
-import type { PluginInput } from "@opencode-ai/plugin";
-import type { BackgroundManager } from "../../features/background-agent";
-import type { DelegateAgentArgs } from "./types";
-export declare function executeBackground(args: DelegateAgentArgs, toolContext: {
-    sessionID: string;
-    messageID: string;
-    agent: string;
-    abort: AbortSignal;
-    metadata?: (input: {
-        title?: string;
-        metadata?: Record<string, unknown>;
-    }) => void;
-}, manager: BackgroundManager, client: PluginInput["client"]): Promise<string>;

package/dist/tools/delegate-agent/completion-poller.d.ts

@@ -1,11 +0,0 @@
-import type { PluginInput } from "@opencode-ai/plugin";
-export declare function waitForCompletion(sessionID: string, toolContext: {
-    sessionID: string;
-    messageID: string;
-    agent: string;
-    abort: AbortSignal;
-    metadata?: (input: {
-        title?: string;
-        metadata?: Record<string, unknown>;
-    }) => void;
-}, ctx: PluginInput): Promise<void>;

package/dist/tools/delegate-agent/constants.d.ts

@@ -1,2 +0,0 @@
-export declare const ALLOWED_AGENTS: readonly ["trinity", "operator", "oracle", "construct"];
-export declare const CALL_DELEGATE_AGENT_DESCRIPTION = "Spawn explore/librarian agent. run_in_background REQUIRED (true=async with task_id, false=sync).\n\nAvailable: {agents}\n\nPass `session_id=<id>` to continue previous agent with full context. Prompts MUST be in English. Use `background_output` for async results.";

package/dist/tools/delegate-agent/index.d.ts

@@ -1,3 +0,0 @@
-export * from "./constants";
-export { createDelegateAgent } from "./tools";
-export * from "./types";

package/dist/tools/delegate-agent/message-dir.d.ts

@@ -1 +0,0 @@
-export { getMessageDir } from "../../shared/opencode-message-dir";

package/dist/tools/delegate-agent/message-processor.d.ts

@@ -1,2 +0,0 @@
-import type { PluginInput } from "@opencode-ai/plugin";
-export declare function processMessages(sessionID: string, ctx: PluginInput): Promise<string>;

package/dist/tools/delegate-agent/session-creator.d.ts

@@ -1,15 +0,0 @@
-import type { PluginInput } from "@opencode-ai/plugin";
-import type { DelegateAgentArgs } from "./types";
-export declare function createOrGetSession(args: DelegateAgentArgs, toolContext: {
-    sessionID: string;
-    messageID: string;
-    agent: string;
-    abort: AbortSignal;
-    metadata?: (input: {
-        title?: string;
-        metadata?: Record<string, unknown>;
-    }) => void;
-}, ctx: PluginInput): Promise<{
-    sessionID: string;
-    isNew: boolean;
-}>;

package/dist/tools/delegate-agent/sync-executor.d.ts

@@ -1,21 +0,0 @@
-import type { PluginInput } from "@opencode-ai/plugin";
-import { waitForCompletion } from "./completion-poller";
-import { processMessages } from "./message-processor";
-import { createOrGetSession } from "./session-creator";
-import type { DelegateAgentArgs } from "./types";
-type ExecuteSyncDeps = {
-    createOrGetSession: typeof createOrGetSession;
-    waitForCompletion: typeof waitForCompletion;
-    processMessages: typeof processMessages;
-};
-export declare function executeSync(args: DelegateAgentArgs, toolContext: {
-    sessionID: string;
-    messageID: string;
-    agent: string;
-    abort: AbortSignal;
-    metadata?: (input: {
-        title?: string;
-        metadata?: Record<string, unknown>;
-    }) => void;
-}, ctx: PluginInput, deps?: ExecuteSyncDeps): Promise<string>;
-export {};

package/dist/tools/delegate-agent/tools.d.ts

@@ -1,3 +0,0 @@
-import { type PluginInput, type ToolDefinition } from "@opencode-ai/plugin";
-import type { BackgroundManager } from "../../features/background-agent";
-export declare function createDelegateAgent(ctx: PluginInput, backgroundManager: BackgroundManager, disabledAgents?: string[]): ToolDefinition;

package/dist/tools/delegate-agent/types.d.ts

@@ -1,19 +0,0 @@
-import type { ALLOWED_AGENTS } from "./constants";
-export type AllowedAgentType = (typeof ALLOWED_AGENTS)[number];
-export interface DelegateAgentArgs {
-    description: string;
-    prompt: string;
-    subagent_type: string;
-    run_in_background: boolean;
-    session_id?: string;
-}
-export type ToolContextWithMetadata = {
-    sessionID: string;
-    messageID: string;
-    agent: string;
-    abort: AbortSignal;
-    metadata?: (input: {
-        title?: string;
-        metadata?: Record<string, unknown>;
-    }) => void;
-};