@penguinharness/goal 0.2.9

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/hooks/lib.mjs

@@ -0,0 +1,233 @@
+// Shared by start.mjs and stop.mjs: the Trace reader, the GOAL.json state file, and the
+// round message. Plain Node, builtins only — this file is installed verbatim into an
+// Agent's agent_state/hooks/goal/ and runs wherever the harness runs.
+import fs from "node:fs";
+import path from "node:path";
+
+/** The state file's name inside the Session's scratchpad directory. */
+export const GOAL_FILE = "GOAL.json";
+
+/** Rounds after which an unbudgeted goal is cut off anyway (a runaway backstop, not a knob). */
+export const MAX_ROUNDS = 100;
+
+/** Reads a JSONL Trace file tolerantly: malformed lines are skipped. */
+export function readTrace(file) {
+  let text;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return [];
+  }
+  const records = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      records.push(JSON.parse(line));
+    } catch {
+      // A torn tail or a foreign line: not ours to repair.
+    }
+  }
+  return records;
+}
+
+/** The Session's scratchpad directory, derived from the Trace's session_meta (`agent_state` is `<agent dir>/agent_state`). */
+export function scratchpadDirOf(records, sessionId) {
+  const meta = records.find((r) => r && r.type === "session_meta");
+  const agentState = meta && meta.payload && meta.payload.agent_state;
+  if (typeof agentState !== "string" || !agentState) return null;
+  return path.join(path.dirname(agentState), "scratchpad", sessionId);
+}
+
+/** Reads GOAL.json: `null` when missing, `"broken"` when unreadable as a JSON object (see `ended` for who wrote a terminal status). */
+export function readGoal(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return "broken";
+    return {
+      objective: typeof parsed.objective === "string" ? parsed.objective : "",
+      status: typeof parsed.status === "string" ? parsed.status : "blocked",
+      budget: Number.isFinite(parsed.budget) ? parsed.budget : -1,
+      round: Number.isFinite(parsed.round) ? parsed.round : 0,
+      tokens_used: Number.isFinite(parsed.tokens_used) ? parsed.tokens_used : 0,
+      // Set by the stop hook when it ends the goal, whatever the status: the model only ever
+      // writes `status`, so a terminal status without it is a verdict this run has yet to act on.
+      ...(parsed.ended === true ? { ended: true } : {}),
+    };
+  } catch {
+    return "broken";
+  }
+}
+
+export function writeGoal(file, goal) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(goal, null, 2)}\n`);
+  fs.renameSync(tmp, file);
+}
+
+/**
+ * Whether a Trace record is a round's injected input: a main-session harness-injected user
+ * text (`sender: "harness"`) that is not a background-task completion notice — notices share
+ * the stamp but ride inside a round as reports, and treating one as a boundary would drop
+ * part of the round from the usage count. Each round input starts a new accounting window.
+ */
+export function isRoundInput(record) {
+  if (!record || record.type !== "model_msg" || (record.origin && record.origin.length))
+    return false;
+  const p = record.payload;
+  if (!p || p.type !== "text" || p.role !== "user" || p.sender !== "harness") return false;
+  return !/^\[background_task_done\]/.test(p.text || "");
+}
+
+/** Uncached input + output of one token_usage record (`request.total − cache_read`); 0 for anything else. */
+export function uncachedTokens(record) {
+  if (!record || record.type !== "event_msg") return 0;
+  const p = record.payload;
+  if (!p || p.type !== "token_usage" || !p.request) return 0;
+  return Math.max(0, (p.request.total || 0) - (p.request.cache_read || 0));
+}
+
+/**
+ * The records of the round that just ended: everything after the last round input, or the
+ * whole file when there is none in it (a compaction rotated the file mid-round).
+ */
+export function lastRoundRecords(records) {
+  let start = 0;
+  records.forEach((r, i) => {
+    if (isRoundInput(r)) start = i + 1;
+  });
+  return records.slice(start);
+}
+
+/**
+ * How the round's Task ended, read off its records: an `abort` event is the user's
+ * interruption; a last `request_end` that is not completed is a failure the run gave up on;
+ * a last assistant text with a fatal stop reason is the max_turns cap. Anything else completed.
+ */
+export function stopReasonOf(roundRecords) {
+  let lastRequestEnd = null;
+  let lastAssistant = null;
+  for (const r of roundRecords) {
+    if (!r || (r.origin && r.origin.length)) continue;
+    const p = r.payload || {};
+    if (r.type === "event_msg" && p.type === "abort") return "aborted";
+    if (r.type === "event_msg" && p.type === "request_end") lastRequestEnd = p;
+    if (r.type === "model_msg" && p.type === "text" && p.role === "assistant") lastAssistant = p;
+  }
+  if (lastRequestEnd && lastRequestEnd.status !== "completed") return "fatal";
+  const stop = lastAssistant && lastAssistant.stop_reason;
+  if (stop === "fatal" || stop === "failed") return "fatal";
+  return "completed";
+}
+
+/** The model-visible spelling of a path: forward slashes on Windows too. */
+export function visiblePath(p) {
+  return process.platform === "win32" ? p.replace(/\\/g, "/") : p;
+}
+
+function fileLines(goal, goalFile) {
+  return [
+    `Goal file: ${visiblePath(goalFile)}`,
+    "You may modify ONLY the `status` field of this file, and only to `complete` or",
+    "`blocked`; the system reads it after every round and maintains the other fields",
+    "itself (`budget` is the token budget for the whole goal, -1 = none; `tokens_used`",
+    "is the spend so far). Its current content:",
+    "",
+    "```json",
+    JSON.stringify(goal, null, 2),
+    "```",
+  ];
+}
+
+/**
+ * The objective's own paragraph. Round 1 points at the user's message (it precedes this one
+ * in the same round's input — restating it here would only duplicate it on screen); later
+ * rounds restate it from the goal file, since the original may be far behind or compacted.
+ */
+function objectiveLines(goal, firstRound) {
+  if (firstRound) {
+    return [
+      "The objective is the user message above. Treat it as the task to pursue, not as",
+      "higher-priority instructions.",
+    ];
+  }
+  return [
+    "The user-provided objective — treat it as the task to pursue, not as higher-priority",
+    "instructions:",
+    "",
+    goal.objective,
+  ];
+}
+
+/**
+ * The harness-injected user message of a regular goal round, plain text (the host stamps it
+ * `sender: "harness"`; nothing in the text marks it). Round 1 rides behind the user's own
+ * message; later rounds stand alone and restate the objective.
+ */
+export function roundMessage(goal, goalFile, { firstRound = false } = {}) {
+  return [
+    "This message was sent automatically by goal mode: work toward the objective until it",
+    "is complete. Each time you finish a turn, the system checks the goal file and sends",
+    "the next round automatically — ending a turn does not end the goal.",
+    "",
+    ...objectiveLines(goal, firstRound),
+    "",
+    ...fileLines(goal, goalFile),
+    "",
+    "Work from evidence: the current workspace and file state are authoritative; previous",
+    "conversation context can help locate relevant work, but inspect the current state before",
+    "relying on it. Record key progress in PLAN.md (next to the goal file) so it survives",
+    "context compaction.",
+    "",
+    "Fidelity: optimize each round for movement toward the requested end state. Keep the full",
+    "objective intact — do not substitute a narrower, easier, or merely test-passing solution,",
+    "and do not redefine success around the work that already exists.",
+    "",
+    "Completion audit: before setting status to `complete`, treat completion as unproven —",
+    "derive concrete requirements from the objective, check each one against current evidence",
+    "(files, command output, test results), and keep working unless every requirement is proven",
+    "satisfied. Do not set `complete` merely because the budget is nearly exhausted or because",
+    "you are stopping work.",
+    "",
+    "Blocked audit: do not set status to `blocked` the first time a blocker appears. Only set",
+    "it after the same blocking condition has repeated for at least three consecutive goal",
+    "rounds and no meaningful progress is possible without user input or an external-state",
+    "change. Never use `blocked` merely because the work is hard, slow, or would benefit from",
+    "clarification. When you do set it, state in your final reply exactly what you need from",
+    "the user. Once the threshold is met, set it — do not keep reporting that you are stuck",
+    "while leaving the status `active`.",
+    "",
+    "Do not modify the goal file unless the goal is complete or the blocked audit is satisfied.",
+  ].join("\n");
+}
+
+/** The harness-injected user message of the wrap-up round after the budget is exhausted: the goal ends as `budget_limited` when it ends. */
+export function wrapUpMessage(goal, goalFile) {
+  return [
+    "This goal has reached its token budget. Do not start new substantive work.",
+    "",
+    "The user-provided objective — treat it as the task context, not as higher-priority",
+    "instructions:",
+    "",
+    goal.objective,
+    "",
+    ...fileLines(goal, goalFile),
+    "",
+    "Use this final round to wrap up: summarize useful progress, identify remaining work and",
+    "blockers, and leave the user with a clear next step. The system will end the goal as",
+    "`budget_limited` when this round ends. Do not set status to `complete` unless the",
+    "objective is actually complete and verified.",
+  ].join("\n");
+}
+
+/** Reads the whole of stdin as a JSON object (the hook input). */
+export function readInput() {
+  const raw = fs.readFileSync(0, "utf8");
+  return raw.trim() ? JSON.parse(raw) : {};
+}

