@basou/core 0.39.0 → 0.40.0

package/dist/index.d.ts

@@ -818,6 +818,110 @@ declare function resolveCodexCommand(lookup?: CommandLookup): Promise<{
     command: string;
 }>;
 
+/**
+ * Pure transforms for registering / removing basou's SessionStart hook inside a
+ * parsed Codex `hooks.json` object. No disk or environment access: the CLI reads
+ * and writes the file, parses the JSON, and passes the object here so the
+ * merge/removal logic stays deterministic and unit-testable. The Codex twin of
+ * the Claude Code `settings-hook` transforms.
+ *
+ * Why a hook, and why this shape: `~/.codex/hooks.json` is user-global, but a
+ * hook stores nothing — Codex runs it when a session starts and passes the
+ * session's own `cwd` on stdin, and whatever the hook prints on stdout becomes
+ * developer context for THAT session only. basou resolves the workspace from
+ * that `cwd` and prints that workspace's position. So one installed hook serves
+ * every workspace on the machine while no workspace's position is ever written
+ * where another workspace's session reads it — the property the retired
+ * `~/.codex/AGENTS.md` orientation render could not have.
+ *
+ * `hooks.json` holds other events and other people's hooks; these functions
+ * clone the input and touch ONLY the `hooks.SessionStart` handler that basou
+ * owns, preserving everything else byte-for-byte through the round-trip.
+ */
+/**
+ * Seconds before Codex kills the hook. `basou orient` reads the store and
+ * probes the native logs for staleness; on a large store that is seconds, not
+ * minutes. Codex's own default is 600 — far too long for a session-start
+ * handler whose failure mode is "the session waits".
+ */
+declare const SESSION_START_HOOK_TIMEOUT_SECONDS = 30;
+/**
+ * Which SessionStart sources fire the hook. Codex applies the matcher to the
+ * payload's `source`: `startup` (a new session), `resume`, `clear` (context
+ * reset). `compact` is left out: the position is already in the context being
+ * compacted, and re-injecting ~10 KB after every compaction would crowd the
+ * budget the compaction just freed.
+ */
+declare const SESSION_START_HOOK_MATCHER = "startup|resume|clear";
+/**
+ * Codex caps each hook's model-visible output at roughly 2,500 tokens by default
+ * and spills the rest to a temp file, handing the model a head-and-tail preview
+ * plus the path. A position is ~10 KB and is useless truncated — the open
+ * tracks and the next step sit at the end — so the cap is disabled for this
+ * handler (`0` passes the complete output).
+ */
+declare const SESSION_START_HOOK_CONTEXT_LIMIT = 0;
+/** Shown in the Codex UI while the hook runs. */
+declare const SESSION_START_HOOK_STATUS_MESSAGE = "basou orient";
+declare function isBasouSessionStartHookCommand(command: string): boolean;
+/**
+ * Build the shell command basou registers as a Codex SessionStart hook. Uses
+ * the node path (the `basou` alias is often absent from a hook's PATH) and a
+ * `2>/dev/null || true` wrapper so a stale dist path or any crash fails open —
+ * a session start must never be blocked by its orientation. The handler itself
+ * is also fail-open, so the wrapper is belt-and-braces. The entry path is
+ * shell-quoted for directories containing spaces or metacharacters.
+ */
+declare function buildSessionStartHookCommand(options: {
+    cliEntry: string;
+}): string;
+type CodexHooksFile = Record<string, unknown>;
+type SessionStartHookUpsert = {
+    hooksFile: CodexHooksFile;
+    /** `installed` = a new entry was appended; `updated` = an existing basou entry was rewritten; `unchanged` = already canonical. */
+    action: "installed" | "updated" | "unchanged";
+};
+type SessionStartHookRemoval = {
+    hooksFile: CodexHooksFile;
+    action: "removed" | "absent";
+};
+/**
+ * Where basou's handler sits in the file. Codex records trust per handler under
+ * `[hooks.state."<hooks.json path>:session_start:<group>:<handler>"]` in
+ * `config.toml`, so the two indexes are what `hook status codex` needs to look
+ * the trust entry up.
+ */
+type SessionStartHookLocation = {
+    command: string;
+    groupIndex: number;
+    handlerIndex: number;
+    /** The matcher of the group the handler sits in (undefined = fires on every source). */
+    matcher: string | undefined;
+    /**
+     * The handler object exactly as installed. Codex hashes the installed fields
+     * (not basou's canonical ones) when it decides whether the hook is trusted, so
+     * a status check must hash what is in the file.
+     */
+    handler: Record<string, unknown>;
+};
+/**
+ * Register (or upgrade in place) basou's SessionStart hook. Idempotent: an
+ * existing basou handler is rewritten to the canonical fields; a foreign
+ * handler, another event, or any other key is left untouched. A new install
+ * appends its own matcher group so it never widens or narrows someone else's
+ * matcher.
+ */
+declare function upsertSessionStartHook(hooksFile: unknown, command: string): SessionStartHookUpsert;
+/**
+ * Remove every basou-owned SessionStart handler. A group emptied by the removal
+ * is dropped; a now-empty `hooks.SessionStart` / `hooks` container is deleted so
+ * the file does not accumulate empty scaffolding. Foreign handlers and other
+ * keys are preserved.
+ */
+declare function removeSessionStartHook(hooksFile: unknown): SessionStartHookRemoval;
+/** Locate the installed basou SessionStart handler, or null if none is registered. */
+declare function findBasouSessionStartHook(hooksFile: unknown): SessionStartHookLocation | null;
+
 /**
  * The `source` string stamped on every event derived from an OpenAI Codex
  * native rollout log, and the matching session `source.kind`.
@@ -6877,4 +6981,4 @@ declare function overwriteYamlFile(filePath: string, value: unknown): Promise<vo
  */
 declare const BASOU_CORE_VERSION = "0.1.0";
 
