getcompanion-ai/co-mono
1
0
Fork 0
mirror of https://github.com/getcompanion-ai/co-mono.git synced 2026-04-16 00:03:00 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

feat(coding-agent): add hook API for CLI flags, shortcuts, and tool control

Browse source 
Hook API additions:
- pi.getTools() / pi.setTools(toolNames) - dynamically enable/disable tools
- pi.registerFlag(name, options) / pi.getFlag(name) - register custom CLI flags
- pi.registerShortcut(shortcut, options) - register keyboard shortcuts

Plan mode hook (examples/hooks/plan-mode.ts):
- /plan command or Shift+P shortcut to toggle
- --plan CLI flag to start in plan mode
- Read-only tools: read, bash, grep, find, ls
- Bash restricted to non-destructive commands (blocks rm, mv, git commit, etc.)
- Interactive prompt after each response: execute, stay, or refine
- Shows plan indicator in footer when active
- State persists across sessions
This commit is contained in:
Helmut Januschka 2026-01-03 09:52:13 +01:00 • committed by Mario Zechner
parent 059292ead1
commit c956a726ed
13 changed files with 636 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

2
packages/coding-agent/src/core/hooks/index.ts
View file

@ -5,6 +5,8 @@ export {
type AppendEntryHandler,
type BranchHandler,
type GetToolsHandler,
type HookFlag,
type HookShortcut,
type LoadedHook,
type LoadHooksResult,
type NavigateTreeHandler,

84
packages/coding-agent/src/core/hooks/loader.ts
View file

@ -71,6 +71,36 @@ export type GetToolsHandler = () => string[];
*/
export type SetToolsHandler = (toolNames: string[]) => void;
/**
* CLI flag definition registered by a hook.
*/
export interface HookFlag {
/** Flag name (without --) */
name: string;
/** Description for --help */
description?: string;
/** Type: boolean or string */
type: "boolean" | "string";
/** Default value */
default?: boolean | string;
/** Hook path that registered this flag */
hookPath: string;
}
/**
* Keyboard shortcut registered by a hook.
*/
export interface HookShortcut {
/** Shortcut string (e.g., "shift+p", "ctrl+shift+x") */
shortcut: string;
/** Description for help */
description?: string;
/** Handler function */
handler: (ctx: import("./types.js").HookContext) => Promise<void> | void;
/** Hook path that registered this shortcut */
hookPath: string;
}
/**
* New session handler type for ctx.newSession() in HookCommandContext.
*/
@ -106,6 +136,12 @@ export interface LoadedHook {
messageRenderers: Map<string, HookMessageRenderer>;
/** Map of command name to registered command */
commands: Map<string, RegisteredCommand>;
/** CLI flags registered by this hook */
flags: Map<string, HookFlag>;
/** Flag values (set after CLI parsing) */
flagValues: Map<string, boolean | string>;
/** Keyboard shortcuts registered by this hook */
shortcuts: Map<string, HookShortcut>;
/** Set the send message handler for this hook's pi.sendMessage() */
setSendMessageHandler: (handler: SendMessageHandler) => void;
/** Set the append entry handler for this hook's pi.appendEntry() */
@ -114,6 +150,8 @@ export interface LoadedHook {
setGetToolsHandler: (handler: GetToolsHandler) => void;
/** Set the set tools handler for this hook's pi.setTools() */
setSetToolsHandler: (handler: SetToolsHandler) => void;
/** Set a flag value (called after CLI parsing) */
setFlagValue: (name: string, value: boolean | string) => void;
}
/**
@ -167,14 +205,19 @@ function resolveHookPath(hookPath: string, cwd: string): string {
function createHookAPI(
handlers: Map<string, HandlerFn[]>,
cwd: string,
hookPath: string,
): {
api: HookAPI;
messageRenderers: Map<string, HookMessageRenderer>;
commands: Map<string, RegisteredCommand>;
flags: Map<string, HookFlag>;
flagValues: Map<string, boolean | string>;
shortcuts: Map<string, HookShortcut>;
setSendMessageHandler: (handler: SendMessageHandler) => void;
setAppendEntryHandler: (handler: AppendEntryHandler) => void;
setGetToolsHandler: (handler: GetToolsHandler) => void;
setSetToolsHandler: (handler: SetToolsHandler) => void;
setFlagValue: (name: string, value: boolean | string) => void;
} {
let sendMessageHandler: SendMessageHandler = () => {
// Default no-op until mode sets the handler
@ -188,6 +231,9 @@ function createHookAPI(
};
const messageRenderers = new Map<string, HookMessageRenderer>();
const commands = new Map<string, RegisteredCommand>();
const flags = new Map<string, HookFlag>();
const flagValues = new Map<string, boolean | string>();
const shortcuts = new Map<string, HookShortcut>();
// Cast to HookAPI - the implementation is more general (string event names)
// but the interface has specific overloads for type safety in hooks
@ -221,12 +267,37 @@ function createHookAPI(
setTools(toolNames: string[]): void {
setToolsHandler(toolNames);
},
registerFlag(
name: string,
options: { description?: string; type: "boolean" | "string"; default?: boolean | string },
): void {
flags.set(name, { name, hookPath, ...options });
// Set default value if provided
if (options.default !== undefined) {
flagValues.set(name, options.default);
}
},
getFlag(name: string): boolean | string | undefined {
return flagValues.get(name);
},
registerShortcut(
shortcut: string,
options: {
description?: string;
handler: (ctx: import("./types.js").HookContext) => Promise<void> | void;
},
): void {
shortcuts.set(shortcut, { shortcut, hookPath, ...options });
},
} as HookAPI;
return {
api,
messageRenderers,
commands,
flags,
flagValues,
shortcuts,
setSendMessageHandler: (handler: SendMessageHandler) => {
sendMessageHandler = handler;
},
@ -239,6 +310,9 @@ function createHookAPI(
setSetToolsHandler: (handler: SetToolsHandler) => {
setToolsHandler = handler;
},
setFlagValue: (name: string, value: boolean | string) => {
flagValues.set(name, value);
},
};
}
@ -270,11 +344,15 @@ async function loadHook(hookPath: string, cwd: string): Promise<{ hook: LoadedHo
api,
messageRenderers,
commands,
flags,
flagValues,
shortcuts,
setSendMessageHandler,
setAppendEntryHandler,
setGetToolsHandler,
setSetToolsHandler,
} = createHookAPI(handlers, cwd);
setFlagValue,
} = createHookAPI(handlers, cwd, hookPath);
// Call factory to register handlers
factory(api);
@ -286,10 +364,14 @@ async function loadHook(hookPath: string, cwd: string): Promise<{ hook: LoadedHo
handlers,
messageRenderers,
commands,
flags,
flagValues,
shortcuts,
setSendMessageHandler,
setAppendEntryHandler,
setGetToolsHandler,
setSetToolsHandler,
setFlagValue,
},
error: null,
};

37
packages/coding-agent/src/core/hooks/runner.ts
View file

@ -168,6 +168,43 @@ export class HookRunner {
return this.hooks.map((h) => h.path);
}
/**
* Get all CLI flags registered by hooks.
*/
getFlags(): Map<string, import("./loader.js").HookFlag> {
const allFlags = new Map<string, import("./loader.js").HookFlag>();
for (const hook of this.hooks) {
for (const [name, flag] of hook.flags) {
allFlags.set(name, flag);
}
}
return allFlags;
}
/**
* Set a flag value (after CLI parsing).
*/
setFlagValue(name: string, value: boolean | string): void {
for (const hook of this.hooks) {
if (hook.flags.has(name)) {
hook.setFlagValue(name, value);
}
}
}
/**
* Get all keyboard shortcuts registered by hooks.
*/
getShortcuts(): Map<string, import("./loader.js").HookShortcut> {
const allShortcuts = new Map<string, import("./loader.js").HookShortcut>();
for (const hook of this.hooks) {
for (const [key, shortcut] of hook.shortcuts) {
allShortcuts.set(key, shortcut);
}
}
return allShortcuts;
}
/**
* Subscribe to hook errors.
* @returns Unsubscribe function

64
packages/coding-agent/src/core/hooks/types.ts
View file

@ -771,6 +771,70 @@ export interface HookAPI {
* pi.setTools(["read", "bash", "edit", "write"]);
*/
setTools(toolNames: string[]): void;
/**
* Register a CLI flag for this hook.
* Flags are parsed from command line and values accessible via getFlag().
*
* @param name - Flag name (will be --name on CLI)
* @param options - Flag configuration
*
* @example
* pi.registerFlag("plan", {
* description: "Start in plan mode (read-only)",
* type: "boolean",
* });
*/
registerFlag(
name: string,
options: {
/** Description shown in --help */
description?: string;
/** Flag type: boolean (--flag) or string (--flag value) */
type: "boolean" | "string";
/** Default value */
default?: boolean | string;
},
): void;
/**
* Get the value of a CLI flag registered by this hook.
* Returns undefined if flag was not provided and has no default.
*
* @param name - Flag name (without --)
* @returns Flag value, or undefined
*
* @example
* if (pi.getFlag("plan")) {
* // plan mode enabled
* }
*/
getFlag(name: string): boolean | string | undefined;
/**
* Register a keyboard shortcut for this hook.
* The handler is called when the shortcut is pressed in interactive mode.
*
* @param shortcut - Shortcut definition (e.g., "shift+p", "ctrl+shift+x")
* @param options - Shortcut configuration
*
* @example
* pi.registerShortcut("shift+p", {
* description: "Toggle plan mode",
* handler: async (ctx) => {
* // toggle plan mode
* },
* });
*/
registerShortcut(
shortcut: string,
options: {
/** Description shown in help */
description?: string;
/** Handler called when shortcut is pressed */
handler: (ctx: HookContext) => Promise<void> | void;
},
): void;
}
/**

31
packages/coding-agent/src/core/sdk.ts
View file

@ -112,6 +112,8 @@ export interface CreateAgentSessionOptions {
hooks?: Array<{ path?: string; factory: HookFactory }>;
/** Additional hook paths to load (merged with discovery). */
additionalHookPaths?: string[];
/** Pre-loaded hooks (skips loading, used when hooks were loaded early for CLI flags). */
preloadedHooks?: LoadedHook[];
/** Skills. Default: discovered from multiple locations */
skills?: Skill[];
@ -341,9 +343,13 @@ function createFactoryFromLoadedHook(loaded: LoadedHook): HookFactory {
*/
function createLoadedHooksFromDefinitions(definitions: Array<{ path?: string; factory: HookFactory }>): LoadedHook[] {
return definitions.map((def) => {
const hookPath = def.path ?? "<inline>";
const handlers = new Map<string, Array<(...args: unknown[]) => Promise<unknown>>>();
const messageRenderers = new Map<string, any>();
const commands = new Map<string, any>();
const flags = new Map<string, any>();
const flagValues = new Map<string, boolean | string>();
const shortcuts = new Map<string, any>();
let sendMessageHandler: (
message: any,
options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" },
@ -375,6 +381,16 @@ function createLoadedHooksFromDefinitions(definitions: Array<{ path?: string; fa
registerCommand: (name: string, options: any) => {
commands.set(name, { name, ...options });
},
registerFlag: (name: string, options: any) => {
flags.set(name, { name, hookPath, ...options });
if (options.default !== undefined) {
flagValues.set(name, options.default);
}
},
getFlag: (name: string) => flagValues.get(name),
registerShortcut: (shortcut: string, options: any) => {
shortcuts.set(shortcut, { shortcut, hookPath, ...options });
},
newSession: (options?: any) => newSessionHandler(options),
branch: (entryId: string) => branchHandler(entryId),
navigateTree: (targetId: string, options?: any) => navigateTreeHandler(targetId, options),
@ -385,11 +401,14 @@ function createLoadedHooksFromDefinitions(definitions: Array<{ path?: string; fa
def.factory(api as any);
return {
path: def.path ?? "<inline>",
resolvedPath: def.path ?? "<inline>",
path: hookPath,
resolvedPath: hookPath,
handlers,
messageRenderers,
commands,
flags,
flagValues,
shortcuts,
setSendMessageHandler: (
handler: (message: any, options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" }) => void,
) => {
@ -413,6 +432,9 @@ function createLoadedHooksFromDefinitions(definitions: Array<{ path?: string; fa
setSetToolsHandler: (handler: (toolNames: string[]) => void) => {
setToolsHandler = handler;
},
setFlagValue: (name: string, value: boolean | string) => {
flagValues.set(name, value);
},
};
});
}
@ -566,7 +588,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
}
let hookRunner: HookRunner | undefined;
if (options.hooks !== undefined) {
if (options.preloadedHooks !== undefined && options.preloadedHooks.length > 0) {
// Use pre-loaded hooks (from early CLI flag discovery)
hookRunner = new HookRunner(options.preloadedHooks, cwd, sessionManager, modelRegistry);
} else if (options.hooks !== undefined) {
if (options.hooks.length > 0) {
const loadedHooks = createLoadedHooksFromDefinitions(options.hooks);
hookRunner = new HookRunner(loadedHooks, cwd, sessionManager, modelRegistry);