@blogic-cz/agent-tools 0.1.0 → 0.2.0

package/README.md

@@ -15,6 +15,14 @@ These tools wrap each CLI with:
 
 ## Installation
 
+> **Recommended:** Copy the repo URL and tell your AI agent to install it. The agent will set up everything — dependencies, config file, credential guard — in the right places for your project.
+>
+> ```
+> Install @blogic-cz/agent-tools from https://github.com/blogic-cz/agent-tools and set it up for this project.
+> ```
+
+### Manual installation
+
 ```bash
 bun add @blogic-cz/agent-tools
 ```
@@ -38,6 +46,7 @@ ls src/  # gh-tool/ db-tool/ k8s-tool/ az-tool/ logs-tool/ session-tool/ credent
 ```json5
 {
   $schema: "https://raw.githubusercontent.com/blogic-cz/agent-tools/main/schemas/agent-tools.schema.json",
+  defaultEnvironment: "test", // optional: any string (e.g. "local", "test", "prod")
   kubernetes: {
     default: {
       clusterId: "your-cluster-id",
@@ -56,9 +65,14 @@ ls src/  # gh-tool/ db-tool/ k8s-tool/ az-tool/ logs-tool/ session-tool/ credent
 3. Run tools:
 
 ```bash
-npx agent-tools-gh pr list
-npx agent-tools-k8s kubectl -n prod-ns get pods
-npx agent-tools-logs list --env local
+bunx agent-tools-gh pr status
+bunx agent-tools-k8s kubectl --env test --cmd "get pods"
+bunx agent-tools-logs list --env local
+```
+
+```bash
+bunx agent-tools-gh pr review-triage   # interactive summary of PR feedback
+bunx agent-tools-k8s pods --env test   # list pods (structured command)
 ```
 
 4. Hook up the credential guard in your agent config (Claude Code, OpenCode, etc.):
@@ -71,14 +85,14 @@ export default { handleToolExecuteBefore };
 
 ## Tools
 
-| Binary                | Description                                                     |
-| --------------------- | --------------------------------------------------------------- |
-| `agent-tools-gh`      | GitHub CLI wrapper — PR management, issues, workflows           |
-| `agent-tools-db`      | Database query tool — SQL execution, schema introspection       |
-| `agent-tools-k8s`     | Kubernetes tool — kubectl with config-driven context resolution |
-| `agent-tools-az`      | Azure DevOps tool — pipelines, builds, repos                    |
-| `agent-tools-logs`    | Application logs — read local and remote (k8s pod) logs         |
-| `agent-tools-session` | OpenCode session browser — list, read, search sessions          |
+| Binary                | Description                                                                                                      |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `agent-tools-gh`      | GitHub CLI wrapper — PR management, issues, workflows, composite commands (`review-triage`, `reply-and-resolve`) |
+| `agent-tools-db`      | Database query tool — SQL execution, schema introspection                                                        |
+| `agent-tools-k8s`     | Kubernetes tool — kubectl wrapper + structured commands (`pods`, `logs`, `describe`, `exec`, `top`)              |
+| `agent-tools-az`      | Azure DevOps tool — pipelines, builds, repos                                                                     |
+| `agent-tools-logs`    | Application logs — read local and remote (k8s pod) logs                                                          |
+| `agent-tools-session` | OpenCode session browser — list, read, search sessions                                                           |
 
 All tools support `--help` for full usage documentation.
 
@@ -86,6 +100,16 @@ All tools support `--help` for full usage documentation.
 
 Config is loaded from `agent-tools.json5` (or `agent-tools.json`) by walking up from the current working directory. Missing config = zero-config mode (works for `gh-tool`; others require config).
 
+### Global Settings
+
+Use `defaultEnvironment` to set the default target for tools that support environments (k8s-tool, logs-tool, db-tool). Passing `--env` explicitly always takes precedence. Note that tools will block implicit production access if `defaultEnvironment` is set to `"prod"`.
+
+```json5
+{
+  defaultEnvironment: "test",
+}
+```
+
 ### IDE Autocompletion
 
 Add `$schema` to your config file:
@@ -110,8 +134,8 @@ Each tool section supports multiple named profiles. Select with `--profile <name
 ```
 
 ```bash
