@gajae-code/coding-agent 0.7.2 → 0.7.4

package/CHANGELOG.md

@@ -2,6 +2,91 @@
 
 ## [Unreleased]
 
+## [0.7.4] - 2026-06-27
+
+### Added
+
+- Native Windows `gjc --tmux` is now backed by [psmux](https://github.com/psmux/psmux) when no real tmux is on PATH: a new `psmux-detect` module probes `psmux` / `pmux` / `tmux` on Windows and resolves the multiplexer to use, `tmux-common.ts` re-exports the resolver for downstream callers, and `buildDefaultTmuxLaunchPlan` builds a real PowerShell-encoded `--tmux` plan instead of falling through to the direct-launch diagnostic. The native Windows `gjc session` / `gjc team` ownership-tag and worker-spawn paths therefore work end-to-end on a Windows host with psmux installed (no WSL required).
+- Three new environment knobs back the Windows psmux path: `GJC_PSMUX_COMMAND` (force the multiplexer to be treated as psmux), `GJC_PSMUX_DETECTION` (`off` / `false` to skip probing entirely), and `GJC_PSMUX_FORCE_DETECT` (`1` / `true` to re-probe on every call). `GJC_TMUX_COMMAND` and `GJC_TEAM_TMUX_COMMAND` continue to override the multiplexer selection on every platform.
+- Implemented a GJC plugin bundle architecture: `gjc plugin install <path|package>` resolves and installs declarative GJC plugin bundles into user/project scope with a content-addressed registry (per-file SHA-256 manifest hashes), and `gjc plugin list|doctor|enable|disable|uninstall` manage them; local-path bundles install offline without npm (#1149).
+- Added Telegram-driven session lifecycle control so sessions can be created, closed, and resumed from Telegram, with per-session topic management wired into connect and shutdown (#1148).
+- Added a keyless `insane` web search provider that safely ports upstream [`fivetaku/insane-search`](https://github.com/fivetaku/insane-search) public-route fallbacks (MIT; vendored engine pinned in `packages/coding-agent/vendor/insane-search/`) without TLS impersonation, browser/cookie bypasses, credential storage, or auto-installed dependencies (#1011).
+- Added durable cold-spill eviction for compacted session history: after a compaction, `SessionManager.evictCompactedContent()` moves pre-`firstKeptEntryId` payloads (user/assistant text, thinking, tool-call arguments) out of the hot JSONL and resident heap into durable content-addressed sidecar blobs via `BlobStore.putImmutableSync`, keeping hot retained bytes bounded regardless of pre-compaction history size while preserving graph integrity and the compaction summary (#1166).
+- Added a non-materializing, path-only `buildSessionContext()` that no longer populates `#materializedEntriesCache` and performs zero cold-spill reads on covered compacted branches, plus fidelity read APIs (`getEntryForFidelity`/`getBranchForFidelity`/`getEntriesForExport`) that rehydrate cold-spilled content on demand for HTML export, branch & re-edit, and branched-session creation (#1166).
+- Added `BlobStore.putImmutableSync`/`getCheckedSync` (plus `EphemeralBlobStore`/`MemoryBlobStore` overrides): immutable, crash-safe, hash-verified content-addressed install (exclusive copy fallback + fsync) and checked reads that throw `BlobCorruptError` on corrupt blobs and never return silent wrong data (#1166).
+- Raised the `deep-interview` default maximum round count to 100.
+- New unit tests under `packages/coding-agent/test/gjc-runtime/psmux-detect.test.ts` cover detection verdicts, override precedence, cache behavior, and the `resolveGjcTmuxBinary` Windows / POSIX resolution paths.
+
+### Changed
+
+- `gjc team` now adopts any real tmux session as its leader — including one you started yourself outside `gjc --tmux` — by writing and reading back GJC's `@gjc-profile` ownership tag, instead of only accepting `gjc --tmux`-launched sessions. Providers that cannot round-trip tmux user options (e.g. psmux) are still rejected as unmanaged (#1140).
+- `gjc team` now fails with actionable guidance when there is no tmux leader to host workers: running it with no tmux installed reports `tmux_not_installed`, and running it outside any tmux session reports `not_inside_tmux` (with a hint to start one via `gjc --tmux` or your own `tmux`, or use `--dry-run`), instead of surfacing raw tmux stderr (#1143).
+- Improved `ultragoal` artifact-gate guidance in the completion quality gate (#1163).
+
+### Fixed
+
+- First-time `gjc` startup now shows only the installed/current version changelog entry instead of dumping the full historical changelog before the actionable UI; full history remains available through `/changelog --full` (#1184).
+- `gjc --tmux` on native Windows no longer silently falls through to a tmux-less launch: when psmux is installed the plan now boots gjc through a PowerShell-encoded inner command, when no tmux-class binary resolves on PATH the diagnostic points at the psmux install URL and `GJC_TMUX_COMMAND` override, and explicit `GJC_TMUX_COMMAND` overrides are honored on every platform.
+- The `gjc team` worker-command string is now formatted for the host shell: on Windows + psmux each env assignment uses the `$env:VAR = 'value';` PowerShell form (with PowerShell-safe single-quote escaping) instead of the POSIX `VAR='value'` form, so worker panes spawned via psmux ConPTY panes inherit the right `GJC_TEAM_*` environment.
+- `createGjcTmuxSession` now chooses the new-session bootstrap command for the host shell: PowerShell `$env:GJC_TMUX_LAUNCHED = '1'; gjc` on Windows, `exec env GJC_TMUX_LAUNCHED=1 gjc` on POSIX, so psmux-managed sessions tag the spawned gjc the same way tmux-managed ones do.
+- `applyGjcTmuxProfile` no longer hard-fails the `gjc --tmux` boot on Windows when psmux drops the UX profile round-trip. When the resolved multiplexer is psmux, only the `mouse` / `set-clipboard` / `mode-style` UX keys are filtered out; the `@gjc-profile` / branch / project / session-identity ownership tags are still emitted because those are required for `gjc session` and `gjc team`.
+- `renameExistingTmuxWindowIfNeeded` no longer short-circuits on `platform === "win32"`: on a Windows host running psmux inside `gjc --tmux`, the leader window now inherits the project:branch title the same way it does on POSIX.
+- Fixed tmux startup fast paths (#1142).
+- Deep Interview (and any scrollable `ask`/hook selector) no longer enables SGR mouse reporting, which was hijacking the mouse wheel and disabling the terminal's native scrollback while a question was on screen. The wheel now scrolls the terminal as usual; long questions still scroll inside the dialog via PgUp/PgDn (#1164).
+- Scrollable Deep Interview question boxes now show explicit `▲ more` / `▼ more` affordances when hidden question text exists, and selector mode also supports Ctrl+u/Ctrl+d as question-scroll aliases for PgUp/PgDn (#1164).
+- Fixed unbounded memory growth in long sessions: the full verbatim transcript was retained in `SessionManager.#fileEntries`/`#byId` forever across compactions (compaction only summarized the LLM-bound context), so long coding sessions could OOM. Compaction now reclaims hot resident content via cold-spill, the `AgentSession.compact()` post-append path no longer bulk-materializes the branch, and assistant tool-call arguments/text are no longer kept verbatim indefinitely (#1166).
+- Lossless branch/export fidelity after compaction: HTML export and branch & re-edit now rehydrate cold-spilled pre-compaction content instead of showing tombstone notices, and branched-session creation preserves cold-spill refs without truncating >500k-char content (#1166).
+- Materialize resident blobs before branch export so exported branches never reference unresolved resident blob refs.
+- Inherit the live fast-mode (`serviceTier`) into task subagents so delegated work uses the parent session's service tier (#1171).
+- Fixed model selection after model-profile preset activation so the activated preset's model is actually used (#1172).
+- Preserve session-only model-profile overrides instead of dropping them on later resolution (#1175).
+- Fixed the `gjc ultragoal checkpoint` goal-snapshot fallback so checkpoints reconcile correctly when a fresh snapshot is unavailable (#1177).
+- Added durable `gjc-session` diagnostics for the routed-session harness scripts (#1189).
+- Telegram: apply verbosity commands (#1139), fix clarify-choice rendering (#1147), create the session topic on connect, and delete session topics on shutdown.
+
+### Documentation
+
+- The native Windows psmux section in `docs/environment-variables.md` now reflects that `gjc --tmux` builds a real tmux-backed plan via psmux, lists the new `GJC_PSMUX_*` knobs, and explains the worker-spawn shell-quoting rule. The bundled `team` skill doc points readers at the same environment section instead of the legacy "psmux is not fully supported" warning.
+- Clarified Windows tmux fallback guidance.
+- Credited `fivetaku/insane-search` for the ported public-route search fallbacks.
+
+## [0.7.3] - 2026-06-25
+
+### Added
+
+- Added the `gruvbox-dark` built-in theme: the canonical Gruvbox dark palette mapped across every GJC theme token, selectable via `/theme`.
+- Added a standalone MCP registration command: `gjc mcp add|list|remove` writes explicit user-provided MCP server definitions (stdio/http/sse) into GJC config without importing or inheriting other tools' live MCP configs, with env/header/auth values redacted in output (#1095).
+
+### Changed
+
+- Refined the interactive composer chrome so the input box, status rail, and welcome banner share one visual language: the composer now uses a rounded border (matching the rounded welcome banner) instead of a sharp rectangle, and the status rail uses the subtle elevated `userMessageBg` surface tone instead of the heavy `statusLineBg` block, so it reads as a quiet layered zone rather than a solid bar. Both resolve through existing semantic theme slots, so every bundled theme tracks automatically.
+- When a Composer harness model is active, the `bash` tool now hard-blocks repository file I/O — pipes, process/heredoc/command substitution, redirection, `tee`, file read/discovery (`cat`/`head`/`tail`/`grep`/`find`/`ls`), file mutation (`cp`/`mv`/`rm`/`touch`/`mkdir`/`chmod`/`ln`), `sed`/`awk`, git file-read subcommands, and script file I/O — unless the command is on a strict allowlist (`bun test`/`run check|test|build`, `cargo test|check|build`, `git status`/`rev-parse`, package version queries), forcing Composer models to use the dedicated find/search/read/edit tools for file discovery and mutation (#1027).
+### Documentation
+
+- Documented the docs-only Aside evaluation boundary as an opt-in search/context retrieval sidecar using explicit user-provided MCP configuration, with browser actions, login flows, payments, internal tools, secrets, and raw browser/session payload logging out of scope by default (#1097).
+- Added a UI design and visual QA contract governing future TUI/dashboard/terminal visual work (#1101).
+- Added a CodeGraph custom-tool integration guide (#1073).
+- Documented the Windows psmux namespace boundary for `gjc --tmux`, `gjc session`, and `gjc team`: cwd/`-c` is now called out as a start directory rather than server isolation, `-L <namespace>` is identified as the psmux namespace primitive, and tmux command overrides are documented as executable names rather than shell command lines (#1118).
+- Clarified the Telegram Threaded Mode fallback documentation (#1122).
+
+### Fixed
+
+- Expanded the initial GJC forge welcome box to the live terminal viewport width and pinned the status/composer area to the bottom when the startup layout is shorter than the screen (#1120).
+
+- Deep Interview Restate/option gates now recover through the ask selector path instead of waiting on plaintext `Options:` output.
+- Widened the forge splash on wide terminals so it no longer clips (#1110).
+- Parse quoted SSH remote host names in the slash-command host parser (#1104).
+- Tolerate an unreadable git HEAD in the status chrome instead of throwing (#1072).
+- Registered the `plugin` command in the CLI command registry so `gjc plugin …` (install/uninstall/list/marketplace/enable/disable/doctor) resolves instead of silently falling through to the default launch/chat command — the command was implemented and tested but was never registered (#1071).
+- Keybinding/Ctrl+Enter newline-handling sweep across the editor and input controller (#1111).
+- Fixed model-profile default badge precedence in the `/model` selector so the correct default-profile badge wins (#1117).
+- Prevented duplicate Telegram topics being created for transient sessions (#1125).
+
+### Security
+
+- User-supplied URL reads now share the public HTTP(S) network guard that was previously insane-fallback-only: the initial target, the redirect chain, and binary-conversion redirects are all revalidated against private-network blocking before any request is opened or followed, closing an SSRF path through the normal read-tool fetch pipeline (#1114).
+- Bridge workflow-gate responses now require the claimed controller token before the unattended control plane may resolve a gate, and the `workflow_gate_response` RPC command was raised from prompt scope to control scope, so prompt-only clients can no longer answer lifecycle workflow gates (#1116).
+
 ## [0.7.2] - 2026-06-24
 ### Added
 
@@ -19,6 +104,7 @@
 - Preserve GJC-managed tmux sessions on attach/disconnect instead of tearing them down, and stop implicitly attaching on launch (#1063).
 - Corrected the auto-compaction output reserve so post-compaction responses keep adequate headroom (#1021).
 - Improved active-input shortcut hints and the busy-input queueing hint for clearer in-session guidance (#1022, #1024).
+- Fixed the Ultragoal ask guard blocking the `ask` tool when no GJC session can be resolved. `ultragoalReadPaths` falls back to the legacy/global `.gjc/ultragoal` directory when neither `GJC_SESSION_ID` nor an auto-detectable active session is present, but the follow-up `readUltragoalPlan`/`readUltragoalLedger` reads ignored that resolution and re-ran session detection, throwing `no active GJC session found` and surfacing `durable_state_unreadable` — which blocked `ask` for every agent even with no active Ultragoal run. `ultragoalReadPaths` now returns the resolved session id (or `null`); the ask guard treats a null session as inactive and falls open, and threads the resolved id into the plan/ledger reads so they no longer re-resolve. An inconsistent state (state dir present but `goals.json` missing/empty) still fails closed so the pause guard keeps blocking give-ups.
 
 ## [0.7.1] - 2026-06-23
 ### Fixed

package/bin/gjc.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { runCli } from "@gajae-code/coding-agent/cli";
+
+await runCli(process.argv.slice(2));

package/dist/types/cli/mcp-cli.d.ts

@@ -0,0 +1,25 @@
+import type { MCPServerConfig } from "../runtime-mcp/types";
+export type MCPAction = "add" | "list" | "remove";
+export interface MCPCommandArgs {
+    action: MCPAction;
+    name?: string;
+    commandArgs?: string[];
+    flags: {
+        project?: boolean;
+        force?: boolean;
+        json?: boolean;
+        type?: "stdio" | "http" | "sse";
+        command?: string;
+        url?: string;
+        arg?: string[];
+        env?: string[];
+        header?: string[];
+        cwd?: string;
+        timeout?: number;
+    };
+    cwd?: string;
+}
+export declare class MCPArgsError extends Error {
+}
+export declare function redactMCPServerConfig(config: MCPServerConfig): MCPServerConfig;
+export declare function runMCPCommand(args: MCPCommandArgs): Promise<void>;

package/dist/types/cli/plugin-cli.d.ts

@@ -17,6 +17,8 @@ export interface PluginCommandArgs {
         disable?: string;
         set?: string;
         scope?: "user" | "project";
+        user?: boolean;
+        project?: boolean;
     };
 }
 /**

package/dist/types/cli.d.ts

@@ -1,3 +1,9 @@
 #!/usr/bin/env bun
+/**
+ * CLI entry point — registers all commands explicitly and delegates to the
+ * lightweight CLI runner from pi-utils.
+ */
+import { type CommandEntry } from "@gajae-code/utils/cli";
+export declare const commands: CommandEntry[];
 /** Run the CLI with the given argv (no `process.argv` prefix). */
 export declare function runCli(argv: string[]): Promise<void>;

package/dist/types/commands/mcp.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Direct MCP server registration for standalone GJC.
+ */
+import { Command } from "@gajae-code/utils/cli";
+import { type MCPAction } from "../cli/mcp-cli";
+export default class MCP extends Command {
+    static description: string;
+    static delegateHelp: boolean;
+    static examples: string[];
+    static args: {
+        action: import("@gajae-code/utils/cli").ArgDescriptor & {
+            description: string;
+            required: false;
+            options: MCPAction[];
+        };
+        name: import("@gajae-code/utils/cli").ArgDescriptor & {
+            description: string;
+            required: false;
+        };
+        commandArgs: import("@gajae-code/utils/cli").ArgDescriptor & {
+            description: string;
+            required: false;
+            multiple: true;
+        };
+    };
+    static flags: {
+        project: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        force: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+        json: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            char: string;
+            description: string;
+            default: boolean;
+        };
+        type: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            options: string[];
+        };
+        command: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        url: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        arg: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            multiple: true;
+        };
+        env: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            multiple: true;
+        };
+        header: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+            multiple: true;
+        };
+        cwd: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        timeout: import("@gajae-code/utils/cli").FlagDescriptor<"integer"> & {
+            description: string;
+        };
+    };
+    run(): Promise<void>;
+    private printHelp;
+}

package/dist/types/commands/plugin.d.ts

@@ -47,6 +47,12 @@ export default class Plugin extends Command {
             description: string;
             options: string[];
         };
+        user: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        project: import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
     };
     run(): Promise<void>;
 }

package/dist/types/commands/session.d.ts

@@ -18,6 +18,12 @@ export default class Session extends Command {
             description: string;
             default: boolean;
         };
+        "session-id": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        "state-file": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
     };
     static examples: string[];
     run(): Promise<void>;

package/dist/types/config/keybindings.d.ts

@@ -230,8 +230,8 @@ export declare const KEYBINDINGS: {
         readonly description: "Open external editor";
     };
     readonly "app.message.followUp": {
-        readonly defaultKeys: "ctrl+enter";
-        readonly description: "Send follow-up message";
+        readonly defaultKeys: [];
+        readonly description: "Send follow-up message (no default; Ctrl+Enter inserts a newline)";
     };
     readonly "app.message.queue": {
         readonly defaultKeys: "alt+enter";

package/dist/types/config/model-profile-activation.d.ts

@@ -1,7 +1,7 @@
 import type { ThinkingLevel } from "@gajae-code/agent-core";
 import type { Api, Model } from "@gajae-code/ai";
 import type { AgentSession } from "../session/agent-session";
-import { type ModelRegistry } from "./model-registry";
+import { type GjcModelAssignmentTargetId, type ModelRegistry } from "./model-registry";
 import type { Settings } from "./settings";
 type ModelProfileActivationSession = Pick<AgentSession, "model" | "thinkingLevel" | "sessionId"> & {
     setModelTemporary?: AgentSession["setModelTemporary"];
@@ -40,6 +40,13 @@ export interface PreparedModelProfileActivation {
      */
     previousSessionDefaultModel: string | undefined;
 }
+export interface MaterializeModelProfileAssignmentOptions {
+    session: Pick<ModelProfileActivationSession, "model" | "thinkingLevel" | "setActiveModelProfile" | "getActiveModelProfile">;
+    settings: Pick<Settings, "clearOverride" | "get" | "override" | "set">;
+    role: GjcModelAssignmentTargetId;
+    selector: string;
+}
+export declare function materializeActiveModelProfileAssignment(options: MaterializeModelProfileAssignmentOptions): boolean;
 export declare function formatModelProfileCredentialError(profileName: string, providers: readonly string[]): string;
 export declare function prepareModelProfileActivation(options: PrepareModelProfileActivationOptions): Promise<PreparedModelProfileActivation>;
 export declare function applyPreparedModelProfileActivation(prepared: PreparedModelProfileActivation, options?: {

package/dist/types/deep-interview/plaintext-gate-guard.d.ts

@@ -0,0 +1,11 @@
+export type DeepInterviewPlaintextAskLeakOption = "Yes, crystallize" | "Adjust wording" | "Missing scope";
+export type DeepInterviewPlaintextAskLeakResult = {
+    kind: "deep_interview_plaintext_ask_leak";
+    matchedOptions: DeepInterviewPlaintextAskLeakOption[];
+    signals: {
+        optionsHeading: true;
+        restateIntent: true;
+        deepInterviewContext: boolean;
+    };
+};
+export declare function detectDeepInterviewPlaintextAskLeak(text: string): DeepInterviewPlaintextAskLeakResult | null;

package/dist/types/extensibility/gjc-plugins/compiler.d.ts

@@ -0,0 +1,19 @@
+import { type NormalizedGjcPluginBundle } from "./types";
+/**
+ * Stable surface extension-id builders. Kept here so install, runtime, and
+ * observability all derive identical ids.
+ */
+export declare const surfaceIds: {
+    readonly tool: (name: string) => string;
+    readonly hook: (event: string, phase: string | undefined, target: string | undefined, name: string) => string;
+    readonly mcp: (name: string) => string;
+    readonly systemAppendix: (plugin: string, name: string) => string;
+    readonly agentAppendix: (agent: string, plugin: string, name: string) => string;
+    readonly subskill: (parent: string, phase: string, activationArg: string) => string;
+};
+/**
+ * Pure compile step: reads only the manifest, subskill frontmatter, and
+ * declared files (as bytes for hashing/existence). It NEVER imports or executes
+ * plugin tool/hook code.
+ */
+export declare function compileGjcPluginBundle(root: string): Promise<NormalizedGjcPluginBundle>;

package/dist/types/extensibility/gjc-plugins/constrained-hooks.d.ts

@@ -0,0 +1,29 @@
+import { type SessionQuarantine } from "./session-validation";
+/**
+ * Constrained plugin-hook loader.
+ *
+ * Third-party plugin hooks are NOT given the broad first-party HookAPI. They
+ * receive a restricted API that can only register a handler for their declared
+ * event; every session-mutation / command / shell capability throws
+ * security_policy. After the factory runs we verify it registered exactly the
+ * declared event (and nothing else), or the hook is quarantined.
+ */
+export interface ConstrainedPluginHook {
+    plugin: string;
+    event: string;
+    target?: string;
+    phase?: "before" | "after";
+    handler: (...args: any[]) => unknown;
+}
+export interface ConstrainedHookLoadResult {
+    hooks: ConstrainedPluginHook[];
+    quarantine: SessionQuarantine[];
+}
+/**
+ * Load all always-on constrained plugin hooks for the effective registry at
+ * `cwd`, applying hash-drift + collision quarantine first. Returns empty when
+ * no plugins are installed.
+ */
+export declare function loadConstrainedPluginHooks(input: {
+    cwd: string;
+}): Promise<ConstrainedHookLoadResult>;

package/dist/types/extensibility/gjc-plugins/index.d.ts

@@ -1,8 +1,17 @@
 export * from "./activation";
+export * from "./compiler";
+export * from "./constrained-hooks";
 export * from "./injection";
+export * from "./installer";
 export * from "./loader";
+export * from "./mcp-policy";
+export * from "./observability";
 export * from "./paths";
+export * from "./prompt-appendix";
+export * from "./registry";
+export * from "./runtime-adapters";
 export * from "./schema";
+export * from "./session-validation";
 export * from "./state";
 export * from "./tools";
 export * from "./types";

package/dist/types/extensibility/gjc-plugins/injection.d.ts

@@ -29,3 +29,12 @@ export declare function buildAgentSubskillInjection(input: {
     sessionId?: string;
     agentName: string;
 }): Promise<string>;
+import type { GjcPluginRegistryEntry } from "./types";
+/**
+ * Tier-1 advertisement for a workflow parent skill: bounded, metadata-only list
+ * of installed sub-skills bound to `parent`, rendered ONLY in that parent's
+ * prompt (never the global public-workflow-surface). No body content.
+ */
+export declare function buildSubskillAdvertisement(entries: readonly GjcPluginRegistryEntry[], parent: string, phase?: string): string;
+/** Tier-1 advertisement for a role-agent parent. */
+export declare function buildAgentSubskillAdvertisement(entries: readonly GjcPluginRegistryEntry[], agentName: string): string;

package/dist/types/extensibility/gjc-plugins/installer.d.ts

@@ -0,0 +1,13 @@
+import { type GjcPluginRegistryEntry, type GjcPluginScope } from "./types";
+export interface InstallGjcPluginOptions {
+    scope: GjcPluginScope;
+    cwd: string;
+    force?: boolean;
+}
+export interface InstallGjcPluginResult {
+    status: "installed" | "updated" | "unchanged";
+    entry: GjcPluginRegistryEntry;
+}
+export declare function installGjcPluginBundle(source: string, options: InstallGjcPluginOptions): Promise<InstallGjcPluginResult>;
+/** True only when the source actually resolves to a GJC plugin bundle (root gajae-plugin.json). */
+export declare function isGjcPluginBundleSource(source: string): Promise<boolean>;

package/dist/types/extensibility/gjc-plugins/mcp-policy.d.ts

@@ -0,0 +1,26 @@
+import { type GjcPluginMcpManifestEntry } from "./types";
+export declare function isDeniedIpv4(host: string): boolean;
+export declare function isDeniedIpv6(host: string): boolean;
+/**
+ * Synchronous URL policy (scheme, credentials, host literal ranges). Used for
+ * the primary endpoint and any redirect/token/discovery URL.
+ */
+export declare function assertUrlAllowed(rawUrl: string, label?: string): URL;
+/** Reject headers with control characters / CRLF injection. */
+export declare function assertHeadersAllowed(headers: Record<string, string> | undefined): void;
+/**
+ * Runtime DNS check: resolve the host and ensure no resolved address falls in a
+ * denied range (covers DNS rebinding when re-run before each connect).
+ */
+export declare function assertDnsResolvesPublic(hostname: string, label?: string): Promise<void>;
+export interface StdioPolicyContext {
+    pluginRoot: string;
+}
+/** stdio launcher/path confinement policy. */
+export declare function assertStdioAllowed(entry: GjcPluginMcpManifestEntry, ctx: StdioPolicyContext): void;
+/**
+ * Install-time MCP policy (no network required). Validates scheme/host literals
+ * and stdio confinement. Runtime connect additionally calls
+ * assertDnsResolvesPublic and re-validates redirect/token URLs.
+ */
+export declare function assertMcpInstallPolicy(entry: GjcPluginMcpManifestEntry, ctx: StdioPolicyContext): void;

package/dist/types/extensibility/gjc-plugins/observability.d.ts

@@ -0,0 +1,27 @@
+import type { GjcPluginRegistryEntry, GjcPluginScope } from "./types";
+/**
+ * Observability for GJC plugin bundle surfaces, consumable by the extension
+ * dashboard / state manager. Each surface row carries its stable extension id,
+ * owning plugin, scope, source kind, enabled/disabled/quarantined status, and a
+ * content hash. MCP auth/header values are NEVER included.
+ */
+export type PluginSurfaceStatus = "enabled" | "disabled" | "quarantined";
+export interface PluginSurfaceRow {
+    extensionId: string;
+    kind: "tool" | "hook" | "mcp" | "system-appendix" | "agent-appendix" | "subskill";
+    plugin: string;
+    scope: GjcPluginScope;
+    sourceKind: GjcPluginRegistryEntry["source"]["kind"];
+    status: PluginSurfaceStatus;
+    hash: string;
+    quarantineCode?: string;
+}
+export interface PluginObservabilitySummary {
+    plugins: number;
+    surfaces: PluginSurfaceRow[];
+}
+/**
+ * Build the observability summary for the effective registry at `cwd`, including
+ * hash-drift and session-collision quarantine status.
+ */
+export declare function summarizeGjcPluginObservability(cwd: string): Promise<PluginObservabilitySummary>;

package/dist/types/extensibility/gjc-plugins/prompt-appendix.d.ts

@@ -0,0 +1,16 @@
+import type { GjcPluginRegistryEntry, GjcSubskillParentAgent } from "./types";
+export interface RenderedPluginAppendices {
+    /** Combined system-appendix block text (empty if none). */
+    system: string;
+    /** Per-agent appendix block text. */
+    byAgent: Map<GjcSubskillParentAgent, string>;
+    /** Stable digest of all rendered appendix content + identities (for cache/refresh). */
+    digest: string;
+}
+/**
+ * Build appendix blocks from the active, enabled registry entries in their
+ * deterministic order. Per-appendix and total size caps are enforced
+ * fail-closed (oversize content is dropped with a marker, never silently
+ * truncated into the prompt as authoritative text).
+ */
+export declare function renderPluginAppendices(entries: readonly GjcPluginRegistryEntry[]): Promise<RenderedPluginAppendices>;

package/dist/types/extensibility/gjc-plugins/registry.d.ts

@@ -0,0 +1,32 @@
+import { type GjcPluginRegistry, type GjcPluginRegistryEntry, type GjcPluginScope } from "./types";
+export declare function registryRootForScope(scope: GjcPluginScope, cwd: string): string;
+export declare function registryPathForScope(scope: GjcPluginScope, cwd: string): string;
+/**
+ * Deterministic ordering: scope (user before project) -> normalized name ->
+ * resolved plugin root. Collisions are errors elsewhere; order only controls
+ * stable hook/appendix sequencing.
+ */
+export declare function sortRegistryEntries(entries: GjcPluginRegistryEntry[]): GjcPluginRegistryEntry[];
+export declare function readRegistry(scope: GjcPluginScope, cwd: string): Promise<GjcPluginRegistry>;
+export declare function withRegistryLock<T>(scope: GjcPluginScope, cwd: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Lock-free atomic write (temp+fsync+rename). Only call while already holding
+ * the per-scope registry lock via withRegistryLock.
+ */
+export declare function writeRegistryUnlocked(registry: GjcPluginRegistry, cwd: string): Promise<void>;
+/**
+ * Atomic registry write: write to a temp sibling, fsync, then rename. Guarded
+ * by an interprocess lockfile so concurrent installs cannot clobber each other.
+ */
+export declare function writeRegistry(registry: GjcPluginRegistry, cwd: string): Promise<void>;
+/**
+ * Mutate a scope's registry as a single locked read-modify-write transaction so
+ * concurrent installs cannot lose each other's updates. The mutator receives a
+ * sorted copy and returns the next entry list.
+ */
+export declare function updateRegistry(scope: GjcPluginScope, cwd: string, mutator: (entries: GjcPluginRegistryEntry[]) => GjcPluginRegistryEntry[]): Promise<GjcPluginRegistry>;
+/**
+ * Effective registry for a cwd: user + project entries in deterministic order.
+ */
+export declare function loadEffectiveGjcPluginRegistry(cwd: string): Promise<GjcPluginRegistryEntry[]>;
+export declare function registryEntryFingerprint(entry: GjcPluginRegistryEntry): string;

package/dist/types/extensibility/gjc-plugins/runtime-adapters.d.ts

@@ -0,0 +1,64 @@
+import type { CustomTool } from "../custom-tools/types";
+import { type SessionQuarantine } from "./session-validation";
+export interface AlwaysOnPluginTools {
+    tools: CustomTool[];
+    quarantine: SessionQuarantine[];
+}
+/**
+ * Load the always-on plugin tool surfaces for the effective registry at `cwd`.
+ *
+ * Safety properties:
+ * - Hash drift quarantines the plugin (runtime_mismatch) before any import.
+ * - Session-start collisions vs reserved/built-in names quarantine fail-closed.
+ * - Manifest-declared tool names are authoritative: a factory that returns a
+ *   different/extra/missing name is rejected with runtime_mismatch and skipped.
+ * - Reserved tool names are never overwritten.
+ *
+ * Returns an empty result when no plugins are installed, so callers that always
+ * call this in `createAgentSession` incur no behavior change without plugins.
+ */
+export declare function loadAlwaysOnPluginTools(input: {
+    cwd: string;
+    reservedToolNames: string[];
+}): Promise<AlwaysOnPluginTools>;
+/**
+ * Render the always-on system-appendix blocks for the effective registry at
+ * `cwd`, applying hash-drift + collision quarantine first. Returns "" when no
+ * plugins are installed/enabled. Safe to call unconditionally at session start.
+ */
+export declare function renderAlwaysOnSystemAppendices(input: {
+    cwd: string;
+}): Promise<string>;
+/**
+ * Render the agent-appendix block and Tier-1 sub-skill advertisement for a role
+ * agent at session/spawn time. Hash-drift + collision quarantine applied first.
+ * Returns empty strings when nothing applies.
+ */
+export declare function renderAgentPromptAdditions(input: {
+    cwd: string;
+    agentName: string;
+}): Promise<{
+    appendix: string;
+    advertisement: string;
+}>;
+/**
+ * Render the Tier-1 sub-skill advertisement for a workflow parent skill.
+ * Returns "" when nothing applies. Quarantine applied first.
+ */
+export declare function renderSkillAdvertisement(input: {
+    cwd: string;
+    skillName: string;
+    phase?: string;
+}): Promise<string>;
+/**
+ * Convert active plugin-bundle MCP surfaces into runtime MCPServerConfig entries,
+ * applying install + runtime MCP policy (URL scheme/private-range deny, DNS
+ * re-resolution for http/sse, stdio root-confinement) before connection. Servers
+ * failing policy are quarantined and excluded. Returns {} when none.
+ */
+export declare function buildPluginMcpConfigs(input: {
+    cwd: string;
+}): Promise<{
+    configs: Record<string, any>;
+    quarantine: SessionQuarantine[];
+}>;

package/dist/types/extensibility/gjc-plugins/session-validation.d.ts

@@ -0,0 +1,42 @@
+import type { GjcPluginLoadErrorCode, GjcPluginRegistryEntry } from "./types";
+/**
+ * Session-start validation: the registry is the collision authority. Capability
+ * provider output is supplied as EVIDENCE only; plugin surfaces are never
+ * resolved by capability first-wins. Offending surfaces are quarantined
+ * fail-closed with a stable error code rather than silently shadowed.
+ */
+export interface SessionCapabilityEvidence {
+    /** Built-in + provider tool names already present before plugin insertion. */
+    toolNames?: Iterable<string>;
+    /** Non-plugin MCP server names from providers/built-ins. */
+    mcpNames?: Iterable<string>;
+    /** Non-plugin hook keys (event:phase:target:name) from providers/built-ins. */
+    hookKeys?: Iterable<string>;
+    /** Existing appendix extension ids already present. */
+    appendixIds?: Iterable<string>;
+}
+export interface SessionQuarantine {
+    plugin: string;
+    surfaceId: string;
+    code: GjcPluginLoadErrorCode;
+    message: string;
+}
+export interface SessionValidationResult {
+    /** Registry entries (enabled, non-quarantined) whose surfaces may activate. */
+    active: GjcPluginRegistryEntry[];
+    /** Per-surface quarantine records (fail-closed). */
+    quarantine: SessionQuarantine[];
+}
+/**
+ * Re-verify that the installed files still match the registry's recorded hashes.
+ * Drift (manual edits, partial writes) quarantines the whole plugin with
+ * runtime_mismatch.
+ */
+export declare function verifyEntryHashes(entry: GjcPluginRegistryEntry): Promise<SessionQuarantine | null>;
+/**
+ * Validate the effective installed registry against the current capability
+ * universe (evidence) and across plugins. Returns the entries that may activate
+ * plus per-surface quarantine records. Disabled entries/surfaces are skipped
+ * (not an error).
+ */
+export declare function validateSessionBundles(entries: readonly GjcPluginRegistryEntry[], evidence?: SessionCapabilityEvidence, preQuarantined?: readonly SessionQuarantine[]): SessionValidationResult;