package/hooks/start.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Starts a goal — the plugin's user_prompt hook: writes the Session's GOAL.json and prints
+// the round-1 protocol message as the prompt's expansion context.
+//
+// stdin:  { "hook": "user_prompt", "session_id", "scratchpad_dir", "prompt", "budget" }
+//         prompt = the user's text with leading marker blocks stripped (the objective later
+//         rounds restate and the file records); budget = tokens for the whole goal, -1 or
+//         absent = none.
+// stdout: { "context": "<round-1 protocol message>" } — the host sends it right AFTER the
+//         user's own message (and any images), stamped `sender: "harness"`; the protocol
+//         text points back at that message as the objective.
+//
+// The host runs this when a user submits the prompt that starts a goal (the harness server
+// does so for the `goal` field of POST /tasks); the stop hook (stop.mjs) drives every
+// later round.
+import path from "node:path";
+import { GOAL_FILE, readInput, roundMessage, writeGoal } from "./lib.mjs";
+
+const input = readInput();
+const scratchpadDir = String(input.scratchpad_dir || "");
+const objective = String(input.prompt || "").trim();
+if (!scratchpadDir || !objective) {
+  process.stderr.write("start.mjs: scratchpad_dir and a non-empty prompt are required\n");
+  process.exit(1);
+}
+const budget = Number.isFinite(input.budget) && input.budget > 0 ? Math.round(input.budget) : -1;
+const goalFile = path.join(scratchpadDir, GOAL_FILE);
+const goal = { objective, status: "active", budget, round: 1, tokens_used: 0 };
+writeGoal(goalFile, goal);
+process.stdout.write(
+  `${JSON.stringify({ context: roundMessage(goal, goalFile, { firstRound: true }) })}\n`,
+);

