@sun-asterisk/sungen 3.2.34 → 3.3.0-alpha.2

package/dist/hooks/guard-rules.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The pre-tool guard's rules. Each looks at one normalized tool call and returns a decision or
+ * null; pre-tool-guard-hook.ts runs them in order (first deny wins, else first ask).
+ *
+ *   protected-approval-paths  DENY  a precise write (Edit/Write/MultiEdit, or Bash `>`, `tee`,
+ *                                   `sed -i`) to a contract lock, a decision record, approval state or
+ *                                   trace evidence (.sungen/trace-identity, test-results[-free]/sungen-run-record*)
+ *   protected-hook-control    ASK   the same writes to the files that control the hooks, so the
+ *                                   agent cannot switch its own guard off unasked
+ *   bash-protected-mention    ASK   any other Bash segment that names a protected path and does not
+ *                                   start with a read-only command (cp, mv, ln, install, rm,
+ *                                   bash -c, python -c, perl -i…)
+ *
+ * A floor, not a sandbox: a path built at runtime, a symlink, or a script file that writes without
+ * naming the path on the command line is out of reach by design. Each rule only matches strings,
+ * so each fails open (`onError: 'no-op'`); a rule that READS project state must declare `'ask'`.
+ */
+import type { HookContext, HookResult } from './hook-result-contract';
+/** One tool call, normalized from the untrusted payload. */
+export interface GuardedCall {
+    tool: string;
+    /** Absolute target paths of a file tool (Edit/Write/MultiEdit). */
+    filePaths: string[];
+    bashCommand?: string;
+    cwd: string;
+}
+export interface GuardRule {
+    id: string;
+    /** What a throw inside `check` becomes: `ask` for a rule that reads state, `no-op` otherwise. */
+    onError: 'ask' | 'no-op';
+    /** A decision for this call, or null when the rule has nothing to say about it. */
+    check(call: GuardedCall, ctx: HookContext): HookResult | null;
+}
+export declare const protectedApprovalPaths: GuardRule;
+export declare const protectedHookControl: GuardRule;
+export declare const bashProtectedMention: GuardRule;
+//# sourceMappingURL=guard-rules.d.ts.map

package/dist/hooks/guard-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-rules.d.ts","sourceRoot":"","sources":["../../src/hooks/guard-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAItE,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,iGAAiG;IACjG,OAAO,EAAE,KAAK,GAAG,OAAO,CAAC;IACzB,mFAAmF;IACnF,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,UAAU,GAAG,IAAI,CAAC;CAC/D;AAMD,eAAO,MAAM,sBAAsB,EAAE,SAqBpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,SAWlC,CAAC;AAQF,eAAO,MAAM,oBAAoB,EAAE,SAalC,CAAC"}

