Keep the 1.x defaults that existing agents rely on

- model.constraints top_p, top_k and stop_sequences reach every provider
  whose API takes them; the others are reported by the run and by
  validate, which also warns that current Claude models reject sampling
  settings. The SDKs' constraints apply them too.
- TypeScript tool handlers get an AbortSignal again, aborted when the
  turn is stopped or the session ends.
- A plugin's settings reach its script tools and hooks as environment
  variables.
- compliance/regulatory-map.yaml and validation-schedule.yaml are summed
  up in the system prompt again.
- .sh tools and hooks run under sh unless their #! line names another
  shell; hooks get 10 seconds by default.
- Unknown gitagent.yaml keys are warnings instead of errors, and validate
  checks the file.
- README: what changed from 1.x; BLUEPRINT D28.

Author: chandan25809-lyzr

BLUEPRINT.md

@@ -131,6 +131,7 @@ Steps 4 to 9 repeat until the stop check accepts, the agent replies in conversat
 | D25 | Sub-agents are warned as their turns run low, may be given their own turn limit (up to 100), and come back marked partial when they run out | A review cut off mid-step wastes its whole cost; a warned one hands back what it found, and the lead re-runs only what is marked partial |
 | D26 | The `/tests` write guard applies to benchmark runs only | It protects graders' tests; in a user's project `/tests` is an ordinary path and a pattern such as `grep -v /tests/` must not be refused |
 | D27 | One throttle per session: `max_parallel` is a ceiling, a rate-limit refusal halves the window, ten clean calls in a row give a slot back | The right number of parallel calls depends on the account's rate limit, which gitagent cannot know; backing off beats retrying blindly, and the ceiling stays the user's choice |
+| D28 | Where a 1.x agent relies on a default, 1.x's default stays: `.sh` scripts under `sh`, 10-second hooks, every sampling setting a provider takes, plugin settings for plugin scripts, unknown `gitagent.yaml` keys as warnings; a setting that cannot be honoured is a warning, never silent | Existing agents must run unchanged, and a difference nobody is told about costs more than an old default |
 
 **Left out on purpose:** critics that rewrite answers; best-of-N on benchmarks; memory or learning during a scored run; automated rewriting of the harness; masking every turn; third-party multi-provider frameworks; a web interface; voice; remote sandboxes.
 

README.md

@@ -533,13 +533,24 @@ gitagent 3 replaces the TypeScript packages (1.x and 2.x) with one binary. What
 - **Agent folders.** `agent.yaml`, `SOUL.md`, `RULES.md`, `memory/`, `skills/`, `tools/`, `hooks/`, `schedules/`, `workflows/`, `agents/`, `config/` and `.env` are read as they were. 1.x settings such as `tools: [cli, read, write, memory]`, `runtime.timeout` and the 1.x `compliance` shape are accepted; `gitagent validate` points out the newer spelling as a warning, never an error.
 - **Hook scripts.** They get the same JSON and answer the same way; output that is not an answer, or a script that crashes, allows the action with a warning, as before. Only hooks marked `compliance: true` or `fail_open: false`, which are new, block in those cases.
 - **The CLI.** `gitagent`, `-p`, `-d`, `-m`, `-e`, `--repo`, `--pat`, `--session` and the REPL's slash commands work as before.
-- **SDK code.** `query()`, `tool()`, hooks, `steer()`, `abort()`, the message types and the `repo` option are the same; the TypeScript package now needs the `gitagent` binary installed.
+- **SDK code.** `query()`, `tool()`, hooks, `steer()`, `abort()`, the message types and the `repo` option are the same; the TypeScript package now needs the `gitagent` binary installed. A `tool()` handler still gets the arguments and an `AbortSignal`, and may return a string, 1.x's `{text, details}` or `{content, isError}`.
+- **Model settings.** `model.constraints` (`temperature`, `max_tokens`, `top_p`, `top_k`, `stop_sequences`) are sent to the providers whose API takes them. OpenAI's API has no `top_k` or stop sequences, so those two are ignored there with a warning. Current Claude models reject `temperature`, `top_p` and `top_k`, so the model call fails; `gitagent validate` warns about them.
+- **Scripts.** A declared tool or hook ending in `.sh` runs under `sh`, as before, unless its `#!` line names another shell. Hooks get 10 seconds unless `hooks.yaml` sets `timeout`. A plugin's settings reach its script tools and hooks as environment variables (see `plugin.yaml`'s `env` names, or `GITAGENT_PLUGIN_CONFIG` for all of them as JSON).
+- **Compliance files.** The frameworks named in `compliance/regulatory-map.yaml` and the checks in `compliance/validation-schedule.yaml` are added to the system prompt, as before.
 
