type ActiveGoal = {
  condition: string;        // Goal condition entered by the user
  iterations: number;       // Number of unmet attempts (Stop hook interception +1 each time)
  setAt: number;            // Date.now() creation time
  tokensAtStart: number;    // "Cumulative output token count" at creation (⚠ output tokens only; see §10)
  lastReason?: string;      // Stop reason provided by the model in the previous turn
};

type GoalStatusAttachment = {
  type: "goal_status";
  met: boolean;
  condition: string;
  sentinel?: boolean;       // true = user-state set/clear anchor; UI does not render it, but resume flow searches for it
  reason?: string;          // Stop reason when unmet
  iterations?: number;      // Statistics when met
  durationMs?: number;
  tokens?: number;          // Output tokens consumed during the period
};

const MAX_CONDITION_LENGTH /* $oH */ = 4000;

const CLEAR_KEYWORDS /* l23 */ = new Set([
  "clear", "stop", "off", "reset", "none", "cancel",
]);

const POLICY_GATE_MESSAGE /* i23 */ =
  "/goal is disabled by your organization's policy (disableAllHooks).";

const TRUST_GATE_MESSAGE /* n23 */ =
  "/goal is only available in trusted workspaces. " +
  "Restart, accept the trust dialog, and try again.";

// ⭐ Runtime instruction sent to the model immediately after setting a goal (copy verbatim)
const buildGoalDirective /* uD6 */ = (condition: string): string =>
  `A session-scoped Stop hook is now active with condition: "${condition}". ` +
  `Briefly acknowledge the goal, then immediately start (or continue) working toward it ` +
  `— treat the condition itself as your directive and do not pause to ask the user what to do. ` +
  `The hook will block stopping until the condition holds. ` +
  `It auto-clears once the condition is met — do not tell the user to run \`/goal clear\` after success; ` +
  `that's only for clearing a goal early.`;

function getSessionId /* k_ */ (): string;            // cli.js L2288

// ⚠ Note: this is "cumulative output tokens", not "total tokens or context usage"
function getOutputTokenCount /* Wf */ (): number;     // cli.js L2409

function isNonInteractive /* Z8 */ (): boolean;       // cli.js L2656 —— !isInteractive
function isRemoteWorkspace /* V8 */ (): boolean;      // cli.js L3076
function isWorkspaceTrusted /* q3 */ (): boolean;     // cli.js L149640
function isHooksDisabledByPolicy /* eu */ (): boolean;// cli.js L255357

type SessionHook =
  | { type: "prompt"; prompt: string }
  | { type: "function"; id: string; timeout: number; callback: Function; errorMessage?: string }
  | { type: "command"; command: string; /* … */ };

type HookEntry = {
  matcher: string;                    // empty string means "no matcher" → /goal uses empty string
  skillRoot?: string;                 // /goal uses undefined (distinct from skill-injected hooks)
  hooks: SessionHook[];
};

interface SessionHooksRegistry <ruby>add(sessionId: string, event: &quot;Stop&quot;<rt>&quot;SubagentStop&quot; | /* … */,
      matcher: string, hook: SessionHook, skillRoot?: string): void;
  remove(sessionId: string, event: string, hook: SessionHook): void;</rt></ruby>

// See cli.js L376600 iD_ → OI7: upsert by (matcher, skillRoot)
function installHook /* iD_ */ (
  setAppState: AppStateSetter,
  sessionId: string,
  event: "Stop",
  matcher: string,
  hook: SessionHook,
): void;

// Get all HookEntry items for this session and event
function getHooksForEvent /* twH */ (
  state: AppState, sessionId: string, event: string,
): Map<string, HookEntry[]>;

interface AppStateCtx {
  getAppState(): AppState;
  setAppState(updater: (s: AppState) => AppState): void;
  applyMessageOp(op: { type: "append"; messages: Message[] }): void;
  sessionHooksRegistry: SessionHooksRegistry;
  messages: Message[];
}