-npx agent-tools-az pipeline list                    # uses "default" profile
-npx agent-tools-az pipeline list --profile legacy   # uses "legacy" profile
+bunx agent-tools-az cmd --cmd "pipelines list"                    # uses "default" profile
+bunx agent-tools-az cmd --cmd "pipelines list" --profile legacy   # uses "legacy" profile
 ```
 
 **Profile resolution:** `--profile` flag > auto-select (single profile) > `"default"` key > error.
@@ -120,34 +144,38 @@ npx agent-tools-az pipeline list --profile legacy   # uses "legacy" profile
 
 See [`examples/agent-tools.json5`](./examples/agent-tools.json5) for a complete example with all options documented.
 
-## Environment Variables
+## Authentication
 
-Secrets are **never** stored in the config file. Use environment variables:
+Each tool uses its own auth method — no unified token store:
 
-| Variable           | Used By | Description                                               |
-| ------------------ | ------- | --------------------------------------------------------- |
-| `AGENT_TOOLS_DB_*` | db-tool | DB passwords (name defined by `passwordEnvVar` in config) |
-| `GITHUB_TOKEN`     | gh-tool | GitHub API token (falls back to `gh` CLI auth)            |
+| Tool        | Auth Method                                                                                  |
+| ----------- | -------------------------------------------------------------------------------------------- |
+| `gh-tool`   | `gh` CLI session (`gh auth login`) or `GITHUB_TOKEN` env var                                 |
+| `k8s-tool`  | Existing kubectl context (kubeconfig). Cluster ID from config resolves context automatically |
+| `az-tool`   | `az` CLI session (`az login`)                                                                |
+| `db-tool`   | Password from env var defined by `passwordEnvVar` in config (e.g. `AGENT_TOOLS_DB_PASSWORD`) |
+| `logs-tool` | No auth — reads local files or uses k8s-tool for remote access                               |
 
-### Setting up credentials
+Secrets are **never** stored in the config file. The `db-tool` config references env var **names** only:
 
-The config file only references env var **names** (via `passwordEnvVar`), never actual secrets. Set the values in your shell:
+```json5
+{
+  databases: {
+    default: {
+      passwordEnvVar: "AGENT_TOOLS_DB_PASSWORD", // tool reads process.env[passwordEnvVar] at runtime
+    },
+  },
+}
+```
 
-**macOS / Linux** — add to `~/.zshrc` or `~/.bashrc`:
+Set the values in your shell:
 
 ```bash
 export AGENT_TOOLS_DB_PASSWORD="your-password"
 export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
 ```
 
-**Windows** — PowerShell (persistent, user-level):
-
-```powershell
-[Environment]::SetEnvironmentVariable("AGENT_TOOLS_DB_PASSWORD", "your-password", "User")
-[Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_xxxxxxxxxxxx", "User")
-```
-
-Restart your terminal after adding env vars. The credential guard ensures these values never leak into agent output.
+The credential guard ensures these values never leak into agent output.
 
 ## Credential Guard
 
@@ -231,6 +259,16 @@ Use the `credentialGuard` config section to extend built-in defaults (arrays are
 
 The guard source is at [`src/credential-guard/index.ts`](./src/credential-guard/index.ts). Fork the repo, adjust patterns, submit a PR: https://github.com/blogic-cz/agent-tools
 
+## Development & Evaluation
+
+### Run Evaluation Harness
+
+The evaluation harness runs a set of test cases against the tools to ensure quality and reliability:
+
+```bash
+bun run tests/eval/run.ts
+```
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, and sessions",
   "keywords": [
     "agent",
@@ -38,6 +38,9 @@
     "./credential-guard": "./src/credential-guard/index.ts",
     "./config": "./src/config/index.ts"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "check": "bun check.ts",
     "check:ci": "bun check.ts ci",
@@ -61,9 +64,6 @@
     "typescript": "5.9.3",
     "vitest": "^4.0.18"
   },
-  "publishConfig": {
-    "access": "public"
-  },
   "engines": {
     "bun": ">=1.0.0"
   }

package/schemas/agent-tools.schema.json

@@ -49,6 +49,10 @@
     "credentialGuard": {
       "description": "Global credential guard configuration merged with built-in defaults.",
       "$ref": "#/definitions/CredentialGuardConfig"
+    },
+    "defaultEnvironment": {
+      "description": "Optional default environment name used by tools when no --env flag is provided.",
+      "type": "string"
     }
   },
   "definitions": {

package/src/az-tool/build.ts

@@ -54,6 +54,7 @@ export const getBuildTimeline = Effect.fn("Build.getBuildTimeline")(function* (b
         new AzParseError({
           message: `Failed to parse build timeline: ${String(e)}`,
           rawOutput: JSON.stringify(result).slice(0, 500),
+          hint: "The Azure DevOps API returned an unexpected response format for build timeline",
         }),
     ),
   );
@@ -107,6 +108,7 @@ export const getBuildLogs = Effect.fn("Build.getBuildLogs")(function* (buildId:
         new AzParseError({
           message: `Failed to parse build logs: ${String(e)}`,
           rawOutput: JSON.stringify(result).slice(0, 500),
+          hint: "The Azure DevOps API returned an unexpected response format for build logs",
         }),
     ),
   );
@@ -143,6 +145,7 @@ export const getBuildLogContent = Effect.fn("Build.getBuildLogContent")(function
         new AzParseError({
           message: `Failed to parse log content: ${String(e)}`,
           rawOutput: String(result).slice(0, 500),
+          hint: "The Azure DevOps API returned an unexpected format for log content",
         }),
     ),
   );
@@ -245,6 +248,7 @@ export const listPipelineRuns = Effect.fn("Build.listPipelineRuns")(function* (o
       new AzParseError({
         message: "Failed to parse JSON from pipeline runs output",
         rawOutput: rawResult.slice(0, 500),
+        hint: "The az CLI returned non-JSON output. Check that the command ran successfully.",
       }),
   });
 
@@ -268,6 +272,7 @@ export const listPipelineRuns = Effect.fn("Build.listPipelineRuns")(function* (o
         new AzParseError({
           message: `Failed to parse pipeline runs: ${String(e)}`,
           rawOutput: rawResult.slice(0, 500),
+          hint: "The Azure DevOps API returned an unexpected response format for pipeline runs",
         }),
     ),
   );

package/src/az-tool/errors.ts

@@ -3,6 +3,9 @@ import { Schema } from "effect";
 export class AzSecurityError extends Schema.TaggedErrorClass<AzSecurityError>()("AzSecurityError", {
   message: Schema.String,
   command: Schema.String,
+  hint: Schema.optionalKey(Schema.String),
+  nextCommand: Schema.optionalKey(Schema.String),
+  retryable: Schema.optionalKey(Schema.Boolean),
 }) {}
 
 export class AzCommandError extends Schema.TaggedErrorClass<AzCommandError>()("AzCommandError", {
@@ -10,17 +13,26 @@ export class AzCommandError extends Schema.TaggedErrorClass<AzCommandError>()("A
   command: Schema.String,
   exitCode: Schema.optionalKey(Schema.Number),
   stderr: Schema.optionalKey(Schema.String),
+  hint: Schema.optionalKey(Schema.String),
+  nextCommand: Schema.optionalKey(Schema.String),
+  retryable: Schema.optionalKey(Schema.Boolean),
 }) {}
 
 export class AzTimeoutError extends Schema.TaggedErrorClass<AzTimeoutError>()("AzTimeoutError", {
   message: Schema.String,
   command: Schema.String,
   timeoutMs: Schema.Number,
+  hint: Schema.optionalKey(Schema.String),
+  nextCommand: Schema.optionalKey(Schema.String),
+  retryable: Schema.optionalKey(Schema.Boolean),
 }) {}
 
 export class AzParseError extends Schema.TaggedErrorClass<AzParseError>()("AzParseError", {
   message: Schema.String,
   rawOutput: Schema.String,
+  hint: Schema.optionalKey(Schema.String),
+  nextCommand: Schema.optionalKey(Schema.String),
+  retryable: Schema.optionalKey(Schema.Boolean),
 }) {}
 
 export type AzError = AzSecurityError | AzCommandError | AzTimeoutError | AzParseError;

package/src/az-tool/index.ts

@@ -11,13 +11,111 @@ import {
   getBuildLogs,
   getBuildTimeline,
 } from "./build";
-import { AzCommandError } from "./errors";
-import { extractOptionValue } from "./extract-option-value";
 import { AzService, AzServiceLayer } from "./service";
 import { ConfigServiceLayer } from "../config";
 
-const mainCommand = Command.make(
-  "az-tool",
+// ---------------------------------------------------------------------------
+// Common flags shared across build subcommands
+// ---------------------------------------------------------------------------
+
+const commonBuildFlags = {
+  format: formatOption,
+  profile: Flag.optional(Flag.string("profile")).pipe(
+    Flag.withDescription("Azure DevOps profile name (from agent-tools config)"),
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Build subcommands
+// ---------------------------------------------------------------------------
+
+const buildTimelineCommand = Command.make(
+  "timeline",
+  {
+    ...commonBuildFlags,
+    buildId: Flag.integer("build-id").pipe(Flag.withDescription("Build ID")),
+  },
+  ({ buildId, format, profile: _profile }) =>
+    Effect.gen(function* () {
+      const result = yield* getBuildTimeline(buildId);
+      yield* Console.log(formatAny(result, format));
+    }),
+).pipe(Command.withDescription("Get build timeline with all records (jobs, stages, tasks)"));
+
+const buildFailedJobsCommand = Command.make(
+  "failed-jobs",
+  {
+    ...commonBuildFlags,
+    buildId: Flag.integer("build-id").pipe(Flag.withDescription("Build ID")),
+  },
+  ({ buildId, format, profile: _profile }) =>
+    Effect.gen(function* () {
+      const failedJobs = yield* findFailedJobs(buildId);
+      yield* Console.log(formatAny({ buildId, failedJobs }, format));
+    }),
+).pipe(Command.withDescription("Find failed or canceled jobs in a build"));
+
+const buildLogsCommand = Command.make(
+  "logs",
+  {
+    ...commonBuildFlags,
+    buildId: Flag.integer("build-id").pipe(Flag.withDescription("Build ID")),
+  },
+  ({ buildId, format, profile: _profile }) =>
+    Effect.gen(function* () {
+      const result = yield* getBuildLogs(buildId);
+      yield* Console.log(formatAny(result, format));
+    }),
+).pipe(Command.withDescription("Get list of build logs"));
+
+const buildLogContentCommand = Command.make(
+  "log-content",
+  {
+    ...commonBuildFlags,
+    buildId: Flag.integer("build-id").pipe(Flag.withDescription("Build ID")),
+    logId: Flag.integer("log-id").pipe(Flag.withDescription("Log ID")),
+  },
+  ({ buildId, format, logId, profile: _profile }) =>
+    Effect.gen(function* () {
+      const content = yield* getBuildLogContent(buildId, logId);
+      yield* Console.log(formatAny({ buildId, logId, content }, format));
+    }),
+).pipe(Command.withDescription("Get specific log content by log ID"));
+
+const buildSummaryCommand = Command.make(
+  "summary",
+  {
+    ...commonBuildFlags,
+    buildId: Flag.integer("build-id").pipe(Flag.withDescription("Build ID")),
+  },
+  ({ buildId, format, profile: _profile }) =>
+    Effect.gen(function* () {
+      const summary = yield* getBuildJobSummary(buildId);
+      yield* Console.log(formatAny({ buildId, summary }, format));
+    }),
+).pipe(Command.withDescription("Get job summaries with duration and status information"));
+
+// ---------------------------------------------------------------------------
+// Build parent command
+// ---------------------------------------------------------------------------
+
+const buildCommand = Command.make("build", {}).pipe(
+  Command.withDescription("Build helpers for Azure DevOps pipelines"),
+  Command.withSubcommands([
+    buildTimelineCommand,
+    buildFailedJobsCommand,
+    buildLogsCommand,
+    buildLogContentCommand,
+    buildSummaryCommand,
+  ]),
+);
+
+// ---------------------------------------------------------------------------
+// Raw command subcommand (preserves existing --cmd behavior)
+// ---------------------------------------------------------------------------
+
+const cmdCommand = Command.make(
+  "cmd",
   {
     profile: Flag.optional(Flag.string("profile")).pipe(
       Flag.withDescription("Azure DevOps profile name (from agent-tools config)"),
@@ -36,20 +134,12 @@ const mainCommand = Command.make(
     Effect.gen(function* () {
       const projectName = project ? Option.getOrUndefined(project) : undefined;
 
-      // Handle dry-run mode
       if (dryRun) {
         const fullCommand = `az ${cmd}`;
         yield* Console.log(`[DRY-RUN] Would execute: ${fullCommand}`);
         return;
       }
 
-      const buildHelperResult = yield* runBuildHelperCommand(cmd);
-
-      if (buildHelperResult !== undefined) {
-        yield* Console.log(formatAny(buildHelperResult, format));
-        return;
-      }
-
       const az = yield* AzService;
 
       const startTime = Date.now();
@@ -68,16 +158,35 @@ const mainCommand = Command.make(
       );
     }),
 ).pipe(
+  Command.withDescription(
+    `Execute raw az CLI commands directly.
+
+EXAMPLES:
+  agent-tools-az cmd --cmd "pipelines list"
+  agent-tools-az cmd --cmd "repos list" --project my-project
+  agent-tools-az cmd --cmd "pipelines runs list --output json"`,
+  ),
+);
+
+// ---------------------------------------------------------------------------
+// Main command with subcommands
+// ---------------------------------------------------------------------------
+
+const mainCommand = Command.make("az-tool", {}).pipe(
   Command.withDescription(
     `Azure CLI Tool for Coding Agents (READ-ONLY)
 
-Supports raw az wrapper via --cmd and convenience build helpers:
-  --cmd "build timeline --build-id 123"
-  --cmd "build failed-jobs --build-id 123"
-  --cmd "build logs --build-id 123"
-  --cmd "build log-content --build-id 123 --log-id 45"
-  --cmd "build summary --build-id 123"`,
+Typed build subcommands:
+  az-tool build timeline --build-id 123
+  az-tool build failed-jobs --build-id 123
+  az-tool build logs --build-id 123
+  az-tool build log-content --build-id 123 --log-id 45
+  az-tool build summary --build-id 123
+
+Raw az wrapper:
+  az-tool cmd --cmd "pipelines list"`,
   ),
