@meistrari/tela-cli 0.4.1 → 0.6.0

package/README.md

@@ -14,6 +14,24 @@ This installs the package globally and adds a `tela` alias to your `~/.zshrc`. A
 source ~/.zshrc
 ```
 
+## Default command
+
+### `tela`
+
+List workspace repositories that are available to sync locally.
+
+When to use: Run this with no subcommand when you want to see which workspace repositories are available before using `tela sync <repo>`.
+
+Examples:
+- `tela` — Render the available repositories in a human-readable table
+- `tela --json` — Emit the available repositories as JSON
+
+## Version
+
+Examples:
+- `tela --version` — Print the current Tela CLI version
+- `tela -v` — Print the current Tela CLI version
+
 ## Commands
 
 ### `setup`
@@ -29,7 +47,7 @@ Examples:
 
 Clone or update a Tela repository, or refresh the current checkout
 
-When to use: Use this before coding to get a clean local checkout, or to refresh every repository under the configured clone root.
+When to use: Use this before coding to get a clean local checkout, or to refresh every repository under the configured clone root. SSH-backed sync automatically accepts first-seen host keys during clone and update flows.
 
 Examples:
 - `tela sync agent-api` — Clone or update a specific repository under the clone root
@@ -38,14 +56,14 @@ Examples:
 
 ### `run`
 
-Run the local agent repository with Claude
+Run the local agent repository with project-scoped Claude
 
-When to use: Use this from inside an agent repository when you want Claude to follow the local contract files, show its progress live, and produce the expected result artifact.
+When to use: Use this from inside an agent repository when you want Claude to follow the repo-local contract files, ignore user/global Claude config by default, show its progress live, and produce the expected result artifact.
 
 Examples:
-- `tela run` — Run the current agent repository with the live viewer
-- `tela run --plain` — Force scrollback-first text output
-- `tela run --json` — Emit the final execution and artifact envelope as JSON
+- `tela run` — Run the current agent repository with project-scoped Claude and the live viewer
+- `tela run --plain` — Force project-scoped execution with scrollback-first text output
+- `tela run --json` — Emit the final project-scoped execution and artifact envelope as JSON
 
 ### `push`
 
@@ -96,6 +114,11 @@ Examples:
 - Human output is structured for terminal use with grouped summaries and next actions.
 - `--json` is available on read-heavy flows and on `tela run` for the final execution envelope.
 
+## `tela run` scope
+
+- `tela run` loads project-scoped Claude settings by default and excludes user/global Claude config.
+- Remaining external inputs are explicit: Claude's built-in system prompt, managed enterprise settings, auth/provider credentials, minimal shell runtime environment, and the default model when `agent.config.json` does not set one.
+
 ## First run
 
 1. `tela setup`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/tela-cli",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "type": "module",
   "bin": {
     "tela": "cli.ts"

package/src/agent-api.ts

@@ -1,10 +1,15 @@
 import { buildAgentApiHeaders, type FetchLike } from './auth.ts'
 import type {
+    AgentRepoSummary,
+    AvailableRepositorySummary,
     AgentFeedbackItem,
     AgentFeedbackListResponse,
     ForgejoUserCreateResponse,
     ForgejoUserSshKeyInput,
     OrganizationListResponse,
+    OrganizationSummary,
+    RepositoryListItemResponse,
+    RepositoryListResponse,
     RepositoryLookupResponse,
     TelaCliConfig,
     TelaCliForgejoOrganization,
@@ -45,6 +50,39 @@ function isForgejoOrganization(value: unknown): value is TelaCliForgejoOrganizat
     return typeof candidate.id === 'string' && typeof candidate.name === 'string'
 }
 
+function isOrganizationSummary(value: unknown): value is OrganizationSummary {
+    if (!value || typeof value !== 'object') {
+        return false
+    }
+
+    const candidate = value as Partial<OrganizationSummary>
+    return typeof candidate.id === 'string'
+        && typeof candidate.workspaceId === 'string'
+        && typeof candidate.name === 'string'
+}
+
+function isAgentRepoSummary(value: unknown): value is AgentRepoSummary {
+    if (!value || typeof value !== 'object') {
+        return false
+    }
+
+    const candidate = value as Partial<AgentRepoSummary>
+    return typeof candidate.id === 'string'
+        && typeof candidate.workspaceId === 'string'
+        && typeof candidate.organizationId === 'string'
+        && typeof candidate.repository === 'string'
+}
+
+function isRepositoryListItemResponse(value: unknown): value is RepositoryListItemResponse {
+    if (!value || typeof value !== 'object') {
+        return false
+    }
+
+    const candidate = value as Partial<RepositoryListItemResponse>
+    return isOrganizationSummary(candidate.organization)
+        && isAgentRepoSummary(candidate.agentRepo)
+}
+
 export class AgentApiError extends Error {
     constructor(
         message: string,
@@ -173,6 +211,44 @@ export async function listOrganizations(
     return payload.organizations
 }
 
+export async function listAvailableRepositories(
+    config: TelaCliConfig,
+    fetchFn: FetchLike = fetch,
+): Promise<AvailableRepositorySummary[]> {
+    const headers = await buildAgentApiHeaders(config, { fetchFn })
+    const response = await fetchFn(
+        joinUrl(config.agentApiUrl, '/v3/agents/repositories'),
+        {
+            method: 'GET',
+            headers,
+            signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+        },
+    )
+
+    const responseText = await response.text()
+    const payload = parseJsonBody(responseText) as RepositoryListResponse | null
+
+    if (!response.ok) {
+        throw new AgentApiError(
+            payload?.error ?? `Agent API repository listing failed with status ${response.status}`,
+            response.status,
+            responseText,
+        )
+    }
+
+    if (!payload
+        || payload.success !== true
+        || !Array.isArray(payload.repositories)
+        || !payload.repositories.every(isRepositoryListItemResponse)) {
+        throw new AgentApiError('Agent API repository listing returned an invalid payload', response.status, responseText)
+    }
+
+    return payload.repositories.map(repository => ({
+        ...repository,
+        syncStatus: 'available' as const,
+    }))
+}
+
 export async function provisionForgejoUser(
     input: {
         organizationName: string

package/src/claude.ts

@@ -0,0 +1,101 @@
+import { commandExists, runCommand } from './process.ts'
+
+export interface ClaudeCliVersion {
+    major: number
+    minor: number
+    patch: number
+}
+
+export interface ClaudeCliInspection {
+    available: boolean
+    version?: string
+    parsedVersion?: ClaudeCliVersion
+    supportsProjectScopedRun: boolean
+    problem?: 'missing' | 'unparseable' | 'unsupported'
+    detail?: string
+}
+
+export const MIN_CLAUDE_VERSION_FOR_PROJECT_SCOPED_RUN: ClaudeCliVersion = {
+    major: 2,
+    minor: 1,
+    patch: 108,
+}
+
+export function formatClaudeCliVersion(version: ClaudeCliVersion): string {
+    return `${version.major}.${version.minor}.${version.patch}`
+}
+
+export function compareClaudeCliVersions(left: ClaudeCliVersion, right: ClaudeCliVersion): number {
+    if (left.major !== right.major) {
+        return left.major - right.major
+    }
+
+    if (left.minor !== right.minor) {
+        return left.minor - right.minor
+    }
+
+    return left.patch - right.patch
+}
+
+export function parseClaudeCliVersion(raw: string): ClaudeCliVersion | null {
+    const match = raw.match(/\b(\d+)\.(\d+)\.(\d+)\b/)
+    if (!match) {
+        return null
+    }
+
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+    }
+}
+
+export async function inspectClaudeCli(options: {
+    commandExistsFn?: typeof commandExists
+    runCommandFn?: typeof runCommand
+} = {}): Promise<ClaudeCliInspection> {
+    const commandExistsFn = options.commandExistsFn ?? commandExists
+    const runCommandFn = options.runCommandFn ?? runCommand
+
+    if (!await commandExistsFn('claude')) {
+        return {
+            available: false,
+            supportsProjectScopedRun: false,
+            problem: 'missing',
+            detail: '`claude` is not available on PATH.',
+        }
+    }
+
+    const result = await runCommandFn(['claude', '--version'], { allowFailure: true })
+    const output = `${result.stdout}\n${result.stderr}`.trim()
+    const parsedVersion = parseClaudeCliVersion(output)
+
+    if (!parsedVersion) {
+        return {
+            available: true,
+            supportsProjectScopedRun: false,
+            problem: 'unparseable',
+            detail: output || 'Claude CLI version output was empty.',
+        }
+    }
+
+    const version = formatClaudeCliVersion(parsedVersion)
+    if (compareClaudeCliVersions(parsedVersion, MIN_CLAUDE_VERSION_FOR_PROJECT_SCOPED_RUN) < 0) {
+        return {
+            available: true,
+            version,
+            parsedVersion,
+            supportsProjectScopedRun: false,
+            problem: 'unsupported',
+            detail: `Claude CLI ${version} is older than the required ${formatClaudeCliVersion(MIN_CLAUDE_VERSION_FOR_PROJECT_SCOPED_RUN)}.`,
+        }
+    }
+
+    return {
+        available: true,
+        version,
+        parsedVersion,
+        supportsProjectScopedRun: true,
+        detail: `Claude CLI ${version} supports project-scoped runs.`,
+    }
+}

package/src/commands/metadata.ts

@@ -32,7 +32,7 @@ const COMMANDS: CommandMetadata[] = [
         name: 'sync',
         summary: 'Clone or update a Tela repository, or refresh the current checkout',
         argumentHint: '[repo]',
-        whenToUse: 'Use this before coding to get a clean local checkout, or to refresh every repository under the configured clone root.',
+        whenToUse: 'Use this before coding to get a clean local checkout, or to refresh every repository under the configured clone root. SSH-backed sync automatically accepts first-seen host keys during clone and update flows.',
         examples: [
             {
                 command: 'tela sync agent-api',
@@ -52,20 +52,20 @@ const COMMANDS: CommandMetadata[] = [
     },
     {
         name: 'run',
-        summary: 'Run the local agent repository with Claude',
-        whenToUse: 'Use this from inside an agent repository when you want Claude to follow the local contract files, show its progress live, and produce the expected result artifact.',
+        summary: 'Run the local agent repository with project-scoped Claude',
+        whenToUse: 'Use this from inside an agent repository when you want Claude to follow the repo-local contract files, ignore user/global Claude config by default, show its progress live, and produce the expected result artifact.',
         examples: [
             {
                 command: 'tela run',
-                description: 'Run the current agent repository with the live viewer',
+                description: 'Run the current agent repository with project-scoped Claude and the live viewer',
             },
             {
                 command: 'tela run --plain',
-                description: 'Force scrollback-first text output',
+                description: 'Force project-scoped execution with scrollback-first text output',
             },
             {
                 command: 'tela run --json',
-                description: 'Emit the final execution and artifact envelope as JSON',
+                description: 'Emit the final project-scoped execution and artifact envelope as JSON',
             },
         ],
         supportsJson: true,
@@ -176,6 +176,24 @@ export function renderReadmeMarkdown(): string {
         'source ~/.zshrc',
         '```',
         '',