-What changed: the binary must be installed (one `curl` line, above); `--voice` and the remote `--sandbox` are not part of gitagent 3; a plugin's `entry` JavaScript is not run (plugins contribute tools, skills, hooks and prompt text through files); usage errors exit with 2, provider failures with 3 and interrupts with 130 instead of 1.
+### What changed
+
+- **Install.** The binary must be installed (one `curl` line, above). The TypeScript and Python packages drive it.
+- **Exit codes.** 1.x exited with 1 for every error. gitagent 3 exits with 0 when a run ends (also when it runs out of turns or time), 2 for usage and setup errors, 3 when the model provider fails, and 130 when the run is stopped. A script that only checks for a nonzero code works as before; one that checks for exactly 1 needs updating.
+- **Not carried over.** `--voice`; the remote `--sandbox` (the binary prints a one-line note); a plugin's `entry` JavaScript (plugins contribute tools, skills, hooks and prompt text through files); the 1.x telemetry adapter (OTLP export replaces it).
+- **Task list.** 1.x's `task_tracker` kept a searchable list of tasks. gitagent 3's `todo` is a plain checklist the agent rewrites whole; the name `task_tracker` still maps to it in tool lists and hooks.
+- **Learning.** 1.x's online skill learning, which adjusted a skill's confidence after each use, is gone. Lessons are learned from finished runs instead (`learning: online` or `gitagent learn`, below) and go into the system prompt; skills are not changed.
+- **Sandbox on macOS.** The sandbox is Linux-only (Landlock and seccomp). On macOS the agent's shell runs without one, where 1.x's remote sandbox worked on every system.
+- **Scripts without a runtime.** 1.x ran every declared tool with `sh` unless `runtime` was set. gitagent 3 picks the interpreter by extension (`.py` with `python3`, `.js` with `node`, `.rb` with `ruby`, …), so such tools now run instead of failing.
 
 ## Configuration
 