+  Command.withSubcommands([buildCommand, cmdCommand]),
 );
 
 const cli = Command.run(mainCommand, {
@@ -94,88 +203,3 @@ const program = cli.pipe(Effect.provide(MainLayer), Effect.tapCause(renderCauseT
 BunRuntime.runMain(program, {
   disableErrorReporting: true,
 });
-
-function runBuildHelperCommand(cmd: string) {
-  return Effect.gen(function* () {
-    const words = cmd.trim().split(/\s+/);
-
-    if (words[0] !== "build") {
-      return undefined;
-    }
-
-    const action = words[1];
-    if (!action) {
-      return yield* invalidBuildCommand(
-        cmd,
-        "Missing build action. Use one of: timeline, failed-jobs, logs, log-content, summary",
-      );
-    }
-
-    const buildId = yield* parseRequiredIntOption(words, "--build-id", cmd);
-
-    if (action === "timeline") {
-      const timeline = yield* getBuildTimeline(buildId);
-      return timeline;
-    }
-
-    if (action === "failed-jobs") {
-      const failedJobs = yield* findFailedJobs(buildId);
-      return { buildId, failedJobs };
-    }
-
-    if (action === "logs") {
-      const logs = yield* getBuildLogs(buildId);
-      return logs;
-    }
-
-    if (action === "log-content") {
-      const logId = yield* parseRequiredIntOption(words, "--log-id", cmd);
-      const content = yield* getBuildLogContent(buildId, logId);
-      return {
-        buildId,
-        logId,
-        content,
-      };
-    }
-
-    if (action === "summary") {
-      const summary = yield* getBuildJobSummary(buildId);
-      return { buildId, summary };
-    }
-
-    return yield* invalidBuildCommand(
-      cmd,
-      `Unknown build action '${action}'. Use one of: timeline, failed-jobs, logs, log-content, summary`,
-    );
-  });
-}
-
-function invalidBuildCommand(cmd: string, message: string) {
-  return Effect.fail(
-    new AzCommandError({
-      message,
-      command: cmd,
-      exitCode: 2,
-      stderr: message,
-    }),
-  );
-}
-
-function parseRequiredIntOption(args: readonly string[], optionName: string, cmd: string) {
-  return Effect.gen(function* () {
-    const rawValue = extractOptionValue(args, optionName);
-    if (!rawValue) {
-      return yield* invalidBuildCommand(cmd, `Missing required option ${optionName}`);
-    }
-
-    const parsedValue = Number.parseInt(rawValue, 10);
-    if (Number.isNaN(parsedValue)) {
-      return yield* invalidBuildCommand(
-        cmd,
-        `Option ${optionName} must be an integer, received '${rawValue}'`,
-      );
-    }
-
-    return parsedValue;
-  });
-}

package/src/az-tool/service.ts

@@ -32,7 +32,7 @@ export class AzService extends ServiceMap.Service<
           message: "No Azure configuration found. Add an 'azure' section to agent-tools.json5.",
           command: "unknown",
           exitCode: -1,
-          stderr: undefined,
+          hint: "Create or update agent-tools.json5 with an 'azure' section containing organization and defaultProject",
         });
         return {
           runCommand: (_cmd: string, _project?: string) => Effect.fail(noConfigError),
@@ -69,7 +69,9 @@ export class AzService extends ServiceMap.Service<
                 message: `Command execution failed: ${platformError.message}`,
                 command: fullCommand,
                 exitCode: -1,
-                stderr: undefined,
+                hint: "Check that the az CLI is installed and authenticated",
+                nextCommand: "az login",
+                retryable: true,
               }),
           ),
         );