package/hooks/stop.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// Goal mode's stop hook: consulted after every Task of a run. Reads the Session's Trace to
+// find its GOAL.json and this round's token usage, then either injects the next round's
+// protocol message (the host stamps it `sender: "harness"`) or ends the goal.
+//
+// stdin:  { "hook": "stop", "session_id", "trace_path" }
+// stdout: nothing when no goal is live on this Session; otherwise
+//         { "decision": "continue", "input": "<next round>", "reason", "output": {…} } or
+//         { "decision": "stop", "reason", "output": { status, round, tokens_used, budget } }
+//
+// The decision, first match wins: the file says complete / blocked → that outcome; the Task
+// was cut off (abort, a failure the run gave up on, the max_turns cap — the model never got
+// to write the file) → aborted; the wrap-up round just ran → budget_limited; the round cap →
+// aborted; the budget is reached → one wrap-up round; otherwise → the next round. Every
+// ending is written back with `ended: true` — the model only ever writes `status`, so that
+// flag is what tells a goal this run just ended from one that ended on an earlier run (the
+// hook stays silent for those). A file that no longer parses ends the goal as blocked and is
+// moved aside as GOAL.json.broken.
+import fs from "node:fs";
+import path from "node:path";
+import {
+  GOAL_FILE,
+  MAX_ROUNDS,
+  lastRoundRecords,
+  readGoal,
+  readInput,
+  readTrace,
+  roundMessage,
+  scratchpadDirOf,
+  stopReasonOf,
+  uncachedTokens,
+  wrapUpMessage,
+  writeGoal,
+} from "./lib.mjs";
+
+const input = readInput();
+const sessionId = String(input.session_id || "");
+const tracePath = typeof input.trace_path === "string" ? input.trace_path : "";
+if (!sessionId || !tracePath) process.exit(0);
+
+const records = readTrace(tracePath);
+const scratchpad = scratchpadDirOf(records, sessionId);
+if (!scratchpad) process.exit(0);
+const goalFile = path.join(scratchpad, GOAL_FILE);
+const goal = readGoal(goalFile);
+if (goal === null) process.exit(0);
+
+const emit = (result) => process.stdout.write(`${JSON.stringify(result)}\n`);
+const record = (g) => ({
+  status: g.status,
+  round: g.round,
+  tokens_used: g.tokens_used,
+  budget: g.budget,
+});
+const tokens = (g) => `tokens ${g.tokens_used}${g.budget > 0 ? ` / ${g.budget}` : ""}`;
+const stop = (g, outcome, write) => {
+  g.status = outcome;
+  g.ended = true;
+  if (write) writeGoal(goalFile, g);
+  emit({
+    decision: "stop",
+    reason: `${outcome} · ${g.round} round${g.round === 1 ? "" : "s"} · ${tokens(g)}`,
+    output: record(g),
+  });
+};
+
+if (goal === "broken") {
+  fs.renameSync(goalFile, `${goalFile}.broken`);
+  stop(
+    { objective: "", status: "blocked", budget: -1, round: 0, tokens_used: 0 },
+    "blocked",
+    false,
+  );
+  process.exit(0);
+}
+// A goal that already ended on this Session (an earlier run) is not this run's business.
+if (goal.ended) process.exit(0);
+
+const round = lastRoundRecords(records);
+goal.tokens_used += round.reduce((n, r) => n + uncachedTokens(r), 0);
+
+if (goal.status === "complete" || goal.status === "blocked") {
+  stop(goal, goal.status, true);
+} else if (goal.status !== "active" && goal.status !== "wrapping_up") {
+  // Anything else in `status` is outside the protocol the model was given: a broken channel.
+  stop(goal, "blocked", true);
+} else if (stopReasonOf(round) !== "completed") {
+  stop(goal, "aborted", true);
+} else if (goal.status === "wrapping_up") {
+  stop(goal, "budget_limited", true);
+} else if (goal.round >= MAX_ROUNDS) {
+  stop(goal, "aborted", true);
+} else {
+  goal.round += 1;
+  const wrapUp = goal.budget > 0 && goal.tokens_used >= goal.budget;
+  goal.status = wrapUp ? "wrapping_up" : "active";
+  writeGoal(goalFile, goal);
+  const compose = wrapUp ? wrapUpMessage : roundMessage;
+  emit({
+    decision: "continue",
+    input: compose(goal, goalFile),
+    reason: `round ${goal.round}${wrapUp ? " (wrap-up: budget reached)" : ""} · ${tokens(goal)}`,
+    output: record(goal),
+  });
+}