package/dist/hooks/guard-rules.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bashProtectedMention = exports.protectedHookControl = exports.protectedApprovalPaths = void 0;
+const bash_write_targets_1 = require("./bash-write-targets");
+const guard_protected_paths_1 = require("./guard-protected-paths");
+/** The files a call writes precisely: a file tool's target, or Bash's `>` / `tee` / `sed -i` targets. */
+const preciseWrites = (call) => call.tool === 'Bash' ? (0, bash_write_targets_1.bashSegments)(call.bashCommand ?? '', call.cwd).flatMap((s) => s.writes) : call.filePaths;
+exports.protectedApprovalPaths = {
+    id: 'protected-approval-paths',
+    onError: 'no-op',
+    check(call) {
+        const writes = preciseWrites(call);
+        const rel = writes.map(guard_protected_paths_1.approvalRecordPath).find((r) => r !== null);
+        if (rel) {
+            return {
+                status: 'deny',
+                denyReason: `sungen: \`${rel}\` is an approval record — contract locks, decisions, waivers and the accepted `
+                    + 'viewpoint baseline change only through a human at a terminal, never by an agent edit. If this change is '
+                    + 'intended, stop and ask the user to make it themselves.',
+            };
+        }
+        const evidence = writes.map(guard_protected_paths_1.traceEvidencePath).find((r) => r !== null);
+        return evidence ? {
+            status: 'deny',
+            denyReason: `sungen: \`${evidence}\` is trace evidence — only \`sungen contract check --trace\` / \`contract derive\` `
+                + 'and the Playwright run-record reporter write it. Re-run the free tests or the CLI instead of editing it.',
+        } : null;
+    },
+};
+exports.protectedHookControl = {
+    id: 'protected-hook-control',
+    onError: 'no-op',
+    check(call) {
+        const rel = preciseWrites(call).map(guard_protected_paths_1.hookControlPath).find((r) => r !== null);
+        return rel ? {
+            status: 'ask',
+            askReason: `sungen: \`${rel}\` controls sungen's hooks and guard, so an agent does not change it on its own. `
+                + 'Allow only if you asked for exactly this change — the usual path is to edit it by hand, then run `sungen update`.',
+        } : null;
+    },
+};
+/** Segments that only read: they may name a protected path freely. */
+const READ_ONLY = new Set(['cat', 'ls', 'head', 'tail', 'grep', 'rg', 'wc', 'diff', 'sungen', 'sungen.js']);
+const GIT_READ_ONLY = new Set(['diff', 'log', 'show', 'status']);
+const isReadOnly = (cmd, words) => READ_ONLY.has(cmd) || (cmd === 'git' && GIT_READ_ONLY.has(words.find((w) => !w.startsWith('-')) ?? ''));
+exports.bashProtectedMention = {
+    id: 'bash-protected-mention',
+    onError: 'no-op',
+    check(call) {
+        if (call.tool !== 'Bash' || !call.bashCommand)
+            return null;
+        const seg = (0, bash_write_targets_1.bashSegments)(call.bashCommand, call.cwd)
+            .find((s) => s.cmd && !isReadOnly(s.cmd, s.words) && s.words.some((w) => (0, guard_protected_paths_1.mentionsProtectedPath)(w, s.dir)));
+        return seg ? {
+            status: 'ask',
+            askReason: `sungen: this \`${seg.cmd}\` command names a contract lock, a decision record, approval state or a hook-control file, `
+                + 'and the guard cannot tell whether it writes it. Allow only if you asked for exactly this.',
+        } : null;
+    },
+};
+//# sourceMappingURL=guard-rules.js.map

package/dist/hooks/guard-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-rules.js","sourceRoot":"","sources":["../../src/hooks/guard-rules.ts"],"names":[],"mappings":"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"}

package/dist/hooks/guard-tty-spoof-rule.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Guard rule `tty-spoof` (phase 06, M5): ASK before an agent runs a human-confirmed sungen command
+ * through a terminal emulator.
+ *
+ * `contract approve`, `journey --waive`, `journey --decide` and `journey --signoff` refuse without a TTY (DOS-13.4), and
+ * an agent's Bash has none — unless it borrows one: `script`, `expect`, `unbuffer`, or a pty from
+ * Python/Perl/zsh. Then the prompt sees a "terminal" and a piped phrase reads as a human typing it.
+ * This rule spots the pair in the raw command (quotes included, so `bash -c "…"` and `expect -c '…'`
+ * are covered) and hands the call to the user. A floor, not a sandbox: a script file that does the
+ * same without naming either on the command line is out of reach by design. String match only, so
+ * it fails open.
+ */
+import type { GuardRule } from './guard-rules';
+export declare const ttySpoof: GuardRule;
+//# sourceMappingURL=guard-tty-spoof-rule.d.ts.map

package/dist/hooks/guard-tty-spoof-rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-tty-spoof-rule.d.ts","sourceRoot":"","sources":["../../src/hooks/guard-tty-spoof-rule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAK/C,eAAO,MAAM,QAAQ,EAAE,SAatB,CAAC"}