@@ -87,6 +89,7 @@ export class AzService extends ServiceMap.Service<
           return yield* new AzSecurityError({
             message: securityCheck.reason ?? "Command not allowed",
             command: cmd,
+            hint: "Only read-only az devops commands are allowed. Use build helpers for common operations.",
           });
         }
 
@@ -125,6 +128,8 @@ export class AzService extends ServiceMap.Service<
             message: `Command timed out after ${azConfig.timeoutMs ?? 60000}ms`,
             command: fullCommand,
             timeoutMs: azConfig.timeoutMs ?? 60000,
+            retryable: true,
+            hint: "The command took too long. Retry or increase timeoutMs in azure config.",
           });
         }
 
@@ -148,6 +153,7 @@ export class AzService extends ServiceMap.Service<
           return yield* new AzSecurityError({
             message: securityCheck.reason ?? "Invoke not allowed",
             command: `invoke --area ${params.area} --resource ${params.resource}`,
+            hint: "Only allowed invoke areas/resources can be used. Check az-tool security config.",
           });
         }
 
@@ -183,6 +189,8 @@ export class AzService extends ServiceMap.Service<
             message: `Invoke timed out after ${azConfig.timeoutMs ?? 60000}ms`,
             command: fullCommand,
             timeoutMs: azConfig.timeoutMs ?? 60000,