+        '## Default command',
+        '',
+        '### `tela`',
+        '',
+        'List workspace repositories that are available to sync locally.',
+        '',
+        'When to use: Run this with no subcommand when you want to see which workspace repositories are available before using `tela sync <repo>`.',
+        '',
+        'Examples:',
+        '- `tela` — Render the available repositories in a human-readable table',
+        '- `tela --json` — Emit the available repositories as JSON',
+        '',
+        '## Version',
+        '',
+        'Examples:',
+        '- `tela --version` — Print the current Tela CLI version',
+        '- `tela -v` — Print the current Tela CLI version',
+        '',
         '## Commands',
         '',
     ]
@@ -205,6 +223,11 @@ export function renderReadmeMarkdown(): string {
     lines.push('- Human output is structured for terminal use with grouped summaries and next actions.')
     lines.push('- `--json` is available on read-heavy flows and on `tela run` for the final execution envelope.')
     lines.push('')
+    lines.push('## `tela run` scope')
+    lines.push('')
+    lines.push('- `tela run` loads project-scoped Claude settings by default and excludes user/global Claude config.')
+    lines.push('- Remaining external inputs are explicit: Claude\'s built-in system prompt, managed enterprise settings, auth/provider credentials, minimal shell runtime environment, and the default model when `agent.config.json` does not set one.')
+    lines.push('')
     lines.push('## First run')
     lines.push('')
     lines.push('1. `tela setup`')

package/src/commands/run.ts

@@ -1,9 +1,16 @@
+import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { basename, join } from 'node:path'
+import {
+    formatClaudeCliVersion,
+    inspectClaudeCli,
+    MIN_CLAUDE_VERSION_FOR_PROJECT_SCOPED_RUN,
+} from '../claude.ts'
 import { getRepositoryRoot } from '../git.ts'
 import { createUserFacingError } from '../errors.ts'
 import {
     commandExists,
+    runCommand,
     runInteractiveCommand,
     runStreamingCommand,
     spawnStreamingCommand,
@@ -37,6 +44,7 @@ export interface PreparedLocalAgentRun {
     config: AgentRunConfig
     resultKind: 'json' | 'markdown'
     resultPath: string
+    mcpConfigPath?: string
 }
 
 export interface RunStepSummary {
@@ -110,6 +118,8 @@ export interface RunLocalAgentCommandOptions {
     contract?: PreparedLocalAgentRun
     surface?: RunOutputSurface
     commandExists?: typeof commandExists
+    inspectClaudeCli?: typeof inspectClaudeCli
+    runCommand?: typeof runCommand
     runInteractiveCommand?: typeof runInteractiveCommand
     runStreamingCommand?: typeof runStreamingCommand
     spawnStreamingCommand?: typeof spawnStreamingCommand
@@ -1130,6 +1140,88 @@ function parseAgentConfig(path: string, content: string): AgentRunConfig {
     }
 }
 
+const CLAUDE_RUN_ENV_DENYLIST = new Set([
+    'CLAUDE_CONFIG_DIR',
+    'CLAUDE_ENV_FILE',
+    'ANTHROPIC_MODEL',
+    'ANTHROPIC_CUSTOM_MODEL_OPTION',
+    'ANTHROPIC_CUSTOM_MODEL_OPTION_NAME',
+    'ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION',
+    'ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES',
+    'ANTHROPIC_DEFAULT_OPUS_MODEL',
+    'ANTHROPIC_DEFAULT_OPUS_MODEL_NAME',
+    'ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION',
+    'ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES',
+    'ANTHROPIC_DEFAULT_SONNET_MODEL',
+    'ANTHROPIC_DEFAULT_SONNET_MODEL_NAME',
+    'ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION',
+    'ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES',
+    'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+    'ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME',
+    'ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION',
+    'ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES',
+    'CLAUDE_CODE_SUBAGENT_MODEL',
+])
+
+function buildClaudeRunEnvironment(
+    baseEnv: NodeJS.ProcessEnv = process.env,
+): Record<string, string | undefined> {
+    return Object.fromEntries(
+        Object.entries(baseEnv).filter(([key]) => !CLAUDE_RUN_ENV_DENYLIST.has(key)),
+    )
+}
+
+function buildUnsupportedClaudeVersionError(detail: string | undefined): ReturnType<typeof createUserFacingError> {
+    const requiredVersion = formatClaudeCliVersion(MIN_CLAUDE_VERSION_FOR_PROJECT_SCOPED_RUN)
+
+    return createUserFacingError({
+        code: 'run_claude_version_unsupported',
+        summary: `\`tela run\` requires Claude CLI ${requiredVersion} or newer for project-scoped runs.`,
+        details: detail,
+        fixes: [
+            'Update Claude CLI before using `tela run`.',
+            'Run `claude --version` to confirm the installed version.',
+        ],
+    })
+}
+
+function buildClaudeBaseCommand(prepared: PreparedLocalAgentRun): string[] {
+    const command = [
+        'claude',
+        '--setting-sources',
+        'project',
+    ]
+
+    if (prepared.mcpConfigPath) {
+        command.push('--strict-mcp-config', '--mcp-config', prepared.mcpConfigPath)
+    }
+
+    if (prepared.config.model) {
+        command.push('--model', prepared.config.model)
+    }
+
+    return command
+}
+
+function buildClaudeCommand(
+    prepared: PreparedLocalAgentRun,
+    mode: RunMode,
+): string[] {
+    const command = buildClaudeBaseCommand(prepared)
+
+    if (mode === 'one-shot') {
+        command.push(
+            '-p',
+            '--output-format',
+            'stream-json',
+            '--verbose',
+        )
+    }
+
+    command.push(INITIAL_PROMPT)
+    return command
+}
+
 async function resolveRepositoryRoot(cwd: string): Promise<string> {
     try {
         return await getRepositoryRoot(cwd)
@@ -1176,12 +1268,19 @@ async function validateRequiredFiles(repoRoot: string): Promise<void> {
 export async function prepareLocalAgentRun(options: {
     cwd?: string
     commandExists?: typeof commandExists
+    inspectClaudeCli?: typeof inspectClaudeCli
+    runCommand?: typeof runCommand
 } = {}): Promise<PreparedLocalAgentRun> {
     const cwd = options.cwd ?? process.cwd()
-    const commandExistsFn = options.commandExists ?? commandExists
     const repoRoot = await resolveRepositoryRoot(cwd)
+    const inspectClaudeCliFn = options.inspectClaudeCli ?? inspectClaudeCli
+
+    const claudeInspection = await inspectClaudeCliFn({
+        commandExistsFn: options.commandExists,
+        runCommandFn: options.runCommand,
+    })
 
-    if (!await commandExistsFn('claude')) {
+    if (!claudeInspection.available) {
         throw createUserFacingError({
             code: 'run_claude_missing',
             summary: 'Claude CLI is not available on PATH.',
@@ -1189,6 +1288,10 @@ export async function prepareLocalAgentRun(options: {
         })
     }
 
+    if (!claudeInspection.supportsProjectScopedRun) {
+        throw buildUnsupportedClaudeVersionError(claudeInspection.detail)
+    }
+
     await validateRequiredFiles(repoRoot)
 
     const [outputFormatContent, agentConfigContent] = await Promise.all([
@@ -1209,6 +1312,9 @@ export async function prepareLocalAgentRun(options: {
         config,
         resultKind,
         resultPath: join(repoRoot, 'output', resultKind === 'json' ? 'result.json' : 'result.md'),
+        mcpConfigPath: existsSync(join(repoRoot, '.mcp.json'))
+            ? join(repoRoot, '.mcp.json')
+            : undefined,
     }
 }
 
@@ -1375,13 +1481,10 @@ async function runInteractiveAgent(
         writeLine(options.writeStdout, 'Launching Claude in interactive chat mode. Tela will resume after Claude exits.')
     }
 
-    const command = [
-        'claude',
-        ...(prepared.config.model ? ['--model', prepared.config.model] : []),
-        INITIAL_PROMPT,
-    ]
-
-    await runInteractiveCommandFn(command, { cwd: prepared.repoRoot })
+    await runInteractiveCommandFn(buildClaudeCommand(prepared, 'chat'), {
+        cwd: prepared.repoRoot,
+        env: buildClaudeRunEnvironment(),
+    })
 }
 
 async function runOneShotAgent(
@@ -1408,18 +1511,11 @@ async function runOneShotAgent(
     }
 
     let cancelled = false
-    const command = [
-        'claude',
-        '-p',
-        '--output-format',
-        'stream-json',
-        '--verbose',
-        ...(prepared.config.model ? ['--model', prepared.config.model] : []),
-        INITIAL_PROMPT,
-    ]
+    const command = buildClaudeCommand(prepared, 'one-shot')
 
     const handle = spawnStreamingCommandFn(command, {
         cwd: prepared.repoRoot,
+        env: buildClaudeRunEnvironment(),
         allowFailure: true,
         onStdoutLine: async (line) => {
             const trimmed = line.trim()
@@ -1509,6 +1605,8 @@ export async function runLocalAgentCommand(
     const prepared = options.contract ?? await prepareLocalAgentRun({
         cwd: options.cwd ?? process.cwd(),
         commandExists: options.commandExists,
+        inspectClaudeCli: options.inspectClaudeCli,
+        runCommand: options.runCommand,
     })
     const mode: RunMode = prepared.config.isMultiturn ? 'chat' : 'one-shot'
     const tracker = new RunStateTracker(prepared, mode)

package/src/commands/status.ts

@@ -52,7 +52,17 @@ export function renderStatusReport(report: StatusReport, options: RenderOptions
 
     const toolRows = [
         ['git', report.tools.git ? 'available' : 'missing', report.tools.git ? 'ready' : 'install git'],
-        ['claude', report.tools.claude ? 'available' : 'missing', report.tools.claude ? 'ready' : 'required for `tela run`, `tela feedback`, and Claude commit messages'],
+        [
+            'claude',
+            !report.tools.claude
+                ? 'missing'
+                : (report.tools.claudeProjectScopedRunSupported === false ? 'unsupported' : 'available'),
+            !report.tools.claude
+                ? 'required for `tela run`, `tela feedback`, and Claude commit messages'
+                : (report.tools.claudeProjectScopedRunSupported === false
+                    ? (report.tools.claudeDetail ?? `version ${report.tools.claudeVersion ?? '<unknown>'}`)
+                    : (report.tools.claudeVersion ? `version ${report.tools.claudeVersion}` : 'ready')),
+        ],
         [
             'agent-api-origin',
             report.tools.agentApiReachable === null

package/src/diagnostics.ts

@@ -1,6 +1,11 @@
 import { accessSync, constants, existsSync, statSync } from 'node:fs'
 import { dirname } from 'node:path'
 import { buildAgentApiHeaders } from './auth.ts'
+import {
+    formatClaudeCliVersion,
+    inspectClaudeCli,
+    MIN_CLAUDE_VERSION_FOR_PROJECT_SCOPED_RUN,
+} from './claude.ts'
 import { inspectSavedConfig, redactSecret } from './config.ts'
 import { resolveSshPrivateKeyPath } from './forgejo.ts'
 import {
@@ -70,6 +75,9 @@ export interface StatusReport {
     tools: {
         git: boolean
         claude: boolean
+        claudeVersion?: string
+        claudeProjectScopedRunSupported?: boolean | null
+        claudeDetail?: string
         agentApiReachable: boolean | null
         agentApiCategory?: AgentApiReachabilityCategory
         agentApiStatus?: number
@@ -269,6 +277,7 @@ function buildStatusNextActions(
     hasForgejoOrganization: boolean,
     hasForgejoAccess: boolean,
     hasGitSshKey: boolean,
+    claudeFix?: string,
 ): string[] {
     const actions: string[] = []
 
@@ -300,6 +309,10 @@ function buildStatusNextActions(
         actions.push('Review local changes before syncing, or use `tela push` to stage and commit them.')
     }
 
+    if (claudeFix) {
+        actions.push(claudeFix)
+    }
+
     if (warnings.length === 0) {
         actions.push('Run `tela sync --current`, `tela run`, or `tela push` when you are ready.')
     }
@@ -311,15 +324,16 @@ export async function createStatusReport(
     cwd = process.cwd(),
     fetchFn: typeof fetch = fetch,
 ): Promise<StatusReport> {
-    const [configInspection, gitAvailable, claudeAvailable, repo] = await Promise.all([
+    const [configInspection, gitAvailable, claudeInspection, repo] = await Promise.all([
         Promise.resolve(inspectSavedConfig()),
         commandExists('git'),
-        commandExists('claude'),
+        inspectClaudeCli(),
         inspectCurrentRepository(cwd),
     ])
 
     const warnings: string[] = []
     let reachability: AgentApiReachability | undefined
+    let claudeFix: string | undefined
 
     if (!configInspection.exists) {
         warnings.push('Tela CLI is not configured yet.')
@@ -354,8 +368,18 @@ export async function createStatusReport(
         warnings.push('`git` is not available on PATH.')
     }
 
-    if (!claudeAvailable) {
+    if (!claudeInspection.available) {
         warnings.push('`claude` is not available on PATH.')
+        claudeFix = 'Install the Claude CLI before using `tela run`, `tela push --claude`, or `tela feedback`.'
+    }
+    else if (!claudeInspection.supportsProjectScopedRun) {
+        const requiredVersion = formatClaudeCliVersion(MIN_CLAUDE_VERSION_FOR_PROJECT_SCOPED_RUN)
+        warnings.push(
+            claudeInspection.problem === 'unparseable'
+                ? `Claude CLI version could not be determined for project-scoped runs: ${claudeInspection.detail ?? 'unknown output'}`
+                : `Claude CLI must be updated to ${requiredVersion} or newer for project-scoped \`tela run\`.`,
+        )
+        claudeFix = `Update Claude CLI to version ${requiredVersion} or newer before using \`tela run\`.`
     }
 
     if (repo.detached) {
@@ -382,6 +406,7 @@ export async function createStatusReport(
         Boolean(configInspection.config?.forgejoOrganization),
         Boolean(configInspection.config?.forgejoUserRegistered),
         Boolean(configInspection.config?.gitSshKey),
+        claudeFix,
     )
 
     return {
@@ -410,7 +435,12 @@ export async function createStatusReport(
         repo,
         tools: {
             git: gitAvailable,
-            claude: claudeAvailable,
+            claude: claudeInspection.available,
+            claudeVersion: claudeInspection.version,
+            claudeProjectScopedRunSupported: claudeInspection.available
+                ? claudeInspection.supportsProjectScopedRun
+                : null,
+            claudeDetail: claudeInspection.detail,
             agentApiReachable: reachability?.reachable ?? null,
             agentApiCategory: reachability?.category,
             agentApiStatus: reachability?.statusCode,
@@ -632,10 +662,10 @@ export async function createDoctorReport(
     cwd = process.cwd(),
     fetchFn: typeof fetch = fetch,
 ): Promise<DoctorReport> {
-    const [configInspection, gitAvailable, claudeAvailable, repo] = await Promise.all([
+    const [configInspection, gitAvailable, claudeInspection, repo] = await Promise.all([
         Promise.resolve(inspectSavedConfig()),
         commandExists('git'),
-        commandExists('claude'),
+        inspectClaudeCli(),
         inspectCurrentRepository(cwd),
     ])
 
@@ -675,9 +705,22 @@ export async function createDoctorReport(
         {
             id: 'tool-claude',
             group: 'tools',
-            status: claudeAvailable ? 'pass' : 'warn',
-            summary: claudeAvailable ? '`claude` is available.' : '`claude` is not available on PATH.',
-            fixes: claudeAvailable ? ['No action required.'] : ['Install the Claude CLI before using `tela run`, `tela push --claude`, or `tela feedback`.'],
+            status: !claudeInspection.available
+                ? 'warn'
+                : (claudeInspection.supportsProjectScopedRun ? 'pass' : 'fail'),
+            summary: !claudeInspection.available
+                ? '`claude` is not available on PATH.'
+                : (claudeInspection.supportsProjectScopedRun
+                    ? `Claude CLI is available (${claudeInspection.version ?? 'unknown version'}) and supports project-scoped runs.`
+                    : (claudeInspection.problem === 'unparseable'
+                        ? 'Claude CLI version could not be determined for project-scoped runs.'
+                        : `Claude CLI ${claudeInspection.version ?? '<unknown>'} is too old for project-scoped runs.`)),
+            fixes: !claudeInspection.available
+                ? ['Install the Claude CLI before using `tela run`, `tela push --claude`, or `tela feedback`.']
+                : (claudeInspection.supportsProjectScopedRun
+                    ? ['No action required.']
+                    : [`Update Claude CLI to version ${formatClaudeCliVersion(MIN_CLAUDE_VERSION_FOR_PROJECT_SCOPED_RUN)} or newer before using \`tela run\`.`]),
+            evidence: claudeInspection.available && claudeInspection.detail ? [claudeInspection.detail] : undefined,
         },
         ...buildRepoChecks(repo),
     ]

package/src/git.ts

@@ -23,16 +23,33 @@ export interface GitStatusCounts {
     total: number
 }
 
+type GitSshHostKeyPolicy = 'default' | 'accept-new'
+
 interface GitRunOptions extends Omit<RunCommandOptions, 'env'> {
     requireConfiguredSsh?: boolean
+    sshHostKeyPolicy?: GitSshHostKeyPolicy
 }
 
 function quoteForShell(value: string): string {
     return `'${value.replaceAll('\'', `'"'"'`)}'`
 }
 
-export function buildGitSshCommand(privateKeyPath: string): string {
-    return `ssh -i ${quoteForShell(privateKeyPath)} -o IdentitiesOnly=yes`
+export function buildGitSshCommand(
+    privateKeyPath: string,
+    options: {
+        hostKeyPolicy?: GitSshHostKeyPolicy
+    } = {},
+): string {
+    const args = [
+        `-i ${quoteForShell(privateKeyPath)}`,
+        '-o IdentitiesOnly=yes',
+    ]
+
+    if (options.hostKeyPolicy === 'accept-new') {
+        args.push('-o StrictHostKeyChecking=accept-new')
+    }
+
+    return `ssh ${args.join(' ')}`
 }
 
 export function isSshRemoteUrl(remoteUrl: string): boolean {
@@ -108,14 +125,19 @@ function resolveConfiguredGitSshKey(requireConfiguredSsh: boolean): TelaCliGitSs
     }
 }
 
-function buildGitEnv(requireConfiguredSsh: boolean): Record<string, string> | undefined {
+function buildGitEnv(
+    requireConfiguredSsh: boolean,
+    sshHostKeyPolicy: GitSshHostKeyPolicy = 'default',
+): Record<string, string> | undefined {
     const gitSshKey = resolveConfiguredGitSshKey(requireConfiguredSsh)
     if (!gitSshKey) {
         return undefined
     }
 
     return {
-        GIT_SSH_COMMAND: buildGitSshCommand(gitSshKey.privateKeyPath),
+        GIT_SSH_COMMAND: buildGitSshCommand(gitSshKey.privateKeyPath, {
+            hostKeyPolicy: sshHostKeyPolicy,
+        }),
     }
 }
 
@@ -123,7 +145,10 @@ async function runGitCommand(
     args: string[],
     options: GitRunOptions = {},
 ): Promise<CommandResult> {
-    const env = buildGitEnv(Boolean(options.requireConfiguredSsh))
+    const env = buildGitEnv(
+        Boolean(options.requireConfiguredSsh),
+        options.sshHostKeyPolicy,
+    )
 
     return await runCommand(
         ['git', ...args],
@@ -215,6 +240,8 @@ export async function assertGitRepository(cwd: string): Promise<void> {
 export async function cloneRepository(remoteUrl: string, targetDir: string): Promise<void> {
     await runGitCommand(['clone', remoteUrl, targetDir], {
         requireConfiguredSsh: isSshRemoteUrl(remoteUrl),
+        // Sync accepts first-seen SSH host keys automatically, but changed host keys still fail.
+        sshHostKeyPolicy: 'accept-new',
     })
 }
 
@@ -227,6 +254,7 @@ export async function fetchOrigin(cwd: string): Promise<void> {
     await runGitCommand(['fetch', 'origin', '--prune'], {
         cwd,
         requireConfiguredSsh: await remoteRequiresConfiguredSsh(cwd, 'origin'),
+        sshHostKeyPolicy: 'accept-new',
     })
 }
 
@@ -234,6 +262,7 @@ export async function fetchAllRemotes(cwd: string): Promise<void> {
     await runGitCommand(['fetch', '--all', '--prune'], {
         cwd,
         requireConfiguredSsh: await anyRemoteRequiresConfiguredSsh(cwd),
+        sshHostKeyPolicy: 'accept-new',
     })
 }
 
@@ -280,6 +309,7 @@ export async function pullCurrentBranch(cwd: string): Promise<void> {
     await runGitCommand(['pull', '--ff-only'], {
         cwd,
         requireConfiguredSsh: await upstreamRequiresConfiguredSsh(cwd),
+        sshHostKeyPolicy: 'accept-new',
     })
 }
 
@@ -287,6 +317,7 @@ export async function pullDefaultBranch(cwd: string, defaultBranch: string): Pro
     await runGitCommand(['pull', '--ff-only', 'origin', defaultBranch], {
         cwd,
         requireConfiguredSsh: await remoteRequiresConfiguredSsh(cwd, 'origin'),
+        sshHostKeyPolicy: 'accept-new',
     })
 }
 

package/src/program.ts

@@ -12,9 +12,9 @@ import { RunChatHandoffScreen, RunScreen } from './ink/screens/run-screen.tsx'
 import { SetupScreen, type SetupScreenResult } from './ink/screens/setup/setup-screen.tsx'
 import { SyncScreen, type SyncProgressItem } from './ink/screens/sync-screen.tsx'
 import { renderCommandScreen } from './ink/runtime.tsx'
-import { listOrganizations } from './agent-api.ts'
+import { listAvailableRepositories, listOrganizations } from './agent-api.ts'
 import { authenticateWithDeviceFlow, type SetupAuthEvent } from './auth.ts'
-import { createUserFacingError } from './errors.ts'
+import { createUserFacingError, toUserFacingError } from './errors.ts'
 import {
     getCommandMetadata,
     listCommandMetadata,
@@ -90,6 +90,7 @@ import {
 import { commandExists, runInteractiveCommand, runStreamingCommand } from './process.ts'
 import { CommandRuntime } from './runtime.ts'
 import type {
+    AvailableRepositorySummary,
     BatchSyncFailure,
     SyncResult,
     TelaCliAuthState,
@@ -107,6 +108,7 @@ import {
     stepList,
     table,
 } from './ui.ts'
+import { CLI_VERSION } from './version.ts'
 
 type PromptModule = FeedbackPromptModule
 
@@ -125,6 +127,7 @@ interface CliDeps {
     syncAllRepositories?: typeof syncAllRepositories
     syncCurrentRepository?: typeof syncCurrentRepository
     listCloneRootRepositories?: typeof listCloneRootRepositories
+    listAvailableRepositories?: typeof listAvailableRepositories
     previewPush?: typeof previewPush
     pushRepository?: typeof pushRepository
     runLocalAgentCommand?: typeof runLocalAgentCommand
@@ -266,11 +269,13 @@ function renderRootHelp(program: Command): string {
     return joinBlocks([
         bootstrapPane('Tela CLI', [
             'One-shot workflows for setting up Tela, syncing repositories, running local agents, preparing pushes, and applying commit feedback.',
+            'Run `tela` with no subcommand to list workspace repositories available to sync.',
             '',
             'First successful path:',
             stepList([
                 'tela setup',
                 'tela status',
+                'tela',
                 'tela sync <repo> or tela sync --current',
                 'tela run',
                 'tela push',
@@ -282,6 +287,7 @@ function renderRootHelp(program: Command): string {
             ['Flag', 'Description'],
             [
                 ['--verbose', 'Include raw evidence for failures where available'],
+                ['-v, --version', 'Show current Tela CLI version'],
                 ['-h, --help', 'Show command help'],
             ],
             renderOptions,
@@ -331,6 +337,27 @@ function installCustomHelp(program: Command): void {
     })
 }
 
+function installCommanderOutput(program: Command, deps: CliDeps): void {
+    program.configureOutput({
+        writeOut: (message) => {
+            if (deps.writeStdout) {
+                deps.writeStdout(message)
+                return
+            }
+
+            process.stdout.write(message)
+        },
+        writeErr: (message) => {
+            if (deps.writeStderr) {
+                deps.writeStderr(message)
+                return
+            }
+
+            process.stderr.write(message)
+        },
+    })
+}
+
 function emitBootstrap(runtime: CommandRuntime, title: string, summary: string): void {
     runtime.emit(bootstrapPane(title, summary, { decorate: runtime.decorate }))
 }
@@ -762,6 +789,26 @@ function syncCategoryFixes(category: SyncFailureCategory): string[] {
     }
 }
 
+function buildSyncFailureError(error: unknown): ReturnType<typeof createUserFacingError> {
+    const category = categorizeSyncError(error)
+    const userError = toUserFacingError(error)
+    const stderrDetails = userError.evidence
+        .find(line => line.startsWith('stderr: '))
+        ?.replace(/^stderr: /, '')
+    const stdoutDetails = userError.evidence
+        .find(line => line.startsWith('stdout: '))
+        ?.replace(/^stdout: /, '')
+
+    return createUserFacingError({
+        code: `sync_${category}`,
+        summary: error instanceof Error ? error.message : String(error),
+        details: stderrDetails || stdoutDetails || userError.details,
+        fixes: syncCategoryFixes(category),
+        evidence: userError.evidence,
+        cause: error,
+    })
+}
+
 function renderSyncPlan(input: {
     mode: SyncCommandResult['mode']
     target: string
@@ -1025,13 +1072,7 @@ async function runSyncInk(
                 }
             }
             catch (error) {
-                const category = categorizeSyncError(error)
-                throw createUserFacingError({
-                    code: `sync_${category}`,
-                    summary: error instanceof Error ? error.message : String(error),
-                    fixes: syncCategoryFixes(category),
-                    cause: error,
-                })
+                throw buildSyncFailureError(error)
             }
         },
     }))
@@ -1203,13 +1244,7 @@ export async function runSync(
         return result
     }
     catch (error) {
-        const category = categorizeSyncError(error)
-        throw createUserFacingError({
-            code: `sync_${category}`,
-            summary: error instanceof Error ? error.message : String(error),
-            fixes: syncCategoryFixes(category),
-            cause: error,
-        })
+        throw buildSyncFailureError(error)
     }
 }
 
@@ -1857,8 +1892,10 @@ export async function runDoctor(
 }
 
 export interface ListRepositoriesResult {
-    cloneRoot: string
-    repositories: string[]
+    success: boolean
+    repositories: AvailableRepositorySummary[]
+    message?: string
+    nextActions?: string[]
 }
 
 export async function runListRepositories(
@@ -1867,35 +1904,76 @@ export async function runListRepositories(
 ): Promise<ListRepositoriesResult> {
     const runtime = createRuntime(deps, options)
     const inspection = (deps.inspectSavedConfig ?? inspectSavedConfig)()
-    const cloneRoot = inspection.config?.cloneRoot ?? getDefaultCloneRoot()
-    const listRepos = deps.listCloneRootRepositories ?? listCloneRootRepositories
-    const repositories = listRepos(cloneRoot)
-    const result: ListRepositoriesResult = { cloneRoot, repositories }
+    const decorate = runtime.decorate
+    const setupRequiredNextActions = [
+        'Run `tela setup` to configure Tela CLI and sign in.',
+        'Run `tela --help` to see all available commands.',
+    ]
+    const setupRequiredMessage = 'Setup and sign-in are required before Tela can list repositories available to sync.'
+
+    if (!inspection.valid || !inspection.config?.auth) {
+        const result: ListRepositoriesResult = {
+            success: false,
+            repositories: [],
+            message: setupRequiredMessage,
+            nextActions: setupRequiredNextActions,
+        }
+
+        if (options.json) {
+            runtime.emitJson(result)
+            return result
+        }
+
+        emitBootstrap(runtime, 'Tela CLI', 'Workspace repositories available to sync.')
+        runtime.emit(joinBlocks([
+            section('Repositories', [
+                setupRequiredMessage,
+                '',
+                'These repositories will appear here after setup is complete.',
+            ], { decorate }),
+            nextActions(setupRequiredNextActions, { decorate }),
+        ]))
+
+        return result
+    }
+
+    const listRepos = deps.listAvailableRepositories ?? listAvailableRepositories
+    const repositories = await listRepos(inspection.config, deps.fetchFn ?? fetch)
+    const result: ListRepositoriesResult = {
+        success: true,
+        repositories,
+    }
 
     if (options.json) {
         runtime.emitJson(result)
         return result
     }
 
-    emitBootstrap(runtime, 'Tela CLI', 'Workspace repositories under the configured clone root.')
-    const decorate = runtime.decorate
+    emitBootstrap(runtime, 'Tela CLI', 'Workspace repositories available to sync.')
     const body = repositories.length > 0
-        ? section('Repositories', bulletList(repositories), { decorate })
+        ? section(
+            'Repositories',
+            table(
+                ['Organization', 'Repository', 'Sync'],
+                repositories.map(repository => [
+                    repository.organization.name,
+                    repository.agentRepo.repository,
+                    repository.syncStatus,
+                ]),
+                { decorate },
+            ),
+            { decorate },
+        )
         : section('Repositories', [
-            `No repositories found under ${cloneRoot}.`,
+            'No workspace repositories are currently registered for this workspace.',
             '',
-            'Next steps:',
-            bulletList([
-                'Run `tela setup` to configure the clone root.',
-                'Run `tela sync <repo>` to clone a workspace repository.',
-            ]),
+            'There is nothing to sync yet.',
         ], { decorate })
 
     runtime.emit(joinBlocks([
         body,
-        section('Clone root', cloneRoot, { decorate }),
         nextActions([
-            'Run `tela sync <repo>` to clone or refresh a repository.',
+            'Run `tela sync <repo>` to clone or refresh an available repository.',
             'Run `tela --help` to see all available commands.',
         ], { decorate }),
     ]))
@@ -1913,8 +1991,10 @@ export function createProgram(deps: CliDeps = {}): Command {
         .name('tela')
         .description('Tela CLI workspace and auth helper')
         .showHelpAfterError()
+        .version(CLI_VERSION, '-v, --version', 'show current Tela CLI version')
         .option('--verbose', 'include raw evidence on failures')
 
+    installCommanderOutput(program, deps)
     installCustomHelp(program)
 
     addStandardReadOptions(program).action(async (commandOptions: GlobalCliOptions) => {

package/src/types.ts

@@ -82,6 +82,21 @@ export interface RepositoryLookupResponse {
     error?: string
 }
 
+export interface RepositoryListItemResponse {
+    organization: OrganizationSummary
+    agentRepo: AgentRepoSummary
+}
+
+export interface RepositoryListResponse {
+    success: boolean
+    repositories?: RepositoryListItemResponse[]
+    error?: string
+}
+
+export interface AvailableRepositorySummary extends RepositoryListItemResponse {
+    syncStatus: 'available'
+}
+
 export interface OrganizationListResponse {
     success: boolean
     organizations?: TelaCliForgejoOrganization[]

package/src/version.ts

@@ -0,0 +1,3 @@
+import packageJson from '../package.json' with { type: 'json' }
+
+export const CLI_VERSION = packageJson.version