@gajae-code/coding-agent 0.13.3 → 0.14.0

package/dist/types/gjc-runtime/session-state-sidecar.d.ts

@@ -19,6 +19,8 @@ export type RuntimeInputReadyMarker = Readonly<{
     created_at: string;
 }>;
 export type RuntimeState = "ready_for_input" | "running" | "needs_user_input" | "completed" | "errored";
+/** Recorded whenever the caller could not prove a canonical public label for a tool. */
+export declare const UNPROVEN_TOOL_LABEL = "custom";
 /** Test-only counters for runtime sidecar hot-path assertions. */
 export declare const __sessionStateSidecarPerfCounters: {
     persistFromEventCalls: number;
@@ -28,9 +30,117 @@ interface RuntimeStateEvent {
     type: string;
     messages?: unknown[];
     toolCallId?: unknown;
-    toolName?: unknown;
     isError?: unknown;
 }
+export type RuntimeToolActivityPhase = "started" | "finished";
+/**
+ * A finished call's outcome. `cancelled` is the only honest answer for a call that was
+ * still in flight when the session settled: it neither succeeded nor failed, and nothing
+ * observed its end.
+ */
+export type RuntimeToolActivityOutcome = "success" | "failure" | "cancelled";
+/**
+ * What a session is doing right now, split into a bounded public projection and the
+ * minimum private state needed to keep that projection exact.
+ *
+ * Deliberately carries no tool arguments, results, command text, paths, output, prompt or
+ * model text, environment values, or credentials — only a proven public tool label, a
+ * phase, and timing.
+ */
+export interface RuntimeToolActivity {
+    seq: number;
+    last_activity_at: string;
+    tool: string;
+    phase: RuntimeToolActivityPhase;
+    outcome: RuntimeToolActivityOutcome | null;
+    elapsed_ms: number | null;
+    /** Exact number of in-flight calls; derived with `active_tools`, so it can never be smaller. */
+    active_tool_count: number;
+    /** Public projection of the newest in-flight calls, capped at `MAX_ACTIVE_TOOL_ENTRIES`. */
+    active_tools: Array<{
+        tool: string;
+        started_at: string;
+    }>;
+    /**
+     * Private exact correlation state. Each digest is one-way over the session id and the
+     * tool call id, so no raw call id is persisted, and the whole field is stripped by
+     * `publicRuntimeToolActivity` before any coordinator reader sees the snapshot.
+     */
+    in_flight: Array<{
+        digest: string;
+        tool: string;
+        started_at: string;
+    }>;
+}
+/**
+ * Collapses anything the caller could not prove into `custom`.
+ *
+ * Public safety comes from the caller's proof plus this closed vocabulary, never from a
+ * syntax check: a label that merely looks like a token is still model-influenced text.
+ */
+export declare function safeRuntimeToolLabel(value: unknown): string;
+export declare function toolActivityPhaseForEvent(event: RuntimeStateEvent): RuntimeToolActivityPhase | null;
+export type RuntimeToolActivityReadout = {
+    kind: "absent";
+} | {
+    kind: "malformed";
+} | {
+    kind: "valid";
+    activity: RuntimeToolActivity;
+};
+/**
+ * Re-validates an activity snapshot read back from disk.
+ *
+ * `absent` and `malformed` are deliberately distinct outcomes: an absent snapshot may be
+ * seeded from sequence 1, while a malformed one must never be replaced by a lower
+ * sequence. The public counters are re-derived from the private in-flight table rather
+ * than trusted from disk, so a hand-edited file cannot publish a contradiction.
+ */
+export declare function classifyRuntimeToolActivity(value: unknown): RuntimeToolActivityReadout;
+export declare function normalizedRuntimeToolActivity(value: unknown): RuntimeToolActivity | null;
+/**
+ * The only activity shape a coordinator reader may see: the private correlation digests
+ * are dropped here, so no projection can leak them, and a snapshot that contradicts the
+ * lifecycle state it accompanies is withheld entirely.
+ *
+ * Withheld, never repaired: the bytes on disk are preserved exactly as written — a
+ * malformed or contradictory snapshot is evidence — while every public projection shows
+ * nothing rather than a reconciled guess.
+ */
+export declare function publicRuntimeToolActivity(value: unknown, lifecycleState: unknown): Record<string, unknown> | null;
+/**
+ * What the caller observed at the exact moment the agent event was dispatched.
+ *
+ * Both the timestamp and the label are captured at that synchronous boundary, never
+ * re-derived here: a later lookup would see a tool registry that may already have been
+ * replaced, and a later clock reading would fold subscriber and lock latency into the
+ * measured interval.
+ */
+export interface CoordinatorToolObservation {
+    /** Canonical public label proven at the observation boundary; anything else is `custom`. */
+    label: string;
+    /** Wall clock captured when the agent event was observed, before any queueing or lock wait. */
+    observedAt: string;
+}
+/**
+ * Settle the activity snapshot a terminal lifecycle transition inherits.
+ *
+ * A settled session cannot still be running a tool, and later tool events are fenced out,
+ * so an unmatched start would otherwise leave a nonzero `active_tool_count` forever. The
+ * orphans are represented honestly — finished, `cancelled`, no elapsed interval — rather
+ * than claimed as a success or a failure nothing observed.
+ *
+ * The same helper serves the runtime `agent_end`/postmortem path and the Coordinator's
+ * canonical terminal repair so the two writers cannot settle differently.
+ *
+ * Two shapes need settling, not one. An orphaned in-flight call is the obvious case. The
+ * other is a `phase: started` snapshot with NOTHING correlated — a start whose call id was
+ * missing or blank never entered the in-flight table, so no end can ever close it — and
+ * leaving it would write the prohibited terminal+started pair, a settled session that
+ * still claims a tool is starting. An already-finished snapshot with nothing in flight is
+ * returned unchanged: a normal terminal transition is not an activity event.
+ */
+export declare function terminallySettledRuntimeToolActivity(value: unknown, observedAt: string): RuntimeToolActivityReadout;
 export interface OwnerTerminalContext {
     generation: string;
     stateDir: string;
@@ -68,8 +178,16 @@ export declare function readTerminalRuntimeStateMarker(input: {
     platform?: NodeJS.Platform;
 }): Promise<TerminalRuntimeStateStatus>;
 export declare function stateForEvent(event: RuntimeStateEvent): RuntimeState | null;
+/** True for every event the coordinator-shared file records: lifecycle state or tool activity. */
 export declare function eventAffectsCoordinatorRuntimeState(event: RuntimeStateEvent): boolean;
-export declare function persistCoordinatorRuntimeStateFromEvent(event: RuntimeStateEvent, context: RuntimeStateContext): Promise<void>;
+export declare function persistCoordinatorRuntimeStateFromEvent(event: RuntimeStateEvent, context: RuntimeStateContext, 
+/**
+ * What the caller observed at the synchronous agent-event boundary: the canonical
+ * public label it proved against the ACTIVE tool object, and the wall clock it read
+ * there. Without one, a tool event records `custom` at this writer's own clock — the
+ * sidecar never trusts a model-supplied name.
+ */
+observation?: CoordinatorToolObservation): Promise<void>;
 export declare function ownerTerminalContextFromEnvironment(): OwnerTerminalContext | "invalid" | null;
 export declare function persistCoordinatorRuntimeStateFromPostmortem(reason: postmortem.Reason, context: RuntimeStateContext): Promise<void>;
 export declare function registerCoordinatorRuntimeStateFinalizer(context: RuntimeStateContext): () => void;

package/dist/types/gjc-runtime/state-writer.d.ts

@@ -74,11 +74,19 @@ export type GuardedWriteResult = {
     reason: "stale-skip";
     revision: number;
 };
+export interface GuardedStateWriteReceipt {
+    path: string;
+    revision: number;
+    stamped: unknown;
+}
+export declare function guardedStateWriteReceipt(result: GuardedWriteResult): GuardedStateWriteReceipt | undefined;
 export interface StateWriterOptions {
     cwd?: string;
     receipt?: StateWriterReceiptContext;
     audit?: StateWriterAuditContext;
     sourceRevision?: number;
+    /** Advance a cache source revision under the target lock when the value carries none. */
+    advanceSourceRevision?: boolean;
     /**
      * Cross-process lock tuning for read-modify-write paths that route through
      * `withWorkflowStateLock` / `updateJsonAtomic`. Omit for the hardened
@@ -150,6 +158,7 @@ export declare function detectWorkflowEnvelopeIntegrityMismatch(filePath: string
 type ActiveStateCacheInvalidator = (cwd?: string, sessionId?: string) => void;
 export declare function setActiveStateCacheInvalidator(invalidator: ActiveStateCacheInvalidator): void;
 export declare function persistedStateRevision(value: unknown): number;
+export declare function matchesGuardedStateWriteReceipt(current: unknown, receipt: GuardedStateWriteReceipt): boolean;
 export declare function writeGuardedJsonAtomic(targetPath: string, value: unknown, options: GuardedStateWriterOptions): Promise<GuardedWriteResult>;
 export declare function writeGuardedWorkflowEnvelopeAtomic(targetPath: string, value: unknown, options: GuardedStateWriterOptions): Promise<GuardedWriteResult>;
 export declare function writeJsonAtomic(targetPath: string, value: unknown, options?: StateWriterOptions): Promise<string>;
@@ -222,7 +231,7 @@ export declare function removeFileAudited(targetPath: string, options?: StateWri
  * those entries, so concurrent snapshot rebuilds can race without losing any
  * writer's per-skill state.
  */
-export declare function writeActiveEntry(cwd: string, sessionScope: string | ActiveSessionScope | undefined, skill: string, entry: SkillActiveEntry, options?: StateWriterOptions): Promise<string>;
+export declare function writeActiveEntry(cwd: string, sessionScope: string | ActiveSessionScope | undefined, skill: string, entry: SkillActiveEntry, options?: StateWriterOptions): Promise<GuardedWriteResult>;
 export declare function removeActiveEntry(cwd: string, sessionScope: string | ActiveSessionScope | undefined, skill: string, options?: StateWriterOptions): Promise<DeleteResult>;
 export declare function readActiveEntries(cwd: string, sessionScope?: string | ActiveSessionScope): Promise<SkillActiveEntry[]>;
 export declare function rebuildActiveSnapshot(cwd: string, sessionScope?: string | ActiveSessionScope, options?: StateWriterOptions): Promise<string>;

package/dist/types/gjc-runtime/ultragoal-guard.d.ts

@@ -61,7 +61,7 @@ export declare function formatUltragoalNudgeMessage(input: {
  * Resolves the active (leader) Ultragoal session so subagent/headless asks consume
  * the leader run's budget rather than a fresh child ledger.
  */
-export declare function consumeUltragoalAskNudge(cwd: string, sessionId?: string | null): Promise<{
+export declare function consumeUltragoalAskNudge(cwd: string, sessionId?: string | null, agentDir?: string): Promise<{
     nudged: true;
     message: string;
 } | {
@@ -71,6 +71,7 @@ export declare function assertCanCompleteCurrentGoal(input: {
     cwd: string;
     currentGoal?: CurrentGoalLike | null;
     sessionId?: string | null;
+    agentDir?: string;
 }): Promise<void>;
 export declare function isUltragoalBypassPrompt(prompt: string): boolean;
 export interface UltragoalPauseBlockDiagnostic {
@@ -85,7 +86,7 @@ export interface UltragoalPauseBlockDiagnostic {
  * ledger data blocks pause rather than silently allowing a give-up.
  */
 export declare function isUltragoalPauseBlocked(cwd: string): Promise<UltragoalPauseBlockDiagnostic>;
-export declare function assertUltragoalPauseAllowed(cwd: string): Promise<void>;
+export declare function assertUltragoalPauseAllowed(cwd: string, agentDir?: string): Promise<void>;
 /**
  * Guard `goal({"op":"drop"})` during an active Ultragoal run. A *real give-up* (an
  * aggregate run still mid-flight with incomplete required stories) is nudged while
@@ -98,4 +99,5 @@ export declare function assertUltragoalDropAllowed(input: {
     cwd: string;
     currentGoal?: CurrentGoalLike | null;
     sessionId?: string | null;
+    agentDir?: string;
 }): Promise<void>;

package/dist/types/gjc-runtime/ultragoal-runtime.d.ts

@@ -170,11 +170,11 @@ export declare const DEFAULT_ULTRAGOAL_NUDGE_BUDGET = 10;
 /** Pure: count ledger `nudge` rows for an exact goalId. */
 export declare function countUltragoalNudges(ledger: readonly UltragoalLedgerEvent[], goalId: string): number;
 /**
- * Resolve the per-story nudge budget. Project `./.gjc/settings.json` overrides the
- * user settings (`$GJC_CONFIG_DIR/settings.json` or `~/.gjc/settings.json`), else the
- * default. Mirrors the `gjc.deepInterview.ambiguityThreshold` user+project precedence.
+ * Resolve the per-story nudge budget through the shared five-layer resolver.
+ * Ultragoal stays tolerant: an invalid optional settings file continues to the
+ * next layer and finally to the built-in default (10).
  */
-export declare function resolveUltragoalNudgeBudget(cwd: string): Promise<{
+export declare function resolveUltragoalNudgeBudget(cwd: string, agentDir?: string): Promise<{
     budget: number;
     source: string;
 }>;
@@ -210,7 +210,7 @@ export declare function writePlan(cwd: string, plan: UltragoalPlan, sessionId?:
 export declare function nonEmptyString(value: unknown): string | null;
 export declare function stringArray(value: unknown): string[] | null;
 export declare function readUltragoalPlan(cwd: string, sessionId?: string | null): Promise<UltragoalPlan | null>;
-export declare function getUltragoalStatus(cwd: string, sessionId?: string | null): Promise<UltragoalStatusSummary>;
+export declare function getUltragoalStatus(cwd: string, sessionId?: string | null, agentDir?: string): Promise<UltragoalStatusSummary>;
 export declare function buildUltragoalHudSummary(summary: UltragoalStatusSummary, latestLedger?: UltragoalLedgerEvent): WorkflowHudSummary;
 export declare function createUltragoalPlan(input: {
     cwd: string;
@@ -442,4 +442,6 @@ export declare class UltragoalReviewBlockerRecursionCapError extends Error {
     constructor(blockedGoalId: string, unresolvedDescents: number, cap?: number);
 }
 export declare function runUltragoalReview(cwd: string, args: readonly string[]): Promise<UltragoalReviewResult>;
-export declare function runNativeUltragoalCommand(args: string[], cwd?: string): Promise<UltragoalCommandResult>;
+export declare function runNativeUltragoalCommand(args: string[], cwd?: string, options?: {
+    agentDir?: string;
+}): Promise<UltragoalCommandResult>;

package/dist/types/gjc-runtime/workflow-settings.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Single source of precedence for the workflow settings surfaces.
+ *
+ * Every workflow runtime (ralplan, ultragoal, deep-interview) reads its
+ * settings through {@link resolveWorkflowSetting}; no runtime hand-rolls file
+ * discovery, YAML/JSON parsing, or key extraction. The precedence is fixed:
+ *
+ *   1. project `.gjc/config.yml`
+ *   2. user `<agentDir>/config.yml` (default `~/.gjc/agent/config.yml`)
+ *   3. built-in default
+ *
+ * Project configuration always beats user configuration, and `config.yml` is
+ * the primary settings surface: the legacy `settings.json` files (project and
+ * config-root) are retired, their workflow values migrated into `config.yml` by
+ * Settings once. The retained legacy source still applies while the migration
+ * has NOT durably recorded ownership/completion for its key: the project source
+ * until the per-key migrated-keys marker records the key, the config-root
+ * source until the migration retires it. A completed migration owns the value
+ * (a later `gjc config unset` sticks), so an owned key is never resurrected;
+ * the project legacy sits above the agent config.yml, the config-root legacy
+ * below it. Settings therefore writes exactly what the runtimes read: `gjc
+ * config set gjc.ralplan.maxIterations 7` is honored by ralplan.
+ *
+ * `config.yml` uses the nested schema form (`gjc: { ralplan: { maxIterations } }`);
+ * flat dotted keys are honored only while parsing a legacy `settings.json`
+ * during migration (see Settings) or the retained-legacy fallback layer.
+ *
+ * This module must stay pure and acyclic: it imports only path helpers and the
+ * pure `gjcRoot`/`dirs` utilities, never `Settings`, discovery/capability
+ * loaders, or workflow runtimes. All config/agent paths are constructed inside
+ * each resolver call (never at module scope) because `dirs.ts` caches directory
+ * resolution at module load.
+ */
+export type WorkflowSettingKey = "gjc.deepInterview.ambiguityThreshold" | "gjc.ralplan.autoHandoff" | "gjc.ralplan.maxIterations" | "gjc.ralplan.maxReviewPassesPerLane" | "gjc.ultragoal.nudgeBudget";
+export type WorkflowSettingLayer = "project-config" | "agent-config";
+export type WorkflowSettingParseResult<T> = {
+    kind: "valid";
+    value: T;
+} | {
+    kind: "invalid";
+    reason: string;
+};
+export type WorkflowSettingDiagnosticStatus = "missing-file" | "empty-document" | "missing-key" | "invalid" | "valid";
+export interface WorkflowSettingDiagnostic {
+    layer: WorkflowSettingLayer;
+    /** Lexical absolute candidate; missing paths stay actionable. */
+    path: string;
+    format: "yaml" | "json";
+    status: WorkflowSettingDiagnosticStatus;
+    classification?: "read" | "syntax" | "shape" | "value";
+    reason?: string;
+}
+export interface ResolveWorkflowSettingOptions<T> {
+    defaultValue: T;
+    parse: (value: unknown) => WorkflowSettingParseResult<T>;
+    /** Omitted means "continue"; ralplan passes "throw" explicitly. */
+    invalidPolicy?: "throw" | "continue";
+    /**
+     * The session's effective agent directory. Defaults to the process-global
+     * `getAgentDir()`; an SDK embedder that created the session with
+     * `createAgentSession({ agentDir })` must pass that directory here so the
+     * agent-config layer matches the profile `Settings.init` loaded and
+     * migrated, instead of inheriting an unrelated default-profile value.
+     */
+    agentDir?: string;
+}
+export interface WorkflowSettingResolution<T> {
+    value: T;
+    /** Canonical realpath for a winning existing file, or "default". */
+    source: string;
+    diagnostics: readonly WorkflowSettingDiagnostic[];
+}
+export type WorkflowSettingInvalidClassification = "read" | "syntax" | "shape" | "value";
+/** Raised under the strict ("throw") invalid policy; stable properties for callers. */
+export declare class WorkflowSettingError extends Error {
+    readonly diagnostic: WorkflowSettingDiagnostic;
+    readonly path: string;
+    readonly layer: WorkflowSettingLayer;
+    readonly classification: WorkflowSettingInvalidClassification;
+    readonly reason: string;
+    constructor(diagnostic: WorkflowSettingDiagnostic & {
+        classification: WorkflowSettingInvalidClassification;
+        reason: string;
+    });
+}
+/**
+ * Extract a workflow key from a parsed settings document. Flat dotted keys are
+ * honored only while parsing a legacy `settings.json` during migration (see
+ * Settings) - `config.yml` uses the nested (schema) form, so the public
+ * Settings/config CLI path (which addresses nested paths) can manage every
+ * effective override. Flat keys are checked before the nested `gjc: { ... }`
+ * shape (flat wins); an explicitly present `undefined` value counts as present.
+ */
+export declare function extractWorkflowSetting(document: unknown, key: WorkflowSettingKey, options?: {
+    flat?: boolean;
+}): {
+    present: boolean;
+    value: unknown;
+    malformedParent?: boolean;
+};
+/**
+ * Resolve a workflow setting across the fixed three-layer precedence (project
+ * `.gjc/config.yml`, then user `<agentDir>/config.yml`, then the built-in
+ * default). Returns the first valid configured value, otherwise
+ * {@link options.defaultValue} with `source: "default"`. Diagnostics are
+ * retained for unit tests and optional logging; runtime public wrappers expose
+ * their existing compact result shapes.
+ */
+export declare function resolveWorkflowSetting<T>(cwd: string, key: WorkflowSettingKey, options: ResolveWorkflowSettingOptions<T>): Promise<WorkflowSettingResolution<T>>;

package/dist/types/hooks/events.d.ts

@@ -0,0 +1,60 @@
+/** Stable canonical names used to compare hook surfaces without replacing runtime event types. */
+export declare const HookEventKind: {
+    readonly UserPromptSubmit: "user_prompt_submit";
+    readonly PreToolUse: "pre_tool_use";
+    readonly PostToolUse: "post_tool_use";
+    readonly Stop: "stop";
+    readonly SessionStart: "session_start";
+    readonly SessionShutdown: "session_shutdown";
+};
+export type HookEventKind = (typeof HookEventKind)[keyof typeof HookEventKind];
+export declare const HookAuthority: {
+    readonly Constrained: "constrained";
+    readonly Command: "command";
+    readonly InProcess: "in-process";
+};
+export type HookAuthority = (typeof HookAuthority)[keyof typeof HookAuthority];
+export declare const HookSourceConvention: {
+    readonly NativeGjc: "native-gjc";
+    readonly ClaudeCode: "claude-code";
+    readonly Codex: "codex";
+    readonly CodexManagedJson: "codex-managed-json";
+    readonly GjcPlugin: "gjc-plugin";
+    readonly InProcess: "in-process";
+};
+export type HookSourceConvention = (typeof HookSourceConvention)[keyof typeof HookSourceConvention];
+export interface HookEventSchemaContract {
+    kind: HookEventKind;
+    input: string;
+    output: string;
+}
+/**
+ * Canonical schema references. These point at existing runtime types; they are not a
+ * second runtime event union and do not change payloads dispatched by the hook runners.
+ */
+export declare const HOOK_EVENT_SCHEMAS: Record<HookEventKind, HookEventSchemaContract>;
+export type HookOrdering = "sequential" | "external-runtime";
+export type HookAwaitBehavior = "awaited" | "external-runtime";
+export type HookErrorBehavior = "isolate" | "fail-closed" | "external-runtime";
+export type HookProcessAuthority = "none" | "hook-api" | "command" | "ambient-host";
+export type HookTrustRequirement = "not-enforced" | "provider-owned";
+export type HookRedaction = "none" | "provider-owned";
+export interface HookExecutionContract {
+    kind: HookEventKind;
+    runtimeEvent: string;
+    authority: HookAuthority;
+    awaitBehavior: HookAwaitBehavior;
+    ordering: HookOrdering;
+    canCancel: boolean;
+    mutation: readonly string[];
+    timeoutMs: number | null;
+    errorBehavior: HookErrorBehavior;
+    processAuthority: HookProcessAuthority;
+    trustRequirement: HookTrustRequirement;
+    redaction: HookRedaction;
+    logging: string;
+    semanticNotes: string;
+}
+/** Per-convention execution truth. Missing entries are unsupported. */
+export declare const CONVENTION_EVENT_CONTRACTS: Record<HookSourceConvention, Partial<Record<HookEventKind, HookExecutionContract>>>;
+export declare const EXTERNAL_EVENT_ALIASES: Readonly<Record<string, HookEventKind>>;

package/dist/types/hooks/normalize.d.ts

@@ -0,0 +1,83 @@
+import { type HookAuthority, HookEventKind, type HookExecutionContract, HookSourceConvention } from "./events";
+export declare const HookDiagnosticSeverity: {
+    readonly Error: "error";
+    readonly Warning: "warning";
+};
+export type HookDiagnosticSeverity = (typeof HookDiagnosticSeverity)[keyof typeof HookDiagnosticSeverity];
+export declare const HookDiagnosticCode: {
+    readonly UnsupportedConventionEvent: "unsupported_convention_event";
+    readonly UnrecognizedPluginEvent: "unrecognized_plugin_event";
+    readonly InvalidPluginPhase: "invalid_plugin_phase";
+    readonly InvalidToolMatcher: "invalid_tool_matcher";
+    readonly InvalidSource: "invalid_source";
+    readonly InvalidCommand: "invalid_command";
+    readonly DuplicateHook: "duplicate_hook";
+    readonly InProcessEventOutsideIr: "in_process_event_outside_hook_ir";
+    readonly SemanticMismatch: "semantic_mismatch";
+};
+export type HookDiagnosticCode = (typeof HookDiagnosticCode)[keyof typeof HookDiagnosticCode];
+export interface HookNormalizationDiagnostic {
+    severity: HookDiagnosticSeverity;
+    code: HookDiagnosticCode;
+    message: string;
+    convention: HookSourceConvention;
+    externalEvent?: string;
+    canonicalKind?: HookEventKind;
+    source?: string;
+}
+export interface NormalizedHook {
+    kind: HookEventKind;
+    authority: HookAuthority;
+    convention: HookSourceConvention;
+    runtimeEvent: string;
+    toolName: string;
+    source: string;
+    contract: HookExecutionContract;
+}
+export interface NormalizeHookResult {
+    hook: NormalizedHook | null;
+    diagnostics: HookNormalizationDiagnostic[];
+}
+export declare function resolveExecutionContract(convention: HookSourceConvention, kind: HookEventKind): HookExecutionContract | null;
+export declare function resolveAuthority(convention: HookSourceConvention, kind: HookEventKind): HookAuthority | null;
+export declare function resolveCanonicalKind(externalEvent: string): HookEventKind | null;
+export declare function unsupportedEventDiagnostic(convention: HookSourceConvention, externalEvent: string, canonicalKind: HookEventKind | null, source?: string): HookNormalizationDiagnostic;
+/** Tool identifiers are logical, case-sensitive runtime names, not filesystem paths. */
+export declare function normalizeToolMatcher(toolName: unknown): string | null;
+export interface DirectoryHookInput {
+    convention: HookSourceConvention;
+    phase: "pre" | "post";
+    toolName: string;
+    source: string;
+    /** Original discovered filename, when normalization participates in discovery. */
+    externalName?: string;
+}
+/** Normalize discovery metadata for native, Claude, or Codex hook modules. */
+export declare function normalizeDirectoryHook(input: DirectoryHookInput): NormalizeHookResult;
+export interface ManagedJsonHookInput {
+    externalEvent: string;
+    command: string;
+    source: string;
+}
+/** Normalize the two GJC-managed Codex hooks.json entries. */
+export declare function normalizeManagedJsonHook(input: ManagedJsonHookInput): NormalizeHookResult;
+export interface PluginHookInput {
+    declaredEvent: string;
+    target?: unknown;
+    phase?: unknown;
+    plugin: string;
+    source: string;
+}
+/** Normalize only manifest shapes that the constrained plugin compiler accepts. */
+export declare function normalizePluginHook(input: PluginHookInput): NormalizeHookResult;
+export interface InProcessHookInput {
+    registeredEvent: string;
+    source: string;
+}
+export declare function normalizeInProcessHook(input: InProcessHookInput): NormalizeHookResult;
+export interface BatchNormalizeResult {
+    hooks: NormalizedHook[];
+    diagnostics: HookNormalizationDiagnostic[];
+}
+/** Stable first-wins deduplication; rejected and duplicate entries remain visible as diagnostics. */
+export declare function normalizeHookBatch(results: ReadonlyArray<NormalizeHookResult>): BatchNormalizeResult;

package/dist/types/hooks/skill-state.d.ts

@@ -1,5 +1,5 @@
-import type { SkillDiscoverySettings } from "../config/skill-settings-defaults";
-import { type SkillActiveState } from "../skill-state/active-state";
+import { type SkillDiscoverySettings } from "../config/skill-settings-defaults";
+import { type SkillActiveEntry, type SkillActiveState } from "../skill-state/active-state";
 import { initialPhaseForSkill } from "../skill-state/initial-phase";
 export { initialPhaseForSkill };
 import { type GjcWorkflowSkill } from "./skill-keywords";
@@ -75,6 +75,12 @@ export interface EnsureWorkflowSkillActivationInput {
     turnId?: string;
     nowIso?: string;
     stateDir?: string;
+    activeSubskills?: SkillActiveEntry["active_subskills"];
+}
+export interface WorkflowSkillActivationSeed {
+    state: SkillActiveState | null;
+    seeded: boolean;
+    rollback(): Promise<boolean>;
 }
 /**
  * Idempotently seed `.gjc/state` for a workflow skill that was invoked directly
@@ -87,6 +93,7 @@ export interface EnsureWorkflowSkillActivationInput {
  * `handoff_from`/`handoff_at` lineage), nothing is written so lineage is
  * preserved. Non-workflow skills are ignored.
  */
+export declare function ensureWorkflowSkillActivationSeed(input: EnsureWorkflowSkillActivationInput): Promise<WorkflowSkillActivationSeed>;
 export declare function ensureWorkflowSkillActivationState(input: EnsureWorkflowSkillActivationInput): Promise<SkillActiveState | null>;
 export declare function buildActiveUltragoalPromptContext(input: UserPromptSubmitStateInput): Promise<string | null>;
 export declare function buildSkillStopOutput(input: StopHookInput): Promise<Record<string, unknown> | null>;

package/dist/types/main.d.ts

@@ -41,7 +41,7 @@ export declare function initializeInteractiveModeWithStartupUpdate(mode: Startup
  * Every other local-session flag is rejected so the broker-backed ACP host
  * never appears to accept options it cannot apply to its remote session.
  */
-export declare function resolveAcpStartupOptions(parsed: Pick<Args, "allowHome" | "apiKey" | "appendSystemPrompt" | "credential" | "continue" | "default" | "cwd" | "fileArgs" | "fork" | "hooks" | "messages" | "mpreset" | "mcpConfig" | "model" | "models" | "noLsp" | "noPty" | "noRules" | "noSession" | "noSkills" | "noTitle" | "noTools" | "pluginDirs" | "print" | "provider" | "providerSessionId" | "resume" | "sessionDir" | "skills" | "slow" | "smol" | "plan" | "systemPrompt" | "thinking" | "tmux" | "tools" | "extensions" | "unknownFlags">, sessionOptions: Pick<CreateAgentSessionOptions, "model" | "modelPattern" | "thinkingLevel">): AcpStartupOptions;
+export declare function resolveAcpStartupOptions(parsed: Pick<Args, "allowHome" | "apiKey" | "appendSystemPrompt" | "credential" | "preferCredential" | "continue" | "default" | "cwd" | "fileArgs" | "fork" | "hooks" | "messages" | "mpreset" | "mcpConfig" | "model" | "models" | "noLsp" | "noMcp" | "noPty" | "noRules" | "noSession" | "noSkills" | "noTitle" | "noTools" | "pluginDirs" | "print" | "provider" | "providerSessionId" | "resume" | "sessionDir" | "skills" | "slow" | "smol" | "plan" | "systemPrompt" | "thinking" | "tmux" | "tools" | "extensions" | "unknownFlags">, sessionOptions: Pick<CreateAgentSessionOptions, "model" | "modelPattern" | "thinkingLevel">): AcpStartupOptions;
 declare function readPipedInput(): Promise<string | undefined>;
 export interface InteractiveModeNotify {
     kind: "warn" | "error" | "info";

package/dist/types/modes/acp/abort-scope.d.ts

@@ -0,0 +1,13 @@
+import type { AbortScope } from "../../sdk/host/control/operations";
+/**
+ * Resolves the C04 terminal-abort scope for an ACP `session/cancel`. Client
+ * metadata is authoritative; the process environment is only a fallback when
+ * that field is absent. Both default to `"turn"` so an external client that
+ * ends a turn only stops that turn, matching the SDK `turn.abort` default and
+ * other ACP clients' cancel behavior; a client that also wants exact owned
+ * subagents and background tasks stopped opts in per request with
+ * `_meta.gjc.abortScope: "owned"` (or process-wide with
+ * `GJC_ACP_ABORT_SCOPE=owned`). Paseo keeps owned cancels through its provider
+ * config `env: { "GJC_ACP_ABORT_SCOPE": "owned" }` without source changes.
+ */
+export declare function resolveAcpAbortScope(meta: unknown, env?: NodeJS.ProcessEnv): AbortScope;

package/dist/types/modes/acp/acp-agent.d.ts

@@ -1,4 +1,4 @@
-import { type Agent, type AgentSideConnection, type AuthenticateRequest, type AuthenticateResponse, type AvailableCommand, type ClientCapabilities, type CloseSessionRequest, type CloseSessionResponse, type DeleteSessionRequest, type DeleteSessionResponse, type ForkSessionRequest, type ForkSessionResponse, type InitializeRequest, type InitializeResponse, type ListSessionsRequest, type ListSessionsResponse, type LoadSessionRequest, type LoadSessionResponse, type NewSessionRequest, type NewSessionResponse, type PromptRequest, type PromptResponse, type ResumeSessionRequest, type ResumeSessionResponse, type SetSessionConfigOptionRequest, type SetSessionConfigOptionResponse, type SetSessionModeRequest, type SetSessionModeResponse } from "@agentclientprotocol/sdk";
+import { type Agent, type AgentSideConnection, type AuthenticateRequest, type AuthenticateResponse, type AvailableCommand, type CancelNotification, type ClientCapabilities, type CloseSessionRequest, type CloseSessionResponse, type DeleteSessionRequest, type DeleteSessionResponse, type ForkSessionRequest, type ForkSessionResponse, type InitializeRequest, type InitializeResponse, type ListSessionsRequest, type ListSessionsResponse, type LoadSessionRequest, type LoadSessionResponse, type NewSessionRequest, type NewSessionResponse, type PromptRequest, type PromptResponse, type ResumeSessionRequest, type ResumeSessionResponse, type SetSessionConfigOptionRequest, type SetSessionConfigOptionResponse, type SetSessionModeRequest, type SetSessionModeResponse } from "@agentclientprotocol/sdk";
 import { type AcpProviderRegistration, type AcpReverseConnection, AcpSdkAdapter } from "../../sdk/acp";
 import { type PromptWatchdogClock } from "../../sdk/prompt-watchdog";
 import type { AcpStartupOptions } from "./startup-options";
@@ -240,6 +240,11 @@ export declare function acpSessionStateFromConfig(query: unknown, modelCatalogQu
         currentModeId: string;
     };
 };
+/** Recognize a canonical ACP skill command only when it is the complete, single text prompt. */
+export declare function acpSkillInvocation(blocks: PromptRequest["prompt"]): {
+    name: string;
+    args: string;
+} | undefined;
 /** Convert every ACP prompt block the agent advertises without silently discarding context. */
 export declare function acpPromptPayload(blocks: PromptRequest["prompt"]): {
     text: string;
@@ -295,9 +300,7 @@ export declare class AcpAgent implements Agent {
     setSessionMode(params: SetSessionModeRequest): Promise<SetSessionModeResponse>;
     setSessionConfigOption(params: SetSessionConfigOptionRequest): Promise<SetSessionConfigOptionResponse>;
     prompt(params: PromptRequest): Promise<PromptResponse>;
-    cancel(params: {
-        sessionId: string;
-    }): Promise<void>;
+    cancel(params: CancelNotification): Promise<void>;
     extMethod(method: string, params: JsonObject): Promise<JsonObject>;
     extNotification(_method: string, _params: JsonObject): Promise<void>;
     get signal(): AbortSignal;

package/dist/types/modes/components/customization/customization-dashboard.d.ts

@@ -0,0 +1,44 @@
+/**
+ * CustomizationDashboard — the umbrella local-customization home opened by the
+ * `/extensions` slash command (issue #4291).
+ *
+ * This is a standalone state model and component tree around local
+ * Skills/Hooks/MCPs/Import. It is intentionally NOT built on the
+ * provider/extension-module ExtensionDashboard; the two surfaces share only
+ * generic TUI primitives (Container, Text, SelectList, DynamicBorder).
+ *
+ * The scope switch is a real management boundary: each list only shows rows
+ * persisted at the active scope, and mutations refuse rows from the other
+ * scope. All dynamic text is sanitized before rendering.
+ *
+ * Layout (narrow-terminal safe):
+ *   title: /extensions — Configure skills, hooks, and MCPs.
+ *   scope badge (Project .gjc / Global .gjc) — `s` switches
+ *   section tabs: Skills | Hooks | MCPs — left/right switch
+ *   inventory rows for the active section + scope with status + provenance
+ *   footer key hints
+ */
+import { Container } from "@gajae-code/tui";
+import { type CustomizationInventory } from "../../../customization/inventory";
+import { type CustomizationSurface, type GjcScope } from "../../../customization/types";
+/** Minimal settings slice the dashboard reads and writes. */
+export interface CustomizationSettingsSlice {
+    get(key: string): unknown;
+    set?(key: string, value: unknown): void;
+}
+export declare class CustomizationDashboard extends Container {
+    #private;
+    /** Called when the dashboard wants to close (Esc / q / interrupt). */
+    onClose: (() => void) | undefined;
+    /** Called whenever the dashboard needs a re-render. */
+    onRequestRender: (() => void) | undefined;
+    /** Use `create()` — async inventory load runs before chrome construction. */
+    constructor(cwd: string, settings: CustomizationSettingsSlice | undefined, homeDir: string | undefined);
+    static create(cwd: string, settings?: CustomizationSettingsSlice, homeDir?: string): Promise<CustomizationDashboard>;
+    get scope(): GjcScope;
+    get section(): CustomizationSurface;
+    /** Current inventory snapshot (test-visible). */
+    get inventory(): CustomizationInventory;
+    handleInput(keyData: string): void;
+    render(width: number): string[];
+}