-export { ACTIVE_GAP_CAP_MS, AGENT_INFRA_DIRS, type ActiveTimeBasis, type AdapterOutputEvent, type AdoptCandidate, type AdoptCandidateKind, type AnchorStarterInput, type AnchorStarterRepo, type AppendBasouGitignoreOptions, type AppendBasouGitignoreResult, type AppendEventToExistingInput, type AppendEventToExistingResult, type Approval, type ApprovalApprovedEvent, type ApprovalExpiredEvent, ApprovalIdSchema, type ApprovalLocation, type ApprovalRejectedEvent, type ApprovalRequestedEvent, ApprovalSchema, type ApprovalStatus, ApprovalStatusSchema, type ArchivePlan, type ArchiveTaskInput, type ArchiveTaskResult, type AttachTaskInput, type AttachUpdateTaskStatusInput, type AttachableStatus, BASOU_CORE_VERSION, type BasouPaths, type BuildStopHookCommandOptions, type BulkChainResult, CLAUDE_IMPORT_SOURCE, CODEX_IMPORT_SOURCE, type CaptureMode, type ChainBreakReason, type ChainTailState, type ChainVerdict, type ChainVerdictStatus, type ChainedEvents, ChildProcessRunner, type CitedReview, type ClaudeSettings, type ClaudeTranscriptRecord, type ClaudeTranscriptToPayloadOptions, type CodexCommandLookup, type CodexRolloutRecord, type CodexRolloutToPayloadOptions, type CommandExecutedEvent, type CommandLookup, type CreateAdHocSessionInput, type CreateAdHocSessionResult, type CreateAdHocTaskInput, type CreateManifestInput, type CreateTaskInput, type CreateTaskResult, DEFAULT_STOP_HOOK_MIN_EDITS, type DayWorkStats, DecisionIdSchema, type DecisionRecordedEvent, type DecisionsRendererInput, type DecisionsRendererResult, type DeleteTaskInput, type DeleteTaskResult, type DiffResult, type EditTaskInput, type EditTaskResult, type Event, EventIdSchema, EventSchema, EventSourceSchema, type ExistingViewLink, FailedToFinalizeError, type FederatedRoot, type FileChange, type FileChangeStatus, type FileChangedEvent, GENERATED_END, GENERATED_START, type GitSnapshot, type GitSnapshotEvent, type GitignorePlanSummary, type HandoffRendererInput, type HandoffRendererResult, ID_PREFIXES, type IdPrefix, type ImportSessionOptions, type ImportSessionResult, type IncompleteWiring, type InstructionFileFact, type InstructionSymlinkFact, type InstructionSymlinkState, IsoTimestampSchema, JSON_SCHEMA_VERSION, type JsonSchemaArtifact, type LoadFederatedOptions, type LoadSessionEntriesOptions, type LoadTaskEntriesOptions, type LoadedApproval, type LockHandle, type LockScope, type Manifest, ManifestSchema, type MarkerSection, type Markers, type MeasureAvailability, type MissingCanonical, type NoteAddedEvent, ORIENTATION_END, ORIENTATION_START, type OrientationRendererInput, type OrientationRendererResult, type OrientationSummary, PROTOCOL_END, PROTOCOL_START, type PrefixedId, type PresetAction, type PresetCollision, type PresetMarkerConflict, type PresetMarkerKind, type PresetPlanSummary, type PresetRepo, type PresetStrings, type ProcessRunner, type PublishKind, type PublishTarget, REVIEW_RECORD_NO_INPUT_HINT, type RechainOptions, type RechainResult, type ReconcileAllResult, type ReconcileAllTasksInput, type ReconcileAllTasksOptions, type ReconcileFailure, type ReconcileResult, type ReconcileTaskInput, type RefreshLinkageInput, type RefreshLinkageResult, type ReimportOptions, type ReimportResult, type RenamePlan, type ReplayOptions, type ReplayWarning, type RepoEntry, type RepoGitignoreFacts, type RepoGitignorePlan, type RepoInstructions, type RepoLanguage, type RepoPathProblem, type RepoPresetFacts, type RepoPresetPlan, type RepoSymlinkFacts, type RepoSymlinkPlan, type RepoVisibility, type RepoWiringFacts, type ReportApprovalItem, type ReportData, type ReportDecisionItem, type ReportRendererInput, type ReportRendererResult, type ReportSessionItem, type ReportTaskItem, type RetrofitAction, type RetrofitAgentsState, type RetrofitFacts, type RetrofitPlan, type RetrofitReason, type ReviewBlocked, type ReviewFinding, type ReviewGapRepoSummary, type ReviewGapUnit, type ReviewGapVerdict, type ReviewGapsInput, type ReviewGapsSummary, type ReviewGateResult, type ReviewGateSilentReason, type ReviewRecordBlockedInput, type ReviewRecordFindingInput, type ReviewRecordInput, type ReviewRecordedEvent, type RiskLevel, RiskLevelSchema, type RosterAdoptionPlan, type RosterDriftSummary, type RunOptions, type RunResult, STOP_HOOK_TIMEOUT_SECONDS, STUCK_THRESHOLD_MS, type SanitizePathOptions, type SanitizeRelatedFilesResult, SchemaVersionSchema, type SelfReportedReview, type Session, type SessionEndedEvent, type SessionEntry, SessionIdSchema, type SessionImportPayload, SessionImportPayloadSchema, type SessionInnerImportInput, SessionInnerImportSchema, type SessionIntegrity, SessionIntegritySchema, type SessionMetrics, SessionMetricsSchema, SessionSchema, type SessionSkipReason, type SessionSourceKind, SessionSourceKindSchema, type SessionStartedEvent, type SessionStatus, type SessionStatusChangedEvent, SessionStatusSchema, type SessionWorkStats, type SourceRootScope, type SourceRootsReconcile, type SourceWorkStats, type StatusCount, StatusSchema, type StatusSnapshot, type StopHookEvaluation, type StopHookEvaluationInput, type StopHookRemoval, type StopHookSilentReason, type StopHookUpsert, type SuspectReason, type SymlinkCollision, type SymlinkConflict, type SymlinkPlanSummary, type Task, type TaskArchivedEvent, type TaskCreatedEvent, type TaskDeletedEvent, type TaskDocument, TaskIdSchema, type TaskLinkageRefreshedEvent, type TaskReconciledEvent, TaskSchema, type TaskSkipReason, type TaskStatus, type TaskStatusChangedEvent, type TaskStatusCount, TaskStatusSchema, TaskWriteAfterEventError, type TaskWriteAfterEventPhase, type TokenTotals, type UnattachedSelfReports, type UnbindableRepo, type UpdateAdHocTaskStatusInput, type UpdateTaskStatusInput, type UpdateTaskStatusResult, type ViewCollision, type ViewConflict, type ViewLanguage, type ViewLinkState, type ViewPresetInput, type ViewPresetRepo, type ViewRepoFact, type ViewStrayUnknown, type ViewStrings, type ViewWiringFacts, type WiringCollision, type WiringConflict, type WiringDriftSummary, type WiringRisk, type WiringSummary, type WorkStatsInput, type WorkStatsResult, type WorkStatsTotals, WorkspaceIdSchema, type WorkspaceViewPlan, type WriteEventsBulkOptions, type WriteTaskFileMode, acquireLock, appendBasouGitignore, appendChainedEvent, appendChainedEventLocked, appendEvent, appendEventToExistingSession, archiveTask, assertBasouRootSafe, basouPaths, buildJsonSchemas, buildReviewRecordLabel, buildReviewRecordedEvent, buildStatusSnapshot, buildStopHookCommand, chainEvents, chainRawJsonLines, classifyFilesBySourceRoot, classifyRetrofit, classifySuspect, claudeCodeAdapterMetadata, claudeTranscriptToImportPayload, codexAdapterMetadata, codexRolloutToImportPayload, computeWorkStats, createAdHocSessionWithEvent, createManifest, createTaskWithEvent, deleteTask, editTask, ensureBasouDirectory, enumerateApprovals, enumerateArchivedTaskIds, enumerateSessionDirs, enumerateTaskIds, evaluateStopHook, finalizeSessionYaml, findBasouStopHookCommand, findErrorCode, findReviewGaps, findUnbindableRepos, formatDurationMs, genesisHash, getDiff, getSnapshot, importSessionFromJson, inspectChainTail, instructionMode, isBasouStopHookCommand, isGitNotFound, isImportDerivedSource, isLazyExpired, isRenderable, isValidPrefixedId, lineHash, linkYamlFile, loadApproval, loadFederatedSessionEntries, loadSessionEntries, loadTaskEntries, normalizeRepoKey, normalizeRepoPath, overwriteYamlFile, parseDuration, parseMarkers, parseReviewRecordInput, pathBasename, planArchive, planGitignore, planRename, planRosterAdoption, planWorkspaceView, prefixedUlid, presetStrings, readAllEvents, readManifest, readMarkdownFile, readSessionYaml, readStatus, readTaskFile, readTaskFileWithArchiveFallback, readYamlFile, rechainSessionInPlace, reconcileAllTasks, reconcileSourceRoots, reconcileTask, refreshTaskLinkedSessions, reimportPreservingId, removeMarkerSection, removeStopHook, renderAnchorStarter, renderDecisions, renderHandoff, renderOrientation, renderPresetBlock, renderReport, renderViewPresetBlock, renderWithMarkers, replayEvents, resolveAnchorContentLanguage, resolveBasouRepositoryRoot, resolveClaudeCodeCommand, resolveCodexCommand, resolveRepoContentLanguage, resolveRepoRoot, resolveRepositoryRoot, resolveSessionId, resolveTaskId, resolveViewLanguage, resolveViewLanguageFromPaths, safeSimpleGit, sanitizePath, sanitizeRelatedFiles, sanitizeWorkingDirectory, seedMarkers, serializeEventLine, serializeJsonSchema, sessionWorkStatsFromEvents, summarizeAdapterOutput, summarizeOrientation, summarizePresetPlan, summarizeRosterDrift, summarizeSymlinkPlan, summarizeWiring, summarizeWiringDrift, tryRemoteUrl, ulid, unknownManifestKeys, updateTaskStatusWithEvent, upsertStopHook, verifyEventsChain, viewStrings, writeEventsBulk, writeManifest, writeMarkdownFile, writeStatus, writeTaskFile, writeYamlFile };
+export { ACTIVE_GAP_CAP_MS, AGENT_INFRA_DIRS, type ActiveTimeBasis, type AdapterOutputEvent, type AdoptCandidate, type AdoptCandidateKind, type AnchorStarterInput, type AnchorStarterRepo, type AppendBasouGitignoreOptions, type AppendBasouGitignoreResult, type AppendEventToExistingInput, type AppendEventToExistingResult, type Approval, type ApprovalApprovedEvent, type ApprovalExpiredEvent, ApprovalIdSchema, type ApprovalLocation, type ApprovalRejectedEvent, type ApprovalRequestedEvent, ApprovalSchema, type ApprovalStatus, ApprovalStatusSchema, type ArchivePlan, type ArchiveTaskInput, type ArchiveTaskResult, type AttachTaskInput, type AttachUpdateTaskStatusInput, type AttachableStatus, BASOU_CORE_VERSION, type BasouPaths, type BuildStopHookCommandOptions, type BulkChainResult, CLAUDE_IMPORT_SOURCE, CODEX_IMPORT_SOURCE, type CaptureMode, type ChainBreakReason, type ChainTailState, type ChainVerdict, type ChainVerdictStatus, type ChainedEvents, ChildProcessRunner, type CitedReview, type ClaudeSettings, type ClaudeTranscriptRecord, type ClaudeTranscriptToPayloadOptions, type CodexCommandLookup, type CodexHooksFile, type CodexRolloutRecord, type CodexRolloutToPayloadOptions, type CommandExecutedEvent, type CommandLookup, type CreateAdHocSessionInput, type CreateAdHocSessionResult, type CreateAdHocTaskInput, type CreateManifestInput, type CreateTaskInput, type CreateTaskResult, DEFAULT_STOP_HOOK_MIN_EDITS, type DayWorkStats, DecisionIdSchema, type DecisionRecordedEvent, type DecisionsRendererInput, type DecisionsRendererResult, type DeleteTaskInput, type DeleteTaskResult, type DiffResult, type EditTaskInput, type EditTaskResult, type Event, EventIdSchema, EventSchema, EventSourceSchema, type ExistingViewLink, FailedToFinalizeError, type FederatedRoot, type FileChange, type FileChangeStatus, type FileChangedEvent, GENERATED_END, GENERATED_START, type GitSnapshot, type GitSnapshotEvent, type GitignorePlanSummary, type HandoffRendererInput, type HandoffRendererResult, ID_PREFIXES, type IdPrefix, type ImportSessionOptions, type ImportSessionResult, type IncompleteWiring, type InstructionFileFact, type InstructionSymlinkFact, type InstructionSymlinkState, IsoTimestampSchema, JSON_SCHEMA_VERSION, type JsonSchemaArtifact, type LoadFederatedOptions, type LoadSessionEntriesOptions, type LoadTaskEntriesOptions, type LoadedApproval, type LockHandle, type LockScope, type Manifest, ManifestSchema, type MarkerSection, type Markers, type MeasureAvailability, type MissingCanonical, type NoteAddedEvent, ORIENTATION_END, ORIENTATION_START, type OrientationRendererInput, type OrientationRendererResult, type OrientationSummary, PROTOCOL_END, PROTOCOL_START, type PrefixedId, type PresetAction, type PresetCollision, type PresetMarkerConflict, type PresetMarkerKind, type PresetPlanSummary, type PresetRepo, type PresetStrings, type ProcessRunner, type PublishKind, type PublishTarget, REVIEW_RECORD_NO_INPUT_HINT, type RechainOptions, type RechainResult, type ReconcileAllResult, type ReconcileAllTasksInput, type ReconcileAllTasksOptions, type ReconcileFailure, type ReconcileResult, type ReconcileTaskInput, type RefreshLinkageInput, type RefreshLinkageResult, type ReimportOptions, type ReimportResult, type RenamePlan, type ReplayOptions, type ReplayWarning, type RepoEntry, type RepoGitignoreFacts, type RepoGitignorePlan, type RepoInstructions, type RepoLanguage, type RepoPathProblem, type RepoPresetFacts, type RepoPresetPlan, type RepoSymlinkFacts, type RepoSymlinkPlan, type RepoVisibility, type RepoWiringFacts, type ReportApprovalItem, type ReportData, type ReportDecisionItem, type ReportRendererInput, type ReportRendererResult, type ReportSessionItem, type ReportTaskItem, type RetrofitAction, type RetrofitAgentsState, type RetrofitFacts, type RetrofitPlan, type RetrofitReason, type ReviewBlocked, type ReviewFinding, type ReviewGapRepoSummary, type ReviewGapUnit, type ReviewGapVerdict, type ReviewGapsInput, type ReviewGapsSummary, type ReviewGateResult, type ReviewGateSilentReason, type ReviewRecordBlockedInput, type ReviewRecordFindingInput, type ReviewRecordInput, type ReviewRecordedEvent, type RiskLevel, RiskLevelSchema, type RosterAdoptionPlan, type RosterDriftSummary, type RunOptions, type RunResult, SESSION_START_HOOK_CONTEXT_LIMIT, SESSION_START_HOOK_MATCHER, SESSION_START_HOOK_STATUS_MESSAGE, SESSION_START_HOOK_TIMEOUT_SECONDS, STOP_HOOK_TIMEOUT_SECONDS, STUCK_THRESHOLD_MS, type SanitizePathOptions, type SanitizeRelatedFilesResult, SchemaVersionSchema, type SelfReportedReview, type Session, type SessionEndedEvent, type SessionEntry, SessionIdSchema, type SessionImportPayload, SessionImportPayloadSchema, type SessionInnerImportInput, SessionInnerImportSchema, type SessionIntegrity, SessionIntegritySchema, type SessionMetrics, SessionMetricsSchema, SessionSchema, type SessionSkipReason, type SessionSourceKind, SessionSourceKindSchema, type SessionStartHookLocation, type SessionStartHookRemoval, type SessionStartHookUpsert, type SessionStartedEvent, type SessionStatus, type SessionStatusChangedEvent, SessionStatusSchema, type SessionWorkStats, type SourceRootScope, type SourceRootsReconcile, type SourceWorkStats, type StatusCount, StatusSchema, type StatusSnapshot, type StopHookEvaluation, type StopHookEvaluationInput, type StopHookRemoval, type StopHookSilentReason, type StopHookUpsert, type SuspectReason, type SymlinkCollision, type SymlinkConflict, type SymlinkPlanSummary, type Task, type TaskArchivedEvent, type TaskCreatedEvent, type TaskDeletedEvent, type TaskDocument, TaskIdSchema, type TaskLinkageRefreshedEvent, type TaskReconciledEvent, TaskSchema, type TaskSkipReason, type TaskStatus, type TaskStatusChangedEvent, type TaskStatusCount, TaskStatusSchema, TaskWriteAfterEventError, type TaskWriteAfterEventPhase, type TokenTotals, type UnattachedSelfReports, type UnbindableRepo, type UpdateAdHocTaskStatusInput, type UpdateTaskStatusInput, type UpdateTaskStatusResult, type ViewCollision, type ViewConflict, type ViewLanguage, type ViewLinkState, type ViewPresetInput, type ViewPresetRepo, type ViewRepoFact, type ViewStrayUnknown, type ViewStrings, type ViewWiringFacts, type WiringCollision, type WiringConflict, type WiringDriftSummary, type WiringRisk, type WiringSummary, type WorkStatsInput, type WorkStatsResult, type WorkStatsTotals, WorkspaceIdSchema, type WorkspaceViewPlan, type WriteEventsBulkOptions, type WriteTaskFileMode, acquireLock, appendBasouGitignore, appendChainedEvent, appendChainedEventLocked, appendEvent, appendEventToExistingSession, archiveTask, assertBasouRootSafe, basouPaths, buildJsonSchemas, buildReviewRecordLabel, buildReviewRecordedEvent, buildSessionStartHookCommand, buildStatusSnapshot, buildStopHookCommand, chainEvents, chainRawJsonLines, classifyFilesBySourceRoot, classifyRetrofit, classifySuspect, claudeCodeAdapterMetadata, claudeTranscriptToImportPayload, codexAdapterMetadata, codexRolloutToImportPayload, computeWorkStats, createAdHocSessionWithEvent, createManifest, createTaskWithEvent, deleteTask, editTask, ensureBasouDirectory, enumerateApprovals, enumerateArchivedTaskIds, enumerateSessionDirs, enumerateTaskIds, evaluateStopHook, finalizeSessionYaml, findBasouSessionStartHook, findBasouStopHookCommand, findErrorCode, findReviewGaps, findUnbindableRepos, formatDurationMs, genesisHash, getDiff, getSnapshot, importSessionFromJson, inspectChainTail, instructionMode, isBasouSessionStartHookCommand, isBasouStopHookCommand, isGitNotFound, isImportDerivedSource, isLazyExpired, isRenderable, isValidPrefixedId, lineHash, linkYamlFile, loadApproval, loadFederatedSessionEntries, loadSessionEntries, loadTaskEntries, normalizeRepoKey, normalizeRepoPath, overwriteYamlFile, parseDuration, parseMarkers, parseReviewRecordInput, pathBasename, planArchive, planGitignore, planRename, planRosterAdoption, planWorkspaceView, prefixedUlid, presetStrings, readAllEvents, readManifest, readMarkdownFile, readSessionYaml, readStatus, readTaskFile, readTaskFileWithArchiveFallback, readYamlFile, rechainSessionInPlace, reconcileAllTasks, reconcileSourceRoots, reconcileTask, refreshTaskLinkedSessions, reimportPreservingId, removeMarkerSection, removeSessionStartHook, removeStopHook, renderAnchorStarter, renderDecisions, renderHandoff, renderOrientation, renderPresetBlock, renderReport, renderViewPresetBlock, renderWithMarkers, replayEvents, resolveAnchorContentLanguage, resolveBasouRepositoryRoot, resolveClaudeCodeCommand, resolveCodexCommand, resolveRepoContentLanguage, resolveRepoRoot, resolveRepositoryRoot, resolveSessionId, resolveTaskId, resolveViewLanguage, resolveViewLanguageFromPaths, safeSimpleGit, sanitizePath, sanitizeRelatedFiles, sanitizeWorkingDirectory, seedMarkers, serializeEventLine, serializeJsonSchema, sessionWorkStatsFromEvents, summarizeAdapterOutput, summarizeOrientation, summarizePresetPlan, summarizeRosterDrift, summarizeSymlinkPlan, summarizeWiring, summarizeWiringDrift, tryRemoteUrl, ulid, unknownManifestKeys, updateTaskStatusWithEvent, upsertSessionStartHook, upsertStopHook, verifyEventsChain, viewStrings, writeEventsBulk, writeManifest, writeMarkdownFile, writeStatus, writeTaskFile, writeYamlFile };