+            retryable: true,
+            hint: "The invoke took too long. Retry or increase timeoutMs in azure config.",
           });
         }
 
@@ -203,6 +211,7 @@ export class AzService extends ServiceMap.Service<
             new AzParseError({
               message: `Failed to parse JSON response from invoke`,
               rawOutput: result.stdout.slice(0, 500),
+              hint: "The az CLI returned non-JSON output. Ensure --output json is used.",
             }),
         });
         return jsonData;

package/src/config/index.ts

@@ -9,4 +9,10 @@ export type {
   CredentialGuardConfig,
 } from "./types.ts";
 
-export { ConfigService, ConfigServiceLayer, getToolConfig, loadConfig } from "./loader";
+export {
+  ConfigService,
+  ConfigServiceLayer,
+  getToolConfig,
+  getDefaultEnvironment,
+  loadConfig,
+} from "./loader";

package/src/config/loader.ts

@@ -65,6 +65,7 @@ const AgentToolsConfigSchema = Schema.Struct({
     }),
   ),
   credentialGuard: Schema.optionalKey(CredentialGuardConfigSchema),
+  defaultEnvironment: Schema.optionalKey(Schema.String),
 });
 
 async function findConfigFile(startDirectory: string = process.cwd()): Promise<string | undefined> {
@@ -168,3 +169,7 @@ export function getToolConfig<T>(
     `Multiple ${section} profiles found: [${keys.join(", ")}]. Use --profile <name> to select one.`,
   );
 }
+
+export function getDefaultEnvironment(config: AgentToolsConfig | undefined): string | undefined {
+  return config?.defaultEnvironment;
+}

package/src/config/types.ts

@@ -79,4 +79,6 @@ export type AgentToolsConfig = {
   };
   /** Global credential guard config (merged with built-in defaults, not per-profile) */
   credentialGuard?: CredentialGuardConfig;
+  /** Optional default environment name (local|test|prod) used by tools when no --env flag is provided */
+  defaultEnvironment?: string;
 };