package/dist/hooks/guard-tty-spoof-rule.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ttySpoof = void 0;
+const TTY_EMULATOR = /\b(?:script|unbuffer|expect|pty|zpty|openpty|forkpty|ptyprocess)\b/i;
+const HUMAN_GATED = /\bsungen\b[\s\S]*?\b(?:contract['",\s]+approve\b|journey\b[\s\S]*?--(?:waive|decide|signoff)\b)/i;
+exports.ttySpoof = {
+    id: 'tty-spoof',
+    onError: 'no-op',
+    check(call) {
+        const cmd = call.tool === 'Bash' ? call.bashCommand : undefined;
+        if (!cmd || !TTY_EMULATOR.test(cmd) || !HUMAN_GATED.test(cmd))
+            return null;
+        return {
+            status: 'ask',
+            askReason: 'sungen: this runs a human-confirmed sungen action (`contract approve` / `journey --waive|--decide|--signoff`) through a terminal '
+                + 'emulator (script / expect / unbuffer / pty). Those confirmations exist so a PERSON at a terminal decides — allow only if you '
+                + 'are that person and asked for exactly this; otherwise run the command yourself in your own terminal.',
+        };
+    },
+};
+//# sourceMappingURL=guard-tty-spoof-rule.js.map

package/dist/hooks/guard-tty-spoof-rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-tty-spoof-rule.js","sourceRoot":"","sources":["../../src/hooks/guard-tty-spoof-rule.ts"],"names":[],"mappings":";;;AAcA,MAAM,YAAY,GAAG,qEAAqE,CAAC;AAC3F,MAAM,WAAW,GAAG,kGAAkG,CAAC;AAE1G,QAAA,QAAQ,GAAc;IACjC,EAAE,EAAE,WAAW;IACf,OAAO,EAAE,OAAO;IAChB,KAAK,CAAC,IAAI;QACR,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;QAChE,IAAI,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3E,OAAO;YACL,MAAM,EAAE,KAAK;YACb,SAAS,EAAE,mIAAmI;kBAC1I,+HAA+H;kBAC/H,sGAAsG;SAC3G,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/hooks/hand-back-core.d.ts

@@ -0,0 +1,39 @@
+import { NextStep, UnitState } from '../harness/next-step';
+import { HookContext, HookInput, HookResult } from './hook-result-contract';
+import { UnitRef } from './sungen-project-root';
+/** `invocation`: how the project runs sungen (`npx sungen` with a local install, #939). */
+export declare function handBackLine(unit?: string, invocation?: string): string;
+export interface CliHandBackState {
+    unit?: string;
+    machine: boolean;
+    silent: boolean;
+    answer: boolean;
+    actionRan: boolean;
+}
+/** The default, set before commander parses — what a usage error or a fatal error hands back. */
+export declare function initialHandBackState(argv: string[]): CliHandBackState;
+/** commander's preAction: the action now KNOWS its unit and output mode. */
+export declare function onCliAction(state: CliHandBackState, name: string, opts: Record<string, unknown>, args: unknown[]): void;
+/**
+ * What to print as the process exits, or null for nothing. A positional that is not a unit on
+ * disk (`capability add mock` → `mock`) is dropped rather than offered as `sungen next mock`.
+ */
+export declare function exitHandBack(state: CliHandBackState, code: number, cwd: string): {
+    stream: 'stdout' | 'stderr';
+    text: string;
+} | null;
+/** Wire the hand-back to process exit; returns the preAction callback. Never masks the real exit. */
+export declare function attachCliHandBack(argv: string[], cwd: string): {
+    onAction: (name: string, opts: Record<string, unknown>, args: unknown[]) => void;
+};
+/** `sungen next` rendered compactly for an agent's context; commands as `root` runs sungen. */
+export declare function formatSteps(steps: NextStep[], max?: number, root?: string): string[];
+/** The unit a session is on (a named one when it exists, else the nearest) and its derived state. */
+export declare function locateUnitState(ctx: HookContext, preferred?: string): {
+    root: string;
+    unit: UnitRef;
+    state: UnitState;
+} | null;
+/** Hook core: the next steps for the session's unit (input.unit, else the nearest) as context. */
+export declare function run(input: HookInput, ctx: HookContext): HookResult;
+//# sourceMappingURL=hand-back-core.d.ts.map

package/dist/hooks/hand-back-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hand-back-core.d.ts","sourceRoot":"","sources":["../../src/hooks/hand-back-core.ts"],"names":[],"mappings":"AAcA,OAAO,EAAiB,QAAQ,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAS,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACnF,OAAO,EAAyC,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAWvF,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,SAAW,GAAG,MAAM,CAEzE;AAED,MAAM,WAAW,gBAAgB;IAAG,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE;AAE3H,iGAAiG;AACjG,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAUrE;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAQvH;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CASrI;AAED,qGAAqG;AACrG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;CAAE,CASnJ;AAMD,+FAA+F;AAC/F,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,GAAG,SAAI,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAG/E;AAED,qGAAqG;AACrG,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAAG,IAAI,CAK9H;AAED,kGAAkG;AAClG,wBAAgB,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,UAAU,CAOlE"}

package/dist/hooks/hand-back-core.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handBackLine = handBackLine;
+exports.initialHandBackState = initialHandBackState;
+exports.onCliAction = onCliAction;
+exports.exitHandBack = exitHandBack;
+exports.attachCliHandBack = attachCliHandBack;
+exports.formatSteps = formatSteps;
+exports.locateUnitState = locateUnitState;
+exports.run = run;
+/**
+ * The hand-back, written once (P0.1, takumi T1). Two callers share it:
+ *
+ *   - the CLI exit (cli/index.ts only wires it): the one-line `Next: sungen next <unit>` every
+ *     command ends with — on stdout after a success, on STDERR after a failure or under --json/--grep;
+ *   - the Claude Code Stop hook (stop-next-step-hook.ts): the same pointer plus what `sungen next`
+ *     derives right now, so a session that ended without a hand-back gets one injected.
+ *
+ * #597 skipped exit code 1 ("the error is the actionable thing") and set the hand-back only in
+ * commander's preAction, so a usage error — which never reaches an action — and `main().catch`
+ * ended in silence. The state now starts the moment parsing does; the action only refines it.
+ */
+const project_sungen_invocation_1 = require("../cli/project-sungen-invocation");
+const resolve_unit_1 = require("../cli/resolve-unit");
+const next_step_1 = require("../harness/next-step");
+const hook_result_contract_1 = require("./hook-result-contract");
+const sungen_project_root_1 = require("./sungen-project-root");
+/** `hook` speaks JSON to Claude Code on stdout: it never prints a hand-back. */
+const SILENT_COMMANDS = new Set(['hook']);
+/** `next` IS the answer when it succeeds; a failed `next` answered nothing and hands back like any failure (#937). */
+const ANSWER_COMMANDS = new Set(['next']);
+const UNIT_FLAG = /^(?:--screen|-s|--flow|--area|--api)$/;
+const UNIT_FLAG_EQ = /^--(?:screen|flow|area|api)=(.+)$/;
+/** A unit id is a name or `flows/<name>` — anything else is not offered back to the operator. */
+const SAFE_UNIT = /^[\w.-]+(?:\/[\w.-]+)?$/;
+/** `invocation`: how the project runs sungen (`npx sungen` with a local install, #939). */
+function handBackLine(unit, invocation = 'sungen') {
+    return `Next: ${invocation} next${unit ? ` ${unit}` : ''}`;
+}
+/** The default, set before commander parses — what a usage error or a fatal error hands back. */
+function initialHandBackState(argv) {
+    const args = argv.slice(2);
+    let unit;
+    for (let i = 0; i < args.length; i++) {
+        const eq = args[i].match(UNIT_FLAG_EQ);
+        if (eq)
+            unit ?? (unit = eq[1]);
+        else if (UNIT_FLAG.test(args[i]) && args[i + 1] && !args[i + 1].startsWith('-'))
+            unit ?? (unit = args[++i]);
+    }
+    const command = args.find((a) => !a.startsWith('-')) ?? '';
+    return { unit, machine: args.includes('--json') || args.includes('--grep'), silent: SILENT_COMMANDS.has(command), answer: ANSWER_COMMANDS.has(command), actionRan: false };
+}
+/** commander's preAction: the action now KNOWS its unit and output mode. */
+function onCliAction(state, name, opts, args) {
+    state.actionRan = true;
+    if (SILENT_COMMANDS.has(name)) {
+        state.silent = true;
+        return;
+    }
+    state.answer = ANSWER_COMMANDS.has(name);
+    const flagged = [opts.screen, opts.flow, opts.area, opts.api].find((v) => typeof v === 'string' && v);
+    state.unit = flagged ?? (typeof args?.[0] === 'string' ? args[0] : undefined);
+    // `--grep` is machine output too: callers capture it with `$(…)` (#836).
+    state.machine = opts.json === true || opts.grep === true;
+}
+/**
+ * What to print as the process exits, or null for nothing. A positional that is not a unit on
+ * disk (`capability add mock` → `mock`) is dropped rather than offered as `sungen next mock`.
+ */
+function exitHandBack(state, code, cwd) {
+    if (state.silent)
+        return null;
+    if (state.answer && code === 0)
+        return null; // a successful `next` is the hand-back itself
+    if (!state.actionRan && code === 0)
+        return null; // --help / --version printed what was asked
+    const unit = state.unit && SAFE_UNIT.test(state.unit) && !state.unit.split('/').includes('..')
+        && (0, resolve_unit_1.resolveUnitCandidates)(state.unit, cwd).length > 0 ? state.unit : undefined;
+    const line = handBackLine(unit, (0, project_sungen_invocation_1.sungenInvocation)((0, sungen_project_root_1.findSungenRoot)(cwd) ?? cwd));
+    if (code === 1)
+        return { stream: 'stderr', text: `${line}\n` }; // after the error, one line
+    return { stream: state.machine ? 'stderr' : 'stdout', text: `\n${line}\n` };
+}
+/** Wire the hand-back to process exit; returns the preAction callback. Never masks the real exit. */
+function attachCliHandBack(argv, cwd) {
+    const state = initialHandBackState(argv);
+    process.on('exit', (code) => {
+        try {
+            const out = exitHandBack(state, code, cwd);
+            if (out)
+                process[out.stream].write(out.text);
+        }
+        catch { /* the hand-back is advice; the exit code is the contract */ }
+    });
+    return { onAction: (name, opts, args) => onCliAction(state, name, opts, args) };
+}
+// --- the hook-shaped core -----------------------------------------------------------------------
+const MARK = { do: '→', blocked: '⛔', optional: '○', decide: '⚖' };
+/** `sungen next` rendered compactly for an agent's context; commands as `root` runs sungen. */
+function formatSteps(steps, max = 4, root) {
+    return steps.slice(0, max).map((st) => `  ${MARK[st.kind]} ${root ? (0, project_sungen_invocation_1.withProjectInvocation)(st.command, root) : st.command}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}\n     ${st.because}`);
+}
+/** The unit a session is on (a named one when it exists, else the nearest) and its derived state. */
+function locateUnitState(ctx, preferred) {
+    const root = (0, sungen_project_root_1.findSungenRoot)(ctx.cwd);
+    if (!root)
+        return null;
+    const unit = (preferred && SAFE_UNIT.test(preferred) ? (0, sungen_project_root_1.findUnit)(root, preferred) : null) ?? (0, sungen_project_root_1.nearestUnit)(root, ctx.cwd);
+    return unit ? { root, unit, state: (0, next_step_1.readUnitState)(root, unit.dir, unit.name, unit.kind) } : null;
+}
+/** Hook core: the next steps for the session's unit (input.unit, else the nearest) as context. */
+function run(input, ctx) {
+    const found = locateUnitState(ctx, typeof input.unit === 'string' ? input.unit : undefined);
+    if (!found || found.state.steps.length === 0)
+        return hook_result_contract_1.NO_OP;
+    return {
+        status: 'context',
+        output: [`${handBackLine(found.unit.name, (0, project_sungen_invocation_1.sungenInvocation)(found.root))} — derived from what the project holds now:`, ...formatSteps(found.state.steps, 4, found.root)].join('\n'),
+    };
+}
+//# sourceMappingURL=hand-back-core.js.map

package/dist/hooks/hand-back-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hand-back-core.js","sourceRoot":"","sources":["../../src/hooks/hand-back-core.ts"],"names":[],"mappings":"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"}

package/dist/hooks/hook-cli-command.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `sungen hook <name>` — hidden: runs one Claude Code hook through the normal CLI (event JSON on
+ * stdin, decision JSON on stdout). The installed hooks call the dist entry directly for speed; this
+ * path is for debugging a hook by hand and for dev checkouts that run sungen from source.
+ * The CLI hand-back skips it, so stdout stays pure JSON.
+ */
+import { Command } from 'commander';
+export declare function registerHookCommand(program: Command): void;
+//# sourceMappingURL=hook-cli-command.d.ts.map

package/dist/hooks/hook-cli-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-cli-command.d.ts","sourceRoot":"","sources":["../../src/hooks/hook-cli-command.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAQ1D"}

package/dist/hooks/hook-cli-command.js

@@ -0,0 +1,46 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerHookCommand = registerHookCommand;
+function registerHookCommand(program) {
+    program
+        .command('hook <name>', { hidden: true })
+        .description('Run one Claude Code hook: event JSON on stdin, decision JSON on stdout (internal)')
+        .action(async (name) => {
+        const { main } = await Promise.resolve().then(() => __importStar(require('./claude-hook-entry')));
+        await main(name);
+    });
+}
+//# sourceMappingURL=hook-cli-command.js.map

package/dist/hooks/hook-cli-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-cli-command.js","sourceRoot":"","sources":["../../src/hooks/hook-cli-command.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAQA,kDAQC;AARD,SAAgB,mBAAmB,CAAC,OAAgB;IAClD,OAAO;SACJ,OAAO,CAAC,aAAa,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;SACxC,WAAW,CAAC,mFAAmF,CAAC;SAChG,MAAM,CAAC,KAAK,EAAE,IAAY,EAAE,EAAE;QAC7B,MAAM,EAAE,IAAI,EAAE,GAAG,wDAAa,qBAAqB,GAAC,CAAC;QACrD,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/hooks/hook-registry.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Every sungen Claude Code hook, by name. Modules load ON DEMAND: the guard runs on every Edit,
+ * Write and Bash call and must not pay for the next-step reader the Stop hook needs.
+ */
+import { SungenHook } from './hook-result-contract';
+/** The hook with this name, or null for anything else (an unknown name is never an error). */
+export declare function loadHook(name: string): SungenHook | null;
+/** All hooks — for the installer, which reads their `meta`. */
+export declare function allHooks(): SungenHook[];
+//# sourceMappingURL=hook-registry.d.ts.map

package/dist/hooks/hook-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-registry.d.ts","sourceRoot":"","sources":["../../src/hooks/hook-registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAwB,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAW1E,8FAA8F;AAC9F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAExD;AAED,+DAA+D;AAC/D,wBAAgB,QAAQ,IAAI,UAAU,EAAE,CAEvC"}

package/dist/hooks/hook-registry.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadHook = loadHook;
+exports.allHooks = allHooks;
+/**
+ * Every sungen Claude Code hook, by name. Modules load ON DEMAND: the guard runs on every Edit,
+ * Write and Bash call and must not pay for the next-step reader the Stop hook needs.
+ */
+const hook_result_contract_1 = require("./hook-result-contract");
+const LOADERS = {
+    'stop-next-step': () => require('./stop-next-step-hook').stopNextStepHook,
+    'session-start-unit-state': () => require('./session-start-unit-state-hook').sessionStartUnitStateHook,
+    'pre-tool-guard': () => require('./pre-tool-guard-hook').preToolGuardHook,
+};
+const isHookName = (name) => hook_result_contract_1.HOOK_NAMES.includes(name);
+/** The hook with this name, or null for anything else (an unknown name is never an error). */
+function loadHook(name) {
+    return isHookName(name) ? LOADERS[name]() : null;
+}
+/** All hooks — for the installer, which reads their `meta`. */
+function allHooks() {
+    return hook_result_contract_1.HOOK_NAMES.map((n) => LOADERS[n]());
+}
+//# sourceMappingURL=hook-registry.js.map

package/dist/hooks/hook-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-registry.js","sourceRoot":"","sources":["../../src/hooks/hook-registry.ts"],"names":[],"mappings":";;AAgBA,4BAEC;AAGD,4BAEC;AAvBD;;;GAGG;AACH,iEAA0E;AAE1E,MAAM,OAAO,GAAuC;IAClD,gBAAgB,EAAE,GAAG,EAAE,CAAE,OAAO,CAAC,uBAAuB,CAA4C,CAAC,gBAAgB;IACrH,0BAA0B,EAAE,GAAG,EAAE,CAC9B,OAAO,CAAC,iCAAiC,CAAsD,CAAC,yBAAyB;IAC5H,gBAAgB,EAAE,GAAG,EAAE,CAAE,OAAO,CAAC,uBAAuB,CAA4C,CAAC,gBAAgB;CACtH,CAAC;AAEF,MAAM,UAAU,GAAG,CAAC,IAAY,EAAoB,EAAE,CAAE,iCAAgC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAExG,8FAA8F;AAC9F,SAAgB,QAAQ,CAAC,IAAY;IACnC,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACnD,CAAC;AAED,+DAA+D;AAC/D,SAAgB,QAAQ;IACtB,OAAO,iCAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAC7C,CAAC"}

package/dist/hooks/hook-result-contract.d.ts

@@ -0,0 +1,50 @@
+export declare const HOOK_NAMES: readonly ["stop-next-step", "session-start-unit-state", "pre-tool-guard"];
+export type HookName = (typeof HOOK_NAMES)[number];
+export type HookStatus = 'ok' | 'deny' | 'ask' | 'context' | 'no-op';
+export interface HookResult {
+    status: HookStatus;
+    /** Context text for the agent (status `context`). */
+    output?: string;
+    /** Why a tool call is refused (status `deny`). */
+    denyReason?: string;
+    /** Why the user must confirm a tool call (status `ask`). */
+    askReason?: string;
+}
+export type ClaudeHookEvent = 'SessionStart' | 'Stop' | 'PreToolUse';
+export interface HookMeta {
+    events: ClaudeHookEvent[];
+    /** Per-event matcher written into settings.json (e.g. `{ PreToolUse: 'Edit|Write' }`). */
+    matchers?: Partial<Record<ClaudeHookEvent, string>>;
+    /** settings.json timeout in SECONDS — Claude Code kills the hook after it (and fails open). */
+    timeout?: number;
+}
+/** The event payload: untrusted JSON from stdin. Each hook checks every field where it reads it. */
+export type HookInput = Record<string, unknown>;
+export interface HookContext {
+    /** The environment the hook sees — injected, so tests never mutate process.env. */
+    env: Record<string, string | undefined>;
+    /** Where the session runs: the payload `cwd`, else CLAUDE_PROJECT_DIR, else process.cwd(). */
+    cwd: string;
+}
+export interface SungenHook {
+    name: HookName;
+    meta: HookMeta;
+    /** What a throw inside `run` becomes. A hook that READS state to decide must not deny blind. */
+    onError?: HookResult;
+    /** What a payload too large to read becomes (default no-op). A guard must not treat it as a pass. */
+    onUnreadableInput?: HookResult;
+    run(input: HookInput, ctx: HookContext): HookResult;
+}
+export declare const NO_OP: HookResult;
+/** A result Claude Code can act on safely; anything else is treated as `no-op`. */
+export declare function isValidHookResult(r: unknown): r is HookResult;
+/** The one way to call a hook: toggles first, then the hook, failing open on any error. */
+export declare function runHook(hook: SungenHook, input: HookInput, ctx: HookContext): HookResult;
+/** The payload could not be read (too large): the hook's declared answer, toggles still first. */
+export declare function runHookOnUnreadableInput(hook: SungenHook, ctx: HookContext): HookResult;
+/**
+ * HookResult → the stdout Claude Code reads (exit code is always 0). `deny`/`ask` exist only for
+ * PreToolUse; on any other event they degrade to no decision rather than to an invented one.
+ */
+export declare function toClaudeStdout(event: string, r: HookResult): string;
+//# sourceMappingURL=hook-result-contract.d.ts.map

package/dist/hooks/hook-result-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-result-contract.d.ts","sourceRoot":"","sources":["../../src/hooks/hook-result-contract.ts"],"names":[],"mappings":"AAiBA,eAAO,MAAM,UAAU,2EAA4E,CAAC;AACpG,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,OAAO,CAAC;AACrE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,UAAU,CAAC;IACnB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,MAAM,GAAG,YAAY,CAAC;AACrE,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,oGAAoG;AACpG,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,gGAAgG;IAChG,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,qGAAqG;IACrG,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,UAAU,CAAC;CACrD;AAED,eAAO,MAAM,KAAK,EAAE,UAAgC,CAAC;AAIrD,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,UAAU,CAU7D;AAED,2FAA2F;AAC3F,wBAAgB,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,UAAU,CAQxF;AAED,kGAAkG;AAClG,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,WAAW,GAAG,UAAU,CAOvF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,GAAG,MAAM,CAWnE"}

package/dist/hooks/hook-result-contract.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_OP = exports.HOOK_NAMES = void 0;
+exports.isValidHookResult = isValidHookResult;
+exports.runHook = runHook;
+exports.runHookOnUnreadableInput = runHookOnUnreadableInput;
+exports.toClaudeStdout = toClaudeStdout;
+/**
+ * The hook contract (P0.1, takumi T1 dual-mode): one PURE core per hook, many callers.
+ *
+ *   run(input, ctx) → HookResult     no stdin read, no stdout write, no process.exit
+ *   meta { events, matchers?, timeout? }   read once at INSTALL time, never at run time
+ *
+ * The same `run` serves the Claude Code entry (claude-hook-entry.ts), the hidden `sungen hook`
+ * command, and later MCP / VS Code — so the decision logic is written once. Every caller goes
+ * through `runHook`, which owns the three properties no hook may get wrong on its own:
+ *
+ *   - kill-switch / per-hook toggle  → `no-op` before the hook runs at all
+ *   - FAIL OPEN                      → a throw becomes the hook's `onError` result (default no-op)
+ *   - shape check                    → a malformed result is `no-op`; a deny/ask without a reason
+ *                                      never blocks anyone
+ */
+const hook_toggles_1 = require("./hook-toggles");
+exports.HOOK_NAMES = ['stop-next-step', 'session-start-unit-state', 'pre-tool-guard'];
+exports.NO_OP = { status: 'no-op' };
+const nonEmpty = (v) => typeof v === 'string' && v.trim().length > 0;
+/** A result Claude Code can act on safely; anything else is treated as `no-op`. */
+function isValidHookResult(r) {
+    if (!r || typeof r !== 'object')
+        return false;
+    const { status, output, denyReason, askReason } = r;
+    switch (status) {
+        case 'ok':
+        case 'no-op': return true;
+        case 'context': return nonEmpty(output);
+        case 'deny': return nonEmpty(denyReason);
+        case 'ask': return nonEmpty(askReason);
+        default: return false;
+    }
+}
+/** The one way to call a hook: toggles first, then the hook, failing open on any error. */
+function runHook(hook, input, ctx) {
+    try {
+        if (!(0, hook_toggles_1.isHookEnabled)(hook.name, ctx))
+            return exports.NO_OP;
+        const r = hook.run(input, ctx);
+        return isValidHookResult(r) ? r : exports.NO_OP;
+    }
+    catch {
+        return hook.onError && isValidHookResult(hook.onError) ? hook.onError : exports.NO_OP;
+    }
+}
+/** The payload could not be read (too large): the hook's declared answer, toggles still first. */
+function runHookOnUnreadableInput(hook, ctx) {
+    try {
+        if (!(0, hook_toggles_1.isHookEnabled)(hook.name, ctx))
+            return exports.NO_OP;
+        return hook.onUnreadableInput && isValidHookResult(hook.onUnreadableInput) ? hook.onUnreadableInput : exports.NO_OP;
+    }
+    catch {
+        return exports.NO_OP;
+    }
+}
+/**
+ * HookResult → the stdout Claude Code reads (exit code is always 0). `deny`/`ask` exist only for
+ * PreToolUse; on any other event they degrade to no decision rather than to an invented one.
+ */
+function toClaudeStdout(event, r) {
+    if (r.status === 'context' && nonEmpty(r.output)) {
+        return JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: r.output } });
+    }
+    if (event === 'PreToolUse' && (r.status === 'deny' || r.status === 'ask')) {
+        const reason = r.status === 'deny' ? r.denyReason : r.askReason;
+        if (nonEmpty(reason)) {
+            return JSON.stringify({ hookSpecificOutput: { hookEventName: event, permissionDecision: r.status, permissionDecisionReason: reason } });
+        }
+    }
+    return '{}';
+}
+//# sourceMappingURL=hook-result-contract.js.map