interface AppState <ruby>activeGoal: ActiveGoal<rt>undefined;
  // … other fields</rt></ruby>

function wrapAttachmentAsMessage /* z9 */ (att: GoalStatusAttachment): Message; // cli.js L423101

function makeUserMessage /* $6 */ (opts: <ruby>content: string<rt>ContentBlock[];
  isMeta?: boolean;
  // …</rt></ruby>): Message;                                                                    // cli.js L450191

function formatBlockingError /* oV8 */ (err: { blockingError: string }): string;
// Implementation: return `Stop hook feedback:\n${err.blockingError}`            // cli.js L554731

function pluralize /* x6 */ (n: number, singular: string, plural?: string): string; // cli.js L9966
function firstLine /* s5 */ (text: string): string;        // cut at the first \n // cli.js L10026
function formatDuration /* r7 */ (ms: number, opts: { mostSignificantOnly?: boolean }): string;
function formatTokenCount /* F4 */ (n: number): string;

function track /* Q */ (event: string, props: Record<string, unknown>): void;       // cli.js L3256
function trackWithCode /* j6 */ (event: string, code: string): void;                // cli.js L43254
function showToast /* yH */ (id: "goal_set" | "goal_met"): void;                    // cli.js L43248

// cli.js L540226–540237
const goalCommandNonInteractive /* gV3 */ = {
  type: "local" as const,
  name: "goal",
  supportsNonInteractive: true,
  thinClientDispatch: "post-text" as const,
  description: "Set a goal — keep working until the condition is met",
  argumentHint: "[<condition> | clear]",
  get isHidden() { return !isNonInteractive(); },
  isEnabled:  () => isNonInteractive() || isRemoteWorkspace(),
  load: () => Promise.resolve({ call: handleGoalText }),
};

type GoalReply =
  | { type: "text";  value: string }
  | { type: "query"; value: string; prompt: string };

async function handleGoalText /* UV3 */ (input: string, ctx: AppStateCtx): Promise<GoalReply> {
  const q = input.trim();

  // (1) Empty input → show current status
  if (q === "") {
    const goal = ctx.getAppState().activeGoal;
    if (!goal) return { type: "text", value: "No goal set. Usage: `/goal <condition>`" };

    const turns = goal.iterations === 0
      ? "not yet evaluated"
      : `${goal.iterations} ${pluralize(goal.iterations, "turn")}`;
    const tail = goal.lastReason ? `\n${formatLastCheckLine(goal.lastReason)}` : "";
    return { type: "text", value: `Goal active: ${goal.condition} (${turns})${tail}` };
  }

  // (2) clear/stop/off/reset/none/cancel → clear
  if (isClearKeyword(q)) {
    const cleared = clearGoal(ctx);
    return { type: "text", value: cleared === null ? "No goal set" : `Goal cleared: ${cleared}` };
  }

  // (3) Character limit
  if (q.length > MAX_CONDITION_LENGTH) {
    trackWithCode("goal_set", "too_long");
    return {
      type: "text",
      value: `Goal condition is limited to ${MAX_CONDITION_LENGTH} characters (got ${q.length})`,
    };
  }

  // (4) Set → on failure, return error text; on success, immediately trigger a query with runtime instructions
  const errMsg = setGoal(q, ctx);
  if (errMsg !== null) return { type: "text", value: errMsg };
  return { type: "query", value: `Goal set: ${q}`, prompt: buildGoalDirective(q) };
}

function isClearKeyword /* xD6 */ (s: string): boolean {
  return CLEAR_KEYWORDS.has(s.toLowerCase());
}

function formatLastCheckLine /* hjK */ (reason: string): string {
  return `Last check: ${firstLine(reason.trim())}`;
}

// Admission gate
function checkGoalGate /* Wu8 */ (): <ruby>message: string; code: &quot;policy_gate&quot;<rt>&quot;trust_gate&quot;</rt></ruby> | null {
  if (isHooksDisabledByPolicy()) return { message: POLICY_GATE_MESSAGE, code: "policy_gate" };
  if (!isNonInteractive() && !isWorkspaceTrusted()) {
    return { message: TRUST_GATE_MESSAGE, code: "trust_gate" };
  }
  return null;
}

// List all Stop hooks in this session that were "injected by /goal"
function listGoalStopHooks /* mD6 */ (state: AppState, sessionId: string): SessionHook[] {
  const out: SessionHook[] = [];
  for (const entry of getHooksForEvent(state, sessionId, "Stop").get("Stop") ?? []) <ruby>if (entry.matcher !== &quot;&quot;<rt>| entry.skillRoot !== undefined) continue; // user-mode goal marker
    for (const hook of entry.hooks) if (hook.type === &quot;prompt&quot;) out.push(hook);</rt></ruby>
  return out;
}

// Construct a sentinel attachment message (not rendered by the UI; only used as a resume anchor)
function makeGoalSentinelMessage /* EjK */ (met: boolean, condition: string): Message {
  return {
    type: "attachment",
    uuid: crypto.randomUUID(),
    timestamp: new Date().toISOString(),
    attachment: { type: "goal_status", met, sentinel: true, condition },
  };
}

// Set goal — returns null on success; returns error text to display to the user on failure
function setGoal /* YoH */ (condition: string, ctx: AppStateCtx): string | null {
  const gate = checkGoalGate();
  if (gate !== null) {
    trackWithCode("goal_set", gate.code);
    return gate.message;
  }

  const sessionId = getSessionId();

  // Only one goal hook is allowed at a time: clear the old one first
  for (const old of listGoalStopHooks(ctx.getAppState(), sessionId)) {
    ctx.sessionHooksRegistry.remove(sessionId, "Stop", old);
  }

  // ⭐ Inject condition as a prompt-type Stop hook
  ctx.sessionHooksRegistry.add(
    sessionId, "Stop", "",
    { type: "prompt", prompt: condition },
  );

  const goal: ActiveGoal = {
    condition,
    iterations: 0,
    setAt: Date.now(),
    tokensAtStart: getOutputTokenCount(),
  };
  ctx.setAppState(s => ({ ...s, activeGoal: goal }));
  ctx.applyMessageOp({ type: "append", messages: [makeGoalSentinelMessage(false, condition)] });

  track("tengu_stop_hook_added", { promptLength: condition.length, via: "goal" });
  showToast("goal_set");
  return null;
}

// Clear goal — returns null if none exists; otherwise returns the cleared condition
function clearGoal /* woH */ (ctx: AppStateCtx): string | null {
  const sessionId = getSessionId();
  const existing = listGoalStopHooks(ctx.getAppState(), sessionId);
  if (existing.length === 0) return null;

  const cleared = (existing[0] as { type: "prompt"; prompt: string }).prompt;
  for (const h of existing) ctx.sessionHooksRegistry.remove(sessionId, "Stop", h);

  ctx.setAppState(s => (s.activeGoal === undefined ? s : { ...s, activeGoal: undefined }));
  ctx.applyMessageOp({ type: "append", messages: [makeGoalSentinelMessage(true, cleared)] });

  track("tengu_stop_hook_removed", { via: "goal" });
  return cleared;
}

// The main loop consumes the message stream produced by the hook
for await (const frame of hookStream) {
  // Helper: maps the hook descriptor on the frame back to the currently registered hook
  // (Z = (b) => { … }, corresponding to cli.js L418182)
  const matchedHook = (frame.hook && hookStillRegistered(frame.hook)) ? frame.hook : undefined;

  // ── Success path: hook did not block → treat goal as achieved ───────────────
  if (frame.message?.type === "attachment") {
    const att = frame.message.attachment;
    const isStop = att.hookEvent === "Stop" || att.hookEvent === "SubagentStop";

    if (isStop && att.type === "hook_success" && matchedHook?.type === "prompt") {
      ctx.sessionHooksRegistry.remove(getSessionId(), "Stop", matchedHook);
      const cur = ctx.getAppState().activeGoal;

      if (cur?.condition === matchedHook.prompt) {
        const iterations = cur.iterations + 1;
        const durationMs = Date.now() - cur.setAt;
        const tokens     = getOutputTokenCount() - cur.tokensAtStart;

        yield { type: "active_goal", value: undefined };       // Clear state
        yield wrapAttachmentAsMessage({
          type: "goal_status",
          met: true,
          condition: matchedHook.prompt,
          reason: frame.stopReason,
          iterations, durationMs, tokens,
        });

        track("tengu_goal_achieved", {
          promptLength: matchedHook.prompt.length, iterations, durationMs, tokens,
        });
        showToast("goal_met");
      }
    }
  }

  // ── Failure path: hook blocks → not achieved; feed reason back to model to continue work ──
  if (frame.blockingError) {
    // This meta message is injected as a system prompt into the next LLM call
    const feedback = makeUserMessage({
      content: formatBlockingError(frame.blockingError),   // "Stop hook feedback:\n<reason>"
      isMeta: true,
    });
    yield feedback;

    const cur = ctx.getAppState().activeGoal;
    if (matchedHook?.type === "prompt" && cur?.condition === matchedHook.prompt) {
      yield {
        type: "active_goal",
        value: { ...cur, iterations: cur.iterations + 1, lastReason: frame.stopReason },
      };
      yield wrapAttachmentAsMessage({
        type: "goal_status",
        met: false,
        condition: matchedHook.prompt,
        reason: frame.stopReason,
      });
    }
  }
}

// Find the most recent unmet goal anchor (including sentinel and failure feedback)
export function findGoalToRestore /* _mK */ (messages: Message[] | undefined): string | null {
  if (!messages) return null;
  for (let i = messages.length - 1; i >= 0; i--) <ruby>const m = messages[i];
    if (m?.type !== &quot;attachment&quot;<rt>| m.attachment.type !== &quot;goal_status&quot;) continue;
    return m.attachment.met ? null : m.attachment.condition;</rt></ruby>
  return null;
}

export function restoreGoalFromTranscript /* Rg3 */ (
  messages: Message[],
  setAppState: AppStateSetter,
): void {
  const condition = findGoalToRestore(messages);
  const gate = condition !== null ? checkGoalGate() : null;
  if (gate !== null) trackWithCode("goal_set", gate.code);

  if (condition === null || gate !== null) {
    setAppState(s => (s.activeGoal === undefined ? s : { ...s, activeGoal: undefined }));
    return;
  }

  installHook(setAppState, getSessionId(), "Stop", "",
              { type: "prompt", prompt: condition });

  setAppState(s => ({
    ...s,
    activeGoal: {
      condition,
      iterations: 0,
      setAt: Date.now(),
      tokensAtStart: getOutputTokenCount(),
    },
  }));

  track("tengu_goal_restored_on_resume", { promptLength: condition.length });
}

## 10. Known Pitfalls / Correction Log

1. **`getOutputTokenCount` is output tokens only** — both `cur.tokensAtStart` and `goal_status.tokens` are “cumulative output tokens since the goal was set”; do not treat it as context usage.
2. **`isNonInteractive()` ≠ remote client** — it is simply `!g_.isInteractive`. The command display/enable rules are therefore: show by default in non-interactive mode; enable when non-interactive or in a remote workspace.
3. **Semantics of the trust gate** — note that `checkGoalGate` blocks only when `!isNonInteractive() && !isWorkspaceTrusted()`, i.e. it blocks `/goal` only “in interactive mode and when the workspace is untrusted”; non-interactive mode is not subject to the trust restriction.
4. **`/goal` coexists with other Stop hooks** — `listGoalStopHooks` uses `matcher === "" && skillRoot === undefined && type === "prompt"` to distinguish user-level goals, and will not clear Stop hooks injected by settings. When replicating this, this combination **must not be changed**.
5. **The sentinel must be stored in the transcript** — resume relies entirely on `findGoalToRestore` scanning `goal_status` attachments in reverse to decide whether to reattach the hook.

---