@the-open-engine/zeroshot 6.7.1 → 6.8.0

package/src/agent-cli-provider/adapters/opencode.ts

@@ -11,14 +11,9 @@ import {
   type BuildProviderCommandOptions,
   type CommandSpec,
   type ErrorClassification,
-  type LevelModelSpec,
-  type LevelOverrides,
-  type ModelCatalogEntry,
-  type ModelLevel,
   type OpencodeCliFeatures,
   type OutputEvent,
   type ProviderAdapter,
-  type ResolvedModelSpec,
   type WarningMetadata,
 } from '../types';
 import {
@@ -26,55 +21,16 @@ import {
   commandSpec,
   createParserState,
   optionFeatures,
-  resolveModelSpecWithConfig,
   unsupportedSessionControlWarnings,
-  validateModelIdFromCatalog,
   warning,
 } from './common';
-
-const MODEL_CATALOG: Readonly<Record<string, ModelCatalogEntry>> = {
-  'opencode/big-pickle': { rank: 1 },
-  'opencode/glm-4.7-free': { rank: 1 },
-  'opencode/gpt-5-nano': { rank: 1 },
-  'opencode/grok-code': { rank: 1 },
-  'opencode/minimax-m2.1-free': { rank: 1 },
-  'google/gemini-1.5-flash': { rank: 1 },
-  'google/gemini-1.5-flash-8b': { rank: 1 },
-  'google/gemini-1.5-pro': { rank: 1 },
-  'google/gemini-2.0-flash': { rank: 1 },
-  'google/gemini-2.0-flash-lite': { rank: 1 },
-  'google/gemini-2.5-flash': { rank: 1 },
-  'google/gemini-2.5-flash-image': { rank: 1 },
-  'google/gemini-2.5-flash-image-preview': { rank: 1 },
-  'google/gemini-2.5-flash-lite': { rank: 1 },
-  'google/gemini-2.5-flash-lite-preview-06-17': { rank: 1 },
-  'google/gemini-2.5-flash-lite-preview-09-2025': { rank: 1 },
-  'google/gemini-2.5-flash-preview-04-17': { rank: 1 },
-  'google/gemini-2.5-flash-preview-05-20': { rank: 1 },
-  'google/gemini-2.5-flash-preview-09-2025': { rank: 1 },
-  'google/gemini-2.5-flash-preview-tts': { rank: 1 },
-  'google/gemini-2.5-pro': { rank: 1 },
-  'google/gemini-2.5-pro-preview-05-06': { rank: 1 },
-  'google/gemini-2.5-pro-preview-06-05': { rank: 1 },
-  'google/gemini-2.5-pro-preview-tts': { rank: 1 },
-  'google/gemini-3-flash-preview': { rank: 1 },
-  'google/gemini-3-pro-preview': { rank: 1 },
-  'google/gemini-embedding-001': { rank: 1 },
-  'google/gemini-flash-latest': { rank: 1 },
-  'google/gemini-flash-lite-latest': { rank: 1 },
-  'google/gemini-live-2.5-flash': { rank: 1 },
-  'google/gemini-live-2.5-flash-preview-native-audio': { rank: 1 },
-  'openai/gpt-5.1-codex-max': { rank: 1 },
-  'openai/gpt-5.1-codex-mini': { rank: 1 },
-  'openai/gpt-5.2': { rank: 1 },
-  'openai/gpt-5.2-codex': { rank: 1 },
-};
-
-const LEVEL_MAPPING: Readonly<Record<ModelLevel, LevelModelSpec>> = {
-  level1: { rank: 1, model: null, reasoningEffort: 'low' },
-  level2: { rank: 2, model: null, reasoningEffort: 'medium' },
-  level3: { rank: 3, model: null, reasoningEffort: 'high' },
-};
+import {
+  LEVEL_MAPPING,
+  MODEL_CATALOG,
+  resolveModelSpec,
+  validateConfiguredModelId,
+  validateModelId,
+} from './opencode-models';
 
 function detectCliFeatures(helpText?: string | null): OpencodeCliFeatures {
   const help = helpText ?? '';
@@ -244,20 +200,6 @@ function parseEvent(line: string): OutputEvent | null {
   return null;
 }
 
-function resolveModelSpec(level: ModelLevel, overrides?: LevelOverrides): ResolvedModelSpec {
-  return resolveModelSpecWithConfig({
-    mapping: LEVEL_MAPPING,
-    defaultLevel: 'level2',
-    level,
-    overrides,
-    validateModelId,
-  });
-}
-
-function validateModelId(modelId: string | null | undefined): string | null | undefined {
-  return validateModelIdFromCatalog('opencode', MODEL_CATALOG, modelId);
-}
-
 function classifyError(error: unknown): ErrorClassification {
   return classifyBaseProviderError(error, [], []);
 }
@@ -285,5 +227,6 @@ export const opencodeAdapter: ProviderAdapter = {
   createParserState: () => createParserState('opencode'),
   resolveModelSpec,
   validateModelId,
+  validateConfiguredModelId,
   classifyError,
 };

package/src/agent-cli-provider/single-agent-runtime.ts

@@ -34,6 +34,11 @@ interface RuntimeProviderSettings {
   readonly gateway?: GatewayBuildOptions;
 }
 
+interface RuntimeCommandContext {
+  readonly cliFeatures: CliFeatureOverrides;
+  readonly authEnv: Readonly<Record<string, string>>;
+}
+
 export interface SingleAgentProviderCommandInput {
   readonly provider?: string | null;
   readonly context: string;
@@ -62,6 +67,7 @@ type MutableModelSpec = {
 
 const MODEL_LEVELS: readonly ModelLevel[] = ['level1', 'level2', 'level3'];
 const REASONING_EFFORTS: readonly ReasoningEffort[] = ['low', 'medium', 'high', 'xhigh', 'max'];
+const LEGACY_ISOLATED_PROVIDER_SETTINGS_ENV = 'ZEROSHOT_ISOLATED_PROVIDER_SETTINGS_JSON';
 const settingsModule: unknown = require('../../lib/settings');
 const providerDetectionModule: unknown = require('../../lib/provider-detection');
 const claudeAuthModule: unknown = require('../../lib/settings/claude-auth');
@@ -76,6 +82,7 @@ const resolveClaudeAuthFn = moduleFunction(claudeAuthModule, 'resolveClaudeAuth'
 export function prepareSingleAgentProviderCommand(
   input: SingleAgentProviderCommandInput
 ): PreparedSingleAgentProviderCommand {
+  rejectCallerSuppliedModelProvenance(input);
   const baseOptions = input.options ?? {};
   const settings = loadRuntimeSettings();
   const adapter = adapterForRuntimeInput(input.provider, settings);
@@ -86,7 +93,10 @@ export function prepareSingleAgentProviderCommand(
   );
   const cliFeatures = resolveRuntimeCliFeatures(adapter.id, baseOptions.cliFeatures);
   const authEnv = baseOptions.authEnv ?? resolveRuntimeAuthEnv(adapter.id, settings);
-  const options = buildRuntimeOptions(baseOptions, adapter, providerSettings, cliFeatures, authEnv);
+  const options = buildRuntimeOptions(baseOptions, adapter, providerSettings, {
+    cliFeatures,
+    authEnv,
+  });
   return {
     adapter,
     options,
@@ -128,8 +138,7 @@ function mergeAcpFailClosedCliFeatures(
     ...detected,
     ...overrides,
     supportsAcpStdio: detected.supportsAcpStdio && overrides.supportsAcpStdio !== false,
-    supportsPromptImages:
-      detected.supportsPromptImages && overrides.supportsPromptImages !== false,
+    supportsPromptImages: detected.supportsPromptImages && overrides.supportsPromptImages !== false,
     supportsLoadSession: detected.supportsLoadSession && overrides.supportsLoadSession !== false,
     supportsSessionCancel:
       detected.supportsSessionCancel && overrides.supportsSessionCancel !== false,
@@ -162,7 +171,9 @@ export function probeRuntimeProviderCli(provider: string): RuntimeProviderProbe
   }
 
   const helpText = stringResult(getHelpOutputFn(helpCommand.command, helpCommand.args)).trim();
-  const versionText = stringResult(getVersionOutputFn(helpCommand.command, helpCommand.args)).trim();
+  const versionText = stringResult(
+    getVersionOutputFn(helpCommand.command, helpCommand.args)
+  ).trim();
   const availabilityProbe = getProviderRegistryEntry(adapter.id).availabilityProbe ?? 'command';
 
   return {
@@ -177,8 +188,7 @@ function buildRuntimeOptions(
   baseOptions: BuildProviderCommandOptions,
   adapter: ProviderAdapter,
   providerSettings: RuntimeProviderSettings,
-  cliFeatures: CliFeatureOverrides,
-  authEnv: Readonly<Record<string, string>>
+  runtime: RuntimeCommandContext
 ): BuildProviderCommandOptions {
   const modelSpec = resolveRuntimeModelSpec(adapter, baseOptions.modelSpec, providerSettings);
   const gateway = resolveRuntimeGatewayOptions(
@@ -191,16 +201,16 @@ function buildRuntimeOptions(
     ...baseOptions,
     modelSpec,
     ...(gateway === undefined ? {} : { gateway }),
-    cliFeatures,
+    cliFeatures: runtime.cliFeatures,
   };
   if (baseOptions.jsonSchema && !supportsProviderCapability(adapter.id, 'jsonSchema')) {
-    if (!shouldIncludeAuthEnv(baseOptions, authEnv)) {
+    if (!shouldIncludeAuthEnv(baseOptions, runtime.authEnv)) {
       return { ...resolved, strictSchema: false };
     }
-    return { ...resolved, authEnv, strictSchema: false };
+    return { ...resolved, authEnv: runtime.authEnv, strictSchema: false };
   }
-  if (!shouldIncludeAuthEnv(baseOptions, authEnv)) return resolved;
-  return { ...resolved, authEnv };
+  if (!shouldIncludeAuthEnv(baseOptions, runtime.authEnv)) return resolved;
+  return { ...resolved, authEnv: runtime.authEnv };
 }
 
 function resolveRuntimeGatewayOptions(
@@ -218,23 +228,19 @@ function resolveRuntimeGatewayOptions(
       ? settingsGateway.headers
       : { ...(settingsGateway.headers ?? {}), ...requestGateway.headers };
   const mergedGateway: GatewayBuildOptions = {
-    ...(requestGateway.baseUrl ?? settingsGateway.baseUrl
+    ...((requestGateway.baseUrl ?? settingsGateway.baseUrl)
       ? { baseUrl: requestGateway.baseUrl ?? settingsGateway.baseUrl }
       : {}),
-    ...(requestGateway.apiKey ?? settingsGateway.apiKey
+    ...((requestGateway.apiKey ?? settingsGateway.apiKey)
       ? { apiKey: requestGateway.apiKey ?? settingsGateway.apiKey }
       : {}),
     ...(mergedHeaders === undefined ? {} : { headers: mergedHeaders }),
     model: requestGateway.model ?? modelSpec.model ?? settingsGateway.model ?? null,
-    ...(requestGateway.toolPolicy ?? settingsGateway.toolPolicy
+    ...((requestGateway.toolPolicy ?? settingsGateway.toolPolicy)
       ? { toolPolicy: requestGateway.toolPolicy ?? settingsGateway.toolPolicy }
       : {}),
   };
-  return resolveGatewayConfiguration(
-    mergedGateway,
-    'options.gateway',
-    cwd
-  );
+  return resolveGatewayConfiguration(mergedGateway, 'options.gateway', cwd);
 }
 
 function shouldIncludeAuthEnv(
@@ -286,7 +292,8 @@ function adapterForRuntimeInput(
   provider: string | null | undefined,
   settings: Record<string, unknown>
 ): ProviderAdapter {
-  const configured = provider ?? optionalString(settings.defaultProvider, 'settings.defaultProvider');
+  const configured =
+    provider ?? optionalString(settings.defaultProvider, 'settings.defaultProvider');
   return getProviderAdapter(configured ?? 'claude');
 }
 
@@ -309,16 +316,14 @@ function runtimeProviderSettings(
   );
   const gateway =
     provider === 'gateway'
-      ? normalizeGatewayBuildOptions(
-          providerSettings,
-          'settings.providerSettings.gateway',
-          cwd
-        )
+      ? normalizeGatewayBuildOptions(providerSettings, 'settings.providerSettings.gateway', cwd)
       : undefined;
   if (defaultLevel === undefined) {
     return gateway === undefined ? { levelOverrides } : { levelOverrides, gateway };
   }
-  return gateway === undefined ? { defaultLevel, levelOverrides } : { defaultLevel, levelOverrides, gateway };
+  return gateway === undefined
+    ? { defaultLevel, levelOverrides }
+    : { defaultLevel, levelOverrides, gateway };
 }
 
 function runtimeHelpCommand(provider: ProviderId): CommandParts {
@@ -333,7 +338,11 @@ function probeGatewayProvider(adapter: ProviderAdapter): RuntimeProviderProbe {
   try {
     const settings = loadRuntimeSettings();
     const providerSettings = runtimeProviderSettings(settings, 'gateway', process.cwd());
-    resolveGatewayConfiguration(providerSettings.gateway, 'settings.providerSettings.gateway', process.cwd());
+    resolveGatewayConfiguration(
+      providerSettings.gateway,
+      'settings.providerSettings.gateway',
+      process.cwd()
+    );
     return {
       available: true,
       helpText: 'Bundled gateway runner',
@@ -351,8 +360,20 @@ function probeGatewayProvider(adapter: ProviderAdapter): RuntimeProviderProbe {
 }
 
 function loadRuntimeSettings(): Record<string, unknown> {
-  const settings = loadSettingsFn();
-  return requiredRecord(settings, 'loadSettings');
+  if (Object.prototype.hasOwnProperty.call(process.env, LEGACY_ISOLATED_PROVIDER_SETTINGS_ENV)) {
+    throw new Error(
+      `${LEGACY_ISOLATED_PROVIDER_SETTINGS_ENV} is not a trusted settings channel; use the settings file.`
+    );
+  }
+  return requiredRecord(loadSettingsFn(), 'loadSettings');
+}
+
+function rejectCallerSuppliedModelProvenance(input: SingleAgentProviderCommandInput): void {
+  if (Object.prototype.hasOwnProperty.call(input, 'modelSpecSource')) {
+    throw new Error(
+      'modelSpecSource is not accepted at the child provider boundary; use modelLevel and effective provider settings.'
+    );
+  }
 }
 
 function moduleFunction(moduleValue: unknown, field: string): UnknownFunction {
@@ -456,10 +477,7 @@ function requiredRecord(value: unknown, field: string): Record<string, unknown>
   throw new Error(`${field} must be an object.`);
 }
 
-function stringRecordFromUnknown(
-  value: unknown,
-  field: string
-): Readonly<Record<string, string>> {
+function stringRecordFromUnknown(value: unknown, field: string): Readonly<Record<string, string>> {
   if (value === undefined || value === null) return {};
   const record = requiredRecord(value, field);
   const result: Record<string, string> = {};

package/src/agent-cli-provider/types.ts

@@ -367,6 +367,7 @@ export interface ProviderAdapter {
   createParserState(): ProviderParserState;
   resolveModelSpec(level: ModelLevel, overrides?: LevelOverrides): ResolvedModelSpec;
   validateModelId(modelId: string | null | undefined): string | null | undefined;
+  validateConfiguredModelId?(modelId: string | null | undefined): string | null | undefined;
   classifyError(error: unknown): ErrorClassification;
 }
 

package/src/agent-wrapper.js

@@ -103,10 +103,11 @@ class AgentWrapper {
       const taskRunner = options.taskRunner;
       this.mockSpawnFn = (args, { context }) => {
         const spec = this._resolveModelSpec();
+        const source = this._resolveModelSpecSource();
         return taskRunner.run(context, {
           agentId: this.id,
-          model: this._selectModel(),
-          modelSpec: spec,
+          ...(source === 'direct' ? { model: spec.model } : { modelLevel: spec.level }),
+          ...(spec.reasoningEffort ? { reasoningEffort: spec.reasoningEffort } : {}),
           provider: this._resolveProvider(),
           cwd: this.config.cwd || process.cwd(),
           worktreePath: this.worktree?.path || null,
@@ -222,6 +223,17 @@ class AgentWrapper {
     return applyReasoningOverride({ ...spec, level }, this.config.reasoningEffort);
   }
 
+  _resolveModelSpecSource() {
+    if (this.modelConfig.type === 'rules') {
+      for (const rule of this.modelConfig.rules) {
+        if (this._matchesIterationRange(rule.iterations)) {
+          return rule.model ? 'direct' : 'provider-level';
+        }
+      }
+    }
+    return this.modelConfig.model ? 'direct' : 'provider-level';
+  }
+
   /**
    * Publish a message to the message bus, always including sender_model
    * @private

package/src/agents/git-pusher-template.js

@@ -275,6 +275,7 @@ const hasSufficientEvidence = latestValidatorMessages.every((r) => {
 return hasSufficientEvidence;`;
 
 const { readRepoSettings } = require('../../lib/repo-settings');
+const { normalizeGitRemoteName, quoteShellArgument } = require('../../lib/git-remote-utils');
 const { resolveRequiredQualityGates } = require('../quality-gates');
 
 function getSafeBranchName(value) {
@@ -313,6 +314,35 @@ function normalizeCloseIssueMode(value) {
   return null;
 }
 
+function normalizeIssueNumber(value) {
+  const candidate = typeof value === 'number' ? String(value) : value;
+  if (typeof candidate !== 'string') return 'unknown';
+  const trimmed = candidate.trim();
+  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(trimmed) ? trimmed : 'unknown';
+}
+
+function normalizeIssueTitle(value) {
+  if (typeof value !== 'string' || value.trim() === '') return 'Implementation';
+  const normalized = [...value]
+    .map((character) => {
+      const codePoint = character.codePointAt(0);
+      return codePoint < 0x20 || codePoint === 0x7f ? ' ' : character;
+    })
+    .join('')
+    .trim();
+  return normalized || 'Implementation';
+}
+
+function resolveIssueContext(options) {
+  const issueNumber = normalizeIssueNumber(options.issueNumber);
+  const issueTitle = normalizeIssueTitle(options.issueTitle);
+  const issueReference =
+    options.includeIssueReference === false || issueNumber === 'unknown'
+      ? ''
+      : `Closes #${issueNumber}`;
+  return { issueNumber, issueTitle, issueReference };
+}
+
 /**
  * Resolve GitHub configuration from CLI options and repo settings.
  * Priority: CLI options > repo settings (.zeroshot/settings.json) > defaults
@@ -321,12 +351,20 @@ function normalizeCloseIssueMode(value) {
  * @param {string} [options.prBase] - Target branch for PRs
  * @param {boolean} [options.mergeQueue] - Use GitHub merge queue
  * @param {string} [options.closeIssue] - When to close issue: auto|always|never
+ * @param {string} [options.gitRemote=origin] - Remote to push the implementation branch to
+ * @param {string|number} [options.issueNumber] - Typed issue identifier for prompt commands
+ * @param {string} [options.issueTitle] - Typed issue title for prompt commands
+ * @param {boolean} [options.includeIssueReference] - Include the closing reference in PR text
  * @returns {Object} Resolved configuration
  */
 function resolveGitHubConfig(options = {}) {
   const repoSettingsResult = readRepoSettings(options.cwd || process.cwd());
   const repoSettings = repoSettingsResult.settings || {};
   const repoGithub = repoSettings.github || {};
+  const gitRemote = normalizeGitRemoteName(options.gitRemote ?? 'origin');
+  if (!gitRemote) {
+    throw new Error(`Invalid git remote name '${options.gitRemote}'`);
+  }
 
   // CLI options override repo settings
   const prBase = getSafeBranchName(options.prBase) || getSafeBranchName(repoGithub.prBase);
@@ -347,7 +385,14 @@ function resolveGitHubConfig(options = {}) {
     options.autoMerge === true ||
     (options.autoMerge !== false && parseBool(repoGithub.autoMerge) === true);
 
-  return { prBase, useMergeQueue, closeIssueMode, autoMerge };
+  return {
+    prBase,
+    useMergeQueue,
+    closeIssueMode,
+    autoMerge,
+    gitRemote,
+    issueContext: resolveIssueContext(options),
+  };
 }
 
 /**
@@ -358,13 +403,16 @@ function resolveGitHubConfig(options = {}) {
  * @returns {Object|null} Platform configuration or null if unsupported
  */
 function getPlatformConfig(platform, config = {}) {
-  const { prBase, useMergeQueue, closeIssueMode, autoMerge } = config;
+  const { prBase, useMergeQueue, closeIssueMode, autoMerge, gitRemote } = config;
+  const issueContext = config.issueContext || resolveIssueContext({});
+  const issueTitleArgument = quoteShellArgument(`feat: ${issueContext.issueTitle}`);
+  const issueReferenceArgument = quoteShellArgument(issueContext.issueReference);
 
   const PLATFORM_CONFIGS = {
     github: {
       prName: 'PR',
       prNameLower: 'pull request',
-      createCmd: `gh pr create${prBase ? ` --base ${prBase}` : ''} --title "feat: {{issue_title}}" --body "Closes #{{issue_number}}"`,
+      createCmd: `gh pr create${prBase ? ` --base ${prBase}` : ''} --title ${issueTitleArgument} --body ${issueReferenceArgument}`,
       mergeCmd: useMergeQueue
         ? `PR_ID="$(timeout 30 gh pr view --json id --jq .id)"
 gh api graphql -f query='mutation($id:ID!){enqueuePullRequest(input:{pullRequestId:$id}){mergeQueueEntry{state}}}' -f id="$PR_ID"
@@ -380,24 +428,26 @@ for i in $(seq 1 90); do if timeout 30 gh pr view --json mergedAt --jq .mergedAt
       usesMergeQueue: useMergeQueue,
       closeIssueMode: closeIssueMode || 'never',
       autoMerge: Boolean(autoMerge),
+      gitRemote,
+      issueContext,
     },
     gitlab: {
       prName: 'MR',
       prNameLower: 'merge request',
-      createCmd:
-        'glab mr create --title "feat: {{issue_title}}" --description "Closes #{{issue_number}}"',
+      createCmd: `glab mr create --title ${issueTitleArgument} --description ${issueReferenceArgument}`,
       mergeCmd: 'glab mr merge --auto-merge',
       mergeFallbackCmd: 'glab mr merge',
       prUrlExample: 'https://gitlab.com/owner/repo/-/merge_requests/123',
       outputFields: { urlField: 'mr_url', numberField: 'mr_number', mergedField: 'merged' },
       closeIssueMode: closeIssueMode || 'never',
       autoMerge: Boolean(autoMerge),
+      gitRemote,
+      issueContext,
     },
     'azure-devops': {
       prName: 'PR',
       prNameLower: 'pull request',
-      createCmd:
-        'az repos pr create --title "feat: {{issue_title}}" --description "Closes #{{issue_number}}"',
+      createCmd: `az repos pr create --title ${issueTitleArgument} --description ${issueReferenceArgument}`,
       mergeCmd: 'az repos pr update --id <PR_ID> --auto-complete true',
       mergeFallbackCmd: 'az repos pr update --id <PR_ID> --status completed',
       prUrlExample: 'https://dev.azure.com/org/project/_git/repo/pullrequest/123',
@@ -411,6 +461,8 @@ for i in $(seq 1 90); do if timeout 30 gh pr view --json mergedAt --jq .mergedAt
       requiresPrIdExtraction: true,
       closeIssueMode: closeIssueMode || 'never',
       autoMerge: Boolean(autoMerge),
+      gitRemote,
+      issueContext,
     },
   };
 
@@ -430,8 +482,20 @@ const SUPPORTED_PLATFORMS = ['github', 'gitlab', 'azure-devops'];
  * @returns {string} The complete review-mode prompt
  */
 function generateReviewModePrompt(config) {
-  const { prName, prNameLower, createCmd, prUrlExample, outputFields, requiresPrIdExtraction } =
-    config;
+  const {
+    prName,
+    prNameLower,
+    createCmd,
+    prUrlExample,
+    outputFields,
+    requiresPrIdExtraction,
+    gitRemote,
+    issueContext,
+  } = config;
+  const gitRemoteArgument = quoteShellArgument(gitRemote);
+  const commitMessageArgument = quoteShellArgument(
+    `feat: implement #${issueContext.issueNumber} - ${issueContext.issueTitle}`
+  );
 
   return `CRITICAL: ALL VALIDATORS APPROVED. YOU ARE A TRANSPORT-ONLY GIT PUSHER.
 
@@ -467,13 +531,13 @@ Run this. If nothing to commit, output JSON with ${outputFields.urlField}: null
 
 ### STEP 3: Commit the changes (MANDATORY if there are changes)
 \`\`\`bash
-git commit -m "feat: implement #{{issue_number}} - {{issue_title}}"
+git commit -m ${commitMessageArgument}
 \`\`\`
 Run this command. Do not skip it.
 
-### STEP 4: Push to origin (MANDATORY)
+### STEP 4: Push to ${gitRemote} (MANDATORY)
 \`\`\`bash
-git push -u origin HEAD
+git push -u -- ${gitRemoteArgument} HEAD
 \`\`\`
 Run this. If it fails, do not edit files, rebase, or resolve conflicts. Output blocked JSON with the failure summary.
 
@@ -543,7 +607,14 @@ function generatePrompt(config) {
     usesMergeQueue,
     closeIssueMode,
     autoMerge,
+    gitRemote,
+    issueContext,
   } = config;
+  const gitRemoteArgument = quoteShellArgument(gitRemote);
+  const issueNumberArgument = quoteShellArgument(issueContext.issueNumber);
+  const commitMessageArgument = quoteShellArgument(
+    `feat: implement #${issueContext.issueNumber} - ${issueContext.issueTitle}`
+  );
 
   if (!autoMerge) {
     return generateReviewModePrompt(config);
@@ -627,13 +698,13 @@ Run this. If nothing to commit, output JSON with ${outputFields.urlField}: null
 
 ### STEP 3: Commit the changes (MANDATORY if there are changes)
 \`\`\`bash
-git commit -m "feat: implement #{{issue_number}} - {{issue_title}}"
+git commit -m ${commitMessageArgument}
 \`\`\`
 Run this command. Do not skip it.
 
-### STEP 4: Push to origin (MANDATORY)
+### STEP 4: Push to ${gitRemote} (MANDATORY)
 \`\`\`bash
-git push -u origin HEAD
+git push -u -- ${gitRemoteArgument} HEAD
 \`\`\`
 Run this. If it fails, do not edit files, rebase, or resolve conflicts. Output blocked JSON with the failure summary.
 
@@ -665,8 +736,8 @@ ${
   closeIssueMode !== 'never'
     ? `### STEP 7: Close the issue (MANDATORY)
 \`\`\`bash
-if [ "{{issue_number}}" != "unknown" ]; then
-  ISSUE_STATE="$(gh issue view {{issue_number}} --json state --jq .state 2>/dev/null || true)"
+if [ ${issueNumberArgument} != "unknown" ]; then
+  ISSUE_STATE="$(gh issue view ${issueNumberArgument} --json state --jq .state 2>/dev/null || true)"
   if [ "$ISSUE_STATE" = "OPEN" ]; then
     BASE_BRANCH="${rebaseBranch || 'main'}"
     DEFAULT_BRANCH="$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name 2>/dev/null || true)"
@@ -682,9 +753,9 @@ if [ "{{issue_number}}" != "unknown" ]; then
     if [ "$SHOULD_CLOSE" = "1" ]; then
   PR_URL="$(gh pr view --json url --jq .url 2>/dev/null || true)"
   if [ -n "$PR_URL" ]; then
-    gh issue close {{issue_number}} --comment "Implemented in $PR_URL"
+    gh issue close ${issueNumberArgument} --comment "Implemented in $PR_URL"
   else
-    gh issue close {{issue_number}} --comment "Implemented"
+    gh issue close ${issueNumberArgument} --comment "Implemented"
   fi
     fi
   fi
@@ -728,6 +799,10 @@ If blocked before creating a ${prName}, output:
  * @param {string} [options.prBase] - Target branch for PRs
  * @param {boolean} [options.mergeQueue] - Use GitHub merge queue
  * @param {string} [options.closeIssue] - When to close issue: auto|always|never
+ * @param {string} [options.gitRemote=origin] - Remote to push the implementation branch to
+ * @param {string|number} [options.issueNumber] - Typed issue identifier for prompt commands
+ * @param {string} [options.issueTitle] - Typed issue title for prompt commands
+ * @param {boolean} [options.includeIssueReference] - Include the closing reference in PR text
  * @param {Array} [options.requiredQualityGates] - Required handoff quality gates
  * @param {boolean} [options.autoMerge] - Merge the PR (--ship). False stops after PR creation (--pr).
  * @returns {Object} Agent configuration object

package/src/attach/socket-discovery.js

@@ -1,20 +1,18 @@
 /**
  * Socket Discovery - Utilities for socket path management
  *
- * Socket locations:
- * - Tasks: ~/.zeroshot/sockets/task-<id>.sock
- * - Clusters: ~/.zeroshot/sockets/cluster-<id>.sock (cluster-level, future)
- * - Agents: ~/.zeroshot/sockets/cluster-<id>/<agent-id>.sock
+ * Socket locations are allocated by socket-paths.js under a short, per-user
+ * runtime directory so long HOME paths cannot exceed Unix socket limits.
  */
 
 const path = require('path');
 const fs = require('fs');
-const os = require('os');
 const net = require('net');
 const { readClustersFileSync } = require('../../lib/clusters-registry');
+const socketPaths = require('./socket-paths');
 
-const ZEROSHOT_DIR = path.join(os.homedir(), '.zeroshot');
-const SOCKET_DIR = path.join(ZEROSHOT_DIR, 'sockets');
+const ZEROSHOT_DIR = path.join(socketPaths.resolveHomeDir(), '.zeroshot');
+const SOCKET_DIR = socketPaths.getSocketDir();
 
 /**
  * Check if an ID is a known cluster by looking up clusters.json
@@ -35,9 +33,7 @@ function isKnownCluster(id) {
  * Ensure socket directory exists
  */
 function ensureSocketDir() {
-  if (!fs.existsSync(SOCKET_DIR)) {
-    fs.mkdirSync(SOCKET_DIR, { recursive: true });
-  }
+  socketPaths.ensureSocketDir();
 }
 
 /**
@@ -46,8 +42,7 @@ function ensureSocketDir() {
  * @returns {string} - Socket path
  */
 function getTaskSocketPath(taskId) {
-  ensureSocketDir();
-  return path.join(SOCKET_DIR, `${taskId}.sock`);
+  return socketPaths.getTaskSocketPath(taskId);
 }
 
 /**
@@ -57,11 +52,7 @@ function getTaskSocketPath(taskId) {
  * @returns {string} - Socket path
  */
 function getAgentSocketPath(clusterId, agentId) {
-  const clusterDir = path.join(SOCKET_DIR, clusterId);
-  if (!fs.existsSync(clusterDir)) {
-    fs.mkdirSync(clusterDir, { recursive: true });
-  }
-  return path.join(clusterDir, `${agentId}.sock`);
+  return socketPaths.getAgentSocketPath(clusterId, agentId);
 }
 
 /**
@@ -81,8 +72,7 @@ function getSocketPath(id, agentId = null) {
       return getAgentSocketPath(id, agentId);
     }
     // Cluster-level socket (future use)
-    ensureSocketDir();
-    return path.join(SOCKET_DIR, `${id}.sock`);
+    return socketPaths.getClusterSocketPath(id);
   }
   // Unknown format, treat as task
   return getTaskSocketPath(id);