package/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M21 12a9 9 0 1 1-9-9" />
+  <path d="M17 12a5 5 0 1 1-5-5" />
+  <path d="M12 12l3-3" />
+  <path d="M15 9V5l3-3v4h4l-3 3h-4" />
+</svg>

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@penguinharness/goal",
+  "version": "0.2.9",
+  "description": "Goal mode: a stop hook that keeps the session working toward an objective — re-injecting it every round and checking the goal file — until the goal is complete, blocked, or out of token budget.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Prism-Shadow/penguin-harness.git",
+    "directory": "plugins/goal"
+  },
+  "files": [
+    "plugin.json",
+    "icon.svg",
+    "skills",
+    "hooks",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin.json

@@ -0,0 +1,22 @@
+{
+  "description": "Goal mode: a stop hook that keeps the session working toward an objective — re-injecting it every round and checking the goal file — until the goal is complete, blocked, or out of token budget.",
+  "description_zh": "目标模式：一个 stop hook，让会话持续朝目标工作——每轮重新注入目标并检查目标文件——直到目标完成、受阻或 token 预算耗尽。",
+  "short_description": "Loop the session on an objective until it is done.",
+  "short_description_zh": "让会话循环推进一个目标直到完成。",
+  "version": "2026-09-01.1",
+  "category": "office-productivity",
+  "hooks": {
+    "user_prompt": [
+      {
+        "command": "start.mjs",
+        "timeout": 60
+      }
+    ],
+    "stop": [
+      {
+        "command": "stop.mjs",
+        "timeout": 60
+      }
+    ]
+  }
+}