import type { Runtime } from "../runtime/index.js";
/**
 * Discriminator for which verbs the hook ran (or skipped).
 */
export type HookVerb = "task.move" | "checklist.check" | "task.comment.add" | "task.close";
/**
 * Task reference for onTaskStart.
 * The adapter-native task id and optional target list/section id for work-in-progress state.
 */
export interface OnTaskStartTask {
    /** Adapter-native task id (Trello cardId; Asana task gid). */
    id: string;
    /**
     * Target list/section id for "work in progress" state.
     * If undefined, onTaskStart is a no-op AND emits a WARN audit entry
     * (when auditLogPath is also provided).
     */
    listsWipId?: string;
}
/**
 * Options for onTaskStart hook.
 * Moves the task to the configured work-in-progress list, or emits a WARN audit entry if listsWipId is absent.
 */
export interface OnTaskStartOptions {
    /** Adapter runtime exposing the taskMove verb. */
    adapter: Runtime;
    /** Task reference with id and optional wip list. */
    task: OnTaskStartTask;
    /**
     * Absolute path to the adapter's audit log file. When provided AND
     * listsWipId is missing, the hook appends one WARN entry recording
     * the no-op. Omit in tests that don't care about the WARN trail.
     */
    auditLogPath?: string;
    /**
     * Tool name written into the WARN audit entry's `tool` field
     * (e.g. "trello", "asana"). Required when auditLogPath is set.
     */
    tool?: string;
    /**
     * Session id written into the WARN audit entry's `session` field.
     * Required when auditLogPath is set.
     */
    session?: string;
}
/**
 * Task reference for onTaskComplete.
 * The adapter-native task id, target done list, and optional checklist to mark complete.
 */
export interface OnTaskCompleteTask {
    /** Adapter-native task id. */
    id: string;
    /** Target list/section id for the "done" state. REQUIRED. */
    listsDoneId: string;
    /**
     * Optional checklist + item to mark complete BEFORE moving the task.
     * Both fields must be present together (the hook checks both); if either
     * is missing, the checklist.check step is skipped (not run, not failed).
     */
    checklistId?: string;
    checklistItemId?: string;
}
/**
 * Options for onTaskComplete hook.
 * Runs the 4-verb sequence: optional checklist.check → task.move(done) →
 * task.comment.add (with commit SHA as clientToken) → task.close.
 */
export interface OnTaskCompleteOptions {
    /** Adapter runtime exposing all four verbs. */
    adapter: Runtime;
    /** Task reference with id, done list, and optional checklist. */
    task: OnTaskCompleteTask;
    /** Commit SHA — used as clientToken for the comment dedup marker. REQUIRED. */
    commitSha: string;
    /** Optional branch name woven into the comment body. */
    branch?: string;
}
/**
 * Result of a hook execution.
 * Tracks which verbs succeeded (performed), which were skipped (no-op or idempotent),
 * and whether the overall hook result was ok.
 */
export interface HookResult {
    /**
     * Overall success indicator.
     * - true: all attempted verbs returned ok:true OR ok:false with code "ALREADY_IN_STATE"
     * - false: at least one verb returned ok:false with a different code
     */
    ok: boolean;
    /** Verbs whose underlying call returned ok:true. */
    performed: HookVerb[];
    /**
     * Verbs short-circuited because their target state already held
     * (transport returned ok:false, code "ALREADY_IN_STATE"), OR because
     * inputs to that step were absent (e.g. checklist not configured),
     * OR the transport returned ok:false with a code other than ALREADY_IN_STATE
     * (those verbs also land here; check `ok` to distinguish).
     */
    skipped: HookVerb[];
}
/**
 * Reset the process-local completion memo. Intended for tests only —
 * production callers should never need this. The memo's lifetime is one
 * Node process; a new agent session starts with a fresh memo automatically.
 * Test files use this escape hatch to reset between test cases and ensure
 * no cross-test contamination.
 */
export declare function __resetHookCacheForTests(): void;
/**
 * Hook invoked when the agent starts working on a plan task.
 * Moves the task to the configured work-in-progress list.
 * If listsWipId is absent, emits a WARN audit entry (when auditLogPath is provided)
 * and returns no-op without calling taskMove.
 *
 * Never throws; transport errors are converted to { ok: false }.
 */
export declare function onTaskStart(opts: OnTaskStartOptions): Promise<HookResult>;
/**
 * Hook invoked when the agent completes a plan task.
 * Runs the 4-verb sequence (in order):
 * 1. optional checklist.check (if both checklistId and checklistItemId are present)
 * 2. task.move to the done list
 * 3. task.comment.add with commit SHA as clientToken (dedup marker)
 * 4. task.close
 *
 * Continues dispatching even after a verb fails (best-effort; the calling agent
 * reads ok/performed/skipped to decide). Never throws; all errors are converted
 * to { ok: false, performed, skipped }.
 *
 * ### Idempotency
 *
 * A repeat call with the SAME task.id AND SAME commitSha short-circuits and
 * returns `{ ok: true, performed: [], skipped: [all four verbs] }` without
 * dispatching any transport call. This is backed by a process-local memo
 * (Map<string, true>) that records only SUCCESSFUL completions (ok === true).
 *
 * A prior call that hard-failed (any verb returned a code other than
 * ALREADY_IN_STATE) leaves the memo unset, so the next call re-attempts the
 * full sequence.
 *
 * The cross-process / cross-session dedup trail is the `[ct:<commitSha>]`
 * marker the transport prepends to the comment body. A future v1.x enhancement
 * may layer a transport-level `listComments` lookup on top without breaking
 * this contract. For now, test files reset the memo via
 * `__resetHookCacheForTests()` to ensure clean state between cases.
 */
export declare function onTaskComplete(opts: OnTaskCompleteOptions): Promise<HookResult>;
//# sourceMappingURL=hooks.d.ts.map