package/dist/index.js

@@ -660,6 +660,135 @@ async function resolveCodexCommand(lookup = isOnPath) {
   throw new Error("Codex CLI not found in PATH. Install codex first.");
 }
 
+// src/adapters/codex/hooks-json.ts
+var SESSION_START_HOOK_TIMEOUT_SECONDS = 30;
+var SESSION_START_HOOK_MATCHER = "startup|resume|clear";
+var SESSION_START_HOOK_CONTEXT_LIMIT = 0;
+var SESSION_START_HOOK_STATUS_MESSAGE = "basou orient";
+var BASOU_SESSION_START_HOOK = /(?:\bbasou|(?:@basou|packages)\/cli\/dist\/index\.js['"]?)\s+hook\s+session-start\b/;
+function isBasouSessionStartHookCommand(command) {
+  return BASOU_SESSION_START_HOOK.test(command);
+}
+function shellQuote2(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function buildSessionStartHookCommand(options) {
+  return `node ${shellQuote2(options.cliEntry)} hook session-start 2>/dev/null || true`;
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function cloneHooksFile(hooksFile) {
+  if (hooksFile === void 0 || hooksFile === null) return {};
+  if (!isRecord2(hooksFile)) {
+    throw new Error("The Codex hooks.json is not a JSON object.");
+  }
+  return structuredClone(hooksFile);
+}
+function canonicalHandler(command) {
+  return {
+    type: "command",
+    command,
+    timeout: SESSION_START_HOOK_TIMEOUT_SECONDS,
+    statusMessage: SESSION_START_HOOK_STATUS_MESSAGE,
+    additionalContextLimit: SESSION_START_HOOK_CONTEXT_LIMIT
+  };
+}
+function handlerIsCanonical(entry, command) {
+  const want = canonicalHandler(command);
+  return Object.keys(want).every((k) => entry[k] === want[k]);
+}
+function upsertSessionStartHook(hooksFile, command) {
+  const root = cloneHooksFile(hooksFile);
+  if (root.hooks === void 0) {
+    root.hooks = {};
+  } else if (!isRecord2(root.hooks)) {
+    throw new Error("The 'hooks' key in the Codex hooks.json is not an object.");
+  }
+  const hooks = root.hooks;
+  if (hooks.SessionStart === void 0) {
+    hooks.SessionStart = [];
+  } else if (!Array.isArray(hooks.SessionStart)) {
+    throw new Error("The 'hooks.SessionStart' key in the Codex hooks.json is not an array.");
+  }
+  const groups = hooks.SessionStart;
+  for (const group of groups) {
+    if (!isRecord2(group) || !Array.isArray(group.hooks)) continue;
+    for (const entry of group.hooks) {
+      if (!isRecord2(entry)) continue;
+      if (typeof entry.command === "string" && isBasouSessionStartHookCommand(entry.command)) {
+        const unchanged = handlerIsCanonical(entry, command);
+        Object.assign(entry, canonicalHandler(command));
+        return { hooksFile: root, action: unchanged ? "unchanged" : "updated" };
+      }
+    }
+  }
+  groups.push({ matcher: SESSION_START_HOOK_MATCHER, hooks: [canonicalHandler(command)] });
+  return { hooksFile: root, action: "installed" };
+}
+function removeSessionStartHook(hooksFile) {
+  const root = cloneHooksFile(hooksFile);
+  if (!isRecord2(root.hooks) || !Array.isArray(root.hooks.SessionStart)) {
+    return { hooksFile: root, action: "absent" };
+  }
+  const hooks = root.hooks;
+  const groups = hooks.SessionStart;
+  let removed = false;
+  const kept = [];
+  for (const group of groups) {
+    if (!isRecord2(group) || !Array.isArray(group.hooks)) {
+      kept.push(group);
+      continue;
+    }
+    const keptHandlers = group.hooks.filter((entry) => {
+      if (isRecord2(entry) && typeof entry.command === "string" && isBasouSessionStartHookCommand(entry.command)) {
+        removed = true;
+        return false;
+      }
+      return true;
+    });
+    if (keptHandlers.length === group.hooks.length) {
+      kept.push(group);
+    } else if (keptHandlers.length > 0) {
+      group.hooks = keptHandlers;
+      kept.push(group);
+    }
+  }
+  if (!removed) return { hooksFile: root, action: "absent" };
+  if (kept.length === 0) {
+    delete hooks.SessionStart;
+  } else {
+    hooks.SessionStart = kept;
+  }
+  if (Object.keys(hooks).length === 0) {
+    delete root.hooks;
+  }
+  return { hooksFile: root, action: "removed" };
+}
+function findBasouSessionStartHook(hooksFile) {
+  if (!isRecord2(hooksFile) || !isRecord2(hooksFile.hooks) || !Array.isArray(hooksFile.hooks.SessionStart)) {
+    return null;
+  }
+  const groups = hooksFile.hooks.SessionStart;
+  for (let g = 0; g < groups.length; g++) {
+    const group = groups[g];
+    if (!isRecord2(group) || !Array.isArray(group.hooks)) continue;
+    for (let h = 0; h < group.hooks.length; h++) {
+      const entry = group.hooks[h];
+      if (isRecord2(entry) && typeof entry.command === "string" && isBasouSessionStartHookCommand(entry.command)) {
+        return {
+          command: entry.command,
+          groupIndex: g,
+          handlerIndex: h,
+          matcher: typeof group.matcher === "string" ? group.matcher : void 0,
+          handler: structuredClone(entry)
+        };
+      }
+    }
+  }
+  return null;
+}
+
 // src/adapters/codex/rollout-importer.ts
 var CODEX_IMPORT_SOURCE = "codex-import";
 function codexRolloutToImportPayload(records, options) {
@@ -1783,31 +1912,26 @@ var WorkspaceMetaSchema = z4.looseObject({
   view: SourceRootSchema.optional()
 });
 var ChannelsSchema = z4.looseObject({
-  /**
-   * Render this workspace's orientation into `~/.codex/AGENTS.md` on `basou
-   * refresh` / `basou run codex`. A boolean today; if a face ever needs
-   * per-block control this widens to `boolean | object`, which existing
-   * manifests keep parsing — so the boolean does not foreclose that.
-   */
+  /** Retired (see above). Parsed for compatibility; has no effect. */
   codex: z4.boolean().optional().meta({
-    description: "Opt in to rendering this workspace's orientation into the user-global ~/.codex/AGENTS.md on `basou refresh` and `basou run codex`. Off when absent: that file is auto-loaded by Codex for every project on the machine, so nothing is written there unless the workspace says so."
+    description: "Retired and ignored. It used to opt this workspace into rendering its orientation into the user-global ~/.codex/AGENTS.md; nothing is written there any more \u2014 a Codex session receives the workspace's position from the SessionStart hook (`basou hook install codex`)."
   })
 });
 var PoliciesSchema = z4.looseObject({
   /**
    * This workspace's provenance must not persist where another workspace's
-   * tool reads it. That is the GOAL the key states; what it gates today is one
-   * thing: rendering the orientation into the user-global `~/.codex/AGENTS.md`
-   * (`basou refresh` / `basou run codex`) — never, regardless of `channels`, so
-   * a confidential workspace cannot be re-enabled by a second declaration in
-   * the same file. It does not yet govern `basou protocol sync` (a global
-   * render, not a per-workspace one), and it gates writing only: it cannot keep
-   * another workspace's block out of this workspace's tool (see `basou channel
-   * clear`). Stated as a goal rather than as "never write" so that a transient
-   * render removed before anyone else can read it remains permissible.
+   * tool reads it. That is the GOAL the key states. The one writer it used to
+   * gate — the orientation render into the user-global `~/.codex/AGENTS.md` —
+   * is retired, so today the key gates nothing: basou has no per-workspace path
+   * that writes a position anywhere another workspace's tool reads. It is kept,
+   * parsed, and honoured as a declaration, so a future writer to a shared
+   * surface must consult it before it ships (`basou protocol sync`, a global
+   * render rather than a per-workspace one, does not consult it). A top-level
+   * `confidential` is still refused rather than ignored, for the same reason it
+   * always was: a safety key that is not honoured must fail loudly.
    */
   confidential: z4.boolean().optional().meta({
-    description: "This workspace's provenance must not persist where another workspace's tool reads it. Today this means its orientation is never rendered into the user-global ~/.codex/AGENTS.md by `basou refresh` or `basou run codex`, regardless of `channels`. It does not yet govern `basou protocol sync`, and it gates writing only \u2014 it cannot keep another workspace's block out of this workspace's tool."
+    description: "Posture: this workspace's provenance must not persist where another workspace's tool reads it. The one writer this used to gate \u2014 rendering the orientation into the user-global ~/.codex/AGENTS.md \u2014 is retired, so today the key gates nothing; it stays declared so a future writer to a shared surface must consult it. A top-level `confidential` is rejected rather than ignored."
   })
 });
 var ManifestObjectSchema = z4.looseObject({
@@ -9451,6 +9575,10 @@ export {
   PROTOCOL_START,
   REVIEW_RECORD_NO_INPUT_HINT,
   RiskLevelSchema,
+  SESSION_START_HOOK_CONTEXT_LIMIT,
+  SESSION_START_HOOK_MATCHER,
+  SESSION_START_HOOK_STATUS_MESSAGE,
+  SESSION_START_HOOK_TIMEOUT_SECONDS,
   STOP_HOOK_TIMEOUT_SECONDS,
   STUCK_THRESHOLD_MS,
   SchemaVersionSchema,
@@ -9480,6 +9608,7 @@ export {
   buildJsonSchemas,
   buildReviewRecordLabel,
   buildReviewRecordedEvent,
+  buildSessionStartHookCommand,
   buildStatusSnapshot,
   buildStopHookCommand,
   chainEvents,
@@ -9504,6 +9633,7 @@ export {
   enumerateTaskIds,
   evaluateStopHook,
   finalizeSessionYaml,
+  findBasouSessionStartHook,
   findBasouStopHookCommand,
   findErrorCode,
   findReviewGaps,
@@ -9515,6 +9645,7 @@ export {
   importSessionFromJson,
   inspectChainTail,
   instructionMode,
+  isBasouSessionStartHookCommand,
   isBasouStopHookCommand,
   isGitNotFound,
   isImportDerivedSource,
@@ -9556,6 +9687,7 @@ export {
   refreshTaskLinkedSessions,
   reimportPreservingId,
   removeMarkerSection,
+  removeSessionStartHook,
   removeStopHook,
   renderAnchorStarter,
   renderDecisions,
@@ -9596,6 +9728,7 @@ export {
   ulid,
   unknownManifestKeys,
   updateTaskStatusWithEvent,
+  upsertSessionStartHook,
   upsertStopHook,
   verifyEventsChain,
   viewStrings,