package/dist/hooks/hook-result-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-result-contract.js","sourceRoot":"","sources":["../../src/hooks/hook-result-contract.ts"],"names":[],"mappings":"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"}

package/dist/hooks/hook-toggles.d.ts

@@ -0,0 +1,10 @@
+import type { HookContext, HookName } from './hook-result-contract';
+export declare const KILL_SWITCH_ENV = "SUNGEN_HOOKS";
+export declare const PROJECT_CONFIG: string;
+/** `stop-next-step` → `SUNGEN_HOOK_STOP_NEXT_STEP`. */
+export declare const hookEnvVar: (name: HookName) => string;
+export declare function hooksKilled(env: Record<string, string | undefined>): boolean;
+/** Hooks the project config turns off: `'all'`, or the names set to false. */
+export declare function configDisabledHooks(root: string | null): 'all' | Set<string>;
+export declare function isHookEnabled(name: HookName, ctx: HookContext): boolean;
+//# sourceMappingURL=hook-toggles.d.ts.map

package/dist/hooks/hook-toggles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-toggles.d.ts","sourceRoot":"","sources":["../../src/hooks/hook-toggles.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAIpE,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAC9C,eAAO,MAAM,cAAc,QAAwC,CAAC;AAEpE,uDAAuD;AACvD,eAAO,MAAM,UAAU,GAAI,MAAM,QAAQ,KAAG,MAAgE,CAAC;AAI7G,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,OAAO,CAE5E;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,CAgB5E;AAKD,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAKvE"}