-gitagent reads `gitagent.yaml` from `--config`, else the project folder (`gitagent.yaml` or `.gitagent/gitagent.yaml`), else `~/.gitagent/gitagent.yaml`. The other files are looked up one by one in the same places (the config's folder, the project's `.gitagent/`, then `~/.gitagent/`, then the project's and home `.claude/`), and fall back to the built-in versions:
+gitagent reads `gitagent.yaml` from `--config`, else the project folder (`gitagent.yaml` or `.gitagent/gitagent.yaml`), else `~/.gitagent/gitagent.yaml`. The other files are looked up one by one in the same places (the config's folder, the project's `.gitagent/`, then `~/.gitagent/`, then the project's and home `.claude/`), and fall back to the built-in versions. A key that `gitagent.yaml` does not know is ignored with a warning, and `gitagent validate` checks the project's copy.
 
 | Path | What it is |
 |---|---|

clients/typescript/README.md

@@ -46,6 +46,10 @@ console.log(q.result()?.outcome, q.costs());
   the session after the current turn.
 - `sessionId()`, `manifest()`, `messages()`, `result()` and `costs()`
   report on the session.
+- A tool's handler gets the arguments and an `AbortSignal`, aborted when
+  the turn is stopped or the session ends. It returns a string, `{content,
+  isError?}`, or 1.x's `{text, details?}` (the text becomes the result;
+  `details` is not sent to the model).
 - Hooks (`onSessionStart`, `preQuery`, `preToolUse`, `postToolUse`,
   `postToolFailure`, `fileChanged`,
   `postResponse`, `onError`) get the protocol's input and return `{action:

clients/typescript/src/index.ts

@@ -66,7 +66,11 @@ export interface GCToolDefinition {
   name: string;
   description: string;
   inputSchema: JsonObject;
-  handler: (args: JsonObject) => unknown | Promise<unknown>;
+  /**
+   * Returns a string, `{ content, isError? }`, or 1.x's `{ text, details? }`.
+   * `signal` is aborted when the running turn is stopped or the session ends.
+   */
+  handler: (args: JsonObject, signal: AbortSignal) => unknown | Promise<unknown>;
 }
 
 /** 1.x's local repo mode: the session works in a clone of `url` on a
@@ -97,8 +101,14 @@ export interface QueryOptions {
   sessionId?: string;
   resume?: boolean;
   mcpServers?: Record<string, JsonObject>;
-  /** `topP` and `topK` are accepted for 1.x code and ignored with a warning. */
-  constraints?: { temperature?: number; maxTokens?: number; topP?: number; topK?: number };
+  /** A setting the model's provider has no field for is ignored with a warning. */
+  constraints?: {
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    topK?: number;
+    stopSequences?: string[];
+  };
   tools?: GCToolDefinition[];
   hooks?: GCHooks;
   /** Hooks whose failure blocks the action; the others report the failure
@@ -194,6 +204,8 @@ export class Query implements AsyncIterable<GCMessage> {
   private readonly wakers: ((m: GCMessage | null) => void)[] = [];
   private readonly stderrLines: string[] = [];
   private readonly pending: string[] = [];
+  /** Given to client tools; aborted, and replaced, when a turn is stopped. */
+  private toolAbort = new AbortController();
   private promptsDone = false;
   private openTurn = false;
   /** A turn ended with nothing queued: the session ends when the caller
@@ -321,11 +333,13 @@ export class Query implements AsyncIterable<GCMessage> {
   /** Stops the running turn; the session stays open. */
   abort(): void {
     this.write({ type: "abort" });
+    this.stopTools();
   }
 
   /** Stops the running turn and ends the session. */
   kill(): void {
     this.write({ type: "kill" });
+    this.stopTools();
   }
 
   /** Ends the session after the current turn. */
@@ -357,9 +371,15 @@ export class Query implements AsyncIterable<GCMessage> {
     else this.waiting.push(message);
   }
 
+  private stopTools(): void {
+    this.toolAbort.abort();
+    this.toolAbort = new AbortController();
+  }
+
   private finish(): void {
     if (this.closed) return;
     this.closed = true;
+    this.toolAbort.abort();
     this.readyResolve(this.ready !== undefined);
     for (const w of this.wakers.splice(0)) w(null);
   }
@@ -431,7 +451,7 @@ export class Query implements AsyncIterable<GCMessage> {
       if (kind === "tool") {
         const t = this.tools.get(name);
         if (!t) return { content: `no handler for the tool ${name}`, isError: true };
-        const result = await t.handler(input);
+        const result = await t.handler(input, this.toolAbort.signal);
         if (result === undefined || result === null) return { content: "" };
         if (typeof result === "object") return result as JsonObject;
         return { content: String(result) };

crates/cli/src/ipc.rs

@@ -717,14 +717,31 @@ async fn session(cli: Cli, out: Out) -> i32 {
     if let Some(n) = c["maxTokens"].as_u64().or(c["max_tokens"].as_u64()) {
         s.spec.profile.max_output_tokens = n as u32;
     }
-    for key in ["topP", "topK"] {
-        if !c[key].is_null() {
-            out.system(
-                "warning",
-                format!("constraints.{key} is not supported; ignored"),
-                None,
-            );
-        }
+    let sampling = &mut s.spec.profile.sampling;
+    if let Some(p) = c["topP"].as_f64().or(c["top_p"].as_f64()) {
+        sampling.top_p = Some(p as f32);
+    }
+    if let Some(k) = c["topK"].as_u64().or(c["top_k"].as_u64()) {
+        sampling.top_k = Some(k as u32);
+    }
+    let stops = c.get("stopSequences").or(c.get("stop_sequences"));
+    if let Some(list) = stops.and_then(Value::as_array) {
+        sampling.stop_sequences = list
+            .iter()
+            .filter_map(Value::as_str)
+            .map(str::to_string)
+            .collect();
+    }
+    let family = s.spec.model.family();
+    for name in s.spec.profile.sampling.unsupported(family) {
+        out.system(
+            "warning",
+            format!(
+                "constraints.{name} is not supported by {} models; ignored",
+                family.as_str()
+            ),
+            None,
+        );
     }
     for (name, v) in o["mcpServers"].as_object().into_iter().flatten() {
         match gitagent_loader::mcp::parse(name, v, &s.work_dir) {

crates/core/src/lib.rs

@@ -505,6 +505,7 @@ pub async fn run(
             tools: tools.clone(),
             effort,
             temperature: spec.profile.temperature,
+            sampling: spec.profile.sampling.clone(),
             max_output_tokens: spec.profile.max_output_tokens,
             cache: cache_plan,
             server_masking,
@@ -2045,6 +2046,7 @@ impl Compaction<'_> {
             tools: self.tools.to_vec(),
             effort: self.spec.profile.effort,
             temperature: self.spec.profile.temperature,
+            sampling: self.spec.profile.sampling.clone(),
             max_output_tokens: self.spec.profile.max_output_tokens,
             cache: self.cache,
             server_masking: None,

crates/core/src/tests.rs

@@ -1452,6 +1452,7 @@ async fn declared_tools_marked_for_confirmation_always_ask() {
         timeout: Duration::from_secs(10),
         requires_confirmation: true,
         read_only: true,
+        env: Default::default(),
     });
     let script = "- tool_calls: [{name: pay, arguments: {note: nope}}]\n\
                   - tool_calls: [{name: pay, arguments: {note: approved}}]\n\
@@ -2178,6 +2179,7 @@ async fn a_workflow_tool_step_needs_the_same_approval_as_the_model() {
         timeout: Duration::from_secs(10),
         requires_confirmation: true,
         read_only: false,
+        env: Default::default(),
     });
     let provider = ScriptedProvider::from_yaml("- text: should not be asked\n").unwrap();
     let report = run_workflow(

crates/hooks/src/lifecycle.rs

@@ -209,6 +209,7 @@ impl AgentHooks {
         let mut cmd = Command::new(program);
         cmd.args(rest)
             .envs(self.env.iter().map(|(k, v)| (k, v)))
+            .envs(&hook.env)
             .current_dir(&self.root)
             .env("GITAGENT_AGENT_DIR", &self.root)
             .env("GITAGENT_SESSION_ID", session_id)
@@ -294,6 +295,7 @@ mod tests {
             compliance: false,
             fail_open,
             applies_to: Vec::new(),
+            env: Default::default(),
         }
     }
 

crates/learn/src/distill.rs

@@ -62,6 +62,7 @@ pub async fn propose(
         tools: Vec::new(),
         effort: spec.profile.effort,
         temperature: spec.profile.temperature,
+        sampling: spec.profile.sampling.clone(),
         max_output_tokens: spec.profile.max_output_tokens,
         cache: CachePlan::default(),
         server_masking: None,

crates/loader/src/agent_hooks.rs

@@ -18,14 +18,16 @@
 //! Script paths are relative to `hooks/` and must stay inside the agent
 //! directory. Problems are warnings and the hook is left out.
 
+use std::collections::BTreeMap;
 use std::path::Path;
 use std::time::Duration;
 
 use serde_json::Value;
 
 use crate::AgentDir;
 
-pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
+/// How long a hook may run when hooks.yaml gives no `timeout` (1.x's limit).
+pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(10);
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum HookEvent {
@@ -110,6 +112,8 @@ pub struct HookEntry {
     pub fail_open: bool,
     /// gitagent tool names this hook is for; empty means every tool.
     pub applies_to: Vec<String>,
+    /// More environment for its script: a plugin's settings.
+    pub env: BTreeMap<String, String>,
 }
 
 /// The hooks in an agent directory's `hooks/hooks.yaml`, in file order, and
@@ -188,6 +192,7 @@ pub fn entry_in(
         // As in 1.x, a failing plugin hook is a warning, not a block.
         fail_open: true,
         applies_to: Vec::new(),
+        env: BTreeMap::new(),
     })
 }
 
@@ -251,6 +256,7 @@ fn entry(event: HookEvent, v: &Value, root: &Path) -> Result<HookEntry, String>
             .and_then(Value::as_bool)
             .unwrap_or(!flag("compliance")),
         applies_to,
+        env: BTreeMap::new(),
     })
 }
 
@@ -290,7 +296,7 @@ mod tests {
         assert_eq!(a.timeout, Duration::from_secs(5));
         assert!(a.fail_open && !a.compliance);
         assert_eq!(a.applies_to, vec!["exec", "write_stdin", "write_file"]);
-        assert_eq!(a.command[0], "bash");
+        assert_eq!(a.command[0], "sh");
         let b = &hooks[1];
         assert_eq!(b.command[0], "python3");
         assert_eq!(b.timeout, DEFAULT_TIMEOUT);